@astralyn/pi 1.4.4 → 1.4.6

package/docs/extensions.md

@@ -1214,6 +1214,17 @@ Use `ctx.modelRegistry.streamSimple(model, context, options)` for provider-neutr
 
 Both return an `AssistantMessageEventStream`. Iterate it for response events and await `.result()` for the final message. Setup failures produce error events and error results.
 
+### ctx.getExtensionSettings() / ctx.setExtensionSettings()
+
+Extensions can store one JSON object in their own global namespace under `extensionSettings` in `settings.json`:
+
+```typescript
+const settings = ctx.getExtensionSettings("my-extension");
+await ctx.setExtensionSettings("my-extension", { ...settings, model: "provider/model-id" });
+```
+
+Reads return a detached object and reject malformed existing configuration. Writes replace only that namespace, merge with the latest file under the SettingsManager lock, skip unchanged values, and resolve only after successful persistence. Project settings do not override this global API. Namespace names contain lowercase letters, digits, and hyphens, start with a letter, and have at most 64 characters. Await writes before reporting success; captured contexts become stale after session replacement like the rest of `ExtensionContext`.
+
 ### ctx.signal
 
 The current agent abort signal, or `undefined` when no agent turn is active.
@@ -1245,9 +1256,9 @@ Session-bound `TasksContext` supervises native and extension-owned execution. Fo
 
 | Method | Contract |
 |---|---|
-| `execute<T>(execution)` | Returns `{ kind: "result", result, status?, error? }` or `{ kind: "background", task }` |
+| `execute<T>(execution)` | Returns `{ kind: "result", result, status, error? }` or `{ kind: "background", task }` |
 | `list()` / `get(id)` | Bounded, read-only (frozen) retained snapshots; IDs support unique prefixes |
-| `read(id, options?)` | Bounded head, tail, or byte-offset output |
+| `read(id, options?)` | Bounded head, tail, or byte-offset model-readable output; excludes human-only display text |
 | `wait(id, timeoutMs?, signal?, interruptSignal?)` | Observation only; timeout, cancellation, or `interruptSignal` ends the wait, not execution |
 | `waitAny(timeoutMs?, signal?, interruptSignal?)` | Observes the first task running at call time to settle; returns `undefined` for an empty cohort, timeout, interruption, or closed host. Later tasks are excluded |
 | `kill(id)` | Requests cancellation; `stopping` is not a terminal status |
@@ -1257,18 +1268,34 @@ Session-bound `TasksContext` supervises native and extension-owned execution. Fo
 | `retain(id)` | Returns an idempotent release function protecting retained data, without delaying notifications |
 | `holdDelivery(id)` | Explicitly retains data and delays automatic delivery until released |
 
-`TaskExecution<T>` supplies `kind`, `title`, `toolCallId`, `run(control)`, optional `command`, `cwd`, `background`, `signal`, and `onUpdate`. `kind` is an executor-owned source label matching `[a-z][a-z0-9-]{0,63}`; the runtime never dispatches on it. At most eight background executions run at once; foreground executions are not limited by them. Foreground and background results have separate history quotas.
+`TaskExecution<T>` supplies `kind`, `title`, `toolCallId`, and `run(control)`, plus optional fields:
+
+| Field | Contract |
+|---|---|
+| `label` | Human source name for the panel and completion card, such as `Bash` or `Agent`; defaults to `kind` |
+| `output` | `"log"` (default) or `"report"`. A log's outcome is at its end, so a background completion gives the model an 8 KiB tail. A report leads with its conclusion, so it arrives from its beginning, whole when it fits the 48 KiB context budget, as its foreground result would; a completed report renders as Markdown in `/tasks` |
+| `input` | `{ label, text, truncated, language? }`: what the task was asked to do, such as a command or briefing. Shown in Details and the expanded completion card, highlighted when `language` is set |
+| `facts` | Up to 16 labelled `[label, value]` Details rows, such as `["Directory", cwd]` |
+| `concurrency` | `{ key, limit }`: at most `limit` executions sharing `key` run at once. Later ones wait as `queued` tasks and `run` starts when a slot frees |
+| `background`, `signal`, `onUpdate` | Requested handoff, parent cancellation, and foreground progress forwarding |
+
+`kind` is an executor-owned source label matching `[a-z][a-z0-9-]{0,63}`; the runtime never dispatches on it. Presentation is declared data: the panel and completion card render `label`, `input`, `facts`, and `output` the same way for every executor. Input and facts restore with terminal task history; facts also appear in the completion notification. At most eight background executions, queued ones included, are retained as active at once; foreground executions are not limited by them. Foreground and background results have separate history quotas.
+
+A caller can be handed off to the background while its task is queued, before `run` starts, or after `run` calls `accept()`. A queued task becomes `running` when its `run` starts; cancelling it settles it as `cancelled` without starting it.
 
-`run` returns `TaskCompletion<T>`: `{ result, status?, error?, exitCode?, usage? }`. The original tool result is returned to a foreground caller; private `result.details` is not copied into task history. Explicit terminal statuses are `completed`, `partial`, `failed`, `cancelled`, and `timeout`. Usage is settled by the host once; managed foreground results omit usage to avoid billing it twice.
+`run` returns `TaskCompletion<T>`: `{ result, status?, display?, error?, facts?, usage? }`. The original tool result is returned to a foreground caller; task history keeps only its bounded text. Optional `display` is bounded human-only Output suffix text, excluded from `tasks read`, settled waits, and completion context. Terminal `facts` replace launch facts with the same label, as the shell does with `["Exit", "42"]`. Explicit terminal statuses are `completed`, `partial`, `failed`, `cancelled`, and `timeout`. The host settles usage once, preferring `usage`, then `result.usage`, then the latest published usage; managed foreground results omit usage to avoid billing it twice.
 
-`TaskControl<T>` exposes `id`, `signal`, `mode`, `accept()`, `publish(result)`, `setOutputPath(path, cleanup?)`, `onModeChange(listener)`, and `requestCancel()`. `publish` replaces the task's bounded text result, which the `/tasks` panel, `tasks read`, and the completion notification show; a task with an output path is read from that log instead. Call `accept()` after whole-invocation preflight, before allowing a background handoff. Use the control's signal throughout execution. Parent-call cancellation is disconnected after handoff, while runtime shutdown still cancels the task. Mode subscriptions concern only this task; executors do not need the global registry to observe their own handoff or cancel themselves.
+`TaskControl<T>` exposes `id`, `signal`, `mode`, `onModeChange(listener)`, `accept()`, `publish(update)`, `attachOutput(path, cleanup?)`, and `cancel()`. `publish({ result, display?, usage? })` replaces the bounded model-readable result and optionally the human-only Output suffix and cumulative usage; `/tasks` combines result and display, while model reads and completion notifications use only the result. A task with an attached output file is read from that file instead. Call `accept()` after whole-invocation preflight, before allowing a background handoff. Use the control's signal throughout execution. Parent-call cancellation is disconnected after handoff, while runtime shutdown still cancels the task. Mode subscriptions concern only this task; executors do not need the global registry to observe their own handoff or cancel themselves.
 
-Completion messages store a self-contained `TaskCompletionSnapshot`; only their bounded `content` enters model context, with an 8 KiB output tail while replay details retain 40 KiB. Built-in `tasks wait` binds delivery to the actual tool call, and the host confirms it after successful persistence; a settled waitAny binds only its winning task. Ordinary extension reads/waits, including `waitAny`, do not acknowledge delivery, and arbitrary tool-result detail fields cannot acknowledge a task.
+Completion messages store `{ version: 3, task }` in `details`, a bounded terminal `TaskSnapshot`; only their bounded `content` enters model context. Built-in `tasks wait` binds delivery to the actual tool call, and the host confirms it after successful persistence; a settled waitAny binds only its winning task. Ordinary extension reads/waits, including `waitAny`, do not acknowledge delivery, and arbitrary tool-result detail fields cannot acknowledge a task.
 
 ```typescript
 const outcome = await ctx.tasks.execute({
   kind: "report-job",
+  label: "Review",
   title: "Inspect project",
+  output: "report",
+  facts: [["Directory", ctx.cwd]],
   toolCallId,
   signal,
   background: params.background,

package/docs/sdk.md

@@ -280,7 +280,7 @@ try {
 
 For a longer-lived embedding, keep the host alive, subscribe to snapshots and choose bounded waits or release notification delivery according to your model-turn policy. Do not use a panel or repeated reads as the billing or cleanup mechanism.
 
-Automatic completion messages carry a version-2 `TaskCompletionSnapshot` in `details`, with the command, a 40 KiB output tail, diagnostics and explicit truncation flags. This snapshot is self-contained for transcript replay and is not sent to the model; `content` contains separately bounded prose with an 8 KiB output tail. After compaction, one request-local reminder lists still-active background tasks to prevent duplicate work; it is not persisted and does not start a turn. Current terminal history uses version-2 `task-result` records, with no migration of earlier result records. The usage ledger remains independent. See [Background records](session-format.md#background-records).
+Automatic completion messages carry `{ version: 3, task }` in `details`: the bounded terminal snapshot with its input, facts, diagnostics, up to 40 KiB of output and explicit truncation flags. This snapshot is self-contained for transcript replay and is not sent to the model. `content` is separately bounded prose: a log contributes an 8 KiB tail, while a report arrives from its beginning, whole when it fits the 48 KiB budget. After compaction, one request-local reminder lists still-active background tasks to prevent duplicate work; it is not persisted and does not start a turn. Each settlement appends one version-3 `task-record` holding the terminal snapshot and its usage, with no migration of earlier result records. See [Background records](session-format.md#background-records).
 
 `backgroundAllowed: false` on `createAgentSession()` is a host capability ceiling, independent of task kind. It prevents enabling background execution through `bindExtensions` or direct runtime activation, including after reload. Requests for `background: true` are rejected before startup; foreground execution remains available. Omitting this option permits host opt-in but does not enable background execution by itself. This capability restriction is not an OS sandbox.
 
@@ -292,7 +292,7 @@ An executor that ignores abort and settles after its originating runtime/branch
 
 `session.getSessionStats()` returns `sessionFile`, `sessionId`, `userMessages`, `assistantMessages`, `toolCalls`, `toolResults`, `totalMessages`, `tokens`, `cost`, and optional `contextUsage`. `tokens` contains `input`, `output`, `cacheRead`, `cacheWrite`, and `total` (the sum of those four categories); `cost` is accumulated reported cost.
 
-Usage totals cover all session entries, including other branches and compacted history: assistant requests, usage-bearing tool results, compaction/branch summaries, and the first valid `task-usage` record per execution ID. Managed foreground results omit duplicate usage. Background records do not increment message/tool counts, and reads, waits, handoff and history restoration do not add billing. Worker retry, failure, cancellation and compaction usage is included when supplied; missing provider usage is not fabricated. Quarantined late settlements are excluded.
+Usage totals cover all session entries, including other branches and compacted history: assistant requests, usage-bearing tool results, compaction/branch summaries, and the first valid task usage settlement per execution ID, from a `task-record` or a released session's `task-usage` entry. Managed foreground results omit duplicate usage. Background records do not increment message/tool counts, and reads, waits, handoff and history restoration do not add billing. Worker retry, failure, cancellation and compaction usage is included when supplied; missing provider usage is not fabricated. Quarantined late settlements are excluded.
 
 This differs from the bundled Statusline's active-branch totals. Neither accumulated worker usage nor Background billing changes the parent context-occupancy estimate or the latest parent request's cache-hit ratio.
 

package/docs/session-format.md

@@ -336,46 +336,50 @@ Use `customType` to identify your extension's entries on reload. Interactive mod
 
 ### Background records
 
-Managed execution uses ordinary version-3 custom entries; it does not add a new session-file version or persist live execution handles. Every managed execution — including a foreground one — appends its own bounded terminal snapshot. A foreground snapshot omits `result`: its tool result already holds the output, and restoration reads it from the tool result with the same `toolCallId` on the branch.
+Managed execution uses ordinary version-3 custom entries; it does not add a new session-file version or persist live execution handles. Every managed execution — including a foreground one — appends exactly one record when it settles, holding its bounded terminal snapshot and the usage settled for it. A foreground snapshot omits `result`: its tool result already holds the output, and restoration reads it from the tool result with the same `toolCallId` on the branch.
 
 | `customType` | `data` | Purpose |
 |---|---|---|
-| `task-usage` | `{ version: 1, taskId, usage }` | Independent settlement of provider-reported nested usage |
-| `task-result` | `{ version: 2, task }` | Bounded terminal `TaskSnapshot` |
+| `task-record` | `{ version: 3, task, usage? }` | Bounded terminal `TaskSnapshot` and its settlement of provider-reported nested usage |
 
-`taskId` is the execution/group ID, not a worker display number. `usage` has the `Usage` shape above. Consumers count only the first valid usage record 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.
+`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), `title`, `toolCallId`, `anchorId`, `mode`, `status`, and numeric millisecond `startedAt`; optional fields include `endedAt`, `command`, `commandTruncated`, `cwd`, `exitCode`, `outputPath`, `result`, `resultTruncated`, and `error`. 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 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`.
 
-The retained tool result contains bounded text (up to 48 KiB) and 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.
+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.
 
-Terminal history is restored only from the selected branch's valid version-2 result records; older fields such as `format` and `projection` are ignored. Version-1 result records are ignored without migration; their independent usage entries still participate in accounting. This is read-only history: no processes or workers are restarted or reattached, and restoration does not replay usage settlement or completion events. Forks can carry historical entries on their copied path, never live execution handles.
+Terminal history is restored only from the selected branch's valid version-3 records. Released sessions also contain `task-result` records (versions 1 and 2) and separate version-1 `task-usage` entries, `{ version: 1, taskId, usage }`. Those results are ignored without migration, while their usage entries still count toward session totals. This is read-only history: no processes or workers are restarted or reattached, and restoration does not replay usage settlement or completion events. Forks can carry historical entries on their copied path, never live execution handles.
 
-These `custom` entries do not enter model context. Automatic delivery creates a `custom_message` with `customType: "task-completion"`, `display: true`, and a self-contained `TaskCompletionSnapshot` in `details`. The session formats `content` from the same snapshot, with a total limit of 48 KiB and 2,000 lines, keeping only an 8 KiB output tail for the automatic model turn. Only `content` is sent to the model.
+These `custom` entries do not enter model context. Automatic terminal delivery creates a `custom_message` with `customType: "task-completion"`, `display: true`, and `{ version: 3, task }` in `details`. The session formats `content` from the same snapshot, with a total limit of 48 KiB and 2,000 lines. A `log` task contributes only an 8 KiB output tail to the automatic model turn; a `report` task contributes its beginning, whole when it fits. Only `content` is sent to the model.
 
-Completion details use one format, `version: 2`, bounded to 120 KiB of serialized JSON including escaping. It has `version`, `kind`, `taskId`, `title`, terminal `status`, numeric millisecond `startedAt` and `endedAt`, and `output: { text, truncated }`, plus optional `error`, `command: { text, truncated }`, `cwd`, `outputPath`, and `exitCode` (a number, or `null` when signal-reaped).
-
-`output` is the end of the final result text, bounded to 40 KiB including JSON escaping for replay and expanded rendering; the smaller model-facing projection does not change this stored field. Source flags survive further clipping. Missing shell metadata is left unspecified. The renderer sanitizes terminal control sequences and applies separate display row limits.
+Completion details are bounded to 120 KiB of serialized JSON including escaping. `task` is the terminal snapshot without `display`. Its `input` is clipped to 8 KiB, and its `result` keeps the end of a log or the beginning of a report, up to 40 KiB for replay and expanded rendering. The smaller model-facing projection does not change these stored fields. Source flags survive further clipping. The renderer sanitizes terminal control sequences and applies separate display row limits.
 
 A shell completion's `details` can look like this:
 
 ```json
 {
-  "version": 2,
-  "taskId": "bash-12345678-abcd-4321-abcd-123456789012",
-  "kind": "bash",
-  "title": "npm run build",
-  "status": "completed",
-  "startedAt": 1733234400000,
-  "endedAt": 1733234405000,
-  "command": { "text": "npm run build", "truncated": false },
-  "cwd": "/project",
-  "outputPath": "/tmp/pi-bash-example.log",
-  "output": { "text": "Build finished", "truncated": false }
+  "version": 3,
+  "task": {
+    "id": "bash-12345678-abcd-4321-abcd-123456789012",
+    "kind": "bash",
+    "label": "Bash",
+    "title": "npm run build",
+    "output": "log",
+    "input": { "label": "Command", "text": "npm run build", "truncated": false, "language": "bash" },
+    "facts": [["Directory", "/project"], ["Exit", "0"]],
+    "toolCallId": "call_1",
+    "anchorId": "a1b2c3d4",
+    "mode": "background",
+    "status": "completed",
+    "startedAt": 1733234400000,
+    "endedAt": 1733234405000,
+    "outputPath": "/tmp/pi-bash-example.log",
+    "result": { "text": "Build finished", "truncated": false }
+  }
 }
 ```
 
-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 version 1, use bounded plain message text. There is no legacy text parser, dual-format reconstruction or migration.
+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()` is observational. 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.
 

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
 	"name": "@astralyn/pi",
-	"version": "1.4.4",
+	"version": "1.4.6",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@astralyn/pi",
-			"version": "1.4.4",
+			"version": "1.4.6",
 			"license": "MIT",
 			"dependencies": {
 				"@earendil-works/pi-agent-core": "1.4.0",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@astralyn/pi",
-	"version": "1.4.4",
+	"version": "1.4.6",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"piConfig": {

package/schemas/settings.schema.json

@@ -8,6 +8,18 @@
       "type": "string",
       "description": "JSON Schema reference."
     },
+    "extensionSettings": {
+      "type": "object",
+      "patternProperties": {
+        "^.*$": {
+          "type": "object",
+          "patternProperties": {
+            "^.*$": {}
+          }
+        }
+      },
+      "description": "Per-extension global JSON namespaces, written through the extension settings API."
+    },
     "lastChangelogVersion": {
       "type": "string"
     },