@sapiom/agent-core 0.6.0

package/templates/coding-pause/AGENTS.md

@@ -0,0 +1,48 @@
+# Working in this orchestration
+
+This project defines exactly one Sapiom orchestration in `index.ts`, authored against `@sapiom/agent`. Inside a step's `run`, Sapiom capabilities are on `ctx.sapiom` (e.g. `ctx.sapiom.repositories.list()`, `repo.pushFromSandbox(...)`).
+
+## Authoring
+
+- An orchestration is `defineAgent({ entry, steps })`; each step is `defineStep({ name, next, run })`. Keep exactly one `defineAgent(...)` export.
+- **Capabilities come from the types.** What's available on `ctx.sapiom` is defined by `@sapiom/tools` — read the types / use autocomplete rather than guessing. A wrong capability or method name fails typecheck.
+
+## Validating
+
+When you've made a coherent change and want to validate it — the same point you'd run tests in any project — this project ships a near-complete local suite. Reach for it then; you don't need to run it after every small edit.
+
+- **`npm run typecheck`** — types, and confirms every `ctx.sapiom.*` capability/method you used exists.
+- **check** — typecheck + bundle + manifest + step-graph validation. The full local pre-flight before deploy.
+- **run_local** — runs your **real** step code locally against **stub capabilities**: every `ctx.sapiom.*` call (namespace calls *and* handle methods like `repo.pushFromSandbox`) returns a built-in default, so a workflow runs end-to-end with zero setup. Returns a per-step trace.
+- **deploy** — ship it.
+
+> Write each step the way it should run in production. `run_local` adapts to your code (stub capabilities), not the other way around — never weaken or drop real logic to shape a local run.
+
+## Stubs (overrides)
+
+`run_local` works with **no stubs** — capabilities return sensible defaults. Add an override only when a step's logic branches on a specific result (e.g. "if `repositories.list()` already contains my repo, skip create"). Put overrides in `.sapiom-dev/stubs.json` (committed and human-reviewable); `run_local` reads it automatically. Shape:
+
+```jsonc
+{ "version": 1, "steps": { "<stepName>": { "<capability.path>": <response> } } }
+```
+
+- Capability paths are namespace methods (`repositories.list`, `repositories.create`, `agent.coding.run`) or handle methods, which use the **singular** handle type (`repository.pushFromSandbox`, `sandbox.exec`) — not the plural namespace.
+- `<response>` is returned **verbatim** — it is the value that call would return, so match its real shape. `repositories.list` takes the array `list()` returns: `[{ "slug": "...", "cloneUrl": "..." }]` (each element a repository — *not* `[[ … ]]`). `repositories.create`/`get`/`attach` take a single `{ "slug", "cloneUrl" }`.
+- `run_local` reports **`unusedStubs`** (a key that matched no call — usually a typo or the plural/singular mistake) and **`stubWarnings`** (a key matched but the value was the wrong shape). A green run with either non-empty means a stub silently didn't take effect — check them.
+
+## Dispatched runs: pause & resume
+
+A long-running capability (today the coding agent) is launched fire-and-forget and the workflow suspends until it finishes:
+
+```ts
+const run = await ctx.sapiom.models.coding.launch({ task, gitRepository: repo }); // returns a handle, not a result
+return pauseUntilSignal(run, { resumeStep: "finalize" });                         // suspend on the run's result signal
+```
+
+- **The resumed step's `input` IS the run's result signal payload.** Annotate it with `CodingResultPayload` (from `@sapiom/tools`) — you don't have to hand-roll the shape.
+- That payload crossed a wire boundary, so it carries **no live handles** — to act on the run's sandbox, re-attach one from **`executionEnvironment`** with `ctx.sapiom.sandboxes.attach(result.executionEnvironment.id)` (`executionEnvironment` is `null` when the run provisioned none, e.g. a launch failure). Anything else the resumed step needs, stash in `ctx.shared` before pausing.
+- **To stub the resume payload** (e.g. to exercise the failure branch), override `agent.coding.run` *in the launching step* — that one value is both the `run()` result and the payload the paused step resumes with. `agent.coding.launch` is accepted there too.
+
+## Determinism
+
+A step body runs **once** on the happy path; it re-runs only on retry (after a throw). Don't rely on a value being recomputed identically across a pause/resume — capture non-deterministic values (timestamps, ids) once and pass them forward via the `goto(...)` input or `ctx.shared`.

package/templates/coding-pause/CLAUDE.md

@@ -0,0 +1,7 @@
+# Working in this orchestration
+
+Follow [AGENTS.md](./AGENTS.md) for authoring and validation.
+
+This project ships a near-complete local suite — `npm run typecheck`, the **check** tool (typecheck + bundle + manifest + graph), and **run_local** (runs your real step code against stub capabilities, including handle methods like `repo.pushFromSandbox`). Reach for it when you'd normally validate a change (not after every small edit), and rely on `check` / `typecheck` to confirm the `ctx.sapiom.*` capabilities you used exist.
+
+`run_local` works with no stubs (capabilities return defaults); add overrides in `.sapiom-dev/stubs.json` only for results a step branches on. Write each step the way it should run in production — never weaken or drop real logic to shape a local run.

package/templates/coding-pause/README.md

@@ -0,0 +1,53 @@
+# __PROJECT_NAME__
+
+A Sapiom orchestration that runs a **coding agent without blocking the workflow**:
+it launches the agent fire-and-forget, suspends on the run's result signal, and
+resumes once the run finishes — authored as code against
+[`@sapiom/agent`](https://www.npmjs.com/package/@sapiom/agent).
+
+```
+prepare → kickoff ──pause(models.coding.result)──▶ finalize
+```
+
+- **kickoff** calls `agent.coding.launch(...)` (which returns a handle, *not* a
+  result) and returns `pauseUntilSignal(handle, { resumeStep: "finalize" })`. The
+  workflow suspends — a long run holds no worker.
+- **finalize** is resumed by the engine when the run reaches a terminal state.
+  Its `input` **is** the run's result signal payload (typed `CodingResultPayload`).
+  Because that payload crossed the pause/resume boundary, `sandbox` is plain data
+  — re-attach a live handle with `ctx.sapiom.sandboxes.attach(name)` to push.
+
+State that must survive the pause goes in `ctx.shared`. To test the **failure**
+branch locally, stub a failed result under the *launching* step in
+`.sapiom-dev/stubs.json` — that value is also the resume payload:
+
+```jsonc
+{ "version": 1, "steps": { "kickoff": { "agent.coding.launch": { "status": "failed", "result": { "success": false }, "error": { "stage": "run", "message": "…" } } } } }
+```
+
+## Getting started
+
+```sh
+npm install
+```
+
+Then open `index.ts`. The orchestration is defined with `defineAgent({ steps })`; each step is a `defineStep({ name, next, run })`. The `run` body is ordinary code — and inside it, the full Sapiom tool catalog is available, pre-auth'd and tenant-scoped, on `ctx.sapiom`:
+
+```ts
+const box = await ctx.sapiom.sandboxes.create({ name: 'demo' });
+const repo = await ctx.sapiom.repositories.create('my-repo');
+```
+
+No credentials to wire — a per-execution tenant credential is injected when your orchestration runs.
+
+## The loop
+
+Author and run this orchestration with the Sapiom dev tools:
+
+- **check** — validate locally (bundle, manifest, step graph). Offline.
+- **run_local** — execute the steps locally against stubs (no real capability calls), iterating until it completes.
+- **deploy** — build and ship.
+
+`npm run typecheck` and `npm run format` are also available for editor-level checks.
+
+See `AGENTS.md` for the full authoring loop.

package/templates/coding-pause/_gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+*.tsbuildinfo

package/templates/coding-pause/index.ts

@@ -0,0 +1,109 @@
+import {
+  defineAgent,
+  defineStep,
+  goto,
+  terminate,
+  fail,
+  pauseUntilSignal,
+} from "@sapiom/agent";
+import { CODING_RESULT_SIGNAL, type CodingResultPayload } from "@sapiom/tools";
+
+/**
+ * __PROJECT_NAME__ — a non-blocking coding-agent workflow.
+ *
+ *   prepare → kickoff ──pause(models.coding.result)──▶ finalize
+ *
+ * `kickoff` *launches* the coding agent (fire-and-forget) and returns
+ * `pauseUntilSignal(handle, …)`, suspending the workflow on the run's result
+ * signal — so a long run holds no worker. When the run reaches a terminal state
+ * the engine resumes `finalize` with the run result as its input.
+ *
+ * Key idea: the resumed step's `input` IS the signal payload (typed here as
+ * `CodingResultPayload`). It crossed a wire boundary, so there are no live
+ * handles — re-attach the run's sandbox from `executionEnvironment` with
+ * `ctx.sapiom.sandboxes.attach(executionEnvironment.id)`. Anything else the
+ * resumed step needs is stashed in `ctx.shared` before pausing.
+ */
+
+const REPO_SLUG = "__PROJECT_NAME__-notes";
+
+interface Shared extends Record<string, unknown> {
+  slug: string;
+  cloneUrl: string;
+}
+
+/** Find the repo, or create it on the first run. */
+const prepare = defineStep({
+  name: "prepare",
+  next: ["kickoff"],
+  async run(_input, ctx) {
+    const existing = await ctx.sapiom.repositories.list();
+    const repo =
+      existing.find((r) => r.slug === REPO_SLUG) ??
+      (await ctx.sapiom.repositories.create(REPO_SLUG));
+    ctx.shared.set("slug", repo.slug);
+    ctx.shared.set("cloneUrl", repo.cloneUrl);
+    return goto("kickoff", {});
+  },
+});
+
+/** Launch the agent and suspend until it finishes — do NOT await the run. */
+const kickoff = defineStep({
+  name: "kickoff",
+  next: [],
+  pause: { signal: CODING_RESULT_SIGNAL, resumeStep: "finalize" },
+  async run(_input, ctx) {
+    const repo = ctx.sapiom.repositories.attach(
+      ctx.shared.get("slug") as string,
+      ctx.shared.get("cloneUrl") as string,
+    );
+    const run = await ctx.sapiom.models.coding.launch({
+      task: "Make a small, self-contained change to this repository and commit it.",
+      gitRepository: repo, // auto-cloned into the sandbox at /workspace/<slug>
+    });
+    ctx.logger.info("agent launched; suspending until it finishes", {
+      runId: run.runId,
+    });
+    return pauseUntilSignal(run, { resumeStep: "finalize" });
+  },
+});
+
+/** Resumed once the run is done. The `input` is the coding result payload. */
+const finalize = defineStep({
+  name: "finalize",
+  next: [],
+  terminal: true,
+  canFail: true,
+  async run(run: CodingResultPayload, ctx) {
+    if (run.status !== "completed" || !run.result?.success) {
+      return fail(
+        `coding agent did not succeed: ${run.error?.message ?? run.status}`,
+      );
+    }
+    // Re-attach live handles from plain values, then publish the agent's work.
+    const repo = ctx.sapiom.repositories.attach(
+      ctx.shared.get("slug") as string,
+      ctx.shared.get("cloneUrl") as string,
+    );
+    const env = run.executionEnvironment;
+    if (!env) {
+      return fail("coding run did not provision an execution environment");
+    }
+    const sandbox = ctx.sapiom.sandboxes.attach(env.id);
+    const push = await repo.pushFromSandbox(sandbox, {
+      message: "chore: automated change",
+    });
+    return terminate({
+      runId: run.runId,
+      pushed: push.pushed,
+      sha: push.sha,
+      summary: run.summary,
+    });
+  },
+});
+
+export const agent = defineAgent<unknown, Shared>({
+  name: "__PROJECT_NAME__",
+  entry: "prepare",
+  steps: { prepare, kickoff, finalize },
+});

package/templates/coding-pause/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write \"**/*.ts\"",
+    "format:check": "prettier --check \"**/*.ts\""
+  },
+  "dependencies": {
+    "@sapiom/agent": "__AGENT_VERSION__",
+    "@sapiom/tools": "__TOOLS_VERSION__",
+    "zod": "__ZOD_VERSION__"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.30",
+    "prettier": "^3.2.5",
+    "typescript": "^5.4.2"
+  }
+}

package/templates/coding-pause/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "target": "es2022",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "noEmit": true
+  },
+  "include": ["**/*.ts"]
+}

package/templates/default/AGENTS.md

@@ -0,0 +1,48 @@
+# Working in this orchestration
+
+This project defines exactly one Sapiom orchestration in `index.ts`, authored against `@sapiom/agent`. Inside a step's `run`, Sapiom capabilities are on `ctx.sapiom` (e.g. `ctx.sapiom.repositories.list()`, `repo.pushFromSandbox(...)`).
+
+## Authoring
+
+- An orchestration is `defineAgent({ entry, steps })`; each step is `defineStep({ name, next, run })`. Keep exactly one `defineAgent(...)` export.
+- **Capabilities come from the types.** What's available on `ctx.sapiom` is defined by `@sapiom/tools` — read the types / use autocomplete rather than guessing. A wrong capability or method name fails typecheck.
+
+## Validating
+
+When you've made a coherent change and want to validate it — the same point you'd run tests in any project — this project ships a near-complete local suite. Reach for it then; you don't need to run it after every small edit.
+
+- **`npm run typecheck`** — types, and confirms every `ctx.sapiom.*` capability/method you used exists.
+- **check** — typecheck + bundle + manifest + step-graph validation. The full local pre-flight before deploy.
+- **run_local** — runs your **real** step code locally against **stub capabilities**: every `ctx.sapiom.*` call (namespace calls *and* handle methods like `repo.pushFromSandbox`) returns a built-in default, so a workflow runs end-to-end with zero setup. Returns a per-step trace.
+- **deploy** — ship it.
+
+> Write each step the way it should run in production. `run_local` adapts to your code (stub capabilities), not the other way around — never weaken or drop real logic to shape a local run.
+
+## Stubs (overrides)
+
+`run_local` works with **no stubs** — capabilities return sensible defaults. Add an override only when a step's logic branches on a specific result (e.g. "if `repositories.list()` already contains my repo, skip create"). Put overrides in `.sapiom-dev/stubs.json` (committed and human-reviewable); `run_local` reads it automatically. Shape:
+
+```jsonc
+{ "version": 1, "steps": { "<stepName>": { "<capability.path>": <response> } } }
+```
+
+- Capability paths are namespace methods (`repositories.list`, `repositories.create`, `agent.coding.run`) or handle methods, which use the **singular** handle type (`repository.pushFromSandbox`, `sandbox.exec`) — not the plural namespace.
+- `<response>` is returned **verbatim** — it is the value that call would return, so match its real shape. `repositories.list` takes the array `list()` returns: `[{ "slug": "...", "cloneUrl": "..." }]` (each element a repository — *not* `[[ … ]]`). `repositories.create`/`get`/`attach` take a single `{ "slug", "cloneUrl" }`.
+- `run_local` reports **`unusedStubs`** (a key that matched no call — usually a typo or the plural/singular mistake) and **`stubWarnings`** (a key matched but the value was the wrong shape). A green run with either non-empty means a stub silently didn't take effect — check them.
+
+## Dispatched runs: pause & resume
+
+A long-running capability (today the coding agent) is launched fire-and-forget and the workflow suspends until it finishes:
+
+```ts
+const run = await ctx.sapiom.models.coding.launch({ task, gitRepository: repo }); // returns a handle, not a result
+return pauseUntilSignal(run, { resumeStep: "finalize" });                         // suspend on the run's result signal
+```
+
+- **The resumed step's `input` IS the run's result signal payload.** Annotate it with `CodingResultPayload` (from `@sapiom/tools`) — you don't have to hand-roll the shape.
+- That payload crossed a wire boundary, so it carries **no live handles** — to act on the run's sandbox, re-attach one from **`executionEnvironment`** with `ctx.sapiom.sandboxes.attach(result.executionEnvironment.id)` (`executionEnvironment` is `null` when the run provisioned none, e.g. a launch failure). Anything else the resumed step needs, stash in `ctx.shared` before pausing.
+- **To stub the resume payload** (e.g. to exercise the failure branch), override `agent.coding.run` *in the launching step* — that one value is both the `run()` result and the payload the paused step resumes with. `agent.coding.launch` is accepted there too.
+
+## Determinism
+
+A step body runs **once** on the happy path; it re-runs only on retry (after a throw). Don't rely on a value being recomputed identically across a pause/resume — capture non-deterministic values (timestamps, ids) once and pass them forward via the `goto(...)` input or `ctx.shared`.

package/templates/default/CLAUDE.md

@@ -0,0 +1,7 @@
+# Working in this orchestration
+
+Follow [AGENTS.md](./AGENTS.md) for authoring and validation.
+
+This project ships a near-complete local suite — `npm run typecheck`, the **check** tool (typecheck + bundle + manifest + graph), and **run_local** (runs your real step code against stub capabilities, including handle methods like `repo.pushFromSandbox`). Reach for it when you'd normally validate a change (not after every small edit), and rely on `check` / `typecheck` to confirm the `ctx.sapiom.*` capabilities you used exist.
+
+`run_local` works with no stubs (capabilities return defaults); add overrides in `.sapiom-dev/stubs.json` only for results a step branches on. Write each step the way it should run in production — never weaken or drop real logic to shape a local run.

package/templates/default/README.md

@@ -0,0 +1,30 @@
+# __PROJECT_NAME__
+
+A Sapiom orchestration, authored as code against [`@sapiom/agent`](https://www.npmjs.com/package/@sapiom/agent).
+
+## Getting started
+
+```sh
+npm install
+```
+
+Then open `index.ts`. The orchestration is defined with `defineAgent({ steps })`; each step is a `defineStep({ name, next, run })`. The `run` body is ordinary code — and inside it, the full Sapiom tool catalog is available, pre-auth'd and tenant-scoped, on `ctx.sapiom`:
+
+```ts
+const box = await ctx.sapiom.sandboxes.create({ name: 'demo' });
+const repo = await ctx.sapiom.repositories.create('my-repo');
+```
+
+No credentials to wire — a per-execution tenant credential is injected when your orchestration runs.
+
+## The loop
+
+Author and run this orchestration with the Sapiom dev tools:
+
+- **check** — validate locally (bundle, manifest, step graph). Offline.
+- **run_local** — execute the steps locally against stubs (no real capability calls), iterating until it completes.
+- **deploy** — build and ship.
+
+`npm run typecheck` and `npm run format` are also available for editor-level checks.
+
+See `AGENTS.md` for the full authoring loop.

package/templates/default/_gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+*.tsbuildinfo

package/templates/default/index.ts

@@ -0,0 +1,26 @@
+import { defineAgent, defineStep, goto, terminate } from '@sapiom/agent';
+
+const start = defineStep({
+  name: 'start',
+  next: ['finish'],
+  async run(input, ctx) {
+    ctx.logger.info('starting', { input });
+    // Sapiom capabilities: ctx.sapiom.sandboxes.create(), ctx.sapiom.repositories.create()
+    return goto('finish', { greeting: 'hello from Sapiom' });
+  },
+});
+
+const finish = defineStep({
+  name: 'finish',
+  next: [],
+  terminal: true,
+  async run() {
+    return terminate({ done: true });
+  },
+});
+
+export const agent = defineAgent({
+  name: '__PROJECT_NAME__',
+  entry: 'start',
+  steps: { start, finish },
+});

package/templates/default/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write \"**/*.ts\"",
+    "format:check": "prettier --check \"**/*.ts\""
+  },
+  "dependencies": {
+    "@sapiom/agent": "__AGENT_VERSION__",
+    "@sapiom/tools": "__TOOLS_VERSION__",
+    "zod": "__ZOD_VERSION__"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.30",
+    "prettier": "^3.2.5",
+    "typescript": "^5.4.2"
+  }
+}

package/templates/default/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "target": "es2022",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "noEmit": true
+  },
+  "include": ["**/*.ts"]
+}