@relayflows/sdk 2.0.6 → 2.0.8

package/dist/authored-flow-error.d.ts

@@ -1,5 +1,5 @@
 import type { CompletionReason as ProtocolCompletionReason, RunCompletionReason as ProtocolRunCompletionReason } from './protocol.js';
-export type AuthoredFlowExecutionErrorCode = 'duplicate_completion' | 'journal_protocol_violation' | 'missing_completion' | 'operation_after_completion' | 'operation_callback_failed' | 'step_failed' | 'unsupported_completion' | 'unsupported_gate' | 'unsupported_header' | 'unsettled_derived_work' | 'unsupported_promise_lifecycle' | 'unawaited_step' | 'unsupported_verb';
+export type AuthoredFlowExecutionErrorCode = 'agent_cli_unresolved' | 'agent_parked' | 'duplicate_completion' | 'journal_protocol_violation' | 'missing_completion' | 'operation_after_completion' | 'operation_callback_failed' | 'step_failed' | 'unsupported_completion' | 'unsupported_gate' | 'unsupported_header' | 'unsettled_derived_work' | 'unsupported_promise_lifecycle' | 'unsupported_workspace_permission' | 'unawaited_step' | 'unsupported_verb';
 export declare class AuthoredFlowExecutionError extends Error {
     readonly code: AuthoredFlowExecutionErrorCode;
     readonly completionReason?: (ProtocolCompletionReason | ProtocolRunCompletionReason) | undefined;

package/dist/authored-flow-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authored-flow-error.d.ts","sourceRoot":"","sources":["../src/authored-flow-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,IAAI,wBAAwB,EAC5C,mBAAmB,IAAI,2BAA2B,EACnD,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,8BAA8B,GACtC,sBAAsB,GACtB,4BAA4B,GAC5B,oBAAoB,GACpB,4BAA4B,GAC5B,2BAA2B,GAC3B,aAAa,GACb,wBAAwB,GACxB,kBAAkB,GAClB,oBAAoB,GACpB,wBAAwB,GACxB,+BAA+B,GAC/B,gBAAgB,GAChB,kBAAkB,CAAC;AAEvB,qBAAa,0BAA2B,SAAQ,KAAK;IAEjD,QAAQ,CAAC,IAAI,EAAE,8BAA8B;IAE7C,QAAQ,CAAC,gBAAgB,CAAC,GAAE,wBAAwB,GAAG,2BAA2B;IAClF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM;gBAHd,IAAI,EAAE,8BAA8B,EAC7C,OAAO,EAAE,MAAM,EACN,gBAAgB,CAAC,GAAE,wBAAwB,GAAG,2BAA2B,aAAA,EACzE,KAAK,CAAC,EAAE,MAAM,YAAA;CAK1B"}
+{"version":3,"file":"authored-flow-error.d.ts","sourceRoot":"","sources":["../src/authored-flow-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,IAAI,wBAAwB,EAC5C,mBAAmB,IAAI,2BAA2B,EACnD,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,8BAA8B,GACtC,sBAAsB,GACtB,cAAc,GACd,sBAAsB,GACtB,4BAA4B,GAC5B,oBAAoB,GACpB,4BAA4B,GAC5B,2BAA2B,GAC3B,aAAa,GACb,wBAAwB,GACxB,kBAAkB,GAClB,oBAAoB,GACpB,wBAAwB,GACxB,+BAA+B,GAC/B,kCAAkC,GAClC,gBAAgB,GAChB,kBAAkB,CAAC;AAEvB,qBAAa,0BAA2B,SAAQ,KAAK;IAEjD,QAAQ,CAAC,IAAI,EAAE,8BAA8B;IAE7C,QAAQ,CAAC,gBAAgB,CAAC,GAAE,wBAAwB,GAAG,2BAA2B;IAClF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM;gBAHd,IAAI,EAAE,8BAA8B,EAC7C,OAAO,EAAE,MAAM,EACN,gBAAgB,CAAC,GAAE,wBAAwB,GAAG,2BAA2B,aAAA,EACzE,KAAK,CAAC,EAAE,MAAM,YAAA;CAK1B"}

package/dist/authored-flow-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"authored-flow-error.js","sourceRoot":"","sources":["../src/authored-flow-error.ts"],"names":[],"mappings":"AAoBA,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAExC;IAEA;IACA;IAJX,YACW,IAAoC,EAC7C,OAAe,EACN,gBAAyE,EACzE,KAAc;QAEvB,KAAK,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;QALpB,SAAI,GAAJ,IAAI,CAAgC;QAEpC,qBAAgB,GAAhB,gBAAgB,CAAyD;QACzE,UAAK,GAAL,KAAK,CAAS;QAGvB,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF"}
+{"version":3,"file":"authored-flow-error.js","sourceRoot":"","sources":["../src/authored-flow-error.ts"],"names":[],"mappings":"AAuBA,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAExC;IAEA;IACA;IAJX,YACW,IAAoC,EAC7C,OAAe,EACN,gBAAyE,EACzE,KAAc;QAEvB,KAAK,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;QALpB,SAAI,GAAJ,IAAI,CAAgC;QAEpC,qBAAgB,GAAhB,gBAAgB,CAAyD;QACzE,UAAK,GAAL,KAAK,CAAS;QAGvB,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF"}

package/dist/authored-flow-executor.d.ts

@@ -1,4 +1,6 @@
 import type { FlowHandle } from '@relayflows/surface/runtime';
+import type { GetFlowDefinition } from './authored-flow-loader.js';
+import { type RunLifecycleOptions } from './cli/run.js';
 import { AuthoredFlowExecutionError, type AuthoredFlowExecutionErrorCode } from './authored-flow-error.js';
 import { JournalClient } from './journal-client.js';
 import type { CompletionReason as ProtocolCompletionReason, RunCompletionReason as ProtocolRunCompletionReason } from './protocol.js';
@@ -24,5 +26,29 @@ export interface AuthoredFlowExecutionResult {
  * `JournalClient`; values are read back from `step.completed` journal entries.
  * Unsupported headers, verbs, gates, or completion lowering fail closed.
  */
-export declare function executeAuthoredFlow<Input = undefined>(handle: FlowHandle, journal: JournalClient, input?: Input): Promise<AuthoredFlowExecutionResult>;
+export interface ExecuteAuthoredFlowOptions {
+    /**
+     * Defaults to this package's own static import — correct for every
+     * existing (internal, single-instance) caller. A flow loaded from an
+     * external path via `loadAuthoredFlow` must pass ITS resolved
+     * `getDefinition` instead; see authored-flow-loader.ts's comment on why.
+     */
+    readonly getDefinition?: GetFlowDefinition;
+    /**
+     * The flow file's own path — passed straight to `checkAuthoredFlow`
+     * (cli/check.ts) so `f.agent` resolves a CLI the same way a declarative
+     * `type: agent` step does: nearest `flows.json`, real auth/model probing,
+     * canonicalized path. `checkAuthoredFlow` always does `dirname()` on this,
+     * matching `checkFlow`'s real `flows check <file>` contract — pass a FILE
+     * path, not a directory, or the search starts one level too high. Defaults
+     * to a synthetic `flow.ts` under `process.cwd()` for exactly this reason:
+     * `process.cwd()` itself is a directory, and `dirname(process.cwd())`
+     * would search cwd's PARENT.
+     */
+    readonly flowPath?: string;
+    /** Passed straight through to classifyOutcome (cli/run.ts) for f.agent's wait. */
+    readonly signal?: RunLifecycleOptions['signal'];
+    readonly onWait?: RunLifecycleOptions['onWait'];
+}
+export declare function executeAuthoredFlow<Input = undefined>(handle: FlowHandle, journal: JournalClient, input?: Input, options?: ExecuteAuthoredFlowOptions): Promise<AuthoredFlowExecutionResult>;
 //# sourceMappingURL=authored-flow-executor.d.ts.map

package/dist/authored-flow-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authored-flow-executor.d.ts","sourceRoot":"","sources":["../src/authored-flow-executor.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAG9D,OAAO,EACL,0BAA0B,EAC1B,KAAK,8BAA8B,EACpC,MAAM,0BAA0B,CAAC;AAOlC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EACV,gBAAgB,IAAI,wBAAwB,EAC5C,mBAAmB,IAAI,2BAA2B,EAEnD,MAAM,eAAe,CAAC;AAqBvB,OAAO,EAAE,0BAA0B,EAAE,KAAK,8BAA8B,EAAE,CAAC;AAE3E,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,EAAE,wBAAwB,CAAC;CACrD;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,gBAAgB,EAAE,2BAA2B,CAAC;IACvD,QAAQ,CAAC,YAAY,EAAE,SAAS,uBAAuB,EAAE,CAAC;CAC3D;AASD;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,GAAG,SAAS,EACzD,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,aAAa,EACtB,KAAK,CAAC,EAAE,KAAK,GACZ,OAAO,CAAC,2BAA2B,CAAC,CAwJtC"}
+{"version":3,"file":"authored-flow-executor.d.ts","sourceRoot":"","sources":["../src/authored-flow-executor.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAI9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEnE,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEzE,OAAO,EACL,0BAA0B,EAC1B,KAAK,8BAA8B,EACpC,MAAM,0BAA0B,CAAC;AAOlC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EACV,gBAAgB,IAAI,wBAAwB,EAC5C,mBAAmB,IAAI,2BAA2B,EAEnD,MAAM,eAAe,CAAC;AAqBvB,OAAO,EAAE,0BAA0B,EAAE,KAAK,8BAA8B,EAAE,CAAC;AAW3E,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,EAAE,wBAAwB,CAAC;CACrD;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,gBAAgB,EAAE,2BAA2B,CAAC;IACvD,QAAQ,CAAC,YAAY,EAAE,SAAS,uBAAuB,EAAE,CAAC;CAC3D;AASD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAC3C;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;CACjD;AAED,wBAAsB,mBAAmB,CAAC,KAAK,GAAG,SAAS,EACzD,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,aAAa,EACtB,KAAK,CAAC,EAAE,KAAK,EACb,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,2BAA2B,CAAC,CA6PtC"}

package/dist/authored-flow-executor.js

@@ -1,24 +1,32 @@
 import { COMPLETION_REASONS, RUN_COMPLETION_REASONS, } from '@relayflows/surface';
+import { join } from 'node:path';
 import { compileSpec, toKernelSpec } from './compile.js';
 import { getAuthoredFlowDefinition } from './authored-flow.js';
+import { checkAuthoredFlow } from './cli/check.js';
+import { classifyOutcome } from './cli/run.js';
 import { AuthoredFlowExecutionError, } from './authored-flow-error.js';
 import { AuthoredFlowOperation, stopAuthoredOperations, verifyAuthoredOperations, } from './authored-flow-operation.js';
 import { AuthoredFlowLifecycle } from './authored-flow-lifecycle.js';
 import { SPEC_SCHEMA_VERSION } from './spec.js';
 export { AuthoredFlowExecutionError };
 /**
- * Exercise the internal authored-flow lowering seam through protocol v0.
- *
- * This is deliberately not exported by the SDK package: without a durable
- * authored root, it is not a resumable public runner. The seam is narrow: an
- * empty-header flow may await plain `f.run(...)` steps and must finish with
- * `f.done("success")`. Every run and
- * the terminal marker is a compiled deterministic spec submitted through
- * `JournalClient`; values are read back from `step.completed` journal entries.
- * Unsupported headers, verbs, gates, or completion lowering fail closed.
+ * Matches the `"path/glob: readonly"` / `"path/glob: readwrite"` shorthand
+ * shown in docs/SURFACE.md and the examples — the only shape a workspace
+ * string could plausibly declare a permission in. No parser anywhere in this
+ * package turns that annotation into a real restriction, so `lowerAgent`
+ * refuses rather than silently accepting and ignoring it.
  */
-export async function executeAuthoredFlow(handle, journal, input) {
-    const definition = getAuthoredFlowDefinition(handle);
+const WORKSPACE_PERMISSION_ANNOTATION = /:\s*(readonly|readwrite)\s*$/i;
+export async function executeAuthoredFlow(handle, journal, input, options = {}) {
+    const getDefinition = options.getDefinition ?? getAuthoredFlowDefinition;
+    const flowPath = options.flowPath ?? join(process.cwd(), 'flow.ts');
+    // Named separately from `options` because `lowerAgent` below has its own,
+    // differently-typed `options: AgentOptions` parameter that shadows this one.
+    const waitOptions = {
+        ...(options.signal !== undefined ? { signal: options.signal } : {}),
+        ...(options.onWait !== undefined ? { onWait: options.onWait } : {}),
+    };
+    const definition = getDefinition(handle);
     const headerFields = Object.keys(definition.header);
     if (headerFields.length > 0) {
         throw new AuthoredFlowExecutionError('unsupported_header', `flow "${definition.name}" uses unsupported header fields: ${headerFields.join(', ')}`);
@@ -37,6 +45,74 @@ export async function executeAuthoredFlow(handle, journal, input) {
         const outcome = await journal.runStart(spec);
         return readSuccessfulOutput(journal, outcome, id, journalSteps);
     };
+    // `name` (the first f.agent argument, e.g. "fixer") is not wired to the
+    // kernel's `agent` field: that field selects a NAMED declaration from
+    // `FlowSpec.agents`, and this executor refuses every non-empty header
+    // (see the top of this function) — an authored flow has no way to declare
+    // one today. `name` is kept only for step-id readability; CLI selection
+    // goes through the project's flows.json default below, same as it does
+    // for a bare `type: agent` YAML step with no explicit `cli`.
+    const lowerAgent = async (id, options) => {
+        if (options.workspace !== undefined && WORKSPACE_PERMISSION_ANNOTATION.test(options.workspace)) {
+            throw new AuthoredFlowExecutionError('unsupported_workspace_permission', `flow "${definition.name}" step "${id}": workspace "${options.workspace}" declares a `
+                + 'permission annotation ("...: readonly" / "...: readwrite"), but nothing enforces it — '
+                + 'no parser anywhere in this package turns that annotation into a real restriction '
+                + '(kernel/DAEMON-LIFECYCLE.md\'s permission model is untouched by f.agent). '
+                + 'Silently accepting and ignoring it would let a flow believe a restriction is in effect '
+                + "when it is not. Declare a bare surface name (no trailing \": readonly\"/\": readwrite\") "
+                + 'if you do not need enforcement, or use the declarative spec\'s `permissions` field, which is real.');
+        }
+        const authoring = {
+            version: SPEC_SCHEMA_VERSION,
+            name: `${definition.name}/${id}`,
+            steps: [{
+                    id,
+                    type: 'agent',
+                    instruction: options.task,
+                    ...(options.workspace === undefined ? {} : {
+                        surfaces: { workspace: [{ surface: options.workspace }] },
+                    }),
+                }],
+        };
+        // The kernel never resolves a `cli` on its own — every declarative
+        // `flows run`/`flows check` binds it first via this exact function
+        // (cli/check.ts), searching for the nearest flows.json from `flowPath`
+        // and real-probing auth/model readiness. An authored agent step gets
+        // nothing for free just because it was declared in TS instead of YAML.
+        const { report, flow: resolved } = checkAuthoredFlow(authoring, flowPath);
+        if (!report.ok || resolved === undefined) {
+            const refusal = report.diagnostics.find((diagnostic) => diagnostic.severity === 'refusal');
+            throw new AuthoredFlowExecutionError('agent_cli_unresolved', refusal?.message
+                ?? `flow "${definition.name}" step "${id}": no CLI could be resolved for f.agent `
+                    + `(searched for flows.json from "${flowPath}")`);
+        }
+        const spec = toKernelSpec(resolved);
+        const outcome = await journal.runStart(spec);
+        // Reuse the declarative CLI's own wait/classification (cli/run.ts) rather
+        // than a hand-rolled poll: `step.completed` and the run's own terminal
+        // state are appended as two SEPARATE actions (kernel/relayflowd-core/src/machine.rs
+        // completion_actions vs complete_run_actions), so a naive read right
+        // after runStart can race a real, valid completion — and a genuinely
+        // long-running agent has no reason to be bounded by anything other than
+        // its own worker's lease, which classifyOutcome already follows
+        // (renewing as the lease renews, per docs/SURFACE.md §5's WAITING
+        // [worker_lease] contract), never an unrelated fixed deadline.
+        const execution = await classifyOutcome(journal, 'run', outcome, report, '', waitOptions);
+        if (execution.exitCode === 3) {
+            const parked = execution.report.parkedStep;
+            throw new AuthoredFlowExecutionError('agent_parked', execution.report.diagnostics.at(-1)?.message
+                ?? `flow "${definition.name}" step "${id}" parked`
+                    + (parked !== undefined ? ` (${parked.type})` : '')
+                    + ': no worker is attached to run it.', undefined, outcome.run_id);
+        }
+        if (execution.exitCode !== 0) {
+            const reason = execution.report.completionReason;
+            throw new AuthoredFlowExecutionError('step_failed', execution.report.diagnostics.at(-1)?.message
+                ?? `flow "${definition.name}" step "${id}" did not complete successfully `
+                    + `(status: ${execution.report.status ?? 'unknown'})`, isSurfaceCompletionReason(reason) ? reason : undefined, outcome.run_id);
+        }
+        return readSuccessfulAgentOutput(journal, outcome.run_id, id, journalSteps);
+    };
     const context = {
         run(command) {
             assertOperationAllowed('run', definition.name, requestedCompletion);
@@ -48,10 +124,11 @@ export async function executeAuthoredFlow(handle, journal, input) {
             const id = `llm-${nextStep++}`;
             return trackStep(authoredSteps, unsupportedStep(id, 'llm', () => assertOperationAllowed('llm', definition.name, requestedCompletion), lifecycle));
         },
-        agent() {
+        agent(name, options) {
             assertOperationAllowed('agent', definition.name, requestedCompletion);
+            void name; // step-id readability only — see the comment on lowerAgent.
             const id = `agent-${nextStep++}`;
-            return trackStep(authoredSteps, unsupportedStep(id, 'agent', () => assertOperationAllowed('agent', definition.name, requestedCompletion), lifecycle));
+            return trackStep(authoredSteps, new AuthoredFlowOperation(id, 'agent', () => assertOperationAllowed('agent', definition.name, requestedCompletion), () => lowerAgent(id, options), lifecycle));
         },
         human() {
             assertOperationAllowed('human', definition.name, requestedCompletion);
@@ -157,26 +234,66 @@ function unsupportedCloud(assertOpen) {
         },
     });
 }
-async function readSuccessfulOutput(journal, outcome, stepId, journalSteps) {
-    const entries = (await journal.journalRead(outcome.run_id, 1)).entries;
+/**
+ * Shared by every `f.*` verb that lowers to one kernel step run in isolation:
+ * find its `step.completed` entry, record it, and refuse anything but a
+ * clean success before handing the raw `output` back for verb-specific
+ * extraction (a plain string for `f.run`, an `AgentResult` for `f.agent`).
+ *
+ * Callers are responsible for having already established that the RUN
+ * reached a terminal, successful state before calling this — `f.run`'s
+ * caller relies on `runStart`'s own immediate response (the kernel drives a
+ * deterministic step to completion inline, no race); `f.agent`'s caller
+ * relies on `classifyOutcome` (cli/run.ts) having already polled to a true
+ * terminal state. Given that, a single read from the start of this run's
+ * (small, single-step) journal is enough — no polling here, and no run
+ * outcome ever needs re-checking.
+ */
+async function readCompletedStepOutput(journal, runId, stepId, journalSteps) {
+    const entries = (await journal.journalRead(runId, 1)).entries;
     const completed = entries.find((entry) => isStepCompleted(entry, stepId));
     if (!isStepCompleted(completed, stepId)) {
-        throw protocolViolation(outcome.run_id, `journal has no step.completed for "${stepId}"`);
+        throw protocolViolation(runId, `journal has no step.completed for "${stepId}"`);
     }
     const reason = completed.payload.completionReason;
-    journalSteps.push(Object.freeze({ id: stepId, runId: outcome.run_id, completionReason: reason }));
+    journalSteps.push(Object.freeze({ id: stepId, runId, completionReason: reason }));
     if (reason !== 'success') {
-        throw new AuthoredFlowExecutionError('step_failed', `journal step "${stepId}" completed with ${reason}`, reason, outcome.run_id);
+        throw new AuthoredFlowExecutionError('step_failed', `journal step "${stepId}" completed with ${reason}`, reason, runId);
     }
-    if (outcome.status !== 'completed' || outcome.completion_reason !== 'success') {
-        throw protocolViolation(outcome.run_id, `successful step entry conflicts with run outcome ${outcome.status}/${String(outcome.completion_reason)}`);
-    }
-    const output = completed.payload.output;
+    return completed.payload.output;
+}
+async function readSuccessfulOutput(journal, outcome, stepId, journalSteps) {
+    const output = await readCompletedStepOutput(journal, outcome.run_id, stepId, journalSteps);
     if (!isRecord(output) || typeof output['stdout_tail'] !== 'string') {
         throw protocolViolation(outcome.run_id, `step "${stepId}" has no string stdout_tail`);
     }
     return output['stdout_tail'];
 }
+/**
+ * The kernel journals an agent step's raw `CliResult` shape
+ * (`exit_code`/`stdout_tail`/`stderr_tail`) — same as a deterministic step —
+ * UNLESS the CLI's stdout parsed as JSON, in which case `output` is that
+ * parsed object directly (worker.ts: `parseJsonOutput(result.stdout_tail) ??
+ * result`). Neither shape carries a real `artifacts` list today: nothing in
+ * the kernel or worker enumerates files an agent wrote, and `f.agent`'s
+ * `AgentOptions` has no `output` schema parameter for a CLI to target either
+ * (unlike the declarative `AgentStepSpec.output` field). `artifacts` is
+ * therefore always empty here — honest about what data exists, not a
+ * placeholder for something not yet wired.
+ */
+async function readSuccessfulAgentOutput(journal, runId, stepId, journalSteps) {
+    const output = await readCompletedStepOutput(journal, runId, stepId, journalSteps);
+    if (!isRecord(output)) {
+        throw protocolViolation(runId, `step "${stepId}" produced a non-object output`);
+    }
+    if (typeof output['stdout_tail'] === 'string') {
+        return { summary: output['stdout_tail'], artifacts: [] };
+    }
+    // The CLI's stdout parsed as JSON, so `output` is that value, not a
+    // CliResult. Fall back to a stable, inspectable summary rather than
+    // refusing a run whose agent step genuinely succeeded.
+    return { summary: JSON.stringify(output), artifacts: [] };
+}
 function isStepCompleted(value, stepId) {
     if (!isRecord(value) || value['entry_type'] !== 'step.completed' || value['step_id'] !== stepId) {
         return false;

package/dist/authored-flow-executor.js.map

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

package/dist/authored-flow-loader.d.ts

@@ -1,7 +1,21 @@
-import { type FlowHandle } from './authored-flow.js';
+import { getAuthoredFlowDefinition, type AuthoredFlowDefinition, type FlowHandle } from './authored-flow.js';
 export declare class AuthoredFlowLoadError extends Error {
     constructor(message: string);
 }
+/** Same signature as `getAuthoredFlowDefinition`, resolved from wherever a flow was loaded. */
+export type GetFlowDefinition = <Input = unknown>(handle: FlowHandle) => AuthoredFlowDefinition<Input>;
+export interface LoadedAuthoredFlow {
+    readonly handle: FlowHandle;
+    /**
+     * Bound to the SAME `@relayflows/surface` module instance the flow file
+     * itself imported `flow` from — see the comment on
+     * {@link resolveGetFlowDefinition}. Callers that go on to execute the flow
+     * (not just validate it) must keep using this, not the SDK's own static
+     * `getAuthoredFlowDefinition` import.
+     */
+    readonly getDefinition: GetFlowDefinition;
+}
 /** Import and validate a direct-run module without executing its authored body. */
-export declare function loadAuthoredFlow(path: string): Promise<FlowHandle>;
+export declare function loadAuthoredFlow(path: string): Promise<LoadedAuthoredFlow>;
+export { getAuthoredFlowDefinition };
 //# sourceMappingURL=authored-flow-loader.d.ts.map

package/dist/authored-flow-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authored-flow-loader.d.ts","sourceRoot":"","sources":["../src/authored-flow-loader.ts"],"names":[],"mappings":"AAGA,OAAO,EAA6B,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhF,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED,mFAAmF;AACnF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CA0BxE"}
+{"version":3,"file":"authored-flow-loader.d.ts","sourceRoot":"","sources":["../src/authored-flow-loader.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,yBAAyB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAE5B,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED,+FAA+F;AAC/F,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,EAAE,UAAU,KAAK,sBAAsB,CAAC,KAAK,CAAC,CAAC;AAEvG,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;CAC3C;AAED,mFAAmF;AACnF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA2BhF;AAoDD,OAAO,EAAE,yBAAyB,EAAE,CAAC"}

package/dist/authored-flow-loader.js

@@ -1,7 +1,8 @@
 import { accessSync, constants } from 'node:fs';
+import { createRequire } from 'node:module';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { getAuthoredFlowDefinition } from './authored-flow.js';
+import { getAuthoredFlowDefinition, } from './authored-flow.js';
 export class AuthoredFlowLoadError extends Error {
     constructor(message) {
         super(message);
@@ -24,15 +25,58 @@ export async function loadAuthoredFlow(path) {
     catch (error) {
         throw new AuthoredFlowLoadError(`Flow "${path}" could not be imported: ${errorMessage(error)}`);
     }
+    const getDefinition = await resolveGetFlowDefinition(absolutePath, path);
     const handle = authoredModule['default'];
     try {
-        getAuthoredFlowDefinition(handle);
+        getDefinition(handle);
     }
     catch (error) {
         throw new AuthoredFlowLoadError(`Flow "${path}" must default-export flow(...): ${errorMessage(error)}`);
     }
-    return handle;
+    return { handle, getDefinition };
 }
+/**
+ * `getFlowDefinition` recognizes a handle by object identity in a `WeakMap`
+ * scoped to whichever copy of `@relayflows/surface` created it — deliberately:
+ * that is what makes a handle unforgeable (surface/tests/flow.test.ts
+ * "refuses malformed and forged handles at the runtime boundary" locks this
+ * in, including against a well-known-symbol forgery, so this must not be
+ * "fixed" by switching that map to a symbol-tagged property instead).
+ *
+ * An author's `.flow.ts` almost never lives inside this monorepo. It
+ * resolves `@relayflows/surface` from ITS OWN `node_modules` — a physically
+ * different module instance than the one this SDK package statically
+ * imports for itself, so the SDK's own copy's `WeakMap` never has the
+ * entry the flow file's copy wrote. The fix is not a new identity
+ * mechanism; it is asking the SAME question Node itself would ask: resolve
+ * `@relayflows/surface/runtime` from the flow file's own location, exactly
+ * as the flow file's `import { flow } from "@relayflows/surface"`
+ * already did, and use THAT copy's `getFlowDefinition`. Since the flow
+ * module already imported successfully (by the time this runs), a
+ * compatible `@relayflows/surface` is provably resolvable from this same
+ * anchor.
+ */
+async function resolveGetFlowDefinition(absolutePath, displayPath) {
+    const require = createRequire(pathToFileURL(absolutePath));
+    let resolvedRuntimePath;
+    try {
+        resolvedRuntimePath = require.resolve('@relayflows/surface/runtime');
+    }
+    catch (error) {
+        throw new AuthoredFlowLoadError(`Flow "${displayPath}" imports @relayflows/surface, but @relayflows/surface/runtime `
+            + `could not be resolved from the same location: ${errorMessage(error)}`);
+    }
+    const runtimeModule = await import(pathToFileURL(resolvedRuntimePath).href);
+    if (typeof runtimeModule.getFlowDefinition !== 'function') {
+        throw new AuthoredFlowLoadError(`Flow "${displayPath}": the @relayflows/surface/runtime resolved from its location `
+            + 'does not export getFlowDefinition — check its @relayflows/surface version.');
+    }
+    return runtimeModule.getFlowDefinition;
+}
+// Exported for callers (internal SDK tests, and any co-located flow that is
+// provably the same `@relayflows/surface` instance as this package) that
+// have no need to resolve a separate copy.
+export { getAuthoredFlowDefinition };
 function errorMessage(error) {
     return error instanceof Error ? error.message : 'unknown authored-flow error';
 }

package/dist/authored-flow-loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"authored-flow-loader.js","sourceRoot":"","sources":["../src/authored-flow-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,yBAAyB,EAAmB,MAAM,oBAAoB,CAAC;AAEhF,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,mFAAmF;AACnF,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAY;IACjD,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC;QACH,UAAU,CAAC,YAAY,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,qBAAqB,CAAC,SAAS,IAAI,oBAAoB,CAAC,CAAC;IACrE,CAAC;IAED,IAAI,cAAuC,CAAC;IAC5C,IAAI,CAAC;QACH,cAAc,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,IAAI,CAA4B,CAAC;IAC7F,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,qBAAqB,CAC7B,SAAS,IAAI,4BAA4B,YAAY,CAAC,KAAK,CAAC,EAAE,CAC/D,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,cAAc,CAAC,SAAS,CAAe,CAAC;IACvD,IAAI,CAAC;QACH,yBAAyB,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,qBAAqB,CAC7B,SAAS,IAAI,oCAAoC,YAAY,CAAC,KAAK,CAAC,EAAE,CACvE,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,6BAA6B,CAAC;AAChF,CAAC"}
+{"version":3,"file":"authored-flow-loader.js","sourceRoot":"","sources":["../src/authored-flow-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EACL,yBAAyB,GAG1B,MAAM,oBAAoB,CAAC;AAE5B,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAiBD,mFAAmF;AACnF,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAY;IACjD,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC;QACH,UAAU,CAAC,YAAY,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,qBAAqB,CAAC,SAAS,IAAI,oBAAoB,CAAC,CAAC;IACrE,CAAC;IAED,IAAI,cAAuC,CAAC;IAC5C,IAAI,CAAC;QACH,cAAc,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,IAAI,CAA4B,CAAC;IAC7F,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,qBAAqB,CAC7B,SAAS,IAAI,4BAA4B,YAAY,CAAC,KAAK,CAAC,EAAE,CAC/D,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,MAAM,wBAAwB,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACzE,MAAM,MAAM,GAAG,cAAc,CAAC,SAAS,CAAe,CAAC;IACvD,IAAI,CAAC;QACH,aAAa,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,qBAAqB,CAC7B,SAAS,IAAI,oCAAoC,YAAY,CAAC,KAAK,CAAC,EAAE,CACvE,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,KAAK,UAAU,wBAAwB,CACrC,YAAoB,EACpB,WAAmB;IAEnB,MAAM,OAAO,GAAG,aAAa,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC;IAC3D,IAAI,mBAA2B,CAAC;IAChC,IAAI,CAAC;QACH,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,6BAA6B,CAAC,CAAC;IACvE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,qBAAqB,CAC7B,SAAS,WAAW,iEAAiE;cACjF,iDAAiD,YAAY,CAAC,KAAK,CAAC,EAAE,CAC3E,CAAC;IACJ,CAAC;IACD,MAAM,aAAa,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,mBAAmB,CAAC,CAAC,IAAI,CAEzE,CAAC;IACF,IAAI,OAAO,aAAa,CAAC,iBAAiB,KAAK,UAAU,EAAE,CAAC;QAC1D,MAAM,IAAI,qBAAqB,CAC7B,SAAS,WAAW,gEAAgE;cAChF,4EAA4E,CACjF,CAAC;IACJ,CAAC;IACD,OAAO,aAAa,CAAC,iBAAsC,CAAC;AAC9D,CAAC;AAED,4EAA4E;AAC5E,yEAAyE;AACzE,2CAA2C;AAC3C,OAAO,EAAE,yBAAyB,EAAE,CAAC;AAErC,SAAS,YAAY,CAAC,KAAc;IAClC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,6BAA6B,CAAC;AAChF,CAAC"}

package/dist/cli/direct-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"direct-run.d.ts","sourceRoot":"","sources":["../../src/cli/direct-run.ts"],"names":[],"mappings":"AAQA,OAAO,EAML,KAAK,YAAY,EACjB,KAAK,mBAAmB,EAEzB,MAAM,UAAU,CAAC;AAElB,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,YAAY,CAAC,CA6DvB"}
+{"version":3,"file":"direct-run.d.ts","sourceRoot":"","sources":["../../src/cli/direct-run.ts"],"names":[],"mappings":"AAQA,OAAO,EAML,KAAK,YAAY,EACjB,KAAK,mBAAmB,EAEzB,MAAM,UAAU,CAAC;AAElB,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,YAAY,CAAC,CAgGvB"}

package/dist/cli/direct-run.js

@@ -26,8 +26,13 @@ export async function runDirectFlow(path, inputArgument, dataDir, options = {})
     if (connected !== undefined)
         return connected;
     try {
-        const handle = await loadAuthoredFlow(path);
-        const result = await executeAuthoredFlow(handle, client, input);
+        const { handle, getDefinition } = await loadAuthoredFlow(path);
+        const result = await executeAuthoredFlow(handle, client, input, {
+            getDefinition,
+            flowPath: path,
+            ...(options.signal !== undefined ? { signal: options.signal } : {}),
+            ...(options.onWait !== undefined ? { onWait: options.onWait } : {}),
+        });
         const terminal = result.journalSteps.at(-1);
         if (terminal === undefined) {
             return protocolFailure('run', base, socketPath, new Error(`authored flow "${result.name}" completed without a journal step`));
@@ -46,8 +51,21 @@ export async function runDirectFlow(path, inputArgument, dataDir, options = {})
         };
     }
     catch (error) {
+        // `agent_cli_unresolved` and `unsupported_workspace_permission` are
+        // preflight-shaped refusals, not protocol failures — `flows check`
+        // returns exit 2 for the equivalent declarative-spec failures, and this
+        // path should match it. Known gap, not solved here: if a `f.run` before
+        // the failing `f.agent` already journaled real work, this still reports
+        // as a clean refusal — true upfront preflight would need to know every
+        // `f.agent` call an imperative TS body will make before running any of
+        // it, which isn't knowable without running the body (see the comment on
+        // ExecuteAuthoredFlowOptions and this project's own examples/README for
+        // the same limitation already documented elsewhere).
         if (error instanceof AuthoredFlowLoadError
-            || (error instanceof AuthoredFlowExecutionError && error.code === 'unsupported_header')) {
+            || (error instanceof AuthoredFlowExecutionError
+                && (error.code === 'unsupported_header'
+                    || error.code === 'agent_cli_unresolved'
+                    || error.code === 'unsupported_workspace_permission'))) {
             return {
                 exitCode: 2,
                 report: {
@@ -59,6 +77,23 @@ export async function runDirectFlow(path, inputArgument, dataDir, options = {})
                 },
             };
         }
+        if (error instanceof AuthoredFlowExecutionError && error.code === 'agent_parked') {
+            return {
+                exitCode: 3,
+                report: {
+                    ...base,
+                    ok: false,
+                    runId: error.runId,
+                    socketPath,
+                    status: 'parked',
+                    diagnostics: [...base.diagnostics, {
+                            severity: 'parked',
+                            kind: 'run_parked',
+                            message: error.message,
+                        }],
+                },
+            };
+        }
         const runId = error instanceof AuthoredFlowExecutionError ? error.runId : undefined;
         return protocolFailure('run', base, socketPath, error, runId);
     }

package/dist/cli/direct-run.js.map

@@ -1 +1 @@
-{"version":3,"file":"direct-run.js","sourceRoot":"","sources":["../../src/cli/direct-run.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"direct-run.js","sourceRoot":"","sources":["../../src/cli/direct-run.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACrF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EACL,OAAO,EACP,WAAW,EACX,eAAe,EACf,eAAe,EACf,SAAS,GAIV,MAAM,UAAU,CAAC;AAElB,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAY,EACZ,aAAiC,EACjC,OAAe,EACf,UAA+B,EAAE;IAEjC,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QACH,KAAK,GAAG,gBAAgB,CAAC,aAAa,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,gBAAgB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;YAC1D,IAAI,EAAE,eAAwB;YAC9B,OAAO,EAAE,mCAAmC;SAC7C,CAAC;QACF,OAAO;YACL,QAAQ,EAAE,CAAC;YACX,MAAM,EAAE,eAAe,CAAC,KAAK,EAAE,kBAAkB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;SAClE,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,IAAI,GAAc,EAAE,GAAG,WAAW,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACxD,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,UAAU,CAAC,CAAC;IAC7C,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACvE,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAE9C,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAC/D,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE;YAC9D,aAAa;YACb,QAAQ,EAAE,IAAI;YACd,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnE,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpE,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,KAAK,CACvD,kBAAkB,MAAM,CAAC,IAAI,oCAAoC,CAClE,CAAC,CAAC;QACL,CAAC;QACD,OAAO;YACL,QAAQ,EAAE,CAAC;YACX,MAAM,EAAE;gBACN,GAAG,IAAI;gBACP,EAAE,EAAE,IAAI;gBACR,KAAK,EAAE,QAAQ,CAAC,KAAK;gBACrB,UAAU;gBACV,MAAM,EAAE,WAAW;gBACnB,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;gBACzC,cAAc,EAAE,MAAM,CAAC,YAAY,CAAC,MAAM;aAC3C;SACF,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,oEAAoE;QACpE,mEAAmE;QACnE,wEAAwE;QACxE,wEAAwE;QACxE,wEAAwE;QACxE,uEAAuE;QACvE,uEAAuE;QACvE,wEAAwE;QACxE,wEAAwE;QACxE,qDAAqD;QACrD,IAAI,KAAK,YAAY,qBAAqB;eACrC,CAAC,KAAK,YAAY,0BAA0B;mBAC1C,CAAC,KAAK,CAAC,IAAI,KAAK,oBAAoB;uBAClC,KAAK,CAAC,IAAI,KAAK,sBAAsB;uBACrC,KAAK,CAAC,IAAI,KAAK,kCAAkC,CAAC,CAAC,EAAE,CAAC;YAC7D,OAAO;gBACL,QAAQ,EAAE,CAAC;gBACX,MAAM,EAAE;oBACN,GAAG,eAAe,CAAC,KAAK,EAAE,kBAAkB,CAAC;wBAC3C,IAAI,EAAE,cAAc;wBACpB,OAAO,EAAE,KAAK,CAAC,OAAO;qBACvB,EAAE,IAAI,CAAC,CAAC;oBACT,UAAU;iBACX;aACF,CAAC;QACJ,CAAC;QACD,IAAI,KAAK,YAAY,0BAA0B,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YACjF,OAAO;gBACL,QAAQ,EAAE,CAAC;gBACX,MAAM,EAAE;oBACN,GAAG,IAAI;oBACP,EAAE,EAAE,KAAK;oBACT,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,UAAU;oBACV,MAAM,EAAE,QAAQ;oBAChB,WAAW,EAAE,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE;4BACjC,QAAQ,EAAE,QAAQ;4BAClB,IAAI,EAAE,YAAY;4BAClB,OAAO,EAAE,KAAK,CAAC,OAAO;yBACvB,CAAC;iBACH;aACF,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,GAAG,KAAK,YAAY,0BAA0B,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QACpF,OAAO,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IAChE,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,KAAK,EAAE,CAAC;IACjB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayflows/sdk",
-  "version": "2.0.6",
+  "version": "2.0.8",
   "description": "TypeScript-first authoring SDK for Relayflows. Compiles specs; speaks the journal protocol.",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,7 +30,7 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
-    "@relayflows/surface": "2.0.6",
+    "@relayflows/surface": "2.0.8",
     "@types/js-yaml": "^4.0.9",
     "ajv": "^8.17.1",
     "ajv-draft-04": "^1.0.0",

package/src/authored-flow-error.ts

@@ -4,6 +4,8 @@ import type {
 } from './protocol.js';
 
 export type AuthoredFlowExecutionErrorCode =
+  | 'agent_cli_unresolved'
+  | 'agent_parked'
   | 'duplicate_completion'
   | 'journal_protocol_violation'
   | 'missing_completion'
@@ -15,6 +17,7 @@ export type AuthoredFlowExecutionErrorCode =
   | 'unsupported_header'
   | 'unsettled_derived_work'
   | 'unsupported_promise_lifecycle'
+  | 'unsupported_workspace_permission'
   | 'unawaited_step'
   | 'unsupported_verb';
 

package/src/authored-flow-executor.ts

@@ -1,6 +1,7 @@
 import {
   COMPLETION_REASONS,
   RUN_COMPLETION_REASONS,
+  type AgentOptions,
   type AgentResult,
   type CloudHelper,
   type CompletionReason as SurfaceCompletionReason,
@@ -9,8 +10,13 @@ import {
   type Step,
 } from '@relayflows/surface';
 import type { FlowHandle } from '@relayflows/surface/runtime';
+import { join } from 'node:path';
 import { compileSpec, toKernelSpec } from './compile.js';
 import { getAuthoredFlowDefinition } from './authored-flow.js';
+import type { GetFlowDefinition } from './authored-flow-loader.js';
+import { checkAuthoredFlow } from './cli/check.js';
+import { classifyOutcome, type RunLifecycleOptions } from './cli/run.js';
+import type { PreflightDiagnostic } from './preflight.js';
 import {
   AuthoredFlowExecutionError,
   type AuthoredFlowExecutionErrorCode,
@@ -27,7 +33,7 @@ import type {
   RunCompletionReason as ProtocolRunCompletionReason,
   RunOutcome,
 } from './protocol.js';
-import { SPEC_SCHEMA_VERSION } from './spec.js';
+import { SPEC_SCHEMA_VERSION, type FlowSpec } from './spec.js';
 
 type Assert<T extends true> = T;
 type Equal<A, B> = [A] extends [B]
@@ -49,6 +55,15 @@ type EveryRunCompletionReasonIsAcceptedByDone = Assert<
 
 export { AuthoredFlowExecutionError, type AuthoredFlowExecutionErrorCode };
 
+/**
+ * Matches the `"path/glob: readonly"` / `"path/glob: readwrite"` shorthand
+ * shown in docs/SURFACE.md and the examples — the only shape a workspace
+ * string could plausibly declare a permission in. No parser anywhere in this
+ * package turns that annotation into a real restriction, so `lowerAgent`
+ * refuses rather than silently accepting and ignoring it.
+ */
+const WORKSPACE_PERMISSION_ANNOTATION = /:\s*(readonly|readwrite)\s*$/i;
+
 export interface AuthoredFlowJournalStep {
   readonly id: string;
   readonly runId: string;
@@ -79,12 +94,46 @@ type JournalStepUsesStepCompletionReason = Assert<
  * `JournalClient`; values are read back from `step.completed` journal entries.
  * Unsupported headers, verbs, gates, or completion lowering fail closed.
  */
+export interface ExecuteAuthoredFlowOptions {
+  /**
+   * Defaults to this package's own static import — correct for every
+   * existing (internal, single-instance) caller. A flow loaded from an
+   * external path via `loadAuthoredFlow` must pass ITS resolved
+   * `getDefinition` instead; see authored-flow-loader.ts's comment on why.
+   */
+  readonly getDefinition?: GetFlowDefinition;
+  /**
+   * The flow file's own path — passed straight to `checkAuthoredFlow`
+   * (cli/check.ts) so `f.agent` resolves a CLI the same way a declarative
+   * `type: agent` step does: nearest `flows.json`, real auth/model probing,
+   * canonicalized path. `checkAuthoredFlow` always does `dirname()` on this,
+   * matching `checkFlow`'s real `flows check <file>` contract — pass a FILE
+   * path, not a directory, or the search starts one level too high. Defaults
+   * to a synthetic `flow.ts` under `process.cwd()` for exactly this reason:
+   * `process.cwd()` itself is a directory, and `dirname(process.cwd())`
+   * would search cwd's PARENT.
+   */
+  readonly flowPath?: string;
+  /** Passed straight through to classifyOutcome (cli/run.ts) for f.agent's wait. */
+  readonly signal?: RunLifecycleOptions['signal'];
+  readonly onWait?: RunLifecycleOptions['onWait'];
+}
+
 export async function executeAuthoredFlow<Input = undefined>(
   handle: FlowHandle,
   journal: JournalClient,
   input?: Input,
+  options: ExecuteAuthoredFlowOptions = {},
 ): Promise<AuthoredFlowExecutionResult> {
-  const definition = getAuthoredFlowDefinition<Input>(handle);
+  const getDefinition = options.getDefinition ?? getAuthoredFlowDefinition;
+  const flowPath = options.flowPath ?? join(process.cwd(), 'flow.ts');
+  // Named separately from `options` because `lowerAgent` below has its own,
+  // differently-typed `options: AgentOptions` parameter that shadows this one.
+  const waitOptions: RunLifecycleOptions = {
+    ...(options.signal !== undefined ? { signal: options.signal } : {}),
+    ...(options.onWait !== undefined ? { onWait: options.onWait } : {}),
+  };
+  const definition = getDefinition<Input>(handle);
   const headerFields = Object.keys(definition.header);
   if (headerFields.length > 0) {
     throw new AuthoredFlowExecutionError(
@@ -112,6 +161,97 @@ export async function executeAuthoredFlow<Input = undefined>(
     return readSuccessfulOutput(journal, outcome, id, journalSteps);
   };
 
+  // `name` (the first f.agent argument, e.g. "fixer") is not wired to the
+  // kernel's `agent` field: that field selects a NAMED declaration from
+  // `FlowSpec.agents`, and this executor refuses every non-empty header
+  // (see the top of this function) — an authored flow has no way to declare
+  // one today. `name` is kept only for step-id readability; CLI selection
+  // goes through the project's flows.json default below, same as it does
+  // for a bare `type: agent` YAML step with no explicit `cli`.
+  const lowerAgent = async (
+    id: string,
+    options: AgentOptions,
+  ): Promise<AgentResult> => {
+    if (options.workspace !== undefined && WORKSPACE_PERMISSION_ANNOTATION.test(options.workspace)) {
+      throw new AuthoredFlowExecutionError(
+        'unsupported_workspace_permission',
+        `flow "${definition.name}" step "${id}": workspace "${options.workspace}" declares a `
+          + 'permission annotation ("...: readonly" / "...: readwrite"), but nothing enforces it — '
+          + 'no parser anywhere in this package turns that annotation into a real restriction '
+          + '(kernel/DAEMON-LIFECYCLE.md\'s permission model is untouched by f.agent). '
+          + 'Silently accepting and ignoring it would let a flow believe a restriction is in effect '
+          + "when it is not. Declare a bare surface name (no trailing \": readonly\"/\": readwrite\") "
+          + 'if you do not need enforcement, or use the declarative spec\'s `permissions` field, which is real.',
+      );
+    }
+    const authoring: FlowSpec = {
+      version: SPEC_SCHEMA_VERSION,
+      name: `${definition.name}/${id}`,
+      steps: [{
+        id,
+        type: 'agent',
+        instruction: options.task,
+        ...(options.workspace === undefined ? {} : {
+          surfaces: { workspace: [{ surface: options.workspace }] },
+        }),
+      }],
+    };
+    // The kernel never resolves a `cli` on its own — every declarative
+    // `flows run`/`flows check` binds it first via this exact function
+    // (cli/check.ts), searching for the nearest flows.json from `flowPath`
+    // and real-probing auth/model readiness. An authored agent step gets
+    // nothing for free just because it was declared in TS instead of YAML.
+    const { report, flow: resolved } = checkAuthoredFlow(authoring, flowPath);
+    if (!report.ok || resolved === undefined) {
+      const refusal = report.diagnostics.find(
+        (diagnostic): diagnostic is PreflightDiagnostic & { severity: 'refusal' } =>
+          diagnostic.severity === 'refusal',
+      );
+      throw new AuthoredFlowExecutionError(
+        'agent_cli_unresolved',
+        refusal?.message
+          ?? `flow "${definition.name}" step "${id}": no CLI could be resolved for f.agent `
+            + `(searched for flows.json from "${flowPath}")`,
+      );
+    }
+    const spec = toKernelSpec(resolved);
+    const outcome = await journal.runStart(spec);
+    // Reuse the declarative CLI's own wait/classification (cli/run.ts) rather
+    // than a hand-rolled poll: `step.completed` and the run's own terminal
+    // state are appended as two SEPARATE actions (kernel/relayflowd-core/src/machine.rs
+    // completion_actions vs complete_run_actions), so a naive read right
+    // after runStart can race a real, valid completion — and a genuinely
+    // long-running agent has no reason to be bounded by anything other than
+    // its own worker's lease, which classifyOutcome already follows
+    // (renewing as the lease renews, per docs/SURFACE.md §5's WAITING
+    // [worker_lease] contract), never an unrelated fixed deadline.
+    const execution = await classifyOutcome(journal, 'run', outcome, report, '', waitOptions);
+    if (execution.exitCode === 3) {
+      const parked = execution.report.parkedStep;
+      throw new AuthoredFlowExecutionError(
+        'agent_parked',
+        execution.report.diagnostics.at(-1)?.message
+          ?? `flow "${definition.name}" step "${id}" parked`
+            + (parked !== undefined ? ` (${parked.type})` : '')
+            + ': no worker is attached to run it.',
+        undefined,
+        outcome.run_id,
+      );
+    }
+    if (execution.exitCode !== 0) {
+      const reason = execution.report.completionReason;
+      throw new AuthoredFlowExecutionError(
+        'step_failed',
+        execution.report.diagnostics.at(-1)?.message
+          ?? `flow "${definition.name}" step "${id}" did not complete successfully `
+            + `(status: ${execution.report.status ?? 'unknown'})`,
+        isSurfaceCompletionReason(reason) ? reason : undefined,
+        outcome.run_id,
+      );
+    }
+    return readSuccessfulAgentOutput(journal, outcome.run_id, id, journalSteps);
+  };
+
   const context: Ctx = {
     run(command) {
       assertOperationAllowed('run', definition.name, requestedCompletion);
@@ -134,13 +274,15 @@ export async function executeAuthoredFlow<Input = undefined>(
         lifecycle,
       ));
     },
-    agent() {
+    agent(name, options) {
       assertOperationAllowed('agent', definition.name, requestedCompletion);
+      void name; // step-id readability only — see the comment on lowerAgent.
       const id = `agent-${nextStep++}`;
-      return trackStep(authoredSteps, unsupportedStep<AgentResult>(
+      return trackStep(authoredSteps, new AuthoredFlowOperation(
         id,
         'agent',
         () => assertOperationAllowed('agent', definition.name, requestedCompletion),
+        () => lowerAgent(id, options),
         lifecycle,
       ));
     },
@@ -286,42 +428,90 @@ function unsupportedCloud(assertOpen: () => void): CloudHelper {
   }) as CloudHelper;
 }
 
-async function readSuccessfulOutput(
+/**
+ * Shared by every `f.*` verb that lowers to one kernel step run in isolation:
+ * find its `step.completed` entry, record it, and refuse anything but a
+ * clean success before handing the raw `output` back for verb-specific
+ * extraction (a plain string for `f.run`, an `AgentResult` for `f.agent`).
+ *
+ * Callers are responsible for having already established that the RUN
+ * reached a terminal, successful state before calling this — `f.run`'s
+ * caller relies on `runStart`'s own immediate response (the kernel drives a
+ * deterministic step to completion inline, no race); `f.agent`'s caller
+ * relies on `classifyOutcome` (cli/run.ts) having already polled to a true
+ * terminal state. Given that, a single read from the start of this run's
+ * (small, single-step) journal is enough — no polling here, and no run
+ * outcome ever needs re-checking.
+ */
+async function readCompletedStepOutput(
   journal: JournalClient,
-  outcome: RunOutcome,
+  runId: string,
   stepId: string,
   journalSteps: AuthoredFlowJournalStep[],
-): Promise<string> {
-  const entries = (await journal.journalRead(outcome.run_id, 1)).entries;
+): Promise<unknown> {
+  const entries = (await journal.journalRead(runId, 1)).entries;
   const completed = entries.find((entry) => isStepCompleted(entry, stepId));
   if (!isStepCompleted(completed, stepId)) {
-    throw protocolViolation(outcome.run_id, `journal has no step.completed for "${stepId}"`);
+    throw protocolViolation(runId, `journal has no step.completed for "${stepId}"`);
   }
 
   const reason = completed.payload.completionReason;
-  journalSteps.push(Object.freeze({ id: stepId, runId: outcome.run_id, completionReason: reason }));
+  journalSteps.push(Object.freeze({ id: stepId, runId, completionReason: reason }));
   if (reason !== 'success') {
     throw new AuthoredFlowExecutionError(
       'step_failed',
       `journal step "${stepId}" completed with ${reason}`,
       reason,
-      outcome.run_id,
-    );
-  }
-  if (outcome.status !== 'completed' || outcome.completion_reason !== 'success') {
-    throw protocolViolation(
-      outcome.run_id,
-      `successful step entry conflicts with run outcome ${outcome.status}/${String(outcome.completion_reason)}`,
+      runId,
     );
   }
+  return completed.payload.output;
+}
 
-  const output = completed.payload.output;
+async function readSuccessfulOutput(
+  journal: JournalClient,
+  outcome: RunOutcome,
+  stepId: string,
+  journalSteps: AuthoredFlowJournalStep[],
+): Promise<string> {
+  const output = await readCompletedStepOutput(journal, outcome.run_id, stepId, journalSteps);
   if (!isRecord(output) || typeof output['stdout_tail'] !== 'string') {
     throw protocolViolation(outcome.run_id, `step "${stepId}" has no string stdout_tail`);
   }
   return output['stdout_tail'];
 }
 
+/**
+ * The kernel journals an agent step's raw `CliResult` shape
+ * (`exit_code`/`stdout_tail`/`stderr_tail`) — same as a deterministic step —
+ * UNLESS the CLI's stdout parsed as JSON, in which case `output` is that
+ * parsed object directly (worker.ts: `parseJsonOutput(result.stdout_tail) ??
+ * result`). Neither shape carries a real `artifacts` list today: nothing in
+ * the kernel or worker enumerates files an agent wrote, and `f.agent`'s
+ * `AgentOptions` has no `output` schema parameter for a CLI to target either
+ * (unlike the declarative `AgentStepSpec.output` field). `artifacts` is
+ * therefore always empty here — honest about what data exists, not a
+ * placeholder for something not yet wired.
+ */
+async function readSuccessfulAgentOutput(
+  journal: JournalClient,
+  runId: string,
+  stepId: string,
+  journalSteps: AuthoredFlowJournalStep[],
+): Promise<AgentResult> {
+  const output = await readCompletedStepOutput(journal, runId, stepId, journalSteps);
+  if (!isRecord(output)) {
+    throw protocolViolation(runId, `step "${stepId}" produced a non-object output`);
+  }
+  if (typeof output['stdout_tail'] === 'string') {
+    return { summary: output['stdout_tail'], artifacts: [] };
+  }
+  // The CLI's stdout parsed as JSON, so `output` is that value, not a
+  // CliResult. Fall back to a stable, inspectable summary rather than
+  // refusing a run whose agent step genuinely succeeded.
+  return { summary: JSON.stringify(output), artifacts: [] };
+}
+
 interface StepCompletedEntry {
   entry_type: 'step.completed';
   step_id: string;

package/src/authored-flow-loader.ts

@@ -1,7 +1,12 @@
 import { accessSync, constants } from 'node:fs';
+import { createRequire } from 'node:module';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { getAuthoredFlowDefinition, type FlowHandle } from './authored-flow.js';
+import {
+  getAuthoredFlowDefinition,
+  type AuthoredFlowDefinition,
+  type FlowHandle,
+} from './authored-flow.js';
 
 export class AuthoredFlowLoadError extends Error {
   constructor(message: string) {
@@ -10,8 +15,23 @@ export class AuthoredFlowLoadError extends Error {
   }
 }
 
+/** Same signature as `getAuthoredFlowDefinition`, resolved from wherever a flow was loaded. */
+export type GetFlowDefinition = <Input = unknown>(handle: FlowHandle) => AuthoredFlowDefinition<Input>;
+
+export interface LoadedAuthoredFlow {
+  readonly handle: FlowHandle;
+  /**
+   * Bound to the SAME `@relayflows/surface` module instance the flow file
+   * itself imported `flow` from — see the comment on
+   * {@link resolveGetFlowDefinition}. Callers that go on to execute the flow
+   * (not just validate it) must keep using this, not the SDK's own static
+   * `getAuthoredFlowDefinition` import.
+   */
+  readonly getDefinition: GetFlowDefinition;
+}
+
 /** Import and validate a direct-run module without executing its authored body. */
-export async function loadAuthoredFlow(path: string): Promise<FlowHandle> {
+export async function loadAuthoredFlow(path: string): Promise<LoadedAuthoredFlow> {
   const absolutePath = resolve(path);
   try {
     accessSync(absolutePath, constants.R_OK);
@@ -28,17 +48,70 @@ export async function loadAuthoredFlow(path: string): Promise<FlowHandle> {
     );
   }
 
+  const getDefinition = await resolveGetFlowDefinition(absolutePath, path);
   const handle = authoredModule['default'] as FlowHandle;
   try {
-    getAuthoredFlowDefinition(handle);
+    getDefinition(handle);
   } catch (error) {
     throw new AuthoredFlowLoadError(
       `Flow "${path}" must default-export flow(...): ${errorMessage(error)}`,
     );
   }
-  return handle;
+  return { handle, getDefinition };
+}
+
+/**
+ * `getFlowDefinition` recognizes a handle by object identity in a `WeakMap`
+ * scoped to whichever copy of `@relayflows/surface` created it — deliberately:
+ * that is what makes a handle unforgeable (surface/tests/flow.test.ts
+ * "refuses malformed and forged handles at the runtime boundary" locks this
+ * in, including against a well-known-symbol forgery, so this must not be
+ * "fixed" by switching that map to a symbol-tagged property instead).
+ *
+ * An author's `.flow.ts` almost never lives inside this monorepo. It
+ * resolves `@relayflows/surface` from ITS OWN `node_modules` — a physically
+ * different module instance than the one this SDK package statically
+ * imports for itself, so the SDK's own copy's `WeakMap` never has the
+ * entry the flow file's copy wrote. The fix is not a new identity
+ * mechanism; it is asking the SAME question Node itself would ask: resolve
+ * `@relayflows/surface/runtime` from the flow file's own location, exactly
+ * as the flow file's `import { flow } from "@relayflows/surface"`
+ * already did, and use THAT copy's `getFlowDefinition`. Since the flow
+ * module already imported successfully (by the time this runs), a
+ * compatible `@relayflows/surface` is provably resolvable from this same
+ * anchor.
+ */
+async function resolveGetFlowDefinition(
+  absolutePath: string,
+  displayPath: string,
+): Promise<GetFlowDefinition> {
+  const require = createRequire(pathToFileURL(absolutePath));
+  let resolvedRuntimePath: string;
+  try {
+    resolvedRuntimePath = require.resolve('@relayflows/surface/runtime');
+  } catch (error) {
+    throw new AuthoredFlowLoadError(
+      `Flow "${displayPath}" imports @relayflows/surface, but @relayflows/surface/runtime `
+        + `could not be resolved from the same location: ${errorMessage(error)}`,
+    );
+  }
+  const runtimeModule = await import(pathToFileURL(resolvedRuntimePath).href) as {
+    getFlowDefinition?: unknown;
+  };
+  if (typeof runtimeModule.getFlowDefinition !== 'function') {
+    throw new AuthoredFlowLoadError(
+      `Flow "${displayPath}": the @relayflows/surface/runtime resolved from its location `
+        + 'does not export getFlowDefinition — check its @relayflows/surface version.',
+    );
+  }
+  return runtimeModule.getFlowDefinition as GetFlowDefinition;
 }
 
+// Exported for callers (internal SDK tests, and any co-located flow that is
+// provably the same `@relayflows/surface` instance as this package) that
+// have no need to resolve a separate copy.
+export { getAuthoredFlowDefinition };
+
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : 'unknown authored-flow error';
 }

package/src/cli/direct-run.ts

@@ -44,8 +44,13 @@ export async function runDirectFlow(
   if (connected !== undefined) return connected;
 
   try {
-    const handle = await loadAuthoredFlow(path);
-    const result = await executeAuthoredFlow(handle, client, input);
+    const { handle, getDefinition } = await loadAuthoredFlow(path);
+    const result = await executeAuthoredFlow(handle, client, input, {
+      getDefinition,
+      flowPath: path,
+      ...(options.signal !== undefined ? { signal: options.signal } : {}),
+      ...(options.onWait !== undefined ? { onWait: options.onWait } : {}),
+    });
     const terminal = result.journalSteps.at(-1);
     if (terminal === undefined) {
       return protocolFailure('run', base, socketPath, new Error(
@@ -65,8 +70,21 @@ export async function runDirectFlow(
       },
     };
   } catch (error) {
+    // `agent_cli_unresolved` and `unsupported_workspace_permission` are
+    // preflight-shaped refusals, not protocol failures — `flows check`
+    // returns exit 2 for the equivalent declarative-spec failures, and this
+    // path should match it. Known gap, not solved here: if a `f.run` before
+    // the failing `f.agent` already journaled real work, this still reports
+    // as a clean refusal — true upfront preflight would need to know every
+    // `f.agent` call an imperative TS body will make before running any of
+    // it, which isn't knowable without running the body (see the comment on
+    // ExecuteAuthoredFlowOptions and this project's own examples/README for
+    // the same limitation already documented elsewhere).
     if (error instanceof AuthoredFlowLoadError
-      || (error instanceof AuthoredFlowExecutionError && error.code === 'unsupported_header')) {
+      || (error instanceof AuthoredFlowExecutionError
+        && (error.code === 'unsupported_header'
+          || error.code === 'agent_cli_unresolved'
+          || error.code === 'unsupported_workspace_permission'))) {
       return {
         exitCode: 2,
         report: {
@@ -78,6 +96,23 @@ export async function runDirectFlow(
         },
       };
     }
+    if (error instanceof AuthoredFlowExecutionError && error.code === 'agent_parked') {
+      return {
+        exitCode: 3,
+        report: {
+          ...base,
+          ok: false,
+          runId: error.runId,
+          socketPath,
+          status: 'parked',
+          diagnostics: [...base.diagnostics, {
+            severity: 'parked',
+            kind: 'run_parked',
+            message: error.message,
+          }],
+        },
+      };
+    }
     const runId = error instanceof AuthoredFlowExecutionError ? error.runId : undefined;
     return protocolFailure('run', base, socketPath, error, runId);
   } finally {