@sapiom/agent-core 0.6.0

package/dist/esm/git.js

@@ -0,0 +1,69 @@
+import { execFileSync } from 'node:child_process';
+import { AgentOperationError } from './errors.js';
+function git(args, cwd) {
+    try {
+        return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+    }
+    catch (err) {
+        const stderr = err.stderr?.toString().trim();
+        throw new AgentOperationError({
+            code: 'GIT',
+            message: `git ${args[0]} failed.`,
+            hint: stderr || (err instanceof Error ? err.message : String(err)),
+        });
+    }
+}
+export function assertDeployable(dir) {
+    try {
+        execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: dir, stdio: 'ignore' });
+    }
+    catch {
+        throw new AgentOperationError({
+            code: 'NOT_GIT',
+            message: 'Not a git repository.',
+            hint: 'Initialize one: git init && git add -A && git commit -m "init"',
+        });
+    }
+    try {
+        execFileSync('git', ['rev-parse', 'HEAD'], { cwd: dir, stdio: 'ignore' });
+    }
+    catch {
+        throw new AgentOperationError({
+            code: 'NO_COMMITS',
+            message: 'This repository has no commits yet.',
+            hint: 'Commit your work: git add -A && git commit -m "…"',
+        });
+    }
+}
+export function redactCredentials(text) {
+    return text.replace(/(https?:\/\/)[^@\s/]+@/gi, '$1***@');
+}
+export function cloneRepo(opts) {
+    const { cloneUrl, targetDir, branch, repoFullName, cwd } = opts;
+    try {
+        execFileSync('git', ['clone', '--depth', '1', '--single-branch', '--branch', branch, '--', cloneUrl, targetDir], { cwd, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' });
+    }
+    catch (err) {
+        const stderr = err.stderr?.toString();
+        const raw = stderr?.trim() || (err instanceof Error ? err.message : String(err));
+        throw new AgentOperationError({
+            code: 'GIT_CLONE',
+            message: 'git clone failed.',
+            hint: redactCredentials(raw),
+        });
+    }
+    try {
+        git(['remote', 'set-url', 'origin', `https://github.com/${repoFullName}.git`], targetDir);
+    }
+    catch {
+    }
+}
+export function pushHead(dir, pushUrl, branch) {
+    git(['push', '--force', pushUrl, `HEAD:${branch}`], dir);
+}
+export function pushSynthesizedTree(treeDir, pushUrl, branch) {
+    git(['init', '-q', '-b', branch], treeDir);
+    git(['add', '-A'], treeDir);
+    git(['-c', 'user.email=deploy@sapiom.ai', '-c', 'user.name=Sapiom Deploy', 'commit', '-q', '-m', 'deploy'], treeDir);
+    git(['push', '--force', pushUrl, `HEAD:${branch}`], treeDir);
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,41 @@
+export { AgentOperationError } from "./errors.js";
+export type { StructuredError } from "./errors.js";
+export { GatewayClient, createClient, DEFAULT_WORKFLOWS_HOST, } from "./client.js";
+export type { ClientOptions, GatewayErrorBody } from "./client.js";
+export { readConfig, requireConfig, writeConfig, CONFIG_FILE, } from "./config.js";
+export type { SapiomConfig, LinkedSapiomConfig } from "./config.js";
+export { scaffold, resolveVersions, resolveTemplate, listTemplates, DEFAULT_TEMPLATE, } from "./scaffold.js";
+export type { ScaffoldOptions, ScaffoldResult, ResolvedVersions, } from "./scaffold.js";
+export { check } from "./check.js";
+export type { CheckOptions, CheckResult } from "./check.js";
+export { bundleForDeploy } from "./bundle.js";
+export type { DeployBundle } from "./bundle.js";
+export { link } from "./link.js";
+export type { LinkOptions, LinkResult, DefinitionSummary } from "./link.js";
+export { clone } from "./clone.js";
+export type { CloneOptions, CloneResult } from "./clone.js";
+export { deploy } from "./deploy.js";
+export type { DeployOptions, DeployResult } from "./deploy.js";
+export { run, parseJsonInput } from "./run.js";
+export type { RunOptions, RunResult } from "./run.js";
+export type { ExecutionProjection, StepProjection, CostNode, SettleState, ExecutionRef, DispatchRef, StepError, StepErrorTrace, StepErrorFrame, StepEvent, SseEvent, SseEventType, } from "./types.js";
+export { SSE_EVENT_TYPES } from "./types.js";
+export { decodeExecutionProjection } from "./decode.js";
+export { inspect, listExecutions, inspectBuild, waitForExecution, isExecutionTerminal, } from "./inspect.js";
+export type { InspectOptions, InspectBuildOptions, InspectBuildResult, BuildDetail, WaitForExecutionOptions, WaitForExecutionResult, WaitStopReason, } from "./inspect.js";
+export { watchExecution, parseSseFrame, parseSseEvent } from "./watch.js";
+export type { WatchExecutionOptions } from "./watch.js";
+export { signal, parseSignalPayload } from "./signal.js";
+export type { SignalOptions, SignalResult } from "./signal.js";
+export { createSchedule, listSchedules, getSchedule, cancelSchedule, previewCron } from "./schedule.js";
+export type { ScheduleKind, ScheduleStatus, SchedulePolicy, CreateScheduleOptions, ListSchedulesOptions, CronPreviewOptions, CronPreview, ScheduleSummary, ScheduleDetail, ScheduleFireRecord, } from "./schedule.js";
+export { assertDeployable, pushHead, cloneRepo, redactCredentials } from "./git.js";
+export type { CloneRepoOptions } from "./git.js";
+export { parseStubFile, STUB_FILE_VERSION } from "./local/stubs.js";
+export type { StubFile, StepStubs, StubResponse } from "./local/stubs.js";
+export { runLocal, runLocalFromDir, STUBS_FILE } from "./local/run-local.js";
+export type { RunLocalOptions, LocalRunResult, LocalRunOutcome, } from "./local/run-local.js";
+export { loadDefinition } from "./local/load.js";
+export type { LoadedDefinition } from "./local/load.js";
+export { LocalStubDispatcher } from "./local/dispatcher.js";
+export type { LocalStepTrace, LogEntry } from "./local/dispatcher.js";

package/dist/esm/index.js

@@ -0,0 +1,21 @@
+export { AgentOperationError } from "./errors.js";
+export { GatewayClient, createClient, DEFAULT_WORKFLOWS_HOST, } from "./client.js";
+export { readConfig, requireConfig, writeConfig, CONFIG_FILE, } from "./config.js";
+export { scaffold, resolveVersions, resolveTemplate, listTemplates, DEFAULT_TEMPLATE, } from "./scaffold.js";
+export { check } from "./check.js";
+export { bundleForDeploy } from "./bundle.js";
+export { link } from "./link.js";
+export { clone } from "./clone.js";
+export { deploy } from "./deploy.js";
+export { run, parseJsonInput } from "./run.js";
+export { SSE_EVENT_TYPES } from "./types.js";
+export { decodeExecutionProjection } from "./decode.js";
+export { inspect, listExecutions, inspectBuild, waitForExecution, isExecutionTerminal, } from "./inspect.js";
+export { watchExecution, parseSseFrame, parseSseEvent } from "./watch.js";
+export { signal, parseSignalPayload } from "./signal.js";
+export { createSchedule, listSchedules, getSchedule, cancelSchedule, previewCron } from "./schedule.js";
+export { assertDeployable, pushHead, cloneRepo, redactCredentials } from "./git.js";
+export { parseStubFile, STUB_FILE_VERSION } from "./local/stubs.js";
+export { runLocal, runLocalFromDir, STUBS_FILE } from "./local/run-local.js";
+export { loadDefinition } from "./local/load.js";
+export { LocalStubDispatcher } from "./local/dispatcher.js";

package/dist/esm/inspect.d.ts

@@ -0,0 +1,40 @@
+import { GatewayClient } from "./client.js";
+import type { ExecutionProjection, ExecutionRef, SseEvent } from "./types.js";
+export interface BuildDetail {
+    id?: string;
+    status: string;
+    error?: unknown;
+}
+export interface InspectOptions {
+    executionId: string;
+}
+export declare function inspect(opts: InspectOptions, client: GatewayClient): Promise<ExecutionProjection>;
+export declare function isExecutionTerminal(status: string): boolean;
+export type WaitStopReason = "terminal" | "needs-signal" | "timeout";
+export interface WaitForExecutionOptions {
+    executionId: string;
+    maxWaitMs?: number;
+    pollMs?: number;
+    autoResumeSignals?: string[];
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    watch?: (opts: {
+        executionId: string;
+        signal?: AbortSignal;
+    }, client: GatewayClient) => AsyncIterable<SseEvent>;
+}
+export interface WaitForExecutionResult {
+    execution: ExecutionProjection;
+    reason: WaitStopReason;
+    done: boolean;
+}
+export declare function waitForExecution(opts: WaitForExecutionOptions, client: GatewayClient): Promise<WaitForExecutionResult>;
+export declare function listExecutions(client: GatewayClient): Promise<ExecutionRef[]>;
+export interface InspectBuildOptions {
+    definitionId: string;
+    buildRunId: string;
+}
+export interface InspectBuildResult {
+    build: BuildDetail;
+}
+export declare function inspectBuild(opts: InspectBuildOptions, client: GatewayClient): Promise<InspectBuildResult>;

package/dist/esm/inspect.js

@@ -0,0 +1,92 @@
+import { decodeExecutionProjection, decodeExecutionRef } from "./decode.js";
+import { watchExecution } from "./watch.js";
+export async function inspect(opts, client) {
+    const raw = await client.get(`/executions/${opts.executionId}`);
+    return decodeExecutionProjection(raw);
+}
+const TERMINAL_STATUSES = new Set([
+    "completed",
+    "failed",
+    "cancelled",
+    "canceled",
+]);
+export function isExecutionTerminal(status) {
+    return TERMINAL_STATUSES.has(status);
+}
+const AUTO_RESUME_PAUSE_SIGNALS = [
+    "models.coding.result",
+    "contentGeneration.video.result",
+];
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function settledResult(execution, autoResume) {
+    if (isExecutionTerminal(execution.status)) {
+        return { reason: "terminal", done: true };
+    }
+    if (execution.status === "paused") {
+        const signal = execution.pausedSignalName ?? null;
+        if (!signal || !autoResume.includes(signal)) {
+            return { reason: "needs-signal", done: false };
+        }
+    }
+    return null;
+}
+export async function waitForExecution(opts, client) {
+    const maxWaitMs = opts.maxWaitMs ?? 45000;
+    const autoResume = opts.autoResumeSignals ?? AUTO_RESUME_PAUSE_SIGNALS;
+    const sleep = opts.sleep ?? defaultSleep;
+    const now = opts.now ?? Date.now;
+    const watch = opts.watch ?? watchExecution;
+    const deadline = now() + maxWaitMs;
+    const read = () => inspect({ executionId: opts.executionId }, client);
+    let execution = await read();
+    let settled = settledResult(execution, autoResume);
+    if (settled)
+        return { execution, ...settled };
+    if (now() >= deadline)
+        return { execution, reason: "timeout", done: false };
+    const abort = new AbortController();
+    const timer = setTimeout(() => abort.abort(), Math.max(0, deadline - now()));
+    timer.unref?.();
+    const events = watch({ executionId: opts.executionId, signal: abort.signal }, client)[Symbol.asyncIterator]();
+    try {
+        for (;;) {
+            const next = await events.next();
+            if (next.done)
+                break;
+            execution = await read();
+            settled = settledResult(execution, autoResume);
+            if (settled)
+                return { execution, ...settled };
+            if (now() >= deadline)
+                return { execution, reason: "timeout", done: false };
+        }
+        if (now() >= deadline)
+            return { execution, reason: "timeout", done: false };
+    }
+    catch {
+    }
+    finally {
+        clearTimeout(timer);
+        await events.return?.(undefined);
+    }
+    let interval = opts.pollMs ?? 1000;
+    for (;;) {
+        const remaining = deadline - now();
+        if (remaining <= 0)
+            return { execution, reason: "timeout", done: false };
+        await sleep(Math.min(interval, remaining));
+        interval = Math.min(interval * 1.5, 5000);
+        execution = await read();
+        settled = settledResult(execution, autoResume);
+        if (settled)
+            return { execution, ...settled };
+    }
+}
+export async function listExecutions(client) {
+    const raw = await client.get("/executions");
+    return Array.isArray(raw) ? raw.map(decodeExecutionRef) : [];
+}
+export async function inspectBuild(opts, client) {
+    const build = await client.get(`/definitions/${opts.definitionId}/builds/${opts.buildRunId}`);
+    return { build };
+}

package/dist/esm/link.d.ts

@@ -0,0 +1,15 @@
+import { GatewayClient } from './client.js';
+export interface DefinitionSummary {
+    id: string;
+    name: string;
+    slug?: string;
+}
+export interface LinkOptions {
+    name: string;
+    create?: boolean;
+}
+export interface LinkResult {
+    definitionId: string;
+    name: string;
+}
+export declare function link(opts: LinkOptions, client: GatewayClient): Promise<LinkResult>;

package/dist/esm/link.js

@@ -0,0 +1,16 @@
+import { AgentOperationError } from './errors.js';
+export async function link(opts, client) {
+    const list = await client.get('/definitions');
+    let def = list.find((d) => d.name === opts.name || d.slug === opts.name);
+    if (!def) {
+        if (!opts.create) {
+            throw new AgentOperationError({
+                code: 'NOT_FOUND',
+                message: `No agent named '${opts.name}'.`,
+                hint: 'Create it with { create: true }, or pass the name of an existing one.',
+            });
+        }
+        def = await client.post('/definitions', { name: opts.name });
+    }
+    return { definitionId: def.id, name: def.name };
+}

package/dist/esm/local/dispatcher.d.ts

@@ -0,0 +1,37 @@
+import { type NextStepDirective, type AgentDefinition } from "@sapiom/agent";
+import { type StepDispatcher, type StepDispatchRequest, type AgentRunnerCore } from "@sapiom/agent-runtime";
+import type { StubFile } from "./stubs.js";
+export interface LogEntry {
+    level: "info" | "warn" | "error" | "debug";
+    msg: string;
+    meta?: Record<string, unknown>;
+}
+export interface LocalStepTrace {
+    step: string;
+    attempt: number;
+    input: unknown;
+    status: "succeeded" | "threw";
+    output?: unknown;
+    directive?: NextStepDirective;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    logs: LogEntry[];
+}
+export declare class LocalStubDispatcher implements StepDispatcher {
+    private readonly definition;
+    private readonly stubs;
+    private core;
+    private maxAttemptsPerStep;
+    private signals;
+    readonly trace: LocalStepTrace[];
+    readonly usedKeysByStep: Map<string, Set<string>>;
+    readonly stubWarnings: Set<string>;
+    constructor(definition: AgentDefinition, stubs: StubFile);
+    setCore(core: AgentRunnerCore): void;
+    setMaxAttempts(max: number): void;
+    setSignals(signals: Map<string, unknown>): void;
+    dispatch(request: StepDispatchRequest): Promise<void>;
+}

package/dist/esm/local/dispatcher.js

@@ -0,0 +1,145 @@
+import { InMemoryContextStore, } from "@sapiom/agent";
+import { parseCorrelationId, STEP_COMPLETION_OUTCOME, } from "@sapiom/agent-runtime";
+import { createStubClient } from "@sapiom/tools/stub";
+export class LocalStubDispatcher {
+    constructor(definition, stubs) {
+        this.definition = definition;
+        this.stubs = stubs;
+        this.core = null;
+        this.signals = new Map();
+        this.trace = [];
+        this.usedKeysByStep = new Map();
+        this.stubWarnings = new Set();
+    }
+    setCore(core) {
+        this.core = core;
+    }
+    setMaxAttempts(max) {
+        this.maxAttemptsPerStep = max;
+    }
+    setSignals(signals) {
+        this.signals = signals;
+    }
+    async dispatch(request) {
+        if (!this.core)
+            throw new Error("LocalStubDispatcher: setCore() was not called");
+        const step = this.definition.steps[request.stepName];
+        if (!step)
+            throw new Error(`LocalStubDispatcher: no step '${request.stepName}' in the definition`);
+        const parsed = parseCorrelationId(request.correlationId);
+        if (!parsed)
+            throw new Error(`LocalStubDispatcher: malformed correlationId '${request.correlationId}'`);
+        const logs = [];
+        const sharedStore = new InMemoryContextStore(request.shared);
+        const overrides = (this.stubs.steps[request.stepName] ?? {});
+        let usedKeys = this.usedKeysByStep.get(request.stepName);
+        if (!usedKeys) {
+            usedKeys = new Set();
+            this.usedKeysByStep.set(request.stepName, usedKeys);
+        }
+        const sapiom = createStubClient({
+            overrides,
+            signals: this.signals,
+            usedKeys,
+            warnings: this.stubWarnings,
+        });
+        const ctx = {
+            executionId: request.executionId,
+            workflowName: request.workflowName,
+            organizationId: request.organizationId,
+            tenantId: request.tenantId,
+            input: request.workflowInput,
+            shared: sharedStore,
+            history: [],
+            attempts: request.attempt,
+            logger: makeLogger(logs),
+            sapiom,
+        };
+        let directive;
+        try {
+            directive = await step.run(request.input, ctx);
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            this.trace.push({
+                step: request.stepName,
+                attempt: request.attempt,
+                input: request.input,
+                status: "threw",
+                error: { name: e.name, message: e.message, stack: e.stack },
+                logs,
+            });
+            await this.core.completeDispatchedStep({
+                protocol: 1,
+                correlationId: request.correlationId,
+                outcome: STEP_COMPLETION_OUTCOME.THREW,
+                error: { name: e.name, message: e.message, stack: e.stack },
+                shared: sharedStore.snapshot(),
+            }, parsed, this.maxAttemptsPerStep);
+            return;
+        }
+        const { output, wire } = splitDirective(directive);
+        this.trace.push({
+            step: request.stepName,
+            attempt: request.attempt,
+            input: request.input,
+            status: "succeeded",
+            output,
+            directive,
+            logs,
+        });
+        const payload = {
+            protocol: 1,
+            correlationId: request.correlationId,
+            outcome: STEP_COMPLETION_OUTCOME.RESULT,
+            result: { output, directive: wire },
+            shared: sharedStore.snapshot(),
+        };
+        await this.core.completeDispatchedStep(payload, parsed, this.maxAttemptsPerStep);
+    }
+}
+function makeLogger(sink) {
+    const at = (level) => (msg, meta) => {
+        sink.push({ level, msg, ...(meta ? { meta } : {}) });
+    };
+    return {
+        info: at("info"),
+        warn: at("warn"),
+        error: at("error"),
+        debug: at("debug"),
+    };
+}
+function splitDirective(d) {
+    switch (d.kind) {
+        case "continue":
+            return {
+                output: d.input,
+                wire: { kind: "continue", stepName: d.stepName, input: d.input },
+            };
+        case "terminate":
+            return {
+                output: d.output,
+                wire: { kind: "terminate", reason: d.reason },
+            };
+        case "fail":
+            return {
+                output: d.output,
+                wire: { kind: "fail", reason: d.reason },
+            };
+        case "pause_until_signal":
+            return {
+                output: d.output,
+                wire: {
+                    kind: "pause_until_signal",
+                    signal: d.signal,
+                    timeoutMs: d.timeoutMs,
+                    resumeStep: d.resumeStep,
+                },
+            };
+        case "retry":
+            return {
+                output: undefined,
+                wire: { kind: "retry", delayMs: d.delayMs, reason: d.reason },
+            };
+    }
+}

package/dist/esm/local/load.d.ts

@@ -0,0 +1,6 @@
+import { type AgentDefinition, type AgentManifest } from '@sapiom/agent';
+export interface LoadedDefinition {
+    definition: AgentDefinition;
+    manifest: AgentManifest;
+}
+export declare function loadDefinition(sourceDir: string): Promise<LoadedDefinition>;

package/dist/esm/local/load.js

@@ -0,0 +1,63 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { buildManifest, isAgentDefinition, agentManifestSchema, } from '@sapiom/agent';
+import * as esbuild from 'esbuild';
+import { AgentOperationError } from '../errors.js';
+const LOCAL_SDK_VERSION = '0.0.0-local';
+export async function loadDefinition(sourceDir) {
+    const entryFile = path.join(sourceDir, 'index.ts');
+    if (!existsSync(entryFile)) {
+        throw new AgentOperationError({
+            code: 'NO_ENTRY',
+            message: `No index.ts found in ${sourceDir}.`,
+            hint: 'Run this from an agent project, or pass its directory.',
+        });
+    }
+    const tmp = mkdtempSync(path.join(tmpdir(), 'sapiom-run-'));
+    const bundlePath = path.join(tmp, 'definition.mjs');
+    try {
+        try {
+            await esbuild.build({
+                entryPoints: [entryFile],
+                outfile: bundlePath,
+                bundle: true,
+                platform: 'node',
+                target: 'node20',
+                format: 'esm',
+                logLevel: 'silent',
+            });
+        }
+        catch (err) {
+            throw new AgentOperationError({
+                code: 'BUNDLE_FAILED',
+                message: 'Failed to bundle the agent.',
+                hint: err instanceof Error ? err.message : String(err),
+            });
+        }
+        const mod = await import(`file://${bundlePath}?t=${Date.now()}`);
+        const defs = Object.values(mod).filter(isAgentDefinition);
+        if (defs.length === 0) {
+            throw new AgentOperationError({
+                code: 'NO_DEFINITION',
+                message: 'No agent was exported from index.ts.',
+                hint: 'Export the result of defineAgent({ … }).',
+            });
+        }
+        if (defs.length > 1) {
+            throw new AgentOperationError({
+                code: 'MULTIPLE_DEFINITIONS',
+                message: 'index.ts exports more than one agent.',
+                hint: 'Export exactly one defineAgent({ … }) result.',
+            });
+        }
+        const definition = defs[0];
+        const sha256 = createHash('sha256').update(readFileSync(bundlePath)).digest('hex');
+        const manifest = agentManifestSchema.parse(buildManifest(definition, { sdkVersion: LOCAL_SDK_VERSION, artifact: { sha256, entryFile: 'definition.mjs' } }));
+        return { definition, manifest };
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}

package/dist/esm/local/run-local.d.ts

@@ -0,0 +1,32 @@
+import type { AgentDefinition, AgentManifest } from "@sapiom/agent";
+import { type LocalStepTrace } from "./dispatcher.js";
+import { type StubFile } from "./stubs.js";
+export declare const STUBS_FILE: string;
+export interface RunLocalOptions {
+    definition: AgentDefinition;
+    manifest: AgentManifest;
+    input?: unknown;
+    stubs?: StubFile;
+    maxAttemptsPerStep?: number;
+}
+export type LocalRunOutcome = "completed" | "failed" | "paused" | "running";
+export interface UnusedStub {
+    step: string;
+    key: string;
+}
+export interface LocalRunResult {
+    outcome: LocalRunOutcome;
+    executionId: string;
+    output?: unknown;
+    error?: unknown;
+    steps: LocalStepTrace[];
+    unusedStubs: UnusedStub[];
+    stubWarnings: string[];
+}
+export declare function runLocal(opts: RunLocalOptions): Promise<LocalRunResult>;
+export declare function runLocalFromDir(opts: {
+    sourceDir: string;
+    input?: unknown;
+    stubs?: StubFile;
+    maxAttemptsPerStep?: number;
+}): Promise<LocalRunResult>;

package/dist/esm/local/run-local.js

@@ -0,0 +1,87 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { DEFAULT_MAX_ATTEMPTS_PER_STEP, InMemoryExecutionStore, NOOP_OBSERVER, AgentRunnerCore, } from "@sapiom/agent-runtime";
+import { AgentOperationError } from "../errors.js";
+import { LocalStubDispatcher } from "./dispatcher.js";
+import { loadDefinition } from "./load.js";
+import { parseStubFile } from "./stubs.js";
+export const STUBS_FILE = path.join(".sapiom-dev", "stubs.json");
+function loadStubsFile(sourceDir) {
+    const file = path.join(sourceDir, STUBS_FILE);
+    if (!existsSync(file))
+        return undefined;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        throw new AgentOperationError({
+            code: "STUBS_INVALID",
+            message: `${STUBS_FILE} is not valid JSON.`,
+            hint: err instanceof Error ? err.message : String(err),
+        });
+    }
+    return parseStubFile(raw);
+}
+const MAX_ADVANCES = 1000;
+export async function runLocal(opts) {
+    const stubs = opts.stubs ?? { version: 1, steps: {} };
+    const max = opts.maxAttemptsPerStep ?? DEFAULT_MAX_ATTEMPTS_PER_STEP;
+    const store = new InMemoryExecutionStore();
+    const dispatcher = new LocalStubDispatcher(opts.definition, stubs);
+    const signals = new Map();
+    dispatcher.setSignals(signals);
+    const core = new AgentRunnerCore({
+        store,
+        dispatcher,
+        observer: NOOP_OBSERVER,
+    });
+    dispatcher.setCore(core);
+    dispatcher.setMaxAttempts(max);
+    const executionId = await core.createExecution(opts.definition.name, opts.definition.entry, opts.input, {
+        manifest: opts.manifest,
+    });
+    let guard = 0;
+    while (guard++ < MAX_ADVANCES) {
+        await core.advance(executionId, max);
+        const row = await store.loadExecution(executionId);
+        if (!row ||
+            row.status === "completed" ||
+            row.status === "failed" ||
+            row.status === "cancelled")
+            break;
+        if (row.status === "paused") {
+            const payload = signals.get(row.pausedSignalCorrelationId ?? "") ?? {};
+            await core.resetForResume(executionId, { fromStepInput: payload });
+        }
+    }
+    const final = await store.loadExecution(executionId);
+    const outcome = final?.status === "cancelled" ? "failed" : (final?.status ?? "running");
+    const unusedStubs = [];
+    for (const [step, used] of dispatcher.usedKeysByStep) {
+        for (const key of Object.keys(stubs.steps[step] ?? {})) {
+            if (!used.has(key))
+                unusedStubs.push({ step, key });
+        }
+    }
+    return {
+        outcome,
+        executionId,
+        output: final?.output,
+        error: final?.error,
+        steps: dispatcher.trace,
+        unusedStubs,
+        stubWarnings: [...dispatcher.stubWarnings],
+    };
+}
+export async function runLocalFromDir(opts) {
+    const { definition, manifest } = await loadDefinition(opts.sourceDir);
+    const stubs = opts.stubs ?? loadStubsFile(opts.sourceDir);
+    return runLocal({
+        definition,
+        manifest,
+        input: opts.input,
+        stubs,
+        maxAttemptsPerStep: opts.maxAttemptsPerStep,
+    });
+}