@uchibeke/gallivant 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,107 @@
 {
   "name": "@uchibeke/gallivant",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Turn repository tasks into reviewed pull requests with local or hosted agents, acceptance checks and a persistent review loop.",
+  "type": "module",
+  "bin": {
+    "gallivant": "bin/gallivant.mjs",
+    "task-delivery-package": "bin/package-plugin.mjs",
+    "task-delivery-state": "bin/task-delivery-state.mjs"
+  },
+  "exports": {
+    ".": "./lib/tasks.mjs",
+    "./tasks": "./lib/tasks.mjs",
+    "./context": "./lib/context.mjs",
+    "./execution": "./lib/execution.mjs",
+    "./execution-result": "./lib/execution_result.mjs",
+    "./capabilities": "./lib/capabilities.mjs",
+    "./task-delivery": "./lib/task_delivery.mjs",
+    "./task-delivery/contracts": "./lib/task_delivery_contract.mjs",
+    "./task-delivery/views": "./lib/task_delivery_view.mjs",
+    "./task-delivery/store": "./lib/task_delivery_store.mjs",
+    "./task-delivery/mcp": "./lib/task_delivery_mcp.mjs",
+    "./runtime/coordinator": "./lib/coordinator.mjs",
+    "./runtime/node": "./lib/runtime_node.mjs",
+    "./runtime/state": "./lib/runtime_state.mjs",
+    "./providers/openai-agents": "./lib/openai_agents.mjs",
+    "./providers/codex-cloud": "./lib/codex_cloud.mjs",
+    "./plugin-package": "./lib/plugin_package.mjs",
+    "./lib/*": "./lib/*",
+    "./package.json": "./package.json",
+    "./runtime/node/dependencies": "./lib/runtime_dependencies.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "templates",
+    "README.md",
+    "LICENSE",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "docs/*.md",
+    "npm-shrinkwrap.json"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "test:install": "node test/install-package.mjs",
+    "test:learning": "node --test test/learning.test.mjs test/learning-openssh.test.mjs test/learning-dispatch.test.mjs",
+    "test:learning:live": "node test/learning-live.mjs",
+    "test:execution-backends": "node --test test/execution-backends.test.mjs test/execution-preparation.test.mjs test/probe.test.mjs test/chains.test.mjs test/loop.test.mjs test/recovery.test.mjs test/review.test.mjs test/control.test.mjs test/tracker_controls.test.mjs test/tracker.test.mjs test/public_format.test.mjs test/public_output.test.mjs",
+    "test:openai-agents": "node --test test/openai-agents.test.mjs",
+    "test:openai-agents:live": "node test/openai-agents-live.mjs",
+    "test:openai-agents:preparation:live": "node test/openai-agents-preparation-live.mjs",
+    "test:codex-cloud": "node --test test/codex-cloud.test.mjs && node --test --test-name-pattern='codex-cloud|result publication validates|verified publication recovery|failed remote verification|deterministic publication rejection|interrupted verification' test/execution-backends.test.mjs",
+    "test:codex-cloud:live": "node test/codex-cloud-live.mjs",
+    "test:task-intake": "node --test test/task-intake.test.mjs",
+    "test:live-harnesses": "node test/live-harnesses.mjs",
+    "test:plugin-package": "node test/plugin-package.mjs",
+    "package:plugin": "node bin/package-plugin.mjs",
+    "lint": "node --check bin/release-package.mjs && node --check bin/release-live.mjs && node --check bin/gallivant.mjs && node --check bin/package-plugin.mjs && node --check bin/task-delivery-state.mjs && for f in lib/*.mjs lib/*/*.mjs; do node --check \"$f\" || exit 1; done",
+    "test:release-package": "node --test test/release-package.test.mjs",
+    "release:preflight": "node bin/release-package.mjs --mode preflight",
+    "release:package": "node bin/release-package.mjs --mode build",
+    "release:validate": "node bin/release-package.mjs --mode validate",
+    "test:release:live": "node bin/release-live.mjs",
+    "test:release:host": "node bin/release-live.mjs --host"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "pull-request",
+    "autonomous",
+    "agent",
+    "aport"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uchibeke/gallivant.git"
+  },
+  "dependencies": {
+    "ajv": "8.20.0",
+    "pngjs": "7.0.0",
+    "smol-toml": "1.9.0"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "esbuild": "0.28.2"
+  },
+  "bundledDependencies": [
+    "smol-toml"
+  ]
+}

package/templates/claude-settings.json

@@ -0,0 +1,18 @@
+{
+  "_comment": "Merge the sandbox block into ~/.gallivant/claude/settings.json after the APort installer has written the hooks block there. On macOS, enableWeakerNetworkIsolation permits Apple's trustd.agent so gh can verify TLS certificates; it opens a potential exfiltration route through that service. It has no effect on Linux. See docs/guardrails.md. Keep this in operator-owned settings, never project settings.",
+  "sandbox": {
+    "enabled": true,
+    "autoAllowBashIfSandboxed": true,
+    "enableWeakerNetworkIsolation": true,
+    "network": {
+      "allowedDomains": [
+        "github.com",
+        "api.github.com",
+        "*.githubusercontent.com",
+        "registry.npmjs.org",
+        "pypi.org",
+        "files.pythonhosted.org"
+      ]
+    }
+  }
+}

package/templates/passport.gallivant.json

@@ -0,0 +1,83 @@
+{
+  "passport_id": "00000000-0000-4000-8000-000000000000",
+  "kind": "template",
+  "spec_version": "oap/1.0",
+  "owner_id": "user_gallivant",
+  "owner_type": "user",
+  "assurance_level": "L2",
+  "status": "active",
+  "capabilities": [
+    { "id": "data.file.read", "params": {} },
+    { "id": "data.file.write", "params": {} },
+    { "id": "system.command.execute", "params": {} },
+    { "id": "web.fetch", "params": {} },
+    { "id": "agent.session.create", "params": {} }
+  ],
+  "limits": {
+    "data.file.write": {
+      "allowed_paths": ["{{worktrees}}/**"],
+      "blocked_paths": [
+        "{{home}}/.claude/**",
+        "{{home}}/.codex/**",
+        "{{home}}/.config/opencode/**",
+        "{{home}}/.gallivant/**",
+        "{{home}}/.aport/**",
+        "**/.env",
+        "**/.env.*"
+      ]
+    },
+    "data.file.read": {
+      "blocked_patterns": [
+        "**/.env",
+        "**/.env.*",
+        "{{home}}/.claude/**",
+        "{{home}}/.codex/**",
+        "{{home}}/.config/opencode/**",
+        "{{home}}/.gallivant/**",
+        "{{home}}/.aport/**",
+        "{{home}}/.ssh/**",
+        "{{home}}/.aws/**",
+        "**/auth.json",
+        "**/*.pem",
+        "**/*.key"
+      ]
+    },
+    "system.command.execute": {
+      "allowed_commands": ["*"],
+      "blocked_patterns": [
+        "push --force",
+        "push -f",
+        "--force-with-lease",
+        "push origin main",
+        "push origin master",
+        "HEAD:main",
+        "HEAD:master",
+        "--no-verify",
+        "sudo",
+        "rm -rf ~",
+        "rm -rf /",
+        "gh auth token",
+        "security find-",
+        "launchctl",
+        "printenv",
+        "auth.json"
+      ],
+      "max_execution_time": 1800,
+      "require_confirmation": false
+    },
+    "web.fetch": {
+      "allowed_domains": [
+        "github.com",
+        "api.github.com",
+        "raw.githubusercontent.com",
+        "registry.npmjs.org",
+        "pypi.org",
+        "files.pythonhosted.org"
+      ]
+    }
+  },
+  "regions": [],
+  "created_at": "2026-09-23T00:00:00Z",
+  "updated_at": "2026-09-23T00:00:00Z",
+  "version": "1.0.0"
+}

package/templates/plugin/bundled-runtime.json

@@ -0,0 +1,26 @@
+{
+  "package": "smol-toml",
+  "version": "1.9.0",
+  "integrity": "sha512-hpd+HLON7HdZXqYchMM/+LaTTbdK0AU3NngIJ4KVyWbY9bfQqdL9cD+4yf6dUoU2Ap4VsU0JkQi6FxAI1B2mXQ==",
+  "files": {
+    "node_modules/smol-toml/LICENSE": "fa5659948374d4f555594f47f6da073b40dc503e921aeeece30df4362b3051a5",
+    "node_modules/smol-toml/README.md": "bcaaa3befbd5bc5373cc6d80f4502afbe83179f96dcf9a336c43deb7ffa24c65",
+    "node_modules/smol-toml/dist/date.d.ts": "c7ad3531c131f2b5b246b2d208b75c5403475ad155b7661fa2d673104b806791",
+    "node_modules/smol-toml/dist/date.js": "ef924a2a42c7f16761e7098c3ed8e04195ecbcb02d5c369db0aee76f251a409c",
+    "node_modules/smol-toml/dist/error.d.ts": "02e33cdc5ca75f517f44b31070640be0fe6d0169dd91c266d02a1e2a71e064ac",
+    "node_modules/smol-toml/dist/error.js": "76f8e47f5fc57273748242d59570656d7c921a80bceb2291ca5a4d7a723e9f29",
+    "node_modules/smol-toml/dist/extract.js": "b964c8f39c737172295b31b9ee61b49e513ff12788e119ddfdbb68c448054c12",
+    "node_modules/smol-toml/dist/index.cjs": "09ce310a8bcc1bb5c7dc2813c88b4bfbbeb685e4c186a9631ff54da7e85c880f",
+    "node_modules/smol-toml/dist/index.d.ts": "b4556819c2ed0cd4016d05a6bfd7d4773c0b5ffb39c8ed547796ce4a1093d9b8",
+    "node_modules/smol-toml/dist/index.js": "dc8e0afc74477e514f5cb8492b587560c1d7d68cec03a994cc8bc4af99c8da2a",
+    "node_modules/smol-toml/dist/parse.d.ts": "2b230dc984b6e51b545bfe222f9965cc2ff434164ed9428bec415c5e508a9854",
+    "node_modules/smol-toml/dist/parse.js": "195e33ea068bf6f3acb5b3342792ac4aa954bba7e751519ba869c00da395ecdb",
+    "node_modules/smol-toml/dist/primitive.js": "be47fe90bf9a410af0b9204b6b34617f4b38e57f08198b10cb024a0272eb5936",
+    "node_modules/smol-toml/dist/stringify.d.ts": "628a6a55714fcf4a4eb0e59866ab1e5cc67c1b9e0cfc8524ccc8d6b5ee24ad7c",
+    "node_modules/smol-toml/dist/stringify.js": "c717d95456426dc8a0b07c9d03a4e434d5dea8254fca24e5fd93a22de3bcd44c",
+    "node_modules/smol-toml/dist/struct.js": "736742cfa645bbd08bc5396c5f7ddbea5c3b7ac5d61fe86031846f5769131deb",
+    "node_modules/smol-toml/dist/util.d.ts": "e6b1d3eecb240dc71d0dc28d1beee69cefd6ee014507c822909be0a7117517e0",
+    "node_modules/smol-toml/dist/util.js": "6327e40efd957128da15867c3a32293950a925570b457b1b78c735452cebc08e",
+    "node_modules/smol-toml/package.json": "0e35bde6992fef675058596ea0e94c2d3ca65e5f9b73a326d94208be6210f192"
+  }
+}

package/templates/plugin/schemas/mcp.schema.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "title": "Agent Plugins MCP Configuration",
+  "description": "Machine-readable schema for mcp.json in Agent Plugins 1.0.0. The Agent Plugins specification defines additional semantic and operational requirements.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "const": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+      "description": "Canonical identifier of the MCP configuration schema for the Agent Plugins version targeted by this document."
+    },
+    "mcpServers": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/server"
+      }
+    }
+  },
+  "required": ["$schema", "mcpServers"],
+  "additionalProperties": false,
+  "$defs": {
+    "server": {
+      "title": "MCP server",
+      "oneOf": [
+        {
+          "$ref": "#/$defs/stdioServer"
+        },
+        {
+          "$ref": "#/$defs/streamableHttpServer"
+        },
+        {
+          "$ref": "#/$defs/sseServer"
+        }
+      ]
+    },
+    "stdioServer": {
+      "title": "stdio MCP server",
+      "type": "object",
+      "properties": {
+        "type": {
+          "const": "stdio"
+        },
+        "command": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Executable token. Resolution rules are defined by the Agent Plugins specification."
+        },
+        "args": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "env": {
+          "type": "object",
+          "propertyNames": {
+            "not": {
+              "enum": ["PLUGIN_ROOT", "PLUGIN_DATA"]
+            }
+          },
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "cwd": {
+          "type": "string",
+          "pattern": "^(?:\\./|\\$\\{PLUGIN_ROOT\\}(?:/|$)|\\$\\{PLUGIN_DATA\\}(?:/|$))",
+          "description": "Plugin-relative, PLUGIN_ROOT-rooted, or PLUGIN_DATA-rooted working directory. Filesystem containment is validated separately."
+        }
+      },
+      "required": ["type", "command"],
+      "additionalProperties": false
+    },
+    "streamableHttpServer": {
+      "title": "Streamable HTTP MCP server",
+      "type": "object",
+      "properties": {
+        "type": {
+          "const": "streamable-http"
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1,
+          "description": "MCP endpoint URL. URL semantics are defined by the Agent Plugins specification."
+        },
+        "headers": {
+          "$ref": "#/$defs/headers"
+        }
+      },
+      "required": ["type", "url"],
+      "additionalProperties": false
+    },
+    "sseServer": {
+      "title": "Legacy HTTP+SSE MCP server",
+      "type": "object",
+      "properties": {
+        "type": {
+          "const": "sse"
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1,
+          "description": "MCP endpoint URL. URL semantics are defined by the Agent Plugins specification."
+        },
+        "headers": {
+          "$ref": "#/$defs/headers"
+        }
+      },
+      "required": ["type", "url"],
+      "additionalProperties": false
+    },
+    "headers": {
+      "title": "HTTP headers",
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    }
+  }
+}

package/templates/plugin/schemas/plugin.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "title": "Agent Plugins Manifest",
+  "description": "Machine-readable schema for plugin.json in Agent Plugins 1.0.0. The Agent Plugins specification defines additional semantic and operational requirements.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "const": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+      "description": "Canonical identifier of the plugin manifest schema for the Agent Plugins version targeted by this document."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^(?!.*(?:--|\\.\\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$",
+      "description": "Human-readable plugin name."
+    },
+    "version": {
+      "type": "string"
+    },
+    "description": {
+      "type": "string"
+    },
+    "author": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "email": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "homepage": {
+      "type": "string"
+    },
+    "repository": {
+      "type": "string"
+    },
+    "license": {
+      "type": "string"
+    },
+    "keywords": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "extensions": {
+      "type": "object",
+      "description": "Client-specific manifest data keyed by reverse-domain extension namespace. Agent Plugins assigns no semantics to namespace object contents.",
+      "additionalProperties": {
+        "type": "object"
+      }
+    }
+  },
+  "required": ["$schema", "name"],
+  "additionalProperties": false
+}

package/templates/plugin/task-delivery.SKILL.md

@@ -0,0 +1,60 @@
+---
+name: task-delivery
+description: Prepare scoped coding tasks through APort and follow their saved progress, evidence and pull requests.
+---
+
+Read task_capabilities for the connected account. Choose an available configured
+harness and authorized repository. Installation supplies no repository authority,
+credentials or inference allowance. Provider costs and unsupported controls are
+described by capabilities; do not silently select another provider.
+Use only tools advertised by the connected host. A server accepting an older
+alias directly does not mean the host can route that alias.
+
+Use task_prepare with the selected repository ID, task text, harness and approved
+allowance. Use a stable operationId and expectedRevision 0. Preparation can incur
+inference costs but does not authorize implementation. Ask the saved questions,
+then call task_answer with their IDs, a new operationId and the saved revision.
+Preserve explicit requirements and any readiness denial. Inspect stale revisions.
+
+Read the repository's completion capabilities and select the creation-only
+completion.target: delivery_ready for a qualified reviewable delivery, or
+integrated when the user wants monitoring through an external merge. An omitted
+target defaults to delivery_ready. This field owns the PR/review/merge lifecycle;
+do not duplicate coordinator publication as a provider implementation criterion.
+Organize the user's implementation requirements clearly yourself; do not require
+the user to format a special prompt. Preserve every constraint and prohibition,
+show the separated delivery goal with the prepared brief, and ask a focused
+clarification if mixed prose cannot be separated without changing meaning.
+Never rewrite an existing false attestation or drop an inconvenient requirement.
+The core preserves exact source ownership for supported publication clauses.
+If TASK_DELIVERY_SCOPE is returned, ask the owner to clarify the whole request;
+preserve prerequisites and prohibitions, and use a new preparation identity after
+clarification. Do not treat that refusal as permission to remove a condition or
+silently move a changed publication instruction into an implementation answer.
+
+After the user authorizes implementation, call task_start with run true, a stable
+operationId and the current revision. Return the task handle promptly. Subsequent
+task_inspect, task_logs and task_evidence calls read saved observations. They do
+not poll providers. Use task_validate to record readiness before authorizing a
+start. Use task_resume to recover saved preparation or an already approved
+implementation after its blocker is repaired; do not allocate a replacement.
+
+The APort host exposes implementation controls as separate tools: task_recheck
+checks an existing implementation, task_continue resumes it, task_message adds
+instructions, task_interrupt requests supported interruption with instructions,
+and task_cancel requests cancellation. Use only a control advertised by the host
+and supported by the saved task. Pass the saved taskId, expectedRevision and a
+stable operationId; task_message and task_interrupt also require a non-empty
+note. Each tool fixes its own action, so do not pass action or interrupt fields.
+Preserve the same operationId and arguments on retries. Cancellation may stop
+future dispatch while remote compute continues. Never claim remote cancellation
+from a stopped submission client.
+
+Keep task identity across reconnects and review corrections. Report observed
+tests, artifacts and the pull request. Use completion.status and its canonical
+evidence to describe fulfillment; awaiting_integration means the existing
+coordinator keeps watching without authorizing a merge. A closed, unmerged PR
+does not fulfill the target. Surface needs-human or unverified observations;
+never merge, publish, request credentials or infer completion from provider status.
+The UI receives the full saved view through tool metadata; do not mirror raw logs,
+briefs or private diagnostics into model context. Use authorized artifact IDs.

package/templates/prd.md

@@ -0,0 +1,32 @@
+---
+status: draft
+harness: claude
+---
+
+# Short imperative title
+
+## Problem
+
+What is wrong today, for whom, and what changes when this ships. At least forty words. Name the user, the moment it hurts, and how you will know it is fixed. Link the issue or conversation that raised it if there is one.
+
+## User stories
+
+- As a <who>, I want <what>, so that <why>.
+- As a <who>, I want <what>, so that <why>.
+
+## Acceptance criteria
+
+- Given <a starting state>, when <an action>, then <an observable result>.
+- Given <a starting state>, when <an action>, then <an observable result>.
+
+## Verify
+
+- `npm test`
+
+## Where to look
+
+- `src/` (or: none)
+
+## Out of scope
+
+- What this PRD will not do, so the session does not do it either.