@agent-watch-ai/edge 0.4.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 (109) hide show
  1. package/CHANGELOG.md +50 -0
  2. package/README.md +8 -7
  3. package/SECURITY.md +1 -1
  4. package/dist/config/config-store.js +1 -1
  5. package/dist/config/repo-config.js +1 -1
  6. package/dist/config/schemas/config.schema.d.ts +93 -857
  7. package/dist/config/schemas/config.schema.js +5 -5
  8. package/dist/credentials/credentials.js +2 -2
  9. package/dist/credentials/schemas/device-api.schema.d.ts +4 -51
  10. package/dist/credentials/schemas/device-state.schema.d.ts +3 -38
  11. package/dist/events/constants/events.constants.d.ts +5 -2
  12. package/dist/events/constants/events.constants.js +4 -1
  13. package/dist/events/index.d.ts +1 -0
  14. package/dist/events/product-event.d.ts +7 -4
  15. package/dist/events/types/repo-snapshot.types.d.ts +1 -4
  16. package/dist/events/types/repo-tree.types.d.ts +24 -0
  17. package/dist/events/types/repo-tree.types.js +1 -0
  18. package/dist/git/code-state.d.ts +33 -0
  19. package/dist/git/code-state.js +44 -0
  20. package/dist/git/constants/git.constants.d.ts +6 -0
  21. package/dist/git/constants/git.constants.js +6 -0
  22. package/dist/git/constants/tree.constants.d.ts +71 -0
  23. package/dist/git/constants/tree.constants.js +92 -0
  24. package/dist/git/git-context.d.ts +1 -0
  25. package/dist/git/git-context.js +3 -2
  26. package/dist/git/index.d.ts +2 -1
  27. package/dist/git/index.js +1 -0
  28. package/dist/git/repo-tree.d.ts +69 -0
  29. package/dist/git/repo-tree.js +130 -0
  30. package/dist/git/types/git.types.d.ts +11 -2
  31. package/dist/git/types/snapshot.types.d.ts +12 -0
  32. package/dist/pipeline/hook-pipeline.js +40 -24
  33. package/dist/privacy/command-fingerprint.d.ts +42 -0
  34. package/dist/privacy/command-fingerprint.js +249 -0
  35. package/dist/privacy/constants/command-fingerprint.constants.d.ts +34 -0
  36. package/dist/privacy/constants/command-fingerprint.constants.js +38 -0
  37. package/dist/privacy/index.d.ts +3 -1
  38. package/dist/privacy/index.js +2 -0
  39. package/dist/privacy/product-capture.js +53 -6
  40. package/dist/privacy/types/privacy.types.d.ts +7 -0
  41. package/dist/providers/antigravity/antigravity.adapter.js +3 -0
  42. package/dist/providers/antigravity/schemas/antigravity.schema.d.ts +18 -492
  43. package/dist/providers/claude/claude.adapter.js +12 -1
  44. package/dist/providers/claude/constants/claude.constants.d.ts +6 -0
  45. package/dist/providers/claude/constants/claude.constants.js +6 -0
  46. package/dist/providers/claude/schemas/claude.schema.d.ts +1 -43
  47. package/dist/providers/codex/codex.adapter.js +14 -0
  48. package/dist/providers/codex/schemas/codex.schema.d.ts +1 -41
  49. package/dist/providers/cursor/cursor.adapter.js +5 -2
  50. package/dist/providers/cursor/schemas/cursor.schema.d.ts +5 -85
  51. package/dist/providers/gemini/constants/gemini.constants.d.ts +2 -0
  52. package/dist/providers/gemini/constants/gemini.constants.js +2 -0
  53. package/dist/providers/gemini/constants/gemini.otel.constants.d.ts +10 -1
  54. package/dist/providers/gemini/constants/gemini.otel.constants.js +11 -2
  55. package/dist/providers/gemini/gemini.detect.d.ts +11 -0
  56. package/dist/providers/gemini/gemini.detect.js +14 -1
  57. package/dist/providers/gemini/gemini.hooks.d.ts +3 -3
  58. package/dist/providers/gemini/gemini.hooks.js +5 -5
  59. package/dist/providers/gemini/gemini.otel.d.ts +6 -6
  60. package/dist/providers/gemini/gemini.otel.js +392 -121
  61. package/dist/providers/gemini/schemas/gemini.schema.d.ts +1 -49
  62. package/dist/providers/shared/event-builder.d.ts +17 -2
  63. package/dist/providers/shared/event-builder.js +43 -3
  64. package/dist/providers/shared/install-record.d.ts +2 -0
  65. package/dist/providers/shared/install-record.js +3 -2
  66. package/dist/providers/shared/tooling.d.ts +7 -0
  67. package/dist/providers/shared/tooling.js +10 -1
  68. package/dist/providers/shared/types/adapter.types.d.ts +18 -0
  69. package/dist/snapshot/branch-selection.js +3 -1
  70. package/dist/snapshot/budget.js +2 -2
  71. package/dist/snapshot/constants/snapshot-stages.constants.d.ts +8 -0
  72. package/dist/snapshot/constants/snapshot-stages.constants.js +8 -0
  73. package/dist/snapshot/constants/snapshot.constants.d.ts +6 -0
  74. package/dist/snapshot/constants/snapshot.constants.js +6 -0
  75. package/dist/snapshot/index.d.ts +5 -0
  76. package/dist/snapshot/index.js +2 -0
  77. package/dist/snapshot/snapshot-event.d.ts +7 -0
  78. package/dist/snapshot/snapshot-event.js +8 -5
  79. package/dist/snapshot/snapshot-state.js +19 -1
  80. package/dist/snapshot/tree-event.d.ts +14 -0
  81. package/dist/snapshot/tree-event.js +91 -0
  82. package/dist/snapshot/tree-pipeline.d.ts +12 -0
  83. package/dist/snapshot/tree-pipeline.js +153 -0
  84. package/dist/snapshot/types/snapshot.types.d.ts +44 -1
  85. package/dist/storage/schemas/storage.schema.d.ts +11 -175
  86. package/dist/storage/schemas/storage.schema.js +7 -1
  87. package/dist/transport/constants/transport.constants.d.ts +5 -0
  88. package/dist/transport/constants/transport.constants.js +5 -0
  89. package/dist/transport/queue.js +40 -6
  90. package/dist/transport/schemas/queue.schema.d.ts +1 -16
  91. package/dist/transport/schemas/queue.schema.js +1 -1
  92. package/dist/turns/constants/turns.constants.d.ts +17 -0
  93. package/dist/turns/constants/turns.constants.js +17 -0
  94. package/dist/turns/index.d.ts +3 -2
  95. package/dist/turns/index.js +1 -0
  96. package/dist/turns/tool-events.d.ts +15 -0
  97. package/dist/turns/tool-events.js +59 -0
  98. package/dist/turns/turn-state.js +2 -2
  99. package/dist/turns/turn-summary.d.ts +1 -1
  100. package/dist/turns/turn-summary.js +4 -4
  101. package/dist/turns/turn-tracker.js +138 -7
  102. package/dist/turns/types/turn-state.types.d.ts +28 -1
  103. package/dist/turns/types/turn-summary.types.d.ts +33 -5
  104. package/dist/turns/types/turn-tracker.types.d.ts +10 -0
  105. package/docs/AUDIT_PROMPT.md +11 -0
  106. package/docs/DATA_HANDLING.md +132 -33
  107. package/docs/ENTERPRISE_DEPLOYMENT.md +2 -1
  108. package/docs/PERFORMANCE.md +17 -0
  109. package/package.json +9 -8
@@ -30,52 +30,4 @@ export declare const geminiPayloadSchema: z.ZodObject<{
30
30
  last_assistant_message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
31
31
  stop_hook_active: z.ZodOptional<z.ZodBoolean>;
32
32
  denialReason: z.ZodOptional<z.ZodString>;
33
- }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
34
- hook_event_name: z.ZodOptional<z.ZodString>;
35
- session_id: z.ZodOptional<z.ZodString>;
36
- thread_id: z.ZodOptional<z.ZodString>;
37
- turn_id: z.ZodOptional<z.ZodString>;
38
- prompt_id: z.ZodOptional<z.ZodString>;
39
- transcript_path: z.ZodOptional<z.ZodString>;
40
- cwd: z.ZodOptional<z.ZodString>;
41
- permission_mode: z.ZodOptional<z.ZodString>;
42
- agent_id: z.ZodOptional<z.ZodString>;
43
- agent_type: z.ZodOptional<z.ZodString>;
44
- tool_name: z.ZodOptional<z.ZodString>;
45
- tool_use_id: z.ZodOptional<z.ZodString>;
46
- tool_input: z.ZodOptional<z.ZodUnknown>;
47
- tool_response: z.ZodOptional<z.ZodUnknown>;
48
- tool_error: z.ZodOptional<z.ZodUnknown>;
49
- prompt: z.ZodOptional<z.ZodString>;
50
- prompt_response: z.ZodOptional<z.ZodString>;
51
- source: z.ZodOptional<z.ZodString>;
52
- model: z.ZodOptional<z.ZodString>;
53
- reason: z.ZodOptional<z.ZodString>;
54
- last_assistant_message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
55
- stop_hook_active: z.ZodOptional<z.ZodBoolean>;
56
- denialReason: z.ZodOptional<z.ZodString>;
57
- }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
58
- hook_event_name: z.ZodOptional<z.ZodString>;
59
- session_id: z.ZodOptional<z.ZodString>;
60
- thread_id: z.ZodOptional<z.ZodString>;
61
- turn_id: z.ZodOptional<z.ZodString>;
62
- prompt_id: z.ZodOptional<z.ZodString>;
63
- transcript_path: z.ZodOptional<z.ZodString>;
64
- cwd: z.ZodOptional<z.ZodString>;
65
- permission_mode: z.ZodOptional<z.ZodString>;
66
- agent_id: z.ZodOptional<z.ZodString>;
67
- agent_type: z.ZodOptional<z.ZodString>;
68
- tool_name: z.ZodOptional<z.ZodString>;
69
- tool_use_id: z.ZodOptional<z.ZodString>;
70
- tool_input: z.ZodOptional<z.ZodUnknown>;
71
- tool_response: z.ZodOptional<z.ZodUnknown>;
72
- tool_error: z.ZodOptional<z.ZodUnknown>;
73
- prompt: z.ZodOptional<z.ZodString>;
74
- prompt_response: z.ZodOptional<z.ZodString>;
75
- source: z.ZodOptional<z.ZodString>;
76
- model: z.ZodOptional<z.ZodString>;
77
- reason: z.ZodOptional<z.ZodString>;
78
- last_assistant_message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
79
- stop_hook_active: z.ZodOptional<z.ZodBoolean>;
80
- denialReason: z.ZodOptional<z.ZodString>;
81
- }, z.ZodTypeAny, "passthrough">>;
33
+ }, z.core.$loose>;
@@ -1,7 +1,7 @@
1
1
  import type { UnknownRecord } from '../../core/types/core.types.js';
2
2
  import type { AgentWatchEvent, EventPatch } from '../../events/types/events.types.js';
3
- import type { BaseEventInput, CapturePolicy, ToolCallInput } from './types/adapter.types.js';
4
- export type { BaseEventInput, CapturePolicy, ToolCallInput } from './types/adapter.types.js';
3
+ import type { BaseEventInput, CapturePolicy, ToolCallEvidenceInput, ToolCallInput } from './types/adapter.types.js';
4
+ export type { BaseEventInput, CapturePolicy, ToolCallEvidenceInput, ToolCallInput } from './types/adapter.types.js';
5
5
  /**
6
6
  * The part of a canonical event every provider fills in the same way.
7
7
  *
@@ -70,6 +70,21 @@ export declare function responsePatch(response: string): EventPatch;
70
70
  * @returns The patch.
71
71
  */
72
72
  export declare function toolPatch(call: ToolCallInput, capture: CapturePolicy): EventPatch;
73
+ /**
74
+ * The content-free facts the turn keeps about one tool call (AWT-675): its
75
+ * ids, exit code, and a digest of its input. Not gated on `capture.toolInput`:
76
+ * the command or connector call is read here, in memory, hashed and dropped,
77
+ * so nothing in this block can quote it. Whether the facts leave the machine
78
+ * is `capture.git`'s, decided at the summary.
79
+ *
80
+ * A shell call is digested with core's command scheme, so the edge's record
81
+ * and the agent's own OTLP record of one call agree; a connector call is the
82
+ * sha256 of its arguments as JSON. Any other tool carries no digest.
83
+ *
84
+ * @param call - The call, as the adapter read it.
85
+ * @returns The block, or undefined when there is nothing to keep.
86
+ */
87
+ export declare function toolCallEvidence(call: ToolCallEvidenceInput): UnknownRecord | undefined;
73
88
  /**
74
89
  * Patch carrying a file path, when one is known and permitted.
75
90
  *
@@ -1,8 +1,9 @@
1
- import { compact } from '../../core/object.js';
1
+ import { asRecord, compact } from '../../core/object.js';
2
2
  import { EVENT_SCHEMA_VERSION } from '../../events/constants/events.constants.js';
3
- import { deriveEventId } from '../../events/event-id.js';
3
+ import { deriveEventId, sha256Hex } from '../../events/event-id.js';
4
4
  import { ticketKeysInText } from '../../feature/ticket-candidates.js';
5
- import { RE_HARNESS_BLOCK } from './constants/tooling.constants.js';
5
+ import { commandFingerprint, commandText } from '../../privacy/command-fingerprint.js';
6
+ import { RE_HARNESS_BLOCK, SHELL_COMMAND_KEY } from './constants/tooling.constants.js';
6
7
  import { contentEvidence, extractCommand, extractFilePath } from './tooling.js';
7
8
  /** Metadata key holding the provider's own, non-canonical fields. */
8
9
  const PROVIDER_METADATA_KEY = 'provider';
@@ -151,10 +152,49 @@ export function toolPatch(call, capture) {
151
152
  toolInput: capture.toolInput && call.input !== undefined ? call.input : undefined,
152
153
  toolOutput: capture.toolOutput && call.output !== undefined ? call.output : undefined,
153
154
  error: call.error !== undefined ? contentEvidence(JSON.stringify(call.error)) : undefined,
155
+ toolCall: toolCallEvidence(call),
154
156
  [PROVIDER_METADATA_KEY]: compact({ toolUseId: call.toolUseId, ...call.providerFields })
155
157
  })
156
158
  };
157
159
  }
160
+ /**
161
+ * The content-free facts the turn keeps about one tool call (AWT-675): its
162
+ * ids, exit code, and a digest of its input. Not gated on `capture.toolInput`:
163
+ * the command or connector call is read here, in memory, hashed and dropped,
164
+ * so nothing in this block can quote it. Whether the facts leave the machine
165
+ * is `capture.git`'s, decided at the summary.
166
+ *
167
+ * A shell call is digested with core's command scheme, so the edge's record
168
+ * and the agent's own OTLP record of one call agree; a connector call is the
169
+ * sha256 of its arguments as JSON. Any other tool carries no digest.
170
+ *
171
+ * @param call - The call, as the adapter read it.
172
+ * @returns The block, or undefined when there is nothing to keep.
173
+ */
174
+ export function toolCallEvidence(call) {
175
+ const digest = inputDigest(call);
176
+ const block = compact({
177
+ callId: call.toolUseId,
178
+ pairingKey: call.pairingKey,
179
+ inputFp: digest?.digest ?? undefined,
180
+ matchesCheck: digest?.matchesCheck === true ? true : undefined,
181
+ exitCode: call.exitCode
182
+ });
183
+ return Object.keys(block).length > 0 ? block : undefined;
184
+ }
185
+ /**
186
+ * The input digest for a shell or connector call.
187
+ *
188
+ * @param call - The call.
189
+ * @returns The digest and check match, or undefined for any other tool.
190
+ */
191
+ function inputDigest(call) {
192
+ if (call.kind === 'shell')
193
+ return commandFingerprint(call.command ?? extractCommand(call.input) ?? commandText(asRecord(call.input)?.[SHELL_COMMAND_KEY]));
194
+ if (call.kind !== 'mcp' || call.input === undefined)
195
+ return undefined;
196
+ return { digest: sha256Hex(JSON.stringify(call.input)), matchesCheck: false };
197
+ }
158
198
  /**
159
199
  * Patch carrying a file path, when one is known and permitted.
160
200
  *
@@ -60,6 +60,8 @@ interface OtelInstallRecord {
60
60
  * the old bits is what makes the change reversible.
61
61
  */
62
62
  readonly priorMode?: number;
63
+ /** What owned keys held before this tool set them; replaces the previous map. */
64
+ readonly priorValues?: Readonly<Record<string, string>>;
63
65
  }
64
66
  /**
65
67
  * Install state with one agent's native-telemetry configuration recorded.
@@ -90,7 +90,8 @@ export function withOtelInstall(state, agentId, record) {
90
90
  otelOwnedKeys: [...new Set(record.ownedKeys)],
91
91
  // First tightening wins: a second configure must not record the 0600 we
92
92
  // ourselves left behind as the file's original mode.
93
- ...(record.priorMode !== undefined && previous?.otelPriorMode === undefined ? { otelPriorMode: record.priorMode } : {})
93
+ ...(record.priorMode !== undefined && previous?.otelPriorMode === undefined ? { otelPriorMode: record.priorMode } : {}),
94
+ ...(record.priorValues ? { otelPriorValues: { ...record.priorValues } } : {})
94
95
  }
95
96
  }
96
97
  };
@@ -110,7 +111,7 @@ export function withoutOtelInstall(state, agentId) {
110
111
  ...state,
111
112
  agents: {
112
113
  ...state.agents,
113
- [agentId]: { ...omitKeys(previous, new Set(['otelConfiguredAt', 'otelPriorMode'])), otelOwnedKeys: [] }
114
+ [agentId]: { ...omitKeys(previous, new Set(['otelConfiguredAt', 'otelPriorMode', 'otelPriorValues'])), otelOwnedKeys: [] }
114
115
  }
115
116
  };
116
117
  }
@@ -44,6 +44,13 @@ export declare function parseMcpToolName(toolName: string): McpToolName;
44
44
  * @returns The key.
45
45
  */
46
46
  export declare function mcpToolKey(server: string, tool: string): string;
47
+ /**
48
+ * One tool name with its MCP server and tool withheld: `mcp__*` becomes `mcp`.
49
+ *
50
+ * @param name - A tool name as `tools_used` and `tool_events` carry it.
51
+ * @returns The name, folded when it is an MCP one.
52
+ */
53
+ export declare function foldMcpName(name: string): string;
47
54
  /**
48
55
  * Fold every `mcp__*` key of a `tools_used` map into `mcp`, keeping the count.
49
56
  *
@@ -81,6 +81,15 @@ export function parseMcpToolName(toolName) {
81
81
  export function mcpToolKey(server, tool) {
82
82
  return sanitizeText(`${MCP_TOOL_PREFIX}${server}${MCP_TOOL_SEPARATOR}${tool}`).slice(0, MAX_TOOL_KEY_LENGTH);
83
83
  }
84
+ /**
85
+ * One tool name with its MCP server and tool withheld: `mcp__*` becomes `mcp`.
86
+ *
87
+ * @param name - A tool name as `tools_used` and `tool_events` carry it.
88
+ * @returns The name, folded when it is an MCP one.
89
+ */
90
+ export function foldMcpName(name) {
91
+ return name.startsWith(MCP_TOOL_PREFIX) ? MCP_FOLDED_KEY : name;
92
+ }
84
93
  /**
85
94
  * Fold every `mcp__*` key of a `tools_used` map into `mcp`, keeping the count.
86
95
  *
@@ -90,7 +99,7 @@ export function mcpToolKey(server, tool) {
90
99
  export function foldMcpNames(toolsUsed) {
91
100
  const folded = {};
92
101
  for (const [name, count] of Object.entries(toolsUsed)) {
93
- const key = name.startsWith(MCP_TOOL_PREFIX) ? MCP_FOLDED_KEY : name;
102
+ const key = foldMcpName(name);
94
103
  folded[key] = (folded[key] ?? 0) + count;
95
104
  }
96
105
  return folded;
@@ -41,6 +41,24 @@ export interface ToolCallInput {
41
41
  readonly error?: unknown;
42
42
  /** Extra provider-specific fields for `metadata.provider`, e.g. MCP routing. */
43
43
  readonly providerFields?: UnknownRecord;
44
+ /** The shell's exit code, where the provider states one. */
45
+ readonly exitCode?: number;
46
+ /**
47
+ * Pairs a start with its completion when the agent names no call id
48
+ * (Antigravity's step index). Local turn state only; never sent as an id.
49
+ */
50
+ readonly pairingKey?: string;
51
+ }
52
+ /** What {@link toolCallEvidence} reads from one tool call. */
53
+ export interface ToolCallEvidenceInput {
54
+ readonly kind: ToolKind;
55
+ /** Raw arguments, whatever shape the provider used. */
56
+ readonly input?: unknown;
57
+ /** The command, for a provider that reports it beside the input (Cursor's shell hooks). */
58
+ readonly command?: string;
59
+ readonly toolUseId?: string;
60
+ readonly pairingKey?: string;
61
+ readonly exitCode?: number;
44
62
  }
45
63
  /** What the effective config allows to be captured. */
46
64
  export interface CapturePolicy {
@@ -62,8 +62,10 @@ export function nextSnapshotState(input, sent) {
62
62
  // deltas were never recomputed, and they would sit on the wrong base until
63
63
  // their heads happened to move.
64
64
  const described = input.refs.every((ref) => sentNames.has(ref.name));
65
+ // The tree is the tree flow's to write; a branch send carries it over untouched.
65
66
  return {
66
67
  defaultBranch: described ? input.defaultBranch : input.stored.defaultBranch,
67
- branches
68
+ branches,
69
+ ...(input.stored.tree ? { tree: input.stored.tree } : {})
68
70
  };
69
71
  }
@@ -27,11 +27,11 @@ export function remainingMs(deadline, now = Date.now) {
27
27
  * @returns A runner whose timeout is whatever is left, capped at the git default.
28
28
  */
29
29
  export function budgetedRunner(run, deadline, now = Date.now) {
30
- return async (args, cwd, timeoutMs, home) => {
30
+ return async (args, cwd, timeoutMs, home, maxBufferBytes) => {
31
31
  const left = remainingMs(deadline, now);
32
32
  if (left === 0)
33
33
  return undefined;
34
- return run(args, cwd, Math.min(timeoutMs || GIT_TIMEOUT_MS, left), home);
34
+ return run(args, cwd, Math.min(timeoutMs || GIT_TIMEOUT_MS, left), home, maxBufferBytes);
35
35
  };
36
36
  }
37
37
  /**
@@ -9,3 +9,11 @@ export declare const STOP_NOT_A_REPOSITORY = "no branches: not a repository, or
9
9
  export declare const STOP_NOTHING_CHANGED = "no branch moved and none is due a refresh";
10
10
  export declare const STOP_BUDGET_SPENT = "snapshot budget spent";
11
11
  export declare const STOP_NO_EVENT = "no snapshot event was built";
12
+ /** The tree flow's stages and stops. */
13
+ export declare const STAGE_TREE_DUE = "tree-due";
14
+ export declare const STAGE_TREE_RESOLVE = "tree-resolve";
15
+ export declare const STAGE_TREE_COLLECT = "tree-collect";
16
+ export declare const STOP_TREE_SENT = "tree already sent for this repository and identity";
17
+ export declare const STOP_TREE_NOT_DUE = "tree attempt failed within the last hour";
18
+ export declare const STOP_TREE_NO_TRUNK = "no default branch tree to list";
19
+ export declare const STOP_TREE_UNLISTED = "tree could not be listed";
@@ -9,3 +9,11 @@ export const STOP_NOT_A_REPOSITORY = 'no branches: not a repository, or it has n
9
9
  export const STOP_NOTHING_CHANGED = 'no branch moved and none is due a refresh';
10
10
  export const STOP_BUDGET_SPENT = 'snapshot budget spent';
11
11
  export const STOP_NO_EVENT = 'no snapshot event was built';
12
+ /** The tree flow's stages and stops. */
13
+ export const STAGE_TREE_DUE = 'tree-due';
14
+ export const STAGE_TREE_RESOLVE = 'tree-resolve';
15
+ export const STAGE_TREE_COLLECT = 'tree-collect';
16
+ export const STOP_TREE_SENT = 'tree already sent for this repository and identity';
17
+ export const STOP_TREE_NOT_DUE = 'tree attempt failed within the last hour';
18
+ export const STOP_TREE_NO_TRUNK = 'no default branch tree to list';
19
+ export const STOP_TREE_UNLISTED = 'tree could not be listed';
@@ -86,3 +86,9 @@ export declare const SNAPSHOT_MAX_PATH_LENGTH = 1024;
86
86
  export declare const SNAPSHOT_RE_CONTROL_CHARACTER: RegExp;
87
87
  /** Hex characters kept from the repository digest that names a state file. */
88
88
  export declare const SNAPSHOT_STATE_HASH_LENGTH = 32;
89
+ /**
90
+ * How long a repository whose `repo.tree` attempt failed (no trunk, listing
91
+ * failed, budget spent) waits before the next one. The tree is sent once per
92
+ * repository and identity; this only bounds the cost of not managing to.
93
+ */
94
+ export declare const TREE_RETRY_INTERVAL_MS: number;
@@ -87,3 +87,9 @@ export const SNAPSHOT_MAX_PATH_LENGTH = 1024;
87
87
  export const SNAPSHOT_RE_CONTROL_CHARACTER = /[\x00-\x1f\x7f]/;
88
88
  /** Hex characters kept from the repository digest that names a state file. */
89
89
  export const SNAPSHOT_STATE_HASH_LENGTH = 32;
90
+ /**
91
+ * How long a repository whose `repo.tree` attempt failed (no trunk, listing
92
+ * failed, budget spent) waits before the next one. The tree is sent once per
93
+ * repository and identity; this only bounds the cost of not managing to.
94
+ */
95
+ export const TREE_RETRY_INTERVAL_MS = 60 * 60 * 1000;
@@ -6,6 +6,9 @@
6
6
  * layer is an overlay on work items, and a team with no tracker connected has
7
7
  * none — the branches on this machine are then the only evidence that a piece
8
8
  * of work exists at all.
9
+ *
10
+ * The tree flow beside it sends the trunk's source paths and declaration names
11
+ * (`repo.tree`) once per repository and identity, for a tenant whose code nothing may clone.
9
12
  */
10
13
  export type { BuildSnapshotInput, SelectionInput, SnapshotFlowInput, SnapshotFlowState, SnapshotIdentity, SnapshotPipelineInput, SnapshotQueue, SnapshotState, SnapshotStateEntry, SnapshotStateReader } from './types/snapshot.types.js';
11
14
  export { SNAPSHOT_BRANCH_COUNT, SNAPSHOT_BUDGET_MS, SNAPSHOT_COMMITS_PER_BRANCH, SNAPSHOT_REFRESH_MS } from './constants/snapshot.constants.js';
@@ -13,4 +16,6 @@ export { nextSnapshotState, selectChangedBranches } from './branch-selection.js'
13
16
  export { budgetedRunner, remainingMs, withinBudget } from './budget.js';
14
17
  export { buildRepoSnapshot } from './snapshot-event.js';
15
18
  export { runSnapshotPipeline } from './snapshot-pipeline.js';
19
+ export { buildRepoTree } from './tree-event.js';
20
+ export { runTreePipeline } from './tree-pipeline.js';
16
21
  export { SnapshotStateStore, emptyState } from './snapshot-state.js';
@@ -3,4 +3,6 @@ export { nextSnapshotState, selectChangedBranches } from './branch-selection.js'
3
3
  export { budgetedRunner, remainingMs, withinBudget } from './budget.js';
4
4
  export { buildRepoSnapshot } from './snapshot-event.js';
5
5
  export { runSnapshotPipeline } from './snapshot-pipeline.js';
6
+ export { buildRepoTree } from './tree-event.js';
7
+ export { runTreePipeline } from './tree-pipeline.js';
6
8
  export { SnapshotStateStore, emptyState } from './snapshot-state.js';
@@ -15,3 +15,10 @@ import type { BuildSnapshotInput } from './types/snapshot.types.js';
15
15
  * @returns The snapshot event.
16
16
  */
17
17
  export declare function buildRepoSnapshot(input: BuildSnapshotInput): RepoSnapshotEvent;
18
+ /**
19
+ * Whether a path may be named at all: not over-long, no control characters, not a credential file.
20
+ *
21
+ * @param filePath - Repository-relative path.
22
+ * @returns True when the path may be sent.
23
+ */
24
+ export declare function sendable(filePath: string): boolean;
@@ -49,11 +49,9 @@ export function buildRepoSnapshot(input) {
49
49
  return compact({
50
50
  name: branch.name,
51
51
  head_sha: branch.headSha,
52
- last_commit_at: branch.lastCommitAt,
53
52
  commits: branch.commits.map((commit, index) => compact({
54
53
  sha: commit.sha,
55
54
  subject: commit.subject.slice(0, SNAPSHOT_MAX_SUBJECT_LENGTH),
56
- authored_at: commit.authoredAt,
57
55
  files: files[index]
58
56
  }))
59
57
  });
@@ -84,15 +82,20 @@ function branchFiles(commits) {
84
82
  continue;
85
83
  files -= 1;
86
84
  bytes -= size;
87
- kept.push(file);
85
+ kept.push({ path: file.path });
88
86
  }
89
87
  // Empty only when git listed nothing: a commit whose every file was withheld
90
88
  // or capped did change something, and an empty list would say it had not.
91
89
  return kept.length > 0 || commit.files?.length === 0 ? kept : undefined;
92
90
  });
93
91
  }
94
- /** Whether a path may be named at all: not over-long, no control characters, not a credential file. */
95
- function sendable(filePath) {
92
+ /**
93
+ * Whether a path may be named at all: not over-long, no control characters, not a credential file.
94
+ *
95
+ * @param filePath - Repository-relative path.
96
+ * @returns True when the path may be sent.
97
+ */
98
+ export function sendable(filePath) {
96
99
  return filePath.length <= SNAPSHOT_MAX_PATH_LENGTH && !SNAPSHOT_RE_CONTROL_CHARACTER.test(filePath) && !RE_SECRET_FILE.test(path.posix.basename(filePath));
97
100
  }
98
101
  /**
@@ -42,7 +42,8 @@ export class SnapshotStateStore {
42
42
  return emptyState();
43
43
  return {
44
44
  defaultBranch: typeof record.defaultBranch === 'string' ? record.defaultBranch : undefined,
45
- branches: readEntries(record.branches)
45
+ branches: readEntries(record.branches),
46
+ tree: readTree(record.tree)
46
47
  };
47
48
  }
48
49
  /**
@@ -90,6 +91,23 @@ function readEntries(value) {
90
91
  }
91
92
  return entries;
92
93
  }
94
+ /**
95
+ * The tree entry out of a stored record, or none when malformed.
96
+ *
97
+ * @param value - The `tree` field as read from disk.
98
+ * @returns The entry, or undefined.
99
+ */
100
+ function readTree(value) {
101
+ const record = asRecord(value);
102
+ if (!record)
103
+ return undefined;
104
+ return {
105
+ sha: typeof record.sha === 'string' ? record.sha : undefined,
106
+ sentAt: typeof record.sentAt === 'number' ? record.sentAt : undefined,
107
+ sentFor: typeof record.sentFor === 'string' ? record.sentFor : undefined,
108
+ triedAt: typeof record.triedAt === 'number' ? record.triedAt : undefined
109
+ };
110
+ }
93
111
  /**
94
112
  * The state of a repository nothing has been sent for.
95
113
  *
@@ -0,0 +1,14 @@
1
+ import type { RepoTreeEvent } from '../events/types/repo-tree.types.js';
2
+ import type { BuildTreeInput } from './types/snapshot.types.js';
3
+ /**
4
+ * Build the record one default-branch tree becomes.
5
+ *
6
+ * The id is the repository and what is sent — each path with its names,
7
+ * sorted — and nothing else, not the agent: a retry, or a second developer or
8
+ * agent sending the same trunk, is the same record, and the gateway
9
+ * deduplicates it. Core identifies a tree the same way; no git oid is sent.
10
+ *
11
+ * @param input - Identity and the tree.
12
+ * @returns The tree event, within the contract's caps.
13
+ */
14
+ export declare function buildRepoTree(input: BuildTreeInput): RepoTreeEvent;
@@ -0,0 +1,91 @@
1
+ import { deriveEventId, sha256Hex } from '../events/event-id.js';
2
+ import { EVENT_SCHEMA_VERSION } from '../events/constants/events.constants.js';
3
+ import { TREE_EVENT_ID_PROVIDER, TREE_MAX_EVENT_BYTES, TREE_MAX_FILES, TREE_MAX_NAME_LENGTH, TREE_MAX_NAMES_PER_FILE } from '../git/constants/tree.constants.js';
4
+ import { compact } from '../core/object.js';
5
+ import { sendable } from './snapshot-event.js';
6
+ /**
7
+ * Build the record one default-branch tree becomes.
8
+ *
9
+ * The id is the repository and what is sent — each path with its names,
10
+ * sorted — and nothing else, not the agent: a retry, or a second developer or
11
+ * agent sending the same trunk, is the same record, and the gateway
12
+ * deduplicates it. Core identifies a tree the same way; no git oid is sent.
13
+ *
14
+ * @param input - Identity and the tree.
15
+ * @returns The tree event, within the contract's caps.
16
+ */
17
+ export function buildRepoTree(input) {
18
+ const { identity, tree } = input;
19
+ const capped = capFiles(tree.files);
20
+ return compact({
21
+ schemaVersion: EVENT_SCHEMA_VERSION,
22
+ id: deriveEventId({
23
+ provider: TREE_EVENT_ID_PROVIDER,
24
+ providerEventType: 'repo.tree',
25
+ payloadFingerprint: contentFingerprint(identity.repository, capped.files)
26
+ }),
27
+ timestamp: identity.capturedAt,
28
+ event: { type: 'repo.tree', providerEventType: 'repo.tree' },
29
+ agent: { provider: identity.provider, name: identity.agentName },
30
+ session: { id: identity.sessionId, providerId: identity.sessionId },
31
+ developer: identity.installationId ? { installationId: identity.installationId } : undefined,
32
+ provider: identity.provider,
33
+ surface: identity.surface,
34
+ repository: identity.repository,
35
+ developer_id: identity.developerId,
36
+ captured_at: identity.capturedAt,
37
+ truncated: capped.truncated || tree.partial,
38
+ files: capped.files
39
+ });
40
+ }
41
+ /**
42
+ * The files one event carries, in `ls-tree` order, within the schema's caps.
43
+ *
44
+ * Over a cap the contract says stop adding and mark the tree truncated: core
45
+ * still names it, and a name it never saw costs less than a 413, which loses
46
+ * the whole tree. A withheld path (credential-named, over-long) is not a
47
+ * truncation — it would never be sent.
48
+ *
49
+ * @param files - The tree's source files.
50
+ * @returns The files to send and whether any were cut.
51
+ */
52
+ function capFiles(files) {
53
+ const kept = [];
54
+ let bytes = 0;
55
+ let truncated = false;
56
+ for (const file of files) {
57
+ if (!sendable(file.path))
58
+ continue;
59
+ const names = capNames(file.names);
60
+ const entry = { path: file.path, names: names.names };
61
+ const size = Buffer.byteLength(JSON.stringify(entry)) + 1;
62
+ if (kept.length === TREE_MAX_FILES || bytes + size > TREE_MAX_EVENT_BYTES)
63
+ return { files: kept, truncated: true };
64
+ truncated ||= names.truncated;
65
+ bytes += size;
66
+ kept.push(entry);
67
+ }
68
+ return { files: kept, truncated };
69
+ }
70
+ /**
71
+ * One file's names within the schema's caps: names over the length dropped, the first 64 kept.
72
+ *
73
+ * @param names - Declaration names in first-seen order.
74
+ * @returns The names to send and whether any were dropped.
75
+ */
76
+ function capNames(names) {
77
+ const fitting = names.filter((name) => name.length <= TREE_MAX_NAME_LENGTH);
78
+ const kept = fitting.slice(0, TREE_MAX_NAMES_PER_FILE);
79
+ return { names: kept, truncated: kept.length < names.length };
80
+ }
81
+ /**
82
+ * A digest of what one tree event says: the repository and every `path:names` line, sorted.
83
+ *
84
+ * @param repository - Sanitized repository identity.
85
+ * @param files - The files the event carries.
86
+ * @returns Hex digest.
87
+ */
88
+ function contentFingerprint(repository, files) {
89
+ const lines = files.map((file) => `${file.path}:${file.names.join(',')}`).sort();
90
+ return sha256Hex([repository, ...lines].join('\n'));
91
+ }
@@ -0,0 +1,12 @@
1
+ import type { FlowResult } from '../core/types/core.types.js';
2
+ import type { TreeFlowState, TreePipelineInput } from './types/snapshot.types.js';
3
+ /**
4
+ * Send the default branch's source paths and declaration names, once per repository and identity.
5
+ *
6
+ * Shares the snapshot's deadline and never outlives it: an overrun stops
7
+ * without recording anything, so the next turn tries again. Never throws.
8
+ *
9
+ * @param pipeline - The snapshot flow's input, the state cache and the offline queue.
10
+ * @returns The final state and where the flow stopped.
11
+ */
12
+ export declare function runTreePipeline(pipeline: TreePipelineInput): Promise<FlowResult<TreeFlowState>>;