Session and executor contract

A trajectory is the durable record of one application task. Persist its session ID before the first request, then keep it through model turns, supported external actions, recovery, and explicit completion.

Session and operation identity#

Requests are serialized within a session. Reusing an operation ID for changed content conflicts. Give each distinct request a new ID. Use application-owned IDs. Reserved service namespaces are rejected with reserved_session_namespace.

Model requests and holds#

Use a supported protocol, explicit history, and a positive output-token limit. In Enforce mode, the current Base connection verifies the session’s initial compiled input contract before inference and reviews actions and final outputs before release. It does not separately rewrite each request or quarantine tool results before model inference.

A hold includes error.type: integrity_hold, a stable code, the assigned operation_id when available, and automatic_retry_authorized: false. Stop execution and preserve the operation. HTTP 200 can still end with an error event in a stream.

Recover without repeating inference#

GET /v1/integrity/operations
x-triage-api-key: <platform key>
x-triage-session-id: <original session ID>
Idempotency-Key: <original operation ID>

Recovery returns the operation's phase and result. A completed released result includes its exact base64 wire and content_type. An identical model POST can replay a completed durable result; an uncertain operation is never automatically redispatched.

If the status cannot be read at that moment, recovery returns HTTP 503 with operation_status_unavailable, a Retry-After header and automatic_retry_authorized: true. It is not a hold and says nothing about the operation: read the same operation again after the delay.

A missing or unfinished record is not permission for a replacement call. Reconcile the original operation through authorized deployment controls. See errors and recovery.

Authorize an external action#

POST /v1/integrity/actions/authorize
Content-Type: application/json

{"name":"write_file","arguments":{"path":"tests/test_auth.py","content":"..."}}

Include the same three identity headers. The action must be supported by the deployment's configured executor schema. Tool schemas stay fixed within a session. A returned permit binds the exact action, session, governing revision, and expiry; it does not execute the action.

1. Validate the permit again at the execution boundary with verify_permit or verifyPermit, including governing pins retained by the harness.
2. Durably consume the permit in your action ledger before executing its exact action. Do not reuse it for a changed action or a second effect.
3. Report the outcome as succeeded, failed, or unknown. Preserve unknown outcomes after a lost acknowledgement.

The report is application-reported evidence, not independently verified proof of the external effect. Local permit checks cannot establish revocation after issuance; retain your application's resource permissions and execution controls.

Report the action outcome#

POST /v1/integrity/actions/report
Content-Type: application/json

{
  "authorization_operation_id": "authorize_action_001",
  "permit_id": "<returned permit ID>",
  "action": {
    "name": "write_file",
    "arguments": {
      "path": "tests/test_auth.py",
      "content": "..."
    }
  },
  "outcome": "unknown",
  "evidence": {
    "note": "The executor did not receive a final acknowledgement."
  }
}

Use a new persisted operation ID in the headers. Reference the original authorization operation and permit, and include the exact authorized action. Outcomes are succeeded, failed, or unknown; optional evidence records what the application observed. A lost acknowledgement must remain unknown until reconciled.

Signed receipts and unsupported controls#

The /v1/integrity/actions/receipt endpoint accepts the executor's original signed event. The SDK takes that event as JSON text and preserves the signed representation. Verification requires a signer already registered for the exact connection, scope, and tool. Successful retention alone does not prove the effect.

The current connection does not support dynamic executor registration, changes to tool schemas within a session, or prepared Case review. The generic review_case / reviewCase SDK method does not enable those capabilities. No Case result is an execution permit.

Finish the task explicitly#

POST /v1/integrity/sessions/close
Content-Type: application/json

{"outcome":"completed"}

Use a new persisted operation ID and the original session. Outcomes are completed, abandoned, or failed. Closing prevents further platform admission to that session. It does not invoke a remote-close operation, prove task success, or resolve unknown external effects.

Closing an HTTP client, receiving a final model message, or leaving a session idle does not finish the task. Budget expiry can hold new work while preserving its evidence.