@harness-control/protocol 0.1.0

package/fixtures/conformance/invalid/unknown-top-level-field.json

@@ -0,0 +1,14 @@
+{
+  "id": "message-unknown-top-level-field",
+  "type": "host.hello",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "runner_id": "runner-local",
+    "host_id": "host-local",
+    "runner_version": "0.0.0",
+    "supported_protocol_versions": ["hcp.v0"],
+    "capabilities": []
+  },
+  "unexpected": true
+}

package/fixtures/conformance/valid/command-ack.json

@@ -0,0 +1,11 @@
+{
+  "id": "message-command-ack",
+  "type": "hcp.command.ack",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "command_id": "command-1",
+    "accepted_at": "2026-01-01T00:00:01.000Z",
+    "duplicate": false
+  }
+}

package/fixtures/conformance/valid/extension-event.json

@@ -0,0 +1,18 @@
+{
+  "id": "message-extension-event",
+  "type": "harness.event",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "session_id": "session-1",
+    "sequence": 3,
+    "event_type": "extension.timeline.marker",
+    "created_at": "2026-01-01T00:00:03.000Z",
+    "data": {
+      "summary": "Timeline marker",
+      "fields": {
+        "marker_id": "marker-1"
+      }
+    }
+  }
+}

package/fixtures/conformance/valid/host-hello.json

@@ -0,0 +1,22 @@
+{
+  "id": "message-host-hello",
+  "type": "host.hello",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "runner_id": "runner-local",
+    "host_id": "host-local",
+    "runner_version": "0.0.0",
+    "supported_protocol_versions": ["hcp.v0"],
+    "capabilities": ["providers", "mcp_streamable_http"],
+    "retained_events": {
+      "sessions": [
+        {
+          "session_id": "session-1",
+          "first_event_sequence": 1,
+          "last_event_sequence": 12
+        }
+      ]
+    }
+  }
+}

package/fixtures/conformance/valid/host-replay-unavailable.json

@@ -0,0 +1,15 @@
+{
+  "id": "message-host-replay-unavailable",
+  "type": "host.replay.unavailable",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:01.000Z",
+  "payload": {
+    "session_id": "session-1",
+    "requested_after_sequence": 12,
+    "reason": "cursor_outside_retention",
+    "retained_range": {
+      "first_event_sequence": 20,
+      "last_event_sequence": 40
+    }
+  }
+}

package/fixtures/conformance/valid/local-action-dev-server-start.json

@@ -0,0 +1,67 @@
+{
+  "id": "message-local-dev-server-start",
+  "type": "local.action.request",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "request_id": "local-action-dev-start-1",
+    "action": "local.dev_server.start",
+    "issued_at": "2026-01-01T00:00:01.000Z",
+    "attribution": {
+      "session_id": "session-1",
+      "turn_id": "turn-1",
+      "workspace_id": "workspace-1",
+      "provider_instance_id": "provider-1",
+      "run_id": "run-1"
+    },
+    "lease": {
+      "lease_id": "local-lease-dev-server",
+      "capability_id": "dev_server",
+      "scope": "workspace",
+      "run_id": "run-1",
+      "hcp_session_id": "session-1",
+      "execution_host_id": "host-1",
+      "provider_instance_id": "provider-1",
+      "workspace_id": "workspace-1",
+      "expires_at": "2026-01-01T01:00:00.000Z"
+    },
+    "sandbox": {
+      "mode": "workspace_write",
+      "workspace_root": "/tmp/workspace",
+      "cwd": "/tmp/workspace",
+      "requires_workspace_containment": true
+    },
+    "approval": {
+      "status": "approved",
+      "request_id": "approval-2",
+      "action_hash": "sha256:dev-server",
+      "decision": "accept_for_session",
+      "actor_id": "user-1",
+      "approved_at": "2026-01-01T00:00:02.000Z"
+    },
+    "output_limits": {},
+    "cancellation": {
+      "cancellable": true,
+      "timeout_ms": 60000,
+      "token": "cancel-dev-start-1"
+    },
+    "audit": {
+      "started_event_type": "local_capability.action.started",
+      "completed_event_type": "local_capability.action.completed",
+      "failed_event_type": "local_capability.action.failed"
+    },
+    "input": {
+      "server_id": "web",
+      "executable": "npm",
+      "argv": ["run", "dev"],
+      "cwd": "/tmp/workspace",
+      "host": "127.0.0.1",
+      "port": 3000,
+      "use_shell": false,
+      "readiness": {
+        "url": "http://127.0.0.1:3000",
+        "timeout_ms": 30000
+      }
+    }
+  }
+}

package/fixtures/conformance/valid/local-action-dev-server-stop.json

@@ -0,0 +1,54 @@
+{
+  "id": "message-local-dev-server-stop",
+  "type": "local.action.request",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "request_id": "local-action-dev-stop-1",
+    "action": "local.dev_server.stop",
+    "issued_at": "2026-01-01T00:00:01.000Z",
+    "attribution": {
+      "session_id": "session-1",
+      "turn_id": "turn-1",
+      "workspace_id": "workspace-1",
+      "provider_instance_id": "provider-1",
+      "run_id": "run-1"
+    },
+    "lease": {
+      "lease_id": "local-lease-dev-server",
+      "capability_id": "dev_server",
+      "scope": "workspace",
+      "run_id": "run-1",
+      "hcp_session_id": "session-1",
+      "execution_host_id": "host-1",
+      "provider_instance_id": "provider-1",
+      "workspace_id": "workspace-1",
+      "expires_at": "2026-01-01T01:00:00.000Z"
+    },
+    "sandbox": {
+      "mode": "workspace_write",
+      "workspace_root": "/tmp/workspace",
+      "cwd": "/tmp/workspace",
+      "requires_workspace_containment": true
+    },
+    "approval": {
+      "status": "not_required"
+    },
+    "output_limits": {},
+    "cancellation": {
+      "cancellable": true,
+      "timeout_ms": 30000,
+      "token": "cancel-dev-stop-1"
+    },
+    "audit": {
+      "started_event_type": "local_capability.action.started",
+      "completed_event_type": "local_capability.action.completed",
+      "failed_event_type": "local_capability.action.failed"
+    },
+    "input": {
+      "server_id": "web",
+      "signal": "SIGTERM",
+      "timeout_ms": 30000
+    }
+  }
+}

package/fixtures/conformance/valid/local-action-error.json

@@ -0,0 +1,40 @@
+{
+  "id": "message-local-action-error",
+  "type": "local.action.error",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "request_id": "local-action-patch-1",
+    "action": "local.filesystem.patch",
+    "status": "failed",
+    "failed_at": "2026-01-01T00:00:03.000Z",
+    "attribution": {
+      "session_id": "session-1",
+      "turn_id": "turn-1",
+      "workspace_id": "workspace-1",
+      "provider_instance_id": "provider-1",
+      "run_id": "run-1"
+    },
+    "lease": {
+      "lease_id": "local-lease-patch",
+      "capability_id": "filesystem",
+      "scope": "workspace_write",
+      "run_id": "run-1",
+      "hcp_session_id": "session-1",
+      "execution_host_id": "host-1",
+      "provider_instance_id": "provider-1",
+      "workspace_id": "workspace-1"
+    },
+    "error": {
+      "code": "local_capability_expected_hash_mismatch",
+      "message": "The expected base hash did not match.",
+      "retryable": false
+    },
+    "audit_events": {
+      "failed": {
+        "event_type": "local_capability.action.failed",
+        "sequence": 12
+      }
+    }
+  }
+}

package/fixtures/conformance/valid/local-action-filesystem-list.json

@@ -0,0 +1,54 @@
+{
+  "id": "message-local-filesystem-list",
+  "type": "local.action.request",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "request_id": "local-action-list-1",
+    "action": "local.filesystem.list",
+    "issued_at": "2026-01-01T00:00:01.000Z",
+    "attribution": {
+      "session_id": "session-1",
+      "turn_id": "turn-1",
+      "workspace_id": "workspace-1",
+      "provider_instance_id": "provider-1",
+      "run_id": "run-1"
+    },
+    "lease": {
+      "lease_id": "local-lease-list",
+      "capability_id": "filesystem",
+      "scope": "workspace_read",
+      "run_id": "run-1",
+      "hcp_session_id": "session-1",
+      "execution_host_id": "host-1",
+      "provider_instance_id": "provider-1",
+      "workspace_id": "workspace-1",
+      "expires_at": "2026-01-01T01:00:00.000Z"
+    },
+    "sandbox": {
+      "mode": "workspace_write",
+      "workspace_root": "/tmp/workspace",
+      "cwd": "/tmp/workspace",
+      "requires_workspace_containment": true
+    },
+    "approval": {
+      "status": "not_required"
+    },
+    "output_limits": {
+      "entries": 200
+    },
+    "cancellation": {
+      "cancellable": false
+    },
+    "audit": {
+      "started_event_type": "local_capability.action.started",
+      "completed_event_type": "local_capability.action.completed",
+      "failed_event_type": "local_capability.action.failed"
+    },
+    "input": {
+      "path": ".",
+      "recursive": false,
+      "include_hidden": false
+    }
+  }
+}

package/fixtures/conformance/valid/local-action-filesystem-patch.json

@@ -0,0 +1,55 @@
+{
+  "id": "message-local-filesystem-patch",
+  "type": "local.action.request",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "request_id": "local-action-patch-1",
+    "action": "local.filesystem.patch",
+    "issued_at": "2026-01-01T00:00:01.000Z",
+    "attribution": {
+      "session_id": "session-1",
+      "turn_id": "turn-1",
+      "workspace_id": "workspace-1",
+      "provider_instance_id": "provider-1",
+      "run_id": "run-1"
+    },
+    "lease": {
+      "lease_id": "local-lease-patch",
+      "capability_id": "filesystem",
+      "scope": "workspace_write",
+      "run_id": "run-1",
+      "hcp_session_id": "session-1",
+      "execution_host_id": "host-1",
+      "provider_instance_id": "provider-1",
+      "workspace_id": "workspace-1",
+      "expires_at": "2026-01-01T01:00:00.000Z"
+    },
+    "sandbox": {
+      "mode": "workspace_write",
+      "workspace_root": "/tmp/workspace",
+      "cwd": "/tmp/workspace",
+      "requires_workspace_containment": true
+    },
+    "approval": {
+      "status": "not_required"
+    },
+    "output_limits": {},
+    "cancellation": {
+      "cancellable": false
+    },
+    "audit": {
+      "started_event_type": "local_capability.action.started",
+      "completed_event_type": "local_capability.action.completed",
+      "failed_event_type": "local_capability.action.failed"
+    },
+    "input": {
+      "path": "README.md",
+      "expected_base_hash": "sha256:old",
+      "patch": {
+        "format": "unified_diff",
+        "content": "--- a/README.md\n+++ b/README.md\n@@\n-old\n+new\n"
+      }
+    }
+  }
+}

package/fixtures/conformance/valid/local-action-filesystem-read.json

@@ -0,0 +1,53 @@
+{
+  "id": "message-local-filesystem-read",
+  "type": "local.action.request",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "request_id": "local-action-read-1",
+    "action": "local.filesystem.read",
+    "issued_at": "2026-01-01T00:00:01.000Z",
+    "attribution": {
+      "session_id": "session-1",
+      "turn_id": "turn-1",
+      "workspace_id": "workspace-1",
+      "provider_instance_id": "provider-1",
+      "run_id": "run-1"
+    },
+    "lease": {
+      "lease_id": "local-lease-read",
+      "capability_id": "filesystem",
+      "scope": "workspace_read",
+      "run_id": "run-1",
+      "hcp_session_id": "session-1",
+      "execution_host_id": "host-1",
+      "provider_instance_id": "provider-1",
+      "workspace_id": "workspace-1",
+      "expires_at": "2026-01-01T01:00:00.000Z"
+    },
+    "sandbox": {
+      "mode": "workspace_write",
+      "workspace_root": "/tmp/workspace",
+      "cwd": "/tmp/workspace",
+      "requires_workspace_containment": true
+    },
+    "approval": {
+      "status": "not_required"
+    },
+    "output_limits": {
+      "content_bytes": 65536
+    },
+    "cancellation": {
+      "cancellable": false
+    },
+    "audit": {
+      "started_event_type": "local_capability.action.started",
+      "completed_event_type": "local_capability.action.completed",
+      "failed_event_type": "local_capability.action.failed"
+    },
+    "input": {
+      "path": "README.md",
+      "encoding": "utf8"
+    }
+  }
+}

package/fixtures/conformance/valid/local-action-filesystem-write.json

@@ -0,0 +1,55 @@
+{
+  "id": "message-local-filesystem-write",
+  "type": "local.action.request",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "request_id": "local-action-write-1",
+    "action": "local.filesystem.write",
+    "issued_at": "2026-01-01T00:00:01.000Z",
+    "attribution": {
+      "session_id": "session-1",
+      "turn_id": "turn-1",
+      "workspace_id": "workspace-1",
+      "provider_instance_id": "provider-1",
+      "run_id": "run-1"
+    },
+    "lease": {
+      "lease_id": "local-lease-write",
+      "capability_id": "filesystem",
+      "scope": "workspace_write",
+      "run_id": "run-1",
+      "hcp_session_id": "session-1",
+      "execution_host_id": "host-1",
+      "provider_instance_id": "provider-1",
+      "workspace_id": "workspace-1",
+      "expires_at": "2026-01-01T01:00:00.000Z"
+    },
+    "sandbox": {
+      "mode": "workspace_write",
+      "workspace_root": "/tmp/workspace",
+      "cwd": "/tmp/workspace",
+      "requires_workspace_containment": true
+    },
+    "approval": {
+      "status": "not_required"
+    },
+    "output_limits": {},
+    "cancellation": {
+      "cancellable": false
+    },
+    "audit": {
+      "started_event_type": "local_capability.action.started",
+      "completed_event_type": "local_capability.action.completed",
+      "failed_event_type": "local_capability.action.failed"
+    },
+    "input": {
+      "path": "README.md",
+      "content": "updated",
+      "encoding": "utf8",
+      "mode": "overwrite",
+      "create_parents": false,
+      "expected_base_hash": "sha256:old"
+    }
+  }
+}

package/fixtures/conformance/valid/local-action-git-diff.json

@@ -0,0 +1,53 @@
+{
+  "id": "message-local-git-diff",
+  "type": "local.action.request",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "request_id": "local-action-git-diff-1",
+    "action": "local.git.diff",
+    "issued_at": "2026-01-01T00:00:01.000Z",
+    "attribution": {
+      "session_id": "session-1",
+      "turn_id": "turn-1",
+      "workspace_id": "workspace-1",
+      "provider_instance_id": "provider-1",
+      "run_id": "run-1"
+    },
+    "lease": {
+      "lease_id": "local-lease-git-diff",
+      "capability_id": "git",
+      "scope": "workspace_read",
+      "run_id": "run-1",
+      "hcp_session_id": "session-1",
+      "execution_host_id": "host-1",
+      "provider_instance_id": "provider-1",
+      "workspace_id": "workspace-1",
+      "expires_at": "2026-01-01T01:00:00.000Z"
+    },
+    "sandbox": {
+      "mode": "workspace_write",
+      "workspace_root": "/tmp/workspace",
+      "cwd": "/tmp/workspace",
+      "requires_workspace_containment": true
+    },
+    "approval": {
+      "status": "not_required"
+    },
+    "output_limits": {
+      "diff_bytes": 65536
+    },
+    "cancellation": {
+      "cancellable": false
+    },
+    "audit": {
+      "started_event_type": "local_capability.action.started",
+      "completed_event_type": "local_capability.action.completed",
+      "failed_event_type": "local_capability.action.failed"
+    },
+    "input": {
+      "paths": ["README.md"],
+      "staged": false
+    }
+  }
+}

package/fixtures/conformance/valid/local-action-git-status.json

@@ -0,0 +1,53 @@
+{
+  "id": "message-local-git-status",
+  "type": "local.action.request",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "request_id": "local-action-git-status-1",
+    "action": "local.git.status",
+    "issued_at": "2026-01-01T00:00:01.000Z",
+    "attribution": {
+      "session_id": "session-1",
+      "turn_id": "turn-1",
+      "workspace_id": "workspace-1",
+      "provider_instance_id": "provider-1",
+      "run_id": "run-1"
+    },
+    "lease": {
+      "lease_id": "local-lease-git-status",
+      "capability_id": "git",
+      "scope": "workspace_read",
+      "run_id": "run-1",
+      "hcp_session_id": "session-1",
+      "execution_host_id": "host-1",
+      "provider_instance_id": "provider-1",
+      "workspace_id": "workspace-1",
+      "expires_at": "2026-01-01T01:00:00.000Z"
+    },
+    "sandbox": {
+      "mode": "workspace_write",
+      "workspace_root": "/tmp/workspace",
+      "cwd": "/tmp/workspace",
+      "requires_workspace_containment": true
+    },
+    "approval": {
+      "status": "not_required"
+    },
+    "output_limits": {
+      "status_bytes": 65536
+    },
+    "cancellation": {
+      "cancellable": false
+    },
+    "audit": {
+      "started_event_type": "local_capability.action.started",
+      "completed_event_type": "local_capability.action.completed",
+      "failed_event_type": "local_capability.action.failed"
+    },
+    "input": {
+      "porcelain_version": "v1",
+      "include_branch": true
+    }
+  }
+}

package/fixtures/conformance/valid/local-action-response.json

@@ -0,0 +1,49 @@
+{
+  "id": "message-local-action-response",
+  "type": "local.action.response",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "request_id": "local-action-shell-1",
+    "action": "local.shell.exec",
+    "status": "completed",
+    "completed_at": "2026-01-01T00:00:03.000Z",
+    "attribution": {
+      "session_id": "session-1",
+      "turn_id": "turn-1",
+      "workspace_id": "workspace-1",
+      "provider_instance_id": "provider-1",
+      "run_id": "run-1"
+    },
+    "lease": {
+      "lease_id": "local-lease-shell",
+      "capability_id": "shell",
+      "scope": "workspace",
+      "run_id": "run-1",
+      "hcp_session_id": "session-1",
+      "execution_host_id": "host-1",
+      "provider_instance_id": "provider-1",
+      "workspace_id": "workspace-1"
+    },
+    "output": {
+      "executable": "npm",
+      "argv": ["test"],
+      "cwd": "/tmp/workspace",
+      "exit_code": 0,
+      "signal": null,
+      "stdout": "ok\n",
+      "stderr": "",
+      "timed_out": false
+    },
+    "audit_events": {
+      "started": {
+        "event_type": "local_capability.action.started",
+        "sequence": 10
+      },
+      "completed": {
+        "event_type": "local_capability.action.completed",
+        "sequence": 11
+      }
+    }
+  }
+}