@parcha/agentrun-kernel 0.0.0-bootstrap.0 → 0.1.0-beta.29

package/dist/delegate.js

@@ -0,0 +1,143 @@
+// A lead hands one task to a named sub-agent, which runs as a child node on the same kernel. Written for AgentRun.
+//
+// `delegateTool` is an ordinary host tool, `delegate({ agent, task, context? })`, for a lead on any harness. Each call runs
+// one child: an `agent` node, through `createHarnessRunner`, with the agent's own system prompt (as the host gave it) and
+// its own subset of the lead's tools, answering in a fixed shape (`DELEGATE_RESULT_SCHEMA`). The child is durable under its
+// own key, `step:<the lead's key>/delegate:<call id>`, so the call is replay-safe: a delegate that finished answers again
+// from its recorded result, and one a crash cut off resumes from its own store (its finished paid requests are never sent
+// again). Its paid requests are booked under that key and go through the lead's `beforeRequest`, so one budget covers the
+// lead and every child; its deadline is the lead's, or the agent's share of what is left. Children run one at a time, and
+// a child has no delegate tool (depth 1).
+import { Mutex } from "./process/tools.js";
+import { createHarnessRunner, RUNNER_RECORDS, SUBMIT_TOOL } from "./runner.js";
+/** The tool's name, as the lead calls it. */
+export const DELEGATE_TOOL = "delegate";
+/** What every delegate answers: its finding, the sources it rests on, and what it could not settle. */
+export const DELEGATE_RESULT_SCHEMA = Object.freeze({
+    type: "object",
+    properties: {
+        answer: { type: "string" },
+        citations: {
+            type: "array",
+            items: { type: "object", properties: { url: { type: "string" }, title: { type: "string" }, quote: { type: "string" } }, required: ["url"], additionalProperties: false },
+        },
+        gaps: { type: "array", items: { type: "string" } },
+    },
+    required: ["answer", "citations"],
+    additionalProperties: false,
+});
+const AGENT_NAME = /^[a-z][a-z0-9-]{0,63}$/;
+/** What is wrong with the delegate's definition, or nothing: checked when the tool is made. */
+export function delegateProblems(options) {
+    const problems = [];
+    const lead = new Set(options.tools.map((t) => t.name));
+    const names = Object.keys(options.agents);
+    if (names.length === 0)
+        problems.push("no agents to delegate to");
+    if (lead.has(DELEGATE_TOOL))
+        problems.push(`the lead already has a tool named ${DELEGATE_TOOL}`);
+    for (const name of names) {
+        const agent = options.agents[name];
+        if (!AGENT_NAME.test(name))
+            problems.push(`the agent name ${JSON.stringify(name.slice(0, 80))} is not lowercase letters, digits and dashes`);
+        if (typeof agent.system !== "string" || agent.system.length === 0)
+            problems.push(`the agent ${name} has no system prompt`);
+        const seen = new Set();
+        for (const tool of agent.tools) {
+            if (seen.has(tool))
+                problems.push(`the agent ${name} names the tool ${tool} twice`);
+            seen.add(tool);
+            if (tool === DELEGATE_TOOL)
+                problems.push(`the agent ${name} may not delegate further (depth 1)`);
+            else if (tool === SUBMIT_TOOL)
+                problems.push(`the agent ${name} names ${SUBMIT_TOOL}, which the runner gives every child itself`);
+            else if (!lead.has(tool))
+                problems.push(`the agent ${name} names the tool ${tool}, which the lead does not have`);
+        }
+        const share = agent.deadlineShare;
+        if (share !== undefined && !(share > 0 && share <= 1))
+            problems.push(`the agent ${name}'s deadline share ${share} is not in (0, 1]`);
+    }
+    return problems;
+}
+/** The `delegate` host tool: refuses a bad definition when made. */
+export function delegateTool(options) {
+    const problems = delegateProblems(options);
+    if (problems.length)
+        throw new Error(`agentrun-kernel: delegate: ${problems.join("; ")}`);
+    const byName = new Map(options.tools.map((t) => [t.name, t]));
+    const names = Object.keys(options.agents);
+    // One child at a time, whatever the harness's own tool calls do.
+    const serial = new Mutex();
+    return {
+        name: DELEGATE_TOOL,
+        description: `Hand one task to a sub-agent, which works on it with its own tools and answers with its finding, its sources and its gaps. One at a time. The agents:\n${names.map((n) => `- ${n}: ${options.agents[n].description}`).join("\n")}`,
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent: { type: "string", enum: names },
+                task: { type: "string", description: "What the sub-agent is to find out or do, complete in itself." },
+                context: { type: "string", description: "What it should know from your work so far." },
+            },
+            required: ["agent", "task"],
+            additionalProperties: false,
+        },
+        // A child is durable under its own key: run again after a crash, it answers from its record or resumes its session.
+        replay: "safe",
+        call: (args, { callId, signal, sessionDir }) => serial.run(async () => {
+            const { agent: name, task, context } = (args ?? {});
+            // An own entry only: a name like `constructor` is not an agent.
+            const agent = typeof name === "string" && Object.hasOwn(options.agents, name) ? options.agents[name] : undefined;
+            if (!agent)
+                return { text: `Not delegated: ${JSON.stringify(String(name).slice(0, 80))} is not one of the agents (${names.join(", ")}).`, isError: true };
+            if (typeof task !== "string" || task.trim() === "")
+                return { text: "Not delegated: give the task as text.", isError: true };
+            const tag = { agent: name, callId, parentKey: options.parentKey };
+            // The child's session: its step's id, so its records are the runner's under `step:<id>`.
+            const sessionId = `${options.parentKey}/delegate:${callId}`;
+            const deadlineAt = options.deadlineAt?.();
+            const left = deadlineAt === undefined ? undefined : deadlineAt - Date.now();
+            if (left !== undefined && left <= 0) {
+                // A child that delivered before a crash answers from its record, deadline or not; only new work is refused. Read,
+                // not opened: opening would fence the session for nothing.
+                const saved = (await options.store.read(`step:${sessionId}`)).findLast((r) => r.kind === RUNNER_RECORDS.accepted);
+                if (saved)
+                    return { text: JSON.stringify(saved.data.value) };
+                return { text: "Not delegated: the lead has no time left.", isError: true };
+            }
+            const timeoutMs = left === undefined ? options.timeoutMs : Math.max(1, Math.floor(left * (agent.deadlineShare ?? 1)));
+            const runNode = createHarnessRunner(typeof options.adapter === "function" ? options.adapter(name) : options.adapter, {
+                store: options.store,
+                tools: agent.tools.map((t) => byName.get(t)),
+                signal,
+                // The lead's runner's private directories, if it has them: the child's is its own, by its own key.
+                ...(sessionDir ? { sessionDir } : {}),
+                ...(timeoutMs === undefined ? {} : { timeoutMs }),
+                ...(options.maxTurns === undefined ? {} : { maxTurns: options.maxTurns }),
+                ...(options.beforeRequest ? { beforeRequest: options.beforeRequest } : {}),
+                ...(options.onEvent ? { onEvent: (event) => options.onEvent({ ...event, delegate: tag }) } : {}),
+            });
+            try {
+                const answer = await runNode({
+                    kind: "agent",
+                    label: `delegate:${name}`,
+                    system: [agent.system],
+                    user: typeof context === "string" && context.trim() ? `${task}\n\nContext from the lead:\n${context}` : task,
+                    schema: DELEGATE_RESULT_SCHEMA,
+                    tools: [...agent.tools],
+                    ...(agent.tier === undefined ? {} : { tier: agent.tier }),
+                    step: { sessionId, attempt: 0, earlierSessionIds: [] },
+                });
+                return { text: JSON.stringify(answer) };
+            }
+            catch (error) {
+                // Stopped (the lead paused, the process is draining): not an answer. Rethrown, the lead's harness records the call
+                // as interrupted and runs the same call id again on resume, which resumes this child. A child that failed on its
+                // own is an answer the lead reads.
+                if (signal?.aborted)
+                    throw signal.reason ?? error;
+                return { text: `The delegate ${name} stopped without an answer: ${String(error?.message ?? error).slice(0, 400)}`, isError: true };
+            }
+        }),
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,36 @@
+/** Why a harness node delivered no record. */
+export type HarnessRunReason = "aborted" | "timeout" | "turn_limit" | "submission_limit" | "no_submission" | "model_error"
+/** Turns kept ending with no paid request and no accepted submission (`NO_PROGRESS_TURNS` in a row), which the turn
+ *  limit never counts: the harness is not reaching its model. */
+ | "no_progress"
+/** The runner or the host refused the node before or while it ran: an unknown tool, a fork, a turn limit above the
+ *  host's cap, a session the adapter refused, or the host's `beforeRequest` (a budget). */
+ | "refused"
+/** A newer process opened this node's session, so this attempt may no longer write it: it stops and delivers nothing.
+ *  Not final: whether the step is delivered is the newer attempt's to say. */
+ | "fenced";
+/** An append through a writer that a newer `open` of its session has fenced. Nothing of the append was written. */
+export declare class SessionFenced extends Error {
+    readonly key: string;
+    readonly code = "SESSION_FENCED";
+    constructor(key: string);
+}
+/** A node that delivered no record. `final` says a second attempt would end the same way, so a recovery driver gives
+ *  it none: the runner's own bounds (the turn cap, no progress, a refusal) are final; an abort, a timeout or a model
+ *  error is not. */
+export declare class HarnessRunError extends Error {
+    readonly reason: HarnessRunReason;
+    readonly turns: number;
+    readonly submissions: number;
+    readonly code = "HARNESS_NODE_NOT_DELIVERED";
+    readonly final?: true;
+    constructor(reason: HarnessRunReason, turns: number, submissions: number, detail?: {
+        message?: string;
+        maxTurns?: number | null;
+        lastTool?: string;
+    });
+    /** The node's turn limit for this attempt, or null when it had none. */
+    readonly maxTurns?: number | null;
+    /** The name of the last tool the node called, never its arguments. */
+    readonly lastTool?: string;
+}

package/dist/errors.js

@@ -0,0 +1,37 @@
+/** An append through a writer that a newer `open` of its session has fenced. Nothing of the append was written. */
+export class SessionFenced extends Error {
+    key;
+    code = "SESSION_FENCED";
+    constructor(key) {
+        super(`session ${key}: a newer writer holds it; this append was refused`);
+        this.key = key;
+        this.name = "SessionFenced";
+    }
+}
+/** A node that delivered no record. `final` says a second attempt would end the same way, so a recovery driver gives
+ *  it none: the runner's own bounds (the turn cap, no progress, a refusal) are final; an abort, a timeout or a model
+ *  error is not. */
+export class HarnessRunError extends Error {
+    reason;
+    turns;
+    submissions;
+    code = "HARNESS_NODE_NOT_DELIVERED";
+    final;
+    constructor(reason, turns, submissions, detail = {}) {
+        super(detail.message ?? `harness node stopped: ${reason} after ${turns} turns and ${submissions} submissions`);
+        this.reason = reason;
+        this.turns = turns;
+        this.submissions = submissions;
+        this.name = "HarnessRunError";
+        if (detail.maxTurns !== undefined)
+            this.maxTurns = detail.maxTurns;
+        if (detail.lastTool !== undefined)
+            this.lastTool = detail.lastTool;
+        if (reason === "turn_limit" || reason === "no_progress" || reason === "refused")
+            this.final = true;
+    }
+    /** The node's turn limit for this attempt, or null when it had none. */
+    maxTurns;
+    /** The name of the last tool the node called, never its arguments. */
+    lastTool;
+}

package/dist/host/alive.d.ts

@@ -0,0 +1,2 @@
+/** `readStat`: how /proc/<pid>/stat is read (a test's seam). */
+export declare function processAlive(pid: number, readStat?: (pid: number) => string): boolean;

package/dist/host/alive.js

@@ -0,0 +1,28 @@
+// Whether a process runs. A zombie (it exited, and its parent has not reaped it) does not, though kill(pid, 0) still
+// finds it: under a PID 1 that does not reap (a container started without an init), an orphan that exits stays one.
+// On Linux, /proc/<pid>/stat says so (its state, after the command name's last ")"); elsewhere, and where that entry
+// cannot be read, kill(pid, 0) is all there is.
+import { existsSync, readFileSync } from "node:fs";
+/** `readStat`: how /proc/<pid>/stat is read (a test's seam). */
+export function processAlive(pid, readStat = (id) => readFileSync(`/proc/${id}/stat`, "utf8")) {
+    if (process.platform === "linux") {
+        try {
+            const stat = readStat(pid);
+            const state = stat.charAt(stat.lastIndexOf(")") + 2);
+            return state !== "Z" && state !== "X";
+        }
+        catch (error) {
+            // Only a missing entry, with /proc mounted, proves it gone. One this process may not read (/proc mounted with
+            // hidepid, another user's process) says nothing: the signal check below decides.
+            if (error.code === "ENOENT" && existsSync("/proc/self/stat"))
+                return false;
+        }
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}

package/dist/host/box-slot.d.ts

@@ -0,0 +1,26 @@
+import { type BoxedChild, type BoxRecord, type BoxRecorder, type Reaped } from "./box.js";
+/** `empty`: a reap counted the last box empty, or there was none. `full`: a reap found it not empty, or could not count. */
+export type BoxSlotState = "empty" | "live" | "reaping" | "full";
+/** What the slot needs of a started box: when it is let go, and when it exited. Its exit status is never read. */
+export type SlotChild = Pick<BoxedChild, "ready" | "exited">;
+export interface BoxStart<P> {
+    /** The box's process, as its start returned it. */
+    process: P;
+    /** Settles once the box's process exited (or never got going) and the reap that follows gave its verdict: resolves
+     *  only when the box holds nothing, else rejects with BoxError box_not_empty. */
+    reaped: Promise<void>;
+}
+export interface BoxSlot<P extends SlotChild> {
+    readonly state: BoxSlotState;
+    /** Starts the session's next box, synchronously end to end. Refused (BoxError box_busy) unless the slot is empty.
+     *  `start` gets the recorder wrapped so the slot keeps the latest record, and calls `ahead` itself before it spawns
+     *  anything. A start that throws after `ahead` has its box reaped (the slot shows it), and the error goes up. */
+    start(start: (recorder: BoxRecorder) => P, recorder: BoxRecorder): BoxStart<P>;
+    /** At open: the record the session's last box left, reaped before anything starts. The slot is empty only if that
+     *  reap counts it empty. */
+    adopt(previous: BoxRecord): Promise<void>;
+}
+/** One session's box slot, reaping with `reap`. */
+export declare function boxSlot<P extends SlotChild>(options: {
+    reap: (record: BoxRecord) => Promise<Reaped>;
+}): BoxSlot<P>;

package/dist/host/box-slot.js

@@ -0,0 +1,112 @@
+// A session's box slot: one box at a time, and what decides it is empty. Written for AgentRun.
+//
+// Whatever the isolation (a bwrap box, a cgroup, a provider sandbox), everything inside the box is the agent's: it can
+// kill the box's first process, write any line and pick any exit status. So nothing here reads the harness's exit status
+// or output to decide anything. The box's record is written durably before anything runs in it (`ahead`, before the
+// spawn, and `started`, before its first process is let go). The box is reaped as soon as its process exits, never when
+// its stdout closes (a stray holding it would keep that from ever happening), and only the reap's own count says it is
+// empty. A session starts one box at a time: a start while its last box is live, being reaped, or not counted empty is
+// refused at once, before anything else happens.
+//
+// This is isolation-agnostic: how a box starts and how it is reaped come in as arguments (box.ts's Box.start and
+// Box.reap, or anything with their shape).
+import { BoxError } from "./box.js";
+const busy = (state) => new BoxError("box_busy", `box_busy: the session's box is ${state}; a new one starts only once a reap has counted the last one empty`);
+/** One session's box slot, reaping with `reap`. */
+export function boxSlot(options) {
+    let state = "empty";
+    // The box's latest record: the one its reap is given.
+    let latest;
+    // Each box's start counts one up: a record of an earlier box never lands as this one's.
+    let generation = 0;
+    const settle = async (record) => {
+        state = "reaping";
+        let verdict;
+        try {
+            verdict = await options.reap(record);
+        }
+        catch (error) {
+            state = "full";
+            throw error;
+        }
+        if (!verdict.empty) {
+            state = "full";
+            throw new BoxError("box_not_empty", `box_not_empty: the box still holds ${verdict.left} process${verdict.left === 1 ? "" : "es"} after its reap (counted by ${verdict.by}); nothing more starts for its session`, { record, left: verdict.left });
+        }
+        state = "empty";
+        latest = undefined;
+    };
+    return {
+        get state() {
+            return state;
+        },
+        start(start, recorder) {
+            if (state !== "empty")
+                throw busy(state);
+            state = "live";
+            latest = undefined;
+            const box = ++generation;
+            // Once the box has ended (its reap is on its way), it records nothing more: a late record would replace the next
+            // box's on disk. Its reap waits for every record write already in flight, and counts by the newest.
+            let ended = false;
+            // The seam's order: the ahead record before the spawn, the started one after. A started record with no ahead one
+            // before it is refused, so no write can be on its way for a box that was never recorded.
+            let recorded = false;
+            let writing = Promise.resolve();
+            const refused = () => new BoxError("box_record_failed", "box_record_failed: the box has ended; its record is not written");
+            const wrapped = {
+                ahead: (record) => {
+                    if (ended || box !== generation)
+                        throw refused();
+                    recorder.ahead(record);
+                    latest = record;
+                    recorded = true;
+                },
+                started: (record) => {
+                    if (!recorded)
+                        return Promise.reject(new BoxError("box_record_failed", "box_record_failed: a started record before the box's ahead record; it is not written"));
+                    if (ended || box !== generation)
+                        return Promise.reject(refused());
+                    const write = recorder.started(record).then(() => {
+                        if (box === generation)
+                            latest = record;
+                    });
+                    writing = Promise.all([writing, write.catch(() => { })]);
+                    return write;
+                },
+            };
+            let boxed;
+            try {
+                boxed = start(wrapped);
+            }
+            catch (error) {
+                // Recorded, so something may run in it: reaped, and the slot says how that went. Unrecorded: nothing spawned.
+                ended = true;
+                if (latest !== undefined)
+                    writing.then(() => settle(latest)).catch(() => { });
+                else
+                    state = "empty";
+                throw error;
+            }
+            if (latest === undefined) {
+                // A box that runs and was never recorded cannot be counted: the session starts nothing more.
+                state = "full";
+                throw new BoxError("box_record_failed", "box_record_failed: the box started without a record of itself");
+            }
+            // The first of these ends the box: its process exited, or it was never let go. Either way it is reaped, once,
+            // by its latest record, and its exit status is not read.
+            let once;
+            const end = () => (once ??= ((ended = true), writing.then(() => settle(latest))));
+            const reaped = Promise.race([boxed.exited, boxed.ready.then(() => boxed.exited)]).then(end, end);
+            // Unhandled until the caller asks: a box left full is the caller's to see, not the process's to crash on.
+            reaped.catch(() => { });
+            return { process: boxed, reaped };
+        },
+        async adopt(previous) {
+            if (state !== "empty")
+                throw busy(state);
+            latest = previous;
+            await settle(previous);
+        },
+    };
+}

package/dist/host/box.d.ts

@@ -0,0 +1,104 @@
+import type { ChildProcess } from "node:child_process";
+/** What a box may reach. Everything else of the host is absent inside it. */
+export interface BoxSpec {
+    /** Bound read-write at its own host path, which is the box's working directory (--chdir), and at /workspace too. */
+    workspace: string;
+    /** The harness's homes (per-run directories, never the server's $HOME), each bound read-write at its own path. */
+    homes: Record<string, string>;
+    /** Read-only, at their own paths, beside the system allowlist: node and the pinned CLIs. */
+    readOnly: readonly string[];
+    /** The model front's Unix socket, bound at /run/agentrun/model.sock. */
+    modelSocket: string;
+    /** The forwarder's loopback port in the box (the forwarder is the caller's to start). */
+    modelPort: number;
+    /** The egress proxy's Unix socket, bound at /run/agentrun/egress.sock; absent when the box has no egress. */
+    egressSocket?: string;
+    egressPort?: number;
+    /** The box's whole environment: --clearenv, then one --setenv each. Nothing is inherited. */
+    env: Record<string, string>;
+    /** On a shared server: the run's cgroup v2, a path under the delegated subtree. */
+    cgroup?: string;
+}
+/** A box as it is recorded on disk: its id and cgroup before it starts, then its pid 1, that pid's start time (clock
+ *  ticks since boot, /proc/<pid>/stat field 22) and its pid namespace (`pid:[<inode>]`). */
+export interface BoxRecord {
+    id: string;
+    cgroup?: string;
+    pid?: number;
+    startTime?: string;
+    pidns?: string;
+    /** The run process that wrote the record (its pid and start time): a record nobody could count clears only once its
+     *  writer is gone. */
+    writer: {
+        pid: number;
+        startTime: string;
+    };
+}
+/** Where a box's record goes. `ahead` is synchronous (the file and its directory are synced before it returns) and runs
+ *  before the spawn; `started` runs while bwrap waits, and no process of the harness runs until it resolves. */
+export interface BoxRecorder {
+    ahead(record: BoxRecord): void;
+    started(record: BoxRecord): Promise<void>;
+}
+/** A started box: the bwrap process (its stdio is the harness's), and its record, complete once `ready` resolves. */
+export interface BoxedChild {
+    readonly child: ChildProcess;
+    readonly exited: Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }>;
+    stderrTail(): string;
+    alive(): boolean;
+    /** Ends the box: SIGKILL to its pid 1 (start time checked), which takes every process of its namespace with it. */
+    kill(): void;
+    /** The record so far: the id and cgroup at once, the pid, start time and pid namespace once `ready` resolves. */
+    readonly record: BoxRecord;
+    /** Resolves once the pid is recorded and the box released; rejects (bwrap killed, the harness never ran) when bwrap
+     *  could not start or `started` failed. */
+    readonly ready: Promise<BoxRecord>;
+}
+/** What a reap found, by the kernel's own count: the processes left in the recorded pid namespace, or the cgroup's.
+ *  `none`: the record names neither a pid nor a cgroup, so there was nothing to count (a crash before the pid was
+ *  known; --die-with-parent ends such a box with its parent). */
+export interface Reaped {
+    empty: boolean;
+    left: number;
+    by: "pidns" | "cgroup" | "none";
+}
+export type Isolation = {
+    mode: "bwrap" | "seatbelt" | "provider";
+    cgroup: boolean;
+}
+/** Only from AGENTRUN_BOX=unsandboxed, the operator's setting. */
+ | {
+    mode: "unsandboxed";
+} | {
+    mode: "unavailable";
+    error: BoxErrorCode;
+    detail: string;
+};
+export type BoxErrorCode = "bwrap_missing" | "bwrap_setuid" | "bwrap_userns_denied" | "box_probe_failed" | "box_refused" | "box_record_failed" | "box_start_failed"
+/** A start while the session's last box is live, being reaped, or was not confirmed empty. */
+ | "box_busy"
+/** A reap whose own count was not 0. */
+ | "box_not_empty";
+export interface Box {
+    readonly isolation: Isolation;
+    start(spec: BoxSpec, child: {
+        command: string;
+        args: string[];
+    }, record: BoxRecorder): BoxedChild;
+    reap(record: BoxRecord): Promise<Reaped>;
+}
+/** A box refused or failed, with its named cause. */
+export declare class BoxError extends Error {
+    readonly code: BoxErrorCode;
+    /** For `box_not_empty`: the box, and what its reap left. */
+    readonly record?: BoxRecord;
+    readonly left?: number;
+    constructor(code: BoxErrorCode, message: string, options?: {
+        cause?: unknown;
+        record?: BoxRecord;
+        left?: number;
+    });
+}

package/dist/host/box.js

@@ -0,0 +1,16 @@
+/** A box refused or failed, with its named cause. */
+export class BoxError extends Error {
+    code;
+    /** For `box_not_empty`: the box, and what its reap left. */
+    record;
+    left;
+    constructor(code, message, options) {
+        super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "BoxError";
+        this.code = code;
+        if (options?.record)
+            this.record = options.record;
+        if (options?.left !== undefined)
+            this.left = options.left;
+    }
+}

package/dist/host/egress-proxy.d.ts

@@ -0,0 +1,45 @@
+import { type Socket } from "node:net";
+/** `dns.lookup` with `{ all: true }`: every address a name resolves to. */
+export type EgressLookup = (hostname: string, options: {
+    all: true;
+    verbatim: true;
+}, callback: (error: NodeJS.ErrnoException | null, addresses: {
+    address: string;
+    family: number;
+}[]) => void) => void;
+export interface EgressProxyOptions {
+    /** Where the socket is made: a path in the session's LOCAL runtime directory (the machine's runtimeDir), never the
+     *  run's directory, which may sit on a disk other hosts mount. A socket there that refuses a connection (its proxy died
+     *  without removing it) is replaced; one that answers is a live proxy's, and the start is refused
+     *  (`egress_socket_in_use`); anything else there is refused and left as it is (`egress_socket_path_taken`). */
+    socketPath: string;
+    /** Connections open at once (tunnels and forwarded requests), past which a new one is refused. */
+    maxTunnels: number;
+    /** Connections in all, for the proxy's life, past which a new one is refused. */
+    maxConnections: number;
+    /** One line per decision: the host, the port, the address and the class. */
+    log: (line: string) => void;
+    /** How a name is resolved (a test's seam). Default: `dns.lookup`. */
+    lookup?: EgressLookup;
+    /** How a connection is opened to an address the table passed, in its canonical text (a test's seam). Default:
+     *  `net.connect`. Only an address that was checked ever reaches it. */
+    dial?: (address: string, port: number) => Socket;
+    /** More addresses to refuse as this host's, beside the interfaces read at each dial (a test's seam: it can only refuse
+     *  more). */
+    alsoLocal?: () => readonly string[];
+    /** The only hosts reached, as parseAllow takes them: exact names, or `*.suffix` for the names below one. Set, every
+     *  other host, any IP literal and any port but 80 and 443 are refused 403 (SOCKS reply 2, class `not-listed`) before
+     *  any lookup. Absent, every public host is reached. */
+    allow?: string | readonly string[];
+    /** What a refusal for a host off the list says to do, after its words (the caller's, which knows its settings): printable
+     *  ASCII, since it goes into the status line; anything else refuses the start. */
+    allowHint?: string;
+}
+/** A host list from its entries, or a comma list of them: each lowercased, its trailing dot dropped, the repeats gone.
+ *  Throws for an entry that is not a name of two labels or more, or `*.` and one (an address, a port, a URL, a bare `*`). */
+export declare function parseAllow(entries: string | readonly string[]): string[];
+export interface EgressProxy {
+    readonly socketPath: string;
+    close(): Promise<void>;
+}
+export declare function startEgressProxy(options: EgressProxyOptions): Promise<EgressProxy>;