@sapiom/orchestration-core 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @sapiom/orchestration-core
 
+## 0.3.0
+
+### Minor Changes
+
+- e17b2d1: `scaffold` now initializes a git repository with an initial commit, so a freshly scaffolded project is immediately deployable (deploy requires a repo with at least one commit). Best-effort: if `git` is unavailable the project is left uninitialized. `ScaffoldResult` gains `gitInitialized`.
+
+  Adds `waitForExecution` (and `isExecutionTerminal`) to poll an execution until it reaches a terminal state, settles on a pause that needs a signal, or a wait budget elapses — so callers don't hand-roll a poll loop. The `sapiom_dev_orchestrations_inspect` MCP tool gains opt-in `wait` / `maxWaitSeconds` options that use it and return `done` / `waiting` / `hint`; a non-blocking inspect of a still-running execution now also hints to use `wait`.
+
+  Fixes `sapiom_dev_orchestrations_link`: omitting `name` no longer sends an empty name (which the gateway rejected). It now defaults to the orchestration's name read from `index.ts` (matching `defineOrchestration({ name })`), and returns a clear error if no name is available.
+
+### Patch Changes
+
+- e17b2d1: **BREAKING (`@sapiom/tools`):** align the coding-run resume payload with the shape a resumed step actually receives. `CodingResultPayload` now carries `executionEnvironment: { type, id } | null` instead of `sandbox: { name, workspaceRoot }`. Re-attach a resumed run's sandbox with `ctx.sapiom.sandboxes.attach(result.executionEnvironment.id)` (for a `blaxel_sandbox`).
+
+  Adds `codingResultSchema` (runtime validation of the resume payload), `toResumePayload`, `ExecutionEnvironmentRef`, and `EXECUTION_ENVIRONMENT_BLAXEL_SANDBOX`. The stub client now emits the same payload shape a resumed step receives, so a step written against the local loop runs identically once deployed.
+
+  The `coding-pause` template and its guidance are updated to the new shape.
+
+- Updated dependencies [e17b2d1]
+  - @sapiom/tools@0.4.0
+  - @sapiom/orchestration@0.1.8
+
 ## 0.2.0
 
 ### Minor Changes

package/dist/cjs/index.d.ts

@@ -1,29 +1,29 @@
-export { OrchestrationError } 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 } 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 { link } from './link.js';
-export type { LinkOptions, LinkResult, DefinitionSummary } from './link.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 { inspect, listExecutions, inspectBuild } from './inspect.js';
-export type { InspectOptions, InspectResult, ListExecutionsResult, InspectBuildOptions, InspectBuildResult, ExecutionDetail, StepRecord, BuildDetail, } from './inspect.js';
-export { signal, parseSignalPayload } from './signal.js';
-export type { SignalOptions, SignalResult } from './signal.js';
-export { assertDeployable, pushHead } 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';
+export { OrchestrationError } 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 } 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 { link } from "./link.js";
+export type { LinkOptions, LinkResult, DefinitionSummary } from "./link.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 { inspect, listExecutions, inspectBuild, waitForExecution, isExecutionTerminal, } from "./inspect.js";
+export type { InspectOptions, InspectResult, ListExecutionsResult, InspectBuildOptions, InspectBuildResult, ExecutionDetail, StepRecord, BuildDetail, WaitForExecutionOptions, WaitForExecutionResult, WaitStopReason, } from "./inspect.js";
+export { signal, parseSignalPayload } from "./signal.js";
+export type { SignalOptions, SignalResult } from "./signal.js";
+export { assertDeployable, pushHead } 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

@@ -1,6 +1,6 @@
 "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.pushHead = exports.assertDeployable = exports.parseSignalPayload = exports.signal = exports.inspectBuild = exports.listExecutions = exports.inspect = exports.parseJsonInput = exports.run = exports.deploy = exports.link = 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.OrchestrationError = void 0;
+exports.LocalStubDispatcher = exports.loadDefinition = exports.STUBS_FILE = exports.runLocalFromDir = exports.runLocal = exports.STUB_FILE_VERSION = exports.parseStubFile = exports.pushHead = exports.assertDeployable = exports.parseSignalPayload = exports.signal = exports.isExecutionTerminal = exports.waitForExecution = exports.inspectBuild = exports.listExecutions = exports.inspect = exports.parseJsonInput = exports.run = exports.deploy = exports.link = 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.OrchestrationError = void 0;
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "OrchestrationError", { enumerable: true, get: function () { return errors_js_1.OrchestrationError; } });
 var client_js_1 = require("./client.js");
@@ -31,6 +31,8 @@ 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 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; } });

package/dist/cjs/inspect.d.ts

@@ -1,4 +1,4 @@
-import { GatewayClient } from './client.js';
+import { GatewayClient } from "./client.js";
 export interface StepRecord {
     stepName: string;
     attempt: number;
@@ -12,6 +12,7 @@ export interface ExecutionDetail {
     id: string;
     status: string;
     currentStep?: string | null;
+    pausedSignalName?: string | null;
     error?: unknown;
     steps?: StepRecord[];
 }
@@ -27,6 +28,22 @@ export interface InspectResult {
     execution: ExecutionDetail;
 }
 export declare function inspect(opts: InspectOptions, client: GatewayClient): Promise<InspectResult>;
+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;
+}
+export interface WaitForExecutionResult {
+    execution: ExecutionDetail;
+    reason: WaitStopReason;
+    done: boolean;
+}
+export declare function waitForExecution(opts: WaitForExecutionOptions, client: GatewayClient): Promise<WaitForExecutionResult>;
 export interface ListExecutionsResult {
     executions: ExecutionDetail[];
 }

package/dist/cjs/inspect.js

@@ -1,14 +1,52 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.inspect = inspect;
+exports.isExecutionTerminal = isExecutionTerminal;
+exports.waitForExecution = waitForExecution;
 exports.listExecutions = listExecutions;
 exports.inspectBuild = inspectBuild;
 async function inspect(opts, client) {
     const execution = await client.get(`/executions/${opts.executionId}`);
     return { execution };
 }
+const TERMINAL_STATUSES = new Set([
+    "completed",
+    "failed",
+    "cancelled",
+    "canceled",
+]);
+function isExecutionTerminal(status) {
+    return TERMINAL_STATUSES.has(status);
+}
+const AUTO_RESUME_PAUSE_SIGNALS = ["agent.coding.result"];
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+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 deadline = now() + maxWaitMs;
+    let interval = opts.pollMs ?? 1000;
+    for (;;) {
+        const { execution } = await inspect({ executionId: opts.executionId }, client);
+        if (isExecutionTerminal(execution.status)) {
+            return { execution, reason: "terminal", done: true };
+        }
+        if (execution.status === "paused") {
+            const signal = execution.pausedSignalName ?? null;
+            if (!signal || !autoResume.includes(signal)) {
+                return { execution, reason: "needs-signal", done: false };
+            }
+        }
+        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);
+    }
+}
 async function listExecutions(client) {
-    const executions = await client.get('/executions');
+    const executions = await client.get("/executions");
     return { executions };
 }
 async function inspectBuild(opts, client) {

package/dist/cjs/scaffold.d.ts

@@ -18,5 +18,6 @@ export interface ScaffoldResult {
     targetDir: string;
     template: string;
     projectName: string;
+    gitInitialized: boolean;
 }
 export declare function scaffold(opts: ScaffoldOptions): Promise<ScaffoldResult>;

package/dist/cjs/scaffold.js

@@ -8,34 +8,37 @@ exports.resolveVersions = resolveVersions;
 exports.listTemplates = listTemplates;
 exports.resolveTemplate = resolveTemplate;
 exports.scaffold = scaffold;
+const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
 const node_url_1 = require("node:url");
 const errors_js_1 = require("./errors.js");
 function resolveModuleDir() {
-    if (typeof __dirname !== 'undefined')
+    if (typeof __dirname !== "undefined")
         return __dirname;
     try {
-        const metaUrl = eval('import.meta.url');
-        if (typeof metaUrl === 'string')
+        const metaUrl = eval("import.meta.url");
+        if (typeof metaUrl === "string")
             return node_path_1.default.dirname((0, node_url_1.fileURLToPath)(metaUrl));
     }
     catch {
     }
-    return '';
+    return "";
 }
 const moduleDir = resolveModuleDir();
 function getTemplatesDir(override) {
-    return override ?? process.env.SAPIOM_TEMPLATES_DIR ?? node_path_1.default.resolve(moduleDir, '..', '..', 'templates');
+    return (override ??
+        process.env.SAPIOM_TEMPLATES_DIR ??
+        node_path_1.default.resolve(moduleDir, "..", "..", "templates"));
 }
-exports.DEFAULT_TEMPLATE = 'default';
-const DOTFILE_NAMES = new Set(['_gitignore', '_npmrc']);
-const REGISTRY = 'https://registry.npmjs.org';
+exports.DEFAULT_TEMPLATE = "default";
+const DOTFILE_NAMES = new Set(["_gitignore", "_npmrc"]);
+const REGISTRY = "https://registry.npmjs.org";
 const VERSION_FALLBACK = {
-    orchestration: '0.1.1',
-    tools: '0.1.1',
+    orchestration: "0.1.1",
+    tools: "0.1.1",
 };
-const ZOD_VERSION = '3.25.76';
+const ZOD_VERSION = "3.25.76";
 async function latestNpmVersion(pkg) {
     try {
         const res = await fetch(`${REGISTRY}/${encodeURIComponent(pkg)}/latest`, {
@@ -44,7 +47,7 @@ async function latestNpmVersion(pkg) {
         if (!res.ok)
             return null;
         const json = (await res.json());
-        return typeof json.version === 'string' ? json.version : null;
+        return typeof json.version === "string" ? json.version : null;
     }
     catch {
         return null;
@@ -52,8 +55,8 @@ async function latestNpmVersion(pkg) {
 }
 async function resolveVersions() {
     const [orchestration, tools] = await Promise.all([
-        latestNpmVersion('@sapiom/orchestration'),
-        latestNpmVersion('@sapiom/tools'),
+        latestNpmVersion("@sapiom/orchestration"),
+        latestNpmVersion("@sapiom/tools"),
     ]);
     return {
         orchestration: orchestration ?? VERSION_FALLBACK.orchestration,
@@ -72,9 +75,11 @@ function resolveTemplate(name, templatesDir) {
     if (!(0, node_fs_1.existsSync)(dir) || !(0, node_fs_1.statSync)(dir).isDirectory()) {
         const available = listTemplates(templatesDir);
         throw new errors_js_1.OrchestrationError({
-            code: 'UNKNOWN_TEMPLATE',
+            code: "UNKNOWN_TEMPLATE",
             message: `Unknown template '${name}'.` +
-                (available.length ? ` Available: ${available.join(', ')}.` : ' No templates are bundled.'),
+                (available.length
+                    ? ` Available: ${available.join(", ")}.`
+                    : " No templates are bundled."),
         });
     }
     return dir;
@@ -82,7 +87,7 @@ function resolveTemplate(name, templatesDir) {
 function applyReplacements(file, replacements) {
     let content;
     try {
-        content = (0, node_fs_1.readFileSync)(file, 'utf8');
+        content = (0, node_fs_1.readFileSync)(file, "utf8");
     }
     catch {
         return;
@@ -111,7 +116,7 @@ function copyTemplate(templateDir, targetDir, replacements) {
     walk(targetDir, (file) => {
         const base = node_path_1.default.basename(file);
         if (DOTFILE_NAMES.has(base)) {
-            const dotted = node_path_1.default.join(node_path_1.default.dirname(file), '.' + base.slice(1));
+            const dotted = node_path_1.default.join(node_path_1.default.dirname(file), "." + base.slice(1));
             (0, node_fs_1.renameSync)(file, dotted);
             applyReplacements(dotted, replacements);
             return;
@@ -119,13 +124,37 @@ function copyTemplate(templateDir, targetDir, replacements) {
         applyReplacements(file, replacements);
     });
 }
+function initGitRepo(dir) {
+    const tryGit = (args) => {
+        try {
+            (0, node_child_process_1.execFileSync)("git", args, { cwd: dir, stdio: "ignore" });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (!tryGit(["init"]))
+        return false;
+    tryGit(["add", "-A"]);
+    return (tryGit(["commit", "-m", "Initial commit"]) ||
+        tryGit([
+            "-c",
+            "user.name=Sapiom",
+            "-c",
+            "user.email=noreply@sapiom.ai",
+            "commit",
+            "-m",
+            "Initial commit",
+        ]));
+}
 async function scaffold(opts) {
     const { targetDir } = opts;
     const template = opts.template ?? exports.DEFAULT_TEMPLATE;
     const projectName = opts.projectName ?? node_path_1.default.basename(targetDir);
     if ((0, node_fs_1.existsSync)(targetDir) && (0, node_fs_1.readdirSync)(targetDir).length > 0) {
         throw new errors_js_1.OrchestrationError({
-            code: 'DIR_NOT_EMPTY',
+            code: "DIR_NOT_EMPTY",
             message: `Target directory '${targetDir}' already exists and is not empty.`,
         });
     }
@@ -138,8 +167,9 @@ async function scaffold(opts) {
         __TOOLS_VERSION__: versions.tools,
         __ZOD_VERSION__: versions.zod,
     });
-    const devDir = node_path_1.default.join(targetDir, '.sapiom-dev');
+    const devDir = node_path_1.default.join(targetDir, ".sapiom-dev");
     (0, node_fs_1.mkdirSync)(devDir, { recursive: true });
-    (0, node_fs_1.writeFileSync)(node_path_1.default.join(devDir, 'stubs.json'), JSON.stringify({ version: 1, steps: {} }, null, 2) + '\n');
-    return { targetDir, template, projectName };
+    (0, node_fs_1.writeFileSync)(node_path_1.default.join(devDir, "stubs.json"), JSON.stringify({ version: 1, steps: {} }, null, 2) + "\n");
+    const gitInitialized = initGitRepo(targetDir);
+    return { targetDir, template, projectName, gitInitialized };
 }

package/dist/esm/index.d.ts

@@ -1,29 +1,29 @@
-export { OrchestrationError } 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 } 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 { link } from './link.js';
-export type { LinkOptions, LinkResult, DefinitionSummary } from './link.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 { inspect, listExecutions, inspectBuild } from './inspect.js';
-export type { InspectOptions, InspectResult, ListExecutionsResult, InspectBuildOptions, InspectBuildResult, ExecutionDetail, StepRecord, BuildDetail, } from './inspect.js';
-export { signal, parseSignalPayload } from './signal.js';
-export type { SignalOptions, SignalResult } from './signal.js';
-export { assertDeployable, pushHead } 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';
+export { OrchestrationError } 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 } 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 { link } from "./link.js";
+export type { LinkOptions, LinkResult, DefinitionSummary } from "./link.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 { inspect, listExecutions, inspectBuild, waitForExecution, isExecutionTerminal, } from "./inspect.js";
+export type { InspectOptions, InspectResult, ListExecutionsResult, InspectBuildOptions, InspectBuildResult, ExecutionDetail, StepRecord, BuildDetail, WaitForExecutionOptions, WaitForExecutionResult, WaitStopReason, } from "./inspect.js";
+export { signal, parseSignalPayload } from "./signal.js";
+export type { SignalOptions, SignalResult } from "./signal.js";
+export { assertDeployable, pushHead } 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

@@ -1,15 +1,15 @@
-export { OrchestrationError } 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 { link } from './link.js';
-export { deploy } from './deploy.js';
-export { run, parseJsonInput } from './run.js';
-export { inspect, listExecutions, inspectBuild } from './inspect.js';
-export { signal, parseSignalPayload } from './signal.js';
-export { assertDeployable, pushHead } 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';
+export { OrchestrationError } 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 { link } from "./link.js";
+export { deploy } from "./deploy.js";
+export { run, parseJsonInput } from "./run.js";
+export { inspect, listExecutions, inspectBuild, waitForExecution, isExecutionTerminal, } from "./inspect.js";
+export { signal, parseSignalPayload } from "./signal.js";
+export { assertDeployable, pushHead } 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

@@ -1,4 +1,4 @@
-import { GatewayClient } from './client.js';
+import { GatewayClient } from "./client.js";
 export interface StepRecord {
     stepName: string;
     attempt: number;
@@ -12,6 +12,7 @@ export interface ExecutionDetail {
     id: string;
     status: string;
     currentStep?: string | null;
+    pausedSignalName?: string | null;
     error?: unknown;
     steps?: StepRecord[];
 }
@@ -27,6 +28,22 @@ export interface InspectResult {
     execution: ExecutionDetail;
 }
 export declare function inspect(opts: InspectOptions, client: GatewayClient): Promise<InspectResult>;
+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;
+}
+export interface WaitForExecutionResult {
+    execution: ExecutionDetail;
+    reason: WaitStopReason;
+    done: boolean;
+}
+export declare function waitForExecution(opts: WaitForExecutionOptions, client: GatewayClient): Promise<WaitForExecutionResult>;
 export interface ListExecutionsResult {
     executions: ExecutionDetail[];
 }

package/dist/esm/inspect.js

@@ -2,8 +2,44 @@ export async function inspect(opts, client) {
     const execution = await client.get(`/executions/${opts.executionId}`);
     return { execution };
 }
+const TERMINAL_STATUSES = new Set([
+    "completed",
+    "failed",
+    "cancelled",
+    "canceled",
+]);
+export function isExecutionTerminal(status) {
+    return TERMINAL_STATUSES.has(status);
+}
+const AUTO_RESUME_PAUSE_SIGNALS = ["agent.coding.result"];
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+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 deadline = now() + maxWaitMs;
+    let interval = opts.pollMs ?? 1000;
+    for (;;) {
+        const { execution } = await inspect({ executionId: opts.executionId }, client);
+        if (isExecutionTerminal(execution.status)) {
+            return { execution, reason: "terminal", done: true };
+        }
+        if (execution.status === "paused") {
+            const signal = execution.pausedSignalName ?? null;
+            if (!signal || !autoResume.includes(signal)) {
+                return { execution, reason: "needs-signal", done: false };
+            }
+        }
+        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);
+    }
+}
 export async function listExecutions(client) {
-    const executions = await client.get('/executions');
+    const executions = await client.get("/executions");
     return { executions };
 }
 export async function inspectBuild(opts, client) {

package/dist/esm/scaffold.d.ts

@@ -18,5 +18,6 @@ export interface ScaffoldResult {
     targetDir: string;
     template: string;
     projectName: string;
+    gitInitialized: boolean;
 }
 export declare function scaffold(opts: ScaffoldOptions): Promise<ScaffoldResult>;