Showrunner Agent Connector

showrunner-agent connects a user-owned provider process to one Showrunner agent installation. It accepts durable, ordered events, runs one provider adapter, and sends idempotent commands through the connector v1 API.

Run

npm ci
npm run build
npm test
npx showrunner-agent connect \
  --api <api-base-url> \
  --pairing-code ABCD-EFGH \
  --adapter codex

Don't type the connect command from here — the agent editor in the app prints one with the pairing code and API URL already filled in for the build you are running (ConnectCommandBuilder). Its API URL comes from scripts/dev-stack.sh (API_PORT) for a numbered dev stack, from applicationUrl in api/src/Bylines.Messenger.Api/Properties/launchSettings.json for stack 0, and from the hosted domain otherwise.

Released builds install the connector from npm, and it ships with the API rather than on a pipeline of its own — the same way agent-gateway does. Staging and production are separate npm packages, each published by its own API deploy after the deploy succeeds: showrunner-agent-staging (<version>-staging.<run> on every merge) and showrunner-agent (the package.json version, once per release). Separate packages because a staging build is pinned to the staging servers, and because npm allows one trusted publisher per package. Both publish by trusted publishing (OIDC, no stored token). Cutting a production release therefore means bumping version in package.json; external-agent-gateway-commit-check fails a PR that changes the connector without bumping it. A local build runs this working tree instead, via the npm link that dev-stack.sh up performs.

Supported CLI adapters are custom, codex, claude, and acp. A custom module must default-export an AgentAdapter (or export it as adapter). Every adapter accepts --cwd /absolute/project/path to choose its working directory; ACP additionally requires --agent <id>. The supported ACP IDs and invocation shapes live in src/adapters/acp/acp-config.ts.

The connector credential is issued by Showrunner pairing and stored by FileConnectorCredentialStorage in the platform data directory selected by env-paths. The directory and file are enforced as modes 0700 and 0600. Pairing, access, and refresh values are never accepted as provider configuration and are redacted from logs.

Provider credentials and isolation

• Codex launches codex app-server over stdio. Authentication comes from the locally installed Codex process and its normal OpenAI credential configuration. App-server endpoints are limited to stdio, Unix sockets, or loopback unless an embedding application explicitly opts out. See the current Codex app-server documentation.
• Claude is transparently re-hosted with @anthropic-ai/claude-agent-sdk through the user's installed Claude Code binary and its existing sign-in. Executable discovery is defined by findClaudeCodeExecutable in src/adapters/claude/claude-adapter.ts.
• ACP agents use their CLI's configured credentials. ACP accepts external MCP server descriptors rather than this connector's in-process tool callbacks, so the generic adapter currently mounts no Showrunner tools and is reply-only. Permission requests still route through the owner approval flow and never auto-approve.
• Custom adapters own their provider credential loading. Keep secrets outside the repository and do not put them in Showrunner messages, adapter state, command errors, or structured log fields.

Run each connector under a dedicated OS account/container with access only to its intended working directory, network destinations, and provider credentials. Do not share a home directory or cloud credential chain with unrelated workloads. Disable unused MCP servers and prefer read-only scopes.

Untrusted content and host policy

Events label message authors as owner, other_participant, agent, or system. Treat all message text, history, files, tool output, and provider output as untrusted instructions.

An agent is reachable only from its own 1:1 chat with its owner: AddUsersToStream refuses a Runner-type stream, and grants are minted only when that chat is created. Every message an agent sees is therefore the owner's or its own, so the connector does not track per-invocation content trust.

Host tools are gated on the risk of the tool itself. Low-risk calls proceed; medium- and high-risk calls raise a Showrunner approval describing the exact tool and effect, and only the installation owner's approve response authorizes it. Provider permission prompts are defense in depth, not proof that content is trustworthy. Opening agents to multi-participant streams would require reinstating a content-trust signal before that reasoning holds.

The API kill switch and per-provider flags should remain off until the relevant adapter conformance, redaction, revocation, and permission matrices pass.