@relayflows/sdk 2.0.8 → 2.0.10

package/dist/authored-memory.js

@@ -0,0 +1,60 @@
+import { createHash } from 'node:crypto';
+import { access, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import { preflightMemory } from './preflight.js';
+/** Stable across runs; disjoint from other flow files and other named flows. */
+export function scriptMemoryScope(flowPath, name) {
+    const absolute = resolve(flowPath);
+    const key = createHash('sha256').update(JSON.stringify([absolute, name])).digest('hex');
+    return join(dirname(absolute), '.relayflows', 'memory', 'scripts', key);
+}
+export async function probeScriptMemory() {
+    const { defaultDbPath, openAiHist } = await import('ai-hist');
+    const path = defaultDbPath();
+    await access(path, constants.R_OK);
+    if (!(await stat(path)).isFile())
+        throw new Error('memory database must be a file');
+    const reader = await openAiHist({ dbPath: path, fallback: 'error' });
+    try {
+        reader.search('', { limit: 1 });
+    }
+    finally {
+        reader.close();
+    }
+}
+export async function assertMemoryReachable() {
+    const refusal = await preflightMemory(probeScriptMemory);
+    if (refusal)
+        throw new AuthoredFlowExecutionError('memory_unreachable', refusal.message);
+}
+export function authoredMemory(scope, assertOpen, enabled) {
+    async function read(action) {
+        assertOpen();
+        if (!enabled)
+            throw new AuthoredFlowExecutionError('unsupported_header', 'f.memory requires script memory; memory.script is false');
+        await assertMemoryReachable();
+        assertOpen();
+        const { openAiHist } = await import('ai-hist');
+        const reader = await openAiHist({ projectScope: scope, fallback: 'error' });
+        try {
+            return action(reader);
+        }
+        finally {
+            reader.close();
+        }
+    }
+    return {
+        recall: (query, options) => read(reader => reader.search(query, { ...options, project: scope })),
+        why: task => read(reader => {
+            const entry = reader.whyForTask(task);
+            return entry?.projectId === scope ? [entry] : [];
+        }),
+        async learn() {
+            assertOpen();
+            throw new AuthoredFlowExecutionError('unsupported_verb', 'f.memory.learn requires the follow-up journal-backed trajectory writer');
+        },
+    };
+}
+//# sourceMappingURL=authored-memory.js.map

package/dist/authored-memory.js.map

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

package/dist/authored-plugin-effect.d.ts

@@ -0,0 +1,16 @@
+import { type LoadedPlugin } from './plugin-loader.js';
+import type { PluginVerb } from './plugin-manifest.js';
+import type { AuthoredBudget } from './authored-budget.js';
+import type { JournalClient } from './journal-client.js';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
+export declare class PluginStepError extends AuthoredFlowExecutionError {
+    readonly diagnostic: string;
+    constructor(diagnostic: string, runId: string);
+}
+/** Helpers lower to an existing agent effect, never a fourth kernel primitive.
+ * The Plugin receipt lives in step.completed.output: { type, input, output, ... }.
+ * A private stream routes the step to this short-lived SDK worker exclusively.
+ */
+export declare function runPluginEffect(journal: JournalClient, flowName: string, id: string, plugin: LoadedPlugin, verb: PluginVerb, args: unknown, journalSteps: AuthoredFlowJournalStep[], budget: AuthoredBudget): Promise<unknown>;
+//# sourceMappingURL=authored-plugin-effect.d.ts.map

package/dist/authored-plugin-effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authored-plugin-effect.d.ts","sourceRoot":"","sources":["../src/authored-plugin-effect.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAI3E,qBAAa,eAAgB,SAAQ,0BAA0B;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM;gBAAlB,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAGvD;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,EAC5F,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,EAAE,MAAM,EAAE,cAAc,GAC7E,OAAO,CAAC,OAAO,CAAC,CAuHlB"}

package/dist/authored-plugin-effect.js

@@ -0,0 +1,163 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { compileSpec, toKernelSpec } from './compile.js';
+import { invokePlugin } from './plugin-loader.js';
+import { SPEC_SCHEMA_VERSION } from './spec.js';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import { readCompletedStepOutput } from './authored-step-output.js';
+import { withWorkerLease } from './worker-lease.js';
+export class PluginStepError extends AuthoredFlowExecutionError {
+    diagnostic;
+    constructor(diagnostic, runId) {
+        super('step_failed', diagnostic, 'worker_error', runId);
+        this.diagnostic = diagnostic;
+    }
+}
+/** Helpers lower to an existing agent effect, never a fourth kernel primitive.
+ * The Plugin receipt lives in step.completed.output: { type, input, output, ... }.
+ * A private stream routes the step to this short-lived SDK worker exclusively.
+ */
+export async function runPluginEffect(journal, flowName, id, plugin, verb, args, journalSteps, budget) {
+    const server = verb.namespace;
+    const tool = verb.method;
+    const idempotencyKey = `plugin:${server}:${tool}:${createHash('sha256').update(JSON.stringify(args)).digest('hex')}`;
+    const surfacePath = `/plugins/${pathPart(server)}/${pathPart(tool)}`;
+    const stream = `plugin-worker-${randomUUID()}`;
+    const instruction = JSON.stringify({ type: 'effect', server, tool, input: args });
+    const peer = journal.createPeer();
+    let diagnostic;
+    let settled;
+    let failed;
+    const completed = new Promise((resolve, reject) => { settled = resolve; failed = reject; });
+    void completed.catch(() => undefined);
+    let timer;
+    let work;
+    let dispatchExpired = false;
+    const dispatch = (event) => {
+        if (dispatchExpired)
+            return;
+        const dispatched = event.spec;
+        if (event.step_id !== id || event.step_type !== 'agent' || work !== undefined
+            || dispatched?.instruction !== instruction
+            || !dispatched.surfaces?.streams?.some(pin => pin.stream === stream)) {
+            failed(new Error('Plugin worker received an unexpected dispatch'));
+            return;
+        }
+        clearTimeout(timer);
+        timer = undefined;
+        work = execute(event);
+        void work.then(settled, failed);
+    };
+    async function execute(event) {
+        const receipt = { type: 'effect', plugin: plugin.manifest.name, version: plugin.manifest.version,
+            namespace: server, method: tool, input: args, idempotencyKey: event.idempotency_key };
+        let output;
+        let confirmed = false;
+        try {
+            // Renew the worker lease while the Plugin tool is in flight. Without this,
+            // a tool that runs longer than the initial lease loses ownership and
+            // the write-back path fails — see worker-lease.ts for the renewal contract.
+            confirmed = await withWorkerLease(peer, event, async () => {
+                return peer.performEffect({
+                    runId: event.run_id, stepId: id, attempt: event.attempt, idempotencyKey: event.idempotency_key,
+                    surfacePath, revisionBefore: 'pending', revisionAfter: idempotencyKey,
+                }, async () => {
+                    try {
+                        output = await invokePlugin(plugin, verb, args, event.idempotency_key);
+                    }
+                    catch {
+                        diagnostic = 'plugin_execution_failed';
+                        throw new PluginExecutionFailure();
+                    }
+                });
+            });
+            // A confirmed election without its receipt is an interrupted writeback,
+            // not a successful result we may invent or a call we may safely repeat.
+            if (!confirmed)
+                throw new Error('plugin_result_unavailable');
+        }
+        catch (error) {
+            if (error instanceof PluginExecutionFailure)
+                diagnostic = 'plugin_execution_failed';
+            else if (error instanceof Error && error.message === 'plugin_result_unavailable')
+                diagnostic = error.message;
+            else
+                throw error; // Journal failures remain fail-closed, never provider errors.
+        }
+        await peer.stepComplete(event.run_id, id, event.attempt, event.idempotency_key, diagnostic === undefined ? 'success' : 'worker_error', {
+            output: { ...receipt, output: output ?? null, ...(diagnostic ? { diagnostic } : {}) },
+            started_pins: event.pins, end_pins: event.pins,
+            ...(diagnostic ? { trajectory_tail: { ...receipt, diagnostic } } : {}),
+            effects: confirmed ? [{ surface_path: surfacePath, idempotency_key: event.idempotency_key }] : [],
+        });
+    }
+    let childRunId;
+    async function cancelChildRun() {
+        const runId = childRunId;
+        childRunId = undefined;
+        if (runId !== undefined) {
+            try {
+                await journal.runCancel(runId);
+            }
+            catch { /* fail-open on cleanup */ }
+        }
+    }
+    const deadlineError = new Error('Plugin worker dispatch deadline exceeded');
+    let finishDeadline;
+    const deadline = new Promise((resolve, reject) => {
+        finishDeadline = resolve;
+        // One deadline covers connection, initialization, run creation and dispatch.
+        timer = setTimeout(() => {
+            dispatchExpired = true;
+            failed(deadlineError);
+            reject(deadlineError);
+        }, 30_000);
+    });
+    try {
+        await Promise.race([peer.connect(), deadline]);
+        await Promise.race([peer.hello('flows-plugin'), deadline]);
+        peer.on('step.dispatch', dispatch);
+        await Promise.race([peer.workerAttach(stream, ['agent'], { workspace: [], streams: [{ stream, read_offset: 0 }] }, 1), deadline]);
+        const spec = toKernelSpec(compileSpec({ version: SPEC_SCHEMA_VERSION, name: `${flowName}/${id}`,
+            steps: [{ id, type: 'agent', instruction,
+                    surfaces: { streams: [{ stream }], external: [surfacePath] }, maxIterations: 1 }],
+        }));
+        return await Promise.race([budget.execute(journal, spec, async (outcome) => {
+                childRunId = outcome.run_id;
+                // run.start may answer after the deadline and the outer cleanup.
+                if (dispatchExpired)
+                    await cancelChildRun();
+                await completed;
+                if (diagnostic !== undefined) {
+                    try {
+                        await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps);
+                    }
+                    catch (error) {
+                        if (!(error instanceof AuthoredFlowExecutionError) || error.code !== 'step_failed')
+                            throw error;
+                        throw new PluginStepError(diagnostic, outcome.run_id);
+                    }
+                }
+                const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps);
+                return receipt.output;
+            }), deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+        finishDeadline();
+        peer.off('step.dispatch', dispatch);
+        // If the dispatch deadline fired we started a child run that will never
+        // be worked -- cancel it so its journal doesn't stay indeterminate.
+        // Best-effort: the parent flow already surfaced the deadline via the
+        // rejected `completed` promise, so a cancel error here must not mask it.
+        if (dispatchExpired)
+            await cancelChildRun();
+        peer.close();
+        await work?.catch(() => undefined);
+    }
+}
+function pathPart(value) {
+    return encodeURIComponent(value).replaceAll('.', '%2E');
+}
+class PluginExecutionFailure extends Error {
+}
+//# sourceMappingURL=authored-plugin-effect.js.map

package/dist/authored-plugin-effect.js.map

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

package/dist/authored-step-output.d.ts

@@ -0,0 +1,23 @@
+import type { JournalClient } from './journal-client.js';
+import type { CompletionReason as ProtocolCompletionReason, RunCompletionReason as ProtocolRunCompletionReason, RunOutcome } from './protocol.js';
+import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
+/**
+ * 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.
+ */
+export declare function readCompletedStepOutput(journal: JournalClient, runId: string, stepId: string, journalSteps: AuthoredFlowJournalStep[]): Promise<unknown>;
+export declare function readSuccessfulOutput(journal: JournalClient, outcome: RunOutcome, stepId: string, journalSteps: AuthoredFlowJournalStep[]): Promise<string>;
+export declare function isSurfaceCompletionReason(value: unknown): value is ProtocolCompletionReason;
+export declare function isSurfaceRunCompletionReason(value: unknown): value is ProtocolRunCompletionReason;
+//# sourceMappingURL=authored-step-output.d.ts.map

package/dist/authored-step-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authored-step-output.d.ts","sourceRoot":"","sources":["../src/authored-step-output.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,IAAI,wBAAwB,EAAE,mBAAmB,IAAI,2BAA2B,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAClJ,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAE3E;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,uBAAuB,EAAE,GACtC,OAAO,CAAC,OAAO,CAAC,CAkBlB;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,uBAAuB,EAAE,GACtC,OAAO,CAAC,MAAM,CAAC,CAajB;AAqBD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,wBAAwB,CAG3F;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,2BAA2B,CAGjG"}

package/dist/authored-step-output.js

@@ -0,0 +1,67 @@
+import { COMPLETION_REASONS, RUN_COMPLETION_REASONS } from '@relayflows/surface';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+/**
+ * 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.
+ */
+export 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(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;
+}
+export async function readSuccessfulOutput(journal, outcome, stepId, journalSteps) {
+    const output = await readCompletedStepOutput(journal, outcome.run_id, stepId, journalSteps).catch(error => {
+        if (error instanceof AuthoredFlowExecutionError
+            && (error.completionReason === 'timeout' || error.completionReason === 'lease_expired')) {
+            throw new AuthoredFlowExecutionError('lease_exceeded', `f.run step "${stepId}" exceeded its command timeout.`, error.completionReason, error.runId);
+        }
+        throw error;
+    });
+    if (!isRecord(output) || typeof output['stdout_tail'] !== 'string') {
+        throw protocolViolation(outcome.run_id, `step "${stepId}" has no string stdout_tail`);
+    }
+    return output['stdout_tail'];
+}
+function isStepCompleted(value, stepId) {
+    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;
+}
+export function isSurfaceCompletionReason(value) {
+    return typeof value === 'string'
+        && COMPLETION_REASONS.includes(value);
+}
+export function isSurfaceRunCompletionReason(value) {
+    return typeof value === 'string'
+        && RUN_COMPLETION_REASONS.includes(value);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function protocolViolation(runId, detail) {
+    return new AuthoredFlowExecutionError('journal_protocol_violation', detail, undefined, runId);
+}
+//# sourceMappingURL=authored-step-output.js.map

package/dist/authored-step-output.js.map

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

package/dist/authored-worker-step.d.ts

@@ -0,0 +1,15 @@
+import type { AuthoredBudget } from './authored-budget.js';
+import type { AgentOptions, AgentResult, LlmOptions, NamedGate } from '@relayflows/surface';
+import { type RunLifecycleOptions } from './cli/run.js';
+import type { JournalClient } from './journal-client.js';
+import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
+/** Agent and LLM calls share the exact declarative preflight and lease wait. */
+export declare function authoredWorkerRunner(definition: {
+    name: string;
+}, journal: JournalClient, flowPath: string, journalSteps: AuthoredFlowJournalStep[], waitOptions: RunLifecycleOptions, localAgentStream?: string, budget?: AuthoredBudget, headerBudget?: unknown): {
+    agent(id: string, options: AgentOptions, verification?: NamedGate): Promise<AgentResult>;
+    llm(id: string, prompt: string, options?: LlmOptions, verification?: NamedGate): Promise<unknown>;
+};
+/** Deterministic commands execute inline under their per-invocation lease. */
+export declare function authoredDeterministicRunner(name: string, journal: JournalClient, journalSteps: AuthoredFlowJournalStep[], budget: AuthoredBudget): (id: string, command: string, terminal?: boolean, leaseMs?: number, verification?: NamedGate) => Promise<string>;
+//# sourceMappingURL=authored-worker-step.d.ts.map

package/dist/authored-worker-step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authored-worker-step.d.ts","sourceRoot":"","sources":["../src/authored-worker-step.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAG5F,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAGzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAK3E,gFAAgF;AAChF,wBAAgB,oBAAoB,CAClC,UAAU,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EACtE,YAAY,EAAE,uBAAuB,EAAE,EAAE,WAAW,EAAE,mBAAmB,EACzE,gBAAgB,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,EAAE,YAAY,CAAC,EAAE,OAAO;cAiExD,MAAM,WAAW,YAAY,iBAAiB,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;YAyDhF,MAAM,UAAU,MAAM,YAAY,UAAU,iBAAiB,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;EAmB1G;AAED,8EAA8E;AAC9E,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,uBAAuB,EAAE,EAAE,MAAM,EAAE,cAAc,IAEvF,IAAI,MAAM,EAAE,SAAS,MAAM,EAAE,kBAAgB,EAAE,UAAU,MAAM,EAAE,eAAe,SAAS,KAAG,OAAO,CAAC,MAAM,CAAC,CAa1H"}

package/dist/authored-worker-step.js

@@ -0,0 +1,136 @@
+import { parseBudget } from './budget.js';
+import { compileSpec, toKernelSpec } from './compile.js';
+import { checkAuthoredFlow } from './cli/check.js';
+import { classifyOutcome } from './cli/run.js';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import { SPEC_SCHEMA_VERSION } from './spec.js';
+import { isSurfaceCompletionReason, readCompletedStepOutput, readSuccessfulOutput } from './authored-step-output.js';
+import { snapshotJsonValue } from './json-value.js';
+const WORKSPACE_PERMISSION_ANNOTATION = /:\s*(readonly|readwrite)\s*$/i;
+/** Agent and LLM calls share the exact declarative preflight and lease wait. */
+export function authoredWorkerRunner(definition, journal, flowPath, journalSteps, waitOptions, localAgentStream, budget, headerBudget) {
+    async function run(step) {
+        const id = step.id;
+        const authoring = { version: SPEC_SCHEMA_VERSION, name: `${definition.name}/${id}`, steps: [step], ...(headerBudget === undefined ? {} : { budget: parseBudget(headerBudget) }) };
+        // 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(refusal?.kind === 'budget_missing_price' || refusal?.kind === 'budget_syntax_invalid' ? refusal.kind
+                : step.type === 'llm' ? 'llm_cli_unresolved' : 'agent_cli_unresolved', refusal?.message
+                ?? `flow "${definition.name}" step "${id}": no CLI could be resolved for f.${step.type} `
+                    + `(searched for flows.json from "${flowPath}")`);
+        }
+        const spec = toKernelSpec(resolved);
+        const consume = async (outcome) => {
+            // 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(step.type === 'llm' ? 'llm_parked' : '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 readCompletedStepOutput(journal, outcome.run_id, id, journalSteps);
+        };
+        return budget === undefined ? consume(await journal.runStart(spec)) : budget.execute(journal, spec, consume);
+    }
+    return {
+        async agent(id, options, verification) {
+            if (options.workspace !== undefined && localAgentStream !== undefined) {
+                throw new AuthoredFlowExecutionError('unsupported_workspace_permission', 'The local agent worker accepts stream-only steps. Remove workspace or attach a worker that holds its revision pins.');
+            }
+            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.');
+            }
+            if (options.cli !== undefined && typeof options.cli !== 'string') {
+                throw new AuthoredFlowExecutionError('agent_cli_unresolved', `f.agent options.cli must be a string when set (got ${typeof options.cli}).`);
+            }
+            if (options.model !== undefined && typeof options.model !== 'string') {
+                throw new AuthoredFlowExecutionError('agent_cli_unresolved', `f.agent options.model must be a string when set (got ${typeof options.model}).`);
+            }
+            if (options.cwd !== undefined && typeof options.cwd !== 'string') {
+                throw new AuthoredFlowExecutionError('agent_cli_unresolved', `f.agent options.cwd must be a string when set (got ${typeof options.cwd}).`);
+            }
+            if (options.transport !== undefined && options.transport !== 'direct' && options.transport !== 'relay') {
+                throw new AuthoredFlowExecutionError('agent_cli_unresolved', `f.agent options.transport must be 'direct' or 'relay' (got ${JSON.stringify(options.transport)}).`);
+            }
+            const output = await run({
+                id, type: 'agent', instruction: options.task,
+                ...(localAgentStream === undefined ? {} : { surfaces: { streams: [{ stream: localAgentStream }] } }),
+                ...(options.workspace === undefined ? {} : { surfaces: { workspace: [{ surface: options.workspace }] } }),
+                ...(options.cli === undefined ? {} : { cli: options.cli }),
+                ...(options.model === undefined ? {} : { model: options.model }),
+                ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+                ...(options.transport === undefined ? {} : { transport: options.transport }),
+                ...(verification === undefined ? {} : { verification }),
+            });
+            if (typeof output !== 'object' || output === null || Array.isArray(output)) {
+                throw new AuthoredFlowExecutionError('journal_protocol_violation', `step "${id}" produced a non-object output`);
+            }
+            const stdout = 'stdout_tail' in output ? output.stdout_tail : undefined;
+            return { summary: typeof stdout === 'string' ? stdout : JSON.stringify(output), artifacts: [] };
+        },
+        async llm(id, prompt, options, verification) {
+            if (options !== undefined && (typeof options !== 'object' || options === null || options.output === undefined)) {
+                throw new AuthoredFlowExecutionError('llm_cli_unresolved', 'f.llm(prompt, options) requires an output JSON Schema.');
+            }
+            const snapshot = options === undefined ? undefined : snapshotJsonValue(options, 'f.llm options');
+            if (snapshot !== undefined && (typeof snapshot !== 'object' || snapshot === null || Array.isArray(snapshot)
+                || Object.keys(snapshot).some(key => !['output', 'cli', 'model'].includes(key)))) {
+                throw new AuthoredFlowExecutionError('llm_cli_unresolved', 'f.llm options accepts only output, cli, and model.');
+            }
+            const output = await run({
+                id, type: 'llm', prompt, ...snapshot,
+                ...(verification === undefined ? {} : { verification }),
+            });
+            if (options === undefined && typeof output !== 'string') {
+                throw new AuthoredFlowExecutionError('journal_protocol_violation', `text step "${id}" produced a non-string output`);
+            }
+            return output;
+        },
+    };
+}
+/** Deterministic commands execute inline under their per-invocation lease. */
+export function authoredDeterministicRunner(name, journal, journalSteps, budget) {
+    return async (id, command, terminal = false, leaseMs, verification) => {
+        const spec = toKernelSpec(compileSpec({
+            version: SPEC_SCHEMA_VERSION,
+            name: `${name}/${id}`,
+            steps: [{
+                    id, type: 'deterministic', command,
+                    ...(leaseMs === undefined ? {} : { lease_ms: leaseMs }),
+                    ...(verification === undefined ? {} : { verification }),
+                }],
+        }));
+        if (terminal)
+            return readSuccessfulOutput(journal, await journal.runStart(spec), id, journalSteps);
+        return budget.execute(journal, spec, outcome => readSuccessfulOutput(journal, outcome, id, journalSteps));
+    };
+}
+//# sourceMappingURL=authored-worker-step.js.map

package/dist/authored-worker-step.js.map

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

package/dist/budget-preflight.d.ts

@@ -0,0 +1,5 @@
+import type { CompiledFlowSpec } from './compile.js';
+import type { PreflightRefusal } from './preflight.js';
+/** Legacy explicit envelopes keep their worker-supplied pricing contract. */
+export declare function budgetDiagnostics(flow: CompiledFlowSpec): PreflightRefusal[];
+//# sourceMappingURL=budget-preflight.d.ts.map

package/dist/budget-preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-preflight.d.ts","sourceRoot":"","sources":["../src/budget-preflight.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGvD,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAyB5E"}

package/dist/budget-preflight.js

@@ -0,0 +1,33 @@
+import { MODEL_PRICING } from './model-pricing.js';
+/** Legacy explicit envelopes keep their worker-supplied pricing contract. */
+export function budgetDiagnostics(flow) {
+    if (flow.budget?.pricing !== 'frozen')
+        return [];
+    const diagnostics = [];
+    const declared = [
+        ...Object.entries(flow.agents ?? {}).map(([agent, d]) => ({ agent, model: d.model })),
+        ...flow.steps.flatMap(s => s.type !== 'deterministic' && s.model !== undefined
+            ? [{ stepId: s.id, model: s.model }] : []),
+    ];
+    for (const step of flow.steps) {
+        if (step.type === 'deterministic' || flow.budget.maxDollars === undefined)
+            continue;
+        const model = step.model ?? (step.type === 'agent' && step.agent !== undefined
+            ? flow.agents?.[step.agent]?.model : undefined);
+        if (model === undefined)
+            diagnostics.push({
+                severity: 'refusal', kind: 'budget_missing_price', stepId: step.id,
+                message: `Step "${step.id}" needs a declared, priced model for its dollar budget.`,
+            });
+    }
+    for (const declaration of declared) {
+        if (Object.hasOwn(MODEL_PRICING, declaration.model))
+            continue;
+        diagnostics.push({
+            severity: 'refusal', kind: 'budget_missing_price', ...declaration,
+            message: `Model "${declaration.model}" has no frozen price for budget accounting.`,
+        });
+    }
+    return diagnostics;
+}
+//# sourceMappingURL=budget-preflight.js.map

package/dist/budget-preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-preflight.js","sourceRoot":"","sources":["../src/budget-preflight.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,6EAA6E;AAC7E,MAAM,UAAU,iBAAiB,CAAC,IAAsB;IACtD,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACjD,MAAM,WAAW,GAAuB,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAAG;QACf,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;QACrF,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,eAAe,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS;YAC5E,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KAC7C,CAAC;IACF,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC9B,IAAI,IAAI,CAAC,IAAI,KAAK,eAAe,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,KAAK,SAAS;YAAE,SAAS;QACpF,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAC5E,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAClD,IAAI,KAAK,KAAK,SAAS;YAAE,WAAW,CAAC,IAAI,CAAC;gBACxC,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,sBAAsB,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;gBAClE,OAAO,EAAE,SAAS,IAAI,CAAC,EAAE,yDAAyD;aACnF,CAAC,CAAC;IACL,CAAC;IACD,KAAK,MAAM,WAAW,IAAI,QAAQ,EAAE,CAAC;QACnC,IAAI,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,WAAW,CAAC,KAAK,CAAC;YAAE,SAAS;QAC9D,WAAW,CAAC,IAAI,CAAC;YACf,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,sBAAsB,EAAE,GAAG,WAAW;YACjE,OAAO,EAAE,UAAU,WAAW,CAAC,KAAK,8CAA8C;SACnF,CAAC,CAAC;IACL,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/budget.d.ts

@@ -0,0 +1,14 @@
+import type { BudgetSpec, KernelBudgetSpec } from './spec.js';
+export type HeaderBudget = string | {
+    tokens?: number;
+    dollars?: number;
+    wallclock?: string;
+};
+export declare class BudgetSyntaxError extends Error {
+    constructor();
+}
+/** Normalize surface sugar; existing explicit envelopes remain supported. */
+export declare function parseBudget(value: unknown): BudgetSpec;
+/** Lower a normalized envelope to the existing kernel protocol. */
+export declare function toKernelBudget(budget: BudgetSpec): KernelBudgetSpec;
+//# sourceMappingURL=budget.d.ts.map

package/dist/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE9D,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9F,qBAAa,iBAAkB,SAAQ,KAAK;;CAE3C;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CA0BtD;AAED,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,gBAAgB,CAUnE"}