@agent-watch-ai/edge 0.3.1 → 0.5.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.
Files changed (123) hide show
  1. package/CHANGELOG.md +75 -0
  2. package/README.md +10 -6
  3. package/SECURITY.md +7 -4
  4. package/dist/cli/constants/cli.constants.d.ts +2 -0
  5. package/dist/cli/constants/cli.constants.js +3 -1
  6. package/dist/cli/doctor.js +13 -2
  7. package/dist/cli/setup.js +138 -29
  8. package/dist/cli/toggle.js +5 -1
  9. package/dist/cli/types/cli.types.d.ts +6 -0
  10. package/dist/cli/uninstall.js +1 -1
  11. package/dist/cli.js +14 -3
  12. package/dist/config/config-store.d.ts +1 -1
  13. package/dist/config/config-store.js +2 -2
  14. package/dist/config/constants/config.constants.d.ts +4 -1
  15. package/dist/config/constants/config.constants.js +7 -2
  16. package/dist/config/repo-config.js +1 -1
  17. package/dist/config/schemas/config.schema.d.ts +113 -767
  18. package/dist/config/schemas/config.schema.js +17 -8
  19. package/dist/credentials/constants/credentials.constants.d.ts +8 -0
  20. package/dist/credentials/constants/credentials.constants.js +9 -1
  21. package/dist/credentials/credential-status.js +8 -4
  22. package/dist/credentials/credentials.d.ts +16 -2
  23. package/dist/credentials/credentials.js +30 -5
  24. package/dist/credentials/device-api.d.ts +10 -1
  25. package/dist/credentials/device-api.js +12 -1
  26. package/dist/credentials/identity.d.ts +12 -1
  27. package/dist/credentials/identity.js +12 -1
  28. package/dist/credentials/migration.d.ts +1 -1
  29. package/dist/credentials/migration.js +1 -1
  30. package/dist/credentials/schemas/device-api.schema.d.ts +4 -51
  31. package/dist/credentials/schemas/device-state.schema.d.ts +3 -38
  32. package/dist/credentials/sign-in.d.ts +14 -1
  33. package/dist/credentials/sign-in.js +24 -5
  34. package/dist/credentials/types/credentials.types.d.ts +12 -1
  35. package/dist/enforcement/decision-client.js +2 -1
  36. package/dist/enforcement/enforcement.js +7 -5
  37. package/dist/enforcement/types/enforcement.types.d.ts +2 -2
  38. package/dist/git/code-state.d.ts +33 -0
  39. package/dist/git/code-state.js +44 -0
  40. package/dist/git/constants/git.constants.d.ts +6 -0
  41. package/dist/git/constants/git.constants.js +6 -0
  42. package/dist/git/index.d.ts +2 -1
  43. package/dist/git/index.js +1 -0
  44. package/dist/git/types/git.types.d.ts +6 -0
  45. package/dist/pipeline/constants/pipeline.constants.d.ts +3 -0
  46. package/dist/pipeline/constants/pipeline.constants.js +3 -0
  47. package/dist/pipeline/hook-pipeline.js +56 -7
  48. package/dist/privacy/command-fingerprint.d.ts +42 -0
  49. package/dist/privacy/command-fingerprint.js +249 -0
  50. package/dist/privacy/constants/command-fingerprint.constants.d.ts +34 -0
  51. package/dist/privacy/constants/command-fingerprint.constants.js +38 -0
  52. package/dist/privacy/index.d.ts +3 -1
  53. package/dist/privacy/index.js +2 -0
  54. package/dist/privacy/product-capture.js +20 -0
  55. package/dist/privacy/types/privacy.types.d.ts +7 -0
  56. package/dist/providers/antigravity/antigravity.adapter.js +3 -0
  57. package/dist/providers/antigravity/schemas/antigravity.schema.d.ts +18 -492
  58. package/dist/providers/claude/claude.adapter.js +12 -1
  59. package/dist/providers/claude/constants/claude.constants.d.ts +6 -0
  60. package/dist/providers/claude/constants/claude.constants.js +6 -0
  61. package/dist/providers/claude/schemas/claude.schema.d.ts +1 -43
  62. package/dist/providers/codex/codex.adapter.js +14 -0
  63. package/dist/providers/codex/codex.otel.d.ts +12 -1
  64. package/dist/providers/codex/codex.otel.js +61 -11
  65. package/dist/providers/codex/constants/codex.otel.constants.d.ts +5 -0
  66. package/dist/providers/codex/constants/codex.otel.constants.js +5 -0
  67. package/dist/providers/codex/schemas/codex.schema.d.ts +1 -41
  68. package/dist/providers/constants/provider.constants.d.ts +8 -0
  69. package/dist/providers/constants/provider.constants.js +8 -0
  70. package/dist/providers/cursor/constants/cursor.constants.d.ts +2 -0
  71. package/dist/providers/cursor/constants/cursor.constants.js +2 -0
  72. package/dist/providers/cursor/cursor.adapter.js +84 -5
  73. package/dist/providers/cursor/schemas/cursor.schema.d.ts +5 -85
  74. package/dist/providers/gemini/constants/gemini.constants.d.ts +2 -0
  75. package/dist/providers/gemini/constants/gemini.constants.js +2 -0
  76. package/dist/providers/gemini/constants/gemini.otel.constants.d.ts +16 -1
  77. package/dist/providers/gemini/constants/gemini.otel.constants.js +16 -1
  78. package/dist/providers/gemini/gemini.detect.d.ts +11 -0
  79. package/dist/providers/gemini/gemini.detect.js +14 -1
  80. package/dist/providers/gemini/gemini.hooks.d.ts +3 -3
  81. package/dist/providers/gemini/gemini.hooks.js +5 -5
  82. package/dist/providers/gemini/gemini.otel.d.ts +14 -4
  83. package/dist/providers/gemini/gemini.otel.js +418 -107
  84. package/dist/providers/gemini/schemas/gemini.schema.d.ts +1 -49
  85. package/dist/providers/shared/bearer-rewrite.d.ts +19 -0
  86. package/dist/providers/shared/bearer-rewrite.js +46 -0
  87. package/dist/providers/shared/constants/tooling.constants.d.ts +6 -0
  88. package/dist/providers/shared/constants/tooling.constants.js +6 -0
  89. package/dist/providers/shared/event-builder.d.ts +17 -2
  90. package/dist/providers/shared/event-builder.js +43 -3
  91. package/dist/providers/shared/install-record.d.ts +2 -0
  92. package/dist/providers/shared/install-record.js +3 -2
  93. package/dist/providers/shared/tooling.d.ts +35 -0
  94. package/dist/providers/shared/tooling.js +61 -1
  95. package/dist/providers/shared/types/adapter.types.d.ts +18 -0
  96. package/dist/providers/types/provider.types.d.ts +24 -0
  97. package/dist/storage/atomic-file.d.ts +14 -0
  98. package/dist/storage/atomic-file.js +19 -0
  99. package/dist/storage/constants/storage.constants.d.ts +2 -0
  100. package/dist/storage/constants/storage.constants.js +2 -0
  101. package/dist/storage/schemas/storage.schema.d.ts +11 -175
  102. package/dist/storage/schemas/storage.schema.js +7 -1
  103. package/dist/transport/schemas/queue.schema.d.ts +1 -16
  104. package/dist/transport/schemas/queue.schema.js +1 -1
  105. package/dist/turns/constants/turns.constants.d.ts +17 -0
  106. package/dist/turns/constants/turns.constants.js +17 -0
  107. package/dist/turns/index.d.ts +3 -2
  108. package/dist/turns/index.js +1 -0
  109. package/dist/turns/tool-events.d.ts +15 -0
  110. package/dist/turns/tool-events.js +59 -0
  111. package/dist/turns/turn-state.js +2 -2
  112. package/dist/turns/turn-summary.d.ts +1 -1
  113. package/dist/turns/turn-summary.js +1 -0
  114. package/dist/turns/turn-tracker.js +138 -7
  115. package/dist/turns/types/turn-state.types.d.ts +28 -1
  116. package/dist/turns/types/turn-summary.types.d.ts +30 -0
  117. package/dist/turns/types/turn-tracker.types.d.ts +10 -0
  118. package/dist/turns/work-checkout.d.ts +5 -3
  119. package/dist/turns/work-checkout.js +46 -12
  120. package/docs/AUDIT_PROMPT.md +11 -0
  121. package/docs/DATA_HANDLING.md +69 -14
  122. package/docs/ENTERPRISE_DEPLOYMENT.md +21 -5
  123. package/package.json +9 -8
@@ -5,7 +5,9 @@ import { asRecord, compact } from '../core/object.js';
5
5
  import { detectBillingMode } from '../billing/billing-mode.js';
6
6
  import { sha256Hex } from '../events/event-id.js';
7
7
  import { REPOSITORY_PATH_METADATA_KEY } from '../events/constants/enrich.constants.js';
8
+ import { codeStateAt } from '../git/code-state.js';
8
9
  import { developerDisplayName, developerIdentity } from '../git/git-context.js';
10
+ import { CHECK_MIN_DURATION_MS } from '../privacy/constants/command-fingerprint.constants.js';
9
11
  import { sanitizeValue } from '../privacy/sanitizer.js';
10
12
  import { acquireLock } from '../storage/lock.js';
11
13
  import { inheritedRootConfig } from '../config/root-config.js';
@@ -16,9 +18,10 @@ import { readCodexTurnUsage } from './codex-transcript.js';
16
18
  import { readCursorTurnUsage } from './cursor-transcript.js';
17
19
  import { readGeminiTurnUsage } from './gemini-transcript.js';
18
20
  import { readCodexSessionTitles, readCursorSessionTitles } from './native-session-titles.js';
19
- import { CLAUDE_ENTRYPOINT_VAR, PARENT_SESSION_VAR, RE_PARENT_SESSION_ID, DEFAULT_SURFACE, EXTERNAL_PATH_KEY, FILE_PATH_KEY, IDE_SURFACE, IDE_SURFACE_PROVIDERS, LOCK_KEY_HASH_LENGTH, MAX_PROMPT_TEXT_LENGTH, MAX_TOOL_INPUT_LENGTH, PROMPT_EVIDENCE_KEY, PROMPT_JIRA_IDS_KEY, PROMPT_TEXT_KEY, RESPONSE_EVIDENCE_KEY, TOOL_COMPLETION_TYPES, EXEC_SURFACE, TRANSCRIPT_PATH_KEY, TURN_STATE_TTL_MS, USAGE_LOCK_POLL_MS, USAGE_LOCK_WAIT_MS, USAGE_RETRY } from './constants/turns.constants.js';
21
+ import { CLAUDE_ENTRYPOINT_VAR, PARENT_SESSION_VAR, RE_PARENT_SESSION_ID, DEFAULT_SURFACE, EXTERNAL_PATH_KEY, FILE_PATH_KEY, IDE_SURFACE, IDE_SURFACE_PROVIDERS, LOCK_KEY_HASH_LENGTH, MAX_PROMPT_TEXT_LENGTH, MAX_TOOL_INPUT_LENGTH, PROMPT_EVIDENCE_KEY, PROMPT_JIRA_IDS_KEY, PROMPT_TEXT_KEY, RESPONSE_EVIDENCE_KEY, INT32_MAX, INT32_MIN, RE_SHA256_HEX, TOOL_CALL_KEY, TOOL_COMPLETION_TYPES, TOOL_START_TYPES, EXEC_SURFACE, TRANSCRIPT_PATH_KEY, TURN_STATE_TTL_MS, USAGE_LOCK_POLL_MS, USAGE_LOCK_WAIT_MS, USAGE_RETRY } from './constants/turns.constants.js';
20
22
  import { resolveFileIdentity } from './file-identity.js';
21
23
  import { TurnStateStore } from './turn-state.js';
24
+ import { buildToolEvents } from './tool-events.js';
22
25
  import { buildTurnSummary } from './turn-summary.js';
23
26
  import { rememberInheritance, retryInheritance } from './inherited-checkout.js';
24
27
  import { recordCheckouts, resolveWorkCheckout } from './work-checkout.js';
@@ -118,7 +121,7 @@ async function processEvent(store, sessionId, event, options) {
118
121
  if (type === 'prompt.submitted')
119
122
  await rememberPromptTicketsSafely(store, sessionId, event, options.config.capture.git);
120
123
  await recordCheckoutsSafely(store, sessionId, event, options);
121
- const record = recordFor(event, options.cwd, options.failOpenReason);
124
+ const record = await withCheckState(store, sessionId, event, recordFor(event, options.cwd, options.failOpenReason, options.config.capture.git), options);
122
125
  if (record)
123
126
  await store.append(sessionId, recordKeyFor(event), record);
124
127
  if (type === 'generation.completed') {
@@ -227,14 +230,19 @@ async function recordCheckoutsSafely(store, sessionId, event, options) {
227
230
  * @param event - Canonical event.
228
231
  * @param cwd - This hook's own working directory.
229
232
  * @param failOpenReason - Why this payload's prompt ran unchecked, if it did.
233
+ * @param git - Whether this hook's capture policy allows git context, which `tool_events` ride.
230
234
  * @returns The record, or undefined when the event carries no turn state.
231
235
  */
232
- function recordFor(event, cwd, failOpenReason) {
236
+ function recordFor(event, cwd, failOpenReason, git) {
233
237
  const type = event.event.type;
234
238
  if (type === 'prompt.submitted')
235
239
  return promptRecord(event, failOpenReason);
236
240
  if (TOOL_COMPLETION_TYPES.has(type))
237
- return toolRecord(event, cwd);
241
+ return toolRecord(event, cwd, git);
242
+ // A start is kept only to date its completion in `tool_events`, which ride
243
+ // `capture.git`: with it off the start would be a write for nothing.
244
+ if (git && TOOL_START_TYPES.has(type))
245
+ return toolStartRecord(event);
238
246
  // Cursor delivers the response text in its own hook (afterAgentResponse)
239
247
  // instead of on Stop; keep it as turn state until the turn closes.
240
248
  if (type === 'agent.other' && responseFrom(event) !== undefined)
@@ -311,7 +319,8 @@ async function closeTurnLocked(store, sessionId, stopEvent, options, readOnly =
311
319
  // the turn) means no empty duplicate.
312
320
  const all = await store.collectEntries(sessionId);
313
321
  const firstPass = filterTurn(all, stopTurnId);
314
- if (firstPass.length === 0)
322
+ // A start alone is not a turn: it only dates a completion that never came.
323
+ if (!firstPass.some(({ record }) => record.kind !== 'tool-start'))
315
324
  return undefined;
316
325
  const window = resolveWindow(all, firstPass, stopEvent.timestamp);
317
326
  const usage = await resolveAndClaimUsage(store, sessionId, stopEvent, options, window, readOnly);
@@ -364,6 +373,8 @@ async function closeTurnLocked(store, sessionId, stopEvent, options, readOnly =
364
373
  parentSessionId: declaredParent(options.env, sessionId) ?? work.parentSessionId,
365
374
  prompts: recordsOfKind(records, 'prompt'),
366
375
  tools: work.tools,
376
+ // Withheld whole with `capture.git` off: digests, times, status and the check flag go together.
377
+ toolEvents: (work.capture ?? options.config.capture).git === false ? undefined : buildToolEvents(records),
367
378
  response: resolveResponse(stopEvent, records),
368
379
  usage,
369
380
  model: resolvedStop.ai?.model,
@@ -697,13 +708,14 @@ function promptRecord(event, failOpenReason) {
697
708
  *
698
709
  * @param event - The tool event.
699
710
  * @param cwd - This hook's own working directory, which the event's repository path is relative to.
711
+ * @param git - Whether this hook's capture policy allows git context, which the call's `tool_events` facts ride.
700
712
  * @returns The record.
701
713
  */
702
- function toolRecord(event, cwd) {
714
+ function toolRecord(event, cwd, git) {
703
715
  const filePath = event.metadata?.[FILE_PATH_KEY];
704
716
  const externalPath = event.metadata?.[EXTERNAL_PATH_KEY];
705
717
  const repositoryPath = event.metadata?.[REPOSITORY_PATH_METADATA_KEY];
706
- return {
718
+ const record = {
707
719
  kind: 'tool',
708
720
  at: event.timestamp,
709
721
  turnId: event.session.turnId,
@@ -716,6 +728,125 @@ function toolRecord(event, cwd) {
716
728
  externalPath: typeof externalPath === 'string' && externalPath ? externalPath : undefined,
717
729
  input: toolInputOf(event)
718
730
  };
731
+ // Decided here by the hook's own policy, as `tool_inputs` is, and again at
732
+ // the close by the reported checkout's: a call seen under `capture.git` off
733
+ // keeps no facts to send, whichever checkout the turn reports.
734
+ if (!git)
735
+ return record;
736
+ const call = toolCallOf(event);
737
+ return {
738
+ ...record,
739
+ status: event.event.type === 'tool.failed' || event.tool?.status === 'failed' || (call.exitCode !== undefined && call.exitCode !== 0) ? 'failed' : 'ok',
740
+ callId: call.callId,
741
+ pairingKey: call.pairingKey,
742
+ exitCode: call.exitCode,
743
+ startedAt: startFromDuration(event.timestamp, event.tool?.durationMs),
744
+ inputFp: call.inputFp
745
+ };
746
+ }
747
+ /**
748
+ * The start of a tool call, from the agent's own record of it.
749
+ *
750
+ * @param event - The tool-start event.
751
+ * @returns The record, or undefined when the call has nothing to pair its completion on.
752
+ */
753
+ function toolStartRecord(event) {
754
+ const pairingKey = toolCallOf(event).pairingKey;
755
+ if (pairingKey === undefined)
756
+ return undefined;
757
+ return { kind: 'tool-start', at: event.timestamp, turnId: event.session.turnId, pairingKey };
758
+ }
759
+ /**
760
+ * The content-free tool-call block the adapter put on the event, type-checked.
761
+ *
762
+ * @param event - A tool event.
763
+ * @returns Its fields; empty when the adapter wrote none.
764
+ */
765
+ function toolCallOf(event) {
766
+ const block = asRecord(event.metadata?.[TOOL_CALL_KEY]);
767
+ const callId = nonEmptyString(block?.['callId']);
768
+ const inputFp = block?.['inputFp'];
769
+ const exitCode = block?.['exitCode'];
770
+ return {
771
+ callId,
772
+ pairingKey: nonEmptyString(block?.['pairingKey']) ?? callId,
773
+ inputFp: typeof inputFp === 'string' && RE_SHA256_HEX.test(inputFp) ? inputFp : undefined,
774
+ matchesCheck: block?.['matchesCheck'] === true,
775
+ // Core's int32 range: one value outside it would cost the whole summary a 422.
776
+ exitCode: typeof exitCode === 'number' && Number.isInteger(exitCode) && exitCode >= INT32_MIN && exitCode <= INT32_MAX ? exitCode : undefined
777
+ };
778
+ }
779
+ /**
780
+ * A string worth keeping, else nothing.
781
+ *
782
+ * @param value - Any decoded value.
783
+ * @returns The string when it is a non-empty one.
784
+ */
785
+ function nonEmptyString(value) {
786
+ return typeof value === 'string' && value ? value : undefined;
787
+ }
788
+ /**
789
+ * When a call that reports its duration started.
790
+ *
791
+ * @param endedAt - The completion's ISO timestamp.
792
+ * @param durationMs - The duration the agent reported, if any.
793
+ * @returns The ISO start, or undefined without a usable duration.
794
+ */
795
+ function startFromDuration(endedAt, durationMs) {
796
+ const end = Date.parse(endedAt);
797
+ if (durationMs === undefined || !Number.isFinite(durationMs) || durationMs < 0 || Number.isNaN(end))
798
+ return undefined;
799
+ return new Date(end - durationMs).toISOString();
800
+ }
801
+ /**
802
+ * A completion of an allowlisted check that ran for a minute, with the code
803
+ * it ran on (workflow SPEC §11.2) taken now, before the tree moves on.
804
+ *
805
+ * Every other record passes through untouched, and costs nothing: the start
806
+ * is looked up, and git asked, only for a call whose command is on the
807
+ * allowlist, and only under `capture.git`. Never throws: a check whose state
808
+ * cannot be read is sent as a check without it.
809
+ *
810
+ * ponytail: git runs in the hook's cwd, not a directory the command `cd`s
811
+ * into; `cd pkg && npm test` is the same checkout. A command that tests
812
+ * another checkout records this one's state. Upgrade path: the provider's
813
+ * `shellCall` workdir, for the agents that report one.
814
+ *
815
+ * @param store - Per-session state store.
816
+ * @param sessionId - Provider session id.
817
+ * @param event - The event the record came from.
818
+ * @param record - The record about to be persisted.
819
+ * @param options - Tracking options.
820
+ * @returns The record, with the check and its code state when it is one.
821
+ */
822
+ async function withCheckState(store, sessionId, event, record, options) {
823
+ if (record?.kind !== 'tool' || !options.config.capture.git || !toolCallOf(event).matchesCheck)
824
+ return record;
825
+ try {
826
+ const startedAt = record.startedAt ?? (await startOf(store, sessionId, record));
827
+ if (startedAt === undefined || Date.parse(record.at) - Date.parse(startedAt) < CHECK_MIN_DURATION_MS)
828
+ return record;
829
+ const state = await codeStateAt(options.cwd);
830
+ return compact({ ...record, startedAt, check: true, commit: state?.commit, diffFp: state?.diffFp });
831
+ }
832
+ catch {
833
+ debugLog('could not read the code state a check ran on');
834
+ return record;
835
+ }
836
+ }
837
+ /**
838
+ * When the call a completion closes started, from its start record.
839
+ *
840
+ * @param store - Per-session state store.
841
+ * @param sessionId - Provider session id.
842
+ * @param record - The completion.
843
+ * @returns The ISO start, or undefined when no start was recorded.
844
+ */
845
+ async function startOf(store, sessionId, record) {
846
+ if (record.pairingKey === undefined)
847
+ return undefined;
848
+ const entries = await store.collectEntries(sessionId);
849
+ return entries.find(({ record: start }) => start.kind === 'tool-start' && start.pairingKey === record.pairingKey && start.turnId === record.turnId)?.record.at;
719
850
  }
720
851
  /**
721
852
  * The shell command or connector call a tool event carries, bounded.
@@ -45,6 +45,33 @@ export interface ToolRecord {
45
45
  readonly externalPath?: string;
46
46
  /** The shell command or connector call, bounded; under `capture.toolInput`. */
47
47
  readonly input?: ToolInputSummary;
48
+ readonly status?: 'ok' | 'failed';
49
+ /** The agent's own id for the call; what joins it to the agent's OTLP record. */
50
+ readonly callId?: string;
51
+ /** Matches the call's start record; the call id, or Antigravity's step index. Local only. */
52
+ readonly pairingKey?: string;
53
+ readonly exitCode?: number;
54
+ /** From the provider's duration, or the start record's time for a check. */
55
+ readonly startedAt?: string;
56
+ /** Unkeyed sha256 of the normalised command or connector arguments. */
57
+ readonly inputFp?: string;
58
+ /** On the check allowlist and ran for `CHECK_MIN_DURATION_MS`. */
59
+ readonly check?: boolean;
60
+ /** HEAD at a check's completion. */
61
+ readonly commit?: string;
62
+ /** Digest of the working tree at a check's completion. */
63
+ readonly diffFp?: string;
64
+ }
65
+ /**
66
+ * A tool call starting, kept only to date its completion: no duration on the
67
+ * completion means no start time without it. Local only; written only when
68
+ * the call has an id to pair on and `capture.git` is on.
69
+ */
70
+ export interface ToolStartRecord {
71
+ readonly kind: 'tool-start';
72
+ readonly at: string;
73
+ readonly turnId?: string;
74
+ readonly pairingKey: string;
48
75
  }
49
76
  /** What went into one shell or connector (MCP) call, as the turn summary sends it. */
50
77
  export interface ToolInputSummary {
@@ -100,7 +127,7 @@ export interface SessionModelRecord {
100
127
  readonly model: string;
101
128
  }
102
129
  /** Anything the accumulator persists between hook invocations. */
103
- export type TurnRecord = PromptRecord | ToolRecord | ResponseRecord | CheckoutRecord;
130
+ export type TurnRecord = PromptRecord | ToolRecord | ToolStartRecord | ResponseRecord | CheckoutRecord;
104
131
  /** The session's last changed checkout, as `work-checkout.json` holds it. Local only. */
105
132
  export interface WorkCheckoutMemo {
106
133
  readonly root: string;
@@ -91,6 +91,8 @@ export interface TurnSummaryEvent extends AgentWatchEvent<'turn.summary'> {
91
91
  readonly response_evidence?: ContentEvidence;
92
92
  readonly tool_calls: number;
93
93
  readonly tools_used: Readonly<Record<string, number>>;
94
+ /** The turn's first 200 tool calls in call order, content-free; under `capture.git` (AWT-675). */
95
+ readonly tool_events?: readonly ToolEvent[];
94
96
  readonly model?: string;
95
97
  /** subscription (flat plan) vs api (per-token billing); see billing-mode.ts. */
96
98
  readonly billing_mode?: UsageBillingMode;
@@ -117,6 +119,32 @@ export interface TurnSummaryEvent extends AgentWatchEvent<'turn.summary'> {
117
119
  readonly started_at?: string;
118
120
  readonly ended_at: string;
119
121
  }
122
+ /**
123
+ * One tool call of a turn, as core's `turn.summary.tool_events` takes it
124
+ * (AWT-674). Content-free by construction: there is no field for a command, a
125
+ * path or an output. The digests are unkeyed sha256; core re-keys them per
126
+ * tenant before it stores them.
127
+ */
128
+ export interface ToolEvent {
129
+ /** Order in the turn, from 0. */
130
+ readonly seq: number;
131
+ readonly tool: string;
132
+ /** The agent's own id for the call, when it names one: what joins this record to its OTLP one. */
133
+ readonly tool_call_id?: string;
134
+ readonly status: 'ok' | 'failed';
135
+ readonly exit_code?: number;
136
+ /** Absent when the provider gives no start; such a call is never a check. */
137
+ readonly started_at?: string;
138
+ readonly ended_at: string;
139
+ /** The normalised command's digest (core's command scheme), or the connector arguments'. */
140
+ readonly input_fp?: string;
141
+ /** On the check allowlist and ran for at least 60 s. */
142
+ readonly check?: boolean;
143
+ /** HEAD when the check finished. */
144
+ readonly commit?: string;
145
+ /** Digest of the working tree when the check finished. */
146
+ readonly diff_fp?: string;
147
+ }
120
148
  export interface BuildTurnSummaryInput {
121
149
  /** Internal provider id ('claude' | 'codex' | ...); mapped to the public label. */
122
150
  readonly provider: string;
@@ -138,6 +166,8 @@ export interface BuildTurnSummaryInput {
138
166
  /** The session's latest native name and generated/display title as the agent holds them, unscrubbed. */
139
167
  readonly sessionTitles?: SessionTitles;
140
168
  readonly tools: readonly ToolRecord[];
169
+ /** Already gated and capped by the tracker; see {@link ToolEvent}. */
170
+ readonly toolEvents?: readonly ToolEvent[];
141
171
  /** Evidence of the response the user actually saw, however the provider delivered it. */
142
172
  readonly response?: ContentEvidence;
143
173
  readonly usage?: TurnUsage;
@@ -51,3 +51,13 @@ export interface TurnWindow {
51
51
  */
52
52
  readonly untilIso: string;
53
53
  }
54
+ /** The content-free tool-call block an adapter put on a tool event, type-checked. */
55
+ export interface ToolCallFacts {
56
+ readonly callId?: string;
57
+ /** The call id, or the provider's own pairing key when it names no call id. */
58
+ readonly pairingKey?: string;
59
+ readonly inputFp?: string;
60
+ /** A command segment is on the check allowlist; the duration decides the rest. */
61
+ readonly matchesCheck: boolean;
62
+ readonly exitCode?: number;
63
+ }
@@ -51,9 +51,11 @@ export declare function recordCheckouts(store: TurnStateStore, sessionId: string
51
51
  * Every admitted checkout the turn named is fingerprinted again, all at once,
52
52
  * and compared with its baseline. The turn reports, in this order: the one it
53
53
  * changed most (`changed`); else the session's last changed checkout
54
- * (`carried`); else the one it named most (`referenced`); else the Stop folder's
55
- * own repository, as before this existed (`cwd`). Ties go to the checkout named
56
- * first. Every failure makes a candidate lose, never the summary.
54
+ * (`carried`); else the one it named most (`referenced`); else the Stop
55
+ * folder's own repository, as before this existed (`cwd`). Below `changed`, a
56
+ * checkout is reported only while the turn touched no file or one there. Ties
57
+ * go to the checkout named first. Every failure makes a candidate lose, never
58
+ * the summary.
57
59
  *
58
60
  * @param store - Per-session state store.
59
61
  * @param sessionId - Provider session id.
@@ -87,9 +87,11 @@ export async function recordCheckouts(store, sessionId, event, options) {
87
87
  * Every admitted checkout the turn named is fingerprinted again, all at once,
88
88
  * and compared with its baseline. The turn reports, in this order: the one it
89
89
  * changed most (`changed`); else the session's last changed checkout
90
- * (`carried`); else the one it named most (`referenced`); else the Stop folder's
91
- * own repository, as before this existed (`cwd`). Ties go to the checkout named
92
- * first. Every failure makes a candidate lose, never the summary.
90
+ * (`carried`); else the one it named most (`referenced`); else the Stop
91
+ * folder's own repository, as before this existed (`cwd`). Below `changed`, a
92
+ * checkout is reported only while the turn touched no file or one there. Ties
93
+ * go to the checkout named first. Every failure makes a candidate lose, never
94
+ * the summary.
93
95
  *
94
96
  * @param store - Per-session state store.
95
97
  * @param sessionId - Provider session id.
@@ -137,16 +139,24 @@ export async function resolveWorkCheckout(store, sessionId, records, stopEvent,
137
139
  return reportCheckout({ root: byChange.root, evidence: 'changed', probed: probes.get(byChange.root), changed: changed.get(byChange.root), withhold: false }, tools, options);
138
140
  // Carried only while the folder is still the repository that was
139
141
  // remembered: a directory re-cloned from another remote is not that work.
142
+ // Every rung below `changed` also needs the turn's edits, when it made any,
143
+ // to include one there (AWT-618, AWT-620, AWT-621): a session that changed
144
+ // one checkout and then wrote files elsewhere is not working in it, nor in
145
+ // the one its shell sits in. A turn that edited no file reports as before,
146
+ // whatever it read.
140
147
  const carriedProbe = carried === undefined ? undefined : probes.get(carried);
141
- const stillSame = carriedProbe?.closing !== undefined && repositoryIdentity(carried, carriedProbe.remote).repository === memo?.repository;
148
+ const allows = fileEvidenceAllows(tools);
149
+ const stillSame = carriedProbe?.closing !== undefined
150
+ && repositoryIdentity(carried, carriedProbe.remote).repository === memo?.repository
151
+ && allows(carried);
142
152
  if (stillSame)
143
153
  return reportCheckout({ root: carried, evidence: 'carried', probed: carriedProbe, changed: [], withhold: withheld(carried, carriedProbe.branch) }, tools, options);
144
- const byVotes = best(reportable, (candidate) => candidate.votes + candidate.read.size);
154
+ const byVotes = best(reportable.filter((candidate) => allows(candidate.root)), (candidate) => candidate.votes + candidate.read.size);
145
155
  const votedProbe = byVotes === undefined ? undefined : probes.get(byVotes.root);
146
156
  if (byVotes)
147
157
  return reportCheckout({ root: byVotes.root, evidence: 'referenced', probed: votedProbe, changed: [], withhold: withheld(byVotes.root, votedProbe.branch) }, tools, options);
148
158
  const stopRoot = await checkoutRootOf(options.cwd);
149
- const inherited = stopRoot === undefined ? await inheritedCheckout(store, sessionId, options, tools) : undefined;
159
+ const inherited = stopRoot === undefined ? await inheritedCheckout(store, sessionId, options, tools, allows) : undefined;
150
160
  if (inherited)
151
161
  return inherited;
152
162
  // The Stop folder's own repository is held to the same admission as every
@@ -154,7 +164,7 @@ export async function resolveWorkCheckout(store, sessionId, records, stopEvent,
154
164
  // outside the start folder.
155
165
  // A folder whose checkout cannot be found is not admitted either: git may
156
166
  // still have named a repository there, past what the walk reaches.
157
- if (stopRoot === undefined || !admits(stopRoot))
167
+ if (stopRoot === undefined || !admits(stopRoot) || !allows(stopRoot))
158
168
  return { tools: keepingPathsIn(tools, undefined) };
159
169
  // Enrichment read the folder's branch; a detached review gets its pull
160
170
  // request's (SPEC §3b), withheld by the same rule as any other.
@@ -200,11 +210,12 @@ export async function resolveWorkCheckout(store, sessionId, records, stopEvent,
200
210
  * @param sessionId - Provider session id.
201
211
  * @param options - Tracking options.
202
212
  * @param tools - The turn's tool records.
213
+ * @param allows - The turn's file test (`fileEvidenceAllows`).
203
214
  * @returns The report, or undefined when nothing was inherited or it cannot be read.
204
215
  */
205
- async function inheritedCheckout(store, sessionId, options, tools) {
216
+ async function inheritedCheckout(store, sessionId, options, tools, allows) {
206
217
  const found = await resolveInherited(store, sessionId, admission(options, (await store.readStart(sessionId)) ?? options.cwd, true));
207
- if (!found)
218
+ if (!found || !allows(found.root))
208
219
  return undefined;
209
220
  const probed = await probe(emptyCandidate(found.root, 0));
210
221
  if (!probed.closing)
@@ -331,15 +342,38 @@ function candidatesOf(records, admits) {
331
342
  candidate.votes += 1;
332
343
  continue;
333
344
  }
334
- // Only a completed read or edit is evidence: a failed call names a file it
335
- // may never have touched, and carries no access marker.
336
- if (record.kind !== 'tool' || typeof record.filePath !== 'string' || (record.access !== 'read' && record.access !== 'edit'))
345
+ if (!touchedFile(record))
337
346
  continue;
338
347
  const candidate = at(record.repositoryRoot);
339
348
  candidate?.[record.access === 'read' ? 'read' : 'edited'].add(record.filePath);
340
349
  }
341
350
  return [...byRoot.values()].sort(byFirstSight).slice(0, MAX_TURN_CHECKOUTS);
342
351
  }
352
+ /**
353
+ * Whether a turn's edits let a rung below `changed` report a checkout: the
354
+ * turn edited no file, or one of its edits is in it. Reads decide nothing (a
355
+ * turn running tests in a checkout may read `/tmp/out.txt`), though they still
356
+ * rank the checkouts this admits on the `referenced` rung. A file's root is
357
+ * its innermost checkout, so a worktree nested in that folder does not count.
358
+ *
359
+ * @param tools - The turn's tool records.
360
+ * @returns A test of one canonical checkout root.
361
+ */
362
+ function fileEvidenceAllows(tools) {
363
+ const roots = tools.filter((record) => touchedFile(record) && record.access === 'edit').map((record) => (typeof record.repositoryRoot === 'string' ? canonicalRoot(record.repositoryRoot) : undefined));
364
+ return (root) => roots.length === 0 || roots.includes(root);
365
+ }
366
+ /**
367
+ * Whether a record is a file the turn read or edited. Only a completed read or
368
+ * edit is evidence: a failed call names a file it may never have touched, and
369
+ * carries no access marker.
370
+ *
371
+ * @param record - A turn record.
372
+ * @returns True for a completed read or edit of a file.
373
+ */
374
+ function touchedFile(record) {
375
+ return record.kind === 'tool' && typeof record.filePath === 'string' && (record.access === 'read' || record.access === 'edit');
376
+ }
343
377
  /**
344
378
  * A checkout at the Stop: fingerprint and remote together, then the commit diff
345
379
  * when HEAD moved. A checkout whose directory is gone keeps its baseline's
@@ -72,6 +72,17 @@ is there any code path through which prompt text, model response text, tool
72
72
  input bodies, tool output bodies, or file contents leave the machine? If yes,
73
73
  show the path.
74
74
 
75
+ `turn.summary` carries `tool_events` by default, one record per tool call:
76
+ `seq`, `tool`, `tool_call_id`, `status`, `exit_code`, `started_at`, `ended_at`,
77
+ `input_fp`, `check`, `commit` and `diff_fp`. `input_fp` is a sha256 of the
78
+ normalized shell command or of a connector call's JSON arguments, and `diff_fp`
79
+ a sha256 of the check's uncommitted `git diff HEAD`. Verify that no field of a record can hold a
80
+ command, a path, arguments or an output, that the command is hashed in memory
81
+ and never written to turn state without `toolInput`, that the whole list is
82
+ absent with `capture.git: false` (at build time and again before send), and
83
+ which git processes a check runs on the hook path. Say what a guessed common
84
+ command's hash lets someone confirm.
85
+
75
86
  ## 5. The consent gate
76
87
  Explain how content capture is enabled. Can a repository-level config file,
77
88
  an environment variable, a command-line flag, or a corrupt or missing global
@@ -41,10 +41,12 @@ every agent the edge supports: Claude Code, Codex, Cursor, Gemini CLI and
41
41
  Antigravity. The command's working directory is used as a candidate when the agent
42
42
  reports it (Cursor's shell `cwd`, Gemini's `dir_path`, Antigravity's `Cwd`), and so
43
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).
44
+ are kept, in local turn state, until the turn closes. The command text is never
45
+ stored, queued, logged or sent for that purpose. This happens only while
46
+ `capture.git` is on. Separately, and also only while `capture.git` is on, a sha256
47
+ fingerprint of the normalized command is sent in the turn summary's `tool_events`
48
+ (below), never the text; with `toolInput` on, the command text itself is sent on
49
+ the turn summary (see `tool_inputs` below).
48
50
 
49
51
  Configurations written by earlier releases may still carry `capture.prompts` or
50
52
  `capture.responses`. Those keys are ignored on load whatever their value —
@@ -73,7 +75,7 @@ fields.
73
75
  Current policy is reapplied to old turn state before queueing, and to every queued
74
76
  record before HTTP delivery: summaries always lose `prompt` and `response` text an
75
77
  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
78
+ flag is on with consent, lose every path list once `capture.files` is off, lose `tool_events` once `capture.git` is off, and repository snapshots are dropped entirely once
77
79
  `capture.git` is off. Old files are not erased by an upgrade; their original content
78
80
  may remain locally until consumed or expired, but it is never sent.
79
81
 
@@ -88,7 +90,8 @@ whatever the consent state, and never enables Gemini detailed traces, which can
88
90
  carry prompts. Codex and Gemini usage logs can contain tool arguments/results
89
91
  without a reliable per-field filter, so the Edge configures those logs only when
90
92
  global consent exists and both `toolInput` and `toolOutput` are enabled. Gemini
91
- metrics may run without content consent. This can leave `llm.call` usage
93
+ gets no native export at all without that consent, metrics included, because it
94
+ ignores `OTEL_LOGS_EXPORTER=none` and `OTEL_TRACES_EXPORTER=none`. This can leave `llm.call` usage
92
95
  unavailable by default for Codex and Gemini. Codex turns still carry token
93
96
  counts: the Edge reads only the `token_count` and `turn_context` rows of the
94
97
  Codex rollout file locally (per-request token numbers and the model name) and
@@ -115,7 +118,7 @@ The hook-generated flat fields are `provider`, `surface`, `session_id`, `turn_id
115
118
  `developer_id`, `repository`, `branch`, `commit`, `jira_ids`, `prompt_jira_ids`, `work_evidence`,
116
119
  `parent_session_id`, `content_hashes`, `manifest_repository`, `files_changed`, `files_touched`, `files_read`, `external_files_touched`,
117
120
  `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`,
121
+ `tool_calls`, `tools_used`, `tool_events`, `model`, `billing_mode`, `input_tokens`,
119
122
  `cached_input_tokens`, `cache_creation_input_tokens`, `output_tokens`,
120
123
  `usage_status`, `started_at`, and `ended_at`. The nested `session` contains `id`,
121
124
  `providerId`, and optionally `turnId`.
@@ -162,12 +165,63 @@ prompt evidence hashes the prompt as the agent reported it.
162
165
  transcript tail no longer reaches one, and deleted with the session. Codex and
163
166
  Cursor's SQLite indexes are opened read-only through Node's standard library;
164
167
  Node versions before 22.12 omit those optional title fields.
168
+ - `tools_used`: per-tool call counts. An MCP call is keyed `mcp__<server>__<tool>`
169
+ (the server's name, else a remote endpoint's host:port or a stdio command's base name,
170
+ else `unknown`; never arguments. Cursor keys are cut at 200 characters; every key is
171
+ secret-scrubbed before it is sent). `capture.mcpNames: false`
172
+ folds every MCP key into `mcp`, keeping the count; a repository file can set it
173
+ false, never true. It is metadata, so `toolInput` does not gate it.
165
174
  - `tool_inputs` (only under `toolInput` with consent): per shell or connector (MCP)
166
175
  call, `{tool, command}` or `{tool, server, name, arguments}` with the arguments as
167
176
  JSON text; sensitive argument keys are redacted before that, every string is cut
168
177
  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.
178
+ Tool output bodies are not sent on the summary; enabling tool flags adds nothing
179
+ to `tool_events`, which never carries content.
180
+ - `tool_events` (under `git`, on by default): one record per tool call, in call
181
+ order, at most 200 per turn (`tool_calls` and `tools_used` still count every
182
+ call). Each record holds only `seq` (its order), `tool` (the tool's name, as in
183
+ `tools_used`), `tool_call_id` (the agent's own id for the call, where its hook payload names
184
+ one: Claude Code, Codex, Cursor's generic tool hooks, Gemini CLI when it sends
185
+ `tool_use_id`), `status` (`ok` or `failed`),
186
+ `exit_code` (where the agent states one: Codex, and Claude Code's failed shell
187
+ calls), `started_at` (from the provider's duration, or from the call's start
188
+ hook paired on its call id or Antigravity's step index; a call with neither, such
189
+ as a Gemini CLI call without `tool_use_id`, sends none), `ended_at`, `input_fp`, `check`,
190
+ `commit` and `diff_fp`. There is no field for a command, a path, arguments or
191
+ an output.
192
+ - `input_fp`: for a shell call, the sha256 of the command after normalization
193
+ (quotes undone, whitespace collapsed, `cd` segments, redirections and leading
194
+ `VAR=value` words dropped; for a check, of the check's own segment only); for a
195
+ connector (MCP) call, the sha256 of its arguments as JSON. Other tools send
196
+ none. The command and arguments are read in memory in the hook, hashed and
197
+ dropped: the text is never stored, queued, logged or sent without `toolInput`.
198
+ The same caveat as prompt evidence applies, more so: a hash of a short or
199
+ common command (`npm test`, `git status`) can be confirmed by anyone who hashes
200
+ the same guess. The platform re-keys every stored fingerprint with a key per
201
+ tenant, so a stored value cannot be compared across tenants or confirmed
202
+ without that key.
203
+ - `check`: the command is on a fixed allowlist of test, lint, typecheck and build
204
+ commands (`npm`/`pnpm`/`yarn` `test`, `lint`, `typecheck`, `check`, `verify`,
205
+ `build`; `vitest`, `jest`, `tsc`, `pytest`, `go test`, `cargo test`,
206
+ `make test|check`, `pr-tests.sh`, also through `npx` or `python -m`) and ran
207
+ for at least 60 seconds. A call with no start time
208
+ is never a check.
209
+ - `commit` and `diff_fp`, on a check only: HEAD, and the sha256 of the
210
+ uncommitted diff of tracked files against HEAD when the check finished
211
+ (`git diff HEAD --binary`, streamed into the hash; a clean checkout hashes
212
+ the empty diff; untracked files are not covered). The diff itself never
213
+ leaves the hook process. These two, and the start record's lookup, are the
214
+ only extra work a check costs the hook: `git rev-parse HEAD` and `git diff`,
215
+ both read-only and run with `--no-optional-locks`, so they write nothing to
216
+ the repository and never take the agent's index lock.
217
+
218
+ On the machine, a tool call's start is kept in local turn state (mode 0600) until
219
+ the turn closes, only while `capture.git` is on: its time and the agent's call id
220
+ (or Antigravity's step index), nothing else. The platform also reads tool calls
221
+ from the agents' own OTLP export, where Claude Code, Codex and Gemini CLI include
222
+ a shell call's command when their own tool-detail logging is on; the platform
223
+ reads that command in memory only, to fingerprint it the same way, and drops it
224
+ (core AWT-674). The two records of one call are joined on `tool_call_id`.
171
225
  - `external_files_touched` / `external_files_read` (under `files`, and only while
172
226
  `git` is on, since that is what tells inside a checkout from outside): files outside
173
227
  every checkout, home-relative (`~/Documents/a.xlsx`); a path outside the home
@@ -419,10 +473,11 @@ Global configuration is stored in `~/.agentwatch/config.json` (0600). The
419
473
  organization install key written by setup (from `--token`, `$AGENTWATCH_TOKEN`
420
474
  or the prompt) is exchanged once through `POST /v1/devices/enroll` for a device
421
475
  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
476
+ beside the key. The key stays in the file to enroll again when the device
477
+ secret expires. The Claude hooks and header helper send the device's access
478
+ token and never the key once the device is recorded; Codex and Gemini get the
479
+ same access token in their own config, rewritten by each hook as it rotates
480
+ (docs/NATIVE_OTLP_TOKENS.md). The device reference is an id
426
481
  derived from the install key's digest and the name of the store that holds the
427
482
  secret. The device secret lives in the macOS Keychain (service
428
483
  `agentwatch-device`), the Secret Service keyring through `secret-tool` (only
@@ -480,7 +535,7 @@ and this is a property of those agents rather than a choice made here.** Neither
480
535
  CLI has a mechanism for fetching a credential at request time, so the only way
481
536
  to authenticate their native OTLP exporters is to write the bearer into the file
482
537
  they read at startup: `~/.codex/config.toml` for Codex, and
483
- `OTEL_EXPORTER_OTLP_HEADERS` inside `~/.gemini/settings.json` for Gemini. Claude
538
+ `OTEL_EXPORTER_OTLP_HEADERS` inside `~/.gemini/.env` for Gemini. Claude
484
539
  Code does have such a mechanism — `otelHeadersHelper`, which calls
485
540
  `agentwatch otel-headers` at runtime — so no Claude configuration file ever
486
541
  contains a token. Cursor and Antigravity have no managed native exporter, so the