@harness-control/protocol 0.1.0

package/fixtures/conformance/valid/local-action-shell-exec.json

@@ -0,0 +1,63 @@
+{
+  "id": "message-local-shell-exec",
+  "type": "local.action.request",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "request_id": "local-action-shell-1",
+    "action": "local.shell.exec",
+    "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-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",
+      "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-1",
+      "action_hash": "sha256:action",
+      "decision": "accept",
+      "actor_id": "user-1",
+      "approved_at": "2026-01-01T00:00:02.000Z"
+    },
+    "output_limits": {
+      "stdout_bytes": 65536,
+      "stderr_bytes": 65536
+    },
+    "cancellation": {
+      "cancellable": true,
+      "timeout_ms": 60000,
+      "token": "cancel-shell-1"
+    },
+    "audit": {
+      "started_event_type": "local_capability.action.started",
+      "completed_event_type": "local_capability.action.completed",
+      "failed_event_type": "local_capability.action.failed"
+    },
+    "input": {
+      "executable": "npm",
+      "argv": ["test"],
+      "cwd": "/tmp/workspace",
+      "use_shell": false
+    }
+  }
+}

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

@@ -0,0 +1,18 @@
+{
+  "id": "message-provider-event",
+  "type": "harness.event",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "session_id": "session-1",
+    "sequence": 2,
+    "event_type": "provider.codex.native_event",
+    "created_at": "2026-01-01T00:00:02.000Z",
+    "data": {
+      "summary": "Native provider event",
+      "fields": {
+        "provider_event_id": "evt-1"
+      }
+    }
+  }
+}

package/fixtures/conformance/valid/session-snapshot-request.json

@@ -0,0 +1,9 @@
+{
+  "id": "message-session-snapshot-request",
+  "type": "harness.session.snapshot.request",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "session_id": "session-1"
+  }
+}

package/fixtures/conformance/valid/session-snapshot.json

@@ -0,0 +1,28 @@
+{
+  "id": "message-session-snapshot",
+  "type": "harness.session.snapshot",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:01.000Z",
+  "payload": {
+    "command_id": "message-session-snapshot-request",
+    "session_id": "session-1",
+    "generated_at": "2026-01-01T00:00:01.000Z",
+    "completeness": "complete",
+    "omission_semantics": "replace",
+    "from_sequence": 1,
+    "through_sequence": 1,
+    "events": [
+      {
+        "session_id": "session-1",
+        "sequence": 1,
+        "event_type": "session.started",
+        "created_at": "2026-01-01T00:00:00.500Z",
+        "data": {
+          "provider_instance_id": "provider-1",
+          "workspace_id": "workspace-1"
+        }
+      }
+    ],
+    "tombstones": []
+  }
+}

package/fixtures/conformance/valid/session-start-with-leases.json

@@ -0,0 +1,80 @@
+{
+  "id": "message-session-start",
+  "type": "harness.session.start",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "session_id": "session-1",
+    "workspace_id": "workspace-1",
+    "provider_instance_id": "provider-1",
+    "driver_kind": "codex",
+    "cwd": "/tmp/workspace",
+    "sandbox_mode": "workspace_write",
+    "approval_policy": "ask",
+    "continue_session": false,
+    "model_selection": {
+      "model": "gpt-5.3-codex"
+    },
+    "workspace_preflight": {
+      "workspace_id": "workspace-1",
+      "expected_branch": "main",
+      "allow_dirty_worktree": true
+    },
+    "local_capability_lease": {
+      "lease_id": "local-lease-1",
+      "org_id": "org-1",
+      "actor_id": "user-1",
+      "workflow_id": "workflow-1",
+      "run_id": "run-1",
+      "node_id": "node-harness",
+      "hcp_session_id": "session-1",
+      "execution_host_id": "host-local",
+      "provider_instance_id": "provider-1",
+      "workspace_id": "workspace-1",
+      "issued_at": "2026-01-01T00:00:00.000Z",
+      "expires_at": "2026-01-01T01:00:00.000Z",
+      "policy_version": "policy-2026-01-01",
+      "capabilities": [
+        {
+          "id": "filesystem",
+          "scopes": ["workspace_read", "workspace_write"]
+        },
+        {
+          "id": "shell",
+          "scopes": ["workspace"],
+          "approval_policy": "ask",
+          "command_policy": {
+            "allowed_executables": ["npm"],
+            "denied_executables": ["rm"],
+            "cwd_policy": "selected_workspace_only",
+            "env_policy": "minimal",
+            "allow_shell": false,
+            "timeout_seconds": 60,
+            "network_policy": "inherit"
+          }
+        }
+      ]
+    },
+    "mcp_servers": [
+      {
+        "name": "linear",
+        "transport": "streamable_http",
+        "url": "https://example.com/mcp/linear",
+        "headers": {
+          "Authorization": "Bearer lease-token"
+        },
+        "lease_id": "mcp-lease-1",
+        "proof_of_possession": {
+          "scheme": "runner_signed_request",
+          "key_id": "proof-key-1",
+          "required_headers": [
+            "x-hcp-session-id",
+            "x-hcp-host-id",
+            "x-hcp-proof-signature",
+            "x-hcp-proof-nonce"
+          ]
+        }
+      }
+    ]
+  }
+}

package/fixtures/conformance/valid/session-start-with-runner-stdio-profile.json

@@ -0,0 +1,27 @@
+{
+  "id": "message-runner-stdio-profile",
+  "type": "harness.session.start",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "session_id": "session-stdio-1",
+    "workspace_id": "workspace-1",
+    "provider_instance_id": "provider-1",
+    "driver_kind": "codex",
+    "cwd": "/tmp/workspace",
+    "sandbox_mode": "workspace_write",
+    "approval_policy": "ask",
+    "continue_session": false,
+    "model_selection": {
+      "model": "gpt-5.3-codex"
+    },
+    "mcp_servers": [
+      {
+        "name": "local-tools",
+        "transport": "runner_stdio_profile",
+        "profile_id": "sample-tools",
+        "allowed_tools": ["echo"]
+      }
+    ]
+  }
+}

package/fixtures/conformance/valid/turn-completed.json

@@ -0,0 +1,30 @@
+{
+  "id": "message-turn-completed",
+  "type": "harness.event",
+  "version": "hcp.v0",
+  "sent_at": "2026-01-01T00:00:00.000Z",
+  "payload": {
+    "session_id": "session-1",
+    "turn_id": "turn-1",
+    "sequence": 4,
+    "event_type": "turn.completed",
+    "created_at": "2026-01-01T00:00:04.000Z",
+    "data": {
+      "status": "accepted",
+      "final_output": {
+        "final_text": "Done.",
+        "changed_files": [
+          {
+            "path": "README.md",
+            "change_type": "modified"
+          }
+        ],
+        "usage": {
+          "input_tokens": 10,
+          "output_tokens": 5,
+          "total_tokens": 15
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@harness-control/protocol",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "hcp-protocol-conformance": "./dist/bin/conformance.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./conformance": {
+      "types": "./dist/conformance.d.ts",
+      "import": "./dist/conformance.js"
+    },
+    "./json-schema": {
+      "types": "./dist/json-schema.d.ts",
+      "import": "./dist/json-schema.js"
+    },
+    "./schema.json": {
+      "default": "./schemas/hcp-message.schema.json"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b && npm run schema:generate",
+    "check": "tsc -b --pretty false",
+    "conformance": "tsx src/bin/conformance.ts --fixtures fixtures/conformance",
+    "schema:generate": "tsx src/bin/generate-json-schema.ts",
+    "test": "tsx --test src/**/*.test.ts test/**/*.test.ts"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "description": "Types, validation, JSON Schema and reducers for Harness Control Protocol",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qazisaad/harness-control-protocol.git",
+    "directory": "packages/hcp-protocol"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/test/**",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE",
+    "schemas",
+    "fixtures/conformance"
+  ]
+}