Runtime and Control Plane

Agent Runtime Responsibilities

The agent app owns runtime mechanics: claims, backend calls, manifest loading, workspace hydration and sync, harness invocation, event normalization, heartbeats, and graceful shutdown. The backend owns policy and canonical transitions.

Depend on TAgentHarness, not Codex SDK types. Normalize provider events at the adapter boundary.

Context Manifest

The manifest contains runtime configuration, static MCP keys, organization integration IDs, missing required-integration markers, authorization epoch, context files, and declared output directories. It never contains provider credentials.

Context construction must page every filtered repository collection before selecting relevant dependencies, durability, human items, actions, task descendants, or integrations. Do not filter a single first page in memory: a valid item beyond that page would disappear from the run snapshot.

Treat every manifest loaded from object storage as untrusted persisted input. Validate paths, expected sizes, hashes, roles, and read-only/output contracts before hydration.

Task workers pass a 100 changed-file ceiling to terminal workspace sync. The workspace manager must inventory and validate the full candidate set before its first object-store write. Chat sync does not use this task-only ceiling.

Add Harness Behavior

1. Extend the provider-neutral interface only for a real cross-adapter need.
2. Keep Codex-specific configuration in the Codex adapter.
3. Preserve trace, revision, lease, authorization, and cancellation semantics.
4. Normalize events into existing agent runtime contracts.
5. Add adapter and runtime tests.
6. Update the developer guide when the public extension contract changes.

Add an oblivectl Command

oblivectl is the only authenticated state-changing/control-plane CLI available to agents. The trusted chat/worker process keeps the global service token; the model process receives only a short-lived capability bound to its organization, profile, and exact task run or chat turn.

1. Confirm the workflow is a backend-owned mutation rather than a filesystem operation.
2. Add a typed command parser in packages/oblivectl.
3. Extend its backend client with the smallest request/response contract.
4. Read organization, profile, task, run, and snapshot identity from hydrated context; read only the execution capability from the session environment.
5. Add or update the backend service-authenticated endpoint.
6. Preserve version, lease, ownership, and transition fencing.
7. Produce complete observable output suitable for the calling skill.
8. Update the oblivectl agent skill and command reference.
9. Update backend OpenAPI documentation.
10. Add CLI, client, route, and lifecycle tests.

Department execution capabilities may read only their department’s tasks and mutate only their owned tasks in the active root. Operator executions coordinate within the active root. Chat turns may perform organization-level control-plane work only in response to the active user turn.

Codex event normalization forwards actual provider events only. Do not manufacture compaction events; persistent chat resumes its real harness session, while ephemeral task runs start fresh.

Every new run receives a backend-built safe integration snapshot. Existing runs are not hot-patched. Material changes advance the organization authorization epoch, so a stale execution cannot continue through the integration gateway and must restart from the current snapshot. The snapshot reports control-plane readiness only and must not trigger a live provider health call.

Do not add agent-facing wrappers for ordinary reads or declared-output writes when native filesystem access and deterministic validation are sufficient.

contextctl

contextctl verify is intentionally local and read-only. It validates staged structured Context. It must not read files on behalf of the agent, write files, create manifests, call the network, or promote canonical state.