agents-handoff 0.0.0-stage → 2.0.2

package/schemas/handoff.schema.json

@@ -0,0 +1,275 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Agent-Handoff",
+  "description": "Portable execution state for agent-handoff — canonical handoff schema v1.0",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "handoff_id",
+    "mission_id",
+    "task_id",
+    "created_at",
+    "updated_at",
+    "source",
+    "state",
+    "next_action"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^1\\.0$",
+      "description": "Schema version for compatibility checking"
+    },
+    "handoff_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unique handoff identifier"
+    },
+    "mission_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Mission this handoff belongs to"
+    },
+    "task_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Task this handoff is for"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 creation timestamp"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 last update timestamp"
+    },
+    "source": {
+      "type": "object",
+      "required": ["agent", "runtime", "version"],
+      "properties": {
+        "agent": { "type": "string" },
+        "runtime": { "type": "string" },
+        "version": { "type": "string" }
+      },
+      "description": "Source agent/runtime that created this handoff"
+    },
+    "target": {
+      "type": "object",
+      "properties": {
+        "agent": { "type": "string" },
+        "runtime": { "type": "string" },
+        "version": { "type": "string" }
+      },
+      "description": "Target agent/runtime for resume"
+    },
+    "input_contract": {
+      "type": "object",
+      "description": "Input contract for the session that produced this handoff"
+    },
+    "state": {
+      "type": "object",
+      "required": ["status", "current_action"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["PENDING", "ACTIVE", "COMPLETED", "SATISFIED", "NOT_APPLICABLE", "BLOCKED", "FAILED", "IN_PROGRESS"]
+        },
+        "current_action": { "type": "string" },
+        "completed_work": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "pending_work": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "blockers": {
+          "type": "array",
+          "items": { "type": "object" }
+        },
+        "unknowns": {
+          "type": "array",
+          "items": { "type": "object" }
+        },
+        "assumptions": {
+          "type": "array",
+          "items": { "type": "object" }
+        }
+      }
+    },
+    "execution": {
+      "type": "object",
+      "properties": {
+        "last_operation": { "type": "string" },
+        "result": { "type": "string" },
+        "exit_code": { "type": ["integer", "null"] },
+        "changed_files": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "properties": {
+        "required": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/capability" }
+        },
+        "selected": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/capability" }
+        },
+        "unavailable": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/capability" }
+        }
+      }
+    },
+    "permissions": {
+      "type": "object",
+      "properties": {
+        "current": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "approvals": {
+          "type": "array",
+          "items": { "type": "object" }
+        }
+      }
+    },
+    "checkpoint": {
+      "type": "object",
+      "required": ["checkpoint_id", "state_hash", "created_at"],
+      "properties": {
+        "checkpoint_id": { "type": "string" },
+        "predecessor_checkpoint": { "type": "string" },
+        "state_summary": { "type": "string" },
+        "state_hash": { "type": "string" },
+        "created_at": { "type": "string", "format": "date-time" },
+        "completed_work": { "type": "array", "items": { "type": "string" } },
+        "verified_work": { "type": "array", "items": { "type": "string" } },
+        "pending_work": { "type": "array", "items": { "type": "string" } },
+        "artifact_manifest": { "type": "array", "items": { "type": "object" } },
+        "environment_fingerprint": { "type": "string" },
+        "capability_requirements": { "type": "array", "items": { "type": "string" } },
+        "permission_state": { "type": "array", "items": { "type": "string" } },
+        "verification_results": { "type": "array", "items": { "type": "object" } },
+        "next_action": { "type": "string" },
+        "recovery_notes": { "type": "string" }
+      }
+    },
+    "artifacts": {
+      "type": "object",
+      "properties": {
+        "manifest": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["path", "purpose"],
+            "properties": {
+              "path": { "type": "string" },
+              "purpose": { "type": "string" },
+              "canonical": { "type": "boolean" },
+              "generated": { "type": "boolean" },
+              "source_of_truth": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "properties": {
+        "verified": {
+          "type": "array",
+          "items": { "type": "object" }
+        },
+        "observed": {
+          "type": "array",
+          "items": { "type": "object" }
+        },
+        "unresolved": {
+          "type": "array",
+          "items": { "type": "object" }
+        }
+      }
+    },
+    "decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["decision", "reason"],
+        "properties": {
+          "decision": { "type": "string" },
+          "reason": { "type": "string" },
+          "timestamp": { "type": "string" }
+        }
+      }
+    },
+    "errors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["error", "timestamp"],
+        "properties": {
+          "error": { "type": "string" },
+          "timestamp": { "type": "string" },
+          "resolved": { "type": "boolean" }
+        }
+      }
+    },
+    "next_action": {
+      "type": "object",
+      "required": ["objective"],
+      "properties": {
+        "objective": { "type": "string" },
+        "reason": { "type": "string" },
+        "preconditions": { "type": "array", "items": { "type": "string" } },
+        "required_capabilities": { "type": "array", "items": { "type": "string" } },
+        "required_permissions": { "type": "array", "items": { "type": "string" } },
+        "verification": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  },
+  "definitions": {
+    "capability": {
+      "type": "object",
+      "required": ["id", "name", "type", "provider"],
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "type": { "type": "string" },
+        "provider": { "type": "string" },
+        "purpose": { "type": "string" },
+        "inputs": { "type": "array", "items": { "type": "string" } },
+        "outputs": { "type": "array", "items": { "type": "string" } },
+        "prerequisites": { "type": "array", "items": { "type": "string" } },
+        "dependencies": { "type": "array", "items": { "type": "string" } },
+        "supports": { "type": "array", "items": { "type": "string" } },
+        "does_not_support": { "type": "array", "items": { "type": "string" } },
+        "side_effects": { "type": "array", "items": { "type": "string" } },
+        "risk_class": { "type": "string", "enum": ["R0", "R1", "R2", "R3", "R4"] },
+        "permission_level": { "type": "string" },
+        "scope": { "type": "array", "items": { "type": "string" } },
+        "targets": { "type": "array", "items": { "type": "string" } },
+        "reversibility": { "type": "string" },
+        "availability": { "type": "string", "enum": ["available", "unavailable", "degraded"] },
+        "health": { "type": "string", "enum": ["healthy", "unhealthy", "unknown"] },
+        "version": { "type": "string" },
+        "platform": { "type": "array", "items": { "type": "string" } },
+        "architecture": { "type": "array", "items": { "type": "string" } },
+        "cost": { "type": "string" },
+        "latency": { "type": "string" },
+        "failure_modes": { "type": "array", "items": { "type": "string" } },
+        "verification_method": { "type": "string" },
+        "provenance": { "type": "string" },
+        "trust": { "type": "string", "enum": ["BUILT_IN", "PROJECT", "LOCAL", "USER_AUTHORIZED_EXTERNAL", "EXTERNAL", "UNTRUSTED"] }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/skill.json

@@ -0,0 +1,147 @@
+{
+  "name": "agent-handoff",
+  "version": "2.0.2",
+  "description": "Write, verify, and hand off complete AI working sessions across any harness (Claude Code, Codex, DeepSeek Harness, plain JSONL or text logs). Cross-harness session capture + verified continuation.",
+  "domain": "orchestration",
+  "installer": {
+    "type": "npx",
+    "package": "agents-handoff",
+    "packageVersion": "2.0.2",
+    "repository": "https://github.com/Alot1z/agent-handoff",
+    "installCommand": "npx agents-handoff"
+  },
+  "locations": {
+    "source": "skills/agent-handoff/",
+    "global": {
+      "windows": "<store>/<account-id>/<profile-id>/agent-handoff/  (resolved, see docs/INSTALL.md)",
+      "posix": "~/.config/<client>/account-skills/<account-id>/<profile-id>/agent-handoff/  (resolved)"
+    },
+    "local": "./local/skills/agent-handoff/",
+    "project": "./skills/agent-handoff/"
+  },
+  "dependencies": {
+    "node": ">=18.0.0",
+    "external": []
+  },
+  "commands": {
+    "build": "node tools/handoff.mjs build --source <input> [--session id] [--harness name] [--model name] [--project name] [--objective text]",
+    "build-alias": "node tools/handoff.mjs --handoff --source <input>",
+    "list": "node tools/handoff.mjs list [project-or-prefix]",
+    "show": "node tools/handoff.mjs show <id-prefix>",
+    "verify": "node tools/handoff.mjs verify <id-prefix>",
+    "rename": "node tools/handoff.mjs rename <id-prefix> <new-project>",
+    "retitle": "node tools/handoff.mjs retitle <id-prefix> <new-name>"
+  },
+  "l4": {
+    "runtime": "node tools/agent-handoff.mjs <verb> [args]",
+    "verbs": [
+      "auto",
+      "verify-gate",
+      "promote",
+      "merge",
+      "self-improve",
+      "index",
+      "dispatch"
+    ]
+  },
+  "handoff": {
+    "default_dir": "handoffs/",
+    "config_file": "handoff.config.json",
+    "environment": {
+      "HANDOFFS_ROOT": "Override default handoffs location"
+    },
+    "max_brief_tokens": 30000,
+    "schema_version": "2.0.0"
+  },
+  "update": {
+    "check_url": "https://github.com/Alot1z/agent-handoff/releases/latest",
+    "auto_check": true,
+    "installer": "npx agents-handoff --update"
+  },
+  "secrets": {
+    "required": false,
+    "warning": "Never commit secrets. Use environment variables or local secrets file.",
+    "envVars": []
+  },
+  "files": {
+    "source": [
+      "SKILL.md",
+      "README.md",
+      "tools/handoff.mjs",
+      "tools/agent-handoff.mjs",
+      "tools/handoff.test.mjs",
+      "tools/capability-registry.mjs",
+      "tools/runtime-engine.mjs",
+      "tools/lib/handoff-root.mjs",
+      "schemas/handoff.schema.json",
+      "templates/*.md",
+      "templates/*.json",
+      "refs/*.md",
+      "install/",
+      "tests/"
+    ],
+    "published": [
+      "SKILL.md",
+      "README.md",
+      "LICENSE",
+      "package.json",
+      "skill.json",
+      "capability-registry.json",
+      "permission-policy.json",
+      "handoff.config.schema.json",
+      "handoff.config.example.json",
+      "tools/handoff.mjs",
+      "tools/agent-handoff.mjs",
+      "tools/handoff.test.mjs",
+      "tools/capability-registry.mjs",
+      "tools/runtime-engine.mjs",
+      "tools/lib/handoff-root.mjs",
+      "schemas/handoff.schema.json",
+      "templates/HANDOFF.template.md",
+      "templates/HANDOFF.llm.schema.json",
+      "tests/acceptance/acceptance.yaml",
+      "tests/fixtures/minimal-transcript.jsonl",
+      "refs/ADAPTERS.md",
+      "refs/handbook.md",
+      "refs/protocol.md",
+      "refs/roles.md",
+      "refs/validator.md",
+      "refs/brief-checklist.md",
+      "refs/bootstrap.md",
+      "docs/index.md",
+      "docs/INSTALL.md",
+      "docs/UPGRADE.md",
+      "docs/UNINSTALL.md",
+      "docs/INTEGRATION.md",
+      "docs/LEVEL4.md",
+      "docs/LEVEL5.md",
+      "docs/FORMAT.md",
+      "docs/PERMISSIONS.md",
+      "docs/SECURITY.md",
+      "docs/COMPATIBILITY.md",
+      "docs/PROVENANCE.md",
+      "docs/CONTRIBUTING.md",
+      "install/install.mjs",
+      "install/README.md",
+      "install/package.json",
+      "CHANGELOG.md",
+      "docs/ARCHITECTURE.md",
+      "docs/CLI.md",
+      "docs/TROUBLESHOOTING.md",
+      "docs/CHANGELOG.md",
+      "install/CHANGELOG.md"
+    ],
+    "local_only": [
+      "local/",
+      "projects/",
+      "links/",
+      "tasks/",
+      "private research corpus and internal design notes",
+      "docs/ARCHITECTURE-UPDATES.md",
+      ".env",
+      "*.key",
+      "*.pem",
+      "secrets/"
+    ]
+  }
+}

package/templates/HANDOFF.llm.schema.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "AgentSessionHandoff v1",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "session",
+    "generated_at",
+    "counts",
+    "timeline",
+    "provenance"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string", "description": "2.0.0 or 2.0.0-summary"
+    },
+    "session": {
+      "type": "object",
+      "required": [
+        "id",
+        "harness"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "harness": {
+          "type": "string"
+        },
+        "model": {
+          "type": "string"
+        },
+        "thread": {
+          "type": "string"
+        }
+      }
+    },
+    "generated_at": {
+      "type": "string"
+    },
+    "objective": {
+      "type": "string"
+    },
+    "state_now": {
+      "type": "string"
+    },
+    "open_loops": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "evidence_class": {
+      "enum": [
+        "OBSERVED",
+        "VERIFIED",
+        "DERIVED"
+      ]
+    },
+    "counts": {
+      "type": "object",
+      "properties": {
+        "USER": {
+          "type": "integer"
+        },
+        "AGENT": {
+          "type": "integer"
+        },
+        "THOUGHT": {
+          "type": "integer"
+        },
+        "TOOL": {
+          "type": "integer"
+        }
+      }
+    },
+    "timeline": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "seq",
+          "class",
+          "text"
+        ],
+        "properties": {
+          "seq": {
+            "type": "integer"
+          },
+          "ts": {
+            "type": [
+              "string",
+              "integer"
+            ]
+          },
+          "class": {
+            "enum": [
+              "USER",
+              "AGENT",
+              "THOUGHT",
+              "TOOL",
+              "OTHER"
+            ],
+            "description": "OTHER = kept for raw fidelity (system/meta turns), omitted from human render tables"
+          },
+          "text": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "tool_calls": {
+      "type": "array"
+    },
+    "provenance": {
+      "type": "object",
+      "required": [
+        "sources",
+        "raw_sha256",
+        "total_turns"
+      ],
+      "properties": {
+        "sources": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "raw_sha256": {
+          "type": "string"
+        },
+        "manifest_sha256": {
+          "type": "string"
+        },
+        "watermark": {
+          "type": "integer"
+        },
+        "total_turns": {
+          "type": "integer"
+        }
+      }
+    }
+  }
+}

package/templates/HANDOFF.template.md

@@ -0,0 +1,40 @@
+# Handoff: <SESSION-ID>
+
+**Harness:** <claude-code|codex|dsh|ci|generic>  |  **Model:** <name>
+**Updated:** <ISO>  |  **Turns:** N  |  **Watermark:** seq <= N  |  **Revision:** R
+
+## Objective (verbatim head)
+
+```
+<first USER (else AGENT) turn, <=400 chars, never paraphrased>
+```
+
+## State right now (verbatim tail)
+
+```
+<last AGENT (else USER) turn tail, <=1200 chars>
+```
+
+## Open loops / next steps
+- <lines matching next step|todo|blocked|open loop|remaining>
+
+## Timeline (recent turns)
+
+| seq | class | text (head 140) |
+|---:|---|---|
+| 0 | USER | ... |
+
+<!-- classes: USER · AGENT · THOUGHT (reasoning) · TOOL (tool_use/result) · OTHER (raw-fidelity meta, omitted from render) -->
+
+## Tool calls (full)
+- [seq] ts: excerpt <=500 chars
+
+## Provenance
+- sources: <original store paths>
+- raw sha256: <hash of exact ingested bytes>
+- manifest sha256: <self-hash of manifest minus this field>
+- incremental: revisions=N (update-not-recreate; watermark skips emitted turns)
+
+!! Laws: RAW IS NEVER ALTERED — handoffs RENDER from canonical/vault data · objectives verbatim ·
+re-run = merge not duplicate (watermark) · every artifact carries sha256 provenance · works on ANY
+harness that emits JSONL or plain text (refs/ADAPTERS.md).