@agent-watch-ai/edge 0.7.0 → 0.7.1

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 (82) hide show
  1. package/CHANGELOG.md +69 -0
  2. package/README.md +4 -1
  3. package/dist/billing/session-billing.d.ts +5 -2
  4. package/dist/billing/session-billing.js +27 -6
  5. package/dist/capture/captured-step.js +24 -0
  6. package/dist/capture/constants/capture.constants.d.ts +15 -0
  7. package/dist/capture/constants/capture.constants.js +15 -0
  8. package/dist/capture/launched-runs.d.ts +27 -0
  9. package/dist/capture/launched-runs.js +15 -9
  10. package/dist/capture/python/sitecustomize.py +11 -2
  11. package/dist/capture/venv-loader.d.ts +68 -0
  12. package/dist/capture/venv-loader.js +189 -0
  13. package/dist/cli/constants/cli.constants.d.ts +21 -0
  14. package/dist/cli/constants/cli.constants.js +21 -0
  15. package/dist/cli/doctor-run-capture.d.ts +8 -0
  16. package/dist/cli/doctor-run-capture.js +14 -0
  17. package/dist/cli/doctor.js +6 -2
  18. package/dist/cli/hook-check.d.ts +7 -2
  19. package/dist/cli/hook-check.js +30 -15
  20. package/dist/cli/hook.js +44 -3
  21. package/dist/cli/npm-global.d.ts +24 -0
  22. package/dist/cli/npm-global.js +77 -0
  23. package/dist/cli/npx-install.js +22 -6
  24. package/dist/cli/replay.js +42 -7
  25. package/dist/cli/setup.js +47 -6
  26. package/dist/cli/uninstall.js +34 -1
  27. package/dist/cli/update.js +3 -2
  28. package/dist/config/config-store.d.ts +15 -4
  29. package/dist/config/config-store.js +31 -7
  30. package/dist/config/constants/config.constants.d.ts +8 -1
  31. package/dist/config/constants/config.constants.js +8 -1
  32. package/dist/config/schemas/config.schema.d.ts +2 -2
  33. package/dist/config/schemas/config.schema.js +10 -2
  34. package/dist/credentials/cloud-claim.d.ts +2 -0
  35. package/dist/credentials/cloud-claim.js +21 -2
  36. package/dist/credentials/constants/credentials.constants.d.ts +8 -0
  37. package/dist/credentials/constants/credentials.constants.js +8 -0
  38. package/dist/credentials/credential-status.js +1 -1
  39. package/dist/credentials/credentials.d.ts +3 -3
  40. package/dist/credentials/credentials.js +26 -12
  41. package/dist/credentials/identity.d.ts +2 -2
  42. package/dist/credentials/identity.js +2 -2
  43. package/dist/credentials/install-key.d.ts +31 -0
  44. package/dist/credentials/install-key.js +58 -0
  45. package/dist/credentials/migration.d.ts +9 -7
  46. package/dist/credentials/migration.js +58 -18
  47. package/dist/credentials/secret-store.d.ts +12 -0
  48. package/dist/credentials/secret-store.js +18 -1
  49. package/dist/enforcement/enforcement.js +1 -1
  50. package/dist/events/enrich.d.ts +14 -0
  51. package/dist/events/enrich.js +1 -1
  52. package/dist/git/constants/git.constants.d.ts +2 -0
  53. package/dist/git/constants/git.constants.js +9 -0
  54. package/dist/git/repo-snapshot.js +8 -2
  55. package/dist/git/types/snapshot.types.d.ts +4 -0
  56. package/dist/pipeline/hook-pipeline.js +2 -1
  57. package/dist/providers/claude/claude.provider.js +9 -5
  58. package/dist/providers/types/provider.types.d.ts +5 -5
  59. package/dist/replay/checkout-resolver.d.ts +41 -14
  60. package/dist/replay/checkout-resolver.js +134 -30
  61. package/dist/replay/replay-runner.d.ts +3 -1
  62. package/dist/replay/replay-runner.js +74 -22
  63. package/dist/replay/replay-scan.d.ts +2 -1
  64. package/dist/replay/replay-scan.js +14 -2
  65. package/dist/replay/throttle.d.ts +2 -1
  66. package/dist/replay/throttle.js +4 -1
  67. package/dist/replay/transcript-turns.js +29 -3
  68. package/dist/replay/turn-event.d.ts +4 -2
  69. package/dist/replay/turn-event.js +22 -11
  70. package/dist/replay/types/replay.types.d.ts +39 -3
  71. package/dist/replay/worktree-map.d.ts +42 -0
  72. package/dist/replay/worktree-map.js +134 -0
  73. package/dist/snapshot/snapshot-pipeline.js +15 -4
  74. package/dist/snapshot/types/snapshot.types.d.ts +2 -0
  75. package/dist/turns/constants/turns.constants.d.ts +16 -0
  76. package/dist/turns/constants/turns.constants.js +16 -0
  77. package/dist/turns/turn-state.d.ts +33 -0
  78. package/dist/turns/turn-state.js +80 -1
  79. package/dist/turns/turn-tracker.js +2 -2
  80. package/docs/DATA_HANDLING.md +8 -6
  81. package/docs/ENTERPRISE_DEPLOYMENT.md +2 -2
  82. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -2,6 +2,75 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ## 0.7.1
6
+
7
+ - The budget check before each turn now waits up to 500 ms for the platform's answer, up
8
+ from 300 ms. From outside the US the round trip alone took about 300 ms, so about half
9
+ the checks gave up and let the turn run unchecked. A config that still holds 300 (the
10
+ old default, which setup wrote into every config) is read as 500. Any other value you
11
+ set is kept.
12
+ - `setup --token` no longer leaves the organization install key in plain text in
13
+ `~/.agentwatch/config.json`. Once the key is exchanged for a device credential it
14
+ is kept in the same store as the device secret (keychain, DPAPI or the 0600
15
+ `credentials/` file), only to enroll again when the secret expires, and uninstall
16
+ removes it. A config written by an earlier version loses the key the next time
17
+ `agentwatch setup` runs for that machine entry or root. After uninstall, a reinstall needs the key again
18
+ (`--token` or `$AGENTWATCH_TOKEN`).
19
+ - A session's billing mode (subscription or API) is now sent for sessions started
20
+ outside a repository. When Edge looked at the processes that started the agent and
21
+ that look ran out of time or found nothing, the mode was never sent, so the calls
22
+ could show as pay per use. On a machine without project roots it is now always sent;
23
+ with roots it waits only while the look is still to be retried.
24
+ - `agentwatch setup --cloud` claims the device at the backend the managed settings block
25
+ sends usage to. Without `--endpoint` it went to `https://api.agent-watch.ai` even when
26
+ the block's `OTEL_EXPORTER_OTLP_ENDPOINT` named another gateway (a self-hosted or test
27
+ backend). It takes that gateway when the endpoint is `<gateway>/v1/otlp`, as Settings
28
+ renders it, and logs the backend before it sends the claim. The endpoint allowlist
29
+ still applies: a gateway that is not an Agent Watch host or loopback is refused, and
30
+ nothing is sent.
31
+ - `agentwatch doctor` no longer fails a healthy install on a busy machine. The check that
32
+ runs the installed hook command with `--version` now waits up to 10 s instead of 1.5 s;
33
+ under load Node alone can take about a second to start.
34
+ - `npx -y @agent-watch-ai/edge setup` and `agentwatch update` work when npm's global
35
+ folder has a UUID in its path. npm 11 prints such a segment as `***`; setup crashed
36
+ with `MODULE_NOT_FOUND` and update said Edge was not installed with `npm install -g`.
37
+ The masked segment is now found again on disk.
38
+ - A Claude Code turn ended with `/exit` or `/clear` right after its answer is no longer
39
+ lost. The background process that sends a terminal session's turn could find the
40
+ turn already deleted by the session's end; now the session end leaves its cleanup to
41
+ that process while it is still running.
42
+ - Run capture now counts a `python -I` (or `-E`) run inside a virtual environment.
43
+ Those flags make Python ignore `PYTHONPATH`, so the capture shim never loaded and
44
+ the run's spend was lost. When a coding agent runs a venv's interpreter by path
45
+ (`venv/bin/python -I run.py`), Edge leaves a one-line `agentwatch-capture.pth` in
46
+ that venv's `site-packages`. It loads the shim only when the process holds the
47
+ agent's capture `PYTHONPATH`, so the same venv run from your own terminal is
48
+ untouched. `agentwatch doctor` lists those venvs and `agentwatch uninstall`
49
+ removes the files; one it cannot remove is named, and `--purge` then keeps only
50
+ its record so a re-run can still find it. A `python -S` run, and a bare `python` resolved from an
51
+ activated venv, are still not captured.
52
+ - Replay follow-ups. A failed or denied edit no longer decides which checkout a
53
+ turn belongs to. A turn carried from an earlier edit in the same folder takes the
54
+ transcript's branch. A resumed replay still snapshots the branches an earlier leg
55
+ saw, and each group of forced branches gets its own time budget. `agentwatch replay
56
+ --stop` is heard while the worktree scan runs. With `capture.git` off, a rooted
57
+ replay runs no git over child checkouts. Setup's automatic replay ignores the
58
+ operator window variables, and an operator run names its window when it starts.
59
+ - Replay sends the checkout evidence the live hook sends. A turn's repository and
60
+ branch now come from the checkout holding most of its edits, then the session's
61
+ last changed checkout, then its folder. A deleted worktree resolves through the
62
+ `git worktree add` commands in your Claude Code transcripts. A file outside any
63
+ checkout is sent as live sends it: basename in the file lists, home-relative path
64
+ in the external lists.
65
+
66
+ - `agentwatch replay` accepts an explicit historical window through
67
+ `AGENTWATCH_OPERATOR_REPLAY_FROM` and `AGENTWATCH_OPERATOR_REPLAY_UNTIL`, for an
68
+ operator replaying a chosen period into a fresh isolated tenant. Both bounds are
69
+ required and an invalid window is refused. Such a run skips the local machine
70
+ gates and still honours backend health, refusals and rate limits. Replayed
71
+ branches are forced into repository snapshots and stay eligible after a squash
72
+ merge, and a rooted replay now indexes its direct child checkouts.
73
+
5
74
  ## 0.7.0
6
75
 
7
76
  - `agentwatch setup --agent <id>` now installs hooks into that one agent only. Before, the
package/README.md CHANGED
@@ -314,6 +314,9 @@ no Agent Watch credential yet:
314
314
  `noreply@anthropic.com`: without an account email it installs nothing and logs one line saying so.
315
315
  * It signs a claim with the key (Node's built-in Ed25519), trades it for a device of this VM's own,
316
316
  and stores it the way `setup` does. Every VM is its own device, and each refreshes on its own.
317
+ It claims at the gateway of the block's `OTEL_EXPORTER_OTLP_ENDPOINT` (`<gateway>/v1/otlp`),
318
+ or at `--endpoint` when given, and logs that backend before it sends the claim. Only Agent
319
+ Watch hosts and loopback are claimed at; any other gateway is refused and nothing is sent.
317
320
  * On `resume`, or anywhere a credential is already present, it returns at once, before `npx`
318
321
  installs anything.
319
322
  * It always exits 0: a refused claim or an unreachable Agent Watch never stops the session, and
@@ -544,7 +547,7 @@ before the agent's first LLM call, in the agent's own protocol (Claude Code, Cod
544
547
  CLI), with the backend's explanation shown to the developer.
545
548
 
546
549
  ```json
547
- { "enforcement": { "enabled": true, "timeoutMs": 300, "cacheTtlMs": 5000 } }
550
+ { "enforcement": { "enabled": true, "timeoutMs": 500, "cacheTtlMs": 5000 } }
548
551
  ```
549
552
 
550
553
  The check **fails open, always.** A turn stops only on an explicit
@@ -14,7 +14,10 @@ import type { TurnProvider } from '../turns/types/turn-provider.types.js';
14
14
  * @param provider - The agent the hook came from, for its billing reader.
15
15
  * @param env - Environment supplying HOME and the relevant variables.
16
16
  * @param surface - Product surface the session runs on.
17
+ * @param rooted - Whether this machine has project roots, the only way an
18
+ * inherited checkout can send the session to another tenant.
17
19
  * @returns The event, or undefined when the session already has one, this hook
18
- * does not open anything, or the mode cannot be told.
20
+ * does not open anything, the mode cannot be told, or (with roots) the
21
+ * session inherited a checkout or its walk is still to be retried.
19
22
  */
20
- export declare function sessionBillingFact(store: TurnStateStore, events: readonly AgentWatchEvent[], provider: TurnProvider, env: Env, surface: string): Promise<SessionBillingEvent | undefined>;
23
+ export declare function sessionBillingFact(store: TurnStateStore, events: readonly AgentWatchEvent[], provider: TurnProvider, env: Env, surface: string, rooted: boolean): Promise<SessionBillingEvent | undefined>;
@@ -2,6 +2,7 @@ import { compact } from '../core/object.js';
2
2
  import { deriveEventId } from '../events/event-id.js';
3
3
  import { EVENT_SCHEMA_VERSION } from '../events/constants/events.constants.js';
4
4
  import { CANONICAL_PROVIDER_NAMES } from '../otlp/constants/otlp.constants.js';
5
+ import { MAX_WALK_ATTEMPTS } from '../process/constants/process.constants.js';
5
6
  import { billingModeOf } from './billing-mode.js';
6
7
  /** The hooks that open a session or a turn: the earliest a collector hears from it. */
7
8
  const OPENING_TYPES = new Set(['session.started', 'prompt.submitted']);
@@ -16,10 +17,13 @@ const OPENING_TYPES = new Set(['session.started', 'prompt.submitted']);
16
17
  * @param provider - The agent the hook came from, for its billing reader.
17
18
  * @param env - Environment supplying HOME and the relevant variables.
18
19
  * @param surface - Product surface the session runs on.
20
+ * @param rooted - Whether this machine has project roots, the only way an
21
+ * inherited checkout can send the session to another tenant.
19
22
  * @returns The event, or undefined when the session already has one, this hook
20
- * does not open anything, or the mode cannot be told.
23
+ * does not open anything, the mode cannot be told, or (with roots) the
24
+ * session inherited a checkout or its walk is still to be retried.
21
25
  */
22
- export async function sessionBillingFact(store, events, provider, env, surface) {
26
+ export async function sessionBillingFact(store, events, provider, env, surface, rooted) {
23
27
  const opening = events.find((event) => OPENING_TYPES.has(event.event.type) && event.session.id);
24
28
  if (!opening?.session.id)
25
29
  return undefined;
@@ -27,10 +31,11 @@ export async function sessionBillingFact(store, events, provider, env, surface)
27
31
  // Unknown is not a fact, and must not use up the session's one send.
28
32
  if (mode === 'unknown')
29
33
  return undefined;
30
- // A session that inherited its checkout may belong to another root's tenant,
31
- // which only its turn summary resolves. Sent from here it would reach the
32
- // machine's tenant and spend the session's one send; its summary carries the mode.
33
- if (await store.readInherited(opening.session.id))
34
+ // On a machine with roots, a session that inherited its checkout may belong
35
+ // to another root's tenant, which only its turn summary resolves. Sent from
36
+ // here it would reach the machine's tenant and spend the session's one send;
37
+ // its summary carries the mode. Without roots every session is the machine's.
38
+ if (rooted && (await mayRouteElsewhere(store, opening.session.id)))
34
39
  return undefined;
35
40
  if (!(await store.takeBillingFact(opening.session.id)))
36
41
  return undefined;
@@ -50,3 +55,19 @@ export async function sessionBillingFact(store, events, provider, env, surface)
50
55
  billing_mode: mode
51
56
  });
52
57
  }
58
+ /**
59
+ * Whether the session's walk found, or may still find, a checkout to inherit.
60
+ * A memo that names a parent or a checkout did; a walk the deadline cut is
61
+ * walked again on a later hook (below MAX_WALK_ATTEMPTS), so its answer is
62
+ * awaited without spending the send. `{}` or a walk that gave up did not.
63
+ *
64
+ * @param store - Per-session state store.
65
+ * @param sessionId - Provider session id.
66
+ * @returns True when the fact should wait for the summary or a later hook.
67
+ */
68
+ async function mayRouteElsewhere(store, sessionId) {
69
+ const memo = await store.readInherited(sessionId);
70
+ if (memo?.parent !== undefined || memo?.root !== undefined)
71
+ return true;
72
+ return memo?.cuts !== undefined && memo.cuts < MAX_WALK_ATTEMPTS;
73
+ }
@@ -9,6 +9,7 @@ import { buildLlmCall } from '../events/llm-call.js';
9
9
  import { sha256Hex } from '../events/event-id.js';
10
10
  import { CANONICAL_PROVIDER_NAMES } from '../otlp/constants/otlp.constants.js';
11
11
  import { applyProductCapture } from '../privacy/product-capture.js';
12
+ import { runCaptureRoute } from '../providers/provider.js';
12
13
  import { SECRET_FILE_MODE, SWEEP_MARKER_FILE } from '../storage/constants/storage.constants.js';
13
14
  import { DeliveryStats } from '../transport/delivery-stats.js';
14
15
  import { identityPaths } from '../transport/queue-partition.js';
@@ -17,8 +18,10 @@ import { latestRunIn, RunStateStore } from '../turns/run-state.js';
17
18
  import { TurnStateStore } from '../turns/turn-state.js';
18
19
  import { resolveSurface } from '../turns/turn-tracker.js';
19
20
  import { CONSUMING_ABANDONED_MS, CONSUMING_FILE_SUFFIX, DROPPED_FILE_SUFFIX, MAX_ID_LENGTH, MAX_RECORDS_PER_HOOK, MAX_SPOOL_FILE_BYTES, RE_SCRIPT_FILE, SPOOL_DIR_NAME, SPOOL_FILE_SUFFIX, SPOOL_IDENTITY_FILE, UNNAMED_COMMAND, WIRE_CONVENTIONS } from './constants/capture.constants.js';
21
+ import { copiedShims } from './capture-env.js';
20
22
  import { runEntry } from './launched-runs.js';
21
23
  import { spoolRecordSchema } from './schemas/capture.schema.js';
24
+ import { armVenvLoaders, pythonInterpreters } from './venv-loader.js';
22
25
  const MS_PER_DAY = 86_400_000;
23
26
  const SENDS_EVERYTHING = async () => true;
24
27
  /** UTC offsets differ by quarter hours, and two zones by 26 hours at most. */
@@ -154,8 +157,29 @@ export async function armCaptureStage(state) {
154
157
  catch {
155
158
  debugLog('capture: could not arm the spool');
156
159
  }
160
+ if (identities.length > 0)
161
+ await armVenvsOfThisRun(state).catch(() => debugLog('capture: venv loaders skipped'));
157
162
  return next(state);
158
163
  }
164
+ // Before the command runs: a `venv/bin/python -I` run ignores PYTHONPATH, so its venv
165
+ // gets a loader the shim comes in through instead (`venv-loader.ts`).
166
+ async function armVenvsOfThisRun(state) {
167
+ if (!state.events.some((candidate) => candidate.event.type === 'shell.started'))
168
+ return;
169
+ const call = state.provider.shellCall?.(state.payload);
170
+ if (typeof call?.command !== 'string')
171
+ return;
172
+ const directory = typeof call.workdir === 'string' && path.isAbsolute(call.workdir) ? call.workdir : state.cwd;
173
+ const shimDir = copiedShims(state.paths.dataDir).python;
174
+ if (pythonInterpreters(call.command, directory).length === 0)
175
+ return;
176
+ // Only while this agent's route loads the copy: `otel: none`, `off`, and a route not
177
+ // yet verified (Cursor, Antigravity) leave its config without it, and the venv alone.
178
+ const config = runCaptureRoute(state.provider)?.configPath(state.env);
179
+ if (config === undefined || !(await fs.readFile(config, 'utf8').catch(() => '')).includes(shimDir))
180
+ return;
181
+ await armVenvLoaders(call.command, directory, state.paths.dataDir, shimDir);
182
+ }
159
183
  /**
160
184
  * Remember this shell call as a run, and attach what the spool holds to its runs.
161
185
  *
@@ -68,3 +68,18 @@ export declare const MAX_SPOOL_FILE_BYTES: number;
68
68
  export declare const SPOOL_IDENTITY_FILE = "captured.identity";
69
69
  /** A relative preload: kept from the shell it would run from every repository. */
70
70
  export declare const RE_RELATIVE_PRELOAD: RegExp;
71
+ /**
72
+ * The file Edge leaves in a virtual environment's site-packages, so that `python -I`,
73
+ * which ignores PYTHONPATH, still loads the shim. Python reads every `.pth` there unless
74
+ * run with `-S`.
75
+ */
76
+ export declare const VENV_LOADER_FILE = "agentwatch-capture.pth";
77
+ /** One record per venv written to, under the data dir, for uninstall and doctor. */
78
+ export declare const VENV_RECORDS_DIR = "capture-venvs";
79
+ export declare const VENV_CONFIG_FILE = "pyvenv.cfg";
80
+ export declare const VENV_LOADER_MODE = 420;
81
+ /** In every loader Edge writes, so uninstall removes only its own file. */
82
+ export declare const VENV_LOADER_MARK = "# agentwatch run capture";
83
+ export declare const RE_SITE_PACKAGES_PARENT: RegExp;
84
+ /** A path Python reads as a string literal, written as ASCII so the file's encoding never matters. */
85
+ export declare const RE_ASCII_PATH: RegExp;
@@ -70,3 +70,18 @@ export const MAX_SPOOL_FILE_BYTES = 32 * 1024 * 1024;
70
70
  export const SPOOL_IDENTITY_FILE = 'captured.identity';
71
71
  /** A relative preload: kept from the shell it would run from every repository. */
72
72
  export const RE_RELATIVE_PRELOAD = /(?:^|\s)(?:--require|--import|--loader|--experimental-loader|-r)(?:[= ]|(?=[^\s=-]))(?:"(?!\/)[^"]*"|(?!["/])\S+)/g;
73
+ /**
74
+ * The file Edge leaves in a virtual environment's site-packages, so that `python -I`,
75
+ * which ignores PYTHONPATH, still loads the shim. Python reads every `.pth` there unless
76
+ * run with `-S`.
77
+ */
78
+ export const VENV_LOADER_FILE = 'agentwatch-capture.pth';
79
+ /** One record per venv written to, under the data dir, for uninstall and doctor. */
80
+ export const VENV_RECORDS_DIR = 'capture-venvs';
81
+ export const VENV_CONFIG_FILE = 'pyvenv.cfg';
82
+ export const VENV_LOADER_MODE = 0o644;
83
+ /** In every loader Edge writes, so uninstall removes only its own file. */
84
+ export const VENV_LOADER_MARK = '# agentwatch run capture';
85
+ export const RE_SITE_PACKAGES_PARENT = /^python\d+(?:\.\d+)*t?$/;
86
+ /** A path Python reads as a string literal, written as ASCII so the file's encoding never matters. */
87
+ export const RE_ASCII_PATH = /^[\x20-\x7e]+$/;
@@ -1,3 +1,19 @@
1
+ /**
2
+ * The words of one command segment, its `VAR=value` prefixes gone unread: a value
3
+ * set on a command line is often the very key this code must never hold.
4
+ *
5
+ * @param segment - One `&&`/`;`/`|`-separated part of a command.
6
+ * @returns The words, unquoted.
7
+ */
8
+ export declare function wordsOf(segment: string): string[];
9
+ /**
10
+ * A command's `&&`/`||`/`;`/`|`/newline parts, split only outside quotes and `$(...)`:
11
+ * a separator inside a quoted value would otherwise cut that value into a "command".
12
+ *
13
+ * @param command - The shell command, read in memory only.
14
+ * @returns The parts, trimmed; never an empty one.
15
+ */
16
+ export declare function segmentsOf(command: string): string[];
1
17
  /**
2
18
  * The name a shell call's captured calls are labelled with.
3
19
  *
@@ -14,3 +30,14 @@
14
30
  * @returns The entry, or undefined for an empty command.
15
31
  */
16
32
  export declare function runEntry(command: string, directory: string, filesAllowed: boolean): Promise<string | undefined>;
33
+ /**
34
+ * The folder the chosen segment runs in. A `cd` this cannot follow (`$DIR`, `~`) ends the
35
+ * walk: the script is then named from where the walk stopped, or by its name alone.
36
+ *
37
+ * @param segments - The command's segments, from `segmentsOf`.
38
+ * @param chosen - The index of the segment whose folder is asked for: by index, as a
39
+ * command can repeat a segment after a `cd`.
40
+ * @param directory - Where the command starts.
41
+ * @returns The folder.
42
+ */
43
+ export declare function afterCds(segments: readonly string[], chosen: number, directory: string): string;
@@ -10,7 +10,7 @@ import { INLINE_FLAGS, MAX_RUN_ENTRY_LENGTH, MODULE_FLAG, RE_CD, RE_SHELL_EXPAND
10
10
  * @param segment - One `&&`/`;`/`|`-separated part of a command.
11
11
  * @returns The words, unquoted.
12
12
  */
13
- function wordsOf(segment) {
13
+ export function wordsOf(segment) {
14
14
  const raw = segment.match(RE_COMMAND_WORD) ?? [];
15
15
  const words = raw.map((word) => word.replace(RE_WORD_QUOTES, ''));
16
16
  const firstReal = words.findIndex((word) => !RE_ENV_ASSIGNMENT.test(word));
@@ -33,7 +33,7 @@ function nameOr(word) {
33
33
  * @param command - The shell command, read in memory only.
34
34
  * @returns The parts, trimmed; never an empty one.
35
35
  */
36
- function segmentsOf(command) {
36
+ export function segmentsOf(command) {
37
37
  const segments = [];
38
38
  let quote;
39
39
  let depth = 0;
@@ -126,17 +126,23 @@ export async function runEntry(command, directory, filesAllowed) {
126
126
  const namesAFile = !filesAllowed && program.name === path.basename(words[0]) && words[0].includes('/') && !RE_PYTHON.test(program.name);
127
127
  return clean(namesAFile ? UNNAMED_COMMAND : (program.name ?? (program.file === words[0] ? UNNAMED_COMMAND : nameOr(path.basename(words[0])))));
128
128
  }
129
- const absolute = path.resolve(afterCds(segments, chosen, directory), program.file);
129
+ const absolute = path.resolve(afterCds(segments, segments.indexOf(chosen), directory), program.file);
130
130
  const checkout = await checkoutOf(absolute);
131
131
  return clean(checkout && !checkout.relative.startsWith('..') ? checkout.relative : path.basename(absolute));
132
132
  }
133
- // The folder the chosen segment runs in. A `cd` this cannot follow (`$DIR`, `~`) ends the
134
- // walk: the script is then named from where the walk stopped, or by its name alone.
135
- function afterCds(segments, chosen, directory) {
133
+ /**
134
+ * The folder the chosen segment runs in. A `cd` this cannot follow (`$DIR`, `~`) ends the
135
+ * walk: the script is then named from where the walk stopped, or by its name alone.
136
+ *
137
+ * @param segments - The command's segments, from `segmentsOf`.
138
+ * @param chosen - The index of the segment whose folder is asked for: by index, as a
139
+ * command can repeat a segment after a `cd`.
140
+ * @param directory - Where the command starts.
141
+ * @returns The folder.
142
+ */
143
+ export function afterCds(segments, chosen, directory) {
136
144
  let current = directory;
137
- for (const segment of segments) {
138
- if (segment === chosen)
139
- break;
145
+ for (const segment of segments.slice(0, chosen)) {
140
146
  const target = RE_CD.exec(segment)?.[1]?.replace(RE_WORD_QUOTES, '');
141
147
  if (target === undefined)
142
148
  continue;
@@ -65,6 +65,8 @@ PS_PATHS = ("/bin/ps", "/usr/bin/ps")
65
65
  RE_WINDOWS_EXEC = re.compile(r"\.(?:exe|cmd)$", re.IGNORECASE)
66
66
 
67
67
  SPOOL_DIR = "captured"
68
+ # Set on sys once installed; its presence in a file also marks that file as a copy of this one.
69
+ LOADED_FLAG = "_agentwatch_capture_loaded"
68
70
  DISABLED_MARKER = "disabled.json"
69
71
  MAX_LINES_PER_FILE = 10000
70
72
  # Past this, a JSON or compressed body costs its usage rather than memory.
@@ -796,7 +798,11 @@ def _run_next_sitecustomize():
796
798
  candidate = os.path.join(folder, "sitecustomize.py")
797
799
  if folder != own and os.path.isfile(candidate):
798
800
  with open(candidate, "rb") as source:
799
- exec(compile(source.read(), candidate, "exec"), {"__name__": "sitecustomize", "__file__": candidate})
801
+ code = source.read()
802
+ # Another copy of this file is passed over, not run: the developer's own may come after it.
803
+ if LOADED_FLAG.encode() in code:
804
+ continue
805
+ exec(compile(code, candidate, "exec"), {"__name__": "sitecustomize", "__file__": candidate})
800
806
  return
801
807
 
802
808
 
@@ -818,6 +824,9 @@ def _replay(meta, status, headers, chunks):
818
824
  return result or None
819
825
 
820
826
 
821
- if __name__ == "sitecustomize":
827
+ # Once per process: PYTHONPATH and a venv's agentwatch-capture.pth can both load this file,
828
+ # and the sitecustomize it runs next may be another copy of it.
829
+ if __name__ == "sitecustomize" and not getattr(sys, LOADED_FLAG, False):
830
+ setattr(sys, LOADED_FLAG, True)
822
831
  _safely(_install)
823
832
  _safely(_run_next_sitecustomize)
@@ -0,0 +1,68 @@
1
+ /**
2
+ * The interpreters a shell command runs by path (`venv/bin/python -I x.py`, `cd app && .venv/bin/python3 x.py`),
3
+ * resolved against where each runs. A bare `python` is looked up on a PATH this hook cannot see, so it is left out.
4
+ *
5
+ * @param command - The shell command, read in memory only.
6
+ * @param directory - Where it runs.
7
+ * @returns Absolute interpreter paths, possibly none.
8
+ */
9
+ export declare function pythonInterpreters(command: string, directory: string): string[];
10
+ /**
11
+ * The site-packages folders of the venv an interpreter belongs to, by its `pyvenv.cfg`
12
+ * beside it or one level up. Not resolved through links: a venv's `python` links to the
13
+ * system one, whose site-packages is never ours to write.
14
+ *
15
+ * @param interpreter - The interpreter's absolute path, as the command named it.
16
+ * @returns The folders, real and inside the venv; none for an interpreter outside one.
17
+ */
18
+ export declare function venvSitePackages(interpreter: string): Promise<string[]>;
19
+ /**
20
+ * The one line Python runs from the `.pth` at startup.
21
+ *
22
+ * It acts only when Python ignored the environment (`-I`, `-E`): otherwise PYTHONPATH loads
23
+ * the shim the usual way. And only when the process's environment names the capture folder
24
+ * in PYTHONPATH, which only an agent's environment does: `-I` stops Python from reading the
25
+ * variable, not the process from holding it. The developer running the same venv from their
26
+ * own terminal gets nothing. It loads nothing itself: a one-shot finder answers site's own
27
+ * `import sitecustomize`, which comes after every `.pth`, so the shim runs the developer's
28
+ * `sitecustomize` next on the full `sys.path`. Any fault is swallowed, since site prints a
29
+ * failing `.pth` line, or a failing `sitecustomize`, into the customer's stderr.
30
+ *
31
+ * ponytail: rides on `.pth` import lines. CPython's docs for 3.15 reportedly deprecate them
32
+ * (ignored from 3.18); 3.14 still runs them silently. When they go, a `-I` run on that
33
+ * Python is uncaptured again, and the upgrade is whatever startup hook replaces them.
34
+ *
35
+ * @param shimDir - The capture copy's python folder.
36
+ * @returns The file's contents, or undefined for a path that is not plain ASCII.
37
+ */
38
+ export declare function venvLoader(shimDir: string): string | undefined;
39
+ /**
40
+ * Leave the loader in the venv of every interpreter a shell command runs by path, so a
41
+ * `python -I` run is captured too. Recorded first, so a file written is always one
42
+ * uninstall can find. Never throws: a venv it cannot write is skipped.
43
+ *
44
+ * @param command - The shell command, read in memory only.
45
+ * @param directory - Where it runs.
46
+ * @param dataDir - The data dir.
47
+ * @param shimDir - The capture copy's python folder.
48
+ * @returns The site-packages folders that now hold the loader.
49
+ */
50
+ export declare function armVenvLoaders(command: string, directory: string, dataDir: string, shimDir: string): Promise<string[]>;
51
+ /**
52
+ * The site-packages folders Edge has left a loader in, as recorded.
53
+ *
54
+ * @param dataDir - The data dir.
55
+ * @returns The folders, whether or not the loader is still there.
56
+ */
57
+ export declare function recordedVenvs(dataDir: string): Promise<string[]>;
58
+ /**
59
+ * Remove every loader Edge recorded, and its record. A file that no longer carries our
60
+ * mark is the developer's now and stays.
61
+ *
62
+ * @param dataDir - The data dir.
63
+ * @returns The folders a loader was removed from, and those whose loader could not be.
64
+ */
65
+ export declare function removeVenvLoaders(dataDir: string): Promise<{
66
+ removed: string[];
67
+ left: string[];
68
+ }>;
@@ -0,0 +1,189 @@
1
+ import { createHash } from 'node:crypto';
2
+ import fs from 'node:fs/promises';
3
+ import path from 'node:path';
4
+ import { debugLog } from '../core/logger.js';
5
+ import { writeFileAtomic } from '../storage/atomic-file.js';
6
+ import { PYTHON_SHIM_FILE, RE_ASCII_PATH, RE_PYTHON, RE_SITE_PACKAGES_PARENT, VENV_CONFIG_FILE, VENV_LOADER_FILE, VENV_LOADER_MARK, VENV_LOADER_MODE, VENV_RECORDS_DIR } from './constants/capture.constants.js';
7
+ import { afterCds, segmentsOf, wordsOf } from './launched-runs.js';
8
+ /**
9
+ * The interpreters a shell command runs by path (`venv/bin/python -I x.py`, `cd app && .venv/bin/python3 x.py`),
10
+ * resolved against where each runs. A bare `python` is looked up on a PATH this hook cannot see, so it is left out.
11
+ *
12
+ * @param command - The shell command, read in memory only.
13
+ * @param directory - Where it runs.
14
+ * @returns Absolute interpreter paths, possibly none.
15
+ */
16
+ export function pythonInterpreters(command, directory) {
17
+ const segments = segmentsOf(command);
18
+ const found = new Set();
19
+ for (const [index, segment] of segments.entries()) {
20
+ const program = wordsOf(segment)[0];
21
+ if (program === undefined || !program.includes('/') || !RE_PYTHON.test(path.basename(program)))
22
+ continue;
23
+ found.add(path.resolve(afterCds(segments, index, directory), program));
24
+ }
25
+ return [...found];
26
+ }
27
+ async function isFile(file) {
28
+ return (await fs.stat(file).catch(() => undefined))?.isFile() ?? false;
29
+ }
30
+ /**
31
+ * The site-packages folders of the venv an interpreter belongs to, by its `pyvenv.cfg`
32
+ * beside it or one level up. Not resolved through links: a venv's `python` links to the
33
+ * system one, whose site-packages is never ours to write.
34
+ *
35
+ * @param interpreter - The interpreter's absolute path, as the command named it.
36
+ * @returns The folders, real and inside the venv; none for an interpreter outside one.
37
+ */
38
+ export async function venvSitePackages(interpreter) {
39
+ const bin = path.dirname(interpreter);
40
+ const candidates = [bin, path.dirname(bin)];
41
+ let root;
42
+ for (const candidate of candidates) {
43
+ if (await isFile(path.join(candidate, VENV_CONFIG_FILE))) {
44
+ root = candidate;
45
+ break;
46
+ }
47
+ }
48
+ if (root === undefined)
49
+ return [];
50
+ const realRoot = await fs.realpath(root);
51
+ const versions = await fs.readdir(path.join(root, 'lib')).catch(() => []);
52
+ const folders = [];
53
+ for (const version of versions) {
54
+ if (!RE_SITE_PACKAGES_PARENT.test(version))
55
+ continue;
56
+ const folder = path.join(root, 'lib', version, 'site-packages');
57
+ const real = await fs.realpath(folder).catch(() => undefined);
58
+ // Never outside the venv: a site-packages linked elsewhere is someone else's.
59
+ if (real !== undefined && real.startsWith(realRoot + path.sep) && (await fs.stat(real)).isDirectory())
60
+ folders.push(real);
61
+ }
62
+ return folders;
63
+ }
64
+ /**
65
+ * The one line Python runs from the `.pth` at startup.
66
+ *
67
+ * It acts only when Python ignored the environment (`-I`, `-E`): otherwise PYTHONPATH loads
68
+ * the shim the usual way. And only when the process's environment names the capture folder
69
+ * in PYTHONPATH, which only an agent's environment does: `-I` stops Python from reading the
70
+ * variable, not the process from holding it. The developer running the same venv from their
71
+ * own terminal gets nothing. It loads nothing itself: a one-shot finder answers site's own
72
+ * `import sitecustomize`, which comes after every `.pth`, so the shim runs the developer's
73
+ * `sitecustomize` next on the full `sys.path`. Any fault is swallowed, since site prints a
74
+ * failing `.pth` line, or a failing `sitecustomize`, into the customer's stderr.
75
+ *
76
+ * ponytail: rides on `.pth` import lines. CPython's docs for 3.15 reportedly deprecate them
77
+ * (ignored from 3.18); 3.14 still runs them silently. When they go, a `-I` run on that
78
+ * Python is uncaptured again, and the upgrade is whatever startup hook replaces them.
79
+ *
80
+ * @param shimDir - The capture copy's python folder.
81
+ * @returns The file's contents, or undefined for a path that is not plain ASCII.
82
+ */
83
+ export function venvLoader(shimDir) {
84
+ // ponytail: a non-ASCII data dir gets no loader; JSON's \u escapes split astral characters in Python.
85
+ if (!RE_ASCII_PATH.test(shimDir))
86
+ return undefined;
87
+ const code = [
88
+ 'try:',
89
+ ` d = ${JSON.stringify(shimDir)}`,
90
+ ` f = os.path.join(d, ${JSON.stringify(PYTHON_SHIM_FILE)})`,
91
+ " if sys.flags.ignore_environment and d in os.environ.get('PYTHONPATH', '').split(os.pathsep) and os.path.isfile(f):",
92
+ ' import importlib.util',
93
+ ' class AgentWatchCapture:',
94
+ ' def find_spec(self, name, path=None, target=None):',
95
+ " if name != 'sitecustomize':",
96
+ ' return None',
97
+ ' try:',
98
+ ' sys.meta_path.remove(self)',
99
+ " return importlib.util.spec_from_file_location('sitecustomize', f)",
100
+ ' except Exception:',
101
+ ' return None',
102
+ ' sys.meta_path.insert(0, AgentWatchCapture())',
103
+ 'except Exception:',
104
+ ' pass',
105
+ ''
106
+ ].join('\n');
107
+ // Its own globals: site runs the line inside a function, whose locals a class's methods cannot see.
108
+ return `${VENV_LOADER_MARK}\nimport os, sys; exec(${JSON.stringify(code)}, {'os': os, 'sys': sys})\n`;
109
+ }
110
+ function recordFile(dataDir, folder) {
111
+ return path.join(dataDir, VENV_RECORDS_DIR, `${createHash('sha256').update(folder).digest('hex').slice(0, 16)}.txt`);
112
+ }
113
+ /**
114
+ * Leave the loader in the venv of every interpreter a shell command runs by path, so a
115
+ * `python -I` run is captured too. Recorded first, so a file written is always one
116
+ * uninstall can find. Never throws: a venv it cannot write is skipped.
117
+ *
118
+ * @param command - The shell command, read in memory only.
119
+ * @param directory - Where it runs.
120
+ * @param dataDir - The data dir.
121
+ * @param shimDir - The capture copy's python folder.
122
+ * @returns The site-packages folders that now hold the loader.
123
+ */
124
+ export async function armVenvLoaders(command, directory, dataDir, shimDir) {
125
+ const contents = venvLoader(shimDir);
126
+ if (contents === undefined || !(await isFile(path.join(shimDir, PYTHON_SHIM_FILE))))
127
+ return [];
128
+ const armed = [];
129
+ for (const interpreter of pythonInterpreters(command, directory)) {
130
+ for (const folder of await venvSitePackages(interpreter).catch(() => [])) {
131
+ const file = path.join(folder, VENV_LOADER_FILE);
132
+ try {
133
+ const current = await fs.readFile(file, 'utf8').catch(() => undefined);
134
+ // A file of that name Edge did not write is the developer's: left, and not armed.
135
+ if (current !== undefined && !current.startsWith(VENV_LOADER_MARK))
136
+ continue;
137
+ const record = recordFile(dataDir, folder);
138
+ // Recorded even when the loader is already there: a purge can take the record and leave the file.
139
+ if (current !== contents || !(await isFile(record)))
140
+ await writeFileAtomic(record, folder, 0o600);
141
+ if (current !== contents)
142
+ await writeFileAtomic(file, contents, VENV_LOADER_MODE);
143
+ armed.push(folder);
144
+ }
145
+ catch {
146
+ // A fixed sentence: the error could quote a path.
147
+ debugLog('capture: could not write a venv loader; that venv is skipped');
148
+ }
149
+ }
150
+ }
151
+ return armed;
152
+ }
153
+ /**
154
+ * The site-packages folders Edge has left a loader in, as recorded.
155
+ *
156
+ * @param dataDir - The data dir.
157
+ * @returns The folders, whether or not the loader is still there.
158
+ */
159
+ export async function recordedVenvs(dataDir) {
160
+ const dir = path.join(dataDir, VENV_RECORDS_DIR);
161
+ const names = await fs.readdir(dir).catch(() => []);
162
+ const folders = await Promise.all(names.map((name) => fs.readFile(path.join(dir, name), 'utf8').catch(() => '')));
163
+ return folders.filter((folder) => path.isAbsolute(folder));
164
+ }
165
+ /**
166
+ * Remove every loader Edge recorded, and its record. A file that no longer carries our
167
+ * mark is the developer's now and stays.
168
+ *
169
+ * @param dataDir - The data dir.
170
+ * @returns The folders a loader was removed from, and those whose loader could not be.
171
+ */
172
+ export async function removeVenvLoaders(dataDir) {
173
+ const removed = [];
174
+ const left = [];
175
+ for (const folder of await recordedVenvs(dataDir)) {
176
+ const file = path.join(folder, VENV_LOADER_FILE);
177
+ const contents = await fs.readFile(file, 'utf8').catch(() => undefined);
178
+ const ours = contents?.startsWith(VENV_LOADER_MARK) === true;
179
+ // A loader it could not remove keeps its record, for the next uninstall.
180
+ if (ours && !(await fs.rm(file).then(() => true, () => false))) {
181
+ left.push(folder);
182
+ continue;
183
+ }
184
+ if (ours)
185
+ removed.push(folder);
186
+ await fs.rm(recordFile(dataDir, folder), { force: true }).catch(() => undefined);
187
+ }
188
+ return { removed, left };
189
+ }