Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

feat(console): publish the agent runtime to npmjs with trusted publishing (CHOO-2021) (#154)

Louis Amaudruze086e547ac29
diff --git a/.github/workflows/switch-agent-runtime-publish.yml b/.github/workflows/switch-agent-runtime-publish.yml
index afb1a386f..d1073772d 100644
--- a/.github/workflows/switch-agent-runtime-publish.yml
+++ b/.github/workflows/switch-agent-runtime-publish.yml
@@ -1,8 +1,10 @@
-# Publish the shared agent runtime to GitHub Packages.
+# Publish the shared agent runtime to the public npm registry.
#
# The package is consumed two ways, and only one of them needs a registry:
# Switch Console builds it from the workspace, so it never waits on a publish. The
-# Claude Code plugin runs it with `npx`, and that needs a version to exist.
+# connector plugins run it with `npx`, and that needs a version to exist — for
+# anyone, including people outside SandboxAQ, which is why this publishes to
+# npmjs.com rather than to a registry that demands a credential to read.
#
# Triggered by a tag, so a version can be published from a BRANCH — you should
# not have to merge to main to test the thing you are testing. To cut one:
@@ -23,9 +25,17 @@
# Publishing is idempotent: a tag for a version already on the registry reports
# that and exits cleanly rather than failing.
#
-# No secret is needed. GitHub Packages accepts the workflow's own GITHUB_TOKEN
-# with `packages: write`, so there is no PAT to create, rotate, or leak.
-# Consumers authenticate with `gh auth token` on the host instead.
+# No secret is needed, and none is stored. npm trusted publishing authenticates
+# this workflow by OIDC: GitHub mints a short-lived token asserting which
+# repository and workflow file is running, and npm checks that against the
+# trusted publisher registered for the package. There is no NPM_TOKEN to
+# create, rotate, or leak, and a token stolen from anywhere else cannot publish.
+#
+# That registration is manual, one-time, and must exist BEFORE this workflow
+# first runs. It names the repository, THIS FILE'S NAME, and the environment
+# below — all case-sensitive, none validated when saved, so renaming any of
+# them breaks publishing and the error arrives at the next release rather than
+# at the rename.
name: Publish switch-agent-runtime
on:
@@ -44,12 +54,22 @@ jobs:
runs-on: ubuntu-latest
# Publish only from a matching tag or from main. A workflow_dispatch from an
# arbitrary branch would otherwise publish whatever that branch's
- # package.json says into the real @sandbox-quantum namespace, bypassing the
+ # package.json says into the real @sandboxaq namespace, bypassing the
# tag-vs-version guard below (which only runs on the tag path).
if: ${{ startsWith(github.ref, 'refs/tags/switch-agent-runtime-v') || github.ref == 'refs/heads/main' }}
+ # Gates the publish on the `release` environment's protection rules, so a
+ # pushed tag queues a release for approval rather than shipping one.
+ #
+ # It is also half of the trusted publisher's identity: the environment is a
+ # claim in the OIDC token, so this name and the one registered on npm must
+ # match exactly. Changing it here without changing it there fails the
+ # publish, and only at the next release.
+ environment: release
permissions:
contents: read
- packages: write
+ # Mints the OIDC token npm verifies. This replaces `packages: write`:
+ # nothing here can write to a registry with an ambient credential.
+ id-token: write
defaults:
run:
working-directory: console
@@ -72,19 +92,29 @@ jobs:
node-version: 22
cache: pnpm
cache-dependency-path: console/pnpm-lock.yaml
- registry-url: https://npm.pkg.github.com
- scope: '@sandbox-quantum'
+ # Still required with OIDC: this is what writes the .npmrc that points
+ # npm at the public registry for the scope.
+ registry-url: https://registry.npmjs.org
+ scope: '@sandboxaq'
+
+ # Trusted publishing needs npm 11.5.1+; Node 22 ships an older one, and
+ # without this the publish fails with an authentication error that says
+ # nothing about the version.
+ #
+ # Held on 11.x rather than `@latest`: npm 12 requires Node ^22.22.2, so
+ # `@latest` couples this job to whatever patch `node-version: 22` resolves
+ # to today, and the next npm major would break it without a change here.
+ - run: npm install -g npm@^11.15.0
- run: pnpm install --frozen-lockfile
# Build from source rather than trusting a committed artifact — the whole
# point of publishing is that there is no artifact in the repo to drift.
- - run: pnpm --filter @sandbox-quantum/switch-agent-runtime run build
+ - run: pnpm --filter @sandboxaq/switch-agent-runtime run build
- name: Publish if this version is new
working-directory: console/packages/switch-agent-runtime
env:
- NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TAG_REF: ${{ github.ref }}
run: |
set -euo pipefail
@@ -127,11 +157,21 @@ jobs:
exit 0
fi
+ # --access public: a scoped package defaults to private, which on this
+ # account is not merely unwanted but unpublishable. Harmless to repeat
+ # after the first publish sets it.
+ #
+ # --provenance: signed attestation of which workflow and commit built
+ # the tarball. It requires a PUBLIC repository — while this one is
+ # private the publish fails here, deliberately, rather than shipping a
+ # release that can never be given provenance retroactively.
+ #
# A prerelease must not become what `@latest` resolves to.
case "$version" in
- *-*) npm publish --tag next ;;
- *) npm publish ;;
+ *-*) npm publish --access public --provenance --tag next ;;
+ *) npm publish --access public --provenance ;;
esac
echo "Published $name@$version"
- echo "Point the plugin at it: bump the pinned version in" \
- "connectors/claude-code-plugin/.mcp.json and the plugin's own version."
+ echo "Point the sessions at it: bump the three pins that name the" \
+ "version — both connectors' .mcp.json and" \
+ "SWITCH_AGENT_RUNTIME_VERSION — plus the plugin versions."
diff --git a/CLAUDE.md b/CLAUDE.md
index 25592522b..e1a211bb4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -82,7 +82,7 @@ each ships its own copy of the Switch room-workflow skill at
- `connectors/claude-code-plugin/` — manifest `.claude-plugin/plugin.json`.
Ships the skill plus an MCP config (`.mcp.json`) and hooks. It contains **no
- runtime code**: the MCP server is `@sandbox-quantum/switch-agent-runtime`,
+ runtime code**: the MCP server is `@sandboxaq/switch-agent-runtime`,
fetched with `npx` and built from `console/packages/switch-agent-runtime/`.
Switch Console imports the same package for its protocol client, so there is one
implementation of the agent protocol rather than a copy per consumer.
diff --git a/connectors/claude-code-plugin/.mcp.json b/connectors/claude-code-plugin/.mcp.json
index b498ff6fa..f5b768961 100644
--- a/connectors/claude-code-plugin/.mcp.json
+++ b/connectors/claude-code-plugin/.mcp.json
@@ -2,7 +2,7 @@
"mcpServers": {
"switch": {
"command": "npx",
- "args": ["-y", "@sandbox-quantum/[email protected]"]
+ "args": ["-y", "@sandboxaq/[email protected]"]
}
}
}
diff --git a/connectors/codex-plugin/.mcp.json b/connectors/codex-plugin/.mcp.json
index e5d62be73..89d57fa17 100644
--- a/connectors/codex-plugin/.mcp.json
+++ b/connectors/codex-plugin/.mcp.json
@@ -2,7 +2,7 @@
"mcpServers": {
"switch": {
"command": "npx",
- "args": ["-y", "@sandbox-quantum/[email protected]"],
+ "args": ["-y", "@sandboxaq/[email protected]"],
"env_vars": [
"SWITCH_API_ENDPOINT",
"SWITCH_API_TOKEN",
diff --git a/connectors/codex-plugin/README.md b/connectors/codex-plugin/README.md
index 868b52de0..20329e6ea 100644
--- a/connectors/codex-plugin/README.md
+++ b/connectors/codex-plugin/README.md
@@ -17,7 +17,7 @@ Claude Code-specific and deliberately not part of this one.
## The Switch MCP server
The manifest declares `"mcpServers": "./.mcp.json"`, and that file registers
-`@sandbox-quantum/switch-agent-runtime` over stdio under the server name
+`@sandboxaq/switch-agent-runtime` over stdio under the server name
`switch` — the name the skill assumes. A Codex session with this plugin
installed has the Switch tools, whether or not Switch Console launched it.
@@ -29,7 +29,7 @@ The config holds **no secret**. It names the variables the runtime needs under
"mcpServers": {
"switch": {
"command": "npx",
- "args": ["-y", "@sandbox-quantum/[email protected]"],
+ "args": ["-y", "@sandboxaq/[email protected]"],
"env_vars": ["SWITCH_API_ENDPOINT", "SWITCH_API_TOKEN", "SWITCH_AGENT_ID", "…"],
"startup_timeout_sec": 60
}
diff --git a/console/AGENTS.md b/console/AGENTS.md
index f9202bf91..df74b7846 100644
--- a/console/AGENTS.md
+++ b/console/AGENTS.md
@@ -384,7 +384,7 @@ pnpm run lint
directory, and does not need the credential. Do not add a token back to it:
two copies is how one goes stale and authenticates as the wrong agent.
- Three consumers read this layout: switchdash, the sidecar, and
- `@sandbox-quantum/switch-agent-runtime` (which reads it directly when
+ `@sandboxaq/switch-agent-runtime` (which reads it directly when
nothing sets `SWITCH_*` in the environment). Changing the shape means
changing all three.
- The token being in a working tree at all is a known exposure — a
@@ -417,7 +417,7 @@ The pairs that must stay in step:
| `agent-hooks/hook-config-service.ts` + `ssh-agent-runtime.installRemoteHooks` | `sidecar/session-spawner.installHooks` | nothing — same failure mode: one side quietly installs fewer hooks |
| `switch-rooms/auto-session-watcher.ts` | `sidecar/notification-watcher.ts` | nothing — two implementations of one watcher |
| `switch-rooms/room-connection.ts` | — | shared: the sidecar constructs the same class |
-| protocol client (stream, heartbeat, cursor) | — | shared: `@sandbox-quantum/switch-agent-runtime` |
+| protocol client (stream, heartbeat, cursor) | — | shared: `@sandboxaq/switch-agent-runtime` |
Where a row says *shared*, a change lands in both for free — prefer putting
logic there. Where it says *nothing*, you are editing one of two copies and the
diff --git a/console/apps/switch-console-desktop/package.json b/console/apps/switch-console-desktop/package.json
index 8aedb03f2..7228cf7b0 100644
--- a/console/apps/switch-console-desktop/package.json
+++ b/console/apps/switch-console-desktop/package.json
@@ -52,7 +52,7 @@
},
"dependencies": {
"@parcel/watcher": "^2.5.6",
- "@sandbox-quantum/switch-agent-runtime": "workspace:*",
+ "@sandboxaq/switch-agent-runtime": "workspace:*",
"@switch-console/core": "workspace:*",
"@switch-console/plugins": "workspace:*",
"@switch-console/shared": "workspace:*",
diff --git a/console/apps/switch-console-desktop/src/main/core/switch-rooms/auto-session-watcher.ts b/console/apps/switch-console-desktop/src/main/core/switch-rooms/auto-session-watcher.ts
index 315b4ee58..7e0b1af36 100644
--- a/console/apps/switch-console-desktop/src/main/core/switch-rooms/auto-session-watcher.ts
+++ b/console/apps/switch-console-desktop/src/main/core/switch-rooms/auto-session-watcher.ts
@@ -1,6 +1,6 @@
import { randomUUID } from 'node:crypto';
import path from 'node:path';
-import { SwitchEventStream } from '@sandbox-quantum/switch-agent-runtime';
+import { SwitchEventStream } from '@sandboxaq/switch-agent-runtime';
import { getRemoteAgentLocation } from '@main/core/agents/agent-location';
import { getAgentById } from '@main/core/agents/getAgentById';
import {
diff --git a/console/apps/switch-console-desktop/src/main/core/switch-rooms/room-connection.ts b/console/apps/switch-console-desktop/src/main/core/switch-rooms/room-connection.ts
index e74f64170..d223c0261 100644
--- a/console/apps/switch-console-desktop/src/main/core/switch-rooms/room-connection.ts
+++ b/console/apps/switch-console-desktop/src/main/core/switch-rooms/room-connection.ts
@@ -1,6 +1,6 @@
import * as fs from 'node:fs';
import * as path from 'node:path';
-import { SwitchEventStream } from '@sandbox-quantum/switch-agent-runtime';
+import { SwitchEventStream } from '@sandboxaq/switch-agent-runtime';
import type { AgentStatus, NotificationType } from '@shared/core/providers/agentEvents';
import type { InjectionSink } from './injection-sink';
import type { SessionControl } from './session-control';
diff --git a/console/apps/switch-console-desktop/src/main/core/switch-rooms/switch-event-format.ts b/console/apps/switch-console-desktop/src/main/core/switch-rooms/switch-event-format.ts
index e5a61ad40..2ce67af83 100644
--- a/console/apps/switch-console-desktop/src/main/core/switch-rooms/switch-event-format.ts
+++ b/console/apps/switch-console-desktop/src/main/core/switch-rooms/switch-event-format.ts
@@ -2,7 +2,7 @@
* Formatting agent-bridge events for injection into a session's terminal.
*
* The event *shapes* are protocol, and live in
- * `@sandbox-quantum/switch-agent-runtime`; they are re-exported here so the
+ * `@sandboxaq/switch-agent-runtime`; they are re-exported here so the
* many call sites that import both from this module keep working. What is
* genuinely Switch Console's is below: turning an event into the line a human (and
* an agent reading its own terminal) sees.
@@ -15,14 +15,14 @@ export type {
MessagePayload,
RoomJoinPayload,
TaskPayload,
-} from '@sandbox-quantum/switch-agent-runtime';
+} from '@sandboxaq/switch-agent-runtime';
import type {
AgentBridgeEvent,
CommandPayload,
MessagePayload,
RoomJoinPayload,
TaskPayload,
-} from '@sandbox-quantum/switch-agent-runtime';
+} from '@sandboxaq/switch-agent-runtime';
/**
* Format an agent-bridge event as a self-contained line to inject into the
diff --git a/console/apps/switch-console-desktop/src/shared/core/switch-rooms/switch-agent-runtime.ts b/console/apps/switch-console-desktop/src/shared/core/switch-rooms/switch-agent-runtime.ts
index 705ff70f9..c7f9cf6ae 100644
--- a/console/apps/switch-console-desktop/src/shared/core/switch-rooms/switch-agent-runtime.ts
+++ b/console/apps/switch-console-desktop/src/shared/core/switch-rooms/switch-agent-runtime.ts
@@ -13,7 +13,7 @@
import { NPM_TOKEN_VAR } from '@shared/core/npm-registry';
/** npm package name of the local Switch MCP runtime. */
-export const SWITCH_AGENT_RUNTIME_PACKAGE = '@sandbox-quantum/switch-agent-runtime';
+export const SWITCH_AGENT_RUNTIME_PACKAGE = '@sandboxaq/switch-agent-runtime';
/**
* Exact version the runtime is pinned to. Must match the pin in
diff --git a/console/apps/switch-console-desktop/src/sidecar/notification-watcher.ts b/console/apps/switch-console-desktop/src/sidecar/notification-watcher.ts
index f85fb104f..923e8152c 100644
--- a/console/apps/switch-console-desktop/src/sidecar/notification-watcher.ts
+++ b/console/apps/switch-console-desktop/src/sidecar/notification-watcher.ts
@@ -1,5 +1,5 @@
import { randomUUID } from 'node:crypto';
-import { SwitchEventStream } from '@sandbox-quantum/switch-agent-runtime';
+import { SwitchEventStream } from '@sandboxaq/switch-agent-runtime';
import type { SwitchAgentCredentials } from '@main/core/switch-rooms/switch-credentials';
// How often the auto_session gate is re-read, so toggling it takes effect
diff --git a/console/packages/switch-agent-runtime/package.json b/console/packages/switch-agent-runtime/package.json
index 693ed3ff6..e9d760d27 100644
--- a/console/packages/switch-agent-runtime/package.json
+++ b/console/packages/switch-agent-runtime/package.json
@@ -1,5 +1,5 @@
{
- "name": "@sandbox-quantum/switch-agent-runtime",
+ "name": "@sandboxaq/switch-agent-runtime",
"version": "0.2.0",
"description": "Switch agent protocol client, and the local MCP runtime built on it",
"license": "Apache-2.0",
@@ -27,7 +27,8 @@
"./package.json": "./package.json"
},
"publishConfig": {
- "registry": "https://npm.pkg.github.com"
+ "access": "public",
+ "registry": "https://registry.npmjs.org"
},
"scripts": {
"dev": "tsdown --watch",
diff --git a/console/pnpm-lock.yaml b/console/pnpm-lock.yaml
index 0c0c2eaab..1c5a453a9 100644
--- a/console/pnpm-lock.yaml
+++ b/console/pnpm-lock.yaml
@@ -19,7 +19,7 @@ importers:
'@parcel/watcher':
specifier: ^2.5.6
version: 2.5.6
- '@sandbox-quantum/switch-agent-runtime':
+ '@sandboxaq/switch-agent-runtime':
specifier: workspace:*
version: link:../../packages/switch-agent-runtime
'@switch-console/core':
diff --git a/docs/api/AGENT_PROTOCOL.md b/docs/api/AGENT_PROTOCOL.md
index d4cc3f4a1..c0c65c770 100644
--- a/docs/api/AGENT_PROTOCOL.md
+++ b/docs/api/AGENT_PROTOCOL.md
@@ -821,7 +821,7 @@ A connection that has silently missed events must never appear healthy.
drift. Unblocks the local runtime and closes the overlap with CHOO-490.
**The two MCP servers are merged into one local runtime.** *(implemented)*
- `@sandbox-quantum/switch-agent-runtime` serves the tool surface over stdio —
+ `@sandboxaq/switch-agent-runtime` serves the tool surface over stdio —
fetched from the server at startup, so it cannot drift — and translates each
call to `POST /ops/${toolName}` on its connection. Each connector plugin now
registers exactly one MCP server (`switch`); the separate remote `switch` and