@naiba/pi-durable-background-tasks 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,15 @@
 
 Supervised background shell commands for Pi Durable. No delegated agents, model configuration, or implicit model calls.
 
-**Initial development version. Linux only; requires Python 3.9+ and Linux pidfd support.** Not yet published to npm.
+**Initial development version. Linux only; requires Python 3.9+ and Linux pidfd support.**
+
+```sh
+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.
+
+This is an extension for **Pi Durable**, not an auto-discovered Pi coding-agent CLI plugin. The host must install the extension in its registry and own its lifecycle. It does not manage Claude Code or Codex background tasks.
 
 ## Usage
 
@@ -10,6 +18,7 @@ Supervised background shell commands for Pi Durable. No delegated agents, model
 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.
@@ -19,7 +28,14 @@ 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_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.
@@ -34,6 +50,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.
+
+The package itself has no Web UI and does not automatically resume a model when a command completes. CloudCode's Claude Code/Codex ACP background activity adapters are not implemented by this package; their execution must remain native.
+
 ## Development
 
 ```sh
@@ -43,3 +65,14 @@ bun test
 ```
 
 Tests exercise real Linux processes rather than mocked cancellation. The build includes the Python supervisor beside the JavaScript distribution.
+
+## Publishing
+
+Releases use `.github/workflows/publish.yml` on pushed `v*` tags, with npm Trusted Publishing (OIDC); no npm token secret is required. Configure this package's GitHub Actions trusted publisher on npm:
+
+- Organization or user: `naiba`
+- Repository: `pi-durable-background-tasks`
+- 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.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/pi.js

@@ -1,16 +1,17 @@
 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) }] });
+// 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_stop", description: "Stop a session-owned command and reap its descendants. Returns after supervisor cleanup.", replay: "unsafe",

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@naiba/pi-durable-background-tasks",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Background shell tools for Pi Durable; no model delegation",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/naiba/pi-durable-background-tasks.git"
+    "url": "git+https://github.com/naiba/pi-durable-background-tasks.git"
   },
   "exports": {
     ".": {
@@ -36,14 +36,14 @@
     "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"
   },
   "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"
+    "@types/node": "^26.6.5",
+    "@types/bun": "^1.4.3",
+    "typescript": "~7.0.2",
+    "@earendil-works/pi-durable": "1.2.0",
+    "@earendil-works/pi-ai": "1.2.0"
   }
 }

package/src/pi.ts

@@ -1,17 +1,18 @@
 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)}]});
+// 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_stop",description:"Stop a session-owned command and reap its descendants. Returns after supervisor cleanup.",replay:"unsafe",