@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
package/CHANGELOG.md CHANGED
@@ -6,6 +6,27 @@
6
6
  together from one `otel-vX.Y.Z` tag by `otel-release.yml`, at one version and
7
7
  only when both suites pass. `python-release.yml` no longer publishes alone.
8
8
 
9
+ ## 0.6.0
10
+
11
+ ### New record: `repo.tree`
12
+
13
+ Once per repository per install identity, on the first closed turn in it, the
14
+ edge sends the default branch's source file paths and their top-level
15
+ declaration and route names, read from git's object store: never file contents,
16
+ never the working copy, no blob or tree ids. It is what a tenant with no GitHub
17
+ App gets its feature catalog named from. Needs `capture.git` and
18
+ `capture.files`; `docs/DATA_HANDLING.md` lists every field. Needs a platform
19
+ that accepts `repo.tree` (AWT-680).
20
+
21
+ ### Fields nothing reads are no longer sent
22
+
23
+ `turn.summary` drops `prompt_evidence` and `response_evidence` (a prompt's and
24
+ response's length and SHA-256), sends at most one `prompt_jira_ids` key (the
25
+ platform reads only the first), and sends `content_hashes` as blob ids without
26
+ paths. `repo.snapshot` drops branch `last_commit_at`, commit `authored_at` and
27
+ each file's `status` letter. Records queued by an older release lose the same
28
+ fields at delivery. Needs a platform that accepts their absence (AWT-682).
29
+
9
30
  ## 0.5.0
10
31
 
11
32
  ### Behaviour change: turn summaries carry per-tool-call records
package/README.md CHANGED
@@ -105,10 +105,10 @@ One global file: `~/.agentwatch/config.json`, written by `agentwatch setup`.
105
105
 
106
106
  Prompt text, tool inputs, tool outputs and session titles are off by default. Turning one on takes **two** things —
107
107
  the global `contentCaptureConsent` marker *and* the individual flag. The marker alone enables
108
- nothing; a flag alone collects nothing. With all of them off a prompt or response is recorded only
109
- as a length and a SHA-256, so turn counts and cost attribution work without the text. Ticket keys
110
- named in the opening prompt are extracted on the machine and sent as `prompt_jira_ids`, unfiltered
111
- (the platform keeps only keys it knows); the prompt text is not.
108
+ nothing; a flag alone collects nothing. With all of them off nothing about a prompt or response
109
+ is sent — no text, no length, no hash — and turn counts and cost attribution still work. The first
110
+ ticket key named in the opening prompt is extracted on the machine and sent as `prompt_jira_ids`
111
+ (the platform keeps it only if it knows the key); the prompt text is not.
112
112
 
113
113
  ```json
114
114
  {
@@ -267,9 +267,10 @@ To try it locally: `BLOCK=1 npm run example` refuses every check.
267
267
 
268
268
  | Record | How | Contents |
269
269
  |---|---|---|
270
- | `turn.summary` | Edge hooks → `POST <backend>/v1/events` | One completed turn: prompt/response length and hash, tool counts, file paths (repo-relative, and home-relative outside a checkout), Git branch, ticket keys from the branch name and the opening prompt. With Git capture on, `tool_events`: per tool call its order, status, exit code, times, a sha256 fingerprint of the normalized command or connector arguments (never the text), and for a test/lint/build check over 60 s the commit and a working-tree digest. Prompt text and shell/connector inputs only when opted in. Never response text. |
270
+ | `turn.summary` | Edge hooks → `POST <backend>/v1/events` | One completed turn: tool counts, file paths (repo-relative, and home-relative outside a checkout), Git branch, ticket keys from the branch name and the first from the opening prompt. With Git capture on, `tool_events`: per tool call its order, status, exit code, times, a sha256 fingerprint of the normalized command or connector arguments (never the text), and for a test/lint/build check over 60 s the commit and a working-tree digest. Prompt text and shell/connector inputs only when opted in. Never response text. |
271
271
  | `llm.call` | The agent's own OTLP → `POST <backend>/v1/otlp/v1/logs` | Token usage, cost and latency per model request. The edge does not proxy this. |
272
272
  | `repo.snapshot` | Edge hooks, after a closed turn | Changed branch/commit metadata, including commit subjects, when Git capture is on. |
273
+ | `repo.tree` | Edge hooks, after the first closed turn in a repository, once per install identity | The default branch's source paths and top-level declaration and route names, when Git and file capture are on. Never file contents. |
273
274
 
274
275
  The backend joins `llm.call` to `turn.summary` on conversation and turn ids.
275
276
 
@@ -20,9 +20,12 @@ export declare const INTERNAL_HOOK_EVENT_TYPES: readonly ["session.started", "se
20
20
  * `session.billing` states how the session's developer pays, once, when the
21
21
  * session opens: a turn that never reaches its Stop hook has no summary to
22
22
  * carry that fact, and its calls would be priced as metered spend (AWT-476).
23
+ *
24
+ * `repo.tree` is the default branch's source paths and declaration names, once
25
+ * per repository and identity: what a tenant with no GitHub App gets its feature catalog named from.
23
26
  */
24
- export declare const PRODUCT_EVENT_TYPES: readonly ["llm.call", "turn.summary", "repo.snapshot", "session.billing"];
25
- export declare const CANONICAL_EVENT_TYPES: readonly ["session.started", "session.ended", "prompt.submitted", "tool.started", "tool.completed", "tool.failed", "permission.requested", "file.read", "file.edited", "shell.started", "shell.completed", "mcp.started", "mcp.completed", "subagent.started", "subagent.completed", "generation.completed", "compaction.started", "compaction.completed", "agent.error", "agent.other", "llm.call", "turn.summary", "repo.snapshot", "session.billing"];
27
+ export declare const PRODUCT_EVENT_TYPES: readonly ["llm.call", "turn.summary", "repo.snapshot", "session.billing", "repo.tree"];
28
+ export declare const CANONICAL_EVENT_TYPES: readonly ["session.started", "session.ended", "prompt.submitted", "tool.started", "tool.completed", "tool.failed", "permission.requested", "file.read", "file.edited", "shell.started", "shell.completed", "mcp.started", "mcp.completed", "subagent.started", "subagent.completed", "generation.completed", "compaction.started", "compaction.completed", "agent.error", "agent.other", "llm.call", "turn.summary", "repo.snapshot", "session.billing", "repo.tree"];
26
29
  /** O(1) membership for the hot path: queue drain checks this per entry. */
27
30
  export declare const PRODUCT_EVENT_TYPE_SET: ReadonlySet<string>;
28
31
  /** Canonical event types that close a turn. */
@@ -42,8 +42,11 @@ export const INTERNAL_HOOK_EVENT_TYPES = [
42
42
  * `session.billing` states how the session's developer pays, once, when the
43
43
  * session opens: a turn that never reaches its Stop hook has no summary to
44
44
  * carry that fact, and its calls would be priced as metered spend (AWT-476).
45
+ *
46
+ * `repo.tree` is the default branch's source paths and declaration names, once
47
+ * per repository and identity: what a tenant with no GitHub App gets its feature catalog named from.
45
48
  */
46
- export const PRODUCT_EVENT_TYPES = ['llm.call', 'turn.summary', 'repo.snapshot', 'session.billing'];
49
+ export const PRODUCT_EVENT_TYPES = ['llm.call', 'turn.summary', 'repo.snapshot', 'session.billing', 'repo.tree'];
47
50
  export const CANONICAL_EVENT_TYPES = [...INTERNAL_HOOK_EVENT_TYPES, ...PRODUCT_EVENT_TYPES];
48
51
  /** O(1) membership for the hot path: queue drain checks this per entry. */
49
52
  export const PRODUCT_EVENT_TYPE_SET = new Set(PRODUCT_EVENT_TYPES);
@@ -5,6 +5,7 @@
5
5
  export type { AgentWatchEvent, CanonicalEventType, ContentEvidence, EventAi, EventGit, EventIdInput, EventPatch, EventSession, EventTool, EventUsage, FeatureCandidate, InternalHookEventType, ProductEventType, UsageBillingMode, UsageSource } from './types/events.types.js';
6
6
  export type { BuildLlmCallInput, LlmCallCorrelation, LlmCallEvent, LlmCallStatus, LlmCallUsage } from './types/llm-call.types.js';
7
7
  export type { RepoSnapshotBranch, RepoSnapshotCommit, RepoSnapshotCommitFile, RepoSnapshotEvent } from './types/repo-snapshot.types.js';
8
+ export type { RepoTreeEvent, RepoTreeFile } from './types/repo-tree.types.js';
8
9
  export type { EnrichOptions, PathRewriter, PathRule } from './types/enrich.types.js';
9
10
  export type { ProductEvent } from './product-event.js';
10
11
  export { CANONICAL_EVENT_TYPES, EVENT_SCHEMA_VERSION, INTERNAL_HOOK_EVENT_TYPES, PRODUCT_EVENT_TYPES, PRODUCT_EVENT_TYPE_SET, TURN_CLOSING_EVENT_TYPE } from './constants/events.constants.js';
@@ -1,24 +1,27 @@
1
1
  import type { TurnSummaryEvent } from '../turns/types/turn-summary.types.js';
2
2
  import type { LlmCallEvent } from './types/llm-call.types.js';
3
3
  import type { RepoSnapshotEvent } from './types/repo-snapshot.types.js';
4
+ import type { RepoTreeEvent } from './types/repo-tree.types.js';
4
5
  import type { SessionBillingEvent } from './types/session-billing.types.js';
5
6
  export { PRODUCT_EVENT_TYPES } from './constants/events.constants.js';
6
7
  export type { ProductEventType } from './types/events.types.js';
7
8
  export type { LlmCallEvent, LlmCallCorrelation, LlmCallStatus } from './types/llm-call.types.js';
8
9
  export type { RepoSnapshotBranch, RepoSnapshotCommit, RepoSnapshotCommitFile, RepoSnapshotEvent } from './types/repo-snapshot.types.js';
10
+ export type { RepoTreeEvent, RepoTreeFile } from './types/repo-tree.types.js';
9
11
  export type { SessionBillingEvent } from './types/session-billing.types.js';
10
12
  export type { AgentUsageSummary, TurnSummaryEvent, TurnUsageStatus } from '../turns/types/turn-summary.types.js';
11
13
  /**
12
14
  * The complete public AgentWatch domain contract.
13
15
  *
14
- * Four record types, deliberately: `llm.call` is the lossless per-request
16
+ * Five record types, deliberately: `llm.call` is the lossless per-request
15
17
  * usage ledger, `turn.summary` is the human unit of work, `repo.snapshot`
16
- * is what the working copy says the work *is* when no tracker can be asked, and
17
- * `session.billing` is how the session's developer pays. No
18
+ * is what the working copy says the work *is* when no tracker can be asked,
19
+ * `session.billing` is how the session's developer pays, and `repo.tree` is
20
+ * what the trunk's code is called when nothing can clone it. No
18
21
  * lifecycle or tool event is public — those exist only to assemble a summary
19
22
  * locally.
20
23
  */
21
- export type ProductEvent = LlmCallEvent | TurnSummaryEvent | RepoSnapshotEvent | SessionBillingEvent;
24
+ export type ProductEvent = LlmCallEvent | TurnSummaryEvent | RepoSnapshotEvent | SessionBillingEvent | RepoTreeEvent;
22
25
  /** The least a value must look like for {@link isProductEvent} to judge it. */
23
26
  export interface EventTypeCarrier {
24
27
  readonly event?: {
@@ -1,14 +1,12 @@
1
1
  import type { AgentWatchEvent } from './events.types.js';
2
- /** One file a commit changed: the path from the repository root, and git's name-status letter. */
2
+ /** One file a commit changed: the path from the repository root. No status letter: nothing reads it. */
3
3
  export interface RepoSnapshotCommitFile {
4
4
  readonly path: string;
5
- readonly status: string;
6
5
  }
7
6
  /** One commit of a branch's delta, as the backend receives it. */
8
7
  export interface RepoSnapshotCommit {
9
8
  readonly sha: string;
10
9
  readonly subject: string;
11
- readonly authored_at?: string;
12
10
  /** Names only, never contents. Absent when the listing failed or ran out of time. */
13
11
  readonly files?: readonly RepoSnapshotCommitFile[];
14
12
  }
@@ -16,7 +14,6 @@ export interface RepoSnapshotCommit {
16
14
  export interface RepoSnapshotBranch {
17
15
  readonly name: string;
18
16
  readonly head_sha: string;
19
- readonly last_commit_at?: string;
20
17
  readonly commits: readonly RepoSnapshotCommit[];
21
18
  }
22
19
  /**
@@ -0,0 +1,24 @@
1
+ import type { AgentWatchEvent } from './events.types.js';
2
+ /** One source file of the default branch: path and top-level declaration names. Never contents. */
3
+ export interface RepoTreeFile {
4
+ readonly path: string;
5
+ readonly names: readonly string[];
6
+ }
7
+ /**
8
+ * A repository's default-branch source listing (contract: core `repoTreeSchema`).
9
+ *
10
+ * What a tenant with no GitHub App gets its code feature catalog named from:
11
+ * paths and declaration names stand in for the source nothing may clone. Sent
12
+ * once per repository per install identity; later turns cost one state read.
13
+ */
14
+ export interface RepoTreeEvent extends AgentWatchEvent<'repo.tree'> {
15
+ readonly provider: string;
16
+ readonly surface: string;
17
+ readonly repository: string;
18
+ readonly developer_id?: string;
19
+ /** When the listing was read. */
20
+ readonly captured_at: string;
21
+ /** Files or names were dropped to fit the contract's caps; core still names the tree. */
22
+ readonly truncated: boolean;
23
+ readonly files: readonly RepoTreeFile[];
24
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,71 @@
1
+ /**
2
+ * The extensions core's naming pass reads (`isNamingSourceFile`,
3
+ * agent-watch-core `packages/llm/src/naming.ts`), mirrored verbatim. Core
4
+ * filters again with the same rule, so a drifted copy costs bytes, never
5
+ * correctness.
6
+ */
7
+ export declare const TREE_SOURCE_EXTENSIONS: readonly string[];
8
+ /** And the paths it skips: tests, vendored and generated trees, docs, migrations. */
9
+ export declare const TREE_RE_SKIP: RegExp;
10
+ /**
11
+ * The declarations the spike measured (`decl-all.cjs`), as one git ERE:
12
+ * exported TS/JS declarations, column-0 Python (and Ruby) `def`/`class`, and
13
+ * exported Go funcs. Run over every source file, so the TS, Python and Go
14
+ * names are exactly what the naming result was measured on.
15
+ *
16
+ * One anchored alternation, deliberately: anchored, git skips a line at its
17
+ * first byte; mixed with an unanchored pattern every position of every line is
18
+ * tried, and agent-watch-core's search goes from ~130 ms to ~800 ms.
19
+ */
20
+ export declare const TREE_DECLARATION_PATTERN: string;
21
+ /**
22
+ * Route paths, the one string content a catalog may read: Nest decorators and
23
+ * Express routers (the spike's), and Spring mappings. PCRE, because these are
24
+ * unanchored and the platform ERE engine scans them at ~500 ms on
25
+ * agent-watch-core against ~80 ms. A git built without PCRE fails this search
26
+ * alone, and the tree goes without route names.
27
+ */
28
+ export declare const TREE_ROUTE_PATTERN: string;
29
+ /**
30
+ * Declarations of the languages the spike's patterns do not reach, run only
31
+ * over their own files so they cannot change what TS, Python or Go send:
32
+ * types (Java, Kotlin, C#, PHP, Rust, Dart, Ruby modules; indented, for C#
33
+ * namespaces and nested types), column-0 functions (Kotlin, PHP, Rust) and
34
+ * Elixir modules. Anchored, for the reason above.
35
+ */
36
+ export declare const TREE_EXTRA_DECLARATION_PATTERN: string;
37
+ /** The files the extra patterns run over. */
38
+ export declare const TREE_EXTRA_PATHSPECS: readonly string[];
39
+ /** The name a declaration match ends with: a quoted route, or the identifier. */
40
+ export declare const TREE_RE_QUOTED_NAME: RegExp;
41
+ export declare const TREE_RE_TRAILING_NAME: RegExp;
42
+ /** The schema's caps (core `REPO_TREE_LIMITS`): over them, files or names are dropped and the tree marked truncated. */
43
+ export declare const TREE_MAX_FILES = 20000;
44
+ export declare const TREE_MAX_NAMES_PER_FILE = 64;
45
+ export declare const TREE_MAX_NAME_LENGTH = 200;
46
+ /** The id's provider slot: fixed, so every agent sending one trunk derives one id. */
47
+ export declare const TREE_EVENT_ID_PROVIDER = "agent-watch-edge";
48
+ /** The contract's target for one serialized event (UTF-8 bytes), half the gateway's 8 MiB body limit. */
49
+ export declare const TREE_MAX_EVENT_BYTES: number;
50
+ /** A blob larger than this is generated or vendored: listed, but its names are not read. */
51
+ export declare const TREE_MAX_NAMED_BLOB_BYTES: number;
52
+ /**
53
+ * stdout ceiling for the listing and the name search. With `-z` an overrun
54
+ * listing cannot be salvaged (no newline to cut at), so a tree past it is
55
+ * simply not sent rather than sent partial.
56
+ */
57
+ export declare const TREE_MAX_BUFFER_BYTES: number;
58
+ /** Output this close to {@link TREE_MAX_BUFFER_BYTES} was salvaged from an overrun, not complete. */
59
+ export declare const TREE_SALVAGE_MARGIN_BYTES: number;
60
+ /** The tree object of one commit-ish, quietly absent when there is none. */
61
+ export declare function gitTreeShaArgs(ref: string): readonly string[];
62
+ /** Every entry of one tree, with blob sizes, NUL-terminated. */
63
+ export declare function gitListTreeArgs(tree: string): readonly string[];
64
+ /**
65
+ * Only the matched declaration text of every blob in one tree, never a body:
66
+ * `-o` prints the match alone, `-I` skips binaries. Line numbers and columns
67
+ * are switched off explicitly so a user's `grep.lineNumber` cannot reshape it.
68
+ * `:(top)` and `--full-name` keep a hook that runs in a subdirectory searching
69
+ * and naming the whole tree, as `ls-tree --full-tree` lists it.
70
+ */
71
+ export declare function gitDeclarationGrepArgs(tree: string, syntax: '-E' | '-P', pattern: string, pathspecs: readonly string[]): readonly string[];
@@ -0,0 +1,92 @@
1
+ /**
2
+ * The extensions core's naming pass reads (`isNamingSourceFile`,
3
+ * agent-watch-core `packages/llm/src/naming.ts`), mirrored verbatim. Core
4
+ * filters again with the same rule, so a drifted copy costs bytes, never
5
+ * correctness.
6
+ */
7
+ // prettier-ignore
8
+ export const TREE_SOURCE_EXTENSIONS = [
9
+ '.ts', '.tsx', '.js', '.mjs', '.jsm', '.vue', '.svelte', '.py', '.go', '.rb', '.rs', '.java',
10
+ '.kt', '.ex', '.exs', '.php', '.dart', '.cs', '.sql', '.prisma',
11
+ '.c', '.cc', '.cpp', '.cxx', '.h', '.hh', '.hpp', '.m', '.mm', '.idl', '.webidl'
12
+ ];
13
+ /** And the paths it skips: tests, vendored and generated trees, docs, migrations. */
14
+ export const TREE_RE_SKIP = /(^|\/)(test|tests|__tests__|e2e|spec|fixtures|node_modules|vendor|third_party|dist|build|\.github|docs?)\/|\.(test|spec|stories|d)\.[cm]?[jt]sx?$|\.md$|(^|\/)migrations?\//;
15
+ /**
16
+ * The declarations the spike measured (`decl-all.cjs`), as one git ERE:
17
+ * exported TS/JS declarations, column-0 Python (and Ruby) `def`/`class`, and
18
+ * exported Go funcs. Run over every source file, so the TS, Python and Go
19
+ * names are exactly what the naming result was measured on.
20
+ *
21
+ * One anchored alternation, deliberately: anchored, git skips a line at its
22
+ * first byte; mixed with an unanchored pattern every position of every line is
23
+ * tried, and agent-watch-core's search goes from ~130 ms to ~800 ms.
24
+ */
25
+ export const TREE_DECLARATION_PATTERN = '^('
26
+ + 'export[[:space:]]+(default[[:space:]]+)?(declare[[:space:]]+)?(abstract[[:space:]]+)?(async[[:space:]]+)?(function\\*?|class|const|let|var|interface|type|enum)[[:space:]]+[A-Za-z_$][A-Za-z0-9_$]*'
27
+ + '|(async[[:space:]]+)?(def|class)[[:space:]]+[A-Za-z_][A-Za-z0-9_]*'
28
+ + '|func[[:space:]]+(\\([^)]*\\)[[:space:]]*)?[A-Z][A-Za-z0-9_]*'
29
+ + ')';
30
+ /**
31
+ * Route paths, the one string content a catalog may read: Nest decorators and
32
+ * Express routers (the spike's), and Spring mappings. PCRE, because these are
33
+ * unanchored and the platform ERE engine scans them at ~500 ms on
34
+ * agent-watch-core against ~80 ms. A git built without PCRE fails this search
35
+ * alone, and the tree goes without route names.
36
+ */
37
+ export const TREE_ROUTE_PATTERN = '@(?:Controller|Get|Post|Put|Patch|Delete|Resolver)\\(\\s*[\'"`][^\'"`]+[\'"`]'
38
+ + '|\\b(?:router|app)\\.(?:get|post|put|patch|delete|use)\\(\\s*[\'"`][^\'"`]+[\'"`]'
39
+ + '|@(?:Get|Post|Put|Patch|Delete|Request)Mapping\\(\\s*(?:value\\s*=\\s*)?"[^"]+"';
40
+ /**
41
+ * Declarations of the languages the spike's patterns do not reach, run only
42
+ * over their own files so they cannot change what TS, Python or Go send:
43
+ * types (Java, Kotlin, C#, PHP, Rust, Dart, Ruby modules; indented, for C#
44
+ * namespaces and nested types), column-0 functions (Kotlin, PHP, Rust) and
45
+ * Elixir modules. Anchored, for the reason above.
46
+ */
47
+ export const TREE_EXTRA_DECLARATION_PATTERN = '^('
48
+ + '[[:space:]]*((public|internal|private|protected|abstract|final|sealed|static|partial|open|data|enum|annotation|inner|readonly|value|pub(\\([a-z]+\\))?)[[:space:]]+)*(class|interface|enum|record|struct|object|trait|module|mixin)[[:space:]]+[A-Za-z_][A-Za-z0-9_]*'
49
+ + '|((public|internal|private|protected|open|override|suspend|inline|static|final|abstract|async|pub(\\([a-z]+\\))?)[[:space:]]+)*(fun|function|fn)[[:space:]]+[A-Za-z_][A-Za-z0-9_]*'
50
+ + '|[[:space:]]*defmodule[[:space:]]+[A-Z][A-Za-z0-9_.]*'
51
+ + ')';
52
+ /** The files the extra patterns run over. */
53
+ export const TREE_EXTRA_PATHSPECS = ['*.java', '*.kt', '*.cs', '*.php', '*.rs', '*.dart', '*.rb', '*.ex', '*.exs'];
54
+ /** The name a declaration match ends with: a quoted route, or the identifier. */
55
+ export const TREE_RE_QUOTED_NAME = /['"`]([^'"`]+)['"`]$/;
56
+ export const TREE_RE_TRAILING_NAME = /([A-Za-z_$][\w$.]*)$/;
57
+ /** The schema's caps (core `REPO_TREE_LIMITS`): over them, files or names are dropped and the tree marked truncated. */
58
+ export const TREE_MAX_FILES = 20_000;
59
+ export const TREE_MAX_NAMES_PER_FILE = 64;
60
+ export const TREE_MAX_NAME_LENGTH = 200;
61
+ /** The id's provider slot: fixed, so every agent sending one trunk derives one id. */
62
+ export const TREE_EVENT_ID_PROVIDER = 'agent-watch-edge';
63
+ /** The contract's target for one serialized event (UTF-8 bytes), half the gateway's 8 MiB body limit. */
64
+ export const TREE_MAX_EVENT_BYTES = 4 * 1024 * 1024;
65
+ /** A blob larger than this is generated or vendored: listed, but its names are not read. */
66
+ export const TREE_MAX_NAMED_BLOB_BYTES = 1024 * 1024;
67
+ /**
68
+ * stdout ceiling for the listing and the name search. With `-z` an overrun
69
+ * listing cannot be salvaged (no newline to cut at), so a tree past it is
70
+ * simply not sent rather than sent partial.
71
+ */
72
+ export const TREE_MAX_BUFFER_BYTES = 32 * 1024 * 1024;
73
+ /** Output this close to {@link TREE_MAX_BUFFER_BYTES} was salvaged from an overrun, not complete. */
74
+ export const TREE_SALVAGE_MARGIN_BYTES = 64 * 1024;
75
+ /** The tree object of one commit-ish, quietly absent when there is none. */
76
+ export function gitTreeShaArgs(ref) {
77
+ return ['rev-parse', '--verify', '-q', `${ref}^{tree}`];
78
+ }
79
+ /** Every entry of one tree, with blob sizes, NUL-terminated. */
80
+ export function gitListTreeArgs(tree) {
81
+ return ['ls-tree', '-r', '-l', '-z', '--full-tree', tree];
82
+ }
83
+ /**
84
+ * Only the matched declaration text of every blob in one tree, never a body:
85
+ * `-o` prints the match alone, `-I` skips binaries. Line numbers and columns
86
+ * are switched off explicitly so a user's `grep.lineNumber` cannot reshape it.
87
+ * `:(top)` and `--full-name` keep a hook that runs in a subdirectory searching
88
+ * and naming the whole tree, as `ls-tree --full-tree` lists it.
89
+ */
90
+ export function gitDeclarationGrepArgs(tree, syntax, pattern, pathspecs) {
91
+ return ['grep', '-I', '-o', '-z', syntax, '--full-name', '--no-color', '--no-line-number', '--no-column', '-e', pattern, tree, '--', ...pathspecs.map((pathspec) => `:(top)${pathspec}`)];
92
+ }
@@ -92,6 +92,7 @@ export declare function repositoryIdentity(root: string, remoteRaw: string | und
92
92
  * @param timeoutMs - Kill budget.
93
93
  * @param home - HOME to read global git config (identity!) from, so tests and
94
94
  * sandboxes never pick up the developer's real one.
95
+ * @param maxBufferBytes - stdout ceiling, when the default is too small.
95
96
  * @returns Trailing-trimmed stdout, or undefined.
96
97
  */
97
98
  export declare const runGit: GitRunner;
@@ -247,13 +247,14 @@ function readOctalEscape(inner, start) {
247
247
  * @param timeoutMs - Kill budget.
248
248
  * @param home - HOME to read global git config (identity!) from, so tests and
249
249
  * sandboxes never pick up the developer's real one.
250
+ * @param maxBufferBytes - stdout ceiling, when the default is too small.
250
251
  * @returns Trailing-trimmed stdout, or undefined.
251
252
  */
252
- export const runGit = (args, cwd, timeoutMs, home) => new Promise((resolve) => {
253
+ export const runGit = (args, cwd, timeoutMs, home, maxBufferBytes = GIT_MAX_BUFFER_BYTES) => new Promise((resolve) => {
253
254
  const env = home ? { ...process.env, HOME: home, XDG_CONFIG_HOME: path.join(home, '.config') } : undefined;
254
255
  // `--no-optional-locks`, on every call the edge makes: a hook must never
255
256
  // take `index.lock` from under the agent's own `git commit` in that checkout.
256
- execFile('git', [GIT_NO_OPTIONAL_LOCKS, ...args], { cwd, timeout: timeoutMs, maxBuffer: GIT_MAX_BUFFER_BYTES, windowsHide: true, env }, (error, stdout) => {
257
+ execFile('git', [GIT_NO_OPTIONAL_LOCKS, ...args], { cwd, timeout: timeoutMs, maxBuffer: maxBufferBytes, windowsHide: true, env }, (error, stdout) => {
257
258
  // Trailing-only trim: `status --porcelain` lines carry a significant
258
259
  // leading space (" M file"); a full trim() would eat the first character
259
260
  // of the first filename.
@@ -0,0 +1,69 @@
1
+ import type { GitRunner } from './types/git.types.js';
2
+ import type { RepoTree } from './types/snapshot.types.js';
3
+ export type { RepoTree, TreeFile } from './types/snapshot.types.js';
4
+ /**
5
+ * The tree of the default branch as the remote knows it, else as the clone has it.
6
+ *
7
+ * The same rule as a branch delta: the local trunk only when `origin/<trunk>`
8
+ * is absent, never because reading it failed — a stale local `main` would
9
+ * describe a product nobody ships.
10
+ *
11
+ * @param cwd - Repository directory.
12
+ * @param defaultBranch - The trunk's name.
13
+ * @param run - Git runner.
14
+ * @returns The tree oid, or undefined when there is none or git failed.
15
+ */
16
+ export declare function resolveTreeSha(cwd: string, defaultBranch: string, run: GitRunner): Promise<string | undefined>;
17
+ /**
18
+ * Every source file of one tree with its top-level declaration names.
19
+ *
20
+ * Read from git's object store only — `ls-tree` and `git grep <tree>` — so no
21
+ * checkout state, uncommitted file or working-copy secret can reach it, and no
22
+ * body ever leaves git: `grep -o` prints the declaration text alone.
23
+ *
24
+ * Three searches run side by side: the spike's declarations and the route
25
+ * paths over every source file, and the extra languages' declarations over
26
+ * their own files only, so the TS, Python and Go names stay exactly what the
27
+ * naming result was measured on.
28
+ *
29
+ * @param cwd - Repository directory.
30
+ * @param treeSha - The tree to read.
31
+ * @param run - Git runner; the caller's budgeted one bounds every search.
32
+ * @returns The tree, or undefined when it could not be listed. A search that
33
+ * failed or found nothing leaves its files with no names; the caller tells a
34
+ * search cut short by the budget from one that matched nothing.
35
+ */
36
+ export declare function collectRepoTree(cwd: string, treeSha: string, run: GitRunner): Promise<RepoTree | undefined>;
37
+ /**
38
+ * Whether a path is source core's naming pass reads: `isNamingSourceFile`, mirrored.
39
+ *
40
+ * @param filePath - Repository-relative path.
41
+ * @returns True for a source file outside tests, vendored trees, docs and migrations.
42
+ */
43
+ export declare function isTreeSourceFile(filePath: string): boolean;
44
+ /**
45
+ * The source blobs of one `ls-tree -r -l -z` listing, in its order.
46
+ *
47
+ * Submodules (`commit`) and symlinks are not blobs worth naming and fall out of
48
+ * the record pattern; a symlink is a blob but carries a target, not code, and
49
+ * reads as one with no declarations.
50
+ *
51
+ * @param listing - The NUL-terminated listing.
52
+ * @returns Path and size per source file.
53
+ */
54
+ export declare function parseTreeListing(listing: string): {
55
+ path: string;
56
+ size: number;
57
+ }[];
58
+ /**
59
+ * Declaration names per path out of `git grep -o -z <tree>` output.
60
+ *
61
+ * A record is `<tree>:<path>\0<match>\n`. Each match ends with what it declares:
62
+ * a quoted route path, or the identifier. De-duplicated per file in first-seen
63
+ * order, the spike's searches before the extra languages'.
64
+ *
65
+ * @param output - One or more searches' output, newline-joined.
66
+ * @param prefix - `<tree>:`, which git puts before every path.
67
+ * @returns Names by path.
68
+ */
69
+ export declare function parseDeclarations(output: string, prefix: string): Map<string, string[]>;
@@ -0,0 +1,130 @@
1
+ import { GIT_TIMEOUT_MS, gitVerifyRefArgs } from './constants/git.constants.js';
2
+ import { TREE_DECLARATION_PATTERN, TREE_EXTRA_DECLARATION_PATTERN, TREE_EXTRA_PATHSPECS, TREE_MAX_BUFFER_BYTES, TREE_MAX_NAMED_BLOB_BYTES, TREE_RE_QUOTED_NAME, TREE_RE_SKIP, TREE_RE_TRAILING_NAME, TREE_ROUTE_PATTERN, TREE_SALVAGE_MARGIN_BYTES, TREE_SOURCE_EXTENSIONS, gitDeclarationGrepArgs, gitListTreeArgs, gitTreeShaArgs } from './constants/tree.constants.js';
3
+ /** `ls-tree -l` record: `<mode> <type> <sha> <size>\t<path>`. The sha is not kept: nothing reads it. */
4
+ const RE_TREE_ENTRY = /^\d+ blob ([0-9a-f]{40}|[0-9a-f]{64}) +(\d+)\t/;
5
+ /** Every source pathspec at once: `git grep` must not read what the catalog will not send. */
6
+ const SOURCE_PATHSPECS = TREE_SOURCE_EXTENSIONS.map((extension) => `*${extension}`);
7
+ /**
8
+ * The tree of the default branch as the remote knows it, else as the clone has it.
9
+ *
10
+ * The same rule as a branch delta: the local trunk only when `origin/<trunk>`
11
+ * is absent, never because reading it failed — a stale local `main` would
12
+ * describe a product nobody ships.
13
+ *
14
+ * @param cwd - Repository directory.
15
+ * @param defaultBranch - The trunk's name.
16
+ * @param run - Git runner.
17
+ * @returns The tree oid, or undefined when there is none or git failed.
18
+ */
19
+ export async function resolveTreeSha(cwd, defaultBranch, run) {
20
+ const remoteBase = `origin/${defaultBranch}`;
21
+ const remote = await run(gitTreeShaArgs(remoteBase), cwd, GIT_TIMEOUT_MS);
22
+ if (remote)
23
+ return remote;
24
+ if (await run(gitVerifyRefArgs(remoteBase), cwd, GIT_TIMEOUT_MS))
25
+ return undefined;
26
+ return run(gitTreeShaArgs(defaultBranch), cwd, GIT_TIMEOUT_MS);
27
+ }
28
+ /**
29
+ * Every source file of one tree with its top-level declaration names.
30
+ *
31
+ * Read from git's object store only — `ls-tree` and `git grep <tree>` — so no
32
+ * checkout state, uncommitted file or working-copy secret can reach it, and no
33
+ * body ever leaves git: `grep -o` prints the declaration text alone.
34
+ *
35
+ * Three searches run side by side: the spike's declarations and the route
36
+ * paths over every source file, and the extra languages' declarations over
37
+ * their own files only, so the TS, Python and Go names stay exactly what the
38
+ * naming result was measured on.
39
+ *
40
+ * @param cwd - Repository directory.
41
+ * @param treeSha - The tree to read.
42
+ * @param run - Git runner; the caller's budgeted one bounds every search.
43
+ * @returns The tree, or undefined when it could not be listed. A search that
44
+ * failed or found nothing leaves its files with no names; the caller tells a
45
+ * search cut short by the budget from one that matched nothing.
46
+ */
47
+ export async function collectRepoTree(cwd, treeSha, run) {
48
+ const listing = await run(gitListTreeArgs(treeSha), cwd, GIT_TIMEOUT_MS, undefined, TREE_MAX_BUFFER_BYTES);
49
+ if (listing === undefined)
50
+ return undefined;
51
+ const entries = parseTreeListing(listing);
52
+ if (entries.length === 0)
53
+ return { treeSha, files: [], partial: false };
54
+ const searches = await Promise.all([
55
+ run(gitDeclarationGrepArgs(treeSha, '-E', TREE_DECLARATION_PATTERN, SOURCE_PATHSPECS), cwd, GIT_TIMEOUT_MS, undefined, TREE_MAX_BUFFER_BYTES),
56
+ run(gitDeclarationGrepArgs(treeSha, '-P', TREE_ROUTE_PATTERN, SOURCE_PATHSPECS), cwd, GIT_TIMEOUT_MS, undefined, TREE_MAX_BUFFER_BYTES),
57
+ run(gitDeclarationGrepArgs(treeSha, '-E', TREE_EXTRA_DECLARATION_PATTERN, TREE_EXTRA_PATHSPECS), cwd, GIT_TIMEOUT_MS, undefined, TREE_MAX_BUFFER_BYTES)
58
+ ]);
59
+ const names = parseDeclarations(searches.join('\n'), `${treeSha}:`);
60
+ const files = [];
61
+ for (const entry of entries) {
62
+ const named = entry.size <= TREE_MAX_NAMED_BLOB_BYTES ? names.get(entry.path) : undefined;
63
+ files.push({ path: entry.path, names: named ?? [] });
64
+ }
65
+ // The runner salvages an overrun up to its last newline, so a cut listing
66
+ // looks complete: anything within a line of the ceiling is taken as cut.
67
+ const partial = [listing, ...searches].some((output) => Buffer.byteLength(output ?? '') > TREE_MAX_BUFFER_BYTES - TREE_SALVAGE_MARGIN_BYTES);
68
+ return { treeSha, files, partial };
69
+ }
70
+ /**
71
+ * Whether a path is source core's naming pass reads: `isNamingSourceFile`, mirrored.
72
+ *
73
+ * @param filePath - Repository-relative path.
74
+ * @returns True for a source file outside tests, vendored trees, docs and migrations.
75
+ */
76
+ export function isTreeSourceFile(filePath) {
77
+ return TREE_SOURCE_EXTENSIONS.some((extension) => filePath.endsWith(extension)) && !TREE_RE_SKIP.test(filePath);
78
+ }
79
+ /**
80
+ * The source blobs of one `ls-tree -r -l -z` listing, in its order.
81
+ *
82
+ * Submodules (`commit`) and symlinks are not blobs worth naming and fall out of
83
+ * the record pattern; a symlink is a blob but carries a target, not code, and
84
+ * reads as one with no declarations.
85
+ *
86
+ * @param listing - The NUL-terminated listing.
87
+ * @returns Path and size per source file.
88
+ */
89
+ export function parseTreeListing(listing) {
90
+ const entries = [];
91
+ for (const record of listing.split('\0')) {
92
+ const match = RE_TREE_ENTRY.exec(record);
93
+ if (!match)
94
+ continue;
95
+ const filePath = record.slice(match[0].length);
96
+ if (!isTreeSourceFile(filePath))
97
+ continue;
98
+ entries.push({ path: filePath, size: Number(match[2]) });
99
+ }
100
+ return entries;
101
+ }
102
+ /**
103
+ * Declaration names per path out of `git grep -o -z <tree>` output.
104
+ *
105
+ * A record is `<tree>:<path>\0<match>\n`. Each match ends with what it declares:
106
+ * a quoted route path, or the identifier. De-duplicated per file in first-seen
107
+ * order, the spike's searches before the extra languages'.
108
+ *
109
+ * @param output - One or more searches' output, newline-joined.
110
+ * @param prefix - `<tree>:`, which git puts before every path.
111
+ * @returns Names by path.
112
+ */
113
+ export function parseDeclarations(output, prefix) {
114
+ const byPath = new Map();
115
+ for (const line of output.split('\n')) {
116
+ const split = line.indexOf('\0');
117
+ if (split === -1 || !line.startsWith(prefix))
118
+ continue;
119
+ const filePath = line.slice(prefix.length, split);
120
+ const text = line.slice(split + 1);
121
+ const name = TREE_RE_QUOTED_NAME.exec(text)?.[1] ?? TREE_RE_TRAILING_NAME.exec(text)?.[1];
122
+ if (!name)
123
+ continue;
124
+ const names = byPath.get(filePath) ?? [];
125
+ if (!names.includes(name))
126
+ names.push(name);
127
+ byPath.set(filePath, names);
128
+ }
129
+ return byPath;
130
+ }
@@ -22,8 +22,11 @@ export interface GitContextOptions {
22
22
  */
23
23
  readonly rootOnly?: boolean;
24
24
  }
25
- /** Runs one git command and returns its trimmed stdout, or undefined. */
26
- export type GitRunner = (args: readonly string[], cwd: string, timeoutMs: number, home?: string) => Promise<string | undefined>;
25
+ /**
26
+ * Runs one git command and returns its trimmed stdout, or undefined.
27
+ * `maxBufferBytes` raises the stdout ceiling for the one listing that needs it (a whole tree).
28
+ */
29
+ export type GitRunner = (args: readonly string[], cwd: string, timeoutMs: number, home?: string, maxBufferBytes?: number) => Promise<string | undefined>;
27
30
  export interface GitUserEmailOptions {
28
31
  readonly timeoutMs?: number;
29
32
  readonly home?: string;
@@ -32,3 +32,15 @@ export interface CollectCommitsOptions {
32
32
  readonly defaultBranch?: string;
33
33
  readonly commitCount: number;
34
34
  }
35
+ /** One source file of a default-branch tree: its path and its top-level declaration names. */
36
+ export interface TreeFile {
37
+ readonly path: string;
38
+ readonly names: readonly string[];
39
+ }
40
+ /** One default-branch tree's source files, in `ls-tree` order, before any cap. */
41
+ export interface RepoTree {
42
+ readonly treeSha: string;
43
+ readonly files: readonly TreeFile[];
44
+ /** A listing or search reached the output ceiling and was salvaged: some files or names are missing. */
45
+ readonly partial: boolean;
46
+ }