@naiba/pi-durable-background-tasks 0.1.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # Pi Durable Background Tasks
 
-Supervised background shell commands for Pi Durable. No delegated agents, model configuration, or implicit model calls.
+Supervised background shell commands for Pi Coding Agent and Pi Durable. Both adapters share one independent process core. No delegated agents, model configuration, or implicit model calls.
 
 **Initial development version. Linux only; requires Python 3.9+ and Linux pidfd support.**
 
@@ -8,12 +8,34 @@ Supervised background shell commands for Pi Durable. No delegated agents, model
 bun add @naiba/pi-durable-background-tasks
 ```
 
+Available on [npm](https://www.npmjs.com/package/@naiba/pi-durable-background-tasks), with GitHub Actions Trusted Publishing and provenance. Node.js 22+ is required; Bun loads the TypeScript source exports, while Node loads the compiled JavaScript.
+
+The host installs the appropriate adapter and owns its lifecycle. This is not an auto-discovered CLI plugin. It does not manage Claude Code or Codex background tasks. All host peer dependencies are optional: importing the core loads neither Pi runtime; importing `./coding-agent` does not load Durable.
+
 ## Usage
 
+For native Pi, install `@earendil-works/pi-coding-agent` (1.5+) and `typebox` (1.4.4+), then add the factory to your `DefaultResourceLoader`:
+
+```ts
+import {BackgroundTasks} from "@naiba/pi-durable-background-tasks";
+import {backgroundTasksExtension} from "@naiba/pi-durable-background-tasks/coding-agent";
+
+const tasks = new BackgroundTasks("/persistent/session/background");
+const extension = backgroundTasksExtension(tasks, "/workspace", {
+  onStart: task => trackOwnedTask(task.id), // optional host delivery bookkeeping
+});
+// Pass extensionFactories: [extension] to DefaultResourceLoader, reload it,
+// createAgentSession with that loader, then await session.bindExtensions(...).
+// Keep normal tool_call approval hooks; await tasks.close() at host shutdown.
+```
+
+For Durable, install `@earendil-works/pi-durable`, `@earendil-works/pi-ai` (1.2+) and `typebox` (1.4.4+). The existing `./pi` entry point remains unchanged:
+
 ```ts
 import {BackgroundTasks} from "@naiba/pi-durable-background-tasks";
 import {backgroundTasksExtension} from "@naiba/pi-durable-background-tasks/pi";
 
+// `registry` is your host's Pi Durable registry.
 const tasks = new BackgroundTasks("/persistent/session/background");
 registry.install(backgroundTasksExtension(tasks, "/workspace"));
 // Register your normal Pi beforeTool approval policy. This package does not bypass it.
@@ -23,7 +45,15 @@ await tasks.close();
 unsubscribe();
 ```
 
-Tools: `background_start`, `background_status`, `background_output`, `background_wait`, `background_stop`.
+| Tool | Input | Purpose |
+| --- | --- | --- |
+| `background_start` | `command`, optional `name` | Start a session-owned shell command |
+| `background_status` | `{}` | List commands and their recorded state |
+| `background_output` | `id`, optional `offset`, `limit` | Read up to 64 KiB using byte offsets |
+| `background_wait` | `id`, `timeout_ms` | Observe completion for a bounded interval |
+| `background_wait_all` | `ids`, `timeout_ms` | Observe 1–100 distinct commands concurrently |
+| `background_stop` | `id` | Stop a command and await supervisor cleanup |
+
 Wait requires `timeout_ms` between 1 and 600000. Observation timeout/cancellation does not stop the command. Commands have no implicit execution deadline.
 
 The core API works without creating a model session. `start` requires a stable `requestId`; repeats return the original record and mismatching arguments are rejected. Recovered records never automatically relaunch a command. Use one service instance per directory and one writer process; concurrent writers are not supported.
@@ -38,6 +68,12 @@ Records and logs survive reopening; live process continuity across host restart
 
 Output reads are bounded to 64 KiB, with byte offsets. Logs are retained without automatic deletion; configure filesystem quotas at the host level. Commands run with inherited environment and host permissions. Do not expose this service directly to untrusted clients; isolate task directories by session and authorize every tool/HTTP action.
 
+## CloudCode integration
+
+[CloudCode](https://github.com/naiba/cloudcode) consumes this npm package for Pi sessions. It provides a collapsed background-activity panel, on-demand logs, explicit stop controls, native Pi approval, and protection against releasing/deleting sessions with active commands. Closing a browser is not host shutdown and does not stop commands.
+
+CloudCode uses the native `./coding-agent` adapter, retaining its host-specific approval, completion delivery and strict log-evidence checks. The package itself has no Web UI and does not automatically resume a model when a command completes. Claude Code and Codex continue to use their own native executors.
+
 ## Development
 
 ```sh
@@ -57,4 +93,4 @@ Releases use `.github/workflows/publish.yml` on pushed `v*` tags, with npm Trust
 - Workflow filename: `publish.yml`
 - Environment: leave empty (the workflow does not declare an environment)
 
-Update `package.json` to a new stable version, refresh `bun.lock` if needed, commit and push, then push the matching tag (for example, `v0.1.1` for version `0.1.1`). The workflow rejects mismatching or prerelease versions, runs type checks, build and process tests, then publishes publicly with provenance. Published versions are immutable: `0.1.0` already exists and must not be republished. Never move a published release tag. There is no manual-dispatch publish path.
+Update `package.json` to a new stable version, refresh `bun.lock` if needed, commit and push, then push the matching tag (for example, `v0.1.2` for version `0.1.2`). The tag-triggered publish workflow first calls the reusable `test.yml` workflow on the same tag. Its publish job uses `needs: test`, so failed or cancelled tests prevent publication. Branch pushes and pull requests also run `test.yml`; tag pushes avoid a redundant standalone test run. After tests succeed, the publish job rejects mismatching or prerelease versions, rebuilds the package, then publishes publicly with provenance. Published versions are immutable: `0.1.0` and `0.1.1` already exist and must not be republished. Never move a published release tag. There is no manual-dispatch publish path.

package/dist/coding-agent.d.ts

@@ -0,0 +1,7 @@
+import { type ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { BackgroundTasks, type BackgroundTask } from "./index.js";
+export interface BackgroundTasksExtensionOptions {
+    /** Called after start, including a deduplicated start. Host owns delivery policy. */
+    onStart?: (task: BackgroundTask) => void | Promise<void>;
+}
+export declare function backgroundTasksExtension(service: BackgroundTasks, cwd: string, options?: BackgroundTasksExtensionOptions): ExtensionFactory;

package/dist/coding-agent.js

@@ -0,0 +1,20 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { waitForBackgroundTasks } from "./index.js";
+// Coding Agent consumes content; Durable consumes output. Separate entry points
+// prevent a native Pi installation from loading the Durable runtime.
+const result = (value) => ({ content: [{ type: "text", text: JSON.stringify(value) }], details: {} });
+export function backgroundTasksExtension(service, cwd, options = {}) {
+    return pi => {
+        pi.registerTool(defineTool({ name: "background_start", label: "Start background command", description: "Start a supervised command and continue independent work. Commands do not survive host loss. Approval belongs to the host tool policy.", parameters: Type.Object({ command: Type.String(), name: Type.Optional(Type.String()) }), execute: async (id, args) => {
+                const task = service.start({ ...args, cwd, requestId: id });
+                await options.onStart?.(task);
+                return result(task);
+            } }));
+        pi.registerTool(defineTool({ name: "background_status", label: "Background status", description: "List session-owned background commands.", parameters: Type.Object({}), execute: async () => result(service.list()) }));
+        pi.registerTool(defineTool({ name: "background_output", label: "Background output", description: "Read bounded background output using byte offsets.", parameters: Type.Object({ id: Type.String(), offset: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 65536 })) }), execute: async (_id, args) => result(await service.output(args.id, args.offset, args.limit)) }));
+        pi.registerTool(defineTool({ name: "background_wait", label: "Wait for command", description: "Observe a command only when no independent work remains. Timeout ends observation, not execution.", parameters: Type.Object({ id: Type.String(), timeout_ms: Type.Integer({ minimum: 1, maximum: 600000 }) }), execute: async (_id, args, signal) => result(await service.wait(args.id, args.timeout_ms, signal)) }));
+        pi.registerTool(defineTool({ name: "background_wait_all", label: "Wait for commands", description: "Observe selected commands concurrently after independent work is finished. Timeout does not stop commands.", parameters: Type.Object({ ids: Type.Array(Type.String(), { minItems: 1, maxItems: 100, uniqueItems: true }), timeout_ms: Type.Integer({ minimum: 1, maximum: 600000 }) }), execute: async (_id, args, signal) => result(await waitForBackgroundTasks(service, args.ids, args.timeout_ms, signal)) }));
+        pi.registerTool(defineTool({ name: "background_stop", label: "Stop command", description: "Stop a session-owned command and reap its descendants.", parameters: Type.Object({ id: Type.String() }), execute: async (_id, args) => result(await service.stop(args.id)) }));
+    };
+}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { waitForBackgroundTasks } from "./wait-all.js";
 export type BackgroundTask = {
     id: string;
     command: string;

package/dist/index.js

@@ -4,6 +4,7 @@ import { open } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
+export { waitForBackgroundTasks } from "./wait-all.js";
 export class BackgroundTasks {
     python;
     records = new Map();

package/dist/pi.d.ts

@@ -1,3 +1,3 @@
-import { Type } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
 import { BackgroundTasks } from "./index.js";
 export declare function backgroundTasksExtension(service: BackgroundTasks, cwd: string): import("@earendil-works/pi-durable").Extension<import("@earendil-works/pi-durable").ToolRegistration<Type.TObject<{}>, import("@earendil-works/chord").JsonValue>>;

package/dist/pi.js

@@ -1,18 +1,23 @@
 import { defineExtension, defineTool } from "@earendil-works/pi-durable";
-import { Type } from "@earendil-works/pi-ai";
-const result = (value) => ({ content: [{ type: "text", text: JSON.stringify(value) }] });
+import { Type } from "typebox";
+import { waitForBackgroundTasks } from "./index.js";
+// Pi 1.2 consumes output; content silently hides task IDs and status from the model.
+const result = (value) => ({ output: [{ type: "text", text: JSON.stringify(value) }] });
 export function backgroundTasksExtension(service, cwd) {
     return defineExtension({ name: "background-tasks", tools: [
-            defineTool({ name: "background_start", description: "Start a supervised background shell command. Returns immediately; no model delegation. Commands do not survive host loss. Approval belongs to the host tool policy.", replay: "unsafe",
+            defineTool({ name: "background_start", description: "Start a supervised background shell command. Returns immediately; continue independent work before checking results. Do not immediately wait when other work is available; no model delegation. Commands do not survive host loss. Approval belongs to the host tool policy.", replay: "unsafe",
                 parameters: Type.Object({ command: Type.String(), name: Type.Optional(Type.String()) }),
                 execute: async (args, api) => result(service.start({ ...args, cwd, requestId: String(api.taskId) })) }),
             defineTool({ name: "background_status", description: "List background commands owned by this session.", replay: "safe", parameters: Type.Object({}), execute: async () => result(service.list()) }),
             defineTool({ name: "background_output", description: "Read bounded background output using byte offsets.", replay: "safe",
                 parameters: Type.Object({ id: Type.String(), offset: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 65536 })) }),
                 execute: async (args) => result(await service.output(args.id, args.offset, args.limit)) }),
-            defineTool({ name: "background_wait", description: "Wait for a background command. Explicit timeout ends observation only, not execution.", replay: "safe",
+            defineTool({ name: "background_wait", description: "Blocking observation of a background command. Use only when the next step requires its result and no independent work remains; otherwise continue working and check status later. Explicit timeout ends observation only, not execution.", replay: "safe",
                 parameters: Type.Object({ id: Type.String(), timeout_ms: Type.Integer({ minimum: 1, maximum: 600000 }) }),
                 execute: async (args, api, ctx) => result(await service.wait(args.id, args.timeout_ms, ctx.abortSignal)) }),
+            defineTool({ name: "background_wait_all", description: "Observe selected commands concurrently after independent work is finished. Timeout does not stop commands.", replay: "safe",
+                parameters: Type.Object({ ids: Type.Array(Type.String(), { minItems: 1, maxItems: 100, uniqueItems: true }), timeout_ms: Type.Integer({ minimum: 1, maximum: 600000 }) }),
+                execute: async (args, api, ctx) => result(await waitForBackgroundTasks(service, args.ids, args.timeout_ms, ctx.abortSignal)) }),
             defineTool({ name: "background_stop", description: "Stop a session-owned command and reap its descendants. Returns after supervisor cleanup.", replay: "unsafe",
                 parameters: Type.Object({ id: Type.String() }), execute: async (args) => result(await service.stop(args.id)) }),
         ] });

package/dist/wait-all.d.ts

@@ -0,0 +1,13 @@
+import type { BackgroundTasks } from "./index.js";
+/** Validate the entire selection before observing; one timeout applies concurrently. */
+export declare function waitForBackgroundTasks(service: Pick<BackgroundTasks, "get" | "wait">, ids: string[], timeout: number, signal?: AbortSignal): Promise<{
+    id: string;
+    command: string;
+    cwd: string;
+    name: string;
+    status: "starting" | "running" | "stopping" | "completed" | "failed" | "stopped" | "unknown";
+    createdAt: string;
+    updatedAt: string;
+    exitCode?: number | null;
+    error?: string;
+}[]>;

package/dist/wait-all.js

@@ -0,0 +1,10 @@
+/** Validate the entire selection before observing; one timeout applies concurrently. */
+export async function waitForBackgroundTasks(service, ids, timeout, signal) {
+    if (!ids.length || ids.length > 100 || new Set(ids).size !== ids.length)
+        throw new Error("Select 1..100 distinct background task IDs");
+    if (!Number.isInteger(timeout) || timeout < 1 || timeout > 600000)
+        throw new Error("timeout_ms must be 1..600000");
+    for (const id of ids)
+        service.get(id);
+    return Promise.all(ids.map(id => service.wait(id, timeout, signal)));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naiba/pi-durable-background-tasks",
-  "version": "0.1.1",
-  "description": "Background shell tools for Pi Durable; no model delegation",
+  "version": "0.3.0",
+  "description": "Background shell tools for Pi Coding Agent and Pi Durable; no model delegation",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -14,6 +14,11 @@
       "types": "./src/index.ts",
       "default": "./dist/index.js"
     },
+    "./coding-agent": {
+      "bun": "./src/coding-agent.ts",
+      "types": "./src/coding-agent.ts",
+      "default": "./dist/coding-agent.js"
+    },
     "./pi": {
       "bun": "./src/pi.ts",
       "types": "./src/pi.ts",
@@ -36,14 +41,32 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@earendil-works/pi-durable": "^1.0.4",
-    "@earendil-works/pi-ai": "^1.0.4"
+    "@earendil-works/pi-durable": "^1.2.0",
+    "@earendil-works/pi-ai": "^1.2.0",
+    "@earendil-works/pi-coding-agent": "^1.5.0",
+    "typebox": "^1.4.4"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-durable": {
+      "optional": true
+    },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@types/node": "^24.0.0",
-    "@types/bun": "latest",
-    "typescript": "~5.9.3",
-    "@earendil-works/pi-durable": "1.0.4",
-    "@earendil-works/pi-ai": "1.0.4"
+    "@earendil-works/pi-ai": "1.5.0",
+    "@earendil-works/pi-coding-agent": "1.5.0",
+    "@earendil-works/pi-durable": "1.5.0",
+    "@types/bun": "^1.4.3",
+    "@types/node": "^26.6.5",
+    "typebox": "1.4.4",
+    "typescript": "~7.0.2"
   }
 }

package/src/coding-agent.ts

@@ -0,0 +1,24 @@
+import {defineTool,type ExtensionFactory} from "@earendil-works/pi-coding-agent";
+import {Type} from "typebox";
+import {BackgroundTasks,type BackgroundTask,waitForBackgroundTasks} from "./index.js";
+
+export interface BackgroundTasksExtensionOptions {
+ /** Called after start, including a deduplicated start. Host owns delivery policy. */
+ onStart?:(task:BackgroundTask)=>void|Promise<void>;
+}
+
+// Coding Agent consumes content; Durable consumes output. Separate entry points
+// prevent a native Pi installation from loading the Durable runtime.
+const result=(value:unknown)=>({content:[{type:"text" as const,text:JSON.stringify(value)}],details:{}});
+export function backgroundTasksExtension(service:BackgroundTasks,cwd:string,options:BackgroundTasksExtensionOptions={}):ExtensionFactory{
+ return pi=>{
+  pi.registerTool(defineTool({name:"background_start",label:"Start background command",description:"Start a supervised command and continue independent work. Commands do not survive host loss. Approval belongs to the host tool policy.",parameters:Type.Object({command:Type.String(),name:Type.Optional(Type.String())}),execute:async(id,args)=>{
+   const task=service.start({...args,cwd,requestId:id});await options.onStart?.(task);return result(task);
+  }}));
+  pi.registerTool(defineTool({name:"background_status",label:"Background status",description:"List session-owned background commands.",parameters:Type.Object({}),execute:async()=>result(service.list())}));
+  pi.registerTool(defineTool({name:"background_output",label:"Background output",description:"Read bounded background output using byte offsets.",parameters:Type.Object({id:Type.String(),offset:Type.Optional(Type.Integer({minimum:0})),limit:Type.Optional(Type.Integer({minimum:1,maximum:65536}))}),execute:async(_id,args)=>result(await service.output(args.id,args.offset,args.limit))}));
+  pi.registerTool(defineTool({name:"background_wait",label:"Wait for command",description:"Observe a command only when no independent work remains. Timeout ends observation, not execution.",parameters:Type.Object({id:Type.String(),timeout_ms:Type.Integer({minimum:1,maximum:600000})}),execute:async(_id,args,signal)=>result(await service.wait(args.id,args.timeout_ms,signal))}));
+  pi.registerTool(defineTool({name:"background_wait_all",label:"Wait for commands",description:"Observe selected commands concurrently after independent work is finished. Timeout does not stop commands.",parameters:Type.Object({ids:Type.Array(Type.String(),{minItems:1,maxItems:100,uniqueItems:true}),timeout_ms:Type.Integer({minimum:1,maximum:600000})}),execute:async(_id,args,signal)=>result(await waitForBackgroundTasks(service,args.ids,args.timeout_ms,signal))}));
+  pi.registerTool(defineTool({name:"background_stop",label:"Stop command",description:"Stop a session-owned command and reap its descendants.",parameters:Type.Object({id:Type.String()}),execute:async(_id,args)=>result(await service.stop(args.id))}));
+ };
+}

package/src/index.ts

@@ -4,6 +4,7 @@ import {open} from "node:fs/promises";
 import {join, resolve} from "node:path";
 import {fileURLToPath} from "node:url";
 import {createHash} from "node:crypto";
+export {waitForBackgroundTasks} from "./wait-all.js";
 
 export type BackgroundTask = {
  id:string; command:string; cwd:string; name:string;

package/src/pi.ts

@@ -1,19 +1,23 @@
 import {defineExtension,defineTool} from "@earendil-works/pi-durable";
-import {Type} from "@earendil-works/pi-ai";
-import {BackgroundTasks} from "./index.js";
-const result=(value:unknown)=>({content:[{type:"text" as const,text:JSON.stringify(value)}]});
+import {Type} from "typebox";
+import {BackgroundTasks,waitForBackgroundTasks} from "./index.js";
+// Pi 1.2 consumes output; content silently hides task IDs and status from the model.
+const result=(value:unknown)=>({output:[{type:"text" as const,text:JSON.stringify(value)}]});
 export function backgroundTasksExtension(service:BackgroundTasks,cwd:string){
  return defineExtension({name:"background-tasks",tools:[
-  defineTool({name:"background_start",description:"Start a supervised background shell command. Returns immediately; no model delegation. Commands do not survive host loss. Approval belongs to the host tool policy.",replay:"unsafe",
+  defineTool({name:"background_start",description:"Start a supervised background shell command. Returns immediately; continue independent work before checking results. Do not immediately wait when other work is available; no model delegation. Commands do not survive host loss. Approval belongs to the host tool policy.",replay:"unsafe",
    parameters:Type.Object({command:Type.String(),name:Type.Optional(Type.String())}),
    execute:async(args,api)=>result(service.start({...args,cwd,requestId:String(api.taskId)}))}),
   defineTool({name:"background_status",description:"List background commands owned by this session.",replay:"safe",parameters:Type.Object({}),execute:async()=>result(service.list())}),
   defineTool({name:"background_output",description:"Read bounded background output using byte offsets.",replay:"safe",
    parameters:Type.Object({id:Type.String(),offset:Type.Optional(Type.Integer({minimum:0})),limit:Type.Optional(Type.Integer({minimum:1,maximum:65536}))}),
    execute:async(args)=>result(await service.output(args.id,args.offset,args.limit))}),
-  defineTool({name:"background_wait",description:"Wait for a background command. Explicit timeout ends observation only, not execution.",replay:"safe",
+  defineTool({name:"background_wait",description:"Blocking observation of a background command. Use only when the next step requires its result and no independent work remains; otherwise continue working and check status later. Explicit timeout ends observation only, not execution.",replay:"safe",
    parameters:Type.Object({id:Type.String(),timeout_ms:Type.Integer({minimum:1,maximum:600000})}),
    execute:async(args,api,ctx)=>result(await service.wait(args.id,args.timeout_ms,ctx.abortSignal))}),
+  defineTool({name:"background_wait_all",description:"Observe selected commands concurrently after independent work is finished. Timeout does not stop commands.",replay:"safe",
+   parameters:Type.Object({ids:Type.Array(Type.String(),{minItems:1,maxItems:100,uniqueItems:true}),timeout_ms:Type.Integer({minimum:1,maximum:600000})}),
+   execute:async(args,api,ctx)=>result(await waitForBackgroundTasks(service,args.ids,args.timeout_ms,ctx.abortSignal))}),
   defineTool({name:"background_stop",description:"Stop a session-owned command and reap its descendants. Returns after supervisor cleanup.",replay:"unsafe",
    parameters:Type.Object({id:Type.String()}),execute:async(args)=>result(await service.stop(args.id))}),
  ]});

package/src/wait-all.ts

@@ -0,0 +1,9 @@
+import type {BackgroundTasks} from "./index.js";
+
+/** Validate the entire selection before observing; one timeout applies concurrently. */
+export async function waitForBackgroundTasks(service:Pick<BackgroundTasks,"get"|"wait">,ids:string[],timeout:number,signal?:AbortSignal){
+ if(!ids.length||ids.length>100||new Set(ids).size!==ids.length)throw new Error("Select 1..100 distinct background task IDs");
+ if(!Number.isInteger(timeout)||timeout<1||timeout>600000)throw new Error("timeout_ms must be 1..600000");
+ for(const id of ids)service.get(id);
+ return Promise.all(ids.map(id=>service.wait(id,timeout,signal)));
+}