feat(integrations): linear connector + shim + GraphQL gate + docs (LT1)

[madarco]

Summary

Linear path of the @agentbox/integrations foundation, descriptor-only (no relay/ctl core changes — this is what validates the abstraction the Notion T1–T4 work built). Tracked in docs/linear_backlog.md LT1.

Connector + ops

• packages/integrations/src/connectors/linear.ts — new descriptor:
  • Reads: whoami (→ linear auth whoami), issue.list, issue.mine (v2-native; replaces the dropped issue list --me), issue.view, issue.query, team.list, api (GraphQL passthrough).
  • Writes (gated): issue.create, issue.update, issue.comment (→ linear issue comment add — @schpet/linear-cli v2 uses add, not create; the orchestrator brief was wrong and I caught it during review).
• IntegrationService union widened to 'notion' | 'linear'.

GraphQL gate (refuseGraphqlNonQuery)

The api op is a query-only passthrough. The gate:

• Refuses any positional whose first significant keyword (after whitespace + # … line-comment strip) is mutation or subscription (exit 65).
• Consumes value-bearing flags (--variable, --variables-json) so a benign JSON payload starting with mutation isn't misread as the operation. Skips consumption when the next token itself looks like a flag, so --input defenses still fire.
• Refuses --variable key=@<path> — linear-cli's @<path> syntax reads from a host file and sends contents as a GraphQL variable, an exfiltration channel. Refuses on =@ anywhere in the value (last-=-split parser safety).
• Refuses sources prefixed with Unicode whitespace / BOM (U+FEFF, NBSP U+00A0, LSEP U+2028) — pre-fix the ASCII-only whitespace skip let those bypass.
• Refuses positionals whose first significant char isn't { or an ASCII letter ('unparseable' shapes — defense-in-depth).
• Narrows flag-skip from arg.startsWith('-') to arg.startsWith('--') so single-dash positionals like -mutation are inspected.

Auth-token exclusion (key security invariant)

linear auth token PRINTS the raw API key to stdout. Three defenses in series:

1. Shim hard-rejects linear auth token with 'auth token' leaks the raw API key — refused. Use 'linear whoami' for identity. (exit 2). Same hard-reject for auth login/logout/migrate/default.
2. Connector allowlist exposes no op that maps to auth token.
3. Relay dispatch denies anything not on the connector allowlist.

Destructive ops (issue delete, team delete, team create) are off-list (start conservative, widen deliberately).

Shim + image staging

• packages/sandbox-docker/scripts/linear-shim — strict allowlist mirroring ntn-shim. Installed at /usr/local/bin/linear (no symlink alias).
• Staged across all five providers: stage-runtime.mjs (5 lists), Dockerfile.box COPY, packages/sandbox-{hetzner,vercel,e2b}/src/runtime-assets.ts + each provider's install/provision/build-template script. Daytona is shim-less by design.

Config + doctor

• Typed flag integrations.linear.enabled (default false) added to UserConfig / EffectiveConfig / BUILT_IN_DEFAULTS / KEY_REGISTRY in packages/config/src/types.ts.
• agentbox doctor: zero-line change — ALL_CONNECTORS drives integrationsChecks, so the Linear row appears automatically with the install/login hints from the connector descriptor.

Tests (pure, no docker / no network)

• packages/integrations/test/registry.test.ts — registry resolves linear, op classification, argv shapes (including the comment add shape), refuseGraphqlNonQuery (mutation refused, query/anonymous allowed, leading whitespace + comments tolerated, value-bearing flag consumption, --variable key=@<path> refused, --variable foo=name=@<path> refused, Unicode-whitespace / BOM / NBSP / LSEP prefix refused, single-dash positional refused, unparseable shape refused, --input survives a --variable consume).
• packages/ctl/test/gh-and-shims.test.ts — linear-shim allowlist including the explicit auth token rejection, destructive-op refusals, issue mine + issue comment add forwarding, pre-positional api --paginate invocation.
• apps/cli/test/doctor-integrations.test.ts — updated for multi-connector iteration.
• packages/relay/test/{host-actions,integrations}.test.ts — updated the two existing "unknown service" tests (used linear; now use trello).

Docs (same change)

• docs/integrations.md — full Linear section: connector descriptor, op surface, GraphQL gate, auth-token three-defense invariant, env/credentials notes.
• apps/web/content/docs/integrations-linear.mdx (new) — public page mirroring the Notion mdx.
• apps/web/content/docs/{meta.json,configuration.mdx,cli.mdx} — sidebar entry, config row, doctor pointer.
• docs/host-relay.md — integrations bullet extended to cover the new linear ops + auth-token rejection.
• docs/features.md — symmetrical "Linear integration" "what works today" bullet.
• docs/linear_backlog.md — LT1 marked done with shipped-evidence status log. docs/integrations_backlog.md Session 2 plan updated for the corrected subcommand names. LT1 path is NOT yet marked "done" in integrations_backlog.md Status section — that closeout belongs to LT2 after the live Waldosai e2e.

Test plan

• pnpm typecheck green
• pnpm test green (495 + new linear-shim tests)
• pnpm lint green
• pnpm build green (no [stage-runtime] WARN missing source)
• Manual shim smoke-test: whoami / auth whoami / issue mine / issue comment add forward correctly; auth token / issue delete / team create / team delete rejected; api --paginate <query> forwards
• Live Waldosai e2e — LT2 (not run in LT1; deliberate)

Notes

The orchestrator brief specified issue comment create and the orchestrator's reading of the surface had a few other inaccuracies. Verified against the actual @schpet/linear-cli v2 source via the GitHub Contents API: auth-whoami.ts exists, issue-comment-add.ts is the v2 subcommand (create does not exist), issue-mine.ts is the v2-canonical "issues assigned to me" read. The connector, shim, tests, and docs all reflect the verified surface.

---

Note

Medium Risk
Touches security-sensitive integration boundaries (token leakage, GraphQL write bypass, host-file exfiltration) but reuses the existing Notion relay pattern with layered guards and broad unit test coverage; live e2e is deferred to LT2.

Overview
Adds a Linear service integration on the same relay-gated host-CLI model as Notion: a new connector in @agentbox/integrations, an in-box linear shim, opt-in integrations.linear.enabled, and packaging across Docker/Hetzner/Vercel/E2B.

Connector & relay surface (descriptor-only): Registers linearConnector with read ops (whoami, issue list/mine/view/query, team.list, query-only api) and gated writes (issue.create, issue.update, issue.comment → upstream comment add). The api op uses refuseGraphqlNonQuery to block mutations/subscriptions, --input, and --variable host-file loads (@path exfiltration). auth token and destructive/issue-admin commands stay off the allowlist; the shim hard-rejects token-printing and host-auth mutations.

Runtime & config: Stages linear-shim via stage-runtime.mjs, Dockerfile.box, and each cloud provider’s install/provision scripts and runtime-assets. Typed config defaults integrations.linear.enabled to false. agentbox doctor picks up Linear automatically via ALL_CONNECTORS; integration doctor tests now assert multi-connector rows.

Docs & tests: New integrations-linear doc page plus configuration/CLI/features/relay design updates; unit tests cover the connector registry, GraphQL gate, shim allowlist, and relay “unknown service” examples (now trello).

^{Reviewed by Cursor Bugbot for commit 7a914c1. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agentbox-web	Ready	Preview, Comment	Jun 6, 2026 11:43pm