@dna113p/machines 0.3.1 → 0.3.2

package/README.md

@@ -176,10 +176,10 @@ npm ci
 npm pack
 ```
 
-Then install the generated `dna113p-machines-0.3.1.tgz` into a project:
+Then install the generated `dna113p-machines-0.3.2.tgz` into a project:
 
 ```bash
-npm install /absolute/path/to/machines/dna113p-machines-0.3.1.tgz
+npm install /absolute/path/to/machines/dna113p-machines-0.3.2.tgz
 npx machine list
 ```
 

package/dist/mcp/server.js

@@ -177,7 +177,7 @@ export class MachineSession {
     }
     async start(input) {
         // This server publishes its runs itself, so that they also take responses through their inbox.
-        const run = await this.#session.start({ ...parse(startInput, input), publishRunStatus: false });
+        const run = await this.#session.start({ ...parse(startInput, input), publishRunStatus: "caller" });
         return result(`Started ${run.machine}.\nRun id: ${run.id}\nStatus: ${run.status}`, { run });
     }
     status(input) {

package/dist/src/host.d.ts

@@ -11,8 +11,13 @@ export interface MachineHostOptions extends PrepareMachineRunOptions {
     readonly label?: string;
     /** The session that owns the run in its published run status. The environment's owner applies when absent. */
     readonly owner?: string;
-    /** Set to false by a caller that publishes the run's status itself, as the MCP server does. */
-    readonly publishRunStatus?: boolean;
+    /**
+     * Asks for the run's status to be published where run-status publication is on.
+     * `true`: this host publishes it. `"caller"`: the caller publishes it itself,
+     * under the run's id, as the MCP server does. Absent: nothing about the run is
+     * published or handed down, and the caller presents the run in its own way.
+     */
+    readonly publishRunStatus?: boolean | "caller";
     readonly onAgentUpdate?: (update: AgentUpdate) => void;
     readonly onHumanRequest?: (request: HostedHumanRequest) => void;
     readonly onState?: (state: StateValue) => void;

package/dist/src/host.js

@@ -118,7 +118,9 @@ export function startMachineHost(options) {
     // below), so a reader that finds the pid gone rightly shows the run as lost.
     const id = randomUUID();
     const publication = runStatusDirectory() !== undefined;
-    const publishes = publication && options.publishRunStatus !== false;
+    // An embedding program has to ask: its environment alone must not make its runs appear elsewhere.
+    const publishes = publication && options.publishRunStatus === true;
+    const recorded = publishes || (publication && options.publishRunStatus === "caller");
     let published;
     const child = fork(fileURLToPath(import.meta.url), [childArgument], {
         cwd,
@@ -322,7 +324,7 @@ export function startMachineHost(options) {
                 ...(options.agents === undefined ? {} : { agents: options.agents }),
                 ...(options.home === undefined ? {} : { home: options.home }),
                 // A caller that publishes the record itself still publishes it under this id.
-                ...(publication ? { runId: id } : {}),
+                ...(recorded ? { runId: id } : {}),
                 ...(publishes ? { reportStatus: true } : {}),
             };
             void sendChild(child, launch).catch((cause) => fail(asError(cause)));

package/docs/architecture.md

@@ -108,7 +108,7 @@ 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. A run hosted directly through
-`startMachineHost` publishes its status without an inbox: its host remains the
+`startMachineHost` publishes its status only when its host asks, and without an inbox: its host remains the
 only way to answer it, its record says so, and `machine respond` refuses it. See
 [Integrations](integrations.md#answering-a-waiting-run-from-outside).
 

package/docs/integrations.md

@@ -199,8 +199,11 @@ choice to publish that text. `machine run` exports its run id as
 records that id as `parent`; the status line shows only top-level runs.
 
 A run hosted through `startMachineHost` from `@dna113p/machines/host` publishes
-the same record when the variable is set in the hosting process, for example a
-daemon that runs tickets, or Pi with the extension loaded. Two options replace the environment for that one run:
+the same record when its host asks with `publishRunStatus: true` and the
+variable is set in the hosting process, as a daemon that runs tickets does. A
+host that does not ask publishes nothing, whatever its environment says: a
+program that presents its runs itself, such as Pi with the extension loaded, is
+not changed by the variable. Two options replace the environment for that one run:
 `label`, shortened as `MACHINES_RUN_LABEL` is, and `owner`. When an option is
 absent the environment rule above applies; an empty one publishes the run
 without that field. The run exports its id as `MACHINES_RUN_PARENT` to its
@@ -216,7 +219,8 @@ only through the host's own `respond` and `ask`: the run reads no inbox, its
 `human` has no `requestId`, and `machine respond` refuses it. The field is absent
 from every other record and did not exist in earlier version 2 records. A caller
 that publishes its own record for the run, as the MCP server does so that its
-runs keep their inbox, passes `publishRunStatus: false`.
+runs keep their inbox, passes `publishRunStatus: "caller"`: the host then writes
+nothing, and the run still hands its id down to the runs it starts.
 
 While an Agent state waits for a [usage limit](authoring.md#usage-limits) to
 reset, the record stays `running` and carries the wait in `limit`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dna113p/machines",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Reusable workflows coordinating agents, local operations, and human decisions.",
   "license": "MIT",
   "repository": {