Skip to main content

RIG Hard-Cut Remaining Implementation Plan

🚢 SHIPPED — 2026-05. The RIG hard-cut landed in #696 (control-plane authority migration) and was completed by follow-ups #981 (runner gateway hardening) and #1024 (legacy authority routes removed). Architecture is now codified in ADR-018 and docs/decisions/019-rig-hard-cut.md. This plan is retained for historical context.

For agentic workers: REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Finish the hard-cut Rig-derived Human.work runtime control plane so Nest/API is the single production authority for runs, events, approvals/input, tools, models, artifacts, runners, sandbox capabilities, and unresolved ingress, with legacy authority routes disabled.

Architecture: Human.work keeps a NestJS control plane as source of truth. Python/Hermes becomes a runner/model adapter only. Runners, sandbox workers, tools, model calls, artifacts, approvals, and channel execution go through platform gateways and append-only run events. No compatibility layer, no dual-write production stage, no raw shell, no broad runner/provider secrets, no org-less execution.

Tech Stack: NestJS 11, TypeORM, PostgreSQL 16 + pgvector, Next.js 16/React 19, FastAPI Python runner service, GitHub Actions, Railway/Vercel deployment (Railway today; AWS ECS migration in flight per #1101).

Current Baseline​

Branch: dankovk/rig-runtime-hard-cut

Already implemented:

  • Runtime schema/entities/migration for agent_runs, run_events, approvals/input, tool calls, policy decisions, artifacts, runner manifests/registrations, unresolved ingress.
  • Runtime services: lifecycle, event ledger, policy, tool gateway/executor, model gateway, sandbox gateway/executor skeleton, approvals/input, artifacts, runner registration/control-plane skeleton, unresolved ingress.
  • Conversation draft runtime run wrapper started.
  • Agentic task creation partially runtime-backed; legacy approve/reject mutations now 410 in current branch state.
  • Slack/Telegram/Teams/email unknown paths have partial quarantine coverage.
  • Ops frontend skeleton for runs/approvals.
  • Migration-only Postgres CI job.

Non-negotiable remaining invariants:

  • No legacy route can remain an authoritative production execution path.
  • No runtime execution for org-less ingress.
  • No runner/sandbox broad provider/vendor/R2/platform secrets.
  • No persisted signed artifact URLs.
  • No raw shell API; only typed capability ops.
  • Default HITL: no channel send unless explicit policy and approval state allow it.
  • RLS/session context must be real for HTTP, webhook, worker, runner callback, backfill, and tests.

Workstream 1: Legacy Authority Shutdown​

Files:

  • Modify: api/src/tools/tools.controller.ts

  • Modify: api/src/agent-api/agent-api.controller.ts

  • Modify: api/src/agentic/agentic.controller.ts

  • Modify: agent/main.py

  • Modify/Create: agent/routers/tasks.py

  • Tests: api/test/tools.spec.ts, api/test/agent-api.spec.ts, api/test/agentic.spec.ts, agent/tests/test_tasks.py

  • Return 410 Gone for /tools/execute direct execution.

  • Return 410 Gone for direct /v1/agent-api/tools/:toolName execution, unless it is a signed run-scoped wrapper calling ToolGatewayService.execute.

  • Keep only read-only traceability on /agentic/tasks*; mutating task create/approve/reject/plan authority must be runtime-backed or 410.

  • Return 410 Gone for Python /v1/tasks* legacy task authority.

  • Remove process-local idempotency maps from production authority paths.

  • Add tests proving no legacy route invokes tool/vendor/agent side effects.

Validation:

cd api && npm run build
cd api && npm test -- --runInBand test/tools.spec.ts test/agent-api.spec.ts test/agentic.spec.ts
cd agent && python3 -m pytest tests/test_tasks.py -q

Workstream 2: Runtime Read APIs Matching Ops Frontend​

Files:

  • Create/Modify: api/src/runtime-control-plane/agent-runs.controller.ts

  • Create/Modify: api/src/runtime-control-plane/agent-runs-read.service.ts

  • Modify: api/src/runtime-control-plane/runtime-requests.controller.ts

  • Modify: api/src/runtime-control-plane/runtime-control-plane.module.ts

  • Modify: frontend/src/lib/api.ts if endpoint paths change

  • Tests: api/test/agent-runs.controller.spec.ts, api/test/runtime-requests.controller.spec.ts, frontend/src/lib/__tests__/api.test.ts

  • Implement GET /agent-runs list endpoint used by frontend.

  • Implement GET /agent-runs/:id detail endpoint with events/tool calls/artifacts/policy decisions/approvals/input.

  • Add alias or move approval list endpoint to match frontend /approval-requests while preserving scoped runtime-control-plane route if useful.

  • Enforce org scope and AM/SuperAdmin/Expert/client visibility.

  • Add stable DTO serializers with redacted payloads only.

Validation:

cd api && npm run build
cd api && npm test -- --runInBand test/agent-runs.controller.spec.ts test/runtime-requests.controller.spec.ts
cd frontend && npm test -- src/lib/__tests__/api.test.ts --runInBand

Workstream 3: Model Gateway Real Broker and Python Runner Cutover​

Files:

  • Modify/Create: api/src/runtime-control-plane/model-gateway.service.ts

  • Create: api/src/runtime-control-plane/model-broker.service.ts

  • Modify: agent/* model/provider call sites

  • Modify: environment docs/scripts as needed

  • Tests: api/test/model-gateway.service.spec.ts, agent tests for model adapter calls

  • Implement a real Nest model broker using existing OpenAI/OpenRouter/LLM service patterns.

  • Make Python/Hermes request model calls through API broker endpoints, not broad provider env keys.

  • Ensure runner-facing model responses do not expose API keys or provider credentials.

  • Persist durable model request/checkpoint events only; raw token streaming can remain ephemeral or artifact-backed.

  • Add tests for no provider secrets in runner env/response.

Validation:

cd api && npm run build
cd api && npm test -- --runInBand test/model-gateway.service.spec.ts
cd agent && python3 -m pytest tests/ -q

Workstream 4: Runner Scheduler, Signature Verification, and Run Contracts​

Files:

  • Modify: api/src/runtime-control-plane/runner-control-plane.service.ts

  • Modify: api/src/runtime-control-plane/runner-event-signature-verifier.ts

  • Create: api/src/runtime-control-plane/run-contract.service.ts

  • Create/Modify: runner token/signing key storage if needed

  • Tests: api/test/runner-control-plane.service.spec.ts, new signature verifier tests

  • Replace rejecting placeholder verifier with real key lookup and signature verification.

  • Generate signed run contracts for runner polling/claiming.

  • Implement claim semantics with run status transitions and runner registration liveness checks.

  • Enforce manifest hash/policy hash/tool manifest hash compatibility before claim.

  • Add heartbeat expiry/unhealthy state handling.

  • Keep outbound polling/service discovery; never execute DB-provided public URLs.

Validation:

cd api && npm run build
cd api && npm test -- --runInBand test/runner-control-plane.service.spec.ts test/runner-registry.service.spec.ts test/run-event-ledger.service.spec.ts

Workstream 5: Real Sandbox Worker Backend​

Files:

  • Modify: api/src/runtime-control-plane/sandbox-capability-executor.service.ts

  • Create: sandbox worker service/package/scripts as appropriate

  • Modify: deployment manifests if needed

  • Tests: sandbox executor/gateway tests, cleanup/timeout/process denial tests

  • Keep typed ops only: artifact_read, artifact_write, exec_argv, browser_action.

  • Implement actual isolated backend or explicit remote worker adapter; do not pretend skeleton isolation is complete.

  • exec_argv must execute argv array only, no shell string.

  • Enforce timeout, output size cap, network policy, cleanup hook, orphan process reaping contract.

  • Add denial tests for raw shell, env passthrough, signed URL access, and unknown ops.

Validation:

cd api && npm run build
cd api && npm test -- --runInBand test/sandbox-capability-executor.service.spec.ts test/sandbox-capability-gateway.service.spec.ts test/action-policy.service.spec.ts

Workstream 6: Artifact Storage Backend and Lease Signing​

Files:

  • Modify: api/src/runtime-control-plane/run-artifact.service.ts

  • Create: storage lease issuer implementation

  • Modify: env docs/deployment as needed

  • Tests: api/test/run-artifact.service.spec.ts, new lease issuer tests

  • Plug real storage backend into RUN_ARTIFACT_LEASE_ISSUER.

  • Generate short-lived scoped leases/signed URLs only at response time; never persist them.

  • Validate object key prefix belongs to org/run.

  • Add hash verification and redaction-before-write tests.

  • Add artifact lease events without secret URL persistence.

Validation:

cd api && npm run build
cd api && npm test -- --runInBand test/run-artifact.service.spec.ts test/rig-runtime-migration.spec.ts

Workstream 7: Channel Quarantine Completion​

Files:

  • Modify: api/src/channels/channels.controller.ts

  • Modify: api/src/channels/telegram/telegram.service.ts

  • Modify: api/src/channels/whatsapp/*

  • Modify: email inbound/remediation code

  • Tests: api/test/unresolved-ingress-channel-routing.spec.ts, channel tests where feasible

  • Finish WhatsApp unknown sender quarantine.

  • Finish WeChat unknown/mismatched credential quarantine.

  • Finish email unknown Specialist/client/org quarantine without runtime execution.

  • Verify Telegram/Teams mapping metadata and seed expectations.

  • Keep webhook acknowledgement behavior.

Validation:

cd api && npm run build
cd api && npm test -- --runInBand test/unresolved-ingress.service.spec.ts test/unresolved-ingress-channel-routing.spec.ts

Workstream 8: RLS Session Context and Live Postgres Fixes​

Files:

  • Modify/Create: DB/RLS middleware/interceptor under api/src/common or auth modules

  • Modify: migration 1749000000001-RigRuntimeControlPlane.ts as CI reveals issues

  • Modify: .github/workflows/ci.yml only if job needs tuning

  • Tests: new RLS/session tests, migration tests

  • Set app.current_org_id and app.current_role_domain for HTTP requests.

  • Set explicit internal context for webhooks/workers/backfills where appropriate.

  • Ensure PgBouncer/transaction pooling compatibility.

  • Add tests showing unset context is fail-closed, internal context works, org context filters rows.

  • Fix any failures from api-postgres-migrations CI.

Validation:

cd api && npm run build
cd api && npm test -- --runInBand test/rig-runtime-migration.spec.ts <new-rls-tests>

Workstream 9: Ops/Expert/Client UI Completion​

Files:

  • Modify: frontend/src/app/ops/agent-runs/*

  • Modify: frontend/src/app/ops/approvals/page.tsx

  • Create/Modify: /workspace approval UI

  • Create/Modify: /client approval cards

  • Modify: frontend/src/lib/api.ts

  • Tests: frontend tests if harness exists

  • Wire Ops pages to real backend DTOs.

  • Add approval resolve actions in Ops where authorized.

  • Add Expert approval surface for assigned Expert approvals.

  • Add client approval/input cards for client-targeted requests.

  • Preserve default HITL language and correct terminology.

Validation:

cd frontend && npm run lint
cd frontend && npm test -- src/lib/__tests__/api.test.ts --runInBand
cd frontend && npm run build

Workstream 10: Cutover Runbook, Backfill, and Rehearsal​

Files:

  • Create: docs/_archive/RIG_RUNTIME_HARD_CUT_CUTOVER.md (archived 2026-06-04; originally created at docs/runbooks/RIG_RUNTIME_HARD_CUT_CUTOVER.md)

  • Create: api/scripts/backfill-runtime-runs.ts

  • Create: staging rehearsal smoke scripts if needed

  • Tests: script dry-run tests where feasible

  • Define freeze/drain/backfill/reopen runbook with high-water marks.

  • Add dry-run backfill script for active conversations/tasks/queue items into runtime rows.

  • Add runner bootstrap gate and go/no-go checks.

  • Add forward-fix containment and rollback criteria.

  • Rehearse on staging with migrations, RLS, runner registration, quarantine, approvals, and frontend Ops pages.

Validation:

cd api && npm run build
cd api && npm test -- --runInBand <new-script-tests>

Final Acceptance Gate​

The branch is not complete until all are true:

  • API build passes.
  • Agent tests pass.
  • Frontend build passes.
  • Postgres migration CI passes with SYNCHRONIZE=false.
  • Legacy authority routes return 410 or are removed with tests.
  • Every production runtime action creates/updates agent_runs and appends run_events.
  • Tool/model/artifact/sandbox access happens only through gateways.
  • Runner event signatures are verified before events persist.
  • Org-less ingress goes only to quarantine/remediation.
  • RLS/session context is fail-closed unless internal context is explicit.
  • Staging cutover rehearsal completes with recorded evidence.
Last updated on by Degen