@manyoars/oars 0.1.1 → 0.3.0

package/dist/sessions/package-resolve.d.ts

@@ -0,0 +1,30 @@
+import type { Redactor } from './redact.js';
+import type { ToolManifest, ToolPackage, ToolPull } from './schema.js';
+/** The registry's own normalization (spec Section 1.3): npm lowercases, PyPI folds `-`, `_`, and `.`, crates.io folds `-` and `_`. */
+export declare const NORMALIZE: ReadonlyMap<string, (name: string) => string>;
+/** A name in an ecosystem of the vocabulary, spelled as the registry spells it; null when it is not shaped like one. */
+export declare const resolveName: (ecosystem: string, name: string) => string | null;
+/** One pull as the `package` and `packageVersion` it names, or null when it names no package. */
+export declare const resolvePull: (pull: ToolPull) => Omit<ToolPackage, "first"> | null;
+/**
+ * The packages one call installs or runs, each marked `first` when no earlier call of the transcript file named that package at that version. `seen` is the
+ * file's running set, so the caller passes the same one for every call in order. A version that fails on first try still counts: the mark is made
+ * from the command, before its result is known.
+ */
+export declare const packagesOf: (pulls: readonly ToolPull[], seen: Set<string>) => ToolPackage[];
+export type ManifestFile = ToolManifest['file'];
+/**
+ * The manifest a path names, by its basename: `requirements-dev.txt` is a requirements file, `Cargo.toml` is exact. A path with a `node_modules`, `vendor`, `site-packages`,
+ * `.venv`, `venv`, `.cargo`, or `bower_components` folder (in any case) names none, since that manifest is a dependency's own. Not covered: pyproject.toml, go.mod, Gemfile, pom.xml.
+ */
+export declare const manifestFileOf: (path: string) => ManifestFile | null;
+/**
+ * The packages a manifest text names, as `<ecosystem>:<name>`, each once, sorted. A name the redactor changes is a secret or a mask and is dropped as it was
+ * written, before resolving folds its case: the redactor's rules are case-sensitive, so a folded key would pass them.
+ */
+export declare const manifestNames: (file: ManifestFile, text: string, redact: Redactor) => string[];
+/** The names an edit adds and removes: those only in the new text, and those only in the old. A version change moves neither. */
+export declare const manifestDelta: (file: ManifestFile, before: string, after: string, redact: Redactor) => {
+    added: string[];
+    removed: string[];
+};

package/dist/sessions/package-resolve.js

@@ -0,0 +1,183 @@
+// Packages as a capture stores them (pool vocabulary spec Sections 1.2 and 1.3): a name a transcript shows, resolved to `<ecosystem>:<name>` in the
+// registry's own spelling. Resolving is a check of shape only, since capture asks no registry: a name that cannot be told from a path, a flag, a URL, or a
+// masked word is not a package and stores nothing. Whether the name is public is the projection's question (`projectPackage`), asked at deposit.
+/** The registry's own normalization (spec Section 1.3): npm lowercases, PyPI folds `-`, `_`, and `.`, crates.io folds `-` and `_`. */
+export const NORMALIZE = new Map([
+    ['npm', (name) => name.toLowerCase()],
+    ['pypi', (name) => name.toLowerCase().replace(/[-_.]+/g, '-')],
+    ['crates', (name) => name.toLowerCase().replace(/_/g, '-')],
+    ['rubygems', (name) => name],
+    ['homebrew', (name) => name.toLowerCase()],
+]);
+/** A capture ecosystem to the vocabulary's. `skill`, `plugin`, and `mcp` are not package registries and are absent. */
+const ECOSYSTEM_OF = new Map([
+    ['npm', 'npm'],
+    ['pypi', 'pypi'],
+    ['cargo', 'crates'],
+    ['gem', 'rubygems'],
+    ['brew', 'homebrew'],
+    ['go', 'go'],
+]);
+/** What each registry accepts as a name. A scoped npm name is the only one with a slash besides a Go module path, so `owner/repo` (a GitHub shorthand) fails. */
+const NAME_SHAPE = new Map([
+    ['npm', /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/i],
+    ['pypi', /^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/i],
+    ['crates', /^[a-z][a-z0-9_-]*$/i],
+    ['rubygems', /^[a-z0-9][a-z0-9._-]*$/i],
+    ['homebrew', /^[a-z0-9][a-z0-9@+._-]*$/i],
+    ['go', /^[a-z0-9.-]+\.[a-z0-9.-]+\/[\w.~/-]+$/i],
+]);
+/** A published version: three or four dotted numbers with an optional pre-release or build tail, and Go's leading `v`. A bare `1` is a range to its registry, and capture does not tell a two-part `2.31` (a short exact pin or a short range) apart, so like a range (`^1.2`, `>=2`), a tag (`latest`), or a mask neither is a version. */
+const EXACT_VERSION = /^v?\d+(?:\.\d+){2,3}(?:[-+][0-9A-Za-z.+-]+)?$/;
+/** A name in an ecosystem of the vocabulary, spelled as the registry spells it; null when it is not shaped like one. */
+export const resolveName = (ecosystem, name) => {
+    const shape = NAME_SHAPE.get(ecosystem);
+    if (shape === undefined || !shape.test(name))
+        return null;
+    return `${ecosystem}:${NORMALIZE.get(ecosystem)?.(name) ?? name}`;
+};
+/** One pull as the `package` and `packageVersion` it names, or null when it names no package. */
+export const resolvePull = (pull) => {
+    const ecosystem = ECOSYSTEM_OF.get(pull.ecosystem);
+    const resolved = ecosystem === undefined ? null : resolveName(ecosystem, pull.name);
+    if (resolved === null)
+        return null;
+    return { package: resolved, packageVersion: pull.version !== null && EXACT_VERSION.test(pull.version) ? pull.version : null };
+};
+/**
+ * The packages one call installs or runs, each marked `first` when no earlier call of the transcript file named that package at that version. `seen` is the
+ * file's running set, so the caller passes the same one for every call in order. A version that fails on first try still counts: the mark is made
+ * from the command, before its result is known.
+ */
+export const packagesOf = (pulls, seen) => {
+    const packages = new Map();
+    for (const pull of pulls) {
+        const resolved = resolvePull(pull);
+        if (resolved === null)
+            continue;
+        const key = `${resolved.package}\n${resolved.packageVersion ?? ''}`;
+        if (packages.has(key))
+            continue;
+        packages.set(key, { ...resolved, first: !seen.has(key) });
+    }
+    for (const key of packages.keys())
+        seen.add(key);
+    return [...packages.values()];
+};
+const MANIFEST_ECOSYSTEM = new Map([
+    ['package.json', 'npm'],
+    ['requirements.txt', 'pypi'],
+    ['Cargo.toml', 'crates'],
+]);
+/** A folder that holds code a project installed: a manifest inside it belongs to a dependency, and the session did not choose it. */
+const DEPENDENCY_FOLDERS = new Set(['node_modules', 'vendor', 'site-packages', '.venv', 'venv', '.cargo', 'bower_components']);
+/**
+ * The manifest a path names, by its basename: `requirements-dev.txt` is a requirements file, `Cargo.toml` is exact. A path with a `node_modules`, `vendor`, `site-packages`,
+ * `.venv`, `venv`, `.cargo`, or `bower_components` folder (in any case) names none, since that manifest is a dependency's own. Not covered: pyproject.toml, go.mod, Gemfile, pom.xml.
+ */
+export const manifestFileOf = (path) => {
+    const parts = path.replace(/\\/g, '/').split('/');
+    if (parts.some((part) => DEPENDENCY_FOLDERS.has(part.toLowerCase())))
+        return null;
+    const base = parts.pop() ?? '';
+    if (base === 'package.json' || base === 'Cargo.toml')
+        return base;
+    return /^requirements(?:[-_.][\w.-]+)?\.txt$/.test(base) ? 'requirements.txt' : null;
+};
+/** A Read result numbers its lines (`    12→text`); an edit's text does not. */
+const withoutLineNumbers = (line) => line.replace(/^\s*\d+(?:→|\t)/, '');
+const NODE_DEPENDENCY_KEYS = new Set(['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']);
+/** A range, a pin, or a tag. A `file:`, `workspace:`, `npm:` alias, URL, or git value names no registry package. */
+const NODE_VERSION = /^(?:[~^<>=]*\s*v?\d[\w.*+-]*|\*|latest|next)(?:\s.*)?$/i;
+/** Keys that hold a version-shaped value and are not dependencies, for text that shows no section header. */
+const NOT_NODE_DEPENDENCIES = new Set(['name', 'description', 'main', 'version', 'node', 'npm', 'yarn', 'pnpm', 'tag']);
+const nodeNames = (lines) => {
+    // A whole file opens with `{`, so its top-level values are no dependencies. A fragment stays null until a section header is seen: an edit may hold dependency lines alone.
+    let active = lines.find((line) => line.trim() !== '')?.trim() === '{' ? false : null;
+    const names = [];
+    for (const line of lines) {
+        const section = /^\s*"([^"]+)"\s*:\s*\{\s*$/.exec(line)?.[1];
+        if (section !== undefined)
+            active = NODE_DEPENDENCY_KEYS.has(section);
+        else if (/^\s*\},?\s*$/.test(line))
+            active = false;
+        else if (active !== false) {
+            const entry = /^\s*"([^"]+)"\s*:\s*"([^"]*)"\s*,?\s*$/.exec(line);
+            if (entry !== null && NODE_VERSION.test(entry[2] ?? '') && (active === true || !NOT_NODE_DEPENDENCIES.has(entry[1] ?? '')))
+                names.push(entry[1] ?? '');
+        }
+    }
+    return names;
+};
+/** A line that ends in an archive, before any environment marker, names a file, as a path does. */
+const ARCHIVE = /\.(?:whl|tar\.gz|tgz|tar\.bz2|zip|egg)$/i;
+const pythonNames = (lines) => lines.flatMap((line) => {
+    const text = line.replace(/(?:^|\s)#.*$/, '').trim();
+    if (text === '' || text.startsWith('-') || text.includes('://') || ARCHIVE.test(text.split(';')[0]?.trim() ?? ''))
+        return [];
+    const name = /^([A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?)\s*(?:\[[^\]]*\])?\s*(?:$|[=<>!~;@,])/.exec(text)?.[1];
+    return name === undefined ? [] : [name];
+});
+const CARGO_DEPENDENCY_TABLE = /(?:^|\.)(?:dev-|build-)?dependencies$/;
+const CARGO_DEPENDENCY_ENTRY = /(?:^|\.)(?:dev-|build-)?dependencies\.([A-Za-z][\w-]*)$/;
+const CARGO_VERSION = /^[~^<>=]*\s*\d[\w.*+-]*$|^\*$/;
+const NOT_CARGO_DEPENDENCIES = new Set(['version', 'name', 'edition', 'rust-version', 'resolver', 'license', 'authors', 'description', 'readme', 'repository', 'homepage', 'documentation', 'publish', 'opt-level', 'keywords', 'categories', 'exclude', 'include', 'build', 'links']);
+const cargoNames = (lines) => {
+    // null until a table header is seen, as for package.json.
+    let inDependencies = null;
+    // A dependency written as its own table is known by its keys, which follow the header: it waits here until the next header or the end of the text.
+    let pending = null;
+    const names = [];
+    const settle = () => {
+        if (pending !== null)
+            names.push(pending);
+        pending = null;
+    };
+    for (const line of lines) {
+        const table = /^\s*\[\[?([^\]]+)\]\]?\s*(?:#.*)?$/.exec(line)?.[1]?.replace(/\s/g, '');
+        if (table !== undefined) {
+            settle();
+            pending = CARGO_DEPENDENCY_ENTRY.exec(table)?.[1] ?? null;
+            inDependencies = CARGO_DEPENDENCY_TABLE.test(table);
+        }
+        else if (pending !== null) {
+            // A `path` or `git` key makes the table a source and no registry crate; `package` names the real crate behind an alias.
+            if (/^\s*(?:path|git)\s*=/.test(line))
+                pending = null;
+            else
+                pending = /^\s*package\s*=\s*"([^"]+)"/.exec(line)?.[1] ?? pending;
+        }
+        else if (inDependencies !== false) {
+            const shared = /^\s*([A-Za-z][\w-]*)\.workspace\s*=\s*true\b/.exec(line)?.[1];
+            const entry = /^\s*([A-Za-z][\w-]*)\s*=\s*(.+?)\s*$/.exec(line);
+            // A comment after the closing quote or brace is not part of the value.
+            const value = (entry?.[2] ?? '').replace(/(?<=["}])\s+#.*$/, '');
+            const text = /^"([^"]*)"$/.exec(value)?.[1];
+            // An inline table holding `path` or `git` is a source and no registry crate; `package` names the real crate behind an alias.
+            const named = text !== undefined ? CARGO_VERSION.test(text) : /^\{.*\b(?:version|workspace)\s*=/.test(value) && !/\b(?:path|git)\s*=/.test(value);
+            const real = /\bpackage\s*=\s*"([^"]+)"/.exec(value)?.[1];
+            if (shared !== undefined)
+                names.push(shared);
+            else if (entry !== null && named && (inDependencies === true || !NOT_CARGO_DEPENDENCIES.has(entry[1] ?? '')))
+                names.push(real ?? entry[1] ?? '');
+        }
+    }
+    settle();
+    return names;
+};
+/**
+ * The packages a manifest text names, as `<ecosystem>:<name>`, each once, sorted. A name the redactor changes is a secret or a mask and is dropped as it was
+ * written, before resolving folds its case: the redactor's rules are case-sensitive, so a folded key would pass them.
+ */
+export const manifestNames = (file, text, redact) => {
+    const lines = text.split(/\r?\n/).map(withoutLineNumbers);
+    const found = file === 'package.json' ? nodeNames(lines) : file === 'requirements.txt' ? pythonNames(lines) : cargoNames(lines);
+    const ecosystem = MANIFEST_ECOSYSTEM.get(file) ?? '';
+    return [...new Set(found.filter((name) => redact(name) === name).flatMap((name) => resolveName(ecosystem, name) ?? []))].sort();
+};
+/** The names an edit adds and removes: those only in the new text, and those only in the old. A version change moves neither. */
+export const manifestDelta = (file, before, after, redact) => {
+    const was = manifestNames(file, before, redact);
+    const now = manifestNames(file, after, redact);
+    return { added: now.filter((name) => !was.includes(name)), removed: was.filter((name) => !now.includes(name)) };
+};

package/dist/sessions/pending.d.ts

@@ -0,0 +1,34 @@
+/**
+ * How many pending sessions one Stop hook deposit takes before its own. The cap bounds the COUNT, not the time: a hook that gets the lock late can
+ * still deposit this many transcripts of any size, so the only time limit is the harness's own ceiling on the hook (30 s, install.ts), and a backlog
+ * drains over several hooks (a whole-store deposit takes all).
+ */
+export declare const PENDING_HOOK_CAP = 5;
+/** How many failed deposits a pending entry survives: at this many it is removed and counted as dropped, since a whole-store walk still reaches any transcript on the allowlist. */
+export declare const PENDING_MAX_FAILURES = 5;
+export declare const pendingDir: (storeDir: string) => string;
+export interface PendingEntry {
+    /** The file names of this entry that were read (one per deferral of the same transcript); the files of an unreadable entry are not here. */
+    names: string[];
+    /** The transcript to deposit; undefined for a file that is not a pending entry (it is dropped) or one that could not be read. */
+    transcript: string | undefined;
+    /** True when no file of the entry could be read: it is kept and counted, never removed. */
+    unreadable: boolean;
+    /** Failed deposits so far, the highest over the entry's files. */
+    failures: number;
+}
+/** Records `transcript` as pending without taking the store lock. The same session twice is two files and one entry. */
+export declare const deferSession: (storeDir: string, transcript: string) => Promise<void>;
+/**
+ * The first `limit` readable pending entries, read: fewest failures first, then name order, and then any unreadable entries met on the way (they
+ * never count toward `limit` and never go first, so a file that cannot be read cannot fill the hook's cap or be retried ahead of a real session).
+ * A store with no pending folder has none, and a pending folder that cannot be listed is an empty list with one line on stderr, so it never
+ * fails the deposit it was read for.
+ */
+export declare const listPending: (storeDir: string, limit: number) => Promise<PendingEntry[]>;
+/** Removes the files of the entries a deposit settled, after its `state.json` was written, so a crash before that leaves them for the next run. */
+export declare const removePending: (storeDir: string, entries: readonly PendingEntry[]) => Promise<void>;
+/** Counts one more failed deposit of `entry`, in the name of its first file. The caller holds the store lock, so no one else renames or removes it. */
+export declare const failPending: (storeDir: string, entry: PendingEntry) => Promise<void>;
+/** Removes the `*.tmp` files a hook died before renaming, once they are older than `staleMs`: the age no live write reaches. */
+export declare const sweepPendingTemps: (storeDir: string, staleMs: number) => Promise<void>;

package/dist/sessions/pending.js

@@ -0,0 +1,142 @@
+// The pending list (register row A55): the sessions a Stop hook deposit could not take because another deposit held the store lock.
+//
+// One small file per deferral under `<store>/pending/`, named `<hash of the transcript path>.<uuid>.json` and holding `{"transcript": "<path>"}`:
+// what a later deposit needs to find the transcript, and nothing else (no prompt text, no id, no project name beyond the path). One file per
+// deferral, not one shared list, because the hook that defers must not take the store lock (it just failed to) and two hooks may defer at once:
+// each writes a file name no one else uses. A drain removes only the file names it read, so a session that defers again while a drain runs leaves
+// its newer file behind for the next deposit, and an append racing a drain is never lost. The drain dedupes by the hash, so a session that
+// deferred twice is one entry. Each file is written to a temp name and renamed, so a drain never reads a torn one.
+//
+// A deposit that fails on an entry renames it `<hash>.<uuid>.f<n>.json`, so the number of failures is in the name and ordering the list needs
+// no read of the file: entries with fewer failures come first, and an entry that always fails cannot fill the hook's cap for good.
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * How many pending sessions one Stop hook deposit takes before its own. The cap bounds the COUNT, not the time: a hook that gets the lock late can
+ * still deposit this many transcripts of any size, so the only time limit is the harness's own ceiling on the hook (30 s, install.ts), and a backlog
+ * drains over several hooks (a whole-store deposit takes all).
+ */
+export const PENDING_HOOK_CAP = 5;
+/** How many failed deposits a pending entry survives: at this many it is removed and counted as dropped, since a whole-store walk still reaches any transcript on the allowlist. */
+export const PENDING_MAX_FAILURES = 5;
+/** One line on stderr for a pending-list file operation that failed and was skipped: the deposit that met it goes on. */
+const warn = (what, error) => {
+    process.stderr.write(`oars: ${what}: ${error instanceof Error ? error.message : String(error)}\n`);
+};
+export const pendingDir = (storeDir) => join(storeDir, 'pending');
+const hashOf = (transcript) => createHash('sha256').update(transcript).digest('hex').slice(0, 32);
+/** The part of a file name before the first dot: the hash, which is what makes two deferrals one entry. */
+const keyOf = (name) => name.slice(0, name.indexOf('.'));
+const FAILED = /\.f(\d+)\.json$/;
+const failuresOf = (name) => Number(FAILED.exec(name)?.[1] ?? 0);
+/** Records `transcript` as pending without taking the store lock. The same session twice is two files and one entry. */
+export const deferSession = async (storeDir, transcript) => {
+    const dir = pendingDir(storeDir);
+    await mkdir(dir, { recursive: true });
+    const temp = join(dir, `${randomUUID()}.tmp`);
+    await writeFile(temp, JSON.stringify({ transcript }), { mode: 0o600 });
+    await rename(temp, join(dir, `${hashOf(transcript)}.${randomUUID()}.json`));
+};
+const transcriptOf = (text) => {
+    try {
+        const parsed = JSON.parse(text);
+        const transcript = typeof parsed === 'object' && parsed !== null ? Reflect.get(parsed, 'transcript') : undefined;
+        return typeof transcript === 'string' && transcript !== '' ? transcript : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const entryOf = async (storeDir, names) => {
+    const failures = Math.max(...names.map(failuresOf));
+    const read = [];
+    let transcript;
+    for (const name of names) {
+        try {
+            const found = transcriptOf(await readFile(join(pendingDir(storeDir), name), 'utf8'));
+            read.push(name);
+            transcript ??= found;
+        }
+        catch {
+            // A file that cannot be read stays where it is: it is not in `names`, so a drain never removes it.
+        }
+    }
+    return { names: read, transcript, unreadable: read.length === 0, failures };
+};
+/**
+ * The first `limit` readable pending entries, read: fewest failures first, then name order, and then any unreadable entries met on the way (they
+ * never count toward `limit` and never go first, so a file that cannot be read cannot fill the hook's cap or be retried ahead of a real session).
+ * A store with no pending folder has none, and a pending folder that cannot be listed is an empty list with one line on stderr, so it never
+ * fails the deposit it was read for.
+ */
+export const listPending = async (storeDir, limit) => {
+    let names;
+    try {
+        names = (await readdir(pendingDir(storeDir))).filter((name) => name.endsWith('.json'));
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return [];
+        warn('the pending list could not be read and is skipped', error);
+        return [];
+    }
+    const groups = new Map();
+    for (const name of names.sort())
+        groups.set(keyOf(name), [...(groups.get(keyOf(name)) ?? []), name]);
+    const ordered = [...groups.values()].map((group) => ({ group, failures: Math.max(...group.map(failuresOf)) })).sort((a, b) => a.failures - b.failures);
+    const readable = [];
+    const unreadable = [];
+    // Read in batches of as many entries as are still wanted, so an unreadable one is read past rather than counted.
+    for (let next = 0; next < ordered.length && readable.length < limit;) {
+        const batch = ordered.slice(next, next + Math.max(1, limit - readable.length));
+        next += batch.length;
+        for (const entry of await Promise.all(batch.map((item) => entryOf(storeDir, item.group))))
+            (entry.unreadable ? unreadable : readable).push(entry);
+    }
+    return [...readable, ...unreadable];
+};
+/** Removes the files of the entries a deposit settled, after its `state.json` was written, so a crash before that leaves them for the next run. */
+export const removePending = async (storeDir, entries) => {
+    for (const entry of entries) {
+        for (const name of entry.names) {
+            try {
+                await rm(join(pendingDir(storeDir), name), { force: true });
+            }
+            catch (error) {
+                warn(`a settled pending file could not be removed and is left for the next run: ${name}`, error);
+            }
+        }
+    }
+};
+/** Counts one more failed deposit of `entry`, in the name of its first file. The caller holds the store lock, so no one else renames or removes it. */
+export const failPending = async (storeDir, entry) => {
+    const failures = entry.failures + 1;
+    const first = entry.names[0];
+    if (first !== undefined) {
+        const base = first.replace(FAILED, '.json').replace(/\.json$/, `.f${String(failures)}.json`);
+        try {
+            await rename(join(pendingDir(storeDir), first), join(pendingDir(storeDir), base));
+        }
+        catch (error) {
+            warn(`a failed pending file could not be renamed and is left for the next run: ${first}`, error);
+        }
+    }
+};
+/** Removes the `*.tmp` files a hook died before renaming, once they are older than `staleMs`: the age no live write reaches. */
+export const sweepPendingTemps = async (storeDir, staleMs) => {
+    const dir = pendingDir(storeDir);
+    const names = await readdir(dir).catch(() => []);
+    for (const name of names.filter((entry) => entry.endsWith('.tmp'))) {
+        const age = await stat(join(dir, name)).then((info) => Date.now() - info.mtimeMs, () => 0);
+        if (age <= staleMs)
+            continue;
+        try {
+            await rm(join(dir, name), { force: true });
+        }
+        catch (error) {
+            // Housekeeping: a leftover this sweep cannot remove (a folder named like one, or a file Windows refuses) costs a line, never the deposit.
+            warn(`a stale pending temp file could not be removed and is left in place: ${name}`, error);
+        }
+    }
+};

package/dist/sessions/pool-command.d.ts

@@ -0,0 +1,44 @@
+import type { Outcome, RunDeps } from '../cli.js';
+import { type Outgoing } from './pool-print.js';
+export declare const POOL_PROVIDERS: readonly ["github", "google"];
+/** `--server`, else `OARS_POOL_URL`; never a default. A token and a session's shape cross this connection, so plain http goes only to this machine. */
+export declare const poolServer: (env: NodeJS.ProcessEnv, step: string, named?: string) => string;
+export interface Reply {
+    status: number;
+    body: unknown;
+    headers: Headers;
+}
+/** How a request leaves this machine. The command line passes none and so sends no batch; the lock in `deposit --send` is tested with one. */
+export type Sender = (request: Outgoing) => Promise<Reply>;
+/** The sender a real send would use: the request goes out over the network as built. The command line does not pass it (sending waits on the covenant); the loopback test does, to read what reaches the socket. */
+export declare const networkSender: (deps: RunDeps, step: string) => Sender;
+/**
+ * `oars pool login` (spec Section 1.4): the device flow runs here, against the provider, and the pool sees only the provider's token, once, and answers its own credential. Every request prints before it is sent, with the device code, the provider's token,
+ * and the credential masked as `<credential: n bytes>`. A client ID, scope, grant type, and Google's `client_secret` print as they are: none is secret.
+ */
+export declare const poolLogin: (deps: RunDeps, options: {
+    server?: string | undefined;
+    provider?: string | undefined;
+}) => Promise<Outcome>;
+/**
+ * `oars pool deposit`: every session in the store that passes both session gates is built into a canonical batch in the outbox, and the command stops: nothing is sent. The gates run before any projection does: the folder
+ * allowlist, then the exclusion check. A session that fails either, or has no raw to scan, is counted and never built. A session is built only once it has ended: no transcript of it, main or subagent, has gained a line (the later of its capture
+ * and its raw file's last write) for `session_idle_hours` (6 hours). One that has not is counted under `notEnded`, and any batch of it from an earlier pass is withdrawn. `--send <hash>` is the lock in `sendBatch`.
+ */
+export declare const poolDeposit: (deps: RunDeps, options: {
+    server?: string | undefined;
+    acceptCovenant?: string | undefined;
+    send?: string | undefined;
+    via?: Sender | undefined;
+}) => Promise<Outcome>;
+/** `oars pool outbox`: prints each batch as it would be sent, the request line and every header included, with the bearer credential as its size and nothing else masked, then its SHA-256, and records that it was shown. `--explain` adds each field's rule. */
+export declare const poolOutbox: (deps: RunDeps, options: {
+    server?: string | undefined;
+    explain?: boolean | undefined;
+}) => Promise<Outcome>;
+/** `oars pool fetch`: one harness's signed bundle at one version, kept only once the key pinned at login has verified it. It keeps the signed form, so the replica can be checked again later, and the ETag, so the next fetch asks only whether it changed. The request prints before it is sent. */
+export declare const poolFetch: (deps: RunDeps, options: {
+    server?: string | undefined;
+    harness?: string | undefined;
+    harnessVersion: string;
+}) => Promise<Outcome>;