@relayflows/sdk 2.0.9 → 2.0.10

package/src/authored-flow-executor.ts

@@ -1,22 +1,34 @@
+import { pluginHelpers } from './plugin-loader.js';
+import { runPluginEffect } from './authored-plugin-effect.js';
+import { randomUUID } from 'node:crypto';
+import { dirname } from 'node:path';
+import { runHelperEffect } from './authored-helper-effect.js';
+import { checkSlackHelpers } from './slack-preflight.js';
+import { snapshotJsonValue } from './json-value.js';
+import type { SlackCall } from './slack-writeback.js';
+import { checkMcpHeader, McpPreflightError } from './cli/check-typescript.js';
+import { buildMcpProxy, runMcpEffect } from './authored-mcp.js';
+import { AuthoredBudget } from './authored-budget.js';
+import { assertMemoryReachable, authoredMemory, scriptMemoryScope } from './authored-memory.js';
+import { authoredDeterministicRunner, authoredWorkerRunner } from './authored-worker-step.js';
+import { isSurfaceRunCompletionReason } from './authored-step-output.js';
 import {
-  COMPLETION_REASONS,
-  RUN_COMPLETION_REASONS,
-  type AgentOptions,
   type AgentResult,
+  type LlmOptions,
   type CloudHelper,
   type CompletionReason as SurfaceCompletionReason,
   type Ctx,
+  type FlowCompletionReason,
   type RunCompletionReason as SurfaceRunCompletionReason,
   type Step,
 } from '@relayflows/surface';
-import type { FlowHandle } from '@relayflows/surface/runtime';
+import { createHelpers, helperProviders, type HelperCall, type FlowHandle } from '@relayflows/surface/runtime';
 import { join } from 'node:path';
-import { compileSpec, toKernelSpec } from './compile.js';
+import { observeStep, type ProgressEvent } from './progress.js';
+import { parseStepTimeout } 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 type { RunLifecycleOptions } from './cli/run.js';
 import {
   AuthoredFlowExecutionError,
   type AuthoredFlowExecutionErrorCode,
@@ -31,9 +43,7 @@ import { JournalClient } from './journal-client.js';
 import type {
   CompletionReason as ProtocolCompletionReason,
   RunCompletionReason as ProtocolRunCompletionReason,
-  RunOutcome,
 } from './protocol.js';
-import { SPEC_SCHEMA_VERSION, type FlowSpec } from './spec.js';
 
 type Assert<T extends true> = T;
 type Equal<A, B> = [A] extends [B]
@@ -46,8 +56,8 @@ type RunCompletionVocabularyMatchesProtocol = Assert<
   Equal<SurfaceRunCompletionReason, ProtocolRunCompletionReason>
 >;
 type DoneCompletionReason = Parameters<Ctx['done']>[0];
-type DoneAcceptsOnlyRunCompletionReasons = Assert<
-  DoneCompletionReason extends SurfaceRunCompletionReason ? true : false
+type DoneAcceptsOnlyFlowCompletionReasons = Assert<
+  Equal<DoneCompletionReason, FlowCompletionReason>
 >;
 type EveryRunCompletionReasonIsAcceptedByDone = Assert<
   SurfaceRunCompletionReason extends DoneCompletionReason ? true : false
@@ -55,15 +65,6 @@ 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;
@@ -72,12 +73,12 @@ export interface AuthoredFlowJournalStep {
 
 export interface AuthoredFlowExecutionResult {
   readonly name: string;
-  readonly completionReason: ProtocolRunCompletionReason;
+  readonly completionReason: FlowCompletionReason;
   readonly journalSteps: readonly AuthoredFlowJournalStep[];
 }
 
-type ExecutionResultUsesRunCompletionReason = Assert<
-  Equal<AuthoredFlowExecutionResult['completionReason'], ProtocolRunCompletionReason>
+type ExecutionResultUsesFlowCompletionReason = Assert<
+  Equal<AuthoredFlowExecutionResult['completionReason'], FlowCompletionReason>
 >;
 type JournalStepUsesStepCompletionReason = Assert<
   Equal<AuthoredFlowJournalStep['completionReason'], ProtocolCompletionReason>
@@ -88,9 +89,9 @@ type JournalStepUsesStepCompletionReason = Assert<
  *
  * 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
+ * flow with an optional budget may await `f.run`, `f.llm`, and `f.agent` steps and must
+ * finish with `f.done("success")` or `f.done("needs_human")`. Each step and the terminal marker is
+ * a compiled spec submitted through
  * `JournalClient`; values are read back from `step.completed` journal entries.
  * Unsupported headers, verbs, gates, or completion lowering fail closed.
  */
@@ -102,6 +103,8 @@ export interface ExecuteAuthoredFlowOptions {
    * `getDefinition` instead; see authored-flow-loader.ts's comment on why.
    */
   readonly getDefinition?: GetFlowDefinition;
+  /** Helper receipt and mock-writeback storage; CLI passes its daemon data directory. */
+  readonly dataDir?: string;
   /**
    * The flow file's own path — passed straight to `checkAuthoredFlow`
    * (cli/check.ts) so `f.agent` resolves a CLI the same way a declarative
@@ -117,6 +120,8 @@ export interface ExecuteAuthoredFlowOptions {
   /** Passed straight through to classifyOutcome (cli/run.ts) for f.agent's wait. */
   readonly signal?: RunLifecycleOptions['signal'];
   readonly onWait?: RunLifecycleOptions['onWait'];
+  readonly onProgress?: (event: ProgressEvent) => void;
+  readonly localAgentStream?: string;
 }
 
 export async function executeAuthoredFlow<Input = undefined>(
@@ -126,218 +131,159 @@ export async function executeAuthoredFlow<Input = undefined>(
   options: ExecuteAuthoredFlowOptions = {},
 ): Promise<AuthoredFlowExecutionResult> {
   const getDefinition = options.getDefinition ?? getAuthoredFlowDefinition;
+  const localAgentStream = options.localAgentStream;
+  const onProgress = options.onProgress;
   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);
-  // `agents` is the one header field this executor lowers today (into
-  // `FlowSpec.agents`, resolved by `lowerAgent` below exactly like the
-  // declarative dialect's `agents:` map). Every other header field remains
-  // unimplemented and refuses closed rather than being silently ignored.
-  const unsupportedHeaderFields = Object.keys(definition.header)
-    .filter((field) => field !== 'agents');
-  if (unsupportedHeaderFields.length > 0) {
+  const headerFields = Object.keys(definition.header).filter(key => key !== 'tools' && key !== 'budget' && key !== 'memory');
+  if (definition.header.tools && Object.keys(definition.header.tools).some(key => !['mcp', ...helperProviders.map(p => p.namespace)].includes(key))) headerFields.push('tools');
+  if (definition.header.tools?.relayfile !== undefined) headerFields.push('tools.relayfile');
+  const helperPreflight = checkSlackHelpers(definition);
+  if (!helperPreflight.ok) {
+    const diagnostic = helperPreflight.diagnostics[0]!;
+    throw new AuthoredFlowExecutionError(diagnostic.kind as AuthoredFlowExecutionErrorCode, diagnostic.message);
+  }
+  if (headerFields.length > 0) {
     throw new AuthoredFlowExecutionError(
       'unsupported_header',
-      `flow "${definition.name}" uses unsupported header fields: ${unsupportedHeaderFields.join(', ')}`,
+      `flow "${definition.name}" uses unsupported header fields: ${headerFields.join(', ')}`,
     );
   }
-  // Every declared named agent's model must be checked BEFORE the body runs,
-  // not lazily the first time a matching `f.agent` call happens to be
-  // reached: the declarative dialect's own preflight (preflight.ts's
-  // unknownModelDiagnostics) checks every entry in `flow.agents`, used or
-  // not, before any step submits — an unregistered model on a header entry
-  // the body never selects must refuse the same way, not silently pass. This
-  // is header data available before the body starts (no need to predict
-  // arbitrary TS control flow): a placeholder no-op deterministic step
-  // carries the declared `agents` map through the same real preflight
-  // `lowerAgent` uses, without probing any CLI (deterministic steps are
-  // never CLI-resolved) and without journaling anything on success.
-  if (definition.header.agents !== undefined && Object.keys(definition.header.agents).length > 0) {
-    const { report } = checkAuthoredFlow({
-      version: SPEC_SCHEMA_VERSION,
-      name: `${definition.name}/declared-agents`,
-      agents: { ...definition.header.agents },
-      steps: [{ id: 'declared-agents', type: 'deterministic', command: ':' }],
-    }, flowPath);
-    if (!report.ok) {
-      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}" declares an invalid named agent`,
-        undefined,
-        undefined,
-        refusal?.kind ?? 'invalid_spec',
-      );
-    }
+
+  const checkedMcp = await checkMcpHeader(definition, flowPath);
+  if (!checkedMcp.report.ok) throw new McpPreflightError(checkedMcp.report);
+
+  const budget = new AuthoredBudget(definition.header.budget);
+  if (definition.header.memory?.agent === true) {
+    throw new AuthoredFlowExecutionError('unsupported_header', 'memory.agent requires the follow-up identity-scoped agent memory adapter');
+  }
+  // Direct member use is checked before any body effects; aliases are checked
+  // by the helper itself, without executing the body during discovery.
+  if (definition.header.memory !== undefined || /\.memory\b/.test(String(definition.body))) {
+    await assertMemoryReachable();
   }
 
   const journalSteps: AuthoredFlowJournalStep[] = [];
   const authoredSteps: AuthoredFlowOperation<unknown>[] = [];
   const lifecycle = new AuthoredFlowLifecycle();
   let nextStep = 1;
-  let requestedCompletion: SurfaceRunCompletionReason | undefined;
+  let requestedCompletion: FlowCompletionReason | undefined;
 
-  const lowerDeterministic = async (
-    id: string,
-    command: string,
-  ): Promise<string> => {
-    const spec = toKernelSpec(compileSpec({
-      version: SPEC_SCHEMA_VERSION,
-      name: `${definition.name}/${id}`,
-      steps: [{ id, type: 'deterministic', command }],
-    }));
-    const outcome = await journal.runStart(spec);
-    return readSuccessfulOutput(journal, outcome, id, journalSteps);
-  };
+  const lowerDeterministic = authoredDeterministicRunner(definition.name, journal, journalSteps, budget);
 
-  // `name` (the first f.agent argument, e.g. "fixer") selects a NAMED
-  // declaration from the flow header's `agents` map, exactly like the
-  // declarative dialect's `agent: fixer` step field selects from a top-level
-  // `agents:` map — but ONLY when `name` actually matches a declared entry.
-  // `compile.ts`'s `resolveNamedAgent` throws `unknown named agent` for any
-  // `step.agent` that doesn't resolve, so setting it unconditionally would
-  // break every call that uses `name` purely for step-id readability (the
-  // common case, and every pre-existing `f.agent` caller). When there's no
-  // match, `agent` stays unset and CLI selection falls through to the
-  // project's flows.json default below, same as a bare `type: agent` YAML
-  // step with no explicit `cli`/`agent`. `options.cli`/`options.model`
-  // always pass through as step-level overrides, which win over any named
-  // declaration independent of whether `name` matched one.
-  const lowerAgent = async (
-    id: string,
-    name: 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 namedAgents = definition.header.agents;
-    const matchesNamedAgent = namedAgents !== undefined && Object.hasOwn(namedAgents, name);
-    const authoring: FlowSpec = {
-      version: SPEC_SCHEMA_VERSION,
-      name: `${definition.name}/${id}`,
-      ...(namedAgents === undefined ? {} : { agents: { ...namedAgents } }),
-      steps: [{
-        id,
-        type: 'agent',
-        instruction: options.task,
-        ...(matchesNamedAgent ? { agent: name } : {}),
-        ...(options.cli === undefined ? {} : { cli: options.cli }),
-        ...(options.model === undefined ? {} : { model: options.model }),
-        ...(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}")`,
-        undefined,
-        undefined,
-        refusal?.kind ?? 'invalid_spec',
-      );
-    }
-    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 worker = authoredWorkerRunner(definition, journal, flowPath, journalSteps, waitOptions, localAgentStream, budget, definition.header.budget);
+
+  function llmOperation(strings: TemplateStringsArray, ...values: unknown[]): Step<string>;
+  function llmOperation(prompt: string, options: LlmOptions): Step<unknown>;
+  function llmOperation(prompt: string | TemplateStringsArray, ...values: unknown[]): Step<unknown> {
+    assertOperationAllowed('llm', definition.name, requestedCompletion);
+    const id = `llm-${nextStep++}`;
+    // Hoist the operation reference so the start closure can read the
+    // caller's `.gate(config)` at spec-build time. AuthoredFlowOperation
+    // begins after construction returns, so `llmOp` is defined by then.
+    let llmOp!: AuthoredFlowOperation<unknown>;
+    llmOp = new AuthoredFlowOperation(
+      id, 'llm',
+      () => assertOperationAllowed('llm', definition.name, requestedCompletion),
+      () => observeStep(id, 'llm', () => {
+        if (typeof prompt === 'string') {
+          if (values.length !== 1 || values[0] === undefined) {
+            throw new AuthoredFlowExecutionError('llm_cli_unresolved', 'f.llm(prompt, options) requires an output JSON Schema.');
+          }
+          return worker.llm(id, prompt, values[0] as LlmOptions, llmOp.namedGate);
+        }
+        const text = prompt.reduce((result, part, index) => result + part
+          + (index < values.length ? String(values[index]) : ''), '');
+        return worker.llm(id, text, undefined, llmOp.namedGate);
+      }, onProgress),
+      lifecycle,
+    );
+    return trackStep(authoredSteps, llmOp);
+  }
+
+  const slackRun = randomUUID();
+  function slackOperation<T>(call: SlackCall): Step<T> {
+    assertOperationAllowed(`slack.${call.verb}`, definition.name, requestedCompletion);
+    const snapshot = snapshotJsonValue(call, 'f.slack call') as unknown as SlackCall;
+    const id = `slack-${slackRun}-${nextStep++}`;
+    return trackStep(authoredSteps, new AuthoredFlowOperation<T>(
+      id, `slack.${call.verb}`,
+      () => assertOperationAllowed(`slack.${call.verb}`, definition.name, requestedCompletion),
+      async () => {
+        const receipt = await runHelperEffect(journal, definition.name, id, snapshot,
+          options.dataDir ?? dirname(journal.socketPath), journalSteps);
+        return (call.verb === 'react' ? undefined : receipt) as T;
+      },
+      lifecycle,
+    ));
+  }
 
   const context: Ctx = {
-    run(command) {
+    ...createHelpers(<T>(call: HelperCall): Step<T> => {
+      const verb = `${call.provider}.${call.verb}`;
+      assertOperationAllowed(verb, definition.name, requestedCompletion);
+      const snapshot = snapshotJsonValue(call, `f.${verb} call`) as unknown as HelperCall;
+      const id = `${call.provider}-${slackRun}-${nextStep++}`;
+      return trackStep(authoredSteps, new AuthoredFlowOperation<T>(id, verb,
+        () => assertOperationAllowed(verb, definition.name, requestedCompletion),
+        async () => await runHelperEffect(journal, definition.name, id, snapshot,
+          options.dataDir ?? dirname(journal.socketPath), journalSteps) as T,
+        lifecycle));
+    }),
+    slack: {
+      post: (channel, text, opts) => slackOperation({ type: 'effect', provider: 'slack', verb: 'post', params: { channel, text, ...(opts === undefined ? {} : { opts }) } }),
+      dm: (user, text) => slackOperation({ type: 'effect', provider: 'slack', verb: 'dm', params: { user, text } }),
+      reply: (channel, threadTs, text) => slackOperation({ type: 'effect', provider: 'slack', verb: 'reply', params: { channel, threadTs, text } }),
+      react: (channel, messageTs, emoji) => slackOperation({ type: 'effect', provider: 'slack', verb: 'react', params: { channel, messageTs, emoji } }),
+    },
+    mcp: buildMcpProxy(checkedMcp.inventory, (server, tool, args, known) => {
+      assertOperationAllowed('mcp', definition.name, requestedCompletion);
+      const id = `mcp-${nextStep++}`;
+      return trackStep(authoredSteps, new AuthoredFlowOperation(
+        id, 'mcp',
+        () => assertOperationAllowed('mcp', definition.name, requestedCompletion),
+        () => runMcpEffect(journal, definition.name, id, server, tool, args,
+          known, checkedMcp.servers[server]!, journalSteps),
+        lifecycle,
+      ));
+    }),
+    memory: authoredMemory(
+      scriptMemoryScope(flowPath, definition.name),
+      () => assertOperationAllowed('memory', definition.name, requestedCompletion),
+      definition.header.memory?.script !== false,
+    ),
+    run(command, runOptions) {
       assertOperationAllowed('run', definition.name, requestedCompletion);
+      const leaseMs = runOptions?.timeout === undefined ? undefined : parseStepTimeout(runOptions.timeout);
       const id = `run-${nextStep++}`;
-      return trackStep(authoredSteps, new AuthoredFlowOperation(
+      let runOp!: AuthoredFlowOperation<string>;
+      runOp = new AuthoredFlowOperation<string>(
         id,
         'run',
         () => assertOperationAllowed('run', definition.name, requestedCompletion),
-        () => lowerDeterministic(id, command),
-        lifecycle,
-      ));
-    },
-    llm() {
-      assertOperationAllowed('llm', definition.name, requestedCompletion);
-      const id = `llm-${nextStep++}`;
-      return trackStep(authoredSteps, unsupportedStep(
-        id,
-        'llm',
-        () => assertOperationAllowed('llm', definition.name, requestedCompletion),
+        () => observeStep(id, 'deterministic', () => lowerDeterministic(id, command, false, leaseMs, runOp.namedGate), options.onProgress),
         lifecycle,
-      ));
+      );
+      return trackStep(authoredSteps, runOp);
     },
+    llm: llmOperation,
     agent(name, options) {
       assertOperationAllowed('agent', definition.name, requestedCompletion);
+      void name; // Authored headers do not yet declare reusable named agents.
       const id = `agent-${nextStep++}`;
-      return trackStep(authoredSteps, new AuthoredFlowOperation(
+      let agentOp!: AuthoredFlowOperation<AgentResult>;
+      agentOp = new AuthoredFlowOperation<AgentResult>(
         id,
         'agent',
         () => assertOperationAllowed('agent', definition.name, requestedCompletion),
-        () => lowerAgent(id, name, options),
+        () => observeStep(id, 'agent', () => worker.agent(id, options, agentOp.namedGate), onProgress),
         lifecycle,
-      ));
+      );
+      return trackStep(authoredSteps, agentOp);
     },
     human() {
       assertOperationAllowed('human', definition.name, requestedCompletion);
@@ -348,7 +294,7 @@ export async function executeAuthoredFlow<Input = undefined>(
       throw unsupportedVerb('dispatch');
     },
     done(reason) {
-      if (!isSurfaceRunCompletionReason(reason)) {
+      if (reason !== 'needs_human' && !isSurfaceRunCompletionReason(reason)) {
         throw new AuthoredFlowExecutionError(
           'unsupported_completion',
           `unknown completion reason: ${String(reason)}`,
@@ -360,7 +306,7 @@ export async function executeAuthoredFlow<Input = undefined>(
           `flow "${definition.name}" called done() more than once`,
         );
       }
-      if (reason !== 'success') {
+      if (reason !== 'success' && reason !== 'needs_human') {
         throw new AuthoredFlowExecutionError(
           'unsupported_completion',
           `the initial authored executor cannot lower done("${reason}")`,
@@ -375,6 +321,17 @@ export async function executeAuthoredFlow<Input = undefined>(
     ),
   };
 
+  Object.assign(context, pluginHelpers(checkedMcp.plugins ?? [], (plugin, verb, args) => {
+    const label = `${verb.namespace}.${verb.method}`;
+    assertOperationAllowed(label, definition.name, requestedCompletion);
+    const id = `plugin-${nextStep++}`;
+    return trackStep(authoredSteps, new AuthoredFlowOperation(
+      id, label, () => assertOperationAllowed(label, definition.name, requestedCompletion),
+      () => runPluginEffect(journal, definition.name, id, plugin, verb, args, journalSteps, budget),
+      lifecycle,
+    ));
+  }));
+
   let bodyFailed = false;
   let bodyFailure: unknown;
   try {
@@ -424,7 +381,11 @@ export async function executeAuthoredFlow<Input = undefined>(
     lifecycle.close();
   }
 
-  await lowerDeterministic(`complete-${nextStep}`, ':');
+  // The authored runner has no durable root yet. Record the handoff as a
+  // successful effect containing the authored outcome, not a fabricated kernel
+  // run.completed reason. The CLI reports this outcome as parked (exit 3).
+  await lowerDeterministic(`complete-${nextStep}`, requestedCompletion === 'needs_human'
+    ? `printf '%s' '{"completionReason":"needs_human"}'` : ':', true);
   return Object.freeze({
     name: definition.name,
     completionReason: requestedCompletion,
@@ -440,17 +401,6 @@ function trackStep<T>(
   return operation.step;
 }
 
-function unsupportedStep<T>(
-  id: string,
-  verb: string,
-  assertCanStart: () => void,
-  lifecycle: AuthoredFlowLifecycle,
-): AuthoredFlowOperation<T> {
-  return new AuthoredFlowOperation<T>(id, verb, assertCanStart, async () => {
-    throw unsupportedVerb(verb);
-  }, lifecycle);
-}
-
 function unsupportedVerb(verb: string): AuthoredFlowExecutionError {
   return new AuthoredFlowExecutionError(
     'unsupported_verb',
@@ -461,13 +411,13 @@ function unsupportedVerb(verb: string): AuthoredFlowExecutionError {
 function assertOperationAllowed(
   verb: string,
   flowName: string,
-  completion: SurfaceRunCompletionReason | undefined,
+  completion: FlowCompletionReason | undefined,
 ): void {
   if (completion !== undefined) {
     throw new AuthoredFlowExecutionError(
       'operation_after_completion',
       `flow "${flowName}" called f.${verb} after done()`,
-      completion,
+      completion === 'needs_human' ? undefined : completion,
     );
   }
 }
@@ -480,129 +430,3 @@ function unsupportedCloud(assertOpen: () => void): CloudHelper {
     },
   }) as CloudHelper;
 }
-
-/**
- * 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,
-  runId: string,
-  stepId: string,
-  journalSteps: AuthoredFlowJournalStep[],
-): Promise<unknown> {
-  const entries = (await journal.journalRead(runId, 1)).entries;
-  const completed = entries.find((entry) => isStepCompleted(entry, stepId));
-  if (!isStepCompleted(completed, stepId)) {
-    throw protocolViolation(runId, `journal has no step.completed for "${stepId}"`);
-  }
-
-  const reason = completed.payload.completionReason;
-  journalSteps.push(Object.freeze({ id: stepId, runId, completionReason: reason }));
-  if (reason !== 'success') {
-    throw new AuthoredFlowExecutionError(
-      'step_failed',
-      `journal step "${stepId}" completed with ${reason}`,
-      reason,
-      runId,
-    );
-  }
-  return 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;
-  payload: {
-    completionReason: ProtocolCompletionReason;
-    output: unknown;
-  };
-}
-
-function isStepCompleted(value: unknown, stepId: string): value is StepCompletedEntry {
-  if (!isRecord(value) || value['entry_type'] !== 'step.completed' || value['step_id'] !== stepId) {
-    return false;
-  }
-  const payload = value['payload'];
-  return isRecord(payload)
-    && isSurfaceCompletionReason(payload['completionReason'])
-    && 'output' in payload;
-}
-
-function isSurfaceCompletionReason(value: unknown): value is ProtocolCompletionReason {
-  return typeof value === 'string'
-    && (COMPLETION_REASONS as readonly string[]).includes(value);
-}
-
-function isSurfaceRunCompletionReason(value: unknown): value is ProtocolRunCompletionReason {
-  return typeof value === 'string'
-    && (RUN_COMPLETION_REASONS as readonly string[]).includes(value);
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function protocolViolation(runId: string, detail: string): AuthoredFlowExecutionError {
-  return new AuthoredFlowExecutionError(
-    'journal_protocol_violation',
-    detail,
-    undefined,
-    runId,
-  );
-}