@astralyn/pi 1.4.9 → 1.4.11

package/docs/session-format.md

@@ -10,11 +10,15 @@ Sessions are stored as JSONL (JSON Lines) files. Each line is a JSON object with
 
 Pi resolves the working directory to an absolute path, removes one leading `/` or `\`, replaces every `/`, `\`, and `:` with `-`, then wraps the result in `--`. For example, `/path/to/project` is stored under `--path-to-project--`; `C:\Users\me\project` is stored under `--C--Users-me-project--`. By default the session ID is a UUID; callers can supply their own through the SDK or `--session-id`.
 
+## Session Artifacts
+
+A session file `<name>.jsonl` owns an artifacts directory `<name>/` beside it, created on demand by whatever writes there. The bundled `Agent` extension keeps each Agent's complete report and transcript in `<name>/agents/<task-id>/` (see [Agent](bundled/extensions/agent.md)). The directory holds nested session files, but session discovery reads only `.jsonl` files directly inside the session directory, so they never appear in `/resume` or `pi -c`. Forking or cloning a session does not copy artifacts: they belong to the session that created them. Sessions that are not persisted (`--no-session`) have no artifacts directory.
+
 ## Deleting Sessions
 
-Sessions can be removed by deleting their `.jsonl` files under `~/.pi/agent/sessions/`.
+A session consists of its `.jsonl` file, its artifacts directory, and the `<name>.jsonl.tasks-late.jsonl` sidecar when present. To remove a session by hand, delete all three under `~/.pi/agent/sessions/`.
 
-Pi also supports deleting sessions interactively from `/resume` (select a session and press `Ctrl+D`, then confirm). When available, pi uses the `trash` CLI to avoid permanent deletion.
+Pi also supports deleting sessions interactively from `/resume` (select a session and press `Ctrl+D`, then confirm). It removes the session file, its artifacts directory and its sidecar together. When available, pi uses the `trash` CLI, passing every path in one invocation, to avoid permanent deletion; otherwise it deletes them permanently. The deletion succeeds when the session file is gone, and files that could not be removed are reported.
 
 ## Session Version
 
@@ -344,7 +348,7 @@ Managed execution uses ordinary version-3 custom entries; it does not add a new
 
 `task.id` is the execution ID, not a worker display number. `usage` has the `Usage` shape above and is absent when the executor reported none. Consumers count only the first valid usage settlement per ID within the entries they aggregate; malformed records, unsupported versions, blank IDs, and non-finite or negative usage/cost values are ignored. A later valid duplicate is not an adjustment. Do not create these host-owned entries yourself or bill again from a result/read/notification.
 
-A `TaskSnapshot` has `id`, `kind` (executor-owned source label, such as `bash`, `powershell`, or an extension-defined label), `label` (human source name, such as `Bash` or `Agent`), `title`, `output` (`log` or `report`), `toolCallId`, `anchorId`, `mode`, `status`, and numeric millisecond `startedAt`; optional fields include `endedAt`, `input`, `facts`, `display`, `outputPath`, `result`, and `error`. `input` is `{ label, text, truncated, language? }`, what the task was asked to do; `facts` are up to 16 `[label, value]` Details rows, such as `["Exit", "1"]`. `result` is the bounded model-readable text and `display` is bounded human-only Output suffix text; both use `{ text, truncated }`. Only the result, error and facts reach model context. Truncation flags record clipping at the producing/retention boundary. Mode (`foreground` or `background`) is independent of status. Persisted terminal statuses are `completed`, `partial`, `failed`, `cancelled`, or `timeout`; live snapshots can also be `queued`, `running`, or `stopping`.
+A `TaskSnapshot` has `id`, `kind` (executor-owned source label, such as `bash`, `powershell`, or an extension-defined label), `label` (human source name, such as `Bash` or `Agent`), `title`, `output` (`log` or `report`), `toolCallId`, `anchorId`, `mode`, `status`, and numeric millisecond `startedAt`; optional fields include `endedAt`, `input`, `facts`, `display`, `outputPath`, `result`, and `error`. `input` is `{ label, text, truncated, language? }`, what the task was asked to do; `facts` are up to 16 `[label, value]` Details rows, such as `["Exit", "1"]`. `result` is the bounded model-readable text and `display` is the bounded human-only view that `/tasks` shows in place of the result; both use `{ text, truncated }`. Only the result, error and facts reach model context. Truncation flags record clipping at the producing/retention boundary. Mode (`foreground` or `background`) is independent of status and records where the task actually ran: `background` only when its caller was released with a background outcome, so a task whose result was returned inline is `foreground` even if background was requested. A terminal snapshot carries `display` only when the executor's completion supplied it. Persisted terminal statuses are `completed`, `partial`, `failed`, `cancelled`, or `timeout`; live snapshots can also be `queued`, `running`, or `stopping`.
 
 The retained result text is bounded (up to 48 KiB) and carries no executor-private details; images are replaced with a text omission marker. Source truncation is explicit; the reader never recognizes truncation by matching output text. `outputPath`, if present, points to an ephemeral executor-owned file which may already have been removed on eviction or runtime shutdown; restored records drop it. Save important output separately.
 
@@ -381,11 +385,11 @@ 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).
 
-**Late settlement quarantine:** an executor that ignores cancellation and settles after its runtime or launch branch is retired cannot append to the replacement session or move its active leaf. The originating session retains the latest 32 bounded quarantine records in memory. For persisted sessions it also appends audit JSONL to `<session-file>.tasks-late.jsonl`, with `{ version: 1, sessionId, generation, task, usage? }`. A sidecar write failure is reported and leaves only the bounded in-memory record. This sidecar is separate from the session tree and active totals; it is not automatically reconciled, replayed or used to resume execution. Preserve it if you need to audit late provider costs, and manage its disk retention separately from the session file.
+**Late settlement quarantine:** an executor that ignores cancellation and settles after its runtime or launch branch is retired cannot append to the replacement session or move its active leaf. The originating session retains the latest 32 bounded quarantine records in memory. For persisted sessions it also appends audit JSONL to `<session-file>.tasks-late.jsonl`, with `{ version: 1, sessionId, generation, task, usage? }`. A sidecar write failure is reported and leaves only the bounded in-memory record. This sidecar is separate from the session tree and active totals; it is not automatically reconciled, replayed or used to resume execution. Preserve it if you need to audit late provider costs. Deleting the session from `/resume` also removes its sidecar.
 
 ### CustomMessageEntry
 
@@ -516,6 +520,7 @@ Import `SessionManager` and its session types from `@astralyn/pi` as shown above
 
 - `SessionManager.create(cwd: string, sessionDir?: string, options?: NewSessionOptions): SessionManager` — create a persisted session.
 - `SessionManager.open(path: string, sessionDir?: string, cwdOverride?: string): SessionManager` — open a session file. `cwdOverride` takes precedence over the header's `cwd`.
+- `SessionManager.createAt(path: string, cwd: string, options?: NewSessionOptions): SessionManager` — create a persisted session at an exact file path, creating its directory. As for any session, the file appears once it holds a conversation.
 - `SessionManager.continueRecent(cwd: string, sessionDir?: string): SessionManager` — open the most recent session or create one.
 - `SessionManager.inMemory(cwd?: string, options?: NewSessionOptions, entries?: FileEntry[]): SessionManager` — create a non-persisted session, optionally initialized from entries.
 - `SessionManager.forkFrom(sourcePath: string, targetCwd: string, sessionDir?: string, options?: NewSessionOptions): SessionManager` — fork into another working directory.
@@ -567,6 +572,7 @@ All of these return the appended entry ID:
 - `getEntries(): SessionEntry[]` and `getHeader(): SessionHeader | null`
 - `getSessionName(): string | undefined`
 - `getCwd(): string`, `getSessionDir(): string`, `getSessionId(): string`, and `getSessionFile(): string | undefined`
+- `getArtifactDir(): string | undefined` — the directory the session file owns (`<name>/` for `<name>.jsonl`), or `undefined` when the session is not persisted. It is not created for you; create it before writing. Also available on `ctx.sessionManager` in extensions.
 - `usesDefaultSessionDir(): boolean` and `isPersisted(): boolean`
 
 ## Virtual selections and nested calls

package/docs/sessions.md

@@ -48,7 +48,7 @@ In the picker you can:
 - rename with Ctrl+R
 - delete with Ctrl+D, then confirm
 
-When available, pi uses the `trash` CLI for deletion instead of permanently removing files.
+Deleting a session also removes its artifacts directory (such as saved Agent reports and transcripts) and its late-task sidecar. When available, pi uses the `trash` CLI for deletion instead of permanently removing files.
 
 ## Naming Sessions
 

package/docs/usage.md

@@ -178,6 +178,8 @@ See [Pi Packages](packages.md) for package sources and security notes.
 
 Print mode writes errors to stderr. A final assistant response with an `error` or `aborted` stop reason exits nonzero; a response cut off at the model's output token limit (a `length` stop reason) still prints its partial text to stdout, warns on stderr, and also exits nonzero.
 
+Print mode and `--mode json` wait for Background tasks started by a prompt: the process stays alive until every unsettled task has finished and the turn that delivers its result has completed, so the printed response is the one that follows the result. While it waits, one line on stderr names the running tasks. Ctrl+C (`SIGINT`) or `SIGTERM` stops the wait, terminates the work and exits (130 and 143); a second signal exits at once.
+
 In print mode, pi also reads piped stdin and merges it into the initial prompt:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@astralyn/pi",
-	"version": "1.4.9",
+	"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/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"]}