@agent-watch-ai/edge 0.2.5 → 0.3.1
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 +512 -0
- package/README.md +217 -96
- package/SECURITY.md +69 -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 +50 -4
- package/dist/cli/constants/cli.constants.js +54 -5
- package/dist/cli/context.d.ts +33 -2
- package/dist/cli/context.js +84 -14
- package/dist/cli/doctor.js +309 -32
- 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 +439 -98
- package/dist/cli/status.js +82 -13
- package/dist/cli/toggle.d.ts +9 -0
- package/dist/cli/toggle.js +113 -0
- package/dist/cli/types/cli.types.d.ts +37 -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 +100 -13
- 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 +113 -6
- package/dist/config/constants/config.constants.js +126 -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 +721 -84
- package/dist/config/schemas/config.schema.js +388 -15
- 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 +111 -0
- package/dist/credentials/constants/credentials.constants.js +112 -0
- package/dist/credentials/credential-status.d.ts +14 -0
- package/dist/credentials/credential-status.js +34 -0
- package/dist/credentials/credentials.d.ts +72 -0
- package/dist/credentials/credentials.js +253 -0
- package/dist/credentials/device-api.d.ts +64 -0
- package/dist/credentials/device-api.js +150 -0
- package/dist/credentials/device-state.d.ts +31 -0
- package/dist/credentials/device-state.js +51 -0
- package/dist/credentials/identity.d.ts +62 -0
- package/dist/credentials/identity.js +90 -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 +18 -0
- package/dist/credentials/sign-in.js +86 -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 +195 -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 +62 -16
- package/dist/enforcement/enforcement.d.ts +23 -2
- package/dist/enforcement/enforcement.js +103 -15
- package/dist/enforcement/index.d.ts +4 -3
- package/dist/enforcement/index.js +3 -2
- package/dist/enforcement/types/enforcement.types.d.ts +64 -0
- 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 +7 -0
- package/dist/pipeline/constants/pipeline.constants.js +7 -0
- package/dist/pipeline/hook-pipeline.js +360 -32
- 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 +73 -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 +24 -2
- package/dist/providers/codex/codex.otel.js +147 -30
- 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 +5 -0
- package/dist/providers/codex/constants/codex.otel.constants.js +5 -0
- package/dist/providers/constants/provider.constants.d.ts +0 -3
- package/dist/providers/constants/provider.constants.js +0 -3
- package/dist/providers/cursor/constants/cursor.constants.d.ts +7 -0
- package/dist/providers/cursor/constants/cursor.constants.js +7 -0
- package/dist/providers/cursor/cursor.adapter.d.ts +33 -1
- package/dist/providers/cursor/cursor.adapter.js +52 -3
- 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 +3 -1
- package/dist/providers/gemini/constants/gemini.otel.constants.js +3 -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 +19 -20
- package/dist/providers/gemini/gemini.otel.js +121 -17
- 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/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 +18 -2
- package/dist/providers/shared/constants/tooling.constants.js +19 -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 +12 -1
- package/dist/providers/shared/tooling.js +18 -0
- package/dist/providers/shared/types/adapter.types.d.ts +1 -2
- package/dist/providers/types/provider.types.d.ts +57 -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 +7 -0
- package/dist/storage/atomic-file.js +1 -1
- package/dist/storage/constants/storage.constants.d.ts +17 -0
- package/dist/storage/constants/storage.constants.js +17 -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 +65 -0
- package/dist/turns/work-checkout.js +666 -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 +648 -0
- package/docs/ENTERPRISE_DEPLOYMENT.md +179 -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
|
@@ -0,0 +1,648 @@
|
|
|
1
|
+
# Data handling contract
|
|
2
|
+
|
|
3
|
+
This document describes `0.3.0`, not every previously published package. **Every
|
|
4
|
+
release up to and including npm `0.2.5` enabled content capture by default**;
|
|
5
|
+
`0.3.0` is the release that turns it off and puts it behind explicit consent.
|
|
6
|
+
Check the installed version — `agentwatch --version` — and run `agentwatch config`
|
|
7
|
+
and `agentwatch doctor` during deployment. To check this document against the source
|
|
8
|
+
with your own coding agent, use [AUDIT_PROMPT.md](AUDIT_PROMPT.md).
|
|
9
|
+
AgentWatch is a user-level, hook-only Node.js program. It does not install a daemon,
|
|
10
|
+
require root, proxy model requests, or enforce an administrator-proof policy.
|
|
11
|
+
|
|
12
|
+
## Defaults and upgrade consent
|
|
13
|
+
|
|
14
|
+
**Prompt text and tool content are opt-in; response text is never collected.**
|
|
15
|
+
By default a prompt or response is represented only by its length and SHA-256.
|
|
16
|
+
Ticket keys named in a prompt are the one exception: they are extracted on the
|
|
17
|
+
machine and sent as `prompt_jira_ids`, unfiltered (the platform keeps only keys it
|
|
18
|
+
knows); the prompt text is not.
|
|
19
|
+
There is no capture flag for response text.
|
|
20
|
+
|
|
21
|
+
Prompt text, tool input and tool output bodies, and session titles, are not collected by default.
|
|
22
|
+
Default capture is:
|
|
23
|
+
|
|
24
|
+
```json
|
|
25
|
+
{
|
|
26
|
+
"contentCaptureConsent": false,
|
|
27
|
+
"capture": {
|
|
28
|
+
"promptText": false,
|
|
29
|
+
"toolInput": false,
|
|
30
|
+
"toolOutput": false,
|
|
31
|
+
"sessionTitle": false,
|
|
32
|
+
"git": true,
|
|
33
|
+
"files": true
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
To find which checkout a turn worked in, the hook inspects a shell command's text
|
|
39
|
+
in memory for directory names and discards it. This applies to the shell calls of
|
|
40
|
+
every agent the edge supports: Claude Code, Codex, Cursor, Gemini CLI and
|
|
41
|
+
Antigravity. The command's working directory is used as a candidate when the agent
|
|
42
|
+
reports it (Cursor's shell `cwd`, Gemini's `dir_path`, Antigravity's `Cwd`), and so
|
|
43
|
+
are the folders a Cursor window has open. Only checkout roots confirmed on disk
|
|
44
|
+
are kept, in local turn state, until the turn closes. The command is never stored,
|
|
45
|
+
queued, logged or sent for that purpose. This happens only while `capture.git` is
|
|
46
|
+
on. Separately, with `toolInput` on, the command text itself is sent on the turn
|
|
47
|
+
summary (see `tool_inputs` below).
|
|
48
|
+
|
|
49
|
+
Configurations written by earlier releases may still carry `capture.prompts` or
|
|
50
|
+
`capture.responses`. Those keys are ignored on load whatever their value —
|
|
51
|
+
`prompts: true` does not turn on `promptText`, a new name chosen for that reason — the next
|
|
52
|
+
`agentwatch setup` removes them from the file and says so once, and `doctor`
|
|
53
|
+
reports them while they remain.
|
|
54
|
+
|
|
55
|
+
Old configurations with content flags explicitly `true` are interpreted as
|
|
56
|
+
metadata-only unless the global `contentCaptureConsent` marker is exactly `true`.
|
|
57
|
+
Neither loading nor `agentwatch setup` rewrites those flags: the gate is applied in
|
|
58
|
+
memory on every read, so adding the marker later restores the values already on
|
|
59
|
+
disk rather than finding them erased. Missing, unreadable, invalid, and corrupt
|
|
60
|
+
global configuration do not authorize content capture. Git and file-path capture
|
|
61
|
+
remain enabled unless separately disabled.
|
|
62
|
+
|
|
63
|
+
Intentional content opt-in requires editing the **global**
|
|
64
|
+
`~/.agentwatch/config.json`: set `contentCaptureConsent` to `true` and explicitly
|
|
65
|
+
set `promptText`, `toolInput`, `toolOutput` and/or `sessionTitle` to `true`. The marker alone does not enable
|
|
66
|
+
fields that are false. Set the marker to `false` to revoke consent. `config`,
|
|
67
|
+
`status`, and `doctor` report consent and capture state without printing captured
|
|
68
|
+
content. Repository `.agentwatch.json` files cannot grant consent, increase any
|
|
69
|
+
capture field, alter identity, redirect delivery, or change
|
|
70
|
+
enforcement/delivery/native OTel settings. They may reduce individual capture
|
|
71
|
+
fields.
|
|
72
|
+
|
|
73
|
+
Current policy is reapplied to old turn state before queueing, and to every queued
|
|
74
|
+
record before HTTP delivery: summaries always lose `prompt` and `response` text an
|
|
75
|
+
older release may have written, lose `prompt_text`, `tool_inputs`, `session_name` and `session_title` unless their
|
|
76
|
+
flag is on with consent, lose every path list once `capture.files` is off, and repository snapshots are dropped entirely once
|
|
77
|
+
`capture.git` is off. Old files are not erased by an upgrade; their original content
|
|
78
|
+
may remain locally until consumed or expired, but it is never sent.
|
|
79
|
+
|
|
80
|
+
**Upgrade native telemetry separately:** rerun `agentwatch setup` after upgrading,
|
|
81
|
+
then restart every running coding agent. Existing native exporter configuration
|
|
82
|
+
and in-memory exporters do not change merely because npm replaces the CLI.
|
|
83
|
+
Use `agentwatch off` and close agents before upgrading if export must be stopped
|
|
84
|
+
during the transition. Setup always disables native prompt logging (Claude
|
|
85
|
+
`OTEL_LOG_USER_PROMPTS=0`, Codex `log_user_prompt = false`, Gemini
|
|
86
|
+
`GEMINI_TELEMETRY_LOG_PROMPTS=false`) and Claude tool detail/content logging,
|
|
87
|
+
whatever the consent state, and never enables Gemini detailed traces, which can
|
|
88
|
+
carry prompts. Codex and Gemini usage logs can contain tool arguments/results
|
|
89
|
+
without a reliable per-field filter, so the Edge configures those logs only when
|
|
90
|
+
global consent exists and both `toolInput` and `toolOutput` are enabled. Gemini
|
|
91
|
+
metrics may run without content consent. This can leave `llm.call` usage
|
|
92
|
+
unavailable by default for Codex and Gemini. Codex turns still carry token
|
|
93
|
+
counts: the Edge reads only the `token_count` and `turn_context` rows of the
|
|
94
|
+
Codex rollout file locally (per-request token numbers and the model name) and
|
|
95
|
+
puts the totals on the turn summary; no rollout content is read into it or sent.
|
|
96
|
+
|
|
97
|
+
## Outbound records
|
|
98
|
+
|
|
99
|
+
There are three public event types, not a raw lifecycle or tool event stream:
|
|
100
|
+
|
|
101
|
+
| Type | Source and purpose |
|
|
102
|
+
| --- | --- |
|
|
103
|
+
| `turn.summary` | Edge hooks assemble one completed turn and send it to the events endpoint, or queue it. |
|
|
104
|
+
| `llm.call` | Agents export native OTLP directly. The backend/library normalizes supported completed request records into per-call usage. Edge does not proxy native OTLP. |
|
|
105
|
+
| `repo.snapshot` | Edge queues changed repository branch/commit metadata after a closed turn when Git capture is enabled. |
|
|
106
|
+
|
|
107
|
+
Generated records share `schemaVersion`, `id`, `timestamp`, `event.type`,
|
|
108
|
+
`event.providerEventType`, `agent.provider`, `agent.name`, session identifiers,
|
|
109
|
+
and optional `developer.installationId`. Absent fields are omitted. Provider
|
|
110
|
+
availability determines which identifiers and usage values exist.
|
|
111
|
+
|
|
112
|
+
### `turn.summary`
|
|
113
|
+
|
|
114
|
+
The hook-generated flat fields are `provider`, `surface`, `session_id`, `turn_id`,
|
|
115
|
+
`developer_id`, `repository`, `branch`, `commit`, `jira_ids`, `prompt_jira_ids`, `work_evidence`,
|
|
116
|
+
`parent_session_id`, `content_hashes`, `manifest_repository`, `files_changed`, `files_touched`, `files_read`, `external_files_touched`,
|
|
117
|
+
`external_files_read`, `prompt_evidence`, `prompt_text`, `session_name`, `session_title`, `tool_inputs`, `response_evidence`,
|
|
118
|
+
`tool_calls`, `tools_used`, `model`, `billing_mode`, `input_tokens`,
|
|
119
|
+
`cached_input_tokens`, `cache_creation_input_tokens`, `output_tokens`,
|
|
120
|
+
`usage_status`, `started_at`, and `ended_at`. The nested `session` contains `id`,
|
|
121
|
+
`providerId`, and optionally `turnId`.
|
|
122
|
+
|
|
123
|
+
`prompt_jira_ids` are the ticket keys (same syntax as the branch keys in `jira_ids`)
|
|
124
|
+
found in the session's opening prompt, extracted on the machine and sent on every
|
|
125
|
+
turn at every tier, with no consent step. Only the keys are sent, never the prompt
|
|
126
|
+
text. `capture.git: false` withholds them, as it does `jira_ids`.
|
|
127
|
+
|
|
128
|
+
A prompt is free text, so a string like `INV-204391`, `MRN-123456` or `UTF-8`
|
|
129
|
+
matches the key syntax too. The edge sends every candidate unfiltered, in order,
|
|
130
|
+
deduplicated and capped at 50; the platform matches them against the keys it knows
|
|
131
|
+
(branch names, connected trackers) and ignores the rest, so an unknown key is inert.
|
|
132
|
+
|
|
133
|
+
On the machine the keys are kept in `prompt-tickets.json` in the session's local
|
|
134
|
+
turn state (mode 0600): keys only, written once by the opening prompt, and an
|
|
135
|
+
empty list when `capture.git` is off for that prompt. Unlike the rest of the turn
|
|
136
|
+
state it is not deleted at SessionEnd, so a session resumed under the same id
|
|
137
|
+
keeps its keys instead of taking "continue" as its opening prompt. The memo keeps
|
|
138
|
+
every key the prompt named. The 24-hour
|
|
139
|
+
sweep deletes it, counted from SessionEnd, so a session resumed within a day of
|
|
140
|
+
ending keeps its keys.
|
|
141
|
+
|
|
142
|
+
No field carries response text. Evidence contains `length` and `sha256` of the
|
|
143
|
+
text the developer typed and the agent answered; it is not raw text, but hashes
|
|
144
|
+
and lengths can still reveal information about short or guessable text. The
|
|
145
|
+
prompt evidence hashes the prompt as the agent reported it.
|
|
146
|
+
|
|
147
|
+
- `prompt_text` (only under `promptText` with consent): the turn's first prompt,
|
|
148
|
+
with `<system-reminder>` blocks the agent's harness injected removed, secrets
|
|
149
|
+
scrubbed over the whole text, then cut at 4,000 characters.
|
|
150
|
+
- `session_name` and `session_title` (only under `sessionTitle` with consent):
|
|
151
|
+
the native session titles read from Claude Code's transcript, Codex's local
|
|
152
|
+
state database or Cursor's local conversation search index. `session_name` is
|
|
153
|
+
a separate person-set name where the agent keeps one; `session_title` is the
|
|
154
|
+
generated/display title. A generated
|
|
155
|
+
title is written by the agent from the conversation and can paraphrase the first
|
|
156
|
+
prompt. Secrets are scrubbed over each whole title, then it is cut to 200
|
|
157
|
+
characters without splitting an emoji. Both are sent on every turn, so a renamed
|
|
158
|
+
session's next turn carries the new name. The edge never derives a title from
|
|
159
|
+
the prompt itself. Gemini CLI and Antigravity expose no native title and send
|
|
160
|
+
neither. While the flag is on, Claude Code's last name and generated title seen
|
|
161
|
+
are kept, each on its own, in local turn state (mode 0600) for a turn whose
|
|
162
|
+
transcript tail no longer reaches one, and deleted with the session. Codex and
|
|
163
|
+
Cursor's SQLite indexes are opened read-only through Node's standard library;
|
|
164
|
+
Node versions before 22.12 omit those optional title fields.
|
|
165
|
+
- `tool_inputs` (only under `toolInput` with consent): per shell or connector (MCP)
|
|
166
|
+
call, `{tool, command}` or `{tool, server, name, arguments}` with the arguments as
|
|
167
|
+
JSON text; sensitive argument keys are redacted before that, every string is cut
|
|
168
|
+
at 2,000 characters after scrubbing, and at most 50 calls are sent per turn.
|
|
169
|
+
Tool output bodies are not sent on the summary; enabling tool flags does not add
|
|
170
|
+
a tool event stream.
|
|
171
|
+
- `external_files_touched` / `external_files_read` (under `files`, and only while
|
|
172
|
+
`git` is on, since that is what tells inside a checkout from outside): files outside
|
|
173
|
+
every checkout, home-relative (`~/Documents/a.xlsx`); a path outside the home
|
|
174
|
+
directory is sent as it is. `files_touched` and `files_read` are unchanged:
|
|
175
|
+
repo-relative, or a bare basename for a file in no checkout, as before.
|
|
176
|
+
|
|
177
|
+
Between the prompt hook and the turn's close, the scrubbed prompt text and tool
|
|
178
|
+
inputs sit in local turn state (mode 0600), and only while their flag is on; the
|
|
179
|
+
close consumes them, and a session's end or the 24-hour expiry deletes the rest.
|
|
180
|
+
|
|
181
|
+
The public summary type additionally supports backend-derived `llm_calls`,
|
|
182
|
+
`agent_usage`, `reasoning_output_tokens`, `total_tokens`, and `cost_usd`.
|
|
183
|
+
`agent_usage` holds agent/parent/type identifiers, call count, token counts and
|
|
184
|
+
cost. Hooks initially report usage as `pending` or transcript-based `provisional`;
|
|
185
|
+
backend aggregation may mark it `partial` or `complete`.
|
|
186
|
+
|
|
187
|
+
### OTLP and `llm.call`
|
|
188
|
+
|
|
189
|
+
Normalized calls carry `provider`, `surface`, `call_id`, `provider_request_id`,
|
|
190
|
+
`provider_session_id`, `provider_turn_id`, `session_id`, `turn_id`, `agent_id`,
|
|
191
|
+
`parent_agent_id`, `agent_type`, `model`, `billing_mode`, `status`, `correlation`,
|
|
192
|
+
`input_tokens`, `cached_input_tokens`, `cache_creation_input_tokens`,
|
|
193
|
+
`output_tokens`, `reasoning_output_tokens`, `total_tokens`, `cost_usd`,
|
|
194
|
+
`duration_ms`, `started_at`, `ended_at`, and optional joined `repository`, `branch`,
|
|
195
|
+
`commit`, `jira_ids`. Common envelope fields and optional Git/feature attribution
|
|
196
|
+
also apply. These are identity, usage, timing and development metadata; the
|
|
197
|
+
normalized call schema does not include prompt/response text or tool bodies.
|
|
198
|
+
|
|
199
|
+
Two request headers are added to the managed native exporters, and nothing else
|
|
200
|
+
on that route is ours: `Authorization`, carrying the one-hour device access token
|
|
201
|
+
(or, until it is exchanged, the install key), and
|
|
202
|
+
`x-agentwatch-installation`, carrying this installation's id. That id is a random
|
|
203
|
+
UUID generated locally on first use; it is not derived from a user, a machine
|
|
204
|
+
name or any account, and it identifies nothing without the backend that issued
|
|
205
|
+
the token. It is what lets measured per-call usage be traced back to a sender
|
|
206
|
+
when the turn summary that would have named a developer never arrives. Claude
|
|
207
|
+
Code receives both through its `otelHeadersHelper`, so neither is written to its
|
|
208
|
+
settings file; Codex and Gemini receive them in the config files described under
|
|
209
|
+
"Identity, local storage, and credentials". No developer identity is placed in a
|
|
210
|
+
native exporter header or resource attribute.
|
|
211
|
+
|
|
212
|
+
Native OTLP is a separate trust boundary: provider logs, resource attributes,
|
|
213
|
+
trace/span IDs, and optional traces/metrics reach the receiver **before** this
|
|
214
|
+
normalization. The Edge hook sanitizer and consent marker cannot filter that
|
|
215
|
+
traffic. AgentWatch does not claim the normalized schema describes every raw
|
|
216
|
+
OTLP attribute emitted by every provider version. Provider settings, ambient
|
|
217
|
+
environment, or custom exporters can change what is sent. Validate the actual
|
|
218
|
+
provider version and receiver filtering for a pilot; do not assume a backend
|
|
219
|
+
dropping a field means it never left the machine. Logs are requested by default,
|
|
220
|
+
but the content gate above can prevent their provider configuration; traces and
|
|
221
|
+
metrics default off. See [Claude telemetry](https://code.claude.com/docs/en/monitoring-usage)
|
|
222
|
+
and [Gemini telemetry](https://geminicli.com/docs/cli/telemetry/) for provider gates.
|
|
223
|
+
|
|
224
|
+
### `repo.snapshot` and Git metadata
|
|
225
|
+
|
|
226
|
+
Snapshots contain `provider`, `surface`, `repository`, optional `developer_id`,
|
|
227
|
+
`default_branch`, `captured_at`, and `branches`. Each branch has `name`,
|
|
228
|
+
`head_sha`, optional `last_commit_at`, and `commits`; each commit has `sha`,
|
|
229
|
+
`subject`, optional `authored_at`, and optional `files`. `files` lists the files
|
|
230
|
+
that commit changed as `{ path, status }`: `path` is repository-relative as git
|
|
231
|
+
names it, and `status` is git's name-status letter (`A`, `M`, `D` or `T`; a
|
|
232
|
+
rename is sent as its delete and its add). **Names only, never file contents.**
|
|
233
|
+
Files named like credentials (`.env`, `.env.*`, `*.pem`, `*.key`, `*.p12`, `*.pfx`,
|
|
234
|
+
`id_rsa`/`id_ed25519`/`id_ecdsa`, `credentials`, `credentials.*`, `.npmrc`, `.netrc`), paths
|
|
235
|
+
over 1,024 characters and paths holding control characters are left out. A
|
|
236
|
+
branch names at most 200 files and 16 KiB of path across its commits, newest
|
|
237
|
+
commit first; the rest are dropped without a marker. Only commits the branch has
|
|
238
|
+
that its trunk does not are listed, so trunk work never appears as a branch's
|
|
239
|
+
files. `files` is absent when the listing failed, ran out of the snapshot's time
|
|
240
|
+
budget or was cut short, on a commit the branch's cap had no room left for, and
|
|
241
|
+
on a commit whose every file was left out; an empty `files` means git listed none
|
|
242
|
+
(a merge or an empty commit). `capture.files: false`, global or set by the
|
|
243
|
+
repository, withholds `files` like every other path list: the listing does not
|
|
244
|
+
run, and a snapshot queued before the change loses `files` at delivery. Lists and subjects are bounded by the
|
|
245
|
+
snapshot implementation. Git capture includes commit subjects, which can contain
|
|
246
|
+
sensitive business information even though they are classified as metadata.
|
|
247
|
+
Set global `capture.git: false` to disable new snapshots; already-queued snapshots
|
|
248
|
+
are then discarded at delivery rather than sent.
|
|
249
|
+
|
|
250
|
+
Remote URL userinfo is removed before normalization. Normalization yields
|
|
251
|
+
`host/org/repo`, omitting scheme, query, fragment and `.git` suffix. A SHA-256 hash
|
|
252
|
+
of that normalized identity is available for Git attribution. **Repository names
|
|
253
|
+
are not hash-only:** current summaries and snapshots send the normalized
|
|
254
|
+
repository identity, or the checkout basename when no remote is available.
|
|
255
|
+
Branches, commit SHAs, ticket keys and file paths are metadata, not anonymous data.
|
|
256
|
+
Paths are made repository-relative where possible; paths outside the repository
|
|
257
|
+
can remain absolute, with the home prefix abbreviated to `~`.
|
|
258
|
+
|
|
259
|
+
Each turn reports the checkout its work changed, wherever the session started.
|
|
260
|
+
Agents often sit in one folder and work in a worktree beside it through shell
|
|
261
|
+
commands. A tool hook names candidate checkouts — the one it runs in, a file
|
|
262
|
+
tool's file's, those a shell command names or runs in, and Cursor's open
|
|
263
|
+
workspace folders — and records each candidate's
|
|
264
|
+
root with a fingerprint of it (HEAD, branch, and the dirty paths' status letters,
|
|
265
|
+
sizes and modification times). The turn's closing hook fingerprints them again and
|
|
266
|
+
reports, in order: the checkout the turn changed most; else the session's last
|
|
267
|
+
changed checkout; else the one it named most; else the folder it ended in, as
|
|
268
|
+
before; and, for a session started in a folder that is no checkout, a fifth
|
|
269
|
+
fallback, the checkout inherited from the process that started the agent (see
|
|
270
|
+
"Sessions that start outside a checkout" below). `work_evidence` says which of
|
|
271
|
+
the five (`changed`, `carried`, `referenced`, `cwd`, `inherited`). `files_changed` lists only the files this turn changed
|
|
272
|
+
there (at most 500), no longer the checkout's whole dirty tree, and
|
|
273
|
+
`files_touched` / `files_read` carry that checkout's paths only; paths in other
|
|
274
|
+
checkouts are dropped, while the calls still count. No new class of data is
|
|
275
|
+
collected: repository, branch, commit and paths were already sent for a session
|
|
276
|
+
started inside a repository.
|
|
277
|
+
|
|
278
|
+
Which checkouts may be reported is decided by the folder the session started in.
|
|
279
|
+
With project roots configured, only checkouts that the start folder's root
|
|
280
|
+
claims, or, when the start folder is in no root, checkouts that no root claims
|
|
281
|
+
either; without roots, only checkouts beneath the start folder. A checkout
|
|
282
|
+
another root claims is refused outright: it gets no record and is never
|
|
283
|
+
fingerprinted. Checkouts are judged by where they really are, not through symlinks.
|
|
284
|
+
Local turn state keeps the candidate roots, the fingerprints, the start folder
|
|
285
|
+
and the session's last changed checkout's root (`work-checkout.json`); none of it
|
|
286
|
+
is sent, and it goes with the session's other turn state. The prompt gate reads
|
|
287
|
+
that file to ask about that checkout's repository and branch instead of the
|
|
288
|
+
folder the agent sits in; the same two fields travel as before, and never for a
|
|
289
|
+
checkout the asking folder's root does not govern.
|
|
290
|
+
|
|
291
|
+
That file also keeps the branch the session changed there and the
|
|
292
|
+
repository-relative files its turns changed on it. When several sessions share a
|
|
293
|
+
checkout, a closing turn reads the other active sessions' files of this kind and
|
|
294
|
+
their open turns' edit-tool paths and the branch each open turn first saw a
|
|
295
|
+
checkout on, on the same machine, so that another session's
|
|
296
|
+
branch switch or files are not reported as this turn's. Nothing of it is sent, and
|
|
297
|
+
no git process is added for it.
|
|
298
|
+
|
|
299
|
+
What is reported about that repository follows *its* effective config, not the
|
|
300
|
+
start folder's: a `.agentwatch.json` committed inside it narrows the turn exactly
|
|
301
|
+
as it would a session started there — `capture.git: false` withholds the
|
|
302
|
+
repository, branch, commit and ticket keys, `capture.files: false` its paths.
|
|
303
|
+
And a repository that a project root of its own claims (see README, "Two
|
|
304
|
+
tenants on one machine") is never a candidate: the start folder decides which tenant a
|
|
305
|
+
session sends as (a session started in no root may send as the root that claims
|
|
306
|
+
an inherited checkout, below), so that repository's name, branch, commit and paths are
|
|
307
|
+
dropped rather than delivered to another tenant.
|
|
308
|
+
|
|
309
|
+
This resolution reads the file paths the agent's tools named, so it follows
|
|
310
|
+
`capture.files`: with `capture.files: false` no path is captured, and a session
|
|
311
|
+
started above its repositories then reports no repository or branch — as it did
|
|
312
|
+
before. A session started inside a repository is unaffected, since its
|
|
313
|
+
repository comes from the start folder rather than from any path.
|
|
314
|
+
|
|
315
|
+
### Sessions that start outside a checkout
|
|
316
|
+
|
|
317
|
+
An agent is sometimes started by another process, such as a review bot, an
|
|
318
|
+
orchestrator or an SDK app, in a folder with no Git context. The hook then
|
|
319
|
+
cannot name a repository from its own folder. These paths add local reads and
|
|
320
|
+
three summary fields (`parent_session_id`, `content_hashes`,
|
|
321
|
+
`manifest_repository`); they are designed to support a review of what leaves the
|
|
322
|
+
machine and are not a compliance claim. Except for recording the agent's own
|
|
323
|
+
process id and start time at every session's first hook, each applies only to a
|
|
324
|
+
turn whose own folder has no Git context.
|
|
325
|
+
|
|
326
|
+
**Inherited checkout (`work_evidence: inherited`, `parent_session_id`).** At
|
|
327
|
+
every session's first hook the edge reads, with `ps`, the agent's own process id
|
|
328
|
+
and start time (the hook's parent, or that parent's parent when a shell wraps the
|
|
329
|
+
hook) and records them locally, so a later session started by this agent can find
|
|
330
|
+
it. Only when the folder is no checkout and `capture.git` is on does it go
|
|
331
|
+
further: it lists every process's id and parent id on the machine (`ps -A`) in
|
|
332
|
+
memory, and keeps the chain of at most 8 processes above the agent: process id and
|
|
333
|
+
parent id only. A start time is asked for (one `ps -p`) only for an ancestor
|
|
334
|
+
already recorded as an agent, to rule out a reused process id. Working folders
|
|
335
|
+
(`lsof -b` on macOS, `/proc` on Linux) are read only when no live parent agent
|
|
336
|
+
session already supplies the checkout. All of it runs once per session under one 100 ms overall deadline, which also
|
|
337
|
+
stops any `ps` or `lsof` still running, and any
|
|
338
|
+
failure or timeout leaves the session as it was. The result is the nearest live
|
|
339
|
+
parent agent session's last work checkout; when no live parent agent session is
|
|
340
|
+
found at walk time, or the one found has no work checkout yet, the checkout the
|
|
341
|
+
nearest ancestor's folder lies in. A parent
|
|
342
|
+
found at walk time whose session has since ended still answers with the checkout
|
|
343
|
+
it had at walk time: the walk does not run again, and the ancestors' folders are
|
|
344
|
+
not looked up then. `inherited` is the last resort, behind every other
|
|
345
|
+
`work_evidence` value. Process ids, parent ids, start times and ancestor folders
|
|
346
|
+
never leave the machine and are not logged. They are kept in local turn state
|
|
347
|
+
(mode 0600): `agent-process.json` (the agent's pid and start time),
|
|
348
|
+
`inherited-checkout.json` (the resolved checkout root and the parent session id)
|
|
349
|
+
and `agent-pids/<pid>.json` (an index from a live agent's pid to its session).
|
|
350
|
+
They expire with the other turn state (24 hours). What is sent is what any
|
|
351
|
+
checkout report carries: `repository`, `branch`, `commit` and ticket keys,
|
|
352
|
+
labelled `inherited`, plus `parent_session_id`, the parent agent's own session
|
|
353
|
+
id. `capture.git: false` withholds all of it, and the ancestor walk does not
|
|
354
|
+
run.
|
|
355
|
+
|
|
356
|
+
**Declared parent (`AGENTWATCH_PARENT_SESSION`).** A launcher that starts an
|
|
357
|
+
agent on another agent's behalf (a spinoff in a new terminal tab, a review bot,
|
|
358
|
+
your own orchestrator) can name the launching session by setting
|
|
359
|
+
`AGENTWATCH_PARENT_SESSION=<parent session id>` in the child agent's
|
|
360
|
+
environment. Hooks inherit it, and every turn summary of the child then carries
|
|
361
|
+
it as `parent_session_id`, whatever its `work_evidence`, ahead of any parent the
|
|
362
|
+
ancestor walk finds. A value that is not a plain session id (letters, digits,
|
|
363
|
+
`.`, `_`, `:`, `-`, at most 200 characters) or that equals the child's own
|
|
364
|
+
session id is ignored. Nothing is stored locally for it. `capture.git: false`
|
|
365
|
+
withholds it.
|
|
366
|
+
|
|
367
|
+
**Tenant.** With project roots configured, a session whose start folder is in no
|
|
368
|
+
root sends an inherited checkout only if a root claims that checkout, and then
|
|
369
|
+
under that root's token, destination and developer. A checkout no root claims is
|
|
370
|
+
not sent, and is never sent as the machine default. Without roots there is one
|
|
371
|
+
tenant and nothing is re-routed.
|
|
372
|
+
|
|
373
|
+
**File content ids (`content_hashes`).** Only with both `capture.files` and
|
|
374
|
+
`capture.git` on, and only when the folder has no Git context and the closing hook's own folder
|
|
375
|
+
reported no repository, the edge reads up to 20 files that the agent's own tools
|
|
376
|
+
named (files it edited first, then files it read), within a 100 ms budget past which
|
|
377
|
+
the remaining files are skipped, in memory, to compute Git's
|
|
378
|
+
blob id: the SHA-1 Git itself assigns the content (`git hash-object`). A file over
|
|
379
|
+
1 MB, a file whose name is exactly `.env` or `.env.<anything>`, `credentials` or
|
|
380
|
+
`credentials.<anything>`, `id_rsa`, `id_ed25519`, `id_ecdsa`, `.npmrc` or
|
|
381
|
+
`.netrc`, or ends in `.pem`, `.key`, `.p12` or `.pfx` (matched case-insensitively,
|
|
382
|
+
on both the named path and its real target; other names such as `.envrc` or
|
|
383
|
+
`credentials-prod.json` are not skipped), and a file whose real path lies
|
|
384
|
+
outside the session folder, symlinks included, is skipped. The summary carries up
|
|
385
|
+
to 20 `{path, blob_sha}` pairs, the path relative to the session folder. This feature adds no file content and no path from outside the session folder: a file whose real path lies outside it is skipped, and only its name can appear, under `external_files_touched` or `external_files_read` when `files` is on, as described above. With debug logging on, a failed read can log that file's path on this machine. A blob id is an object id of the same kind as the commit SHAs already
|
|
386
|
+
sent, but a guessable file's id can still be confirmed by someone who has that
|
|
387
|
+
file.
|
|
388
|
+
|
|
389
|
+
**Manifest repository (`manifest_repository`).** Under the same conditions and within the same 100 ms budget (past it no address is sent), the
|
|
390
|
+
edge reads the nearest `package.json`, `composer.json`, `go.mod`, `Cargo.toml` or
|
|
391
|
+
`pyproject.toml` at or above the folder (stopping before the home directory, or, for a folder outside it, at the filesystem root), in
|
|
392
|
+
memory, and keeps only one field from it: `repository` in `package.json`
|
|
393
|
+
(a string, or its `url`), `support.source` in `composer.json`, the module path in
|
|
394
|
+
`go.mod` (a host with a dot, then owner and repository), `package.repository` in
|
|
395
|
+
`Cargo.toml`, and in `pyproject.toml` a `repository`, `source`, `source code`,
|
|
396
|
+
`sourcecode`, `github` or `code` entry under `project.urls`, else `repository` under
|
|
397
|
+
`tool.poetry`. The address is cleaned like
|
|
398
|
+
a Git remote (credentials and scheme removed, `.git` suffix dropped, form
|
|
399
|
+
`host/owner/repo`) and cut at 500 characters, and is sent as `manifest_repository`. The rest of the manifest is discarded.
|
|
400
|
+
|
|
401
|
+
These reads happen locally and in memory, next to the existing rule that tool
|
|
402
|
+
input and output bodies are not collected by default: a named file or manifest is
|
|
403
|
+
read whole, but only the fields above are kept. No new class of outbound data is
|
|
404
|
+
added, because the fields are Git and operational metadata. On the receiving side, hashes and
|
|
405
|
+
manifest addresses are matched only against that tenant's own repositories and
|
|
406
|
+
are not stored in the database or logged; only the resolution result and its source are kept. Like every
|
|
407
|
+
summary field they do travel in the Pub/Sub message, and an event that is dead-lettered keeps
|
|
408
|
+
them, with the rest of the message, in the dead-letter topic until Pub/Sub expires the message.
|
|
409
|
+
|
|
410
|
+
## Identity, local storage, and credentials
|
|
411
|
+
|
|
412
|
+
Developer identity is the configured `developerEmail`, falling back to Git email
|
|
413
|
+
resolution. Setup requires an identity. The email is sent as `developer_id` and
|
|
414
|
+
used for enforcement. It is not currently pseudonymized with a tenant HMAC.
|
|
415
|
+
An installation UUID also identifies the installation. Native providers may send
|
|
416
|
+
their own session/account/resource identifiers independently.
|
|
417
|
+
|
|
418
|
+
Global configuration is stored in `~/.agentwatch/config.json` (0600). The
|
|
419
|
+
organization install key written by setup (from `--token`, `$AGENTWATCH_TOKEN`
|
|
420
|
+
or the prompt) is exchanged once through `POST /v1/devices/enroll` for a device
|
|
421
|
+
credential of this machine's own, and the config records `device: { id, store }`
|
|
422
|
+
beside the key. The key stays in the file only because Codex and Gemini still
|
|
423
|
+
present it (moving them to short-lived tokens, and the key out of the file, is
|
|
424
|
+
AWT-357); the Claude hooks and header helper send the device's access token
|
|
425
|
+
and never the key once the device is recorded. The device reference is an id
|
|
426
|
+
derived from the install key's digest and the name of the store that holds the
|
|
427
|
+
secret. The device secret lives in the macOS Keychain (service
|
|
428
|
+
`agentwatch-device`), the Secret Service keyring through `secret-tool` (only
|
|
429
|
+
with a D-Bus session), or a Windows DPAPI blob under
|
|
430
|
+
`~/.agentwatch/credentials/`; with none of those it is a 0600 file in the same
|
|
431
|
+
directory, reported by `status` and `doctor`. A failed exchange keeps the install
|
|
432
|
+
key, which goes on working, and is retried an hour later. The one-hour access
|
|
433
|
+
token the backend accepts is cached in `identity/<id>/access-token.json` (0600)
|
|
434
|
+
in the data root and refreshed through `POST /v1/devices/token` when under a
|
|
435
|
+
quarter of its life remains; the secret is read from the keychain only then.
|
|
436
|
+
On Windows a hook never starts PowerShell itself: setup makes the exchange,
|
|
437
|
+
and a DPAPI-held device's due refresh runs in one detached
|
|
438
|
+
`agentwatch refresh-credential` (at most one every five minutes), while that
|
|
439
|
+
hook sends with the token it has or queues. A refresh or exchange in a hook
|
|
440
|
+
spends at most half the delivery budget and is skipped while the backend
|
|
441
|
+
cooldown stands. Only the refresh route's own refusals (device unknown,
|
|
442
|
+
revoked or secret expired) are permanent; anything else is retried after the
|
|
443
|
+
cooldown. A refused refresh stops sends for that identity,
|
|
444
|
+
queues every record, is said once on stderr and stays visible in `status` and
|
|
445
|
+
`doctor` until the machine is enrolled again: by itself when the secret only
|
|
446
|
+
expired (hourly backoff), and only by `setup --token <install key>` when the
|
|
447
|
+
device was revoked or is unknown, so a hook never undoes a revocation. `uninstall` (all agents)
|
|
448
|
+
first revokes the device on the platform (`POST /v1/devices/revoke`, the
|
|
449
|
+
secret in the body), then removes the device secret, the cached token and the
|
|
450
|
+
reference. When the platform cannot be reached or does not confirm, uninstall
|
|
451
|
+
still finishes locally and says the credential is still active; an
|
|
452
|
+
administrator revokes the machine in Settings → Install. Uninstall also leaves
|
|
453
|
+
`uninstalled.json` beside the config, naming the machine and each root: until
|
|
454
|
+
`setup` runs again for one of them, nothing exchanges or sends the install key
|
|
455
|
+
kept in the config for it, and `status` and `doctor` say it is uninstalled. Ownership records are in
|
|
456
|
+
`~/.agentwatch/install-state.json`. `AGENTWATCH_CONFIG_DIR` overrides this root.
|
|
457
|
+
The data root is `$XDG_DATA_HOME/agentwatch`, falling back to
|
|
458
|
+
`~/.local/share/agentwatch`. On Windows, when present, `%LOCALAPPDATA%/agentwatch`
|
|
459
|
+
is used; Windows deployment is not verified. `AGENTWATCH_DATA_DIR` overrides it.
|
|
460
|
+
|
|
461
|
+
The data root contains `queue/`, `turns/`, `backups/`, `locks/`, `snapshots/`,
|
|
462
|
+
`checkouts/`, delivery/cooldown/enforcement state, and `disabled.json` when off.
|
|
463
|
+
The queue contains sanitized product records and their destination, attempts,
|
|
464
|
+
and retry timestamps. Defaults are 2,000 events, 20 attempts, and 7 days.
|
|
465
|
+
Expiration is processed during activity, not by a daemon or scheduled erasure.
|
|
466
|
+
Capacity pressure removes oldest entries. Turn state has a 24-hour stale-state
|
|
467
|
+
cleanup bound, and queued records a `maxEventAgeDays` bound (7 by default). Both
|
|
468
|
+
sweeps are activity-driven and run at most hourly. On an active installation,
|
|
469
|
+
removal happens at the next eligible sweep after expiration; an idle machine
|
|
470
|
+
retains the files until activity resumes. Backups and other local caches have no
|
|
471
|
+
guaranteed automatic deletion deadline. The package does not delete provider-owned
|
|
472
|
+
transcripts; it can read them locally for usage attribution.
|
|
473
|
+
|
|
474
|
+
Config, queues, turn state and the off marker use POSIX mode 0600.
|
|
475
|
+
|
|
476
|
+
**Codex and Gemini hold a static bearer token in their own configuration file
|
|
477
|
+
(still the install key setup wrote; moving them to short-lived tokens is
|
|
478
|
+
tracked separately),
|
|
479
|
+
and this is a property of those agents rather than a choice made here.** Neither
|
|
480
|
+
CLI has a mechanism for fetching a credential at request time, so the only way
|
|
481
|
+
to authenticate their native OTLP exporters is to write the bearer into the file
|
|
482
|
+
they read at startup: `~/.codex/config.toml` for Codex, and
|
|
483
|
+
`OTEL_EXPORTER_OTLP_HEADERS` inside `~/.gemini/settings.json` for Gemini. Claude
|
|
484
|
+
Code does have such a mechanism — `otelHeadersHelper`, which calls
|
|
485
|
+
`agentwatch otel-headers` at runtime — so no Claude configuration file ever
|
|
486
|
+
contains a token. Cursor and Antigravity have no managed native exporter, so the
|
|
487
|
+
question does not arise for them.
|
|
488
|
+
|
|
489
|
+
Because those two files then contain a credential, AgentWatch sets them to 0600
|
|
490
|
+
when — and only when — the block it writes actually carries the token. The files
|
|
491
|
+
belong to those agents, not to AgentWatch, so the permission bits each one had
|
|
492
|
+
beforehand are recorded in the install state and restored by `uninstall`: a file
|
|
493
|
+
that was 0644 before does not stay 0600 after the token is gone. A file that was
|
|
494
|
+
already private stays private, and nothing is tightened when no credential is
|
|
495
|
+
written. Backups preserve source permissions and can contain
|
|
496
|
+
credentials, including historical copies. Other directories/files use existing
|
|
497
|
+
permissions or process defaults; POSIX modes are not a verified Windows ACL
|
|
498
|
+
guarantee. Local data is not encrypted by this package. Passing a token on the
|
|
499
|
+
setup command line can expose it through shell history/process inspection.
|
|
500
|
+
|
|
501
|
+
## Endpoints and failure behavior
|
|
502
|
+
|
|
503
|
+
The operator configures the backend; there is no hard-coded hosted destination.
|
|
504
|
+
Defaults derived from that endpoint are `POST /v1/events`, native OTLP base
|
|
505
|
+
`/v1/otlp` with `/v1/logs`, `/v1/traces`, `/v1/metrics` signal suffixes, and
|
|
506
|
+
`GET /v1/enforcement/decision`. Global `eventsUrl`, `otlpUrl`, and
|
|
507
|
+
`enforcementUrl` may override those routes. Authentication uses a bearer token
|
|
508
|
+
when configured. Every URL in the configuration is validated on every *read* of
|
|
509
|
+
the file, not only when `setup` writes it: `https://` anywhere, and `http://`
|
|
510
|
+
only to `localhost`, `127.0.0.1` or `::1`. A configuration naming any other
|
|
511
|
+
scheme — or plain `http://` to a remote host — refuses that URL and `doctor`
|
|
512
|
+
reports it. The remaining valid configuration and identity stay loaded; a
|
|
513
|
+
refused root destination does not inherit machine telemetry routes.
|
|
514
|
+
Enforcement sends developer and checkout attribution, and the session's
|
|
515
|
+
model when the agent named one, not prompt/tool bodies.
|
|
516
|
+
Doctor probes connectivity with an empty events batch carrying the same
|
|
517
|
+
credentials a real delivery uses, so its verdict describes the configured
|
|
518
|
+
install: it distinguishes a backend that accepted the credential, one that
|
|
519
|
+
rejected it (a failure, with a non-zero exit code), one that is unreachable, and
|
|
520
|
+
an install with no backend configured yet. It always performs that probe, even
|
|
521
|
+
while sends are suspended — the diagnostic is a direct question to the backend
|
|
522
|
+
and is never answered from local state. Status can drain the queue. Both stop
|
|
523
|
+
network activity while disabled.
|
|
524
|
+
|
|
525
|
+
The one request that goes to a host other than the backend is the update check:
|
|
526
|
+
at most once a day a session-start hook starts a detached `agentwatch update
|
|
527
|
+
--check`, which sends a plain `GET https://registry.npmjs.org/@agent-watch-ai/edge/latest`
|
|
528
|
+
with no headers or data of ours, and caches the answer in
|
|
529
|
+
`<data dir>/update-check.json`. The hook itself only reads that cache. Global
|
|
530
|
+
`"updateNotices": false` stops both the request and the notice.
|
|
531
|
+
|
|
532
|
+
Hook errors return the provider's passive response/exit zero. Unknown inputs,
|
|
533
|
+
missing configuration, parser failures and unexpected exceptions must not crash
|
|
534
|
+
the coding agent. One exit is not zero: when a file read under the 100 ms budget
|
|
535
|
+
(content ids or the manifest) is still hung, as on a stuck network mount, after
|
|
536
|
+
the turn is queued and the answer is written, the hook ends itself with SIGKILL,
|
|
537
|
+
because Node cannot exit while that read is pending. The agent sees a failed
|
|
538
|
+
hook, as it would at its own hook timeout, only sooner. A delivery pass shares a default 1,500 ms monotonic network budget across
|
|
539
|
+
its direct send, backlog batch and isolation probes. Each request uses the
|
|
540
|
+
remaining budget. Exhaustion defers unsent records without consuming their retry
|
|
541
|
+
attempts or marking the backend unavailable. Filesystem work, transcript settling,
|
|
542
|
+
enforcement and snapshots have separate costs; this is not a hard deadline for
|
|
543
|
+
the entire hook. Failed records are queued before diagnostic writes, with bounded
|
|
544
|
+
retries and eventual loss reported by status.
|
|
545
|
+
|
|
546
|
+
The gateway reports partial publish failures as HTTP 503, so the entire batch
|
|
547
|
+
is retried with its original IDs. A 2xx acknowledges the batch; its `rejected`
|
|
548
|
+
counter records permanent per-event rejection without a retry or cooldown.
|
|
549
|
+
Receivers must handle replay safely: the gateway's dedupe cache lasts 10 minutes,
|
|
550
|
+
while edge backoff can reach 6 hours. Later retries require durable idempotency
|
|
551
|
+
in downstream storage; the gateway cache alone is insufficient. A thrown transport
|
|
552
|
+
error also queues the records. Unread response bodies are cancelled and stream
|
|
553
|
+
readers are released.
|
|
554
|
+
|
|
555
|
+
A backend that answers 401 or 403 is refusing the credential, not failing
|
|
556
|
+
transiently. The records stay queued — a product record is never discarded on a
|
|
557
|
+
failed send, and that does not change — but automatic sends for that
|
|
558
|
+
(destination, credential) pair are suspended rather than re-presenting a
|
|
559
|
+
rejected bearer on every hook for the whole retention window, which reads to a
|
|
560
|
+
backend's security monitoring as low-rate credential stuffing and to the
|
|
561
|
+
operator as nothing at all. No queued entry spends a retry attempt while the
|
|
562
|
+
refusal stands, including when it first occurs during an isolation probe.
|
|
563
|
+
Normal age and size retention limits still apply. `status` reports the refusing status, when the refusals started and how
|
|
564
|
+
many records are held. The suspension is lifted by configuring a different
|
|
565
|
+
credential or endpoint, or by `doctor` proving the credential good again; it
|
|
566
|
+
never expires on a timer. This is
|
|
567
|
+
not a guarantee of lossless delivery. Native exporter retry behavior is owned by
|
|
568
|
+
the provider, not the Edge queue. Sanitization is unconditional for Edge records;
|
|
569
|
+
it redacts known credential patterns/sensitive keys and bounds string/depth sizes.
|
|
570
|
+
Pattern matching cannot guarantee discovery of every possible secret.
|
|
571
|
+
|
|
572
|
+
Enforcement is fail-open on unexpected errors, timeouts, invalid responses and
|
|
573
|
+
unreachable services. A refused root base has no usable decision route; doctor
|
|
574
|
+
reports that budget caps are not enforced, with a failure and a repair instruction.
|
|
575
|
+
It does not send that root's bearer to machine enforcement as a fallback. A supported hook blocks only on an explicit backend block
|
|
576
|
+
decision. Defaults are a 300 ms request timeout and 60-second local decision
|
|
577
|
+
cache. Antigravity has no verified blocking response. This is not a local signed
|
|
578
|
+
enforcement policy or tamper-resistant control.
|
|
579
|
+
|
|
580
|
+
The request may also carry the model the session is on, so a budget can be set
|
|
581
|
+
on one model. Codex, Cursor, Gemini and Antigravity all name their
|
|
582
|
+
model on every hook they send, so for those the payload the gate already holds
|
|
583
|
+
names it. Claude Code names it only when a session starts, so
|
|
584
|
+
that one event writes it to `session.json` in that session's own `turns/`
|
|
585
|
+
directory (mode 0600, beside that session's turn records) to be read back at the
|
|
586
|
+
gate.
|
|
587
|
+
That file lives as long as the session does: it is deleted with the session's
|
|
588
|
+
state at SessionEnd, and by the 24-hour sweep for a session that crashed without
|
|
589
|
+
one. The model is stated exactly as reported usage spells it, and it is part of
|
|
590
|
+
the local decision cache key — an answer about one model is never reused for a
|
|
591
|
+
prompt on another. A collector that never learned a model states none and is
|
|
592
|
+
answered as it is today.
|
|
593
|
+
|
|
594
|
+
**The gate makes a network request.** Before a turn starts, the pre-prompt hook
|
|
595
|
+
reads a local decision cache and, on a miss, asks the platform — one bounded
|
|
596
|
+
request, 300 ms ceiling, every failure allowing the turn. Stating the model adds
|
|
597
|
+
one read of a small local file to that, and nothing else: no subprocess, no
|
|
598
|
+
second request, and a file that cannot be read means no model is stated rather
|
|
599
|
+
than a gate that waits. Two consequences are worth stating rather than leaving
|
|
600
|
+
to be discovered. A platform outage does not stop developers; it un-enforces
|
|
601
|
+
every budget for as long as it lasts, which at the default cache TTL means
|
|
602
|
+
decisions go unmade for up to a minute past recovery. And the cache is not
|
|
603
|
+
always a saving: an organization with a feature-scoped policy receives
|
|
604
|
+
`cache_ttl_ms: 0` on every answer, because a
|
|
605
|
+
reuse key cannot distinguish one checkout from another, so those turns each pay
|
|
606
|
+
a request. A gate that evaluates a locally held policy without a network call is
|
|
607
|
+
planned; it requires the platform to send a policy rather than a verdict, and it
|
|
608
|
+
is not what ships today.
|
|
609
|
+
|
|
610
|
+
## Off, uninstall, and provider limitations
|
|
611
|
+
|
|
612
|
+
`agentwatch off` writes a local marker before changing native configuration.
|
|
613
|
+
Disabled hooks return before stdin processing, do not enforce, send, or queue
|
|
614
|
+
events; they still write the provider's payload-less passive response, because a
|
|
615
|
+
provider whose protocol expects a decision would otherwise stall. `otel-headers`
|
|
616
|
+
returns no authorization header. Configuration and queued data are retained.
|
|
617
|
+
Managed native exporter settings are removed using the same ownership and backup
|
|
618
|
+
mechanisms as uninstall. Failures are reported, with the marker retained, and
|
|
619
|
+
running `agentwatch off` again re-runs the removal for the recorded providers. **Restart/close existing agents:** static headers, exporters,
|
|
620
|
+
and pending native batches may remain in memory until then. Off cannot recall
|
|
621
|
+
requests already in flight or control independently configured exporters.
|
|
622
|
+
|
|
623
|
+
`agentwatch on` restores previously suspended managed exporters and removes the
|
|
624
|
+
marker only on success. It does not add hooks or undo an intervening uninstall.
|
|
625
|
+
Foreign exporter conflicts require repair and a retry. `uninstall` removes owned
|
|
626
|
+
hooks/settings and keeps local state; `uninstall --purge` also removes AgentWatch
|
|
627
|
+
configuration and data, including queued records and backups. Unrelated user
|
|
628
|
+
hooks/settings are preserved. AgentWatch does not remove the globally installed
|
|
629
|
+
npm package itself.
|
|
630
|
+
|
|
631
|
+
Codex and Gemini static token storage is a current limitation, not an encrypted
|
|
632
|
+
credential-store integration; see *Identity, local storage, and credentials*
|
|
633
|
+
above for why those two agents differ from Claude Code, and for what `uninstall`
|
|
634
|
+
restores. Cursor has no native usage exporter/readable usage;
|
|
635
|
+
its CLI currently exposes only shell hooks, while IDE hooks cover more lifecycle
|
|
636
|
+
events. Antigravity has neither native token telemetry nor readable transcript
|
|
637
|
+
usage. Their summaries can remain `pending` without cost; no usage is fabricated.
|
|
638
|
+
|
|
639
|
+
A local administrator—and ordinarily the owning user—can remove or modify hooks,
|
|
640
|
+
configuration, credentials, and the off marker. Every line of code that runs on
|
|
641
|
+
the machine is in this MIT-licensed repository; the closed half is the backend
|
|
642
|
+
that receives the records. No signing, notarization, penetration-test completion,
|
|
643
|
+
or SOC 2 attestation is claimed. MDM templates and a per-agent statement of what
|
|
644
|
+
an administrator can and cannot lock are in
|
|
645
|
+
[examples/mdm](https://github.com/agent-watch-ai/agent-watch-edge/tree/main/examples/mdm); Claude Code is currently the only
|
|
646
|
+
agent with a managed policy file, and Codex requires one manual per-machine
|
|
647
|
+
approval (`/hooks`) that no script can perform.
|
|
648
|
+
See [deferred enterprise work](ENTERPRISE_DEPLOYMENT.md).
|