Work-package charter#
- Task ID:
HITL-002 - Owner: Oshun Agentic Studio maintainers; implementation owner: Codex
- Accountable product: V1 Oshun autonomous-content platform
- Priority: P0
- Target milestone: 2026-07-15 SOTA gap-closure program
- Risk tier: Critical human-authority and non-overridable-policy risk
- Dependencies: Agentic Studio
AgentRunEnvelopeand the existing pure run controls delivered before this work package - Affected runtime:
@oshun/agentic-studiointervention domain API and its public package export - Rollback strategy: Revert the two implementation commits. No database, BFF route, wire contract, or user-facing surface changed in this package.
- Evidence-pack location: This file
Canonical intervention surface#
intervention-api.ts now defines one exhaustive discriminated command union,
one immutable workspace, one comprehensive observation projection, one result
union with typed denials, and one audit record shape. Accepted commands return a
new workspace without mutating their input. Denials return a stable reason and
never change or emit state.
LiveInterventionSession makes observation an actual live API contract rather
than only a point-in-time helper. Subscribers receive the full observation and
the intervention record after every accepted mutation. The observation includes
the plan and current step, all tool effects plus explicit pending and
operator-only subsets, intermediate/node/output artifacts, source set and
evidence trail, cost ledger, gates, run/output/publication lineage, active human
claims, and the complete policy-law projection. Runtime adapters can map the
listener to SSE or WebSocket when HITL-004 binds the domain API to the BFF.
Complete command vocabulary#
| Capability family | Implemented commands |
|---|---|
| Run control | pause, resume, cancel, kill, choose branch, fork, rewind, retry with changes, and publication rollback |
| Discussion | comments targeting a run, artifact, node, or rubric dimension, with attached reference IDs |
| Editing | edit brief, plan, source set, tool arguments, and artifact node |
| Co-authoring | claim step, author from blank, replace artifact, and merge human branch |
| Decisions | approve, reject, veto, defer, reassign, require extra review, grant scoped exception, and change future autonomy level |
The pause/resume/cancel/kill/branch/fork/retry behaviors use the existing Agentic Studio run-control functions, while rewind and publication rollback add the missing domain semantics. Plan replacement rejects duplicate, dangling, self-referential, and cyclic dependencies. Claims reject conflicts; artifact replacement updates intermediate and output references; human-branch merge marks resulting content as mixed and closes matching active claims.
Non-overridable platform laws#
The API names six platform laws as a closed type: safety, rights, child safety, crisis, identity, and irreversible action. A gate associated with any one of these laws can never receive a scoped exception. A blocking law finding also prevents progress-enabling interventions—resume, branch selection, fork, retry, merge, approval, and increased future autonomy—while still permitting remediation edits, rejection/veto/defer, cancellation/kill, comments, and publication rollback. Editing does not silently clear the finding; only a later governed evaluation can do that.
Role rules are fail-closed. Platform operators have the full vocabulary; tenant operators cannot grant exceptions; creators cannot kill, reassign, grant exceptions, or change future autonomy; customers are limited to comment, cancel, reject, and defer. Every command requires a non-empty rationale.
Automated and adversarial verification#
- Focused intervention suite: 20/20 passing. It covers every command, immutable input behavior, all four comment dimensions, live accepted-only subscriptions, target/transition/claim/role/rationale failures, invalid DAGs, invalid/expired exceptions, and observation completeness.
- Each of the six non-overridable laws is independently tested against an attempted exception. A blocked crisis finding is also tested against resume and raised-autonomy bypass attempts while remediation and rollback remain available.
- Full
@oshun/agentic-studiosuite: 309/309 passing across 20/20 test files. - Focused ESLint over all changed TypeScript files: zero errors.
- Production TypeScript typecheck: zero errors.
@oshun/agentic-studio:buildemitted the implementation JavaScript, sourcemap, declarations, and declaration map under the package build output.git diff --checkpasses.
Artifact identity#
| Artifact | SHA-256 |
|---|---|
libs/oshun/agentic-studio/src/interventions/intervention-api.ts |
792c7c12f7f159361dfa4c5186f3f1f7d33d8a792d2d767df9a004e94b8b43c9 |
libs/oshun/agentic-studio/src/interventions/intervention-api.test.ts |
f0178affa54ab147c301083cc051c104905f2dd52d9d898fc5ba3f2ad34c9e7d |
libs/oshun/agentic-studio/src/interventions/index.ts |
425d0944b99f307eec1e693362977c033845799c46cc43fc32564534cd47a105 |
libs/oshun/agentic-studio/src/index.ts |
0ab8d716e1e3432d53d1328a6ab02ce1c347efa2979117ece53c9a247a0d71a6 |
Resource-safe verification#
The host has 15 GiB RAM and 31 GiB swap. Verification stayed scoped to the Agentic Studio package and ran sequentially. The Nx build's project-graph phase briefly used about 1.4 GiB in its ESLint plugin worker; it was supervised with about 9–10 GiB memory still available and completed before another check began. No full-workspace sweep, Next production build, mobile export, or packaging matrix was attempted.
Scope and negative proof#
- This work package implements the complete intervention domain API. It does not claim the optimistic concurrency, invalidation, signed mixed provenance, durable checkpoint, restart/race, or exactly-once guarantees owned by HITL-003.
- It does not claim V1 BFF/common-store binding, Lilith override composition, Yemaya emergency takeover, or Studio Authoring composition owned by HITL-004.
- The live session is an in-process subscription contract, not evidence of an externally deployed SSE/WebSocket route or production traffic.
- No user-facing UI changed, so Playwright and mobile UI automation are inapplicable to HITL-002. No media/model pipeline or Unreal asset changed.
Publication identity#
- Complete intervention API source commit:
c6d53c2c25170209834d072b520ffbac2411d04b - Live observation feed source commit:
cfa056db69aea4170c8211f3a23e08956252b0a8 - Closure evidence commit:
3f21f7e7b183b1bcf209f5aad97aa3f494b18f2a