@dna113p/machines 0.2.0 → 0.3.0

package/dist/src/session.d.ts

@@ -1,4 +1,5 @@
 import type { StateValue } from "xstate";
+import type { JsonValue } from "./json.ts";
 import { type HostedHumanRequest } from "./host.ts";
 import type { AgentUpdate } from "./index.ts";
 import type { PrepareMachineRunOptions } from "./launcher.ts";
@@ -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;
 }
@@ -35,6 +42,12 @@ export declare class MachineSession {
         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

@@ -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";
@@ -61,7 +71,7 @@ export class MachineSession {
             status: "running",
         };
         this.#runs.set(id, run);
-        void host.result.then(({ state }) => this.#finish(run, { state }), (cause) => this.#finish(run, { error: errorMessage(cause) }));
+        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 +102,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 +147,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 +188,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 {};

package/dist/src/system-one-http.js

@@ -0,0 +1,146 @@
+import * as v from "valibot";
+const nonBlank = v.pipe(v.string(), v.check(value => value.trim().length > 0));
+const probability = v.pipe(v.number(), v.minValue(0), v.maxValue(1));
+const responseSchema = v.object({
+    model: nonBlank,
+    answers: v.object({
+        decision: v.object({
+            type: v.literal("choice"),
+            choice: nonBlank,
+            probabilities: v.pipe(v.unknown(), v.check(value => !Array.isArray(value)), v.record(v.string(), probability)),
+            confidence: probability,
+        }),
+    }),
+});
+const maxResponseBytes = 1_048_576;
+/** Internal plumbing shared by Von and Laya, not a new workflow primitive. */
+export function systemOneHttpProvider(service, options) {
+    const { label, envPrefix } = service;
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
+        throw new Error(`${label} timeoutMs must be a positive 32-bit integer`);
+    }
+    return {
+        name: service.name,
+        async decide(request) {
+            // Resolve all environment configuration lazily: discovery never contacts a
+            // service, validates credentials, starts Python, or downloads model weights.
+            const endpoint = serviceEndpoint(options.baseUrl ?? process.env[`${envPrefix}_BASE_URL`] ?? service.baseUrl, label);
+            const apiKey = options.apiKey ?? process.env[`${envPrefix}_API_KEY`];
+            if (apiKey !== undefined && (typeof apiKey !== "string" || !/^[\x21-\x7e]+$/.test(apiKey))) {
+                throw new Error(`${label} apiKey must be a non-empty ASCII Bearer token`);
+            }
+            const model = options.model ?? process.env[`${envPrefix}_MODEL`] ?? service.model;
+            if (typeof model !== "string" || !model.trim())
+                throw new Error(`${label} model must be non-empty`);
+            const choices = Object.entries(request.choices);
+            if (choices.length < service.minChoices) {
+                throw new Error(`${label} Choice requires at least ${service.minChoices} outcome(s)`);
+            }
+            if (!request.question?.trim() || !request.input?.trim()
+                || choices.some(([key, value]) => !key.trim() || key !== key.trim()
+                    || (value !== null && (typeof value !== "string" || !value.trim())))) {
+                throw new Error(`${label} requires non-empty evidence, question, and valid choices`);
+            }
+            const controller = new AbortController();
+            const timeoutError = () => new Error(`${label} request timed out after ${timeoutMs}ms`);
+            let timer;
+            const timeout = new Promise((_resolve, reject) => {
+                timer = setTimeout(() => { controller.abort(); reject(timeoutError()); }, timeoutMs);
+            });
+            const execute = async () => {
+                let response;
+                try {
+                    response = await (options.fetch ?? globalThis.fetch)(endpoint, {
+                        method: "POST", redirect: "error", signal: controller.signal,
+                        headers: {
+                            "Content-Type": "application/json",
+                            ...(apiKey === undefined ? {} : { Authorization: `Bearer ${apiKey}` }),
+                        },
+                        body: JSON.stringify({
+                            model, state: request.input,
+                            questions: {
+                                decision: { type: "choice", instructions: request.question, criteria: request.choices },
+                            },
+                        }),
+                    });
+                }
+                catch {
+                    throw controller.signal.aborted ? timeoutError() : new Error(`${label} network request failed`);
+                }
+                if (controller.signal.aborted || !response.ok) {
+                    // Do not wait on untrusted error streams, or expose their contents.
+                    void response.body?.cancel().catch(() => { });
+                    if (controller.signal.aborted)
+                        throw timeoutError();
+                    throw new Error(`${label} request failed (HTTP ${response.status}); no automatic retry`);
+                }
+                let body;
+                const reader = response.body?.getReader();
+                const cancel = () => { void reader?.cancel().catch(() => { }); };
+                controller.signal.addEventListener("abort", cancel, { once: true });
+                try {
+                    const chunks = [];
+                    let bytes = 0;
+                    if (reader) {
+                        while (true) {
+                            const { value, done } = await reader.read();
+                            if (done)
+                                break;
+                            bytes += value.byteLength;
+                            if (bytes > maxResponseBytes) {
+                                cancel();
+                                throw new RangeError("Response size limit");
+                            }
+                            chunks.push(value);
+                        }
+                    }
+                    body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+                }
+                catch (error) {
+                    if (controller.signal.aborted)
+                        throw timeoutError();
+                    throw new Error(error instanceof RangeError
+                        ? `${label} response exceeds 1 MiB` : `${label} returned invalid JSON`);
+                }
+                finally {
+                    controller.signal.removeEventListener("abort", cancel);
+                    reader?.releaseLock();
+                }
+                if (controller.signal.aborted)
+                    throw timeoutError();
+                const parsed = v.safeParse(responseSchema, body);
+                if (!parsed.success)
+                    throw new Error(`${label} returned an invalid Choice response`);
+                const { choice, probabilities, confidence } = parsed.output.answers.decision;
+                if (!Object.hasOwn(probabilities, choice)
+                    || Object.values(probabilities).some(value => value > probabilities[choice])) {
+                    throw new Error(`${label} choice must have the highest probability`);
+                }
+                return { choice, probabilities, confidence, model: parsed.output.model };
+            };
+            try {
+                return await Promise.race([execute(), timeout]);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+    };
+}
+function serviceEndpoint(value, label) {
+    try {
+        if (typeof value !== "string" || !value.trim() || value !== value.trim())
+            throw new Error();
+        const url = new URL(value);
+        if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+            throw new Error();
+        }
+        url.pathname = `${url.pathname.replace(/\/+$/, "")}/v1/systemone`;
+        return url.href;
+    }
+    catch {
+        // A malformed URL may contain a password; never include it in the error.
+        throw new Error(`${label} baseUrl must be an HTTP(S) server root without credentials, query, or fragment`);
+    }
+}

package/dist/src/terminal-human.d.ts

@@ -1,2 +1,9 @@
 import type { HumanRequest } from "./index.ts";
-export declare function terminalHuman(request: HumanRequest): Promise<string>;
+export declare class TerminalInputClosed extends Error {
+    constructor();
+}
+/**
+ * Asks on the process's own terminal. Aborting the signal withdraws the
+ * question, restores the terminal, and rejects with the signal's reason.
+ */
+export declare function terminalHuman(request: HumanRequest, signal?: AbortSignal): Promise<string>;

package/dist/src/terminal-human.js

@@ -1,27 +1,47 @@
 import { clearScreenDown, createInterface, cursorTo, emitKeypressEvents, moveCursor, } from "node:readline";
 import { cyan, dim, green } from "yoctocolors";
-export function terminalHuman(request) {
+export class TerminalInputClosed extends Error {
+    constructor() {
+        super("Terminal input closed before a response");
+    }
+}
+/**
+ * Asks on the process's own terminal. Aborting the signal withdraws the
+ * question, restores the terminal, and rejects with the signal's reason.
+ */
+export function terminalHuman(request, signal) {
+    if (signal?.aborted)
+        return Promise.reject(signal.reason);
     const values = request.choices ?? request.suggestions ?? [];
     const allowOther = request.suggestions !== undefined;
     if (values.length > 0
         && process.stdin.isTTY
         && process.stdout.isTTY
         && typeof process.stdin.setRawMode === "function") {
-        return selectHumanInput(request.prompt, values, allowOther);
+        return selectHumanInput(request.prompt, values, allowOther, signal);
     }
-    return readFreeformInput(request.prompt, values, allowOther ? "Suggestions" : "Choices");
+    return readFreeformInput(request.prompt, values, allowOther ? "Suggestions" : "Choices", signal);
 }
-function readFreeformInput(prompt, values = [], heading = "Suggestions") {
+function readFreeformInput(prompt, values = [], heading = "Suggestions", signal) {
     const terminal = createInterface({ input: process.stdin, output: process.stdout });
     const suggestionText = values.length === 0
         ? ""
         : `\n${heading}:\n${values.map((value) => `- ${value}`).join("\n")}`;
     return new Promise((resolve, reject) => {
         let answered = false;
+        function onAbort() {
+            answered = true;
+            terminal.close();
+            // Leave the unanswered prompt line behind.
+            process.stdout.write("\n");
+            reject(signal?.reason);
+        }
         terminal.once("close", () => {
+            signal?.removeEventListener("abort", onAbort);
             if (!answered)
-                reject(new Error("Terminal input closed before a response"));
+                reject(new TerminalInputClosed());
         });
+        signal?.addEventListener("abort", onAbort, { once: true });
         terminal.question(`${prompt}${suggestionText}\n> `, (answer) => {
             answered = true;
             terminal.close();
@@ -29,7 +49,7 @@ function readFreeformInput(prompt, values = [], heading = "Suggestions") {
         });
     });
 }
-function selectHumanInput(prompt, values, allowOther) {
+function selectHumanInput(prompt, values, allowOther, signal) {
     return new Promise((resolve, reject) => {
         const choices = allowOther ? [...values, "Other…"] : [...values];
         const initialRawMode = process.stdin.isRaw;
@@ -54,13 +74,20 @@ function selectHumanInput(prompt, values, allowOther) {
             process.stdin.off("keypress", onKeypress);
             process.stdin.off("end", onInputClosed);
             process.stdin.off("close", onInputClosed);
+            signal?.removeEventListener("abort", onAbort);
             process.stdin.setRawMode(initialRawMode ?? false);
             if (!initialRawMode)
                 process.stdin.pause();
         }
         function onInputClosed() {
             cleanup();
-            reject(new Error("Terminal input closed before a response"));
+            reject(new TerminalInputClosed());
+        }
+        function onAbort() {
+            clearMenu();
+            cleanup();
+            process.stdout.write(`${dim("answered elsewhere")}\n`);
+            reject(signal?.reason);
         }
         function onKeypress(_character, key) {
             if (key.ctrl && key.name === "c") {
@@ -84,7 +111,7 @@ function selectHumanInput(prompt, values, allowOther) {
                     resolve(answer);
                 }
                 else {
-                    void readFreeformInput("Feedback").then(resolve, reject);
+                    void readFreeformInput("Feedback", [], undefined, signal).then(resolve, reject);
                 }
             }
         }
@@ -94,6 +121,7 @@ function selectHumanInput(prompt, values, allowOther) {
         process.stdin.on("keypress", onKeypress);
         process.stdin.once("end", onInputClosed);
         process.stdin.once("close", onInputClosed);
+        signal?.addEventListener("abort", onAbort, { once: true });
         process.stdin.resume();
         render();
     });

package/dist/src/von.d.ts

@@ -0,0 +1,15 @@
+import { type DecisionAgentOptions, type DecisionProvider } from "./decision.ts";
+import { type SystemOneHttpOptions } from "./system-one-http.ts";
+export interface VonProviderOptions extends SystemOneHttpOptions {
+    /** Overrides VON_BASE_URL, then http://127.0.0.1:8000. */
+    readonly baseUrl?: string;
+    /** Overrides VON_API_KEY. No TypeSafe/OpenRouter credential fallback. */
+    readonly apiKey?: string;
+    /** Overrides VON_MODEL, then von-1.0.0. Does NOT select the server backend. */
+    readonly model?: string;
+}
+export type VonAgentOptions = VonProviderOptions & DecisionAgentOptions;
+/** One Choice request to a separately managed Von server; no Python dependency. */
+export declare function vonProvider(options?: VonProviderOptions): DecisionProvider;
+/** Convenience binding. Transitions, confidence gates, and retries stay in Machines. */
+export declare function vonAgent(options?: VonAgentOptions): (request: import("./index.ts").AgentRequest, report?: import("./index.ts").AgentReporter) => Promise<import("./decision.ts").DecisionEvent>;

package/dist/src/von.js

@@ -0,0 +1,13 @@
+import { decisionAgent } from "./decision.js";
+import { systemOneHttpProvider } from "./system-one-http.js";
+/** One Choice request to a separately managed Von server; no Python dependency. */
+export function vonProvider(options = {}) {
+    return systemOneHttpProvider({
+        name: "von", label: "Von", envPrefix: "VON",
+        baseUrl: "http://127.0.0.1:8000", model: "von-1.0.0", minChoices: 1,
+    }, options);
+}
+/** Convenience binding. Transitions, confidence gates, and retries stay in Machines. */
+export function vonAgent(options = {}) {
+    return decisionAgent(vonProvider(options), options);
+}

package/docs/architecture.md

@@ -12,7 +12,7 @@ a Human uses a terminal, or a run is displayed in Codex.
 | State | Named position invoking one Agent, Human, or Operation, or a final state |
 | Agent | Bounded request implemented by an `AgentRunner` |
 | Operation | Trusted local function returning an event |
-| Human | Input request returning a `submitted` event with the response |
+| Human | Input request returning `submitted`, or an explicitly enabled `question` event |
 | Run | One execution of a Machine |
 | Adapter | Mechanism connecting a primitive or run to an external interface |
 
@@ -37,12 +37,25 @@ MCP server ────┘       ↑
 | Module | Owns |
 | --- | --- |
 | `src/index.ts` | Typed primitives, Machine validation, XState execution, observer contracts |
+| `src/conversation.ts` | Compound Human/clarification state; the owner supplies the original session responder |
 | `src/terminal-human.ts` | Default terminal Human input, selectors, raw-mode restoration |
 | `src/machine-module.ts` | Shared module contract and metadata validation |
 | `src/catalog.ts` | Definition and preset catalog reads |
 | `src/acp.ts` | ACP process/session protocol, bounded Agent result, normalized activity |
 | `src/agy.ts` | Antigravity CLI (agy) process protocol, bounded Agent result, normalized activity |
+| `src/chatgpt-web.ts` | ChatGPT web conversation over the DevTools protocol, rig-bridge workspace prompt, bridge activity |
+| `src/claude.ts` | Claude Code CLI headless execution, final-result decoding, permission options, normalized activity |
+| `src/codex.ts` | Codex CLI execution, final-response decoding, sandbox options, normalized activity |
+| `src/deepseek.ts` | DeepSeek Harness command/profile configuration over the shared ACP runner |
+| `src/decision.ts` | Provider-neutral classification contract, validated outcome events, normalized observations |
+| `src/jev.ts` | TypeSafe Choice HTTP transport, authentication, model selection, and bounded requests |
+| `src/openrouter.ts` | OpenRouter Decisions Choice transport, independent credentials, optional result metadata |
+| `src/laya.ts`, `src/von.ts` | Self-hosted Choice providers with independent configuration |
+| `src/system-one-http.ts` | Shared bounded HTTP transport for the self-hosted providers |
+| `services/laya/server.py` | Opt-in, externally managed single-checkpoint Python Choice bridge |
 | `src/agent-protocol.ts` | Shared Agent prompt instructions and Machines event decoding |
+| `src/agent-limit.ts` | Typed provider usage-limit error and its recognition across module copies |
+| `src/agent-limits.ts` | Limit-aware runner: fallback order, handoff note, reset waiting, per-run memory of limited presets, report-only requests |
 | `src/discovery.ts` | Project/global definition locations and precedence |
 | `src/launcher.ts` | Definition metadata, Agent bindings, preflight, single-use launch preparation |
 | `src/discovery-worker.ts` | Fresh metadata imports in disposable workers |
@@ -68,7 +81,12 @@ Operation rather than the factory.
 
 The launcher resolves required semantic Agent roles and configured presets before
 starting the actor. Missing bindings, invalid overrides, or invalid definitions
-fail preflight. The resulting prepared run can be started once. Long-lived hosted
+fail preflight. It then wraps each role's runner so that a usage limit swaps to
+the bound preset's allowed fallbacks or waits for the reset; the runtime still
+receives one runner per role. An Agent state that names an `onLimit` event keeps
+that policy in the Machine: the runtime asks the runner to report the limit and
+delivers it as the event, and the wrapper neither swaps nor waits for that
+request. The resulting prepared run can be started once. Long-lived hosted
 runs get a fresh child process; direct runtime users own their own definitions.
 
 ## Session and process lifecycle
@@ -82,6 +100,16 @@ and that request. Claiming a request before asynchronous delivery prevents two
 answers from being accepted, and the identity prevents a stale card or dialog from
 answering a later prompt. Restricted choices are validated for every interface.
 
+`machine run` asks on its own terminal. With run-status publication on it also
+publishes the pending request and its request ID, and takes the first valid
+response from either the terminal or a private per-run inbox file written by
+`machine respond`; the MCP session takes inbox responses through the same
+session `respond` path as its tool, and inbox questions through the session's
+`ask`. The inbox is a second way to deliver a response to the owning run, not a
+second owner: the run still validates the request ID and choices, and a response
+to any other request is discarded. See
+[Integrations](integrations.md#answering-a-waiting-run-from-outside).
+
 Closing a session terminates active and starting hosts. Host termination includes
 ordinary descendants in the host's owned process group on POSIX and process-tree
 termination on Windows. Deliberately detached processes can escape normal ownership;
@@ -95,6 +123,31 @@ Human drafts and focus belong to the presentation adapter while the request ID i
 unchanged. The card polls authoritative status; it does not decide transitions or
 persist a second copy of the workflow state.
 
+## Discussion-capable Human states
+
+Existing Human runners may still return strings. An opt-in request with
+`discussion: true` additionally permits `{ type: "question", text }`; its Human
+state must explicitly handle `question`. Questions never bypass restricted
+choices or become implicit approvals. The public host's `ask(question, requestId)`
+claims the exact current request separately from `respond(answer, requestId)`.
+The child emits the Machine event; the adapter never chooses a destination state.
+
+`@dna113p/machines/conversation` exports `conversation(options, on)`, authoring
+sugar for a bounded Human -> owner-supplied clarification -> Human loop. It keeps
+one pending decision, accepts a final explicit answer, and delegates its outcome
+to the surrounding Machine. Its reply callback owns the agent/session reference;
+the helper does not create an assistant or promise that another call to the same
+Agent role resumes the original native session. For arbitrary clarification
+policies, use ordinary `human`, `agent`, and `operation` states instead.
+
+Drip uses this public host/runtime boundary to show every Machine run and route
+its Human steps through a shared web/CLI focus. Existing Pi/MCP presentation
+adapters remain answer-only unless they explicitly implement the question channel.
+The default terminal Human selector is also answer-only; Drip's `chat` command
+provides the discussion-capable terminal surface, and `machine respond --question`
+sends a question to a published run, started by `machine run` or hosted by the
+MCP server, whose request allows discussion.
+
 ## Distribution
 
 Development runs source TypeScript on Node 24. `npm run build` emits JavaScript and
@@ -111,3 +164,15 @@ the MCP widget resource, and a hosted Human response.
 The earlier implementation plans are retained in the repository's
 [history directory](https://github.com/dna113p/machines/tree/main/docs/history) for rationale.
 Their phase ordering and manual proof gates describe past work.
+
+## External execution owners
+
+The supported `@dna113p/machines/host` export exposes `startMachineHost`, its
+observations, correlated Human responses, termination, and final state/output.
+External applications can own hosted runs without importing private modules or
+parsing terminal output. Hosted input and optional output are JSON values.
+
+Ticket discovery, persistence, scheduling, and tracker updates belong to the
+separate `machines-dispatch` application. Machines has no dependency on ticketing.
+External owners decide how to interpret output; a final state alone does not
+prove that a ticket should close.