@relayflows/sdk 2.0.30 → 2.0.31

package/dist/redact.js

@@ -101,4 +101,132 @@ export function redactRelayError(message, env = process.env) {
     }
     return redact(message, env);
 }
+/**
+ * Credential heads whose value may continue past a line boundary.
+ *
+ * Every NAMED_VALUE pattern puts `\s` between the name and the value, and
+ * `\s` matches newlines: `authorization:` alone at the end of a poll is a
+ * complete, unredacted line, while the opaque value that lands on the next
+ * poll arrives with no recognizable credential context and would print
+ * verbatim. A trailing header — the colon plus only whitespace, or for
+ * `authorization` one scheme word — is therefore an open context. A header
+ * already followed by a non-space word has its value on that line and is not
+ * open. `Bearer` is the one bare scheme word the patterns treat as a name.
+ */
+const OPEN_HEADER_PATTERNS = [
+    /\bauthorization:(?:\s+\w+)?\s*$/i,
+    /\bx-callback-token:\s*$/i,
+    /\bx-nightcto-evidence-token:\s*$/i,
+    /\bBearer\s*$/,
+];
+/** A quoted JSON field name; the value side is inspected by the scanner. */
+const JSON_FIELD_HEAD = /"([A-Za-z0-9_.\-]{1,64})"/g;
+/**
+ * Where a named-credential context may still be half-arrived at the end of
+ * `text`.
+ *
+ * `openSecretStart` covers secret env *values*; this covers the credential
+ * *names* whose patterns can span a line break: a header released on one poll
+ * leaves its late-arriving value unrecognizable on the next, and a credential
+ * JSON field whose value string is not yet closed leaks its first fragment.
+ * Returns the earliest index at which such a context is open — the point past
+ * which nothing may be released until more of the stream arrives — or
+ * `text.length` when none is open. Holding back is line-granular upstream, so
+ * a false positive delays one line one poll rather than dropping it.
+ */
+export function openCredentialStart(text) {
+    let hold = text.length;
+    for (const pattern of OPEN_HEADER_PATTERNS) {
+        const match = pattern.exec(text);
+        if (match && match.index < hold)
+            hold = match.index;
+    }
+    JSON_FIELD_HEAD.lastIndex = 0;
+    let head;
+    while ((head = JSON_FIELD_HEAD.exec(text)) !== null) {
+        if (!isCredentialName(head[1]))
+            continue;
+        let i = head.index + head[0].length;
+        while (i < text.length && /\s/.test(text[i]))
+            i++;
+        if (i >= text.length) {
+            hold = Math.min(hold, head.index);
+            continue;
+        }
+        if (text[i] !== ':')
+            continue;
+        i++;
+        while (i < text.length && /\s/.test(text[i]))
+            i++;
+        if (i >= text.length) {
+            hold = Math.min(hold, head.index);
+            continue;
+        }
+        if (text.startsWith('[redacted]', i) || text[i] !== '"')
+            continue;
+        i++;
+        let closed = false;
+        while (i < text.length) {
+            if (text[i] === '\\') {
+                i += 2;
+                continue;
+            }
+            if (text[i] === '"') {
+                closed = true;
+                break;
+            }
+            i++;
+        }
+        if (!closed)
+            hold = Math.min(hold, head.index);
+    }
+    return hold;
+}
+/**
+ * Does `text` end on a bare credential header — a named credential line whose
+ * value, if it has one, begins on the NEXT line?
+ *
+ * The stream releaser needs this apart from `openCredentialStart`: that check
+ * sees only a header at the very end of the consumed text, but the danger is
+ * wider — a released block that *ends* on `x-callback-token:` prints the
+ * header now and its value, arriving on the next line in some later poll,
+ * without the context `redact` needs. `redact` folds the header's newline into
+ * its own named-pattern match, so the releaser's block-prefix check cannot
+ * detect the dependency on its own. Trailing whitespace-only lines after the
+ * header count as part of it — the value is still to come.
+ */
+export function endsWithOpenCredentialHeader(text) {
+    const stripped = text.replace(/\s+$/, '');
+    const lastLine = stripped.slice(stripped.lastIndexOf('\n') + 1);
+    return OPEN_HEADER_PATTERNS.some((pattern) => pattern.test(lastLine));
+}
+/**
+ * Where a secret value may still be half-arrived at the end of `text`.
+ *
+ * A stream is redacted in pieces, and `redact` only replaces a secret it can
+ * see whole: releasing text up to a point where a secret has begun but not
+ * ended would print the first half of it and never match the second. This
+ * returns the smallest index `i` for which `text.slice(i)` is a proper prefix
+ * of some secret env value — the point past which nothing may be released
+ * until more of the stream arrives — or `text.length` when no value is open.
+ *
+ * Values only, not the token and header *shapes*: those are bounded by
+ * whitespace, so a reader that releases whole lines cannot cut one in half.
+ */
+export function openSecretStart(text, env = process.env) {
+    let start = text.length;
+    for (const [, value] of secretEnvValues(env)) {
+        // A proper prefix is shorter than the value, so it can only begin inside
+        // the last `value.length - 1` characters; the first character narrows the
+        // scan to the few positions worth comparing.
+        const first = Math.max(0, text.length - value.length + 1);
+        for (let at = text.indexOf(value[0], first); at >= 0 && at < start; at = text.indexOf(value[0], at + 1)) {
+            if (value.startsWith(text.slice(at))) {
+                start = at;
+                break;
+            }
+        }
+    }
+    return start;
+}
 //# sourceMappingURL=redact.js.map

package/dist/redact.js.map

@@ -1 +1 @@
-{"version":3,"file":"redact.js","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,EAAE;AACF,4EAA4E;AAC5E,4EAA4E;AAC5E,6EAA6E;AAC7E,yEAAyE;AACzE,oEAAoE;AACpE,EAAE;AACF,6EAA6E;AAC7E,4DAA4D;AAE5D,8EAA8E;AAC9E,MAAM,WAAW,GAAG,mDAAmD,CAAC;AAExE,0EAA0E;AAC1E,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAE5B;;;;GAIG;AACH,MAAM,cAAc,GAAsB;IACxC,oDAAoD;IACpD,0BAA0B;IAC1B,yBAAyB;IACzB,2BAA2B;CAC5B,CAAC;AAEF;;;;GAIG;AACH,MAAM,oBAAoB,GAAsB;IAC9C,qDAAqD;IACrD,iCAAiC;IACjC,6CAA6C;IAC7C,sDAAsD;IACtD,iEAAiE;CAClE,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,iBAAiB,GAAG,2EAA2E,CAAC;AACtG,MAAM,eAAe,GAAG,6DAA6D,CAAC;AAEtF,SAAS,gBAAgB,CAAC,IAAY;IACpC,IAAI,IAAI,CAAC,WAAW,EAAE,KAAK,eAAe;QAAE,OAAO,IAAI,CAAC;IACxD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC,CAAC;IAC7F,MAAM,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1B,OAAO,IAAI,KAAK,SAAS,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1D,CAAC;AAED,2FAA2F;AAC3F,SAAS,eAAe,CAAC,GAAsB;IAC7C,MAAM,OAAO,GAA4B,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAChD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,iBAAiB;YAAE,SAAS;QAC5E,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,MAAyB,OAAO,CAAC,GAAG;IACvE,IAAI,GAAG,GAAG,IAAI,CAAC;IACf,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,eAAe,CAAC,GAAG,CAAC;QAAE,GAAG,GAAG,GAAG,CAAC,UAAU,CAAC,KAAK,EAAE,aAAa,IAAI,GAAG,CAAC,CAAC;IACpG,KAAK,MAAM,OAAO,IAAI,cAAc;QAAE,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAC/E,KAAK,MAAM,OAAO,IAAI,oBAAoB;QAAE,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IACvF,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,iBAAiB,EAAE,CAAC,KAAK,EAAE,IAAY,EAAE,IAAY,EAAE,MAAc,EAAE,KAAa,EAAE,EAAE,CACxG,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,aAAa,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAChE,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,MAAyB,OAAO,CAAC,GAAG;IACpF,KAAK,MAAM,GAAG,IAAI,CAAC,mBAAmB,EAAE,eAAe,CAAC,EAAE,CAAC;QACzD,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,MAAM;YAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"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"}

package/dist/run-projection.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Project a run's lifecycle into its Relaycast channel, `wf-<runId>`, so the
+ * observer dashboard shows the flow: one message per step transition, each
+ * carrying the whole run snapshot under `metadata.relayflow` for a renderer
+ * that draws the step graph.
+ *
+ * A projection, never a source of truth (RFC-0001 settled decision 7): the
+ * journal is the record. Publication is serialized and fire-and-forget; a
+ * failure is reported once through `diagnostic` and never reaches the run.
+ */
+import { type ProgressEvent } from './progress.js';
+import type { StepType } from './spec.js';
+export declare const RELAYFLOW_METADATA_VERSION = 1;
+export type ProjectedStepState = 'pending' | 'running' | 'completed' | 'failed' | 'parked';
+export interface ProjectedStep {
+    id: string;
+    type: StepType;
+    dependsOn: string[];
+    state: ProjectedStepState;
+    attempt?: number;
+    elapsedMs?: number;
+    completionReason?: string;
+}
+export interface RunSnapshot {
+    runId: string;
+    flow: string;
+    status: 'running' | 'completed' | 'failed' | 'parked' | 'canceled';
+    completionReason?: string;
+    steps: ProjectedStep[];
+}
+export interface DeclaredStep {
+    id: string;
+    type: StepType;
+    dependsOn?: string[];
+}
+export interface RunProjection {
+    readonly channel: string;
+    /** Apply a transition; `publish: false` folds replayed history into the snapshot silently. */
+    step(event: ProgressEvent & {
+        attempt?: number;
+    }, publish?: boolean): void;
+    /** Rebuild an epoch boundary from journal facts, never from old terminal state. */
+    epoch(states: Array<{
+        id: string;
+        state: ProjectedStepState;
+        attempt?: number;
+        completionReason?: string;
+    }>, publish?: boolean): void;
+    /** Close the run; only the first call publishes. */
+    finish(outcome: {
+        status: RunSnapshot['status'];
+        completionReason?: string;
+    }): void;
+    /** Resolves when every queued publication settled, or after `timeoutMs`. */
+    drain(timeoutMs: number): Promise<void>;
+    /** Stop publication and remove this session's publisher after its queue settles. */
+    close(timeoutMs: number): Promise<void>;
+}
+export type ProjectionFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+}>;
+export interface RunProjectionOptions {
+    workspaceKey: string;
+    /** Relaycast API base, default `https://cast.agentrelay.com`. */
+    baseUrl?: string;
+    fetch?: ProjectionFetch;
+    diagnostic: (message: string) => void;
+}
+export declare function runChannelName(runId: string): string;
+export declare function createRunProjection(options: RunProjectionOptions, run: {
+    runId: string;
+    flow: string;
+    steps?: DeclaredStep[];
+    resumed?: boolean;
+}): RunProjection;
+//# sourceMappingURL=run-projection.d.ts.map

package/dist/run-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-projection.d.ts","sourceRoot":"","sources":["../src/run-projection.ts"],"names":[],"mappings":"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"}

package/dist/run-projection.js

@@ -0,0 +1,199 @@
+/**
+ * Project a run's lifecycle into its Relaycast channel, `wf-<runId>`, so the
+ * observer dashboard shows the flow: one message per step transition, each
+ * carrying the whole run snapshot under `metadata.relayflow` for a renderer
+ * that draws the step graph.
+ *
+ * A projection, never a source of truth (RFC-0001 settled decision 7): the
+ * journal is the record. Publication is serialized and fire-and-forget; a
+ * failure is reported once through `diagnostic` and never reaches the run.
+ */
+import { randomUUID } from 'node:crypto';
+import { renderProgress } from './progress.js';
+export const RELAYFLOW_METADATA_VERSION = 1;
+const DEFAULT_BASE_URL = 'https://cast.agentrelay.com';
+const REQUEST_TIMEOUT_MS = 5_000;
+export function runChannelName(runId) {
+    return `wf-${runId.toLowerCase()}`;
+}
+export function createRunProjection(options, run) {
+    const doFetch = options.fetch ?? globalThis.fetch;
+    const base = options.baseUrl ?? DEFAULT_BASE_URL;
+    const channel = runChannelName(run.runId);
+    const snapshot = {
+        runId: run.runId, flow: run.flow, status: 'running',
+        steps: (run.steps ?? []).map(step => ({
+            id: step.id, type: step.type, dependsOn: step.dependsOn ?? [], state: 'pending',
+        })),
+    };
+    const call = async (path, token, body, idempotencyKey, method) => {
+        const response = await doFetch(new URL(`/v1${path}`, base).toString(), {
+            method: method ?? (body === undefined ? 'GET' : 'POST'),
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/json',
+                ...(idempotencyKey === undefined ? {} : { 'Idempotency-Key': idempotencyKey }),
+            },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        const parsed = await response.json().catch(() => undefined);
+        if (!response.ok) {
+            throw new RelaycastError(response.status, parsed?.error?.code ?? `http_${response.status}`);
+        }
+        return parsed?.data;
+    };
+    // A per-session publisher: agent names are unique per workspace, and a
+    // resumed run publishes from a fresh session into the same channel.
+    const publisherName = `flow-${randomUUID()}`;
+    let cleanup;
+    const removePublisher = (reportFailure = true) => cleanup ??= (async () => {
+        // The unique name is known before POST. A lost create response is not
+        // proof that creation failed: retire it even after an ambiguous outcome.
+        try {
+            await call(`/agents/${encodeURIComponent(publisherName)}`, options.workspaceKey, undefined, undefined, 'DELETE');
+        }
+        catch (error) {
+            if (error instanceof RelaycastError && error.status === 404)
+                return;
+            if (reportFailure)
+                options.diagnostic(`publisher cleanup for #${channel} failed; the run is unaffected`);
+        }
+    })();
+    const setup = (async () => {
+        const agent = await call('/agents', options.workspaceKey, {
+            name: publisherName, type: 'agent', auto_join_general: false,
+        });
+        if (typeof agent?.token !== 'string')
+            throw new RelaycastError(0, 'agent_token_missing');
+        const token = agent.token;
+        try {
+            await call('/channels', token, { name: channel, topic: `relayflow ${run.flow} · run ${run.runId}` });
+        }
+        catch (error) {
+            // Agent communication in the same run may have created it first.
+            if (!(error instanceof RelaycastError) || error.code !== 'channel_already_exists')
+                throw error;
+            await call(`/channels/${encodeURIComponent(channel)}/join`, token, {});
+        }
+        return token;
+    })().catch(async (error) => { await removePublisher(false); throw error; });
+    let queue = setup;
+    let failed = false;
+    let sequence = 0;
+    let closed = false;
+    const sessionId = randomUUID().slice(0, 8);
+    const publish = (event, text) => {
+        if (closed)
+            return;
+        const data = { relayflow: { version: RELAYFLOW_METADATA_VERSION, event, run: structuredClone(snapshot) } };
+        const key = `${sessionId}-${++sequence}`;
+        queue = queue.then(async () => {
+            if (failed)
+                return;
+            await call(`/channels/${encodeURIComponent(channel)}/messages`, await setup, { text, data }, key);
+        }).catch((error) => {
+            if (failed)
+                return;
+            failed = true;
+            options.diagnostic(`run projection to #${channel} failed (${errorMessage(error)}); `
+                + 'the observer will not show this run, which is unaffected');
+        });
+    };
+    const declared = snapshot.steps.length;
+    publish('run.started', `▶ ${run.flow} ${run.resumed ? 'resumed' : 'started'}`
+        + `${declared > 0 ? ` · ${declared} step${declared === 1 ? '' : 's'}` : ''} · run ${run.runId}`);
+    return {
+        channel,
+        epoch(states, shouldPublish = true) {
+            snapshot.status = 'running';
+            delete snapshot.completionReason;
+            for (const step of snapshot.steps) {
+                step.state = 'pending';
+                delete step.attempt;
+                delete step.elapsedMs;
+                delete step.completionReason;
+                const state = states.find(candidate => candidate.id === step.id);
+                if (state !== undefined)
+                    Object.assign(step, state);
+            }
+            if (shouldPublish)
+                publish('run.started', `▶ ${run.flow} resumed · run ${run.runId}`);
+        },
+        step(event, shouldPublish = true) {
+            let step = snapshot.steps.find(candidate => candidate.id === event.stepId);
+            if (step === undefined) {
+                step = { id: event.stepId, type: event.stepType, dependsOn: [], state: 'pending' };
+                snapshot.steps.push(step);
+            }
+            step.state = STATE[event.type];
+            if (event.attempt !== undefined)
+                step.attempt = event.attempt;
+            if (event.type === 'step.started') {
+                delete step.elapsedMs;
+                delete step.completionReason;
+            }
+            else {
+                step.elapsedMs = Math.max(0, Math.round(event.elapsedMs));
+            }
+            if (event.completionReason !== undefined)
+                step.completionReason = event.completionReason;
+            if (!shouldPublish || event.type === 'step.running')
+                return;
+            publish(event.type, event.type === 'step.started'
+                ? `○ ${step.id} (${step.type}) started${step.attempt !== undefined && step.attempt > 1 ? ` · attempt ${step.attempt}` : ''}`
+                : renderProgress([event])[0]);
+        },
+        finish(outcome) {
+            if (snapshot.status !== 'running')
+                return;
+            snapshot.status = outcome.status;
+            if (outcome.completionReason !== undefined)
+                snapshot.completionReason = outcome.completionReason;
+            const icon = outcome.status === 'completed' ? '■' : outcome.status === 'parked' ? '⏸' : '✗';
+            publish('run.completed', `${icon} ${run.flow} ${outcome.status}`
+                + `${outcome.completionReason === undefined ? '' : ` · completionReason: ${outcome.completionReason}`}`);
+        },
+        async drain(timeoutMs) {
+            let timer;
+            await Promise.race([
+                queue,
+                new Promise(resolve => { timer = setTimeout(resolve, timeoutMs); timer.unref?.(); }),
+            ]);
+            clearTimeout(timer);
+        },
+        async close(timeoutMs) {
+            if (!closed) {
+                closed = true;
+                queue = queue.then(() => removePublisher(), () => removePublisher());
+            }
+            let timer;
+            try {
+                await Promise.race([queue, new Promise(resolve => { timer = setTimeout(resolve, timeoutMs); timer.unref?.(); })]);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+    };
+}
+const STATE = {
+    'step.started': 'running',
+    'step.running': 'running',
+    'step.completed': 'completed',
+    'step.failed': 'failed',
+    'step.parked': 'parked',
+};
+class RelaycastError extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super(status === 0 ? code : `HTTP ${status} ${code}`);
+        this.status = status;
+        this.code = code;
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=run-projection.js.map

package/dist/run-projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-projection.js","sourceRoot":"","sources":["../src/run-projection.ts"],"names":[],"mappings":"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"}

package/dist/shell-word.d.ts

@@ -0,0 +1,19 @@
+/**
+ * POSIX shell quoting for the invocations diagnostics tell people to run.
+ *
+ * Dependency-free on purpose: every module that renders a command reaches for
+ * this, and two of them (`cli/run.ts` and `authored-human.ts`) already import
+ * each other's neighbours. A copy per call site is how one of them ends up
+ * emitting a path with a space in it unquoted.
+ */
+/** `value` as a single word, quoted only when it would not survive a shell. */
+export declare function shellWord(value: string): string;
+/**
+ * `value` as a single-quoted word, always.
+ *
+ * Used where the rendered argument is arbitrary author data — a flow path or a
+ * JSON `--input` — and the quotes are worth keeping even when unnecessary, so
+ * the command reads the same for `a.flow.ts` and for `my flows/a.flow.ts`.
+ */
+export declare function shellQuote(value: string): string;
+//# sourceMappingURL=shell-word.d.ts.map

package/dist/shell-word.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-word.d.ts","sourceRoot":"","sources":["../src/shell-word.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD"}

package/dist/shell-word.js

@@ -0,0 +1,23 @@
+/**
+ * POSIX shell quoting for the invocations diagnostics tell people to run.
+ *
+ * Dependency-free on purpose: every module that renders a command reaches for
+ * this, and two of them (`cli/run.ts` and `authored-human.ts`) already import
+ * each other's neighbours. A copy per call site is how one of them ends up
+ * emitting a path with a space in it unquoted.
+ */
+/** `value` as a single word, quoted only when it would not survive a shell. */
+export function shellWord(value) {
+    return /^[A-Za-z0-9_./=:@%+,-]+$/.test(value) ? value : shellQuote(value);
+}
+/**
+ * `value` as a single-quoted word, always.
+ *
+ * Used where the rendered argument is arbitrary author data — a flow path or a
+ * JSON `--input` — and the quotes are worth keeping even when unnecessary, so
+ * the command reads the same for `a.flow.ts` and for `my flows/a.flow.ts`.
+ */
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+//# sourceMappingURL=shell-word.js.map

package/dist/shell-word.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-word.js","sourceRoot":"","sources":["../src/shell-word.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,+EAA+E;AAC/E,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,0BAA0B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;AAC5E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC;AAC/C,CAAC"}

package/dist/spec.d.ts

@@ -2,6 +2,12 @@ import type { JsonOutputSchema } from './output-schema.js';
 export type { JsonOutputSchema } from './output-schema.js';
 /** The three rungs of the ladder (RFC §1; AGENTS.md rule 7). */
 export type StepType = 'deterministic' | 'llm' | 'agent';
+/**
+ * A deterministic step's exit-code policy. `'fail'` is the kernel's implicit
+ * gate; `'record'` completes the step with its exit code journaled so a later
+ * step can read the outcome instead of re-running the command.
+ */
+export type OnNonZero = 'fail' | 'record';
 /** Project-owned MCP connections. env contains names, never secret values. */
 export type McpServerConfig = {
     command: string;
@@ -76,9 +82,23 @@ export interface ArtifactExistsGate {
     /** Working-directory-relative POSIX path, as the worker journals it. */
     path: string;
 }
+/**
+ * Asserts that every named step recorded a zero exit code, reading the
+ * journaled outcome instead of re-running the command. This is the read side
+ * of `onNonZero: 'record'`: red work is allowed to exist, and this gate is
+ * where a flow declares that it stops being allowed.
+ *
+ * Deterministic hosts only — a worker step has no recorded exit code to read —
+ * and the ids it names must be deterministic steps that precede it.
+ */
+export interface StepsGreenGate {
+    type: 'steps_green';
+    /** Earlier deterministic step ids whose recorded exit codes must all be zero. */
+    ids: string[];
+}
 export type NamedDataGate = ReferencesInputGate | SubprocessGate | WordCountBoundsGate | RegexMatchGate | ArtifactExistsGate;
 export type OutputVerificationSpec = OutputContainsGate | JsonSchemaGate | NamedDataGate;
-export type VerificationSpec = ExitCodeGate | OutputVerificationSpec;
+export type VerificationSpec = ExitCodeGate | StepsGreenGate | OutputVerificationSpec;
 /**
  * Agent-step recovery modes (RFC Appendix A rule 4). Default is `reset`.
  * These recovery modes apply to agent steps; deterministic steps retry their commands.
@@ -196,6 +216,15 @@ export interface DeterministicStepSpec extends BaseStepSpec {
     timeoutMs?: number;
     /** Per-invocation deterministic lease in milliseconds (maximum 15 minutes). */
     lease_ms?: number;
+    /**
+     * What a nonzero exit means. `'fail'` (the default) is the implicit
+     * `exit_code == 0` gate. `'record'` journals the exit code and output tails
+     * as the step's outcome, completes the step red, and lets dependents run —
+     * the repair-before-failure shape, without discarding the exit code the way
+     * `<command> || true` does. Declared content and schema gates, timeouts and
+     * worker errors keep their existing fatal semantics.
+     */
+    onNonZero?: OnNonZero;
     /** Omit to get the implicit `exit_code` gate. */
     verification?: VerificationSpec;
 }
@@ -242,7 +271,17 @@ export interface AgentStepSpec extends BaseStepSpec {
     surfaces?: AgentSurfaces;
     recoveryMode?: RecoveryMode;
     permissions?: PermissionsSpec;
-    /** Working directory for the CLI subprocess; defaults to the flow-runner's cwd. */
+    /**
+     * Directory the declared CLI is spawned in, as a path relative to the run
+     * root — the flow-runner's working directory, which is also where the CLI
+     * runs when this is absent. Absolute paths, `.`, `..` and empty components
+     * are refused lexically by `flows check` and by the kernel; the worker that
+     * spawns the CLI additionally requires the symlink-free directory to exist
+     * inside the symlink-free run root. A declaration, not a sandbox: nothing
+     * stops a CLI from writing outside it. Not supported with
+     * `transport: 'relay'`, where the agent runs on a host this process cannot
+     * resolve. See docs/SURFACE.md.
+     */
     cwd?: string;
     /**
      * Dispatch transport (flows#385). `'direct'` (default) spawns the CLI as
@@ -411,6 +450,12 @@ export interface KernelDeterministicStep extends KernelStepCommon {
     command: string;
     timeout_ms?: number;
     lease_ms?: number;
+    /**
+     * Omitted for the default `'fail'`, exactly as the kernel skips serializing
+     * it: a step that does not declare the policy keeps the canonical bytes —
+     * and therefore the step hash — it had before this field existed.
+     */
+    on_non_zero?: OnNonZero;
 }
 export interface KernelLlmStep extends KernelStepCommon {
     type: 'llm';
@@ -440,7 +485,11 @@ export interface KernelAgentStep extends KernelStepCommon {
     recovery_mode: RecoveryMode;
     surfaces?: KernelAgentSurfaces;
     permissions?: KernelPermissionsSpec;
-    /** Working directory for the CLI subprocess; kernel passes through untouched. */
+    /**
+     * Run-root-relative directory the attached worker spawns the CLI in. The
+     * kernel checks the shape and does no I/O: existence and containment are
+     * decided by the worker, on the host that shares the agent's filesystem.
+     */
     cwd?: string;
     /**
      * Dispatch transport (flows#385). Kernel passes through untouched;