@agent-watch-ai/edge 0.2.5 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +558 -0
- package/README.md +222 -97
- package/SECURITY.md +72 -0
- package/dist/billing/session-billing.d.ts +19 -0
- package/dist/billing/session-billing.js +52 -0
- package/dist/cli/args.d.ts +10 -0
- package/dist/cli/args.js +20 -0
- package/dist/cli/constants/cli.constants.d.ts +52 -4
- package/dist/cli/constants/cli.constants.js +56 -5
- package/dist/cli/context.d.ts +33 -2
- package/dist/cli/context.js +84 -14
- package/dist/cli/doctor.js +321 -33
- package/dist/cli/hook-check.d.ts +23 -0
- package/dist/cli/hook-check.js +114 -0
- package/dist/cli/hook.js +118 -7
- package/dist/cli/index.d.ts +3 -1
- package/dist/cli/index.js +3 -1
- package/dist/cli/misc.d.ts +11 -0
- package/dist/cli/misc.js +80 -4
- package/dist/cli/npx-install.d.ts +37 -0
- package/dist/cli/npx-install.js +79 -0
- package/dist/cli/open-browser.d.ts +39 -0
- package/dist/cli/open-browser.js +62 -0
- package/dist/cli/setup.d.ts +17 -8
- package/dist/cli/setup.js +553 -103
- package/dist/cli/status.js +82 -13
- package/dist/cli/toggle.d.ts +9 -0
- package/dist/cli/toggle.js +117 -0
- package/dist/cli/types/cli.types.d.ts +43 -3
- package/dist/cli/ui.d.ts +7 -0
- package/dist/cli/ui.js +10 -1
- package/dist/cli/uninstall.js +39 -2
- package/dist/cli/update.d.ts +17 -0
- package/dist/cli/update.js +76 -0
- package/dist/cli.js +110 -12
- package/dist/config/config-store.d.ts +57 -0
- package/dist/config/config-store.js +250 -12
- package/dist/config/config.d.ts +53 -6
- package/dist/config/config.js +66 -6
- package/dist/config/constants/config.constants.d.ts +116 -6
- package/dist/config/constants/config.constants.js +131 -8
- package/dist/config/destination.d.ts +24 -0
- package/dist/config/destination.js +33 -0
- package/dist/config/index.d.ts +7 -4
- package/dist/config/index.js +5 -3
- package/dist/config/repo-config.d.ts +11 -7
- package/dist/config/repo-config.js +64 -15
- package/dist/config/root-config.d.ts +72 -0
- package/dist/config/root-config.js +170 -0
- package/dist/config/schemas/config.schema.d.ts +831 -84
- package/dist/config/schemas/config.schema.js +398 -16
- package/dist/config/types/config.types.d.ts +15 -1
- package/dist/config/types/destination.types.d.ts +8 -0
- package/dist/core/async.d.ts +36 -0
- package/dist/core/async.js +68 -0
- package/dist/core/index.d.ts +1 -1
- package/dist/core/index.js +1 -1
- package/dist/core/object.d.ts +5 -0
- package/dist/core/object.js +9 -4
- package/dist/core/pipe.d.ts +0 -13
- package/dist/core/pipe.js +1 -9
- package/dist/core/types/core.types.d.ts +9 -0
- package/dist/core/types/core.types.js +0 -3
- package/dist/core/which.d.ts +14 -0
- package/dist/core/which.js +43 -3
- package/dist/credentials/budget.d.ts +9 -0
- package/dist/credentials/budget.js +16 -0
- package/dist/credentials/command-runner.d.ts +16 -0
- package/dist/credentials/command-runner.js +37 -0
- package/dist/credentials/constants/credentials.constants.d.ts +119 -0
- package/dist/credentials/constants/credentials.constants.js +120 -0
- package/dist/credentials/credential-status.d.ts +14 -0
- package/dist/credentials/credential-status.js +38 -0
- package/dist/credentials/credentials.d.ts +86 -0
- package/dist/credentials/credentials.js +278 -0
- package/dist/credentials/device-api.d.ts +73 -0
- package/dist/credentials/device-api.js +161 -0
- package/dist/credentials/device-state.d.ts +31 -0
- package/dist/credentials/device-state.js +51 -0
- package/dist/credentials/identity.d.ts +73 -0
- package/dist/credentials/identity.js +101 -0
- package/dist/credentials/index.d.ts +7 -0
- package/dist/credentials/index.js +5 -0
- package/dist/credentials/migration.d.ts +46 -0
- package/dist/credentials/migration.js +164 -0
- package/dist/credentials/schemas/device-api.schema.d.ts +77 -0
- package/dist/credentials/schemas/device-api.schema.js +33 -0
- package/dist/credentials/schemas/device-state.schema.d.ts +51 -0
- package/dist/credentials/schemas/device-state.schema.js +20 -0
- package/dist/credentials/secret-store.d.ts +54 -0
- package/dist/credentials/secret-store.js +217 -0
- package/dist/credentials/sign-in.d.ts +31 -0
- package/dist/credentials/sign-in.js +105 -0
- package/dist/credentials/token-refresher.d.ts +39 -0
- package/dist/credentials/token-refresher.js +185 -0
- package/dist/credentials/types/credentials.types.d.ts +206 -0
- package/dist/credentials/types/credentials.types.js +1 -0
- package/dist/enforcement/constants/enforcement.constants.d.ts +47 -1
- package/dist/enforcement/constants/enforcement.constants.js +56 -0
- package/dist/enforcement/decision-cache.d.ts +20 -1
- package/dist/enforcement/decision-cache.js +65 -2
- package/dist/enforcement/decision-client.d.ts +9 -8
- package/dist/enforcement/decision-client.js +64 -17
- package/dist/enforcement/enforcement.d.ts +23 -2
- package/dist/enforcement/enforcement.js +107 -17
- package/dist/enforcement/index.d.ts +4 -3
- package/dist/enforcement/index.js +3 -2
- package/dist/enforcement/types/enforcement.types.d.ts +66 -2
- package/dist/enrollment/constants/enrollment.constants.d.ts +2 -6
- package/dist/enrollment/constants/enrollment.constants.js +2 -6
- package/dist/enrollment/enrollment.d.ts +16 -0
- package/dist/enrollment/enrollment.js +54 -0
- package/dist/enrollment/index.d.ts +3 -7
- package/dist/enrollment/index.js +1 -1
- package/dist/enrollment/types/enrollment.types.d.ts +9 -13
- package/dist/events/constants/enrich.constants.d.ts +15 -0
- package/dist/events/constants/enrich.constants.js +15 -0
- package/dist/events/constants/events.constants.d.ts +6 -2
- package/dist/events/constants/events.constants.js +5 -1
- package/dist/events/enrich.js +92 -10
- package/dist/events/event-id.d.ts +0 -8
- package/dist/events/event-id.js +0 -10
- package/dist/events/index.d.ts +2 -2
- package/dist/events/index.js +1 -1
- package/dist/events/product-event.d.ts +9 -6
- package/dist/events/types/repo-snapshot.types.d.ts +7 -0
- package/dist/events/types/session-billing.types.d.ts +16 -0
- package/dist/events/types/session-billing.types.js +1 -0
- package/dist/feature/constants/feature.constants.d.ts +7 -0
- package/dist/feature/constants/feature.constants.js +7 -0
- package/dist/feature/index.d.ts +1 -1
- package/dist/feature/index.js +1 -1
- package/dist/feature/ticket-candidates.d.ts +14 -0
- package/dist/feature/ticket-candidates.js +26 -8
- package/dist/git/blob-hash.d.ts +21 -0
- package/dist/git/blob-hash.js +69 -0
- package/dist/git/checkout-root.d.ts +27 -0
- package/dist/git/checkout-root.js +75 -0
- package/dist/git/constants/git.constants.d.ts +160 -0
- package/dist/git/constants/git.constants.js +181 -0
- package/dist/git/fingerprint.d.ts +74 -0
- package/dist/git/fingerprint.js +219 -0
- package/dist/git/gate-checkout.d.ts +44 -0
- package/dist/git/gate-checkout.js +201 -0
- package/dist/git/git-context.d.ts +45 -0
- package/dist/git/git-context.js +61 -3
- package/dist/git/index.d.ts +4 -2
- package/dist/git/index.js +2 -1
- package/dist/git/manifest-repository.d.ts +13 -0
- package/dist/git/manifest-repository.js +92 -0
- package/dist/git/repo-snapshot.d.ts +29 -3
- package/dist/git/repo-snapshot.js +110 -7
- package/dist/git/repository-root.d.ts +39 -0
- package/dist/git/repository-root.js +131 -0
- package/dist/git/types/git.types.d.ts +55 -0
- package/dist/git/types/repository-root.types.d.ts +11 -0
- package/dist/git/types/repository-root.types.js +1 -0
- package/dist/git/types/snapshot.types.d.ts +9 -0
- package/dist/pipeline/constants/pipeline.constants.d.ts +10 -0
- package/dist/pipeline/constants/pipeline.constants.js +10 -0
- package/dist/pipeline/hook-pipeline.js +410 -33
- package/dist/pipeline/types/pipeline.types.d.ts +39 -4
- package/dist/privacy/constants/privacy.constants.js +15 -1
- package/dist/privacy/index.d.ts +1 -0
- package/dist/privacy/index.js +1 -0
- package/dist/privacy/product-capture.d.ts +12 -0
- package/dist/privacy/product-capture.js +75 -0
- package/dist/privacy/sanitizer.d.ts +21 -3
- package/dist/privacy/sanitizer.js +52 -8
- package/dist/process/ancestors.d.ts +39 -0
- package/dist/process/ancestors.js +121 -0
- package/dist/process/constants/process.constants.d.ts +34 -0
- package/dist/process/constants/process.constants.js +34 -0
- package/dist/process/index.d.ts +7 -0
- package/dist/process/index.js +2 -0
- package/dist/process/types/process.types.d.ts +23 -0
- package/dist/process/types/process.types.js +1 -0
- package/dist/providers/antigravity/antigravity.adapter.d.ts +12 -1
- package/dist/providers/antigravity/antigravity.adapter.js +21 -3
- package/dist/providers/antigravity/antigravity.detect.d.ts +0 -9
- package/dist/providers/antigravity/antigravity.detect.js +1 -1
- package/dist/providers/antigravity/antigravity.provider.js +3 -2
- package/dist/providers/antigravity/constants/antigravity.constants.d.ts +2 -0
- package/dist/providers/antigravity/constants/antigravity.constants.js +2 -0
- package/dist/providers/claude/claude.adapter.d.ts +11 -1
- package/dist/providers/claude/claude.adapter.js +26 -5
- package/dist/providers/claude/claude.otel.d.ts +32 -18
- package/dist/providers/claude/claude.otel.js +81 -6
- package/dist/providers/claude/claude.provider.js +5 -2
- package/dist/providers/claude/constants/claude.constants.d.ts +2 -0
- package/dist/providers/claude/constants/claude.constants.js +2 -0
- package/dist/providers/claude/constants/claude.otel.constants.d.ts +4 -0
- package/dist/providers/claude/constants/claude.otel.constants.js +8 -0
- package/dist/providers/codex/codex.adapter.d.ts +15 -1
- package/dist/providers/codex/codex.adapter.js +29 -5
- package/dist/providers/codex/codex.otel.d.ts +36 -3
- package/dist/providers/codex/codex.otel.js +199 -32
- package/dist/providers/codex/codex.provider.js +5 -2
- package/dist/providers/codex/constants/codex.constants.d.ts +2 -0
- package/dist/providers/codex/constants/codex.constants.js +16 -0
- package/dist/providers/codex/constants/codex.otel.constants.d.ts +10 -0
- package/dist/providers/codex/constants/codex.otel.constants.js +10 -0
- package/dist/providers/constants/provider.constants.d.ts +8 -3
- package/dist/providers/constants/provider.constants.js +8 -3
- package/dist/providers/cursor/constants/cursor.constants.d.ts +9 -0
- package/dist/providers/cursor/constants/cursor.constants.js +9 -0
- package/dist/providers/cursor/cursor.adapter.d.ts +33 -1
- package/dist/providers/cursor/cursor.adapter.js +129 -4
- package/dist/providers/cursor/cursor.detect.d.ts +0 -7
- package/dist/providers/cursor/cursor.detect.js +1 -1
- package/dist/providers/cursor/cursor.provider.js +5 -2
- package/dist/providers/gemini/constants/gemini.constants.d.ts +9 -0
- package/dist/providers/gemini/constants/gemini.constants.js +9 -0
- package/dist/providers/gemini/constants/gemini.otel.constants.d.ts +9 -1
- package/dist/providers/gemini/constants/gemini.otel.constants.js +9 -0
- package/dist/providers/gemini/gemini.adapter.d.ts +14 -1
- package/dist/providers/gemini/gemini.adapter.js +25 -5
- package/dist/providers/gemini/gemini.detect.d.ts +0 -7
- package/dist/providers/gemini/gemini.detect.js +1 -1
- package/dist/providers/gemini/gemini.otel.d.ts +30 -21
- package/dist/providers/gemini/gemini.otel.js +166 -22
- package/dist/providers/gemini/gemini.provider.js +2 -1
- package/dist/providers/index.d.ts +1 -1
- package/dist/providers/index.js +1 -1
- package/dist/providers/loaders.d.ts +10 -0
- package/dist/providers/loaders.js +40 -0
- package/dist/providers/provider.d.ts +11 -0
- package/dist/providers/provider.js +1 -1
- package/dist/providers/registry.d.ts +11 -8
- package/dist/providers/registry.js +11 -15
- package/dist/providers/shared/bearer-rewrite.d.ts +19 -0
- package/dist/providers/shared/bearer-rewrite.js +46 -0
- package/dist/providers/shared/constants/hook-refusal.constants.d.ts +7 -0
- package/dist/providers/shared/constants/hook-refusal.constants.js +7 -0
- package/dist/providers/shared/constants/shell-directories.constants.d.ts +30 -0
- package/dist/providers/shared/constants/shell-directories.constants.js +39 -0
- package/dist/providers/shared/constants/tooling.constants.d.ts +24 -2
- package/dist/providers/shared/constants/tooling.constants.js +25 -3
- package/dist/providers/shared/event-builder.d.ts +12 -14
- package/dist/providers/shared/event-builder.js +20 -14
- package/dist/providers/shared/exporter-allowlist.d.ts +20 -0
- package/dist/providers/shared/exporter-allowlist.js +49 -0
- package/dist/providers/shared/hook-config.d.ts +2 -21
- package/dist/providers/shared/hook-config.js +5 -4
- package/dist/providers/shared/hook-refusal.d.ts +12 -0
- package/dist/providers/shared/hook-refusal.js +17 -1
- package/dist/providers/shared/install-record.d.ts +12 -2
- package/dist/providers/shared/install-record.js +5 -2
- package/dist/providers/shared/shell-directories.d.ts +24 -0
- package/dist/providers/shared/shell-directories.js +90 -0
- package/dist/providers/shared/tooling.d.ts +40 -1
- package/dist/providers/shared/tooling.js +70 -1
- package/dist/providers/shared/types/adapter.types.d.ts +1 -2
- package/dist/providers/types/provider.types.d.ts +81 -1
- package/dist/snapshot/constants/snapshot.constants.d.ts +32 -0
- package/dist/snapshot/constants/snapshot.constants.js +33 -0
- package/dist/snapshot/snapshot-event.js +52 -11
- package/dist/snapshot/snapshot-pipeline.js +1 -1
- package/dist/snapshot/types/snapshot.types.d.ts +2 -0
- package/dist/storage/atomic-file.d.ts +21 -0
- package/dist/storage/atomic-file.js +20 -1
- package/dist/storage/constants/storage.constants.d.ts +19 -0
- package/dist/storage/constants/storage.constants.js +19 -0
- package/dist/storage/disabled.d.ts +13 -0
- package/dist/storage/disabled.js +24 -0
- package/dist/storage/index.d.ts +2 -0
- package/dist/storage/index.js +2 -0
- package/dist/storage/paths.js +3 -2
- package/dist/storage/schemas/storage.schema.d.ts +72 -0
- package/dist/storage/schemas/storage.schema.js +6 -0
- package/dist/storage/sweep-marker.d.ts +19 -0
- package/dist/storage/sweep-marker.js +55 -0
- package/dist/storage/types/storage.types.d.ts +2 -0
- package/dist/storage/uninstalled.d.ts +58 -0
- package/dist/storage/uninstalled.js +107 -0
- package/dist/transport/auth-block.d.ts +66 -0
- package/dist/transport/auth-block.js +129 -0
- package/dist/transport/constants/transport.constants.d.ts +82 -3
- package/dist/transport/constants/transport.constants.js +83 -4
- package/dist/transport/cooldown.js +8 -1
- package/dist/transport/delivery.d.ts +14 -6
- package/dist/transport/delivery.js +80 -55
- package/dist/transport/http-transport.d.ts +1 -0
- package/dist/transport/http-transport.js +52 -10
- package/dist/transport/index.d.ts +6 -3
- package/dist/transport/index.js +3 -0
- package/dist/transport/queue-partition.d.ts +91 -0
- package/dist/transport/queue-partition.js +143 -0
- package/dist/transport/queue.d.ts +99 -20
- package/dist/transport/queue.js +210 -69
- package/dist/transport/response-body.d.ts +25 -0
- package/dist/transport/response-body.js +64 -0
- package/dist/transport/send.d.ts +11 -0
- package/dist/transport/send.js +17 -0
- package/dist/transport/types/delivery-flow.types.d.ts +19 -0
- package/dist/transport/types/delivery-flow.types.js +1 -0
- package/dist/transport/types/transport.types.d.ts +45 -0
- package/dist/turns/claude-transcript.d.ts +19 -1
- package/dist/turns/claude-transcript.js +46 -1
- package/dist/turns/codex-originator.d.ts +11 -0
- package/dist/turns/codex-originator.js +31 -0
- package/dist/turns/codex-transcript.d.ts +30 -0
- package/dist/turns/codex-transcript.js +88 -0
- package/dist/turns/constants/turns.constants.d.ts +141 -5
- package/dist/turns/constants/turns.constants.js +155 -5
- package/dist/turns/file-identity.d.ts +27 -0
- package/dist/turns/file-identity.js +48 -0
- package/dist/turns/gemini-transcript.d.ts +30 -0
- package/dist/turns/gemini-transcript.js +96 -0
- package/dist/turns/index.d.ts +3 -3
- package/dist/turns/index.js +1 -1
- package/dist/turns/inherited-checkout.d.ts +54 -0
- package/dist/turns/inherited-checkout.js +155 -0
- package/dist/turns/native-session-titles.d.ts +26 -0
- package/dist/turns/native-session-titles.js +102 -0
- package/dist/turns/transcript.d.ts +3 -2
- package/dist/turns/transcript.js +5 -1
- package/dist/turns/turn-state.d.ts +224 -3
- package/dist/turns/turn-state.js +456 -21
- package/dist/turns/turn-summary.d.ts +1 -14
- package/dist/turns/turn-summary.js +87 -51
- package/dist/turns/turn-tracker.d.ts +21 -2
- package/dist/turns/turn-tracker.js +379 -56
- package/dist/turns/types/transcript.types.d.ts +5 -0
- package/dist/turns/types/turn-state.types.d.ts +116 -5
- package/dist/turns/types/turn-summary.types.d.ts +64 -14
- package/dist/turns/types/turn-tracker.types.d.ts +27 -1
- package/dist/turns/work-checkout.d.ts +67 -0
- package/dist/turns/work-checkout.js +700 -0
- package/dist/untraced/constants/untraced.constants.d.ts +31 -0
- package/dist/untraced/constants/untraced.constants.js +63 -0
- package/dist/untraced/untraced.d.ts +35 -0
- package/dist/untraced/untraced.js +105 -0
- package/dist/update/constants/update.constants.d.ts +18 -0
- package/dist/update/constants/update.constants.js +20 -0
- package/dist/update/update-check.d.ts +52 -0
- package/dist/update/update-check.js +113 -0
- package/docs/AUDIT_PROMPT.md +129 -0
- package/docs/DATA_HANDLING.md +655 -0
- package/docs/ENTERPRISE_DEPLOYMENT.md +194 -0
- package/docs/PERFORMANCE.md +81 -0
- package/package.json +14 -4
- package/dist/enrollment/enrollment-provider.d.ts +0 -5
- package/dist/enrollment/manual-enrollment.d.ts +0 -32
- package/dist/enrollment/manual-enrollment.js +0 -72
- package/example/README.md +0 -43
- package/example/server.mjs +0 -240
- /package/dist/{enrollment/enrollment-provider.js → config/types/destination.types.js} +0 -0
package/README.md
CHANGED
|
@@ -3,157 +3,282 @@
|
|
|
3
3
|
[](https://www.npmjs.com/package/@agent-watch-ai/edge)
|
|
4
4
|
[](LICENSE)
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
**See what your AI coding agents cost — per developer, repository and ticket.**
|
|
7
7
|
|
|
8
|
-
It
|
|
8
|
+
It reads the agents' own hooks and their native OpenTelemetry export, and sends usage, cost and Git
|
|
9
|
+
context to your backend. Nothing sits in front of the model: no proxy, no MITM certificate, no
|
|
10
|
+
daemon, no root.
|
|
11
|
+
|
|
12
|
+
Supports **Claude Code**, **OpenAI Codex**, **Cursor**, **Gemini CLI** and **Google Antigravity**.
|
|
9
13
|
|
|
10
14
|
---
|
|
11
15
|
|
|
12
16
|
## Quick Start
|
|
13
17
|
|
|
14
|
-
**Requirements:** Node.js 20+
|
|
18
|
+
**Requirements:** Node.js 20+ — every release runs the whole suite on Node 20 and Node 24 on Linux and macOS. Windows deployment remains unverified.
|
|
15
19
|
|
|
16
20
|
```bash
|
|
17
|
-
|
|
18
|
-
|
|
21
|
+
npx -y @agent-watch-ai/edge setup --token YOUR_TOKEN
|
|
22
|
+
agentwatch doctor # is this machine actually reporting?
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Run through npx, setup installs this version globally (`npm install -g`) and finishes from there, so the hooks point at the permanent install. Restart any running agent afterwards: hooks and exporters are read at startup.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Also here: `agent-watch-otel` (Python)
|
|
19
30
|
|
|
20
|
-
|
|
21
|
-
|
|
31
|
+
[`python/agent-watch-otel/`](python/agent-watch-otel) is a separate package,
|
|
32
|
+
released together with its Node twin `@agent-watch-ai/otel`, for **production**
|
|
33
|
+
LLM spend rather than coding agents. One line
|
|
34
|
+
beside a Phoenix registration sends digests of your prompts — never the prompts —
|
|
35
|
+
to Agent Watch, including the `service.name` and `service.version` Phoenix drops.
|
|
22
36
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
agentwatch doctor
|
|
37
|
+
```python
|
|
38
|
+
tracer_provider.add_span_processor(AgentWatchSpanProcessor(token="..."))
|
|
26
39
|
```
|
|
27
40
|
|
|
28
41
|
---
|
|
29
42
|
|
|
30
|
-
## Supported Agents
|
|
43
|
+
## Supported Agents
|
|
31
44
|
|
|
32
|
-
| Agent |
|
|
45
|
+
| Agent | Hooks configured in | Native OTel signals | Token usage |
|
|
33
46
|
|---|---|---|---|
|
|
34
|
-
| **Claude Code** | `~/.claude/settings.json` | Logs, Traces, Metrics |
|
|
35
|
-
| **OpenAI Codex** | `~/.codex/hooks.json` | Logs, Traces (`~/.codex/config.toml`) |
|
|
36
|
-
| **Gemini CLI** | `~/.gemini/settings.json` | Logs, Traces, Metrics |
|
|
37
|
-
| **Cursor** | `~/.cursor/hooks.json` | None |
|
|
38
|
-
| **Google Antigravity** | `~/.gemini/config/hooks.json` | None |
|
|
39
|
-
|
|
40
|
-
### Agent Limitations & Notes
|
|
41
|
-
|
|
42
|
-
* **Claude Code**:
|
|
43
|
-
* Running sessions must be restarted after `agentwatch setup` to apply telemetry environment variables.
|
|
44
|
-
* **OpenAI Codex**:
|
|
45
|
-
* Requires trusting new hooks: launch `codex`, type `/hooks`, and approve AgentWatch entries.
|
|
46
|
-
* **Gemini CLI**:
|
|
47
|
-
* Running sessions must be restarted after setup to load new hooks and OpenTelemetry configuration.
|
|
48
|
-
* Telemetry is enabled through `GEMINI_TELEMETRY_ENABLED` with `GEMINI_TELEMETRY_TARGET=local`, and the ingest token travels in `OTEL_EXPORTER_OTLP_HEADERS`. Gemini CLI does not support Claude Code's `otelHeadersHelper`.
|
|
49
|
-
* **Google Antigravity**:
|
|
50
|
-
* **No native token usage**: Antigravity exposes no OpenTelemetry exporter configuration and no readable transcript usage, so `turn.summary` events remain `usage_status: "pending"` and carry no cost.
|
|
51
|
-
* **Turns, not model calls**: a turn is one *execution*. `PreInvocation`/`PostInvocation` bracket the individual model calls inside an execution, and only the `Stop` hook closes a turn.
|
|
52
|
-
* The prompt is read from `common.lastUserInput` — Antigravity has no user-prompt hook of its own.
|
|
53
|
-
* Running sessions must be restarted after `agentwatch setup` to load new hooks.
|
|
54
|
-
* **Cursor**:
|
|
55
|
-
* **No native token usage**: Cursor exposes no token usage in hooks or transcripts, so `turn.summary` events remain `usage_status: "pending"`.
|
|
56
|
-
* **Cursor CLI**: Currently emits only shell hook events. Full hook lifecycle is available only in Cursor IDE sessions.
|
|
57
|
-
* **Cloud VMs**: Cloud agents do not have access to the local user hook or binary by default; they require an explicit committed `.cursor/hooks.json` and package installation in the cloud environment.
|
|
58
|
-
* **Tab suggestions**: AgentWatch monitors accepted edits (`afterTabFileEdit`) and intentionally ignores high-frequency `beforeTabFileRead` events.
|
|
47
|
+
| **Claude Code** | `~/.claude/settings.json` | Logs, Traces, Metrics | Yes |
|
|
48
|
+
| **OpenAI Codex** | `~/.codex/hooks.json` | Logs, Traces (`~/.codex/config.toml`) | Yes |
|
|
49
|
+
| **Gemini CLI** | `~/.gemini/settings.json` | Logs, Traces, Metrics | Yes |
|
|
50
|
+
| **Cursor** | `~/.cursor/hooks.json` | None | **No** |
|
|
51
|
+
| **Google Antigravity** | `~/.gemini/config/hooks.json` | None | **No** |
|
|
59
52
|
|
|
60
|
-
|
|
53
|
+
Cursor and Antigravity expose no token usage in hooks or transcripts, so their `turn.summary`
|
|
54
|
+
events stay `usage_status: "pending"` and carry no cost. Everything else — turns, tools, files,
|
|
55
|
+
branches, ticket keys — is reported for all five.
|
|
61
56
|
|
|
62
|
-
|
|
57
|
+
Per-agent notes:
|
|
63
58
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
agentwatch agents # List detected agents & status
|
|
69
|
-
|
|
70
|
-
# Diagnostics & Status
|
|
71
|
-
agentwatch status # Backend, queue, and agent health
|
|
72
|
-
agentwatch doctor # Run environment checks (use --json for CI)
|
|
73
|
-
|
|
74
|
-
# Hook Execution (invoked automatically by agents)
|
|
75
|
-
agentwatch hook --agent claude # Process stdin payload from agent
|
|
76
|
-
agentwatch hook --agent codex --dry-run # Test hook output without sending
|
|
77
|
-
|
|
78
|
-
# Telemetry & Teardown
|
|
79
|
-
agentwatch otel-headers # Output formatted OTel headers
|
|
80
|
-
agentwatch uninstall # Remove hooks and restore backups
|
|
81
|
-
agentwatch uninstall --purge # Also delete ~/.agentwatch and queues
|
|
82
|
-
```
|
|
59
|
+
* **OpenAI Codex** — new hooks must be trusted once: launch `codex`, type `/hooks`, approve the AgentWatch entries.
|
|
60
|
+
* **Gemini CLI** — telemetry runs through `GEMINI_TELEMETRY_ENABLED` with `GEMINI_TELEMETRY_TARGET=local`, and the ingest token travels in `OTEL_EXPORTER_OTLP_HEADERS`; Gemini has no `otelHeadersHelper`.
|
|
61
|
+
* **Google Antigravity** — a turn is one *execution*: `PreInvocation`/`PostInvocation` bracket the model calls inside it and only `Stop` closes it. The prompt comes from `common.lastUserInput`; there is no user-prompt hook.
|
|
62
|
+
* **Cursor** — the CLI emits shell hooks only; the full lifecycle exists in IDE sessions. Cloud agents need a committed `.cursor/hooks.json` and the package installed in the cloud environment. Accepted tab edits (`afterTabFileEdit`) are monitored; high-frequency `beforeTabFileRead` is ignored.
|
|
83
63
|
|
|
84
64
|
---
|
|
85
65
|
|
|
86
|
-
##
|
|
66
|
+
## CLI
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
agentwatch setup --token <key> # install hooks and exporters
|
|
70
|
+
agentwatch status # backend, queue and agent health
|
|
71
|
+
agentwatch doctor # environment checks (--json for CI)
|
|
72
|
+
agentwatch config # active configuration, secrets redacted
|
|
73
|
+
agentwatch agents # detected agents and their state
|
|
74
|
+
|
|
75
|
+
agentwatch off # stop hooks, remove managed exporters
|
|
76
|
+
agentwatch on # put them back
|
|
77
|
+
agentwatch uninstall [--purge] # remove hooks, revoke this machine's credential; --purge also deletes ~/.agentwatch
|
|
78
|
+
agentwatch update [--check] # install the latest release from npm; --check only asks
|
|
79
|
+
|
|
80
|
+
agentwatch hook --agent claude [--dry-run] # invoked by the agents themselves
|
|
81
|
+
agentwatch otel-headers # print OTel headers for an agent
|
|
82
|
+
```
|
|
87
83
|
|
|
88
|
-
| Flag |
|
|
84
|
+
| Flag | Meaning | Default |
|
|
89
85
|
|---|---|---|
|
|
90
|
-
| `--endpoint <url>` | Backend base URL
|
|
91
|
-
| `--
|
|
92
|
-
| `--
|
|
93
|
-
| `--
|
|
94
|
-
| `--
|
|
95
|
-
| `--
|
|
96
|
-
| `--
|
|
97
|
-
| `--dry-run` |
|
|
98
|
-
| `--json` |
|
|
99
|
-
| `--verbose` |
|
|
100
|
-
| `--version` |
|
|
86
|
+
| `--endpoint <url>` | Backend base URL: an Agent Watch host (`https://api.agent-watch.ai`), or loopback (`http:` allowed). Setup never prompts | `https://api.agent-watch.ai` |
|
|
87
|
+
| `--allow-custom-endpoint` | Trust the origin of this run's `--endpoint` when it is outside the Agent Watch hosts, such as a self-hosted backend. Only that origin is stored, in `customEndpoints`, and `status` and `doctor` show it. A re-run naming an origin already trusted needs no flag. Without it, setup refuses such a URL and writes nothing, and a config that names one sends nothing there: records stay queued and `doctor` names the fix. A config written before this release keeps its backends: they are added to `customEndpoints` once, on first load. A native exporter AgentWatch wrote into an agent's own config that points at a refused host is removed by `setup`, by `doctor`, and by the hooks at most once a day; `otel-headers` gives Claude Code's exporter the bearer only when it sends to the configured, allowed host. TLS is still checked against the system trust store, with no pinning | off |
|
|
88
|
+
| `--token <token>` | Bearer token for the backend | — |
|
|
89
|
+
| `--developer-email <email>` | Identity on turn summaries, and what per-developer budgets key on. Setup refuses to write a config when neither this flag nor git names a developer | `git config user.email` |
|
|
90
|
+
| `--root <path>` | File a second identity under a project root, so one machine can report to two tenants (needs its own `--token`) | — |
|
|
91
|
+
| `--otel <signals>` | Signals the agents export: `logs`, `traces`, `metrics`, `all`, `none` | `logs` |
|
|
92
|
+
| `--agent <id>` | Limit the command to one agent (`claude`, `codex`, `cursor`, `gemini`, `antigravity`) | all detected |
|
|
93
|
+
| `--dry-run` | With `hook`: print the events instead of sending them | `false` |
|
|
94
|
+
| `--json` | With `doctor`: machine-readable output | `false` |
|
|
95
|
+
| `--verbose` | Diagnostic logs on stderr | `false` |
|
|
96
|
+
| `--version` | Print the version | — |
|
|
101
97
|
|
|
102
98
|
---
|
|
103
99
|
|
|
104
100
|
## Configuration
|
|
105
101
|
|
|
106
|
-
|
|
107
|
-
|
|
102
|
+
One global file: `~/.agentwatch/config.json`, written by `agentwatch setup`.
|
|
103
|
+
|
|
104
|
+
### Content capture is opt-in
|
|
105
|
+
|
|
106
|
+
Prompt text, tool inputs, tool outputs and session titles are off by default. Turning one on takes **two** things —
|
|
107
|
+
the global `contentCaptureConsent` marker *and* the individual flag. The marker alone enables
|
|
108
|
+
nothing; a flag alone collects nothing. With all of them off a prompt or response is recorded only
|
|
109
|
+
as a length and a SHA-256, so turn counts and cost attribution work without the text. Ticket keys
|
|
110
|
+
named in the opening prompt are extracted on the machine and sent as `prompt_jira_ids`, unfiltered
|
|
111
|
+
(the platform keeps only keys it knows); the prompt text is not.
|
|
108
112
|
|
|
109
113
|
```json
|
|
110
114
|
{
|
|
115
|
+
"contentCaptureConsent": true,
|
|
111
116
|
"capture": {
|
|
112
|
-
"
|
|
113
|
-
"
|
|
114
|
-
"toolInput": true,
|
|
117
|
+
"promptText": false,
|
|
118
|
+
"toolInput": false,
|
|
115
119
|
"toolOutput": false,
|
|
120
|
+
"sessionTitle": false,
|
|
116
121
|
"git": true,
|
|
117
|
-
"files": true
|
|
122
|
+
"files": true,
|
|
123
|
+
"mcpNames": true
|
|
118
124
|
}
|
|
119
125
|
}
|
|
120
126
|
```
|
|
121
127
|
|
|
122
|
-
*
|
|
123
|
-
|
|
124
|
-
|
|
128
|
+
* `promptText` sends the turn's first prompt as `prompt_text`: blocks the agent's harness injected
|
|
129
|
+
(Claude Desktop's `<system-reminder>`) removed, secrets scrubbed over the whole text, then cut at
|
|
130
|
+
4,000 characters. It is what lets the backend tell what a session with no repository was about.
|
|
131
|
+
* `toolInput` sends, per shell or connector (MCP) call, the command text or the server, tool and
|
|
132
|
+
arguments, as `tool_inputs`: at most 50 calls a turn, each string cut at 2,000 characters after
|
|
133
|
+
scrubbing.
|
|
134
|
+
* `sessionTitle` sends a Claude Code, Codex or Cursor session's native title on every turn:
|
|
135
|
+
`session_name` when the agent keeps a separate person-set name, and `session_title` for its
|
|
136
|
+
generated/display title, which can paraphrase the first prompt. Each is scrubbed, then cut at 200
|
|
137
|
+
characters. Reading Codex and Cursor's SQLite indexes requires Node 22.12 or newer; older runtimes
|
|
138
|
+
omit those optional fields. Gemini CLI and Antigravity expose neither, so the edge does not invent one.
|
|
139
|
+
* `mcpNames` (on by default) names each MCP call in `tools_used` as `mcp__<server>__<tool>`, no
|
|
140
|
+
arguments. Off, every MCP call counts under `mcp`. A repository file can turn it off, never on.
|
|
141
|
+
* The agent's response text has no flag: it never leaves the machine.
|
|
142
|
+
|
|
143
|
+
`git` and `files` are on because they carry metadata, not content: remote, branch, SHA, and the
|
|
144
|
+
*path* of a file the agent touched — which is what feature and project attribution is built from.
|
|
145
|
+
A file outside every checkout (`~/Documents/Sample Budget.xlsx`) goes in its own
|
|
146
|
+
`external_files_touched` / `external_files_read` lists (while `git` is also on), home-relative: the home directory's name
|
|
147
|
+
is never sent.
|
|
148
|
+
|
|
149
|
+
**Upgrading from an earlier release?** `capture.prompts` and `capture.responses` no longer exist. A
|
|
150
|
+
config that still sets them collects nothing — `prompts: true` does not turn on `promptText`; the next `agentwatch setup` removes them and says so,
|
|
151
|
+
and `agentwatch doctor` names them until it does. Summaries an older release queued with text in
|
|
152
|
+
them are sent without it. The two tool flags without the consent marker read as `false`, are kept as
|
|
153
|
+
written, and `setup` names the ones that are set but inert.
|
|
154
|
+
|
|
155
|
+
**Native exporters never log prompts.** Setup forces prompt and response logging off in every agent
|
|
156
|
+
it configures (Claude `OTEL_LOG_USER_PROMPTS=0`, Codex `log_user_prompt = false`, Gemini
|
|
157
|
+
`GEMINI_TELEMETRY_LOG_PROMPTS=false`), whatever the consent state, and never enables Gemini traces,
|
|
158
|
+
which can carry prompts. Codex and Gemini usage logs can carry tool arguments and results with no
|
|
159
|
+
per-field filter, so setup configures them only when consent covers both `toolInput` and
|
|
160
|
+
`toolOutput` — which can leave `llm.call` usage unavailable for those two in metadata-only mode.
|
|
161
|
+
|
|
162
|
+
### Untraced-run notice
|
|
163
|
+
|
|
164
|
+
After a shell run (`python`, `node`, `npm test`, …) in a repository whose dependency manifests
|
|
165
|
+
declare an LLM SDK and no tracing package, Claude Code and Codex show the developer one line saying
|
|
166
|
+
the run's spend is invisible. At most once per repository per session; decided on the laptop from
|
|
167
|
+
`package.json`, `pyproject.toml`, `requirements*.txt` and `Pipfile` only, and nothing is sent.
|
|
168
|
+
Turn it off in the global file (a repository's `.agentwatch.json` cannot change it):
|
|
125
169
|
|
|
126
|
-
|
|
170
|
+
```json
|
|
171
|
+
{ "untracedNotices": false }
|
|
172
|
+
```
|
|
127
173
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
174
|
+
### Repository overrides
|
|
175
|
+
|
|
176
|
+
A `.agentwatch.json` in a repository root can only turn capture **down** for that repository:
|
|
177
|
+
|
|
178
|
+
```json
|
|
179
|
+
{ "capture": { "toolOutput": false, "files": false } }
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
A committed file that asks for *more* than the machine allows is ignored with a warning, so
|
|
183
|
+
checking a repository out can never start collecting content on someone else's machine. `endpoint`,
|
|
184
|
+
`token`, `developerEmail`, `enforcementUrl`, `roots` and the `delivery` / `otel` / `enforcement`
|
|
185
|
+
blocks are global-only: a repository file cannot redirect delivery or switch off a budget cap.
|
|
186
|
+
|
|
187
|
+
### Two tenants on one machine
|
|
188
|
+
|
|
189
|
+
`roots` maps an absolute project root to the identity used beneath it; work outside every root keeps
|
|
190
|
+
the machine's own. Set the machine up first, then
|
|
191
|
+
`agentwatch setup --root ~/dev/acme --token <tenant token>` — a root never inherits the machine's
|
|
192
|
+
token — or by hand:
|
|
131
193
|
|
|
132
194
|
```json
|
|
133
195
|
{
|
|
134
|
-
"
|
|
196
|
+
"endpoint": "https://backend.example.com",
|
|
197
|
+
"token": "<machine default>",
|
|
198
|
+
"roots": {
|
|
199
|
+
"/Users/me/dev/tripPlanner": { "token": "<tenant A>" },
|
|
200
|
+
"/Users/me/dev/acme": { "token": "<tenant B>", "developerEmail": "me@acme.com" }
|
|
201
|
+
}
|
|
135
202
|
}
|
|
136
203
|
```
|
|
137
204
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
205
|
+
Longest match wins. Point a root at the directory the agent actually opens: a session started one
|
|
206
|
+
level above it does not match. Only identity varies per root — capture and OTel signals stay
|
|
207
|
+
machine-wide, so `--otel` is refused together with `--root`. A session started above its
|
|
208
|
+
repositories reports the repository each turn worked in, but that changes nothing here: the start
|
|
209
|
+
folder decides which root, and therefore which tenant, a session belongs to — except that a session
|
|
210
|
+
started in no root, working in a checkout it inherited from the process that started the agent, sends
|
|
211
|
+
as the root that claims that checkout; if none does, the checkout is not reported. With roots configured and the start folder in none, a
|
|
212
|
+
checkout that no root claims is also reported, whatever its location. A repository
|
|
213
|
+
beneath it that another root claims is refused outright — its name, branch, commit and paths
|
|
214
|
+
belong to that root's tenant — and a repository's own `.agentwatch.json` narrows what a turn
|
|
215
|
+
reports about it, as it would for a session started inside.
|
|
216
|
+
|
|
217
|
+
The offline queue is partitioned to match (`<data>/queue/<digest-of-token>/`), as are the backend
|
|
218
|
+
cooldown and the loss tally, so a drain only ever sends the backlog belonging to the token it signs
|
|
219
|
+
with. Agents export native OTLP to one machine-wide endpoint, so under a root pointing at a
|
|
220
|
+
*different* backend `otel-headers` sends no bearer rather than the wrong tenant's — that tenant then
|
|
221
|
+
gets hook-path events only. Roots on the same backend, the usual case, differ only in bearer.
|
|
222
|
+
|
|
223
|
+
Upgrading from a version without partitions adopts an existing backlog when the machine has one
|
|
224
|
+
identity; when it already has several, those entries name no tenant and are moved to
|
|
225
|
+
`<data>/queue/unattributed/`, where `status` and `doctor` report them. Move them into a partition to
|
|
226
|
+
deliver them, or delete the directory to discard them.
|
|
227
|
+
|
|
228
|
+
### Stopping collection without uninstalling
|
|
229
|
+
|
|
230
|
+
`agentwatch off` stops the hooks before they read stdin, withholds the OTLP bearer, and removes the
|
|
231
|
+
exporters AgentWatch installed — keeping config and queued events. `agentwatch on` restores it.
|
|
232
|
+
Restart running agents either way. See [docs/DATA_HANDLING.md](docs/DATA_HANDLING.md) for what the
|
|
233
|
+
off switch does and does not reach.
|
|
234
|
+
|
|
235
|
+
### Fleet deployment
|
|
236
|
+
|
|
237
|
+
[`examples/mdm/`](https://github.com/agent-watch-ai/agent-watch-edge/tree/main/examples/mdm) has a
|
|
238
|
+
Jamf/Kandji script, an Intune script, a Claude Code `managed-settings.json` policy file, and a
|
|
239
|
+
per-agent answer about what an administrator can lock — which for every agent but Claude Code is
|
|
240
|
+
currently "the developer can remove the hooks".
|
|
241
|
+
|
|
242
|
+
### Budget enforcement
|
|
243
|
+
|
|
244
|
+
When a backend budget is set to **block** and the developer has breached it, the turn is refused
|
|
245
|
+
before the agent's first LLM call, in the agent's own protocol (Claude Code, Codex, Cursor, Gemini
|
|
246
|
+
CLI), with the backend's explanation shown to the developer.
|
|
142
247
|
|
|
143
|
-
|
|
144
|
-
|
|
248
|
+
```json
|
|
249
|
+
{ "enforcement": { "enabled": true, "timeoutMs": 300, "cacheTtlMs": 5000 } }
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
The check **fails open, always.** A turn stops only on an explicit
|
|
253
|
+
`{"decision":"block","message":"…"}` from `GET <backend>/v1/enforcement/decision`; an unreachable
|
|
254
|
+
backend, a timeout, any other status and any unreadable body let the turn proceed silently — so an
|
|
255
|
+
outage un-enforces budgets rather than stopping anyone. Set `enabled: false` to opt out.
|
|
256
|
+
|
|
257
|
+
Decisions are cached for `cacheTtlMs`, so a flat cap costs at most one bounded request per turn. A
|
|
258
|
+
feature-scoped cap costs one per gated prompt: the backend answers `cache_ttl_ms: 0` and the edge
|
|
259
|
+
honours that by not storing the answer. Antigravity is not gated — its pre-invocation hook carries
|
|
260
|
+
no decision field — and its turns are reported without token usage, so no cap advances on them.
|
|
145
261
|
|
|
146
|
-
To try it locally: `BLOCK=1 npm run example`
|
|
262
|
+
To try it locally: `BLOCK=1 npm run example` refuses every check.
|
|
147
263
|
|
|
148
264
|
---
|
|
149
265
|
|
|
150
|
-
##
|
|
266
|
+
## What reaches the backend
|
|
267
|
+
|
|
268
|
+
| Record | How | Contents |
|
|
269
|
+
|---|---|---|
|
|
270
|
+
| `turn.summary` | Edge hooks → `POST <backend>/v1/events` | One completed turn: prompt/response length and hash, tool counts, file paths (repo-relative, and home-relative outside a checkout), Git branch, ticket keys from the branch name and the opening prompt. Prompt text and shell/connector inputs only when opted in. Never response text. |
|
|
271
|
+
| `llm.call` | The agent's own OTLP → `POST <backend>/v1/otlp/v1/logs` | Token usage, cost and latency per model request. The edge does not proxy this. |
|
|
272
|
+
| `repo.snapshot` | Edge hooks, after a closed turn | Changed branch/commit metadata, including commit subjects, when Git capture is on. |
|
|
273
|
+
|
|
274
|
+
The backend joins `llm.call` to `turn.summary` on conversation and turn ids.
|
|
151
275
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
276
|
+
Exact fields, local retention, privacy migration and off-switch behaviour:
|
|
277
|
+
[docs/DATA_HANDLING.md](docs/DATA_HANDLING.md). Release artifacts, rollback verification and the
|
|
278
|
+
explicitly deferred enterprise work (Windows, native binaries, signing, SOC 2):
|
|
279
|
+
[docs/ENTERPRISE_DEPLOYMENT.md](docs/ENTERPRISE_DEPLOYMENT.md).
|
|
155
280
|
|
|
156
|
-
### Backend SDK
|
|
281
|
+
### Backend SDK helpers
|
|
157
282
|
|
|
158
283
|
```ts
|
|
159
284
|
import type { ProductEvent } from '@agent-watch-ai/edge/events';
|
package/SECURITY.md
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Security Policy
|
|
2
|
+
|
|
3
|
+
## Reporting a vulnerability
|
|
4
|
+
|
|
5
|
+
Please report vulnerabilities privately via GitHub Security Advisories on this repository
|
|
6
|
+
(Security → "Report a vulnerability"). Do not open public issues for security reports. You can
|
|
7
|
+
expect an acknowledgement within a few business days.
|
|
8
|
+
|
|
9
|
+
## Scope & design guarantees
|
|
10
|
+
|
|
11
|
+
AgentWatch Edge handles developer activity metadata, so the following are treated as security
|
|
12
|
+
bugs of the highest priority:
|
|
13
|
+
|
|
14
|
+
- response text leaving the machine, or reaching the queue or turn state, under any configuration;
|
|
15
|
+
prompt text or tool content leaving the machine while its capture flag or the global consent
|
|
16
|
+
marker is off; captured text leaving unscrubbed or beyond its bound; a path naming the home
|
|
17
|
+
directory
|
|
18
|
+
- setup enabling any agent's native prompt or response logging
|
|
19
|
+
- secrets (tokens, keys, credentials, URL-embedded credentials) surviving the sanitizer in
|
|
20
|
+
events, logs, queue files, or diagnostics output
|
|
21
|
+
- credentials written into agent config files beyond the two sanctioned places: Claude Code
|
|
22
|
+
gets a short-lived access token via `otelHeadersHelper` (never written to its settings), while
|
|
23
|
+
Codex has no headers-helper mechanism, so its OTel exporter carries the device's one-hour
|
|
24
|
+
access token inside `~/.codex/config.toml` — which setup therefore keeps at mode 0600, and
|
|
25
|
+
every hook rewrites as the token rotates. Gemini stores the same access token in
|
|
26
|
+
`~/.gemini/settings.json` (0600); it has no headers helper. The device secret is never written
|
|
27
|
+
to either file, and the install key only while the machine has no device yet: the
|
|
28
|
+
first hook with a device token replaces it, and on Windows the next successful setup does (docs/NATIVE_OTLP_TOKENS.md).
|
|
29
|
+
- a long-lived credential on disk in plaintext where an OS keychain exists. The edge exchanges
|
|
30
|
+
the organization install key for a per-device credential on its first run after setup or
|
|
31
|
+
upgrade, records the device beside the install key in `~/.agentwatch/config.json` (the key
|
|
32
|
+
stays there, 0600, to enroll again when the secret expires), and keeps the device
|
|
33
|
+
secret in the macOS Keychain, the Secret Service keyring (libsecret) or a Windows
|
|
34
|
+
DPAPI-protected file. Only where none of those is usable (for example headless Linux) does
|
|
35
|
+
it fall back to a 0600 file under `~/.agentwatch/credentials/`, and `status` and `doctor`
|
|
36
|
+
say so. The secret is handed to the keychain tool on stdin, never in argv or the
|
|
37
|
+
environment, and the tool is run from the system directories, never found on `PATH`. What goes on the wire is a one-hour access token, cached 0600 per identity in
|
|
38
|
+
the data directory and refreshed by one process per machine under a lock.
|
|
39
|
+
- destructive or non-mergeful writes to `~/.claude` / `~/.codex` configuration
|
|
40
|
+
- the hook process breaking or blocking the host coding agent
|
|
41
|
+
|
|
42
|
+
## Every line that runs on the developer's machine is open
|
|
43
|
+
|
|
44
|
+
There is no closed on-device component. What the Edge does on a laptop — which
|
|
45
|
+
hooks it registers, what it reads, what it sends, what the sanitizer strips — is
|
|
46
|
+
this repository, MIT-licensed, and a reviewer can read it rather than take our
|
|
47
|
+
word for it. The closed half is the backend that receives the records.
|
|
48
|
+
|
|
49
|
+
That is also the honest limit: a local administrator can read, edit or remove
|
|
50
|
+
any of it. The Edge does not self-protect and does not re-apply itself on a
|
|
51
|
+
schedule; a machine that stops reporting is the signal, and it is visible on the
|
|
52
|
+
platform side. See [MDM deployment](https://github.com/agent-watch-ai/agent-watch-edge/tree/main/examples/mdm) for what an
|
|
53
|
+
administrator can and cannot lock per agent.
|
|
54
|
+
|
|
55
|
+
## Data handling summary
|
|
56
|
+
|
|
57
|
+
- The public contract contains `llm.call`, `turn.summary`, and `repo.snapshot`. Raw lifecycle/tool hooks stay
|
|
58
|
+
local; tool I/O is never a third outbound event stream. If config is missing or corrupt, the
|
|
59
|
+
runtime fails safe to metadata-only summary capture.
|
|
60
|
+
- Git remote URLs are credential-stripped and normalized; hashes are available,
|
|
61
|
+
but summaries and snapshots also disclose normalized repository names.
|
|
62
|
+
- Local queue files live under the user's data directory and contain already-sanitized events.
|
|
63
|
+
- `doctor`/`status` never print token values.
|
|
64
|
+
|
|
65
|
+
The [data handling contract](docs/DATA_HANDLING.md) specifies collection defaults,
|
|
66
|
+
global consent migration, native OTLP boundaries, credentials, retention and the
|
|
67
|
+
local off switch. Native exporters require setup and an agent restart after an
|
|
68
|
+
upgrade; the hook consent gate cannot filter traffic sent directly by an agent.
|
|
69
|
+
To check that contract against the source with your own coding agent, use the
|
|
70
|
+
[audit prompt](docs/AUDIT_PROMPT.md).
|
|
71
|
+
No compliance attestation or completed penetration test is claimed. See
|
|
72
|
+
[deferred enterprise work](docs/ENTERPRISE_DEPLOYMENT.md).
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import type { Env } from '../core/types/core.types.js';
|
|
2
|
+
import type { AgentWatchEvent } from '../events/types/events.types.js';
|
|
3
|
+
import type { SessionBillingEvent } from '../events/types/session-billing.types.js';
|
|
4
|
+
import type { TurnStateStore } from '../turns/turn-state.js';
|
|
5
|
+
/**
|
|
6
|
+
* The session's billing fact, the first time it is asked for.
|
|
7
|
+
*
|
|
8
|
+
* The id is derived from provider and session alone, so a resend (a resumed
|
|
9
|
+
* session, a queue retry) is the same record to the backend.
|
|
10
|
+
*
|
|
11
|
+
* @param store - Per-session state store; remembers that the fact was taken.
|
|
12
|
+
* @param events - The hook's canonical events.
|
|
13
|
+
* @param agentId - Internal provider id.
|
|
14
|
+
* @param env - Environment supplying HOME and the relevant variables.
|
|
15
|
+
* @param surface - Product surface the session runs on.
|
|
16
|
+
* @returns The event, or undefined when the session already has one, this hook
|
|
17
|
+
* does not open anything, or the mode cannot be told.
|
|
18
|
+
*/
|
|
19
|
+
export declare function sessionBillingFact(store: TurnStateStore, events: readonly AgentWatchEvent[], agentId: string, env: Env, surface: string): Promise<SessionBillingEvent | undefined>;
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import { compact } from '../core/object.js';
|
|
2
|
+
import { deriveEventId } from '../events/event-id.js';
|
|
3
|
+
import { EVENT_SCHEMA_VERSION } from '../events/constants/events.constants.js';
|
|
4
|
+
import { PROVIDER_LABELS } from '../turns/constants/turns.constants.js';
|
|
5
|
+
import { detectBillingMode } from './billing-mode.js';
|
|
6
|
+
/** The hooks that open a session or a turn: the earliest a collector hears from it. */
|
|
7
|
+
const OPENING_TYPES = new Set(['session.started', 'prompt.submitted']);
|
|
8
|
+
/**
|
|
9
|
+
* The session's billing fact, the first time it is asked for.
|
|
10
|
+
*
|
|
11
|
+
* The id is derived from provider and session alone, so a resend (a resumed
|
|
12
|
+
* session, a queue retry) is the same record to the backend.
|
|
13
|
+
*
|
|
14
|
+
* @param store - Per-session state store; remembers that the fact was taken.
|
|
15
|
+
* @param events - The hook's canonical events.
|
|
16
|
+
* @param agentId - Internal provider id.
|
|
17
|
+
* @param env - Environment supplying HOME and the relevant variables.
|
|
18
|
+
* @param surface - Product surface the session runs on.
|
|
19
|
+
* @returns The event, or undefined when the session already has one, this hook
|
|
20
|
+
* does not open anything, or the mode cannot be told.
|
|
21
|
+
*/
|
|
22
|
+
export async function sessionBillingFact(store, events, agentId, env, surface) {
|
|
23
|
+
const opening = events.find((event) => OPENING_TYPES.has(event.event.type) && event.session.id);
|
|
24
|
+
if (!opening?.session.id)
|
|
25
|
+
return undefined;
|
|
26
|
+
const mode = await detectBillingMode(agentId, env);
|
|
27
|
+
// Unknown is not a fact, and must not use up the session's one send.
|
|
28
|
+
if (mode === 'unknown')
|
|
29
|
+
return undefined;
|
|
30
|
+
// A session that inherited its checkout may belong to another root's tenant,
|
|
31
|
+
// which only its turn summary resolves. Sent from here it would reach the
|
|
32
|
+
// machine's tenant and spend the session's one send; its summary carries the mode.
|
|
33
|
+
if (await store.readInherited(opening.session.id))
|
|
34
|
+
return undefined;
|
|
35
|
+
if (!(await store.takeBillingFact(opening.session.id)))
|
|
36
|
+
return undefined;
|
|
37
|
+
const timestamp = env.now().toISOString();
|
|
38
|
+
// The public label, as the turn summary and the calls carry it.
|
|
39
|
+
const provider = PROVIDER_LABELS[opening.agent.provider] ?? opening.agent.provider;
|
|
40
|
+
return compact({
|
|
41
|
+
schemaVersion: EVENT_SCHEMA_VERSION,
|
|
42
|
+
id: deriveEventId({ provider: opening.agent.provider, providerEventType: 'session.billing', sessionId: opening.session.id }),
|
|
43
|
+
timestamp,
|
|
44
|
+
event: { type: 'session.billing', providerEventType: 'session.billing' },
|
|
45
|
+
agent: { ...opening.agent, provider },
|
|
46
|
+
session: { id: opening.session.id, providerId: opening.session.id },
|
|
47
|
+
provider,
|
|
48
|
+
surface,
|
|
49
|
+
session_id: opening.session.id,
|
|
50
|
+
billing_mode: mode
|
|
51
|
+
});
|
|
52
|
+
}
|
package/dist/cli/args.d.ts
CHANGED
|
@@ -11,6 +11,16 @@ export type { ParsedArgs } from './types/cli.types.js';
|
|
|
11
11
|
* @returns The command, positionals and flags.
|
|
12
12
|
*/
|
|
13
13
|
export declare function parseArgs(argv: readonly string[]): ParsedArgs;
|
|
14
|
+
/**
|
|
15
|
+
* The value flags given with no value, such as `--endpoint --token KEY`.
|
|
16
|
+
*
|
|
17
|
+
* Those parse as booleans and would read as absent, and an absent endpoint
|
|
18
|
+
* means the default backend: a typo must fail instead.
|
|
19
|
+
*
|
|
20
|
+
* @param parsed - Parsed arguments.
|
|
21
|
+
* @returns The flag names, without the `--`.
|
|
22
|
+
*/
|
|
23
|
+
export declare function valuelessFlags(parsed: ParsedArgs): string[];
|
|
14
24
|
/**
|
|
15
25
|
* A flag's value when it was given as a string.
|
|
16
26
|
*
|
package/dist/cli/args.js
CHANGED
|
@@ -27,6 +27,14 @@ export function parseArgs(argv) {
|
|
|
27
27
|
continue;
|
|
28
28
|
}
|
|
29
29
|
const name = arg.slice(FLAG_PREFIX.length);
|
|
30
|
+
const equals = name.indexOf('=');
|
|
31
|
+
// `--endpoint=https://…`: read as the flag and its value, never as an
|
|
32
|
+
// unknown flag that leaves the endpoint absent and the default in force.
|
|
33
|
+
if (equals > 0 && VALUE_FLAGS.has(name.slice(0, equals))) {
|
|
34
|
+
flags[name.slice(0, equals)] = name.slice(equals + 1) || true;
|
|
35
|
+
index += 1;
|
|
36
|
+
continue;
|
|
37
|
+
}
|
|
30
38
|
const value = argv[index + 1];
|
|
31
39
|
if (VALUE_FLAGS.has(name) && value !== undefined && !value.startsWith(FLAG_PREFIX)) {
|
|
32
40
|
flags[name] = value;
|
|
@@ -38,6 +46,18 @@ export function parseArgs(argv) {
|
|
|
38
46
|
}
|
|
39
47
|
return { command, positional, flags };
|
|
40
48
|
}
|
|
49
|
+
/**
|
|
50
|
+
* The value flags given with no value, such as `--endpoint --token KEY`.
|
|
51
|
+
*
|
|
52
|
+
* Those parse as booleans and would read as absent, and an absent endpoint
|
|
53
|
+
* means the default backend: a typo must fail instead.
|
|
54
|
+
*
|
|
55
|
+
* @param parsed - Parsed arguments.
|
|
56
|
+
* @returns The flag names, without the `--`.
|
|
57
|
+
*/
|
|
58
|
+
export function valuelessFlags(parsed) {
|
|
59
|
+
return [...VALUE_FLAGS].filter((name) => parsed.flags[name] === true);
|
|
60
|
+
}
|
|
41
61
|
/**
|
|
42
62
|
* A flag's value when it was given as a string.
|
|
43
63
|
*
|