@relayflows/sdk 2.0.30 → 2.0.32

package/dist/agent-artifacts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-artifacts.d.ts","sourceRoot":"","sources":["../src/agent-artifacts.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAItF;AAsCD,8FAA8F;AAC9F,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,EAAE,CAMpG"}
+{"version":3,"file":"agent-artifacts.d.ts","sourceRoot":"","sources":["../src/agent-artifacts.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAItF;AAsCD,8FAA8F;AAC9F,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,EAAE,CAMpG"}

package/dist/agent-artifacts.js

@@ -1,17 +1,10 @@
 import { createHash } from 'node:crypto';
 import { readFile, readdir, stat } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
+import { isUnscannedEntryName } from './artifact-scan-policy.js';
 function isEnoent(error) {
     return error instanceof Error && error.code === 'ENOENT';
 }
-/**
- * Entry names never walked and never reported, matched exactly, at any depth,
- * before the entry's type is consulted — so a `.git` *file* (a worktree's
- * gitdir pointer) is skipped as surely as a `.git` directory. Exact names, not
- * prefixes: `.github`, `.relayflowd-notes` and every other author-chosen name
- * that merely starts the same way stays eligible.
- */
-const SKIPPED_ENTRY_NAMES = new Set(['.git', '.relayflowd', 'node_modules']);
 /**
  * A recursive snapshot of every regular file under `dir`, keyed by its
  * `dir`-relative POSIX path, valued by a content signature (size + sha256).
@@ -53,7 +46,7 @@ async function walk(root, current, out) {
         throw error;
     }
     for (const entry of entries) {
-        if (SKIPPED_ENTRY_NAMES.has(entry.name))
+        if (isUnscannedEntryName(entry.name))
             continue;
         const path = join(current, entry.name);
         if (entry.isDirectory()) {

package/dist/agent-artifacts.js.map

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

package/dist/agent-cwd.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Where an agent step runs.
+ *
+ * A declared `cwd` is a path relative to the **run root** — the working
+ * directory of the process running the agent worker, which is the directory
+ * `flows run` was invoked from and, on the Cloud path, the uploaded tree
+ * (docs/CLOUD.md, "Code sync"). Absent, a step runs in the run root itself.
+ *
+ * Two checks, in two places, because they are two different facts:
+ *
+ * - The **declaration** is lexical and filesystem-free, so `flows check`, the
+ *   kernel's `validate()` and this worker all answer identically for the same
+ *   spec. `testdata/agent-cwd-cases.json` is the shared corpus both dialects
+ *   are tested against.
+ * - The **target** is resolved here, in the worker that spawns the CLI — the
+ *   one process provably sharing the agent's filesystem. A directory that
+ *   exists, and whose symlink-free path is inside the symlink-free run root.
+ *   Repeated at execution even when a preflight already passed, because the
+ *   filesystem moves underneath a spec.
+ *
+ * This contains a declaration; it does not sandbox an agent. Nothing stops a
+ * CLI from writing outside the directory it was started in. Per-step scoping
+ * is `permissions`, which is recorded and not enforced (gate 8 / #442).
+ */
+export declare class AgentCwdError extends Error {
+    constructor(message: string);
+}
+/**
+ * Why a declared `cwd` is not a run-root-relative path, or `undefined` when it
+ * is one. Pure and lexical: the exact rule
+ * `relayflowd_core::spec::is_run_root_relative_path` applies at the kernel
+ * boundary, so a declaration that passes `flows check` is not refused later by
+ * the daemon for its shape.
+ */
+export declare function agentCwdDeclarationError(cwd: unknown): string | undefined;
+/**
+ * The refusal for a `cwd` declared on a step dispatched over the relay
+ * transport, or `undefined` when there is nothing to refuse.
+ *
+ * The relay agent runs on another host. This process can neither resolve that
+ * host's filesystem nor establish that the directory is inside that run's
+ * tree, and forwarding the string as `worker_cwd` would let a declaration this
+ * contract promises to contain go unchecked. Fail closed instead of pretending.
+ */
+export declare function agentCwdTransportError(cwd: unknown, transport: unknown): string | undefined;
+/**
+ * The directory to spawn the CLI in: `root` when nothing is declared, else the
+ * symlink-free directory `cwd` names beneath `root`.
+ *
+ * @throws AgentCwdError naming the declaration and what is wrong with it.
+ */
+export declare function resolveAgentCwd(root: string, cwd: unknown, transport?: unknown): string | undefined;
+/** Either the directory an agent step runs in, or why the step is refused. */
+export type AgentCwdOutcome = {
+    directory: string | undefined;
+} | {
+    refusal: string;
+};
+/**
+ * The dispatch-time form: resolve a dispatched agent step's `cwd` against the
+ * run root, or report the refusal for the worker to complete the step with.
+ * Reporting rather than throwing keeps the refusal on the step's completion —
+ * `worker_error`, with the reason journaled — instead of on the worker.
+ */
+export declare function agentStepCwd(spec: {
+    cwd?: unknown;
+    transport?: unknown;
+}, stepId: string, root?: string): AgentCwdOutcome;
+//# sourceMappingURL=agent-cwd.d.ts.map

package/dist/agent-cwd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-cwd.d.ts","sourceRoot":"","sources":["../src/agent-cwd.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAYzE;AAYD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI3F;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CA8BnG;AAED,8EAA8E;AAC9E,MAAM,MAAM,eAAe,GAAG;IAAE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtF;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE;IAAE,GAAG,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,EAC5C,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,MAAsB,GAC3B,eAAe,CAOjB"}

package/dist/agent-cwd.js

@@ -0,0 +1,140 @@
+import { realpathSync, statSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+/**
+ * Where an agent step runs.
+ *
+ * A declared `cwd` is a path relative to the **run root** — the working
+ * directory of the process running the agent worker, which is the directory
+ * `flows run` was invoked from and, on the Cloud path, the uploaded tree
+ * (docs/CLOUD.md, "Code sync"). Absent, a step runs in the run root itself.
+ *
+ * Two checks, in two places, because they are two different facts:
+ *
+ * - The **declaration** is lexical and filesystem-free, so `flows check`, the
+ *   kernel's `validate()` and this worker all answer identically for the same
+ *   spec. `testdata/agent-cwd-cases.json` is the shared corpus both dialects
+ *   are tested against.
+ * - The **target** is resolved here, in the worker that spawns the CLI — the
+ *   one process provably sharing the agent's filesystem. A directory that
+ *   exists, and whose symlink-free path is inside the symlink-free run root.
+ *   Repeated at execution even when a preflight already passed, because the
+ *   filesystem moves underneath a spec.
+ *
+ * This contains a declaration; it does not sandbox an agent. Nothing stops a
+ * CLI from writing outside the directory it was started in. Per-step scoping
+ * is `permissions`, which is recorded and not enforced (gate 8 / #442).
+ */
+export class AgentCwdError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AgentCwdError';
+    }
+}
+/**
+ * Why a declared `cwd` is not a run-root-relative path, or `undefined` when it
+ * is one. Pure and lexical: the exact rule
+ * `relayflowd_core::spec::is_run_root_relative_path` applies at the kernel
+ * boundary, so a declaration that passes `flows check` is not refused later by
+ * the daemon for its shape.
+ */
+export function agentCwdDeclarationError(cwd) {
+    const expected = 'expected a run-root-relative path';
+    if (typeof cwd !== 'string')
+        return `${expected} (got ${cwd === null ? 'null' : typeof cwd})`;
+    if (cwd === '')
+        return `${expected}, not an empty string`;
+    if (PADDING.test(cwd))
+        return `${expected} without surrounding whitespace`;
+    if (cwd.includes('\0'))
+        return `${expected} without NUL`;
+    if (cwd.startsWith('/'))
+        return `${expected}, not an absolute path`;
+    if (cwd.includes('://'))
+        return `${expected}, not a URI-like mount identity`;
+    if (cwd.split('/').some((part) => part === '' || part === '.' || part === '..')) {
+        return `${expected} without empty, "." or ".." components`;
+    }
+    return undefined;
+}
+/**
+ * Whitespace at either end, spelled so both dialects refuse the same set.
+ * JavaScript's `\s` is Unicode `White_Space` without U+0085 and with U+FEFF;
+ * Rust's `char::is_whitespace` is `White_Space` exactly. Naming U+0085 here
+ * and U+FEFF there makes both `White_Space ∪ {U+FEFF}`. Left to `trim()`
+ * alone, a path padded with either character would pass `flows check` and be
+ * refused by the kernel — the accept-then-refuse split this contract closes.
+ */
+const PADDING = /^[\s\u0085]|[\s\u0085]$/u;
+/**
+ * The refusal for a `cwd` declared on a step dispatched over the relay
+ * transport, or `undefined` when there is nothing to refuse.
+ *
+ * The relay agent runs on another host. This process can neither resolve that
+ * host's filesystem nor establish that the directory is inside that run's
+ * tree, and forwarding the string as `worker_cwd` would let a declaration this
+ * contract promises to contain go unchecked. Fail closed instead of pretending.
+ */
+export function agentCwdTransportError(cwd, transport) {
+    if (cwd === undefined || transport !== 'relay')
+        return undefined;
+    return 'cwd is not supported with transport "relay": the agent runs on another host, '
+        + 'where this worker cannot resolve the directory or hold it inside the run root';
+}
+/**
+ * The directory to spawn the CLI in: `root` when nothing is declared, else the
+ * symlink-free directory `cwd` names beneath `root`.
+ *
+ * @throws AgentCwdError naming the declaration and what is wrong with it.
+ */
+export function resolveAgentCwd(root, cwd, transport) {
+    if (cwd === undefined)
+        return undefined;
+    const refusal = (detail) => new AgentCwdError(`cwd ${JSON.stringify(cwd)}: ${detail}`);
+    const declaration = agentCwdDeclarationError(cwd);
+    if (declaration !== undefined)
+        throw refusal(declaration);
+    const unsupported = agentCwdTransportError(cwd, transport);
+    if (unsupported !== undefined)
+        throw new AgentCwdError(unsupported);
+    let realRoot;
+    try {
+        realRoot = realpathSync(root);
+    }
+    catch {
+        throw refusal(`the run root ${JSON.stringify(root)} cannot be resolved on this host`);
+    }
+    let target;
+    try {
+        target = realpathSync(resolve(realRoot, cwd));
+    }
+    catch {
+        throw refusal(`no such directory under the run root ${JSON.stringify(realRoot)}`);
+    }
+    // Component-aware, on the symlink-free forms of both: `checkout-b-old` is
+    // not inside `checkout-b`, and a symlink pointing out of the tree is not
+    // inside it either however it is spelled.
+    const prefix = realRoot.endsWith(sep) ? realRoot : realRoot + sep;
+    if (target !== realRoot && !target.startsWith(prefix)) {
+        throw refusal(`resolves to ${JSON.stringify(target)}, outside the run root ${JSON.stringify(realRoot)}`);
+    }
+    if (!statSync(target).isDirectory())
+        throw refusal(`${JSON.stringify(target)} is not a directory`);
+    return target;
+}
+/**
+ * The dispatch-time form: resolve a dispatched agent step's `cwd` against the
+ * run root, or report the refusal for the worker to complete the step with.
+ * Reporting rather than throwing keeps the refusal on the step's completion —
+ * `worker_error`, with the reason journaled — instead of on the worker.
+ */
+export function agentStepCwd(spec, stepId, root = process.cwd()) {
+    try {
+        return { directory: resolveAgentCwd(root, spec.cwd, spec.transport) };
+    }
+    catch (error) {
+        if (!(error instanceof AgentCwdError))
+            throw error;
+        return { refusal: `agent step "${stepId}": ${error.message}` };
+    }
+}
+//# sourceMappingURL=agent-cwd.js.map

package/dist/agent-cwd.js.map

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

package/dist/artifact-scan-policy.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The bundled agent worker's artifact-scan policy, as a pure predicate.
+ *
+ * `agent-artifacts.ts` walks an agent step's cwd and records every regular
+ * file it finds, except entries named exactly `.git`, `.relayflowd` or
+ * `node_modules` — files as well as directories, in both cases. Dotfiles and
+ * dot-directories ARE eligible: `.workflow-artifacts/` is the conventional
+ * place a flow tells its agents to write. What that walk records is one
+ * source of the journaled `output.artifacts` list, which is the only thing an
+ * `artifact_exists` gate reads (`named-gate-lowering.ts` tests exact
+ * membership in that list and never touches disk).
+ *
+ * Static analysis needs the same rule without importing filesystem traversal,
+ * so the rule lives here and both consume it. It bounds the *scan*, not the
+ * list: `worker.ts` journals object-shaped JSON stdout and completed Relay
+ * task output verbatim instead of the scanned wrapper, and
+ * `JournalClient.stepComplete` accepts any `output` from any worker — so a
+ * path this predicate excludes can still reach the list by those routes
+ * (`named-gate-preflight.ts` warns rather than refusing for exactly that
+ * reason).
+ */
+export declare function isUnscannedEntryName(name: string): boolean;
+/**
+ * The shortest `/`-prefix of a relative POSIX `path` the scan excludes, or
+ * `undefined` when every segment is scanned.
+ *
+ * Segments are compared exactly, with no normalization: the gate matches the
+ * author's literal string against the worker's literal list, so `node_modules`
+ * is excluded and `node_modules-copy` is not, and a backslash is an ordinary
+ * filename character rather than a separator. The whole prefix is returned,
+ * not the offending segment alone, because that prefix is the directory an
+ * author has to move the artifact out of.
+ */
+export declare function unscannedArtifactPrefix(path: string): string | undefined;
+//# sourceMappingURL=artifact-scan-policy.d.ts.map

package/dist/artifact-scan-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-scan-policy.d.ts","sourceRoot":"","sources":["../src/artifact-scan-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAWH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIxE"}

package/dist/artifact-scan-policy.js

@@ -0,0 +1,49 @@
+/**
+ * The bundled agent worker's artifact-scan policy, as a pure predicate.
+ *
+ * `agent-artifacts.ts` walks an agent step's cwd and records every regular
+ * file it finds, except entries named exactly `.git`, `.relayflowd` or
+ * `node_modules` — files as well as directories, in both cases. Dotfiles and
+ * dot-directories ARE eligible: `.workflow-artifacts/` is the conventional
+ * place a flow tells its agents to write. What that walk records is one
+ * source of the journaled `output.artifacts` list, which is the only thing an
+ * `artifact_exists` gate reads (`named-gate-lowering.ts` tests exact
+ * membership in that list and never touches disk).
+ *
+ * Static analysis needs the same rule without importing filesystem traversal,
+ * so the rule lives here and both consume it. It bounds the *scan*, not the
+ * list: `worker.ts` journals object-shaped JSON stdout and completed Relay
+ * task output verbatim instead of the scanned wrapper, and
+ * `JournalClient.stepComplete` accepts any `output` from any worker — so a
+ * path this predicate excludes can still reach the list by those routes
+ * (`named-gate-preflight.ts` warns rather than refusing for exactly that
+ * reason).
+ */
+/**
+ * Entry names the walk never descends into or records, matched exactly, at
+ * any depth, before the entry's type is consulted — so a `.git` *file* (a
+ * worktree's gitdir pointer) is skipped as surely as a `.git` directory.
+ * Exact names, not prefixes: `.github`, `.relayflowd-notes` and every other
+ * author-chosen name that merely starts the same way stays eligible.
+ */
+const SKIPPED_ENTRY_NAMES = new Set(['.git', '.relayflowd', 'node_modules']);
+export function isUnscannedEntryName(name) {
+    return SKIPPED_ENTRY_NAMES.has(name);
+}
+/**
+ * The shortest `/`-prefix of a relative POSIX `path` the scan excludes, or
+ * `undefined` when every segment is scanned.
+ *
+ * Segments are compared exactly, with no normalization: the gate matches the
+ * author's literal string against the worker's literal list, so `node_modules`
+ * is excluded and `node_modules-copy` is not, and a backslash is an ordinary
+ * filename character rather than a separator. The whole prefix is returned,
+ * not the offending segment alone, because that prefix is the directory an
+ * author has to move the artifact out of.
+ */
+export function unscannedArtifactPrefix(path) {
+    const segments = path.split('/');
+    const index = segments.findIndex(isUnscannedEntryName);
+    return index === -1 ? undefined : segments.slice(0, index + 1).join('/');
+}
+//# sourceMappingURL=artifact-scan-policy.js.map

package/dist/artifact-scan-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-scan-policy.js","sourceRoot":"","sources":["../src/artifact-scan-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;GAMG;AACH,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,aAAa,EAAE,cAAc,CAAC,CAAC,CAAC;AAE7E,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,OAAO,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAY;IAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,KAAK,GAAG,QAAQ,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC;IACvD,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC3E,CAAC"}

package/dist/authored-completion-record.d.ts

@@ -0,0 +1,35 @@
+import { type LoweredCompletionReason } from './authored-completion.js';
+import type { JournalClient } from './journal-client.js';
+export declare const AUTHORED_VERDICT_STREAM = "authored-verdict";
+export interface AuthoredVerdictRecord {
+    readonly reason: LoweredCompletionReason;
+    /** Recorded only when the body passed one; see the module comment. */
+    readonly detail?: string;
+}
+/**
+ * Commit this body's verdict, or recover the one this root already committed.
+ *
+ * Returns the verdict the marker must be built from — the recorded one when
+ * the root holds it, this attempt's otherwise. With no root run there is
+ * nothing durable to write to (the non-durable executor seam), so that path
+ * passes straight through without a round trip. A root run is always read
+ * first: a committed record stays authoritative even for an attempt that has
+ * no detail of its own — an optional source can be present on the first
+ * execution and gone on the retry, and "this attempt has no detail" is not
+ * "this root never recorded one". Only when no record exists AND this attempt
+ * has no detail does it return without appending, preserving the no-detail
+ * marker, spec hash, and journal exactly as before.
+ */
+export declare function commitAuthoredVerdict(journal: JournalClient, rootRunId: string | undefined, step: string, verdict: AuthoredVerdictRecord): Promise<AuthoredVerdictRecord>;
+/**
+ * The verdict this root recorded for `step`, or `undefined`.
+ *
+ * The FIRST valid record wins: it is the one the marker was — or was about to
+ * be — admitted from, and a later attempt's differently-redacted text must not
+ * displace it. Records this version does not recognise, and details that fail
+ * the durable check every other read boundary applies, are skipped rather than
+ * trusted; the marker then drifts and the kernel refuses it loudly, which is
+ * the right outcome for a record this process cannot read.
+ */
+export declare function readAuthoredVerdict(journal: JournalClient, rootRunId: string, step: string): Promise<AuthoredVerdictRecord | undefined>;
+//# sourceMappingURL=authored-completion-record.d.ts.map

package/dist/authored-completion-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authored-completion-record.d.ts","sourceRoot":"","sources":["../src/authored-completion-record.ts"],"names":[],"mappings":"AAwBA,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAK1D,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,qBAAqB,CAAC,CAShC;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAgB5C"}

package/dist/authored-completion-record.js

@@ -0,0 +1,92 @@
+// The authored verdict, written to the root BEFORE the marker is admitted.
+//
+// The terminal marker's command embeds the detail, and the marker run is
+// opened under a stable admission key (`authored-child:<hash(root, step)>`).
+// Those two facts together mean the detail has to be a durable decision, not a
+// recomputed one: normalization redacts against `process.env`, so a credential
+// rotated or removed while this process was down makes the SAME authored
+// sentence normalize differently. A body resumed into that environment would
+// retry the marker's admission key with a drifted spec, and the kernel refuses
+// that as `run_admission_conflict` — losing an explanation the root had
+// already journaled, for a flow whose every step succeeded.
+//
+// So the verdict is appended to a stream on the root run before the marker run
+// is opened, and a later attempt reaching the same terminal step reuses what
+// is recorded. That is exactly the durability the executor already gives a
+// predicate gate (`applyPredicateGate`): record the decision first, so the
+// spec built from it is identical on every attempt and author code is never
+// asked the question twice.
+//
+// Nothing is recorded for a `done()` with no detail. Without one the marker
+// command is a function of the reason alone — no environment, no drift, and
+// nothing to recover — so a flow that does not opt in writes exactly the
+// journal it has always written.
+import { isDurableCompletionDetail, isLoweredCompletion, } from './authored-completion.js';
+export const AUTHORED_VERDICT_STREAM = 'authored-verdict';
+/** Versioned so a reader can tell this record from a future one. */
+const RECORD_KIND = 'relayflows.authored-verdict.v1';
+/**
+ * Commit this body's verdict, or recover the one this root already committed.
+ *
+ * Returns the verdict the marker must be built from — the recorded one when
+ * the root holds it, this attempt's otherwise. With no root run there is
+ * nothing durable to write to (the non-durable executor seam), so that path
+ * passes straight through without a round trip. A root run is always read
+ * first: a committed record stays authoritative even for an attempt that has
+ * no detail of its own — an optional source can be present on the first
+ * execution and gone on the retry, and "this attempt has no detail" is not
+ * "this root never recorded one". Only when no record exists AND this attempt
+ * has no detail does it return without appending, preserving the no-detail
+ * marker, spec hash, and journal exactly as before.
+ */
+export async function commitAuthoredVerdict(journal, rootRunId, step, verdict) {
+    if (rootRunId === undefined)
+        return verdict;
+    const committed = await readAuthoredVerdict(journal, rootRunId, step);
+    if (committed !== undefined)
+        return committed;
+    if (verdict.detail === undefined)
+        return verdict;
+    await journal.streamAppend(rootRunId, AUTHORED_VERDICT_STREAM, {
+        verdict: RECORD_KIND, step, reason: verdict.reason, detail: verdict.detail,
+    });
+    return verdict;
+}
+/**
+ * The verdict this root recorded for `step`, or `undefined`.
+ *
+ * The FIRST valid record wins: it is the one the marker was — or was about to
+ * be — admitted from, and a later attempt's differently-redacted text must not
+ * displace it. Records this version does not recognise, and details that fail
+ * the durable check every other read boundary applies, are skipped rather than
+ * trusted; the marker then drifts and the kernel refuses it loudly, which is
+ * the right outcome for a record this process cannot read.
+ */
+export async function readAuthoredVerdict(journal, rootRunId, step) {
+    let offset = 0;
+    for (;;) {
+        const page = await journal.streamRead(rootRunId, AUTHORED_VERDICT_STREAM, offset, 1000);
+        for (const message of page.messages) {
+            // `stream.read` returns either the envelope or the bare message,
+            // matching how the executor reads predicate verdicts.
+            const raw = message.message ?? message;
+            if (isVerdictRecord(raw) && raw.step === step) {
+                return Object.freeze({ reason: raw.reason, detail: raw.detail });
+            }
+        }
+        if (page.messages.length === 0 || page.next_offset <= offset)
+            break;
+        offset = page.next_offset;
+    }
+    return undefined;
+}
+function isVerdictRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    return record.verdict === RECORD_KIND
+        && typeof record.step === 'string' && record.step.length > 0
+        && isLoweredCompletion(record.reason)
+        && isDurableCompletionDetail(record.detail);
+}
+//# sourceMappingURL=authored-completion-record.js.map

package/dist/authored-completion-record.js.map

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

package/dist/authored-completion.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The completion reasons an authored body may declare and this executor lowers.
+ *
+ * `FlowCompletionReason` is wider than this on purpose — it is the journal's
+ * run vocabulary plus authored verdicts — but the two sets drifting silently is
+ * exactly what made a type-valid `done("step_failed")` die at runtime as
+ * `unsupported_completion`. Every gate that asks "is this a completion this
+ * runtime can lower?" now asks this one function, so a reason cannot be
+ * accepted in one place and rejected in another.
+ *
+ * These are internal cross-module helpers for the authored seam (the executor,
+ * the durable root, the IPC verifier, the CLI report and `flows status`), NOT
+ * public SDK surface. `src/index.ts` deliberately re-exports nothing from this
+ * module — keep it that way, or the whole authored seam leaks with them.
+ */
+export declare const LOWERED_COMPLETIONS: readonly ["success", "needs_human", "step_failed", "declined"];
+export type LoweredCompletionReason = (typeof LOWERED_COMPLETIONS)[number];
+export declare function isLoweredCompletion(value: unknown): value is LoweredCompletionReason;
+/**
+ * The bound on a normalized completion detail: 2,000 Unicode code points in
+ * the FINAL string, {@link COMPLETION_DETAIL_TRUNCATED_SUFFIX} included.
+ *
+ * Code points, not `String.length`: `.length` counts UTF-16 code units, so an
+ * emoji-heavy detail measured that way is half the length a reader would call
+ * it. The number matches `@relayflows/surface`'s
+ * `COMPLETION_DETAIL_MAX_CODE_POINTS`, which is what an author sees; it is the
+ * same order as the kernel's gate-detail cap
+ * (`kernel/relayflowd/src/engine/remote.rs`) but deliberately NOT the same
+ * bound — that one takes 2,000 characters and then appends its suffix, so its
+ * final string is longer than the number it advertises.
+ */
+export declare const COMPLETION_DETAIL_MAX_CODE_POINTS = 2000;
+/** Fixed width, so the bound above can reserve exactly its room. */
+export declare const COMPLETION_DETAIL_TRUNCATED_SUFFIX = "\u2026 (truncated)";
+/**
+ * Read `done()`'s optional second argument into the detail the marker carries.
+ *
+ * Absence has four spellings — no argument, `undefined`, `{}`, and
+ * `{ detail: undefined }` — and all four mean the same thing: no detail, and a
+ * marker command byte-identical to the one the one-argument call has always
+ * produced. Whitespace-only joins them: say nothing, or say something.
+ *
+ * A `detail` that is present and not a string is a programming error the type
+ * system already catches for TypeScript callers; the runtime check is here for
+ * the same reason `isSurfaceFlowCompletionReason` is, and it refuses with the
+ * existing closed `unsupported_completion` code rather than widening the
+ * taxonomy. Refusals name the type they got, never the value — a malformed
+ * detail is exactly the kind of text that may carry a credential.
+ *
+ * Redaction runs BEFORE truncation, and the order is load-bearing rather than
+ * cosmetic: truncating first can split a token so no pattern matches it any
+ * more, which is a truncation that *causes* a leak. What redaction recognises
+ * is the SDK's existing policy — known token shapes, named credential fields,
+ * and the values of secret-looking environment variables (`redact.ts`) — not a
+ * guarantee to recognise every possible secret.
+ *
+ * Lone surrogates are substituted here too, so what leaves this function is a
+ * well-formed string the journal protocol can carry — see {@link wellFormed}.
+ */
+export declare function normalizeCompletionDetail(options: unknown, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Is this a detail a durable record may carry?
+ *
+ * The gate every read boundary uses — the completed root's output, and the
+ * IPC frame the Bun runner returns — so an over-long or wrong-typed value
+ * fails closed there instead of flowing into a report as if it had been
+ * journaled by this process.
+ */
+export declare function isDurableCompletionDetail(value: unknown): value is string;
+/**
+ * The detail as ONE line, for a diagnostic message.
+ *
+ * Cloud renders a run's `error` through a line-oriented view that elides the
+ * middle of a long one (`cli/cloud-read.ts` `errorLines`), so a forty-line
+ * detail can lose the very finding it exists to carry. Escaping the breaks
+ * keeps the whole detail on the single line that renderer cannot elide, and
+ * keeps control characters out of a terminal. The unescaped normalized detail
+ * still travels in the structured fields beside it.
+ */
+export declare function singleLineCompletionDetail(detail: string): string;
+/**
+ * The deterministic command that carries an authored verdict into the journal.
+ *
+ * `success` with no detail lowers to `:` because success needs no marker: the
+ * marker run's own kernel `success` already IS that record. Every other
+ * lowered verdict is something the kernel's completion vocabulary cannot
+ * express on a step that *succeeded*, so it travels as data on stdout and is
+ * read back from `step.completed`. It is deliberately not lowered as a failing
+ * command: no step failed here, and a fabricated failure would put bogus
+ * evidence in the journal for a flow whose steps all ran correctly.
+ *
+ * A detail rides in the same JSON object, so the marker stays the one durable
+ * record of the verdict and the IPC verifier's existing command comparison
+ * checks the detail against the journal for free. With no detail the command
+ * is byte-identical to the one this function has always returned, which is
+ * what keeps `spec_hash` stable for every flow that does not opt in.
+ */
+export declare function completionMarker(reason: LoweredCompletionReason, detail?: string): string;
+//# sourceMappingURL=authored-completion.d.ts.map

package/dist/authored-completion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authored-completion.d.ts","sourceRoot":"","sources":["../src/authored-completion.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,gEAAiE,CAAC;AAClG,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,uBAAuB,CAEpF;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iCAAiC,OAAO,CAAC;AAEtD,oEAAoE;AACpE,eAAO,MAAM,kCAAkC,uBAAkB,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,EAChB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,SAAS,CAkBpB;AAkCD;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAKzE;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGjE;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,uBAAuB,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CASzF"}