@sapiom/agent-core 0.6.0

package/dist/cjs/deploy.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deploy = deploy;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = __importDefault(require("node:path"));
+const bundle_js_1 = require("./bundle.js");
+const errors_js_1 = require("./errors.js");
+const git_js_1 = require("./git.js");
+const TERMINAL = new Set(['ready', 'failed', 'cancelled', 'superseded']);
+const POLL_DELAYS_MS = [1000, 2000, 3000, 5000, 5000, 8000, 10000];
+const POLL_BUDGET_MS = 300000;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function deploy(opts, client) {
+    const { projectDir, definitionId, branch = 'main' } = opts;
+    (0, git_js_1.assertDeployable)(projectDir);
+    const { code, dependencies } = await (0, bundle_js_1.bundleForDeploy)(projectDir);
+    const { pushUrl } = await client.post(`/definitions/${definitionId}/push-credentials`, {});
+    const treeDir = (0, node_fs_1.mkdtempSync)(node_path_1.default.join((0, node_os_1.tmpdir)(), 'sapiom-deploy-'));
+    try {
+        (0, node_fs_1.writeFileSync)(node_path_1.default.join(treeDir, 'index.ts'), code);
+        (0, node_fs_1.writeFileSync)(node_path_1.default.join(treeDir, 'package.json'), JSON.stringify({ name: 'agent-definition', private: true, type: 'module', dependencies }, null, 2) + '\n');
+        (0, git_js_1.pushSynthesizedTree)(treeDir, pushUrl, branch);
+    }
+    finally {
+        (0, node_fs_1.rmSync)(treeDir, { recursive: true, force: true });
+    }
+    const triggered = await client.post(`/definitions/${definitionId}/builds`, {});
+    const buildRunId = triggered.buildRunId ?? triggered.id;
+    if (!buildRunId) {
+        throw new errors_js_1.AgentOperationError({
+            code: 'BUILD_NO_ID',
+            message: 'The build was triggered but no build id was returned.',
+        });
+    }
+    const final = await pollBuild(client, definitionId, buildRunId);
+    if (final.status !== 'ready') {
+        throw new errors_js_1.AgentOperationError({
+            code: 'BUILD_FAILED',
+            message: `Build ${final.status}.`,
+            step: 'build',
+            hint: final.error?.stack || final.error?.message,
+        });
+    }
+    return { definitionId, buildRunId, status: final.status };
+}
+async function pollBuild(client, definitionId, buildRunId) {
+    let elapsed = 0;
+    let i = 0;
+    while (elapsed < POLL_BUDGET_MS) {
+        const build = await client.get(`/definitions/${definitionId}/builds/${buildRunId}`);
+        if (TERMINAL.has(build.status))
+            return build;
+        const delay = POLL_DELAYS_MS[Math.min(i++, POLL_DELAYS_MS.length - 1)];
+        await sleep(delay);
+        elapsed += delay;
+    }
+    throw new errors_js_1.AgentOperationError({
+        code: 'BUILD_TIMEOUT',
+        message: 'Build did not finish in time.',
+        step: 'build',
+        hint: `Check it later via the logs API for build ${buildRunId}`,
+    });
+}

package/dist/cjs/errors.d.ts

@@ -0,0 +1,15 @@
+export interface StructuredError {
+    code: string;
+    message: string;
+    step?: string;
+    hint?: string;
+    docsUrl?: string;
+}
+export declare class AgentOperationError extends Error {
+    readonly code: string;
+    readonly step?: string;
+    readonly hint?: string;
+    readonly docsUrl?: string;
+    constructor(err: StructuredError);
+    toStructured(): StructuredError;
+}

package/dist/cjs/errors.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentOperationError = void 0;
+class AgentOperationError extends Error {
+    constructor(err) {
+        super(err.message);
+        this.name = 'AgentOperationError';
+        this.code = err.code;
+        this.step = err.step;
+        this.hint = err.hint;
+        this.docsUrl = err.docsUrl;
+    }
+    toStructured() {
+        return {
+            code: this.code,
+            message: this.message,
+            ...(this.step ? { step: this.step } : {}),
+            ...(this.hint ? { hint: this.hint } : {}),
+            ...(this.docsUrl ? { docsUrl: this.docsUrl } : {}),
+        };
+    }
+}
+exports.AgentOperationError = AgentOperationError;

package/dist/cjs/git.d.ts

@@ -0,0 +1,12 @@
+export declare function assertDeployable(dir: string): void;
+export declare function redactCredentials(text: string): string;
+export interface CloneRepoOptions {
+    cloneUrl: string;
+    targetDir: string;
+    branch: string;
+    repoFullName: string;
+    cwd: string;
+}
+export declare function cloneRepo(opts: CloneRepoOptions): void;
+export declare function pushHead(dir: string, pushUrl: string, branch: string): void;
+export declare function pushSynthesizedTree(treeDir: string, pushUrl: string, branch: string): void;

package/dist/cjs/git.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertDeployable = assertDeployable;
+exports.redactCredentials = redactCredentials;
+exports.cloneRepo = cloneRepo;
+exports.pushHead = pushHead;
+exports.pushSynthesizedTree = pushSynthesizedTree;
+const node_child_process_1 = require("node:child_process");
+const errors_js_1 = require("./errors.js");
+function git(args, cwd) {
+    try {
+        return (0, node_child_process_1.execFileSync)('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+    }
+    catch (err) {
+        const stderr = err.stderr?.toString().trim();
+        throw new errors_js_1.AgentOperationError({
+            code: 'GIT',
+            message: `git ${args[0]} failed.`,
+            hint: stderr || (err instanceof Error ? err.message : String(err)),
+        });
+    }
+}
+function assertDeployable(dir) {
+    try {
+        (0, node_child_process_1.execFileSync)('git', ['rev-parse', '--is-inside-work-tree'], { cwd: dir, stdio: 'ignore' });
+    }
+    catch {
+        throw new errors_js_1.AgentOperationError({
+            code: 'NOT_GIT',
+            message: 'Not a git repository.',
+            hint: 'Initialize one: git init && git add -A && git commit -m "init"',
+        });
+    }
+    try {
+        (0, node_child_process_1.execFileSync)('git', ['rev-parse', 'HEAD'], { cwd: dir, stdio: 'ignore' });
+    }
+    catch {
+        throw new errors_js_1.AgentOperationError({
+            code: 'NO_COMMITS',
+            message: 'This repository has no commits yet.',
+            hint: 'Commit your work: git add -A && git commit -m "…"',
+        });
+    }
+}
+function redactCredentials(text) {
+    return text.replace(/(https?:\/\/)[^@\s/]+@/gi, '$1***@');
+}
+function cloneRepo(opts) {
+    const { cloneUrl, targetDir, branch, repoFullName, cwd } = opts;
+    try {
+        (0, node_child_process_1.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 errors_js_1.AgentOperationError({
+            code: 'GIT_CLONE',
+            message: 'git clone failed.',
+            hint: redactCredentials(raw),
+        });
+    }
+    try {
+        git(['remote', 'set-url', 'origin', `https://github.com/${repoFullName}.git`], targetDir);
+    }
+    catch {
+    }
+}
+function pushHead(dir, pushUrl, branch) {
+    git(['push', '--force', pushUrl, `HEAD:${branch}`], dir);
+}
+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/cjs/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/cjs/index.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalStubDispatcher = exports.loadDefinition = exports.STUBS_FILE = exports.runLocalFromDir = exports.runLocal = exports.STUB_FILE_VERSION = exports.parseStubFile = exports.redactCredentials = exports.cloneRepo = exports.pushHead = exports.assertDeployable = exports.previewCron = exports.cancelSchedule = exports.getSchedule = exports.listSchedules = exports.createSchedule = exports.parseSignalPayload = exports.signal = exports.parseSseEvent = exports.parseSseFrame = exports.watchExecution = exports.isExecutionTerminal = exports.waitForExecution = exports.inspectBuild = exports.listExecutions = exports.inspect = exports.decodeExecutionProjection = exports.SSE_EVENT_TYPES = exports.parseJsonInput = exports.run = exports.deploy = exports.clone = exports.link = exports.bundleForDeploy = exports.check = exports.DEFAULT_TEMPLATE = exports.listTemplates = exports.resolveTemplate = exports.resolveVersions = exports.scaffold = exports.CONFIG_FILE = exports.writeConfig = exports.requireConfig = exports.readConfig = exports.DEFAULT_WORKFLOWS_HOST = exports.createClient = exports.GatewayClient = exports.AgentOperationError = void 0;
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "AgentOperationError", { enumerable: true, get: function () { return errors_js_1.AgentOperationError; } });
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "GatewayClient", { enumerable: true, get: function () { return client_js_1.GatewayClient; } });
+Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_js_1.createClient; } });
+Object.defineProperty(exports, "DEFAULT_WORKFLOWS_HOST", { enumerable: true, get: function () { return client_js_1.DEFAULT_WORKFLOWS_HOST; } });
+var config_js_1 = require("./config.js");
+Object.defineProperty(exports, "readConfig", { enumerable: true, get: function () { return config_js_1.readConfig; } });
+Object.defineProperty(exports, "requireConfig", { enumerable: true, get: function () { return config_js_1.requireConfig; } });
+Object.defineProperty(exports, "writeConfig", { enumerable: true, get: function () { return config_js_1.writeConfig; } });
+Object.defineProperty(exports, "CONFIG_FILE", { enumerable: true, get: function () { return config_js_1.CONFIG_FILE; } });
+var scaffold_js_1 = require("./scaffold.js");
+Object.defineProperty(exports, "scaffold", { enumerable: true, get: function () { return scaffold_js_1.scaffold; } });
+Object.defineProperty(exports, "resolveVersions", { enumerable: true, get: function () { return scaffold_js_1.resolveVersions; } });
+Object.defineProperty(exports, "resolveTemplate", { enumerable: true, get: function () { return scaffold_js_1.resolveTemplate; } });
+Object.defineProperty(exports, "listTemplates", { enumerable: true, get: function () { return scaffold_js_1.listTemplates; } });
+Object.defineProperty(exports, "DEFAULT_TEMPLATE", { enumerable: true, get: function () { return scaffold_js_1.DEFAULT_TEMPLATE; } });
+var check_js_1 = require("./check.js");
+Object.defineProperty(exports, "check", { enumerable: true, get: function () { return check_js_1.check; } });
+var bundle_js_1 = require("./bundle.js");
+Object.defineProperty(exports, "bundleForDeploy", { enumerable: true, get: function () { return bundle_js_1.bundleForDeploy; } });
+var link_js_1 = require("./link.js");
+Object.defineProperty(exports, "link", { enumerable: true, get: function () { return link_js_1.link; } });
+var clone_js_1 = require("./clone.js");
+Object.defineProperty(exports, "clone", { enumerable: true, get: function () { return clone_js_1.clone; } });
+var deploy_js_1 = require("./deploy.js");
+Object.defineProperty(exports, "deploy", { enumerable: true, get: function () { return deploy_js_1.deploy; } });
+var run_js_1 = require("./run.js");
+Object.defineProperty(exports, "run", { enumerable: true, get: function () { return run_js_1.run; } });
+Object.defineProperty(exports, "parseJsonInput", { enumerable: true, get: function () { return run_js_1.parseJsonInput; } });
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "SSE_EVENT_TYPES", { enumerable: true, get: function () { return types_js_1.SSE_EVENT_TYPES; } });
+var decode_js_1 = require("./decode.js");
+Object.defineProperty(exports, "decodeExecutionProjection", { enumerable: true, get: function () { return decode_js_1.decodeExecutionProjection; } });
+var inspect_js_1 = require("./inspect.js");
+Object.defineProperty(exports, "inspect", { enumerable: true, get: function () { return inspect_js_1.inspect; } });
+Object.defineProperty(exports, "listExecutions", { enumerable: true, get: function () { return inspect_js_1.listExecutions; } });
+Object.defineProperty(exports, "inspectBuild", { enumerable: true, get: function () { return inspect_js_1.inspectBuild; } });
+Object.defineProperty(exports, "waitForExecution", { enumerable: true, get: function () { return inspect_js_1.waitForExecution; } });
+Object.defineProperty(exports, "isExecutionTerminal", { enumerable: true, get: function () { return inspect_js_1.isExecutionTerminal; } });
+var watch_js_1 = require("./watch.js");
+Object.defineProperty(exports, "watchExecution", { enumerable: true, get: function () { return watch_js_1.watchExecution; } });
+Object.defineProperty(exports, "parseSseFrame", { enumerable: true, get: function () { return watch_js_1.parseSseFrame; } });
+Object.defineProperty(exports, "parseSseEvent", { enumerable: true, get: function () { return watch_js_1.parseSseEvent; } });
+var signal_js_1 = require("./signal.js");
+Object.defineProperty(exports, "signal", { enumerable: true, get: function () { return signal_js_1.signal; } });
+Object.defineProperty(exports, "parseSignalPayload", { enumerable: true, get: function () { return signal_js_1.parseSignalPayload; } });
+var schedule_js_1 = require("./schedule.js");
+Object.defineProperty(exports, "createSchedule", { enumerable: true, get: function () { return schedule_js_1.createSchedule; } });
+Object.defineProperty(exports, "listSchedules", { enumerable: true, get: function () { return schedule_js_1.listSchedules; } });
+Object.defineProperty(exports, "getSchedule", { enumerable: true, get: function () { return schedule_js_1.getSchedule; } });
+Object.defineProperty(exports, "cancelSchedule", { enumerable: true, get: function () { return schedule_js_1.cancelSchedule; } });
+Object.defineProperty(exports, "previewCron", { enumerable: true, get: function () { return schedule_js_1.previewCron; } });
+var git_js_1 = require("./git.js");
+Object.defineProperty(exports, "assertDeployable", { enumerable: true, get: function () { return git_js_1.assertDeployable; } });
+Object.defineProperty(exports, "pushHead", { enumerable: true, get: function () { return git_js_1.pushHead; } });
+Object.defineProperty(exports, "cloneRepo", { enumerable: true, get: function () { return git_js_1.cloneRepo; } });
+Object.defineProperty(exports, "redactCredentials", { enumerable: true, get: function () { return git_js_1.redactCredentials; } });
+var stubs_js_1 = require("./local/stubs.js");
+Object.defineProperty(exports, "parseStubFile", { enumerable: true, get: function () { return stubs_js_1.parseStubFile; } });
+Object.defineProperty(exports, "STUB_FILE_VERSION", { enumerable: true, get: function () { return stubs_js_1.STUB_FILE_VERSION; } });
+var run_local_js_1 = require("./local/run-local.js");
+Object.defineProperty(exports, "runLocal", { enumerable: true, get: function () { return run_local_js_1.runLocal; } });
+Object.defineProperty(exports, "runLocalFromDir", { enumerable: true, get: function () { return run_local_js_1.runLocalFromDir; } });
+Object.defineProperty(exports, "STUBS_FILE", { enumerable: true, get: function () { return run_local_js_1.STUBS_FILE; } });
+var load_js_1 = require("./local/load.js");
+Object.defineProperty(exports, "loadDefinition", { enumerable: true, get: function () { return load_js_1.loadDefinition; } });
+var dispatcher_js_1 = require("./local/dispatcher.js");
+Object.defineProperty(exports, "LocalStubDispatcher", { enumerable: true, get: function () { return dispatcher_js_1.LocalStubDispatcher; } });

package/dist/cjs/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/cjs/inspect.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inspect = inspect;
+exports.isExecutionTerminal = isExecutionTerminal;
+exports.waitForExecution = waitForExecution;
+exports.listExecutions = listExecutions;
+exports.inspectBuild = inspectBuild;
+const decode_js_1 = require("./decode.js");
+const watch_js_1 = require("./watch.js");
+async function inspect(opts, client) {
+    const raw = await client.get(`/executions/${opts.executionId}`);
+    return (0, decode_js_1.decodeExecutionProjection)(raw);
+}
+const TERMINAL_STATUSES = new Set([
+    "completed",
+    "failed",
+    "cancelled",
+    "canceled",
+]);
+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;
+}
+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 ?? watch_js_1.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 };
+    }
+}
+async function listExecutions(client) {
+    const raw = await client.get("/executions");
+    return Array.isArray(raw) ? raw.map(decode_js_1.decodeExecutionRef) : [];
+}
+async function inspectBuild(opts, client) {
+    const build = await client.get(`/definitions/${opts.definitionId}/builds/${opts.buildRunId}`);
+    return { build };
+}

package/dist/cjs/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/cjs/link.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.link = link;
+const errors_js_1 = require("./errors.js");
+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 errors_js_1.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/cjs/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>;
+}