@minpeter/pss-runtime 0.1.0-next.0 → 0.1.0-next.2

package/README.md

@@ -10,12 +10,31 @@ Minimal, platform-agnostic agent runtime with keyed sessions, synchronized
 ## Core DX
 
 ```ts
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { Agent } from "@minpeter/pss-runtime";
-import { createYourLanguageModel } from "...";
+import { createEnv } from "@t3-oss/env-core";
+import { config as loadEnv } from "dotenv";
+import { z } from "zod";
+
+loadEnv({ path: ".env", quiet: true, override: true });
+const env = createEnv({
+  runtimeEnv: process.env,
+  server: {
+    AI_API_KEY: z.string().trim().min(1),
+    AI_BASE_URL: z.url().trim().default("https://apis.opengateway.ai/v1"),
+    AI_MODEL: z.string().trim().min(1).default("minimax/MiniMax-M2.7"),
+  },
+});
 
-const agent = await Agent.create({
+const provider = createOpenAICompatible({
+  name: "custom",
+  apiKey: env.AI_API_KEY,
+  baseURL: env.AI_BASE_URL,
+});
+
+const agent = new Agent({
   instructions: "Answer briefly.",
-  model: createYourLanguageModel(),
+  model: provider(env.AI_MODEL),
 });
 
 const run = await agent.send("Hello");
@@ -28,22 +47,23 @@ for await (const event of run.events()) {
 boundaries until the events consumer asks for the next event, so callers must
 consume the events for the run to progress. This is what lets code react to
 `turn-start`, `step-start`, and `step-end` before the next model snapshot is
-created. `AgentRun.events()` is single-consumer by design: keep rendering,
-logging, tracing, and continuation policy in the same app-owned loop when those
-concerns must share synchronized boundary control.
+created.
+
+`model` is the single public constructor key for model execution. Pass an AI SDK
+`LanguageModel` for the managed runtime path with `instructions`, `tools`, and
+`subagents`, or pass a custom `RuntimeLlm` function when you want to own the model
+adapter yourself:
 
 ```ts
-const run = await agent.send("Implement the plan.");
-const session = agent.session("default");
+import { Agent, type RuntimeLlm } from "@minpeter/pss-runtime";
 
-for await (const event of run.events()) {
-  renderEvent(event);
-  traceEvent(event);
+const runtimeModel: RuntimeLlm = async ({ history }) => [
+  { role: "assistant", content: `Seen ${history.length} messages.` },
+];
 
-  if (event.type === "step-end" && shouldContinueWork()) {
-    await session.steer("Continue. The task is not complete yet.");
-  }
-}
+const agent = new Agent({
+  model: runtimeModel,
+});
 ```
 
 Per-key conversations use `session(key)`:
@@ -96,17 +116,95 @@ The public transcript protocol is `AgentEvent`: live runs emit runtime-defined
 events through `run.events()`. Provider/model message history is internal
 continuation state, not a public history API.
 
-## Send and Steer
+## Subagents
+
+Compose specialist agents by constructing them first and passing them as an
+array. Top-level agents may omit metadata, but agents used as subagents need a
+stable `name` and `description` so the runtime can expose clear model-facing
+delegate tools.
+
+```ts
+const researcher = new Agent({
+  name: "researcher",
+  description: "Researches facts and returns concise evidence.",
+  model,
+  instructions: "Research facts and return concise evidence.",
+});
+
+const coordinator = new Agent({
+  model,
+  instructions: "Coordinate work and delegate when useful.",
+  subagents: [researcher],
+});
+```
+
+For each subagent, the parent model receives a generated
+`delegate_to_<name>` tool. The tool accepts `prompt`, optional `description`,
+optional `sessionKey` suffix, and `run_in_background`. A provided `sessionKey`
+is always scoped under the parent session and subagent name; the model cannot
+select an arbitrary child session key. Omitting `run_in_background` defaults to
+blocking behavior and returns compact child text, not the full child event
+stream.
+
+```ts
+delegate_to_researcher({
+  prompt: "Find the current release notes and summarize the evidence.",
+});
+```
+
+When the model sets `run_in_background: true`, the parent run can finish while
+the child keeps working. The launch result includes a `bg_...` `task_id` and
+tells the model to wait for a `<system-reminder>` before retrieving output.
+When background work finishes, the session is notified with compact runtime
+input. Hosts that support durable background work should resume the parent session
+through the notification inbox and drain the returned `AgentRun`.
+
+```ts
+delegate_to_researcher({
+  prompt: "Compare the API designs.",
+  run_in_background: true,
+});
+
+// After the completion reminder arrives:
+background_output({ task_id: "bg_...", block: true });
+background_cancel({ task_id: "bg_..." });
+```
+
+The parent model context stays compact by default: completion reminders include
+the task id, subagent name, description, and retrieval instruction. Full child
+traces are not injected into the parent transcript by default. Background jobs
+run in task-scoped child sessions. In-memory job handles are cleaned up after
+completed output retrieval, while durable hosts keep compact completed output
+available through the execution store for reconstructed agents. Background jobs
+launched during the same parent turn share an internal completion barrier:
+successful jobs notify once when the group settles, while failed jobs notify
+immediately.
+
+## Send, Host Resume, and Steer
 
 Use `session.send(input)` for a new user turn. If a run is already active, the
-turn is queued until the active run finishes. Use `session.steer(input)` when the
-input should steer the active run; if no run is active, it starts a normal run.
+turn is queued until the active run finishes. Use `session.steer(input)` when
+the input should steer the active run; if no run is active, it starts a normal
+run.
+
+Durable hosts resume completed background work by writing a notification record
+and calling `agent.resume(notificationRunId)`. The resume call claims the
+notification idempotently through its durable run id and returns one `AgentRun`,
+or `null` when a duplicate queue/alarm delivery already claimed it.
+
+Runtime-originated input is delivered through the host notification inbox and
+internal plugin paths. App code should use `session.send()`, `session.steer()`,
+or `agent.resume(runId)` for host-scheduled durable work.
 
-Both APIs accept the same input shapes: strings, arrays of strings,
+Each accepted call returns one `AgentRun`. Drain that run's `events()` stream to
+observe the turn; each `AgentRun.events()` stream is single-consumer.
+
+Input APIs accept the same input shapes: strings, arrays of strings,
 `{ type: "user-text", text }`, and multipart `{ type: "user-message", content }`
-values. Active steering emits `runtime-input` events. A `runtime-input` is
-runtime/API-originated input mapped internally to the model's user role. It is
-distinct from human-origin `user-text` and `user-message` events.
+values. Active steering and host resume input emit `runtime-input` events. A
+`runtime-input` is runtime/API-originated input mapped internally to the model's
+user role. It is distinct from human-origin `user-text` and `user-message`
+events.
 
 Runtime input windows are tied to synchronized events:
 
@@ -138,204 +236,105 @@ for await (const event of run.events()) {
 pending steering path or, when idle, when a new run is scheduled. It does not wait
 for a later model snapshot.
 
-## Overlay
-
-Use `session.overlay(input)` for turn-scoped model context that should affect
-the next model snapshot without becoming canonical session history. It accepts
-the same input shapes as `send()` and `steer()` and has no options in v0.
-
-Overlay context accepted before the first model inference in a turn is composed
-above the current user prompt. This keeps the current prompt near the bottom of
-the model snapshot while still giving the model fresh runtime context first.
-Overlay context accepted after a model inference has already happened is
-append-only: it is added after the messages that already existed for that turn
-and never moves earlier content around.
-
-```ts
-const session = agent.session("room:123:user:456");
-
-await session.overlay("Current wall-clock time: 2026-06-05T19:00:00Z");
-const run = await session.send("What should I do next?");
-
-for await (const event of run.events()) {
-  if (event.type === "step-end" && needsOneMorePass()) {
-    await session.overlay("Additional constraint: answer in two sentences.");
-  }
-}
-```
-
-Active `step-end` overlays intentionally continue the current turn for one more
-model snapshot, like `step-end` steering, but they are not persisted as
-`runtime-input`. Idle overlays do not start a turn; they queue for the next
-`send()` on that session.
-
-Runs emit `overlay-accepted` when overlay input is accepted and
-`overlay-expired` when the turn-scoped frame is discarded at turn end, abort,
-error, or kill. Overlay text is not written to stored history, not encoded in
-session snapshots, and does not survive session reload.
-
-## Plugins, Session Storage, Memory, And Compaction
+## Session storage and portability
 
 The runtime owns full session state encoding and history compaction semantics.
-Persistence, memory, and compaction are configured through in-process plugins:
-
-```ts
-import { Agent } from "@minpeter/pss-runtime";
-import { compaction, memory, sessions } from "@minpeter/pss-runtime/plugins";
-
-const agent = await Agent.create({
-  model,
-  plugins: [sessions.file(".pss/sessions"), memory(), compaction()],
-});
-```
+Adapters own persistence only through `SessionStore`:
 
-If no persistence plugin is provided, sessions are memory-backed by default.
+Stored session state is an opaque, versioned runtime snapshot for continuation.
+Do not inspect it as a replay log; exact replay should be modeled separately as
+an `AgentEvent` log if that capability is added later.
 
-Reusable middleware belongs in plugins. Plugins can observe turn and step
-lifecycle events and call the scoped `steer` function to insert runtime input at
-the active boundary or the scoped `overlay` function to add turn-scoped
-non-persistent context before the turn ends. Plugin `overlay` is available from
-`turn.before`, `step.before`, and `step.after`; `turn.after` runs after the
-turn-scoped overlay frame is closed and rejects overlay calls. App-level control
-should stay with `run.events()` plus `session.steer()` or `session.overlay()`;
-plugin lifecycle is for reusable policy.
+`SessionStore` is snapshot-only. It does not own background task ids, run
+leases, checkpoints, notification inbox state, or scheduling. Those live on the
+optional `host` execution contract.
 
-Plugin event names are dotted middleware names: `turn.before`, `step.before`,
-`step.after`, `turn.after`, `tool.call`, and `tool.result`. These are separate
-from public `run.events()` transcript names such as `turn-start`, `step-start`,
-`assistant-text`, `tool-call`, `tool-result`, `step-end`, and `turn-end`.
+Custom stores own version generation. `load(key)` returns the opaque `state` with
+the store-minted `version`; `commit(key, { state }, { expectedVersion })` receives
+state only and should reject stale versions by returning `{ ok: false, reason:
+"conflict" }`. On success, the store persists `{ state, version }` and returns the
+new version to the runtime. `delete(key)` removes the persisted session for that
+key.
 
 ```ts
-import { Agent, definePlugin } from "@minpeter/pss-runtime";
-
-const continuePlugin = definePlugin({
-  name: "continue-policy",
-  setup(host) {
-    host.on("step.after", async ({ result, history, overlay, steer, stepIndex }) => {
-      if (result === "completed" && stepIndex === 0 && shouldContinueWork(history)) {
-        await overlay("Continue, but do not persist this policy text.");
-        await steer("Continue. The task is not complete yet.");
-      }
-    });
-  },
-});
+import { MemorySessionStore } from "@minpeter/pss-runtime/session-store/memory";
 
-const agent = await Agent.create({
+const agent = new Agent({
+  host: {
+    sessionStore: new MemorySessionStore(), // default when omitted
+  },
   model,
-  plugins: [continuePlugin],
+  namespace: "support-agent",
 });
 ```
 
-`turn.after` is useful for audit, metrics, or scheduling a separate follow-up
-run after the current turn has committed.
+For durable sessions, use the exported file POC. Set a stable `namespace` when
+subagents also use durable stores, so reconstructed agents map the same parent
+session and child `sessionKey` suffixes back to the same child transcripts:
 
 ```ts
-const auditPlugin = definePlugin({
-  name: "turn-audit",
-  setup(host) {
-    host.on("turn.after", ({ result, sessionKey }) => {
-      recordTurnResult(sessionKey, result);
-    });
-  },
-});
-```
-
-Tool policy hooks apply to runtime-owned tools in the `Agent.create({ model,
-tools })` path, including tools registered by plugins. Custom `llm` callers own
-their tool execution and do not receive synthetic tool hook events.
+import { FileSessionStore } from "@minpeter/pss-runtime/session-store/file";
 
-`tool.call` runs after AI SDK input parsing and before the original tool
-`execute`. Handlers run in plugin registration order. `allow` continues to the
-next handler, `modify` replaces the input for later handlers and execution,
-`reject-and-continue` skips the original tool and returns a rejection payload to
-the model, `synthesize` skips the original tool and returns a synthetic output,
-and `error` fails the active run.
-
-```ts
-import { definePlugin } from "@minpeter/pss-runtime";
-
-const toolPolicyPlugin = definePlugin({
-  name: "tool-policy",
-  setup(host) {
-    host.on("tool.call", ({ input, tool }) => {
-      if (tool === "delete_file") {
-        return {
-          action: "reject-and-continue",
-          message: "delete_file is disabled in this workspace.",
-        };
-      }
-
-      if (tool === "search" && shouldNarrowSearch(input)) {
-        return { action: "modify", input: narrowSearchInput(input) };
-      }
-
-      return { action: "allow" };
-    });
-  },
-});
-```
-
-`tool.result` runs after allowed/modified execution, rejected calls, synthesized
-calls, and original tool errors. It can observe or replace the model-facing
-result with `{ status: "done", output }`, `{ status: "error", error, output }`,
-or `{ status: "cancelled", error, output }`. Replacements flow into later
-`tool.result` handlers.
-
-```ts
-const resultPolicyPlugin = definePlugin({
-  name: "tool-result-policy",
-  setup(host) {
-    host.on("tool.result", ({ output, status, tool }) => {
-      if (tool === "read_secret" && status === "done") {
-        return {
-          status: "done",
-          output: redactSecretOutput(output),
-        };
-      }
-    });
+const agent = new Agent({
+  host: {
+    sessionStore: new FileSessionStore(".pss/sessions"),
   },
+  model,
+  namespace: "support-agent",
 });
 ```
 
-Custom stores still own version generation through `SessionStore`. Use
-`sessions.custom(store)` when the runtime should persist through a caller-owned
-store:
+Hosts that need durable runs pass `host:` into `Agent`. A durable host owns
+execution state, scheduling, and its session snapshot store through
+`store.sessions`; `ExecutionHost` does not accept a separate `sessionStore`
+override.
 
 ```ts
-import type { SessionStore } from "@minpeter/pss-runtime";
-import { sessions } from "@minpeter/pss-runtime/plugins";
+import { Agent } from "@minpeter/pss-runtime";
+import {
+  createInMemoryExecutionHost,
+  type ExecutionHost,
+} from "@minpeter/pss-runtime/execution";
 
-declare const store: SessionStore;
+const host = createInMemoryExecutionHost();
 
-const agent = await Agent.create({
+const agent = new Agent({
+  host,
   model,
-  plugins: [sessions.custom(store)],
+  namespace: "support-agent",
 });
-```
 
-Stored session state is opaque, versioned runtime continuation state:
+const durableHost: ExecutionHost = {
+  capabilities: { backgroundSubagents: "durable" },
+  scheduler,
+  store,
+};
+```
 
-Do not inspect it as a replay log; exact replay should be modeled separately as
-an `AgentEvent` log if that capability is added later.
+## Supported Deployment Shapes
 
-`load(key)` returns the opaque `state` with the store-minted `version`;
-`commit(key, { state }, { expectedVersion })` receives state only and should
-reject stale versions by returning `{ ok: false, reason: "conflict" }`. On
-success, the store persists `{ state, version }` and returns the new version to
-the runtime.
+The runtime supports both long-running Node.js processes and edge hosts that
+reconstruct runtime objects between turns. The same public DX stays centered on
+`new Agent({ subagents: [...] })`; host-specific durability and scheduling live
+behind the `host` boundary.
 
-`memory()` adds session-scoped tools named `set_context`, `load_context`, and
-`search_context`. Search is deterministic lexical matching by default; no
-embedding provider is required. Memory is injected into model-facing context
-without mutating top-level instructions.
+Long-running Node.js can keep an `Agent` and `SessionHandle` alive across turns.
+The default in-memory host advertises in-process background subagent capability,
+so `run_in_background`, `background_output`, and `background_cancel` remain
+available while that process owns the work. `FileSessionStore` persists session
+snapshots only; it does not make background work durable by itself.
 
-`compaction()` stores non-destructive overlays with `startIndex` and `endIndex`.
-The full canonical history remains in the session snapshot; summaries are
-applied only to model-facing context.
+Cloudflare Durable Objects and similar edge hosts should reconstruct `Agent`
+objects per turn and persist opaque session state through `store.sessions`.
+When a host does not advertise background subagent capability, the runtime hides
+background tools from the parent model and exposes blocking delegation only.
+This avoids pretending that in-memory background work survived a hibernation,
+isolate restart, or request deadline.
 
-## Future adapter boundary: Cloudflare multi-user DX
+See `examples/cloudflare-edge-subagent` for an edge-hosted turn loop with a
+Worker/Durable Object-shaped host, and `examples/subagent` for a long-running
+local background subagent flow.
 
-Cloudflare Durable Objects are a future adapter target, not a runtime dependency.
 The same core API supports room/user/session routing through stable session keys.
 
 Recommended key patterns:
@@ -344,6 +343,39 @@ Recommended key patterns:
 - Per-user memory inside room: `room:<roomId>:user:<userId>`
 - Ticketed workspace flows: `tenant:<tenantId>:ticket:<ticketId>`
 
-In a Durable Object, map the `SessionStore` contract to `ctx.storage` so DO storage is
-durable across hibernation/restores, while in-memory state remains request-local.
-Do not store canonical agent session state in memory attachments.
+In a Durable Object, map the execution store contract to `ctx.storage` so DO
+storage is durable across hibernation/restores, while in-memory state remains
+request-local. Do not store canonical agent session or run state in memory
+attachments.
+
+Durable background subagents require a host capability that owns task ids,
+attempts, leases, checkpoints, cancellation, scheduling, and completion
+notifications. The Cloudflare edge example includes a Worker/Durable
+Object-shaped host that persists scheduled runs and session prompts, sets alarms, and
+resumes work through `Agent.resume(...)`.
+
+## Checkpoints and Cancellation
+
+Resume is safe only at committed boundaries. Durable hosts can checkpoint before
+and after model steps, around notifications, before child run creation, when a
+child link is committed, and when a run suspends. If a process is killed inside a
+provider call or unsafe tool execution, resume rolls back to the last committed
+checkpoint and may re-enter the operation.
+
+When `Agent` receives an `ExecutionHost`, high-level model turns create a
+`user-turn` run record and thread tool execution context into managed model
+calls. Tools are checkpointed before and after execution and receive stable
+`attempt`, `idempotencyKey`, `retryPolicy`, `signal`, and public `toolCallId`
+values. The `@minpeter/pss-runtime/execution` entrypoint also exposes the same
+low-level tool execution checkpoint types for custom resume runners built
+directly on `createLlm`.
+
+These checkpoints are rollback boundaries, not a complete host adapter by
+themselves. Edge hosts still need durable scheduling, leases, resume workers,
+and notification resume handling; externally visible side-effect tools still need
+idempotent execution or a manual recovery flow.
+
+Cancellation is persisted before aborting active work. Parent `delete()` and
+`kill()` mark linked child runs as `cancelled` through the execution store before
+falling back to process-local cleanup, so stale child completions cannot enqueue
+new parent notifications.

package/dist/agent-child-runs.js

@@ -0,0 +1,16 @@
+import { executionHost } from "./execution/host.js";
+import { cancelBackgroundChildRun } from "./subagent-background-child-run.js";
+//#region src/agent-child-runs.ts
+async function cancelDurableChildRuns(host, parentRunId) {
+	const durableHost = executionHost(host);
+	if (!durableHost) return;
+	const childRuns = await durableHost.store.runs.listByParentRunId(parentRunId);
+	await Promise.all(childRuns.map((run) => cancelBackgroundChildRun({
+		executionHost: durableHost,
+		runId: run.runId
+	})));
+}
+//#endregion
+export { cancelDurableChildRuns };
+
+//# sourceMappingURL=agent-child-runs.js.map

package/dist/agent-child-runs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-child-runs.js","names":[],"sources":["../src/agent-child-runs.ts"],"sourcesContent":["import { executionHost } from \"./execution/host\";\nimport type { AgentHost } from \"./execution/types\";\nimport { cancelBackgroundChildRun } from \"./subagent-background-child-run\";\n\nexport async function cancelDurableChildRuns(\n  host: AgentHost,\n  parentRunId: string\n): Promise<void> {\n  const durableHost = executionHost(host);\n  if (!durableHost) {\n    return;\n  }\n\n  const childRuns = await durableHost.store.runs.listByParentRunId(parentRunId);\n  await Promise.all(\n    childRuns.map((run) =>\n      cancelBackgroundChildRun({\n        executionHost: durableHost,\n        runId: run.runId,\n      })\n    )\n  );\n}\n"],"mappings":";;;AAIA,eAAsB,uBACpB,MACA,aACe;CACf,MAAM,cAAc,cAAc,IAAI;CACtC,IAAI,CAAC,aACH;CAGF,MAAM,YAAY,MAAM,YAAY,MAAM,KAAK,kBAAkB,WAAW;CAC5E,MAAM,QAAQ,IACZ,UAAU,KAAK,QACb,yBAAyB;EACvB,eAAe;EACf,OAAO,IAAI;CACb,CAAC,CACH,CACF;AACF"}

package/dist/agent-host-capabilities.js

@@ -0,0 +1,9 @@
+//#region src/agent-host-capabilities.ts
+function supportsBackgroundSubagents(host, executionHost) {
+	const capability = host.capabilities?.backgroundSubagents;
+	return capability === "in-process" || capability === "durable" && executionHost !== void 0;
+}
+//#endregion
+export { supportsBackgroundSubagents };
+
+//# sourceMappingURL=agent-host-capabilities.js.map

package/dist/agent-host-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-host-capabilities.js","names":[],"sources":["../src/agent-host-capabilities.ts"],"sourcesContent":["import type { AgentHost, ExecutionHost } from \"./execution/types\";\n\nexport function supportsBackgroundSubagents(\n  host: AgentHost,\n  executionHost: ExecutionHost | undefined\n): boolean {\n  const capability = host.capabilities?.backgroundSubagents;\n  return (\n    capability === \"in-process\" ||\n    (capability === \"durable\" && executionHost !== undefined)\n  );\n}\n"],"mappings":";AAEA,SAAgB,4BACd,MACA,eACS;CACT,MAAM,aAAa,KAAK,cAAc;CACtC,OACE,eAAe,gBACd,eAAe,aAAa,kBAAkB,KAAA;AAEnD"}

package/dist/agent-host-session-store.js

@@ -0,0 +1,12 @@
+import { executionHost } from "./execution/host.js";
+import { MemorySessionStore } from "./session/store/memory.js";
+//#region src/agent-host-session-store.ts
+function sessionStoreForHost(host) {
+	if ("sessionStore" in host && host.sessionStore) return host.sessionStore;
+	const hostExecution = executionHost(host);
+	return hostExecution ? hostExecution.store.sessions : new MemorySessionStore();
+}
+//#endregion
+export { sessionStoreForHost };
+
+//# sourceMappingURL=agent-host-session-store.js.map

package/dist/agent-host-session-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-host-session-store.js","names":[],"sources":["../src/agent-host-session-store.ts"],"sourcesContent":["import { executionHost } from \"./execution/host\";\nimport type { AgentHost } from \"./execution/types\";\nimport { MemorySessionStore } from \"./session/store/memory\";\nimport type { SessionStore } from \"./session/store/types\";\n\nexport function sessionStoreForHost(host: AgentHost): SessionStore {\n  if (\"sessionStore\" in host && host.sessionStore) {\n    return host.sessionStore;\n  }\n\n  const hostExecution = executionHost(host);\n  return hostExecution\n    ? hostExecution.store.sessions\n    : new MemorySessionStore();\n}\n"],"mappings":";;;AAKA,SAAgB,oBAAoB,MAA+B;CACjE,IAAI,kBAAkB,QAAQ,KAAK,cACjC,OAAO,KAAK;CAGd,MAAM,gBAAgB,cAAc,IAAI;CACxC,OAAO,gBACH,cAAc,MAAM,WACpB,IAAI,mBAAmB;AAC7B"}