@agent-watch-ai/edge 0.5.0 → 0.6.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 (43) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +6 -5
  3. package/dist/events/constants/events.constants.d.ts +5 -2
  4. package/dist/events/constants/events.constants.js +4 -1
  5. package/dist/events/index.d.ts +1 -0
  6. package/dist/events/product-event.d.ts +7 -4
  7. package/dist/events/types/repo-snapshot.types.d.ts +1 -4
  8. package/dist/events/types/repo-tree.types.d.ts +24 -0
  9. package/dist/events/types/repo-tree.types.js +1 -0
  10. package/dist/git/constants/tree.constants.d.ts +71 -0
  11. package/dist/git/constants/tree.constants.js +92 -0
  12. package/dist/git/git-context.d.ts +1 -0
  13. package/dist/git/git-context.js +3 -2
  14. package/dist/git/repo-tree.d.ts +69 -0
  15. package/dist/git/repo-tree.js +130 -0
  16. package/dist/git/types/git.types.d.ts +5 -2
  17. package/dist/git/types/snapshot.types.d.ts +12 -0
  18. package/dist/pipeline/hook-pipeline.js +40 -24
  19. package/dist/privacy/product-capture.js +34 -5
  20. package/dist/snapshot/branch-selection.js +3 -1
  21. package/dist/snapshot/budget.js +2 -2
  22. package/dist/snapshot/constants/snapshot-stages.constants.d.ts +8 -0
  23. package/dist/snapshot/constants/snapshot-stages.constants.js +8 -0
  24. package/dist/snapshot/constants/snapshot.constants.d.ts +6 -0
  25. package/dist/snapshot/constants/snapshot.constants.js +6 -0
  26. package/dist/snapshot/index.d.ts +5 -0
  27. package/dist/snapshot/index.js +2 -0
  28. package/dist/snapshot/snapshot-event.d.ts +7 -0
  29. package/dist/snapshot/snapshot-event.js +8 -5
  30. package/dist/snapshot/snapshot-state.js +19 -1
  31. package/dist/snapshot/tree-event.d.ts +14 -0
  32. package/dist/snapshot/tree-event.js +91 -0
  33. package/dist/snapshot/tree-pipeline.d.ts +12 -0
  34. package/dist/snapshot/tree-pipeline.js +153 -0
  35. package/dist/snapshot/types/snapshot.types.d.ts +44 -1
  36. package/dist/transport/constants/transport.constants.d.ts +5 -0
  37. package/dist/transport/constants/transport.constants.js +5 -0
  38. package/dist/transport/queue.js +40 -6
  39. package/dist/turns/turn-summary.js +3 -4
  40. package/dist/turns/types/turn-summary.types.d.ts +3 -5
  41. package/docs/DATA_HANDLING.md +77 -26
  42. package/docs/PERFORMANCE.md +17 -0
  43. package/package.json +1 -1
@@ -1,5 +1,6 @@
1
1
  import type { RepoSnapshotEvent } from '../../events/types/repo-snapshot.types.js';
2
- import type { BranchRef, SnapshotBranch } from '../../git/types/snapshot.types.js';
2
+ import type { RepoTreeEvent } from '../../events/types/repo-tree.types.js';
3
+ import type { BranchRef, RepoTree, SnapshotBranch } from '../../git/types/snapshot.types.js';
3
4
  import type { GitRunner } from '../../git/types/git.types.js';
4
5
  /** What was last reported about one branch. */
5
6
  export interface SnapshotStateEntry {
@@ -18,6 +19,19 @@ export interface SnapshotState {
18
19
  */
19
20
  readonly defaultBranch?: string;
20
21
  readonly branches: Record<string, SnapshotStateEntry>;
22
+ /** The default-branch tree last sent as `repo.tree`, and when. */
23
+ readonly tree?: SnapshotTreeEntry;
24
+ }
25
+ /** Whether one repository's trunk tree has been sent, and for whom, or when it was last tried. */
26
+ export interface SnapshotTreeEntry {
27
+ /** The tree that was sent; absent when none has been yet. */
28
+ readonly sha?: string;
29
+ /** Epoch milliseconds the tree was queued. */
30
+ readonly sentAt?: number;
31
+ /** The identity fingerprint it was sent as: a different identity owes the tree again. */
32
+ readonly sentFor?: string;
33
+ /** When an attempt last failed, so the next waits out {@link TREE_RETRY_INTERVAL_MS}. */
34
+ readonly triedAt?: number;
21
35
  }
22
36
  /**
23
37
  * Who and where a snapshot is about: everything the event itself carries.
@@ -41,6 +55,8 @@ export interface SnapshotFlowInput extends SnapshotIdentity {
41
55
  readonly cwd: string;
42
56
  /** Whether the effective capture policy allows file names; when not, no files listing runs. */
43
57
  readonly files: boolean;
58
+ /** Fingerprint of the identity events are sent as; the tree is sent once per repository and identity. */
59
+ readonly identity?: string;
44
60
  readonly deadline: number;
45
61
  readonly run: GitRunner;
46
62
  }
@@ -57,6 +73,29 @@ export interface BuildSnapshotInput {
57
73
  readonly defaultBranch?: string;
58
74
  readonly branches: readonly SnapshotBranch[];
59
75
  }
76
+ /** Identity and the tree one `repo.tree` describes. */
77
+ export interface BuildTreeInput {
78
+ readonly identity: SnapshotIdentity;
79
+ readonly tree: RepoTree;
80
+ }
81
+ /** Everything one run of the tree flow needs beyond its own state. */
82
+ export interface TreePipelineInput {
83
+ /** Reuses the snapshot flow's input; its `files` flag must already be on to get here. */
84
+ readonly input: SnapshotFlowInput;
85
+ readonly store: SnapshotStateReader;
86
+ readonly queue: TreeQueue;
87
+ }
88
+ /** State threaded through the tree flow's stages. */
89
+ export interface TreeFlowState {
90
+ readonly input: SnapshotFlowInput;
91
+ readonly store: SnapshotStateReader;
92
+ readonly queue: TreeQueue;
93
+ readonly run: GitRunner;
94
+ readonly stored?: SnapshotState;
95
+ readonly treeSha?: string;
96
+ readonly tree?: RepoTree;
97
+ readonly event?: RepoTreeEvent;
98
+ }
60
99
  /** Everything one run of the flow needs beyond its own state. */
61
100
  export interface SnapshotPipelineInput {
62
101
  readonly input: SnapshotFlowInput;
@@ -86,3 +125,7 @@ export interface SnapshotStateReader {
86
125
  export interface SnapshotQueue {
87
126
  enqueue(events: readonly RepoSnapshotEvent[]): Promise<void>;
88
127
  }
128
+ /** The one thing the tree flow asks of the offline queue. */
129
+ export interface TreeQueue {
130
+ enqueue(events: readonly RepoTreeEvent[]): Promise<void>;
131
+ }
@@ -124,3 +124,8 @@ export declare const DELIVERY_STAGE_NAMES: {
124
124
  /** In an identity's state directory: its cached access token and its device credential state (AWT-356). */
125
125
  export declare const ACCESS_TOKEN_FILE_NAME = "access-token.json";
126
126
  export declare const DEVICE_STATE_FILE_NAME = "device.json";
127
+ /**
128
+ * How long a `repo.tree` whose upload the delivery budget cut short waits before the next try.
129
+ * Not an attempt: the tree was fine, the link was slow. A catalog tree is never urgent.
130
+ */
131
+ export declare const TREE_DEFERRED_RETRY_MS: number;
@@ -124,3 +124,8 @@ export const DELIVERY_STAGE_NAMES = {
124
124
  /** In an identity's state directory: its cached access token and its device credential state (AWT-356). */
125
125
  export const ACCESS_TOKEN_FILE_NAME = 'access-token.json';
126
126
  export const DEVICE_STATE_FILE_NAME = 'device.json';
127
+ /**
128
+ * How long a `repo.tree` whose upload the delivery budget cut short waits before the next try.
129
+ * Not an attempt: the tree was fine, the link was slow. A catalog tree is never urgent.
130
+ */
131
+ export const TREE_DEFERRED_RETRY_MS = 15 * 60_000;
@@ -6,7 +6,7 @@ import { writeFileAtomic } from '../storage/atomic-file.js';
6
6
  import { acquireLock } from '../storage/lock.js';
7
7
  import { claimSweep } from '../storage/sweep-marker.js';
8
8
  import { SECRET_FILE_MODE, SWEEP_MARKER_FILE } from '../storage/constants/storage.constants.js';
9
- import { ANY_DESTINATION, AUTH_REJECTED_STATUSES, BACKOFF_BASE_MS, BACKOFF_JITTER_MIN, BACKOFF_JITTER_RANGE, BACKOFF_MAX_MS, MAX_ISOLATION_SENDS, MS_PER_DAY, QUEUE_DRAIN_LOCK, QUEUE_FILE_SUFFIX, QUEUE_SCAN_CURSOR_FILE, QUEUE_SWEEP_INTERVAL_MS, RE_UNSAFE_QUEUE_NAME } from './constants/transport.constants.js';
9
+ import { ANY_DESTINATION, AUTH_REJECTED_STATUSES, BACKOFF_BASE_MS, BACKOFF_JITTER_MIN, BACKOFF_JITTER_RANGE, BACKOFF_MAX_MS, MAX_ISOLATION_SENDS, MS_PER_DAY, QUEUE_DRAIN_LOCK, QUEUE_FILE_SUFFIX, QUEUE_SCAN_CURSOR_FILE, QUEUE_SWEEP_INTERVAL_MS, RE_UNSAFE_QUEUE_NAME, TREE_DEFERRED_RETRY_MS } from './constants/transport.constants.js';
10
10
  import { sendEvents } from './send.js';
11
11
  import { queueEntrySchema } from './schemas/queue.schema.js';
12
12
  export { ANY_DESTINATION } from './constants/transport.constants.js';
@@ -103,10 +103,7 @@ export class EventQueue {
103
103
  const collected = await this.collectDue(transport, nowMs, maxBatch);
104
104
  // Oldest first among what was scanned: hash-ordered filenames would
105
105
  // otherwise let a large backlog defer the same late-sorting entries.
106
- const batch = collected.due
107
- .slice()
108
- .sort((a, b) => Date.parse(a.entry.firstQueuedAt) - Date.parse(b.entry.firstQueuedAt))
109
- .slice(0, maxBatch);
106
+ const batch = treesLastAndAlone(collected.due.slice().sort((a, b) => Date.parse(a.entry.firstQueuedAt) - Date.parse(b.entry.firstQueuedAt)), maxBatch);
110
107
  const sent = batch.length === 0 ? EMPTY_DELTA : await this.sendBatch(transport, batch, nowMs, authBlock);
111
108
  const stats = { ...mergeDeltas(mergeDeltas(swept, collected.delta), sent), skipped: false };
112
109
  await report(statsRecorder, stats);
@@ -323,8 +320,16 @@ export class EventQueue {
323
320
  await authBlock?.clear();
324
321
  return { ...EMPTY_DELTA, sent: batch.length, rejected: reportRejected(result.counters?.rejected, 'the drained batch') };
325
322
  }
326
- if (result.deferred)
323
+ if (result.deferred) {
324
+ // A tree the budget cut short would be cut short again on the next hook,
325
+ // re-uploading megabytes on a slow link every time: postpone it, without
326
+ // spending an attempt, since nothing was wrong with it.
327
+ const [only] = batch;
328
+ if (batch.length === 1 && only && isTreeEntry(only)) {
329
+ await writeFileAtomic(only.file, JSON.stringify({ ...only.entry, nextAttemptAt: new Date(nowMs + TREE_DEFERRED_RETRY_MS).toISOString() }), SECRET_FILE_MODE);
330
+ }
327
331
  return { ...EMPTY_DELTA, failed: batch.length };
332
+ }
328
333
  debugLog('queue drain failed', result.error ?? `status ${result.status}`);
329
334
  if (result.status !== undefined && AUTH_REJECTED_STATUSES.has(result.status)) {
330
335
  // The credential was refused, so nothing in this batch is at fault and
@@ -517,6 +522,35 @@ function mergeDeltas(left, right) {
517
522
  rejected: left.rejected + right.rejected
518
523
  };
519
524
  }
525
+ /**
526
+ * The batch one pass sends: everything else first, and a `repo.tree` only
527
+ * alone, when nothing else is due.
528
+ *
529
+ * A tree is up to 4 MiB on its own and the gateway refuses a body over 8 MiB
530
+ * without retry, so two trees, or one beside a backlog, could lose a whole
531
+ * batch. Last, not first: a tree that keeps deferring on a slow link would
532
+ * otherwise sit at the head and starve the spend records behind it, and a
533
+ * catalog tree is never as urgent as a turn.
534
+ *
535
+ * @param ordered - Due entries, oldest first.
536
+ * @param maxBatch - Ceiling on the batch.
537
+ * @returns The entries to send now.
538
+ */
539
+ function treesLastAndAlone(ordered, maxBatch) {
540
+ const others = ordered.filter((due) => !isTreeEntry(due));
541
+ if (others.length > 0)
542
+ return others.slice(0, maxBatch);
543
+ return ordered.slice(0, 1);
544
+ }
545
+ /**
546
+ * Whether a queued entry is a `repo.tree`, the one record large enough to be batched on its own.
547
+ *
548
+ * @param due - A due entry.
549
+ * @returns True for a tree.
550
+ */
551
+ function isTreeEntry(due) {
552
+ return due.entry.event.event?.type === 'repo.tree';
553
+ }
520
554
  /**
521
555
  * Log events the backend permanently refused inside an accepted batch.
522
556
  *
@@ -46,22 +46,21 @@ export function buildTurnSummary(input) {
46
46
  branch: input.git?.branch,
47
47
  commit: input.git?.commit,
48
48
  jira_ids: jiraIds.length > 0 ? jiraIds : undefined,
49
- prompt_jira_ids: input.promptJiraIds?.length ? input.promptJiraIds : undefined,
49
+ // Only the first is read (bridge-live), so only the first is sent.
50
+ prompt_jira_ids: input.promptJiraIds?.length ? input.promptJiraIds.slice(0, 1) : undefined,
50
51
  files_changed: input.git?.changedFiles,
51
52
  work_evidence: input.git?.repository ? input.workEvidence : undefined,
52
53
  parent_session_id: input.parentSessionId,
53
- content_hashes: input.contentHashes?.length ? input.contentHashes : undefined,
54
+ content_hashes: input.contentHashes?.length ? input.contentHashes.map(({ blob_sha }) => ({ blob_sha })) : undefined,
54
55
  manifest_repository: input.manifestRepository,
55
56
  files_touched: files.filesTouched.length > 0 ? files.filesTouched : undefined,
56
57
  files_read: files.filesRead.length > 0 ? files.filesRead : undefined,
57
58
  external_files_touched: files.externalTouched.length > 0 ? files.externalTouched : undefined,
58
59
  external_files_read: files.externalRead.length > 0 ? files.externalRead : undefined,
59
- prompt_evidence: input.prompts[0]?.evidence,
60
60
  prompt_text: input.prompts[0]?.text,
61
61
  session_name: boundSessionTitle(input.sessionTitles?.custom),
62
62
  session_title: boundSessionTitle(input.sessionTitles?.generated),
63
63
  tool_inputs: files.toolInputs.length > 0 ? files.toolInputs : undefined,
64
- response_evidence: input.response,
65
64
  tool_calls: input.tools.length,
66
65
  tools_used: files.toolsUsed,
67
66
  tool_events: input.toolEvents?.length ? input.toolEvents : undefined,
@@ -59,7 +59,7 @@ export interface TurnSummaryEvent extends AgentWatchEvent<'turn.summary'> {
59
59
  readonly branch?: string;
60
60
  readonly commit?: string;
61
61
  readonly jira_ids?: readonly string[];
62
- /** Ticket keys the session's opening prompt named, in order; the same on every turn of the session. Under `capture.git`. */
62
+ /** The first ticket key the session's opening prompt named; the same on every turn of the session. Under `capture.git`. At most one. */
63
63
  readonly prompt_jira_ids?: readonly string[];
64
64
  /** The files this turn changed in its checkout: its edits, its commits' files, its new dirt. */
65
65
  readonly files_changed?: readonly string[];
@@ -67,8 +67,8 @@ export interface TurnSummaryEvent extends AgentWatchEvent<'turn.summary'> {
67
67
  readonly work_evidence?: WorkEvidence;
68
68
  /** The session id of the agent that started this one: declared by its launcher, or the live parent an `inherited` checkout came from. */
69
69
  readonly parent_session_id?: string;
70
- /** One-way content ids of files the turn's tools named, in a folder with no git; under `capture.files`. */
71
- readonly content_hashes?: readonly ContentHash[];
70
+ /** One-way content ids (git blob ids) of files the turn's tools named, in a folder with no git, without their paths; under `capture.files`. */
71
+ readonly content_hashes?: readonly Pick<ContentHash, 'blob_sha'>[];
72
72
  /** The repository address the nearest project manifest names, cleaned like a git remote; under `capture.files`. */
73
73
  readonly manifest_repository?: string;
74
74
  /** Files edited by the agent's tools during this turn (repo-relative). */
@@ -79,7 +79,6 @@ export interface TurnSummaryEvent extends AgentWatchEvent<'turn.summary'> {
79
79
  readonly external_files_touched?: readonly string[];
80
80
  /** Files outside every checkout the turn's tools only read, home-relative. */
81
81
  readonly external_files_read?: readonly string[];
82
- readonly prompt_evidence?: ContentEvidence;
83
82
  /** The turn's first prompt, harness blocks removed, scrubbed, bounded; under `capture.promptText`. */
84
83
  readonly prompt_text?: string;
85
84
  /** The session's latest name, scrubbed then cut to 200; under `capture.sessionTitle`; when the provider exposes one. */
@@ -88,7 +87,6 @@ export interface TurnSummaryEvent extends AgentWatchEvent<'turn.summary'> {
88
87
  readonly session_title?: string;
89
88
  /** The turn's shell commands and connector calls, bounded; under `capture.toolInput`. */
90
89
  readonly tool_inputs?: readonly ToolInputSummary[];
91
- readonly response_evidence?: ContentEvidence;
92
90
  readonly tool_calls: number;
93
91
  readonly tools_used: Readonly<Record<string, number>>;
94
92
  /** The turn's first 200 tool calls in call order, content-free; under `capture.git` (AWT-675). */
@@ -12,10 +12,11 @@ require root, proxy model requests, or enforce an administrator-proof policy.
12
12
  ## Defaults and upgrade consent
13
13
 
14
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.
15
+ By default nothing about a prompt or response is sent: not its text, not its
16
+ length, not a digest of it. The first ticket key named in the session's opening
17
+ prompt is the one exception: it is extracted on the machine and sent as
18
+ `prompt_jira_ids` (the platform keeps it only if it knows the key); the prompt
19
+ text is not.
19
20
  There is no capture flag for response text.
20
21
 
21
22
  Prompt text, tool input and tool output bodies, and session titles, are not collected by default.
@@ -99,13 +100,15 @@ puts the totals on the turn summary; no rollout content is read into it or sent.
99
100
 
100
101
  ## Outbound records
101
102
 
102
- There are three public event types, not a raw lifecycle or tool event stream:
103
+ There are five public event types, not a raw lifecycle or tool event stream:
103
104
 
104
105
  | Type | Source and purpose |
105
106
  | --- | --- |
106
107
  | `turn.summary` | Edge hooks assemble one completed turn and send it to the events endpoint, or queue it. |
107
108
  | `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. |
108
109
  | `repo.snapshot` | Edge queues changed repository branch/commit metadata after a closed turn when Git capture is enabled. |
110
+ | `session.billing` | Edge states how the session's developer pays (`api` or `subscription`, detected from the agent's local auth state), once, when the session opens. |
111
+ | `repo.tree` | Edge queues the default branch's source file paths and top-level declaration names after a closed turn when Git and file capture are enabled, once per repository per install identity. Never file contents. |
109
112
 
110
113
  Generated records share `schemaVersion`, `id`, `timestamp`, `event.type`,
111
114
  `event.providerEventType`, `agent.provider`, `agent.name`, session identifiers,
@@ -117,21 +120,25 @@ availability determines which identifiers and usage values exist.
117
120
  The hook-generated flat fields are `provider`, `surface`, `session_id`, `turn_id`,
118
121
  `developer_id`, `repository`, `branch`, `commit`, `jira_ids`, `prompt_jira_ids`, `work_evidence`,
119
122
  `parent_session_id`, `content_hashes`, `manifest_repository`, `files_changed`, `files_touched`, `files_read`, `external_files_touched`,
120
- `external_files_read`, `prompt_evidence`, `prompt_text`, `session_name`, `session_title`, `tool_inputs`, `response_evidence`,
123
+ `external_files_read`, `prompt_text`, `session_name`, `session_title`, `tool_inputs`,
121
124
  `tool_calls`, `tools_used`, `tool_events`, `model`, `billing_mode`, `input_tokens`,
122
125
  `cached_input_tokens`, `cache_creation_input_tokens`, `output_tokens`,
123
126
  `usage_status`, `started_at`, and `ended_at`. The nested `session` contains `id`,
124
127
  `providerId`, and optionally `turnId`.
125
128
 
126
- `prompt_jira_ids` are the ticket keys (same syntax as the branch keys in `jira_ids`)
127
- found in the session's opening prompt, extracted on the machine and sent on every
128
- turn at every tier, with no consent step. Only the keys are sent, never the prompt
129
- text. `capture.git: false` withholds them, as it does `jira_ids`.
129
+ `prompt_jira_ids` holds the first ticket key (same syntax as the branch keys in
130
+ `jira_ids`) found in the session's opening prompt, extracted on the machine and
131
+ sent on every turn at every tier, with no consent step: at most one key, since
132
+ the platform reads only the first. Never the prompt text. `capture.git: false`
133
+ withholds it, as it does `jira_ids`. A prompt's length and SHA-256 are not sent
134
+ (older releases sent them as `prompt_evidence` and `response_evidence`; a summary
135
+ they queued loses them at delivery).
130
136
 
131
137
  A prompt is free text, so a string like `INV-204391`, `MRN-123456` or `UTF-8`
132
- matches the key syntax too. The edge sends every candidate unfiltered, in order,
133
- deduplicated and capped at 50; the platform matches them against the keys it knows
134
- (branch names, connected trackers) and ignores the rest, so an unknown key is inert.
138
+ matches the key syntax too. The edge keeps the candidates on the machine in
139
+ order, deduplicated and capped at 50, and sends the first; the platform matches it
140
+ against the keys it knows (branch names, connected trackers) and ignores it
141
+ otherwise, so an unknown key is inert.
135
142
 
136
143
  On the machine the keys are kept in `prompt-tickets.json` in the session's local
137
144
  turn state (mode 0600): keys only, written once by the opening prompt, and an
@@ -142,10 +149,8 @@ every key the prompt named. The 24-hour
142
149
  sweep deletes it, counted from SessionEnd, so a session resumed within a day of
143
150
  ending keeps its keys.
144
151
 
145
- No field carries response text. Evidence contains `length` and `sha256` of the
146
- text the developer typed and the agent answered; it is not raw text, but hashes
147
- and lengths can still reveal information about short or guessable text. The
148
- prompt evidence hashes the prompt as the agent reported it.
152
+ No field carries response text, and no field carries a length or a hash of the
153
+ text the developer typed or the agent answered.
149
154
 
150
155
  - `prompt_text` (only under `promptText` with consent): the turn's first prompt,
151
156
  with `<system-reminder>` blocks the agent's harness injected removed, secrets
@@ -195,9 +200,8 @@ prompt evidence hashes the prompt as the agent reported it.
195
200
  connector (MCP) call, the sha256 of its arguments as JSON. Other tools send
196
201
  none. The command and arguments are read in memory in the hook, hashed and
197
202
  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
203
+ A hash is not the text, but a hash of a short or common command (`npm test`,
204
+ `git status`) can be confirmed by anyone who hashes the same guess. The platform re-keys every stored fingerprint with a key per
201
205
  tenant, so a stored value cannot be compared across tenants or confirmed
202
206
  without that key.
203
207
  - `check`: the command is on a fixed allowlist of test, lint, typecheck and build
@@ -279,11 +283,12 @@ and [Gemini telemetry](https://geminicli.com/docs/cli/telemetry/) for provider g
279
283
 
280
284
  Snapshots contain `provider`, `surface`, `repository`, optional `developer_id`,
281
285
  `default_branch`, `captured_at`, and `branches`. Each branch has `name`,
282
- `head_sha`, optional `last_commit_at`, and `commits`; each commit has `sha`,
283
- `subject`, optional `authored_at`, and optional `files`. `files` lists the files
284
- that commit changed as `{ path, status }`: `path` is repository-relative as git
285
- names it, and `status` is git's name-status letter (`A`, `M`, `D` or `T`; a
286
- rename is sent as its delete and its add). **Names only, never file contents.**
286
+ `head_sha` and `commits`; each commit has `sha`, `subject` and optional `files`.
287
+ `files` lists the files that commit changed as `{ path }`, repository-relative as
288
+ git names it (a rename is listed as both its old and its new path). No commit or
289
+ branch times and no change-type letter are sent (older releases sent
290
+ `authored_at`, `last_commit_at` and a `status`; a snapshot they queued loses them
291
+ at delivery). **Names only, never file contents.**
287
292
  Files named like credentials (`.env`, `.env.*`, `*.pem`, `*.key`, `*.p12`, `*.pfx`,
288
293
  `id_rsa`/`id_ed25519`/`id_ecdsa`, `credentials`, `credentials.*`, `.npmrc`, `.netrc`), paths
289
294
  over 1,024 characters and paths holding control characters are left out. A
@@ -301,6 +306,51 @@ sensitive business information even though they are classified as metadata.
301
306
  Set global `capture.git: false` to disable new snapshots; already-queued snapshots
302
307
  are then discarded at delivery rather than sent.
303
308
 
309
+ ### `repo.tree`
310
+
311
+ A tree contains the same identity fields as a snapshot (`provider`, `surface`,
312
+ `repository`, optional `developer_id`), plus `captured_at`, `truncated` and
313
+ `files`. Each file is `{ path, names }`: no blob id, no tree id and no branch
314
+ name are sent. It is what a tenant with no GitHub App gets its code feature
315
+ catalog named from.
316
+
317
+ - **Which tree.** The default branch as the remote knows it (`origin/<trunk>`),
318
+ the local trunk only when that ref does not exist. Read from git's object
319
+ store (`git ls-tree`, `git grep <tree>`), never the working copy: uncommitted
320
+ files, local edits and other branches are not in it.
321
+ - **Which files.** Source files only, by extension (TS/JS, Python, Go, Ruby,
322
+ Rust, Java, Kotlin, Elixir, PHP, Dart, C#, SQL, Prisma, C/C++/Objective-C,
323
+ IDL), minus tests, fixtures, vendored, built and `node_modules` trees, docs,
324
+ migrations and `.d.ts`. Credential-named files, over-long paths and paths
325
+ with control characters are left out, as in a snapshot.
326
+ - **`names`.** The identifiers a file declares at top level, as `git grep -o`
327
+ prints the matching declaration line's head: exported TS/JS declarations,
328
+ column-0 Python and Ruby `def`/`class`/`module`, exported Go functions, Java,
329
+ Kotlin, C#, PHP, Rust and Dart type names and column-0 functions, Elixir
330
+ modules. The one string content read is a **route path** from a Nest, Express
331
+ or Spring route declaration (`'v1/invoices'`). **No function body, comment,
332
+ string literal or other code is read out of git.** A blob over 1 MiB or
333
+ binary sends no names. At most 64 names per file, 200 characters each.
334
+ - **Bounds.** At most 20,000 files and ~4 MiB per record; over a bound, files
335
+ are kept in `ls-tree` order and `truncated` is `true`.
336
+ - **When.** Once per repository per install identity: on the first closed turn
337
+ in that repository, inside the snapshot's one-second budget. Once queued, it is
338
+ never sent again for that identity — later trunk changes are not re-sent (the
339
+ files a session changes already travel in its turn summary and branch
340
+ snapshot). A re-setup with a new credential, or another account, sends it
341
+ again. A failed attempt (no trunk, listing failed, budget spent) is retried at
342
+ most hourly until the first tree is queued; the queue then retries delivery.
343
+ The snapshot state file on the machine records that the tree was sent, its
344
+ git tree id and a digest of the identity it was sent as — never the
345
+ credential; none of these is sent.
346
+ - **Consent.** Needs both `capture.git` and `capture.files`; a repository's own
347
+ `capture.files: false` stops the listing from running at all. A queued tree is
348
+ discarded at delivery when either flag is off.
349
+
350
+ Declaration and route names are identifiers chosen by developers and can reveal
351
+ product or business vocabulary, the same as file paths do; they are metadata,
352
+ not code, and run through the same secret scrubber as every record.
353
+
304
354
  Remote URL userinfo is removed before normalization. Normalization yields
305
355
  `host/org/repo`, omitting scheme, query, fragment and `.git` suffix. A SHA-256 hash
306
356
  of that normalized identity is available for Git attribution. **Repository names
@@ -436,7 +486,8 @@ blob id: the SHA-1 Git itself assigns the content (`git hash-object`). A file ov
436
486
  on both the named path and its real target; other names such as `.envrc` or
437
487
  `credentials-prod.json` are not skipped), and a file whose real path lies
438
488
  outside the session folder, symlinks included, is skipped. The summary carries up
439
- 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
489
+ to 20 `{blob_sha}` entries, without the file's path (older releases sent the path
490
+ beside it; a summary they queued loses it at delivery). 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
440
491
  sent, but a guessable file's id can still be confirmed by someone who has that
441
492
  file.
442
493
 
@@ -57,6 +57,23 @@ a ten-branch snapshot whose every branch is at the cap carries at most ~210 KB o
57
57
  25 such snapshots in one drain pass stay under the gateway's 8 MiB body limit. If the output
58
58
  ceiling (1 MiB) cuts a listing short, the commits it did not reach are sent without `files`.
59
59
 
60
+ Trunk tree in `repo.tree`, October 25, 2026: same machine. Once per repository per
61
+ install identity, the first closing hook in a repository runs `ls-tree -r -l -z` and three
62
+ `git grep -o <tree>` searches side by side (the spike's declarations as one anchored ERE,
63
+ route paths as PCRE, the extra languages over their own files), inside the snapshot's
64
+ one-second budget. Every later turn reads the snapshot state file and stops: no git
65
+ process. Five runs each, warm cache, real state file, event bytes after sanitizing:
66
+
67
+ | Repository | Source files | Names | Event bytes | First turn | Every later turn |
68
+ | --- | ---: | ---: | ---: | ---: | ---: |
69
+ | agent-watch-core | 1,704 | 6,080 | 341,340 | 195–236 ms | 0.15–0.35 ms, 0 git |
70
+ | tripPlanner | 699 | 2,372 | 141,447 | 95–180 ms | 0.15–0.28 ms, 0 git |
71
+ | agent-watch-edge | 266 | 1,366 | 55,407 | 81–142 ms | 0.12–0.14 ms, 0 git |
72
+
73
+ Anchoring matters: one search mixing anchored and unanchored patterns took ~800 ms on
74
+ agent-watch-core, because git can no longer reject a line at its first byte. A tree is
75
+ drained last and alone in its own batch, so it never shares the gateway's 8 MiB body limit.
76
+
60
77
  These are observations, not an SLA or a cross-machine comparison. At 30 samples,
61
78
  p99 is effectively the maximum. CI retains its own JSON measurements on Linux
62
79
  and macOS rather than enforcing unstable absolute timing thresholds on shared
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agent-watch-ai/edge",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "description": "Usage and cost telemetry for Claude Code, Codex, Cursor, Gemini CLI and Antigravity. No daemon, no proxy.",
5
5
  "license": "MIT",
6
6
  "type": "module",