[AAASM-3500] ✨ (node-sdk): Wire OpControlSubscriber into withAssembly tool path

[Chisanan232]

Target

• Task summary:

  Follow-up to Bug AAASM-3491 (live kill switch never reached a running agent). The authoritative runtime fix merged in agent-assembly PR #1176 and the python-sdk companion in python-sdk PR [AAASM-3177] ✅ (node-sdk): Raise test coverage toward 90% #156 (the reference pattern). The node-sdk already shipped a complete OpControlSubscriber in src/op-control.ts, but it was dead code: not exported from index.ts and never consulted by the withAssembly tool wrapper, which only did pre-exec gateway.check() + waitForApproval. This PR exports the subscriber and wires it into the withAssembly tool path so an operator terminate/pause reaches a running tool through the SDK layer.

• Task tickets:

  • Task ID: AAASM-3500.
  • Relative task IDs:
    • AAASM-3491 (parent bug).
  • Relative PRs:
    • python-sdk [AAASM-3177] ✅ (node-sdk): Raise test coverage toward 90% #156 (companion / reference pattern).
    • agent-assembly #1176 (authoritative runtime fix).

• Key point change (optional):

  • Order is load-bearing: the op-control kill switch runs before the gateway check. A terminated op fast-fails the call (short-circuit — the gateway is never queried); a paused op blocks cooperatively in waitForOp until the gateway resumes it.
  • op_id resolves from an explicit opId on the call's first argument, otherwise composes {traceId}:{spanId}; absent a trace identity, op control is skipped.
  • The subscriber is threaded through as an optional opControl dependency on WithAssemblyOptions via a narrow OpControl seam, mirroring the Python companion's build_governance_interceptor(op_control=...). Without it, the tool path behaves exactly as before.

Effecting Scope

• Action Types:
  • ✨ Adding new something
    • 🟢 No breaking change
• Scopes:
  • 🧩 SDK public API
  • 🤖 Framework hooks
  • 🧪 Testing
    • 🧪 Unit testing
• Additional description:
  Purely additive. opControl is optional; existing withAssembly callers are unaffected.

Description

• src/wrappers/with-assembly.ts: add the OpControl seam + optional opControl option; consult op-control before the gateway check in both the execute and invoke tool paths (terminate → PolicyViolationError, pause → cooperative block); add extractOpId (opId else {traceId}:{spanId}).
• src/wrappers/index.ts: re-export the OpControl type.
• src/index.ts: export OpControlSubscriber, OpControlClient, OpControlSubscriberOptions, and OpTerminatedError from the package entrypoint so the kill switch is wireable.
• tests/with-assembly-op-control.test.ts: regression tests — terminate denies BEFORE the gateway is queried (short-circuit), pause blocks then proceeds on resume, no-trace-identity skips op control, op_id resolution, no-opControl path unchanged, invoke path.

How to verify

pnpm test (320 passed / 2 skipped), pnpm typecheck, pnpm lint, pnpm build — all green locally.

Closes AAASM-3500.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 88.88889% with 8 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/wrappers/with-assembly.ts	88.57%	8 Missing ⚠️

📢 Thoughts on this report? Let us know!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
92.1% Coverage on New Code
0.6% Duplication on New Code

See analysis details on SonarQube Cloud

[Chisanan232]

🔎 Review (Claude Code) — ready for approval

CI: ✅ All green — 16/16 checks pass, 0 failures (Analyze/CodeQL/SonarCloud, build ESM+CJS, vitest, typecheck, lint). pnpm test 320 passed locally.

Scope vs AAASM-3500 ("Export + wire OpControlSubscriber in node-sdk withAssembly tool path"): ✅ Fully covers it. The previously-dead OpControlSubscriber (+ OpControlClient, OpTerminatedError) is now exported from the package entrypoint, and withAssembly consults op-control in enforceOpControl before the pre-exec gateway.check() on both the execute and invoke paths: a terminated op short-circuits (throws, gateway never queried), a paused op blocks cooperatively in waitForOp until resume, a call with no trace identity skips op-control, and op_id resolves from an explicit value or {traceId}:{spanId}. 6 regression tests assert exactly these contract points. The OpControl seam is structural so the concrete subscriber satisfies it without a hard import.

Additive & safe: opControl is optional — existing withAssembly callers are unaffected (gateway-check + approval only, unchanged). Auto-constructing the subscriber inside initAssembly is intentionally deferred (matches the python-sdk #156 companion's "callers opt in" scope) — not a gap.

Verdict: Scope complete, CI green, regression coverage present. Ready to approve & merge. Follow-up AAASM-3500 stays open until merge + re-verification.