@manyoars/oars 0.4.0 → 0.5.1

package/dist/gate/hook.d.ts

@@ -6,10 +6,19 @@ export declare const crossingsPath: (storeDir: string) => string;
 export declare const registryCachePath: (storeDir: string) => string;
 /** The registry ask is cut at this many ms on the process clock, less a write reserve; `hook-main.ts` ends the process a short grace after it, so the whole call is under a second. */
 export declare const DEADLINE_MS = 800;
+/** The environment variable a test sets to give a built hook more than `DEADLINE_MS`, so a loaded machine that spends the budget starting node still reaches the code under test. */
+export declare const DEADLINE_ENV = "OARS_GATE_HOOK_DEADLINE_MS";
+/** `DEADLINE_MS`, or the value of `DEADLINE_ENV` when it is a whole number of ms above it; nothing else (a lower, empty, or malformed value) moves the deadline. */
+export declare const deadlineOf: (env: NodeJS.ProcessEnv) => number;
 /** A registry answer the hook kept is used for this many days. A `latest` is read "as of the crossing", so an older one is asked again. */
 export declare const HOOK_REGISTRY_DAYS = 1;
 /** A not-found answer is trusted this long: a name can be published any minute, and a block rests on the answer. */
 export declare const NOT_FOUND_MS = 600000;
+/** The environment variable a test sets to start the hand-off earlier than `HANDOFF_BUDGET_MS` before the deadline, so a case with a long deadline reaches the hand-off at a time the test names. */
+export declare const HANDOFF_MARK_ENV = "OARS_GATE_HOOK_HANDOFF_MARK_MS";
+/** When a registry ask still open starts the hand-off to a helper, on the process clock: `HANDOFF_BUDGET_MS` before the deadline, so the lock and the helper's blocking spawn fit even when the machine is slow.
+ * The value of `HANDOFF_MARK_ENV` moves it earlier when it is a whole number of ms above 0 and below that; nothing else (empty, malformed, zero, or later) moves it. */
+export declare const handOffMarkOf: (env: NodeJS.ProcessEnv, deadlineMs: number) => number;
 export interface GateHookDeps {
     storeDir: string;
     now: () => number;
@@ -17,13 +26,15 @@ export interface GateHookDeps {
     clock: () => number;
     /** The whole hook ends by this many ms on `clock`. */
     deadlineMs: number;
+    /** When an ask still open starts the hand-off to a helper, in ms on `clock`. Absent: `HANDOFF_BUDGET_MS` before `deadlineMs`. */
+    handOffMarkMs?: number;
     /** The draw for the holdback, in [0, 1). Absent: `Math.random`. */
     random?: () => number;
     /** Asks the package manager. Absent: no question is ever asked. */
     registry?: RegistryReader;
     /** Appends text to a file. Replaceable so a full disk can be tried. */
     append?: (file: string, text: string) => Promise<void>;
-    /** Called with the name whose ask was cut or had no time to start, so a helper can finish it and fill the cache for the next sight. Absent: nothing is finished. */
+    /** Called with the name whose ask is still open at the hand-off mark, or had no time to start, so a helper can finish it and fill the cache for the next sight. Absent: nothing is finished. */
     fill?: (ask: FillAsk) => Promise<void>;
     /** Whether a helper already holds the name, which keeps the hook from asking the manager a second time. Absent: never locked. */
     locked?: (ask: FillAsk) => Promise<boolean>;

package/dist/gate/hook.js

@@ -20,6 +20,13 @@ export const crossingsPath = (storeDir) => join(storeDir, 'crossings.jsonl');
 export const registryCachePath = (storeDir) => join(storeDir, 'gate-registry.jsonl');
 /** The registry ask is cut at this many ms on the process clock, less a write reserve; `hook-main.ts` ends the process a short grace after it, so the whole call is under a second. */
 export const DEADLINE_MS = 800;
+/** The environment variable a test sets to give a built hook more than `DEADLINE_MS`, so a loaded machine that spends the budget starting node still reaches the code under test. */
+export const DEADLINE_ENV = 'OARS_GATE_HOOK_DEADLINE_MS';
+/** `DEADLINE_MS`, or the value of `DEADLINE_ENV` when it is a whole number of ms above it; nothing else (a lower, empty, or malformed value) moves the deadline. */
+export const deadlineOf = (env) => {
+    const given = Number(env[DEADLINE_ENV]);
+    return Number.isInteger(given) && given > DEADLINE_MS ? given : DEADLINE_MS;
+};
 /** A registry answer the hook kept is used for this many days. A `latest` is read "as of the crossing", so an older one is asked again. */
 export const HOOK_REGISTRY_DAYS = 1;
 /** A not-found answer is trusted this long: a name can be published any minute, and a block rests on the answer. */
@@ -28,6 +35,17 @@ export const NOT_FOUND_MS = 600_000;
 const WRITE_RESERVE_MS = 150;
 /** One call hands at most this many names to helpers; the rest wait for a later sight, so a call naming dozens cannot start dozens of processes. */
 const MAX_HELPERS = 3;
+/** What the hand-off to a helper is given before the deadline: the lock, then a blocking spawn of the helper. A loaded machine took up to about 400 ms for it. */
+const HANDOFF_BUDGET_MS = 400;
+/** The environment variable a test sets to start the hand-off earlier than `HANDOFF_BUDGET_MS` before the deadline, so a case with a long deadline reaches the hand-off at a time the test names. */
+export const HANDOFF_MARK_ENV = 'OARS_GATE_HOOK_HANDOFF_MARK_MS';
+/** When a registry ask still open starts the hand-off to a helper, on the process clock: `HANDOFF_BUDGET_MS` before the deadline, so the lock and the helper's blocking spawn fit even when the machine is slow.
+ * The value of `HANDOFF_MARK_ENV` moves it earlier when it is a whole number of ms above 0 and below that; nothing else (empty, malformed, zero, or later) moves it. */
+export const handOffMarkOf = (env, deadlineMs) => {
+    const latest = deadlineMs - HANDOFF_BUDGET_MS;
+    const given = Number(env[HANDOFF_MARK_ENV]);
+    return Number.isInteger(given) && given > 0 && given < latest ? given : latest;
+};
 /** An ask with less than this left is not started: it could not finish. */
 const MIN_ASK_MS = 100;
 const isInput = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -95,22 +113,35 @@ const registryAnswer = async (deps, crossing, cwd, kept, helpers, hold) => {
         return undefined;
     const stop = new AbortController();
     let answer;
+    const hand = { off: false };
+    const handOff = async () => {
+        if (helpers.started >= MAX_HELPERS)
+            return;
+        helpers.started += 1;
+        hand.off = true;
+        await deps.fill?.(ask).catch(() => undefined);
+    };
     if (budgetOf(deps) >= MIN_ASK_MS) {
         // The first sight on a fresh store has no folder yet, and the deadline's synchronous write needs one: made here, before the ask, so a cut-off hook can still leave its row.
         await mkdir(deps.storeDir, { recursive: true }).catch(() => undefined);
         hold(() => { stop.abort(); });
         const pending = deps.registry({ ...ask, signal: stop.signal });
-        // Starting the manager is a blocking spawn that can take a good part of the budget, so the cut counts what is left now, not what was left before the call: read before it, the cut
+        // Starting the manager is a blocking spawn that can take a good part of the budget, so the marks count what is left now, not what was left before the call: read before it, the cut
         // could land behind the process's own deadline, which ends the process with the ask still running.
-        answer = await within(pending, budgetOf(deps));
+        // An answer before the mark never pays for a helper; an ask that starts after the mark hands off at once. An ask still open at the mark has the hand-off started beside it (the lock and the helper's spawn, which also block), early enough that a
+        // loaded machine still finishes it inside the deadline; the cut after that drops nothing, because the helper already holds the name.
+        answer = await within(pending, (deps.handOffMarkMs ?? deps.deadlineMs - HANDOFF_BUDGET_MS) - deps.clock());
+        if (answer === undefined) {
+            await handOff();
+            answer = await within(pending, budgetOf(deps));
+        }
     }
     if (answer === undefined) {
-        // Not answered in time: the row reads not-read, and a helper finishes the ask so the next sight reads it from the cache. This ask is stopped first, so the manager is never asked twice at once.
+        // Not answered in time: the row reads not-read, and the helper (started at the mark, or here when there was no time to reach it) finishes the ask so the next sight reads it from the cache.
+        // This ask is stopped first, so the hook's manager does not outlive the hook.
         stop.abort();
-        if (helpers.started < MAX_HELPERS) {
-            helpers.started += 1;
-            await deps.fill?.(ask).catch(() => undefined);
-        }
+        if (!hand.off)
+            await handOff();
         return undefined;
     }
     return { answer, asked: true };

package/dist/hook-bin.js

@@ -1,8 +1,9 @@
-// The one entry file the installed hooks and the nightly task run: `node hook-bin.js <session-start|pre-tool|post-tool|stop|nightly>`, with the
+// The one entry file the installed hooks and the detached sender run: `node hook-bin.js <session-start|pre-tool|post-tool|stop|nightly>`, with the
 // hook event JSON on stdin. It imports only the store modules (not the CLI), so a call costs little more than the node start, and it
 // always exits 0 with no output on any failure: a hook must never fail or block a session.
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
 import { hookEmitter } from './telemetry/hook-emit.js';
 import { sendNightly } from './telemetry/send.js';
 import { HOOK_EVENTS, hookRuntime, nightlyTelemetry, runHook } from './sessions/hooks.js';
@@ -24,20 +25,38 @@ const versionOf = () => {
         return '0.0.0';
     }
 };
-/** After the covenant is accepted, the nightly task sends what the pool outbox holds; with no server, sign-in, or acceptance it sends nothing. Loaded only here so the per-tool hooks never pay for it. It never throws. */
+/** After the covenant is accepted, the detached sender (hook-bin.js nightly) sends what the pool outbox holds; with no server, sign-in, or acceptance it sends nothing. Loaded only here so the per-tool hooks never pay for it. It never throws. */
 const nightlyPool = async (event) => {
     const { nightlyPoolDeps } = await import('./sessions/pool-nightly-deps.js');
     const { nightlyPoolSend } = await import('./sessions/pool-nightly.js');
     await nightlyPoolSend(nightlyPoolDeps(process.env, hookRuntime(event, process.env, process.platform, homedir(), { stdin: process.stdin, stdout: process.stdout }), versionOf(), Date.now));
 };
 const eventOf = (name) => HOOK_EVENTS.find((event) => event === name);
+/** The machine modes: `stop --machine` is the Stop of a cloud VM, a VPS, or a runner (a detached child does the work), and `machine-child` is that child. Neither is a local hook event. */
+const machineModeOf = (argv) => (argv[2] === 'machine-child' ? 'child' : argv[2] === 'stop' && argv.includes('--machine') ? 'stop' : undefined);
 try {
-    const event = eventOf(process.argv[2]);
+    const machineMode = machineModeOf(process.argv);
+    const event = machineMode === undefined ? eventOf(process.argv[2]) : undefined;
+    if (machineMode === 'stop') {
+        const { machineStop } = await import('./sessions/machine-stop.js');
+        const { spawn } = await import('node:child_process');
+        const { storeDir } = hookRuntime('stop', process.env, process.platform, homedir(), { stdin: process.stdin, stdout: process.stdout });
+        machineStop({ env: process.env, stdin: await readStdin(), hookBin: fileURLToPath(import.meta.url), home: homedir(), storeDir, write: (text) => process.stdout.write(text), spawn });
+    }
+    if (machineMode === 'child') {
+        const { runMachineChild } = await import('./sessions/machine-child-deps.js');
+        await runMachineChild(process.env, hookRuntime('stop', process.env, process.platform, homedir(), { stdin: process.stdin, stdout: process.stdout }), versionOf(), Date.now, process.argv[3] ?? '');
+    }
     if (event !== undefined) {
         const output = await runHook(event, event === 'nightly' ? '' : await readStdin(), hookRuntime(event, process.env, process.platform, homedir(), { stdin: process.stdin, stdout: process.stdout }), Date.now, nightlyTelemetry(event, process.env, process.platform, homedir(), versionOf, Date.now), hookEmitter(process.env, process.platform, homedir(), new URL('../package.json', import.meta.url), Date.now));
         if (output !== undefined)
             process.stdout.write(output);
-        // The nightly task is where telemetry is sent from; it never throws, and it sends nothing unless telemetry is on and the notice was shown (the server is OARS_POOL_URL, else the Many Oars pool).
+        // The session just ended and its deposit is written: start a due sweep and send, detached, and do not wait for it (the hook stays sub-second and prints nothing more). Loaded only here so the per-tool hooks never pay for it.
+        if (event === 'stop') {
+            const { afterStop } = await import('./sessions/pool-due.js');
+            await afterStop(hookRuntime(event, process.env, process.platform, homedir(), { stdin: process.stdin, stdout: process.stdout }).storeDir, fileURLToPath(import.meta.url));
+        }
+        // The detached sender is where telemetry is sent from; it never throws, and it sends nothing unless telemetry is on and the notice was shown (the server is OARS_POOL_URL, else the Many Oars pool).
         if (event === 'nightly') {
             await sendNightly(process.env, process.platform, homedir(), Date.now);
             await nightlyPool(event);

package/dist/issuer.d.ts

@@ -7,7 +7,7 @@ export declare const PRODUCTION_ISSUER_URL = "https://login.manyoars.com/realms/
 /**
  * The built-in issuer is in use only when neither `--issuer-url` nor `OARS_ISSUER_URL` named one. If that issuer does not answer
  * discovery (no answer, an error status, or a body that is not discovery JSON), the platform is not up yet, so say so (exit 2) and
- * name the pool. An issuer the developer named keeps its own error.
+ * name the sign-in host. An issuer the developer named keeps its own error.
  */
 export declare const discoverIssuer: <T>(deps: RunDeps, flag: string | undefined, discover: () => Promise<T>) => Promise<T>;
 /** `--issuer-url`, else `OARS_ISSUER_URL`, else the built-in production issuer. */

package/dist/issuer.js

@@ -4,11 +4,11 @@ import { CliError, ExitCode } from './errors.js';
  * and is the default for `oars login`: no site or file can send a login anywhere else.
  */
 export const PRODUCTION_ISSUER_URL = 'https://login.manyoars.com/realms/aor';
-const UNAVAILABLE = 'Cannot reach Many Oars sign-in at login.manyoars.com (Many Oars and its pool at pool.manyoars.com may not be deployed yet). Pass --issuer-url or set OARS_ISSUER_URL to use another issuer.';
+const UNAVAILABLE = 'Cannot reach Many Oars sign-in at login.manyoars.com (it may not be deployed yet). Pass --issuer-url or set OARS_ISSUER_URL to use another issuer.';
 /**
  * The built-in issuer is in use only when neither `--issuer-url` nor `OARS_ISSUER_URL` named one. If that issuer does not answer
  * discovery (no answer, an error status, or a body that is not discovery JSON), the platform is not up yet, so say so (exit 2) and
- * name the pool. An issuer the developer named keeps its own error.
+ * name the sign-in host. An issuer the developer named keeps its own error.
  */
 export const discoverIssuer = async (deps, flag, discover) => {
     try {

package/dist/main.js

@@ -7,8 +7,10 @@ import { setTimeout as sleep } from 'node:timers/promises';
 import { openBrowser } from './browser.js';
 import { run } from './cli.js';
 import { defaultConfigDir, fileCredentialStore } from './credentials.js';
+import { codexRoot } from './sessions/codex.js';
 import { cursorRoot } from './sessions/cursor.js';
 import { claudeEvaluator, runClaude } from './sessions/gold-arms.js';
+import { catchUpOnStore } from './sessions/pool-due.js';
 import { SOURCES } from './sessions/sources.js';
 import { spawnDetachedSend } from './telemetry/send.js';
 /** The version in this package's package.json (one folder up from dist/). */
@@ -28,6 +30,7 @@ process.exitCode = await run(process.argv.slice(2), {
     store: fileCredentialStore(configDir),
     telemetry: { dir: join(configDir, 'oars', 'telemetry'), platform: process.platform, spawnSend: spawnDetachedSend },
     version: readVersion(),
+    catchUp: () => catchUpOnStore(join(configDir, 'oars', 'sessions'), fileURLToPath(new URL('./hook-bin.js', import.meta.url))),
     sleep: (ms) => sleep(ms),
     random: Math.random,
     now: Date.now,
@@ -38,6 +41,7 @@ process.exitCode = await run(process.argv.slice(2), {
         hookBin: fileURLToPath(new URL('./hook-bin.js', import.meta.url)),
         userSettings: join(process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), '.claude'), 'settings.json'),
         cwd: process.cwd(),
+        codex: { home: codexRoot(process.env), nodePath: process.execPath, hookBin: fileURLToPath(new URL('./sessions/codex-hook-bin.js', import.meta.url)) },
         schtasks: (args) => new Promise((resolve) => {
             let output = '';
             const child = spawn('schtasks', args, { windowsHide: true });
@@ -63,5 +67,6 @@ process.exitCode = await run(process.argv.slice(2), {
         sourceRoots: Object.fromEntries(SOURCES.map((source) => [source.name, source.root(process.platform, process.env, homedir())])),
         stdin: process.stdin,
         stdout: process.stdout,
+        stderr: process.stderr,
     },
 });

package/dist/node-floor.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The oldest Node the CLI supports (`engines.node` in package.json): the latest 22.x when the floor leg of `.github/workflows/ci.yml`
+ * (`cli-node-floor`) passed the whole CLI suite on it (run 42783202609, `cli on Node 22.23.4`). The one proven cause below it is `node:sqlite`
+ * URI filenames (`sessions/opencode.ts:91`), which Node 22.13 rejected (t1087 run 42776737858).
+ */
+export declare const MIN_NODE = "22.23.4";
+/** One line for a Node older than the floor, or undefined when `version` (as in `process.versions.node`) is new enough. */
+export declare const nodeFloorMessage: (version: string) => string | undefined;
+/** Writes the one line plus a newline and exits 1 on a Node under the floor; does neither otherwise. `write` and `exit` are injected so a test can see both. */
+export declare const exitIfTooOld: (version: string, write: (text: string) => unknown, exit: (code: number) => unknown) => void;

package/dist/node-floor.js

@@ -0,0 +1,23 @@
+/**
+ * The oldest Node the CLI supports (`engines.node` in package.json): the latest 22.x when the floor leg of `.github/workflows/ci.yml`
+ * (`cli-node-floor`) passed the whole CLI suite on it (run 42783202609, `cli on Node 22.23.4`). The one proven cause below it is `node:sqlite`
+ * URI filenames (`sessions/opencode.ts:91`), which Node 22.13 rejected (t1087 run 42776737858).
+ */
+export const MIN_NODE = '22.23.4';
+const parts = (version) => version.split('.').map((part) => Number.parseInt(part, 10));
+const atLeast = (version, floor) => {
+    const have = parts(version);
+    const need = parts(floor);
+    const at = need.findIndex((value, index) => (have[index] ?? 0) !== value);
+    return at === -1 || (have[at] ?? 0) > (need[at] ?? 0);
+};
+/** One line for a Node older than the floor, or undefined when `version` (as in `process.versions.node`) is new enough. */
+export const nodeFloorMessage = (version) => atLeast(version, MIN_NODE) ? undefined : `oars needs Node ${MIN_NODE} or newer; this is Node ${version}.`;
+/** Writes the one line plus a newline and exits 1 on a Node under the floor; does neither otherwise. `write` and `exit` are injected so a test can see both. */
+export const exitIfTooOld = (version, write, exit) => {
+    const tooOld = nodeFloorMessage(version);
+    if (tooOld !== undefined) {
+        write(`${tooOld}\n`);
+        exit(1);
+    }
+};

package/dist/oars-hook.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/oars-hook.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { exitIfTooOld } from './node-floor.js';
+// The same one line and exit 1 as `oars` gives on a Node under the floor, before the hook program loads.
+exitIfTooOld(process.versions.node, (text) => process.stderr.write(text), (code) => process.exit(code));
+// The `oars-hook` executable: the host-independent command a machine's Stop and SessionEnd hooks run (`oars-hook stop --machine`, written by `oars sessions hook install --machine`). It is the same program as
+// `hook-bin.js`, behind a name on PATH, so a settings file committed from one machine names no install path and still runs on a VM whose setup script installed the package globally.
+await import('./hook-bin.js');

package/dist/sessions/allow.d.ts

@@ -10,6 +10,7 @@ export interface Allow {
 }
 /** The prefix `--deny` saves an entry under. */
 export declare const DENY = "!";
+export declare const isDenial: (entry: string) => boolean;
 export declare const denialOf: (entry: string) => string;
 export declare const compileAllow: (entries: readonly string[]) => Allow;
 /**

package/dist/sessions/allow.js

@@ -34,7 +34,7 @@ const matcherOf = (entry) => {
 };
 /** The prefix `--deny` saves an entry under. */
 export const DENY = '!';
-const isDenial = (entry) => entry.startsWith(DENY);
+export const isDenial = (entry) => entry.startsWith(DENY);
 export const denialOf = (entry) => `${DENY}${entry}`;
 export const compileAllow = (entries) => {
     const compiled = entries.filter((entry) => !isDenial(entry)).map((entry) => ({ entry, matches: matcherOf(expandHome(entry)) }));

package/dist/sessions/call-shape.d.ts

@@ -17,3 +17,114 @@ export declare const targetClassOf: (path: string | undefined, base: TargetBase
 export declare const argClassOf: (input: {
     readonly [key: string]: unknown;
 }) => ArgClass[];
+/** The size of a value as written (its length as text, a number's digits included), as a closed list. A boolean and a null have none. */
+export declare const VALUE_SIZES: readonly ["0", "1-8", "9-32", "33-128", "129-512", "513-2k", "2k-8k", "over-8k"];
+export type ValueSize = (typeof VALUE_SIZES)[number];
+/** How many folders a path value sits below the repository or the working folder; `outside` is an absolute path under neither, so the folders above them are never counted. */
+export declare const PATH_DEPTHS: readonly ["0", "1", "2", "3-4", "5-8", "over-8", "outside"];
+export type PathDepth = (typeof PATH_DEPTHS)[number];
+/** The class of a path value's extension: `none` is a name with none (a folder, a `Makefile`). */
+export declare const EXTENSION_CLASSES: readonly ["source", "doc", "config", "data", "image", "none", "other"];
+export type ExtensionClass = (typeof EXTENSION_CLASSES)[number];
+/** The kind of the folders a path value names: `root` is a value with no folder part. */
+export declare const DIRECTORY_KINDS: readonly ["root", "source", "test", "doc", "generated", "hidden", "other"];
+export type DirectoryKind = (typeof DIRECTORY_KINDS)[number];
+/** What a pattern value uses, as a sorted set: `literal` is a pattern that uses none of the rest. A regular expression and a glob share the list. */
+export declare const PATTERN_FEATURES: readonly ["alternation", "anchor", "class", "escape", "group", "literal", "quantifier", "recursive", "wildcard"];
+export type PatternFeature = (typeof PATTERN_FEATURES)[number];
+/** One argument's features (layer 1): its key and the closed-list facts about its value, never the value. `pathDepth`, `extension`, and `dirKind` are on a path argument only, `patternFeatures` on a pattern only. */
+export interface ArgFeature {
+    key: string;
+    valueSize: ValueSize;
+    pathDepth?: PathDepth;
+    extension?: ExtensionClass;
+    dirKind?: DirectoryKind;
+    patternFeatures?: PatternFeature[];
+}
+/**
+ * The features of each argument of a call (layer 1), sorted by key: its value's size, and for a path its depth below the repository root (else the working folder), its extension class, and its folder kind, and for a pattern what it uses. A Glob call's
+ * `pattern` and a `glob`, `include`, or `exclude` argument read as globs; any other pattern as a regular expression. A boolean and a null have no features (a boolean goes as a closed value, `argValuesOf`). The values are read
+ * here and go no further: every field is a member of a closed list.
+ */
+export declare const argFeaturesOf: (native: string, input: {
+    readonly [key: string]: unknown;
+}, root: string | undefined, cwd?: string) => ArgFeature[];
+/** One argument's closed value (layer 1): a boolean as `true` or `false`, or a member of the closed list its tool pins for the key (`CLOSED_ARG_VALUES`). A value off the list is not one, so it is never sent. */
+export interface ArgValue {
+    key: string;
+    enumValue: string;
+}
+/** The closed values of a call's arguments, sorted by key: every boolean, and every string its tool's list for the key holds. A custom agent's name is off the list, so it is not here. */
+export declare const argValuesOf: (native: string, input: {
+    readonly [key: string]: unknown;
+}, closed: ReadonlyMap<string, ReadonlyMap<string, ReadonlySet<string>>>) => ArgValue[];
+/** What kind of name a token is: a file's name, a folder's name below the session root, an environment variable's name, a flag's value that is a name, or a custom agent's name. */
+export declare const NAME_KINDS: readonly ["file", "dir", "env", "flag", "agent"];
+export type NameKind = (typeof NAME_KINDS)[number];
+/** One name token (layer 2): the kind and the name as it was written. The wire sends it through its one gate (`wireName`). */
+export interface ArgName {
+    kind: NameKind;
+    name: string;
+}
+/** A word of a shell command as the tokenizer read it. */
+export interface CommandWord {
+    text: string;
+    quoted: boolean;
+    /** The variable the whole word references: set only when the word's raw source, quotes included, is exactly one reference (`variableOf`). Every other word holds none, whatever `$` it contains. */
+    variable?: string;
+    /** The word starts at or after the command's opaque point (`tokenize`): no variable, assignment, or flag value is read from it. */
+    opaque?: true;
+    /** The word's raw source starts with an unquoted `NAME=` or `--flag=` and holds a double quote after it (`tokenize`): `quoted` is true, but the name and the joined value are read as for an unquoted word. */
+    joined?: true;
+}
+/** A shell command's words as the name read takes them: those before the program (assignments, wrappers), the program's own word, and its arguments. */
+export interface CommandWords {
+    before: readonly CommandWord[];
+    head: CommandWord;
+    args: readonly CommandWord[];
+}
+/**
+ * The one rule for a variable reference: a word names a variable only when its raw source, quotes included, is exactly one reference: `$NAME`, `${NAME}`, or a PowerShell `$env:NAME` or scope form (`$script:NAME`, `$global:NAME`),
+ * bare or in double quotes. Every other word is literal: a `$` inside a longer word, a quote, a command substitution, an escape, and `%NAME%` (no POSIX shell or PowerShell expands it) name nothing, which sends less and never more.
+ * The tokenizer reads each word through this.
+ */
+export declare const variableOf: (raw: string) => string | undefined;
+/**
+ * The name tokens of a call (layer 2), read from the values layer 1 reads: the file basename of each path value and the directory names of its segments below the root (else the working folder), never a segment above it, so an account
+ * or home folder is not here; the variable names a shell command assigns (`VAR=` before its program), references (`$VAR`, `${VAR}`), or an `env` object holds; a flag value that is a name; and a custom agent's `subagent_type`.
+ * Never a value: an assignment's value, a message, a path, and a number are read for the name and go no further. Sorted by kind, then name, and single. The wire sends each through its one gate.
+ */
+export declare const argNamesOf: (native: string, input: {
+    readonly [key: string]: unknown;
+}, root: string | undefined, cwd: string | undefined, commands: readonly CommandWords[], closed: ReadonlyMap<string, ReadonlyMap<string, ReadonlySet<string>>>, restored?: readonly string[]) => ArgName[];
+/** What a literal of a command becomes in its template: a closed list, so a template holds no argument text. `<flag>` is a flag-like word whose name is not spelled (an attached value, a cluster off the public list). */
+export declare const TEMPLATE_SLOTS: readonly ["<text>", "<path>", "<ident>", "<num>", "<url>", "<var>", "<flag>"];
+export type TemplateSlot = (typeof TEMPLATE_SLOTS)[number];
+/** A call's command templates, one per command in the order they run (`templateOf`). Sent through the wire's one gate, which drops a template whose kept word fails it. */
+export declare const templatesOf: (commands: readonly CommandWords[], redact: (text: string) => string) => string[];
+/** What an edit did, as a closed set: the shape of the change and never its text. Written in this order on the wire. */
+export declare const DIFF_SHAPES: readonly ["import-added", "import-removed", "identifier-renamed", "lines-added", "lines-removed", "lines-changed", "whitespace-only", "file-written"];
+export type DiffShape = (typeof DIFF_SHAPES)[number];
+/**
+ * What a call that edits a file did, as a closed set (layer 3), never its text: a `Write` is `file-written`; an `Edit` or each entry of a `MultiEdit` is read from its old and new text (`shapesOfEdit`), and the call has the union, in the list's order.
+ * A call that is no edit, or an edit that changes nothing, has none.
+ */
+export declare const diffShapeOf: (tool: string, input: {
+    readonly [key: string]: unknown;
+}) => DiffShape[];
+/**
+ * What changed from the previous call of the same tool in the same prompt, as a closed set (layer 1): `same` when nothing did; else any of a key added, a key removed, a kept key's value whose features or closed value
+ * changed (`feature-changed`), a kept key's value that changed while its features did not (`value-changed`), and the target (`target-changed`). The first call of a tool in a prompt has none.
+ */
+export declare const CHANGE_KINDS: readonly ["same", "key-added", "key-removed", "feature-changed", "value-changed", "target-changed"];
+export type ChangeKind = (typeof CHANGE_KINDS)[number];
+/** A call as the change read compares it: its raw input and target, held only while capture reads the transcript, with the features and closed values computed from them. */
+export interface ComparedCall {
+    input: {
+        readonly [key: string]: unknown;
+    };
+    target: string | null;
+    features: readonly ArgFeature[];
+    values: readonly ArgValue[];
+}
+export declare const changeKindOf: (before: ComparedCall, after: ComparedCall) => ChangeKind[];