toki/iop
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
iop/agent-contract/inner/execution-runtime.md

3 KiB
Raw Blame History

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
    • apps/node/internal/node/command_handler.go
    • apps/node/internal/transport/session.go
    • apps/edge/internal/service/model_queue_release.go
    • apps/edge/internal/service/node_command.go
    • apps/edge/internal/openai/stream_gate_runtime.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.
  • FailureCode carries provider-neutral typed failures. The removed response-silence failure and its activity, probe, health-overlay, and provider-avoidance types are not runtime concepts.
  • RunRequest and ProviderTunnelRequest do not carry a provider response-silence timeout. Silence produces no execution event, health mutation, or retry decision.
  • Provider complete, error, and cancelled events, caller cancellation, the request hard deadline, and transport disconnect remain the explicit terminal inputs.
  • A current provider or transport terminal releases its admission lease and request-owned resources exactly once. It does not start a health probe or select a replacement provider.
  • ProviderPoolDispatchRequest contains no request-local provider-avoidance hint. Candidate selection continues to use the configured provider catalog, current connection ownership, capacity, priority, and queue policy.
  • StreamGate consumes provider/transport terminals through the endpoint adapters. Output silence is not a filter input or recovery strategy.

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