@openlatch/client 0.1.14 → 0.1.18

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/OpenLatch/openlatch-client/main/assets/banner.jpg" alt="OpenLatch — Security infrastructure for AI agents" width="600" />
+  <img src="https://raw.githubusercontent.com/OpenLatch/openlatch-client/main/assets/banner.jpg" alt="OpenLatch — runtime enforcement node for the AI Operations Platform" width="600" />
 </p>
 
 <h3 align="center">See what your agent does. Block what it shouldn't.</h3>
@@ -15,13 +15,13 @@
 
 ---
 
-**OpenLatch** is a thin, open-source security forwarder that plugs into AI agents via their **native lifecycle hooks**. One command installs protection across all your agents — no proxies, no code changes, no configuration.
+**OpenLatch** is the open-source **runtime enforcement node** for the [OpenLatch AI Operations Platform](https://openlatch.ai). It plugs into AI agents via their **native lifecycle hooks** — capturing every action inside the agent's own lifecycle and positioned to enforce policy deterministically before an action executes. One command installs it across all your agents — no code changes, no configuration.
 
 ```bash
 npx @openlatch/client init
 ```
 
-That's it. `init` auto-detects your installed agents, writes the hook configs, and starts the daemon that forwards events to the cloud for real-time security analysis.
+That's it. `init` auto-detects your installed agents, writes the hook configs, and starts the daemon that captures agent activity and forwards it to the OpenLatch control plane.
 
 <!-- TODO: Replace with VHS terminal recording once available -->
 <!-- <p align="center">
@@ -35,28 +35,36 @@ AI agents execute shell commands, read files, call APIs, and install tools — a
 OpenLatch gives you:
 
 - **Visibility** — audit logs of every tool call, shell command, and file access across all your agents
-- **Protection** — real-time detection of tool poisoning, credential leakage, prompt injection, and dangerous shell commands
-- **Zero friction** — deploys from inside your agent in one command, auto-detects platforms, requires no security expertise
+- **Control** — actions run through the agent's own lifecycle, the point where OpenLatch is positioned to enforce policy deterministically before they execute
+- **Zero friction** — deploys from inside your agent in one command, auto-detects platforms, no code changes
 
-## Supported Platforms
+## Supported Agents
 
-OpenLatch works across **3 operating systems** and **8 agent platforms** from day one.
+OpenLatch attaches in three flavors, one per class of agent:
 
-| Agent Platform | macOS | Windows | Linux | Hook Events |
-| -------------- | :---: | :-----: | :---: | ----------: |
-| Claude Code | :white_check_mark: | :white_check_mark: | :white_check_mark: | 24 |
-| Cursor | :white_check_mark: | :white_check_mark: | :white_check_mark: | 5 |
-| Windsurf | :white_check_mark: | :white_check_mark: | :white_check_mark: | 5 |
-| GitHub Copilot | :white_check_mark: | :white_check_mark: | :white_check_mark: | 6 |
-| Codex CLI | :white_check_mark: | :white_check_mark: | :white_check_mark: | 4 |
-| Gemini CLI | :white_check_mark: | :white_check_mark: | :white_check_mark: | 4 |
-| Cline | :white_check_mark: | :white_check_mark: | :white_check_mark: | 4 |
-| OpenClaw | :white_check_mark: | :white_check_mark: | :white_check_mark: | 4 |
+| Flavor | Agents | How it attaches | Status |
+| ------ | ------ | --------------- | ------ |
+| Coding agents | Claude Code | Native lifecycle hooks | **Shipping** |
+| Coding agents | Cursor, Windsurf, GitHub Copilot, Codex CLI, Gemini CLI, Cline, OpenClaw | Native lifecycle hooks | Planned |
+| Cloud agent platforms | Azure AI Foundry, AWS Bedrock | SDK + tool/MCP gate | Planned |
+| Agentic Python frameworks | LangChain / LangGraph-class | Framework middleware | Planned |
 
-## Threat Coverage
+Claude Code is the only integration that attaches today, across **macOS, Windows, and Linux**. It is the reference implementation the remaining coding agents will follow.
 
-| Threat Category | What it catches |
-| --------------- | --------------- |
+| Coding Agent | macOS | Windows | Linux | Hook Events |
+| ------------ | :---: | :-----: | :---: | ----------: |
+| Claude Code | :white_check_mark: | :white_check_mark: | :white_check_mark: | 12 |
+
+Nine runtime lifecycle events — `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`, `SessionStart`, `SessionEnd` — plus three configuration-plane events, `ConfigChange`, `InstructionsLoaded` and `FileChanged`, which the daemon dedupes against its own filesystem watcher.
+
+The other coding agents are recognized as envelope `agent_type` values, so events forwarded on their behalf are stored and attributed correctly — but `openlatch init` cannot yet install their hooks, and `openlatch doctor` reports them as `not_supported_in_v1`. Adding one means a new `AgentBinding` in `src/hooks/bindings/` plus a verdict translator in `src/hook_output/`; without the translator a `deny` is discarded before the developer sees it.
+
+## Behavioral Coverage
+
+OpenLatch captures the agent behaviors that matter — the raw signal the platform's modules act on:
+
+| Category | Behaviors captured |
+| -------- | ------------------ |
 | **Tool Poisoning** | Malicious MCP servers, tampered tool definitions, supply chain attacks on agent tooling |
 | **PII & Credential Leakage** | API keys, tokens, passwords, and personal data leaving your machine via agent actions |
 | **Prompt Injection** | Injected instructions hidden in files, tool outputs, or web content that hijack agent behavior |
@@ -89,6 +97,11 @@ Pre-built binaries for macOS (ARM, Intel), Linux (x86_64, ARM), and Windows are
 # Auto-detect agents, install hooks, and start the daemon
 openlatch init
 
+# Point the client at a self-hosted platform (persisted to config.toml).
+# Use the console origin, not the API port: it proxies /api/v1 AND serves
+# the /cli-auth page that browser login opens.
+openlatch init --api-url http://127.0.0.1:5183
+
 # Check daemon status, uptime, and event counts
 openlatch status
 
@@ -138,6 +151,7 @@ openlatch docs
 | `openlatch doctor --rescue [--since 24h] [--output PATH] [--yes]` | Bundle a redacted diagnostic ZIP for sharing with support. Privacy filter runs on every text file; tokens are hard-redacted. |
 | `openlatch uninstall [--purge] [--yes]` | Remove hooks and stop daemon. `--purge` deletes all data |
 | `openlatch supervision {install,uninstall,enable,disable,status}` | Manage the OS-native supervisor that keeps the daemon alive after reboot (launchd / systemd --user / Task Scheduler). Installed by default during `openlatch init`; opt out with `openlatch init --no-persistence`. |
+| `openlatch inventory {list,log,rescan,status,inspect,projects,ack}` | Inspect configuration monitoring: list observed config sources (MCP servers, skills, commands, hooks, rules), tail `ai.openlatch.config.*` events from the audit log, force a rescan, report monitor health, drill down on a single source (`inspect`), enumerate observed project roots (`projects`), and acknowledge pending alerts (`ack`). |
 | `openlatch docs` | Open documentation in browser |
 
 Noun-verb aliases are also available: `openlatch hooks install` = `init`, `openlatch hooks uninstall` = `uninstall`, `openlatch daemon start` = `start`, etc.
@@ -188,35 +202,66 @@ OpenLatch ships two binaries:
 
 ## How It Works
 
-OpenLatch uses a **three-layer architecture** — hooks live inside your agents, the client forwards events, and the cloud runs detection:
+OpenLatch uses a **three-layer architecture** — hooks live inside your agent, the client decides locally and forwards events, and the cloud authors the rules and runs analysis:
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
 │  Your Machine                                                   │
 │                                                                 │
 │  ┌──────────┐  hook event   ┌──────────────────────────────┐    │
-│  │  Claude   │─────────────▶│                              │    │
-│  │  Code     │              │   OpenLatch Client           │    │
-│  ├──────────┤              │   (localhost:7443)            │    │
-│  │  Cursor   │─────────────▶│                              │    │
-│  ├──────────┤              │   1. Wrap in envelope         │    │
-│  │  Copilot  │─────────────▶│   2. Redact credentials      │    │
-│  ├──────────┤              │   3. Forward to cloud         │────┼──▶  OpenLatch Cloud
-│  │  Gemini   │─────────────▶│   4. Return verdict          │◀───┼──   (allow / deny)
-│  │  CLI      │              │   5. Write local audit log   │    │
-│  ├──────────┤              │                              │    │
-│  │  ...      │─────────────▶│                              │    │
-│  └──────────┘  ◀─ verdict ─ └──────────────────────────────┘    │
-│                                                                 │
+│  │  Claude   │─────────────▶│   OpenLatch Client           │    │
+│  │  Code     │              │   (localhost:7443)           │    │
+│  │          │              │                              │    │
+│  │          │              │   1. Wrap in envelope        │    │
+│  │          │              │   2. Evaluate resident       │    │
+│  │          │              │      policy in-process       │    │
+│  │          │  ◀─ verdict ─│   3. Redact credentials      │    │
+│  └──────────┘  (allow/deny) │   4. Write local audit log  │    │
+│                             │   5. Batch → forward        │────┼──▶  OpenLatch Cloud
+│                             │      ◀── policy bundle      │◀───┼──   (rules + analysis)
+│                             └──────────────────────────────┘    │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
 **Key design decisions:**
 
-- **Hook-native** — OpenLatch plugs into each agent's official hook/extension system. It runs inside the agent runtime, not as a network proxy. Events cannot be bypassed.
-- **Thin client, smart cloud** — the client wraps events in a standard envelope and forwards them. All detection, normalization, and analysis happens cloud-side.
+- **Hook-native** — OpenLatch plugs into the agent's official hook/extension system. The enforcement path runs inside the agent runtime, never as a network proxy; events cannot be bypassed. (Model-call economics capture additionally uses a loopback listener on `127.0.0.1` — on by default, see `[boundary]`.)
+- **Local-authoritative verdicts** — the daemon evaluates a resident policy bundle in-process, so the verdict path never touches the network. The cloud authors and serves the rules; it does not decide. Correlation, cross-host analysis, and scanning stay cloud-side. Policy evaluation ships **on** (secure-by-default); `[policy] enabled = false` opts out — a complete off switch, not observe mode.
 - **Privacy-first** — credentials and secrets are redacted locally via regex-based filtering before anything leaves your machine.
-- **Fail-open** — if the cloud is unreachable, agents continue working normally. Events are logged locally and synced later.
+- **Fail-static, not fail-open** — a resident bundle keeps enforcing offline forever, and a failed refresh keeps the last-known-good bundle. Genuine fail-open is limited to two cases: no bundle was ever fetched, and the hook binary being unable to reach the daemon. Event forwarding is separately durable — events spool to `outbox.jsonl` and sync later.
+
+## Updating openlatch
+
+`openlatch` auto-updates itself silently in the background. By default the running daemon polls the npm registry every six hours, downloads + verifies + applies new releases during quiet moments (no agent activity for sixty seconds AND no hook in flight), and re-execs into the new binary. The `min_supported_client` and `cargo install` gates from the manual path apply equally to the worker.
+
+```bash
+# Disable the worker (env or config):
+export OPENLATCH_AUTO_UPDATE=false
+# or, persistently:
+echo -e "[update]\nauto_update = false" >> ~/.openlatch/config.toml
+```
+
+If the supervisor restarts the daemon at least three times within sixty seconds after a fresh update (sentinel + `.bak` siblings both present), the next start auto-rolls-back from the `.bak` files — running before logging is initialised, with output through stderr only. CI environments and `cargo install`-installed binaries are auto-detected and skip the worker entirely.
+
+`openlatch update` is the manual escape hatch and works whether or not the worker is enabled:
+
+```bash
+# Probe the registry; never modifies anything.
+openlatch update --check --json
+
+# Apply the update if one is available.
+openlatch update --apply --yes
+```
+
+When a daemon is running, the CLI routes the apply through the daemon's authenticated `POST /admin/update` RPC; the daemon downloads the tarball, verifies the SHA-512 integrity hash and minisign signatures against the trusted key baked into the binary, performs an atomic swap, drains in-flight HTTP traffic, and re-execs into the new binary. With no daemon running, the CLI performs the same swap in-process.
+
+The pipeline refuses to apply when:
+
+- The binary was installed via `cargo install` (run `cargo install --force --locked openlatch-client` instead — exit 5, OL-1505).
+- The new release's `min_supported_client` is greater than the running version (run `npm install -g @openlatch/client@latest` to resync).
+- A signature does not verify against the trusted key bundled into the running binary (exit 1, OL-1504).
+
+The supported install paths are `npm install -g @openlatch/client` and `npx @openlatch/client …`. Direct curl-installs work but disable the npm-vs-actual drift detection in `openlatch status`. Releases marked `Severity: critical` (in the release commit footer) bypass the activity-aware deferral and apply on the next poll regardless of in-flight hook traffic.
 
 ## Configuration
 
@@ -226,9 +271,8 @@ OpenLatch works with zero configuration. For advanced use cases:
 # Configuration precedence (highest to lowest):
 # 1. CLI flags
 # 2. Environment variables (OPENLATCH_*)
-# 3. Project config (.openlatch.json)
-# 4. User config (~/.openlatch/config.toml)
-# 5. Defaults
+# 3. User config (~/.openlatch/config.toml)
+# 4. Defaults
 ```
 
 | Environment Variable | Description | Default |
@@ -236,18 +280,54 @@ OpenLatch works with zero configuration. For advanced use cases:
 | `OPENLATCH_API_KEY` | Your OpenLatch API key | — |
 | `OPENLATCH_API_URL` | Cloud API base URL. Callers append `/api/v1/...` path segments. | `https://app.openlatch.ai` |
 | `OPENLATCH_APP_URL` | Web app URL used for browser auth. Falls back to `OPENLATCH_API_URL` (with a trailing `/api` stripped, for back-compat with overrides). | `https://app.openlatch.ai` |
-| `OPENLATCH_LOG_LEVEL` | Logging verbosity | `info` |
-| `OPENLATCH_FAIL_MODE` | Behavior when cloud is unreachable | `open` |
+| `OPENLATCH_LOG` | Logging verbosity (`error` / `warn` / `info` / `debug` / `trace`) | `info` |
+| `OPENLATCH_DIR` | State directory — config, logs, outbox, daemon port/token. Override to run a second isolated instance. | `~/.openlatch` |
+| `OPENLATCH_PORT` | Local daemon port. `init` binds this exact port and fails with OL-1500 if it is taken; unset, it probes 7443-7543 for the first free one. | `7443` |
+| `OPENLATCH_SKIP_KEYRING` | Treat the OS keychain as unavailable, so `OPENLATCH_API_KEY` is used instead. The credential chain is keychain → env var → encrypted file, so a stale keychain entry otherwise wins over the env var. | unset |
+| `OPENLATCH_CLOUD_ENABLED` | Set to `false` to stop forwarding events to the cloud | `true` |
+| `OPENLATCH_CLOUD_BATCH_MAX_EVENTS` | Events per ingest batch. Clamped to `1..=100`; `1` restores one POST per event. | `50` |
+| `OPENLATCH_CLOUD_BATCH_MAX_WAIT_MS` | Flush deadline, anchored to the first buffered event | `5000` |
+| `OPENLATCH_POLICY_ENABLED` | Local policy evaluation. Set to `false` to opt out — a complete off switch, not observe mode. | `true` |
+| `OPENLATCH_BOUNDARY_ENABLED` | Model-boundary listener (the loopback proxy that captures model-call economics + attribution). Set to `false` to stop binding the pinned loopback port. While enabled, the daemon points the agent at the listener via `ANTHROPIC_BASE_URL` — but only once a synthetic request has proven the listener can actually reach the provider, and it removes the pointer again if that stops being true. Being wired disables Claude Code Remote Control. | `true` |
+| `OPENLATCH_BOUNDARY_UPSTREAM` | Where the boundary forwards. Every model call and every provider credential on this host goes here, so change it only for a local harness or a deliberate gateway. | `https://api.anthropic.com` |
+| `OPENLATCH_INVENTORY_ENABLED` | Configuration-plane monitoring (MCP servers, skills, rules, hooks) | `true` |
+| `OPENLATCH_TELEMETRY_DISABLED` | Set to `1` to opt out of anonymous usage telemetry | unset |
+| `OPENLATCH_NPM_REGISTRY` | npm registry origin used by `openlatch update` (override for testing) | `https://registry.npmjs.org` |
+| `OPENLATCH_UPDATE_CHECK` | Set to `false` to disable the daemon's startup version check | `true` |
+| `OPENLATCH_AUTO_UPDATE` | Set to `false` to disable the background auto-update worker | `true` |
+| `OPENLATCH_UPDATE_CHECK_INTERVAL_SECS` | Worker poll cadence (E2E override; production keeps the default) | `21600` (6h) |
+| `OPENLATCH_UPDATE_QUIET_WINDOW_SECS` | Seconds of hook silence required before a non-critical apply | `60` |
+| `OPENLATCH_UPDATE_MAX_DEFER_SECS` | Hard cap on cumulative deferral before applying anyway | `86400` (24h) |
+| `OPENLATCH_CLOUD_OUTBOX_MAX_BYTES` | Cap on `~/.openlatch/outbox.jsonl` size before drop-oldest eviction (0 disables) | `104857600` (100 MB) |
+| `OPENLATCH_CLOUD_FALLBACK_MAX_BYTES` | Cap on `~/.openlatch/logs/fallback.jsonl` size before drop-oldest via offset advance (0 disables) | `52428800` (50 MB) |
 
 ## Security
 
-OpenLatch is a security product — we hold ourselves to a high standard:
+OpenLatch is the on-host runtime enforcement node of the AI Operations Platform — and we hold our own code to the same standard the platform is built to enforce for your agents:
 
 - **Responsible disclosure** — report vulnerabilities to **security@openlatch.ai**
 - **Private vulnerability reporting** enabled on this repository
 - All releases are built with **SLSA provenance** via GitHub Actions
 - See [SECURITY.md](SECURITY.md) for our full security policy
 
+## Releases
+
+This repository publishes two artifacts on **independent version lines**:
+
+| Artifact | Tag | Where |
+| -------- | --- | ----- |
+| The client itself | `v1.2.3` | GitHub Releases, [`openlatch`](https://www.npmjs.com/package/openlatch) (npm), [`openlatch-client`](https://crates.io/crates/openlatch-client) (crates.io) |
+| The wire-format JSON Schemas | `schemas-v1.2.3` | [`@openlatch/client-schemas`](https://www.npmjs.com/package/@openlatch/client-schemas) (npm), [`openlatch-client-schemas`](https://pypi.org/project/openlatch-client-schemas/) (PyPI) |
+
+The schema packages are versioned **only** by changes under `schemas/`, so a
+major bump means a breaking change to the events exchanged between the client
+and the platform — and nothing else. Pin them independently of the client
+version; they carry no dependency on it.
+
+Both lines are cut by [release-please](https://github.com/googleapis/release-please)
+from Conventional Commits. Contributor-facing details are in
+[AGENT.md](AGENT.md#releasing--two-independent-version-lines).
+
 ## Contributing
 
 We welcome contributions! Whether it's bug fixes, new agent integrations, or documentation improvements.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openlatch/client",
-  "version": "0.1.14",
-  "description": "OpenLatch — the open-source security layer for AI agents",
+  "version": "0.1.18",
+  "description": "OpenLatch runtime enforcement node — the capture-and-enforce client for the AI Operations Platform",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -20,10 +20,10 @@
     "postinstall": "node lib/postinstall.js"
   },
   "optionalDependencies": {
-    "@openlatch/client-darwin-arm64": "0.1.14",
-    "@openlatch/client-darwin-x64": "0.1.14",
-    "@openlatch/client-linux-x64": "0.1.14",
-    "@openlatch/client-linux-arm64": "0.1.14",
-    "@openlatch/client-win32-x64": "0.1.14"
+    "@openlatch/client-darwin-arm64": "0.1.18",
+    "@openlatch/client-darwin-x64": "0.1.18",
+    "@openlatch/client-linux-x64": "0.1.18",
+    "@openlatch/client-linux-arm64": "0.1.18",
+    "@openlatch/client-win32-x64": "0.1.18"
   }
 }