iop/agent-contract/inner/execution-runtime.md

Provider Execution Runtime Contract

Contract metadata

• id: iop.execution-runtime
• boundary: inner
• status: active
• source evidence:
  • packages/go/execution/types.go
  • packages/go/execution/registry.go
  • packages/go/execution/emitter.go
  • packages/go/execution/failure.go
  • apps/node/internal/node/runtime_bridge.go

Scope

The execution package defines host-neutral provider primitives. It owns provider registration, lifecycle, execution events, typed failures, cancellation, token usage, and the three provider commands capabilities, transport_status, and ollama_api.

session_id is an opaque correlation value. It does not select, create, resume, or terminate a process. Repeated requests with the same value are independent executions. Cancellation targets a non-empty run_id only.

Requirements

• Providers implement the narrow Provider interface and may expose optional lifecycle, command, or tunnel capabilities.
• Event emitters preserve order and publish exactly one terminal event.
• Registry lookup uses provider identity and returns typed failures for missing or unavailable providers.
• Callers must reject commands outside the closed provider-command allowlist before provider lookup.
• Token usage remains observation data attached to execution or tunnel results.

Prohibited ownership

The package must not own interactive shells, persistent processes, terminal emulation, working-directory mutation, resumable conversations, local quota probing, or arbitrary host command execution. It must not import application-internal packages or generated transport types.

Verification

• go test -count=1 ./packages/go/execution
• go test -race -count=1 ./packages/go/execution
• go vet ./packages/go/execution