From 24427ac1f3c570db25c921312d0dfcbd404fabf4 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Tue, 5 May 2026 14:26:40 -0400 Subject: [PATCH 1/2] Define agent harness terminal receipt surface --- .../AGENT_HARNESS_TERMINAL_RECEIPTS.md | 184 ++++++++++++++++++ 1 file changed, 184 insertions(+) create mode 100644 docs/sourceos/AGENT_HARNESS_TERMINAL_RECEIPTS.md diff --git a/docs/sourceos/AGENT_HARNESS_TERMINAL_RECEIPTS.md b/docs/sourceos/AGENT_HARNESS_TERMINAL_RECEIPTS.md new file mode 100644 index 00000000000..42e5f426af6 --- /dev/null +++ b/docs/sourceos/AGENT_HARNESS_TERMINAL_RECEIPTS.md @@ -0,0 +1,184 @@ +# Agent Harness Terminal Receipt Surface + +Status: v0.1 planning baseline +Owner plane: TurtleTerm governed terminal/operator surface +Consumers: SourceOS spec, AgentPlane, Policy Fabric, Memory Mesh, SCOPE-D, Delivery Excellence + +## Purpose + +TurtleTerm is the SourceOS policy-aware, agent-addressable terminal workbench. The Aden/Hive production-agent pattern requires terminal work to be visible, bounded, receipt-producing, and measurable. TurtleTerm should make terminal/operator execution auditable without granting ambient shell authority to agents or cognition layers. + +## Boundary + +TurtleTerm owns: + +- terminal/session UX +- command wrapper behavior +- local agent gateway surface +- terminal receipts +- operator approval surfaces +- tmux/mux bridge receipts +- skill manifests for terminal operations +- replayable operator workflows + +TurtleTerm does not own: + +- AgentPlane graph execution +- Policy Fabric gate authority +- Agent Machine runtime provider lifecycle +- Delivery Excellence scoreboards +- Memory Mesh artifact storage +- SCOPE-D security exercise execution + +## Receipt classes + +### TerminalSessionReceipt + +Records an operator or agent-addressable terminal session. + +Required semantics: + +- terminal session id +- actor/agent ref +- workspace ref +- shell profile +- gateway profile +- policy admission ref +- AgentPlane run/session refs +- start/end timestamps +- mux/tmux pane refs when applicable +- environment profile hash + +### CommandReceipt + +Records a command execution through TurtleTerm. + +Required semantics: + +- command id +- terminal session ref +- command hash +- command display text when policy permits +- working directory +- environment profile hash +- stdin/stdout/stderr artifact pointer refs +- exit code +- duration +- policy decision ref +- side-effect class +- replay eligibility + +### MutationReceipt + +Records observed filesystem, process, deployment, or host mutation. + +Required semantics: + +- mutation id +- command ref +- mutation class +- target scope +- dry-run/live-run mode +- policy decision ref +- human-control event ref when required +- before/after artifact refs when available +- rollback ref +- denied operation refs + +### OperatorApprovalReceipt + +Records human operator decisions in TurtleTerm. + +Required semantics: + +- approval id +- actor ref +- subject ref +- decision +- reason +- timestamp +- policy gate ref +- AgentPlane run/session ref +- Delivery Excellence human-control event ref + +## Controlled actions + +Require Policy Fabric decisions for: + +- package install +- filesystem mutation outside workspace scope +- deployment/apply operations +- service start/stop/restart +- network listener creation +- secret/key material access +- credential helper invocation +- privilege escalation +- destructive command patterns +- host mutation +- cluster mutation + +Fail closed when controlled actions lack a policy decision ref. + +## AgentPlane integration + +AgentPlane should cite TurtleTerm receipts in: + +- RunArtifact +- ReplayArtifact +- SessionEnvelope +- EvidencePack +- FailureDiagnosis +- PromotionGate + +TurtleTerm receipts should preserve enough evidence for replay, diagnosis, and customer-safe proof without exposing raw secrets. + +## Memory Mesh integration + +Large stdout/stderr, shell transcripts, generated files, diffs, and terminal artifacts should be moved behind Memory Mesh `ArtifactPointer` refs when large, sensitive, replay-critical, or customer-proof relevant. + +## Delivery Excellence integration + +Delivery Excellence should consume derived metrics/readouts: + +- command success/failure +- policy-blocked command count +- host mutation denied/approved/performed +- approval latency +- replay-eligible command count +- operator intervention count +- terminal workflow cycle time +- customer-safe proof of operator work + +Delivery Excellence should not consume raw terminal transcripts unless policy explicitly permits it. + +## SCOPE-D integration + +SCOPE-D should validate TurtleTerm workflows for: + +- command injection +- shell escape +- destructive command bypass +- privilege escalation +- secret exfiltration +- unauthorized filesystem mutation +- unauthorized service exposure +- hostile generated scripts +- host/cluster mutation bypass + +## Non-negotiables + +- TurtleTerm must not grant ambient shell authority to agents. +- Agent Machine owns machine-local runtime provider lifecycle. +- Policy Fabric decides controlled action authority. +- Command outputs may need redaction and artifact pointers. +- Host mutation must be explicit, policy-referenced, and rollback-aware. +- Human approvals are typed control events, not freeform notes. +- Delivery Excellence receives metrics and readouts, not uncontrolled shell logs. + +## Near-term implementation path + +1. Align TurtleTerm command wrapper receipts with SourceOS `ShellReceiptEvent` and SourceOS execution receipt boundaries. +2. Add examples for terminal session, command, mutation, and operator approval receipts. +3. Add a verifier requiring policy refs for controlled action classes. +4. Add Delivery Excellence projection examples for command success, mutation posture, and approval latency. +5. Add SCOPE-D terminal-risk checks for command injection, secret access, host mutation, and shell escape. From 71dc442e7622aa849ff45d1934108eb949aac666 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Wed, 6 May 2026 20:39:10 -0400 Subject: [PATCH 2/2] Add agent harness terminal receipts schema --- ...gent-harness-terminal-receipts.schema.json | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 schemas/agent-harness-terminal-receipts.schema.json diff --git a/schemas/agent-harness-terminal-receipts.schema.json b/schemas/agent-harness-terminal-receipts.schema.json new file mode 100644 index 00000000000..e9966dfb03c --- /dev/null +++ b/schemas/agent-harness-terminal-receipts.schema.json @@ -0,0 +1,78 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://sourceos.dev/schemas/turtleterm/agent-harness-terminal-receipts.schema.json", + "title": "AgentHarnessTerminalReceipts", + "type": "object", + "additionalProperties": false, + "required": ["schemaVersion", "kind", "terminalSessionReceipt", "commandReceipt", "mutationReceipt", "operatorApprovalReceipt"], + "properties": { + "schemaVersion": { "const": "v0.1" }, + "kind": { "const": "AgentHarnessTerminalReceipts" }, + "terminalSessionReceipt": { + "type": "object", + "additionalProperties": false, + "required": ["sessionId", "actorRef", "workspaceRef", "shellProfile", "gatewayProfile", "policyAdmissionRef", "agentplaneRunRef", "environmentProfileHash"], + "properties": { + "sessionId": { "type": "string" }, + "actorRef": { "type": "string" }, + "workspaceRef": { "type": "string" }, + "shellProfile": { "type": "string" }, + "gatewayProfile": { "type": "string" }, + "policyAdmissionRef": { "type": "string" }, + "agentplaneRunRef": { "type": "string" }, + "muxPaneRefs": { "type": "array", "items": { "type": "string" } }, + "environmentProfileHash": { "type": "string" } + } + }, + "commandReceipt": { + "type": "object", + "additionalProperties": false, + "required": ["commandId", "terminalSessionRef", "commandHash", "workingDirectory", "environmentProfileHash", "exitCode", "policyDecisionRef", "sideEffectClass", "replayEligible"], + "properties": { + "commandId": { "type": "string" }, + "terminalSessionRef": { "type": "string" }, + "commandHash": { "type": "string" }, + "workingDirectory": { "type": "string" }, + "environmentProfileHash": { "type": "string" }, + "stdoutPointerRef": { "type": "string" }, + "stderrPointerRef": { "type": "string" }, + "exitCode": { "type": "integer" }, + "policyDecisionRef": { "type": "string" }, + "sideEffectClass": { "type": "string", "enum": ["none", "workspace-write", "host-mutation", "secret-access", "network-service", "deployment"] }, + "replayEligible": { "type": "boolean" } + } + }, + "mutationReceipt": { + "type": "object", + "additionalProperties": false, + "required": ["mutationId", "commandRef", "mutationClass", "targetScope", "mode", "policyDecisionRef", "mutatedHost"], + "properties": { + "mutationId": { "type": "string" }, + "commandRef": { "type": "string" }, + "mutationClass": { "type": "string" }, + "targetScope": { "type": "string" }, + "mode": { "type": "string", "enum": ["dry-run", "live"] }, + "policyDecisionRef": { "type": "string" }, + "humanControlEventRef": { "type": "string" }, + "rollbackRef": { "type": "string" }, + "mutatedHost": { "type": "boolean" }, + "deniedOperationRefs": { "type": "array", "items": { "type": "string" } } + } + }, + "operatorApprovalReceipt": { + "type": "object", + "additionalProperties": false, + "required": ["approvalId", "actorRef", "subjectRef", "decision", "policyGateRef", "agentplaneRunRef", "deliveryExcellenceEventRef"], + "properties": { + "approvalId": { "type": "string" }, + "actorRef": { "type": "string" }, + "subjectRef": { "type": "string" }, + "decision": { "type": "string", "enum": ["approved", "rejected", "deferred", "accepted-risk", "revoked"] }, + "reason": { "type": "string" }, + "policyGateRef": { "type": "string" }, + "agentplaneRunRef": { "type": "string" }, + "deliveryExcellenceEventRef": { "type": "string" } + } + } + } +}