agent-hitch 0.1.0

package/docs/schemas/result.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-hitch.local/schemas/result.schema.json",
+  "title": "Hitch run result",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schema_version", "run_id", "status", "exit_code", "completed_at"],
+  "properties": {
+    "schema_version": {
+      "const": "1"
+    },
+    "run_id": {
+      "type": "string",
+      "pattern": "^run_[a-f0-9]{32}$"
+    },
+    "status": {
+      "enum": ["succeeded", "failed", "timed_out", "cancelled"]
+    },
+    "exit_code": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "output": {
+      "type": "string"
+    },
+    "error": {
+      "type": "object",
+      "required": ["code", "message"],
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "message": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "started_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "completed_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}

package/docs/schemas/run-request.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-hitch.local/schemas/run-request.schema.json",
+  "title": "Hitch run request",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["prompt"],
+  "oneOf": [
+    {
+      "required": ["harness_ref"],
+      "not": { "required": ["agent"] }
+    },
+    {
+      "required": ["agent"],
+      "not": { "required": ["harness_ref"] }
+    }
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "1"
+    },
+    "agent": {
+      "type": "string",
+      "minLength": 1
+    },
+    "harness_ref": {
+      "type": "string",
+      "minLength": 1
+    },
+    "model": {
+      "type": "string"
+    },
+    "cwd": {
+      "type": "string",
+      "minLength": 1
+    },
+    "workspace_mode": {
+      "enum": ["shared", "worktree", "copy"],
+      "default": "shared"
+    },
+    "prompt": {
+      "type": "string",
+      "minLength": 1
+    },
+    "timeout_ms": {
+      "type": "number",
+      "minimum": 0
+    },
+    "agent_args": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}

package/docs/schemas/workspace.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-hitch.local/schemas/workspace.schema.json",
+  "title": "Hitch run workspace record",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schema_version",
+    "run_id",
+    "mode",
+    "status",
+    "source_workspace",
+    "source_realpath",
+    "execution_workspace",
+    "snapshot",
+    "retained"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "run_id": { "type": "string", "pattern": "^run_[a-f0-9]{32}$" },
+    "mode": { "enum": ["shared", "worktree", "copy"] },
+    "status": {
+      "enum": [
+        "planned",
+        "provisioning",
+        "ready",
+        "running",
+        "retained",
+        "orphaned",
+        "released",
+        "cancelled",
+        "failed",
+        "unused",
+        "removed"
+      ]
+    },
+    "source_workspace": { "type": "string", "minLength": 1 },
+    "source_realpath": { "type": "string", "minLength": 1 },
+    "execution_workspace": { "type": "string", "minLength": 1 },
+    "changed": { "type": ["boolean", "null"] },
+    "retained": { "type": "boolean" },
+    "snapshot": {
+      "type": "object",
+      "required": ["consistency", "source_subdirectory"],
+      "properties": {
+        "consistency": { "enum": ["none", "git_commit", "best_effort"] },
+        "commit": { "type": "string", "pattern": "^[a-f0-9]{40,64}$" },
+        "source_subdirectory": { "type": "string" },
+        "content_digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+        "captured_at": { "type": "string", "format": "date-time" }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/integrations/harbor/hitch_harbor_agent.py

@@ -0,0 +1,217 @@
+"""Harbor custom agent that runs an immutable harness through Hitch in a trial container."""
+
+from __future__ import annotations
+
+import json
+import shlex
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from harbor.agents.base import BaseAgent
+from harbor.environments.base import BaseEnvironment, ExecResult
+from harbor.models.agent.context import AgentContext
+
+
+class HitchHarborAgent(BaseAgent):
+    """Upload Hitch into a Harbor environment and delegate the agent phase to it."""
+
+    def __init__(
+        self,
+        logs_dir: Path,
+        harness_ref: str,
+        revision_identity: str,
+        hitch_runtime_dir: str,
+        candidate_id: str = "candidate-1",
+        hitch_timeout_ms: int = 900_000,
+        agent_args: list[str] | None = None,
+        workdir: str = "/app",
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(logs_dir=logs_dir, **kwargs)
+        self.harness_ref = harness_ref
+        self.revision_identity = revision_identity
+        self.hitch_runtime_dir = Path(hitch_runtime_dir)
+        self.candidate_id = candidate_id
+        self.hitch_timeout_ms = int(hitch_timeout_ms)
+        self.agent_args = list(agent_args or [])
+        self.workdir = workdir
+        self._hitch_version: str | None = None
+
+    @staticmethod
+    def name() -> str:
+        return "hitch"
+
+    def version(self) -> str | None:
+        return self._hitch_version
+
+    async def setup(self, environment: BaseEnvironment) -> None:
+        if not self.hitch_runtime_dir.is_dir():
+            raise RuntimeError(f"Hitch runtime directory does not exist: {self.hitch_runtime_dir}")
+        await environment.upload_dir(self.hitch_runtime_dir, "/opt/hitch")
+        await self._ensure_node(environment)
+        version = await self._exec(environment, f"{self._node_prefix()} node /opt/hitch/bin/hitch.js --version")
+        self._hitch_version = (version.stdout or "").strip() or None
+        prepare = " ".join(
+            [
+                self._node_prefix(),
+                "HITCH_ROOT=/tmp/hitch-state",
+                "node /opt/hitch/bin/hitch.js prepare",
+                shlex.quote(self.harness_ref),
+                "--json",
+            ]
+        )
+        await self._exec(environment, prepare)
+
+    async def run(
+        self,
+        instruction: str,
+        environment: BaseEnvironment,
+        context: AgentContext,
+    ) -> None:
+        self.logs_dir.mkdir(parents=True, exist_ok=True)
+        temporary: Path | None = None
+        try:
+            with tempfile.NamedTemporaryFile(
+                mode="w",
+                encoding="utf-8",
+                prefix="hitch-instruction-",
+                suffix=".txt",
+                dir=self.logs_dir,
+                delete=False,
+            ) as handle:
+                handle.write(instruction)
+                temporary = Path(handle.name)
+            remote_instruction = "/tmp/hitch-instruction.txt"
+            await environment.upload_file(temporary, remote_instruction)
+        finally:
+            if temporary is not None:
+                temporary.unlink(missing_ok=True)
+
+        arguments = [
+            self._node_prefix(),
+            "HITCH_ROOT=/tmp/hitch-state",
+            "node /opt/hitch/bin/hitch.js run",
+            "--harness",
+            shlex.quote(self.harness_ref),
+            "--cwd",
+            shlex.quote(self.workdir),
+            "--workspace-mode",
+            "shared",
+            "--prompt-file",
+            shlex.quote(remote_instruction),
+            "--timeout",
+            str(self.hitch_timeout_ms),
+            "--output",
+            "jsonl",
+        ]
+        if self.model_name:
+            arguments.extend(["--model", shlex.quote(self.model_name)])
+        for value in self.agent_args:
+            arguments.extend(["--agent-arg", shlex.quote(value)])
+        command = (
+            "set -o pipefail; "
+            + " ".join(arguments)
+            + " 2> >(tee /logs/agent/hitch-stderr.log >&2)"
+            + " | tee /logs/agent/hitch-events.jsonl"
+        )
+        execution = await environment.exec(command, cwd=self.workdir)
+        events = self._events(execution.stdout or "")
+        run_id = next((event.get("run_id") for event in events if event.get("run_id")), None)
+        hitch_result = None
+        if run_id:
+            result_path = f"/tmp/hitch-state/runs/{run_id}/result.json"
+            result = await environment.exec(
+                f"cat {shlex.quote(result_path)} | tee /logs/agent/hitch-result.json"
+            )
+            if result.return_code == 0 and result.stdout:
+                hitch_result = json.loads(result.stdout)
+        context.metadata = {
+            "candidate_id": self.candidate_id,
+            "harness_ref": self.harness_ref,
+            "revision_identity": self.revision_identity,
+            "hitch_run_id": run_id,
+            "hitch_status": hitch_result.get("status") if hitch_result else None,
+            "hitch_artifact_id": hitch_result.get("artifact_id") if hitch_result else None,
+        }
+        if execution.return_code != 0:
+            message = (execution.stderr or "").strip()
+            if hitch_result and hitch_result.get("error", {}).get("message"):
+                message = hitch_result["error"]["message"]
+            raise RuntimeError(
+                f"Hitch agent run failed with code {execution.return_code}: {message or 'no diagnostic output'}"
+            )
+        if hitch_result is None:
+            raise RuntimeError("Hitch agent run completed without a persisted result")
+        if hitch_result.get("revision_identity") != self.revision_identity:
+            raise RuntimeError(
+                "Hitch resolved a different harness revision inside the trial container: "
+                f"expected {self.revision_identity}, got {hitch_result.get('revision_identity')}"
+            )
+
+    async def _ensure_node(self, environment: BaseEnvironment) -> None:
+        probe = await environment.exec(
+            "node -e 'process.exit(Number(process.versions.node.split(\".\")[0]) >= 22 ? 0 : 1)'"
+        )
+        needs_git = "@commit:" in self.harness_ref
+        git_probe = await environment.exec("command -v git >/dev/null 2>&1")
+        if probe.return_code == 0 and (not needs_git or git_probe.return_code == 0):
+            return
+        prerequisites = """
+set -eu
+if command -v curl >/dev/null 2>&1 && command -v git >/dev/null 2>&1; then exit 0; fi
+if command -v apt-get >/dev/null 2>&1; then
+  apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y curl ca-certificates git
+elif command -v apk >/dev/null 2>&1; then
+  apk add --no-cache curl ca-certificates git bash
+elif command -v dnf >/dev/null 2>&1; then
+  dnf install -y curl ca-certificates git
+elif command -v yum >/dev/null 2>&1; then
+  yum install -y curl ca-certificates git
+else
+  echo 'Hitch requires Node.js 22+ and could not install curl in this task image' >&2
+  exit 1
+fi
+"""
+        await self._exec(environment, prerequisites, user=0)
+        if probe.return_code == 0:
+            return
+        install = """
+set -eu
+export NVM_DIR=/opt/hitch-node
+mkdir -p "$NVM_DIR"
+curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
+. "$NVM_DIR/nvm.sh"
+nvm install 22
+nvm alias default 22
+node -e 'process.exit(Number(process.versions.node.split(".")[0]) >= 22 ? 0 : 1)'
+"""
+        await self._exec(environment, install, user=0)
+
+    @staticmethod
+    def _node_prefix() -> str:
+        return "if [ -s /opt/hitch-node/nvm.sh ]; then export NVM_DIR=/opt/hitch-node; . /opt/hitch-node/nvm.sh; fi;"
+
+    @staticmethod
+    def _events(output: str) -> list[dict[str, Any]]:
+        events: list[dict[str, Any]] = []
+        for line in output.splitlines():
+            try:
+                value = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(value, dict):
+                events.append(value)
+        return events
+
+    @staticmethod
+    async def _exec(
+        environment: BaseEnvironment,
+        command: str,
+        user: str | int | None = None,
+    ) -> ExecResult:
+        result = await environment.exec(command, user=user)
+        if result.return_code != 0:
+            diagnostic = (result.stderr or result.stdout or "no output").strip()
+            raise RuntimeError(f"container setup command failed ({result.return_code}): {diagnostic}")
+        return result

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "agent-hitch",
+  "version": "0.1.0",
+  "description": "A local runtime and daemon for coding agents",
+  "keywords": [
+    "ai-agents",
+    "cli",
+    "coding-agents",
+    "daemon"
+  ],
+  "homepage": "https://github.com/rsi-gear/agent-hitch#readme",
+  "bugs": {
+    "url": "https://github.com/rsi-gear/agent-hitch/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rsi-gear/agent-hitch.git"
+  },
+  "type": "module",
+  "bin": {
+    "hitch": "bin/hitch.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "integrations/harbor/hitch_harbor_agent.py",
+    "docs/schemas/"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "coverage": "node --experimental-test-coverage --test-coverage-include=src/*.js --test-coverage-lines=75 --test-coverage-branches=65 --test-coverage-functions=70 --test",
+    "check": "node scripts/check-syntax.js && node --test",
+    "prepublishOnly": "npm run check"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0"
+}