@sapiom/orchestration-core 0.1.1 → 0.3.0

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/orchestration": "__ORCHESTRATION_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

@@ -23,7 +23,26 @@ When you've made a coherent change and want to validate it — the same point yo
 `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> | [<response>, ...] } } }
+{ "version": 1, "steps": { "<stepName>": { "<capability.path>": <response> } } }
 ```
 
-Capability paths are namespace methods (`repositories.list`, `agent.coding.run`) or handle methods (`repository.pushFromSandbox`, `sandbox.exec`). A single value answers every call; an array is consumed one element per call.
+- 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.agent.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`.