@dna113p/machines 0.2.0 → 0.3.1

package/dist/src/run-status.js

@@ -0,0 +1,336 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+const staleAfterMilliseconds = 60 * 60 * 1_000;
+/** How long a record goes on naming a response its run took: longer than a sender waits to hear of it. */
+export const deliveryRetentionMilliseconds = 60_000;
+const disabled = { update() { }, finish() { } };
+let temporaryFiles = 0;
+/** The directory runs publish to, or undefined while publication is off. */
+export function runStatusDirectory(environment = process.env) {
+    const configured = environment.MACHINES_RUN_STATUS_DIR;
+    return configured === undefined || configured === "" ? undefined : resolve(configured);
+}
+/** The one pending outside response for a run, kept beside its record. */
+export function runInboxPath(directory, id) {
+    return join(directory, `${id}.inbox`);
+}
+/**
+ * A second name for a response in a run's inbox, which its sender keeps. Only
+ * the sender and the run remove it, and whichever does owns the response.
+ */
+export function runDeliveryPath(directory, id, delivery) {
+    return join(directory, `.${id}.${delivery}.inbox.sent`);
+}
+/**
+ * Publishes one run for hosts that can only read files, such as a status line.
+ * Opt-in through MACHINES_RUN_STATUS_DIR. Publication is presentation: it never
+ * throws, and it records neither Machine input nor output.
+ */
+export function createRunStatusPublisher(run, environment = process.env) {
+    const directory = runStatusDirectory(environment);
+    const id = run.id ?? randomUUID();
+    if (directory === undefined || !isFileSafeId(id))
+        return disabled;
+    const owner = (run.owner ?? runSessionId(environment)) || undefined;
+    const parent = environment.MACHINES_RUN_PARENT || undefined;
+    const label = formatLabel(run.label ?? environment.MACHINES_RUN_LABEL);
+    const startedAt = run.startedAt ?? new Date().toISOString();
+    let status = "running";
+    let state;
+    let stateSince;
+    let agent;
+    let limit;
+    let human;
+    let deliveries = [];
+    let error;
+    const publish = () => {
+        const record = {
+            schemaVersion: 2,
+            id,
+            pid: process.pid,
+            ...(owner === undefined ? {} : { owner }),
+            ...(parent === undefined ? {} : { parent }),
+            ...(label === undefined ? {} : { label }),
+            machine: run.machine,
+            path: run.path,
+            cwd: run.cwd,
+            status,
+            ...(state === undefined ? {} : { state }),
+            ...(stateSince === undefined ? {} : { stateSince }),
+            ...(agent === undefined ? {} : { agent }),
+            ...(limit === undefined ? {} : { limit }),
+            ...(human === undefined ? {} : { human }),
+            ...(run.answeredBy === undefined ? {} : { answeredBy: run.answeredBy }),
+            ...(deliveries.length === 0 ? {} : { deliveries: deliveries.map((delivery) => delivery.id) }),
+            ...(error === undefined ? {} : { error }),
+            startedAt,
+            updatedAt: new Date().toISOString(),
+        };
+        try {
+            mkdirSync(directory, { recursive: true, mode: 0o700 });
+            // Readers only ever see a whole record: write beside it, then rename over it.
+            const temporary = join(directory, `.${id}.${process.pid}.${temporaryFiles += 1}.tmp`);
+            try {
+                writeFileSync(temporary, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+                renameSync(temporary, join(directory, `${id}.json`));
+            }
+            catch (cause) {
+                rmSync(temporary, { force: true });
+                throw cause;
+            }
+        }
+        catch {
+            // A status line is never worth a run: an unwritable directory is ignored.
+        }
+    };
+    try {
+        pruneRunStatuses(directory);
+    }
+    catch {
+        // Pruning is best effort for the same reason.
+    }
+    publish();
+    return {
+        update(change) {
+            if (status === "completed" || status === "failed")
+                return;
+            const nextState = "state" in change ? formatState(change.state) : state;
+            const next = {
+                status: change.status ?? status,
+                state: nextState,
+                agent: "agent" in change ? pickAgent(change.agent) : agent,
+                // A wait belongs to the state whose Agent is waiting.
+                limit: "limit" in change ? pickLimit(change.limit) : nextState === state ? limit : undefined,
+                human: "human" in change ? pickHuman(change.human) : human,
+                // A later response must not hide an earlier one from a sender that has yet to look.
+                deliveries: change.delivery === undefined ? deliveries : [
+                    ...deliveries.filter((delivery) => Date.now() - delivery.takenAt < deliveryRetentionMilliseconds),
+                    { id: change.delivery, takenAt: Date.now() },
+                ],
+            };
+            // Repeated notifications for an unchanged run do not need another write.
+            if (JSON.stringify(next) === JSON.stringify({ status, state, agent, limit, human, deliveries }))
+                return;
+            if (next.state !== state)
+                stateSince = new Date().toISOString();
+            ({ status, state, agent, limit, human, deliveries } = next);
+            publish();
+        },
+        finish(outcome) {
+            if (status === "completed" || status === "failed")
+                return;
+            if ("error" in outcome) {
+                status = "failed";
+                error = outcome.error;
+            }
+            else {
+                status = "completed";
+                state = formatState(outcome.state) ?? state;
+            }
+            stateSince = undefined;
+            agent = undefined;
+            limit = undefined;
+            human = undefined;
+            publish();
+            try {
+                // Nothing reads the inbox from here on, and only the run empties it.
+                rmSync(runInboxPath(directory, id), { force: true });
+            }
+            catch {
+                // Left for pruning.
+            }
+        },
+    };
+}
+/**
+ * Turns what a run reports as it executes into the changes to its record, for
+ * `machine run` and for a hosted run alike.
+ */
+export function runStatusObserver(update) {
+    let publishedState;
+    // A runner reports its identity as it starts. For a state entered by a
+    // transition that is before the state is announced, so an identity is held
+    // for the rest of the tick and published with the state it belongs to.
+    let arriving;
+    return {
+        onAgentUpdate(agent) {
+            if (agent.type === "identity") {
+                arriving = agent;
+                queueMicrotask(() => {
+                    if (arriving !== agent)
+                        return;
+                    arriving = undefined;
+                    update({ agent });
+                });
+            }
+            else if (agent.type === "limit" && agent.status !== "swapped") {
+                // A swap while every preset is being tried again leaves the wait as it is published.
+                update({
+                    limit: agent.status === "resumed"
+                        ? undefined
+                        : { text: agent.text, ...(agent.until === undefined ? {} : { until: agent.until }) },
+                });
+            }
+        },
+        onState(state) {
+            const entered = formatState(state);
+            if (entered === publishedState)
+                update({ state });
+            else {
+                update({ state, agent: arriving });
+                arriving = undefined;
+            }
+            publishedState = entered;
+        },
+    };
+}
+/**
+ * The session a process belongs to: the owner of the runs it starts, and the
+ * session whose watch list `machine watch` changes.
+ */
+export function runSessionId(environment = process.env) {
+    return environment.MACHINES_RUN_OWNER || environment.CLAUDE_CODE_SESSION_ID || undefined;
+}
+/** Returns the valid records in a directory. Unreadable or malformed files are skipped. */
+export function readRunStatuses(directory) {
+    return readRecordFiles(directory).map(({ record }) => record);
+}
+function pruneRunStatuses(directory) {
+    const now = Date.now();
+    for (const { file, record } of readRecordFiles(directory)) {
+        const settled = record.status === "completed" || record.status === "failed" || !isProcessAlive(record.pid);
+        if (!settled || now - Date.parse(record.updatedAt) <= staleAfterMilliseconds)
+            continue;
+        try {
+            rmSync(file, { force: true });
+            // A response nobody collected goes with the run it was meant for, under each of its names.
+            const id = basename(file, ".json");
+            rmSync(runInboxPath(directory, id), { force: true });
+            for (const name of readdirSync(directory)) {
+                if (!name.startsWith(`.${id}.`))
+                    continue;
+                if (/^[^.]+\.inbox\.(?:sent|taken)$/u.test(name.slice(id.length + 2)))
+                    rmSync(join(directory, name), { force: true });
+            }
+        }
+        catch {
+            // Another publisher may have pruned it first.
+        }
+    }
+}
+function readRecordFiles(directory) {
+    let names;
+    try {
+        names = readdirSync(directory);
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const name of names) {
+        if (name.startsWith(".") || !name.endsWith(".json"))
+            continue;
+        const file = join(directory, name);
+        try {
+            const record = JSON.parse(readFileSync(file, "utf8"));
+            if (isRunStatusRecord(record))
+                found.push({ file, record });
+        }
+        catch {
+            // Not a record, or replaced while it was being read.
+        }
+    }
+    return found;
+}
+function isRunStatusRecord(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const record = value;
+    const agent = record.agent;
+    const human = record.human;
+    const limit = record.limit;
+    return (record.schemaVersion === 1 || record.schemaVersion === 2)
+        && typeof record.id === "string" && record.id !== ""
+        && Number.isSafeInteger(record.pid) && record.pid > 0
+        && isOptionalString(record.owner)
+        && isOptionalString(record.parent)
+        && isOptionalString(record.label)
+        && (record.stateSince === undefined || isTimestamp(record.stateSince))
+        && typeof record.machine === "string"
+        && typeof record.path === "string"
+        && typeof record.cwd === "string"
+        && (record.status === "running" || record.status === "waiting"
+            || record.status === "completed" || record.status === "failed")
+        && isOptionalString(record.state)
+        && (agent === undefined || (agent !== null && typeof agent === "object" && typeof agent.harness === "string"
+            && isOptionalString(agent.model) && isOptionalString(agent.thinking)))
+        && (human === undefined || (human !== null && typeof human === "object" && typeof human.prompt === "string"
+            && isOptionalString(human.requestId) && isOptionalStrings(human.choices) && isOptionalStrings(human.suggestions)
+            && (human.discussion === undefined || typeof human.discussion === "boolean")))
+        && (limit === undefined || (limit !== null && typeof limit === "object" && typeof limit.text === "string"
+            && isOptionalString(limit.until)))
+        && (record.answeredBy === undefined || record.answeredBy === "host")
+        && isOptionalStrings(record.deliveries)
+        && isOptionalString(record.error)
+        && isTimestamp(record.startedAt)
+        && isTimestamp(record.updatedAt);
+}
+function isOptionalString(value) {
+    return value === undefined || typeof value === "string";
+}
+function isOptionalStrings(value) {
+    return value === undefined || (Array.isArray(value) && value.every((item) => typeof item === "string"));
+}
+function isTimestamp(value) {
+    return typeof value === "string" && !Number.isNaN(Date.parse(value));
+}
+/** The id becomes a file name, so it must not be able to leave the directory. */
+export function isFileSafeId(id) {
+    return /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/u.test(id);
+}
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (cause) {
+        // EPERM means the process exists but belongs to someone else.
+        return cause.code === "EPERM";
+    }
+}
+function formatState(state) {
+    if (state === undefined)
+        return undefined;
+    return typeof state === "string" ? state : JSON.stringify(state);
+}
+/** One short line: a label is a caption, not a place for task text. */
+function formatLabel(label) {
+    const line = label?.split(/\r?\n/u).map((part) => part.trim()).find((part) => part !== "");
+    return line === undefined ? undefined : line.slice(0, 160);
+}
+function pickAgent(agent) {
+    if (agent === undefined)
+        return undefined;
+    return {
+        harness: agent.harness,
+        ...(agent.model === undefined ? {} : { model: agent.model }),
+        ...(agent.thinking === undefined ? {} : { thinking: agent.thinking }),
+    };
+}
+function pickLimit(limit) {
+    if (limit === undefined)
+        return undefined;
+    return { text: limit.text, ...(limit.until === undefined ? {} : { until: limit.until }) };
+}
+function pickHuman(human) {
+    if (human === undefined)
+        return undefined;
+    return {
+        prompt: human.prompt,
+        ...(human.requestId === undefined ? {} : { requestId: human.requestId }),
+        ...(human.choices === undefined ? {} : { choices: [...human.choices] }),
+        ...(human.suggestions === undefined ? {} : { suggestions: [...human.suggestions] }),
+        ...(human.discussion === true ? { discussion: true } : {}),
+    };
+}

package/dist/src/run-watch.d.ts

@@ -0,0 +1,24 @@
+import { type RunStatusRecord } from "./run-status.ts";
+/**
+ * One thing a session asked to see on its status line besides its own runs:
+ * runs named by the start of their id or label, or runs working in a directory.
+ */
+export type RunWatch = {
+    readonly text: string;
+} | {
+    readonly dir: string;
+};
+/**
+ * A session's watch list, kept beside the records under a name their readers
+ * skip. `claude/statusline.mjs` reads the same file without loading this module.
+ */
+export declare function runWatchPath(directory: string, sessionId: string): string;
+/** What a session watches. A missing, unreadable, or malformed list watches nothing. */
+export declare function readRunWatches(directory: string, sessionId: string): RunWatch[];
+/** Replaces a session's watch list; an empty one removes its file. */
+export declare function writeRunWatches(directory: string, sessionId: string, watches: readonly RunWatch[]): void;
+/** Whether a watch names a run. A sub-run is never watched: it is its parent's detail. */
+export declare function runWatchMatches(watch: RunWatch, record: RunStatusRecord): boolean;
+/** Checks and normalizes what `machine watch` was given. */
+export declare function runWatch(input: RunWatch): RunWatch;
+export declare function sameRunWatch(left: RunWatch, right: RunWatch): boolean;

package/dist/src/run-watch.js

@@ -0,0 +1,112 @@
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve, sep } from "node:path";
+import { isFileSafeId } from "./run-status.js";
+const forgottenAfterMilliseconds = 30 * 24 * 60 * 60 * 1_000;
+const watchFile = /^\.watch\..+\.json$/u;
+let temporaryFiles = 0;
+/**
+ * A session's watch list, kept beside the records under a name their readers
+ * skip. `claude/statusline.mjs` reads the same file without loading this module.
+ */
+export function runWatchPath(directory, sessionId) {
+    if (!isFileSafeId(sessionId)) {
+        throw new Error(`Session id "${sessionId}" cannot name a watch list: use only letters, digits, ".", "_", and "-"`);
+    }
+    return join(directory, `.watch.${sessionId}.json`);
+}
+/** What a session watches. A missing, unreadable, or malformed list watches nothing. */
+export function readRunWatches(directory, sessionId) {
+    try {
+        const list = JSON.parse(readFileSync(runWatchPath(directory, sessionId), "utf8"));
+        const watches = list?.watches;
+        return Array.isArray(watches) ? watches.flatMap((watch) => pickWatch(watch) ?? []) : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Replaces a session's watch list; an empty one removes its file. */
+export function writeRunWatches(directory, sessionId, watches) {
+    const path = runWatchPath(directory, sessionId);
+    if (watches.length === 0) {
+        rmSync(path, { force: true });
+        return;
+    }
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    // Readers only ever see a whole list: write beside it, then rename over it.
+    const temporary = join(directory, `.watch.${sessionId}.${process.pid}.${temporaryFiles += 1}.tmp`);
+    try {
+        writeFileSync(temporary, `${JSON.stringify({ schemaVersion: 1, watches })}\n`, { mode: 0o600 });
+        renameSync(temporary, path);
+    }
+    catch (cause) {
+        rmSync(temporary, { force: true });
+        throw cause;
+    }
+    try {
+        pruneRunWatches(directory, path);
+    }
+    catch {
+        // Pruning is best effort.
+    }
+}
+/** Whether a watch names a run. A sub-run is never watched: it is its parent's detail. */
+export function runWatchMatches(watch, record) {
+    if (record.parent !== undefined)
+        return false;
+    if ("dir" in watch) {
+        if (!isAbsolute(record.cwd))
+            return false;
+        const cwd = resolve(record.cwd);
+        return cwd === watch.dir || cwd.startsWith(watch.dir.endsWith(sep) ? watch.dir : `${watch.dir}${sep}`);
+    }
+    if (record.id.startsWith(watch.text))
+        return true;
+    // The label must start with the whole text, not with a longer word that begins like it.
+    const next = record.label?.startsWith(watch.text) ? record.label.slice(watch.text.length) : undefined;
+    return next !== undefined && !/^[\p{L}\p{N}_-]/u.test(next);
+}
+/** Checks and normalizes what `machine watch` was given. */
+export function runWatch(input) {
+    if ("dir" in input) {
+        if (input.dir === "")
+            throw new Error("Expected a directory after --dir");
+        return { dir: resolve(input.dir) };
+    }
+    const text = input.text.trim();
+    if (text === "")
+        throw new Error("Expected the start of a run id or label to watch");
+    // Checked before the ends are trimmed: a line break there is still a second line.
+    if (/[\r\n]/u.test(input.text))
+        throw new Error("A watch is one line: the start of a run id or label");
+    return { text };
+}
+export function sameRunWatch(left, right) {
+    return "dir" in left ? "dir" in right && left.dir === right.dir : "text" in right && left.text === right.text;
+}
+function pickWatch(value) {
+    if (value === null || typeof value !== "object")
+        return undefined;
+    const { text, dir } = value;
+    if (typeof text === "string" && text !== "" && dir === undefined)
+        return { text };
+    if (typeof dir === "string" && isAbsolute(dir) && text === undefined)
+        return { dir: resolve(dir) };
+    return undefined;
+}
+/** Sessions end without saying so; a list nobody has changed for a month belongs to one that did. */
+function pruneRunWatches(directory, kept) {
+    const now = Date.now();
+    for (const name of readdirSync(directory)) {
+        const file = join(directory, name);
+        if (!watchFile.test(name) || file === kept)
+            continue;
+        try {
+            if (now - statSync(file).mtimeMs > forgottenAfterMilliseconds)
+                rmSync(file, { force: true });
+        }
+        catch {
+            // Another session may have pruned it first.
+        }
+    }
+}

package/dist/src/session.d.ts

@@ -1,5 +1,6 @@
 import type { StateValue } from "xstate";
-import { type HostedHumanRequest } from "./host.ts";
+import type { JsonValue } from "./json.ts";
+import { type HostedHumanRequest, type MachineHostOptions } from "./host.ts";
 import type { AgentUpdate } from "./index.ts";
 import type { PrepareMachineRunOptions } from "./launcher.ts";
 export type RunStatus = "running" | "waiting" | "completed" | "failed";
@@ -11,12 +12,18 @@ export interface RunSnapshot {
     readonly cwd: string;
     readonly status: RunStatus;
     readonly state?: StateValue;
+    readonly output?: JsonValue;
     readonly startedAt: string;
     readonly updatedAt: string;
     readonly elapsedSeconds: number;
     readonly agent?: Extract<AgentUpdate, {
         type: "identity";
     }>;
+    /** Present while the current Agent state waits for a usage limit to reset; `status` stays `running`. */
+    readonly limit?: {
+        readonly text: string;
+        readonly until?: string;
+    };
     readonly human?: HostedHumanRequest;
     readonly error?: string;
 }
@@ -28,13 +35,19 @@ export interface SessionEvent {
 export declare class MachineSession {
     #private;
     subscribe(listener: (event: SessionEvent) => void): () => void;
-    start(options: PrepareMachineRunOptions): Promise<RunSnapshot>;
+    start(options: PrepareMachineRunOptions & Pick<MachineHostOptions, "label" | "owner" | "publishRunStatus">): Promise<RunSnapshot>;
     status(runId?: string): RunSnapshot[];
     respond(input: {
         readonly runId: string;
         readonly requestId: string;
         readonly response: string;
     }): Promise<RunSnapshot>;
+    /** Sends a discussion question in place of an answer; the Machine then asks again as a new request. */
+    ask(input: {
+        readonly runId: string;
+        readonly requestId: string;
+        readonly question: string;
+    }): Promise<RunSnapshot>;
     close(): void;
 }
 export declare function isActive(status: RunStatus): boolean;

package/dist/src/session.js

@@ -1,4 +1,3 @@
-import { randomUUID } from "node:crypto";
 import { startMachineHost } from "./host.js";
 /** Owns runs from startup to disposal. Presentation belongs to its subscribers. */
 export class MachineSession {
@@ -15,10 +14,11 @@ export class MachineSession {
             throw new Error("Machine session is closed");
         const cancellation = new AbortController();
         this.#starting.add(cancellation);
-        const id = randomUUID();
         const startedAt = Date.now();
+        // The run is known by its host's id, which is also the id of its published run status.
+        let started;
         const update = (type, change) => {
-            const run = this.#runs.get(id);
+            const run = started === undefined ? undefined : this.#runs.get(started.id);
             if (run === undefined || !isActive(run.status))
                 return;
             change(run);
@@ -31,13 +31,23 @@ export class MachineSession {
                 ...options,
                 signal: cancellation.signal,
                 onState: (state) => update("updated", (run) => {
-                    if (JSON.stringify(run.state) !== JSON.stringify(state))
+                    if (JSON.stringify(run.state) !== JSON.stringify(state)) {
                         run.agent = undefined;
+                        run.limit = undefined;
+                    }
                     run.state = state;
                 }),
                 onAgentUpdate: (agent) => {
                     if (agent.type === "identity")
                         update("updated", (run) => { run.agent = agent; });
+                    // A swap while every preset is being tried again leaves the wait as it is shown.
+                    else if (agent.type === "limit" && agent.status !== "swapped") {
+                        update("updated", (run) => {
+                            run.limit = agent.status === "resumed"
+                                ? undefined
+                                : { text: agent.text, ...(agent.until === undefined ? {} : { until: agent.until }) };
+                        });
+                    }
                 },
                 onHumanRequest: (request) => update("human", (run) => {
                     run.status = "waiting";
@@ -53,15 +63,16 @@ export class MachineSession {
             throw new Error("Machine session is closed");
         }
         const run = {
-            id,
+            id: host.id,
             cwd: options.cwd ?? process.cwd(),
             host,
             startedAt,
             updatedAt: Date.now(),
             status: "running",
         };
-        this.#runs.set(id, run);
-        void host.result.then(({ state }) => this.#finish(run, { state }), (cause) => this.#finish(run, { error: errorMessage(cause) }));
+        started = run;
+        this.#runs.set(run.id, run);
+        void host.result.then((result) => this.#finish(run, result), (cause) => this.#finish(run, { error: errorMessage(cause) }));
         this.#emit("updated", run);
         return snapshot(run);
     }
@@ -92,6 +103,29 @@ export class MachineSession {
         await sent;
         return snapshot(run);
     }
+    /** Sends a discussion question in place of an answer; the Machine then asks again as a new request. */
+    async ask(input) {
+        const run = this.#requireRun(input.runId);
+        if (run.status !== "waiting" || run.human === undefined) {
+            throw new Error(`Machine run "${input.runId}" is not waiting for Human input`);
+        }
+        if (run.human.requestId !== input.requestId) {
+            throw new Error("Machine Human request is stale; read the current requestId");
+        }
+        if (run.human.discussion !== true)
+            throw new Error("This Human request does not support discussion");
+        if (input.question.trim() === "" || input.question.length > 8000) {
+            throw new Error("Question must contain 1–8000 characters");
+        }
+        // Claimed as a response is: the request is spent once its question is on the way.
+        run.status = "running";
+        run.human = undefined;
+        run.updatedAt = Date.now();
+        const sent = run.host.ask(input.question, input.requestId);
+        this.#emit("updated", run);
+        await sent;
+        return snapshot(run);
+    }
     close() {
         if (this.#closed)
             return;
@@ -114,12 +148,15 @@ export class MachineSession {
         if (this.#closed || !isActive(run.status))
             return;
         run.status = "state" in outcome ? "completed" : "failed";
-        if ("state" in outcome)
+        if ("state" in outcome) {
             run.state = outcome.state;
+            run.output = outcome.output;
+        }
         else
             run.error = outcome.error;
         run.human = undefined;
         run.agent = undefined;
+        run.limit = undefined;
         run.updatedAt = Date.now();
         const terminal = [...this.#runs.values()]
             .filter((item) => !isActive(item.status))
@@ -152,10 +189,12 @@ function snapshot(run) {
         cwd: run.cwd,
         status: run.status,
         ...(run.state === undefined ? {} : { state: structuredClone(run.state) }),
+        ...(run.output === undefined ? {} : { output: structuredClone(run.output) }),
         startedAt: new Date(run.startedAt).toISOString(),
         updatedAt: new Date(run.updatedAt).toISOString(),
         elapsedSeconds: Math.floor(((isActive(run.status) ? Date.now() : run.updatedAt) - run.startedAt) / 1_000),
         ...(run.agent === undefined ? {} : { agent: { ...run.agent } }),
+        ...(run.limit === undefined ? {} : { limit: { ...run.limit } }),
         ...(run.human === undefined ? {} : { human: structuredClone(run.human) }),
         ...(run.error === undefined ? {} : { error: run.error }),
     };

package/dist/src/system-one-http.d.ts

@@ -0,0 +1,25 @@
+import type { DecisionProvider } from "./decision.ts";
+/** Shared transport options for self-hosted System One Choice services. */
+export interface SystemOneHttpOptions {
+    /** Server root (optionally including a proxy prefix), without /v1/systemone. */
+    readonly baseUrl?: string;
+    /** Optional Bearer token. Only the selected provider's environment is read. */
+    readonly apiKey?: string;
+    /** Wire model identifier; checkpoint/backend selection belongs to the server. */
+    readonly model?: string;
+    /** Defaults to 30 seconds, including reading the response body. */
+    readonly timeoutMs?: number;
+    /** Injected clients must honor the AbortSignal to release network resources. */
+    readonly fetch?: typeof globalThis.fetch;
+}
+interface Service {
+    readonly name: string;
+    readonly label: string;
+    readonly envPrefix: string;
+    readonly baseUrl: string;
+    readonly model: string;
+    readonly minChoices: number;
+}
+/** Internal plumbing shared by Von and Laya, not a new workflow primitive. */
+export declare function systemOneHttpProvider(service: Service, options: SystemOneHttpOptions): DecisionProvider;
+export {};