@jitsusama/agentic-harness.core 0.1.0

package/dist/completion/index.js

@@ -0,0 +1,16 @@
+/**
+ * Side completions: run a one-shot completion against a model
+ * from the registry, off the agent's own loop.
+ *
+ * The advisor and correction capture both need a cheap second
+ * model to distill or judge without disturbing the doer. This is
+ * the shared mechanism, proven by the milestone-5 probe.
+ *
+ * Actually running a model is a port (`CompleteSimple`), not
+ * something this package can do on its own: `runSideCompletion` and
+ * `runInvestigation` both take one as a parameter. An adapter
+ * resolves its own host's completion function and passes it in.
+ */
+export { runInvestigation, } from "./investigate.js";
+export { looksLikeGlm, pickModel, } from "./resolve.js";
+export { runSideCompletion, } from "./side.js";

package/dist/completion/investigate.d.ts

@@ -0,0 +1,63 @@
+/**
+ * A bounded, tool-using investigation against a side model.
+ *
+ * The advisor is a tool-using investigator, not a
+ * transcript-only judge: it must be able to check a suspicion
+ * against the workspace before it raises it. This runs a capped
+ * loop where the model may call read-only tools, each result is
+ * fed back into the same growing message list, and the loop ends
+ * when the model answers with text or the step budget runs out.
+ *
+ * The message list is the caller's persistent context, so the
+ * prefix caches turn to turn: the cost lever the advisor design
+ * rests on. Usage is summed across every step of the loop.
+ *
+ * `complete` is a port, the same as runSideCompletion's: this
+ * module has no way to run a model itself, and does not know or
+ * care what backend the caller's host runs one through.
+ */
+import { type ModelRef } from "./resolve.js";
+import type { CompleteSimple, CompletionRegistry, CompletionUsage } from "./types.js";
+/** A read-only tool the investigation may call. */
+export interface LoopTool {
+    readonly name: string;
+    readonly description: string;
+    /** JSON schema for the tool's arguments. */
+    readonly parameters: unknown;
+    /** Run the tool and return its text result. */
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+/** What to investigate and with what budget. */
+export interface InvestigationRequest {
+    readonly provider?: string;
+    readonly model?: string;
+    readonly systemPrompt: string;
+    /** The persistent message list; appended to in place-safe copies. */
+    readonly messages: unknown[];
+    readonly tools: LoopTool[];
+    readonly current?: ModelRef;
+    /** Maximum model round-trips before the loop stops. */
+    readonly maxSteps: number;
+    readonly signal?: AbortSignal;
+}
+/** The outcome of an investigation. */
+export interface InvestigationResult {
+    readonly ok: boolean;
+    readonly text: string;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly usage: CompletionUsage;
+    /** Model round-trips actually made. */
+    readonly steps: number;
+    /** The grown message list, for the caller to keep as context. */
+    readonly messages: unknown[];
+    readonly error?: string;
+}
+/**
+ * Run a bounded investigation. Resolves a model and its auth,
+ * then loops the model against `tools` through `complete`, feeding
+ * each tool result back in, until the model answers with text or
+ * `maxSteps` is reached. Every failure path returns `ok: false`
+ * with a message rather than throwing.
+ */
+export declare function runInvestigation(registry: CompletionRegistry, request: InvestigationRequest, complete: CompleteSimple): Promise<InvestigationResult>;

package/dist/completion/investigate.js

@@ -0,0 +1,198 @@
+/**
+ * A bounded, tool-using investigation against a side model.
+ *
+ * The advisor is a tool-using investigator, not a
+ * transcript-only judge: it must be able to check a suspicion
+ * against the workspace before it raises it. This runs a capped
+ * loop where the model may call read-only tools, each result is
+ * fed back into the same growing message list, and the loop ends
+ * when the model answers with text or the step budget runs out.
+ *
+ * The message list is the caller's persistent context, so the
+ * prefix caches turn to turn: the cost lever the advisor design
+ * rests on. Usage is summed across every step of the loop.
+ *
+ * `complete` is a port, the same as runSideCompletion's: this
+ * module has no way to run a model itself, and does not know or
+ * care what backend the caller's host runs one through.
+ */
+import { pickModel } from "./resolve.js";
+const ZERO_USAGE = {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+};
+/** Sum two usage records bucket by bucket. */
+function addUsage(a, b) {
+    return {
+        input: a.input + b.input,
+        output: a.output + b.output,
+        cacheRead: a.cacheRead + b.cacheRead,
+        cacheWrite: a.cacheWrite + b.cacheWrite,
+        totalTokens: a.totalTokens + b.totalTokens,
+        cost: {
+            input: a.cost.input + b.cost.input,
+            output: a.cost.output + b.cost.output,
+            cacheRead: a.cost.cacheRead + b.cost.cacheRead,
+            cacheWrite: a.cost.cacheWrite + b.cost.cacheWrite,
+            total: a.cost.total + b.cost.total,
+        },
+    };
+}
+/** Concatenate the text out of a content block list. */
+function textOf(content) {
+    return content
+        .filter((b) => b.type === "text" && typeof b.text === "string")
+        .map((b) => b.text)
+        .join("");
+}
+/** The tool calls present in a content block list. */
+function toolCallsOf(content) {
+    return content.filter((b) => b.type === "toolCall" && b.name);
+}
+/**
+ * Run a bounded investigation. Resolves a model and its auth,
+ * then loops the model against `tools` through `complete`, feeding
+ * each tool result back in, until the model answers with text or
+ * `maxSteps` is reached. Every failure path returns `ok: false`
+ * with a message rather than throwing.
+ */
+export async function runInvestigation(registry, request, complete) {
+    const model = pickModel(registry.getAvailable(), request.current, { provider: request.provider, model: request.model }, (p, m) => registry.find(p, m));
+    if (!model) {
+        return {
+            ok: false,
+            text: "",
+            usage: ZERO_USAGE,
+            steps: 0,
+            messages: request.messages,
+            error: "no model available",
+        };
+    }
+    let auth;
+    try {
+        auth = await registry.getApiKeyAndHeaders(model);
+    }
+    catch (err) {
+        return failure(model, request.messages, `auth resolution threw: ${msg(err)}`);
+    }
+    if (!auth.ok) {
+        return failure(model, request.messages, `auth not configured: ${auth.error}`);
+    }
+    const toolDefs = request.tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters,
+    }));
+    const byName = new Map(request.tools.map((t) => [t.name, t]));
+    const messages = [...request.messages];
+    let usage = ZERO_USAGE;
+    for (let step = 1; step <= request.maxSteps; step++) {
+        let result;
+        try {
+            // The persistent context holds raw runtime messages
+            // (assistant turns and tool results), and tools ride
+            // alongside; the compat surface is typed narrowly here, so
+            // the whole context is cast to what complete expects.
+            const context = {
+                systemPrompt: request.systemPrompt,
+                messages,
+                tools: toolDefs,
+            };
+            result = await complete(model, context, {
+                apiKey: auth.apiKey,
+                headers: auth.headers,
+                env: auth.env,
+                signal: request.signal,
+            });
+        }
+        catch (err) {
+            return {
+                ok: false,
+                text: "",
+                provider: model.provider,
+                model: model.id,
+                usage,
+                steps: step - 1,
+                messages,
+                error: `completion threw: ${msg(err)}`,
+            };
+        }
+        if (result.usage)
+            usage = addUsage(usage, result.usage);
+        const content = result.content;
+        const calls = toolCallsOf(content);
+        messages.push(result);
+        if (calls.length === 0) {
+            return {
+                ok: result.stopReason !== "error",
+                text: textOf(content),
+                provider: model.provider,
+                model: model.id,
+                usage,
+                steps: step,
+                messages,
+                error: result.errorMessage,
+            };
+        }
+        for (const call of calls) {
+            const tool = call.name ? byName.get(call.name) : undefined;
+            let text;
+            let isError = false;
+            if (!tool) {
+                text = `Unknown tool: ${call.name}`;
+                isError = true;
+            }
+            else {
+                try {
+                    text = await tool.execute(call.arguments ?? {});
+                }
+                catch (err) {
+                    text = `Tool ${call.name} failed: ${msg(err)}`;
+                    isError = true;
+                }
+            }
+            messages.push({
+                role: "toolResult",
+                toolCallId: call.id,
+                toolName: call.name,
+                content: [{ type: "text", text }],
+                isError,
+                timestamp: Date.now(),
+            });
+        }
+    }
+    // Budget exhausted with the model still calling tools: return
+    // what we have as a non-error, so the caller can still use any
+    // partial text and the loop never runs unbounded.
+    return {
+        ok: true,
+        text: "",
+        provider: model.provider,
+        model: model.id,
+        usage,
+        steps: request.maxSteps,
+        messages,
+        error: "step budget exhausted",
+    };
+}
+/** Human-readable message from an unknown thrown value. */
+function msg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Build a uniform failure result. */
+function failure(model, messages, error) {
+    return {
+        ok: false,
+        text: "",
+        provider: model.provider,
+        model: model.id,
+        usage: ZERO_USAGE,
+        steps: 0,
+        messages,
+        error,
+    };
+}

package/dist/completion/resolve.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Pure model selection for a side completion.
+ *
+ * Choosing which model a side completion runs against is
+ * independent of actually running it, so it lives here as a pure
+ * function over a model list. The advisor and correction capture
+ * both want the same order: an explicit target first, then a name
+ * match, then a GLM-shaped model (the intended cheap watcher),
+ * then the caller's current model as a last resort.
+ */
+/** The minimum a model reference needs for selection. */
+export interface ModelRef {
+    readonly id: string;
+    readonly provider: string;
+}
+/** A caller's target: an explicit provider and/or model id. */
+export interface ModelTarget {
+    readonly provider?: string;
+    readonly model?: string;
+}
+/** True when a model looks like a GLM / Zhipu model. */
+export declare function looksLikeGlm(model: ModelRef): boolean;
+/**
+ * Choose a model for a side completion, in preference order:
+ * an explicit provider+model resolved through `find`, then a
+ * name match in `available`, then a GLM-shaped model, then the
+ * caller's `current` model. Returns undefined when nothing fits.
+ */
+export declare function pickModel(available: ModelRef[], current: ModelRef | undefined, target: ModelTarget, find?: (provider: string, model: string) => ModelRef | undefined): ModelRef | undefined;

package/dist/completion/resolve.js

@@ -0,0 +1,42 @@
+/**
+ * Pure model selection for a side completion.
+ *
+ * Choosing which model a side completion runs against is
+ * independent of actually running it, so it lives here as a pure
+ * function over a model list. The advisor and correction capture
+ * both want the same order: an explicit target first, then a name
+ * match, then a GLM-shaped model (the intended cheap watcher),
+ * then the caller's current model as a last resort.
+ */
+/** True when a model looks like a GLM / Zhipu model. */
+export function looksLikeGlm(model) {
+    const needle = /glm|z-?ai|zhipu/i;
+    return needle.test(model.id) || needle.test(model.provider);
+}
+/**
+ * Choose a model for a side completion, in preference order:
+ * an explicit provider+model resolved through `find`, then a
+ * name match in `available`, then a GLM-shaped model, then the
+ * caller's `current` model. Returns undefined when nothing fits.
+ */
+export function pickModel(available, current, target, find) {
+    if (target.provider && target.model) {
+        const found = find?.(target.provider, target.model);
+        if (found)
+            return found;
+    }
+    if (target.model) {
+        const byId = available.find((m) => m.id === target.model);
+        if (byId)
+            return byId;
+    }
+    // A provider named without a model still narrows the choice, per
+    // the "provider and/or model" contract: honour it before the
+    // GLM guess so an explicit request is not silently dropped.
+    if (target.provider) {
+        const byProvider = available.find((m) => m.provider === target.provider);
+        if (byProvider)
+            return byProvider;
+    }
+    return available.find(looksLikeGlm) ?? current;
+}

package/dist/completion/side.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Run a one-shot side completion against a model from the
+ * registry, without touching the agent's own loop.
+ *
+ * This is the mechanism the advisor and correction capture are
+ * built on: resolve a model and its request auth from the
+ * registry, then run the caller-supplied `complete` against it.
+ * The result is a plain value with the text, usage and outcome,
+ * so callers never see the underlying message shape.
+ *
+ * `complete` is a port: this module has no way to run a model
+ * itself, and does not know or care what backend the caller's host
+ * runs one through. pi's adapter resolves its own
+ * `@earendil-works/pi-ai/compat` `completeSimple` and passes it in;
+ * a different host supplies its own equivalent.
+ */
+import { type ModelRef } from "./resolve.js";
+import type { CompleteSimple, CompletionMessage, CompletionRegistry, CompletionUsage } from "./types.js";
+/** What to complete: the target model, a system prompt and turns. */
+export interface SideCompletionRequest {
+    /** Explicit provider, when targeting a specific model. */
+    readonly provider?: string;
+    /** Explicit model id, when targeting a specific model. */
+    readonly model?: string;
+    /** System prompt for the completion. */
+    readonly systemPrompt: string;
+    /** A single user prompt, or a full message list. */
+    readonly prompt?: string;
+    readonly messages?: CompletionMessage[];
+    /** The caller's current model, used as a last-resort target. */
+    readonly current?: ModelRef;
+    readonly signal?: AbortSignal;
+}
+/** The outcome of a side completion. */
+export interface SideCompletionResult {
+    readonly ok: boolean;
+    readonly text: string;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly usage?: CompletionUsage;
+    readonly stopReason?: string;
+    readonly error?: string;
+}
+/**
+ * Resolve a model and its auth from `registry`, run one
+ * completion through `complete` and return the text and usage.
+ * Every failure path (no model, no auth, a throwing call) returns
+ * `ok: false` with a message rather than throwing, so a caller on a
+ * hot path can degrade quietly.
+ */
+export declare function runSideCompletion(registry: CompletionRegistry, request: SideCompletionRequest, complete: CompleteSimple): Promise<SideCompletionResult>;

package/dist/completion/side.js

@@ -0,0 +1,93 @@
+/**
+ * Run a one-shot side completion against a model from the
+ * registry, without touching the agent's own loop.
+ *
+ * This is the mechanism the advisor and correction capture are
+ * built on: resolve a model and its request auth from the
+ * registry, then run the caller-supplied `complete` against it.
+ * The result is a plain value with the text, usage and outcome,
+ * so callers never see the underlying message shape.
+ *
+ * `complete` is a port: this module has no way to run a model
+ * itself, and does not know or care what backend the caller's host
+ * runs one through. pi's adapter resolves its own
+ * `@earendil-works/pi-ai/compat` `completeSimple` and passes it in;
+ * a different host supplies its own equivalent.
+ */
+import { pickModel } from "./resolve.js";
+/** Pull the plain text out of a completion's content blocks. */
+function textOf(content) {
+    return content
+        .filter((c) => c.type === "text" && typeof c.text === "string")
+        .map((c) => c.text)
+        .join("");
+}
+/**
+ * Resolve a model and its auth from `registry`, run one
+ * completion through `complete` and return the text and usage.
+ * Every failure path (no model, no auth, a throwing call) returns
+ * `ok: false` with a message rather than throwing, so a caller on a
+ * hot path can degrade quietly.
+ */
+export async function runSideCompletion(registry, request, complete) {
+    const available = registry.getAvailable();
+    const model = pickModel(available, request.current, { provider: request.provider, model: request.model }, (p, m) => registry.find(p, m));
+    if (!model) {
+        return { ok: false, text: "", error: "no model available" };
+    }
+    let auth;
+    try {
+        auth = await registry.getApiKeyAndHeaders(model);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            text: "",
+            provider: model.provider,
+            model: model.id,
+            error: `auth resolution threw: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (!auth.ok) {
+        return {
+            ok: false,
+            text: "",
+            provider: model.provider,
+            model: model.id,
+            error: `auth not configured: ${auth.error}`,
+        };
+    }
+    const messages = request.messages ?? [
+        {
+            role: "user",
+            content: request.prompt ?? "",
+            timestamp: Date.now(),
+        },
+    ];
+    try {
+        const result = await complete(model, { systemPrompt: request.systemPrompt, messages }, {
+            apiKey: auth.apiKey,
+            headers: auth.headers,
+            env: auth.env,
+            signal: request.signal,
+        });
+        return {
+            ok: result.stopReason !== "error",
+            text: textOf(result.content),
+            provider: model.provider,
+            model: model.id,
+            usage: result.usage,
+            stopReason: result.stopReason,
+            error: result.errorMessage,
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            text: "",
+            provider: model.provider,
+            model: model.id,
+            error: `completion threw: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}

package/dist/completion/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Type surface for the side-completion boundary.
+ *
+ * `CompleteSimple` is the port: this package has no way to run a
+ * model itself, so `runSideCompletion` and `runInvestigation` both
+ * take one as a parameter and call it rather than reaching for a
+ * concrete backend. `CompatModule` names the shape an adapter gets
+ * back from dynamically importing its own completion function
+ * (pi's is `@earendil-works/pi-ai/compat`'s `completeSimple`,
+ * reached that way because pi's own typecheck dependency resolves
+ * an older pi-ai where the subpath does not exist); a host with no
+ * such subpath quirk can just pass a function of the same shape.
+ */
+import type { ModelRef } from "./resolve.js";
+/** A per-bucket money breakdown returned by a completion. */
+export interface CompletionCost {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+    readonly total: number;
+}
+/** Token usage and cost returned by a completion. */
+export interface CompletionUsage {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+    readonly totalTokens: number;
+    readonly cost: CompletionCost;
+}
+/** One message in a completion context. */
+export interface CompletionMessage {
+    readonly role: "user" | "assistant";
+    readonly content: string;
+    readonly timestamp: number;
+}
+/** The context a completion runs against. */
+export interface CompletionContext {
+    readonly systemPrompt: string;
+    readonly messages: CompletionMessage[];
+}
+/** Request auth resolved from the model registry. */
+export interface CompletionAuth {
+    readonly apiKey?: string;
+    readonly headers?: Record<string, string>;
+    readonly env?: Record<string, string>;
+}
+/** The assistant message a completion returns. */
+export interface CompletionMessageResult {
+    readonly content: Array<{
+        type: string;
+        text?: string;
+    }>;
+    readonly usage: CompletionUsage;
+    readonly stopReason: string;
+    readonly errorMessage?: string;
+}
+/** The `completeSimple` function as this package calls it. */
+export type CompleteSimple = (model: ModelRef, context: CompletionContext, options: CompletionAuth & {
+    signal?: AbortSignal;
+}) => Promise<CompletionMessageResult>;
+/** The compat module shape reached by dynamic import. */
+export interface CompatModule {
+    readonly completeSimple: CompleteSimple;
+}
+/**
+ * The registry surface a side completion needs. Structurally
+ * satisfied by pi's `ctx.modelRegistry`, kept minimal so the
+ * helper is testable with a fake.
+ */
+export interface CompletionRegistry {
+    getAvailable(): ModelRef[];
+    find(provider: string, model: string): ModelRef | undefined;
+    getApiKeyAndHeaders(model: ModelRef): Promise<{
+        ok: true;
+        apiKey?: string;
+        headers?: Record<string, string>;
+        env?: Record<string, string>;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+}

package/dist/completion/types.js

@@ -0,0 +1,14 @@
+/**
+ * Type surface for the side-completion boundary.
+ *
+ * `CompleteSimple` is the port: this package has no way to run a
+ * model itself, so `runSideCompletion` and `runInvestigation` both
+ * take one as a parameter and call it rather than reaching for a
+ * concrete backend. `CompatModule` names the shape an adapter gets
+ * back from dynamically importing its own completion function
+ * (pi's is `@earendil-works/pi-ai/compat`'s `completeSimple`,
+ * reached that way because pi's own typecheck dependency resolves
+ * an older pi-ai where the subpath does not exist); a host with no
+ * such subpath quirk can just pass a function of the same shape.
+ */
+export {};

package/dist/exec/exec.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The one impure thing a library here needs: running a command.
+ *
+ * Taking it as a dependency rather than importing pi's own exec keeps every caller
+ * testable, and keeps these libraries usable by anything that can run a command.
+ *
+ * It lived under the review providers until two libraries needed it. Review reaches
+ * a backend by running its CLI and work reaches git the same way, so `lib/work`
+ * imported the type out of `lib/review/providers`, which said the working layer
+ * depended on the reviewing one when the only thing it wanted was the shape of a
+ * subprocess. Neither owns this. It sits at the level that matches what it is.
+ */
+/** What running a command returns. */
+export interface ExecResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/** Runs a command and returns its result rather than throwing. */
+export type Exec = (command: string, args: string[]) => Promise<ExecResult>;
+/** What every provider factory takes. */
+export interface ProviderDeps {
+    exec: Exec;
+}
+/**
+ * Run a command, throwing with the backend's own words when it
+ * fails. A CLI's stderr is usually the most useful diagnostic
+ * available, so it is preserved rather than replaced.
+ *
+ * Both streams are kept when both said something, because they carry
+ * different halves of the same answer and the useful half was being thrown
+ * away. `gh api` writes its own summary to stderr and the server's response
+ * body to stdout, so preferring stderr reduced a 422 that named the exact
+ * offending field to `gh: Unprocessable Entity (HTTP 422)`. That is a
+ * complete sentence about nothing: the field name is what tells you the
+ * request was wrong rather than the change.
+ */
+export declare function run(exec: Exec, command: string, args: string[], what: string): Promise<string>;

package/dist/exec/exec.js

@@ -0,0 +1,51 @@
+/**
+ * The one impure thing a library here needs: running a command.
+ *
+ * Taking it as a dependency rather than importing pi's own exec keeps every caller
+ * testable, and keeps these libraries usable by anything that can run a command.
+ *
+ * It lived under the review providers until two libraries needed it. Review reaches
+ * a backend by running its CLI and work reaches git the same way, so `lib/work`
+ * imported the type out of `lib/review/providers`, which said the working layer
+ * depended on the reviewing one when the only thing it wanted was the shape of a
+ * subprocess. Neither owns this. It sits at the level that matches what it is.
+ */
+/**
+ * Run a command, throwing with the backend's own words when it
+ * fails. A CLI's stderr is usually the most useful diagnostic
+ * available, so it is preserved rather than replaced.
+ *
+ * Both streams are kept when both said something, because they carry
+ * different halves of the same answer and the useful half was being thrown
+ * away. `gh api` writes its own summary to stderr and the server's response
+ * body to stdout, so preferring stderr reduced a 422 that named the exact
+ * offending field to `gh: Unprocessable Entity (HTTP 422)`. That is a
+ * complete sentence about nothing: the field name is what tells you the
+ * request was wrong rather than the change.
+ */
+export async function run(exec, command, args, what) {
+    const result = await exec(command, args);
+    if (result.code !== 0) {
+        throw new Error(`${what} failed: ${failureDetail(result, command)}`);
+    }
+    return result.stdout;
+}
+/**
+ * How much of a stream to keep in a failure message.
+ *
+ * An error body is a line or two; a command that fails after writing real
+ * output can put a whole diff on stdout, and a message nobody will read to
+ * the end is its own kind of silence.
+ */
+const DETAIL_LIMIT = 2000;
+/** As much of both streams as says something, in the order they matter. */
+function failureDetail(result, command) {
+    const said = [result.stderr.trim(), result.stdout.trim()]
+        .filter((stream) => stream !== "")
+        // The same words on both streams read like two problems.
+        .filter((stream, at, all) => all.indexOf(stream) === at)
+        .map((stream) => stream.length > DETAIL_LIMIT
+        ? `${stream.slice(0, DETAIL_LIMIT)}\u2026`
+        : stream);
+    return said.join("\n") || `${command} exited nonzero`;
+}