@astralyn/pi 1.4.10 → 1.4.11

package/docs/sdk.md

@@ -250,17 +250,17 @@ Both `steer()` and `followUp()` expand file-based prompt templates but error on
 
 ### Background execution
 
-Background is a session-owned capability, not a daemon or a flag on `createAgentSession()`. Interactive mode enables it. Ordinary SDK sessions and the built-in print, JSON, and RPC hosts leave it disabled and reject native shell or extension calls with `background: true`. Normal foreground tools still work, including standalone `createBashTool()` / `createPowerShellTool()` calls without a session context.
+Background is a session-owned capability, not a daemon or a flag on `createAgentSession()`. Interactive mode and the built-in print, JSON, and RPC hosts enable it. Ordinary SDK sessions leave it disabled and reject native shell or extension calls with `background: true`. Normal foreground tools still work, including standalone `createBashTool()` / `createPowerShellTool()` calls without a session context.
 
 An embedding can opt in with `await session.bindExtensions({ tasksEnabled: true })`. Bind before prompting; this also binds extensions and emits their session-start lifecycle. When using `AgentSessionRuntime`, rebind the replacement session through the runtime's rebind callback. Setting `mode` or providing a UI alone does not enable Background.
 
-Background work is admitted only while the `tasks` management tool is active in the session, so the model that starts work can always read, wait for and stop it. The bundled `builtin:tasks` extension provides that tool; a session that disables the extension or deactivates the tool rejects `background: true` and every detach path (the error says no work was started), while work already admitted keeps running and delivering.
+Background work is admitted only while the `tasks` management tool is active in the session, so the model that starts work can always read and stop it. The bundled `builtin:tasks` extension provides that tool; a session that disables the extension or deactivates the tool rejects `background: true` and every detach path (the error says no work was started), while work already admitted keeps running and delivering.
 
 The host must choose:
 
 - **Lifetime and cancellation:** a settled main-agent turn is not the end of background work. `session.abort()` cancels foreground-owned work, not detached work. Use `session.tasks.kill(id)` for a whole execution, or `await session.tasks.shutdown(graceMs?)` to close admission, cancel all owned work and drain within a bounded grace period (default 2 seconds, maximum 60 seconds). A non-cooperating executor can outlive that grace period.
 - **Result-driven turns and cost:** automatic completions join the host's prompt queue, so a running turn receives them as steering and an idle session starts a completion turn. Use the nestable `session.pauseTaskNotifications()` to defer delivery; its returned release function is idempotent. Pausing does not stop execution or its costs. Budget worker activity and completion-triggered turns explicitly.
-- **Observation and delivery:** `session.tasks` exposes the [public supervision methods](extensions.md#ctxtasks). `read()`, `wait()`, and `waitAny()` observe; a terminal snapshot alone does not acknowledge model delivery. `waitAny()` covers only tasks running at call time and reports `no_tasks` for an empty cohort. Both return a typed `outcome` (`settled`, `timed_out`, `interrupted`, or `closed`), and steering interrupts only waits, never execution. The built-in `tasks wait` tool passes its tool-call ID as `toolCallId`, so the runtime holds the observed result back from notifications and the host confirms it only after persisting that tool result, even if extensions rewrite its details. A direct SDK waiter that consumes the result outside model history omits `toolCallId` and can explicitly call `session.acknowledgeTaskDelivery(task.id)` after successful consumption, which stops the session from notifying the model about it (an unknown or already delivered ID is ignored). An undelivered completion keeps its task and output retained until it is delivered or acknowledged, or its runtime closes. A timeout or cancelled wait does not stop the execution. Failed notification delivery leaves the result available for inspection; after fixing the host failure, call `session.retryTaskNotifications()` explicitly. Pi does not retry a failed delivery forever on a timer.
+- **Observation and delivery:** `session.tasks` exposes the [public supervision methods](extensions.md#ctxtasks). `list()`, `get()` and `read()` observe; a terminal snapshot alone does not acknowledge model delivery, and there is no blocking wait: subscribe with `session.tasks.subscribe()` or use `waitForQuiescence()` below. A direct SDK consumer that handles a result outside model history can call `session.acknowledgeTaskDelivery(task.id)` after successful consumption, which stops the session from notifying the model about it (an unknown or already delivered ID is ignored). An undelivered completion keeps its task and output retained until it is delivered or acknowledged, or its runtime closes. Failed notification delivery leaves the result available for inspection; after fixing the host failure, call `session.retryTaskNotifications()` explicitly. Pi does not retry a failed delivery forever on a timer.
 - **Shutdown:** `await runtime.dispose()` handles background shutdown and extension lifecycle when using the runtime API. For a directly owned session, drain Background, abort the main agent, then dispose; synchronous `session.dispose()` alone is not an awaited drain.
 - **Waiting for all work:** `prompt()` resolves when its own run settles, before any Background completion turn. `await session.waitForQuiescence(signal?)` resolves once the session is quiescent: no run, compaction, retry or branch summary, no unsettled Background task, and no completion left to deliver (the `session_quiescent` event marks the same moment, once per transition). It uses no timers and rejects when `signal` aborts or the session is disposed. A completion whose delivery failed does not count, since it retries only on the next input; a Background task that never ends keeps the wait open, so pass a signal when that matters.
 

package/docs/session-format.md

@@ -385,7 +385,7 @@ A shell completion's `details` can look like this:
 
 The message carries everything needed for replay after `/reload`, branch navigation, history eviction or restart; rendering does not open the saved log or query a live task. Unsupported or malformed completion details, including versions 1 and 2, use bounded plain message text. There is no legacy text parser, dual-format reconstruction or migration.
 
-A completion is acknowledged only after its message is persisted. A terminal `tasks wait` binds a host-owned receipt to the tool-call ID. Only persisting that tool result acknowledges delivery, even if its details were rewritten; aborting during an output read cannot consume a notification. Direct `TasksContext.wait()` and `waitAny()` are observational unless given a `toolCallId` in a session host. Snapshots and repeated reads do not create more usage. Historical extension-owned `background-task` notifications and old `bg create` tool results remain transcript history shown as saved text, not new runnable tasks.
+A completion is acknowledged only after its message is persisted; reads and aborting during an output read cannot consume a notification. Snapshots and repeated reads do not create more usage. Historical extension-owned `background-task` notifications and old `bg create` and `tasks wait` tool results remain transcript history shown as saved text, not new runnable tasks.
 
 Session-wide statistics aggregate the ledger across all entries; the bundled Statusline uses the active branch. Accrued retries, failures, cancellations and worker compaction count when usage is reported. No usage is invented for a provider that does not expose it, and worker billing does not occupy the parent's context window. See [SDK session statistics](sdk.md#session-statistics).
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@astralyn/pi",
-	"version": "1.4.10",
+	"version": "1.4.11",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"piConfig": {
@@ -25,8 +25,7 @@
 		"docs",
 		"examples",
 		"schemas",
-		"CHANGELOG.md",
-		"npm-shrinkwrap.json"
+		"CHANGELOG.md"
 	],
 	"scripts": {
 		"clean": "shx rm -rf dist",
@@ -53,7 +52,7 @@
 		"verify:package-install": "node scripts/verify-package-install.mjs",
 		"profile:tui": "node scripts/profile-node.mjs --mode tui",
 		"profile:rpc": "node scripts/profile-node.mjs --mode rpc",
-		"shrinkwrap": "npm install --package-lock-only --ignore-scripts",
+		"lockfile": "npm install --package-lock-only --ignore-scripts",
 		"prepare": "husky",
 		"prepublishOnly": "npm run clean && npm run build"
 	},

package/dist/core/tasks/wait.d.ts

@@ -1,19 +0,0 @@
-export interface WaitSources {
-    /** Whether any observed execution has settled. */
-    hasSettled(): boolean;
-    /** Subscribe to execution state changes; the returned release must remove the listener. */
-    subscribe(listener: () => void): () => void;
-    timeoutMs: number;
-    /** Rejects the wait with the signal's reason. */
-    signal?: AbortSignal;
-    /** Steering: ends the wait without rejecting. */
-    interrupt?: AbortSignal;
-    /** The runtime closed: ends the wait without rejecting. */
-    closed: AbortSignal;
-}
-/**
- * A race of settlement, timeout, abort, interrupt and close. Whichever ends it first, the timer
- * and every listener are released, so an observation leaves nothing behind. Only an abort rejects.
- */
-export declare function waitForFirst({ hasSettled, subscribe, timeoutMs, signal, interrupt, closed, }: WaitSources): Promise<void>;
-//# sourceMappingURL=wait.d.ts.map

package/dist/core/tasks/wait.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../../src/core/tasks/wait.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IAC3B,kDAAkD;IAClD,UAAU,IAAI,OAAO,CAAC;IACtB,2FAA2F;IAC3F,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,iDAAiD;IACjD,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,2DAA2D;IAC3D,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,EAC5B,UAAU,EACV,SAAS,EACT,SAAS,EACT,MAAM,EACN,SAAS,EACT,MAAM,GACN,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA+B7B"}

package/dist/core/tasks/wait.js

@@ -1,45 +0,0 @@
-import { boundWaitMs } from "./limits.js";
-/**
- * A race of settlement, timeout, abort, interrupt and close. Whichever ends it first, the timer
- * and every listener are released, so an observation leaves nothing behind. Only an abort rejects.
- */
-export function waitForFirst({ hasSettled, subscribe, timeoutMs, signal, interrupt, closed, }) {
-    if (signal?.aborted)
-        return Promise.reject(signal.reason ?? new Error("Wait aborted"));
-    if (hasSettled() || interrupt?.aborted || closed.aborted)
-        return Promise.resolve();
-    return new Promise((resolve, reject) => {
-        const releases = [];
-        let finished = false;
-        const end = (reason) => {
-            if (finished)
-                return;
-            finished = true;
-            for (const release of releases)
-                release();
-            if (reason === undefined)
-                resolve();
-            else
-                reject(reason);
-        };
-        const on = (source, handler) => {
-            if (!source)
-                return;
-            source.addEventListener("abort", handler, { once: true });
-            releases.push(() => source.removeEventListener("abort", handler));
-        };
-        on(signal, () => end(signal?.reason ?? new Error("Wait aborted")));
-        on(interrupt, () => end());
-        on(closed, () => end());
-        const timer = setTimeout(() => end(), boundWaitMs(timeoutMs));
-        releases.push(() => clearTimeout(timer));
-        releases.push(subscribe(() => {
-            if (hasSettled())
-                end();
-        }));
-        // Close the synchronous gap between the first check and subscription.
-        if (hasSettled())
-            end();
-    });
-}
-//# sourceMappingURL=wait.js.map

package/dist/core/tasks/wait.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"wait.js","sourceRoot":"","sources":["../../../src/core/tasks/wait.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAgB1C;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,EAC5B,UAAU,EACV,SAAS,EACT,SAAS,EACT,MAAM,EACN,SAAS,EACT,MAAM,GACO;IACb,IAAI,MAAM,EAAE,OAAO;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC;IACvF,IAAI,UAAU,EAAE,IAAI,SAAS,EAAE,OAAO,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IACnF,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC5C,MAAM,QAAQ,GAAsB,EAAE,CAAC;QACvC,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,MAAM,GAAG,GAAG,CAAC,MAAgB,EAAE,EAAE;YAChC,IAAI,QAAQ;gBAAE,OAAO;YACrB,QAAQ,GAAG,IAAI,CAAC;YAChB,KAAK,MAAM,OAAO,IAAI,QAAQ;gBAAE,OAAO,EAAE,CAAC;YAC1C,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,EAAE,CAAC;;gBAC/B,MAAM,CAAC,MAAM,CAAC,CAAC;QACrB,CAAC,CAAC;QACF,MAAM,EAAE,GAAG,CAAC,MAA+B,EAAE,OAAmB,EAAE,EAAE;YACnE,IAAI,CAAC,MAAM;gBAAE,OAAO;YACpB,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1D,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QACnE,CAAC,CAAC;QACF,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,IAAI,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;QACnE,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;QAC3B,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;QACxB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC;QAC9D,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;QACzC,QAAQ,CAAC,IAAI,CACZ,SAAS,CAAC,GAAG,EAAE;YACd,IAAI,UAAU,EAAE;gBAAE,GAAG,EAAE,CAAC;QACzB,CAAC,CAAC,CACF,CAAC;QACF,sEAAsE;QACtE,IAAI,UAAU,EAAE;YAAE,GAAG,EAAE,CAAC;IACzB,CAAC,CAAC,CAAC;AACJ,CAAC","sourcesContent":["import { boundWaitMs } from \"./limits.ts\";\n\nexport interface WaitSources {\n\t/** Whether any observed execution has settled. */\n\thasSettled(): boolean;\n\t/** Subscribe to execution state changes; the returned release must remove the listener. */\n\tsubscribe(listener: () => void): () => void;\n\ttimeoutMs: number;\n\t/** Rejects the wait with the signal's reason. */\n\tsignal?: AbortSignal;\n\t/** Steering: ends the wait without rejecting. */\n\tinterrupt?: AbortSignal;\n\t/** The runtime closed: ends the wait without rejecting. */\n\tclosed: AbortSignal;\n}\n\n/**\n * A race of settlement, timeout, abort, interrupt and close. Whichever ends it first, the timer\n * and every listener are released, so an observation leaves nothing behind. Only an abort rejects.\n */\nexport function waitForFirst({\n\thasSettled,\n\tsubscribe,\n\ttimeoutMs,\n\tsignal,\n\tinterrupt,\n\tclosed,\n}: WaitSources): Promise<void> {\n\tif (signal?.aborted) return Promise.reject(signal.reason ?? new Error(\"Wait aborted\"));\n\tif (hasSettled() || interrupt?.aborted || closed.aborted) return Promise.resolve();\n\treturn new Promise<void>((resolve, reject) => {\n\t\tconst releases: Array<() => void> = [];\n\t\tlet finished = false;\n\t\tconst end = (reason?: unknown) => {\n\t\t\tif (finished) return;\n\t\t\tfinished = true;\n\t\t\tfor (const release of releases) release();\n\t\t\tif (reason === undefined) resolve();\n\t\t\telse reject(reason);\n\t\t};\n\t\tconst on = (source: AbortSignal | undefined, handler: () => void) => {\n\t\t\tif (!source) return;\n\t\t\tsource.addEventListener(\"abort\", handler, { once: true });\n\t\t\treleases.push(() => source.removeEventListener(\"abort\", handler));\n\t\t};\n\t\ton(signal, () => end(signal?.reason ?? new Error(\"Wait aborted\")));\n\t\ton(interrupt, () => end());\n\t\ton(closed, () => end());\n\t\tconst timer = setTimeout(() => end(), boundWaitMs(timeoutMs));\n\t\treleases.push(() => clearTimeout(timer));\n\t\treleases.push(\n\t\t\tsubscribe(() => {\n\t\t\t\tif (hasSettled()) end();\n\t\t\t}),\n\t\t);\n\t\t// Close the synchronous gap between the first check and subscription.\n\t\tif (hasSettled()) end();\n\t});\n}\n"]}

package/dist/modes/interactive/tool-view/tool-execution.d.ts

@@ -1,14 +0,0 @@
-import type { TUI } from "@earendil-works/pi-tui";
-import { ToolExecutionComponent as NativeToolExecutionComponent, type ToolExecutionOptions } from "../components/tool-execution.ts";
-import { type ToolDefinitionLike } from "./shell.ts";
-export type { ToolRenderers } from "../../../core/extensions/types.ts";
-export type { ToolExecutionOptions } from "../components/tool-execution.ts";
-/**
- * Compatibility entry point for the distribution's original tool-view import path.
- * Lifecycle and renderer composition live in the native component; this adapter only supplies
- * the default shell for callers that construct the old distribution component directly.
- */
-export declare class ToolExecutionComponent extends NativeToolExecutionComponent {
-    constructor(toolName: string, toolCallId: string, args: any, options: ToolExecutionOptions | undefined, toolDefinition: ToolDefinitionLike | undefined, ui: TUI, cwd: string);
-}
-//# sourceMappingURL=tool-execution.d.ts.map

package/dist/modes/interactive/tool-view/tool-execution.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tool-execution.d.ts","sourceRoot":"","sources":["../../../../src/modes/interactive/tool-view/tool-execution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EACN,sBAAsB,IAAI,4BAA4B,EACtD,KAAK,oBAAoB,EACzB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,KAAK,kBAAkB,EAAiB,MAAM,YAAY,CAAC;AAEpE,YAAY,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AACvE,YAAY,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAE5E;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,4BAA4B;gBAEtE,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,GAAG,EACT,OAAO,EAAE,oBAAoB,YAAK,EAClC,cAAc,EAAE,kBAAkB,GAAG,SAAS,EAC9C,EAAE,EAAE,GAAG,EACP,GAAG,EAAE,MAAM;CAIZ"}

package/dist/modes/interactive/tool-view/tool-execution.js

@@ -1,13 +0,0 @@
-import { ToolExecutionComponent as NativeToolExecutionComponent, } from "../components/tool-execution.js";
-import { withToolShell } from "./shell.js";
-/**
- * Compatibility entry point for the distribution's original tool-view import path.
- * Lifecycle and renderer composition live in the native component; this adapter only supplies
- * the default shell for callers that construct the old distribution component directly.
- */
-export class ToolExecutionComponent extends NativeToolExecutionComponent {
-    constructor(toolName, toolCallId, args, options = {}, toolDefinition, ui, cwd) {
-        super(toolName, toolCallId, args, options, withToolShell(toolName, toolDefinition), ui, cwd);
-    }
-}
-//# sourceMappingURL=tool-execution.js.map

package/dist/modes/interactive/tool-view/tool-execution.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tool-execution.js","sourceRoot":"","sources":["../../../../src/modes/interactive/tool-view/tool-execution.ts"],"names":[],"mappings":"AACA,OAAO,EACN,sBAAsB,IAAI,4BAA4B,GAEtD,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAA2B,aAAa,EAAE,MAAM,YAAY,CAAC;AAKpE;;;;GAIG;AACH,MAAM,OAAO,sBAAuB,SAAQ,4BAA4B;IACvE,YACC,QAAgB,EAChB,UAAkB,EAClB,IAAS,EACT,UAAgC,EAAE,EAClC,cAA8C,EAC9C,EAAO,EACP,GAAW;QAEX,KAAK,CAAC,QAAQ,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,CAAC,QAAQ,EAAE,cAAc,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;IAC9F,CAAC;CACD","sourcesContent":["import type { TUI } from \"@earendil-works/pi-tui\";\nimport {\n\tToolExecutionComponent as NativeToolExecutionComponent,\n\ttype ToolExecutionOptions,\n} from \"../components/tool-execution.ts\";\nimport { type ToolDefinitionLike, withToolShell } from \"./shell.ts\";\n\nexport type { ToolRenderers } from \"../../../core/extensions/types.ts\";\nexport type { ToolExecutionOptions } from \"../components/tool-execution.ts\";\n\n/**\n * Compatibility entry point for the distribution's original tool-view import path.\n * Lifecycle and renderer composition live in the native component; this adapter only supplies\n * the default shell for callers that construct the old distribution component directly.\n */\nexport class ToolExecutionComponent extends NativeToolExecutionComponent {\n\tconstructor(\n\t\ttoolName: string,\n\t\ttoolCallId: string,\n\t\targs: any,\n\t\toptions: ToolExecutionOptions = {},\n\t\ttoolDefinition: ToolDefinitionLike | undefined,\n\t\tui: TUI,\n\t\tcwd: string,\n\t) {\n\t\tsuper(toolName, toolCallId, args, options, withToolShell(toolName, toolDefinition), ui, cwd);\n\t}\n}\n"]}