v1.2.0

Merge pull request #230 from Cygnux-Labs/agent/issue-227

Release 1.2.0: one viewer like Causeway, the why and control, faster signer, what's stable

Tracekit 1.0.0

Install: pip install tracekit-ai — then add import tracekit; tracekit.instrument() to your agent and run tracekit last. Container image: ghcr.io/cygnux-labs/tracekit-signer:v1.0.0 (@sha256:d9cbad7dc635959d9812ec7a7507c5d306199285d29a29aa2f7839ee583c8e95).

Verify this release: the wheel and sdist below are the files PyPI serves (SHA256SUMS); each carries SLSA build provenance from this repository's release workflow (gh attestation verify tracekit_ai-1.0.0-py3-none-any.whl --repo Cygnux-Labs/Tracekit), the image is cosign-signed (keyless), and the CycloneDX SBOMs of the package and the image are attached. The npm packages (@cygnux/tracekit) are not published for 1.0.0 yet; use the TypeScript SDK from this repository until they are. Known limits and trade-offs: docs/limits.md.

1.0.0 is 1.0.0rc2 made stable: the v2 signer, evidence format v2 and its verifier, witnesses, the monitor, team approvals,
server deployments (container, Kubernetes sidecar, central signer on Postgres) and the run viewer. The v2 format is now
stable: 1.x verifiers verify every 1.0 bundle, and a bundle that needs a newer verifier says so (UNVERIFIABLE), never
FAILED. The v1 laptop setup and v1 bundles keep working unchanged. Upgrade notes from 0.4.0: see 1.0.0rc1 below.

Added

• One install, one line, a verified run. pip install tracekit-ai now installs everything the dev signer needs
  (tracekit-ai[signer] still works); pip install --no-deps tracekit-ai is the verifier alone, on the standard
  library. import tracekit; tracekit.instrument() wires the frameworks it finds (OpenAI Agents SDK, LangGraph /
  LangChain, Claude Agent SDK, MCP, and the OpenAI, Anthropic and Google Gen AI SDKs), starting a dev signer if none
  is running. tracekit last exports the newest finished run, pins the dev signer's key and verifies it. The README
  and each framework quickstart are those three steps. What this path doesn't cover:
  docs/limits.md.
• docs/limits.md: every known limit and trade-off on one page.

Changed

• tracekit.instrument(tracer) (v1 model-call tracing) is now tracekit.autotrace.instrument(tracer);
  tracekit.instrument() raises a TypeError naming it when given a tracer.

Fixed

• A network service that refused a request before reading its body (wrong Host, missing session or CSRF token) could
  reset the connection before the client read the answer, on Windows always and elsewhere while a large body was
  still arriving. Each service now reads what the client sent, up to 1 MiB, before closing.
• A config file written as JSON (signer.yaml, the viewer's and the gateway's) failed to load where PyYAML isn't
  installed, which tracekit-ai[signer] doesn't install. JSON documents now load either way.

Release

• npm: no @cygnux/tracekit-signer-darwin-x64 package (google-re2 and cryptography publish no Intel-Mac wheels it can
  use). On an Intel Mac, pip install 'tracekit-ai[signer]'; @cygnux/tracekit uses that tracekit from PATH.
• Releases are built and published by the attested release workflow: PyPI files, npm packages and the signer image
  carry SLSA build provenance and SBOMs, the image is cosign-signed, and SHA256SUMS is attached to the GitHub release
  (docs/RELEASING.md).
• SECURITY.md: 1.x is the supported line.

Tracekit 1.0.0rc2 — the run viewer

Install: pip install --pre "tracekit-ai[signer]==1.0.0rc2" (a release candidate: a plain pip install tracekit-ai still gets 0.4.0). The files below are the ones PyPI serves; SHA256SUMS lists their hashes.

The second 1.0 release candidate. Nothing changes in the signer, the evidence formats, the verifier or the policy
packs: rc1's bundles, configs and clients work unchanged (signer RPC version 12).

Viewer (tracekit view)

• Runs panel: each v2 run with its agent's registered name, its verifier verdict (VERIFIED, FAILED, PENDING),
  start, duration, and its calls, blocked, held and gaps. Selecting a run scopes the tape, timeline, tool mix and header
  to it; the header shows the selected run's own verdict, or how many runs failed.
• Run review: integrity and assurance, what the policy allowed, flagged, denied and held, who approved (attested or
  bridged, and whether it was self-approved), gaps by kind and coverage; each line opens its first record.
• Replay: step through a run, or jump to the next deny, hold or gap, with the header and tape as of that moment.
• In words: blocked calls show their rules' reasons; holds and approvals are their own HOLD, APPROVE and
  REJECT rows; the signer's own records no longer count as an agent; tape filters for decisions, approvals, and gaps
  and alerts; the timeline is scaled to the calls shown.

Docs

• docs/viewer.md: a screenshot of a run under review; the README quickstart ends with tracekit view --dev.

Tracekit 1.0.0rc1 — server deployments and teams

Install: pip install --pre "tracekit-ai[signer]==1.0.0rc1" (a release candidate: a plain pip install tracekit-ai still gets 0.4.0). The files below are the ones PyPI serves; SHA256SUMS lists their hashes.

The first 1.0 release candidate: the v2 signer becomes the way to run Tracekit, on a laptop, in a container, as a
Kubernetes sidecar or as a central service on Postgres, with witnesses, a monitor and team approvals. The v1 laptop
setup and v1 bundles keep working unchanged. docs/launch-checklist.md lists what the 1.0
release still waits on; 1.0 itself is the owner's call after real use.

Upgrade notes

• Signer RPC version 12 (0.4.0 spoke 7). Clients and signers of different versions refuse each other; upgrade the
  signer and its clients together. A dev signer of the old version is reported, never restarted behind your back.
• v2 bundles now need tracekit >= 1.0.0 to verify (verifier_min_version): they can carry anchors, hybrid
  checkpoint signatures, certified record keys and other records 0.4.0's verifier doesn't know. An older verifier
  reports them UNVERIFIABLE, never as failed. 0.4.0 bundles still verify. v1 bundles and the v1 verifier are unchanged.
• TypeScript: @cygnux/tracekit's default import is now the native v2 client; the v1 API is at
  @cygnux/tracekit/v1, and the Python bridge it used is deprecated.
• Server deployments run the server policy pack. The image, the compose stack and both Helm charts now set
  policy: (before, they fell back to the laptop pack). Replace /etc/tracekit/policy.yaml to run your own.
• Run-sets need their registry notes cosigned: with witnesses_required set, a run-set exported before the
  witnesses cosigned its registry note verifies INCOMPLETE; the run-set line now names its tenant.
• Policy packs: rules now match what a call acts on (target) rather than everything it carries, so writing a file
  that merely mentions a credentials path is no longer denied; TK-S005 is folded into TK-S004; new rules
  TK-N003, TK-B003 and TK-SQL-PARSE. Policy files are always read by the built-in YAML subset (duplicate keys and
  anchors are errors even where PyYAML is installed). A command or SQL statement the parser can't read is held (ask).
• Clients: one run's events are sent one at a time (other runs still in parallel); a v2 hook that can't start now
  blocks the call in dev mode too.

Fixes from the pre-1.0 review

A five-part review of the signer, storage and verifier, network services, clients and policy before this release; each
fix has a regression test.

• Approvals: self-approval is detected across every identity mapped to the same person, including OIDC person ids;
  a consumed approval covers only the arguments it approved; a passkey-required approval is refused without a verified
  assertion on every path; a blank break-glass reason is refused; a bridge acts for people of its own tenant only
  (unless it is a multi-tenant app); passkeys are registered only soon after a sign-in.
• Signer: nothing is signed with a record key whose certificate has expired; runs are refused in tenants the key
  isn't certified for; closing a log ends its open runs first; finished runs leave the writer's working set; retry
  caches are bounded per identity and keep no executor arguments; OTLP import adds spans only to the importer's own runs.
• Verifier and storage: run-set completeness requires the registry notes' witness quorum and that every bundled run
  is of the run-set's tenant; a power loss can no longer leave the file store unable to start; Postgres calls time out
  instead of hanging; registry notes are read on demand; fsck checks the trees against the logs; exporting an active
  run works; the monitor and export write durably.
• Network services: the signer's HTTPS listener, the viewer, metrics and the Slack bridge bound their connections
  and enforce request deadlines; a pending viewer login can't be evicted; valid credentials work behind an address
  that others failed from; loopback receivers answer only loopback host names; witness proofs no longer rehash the log.
• Clients: an answer can't reach the wrong caller; a stalled signer fails every waiting call within its timeout;
  installers refuse agent settings of an unexpected shape rather than rewriting them; hook approval waits fit the
  harness's hook timeout.
• Policy: SQL rules match outside comments and every literal form; hosts are normalised (numeric, mapped and
  encoded forms) before matching; command names built from expansions, more wrappers, interpreter programs in every
  form, option-borne commands and bundled force-push flags are covered; paths match whatever the separator or case.
• Deploy: the agent's mount of the signer socket is read-only; every chart container has resource requests and
  limits; image and npm bundle dependencies are pinned, and the npm bundles are built from the release's checked wheel.

Deploy anywhere

• Container image of the signer (non-root uid 10001, digest-pinned base) and a Docker Compose stack: signer,
  Postgres, a shipped witness and the viewer.
• Postgres storage (one writer per log, advisory lock, a SELECT-only reader role for export, view and reveal) next
  to the file store, whose snapshots are now HMAC-authenticated.
• Helm charts: tracekit-signer (a sidecar the agent's container can't read) and tracekit-central (one writer
  per log, run ids routed by prefix, a viewer of every log).
• Keys: the log key can live in AWS KMS (Ed25519) or GCP; an issuer service certifies short-lived record keys,
  witnessed before it returns them; checkpoints can carry a second, post-quantum signature (SLH-DSA, FIPS 205).
• Anchoring and monitoring: checkpoints anchored in Rekor v2 with RFC 3161 timestamps; tracekit monitor follows a
  log, checks its rules and publishes signed reports, so bundles can verify at witnessed+monitored.
• tracekit doctor checks v2 deployments, including Kubernetes; laptop system mode runs the v2 signer as its
  own user, with harness binding through a root-owned helper.
• Remote clients reach the signer over HTTPS with Kubernetes service-account, mTLS, bearer-token or OIDC
  identities; v1 remote ingest is replaced.
• LLM gateway (OpenAI-compatible) that records model calls through the signer, optionally mandatory.

Capture and evidence

• Reconciliation of three capture layers (transcripts, hooks, SDK) in the signer, with signed coverage gaps; a
  hardened Claude Code transcript tailer; v2 hooks for Codex, Cursor and Gemini CLI.
• Verifier: the complete v2 report, a golden corpus and a negative corpus, run-set completeness, retired-key use
  failing, revocations reported as unverifiable.
• OpenTelemetry in (OTLP into the signer) and out (spans from v2 records).

Policy and approvals

• Server policy packs: SQL, HTTP egress, cloud CLIs and MCP tools, payments, email and chat, plus cloud metadata,
  secrets and credential files on every tool. On the shipped corpora they catch every deny case and hold 0.16% of
  benign calls. extends takes a list of packs.
• Team approvals: OIDC sign-in for approvers and the viewer; a run's end-user principal can be attested from their
  token and never approves its own run; web approval pages, with passkeys (WebAuthn) required for high-risk rules;
  Slack approvals; break-glass answers need a reason and are recorded.
• External decisions from AWS AgentCore Policy, Amazon Verified Permissions, VS Code agent hooks and GitHub Copilot
  hooks are imported as signed inputs, and a disagreement with the signer becomes a signed gap.
• OCSF webhook: decisions, denies, approvals, gaps and tamper records sent HMAC-signed to a SIEM, without agent
  content.

Viewer

• Multi-tenant viewer over every log of a central deployment: auditor (one tenant), approver and operator-admin
  roles, search and pagination, each run checked by the verifier (labelled as the operator's view) and downloadable as a
  bundle to re-verify.

SDKs and integrations

• Native TypeScript client of the signer RPC, with adapters for the OpenAI Agents SDK, the Vercel AI SDK and the
  Claude Agent SDK, and npx @cygnux/tracekit up for Node-only users.
• Runnable v2 examples and quickstarts per framework; tracekit demo --server; a Browser Use adapter.

Release and docs

• Release engineering for signed artifacts with provenance, SBOMs and multi-arch images (the target workflow is in
  docs/RELEASING.md).
• Deployment, migration, architecture, security-checklist, FAQ and limits docs; a rewritten README; the technical
  report (report/tracekit-v2.md) with the E-series results.

Tracekit 0.3.0

First release published on PyPI, as tracekit-ai (pip install tracekit-ai; the import and the command stay
tracekit). The name tracekit on PyPI belongs to an unrelated project: do not install it.

Breaking changes

• Niche modules moved to contrib/ as separate packages: proof packs (tracekit-proofpack, also tracekit-report),
  SQL over the ledger (tracekit-sql), Causeway, on-chain guards and Stagehand. The old tracekit proofpack, report,
  sql and causeway subcommands print where they went. Entries below that mention them describe the contrib
  packages.
• Proof packs no longer contain a verifier (verify.pyz and SHA256SUMS are gone): auditors verify with a
  Tracekit release they install themselves. A bundled replay.html never affects a verdict.
• The ingest gateway, the Anthropic model proxy and the OTLP receiver need --experimental; they are being rebuilt
  for server-hosted agents.
• GitHub Action: require-anchor defaults to true, so an unanchored bundle fails the step.
• System mode runs only from a root-owned virtualenv at /opt/tracekit, installed from PyPI (tracekit-ai, the
  same version) or from a root-owned clone, with a root-owned Python. tracekit migrate --system refuses installs that
  predate it: re-run sudo /usr/bin/python3 -m tracekit init --user <agent-user>.
• tracekit cost reads the ledger directly; --index was removed.
• tracekit verify output: besides Integrity: and Assurance:, --json now carries integrity, assurance
  and notes. Assurance is separate-user only where the signer itself attested it.

Security and correctness

• Signer: stamps signer_isolation on run.start itself; records an approval before it takes effect; validates
  approval requests (types, sizes, caller owns a started run, bounded wait_s, per-user cap); decides approvals only
  from facts it observes (peer uid, the approving process's terminal); runs first seen without run.start get an owner.
• Hooks and client: an untrusted or unreadable /etc/tracekit/client.json fails closed instead of falling back;
  subagent transcript paths are confined to the session; payloads without ids are not merged and leave a signed gap;
  a signer-rejected tool call blocks under fail_mode: closed, also when an approval was given; client state files use
  collision-free names (existing state carries over); Codex, Cursor and Gemini sessions keep their run.start when
  reasoning_capture is on.
• Redaction: linear time on adversarial input; long connection-string passwords are redacted; a .env mention no
  longer hides the command being run; lone surrogates are recorded instead of breaking capture.
• Verifier: honest exports are no longer failed by a single missed witness publish (a warning instead); a malformed
  or deeply nested bundle is a FAIL, never a crash; the witness-coverage detail names only checkpoints the witness holds.
• Installer: every file write is safe against symlinks and races; reinstalling never leaves an empty runtime (the new
  virtualenv is swapped in only once it imports); the system-mode hook blocks if it cannot run; re-running init keeps
  the policy pin and registered harnesses and restarts the signer; tracekit doctor checks the whole runtime without
  following symlinks; the GitHub Action passes inputs to the shell only through the environment.
• Network servers (witness, ingest): TLS handshakes per connection with timeouts, an overall per-connection
  deadline, bounded threads and a per-client cap; the witness log is locked against a second server and rolls back a
  failed write; witness and Rekor URLs are validated and redirects refused; Rekor read-back includes the signature.
• Observer and replay: all event-derived content is escaped; nonce-based CSP; the observer's token becomes an
  HttpOnly cookie; static exports carry a CSP.
• SDKs: a crashing or slow TypeScript bridge never crashes or hangs the host process, and fail-open lets model calls
  through; bridge requests that time out leave no unfinished signed records; abandoned Python streams are recorded
  before run.end.
• Packaging: contrib packages depend on tracekit-ai; the sdist ships what its tests need.

Added

• tracekit observe polish and a reproducible interface video (docs/demo/observer_scene.py,
  record_observer.mjs).
• Golden verifier corpus (tests/golden/): frozen v0.1 and v1 evidence with the verifier's recorded verdicts.
• Known-gap tests (tests/test_known_gaps.py): strict expected failures for gaps the next evidence format closes.
• eval/e8_insider.py --require-harness, SECURITY.md, CONTRIBUTING (sign-off for contributions from forks).

Install: pip install tracekit-ai · Full history: CHANGELOG.md