[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-92698":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":15,"stars30d":14,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":16,"rankGlobal":10,"rankLanguage":10,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":18,"hasPages":18,"topics":20,"createdAt":10,"pushedAt":10,"updatedAt":35,"readmeContent":36,"aiSummary":37,"trendingCount":15,"starSnapshotCount":15,"syncStatus":38,"lastSyncTime":39,"discoverSource":40},92698,"halo-record","bkuan001\u002Fhalo-record","bkuan001","Tamper-evident runtime records for AI agents. Hash-chained, dependency-free, verifiable by anyone.","https:\u002F\u002Fpypi.org\u002Fproject\u002Fhalo-record\u002F",null,"Python",53,6,1,0,42.64,"Apache License 2.0",false,"main",[21,22,23,24,25,26,27,28,29,30,31,32,33,34],"agents","ai-agents","ai-governance","ai-security","attestation","audit-log","audit-trail","compliance","llm","mcp","opentelemetry","python","security","tamper-evident","2026-07-22 04:02:06","# halo-record\n\nTamper-evident **runtime records for AI agents**: the audit trail the vendor runs but cannot edit.\n\nEvery action your agent takes (tool calls, model calls, data access, approvals) becomes one record in an append-only, hash-chained log. Any party can verify the log was never altered, without trusting whoever produced it. When a customer's security team asks \"what did your agent do with our data?\", you hand them a link instead of a paragraph. Security reviews already ask AI questions next to the SOC 2 checklist, and today a written assurance still passes. The bet behind this project is that it won't for long.\n\nThe record format is open and free to implement. This package is the reference implementation: recorder, verifier, witness client, and report server.\n\n## Why you can trust this code\n\nYou are being asked to put a recorder inside your agent. You should not take that on faith:\n\n- **Zero runtime dependencies.** Standard library only. `pip install halo-record` installs exactly one package.\n- **No network calls**, except the witness, which is opt-in and receives only a record count and a chain fingerprint. Record contents never leave your infrastructure.\n- **Raw inputs never enter a record.** Arguments are hashed and stored only as a redacted summary — never the raw value. Redaction is best-effort (regex over common secret and PII formats): treat it as defense-in-depth, not a guarantee.\n- **Small enough to audit.** ~4,300 lines of Python. Read all of it in an afternoon.\n- **Apache-2.0.**\n\n## 60-second demo\n\nNo agent required. With [uv](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002F), nothing to install:\n\n```\nuvx --from halo-record halo demo --serve\n```\n\nor the classic way:\n\n```\npip install halo-record\nhalo demo --serve\n```\n\nEither one scaffolds a fictional support-agent vendor with two customers, witnesses the chains, serves their gated Runtime Reports, and opens the operator console in your browser. Then try the tamper test: delete a line from one of the `.jsonl` files and reload. The report catches it.\n\n## Record your own agent\n\nOne line at the boundary:\n\n```python\nfrom halo import trace\n\nagent = trace(run_my_agent, profile=\"my-agent\", log=\"audit.jsonl\")   # wraps your entrypoint; records every tool call to .\u002Faudit.jsonl\n```\n\nWithout `log=`, records go to `~\u002F.halo\u002Fmy-agent.jsonl` (one chain per agent). Or use the adapter for what you already run (see the matrix below). Then render the report:\n\n```\nhalo report audit.jsonl -o report.html    # one chain -> self-verifying HTML\nhalo serve .\u002Frecords --port 8721          # all tenants, gated per customer\n```\n\nThe quickstart ends when you are looking at your own agent's Runtime Report in a browser. If you got a JSONL file and no report, something is wrong: open an issue.\n\n## Connect to what you already run\n\n| Captured at the boundary | Ingested from existing telemetry |\n|---|---|\n| Native recorder (`from halo import trace`) | OpenTelemetry GenAI spans |\n| MCP interceptor | LiteLLM callbacks |\n| LangChain \u002F LangGraph callback | Langfuse export |\n| OpenAI Agents SDK hooks | Any gateway \u002F reverse-proxy log |\n| Claude Code \u002F Claude Agent SDK hook | |\n\nEvery record carries a `source` tag, so the report discloses how each piece of evidence was collected. Captured and ingested records live in the same chain.\n\nAnything that emits OpenTelemetry GenAI spans (CrewAI, LlamaIndex, and most agent frameworks with OTel instrumentation) lands in the chain through the OTel adapter, and the [TypeScript package](https:\u002F\u002Fgithub.com\u002Fbkuan001\u002Fhalo-record-ts) ships native adapters for the Vercel AI SDK and the JS agent ecosystem. Missing an adapter for your stack? Open an issue. Most adapters are about a hundred lines.\n\n## Record your coding agent\n\nClaude Code fires a `PostToolUse` hook after every tool call. Point it at `halo hook` and each action — file writes, shell commands, MCP connector calls — becomes a record in a local chain. No code changes; one settings entry:\n\n```json\n{\n  \"hooks\": {\n    \"PostToolUse\": [\n      {\"matcher\": \"*\", \"hooks\": [{\"type\": \"command\", \"command\": \"halo hook\"}]}\n    ]\n  }\n}\n```\n\nAdd that to `~\u002F.claude\u002Fsettings.json` and records land in `~\u002F.halo\u002Faudit.jsonl` (override with `$HALO_LOG`). Pure-orchestration tools that touch no data, network, or external state are skipped — the chain records trust-boundary actions, not thinking. Set `HALO_HASH_ONLY=1` to record content hashes without summaries. Set `HALO_AGENT_VERSION` (and optionally `HALO_AGENT_MODEL`) to bind every record to the agent build that produced it — when an auditor asks about the version that was running in a given window, the export answers by column instead of by recollection.\n\nIf you need the report to answer \"under what rules did this run happen?\", set `HALO_AUTHORITY_FILE` to a JSON snapshot of the effective authority for the session. Keep it privacy-safe: hashes and refs, not raw prompts, private policy text, secrets, or full tool schemas.\n\n```json\n{\n  \"snapshot_id\": \"auth_2026_07_08T1100Z\",\n  \"captured_at\": \"2026-07-08T11:00:00Z\",\n  \"scope\": \"session\",\n  \"workspace\": {\"path_hash\": \"sha256:...\", \"git_commit\": \"abc1234\"},\n  \"refs\": [\n    {\"kind\": \"project_rules\", \"id\": \"CLAUDE.md\", \"hash\": \"sha256:...\", \"loaded\": true, \"truncated\": false},\n    {\"kind\": \"mcp_tool_registry\", \"id\": \"filesystem\", \"hash\": \"sha256:...\"}\n  ],\n  \"omissions\": [{\"kind\": \"private_policy\", \"reason\": \"customer_secret\", \"hash\": \"sha256:...\"}],\n  \"stale_if\": [\"project_rules_hash_changed\", \"mcp_tool_registry_hash_changed\"]\n}\n```\n\n```sh\nHALO_AUTHORITY_FILE=.\u002Fauthority.json halo hook\n```\n\nThe snapshot is sealed into the same hash chain as the action records. A good default is one session-level snapshot at start, plus a new snapshot when rules, Skills, hooks, MCP tool registries, or compaction policy change. To keep long sessions lean, consecutive records with the same `authority.snapshot_id` are compacted after the first full snapshot: later records keep only `{\"snapshot_id\": \"...\", \"same_as_previous\": true}`. The pointer stays hash-chained, but the bulky refs\u002Fomissions\u002Fstale-if block is not repeated on every action. Then, the usual:\n\n```\nhalo verify ~\u002F.halo\u002Faudit.jsonl\nhalo report ~\u002F.halo\u002Faudit.jsonl -o report.html\n```\n\nAny agent runtime that exposes a post-action hook can feed the same command — the hook reads one event as JSON on stdin and appends one record.\n\n## Integrity vs. completeness (read this part)\n\nA self-held chain proves **integrity**: nothing was edited or reordered after the fact. It cannot prove **completeness**: the operator of a recorder can delete the bad day and re-seal the chain, or never write a record at all, and the chain stays internally consistent.\n\nCompleteness requires a party outside the operator's control holding periodic fingerprints of the chain (a count and a head hash, nothing else). That is the witness:\n\n```\nhalo anchor audit.jsonl witness.jsonl           # anchor a checkpoint to a local witness\nhalo anchor audit.jsonl witness.jsonl --check   # completeness verdict against it\n```\n\nAnyone can run a witness. A witness you run yourself proves integrity to *you*; proving completeness to *your customer* requires a witness they have reason to trust. The protocol is open either way.\n\nA hosted, recognized witness is how this project will sustain itself. Early access: bkuan001@gmail.com.\n\n## Where this sits in a compliance stack\n\nhalo-record is an evidence layer, not a certification. It produces the artifact that assessment frameworks keep asking for in different words:\n\n- **Security questionnaires and SOC 2 reviews:** answer the AI sections with a verifiable Runtime Report instead of screenshots and prose.\n- **AIUC-1:** continuous runtime evidence for agent-behavior requirements, instead of evidence reconstructed at audit time.\n- **OWASP (GenAI Security Project):** the runtime evidence behind the agent-behavior risks in the OWASP Top 10 for LLM Applications and the Agentic Security Initiative — excessive agency, tool misuse, sensitive-information disclosure — recorded as what the agent actually did, with which tools and data.\n- **AARM (CSA):** produces the tamper-evident action receipt AARM specifies (R5\u002FR6) — chained and independently witnessed. halo-record is the receipt layer; pair it with an enforcement gateway for a full AARM system. See [`AARM.md`](AARM.md).\n- **Agentic Trust Controls:** the runtime records behind the ATC's evidence controls — tamper-evident action logging (RBM-03) and authority attestation (AID-05) in one chained record, with the witness layer beyond both. See [`ATC.md`](ATC.md).\n- **EU AI Act:** logging and record-keeping obligations for high-risk AI systems.\n- **ISO 42001 \u002F NIST AI RMF:** the operational evidence behind management-system controls.\n\nNone of this certifies anything by itself. It gives your assessor something verifiable to look at.\n\n## CLI\n\n```\nhalo verify   validate schema + hash chain (non-zero exit on failure; CI-friendly)\nhalo report   render a chain as a self-verifying HTML Runtime Report\nhalo serve    serve per-tenant reports over HTTP, access-scoped per customer\nhalo grant    designate a report recipient (email or domain)\nhalo anchor   witness a chain head, or --check completeness\nhalo demo     scaffold the full vendor demo (record -> witness -> gated report)\nhalo export   date-bounded evidence export: CSV + manifest tied to the chain head\nhalo sample   emit a valid example log\nhalo hash     canonical sha256 of a JSON value\nhalo hook     Claude Code PostToolUse hook\n```\n\n## Integrity model\n\nTo compute a record's hash: take the record excluding `integrity.hash`, with `integrity.prev_hash` set to the previous record's hash; canonicalize with RFC 8785 (JSON Canonicalization Scheme); SHA-256 the bytes. The first record's `prev_hash` is 64 zeros. Verification recomputes every hash and checks every link. No secret required; that is the point.\n\nThink you can tamper with a chain without the verifier noticing? [Attempts and results live here](https:\u002F\u002Fgithub.com\u002Fbkuan001\u002Fhalo-record\u002Fdiscussions\u002F2).\n\nFull field reference: [`halo-record.schema.json`](src\u002Fhalo_record\u002Fhalo-record.schema.json).\n\n## TypeScript\n\nThe same recorder ships for Node: [`halo-record-ts`](https:\u002F\u002Fgithub.com\u002Fbkuan001\u002Fhalo-record-ts). Same chain format, same witness protocol. Records written in either language verify with either verifier.\n\n## Contributing\n\nIssues, discussions, and pull requests welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the ground rules (short version: tests required, small PRs, schema changes get discussed first).\n\n## License\n\nApache-2.0\n","halo-record 是一个为 AI 代理（AI agents）提供抗篡改运行时审计日志的轻量级 Python 库。它通过哈希链（hash-chained）机制构建仅追加、无依赖的审计记录，支持任何人离线验证日志完整性与顺序性，无需信任日志生成方。核心特性包括零运行时依赖、无网络外发（见证服务可选）、输入参数自动哈希脱敏、纯标准库实现及约 4300 行可审计代码。适用于需要向客户或合规团队（如 SOC 2、AI 治理审查）提供可信行为证明的 AI 服务提供商、LLM 应用平台及企业级智能体部署场景。",2,"2026-07-10 02:30:10","CREATED_QUERY"]