ajeetraina777/sbx-novu-kits:agent-connect

schemaVersion: "2"
kind: mixin
name: novu
version: 1.0.0
displayName: Novu Agent Connect (Cloud US)
description: 'Adds Novu Agent Connect - the Agent Communication Infrastructure - to any agent, on the Novu Cloud US API (api.novu.co). On top of the novu-py SDK and a proxy-managed secret key, it ships runbooks that provision a Claude-managed agent and connect it to channels like Slack and email for bi-directional conversations - all egress-only, the key never entering the sandbox. Store it once with: sbx secret set novu.'
sourceURL: https://github.com/ajeetraina/sbx-kits-novu
licenses:
    - Apache-2.0
agentInstructions:
    content: |
        ## Novu Agent Connect - agents on channels (Cloud US)

        This variant adds **Agent Connect** (Novu's Agent Communication
        Infrastructure) on top of the base Novu notification wiring. Agent Connect
        connects an agent "brain" to channels - Slack, Teams, WhatsApp, Telegram,
        email - and routes **bi-directional** conversations: a user messages the bot
        on a channel, Novu ingests the webhook, routes it to the brain, delivers the
        reply back into the thread, and stores the exchange. The API is the Novu Cloud
        **US** host `https://api.novu.co` (env `NOVU_API_URL`).

        The secret key is **proxy-managed**: `NOVU_SECRET_KEY` holds the literal
        `proxy-managed` sentinel inside the sandbox, and the sbx proxy swaps in the
        real key (as `Authorization: ApiKey <key>`) only on requests to `api.novu.co`.
        The Agent Connect REST endpoints use that same `ApiKey` header, so they are
        egress-only and need nothing extra.

        ### Primary path: a Claude-managed (hosted) agent

        Use the runbooks under `~/runbooks/` - all stdlib + REST, no bridge server,
        no inbound URL:

        - `integrations.py list --provider anthropic` - find the `integrationId` of
          the Anthropic integration that holds the model key.
        - `agents.py create --identifier support-bot --integration-id <id>
          --system-prompt "..."` - provision a `runtime: managed` agent hosted by
          Novu/Anthropic.
        - `agents.py list` / `agents.py get <id>` - inspect.
        - `conversations.py reply --agent support-bot --conversation <id>
          --integration <integrationIdentifier> --text "..."` - push a reply into a
          live channel thread (the outbound half of a bi-directional exchange).
          Viewing conversations and getting the `<id>` is done in the dashboard
          (Activity Feed -> Agent Conversations) - there is no list-conversations API.

        ### Two things that are NOT headless

        1. **Connecting Slack** (or any channel) is a one-time **browser OAuth** step
           in the Novu dashboard - it cannot be done from inside the sandbox. The
           sandbox provisions the agent and inspects conversations; a human attaches
           the channel once.
        2. **The Anthropic key** rides in the integration's request **body**, not a
           header, so the proxy cannot hide it. Create the Anthropic integration in
           the dashboard and pass its `integrationId` in, or use `--provider
           novu-anthropic` (Novu's own managed key). Only create it from the sandbox
           if you accept the key touching the sandbox for that one call.

        ### Advanced: custom-code bridge

        If the brain must run in your own process, `~/runbooks/bridge/` has a minimal
        `@novu/framework` example. It needs a Node runtime and a public URL (a tunnel
        out of the sandbox), and the allow list must gain the tunnel host +
        `registry.npmjs.org`. This inverts the egress-only posture - prefer the
        managed path unless you truly need it. See `~/runbooks/bridge/README.md`.

        Base notification triggering still works here too (`notify.py`,
        `subscribers.py`, `healthcheck.py`).
permissions:
    network:
        allow:
            - pypi.org
            - files.pythonhosted.org
            - api.novu.co
credentials:
    - service: novu
      description: Novu secret (API) key from Settings -> API Keys in the Novu dashboard
      required: true
      apiKey:
        name: NOVU_SECRET_KEY
        proxyManaged: true
        inject:
            - domain: api.novu.co
              header: Authorization
              format: ApiKey %s
environment:
    variables:
        NO_PROXY: localhost,127.0.0.1,host.docker.internal
        NOVU_ANALYTICS_SOURCE: sbx-kits-novu
        NOVU_API_URL: https://api.novu.co
        no_proxy: localhost,127.0.0.1,host.docker.internal
setup:
    install:
        - command: pip install --break-system-packages 'novu-py==3.19.0' click
          user: "1000"
          description: Install the official Novu Python SDK (novu-py) plus click for the runbooks