@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.
- package/CHANGELOG.md +21 -0
- package/README.md +6 -5
- package/dist/events/constants/events.constants.d.ts +5 -2
- package/dist/events/constants/events.constants.js +4 -1
- package/dist/events/index.d.ts +1 -0
- package/dist/events/product-event.d.ts +7 -4
- package/dist/events/types/repo-snapshot.types.d.ts +1 -4
- package/dist/events/types/repo-tree.types.d.ts +24 -0
- package/dist/events/types/repo-tree.types.js +1 -0
- package/dist/git/constants/tree.constants.d.ts +71 -0
- package/dist/git/constants/tree.constants.js +92 -0
- package/dist/git/git-context.d.ts +1 -0
- package/dist/git/git-context.js +3 -2
- package/dist/git/repo-tree.d.ts +69 -0
- package/dist/git/repo-tree.js +130 -0
- package/dist/git/types/git.types.d.ts +5 -2
- package/dist/git/types/snapshot.types.d.ts +12 -0
- package/dist/pipeline/hook-pipeline.js +40 -24
- package/dist/privacy/product-capture.js +34 -5
- package/dist/snapshot/branch-selection.js +3 -1
- package/dist/snapshot/budget.js +2 -2
- package/dist/snapshot/constants/snapshot-stages.constants.d.ts +8 -0
- package/dist/snapshot/constants/snapshot-stages.constants.js +8 -0
- package/dist/snapshot/constants/snapshot.constants.d.ts +6 -0
- package/dist/snapshot/constants/snapshot.constants.js +6 -0
- package/dist/snapshot/index.d.ts +5 -0
- package/dist/snapshot/index.js +2 -0
- package/dist/snapshot/snapshot-event.d.ts +7 -0
- package/dist/snapshot/snapshot-event.js +8 -5
- package/dist/snapshot/snapshot-state.js +19 -1
- package/dist/snapshot/tree-event.d.ts +14 -0
- package/dist/snapshot/tree-event.js +91 -0
- package/dist/snapshot/tree-pipeline.d.ts +12 -0
- package/dist/snapshot/tree-pipeline.js +153 -0
- package/dist/snapshot/types/snapshot.types.d.ts +44 -1
- package/dist/transport/constants/transport.constants.d.ts +5 -0
- package/dist/transport/constants/transport.constants.js +5 -0
- package/dist/transport/queue.js +40 -6
- package/dist/turns/turn-summary.js +3 -4
- package/dist/turns/types/turn-summary.types.d.ts +3 -5
- package/docs/DATA_HANDLING.md +77 -26
- package/docs/PERFORMANCE.md +17 -0
- package/package.json +1 -1
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { RepoSnapshotEvent } from '../../events/types/repo-snapshot.types.js';
|
|
2
|
-
import type {
|
|
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;
|
package/dist/transport/queue.js
CHANGED
|
@@ -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
|
-
|
|
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
|
-
/**
|
|
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). */
|
package/docs/DATA_HANDLING.md
CHANGED
|
@@ -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
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
knows); the prompt
|
|
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
|
|
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`, `
|
|
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`
|
|
127
|
-
found in the session's opening prompt, extracted on the machine and
|
|
128
|
-
turn at every tier, with no consent step
|
|
129
|
-
text. `capture.git: false`
|
|
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
|
|
133
|
-
deduplicated and capped at 50; the platform matches
|
|
134
|
-
(branch names, connected trackers) and ignores
|
|
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
|
|
146
|
-
text the developer typed
|
|
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
|
-
|
|
199
|
-
|
|
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
|
|
283
|
-
`
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
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 `{
|
|
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
|
|
package/docs/PERFORMANCE.md
CHANGED
|
@@ -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