@crewhaus/tool-proc 0.7.0 → 0.8.0

package/dist/index.js

@@ -26,14 +26,21 @@ import { accessSync, constants as fsConstants, statSync } from "node:fs";
 import { connect } from "node:net";
 import * as path from "node:path";
 import { buildTool } from "@crewhaus/tool-builder";
+import { checkEnvReveal } from "@crewhaus/tool-safety/env";
+import { describeRegexOutcome, openRegexSession } from "@crewhaus/tool-safety/regex";
 import { z } from "zod";
+import { portTarget, resolveListedHost } from "./lib/addr";
 import { backoffDelayMs, totalBackoffMs } from "./lib/backoff";
+import { ENV_REVEAL_KEY, PORT_HOSTS_KEY, portHostsFor, revealAllowFor } from "./lib/config";
 import { FALLBACK_PATH, buildSpawnEnv, inspectEnv } from "./lib/env";
 import { capText, compileSafePattern, formatArgv } from "./lib/format";
-import { __resetRegistryForTest, getProc, listProcs, markKilled, reapProc, startBackground, } from "./registry";
+import { hostPlatform, searchPath } from "./lib/which";
+import { __resetRegistryForTest, __stopAllForTest, getProc, listProcs, markKilled, reapProc, startBackground, watchFinished, } from "./registry";
 import { recheckContainment, resolveSafe, resolveSafeDir } from "./safe-path";
 import { runOnce, sleep } from "./spawn";
-export { __resetRegistryForTest };
+export { __resetRegistryForTest, __stopAllForTest };
+export { _resetProcConfig, registerProcConfig } from "./lib/config";
+export { _setDnsLookup } from "./lib/addr";
 /** Compact JSON — the reader is a model, not a person. */
 const json = (value) => JSON.stringify(value);
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -43,6 +50,8 @@ const MAX_WAIT_MS = 600_000;
 const DEFAULT_MAX_OUTPUT = 100_000;
 const MAX_MAX_OUTPUT = 1_000_000;
 const DEFAULT_POLL_MS = 100;
+/** The longest one WaitForOutput match may run in the regex worker. */
+const MATCH_BUDGET_MS = 2_000;
 // ---------------------------------------------------------------------------
 // shared schema pieces
 // ---------------------------------------------------------------------------
@@ -129,6 +138,9 @@ function outcomeJson(outcome) {
         stderr: outcome.stderr,
         ...(outcome.stdoutTruncated ? { stdoutTruncated: true } : {}),
         ...(outcome.stderrTruncated ? { stderrTruncated: true } : {}),
+        // The child exited, but a process it started held its output open past
+        // the drain grace: what came back is what arrived, perhaps not all of it.
+        ...(outcome.outputIncomplete === true ? { outputIncomplete: true } : {}),
     };
 }
 // ---------------------------------------------------------------------------
@@ -136,7 +148,8 @@ function outcomeJson(outcome) {
 // ---------------------------------------------------------------------------
 export const runCommand = buildTool({
     name: "RunCommand",
-    description: "Run a program from an argv array — the program and each argument as separate strings, with no shell anywhere, so an argument containing a space, a quote or $(...) stays an argument. Use it whenever a harness needs a program's exit code and output without the injection surface of a shell command line. The child inherits no environment except the names you forward, and always has a timeout.",
+    operativeArgs: [{ field: "argv", kind: "command", within: "cwd", env: "envSet", stdin: "stdin" }],
+    description: "Run a program from an argv array — the program and each argument as separate strings, with no shell anywhere, so an argument containing a space, a quote or $(...) stays an argument. Use it whenever a harness needs a program's exit code and output without the injection surface of a shell command line. The child inherits no environment except the names you forward, always has a timeout, and runs in a session of its own with no terminal: a program that prompts (sudo, ssh, gpg) fails instead of waiting for input.",
     inputSchema: z.object({
         argv: argvSchema,
         cwd: z.string().optional().describe("working directory, inside the workspace root"),
@@ -172,7 +185,10 @@ export const runCommand = buildTool({
 });
 export const runPipeline = buildTool({
     name: "RunPipeline",
-    description: "Run several argv commands in order, stopping at the first non-zero exit, and return every step's result. Use it for a short ordered chain — install, then build, then test — without spending a model turn between the steps. Steps run in sequence and do not pipe into each other; each gets its own stdin and its own timeout.",
+    operativeArgs: [
+        { field: "steps.argv", kind: "command", within: "cwd", env: "envSet", stdin: "stdin" },
+    ],
+    description: "Run several argv commands in order, stopping at the first non-zero exit, and return every step's result. Use it for a short ordered chain — install, then build, then test — without spending a model turn between the steps. Steps run in sequence and do not pipe into each other; each gets its own stdin and its own timeout, and runs with no terminal, so a step that prompts fails instead of waiting.",
     inputSchema: z.object({
         steps: z
             .array(z.object({
@@ -271,7 +287,8 @@ const backoffSchema = z
     .describe("the wait between attempts; declared by the caller, with no jitter, so a retry plan replays identically");
 export const retry = buildTool({
     name: "Retry",
-    description: "Re-run an argv command until it succeeds or a bounded attempt count runs out, waiting a caller-declared backoff between attempts. Use it for a flaky step — a service still starting, a lock still held — instead of asking a model to decide when to try again. The backoff is fixed or exponential with an explicit base and carries no jitter, and every attempt is reported.",
+    operativeArgs: [{ field: "argv", kind: "command", within: "cwd", env: "envSet", stdin: "stdin" }],
+    description: "Re-run an argv command until it succeeds or a bounded attempt count runs out, waiting a caller-declared backoff between attempts. Use it for a flaky step — a service still starting, a lock still held — instead of asking a model to decide when to try again. The backoff is fixed or exponential with an explicit base and carries no jitter, and every attempt is reported. Each attempt runs with no terminal, so one that prompts fails instead of waiting.",
     inputSchema: z.object({
         argv: argvSchema,
         maxAttempts: z.number().int().min(1).max(10),
@@ -390,6 +407,7 @@ function noSuchProc(toolName, id) {
 }
 export const processStart = buildTool({
     name: "ProcessStart",
+    operativeArgs: [{ field: "argv", kind: "command", within: "cwd", env: "envSet", stdin: "stdin" }],
     description: "Start a program in the background from an argv array and return an id immediately, without waiting for it to finish. Use it for something that must outlive one tool call — a dev server, a watcher, a tail — then poll it with ProcessStatus and ProcessOutput and end it with ProcessStop. The process is killed if the harness exits, so a session never leaks children.",
     inputSchema: z.object({
         argv: argvSchema,
@@ -439,6 +457,7 @@ export const processStatus = buildTool({
 });
 export const processOutput = buildTool({
     name: "ProcessOutput",
+    operativeArgs: [],
     description: "Return what a background process has written since the last poll, and its current status. Use it to follow a long-running process incrementally instead of buffering everything until it exits. Each call advances a per-stream cursor, so output is returned exactly once — use ProcessStatus for a look that consumes nothing.",
     inputSchema: z.object({
         id: procIdSchema,
@@ -475,6 +494,7 @@ export const processOutput = buildTool({
 });
 export const processStop = buildTool({
     name: "ProcessStop",
+    operativeArgs: [],
     description: "Stop a background process: signal it, wait a bounded grace period, then SIGKILL it if it is still alive. Use it to end a dev server or watcher deterministically rather than leaving it running past the task. Pass reap to drop the entry entirely; otherwise it stays readable so its final output can still be collected.",
     inputSchema: z.object({
         id: procIdSchema,
@@ -618,7 +638,8 @@ function probePort(host, port, timeoutMs) {
 const HOSTNAME = /^[A-Za-z0-9._:-]+$/;
 export const waitForPort = buildTool({
     name: "WaitForPort",
-    description: "Poll a TCP host and port until it is accepting connections, or until it stops, within a required deadline. Use it to wait for a server the harness just started to be ready, instead of guessing with a sleep. It reports whether the condition was met and how many probes it took, and never waits past the deadline.",
+    operativeArgs: [{ field: "host", kind: "recipient", default: "127.0.0.1" }],
+    description: "Poll a TCP host and port until it is accepting connections, or until it stops, within a required deadline. Use it to wait for a server the harness just started to be ready, instead of guessing with a sleep. It reports whether the condition was met and how many probes it took, and never waits past the deadline. It probes loopback (localhost, 127.0.0.1, ::1; 0.0.0.0 and :: are probed as loopback); any other host is refused unless the operator lists it in tool_config.proc.wait_for_port_hosts, and a listed name that does not resolve yet counts as not accepting connections.",
     inputSchema: z.object({
         port: z.number().int().min(1).max(65_535),
         host: z.string().max(255).optional().describe("default 127.0.0.1"),
@@ -637,16 +658,39 @@ export const waitForPort = buildTool({
         if (!HOSTNAME.test(host)) {
             return `[WaitForPort error] "${host}" is not a hostname or address.`;
         }
+        // Loopback, or a host the operator listed — decided before any DNS or
+        // socket, and dialled by the address checked (C144).
+        const allowed = portHostsFor(ctx?.toolConfig);
+        const target = portTarget(host, allowed, PORT_HOSTS_KEY);
+        if (!target.ok)
+            return target.message;
         const want = input.state ?? "open";
         const interval = input.intervalMs ?? DEFAULT_POLL_MS;
         const startedAt = Date.now();
         const deadline = startedAt + input.timeoutMs;
         let attempts = 0;
         let open = false;
+        // A listed name is looked up at each probe until it answers, then that
+        // address is dialled for the rest of the call. Until then the host
+        // accepts no connections: "not open yet", or already "closed".
+        let dial = "dial" in target ? target.dial : undefined;
+        const unresolvedNote = () => dial === undefined
+            ? { note: `"${host}" did not resolve; a name with no address accepts no connections` }
+            : {};
         while (Date.now() < deadline) {
             const remaining = deadline - Date.now();
             attempts++;
-            open = await probePort(host, input.port, Math.max(1, Math.min(1_000, remaining)));
+            if (dial === undefined && "resolve" in target) {
+                const resolved = await resolveListedHost(target.resolve, allowed, PORT_HOSTS_KEY);
+                if (!resolved.ok)
+                    return resolved.message;
+                if ("dial" in resolved)
+                    dial = resolved.dial;
+            }
+            open =
+                dial === undefined
+                    ? false
+                    : await probePort(dial, input.port, Math.max(1, Math.min(1_000, remaining)));
             if ((want === "open") === open) {
                 return json({
                     satisfied: true,
@@ -655,6 +699,7 @@ export const waitForPort = buildTool({
                     port: input.port,
                     attempts,
                     waitedMs: Date.now() - startedAt,
+                    ...unresolvedNote(),
                 });
             }
             if (ctx?.signal?.aborted === true)
@@ -673,6 +718,7 @@ export const waitForPort = buildTool({
             attempts,
             waitedMs: Date.now() - startedAt,
             reason: ctx?.signal?.aborted === true ? "aborted" : "deadline",
+            ...unresolvedNote(),
         });
     },
 });
@@ -788,7 +834,7 @@ export const waitForFile = buildTool({
 });
 export const waitForOutput = buildTool({
     name: "WaitForOutput",
-    description: "Watch a background process's output until a pattern matches, a failure pattern matches first, or a required deadline passes. Use it to wait for the line that means ready — 'Listening on', 'compiled successfully' — and to give up early when the line that means broken shows up instead. It reads without consuming, so ProcessOutput still returns everything afterwards.",
+    description: "Watch a background process's output until a pattern matches, a failure pattern matches first, or a required deadline passes. Use it to wait for the line that means ready — 'Listening on', 'compiled successfully' — and to give up early when the line that means broken shows up instead. It reads without consuming, so ProcessOutput still returns everything afterwards. A pattern that could not be evaluated ends the wait as undetermined (matched: null), never as a miss.",
     inputSchema: z.object({
         id: procIdSchema,
         pattern: z.string().min(1).describe("a JavaScript regular expression source"),
@@ -810,83 +856,142 @@ export const waitForOutput = buildTool({
         const bg = getProc(input.id);
         if (bg === undefined)
             return noSuchProc("WaitForOutput", input.id);
-        const success = compileSafePattern(input.pattern, input.flags ?? "");
+        const flags = input.flags ?? "";
+        // Screened up front so a refused pattern never runs (C079)…
+        const success = compileSafePattern(input.pattern, flags);
         if (!success.ok)
             return `[WaitForOutput error] ${success.message}`;
-        let failure;
         if (input.failurePattern !== undefined) {
-            const compiled = compileSafePattern(input.failurePattern, input.flags ?? "");
+            const compiled = compileSafePattern(input.failurePattern, flags);
             if (!compiled.ok)
                 return `[WaitForOutput error] failurePattern — ${compiled.message}`;
-            failure = compiled.regex;
         }
         const which = input.stream ?? "both";
         const interval = input.intervalMs ?? DEFAULT_POLL_MS;
         const startedAt = Date.now();
         const deadline = startedAt + input.timeoutMs;
+        // Whether a look is the last one is decided BEFORE it is taken. The
+        // exit, and the pipes' last bytes, can land while a match is running in
+        // the worker, so a process seen finished only afterwards gets one more
+        // look. What "finished" means for an exited process (its watched pipe has
+        // ended too) and a stopped one (its exit has been seen) is
+        // watchFinished's.
+        const finished = () => watchFinished(bg, which);
         const haystack = () => which === "stdout"
             ? bg.stdout
             : which === "stderr"
                 ? bg.stderr
                 : `${bg.stdout}\n${bg.stderr}`;
-        for (;;) {
-            const text = haystack();
-            const failed = failure?.exec(text) ?? null;
-            if (failed !== null) {
-                return json({
-                    matched: false,
-                    matchedFailure: true,
-                    id: bg.id,
-                    match: failed[0],
-                    status: bg.status,
-                    exitCode: bg.exitCode,
-                    waitedMs: Date.now() - startedAt,
-                });
-            }
-            const hit = success.regex.exec(text);
-            if (hit !== null) {
-                return json({
-                    matched: true,
-                    id: bg.id,
-                    match: hit[0],
-                    status: bg.status,
-                    exitCode: bg.exitCode,
-                    waitedMs: Date.now() - startedAt,
-                });
-            }
-            // A process that has exited will never produce the line; one last look
-            // has already happened above, so stop instead of burning the deadline.
-            if (bg.status !== "running") {
-                return json({
-                    matched: false,
-                    id: bg.id,
-                    reason: "process finished without matching",
-                    status: bg.status,
-                    exitCode: bg.exitCode,
-                    waitedMs: Date.now() - startedAt,
-                });
-            }
-            if (ctx?.signal?.aborted === true) {
-                return json({
-                    matched: false,
-                    id: bg.id,
-                    reason: "aborted",
-                    status: bg.status,
-                    waitedMs: Date.now() - startedAt,
-                });
-            }
-            const left = deadline - Date.now();
-            if (left <= 0) {
-                return json({
-                    matched: false,
-                    id: bg.id,
-                    reason: "deadline",
-                    status: bg.status,
-                    exitCode: bg.exitCode,
-                    waitedMs: Date.now() - startedAt,
-                });
+        // …and every match runs in @crewhaus/tool-safety's regex worker, under
+        // a deadline: a synchronous exec over this buffer could not be
+        // interrupted, and JavaScriptCore abandons a runaway one as "no match".
+        // An answer the worker could not give ends the wait as undetermined —
+        // never as "deadline", and never as a match that did not happen.
+        const session = openRegexSession();
+        const firstMatch = async (pattern, text) => {
+            const outcome = await session.run({
+                op: "matchAll",
+                pattern,
+                flags,
+                input: text,
+                maxMatches: 1,
+                deadlineMs: Math.max(100, Math.min(MATCH_BUDGET_MS, deadline - Date.now())),
+                ...(ctx?.signal !== undefined ? { signal: ctx.signal } : {}),
+                ...(ctx?.runContext !== undefined ? { runawayKey: ctx.runContext.sessionId } : {}),
+            });
+            if (outcome.status !== "ok")
+                return { ok: false, why: describeRegexOutcome(outcome) };
+            return { ok: true, match: outcome.result.matches[0]?.match };
+        };
+        const undetermined = (which, why) => 
+        // A run the caller's own abort ended is the abort, as before.
+        ctx?.signal?.aborted === true
+            ? json({
+                matched: false,
+                id: bg.id,
+                reason: "aborted",
+                status: bg.status,
+                waitedMs: Date.now() - startedAt,
+            })
+            : json({
+                matched: null,
+                id: bg.id,
+                reason: "undetermined",
+                detail: `${which} could not be evaluated against the output: ${why}`,
+                status: bg.status,
+                exitCode: bg.exitCode,
+                waitedMs: Date.now() - startedAt,
+            });
+        try {
+            for (;;) {
+                const last = finished();
+                const text = haystack();
+                if (input.failurePattern !== undefined) {
+                    const failed = await firstMatch(input.failurePattern, text);
+                    if (!failed.ok)
+                        return undetermined("failurePattern", failed.why);
+                    if (failed.match !== undefined) {
+                        return json({
+                            matched: false,
+                            matchedFailure: true,
+                            id: bg.id,
+                            match: failed.match,
+                            status: bg.status,
+                            exitCode: bg.exitCode,
+                            waitedMs: Date.now() - startedAt,
+                        });
+                    }
+                }
+                const hit = await firstMatch(input.pattern, text);
+                if (!hit.ok)
+                    return undetermined("pattern", hit.why);
+                if (hit.match !== undefined) {
+                    return json({
+                        matched: true,
+                        id: bg.id,
+                        match: hit.match,
+                        status: bg.status,
+                        exitCode: bg.exitCode,
+                        waitedMs: Date.now() - startedAt,
+                    });
+                }
+                // A process that had finished before this look will never produce the
+                // line, so stop instead of burning the deadline.
+                if (last) {
+                    return json({
+                        matched: false,
+                        id: bg.id,
+                        reason: "process finished without matching",
+                        status: bg.status,
+                        exitCode: bg.exitCode,
+                        waitedMs: Date.now() - startedAt,
+                    });
+                }
+                if (ctx?.signal?.aborted === true) {
+                    return json({
+                        matched: false,
+                        id: bg.id,
+                        reason: "aborted",
+                        status: bg.status,
+                        waitedMs: Date.now() - startedAt,
+                    });
+                }
+                const left = deadline - Date.now();
+                if (left <= 0) {
+                    return json({
+                        matched: false,
+                        id: bg.id,
+                        reason: "deadline",
+                        status: bg.status,
+                        exitCode: bg.exitCode,
+                        waitedMs: Date.now() - startedAt,
+                    });
+                }
+                await sleep(Math.min(interval, left), ctx?.signal);
             }
-            await sleep(Math.min(interval, left), ctx?.signal);
+        }
+        finally {
+            session.close();
         }
     },
 });
@@ -895,7 +1000,7 @@ export const waitForOutput = buildTool({
 // ---------------------------------------------------------------------------
 export const commandExists = buildTool({
     name: "CommandExists",
-    description: "Report whether a program is on PATH and where it resolves, without running it. Use it to check a prerequisite before building a plan around it, so a missing binary is a clear answer rather than a failed command. It searches the same PATH RunCommand would use, in order, and returns the first executable match.",
+    description: "Report whether a program is on PATH and where it resolves, without running it. Use it to check a prerequisite before building a plan around it, so a missing binary is a clear answer rather than a failed command. It searches the same PATH RunCommand would use, in order, and returns the first executable match; on Windows it tries PATHEXT's extensions (git finds git.exe) as the shell does.",
     inputSchema: z.object({
         name: z.string().min(1).max(255).describe("a bare program name such as 'git' — not a path"),
     }),
@@ -905,26 +1010,26 @@ export const commandExists = buildTool({
         if (input.name.includes("/") || input.name.includes("\\") || input.name.includes("\0")) {
             return `[CommandExists error] "${input.name}" is a path, not a program name — pass a bare name such as "git".`;
         }
-        const raw = process.env["PATH"] ?? FALLBACK_PATH;
-        const dirs = raw.split(path.delimiter).filter((d) => d !== "");
-        for (const dir of dirs) {
-            const candidate = path.join(dir, input.name);
-            try {
-                if (!statSync(candidate).isFile())
-                    continue;
-                accessSync(candidate, fsConstants.X_OK);
-                return json({ name: input.name, found: true, path: candidate, searchedDirs: dirs.length });
-            }
-            catch {
-                // Not here, or not executable — keep looking.
-            }
-        }
-        return json({ name: input.name, found: false, path: null, searchedDirs: dirs.length });
+        const platform = hostPlatform();
+        // The PATH RunCommand hands its child (buildSpawnEnv). FALLBACK_PATH is
+        // a POSIX list; a Windows host with no PATH has nothing to search.
+        const raw = process.env["PATH"] ?? (platform === "win32" ? "" : FALLBACK_PATH);
+        const found = searchPath(input.name, {
+            pathValue: raw,
+            platform,
+            pathext: process.env["PATHEXT"],
+        });
+        return json({
+            name: input.name,
+            found: found.path !== null,
+            path: found.path,
+            searchedDirs: found.searchedDirs,
+        });
     },
 });
 export const envInspect = buildTool({
     name: "EnvInspect",
-    description: "Report whether named environment variables are set, and how long their values are, revealing a value only when the caller names it. Use it to check that a credential or configuration variable is present before running something that needs it, without pulling the secret into context. There is no way to list the environment: a name you do not ask for is a name you learn nothing about.",
+    description: "Report whether named environment variables are set, and how long their values are. Use it to check that a credential or configuration variable is present before running something that needs it, without pulling the secret into context. A value is shown only for a variable named in `reveal` that the operator listed in tool_config.proc.env_reveal, and never for one whose name looks like a credential (a key, token, secret, password or credential URL), listed or not; any other name in `reveal` comes back with `withheld` and the reason. There is no way to list the environment: a name you do not ask for is a name you learn nothing about.",
     inputSchema: z.object({
         names: z
             .array(z.string().min(1).max(255))
@@ -935,22 +1040,29 @@ export const envInspect = buildTool({
             .array(z.string().min(1).max(255))
             .max(16)
             .optional()
-            .describe("variables whose actual value should be returned; must also appear in names"),
+            .describe("variables whose value should be returned; must also appear in names, and each must be listed in tool_config.proc.env_reveal and not look like a credential"),
     }),
     readOnly: true,
     concurrencySafe: true,
-    execute: async (input) => {
+    execute: async (input, ctx) => {
         const named = new Set(input.names);
         const reveal = input.reveal ?? [];
         const notNamed = reveal.filter((r) => !named.has(r));
         if (notNamed.length > 0) {
             return `[EnvInspect error] reveal lists ${notNamed.join(", ")}, which names does not — add them to names to inspect them.`;
         }
-        const { views, invalid } = inspectEnv(process.env, input.names, reveal);
+        // The list comes from the operator (tool_config), never from the call.
+        const allowed = revealAllowFor(ctx?.toolConfig);
+        const { views, invalid } = inspectEnv(process.env, input.names, reveal, (name) => checkEnvReveal(name, { allowed, configKey: ENV_REVEAL_KEY }));
+        const withheld = views.filter((v) => v.withheld !== undefined);
         return json({
             variables: views,
             ...(invalid.length > 0 ? { notEnvironmentNames: invalid } : {}),
-            note: "values are withheld unless named in reveal",
+            note: withheld.length === 0
+                ? "values are shown only for names in reveal that tool_config.proc.env_reveal lists"
+                : `values are shown only for names in reveal that ${ENV_REVEAL_KEY} lists, and never for a name that looks like a credential; ${withheld
+                    .map((v) => `${v.name}: ${v.withheld}`)
+                    .join(", ")}`,
         });
     },
 });

package/dist/lib/addr.d.ts

@@ -0,0 +1,129 @@
+/**
+ * What WaitForPort may dial (C144).
+ *
+ * WaitForPort is read-only, so plan and auto mode run it unasked, and it
+ * used to connect() to any host a call named: the cloud metadata address,
+ * the LAN, any port on loopback in an inet_aton spelling — a port-scan
+ * oracle, and a DNS query for any name the model chose. Its purpose is
+ * waiting for a server the harness just started, which is loopback. So
+ * loopback is allowed without configuration, and anything else only when
+ * the operator lists it in `tool_config.proc.wait_for_port_hosts`.
+ *
+ * Addresses are classified NUMERICALLY by the repository's shared
+ * private-address classifier, carried here as the byte-identical block
+ * apps/cli/src/tool-registry.test.ts hashes across every copy (so
+ * `0x7f.1`, `2130706433` and `::ffff:127.0.0.1` are all loopback, and
+ * `::ffff:169.254.169.254` is link-local).
+ */
+/**
+ * Canonicalise an IPv4 literal.
+ *
+ * `inet_aton` forms are the classic allow-list bypass: `0177.0.0.1`,
+ * `0x7f.0.0.1`, `2130706433` and `127.1` are all 127.0.0.1, and a check that
+ * only understands dotted-decimal waves every one of them through. Returns
+ * `null` when the string is not an IPv4 literal at all.
+ */
+export declare function normalizeIpv4(raw: string): string | null;
+/**
+ * Expand an IPv6 literal to its eight 16-bit groups, or `null` when the string
+ * is not one.
+ *
+ * Classifying IPv6 by its TEXT is where the bypasses live, because one address
+ * has many spellings and the one a check was written against is rarely the one
+ * that arrives. `http://[::ffff:169.254.169.254]/` never reaches a guard in
+ * that form: the WHATWG URL parser re-serialises the embedded quad as hex
+ * pieces, so what the guard sees is `::ffff:a9fe:a9fe`. Normalising to numbers
+ * first means the prefix tests below are arithmetic, and spelling stops
+ * mattering.
+ */
+export declare function parseIpv6(raw: string): ReadonlyArray<number> | null;
+/** Ranges that are never a public RPC endpoint. */
+export declare function isPrivateIp(address: string): boolean;
+/** True for 127.0.0.0/8, ::1, and a v6 spelling that carries a 127/8 address. */
+export declare function isLoopbackIp(address: string): boolean;
+/**
+ * True for link-local addresses, where cloud metadata services live:
+ * 169.254.0.0/16, fe80::/10, AWS's fd00:ec2::254, and a v6 spelling that
+ * carries a 169.254/16 address.
+ */
+export declare function isLinkLocalIp(address: string): boolean;
+/** The canonical spelling of an IP literal (dotted quad, or v6 as written), or null. */
+export declare function canonicalIp(address: string): string | null;
+export type DnsLookup = (host: string) => Promise<ReadonlyArray<string>>;
+/** Test seam: replace the resolver; `undefined` restores the system one. */
+export declare function _setDnsLookup(fn: DnsLookup | undefined): void;
+/**
+ * True for the unspecified address in any spelling (0.0.0.0, ::, an
+ * IPv4-mapped 0.0.0.0). A server that binds it prints it ("running on
+ * http://0.0.0.0:8000"), and dialling it reaches only this machine on Linux
+ * and macOS, so WaitForPort treats it as loopback and dials loopback itself,
+ * which also works where connecting to 0.0.0.0 does not (Windows).
+ */
+export declare function unspecifiedDial(address: string): string | null;
+/**
+ * An IPv6 literal in the form WaitForPort dials it, or `null` when it is not
+ * one or may not be dialled.
+ *
+ * The form is the URL parser's (`0:0:0:0:0:ffff:127.0.0.1` is
+ * `::ffff:7f00:1`), which is how a permission rule reads a host too, so the
+ * probe goes to the address classified here and decided on there, and no
+ * resolver reads the string again. A spelling the URL parser does not read
+ * as the address {@link parseIpv6} does has no one reading, and is not
+ * dialled: an IPv4 part with a leading zero is octal to parseIpv6, decimal
+ * to macOS's resolver and invalid to the URL parser, so `::ffff:0177.0.0.1`
+ * was classified as loopback and reached 177.0.0.1.
+ */
+export declare function ipv6Dial(address: string): string | null;
+export type PortTarget = {
+    readonly ok: true;
+    readonly dial: string;
+}
+/** A listed name, resolved at probe time by {@link resolveListedHost}. */
+ | {
+    readonly ok: true;
+    readonly resolve: string;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Decide what one WaitForPort call dials for `host`, or why it may not.
+ * Nothing here touches DNS.
+ *
+ * - `localhost`, and any IP literal that is loopback in any spelling, is
+ *   allowed with no configuration (a literal is dialled in its canonical
+ *   form, so `0x7f.1` dials 127.0.0.1, and an IPv6 one in the URL parser's,
+ *   see {@link ipv6Dial}). So is the unspecified address (0.0.0.0, ::),
+ *   dialled as 127.0.0.1 / ::1.
+ * - An IPv6 literal with no one reading (`::ffff:0177.0.0.1`) is refused,
+ *   listed or not.
+ * - Any other host must be listed in `allowed` (the operator's
+ *   `tool_config.proc.wait_for_port_hosts`), and is refused BEFORE any DNS
+ *   query, so an unlisted name is not a way to send one either.
+ * - A listed literal is dialled in that canonical form; a listed NAME is
+ *   resolved at probe time (`resolveListedHost`).
+ */
+export declare function portTarget(host: string, allowed: ReadonlyArray<string>, configKey: string): PortTarget;
+export type ListedResolution = {
+    readonly ok: true;
+    readonly dial: string;
+}
+/** No address yet: a name that does not resolve accepts no connections. */
+ | {
+    readonly ok: true;
+    readonly unresolved: true;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Resolve a listed name for one probe. An empty answer, or a failed lookup,
+ * is "not accepting connections" for that probe, not a refusal: a compose
+ * service's name exists only once its container does, and a torn-down one
+ * stops resolving — which is exactly "closed". Every answer is checked: a
+ * name that resolves to a link-local address (the cloud metadata service) is
+ * refused unless that address itself is listed. The caller dials the address
+ * returned, and keeps dialling it for the rest of the call, so a resolver
+ * that answers differently later cannot move the probe.
+ */
+export declare function resolveListedHost(host: string, allowed: ReadonlyArray<string>, configKey: string): Promise<ListedResolution>;