@astralyn/pi 1.3.0 → 1.4.0

package/docs/extensions.md

@@ -355,6 +355,74 @@ exit (Ctrl+C, Ctrl+D, SIGHUP, SIGTERM)
   └─► session_shutdown
 ```
 
+A normal prompt starts a run. The run repeats turns, then checks whether more work starts another low-level agent run:
+
+```mermaid
+flowchart TD
+    Input["input"] --> Before["before_agent_start"]
+    Before --> AgentStart["agent_start"]
+    AgentStart --> Turns[["turns"]]
+    Turns --> AgentEnd["agent_end"]
+    AgentEnd --> MoreRuns{"More work?"}
+    MoreRuns -->|yes| AgentStart
+    MoreRuns -->|no| BeforeSettle["agent_before_settle"]
+    BeforeSettle --> Continue{"Continuation requested?"}
+    Continue -->|yes| AgentStart
+    Continue -->|no| Settled["agent_settled"]
+```
+
+More work means a retry, recovery, compaction retry, or queued work.
+
+Each turn sends one model request and executes the tool calls in the assistant response:
+
+```mermaid
+flowchart TD
+    TurnStart["turn_start"] --> Request[["model request"]]
+    Request --> ToolDecision{"Tool calls?"}
+    ToolDecision -->|yes| Tools[["tool execution"]]
+    Tools --> TurnEnd["turn_end"]
+    ToolDecision -->|no| TurnEnd
+    TurnEnd --> MoreTurns{"Another turn?"}
+    MoreTurns -->|yes| TurnStart
+    MoreTurns -->|no| AgentEnd(["agent_end"])
+```
+
+The model request runs these hooks in order: `context`, `context_with_system`, `before_provider_headers`, `before_provider_request`, `after_provider_response`, then `provider_stream_event` and assistant message events. Tool execution runs `tool_execution_start`, `tool_call`, `tool_execution_update` while the tool executes, `tool_result`, and `tool_execution_end`.
+
+The lifecycle involves these event groups:
+
+| Area | Events |
+|---|---|
+| Input preparation | `input`, `before_agent_start` |
+| Agent run | `agent_start`, `agent_end` |
+| Model turn | `turn_start`, `context`, `context_with_system`, `turn_end` |
+| Provider call | `before_provider_headers`, `before_provider_request`, `after_provider_response`, `provider_stream_event` |
+| Message lifecycle | `message_start`, `message_update`, `message_end` |
+| Tool execution | `tool_execution_start`, `tool_call`, `tool_execution_update`, `tool_result`, `tool_execution_end` |
+| Settlement | `agent_before_settle`, `agent_settled` |
+
+Pi counts as busy while a run starts, including the compaction check and `before_agent_start`, so messages sent meanwhile go into the starting run. Message lifecycle events also cover user and tool-result messages; the model request list places only the assistant stream where it occurs in each turn.
+
+Retries, recovery, compaction, and queued messages can start another agent run after `agent_end`, so `agent_end` is not a final-idle signal. Reload and session replacement invalidate the old runtime. Code after `await ctx.reload()` still belongs to the old runtime and must not reuse its session-bound state.
+
+### Choose an event by intent
+
+| Goal | Event |
+|---|---|
+| Inspect, transform, or consume raw user input | `input` |
+| Change prompt sections, active tools, or add context before a run | `before_agent_start` |
+| Observe one low-level agent run | `agent_start`, `agent_end` |
+| Act after one model response and its tool calls | `turn_end` |
+| Filter conversation messages for one provider request | `context` |
+| Transform the complete transcript, including system messages | `context_with_system` |
+| Change request headers or the serialized provider payload | `before_provider_headers`, `before_provider_request` |
+| Observe provider response metadata or parsed stream events | `after_provider_response`, `provider_stream_event` |
+| Authorize or modify a tool call | `tool_call` |
+| Redact, annotate, or replace a tool result | `tool_result` |
+| Append final entries or request one last continuation | `agent_before_settle` |
+| Run notification work after automatic processing has stopped | `agent_settled` |
+| Initialize or release session-scoped resources | `session_start`, `session_shutdown` |
+
 ### Startup Events
 
 #### project_trust
@@ -1068,6 +1136,19 @@ pi.on("input", async (event, ctx) => {
 
 Transforms chain across handlers. See [input-transform.ts](../examples/extensions/input-transform.ts) and [input-transform-streaming.ts](../examples/extensions/input-transform-streaming.ts) for `streamingBehavior`-aware routing.
 
+### Understand handler composition
+
+| Pattern | Behavior |
+|---|---|
+| Notification | Return values are ignored. Use the event for observation only. |
+| In-place mutation | Later handlers see changes to values such as `before_provider_headers.headers`, `before_agent_start.systemPromptOptions`, and `tool_call.input`. |
+| Chained transformation | Later handlers receive the value returned by earlier `input`, `context`, `context_with_system`, `message_end`, `tool_result`, and `before_provider_request` handlers. |
+| Gate | A handled input, blocked tool call, cancelled session operation, or handled `user_bash` command stops that operation's normal fallback path. |
+| Actionable boundary | Each `turn_end` or `agent_before_settle` handler sees the entries and continuation decision proposed so far. |
+| Last override | The last `cache_warming_decision` handler that returns an action wins. |
+
+Notification handlers should not perform slow work on a streaming event. Transform handlers should preserve fields they do not intentionally own, and gate handlers should fail closed when their safety decision cannot be made.
+
 ## ExtensionContext
 
 All handlers receive `ctx: ExtensionContext`.
@@ -1167,7 +1248,8 @@ Session-bound `TasksContext` supervises native and extension-owned execution. Fo
 | `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 |
-| `wait(id, timeoutMs?, signal?)` | Observation only; timeout or cancellation ends the wait, not execution |
+| `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 |
 | `detach(id)` / `detachForeground()` | Hands off one task, or eligible foreground tasks oldest first while background slots remain, without restarting them; throws when every background slot is taken |
 | `canDetach(id)` | Reports whether an execution can move now, including host policy and available background slots; does not change the execution |
@@ -1181,7 +1263,7 @@ Session-bound `TasksContext` supervises native and extension-owned execution. Fo
 
 `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.
 
-Completion messages store a self-contained `TaskCompletionSnapshot`; 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. Ordinary extension reads/waits do not acknowledge delivery, and arbitrary tool-result detail fields cannot acknowledge a task.
+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.
 
 ```typescript
 const outcome = await ctx.tasks.execute({
@@ -3206,7 +3288,20 @@ Use `ctx.mode === "tui"` before TUI-specific features (`custom()`, component fac
 
 ## Examples
 
-The complete, maintained catalog is [examples/extensions/README.md](../examples/extensions/README.md). Use it to find a focused starting point by capability.
+The checked [extension examples](../examples/extensions/) are the implementation reference. Start with the smallest example matching the behavior you need:
+
+| Goal | Start with | Why |
+|---|---|---|
+| Confirm or block tool calls | [`permission-gate.ts`](../examples/extensions/permission-gate.ts) | Combines `tool_call`, mode-aware UI, and fail-closed behavior. |
+| Modify prompt sections for a run | [`prompt-customizer.ts`](../examples/extensions/prompt-customizer.ts) | Uses structured prompt options instead of replacing the complete prompt. |
+| Register tools after startup | [`dynamic-tools.ts`](../examples/extensions/dynamic-tools.ts) | Shares registration logic between lifecycle and command handlers. |
+| Run cancellable model work from a command | [`qna.ts`](../examples/extensions/qna.ts) | Combines nested model calls, cancellation, and custom UI. |
+| Replace the main editor | [`modal-editor.ts`](../examples/extensions/modal-editor.ts) | Extends `CustomEditor` while preserving application controls. |
+| Run finalization at shutdown | [`auto-commit-on-exit.ts`](../examples/extensions/auto-commit-on-exit.ts) | Uses the session shutdown hook for finalization work. |
+| Route built-in tools to another machine | [`ssh.ts`](../examples/extensions/ssh.ts) | Reuses tool operation interfaces instead of recreating tool contracts. |
+| Add OAuth and provider-specific streaming | [`custom-provider-gitlab-duo/`](../examples/extensions/custom-provider-gitlab-duo/) | Shows a complete provider integration while delegating supported protocols. |
+
+Use [Custom Providers](custom-provider.md) for model-service integrations, [Terminal UI](tui.md) for custom components, and [Pi Packages](packages.md) to install or distribute extensions with other resources. Use the exported declarations for exact signatures, payloads, and result schemas; this guide focuses on lifecycle choices, composition, and durable implementation patterns.
 
 ## Tool orchestration
 

package/docs/models-configuration.md

@@ -0,0 +1,196 @@
+# Models Configuration
+
+<!-- This file is generated from TypeScript source. Do not edit it manually; run npm run generate:references. -->
+
+This reference lists the fields of `models.json`. See [Configure a compatible endpoint](models.md#minimal-example) for examples; the file lives at `~/.pi/agent/models.json` or `<project-dir>/.pi/models.json`.
+
+Add `"$schema": "https://raw.githubusercontent.com/ming-kang/pi/main/schemas/models.schema.json"` to `models.json` for editor validation and completion.
+
+## Providers
+
+Each key under `providers` is a provider ID. A built-in provider ID changes that provider. Any other ID adds a provider, which needs `baseUrl` and an `api` at provider or model level.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `name` | string |  | Display name. |
+| `baseUrl` | string |  | API base URL. Also applies to the provider's built-in models. |
+| `apiKey` | string |  | Literal key, "$NAME" environment interpolation, or "!command" output. |
+| `api` | string |  | API for the provider's models, such as "openai-completions", "openai-responses", "anthropic-messages", or "google-generative-ai". |
+| `oauth` | `"radius"` |  | OAuth login flow. Requires baseUrl. |
+| `headers` | object |  | Request headers. Values resolve like apiKey. |
+| `compat` | [object](#compatibility) |  | Provider and model compatibility overrides. |
+| `authHeader` | boolean | `false` | Whether to send the resolved API key as Authorization: Bearer. |
+| `models` | [`object[]`](#models) |  |  |
+| `modelOverrides` | [object](#model-overrides) |  |  |
+
+## Models
+
+Each `models` entry adds a model to the provider. An entry whose `id` matches an existing model replaces it.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `id` | string |  | Required. Model ID sent to the API. |
+| `name` | string |  | Display name, also matched by --model patterns. |
+| `api` | string |  | Overrides the provider api. |
+| `baseUrl` | string |  | Overrides the provider baseUrl. |
+| `reasoning` | boolean | `false` | Whether the model supports thinking. |
+| `thinkingLevelMap` | object |  | Provider value sent for each thinking level. null marks a level unsupported. Levels the model does not map use the provider's default value through high; xhigh and max are unsupported. |
+| `input` | `("text" \| "image")[]` | `["text"]` |  |
+| `inputLimits` | [object](#input-limits) |  |  |
+| `cost` | object |  |  |
+| `cost.input` | number |  | Required. Input cost in USD per million tokens. |
+| `cost.output` | number |  | Required. Output cost in USD per million tokens. |
+| `cost.cacheRead` | number |  | Required. Cache-read cost in USD per million tokens. |
+| `cost.cacheWrite` | number |  | Required. Cache-write cost in USD per million tokens. |
+| `cost.tiers` | `object[]` |  | Request-wide pricing tiers. The highest matching input threshold applies to the full request. |
+| `cost.tiers[].inputTokensAbove` | number |  | Required. Use this tier when total request input exceeds this token count. |
+| `cost.tiers[].input` | number |  | Required. Input cost in USD per million tokens. |
+| `cost.tiers[].output` | number |  | Required. Output cost in USD per million tokens. |
+| `cost.tiers[].cacheRead` | number |  | Required. Cache-read cost in USD per million tokens. |
+| `cost.tiers[].cacheWrite` | number |  | Required. Cache-write cost in USD per million tokens. |
+| `promptCache` | object |  | Best-effort prompt cache lifetime in seconds for the short and long retention tiers. Pi warms only tiers with a known lifetime. |
+| `contextWindow` | number | `128000` | Context window in tokens. |
+| `maxTokens` | number | `16384` | Maximum output tokens. |
+| `samplingParams` | object |  | Fields merged into every request body. Applies only to OpenAI-compatible APIs. |
+| `samplingParamsByThinkingLevel` | object |  | samplingParams per thinking level, merged over samplingParams. |
+| `headers` | object |  | Request headers. Values resolve like apiKey. |
+| `compat` | [object](#compatibility) |  | Provider and model compatibility overrides. |
+
+## Model overrides
+
+Each `modelOverrides` key is the ID of a built-in or extension model. Unknown IDs are ignored. Object fields, such as `cost`, merge with the model's value field by field; other fields replace it.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `name` | string |  | Display name, also matched by --model patterns. |
+| `reasoning` | boolean |  | Whether the model supports thinking. |
+| `thinkingLevelMap` | object |  | Provider value sent for each thinking level. null marks a level unsupported. Levels the model does not map use the provider's default value through high; xhigh and max are unsupported. |
+| `input` | `("text" \| "image")[]` |  |  |
+| `inputLimits` | [object](#input-limits) |  |  |
+| `cost` | object |  |  |
+| `cost.input` | number |  | Input cost in USD per million tokens. |
+| `cost.output` | number |  | Output cost in USD per million tokens. |
+| `cost.cacheRead` | number |  | Cache-read cost in USD per million tokens. |
+| `cost.cacheWrite` | number |  | Cache-write cost in USD per million tokens. |
+| `cost.tiers` | `object[]` |  | Request-wide pricing tiers. The highest matching input threshold applies to the full request. |
+| `cost.tiers[].inputTokensAbove` | number |  | Required. Use this tier when total request input exceeds this token count. |
+| `cost.tiers[].input` | number |  | Required. Input cost in USD per million tokens. |
+| `cost.tiers[].output` | number |  | Required. Output cost in USD per million tokens. |
+| `cost.tiers[].cacheRead` | number |  | Required. Cache-read cost in USD per million tokens. |
+| `cost.tiers[].cacheWrite` | number |  | Required. Cache-write cost in USD per million tokens. |
+| `promptCache` | object |  | Best-effort prompt cache lifetime in seconds for the short and long retention tiers. Pi warms only tiers with a known lifetime. |
+| `contextWindow` | number |  | Context window in tokens. |
+| `maxTokens` | number |  | Maximum output tokens. |
+| `samplingParams` | object |  | Fields merged into every request body. Applies only to OpenAI-compatible APIs. |
+| `samplingParamsByThinkingLevel` | object |  | samplingParams per thinking level, merged over samplingParams. |
+| `headers` | object |  | Request headers. Values resolve like apiKey. |
+| `compat` | [object](#compatibility) |  | Provider and model compatibility overrides. |
+
+## Input limits
+
+See [Describe model input and caching](models.md#describe-model-input-and-caching).
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `maxRequestBytes` | integer |  | Maximum serialized provider request size in bytes. |
+| `images` | object |  |  |
+| `images.resize` | object |  | Cache-safe resize profile applied before a new image enters conversation history. |
+| `images.resize.maxWidth` | integer |  |  |
+| `images.resize.maxHeight` | integer |  |  |
+| `images.resize.maxBytes` | integer |  | Maximum base64-encoded payload size in bytes. |
+| `images.resize.jpegQuality` | integer |  |  |
+| `images.maxPerMessage` | integer |  | Maximum images accepted in one provider message. |
+| `images.maxPerRequest` | integer |  | Maximum images accepted across one provider request. |
+
+## Compatibility
+
+`compat` describes verified differences from an API's standard request and response behavior. Model values override provider values per field. The fields that apply depend on the model's `api`.
+
+### `openai-completions`
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `supportsStore` | boolean |  | Whether the provider supports the store field. Default: auto-detected from URL. |
+| `supportsDeveloperRole` | boolean |  | Whether the provider supports the developer role instead of system. Default: auto-detected from URL. |
+| `supportsReasoningEffort` | boolean |  | Whether the provider supports reasoning_effort. Default: auto-detected from URL. |
+| `supportsUsageInStreaming` | boolean | `true` | Whether the provider supports stream_options.include_usage for token usage in streaming responses. |
+| `supportsFinishReason` | boolean | `true` | Whether streamed responses include finish_reason. When false, pi infers stop or toolUse when the stream ends. |
+| `maxTokensField` | `"max_completion_tokens" \| "max_tokens"` |  | Which field to use for max tokens. Default: auto-detected from URL. |
+| `requiresToolResultName` | boolean |  | Whether tool results require the name field. Default: auto-detected from URL. |
+| `requiresAssistantAfterToolResult` | boolean |  | Whether a user message after tool results requires an assistant message in between. Default: auto-detected from URL. |
+| `requiresThinkingAsText` | boolean |  | Whether thinking blocks must be converted to text blocks with &lt;thinking> delimiters. Default: auto-detected from URL. |
+| `requiresReasoningContentOnAssistantMessages` | boolean |  | Whether all replayed assistant messages must include an empty reasoning_content field when reasoning is enabled. Default: auto-detected from URL. |
+| `thinkingFormat` | `"openai" \| "openrouter" \| "deepseek" \| "together" \| "baseten" \| "zai" \| "qwen" \| "chat-template" \| "qwen-chat-template" \| "string-thinking" \| "ant-ling"` |  | Format for reasoning or thinking parameters. When omitted, Pi auto-detects the format from the provider URL. "openai" uses reasoning_effort, "openrouter" uses reasoning.effort, "deepseek" uses thinking.type plus reasoning_effort when supported, "together" uses reasoning.enabled plus reasoning_effort when supported, "baseten" uses configurable chat_template_args plus reasoning_effort when supported, "zai" uses thinking.type, "qwen" uses top-level enable_thinking, "qwen-chat-template" uses chat_template_kwargs.enable_thinking and preserve_thinking, "chat-template" uses configurable chat_template_kwargs, "string-thinking" uses top-level thinking, and "ant-ling" uses reasoning.effort only when the mapped effort is non-null. |
+| `chatTemplateKwargs` | object |  | Kwargs sent as chat_template_kwargs when thinkingFormat is "chat-template". Use $var with "thinking.enabled", "thinking.effort", or "thinking.budget" for pi-controlled values. |
+| `chatTemplateArgs` | object |  | Arguments sent as chat_template_args when thinkingFormat is "baseten". Use $var with "thinking.enabled", "thinking.effort", or "thinking.budget" for pi-controlled values. |
+| `openRouterRouting` | object |  | OpenRouter provider routing preferences. Controls which upstream providers OpenRouter routes requests to. Sent as the provider field in the OpenRouter API request body. See https://openrouter.ai/docs/guides/routing/provider-selection. |
+| `vercelGatewayRouting` | object |  | Vercel AI Gateway routing preferences. Controls which upstream providers the gateway routes requests to. See https://vercel.com/docs/ai-gateway/models-and-providers/provider-options. |
+| `zaiToolStream` | boolean | `false` | Whether z.ai supports top-level tool_stream for streaming tool call deltas. |
+| `thinkingTokenBudgetField` | `"thinking_token_budget" \| "thinking_budget" \| "thinking_budget_tokens"` |  | Top-level request field used to cap reasoning tokens from thinkingBudgets. Reasoning and the answer share max_tokens on these endpoints. "thinking_token_budget" is vLLM, "thinking_budget" is Qwen, DashScope, or SGLang, and "thinking_budget_tokens" is llama.cpp. Off by default and not set on the generated catalog. |
+| `supportsThinkingTokenBudget` | boolean | `false` | Alias for thinkingTokenBudgetField: "thinking_token_budget" (vLLM). Prefer thinkingTokenBudgetField. |
+| `supportsOpenAIGrammarTools` | boolean | `false` | Whether the provider supports OpenAI custom tools with Lark or regex grammar formats. When false, grammar-constrained tools fall back to normal function tools. The generated catalog enables this for capable models. |
+| `supportsMidConvoSystemMessages` | boolean | `false` | Whether the exact model accepts system or developer messages after the conversation has started. When false, later system messages are folded into the leading system message. The generated catalog enables this for verified models. |
+| `supportsMidConvoToolAdditions` | boolean | `false` | Whether system messages can introduce additional tools mid-conversation. Requires supportsMidConvoSystemMessages. The generated catalog enables this for capable models. |
+| `supportsStrictMode` | boolean | `false` | Whether the provider supports the strict field in tool definitions. Generated capable models enable it explicitly. |
+| `cacheControlFormat` | `"anthropic"` |  | Cache control convention for prompt caching. Anthropic applies cache_control markers to the system prompt, last tool definition, and last user, assistant, or tool-result text content. |
+| `sendSessionAffinityHeaders` | boolean |  | Whether to send session-affinity data from options.sessionId. Default: true for OpenRouter endpoints, false otherwise. |
+| `sessionAffinityFormat` | `"openai" \| "openai-nosession" \| "openrouter"` |  | Session-affinity header format. openai sends session_id, x-client-request-id, and x-session-affinity; openai-nosession sends x-client-request-id and x-session-affinity; openrouter sends x-session-id. Does not affect prompt_cache_key. Default: auto-detected. |
+| `supportsLongCacheRetention` | boolean |  | Whether the provider supports long prompt cache retention (prompt_cache_retention: "24h" or Anthropic-style cache_control.ttl: "1h", depending on format). Default: auto-detected from provider and URL. |
+| `vllmPriority` | number |  | vLLM scheduler priority sent as the top-level priority request field. Lower values are handled earlier and the server default is 0. Only meaningful with --scheduling-policy priority. Off by default and not set on the generated catalog. |
+
+### `openai-responses`
+
+Also applies to `azure-openai-responses` and `openai-codex-responses`.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `supportsDeveloperRole` | boolean | `true` | Whether the provider supports the developer role instead of system. |
+| `supportsMidConvoSystemMessages` | boolean | `false` | Whether the exact model accepts developer or system messages after the conversation has started. When false, later system messages are folded into the leading system message. The generated catalog enables this for verified models. |
+| `sessionAffinityFormat` | `"openai" \| "openai-nosession" \| "openrouter"` |  | Session-affinity header format. openai sends session_id and x-client-request-id; openai-nosession sends x-client-request-id; openrouter sends x-session-id. Does not affect prompt_cache_key. Default: auto-detected. |
+| `supportsLongCacheRetention` | boolean | `true` | Whether the provider supports long prompt cache retention. This uses prompt_cache_options.ttl: "30m" on GPT-5.6+ and prompt_cache_retention: "24h" on earlier models. |
+| `supportsStrictMode` | boolean |  | Whether the provider supports strict JSON-schema function tools. Defaults are API-specific; generated OpenAI models enable it explicitly. |
+| `supportsOpenAIGrammarTools` | boolean | `false` | Whether to emit OpenAI custom tools with Lark or regex grammar formats. When false, grammar-constrained tools fall back to normal function tools. The generated catalog enables this for capable models. |
+| `supportsAdditionalTools` | boolean | `false` | Whether the model supports message-anchored additional_tools input items. |
+| `supportsToolSearch` | boolean | `false` | Whether the model supports client-executed tool search for transcript-anchored additions. |
+| `supportsExplicitPromptCacheMode` | boolean | `false` | Whether the model accepts prompt_cache_options. Older OpenAI models reject the parameter. |
+| `supportsMidConvoEffort` | boolean | `false` | Whether thinking level changes are sent as configuration_update input items instead of changing reasoning.effort, so a change keeps the prompt cache. Only used by the openai-responses API, and ignored with Sign in with ChatGPT on the openai provider. |
+| `supportsMaxOutputTokens` | boolean | `true` | Whether the provider accepts max_output_tokens. Some Codex-protocol gateways reject it. |
+
+### `anthropic-messages`
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `supportsEagerToolInputStreaming` | boolean | `true` | Whether the provider accepts per-tool eager_input_streaming. When false, the Anthropic provider omits tools[].eager_input_streaming and sends the legacy fine-grained-tool-streaming-2025-05-14 beta header for tool-enabled requests. |
+| `supportsLongCacheRetention` | boolean | `true` | Whether the provider supports Anthropic long cache retention through cache_control.ttl. |
+| `sendSessionAffinityHeaders` | boolean |  | Whether to send x-session-affinity from options.sessionId when caching is enabled. Required for providers like Fireworks that use session affinity for prompt cache routing; requests to the same replica maximize cache hits. Default: true for OpenRouter endpoints, false otherwise. |
+| `sessionAffinityFormat` | `"openrouter"` |  | Session-affinity format. openrouter sends x-session-id; when unset, sends x-session-affinity. |
+| `supportsCacheControlOnTools` | boolean | `true` | Whether the provider supports Anthropic-style cache_control markers on tool definitions. When false, cache_control is omitted from tool parameters. Some Anthropic-compatible providers, such as Fireworks, do not support this field on tools and may reject or ignore it. |
+| `supportsTemperature` | boolean | `true` | Whether the model accepts the Anthropic temperature request field. Claude Opus 4.7+ rejects non-default values. |
+| `forceAdaptiveThinking` | boolean | `false` | Whether to force adaptive thinking (thinking.type: adaptive plus output_config.effort) regardless of model ID. Built-in models that require adaptive thinking set this in generated metadata. Custom Anthropic-compatible providers can set this to true for any model whose upstream requires the adaptive format. Set false to opt out on overridden built-in models. |
+| `allowEmptySignature` | boolean | `false` | Whether to replay empty thinking signatures instead of converting thinking to text. |
+| `supportsStrictTools` | boolean | `false` | Whether the provider supports Anthropic strict tool schemas. Generated Anthropic models enable it explicitly. |
+| `supportsMidConvoEffort` | boolean | `false` | Whether the exact model transport supports effort-only system messages and thinking binding controls. |
+| `supportsMidConvoSystemMessages` | boolean | `false` | Whether the exact model accepts system-role messages inside the conversation. When false, later system messages are folded into the top-level system prompt. |
+| `supportsMidConvoToolChanges` | boolean | `false` | Whether the exact model accepts mid-conversation tool_addition and tool_removal blocks. Requires supportsMidConvoSystemMessages. |
+| `allowedFallbackModels` | `object[]` |  | Models Anthropic accepts for server-side refusal fallback, with local pricing metadata for returned fallback responses. When absent or empty, callers must omit fallbacks; Anthropic rejects the field for models with no permitted fallback targets. |
+
+### `bedrock-converse-stream`
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `supportsStrictMode` | boolean | `false` | Whether the model supports Bedrock strict tool schemas. |
+
+### `mistral-conversations`
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `supportsMidConvoSystemMessages` | boolean | `false` | Whether the exact model accepts system messages after the conversation has started. When false, later system messages are folded into the leading system message. |
+
+### `typesafe-system-one`
+
+Also applies to `cloudflare-workers-ai-system-one`.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `imageInput` | `"assets" \| "images" \| "state-image-urls"` |  | How the service takes classifier images. "assets" sends TypeSafe's assets map (PNG and JPEG) and references the images from the state, as TypeSafe and Jev on Workers AI expect. "images" sends Clef's images list of data URLs (PNG, JPEG, and WebP, at most four), as Clef on Workers AI expects. "state-image-urls" places image_url parts before the state, as OpenRouter expects; OpenRouter drops assets without an error. Auto-detected from the provider, baseUrl, and model ID. Classifier models read it from the provider-level compat; models and modelOverrides entries apply to chat models only. |
+| `sendImageOptInHeader` | boolean |  | Whether requests with images send the TypeSafe-Danger-Zone-Images: true header, which TypeSafe's own API requires for its experimental image input. Defaults to true for the typesafe-system-one API unless the model is detected as OpenRouter. |

package/docs/models.md

@@ -72,7 +72,7 @@ Some OpenAI-compatible servers do not understand the `developer` role Pi uses fo
 }
 ```
 
-Provider `compat` supplies defaults for its models; a model's `compat` refines those defaults. See [Compatibility Options](#compatibility-options).
+Provider `compat` supplies defaults for its models; a model's `compat` refines those defaults. See [Compatibility Options](#compatibility-options) and the generated [Models Configuration](models-configuration.md) reference for every field.
 
 ## Full Example
 
@@ -704,20 +704,20 @@ For `bedrock-converse-stream`, `compat.supportsStrictMode` controls Bedrock stri
 
 ## Use classifier models
 
-Classifier models do not chat. They answer typed questions about JSON state: pick one of several choices, answer yes or no, or give a score, each with probabilities. Pi includes TypeSafe's Jev model from these providers, Cloudflare's Clef and Clef Flash models from Workers AI, and OpenAI's GPT-6 Luna through the [Decisions API](https://developers.openai.com/api/docs/guides/decisions):
+Classifier models do not chat. They answer typed questions about JSON state: pick one of several choices, answer yes or no, or give a score, each with probabilities. Pi includes TypeSafe's Jev model from these providers, Cloudflare's Clef, Clef Flash, and Clef Omni models from Workers AI and OpenRouter, and OpenAI's GPT-6 Luna through the [Decisions API](https://developers.openai.com/api/docs/guides/decisions):
 
 | Provider | Model IDs | Authentication |
 |---|---|---|
 | `typesafe` | `jev-latest` | `TYPESAFE_API_KEY` |
-| `openrouter` | `typesafe/jev-1.13`, `~typesafe/jev-latest` | `OPENROUTER_API_KEY` or `/login` |
-| `cloudflare-workers-ai` | `typesafe/jev`, `@cf/cloudflare/clef`, `@cf/cloudflare/clef-flash` | `CLOUDFLARE_API_KEY` and `CLOUDFLARE_ACCOUNT_ID` |
+| `openrouter` | `typesafe/jev-1.13`, `typesafe/jev-1.14`, `~typesafe/jev-latest`, `cloudflare/clef`, `cloudflare/clef-flash`, `cloudflare/clef-omni` | `OPENROUTER_API_KEY` or `/login` |
+| `cloudflare-workers-ai` | `typesafe/jev`, `typesafe/jev-1.14.0`, `@cf/cloudflare/clef`, `@cf/cloudflare/clef-flash`, `@cf/cloudflare/clef-omni` | `CLOUDFLARE_API_KEY` and `CLOUDFLARE_ACCOUNT_ID` |
 | `vercel-ai-gateway` | `typesafe-ai/jev` | `AI_GATEWAY_API_KEY` |
 | `opencode` | `jev-1.13`, `jev-1.13-free` | `OPENCODE_API_KEY` |
 | `openai` | `gpt-6-luna` | `OPENAI_API_KEY` |
 
 Chat models on a [llama.cpp router](llama-cpp.md#classification) are also listed as classifier models.
 
-OpenAI's Decisions API needs an API key. Sign in with ChatGPT credentials do not work with it, so `gpt-6-luna` is not listed as available while `openai` is logged in through `/login`, even when `OPENAI_API_KEY` is set; log out of `openai` to use the key. GPT-6 Luna also judges images passed in `images` (see [Codemode](codemode.md#classify)); other classifier models return an error for them. The API rejects inputs above 922K tokens, but requests that run longer than about five seconds, currently above roughly 600K input tokens, fail with a gateway timeout.
+OpenAI's Decisions API needs an API key. Sign in with ChatGPT credentials do not work with it, so `gpt-6-luna` is not listed as available while `openai` is logged in through `/login`, even when `OPENAI_API_KEY` is set; log out of `openai` to use the key. The API rejects inputs above 922K tokens, but requests that run longer than about five seconds, currently above roughly 600K input tokens, fail with a gateway timeout.
 
 Classifier models do not appear in `/model`. The model reaches them through the [`codemode`](usage.md#enable-codemode) tool, which is off unless an MCP server turned it on. Enable it with `"defaultTools": ["+codemode"]` in [settings](settings.md#tools). Scripts then list classifier models with `models.getAvailableOfType("classifier")` and call `models.classify(model, { state, questions })`:
 
@@ -738,6 +738,10 @@ return result.answers;
 
 [Codemode](codemode.md#classify) describes the question and answer types.
 
+Classifier models whose `input` includes `"image"` also judge images passed in `images`; other classifier models return an error for them. Image input works with GPT-6 Luna, with Jev from `typesafe` and `cloudflare-workers-ai`, with Clef from `cloudflare-workers-ai`, and with the OpenRouter models whose catalog lists image input. Jev takes PNG and JPEG images, and image input is experimental on TypeSafe's own API. Clef takes PNG, JPEG, and WebP images, at most four per request. Jev from `vercel-ai-gateway` and `opencode` takes text only.
+
+Each System One service takes images in its own request format, set by the model's `compat.imageInput`. Built-in models set it, so overriding a provider's `baseUrl` keeps it. A custom provider that proxies another service's classifiers sets it in its provider-level `compat` in `models.json` (see [System One compatibility](models-configuration.md#typesafe-system-one)). OpenRouter in particular answers requests in TypeSafe's format without an error but drops the images.
+
 When the service reports token counts, as all System One services do, `result.usage` carries them with their cost. Pi adds the usage of a script's classifier calls to the `codemode` tool result, so it counts toward the session cost in the footer and `/session`. The cost uses the model's catalog price; models without one, such as TypeSafe's direct `jev-latest`, report tokens at no cost.
 
 Extensions call classifiers through `ctx.modelRegistry.classify()`, without codemode. [Virtual models](virtual-models.md#route-requests) can use them to route requests; see the `jev-router.ts` example.

package/docs/sdk.md

@@ -254,7 +254,7 @@ 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()` and `wait()` observe; a terminal snapshot alone does not acknowledge model delivery. The built-in `tasks wait` tool binds a delivery receipt to its tool-call ID; the host confirms it only after persisting the result, even if extensions rewrite its details. A direct SDK waiter that consumes the result outside model history can explicitly call `session.tasks.markDelivered(task.id)` after successful consumption. 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). `read()`, `wait()`, and `waitAny()` observe; a terminal snapshot alone does not acknowledge model delivery. `waitAny()` covers only tasks running at call time and returns `undefined` for an empty cohort, timeout, interruption, or closed host. The optional `interruptSignal` ends only a wait. The built-in `tasks wait` tool binds a delivery receipt to its tool-call ID; the host confirms it only after persisting the result, even if extensions rewrite its details. A direct SDK waiter that consumes the result outside model history can explicitly call `session.tasks.markDelivered(task.id)` after successful consumption. 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.
 - **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.
 
 A deliberately single-turn embedding can suppress completion-triggered turns and cancel leftover work on exit:
@@ -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, the tail of the output, diagnostics and explicit truncation flags. This snapshot is self-contained for transcript replay and is not sent to the model; `content` contains the separately bounded prose generated from it. 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 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).
 
 `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.
 

package/docs/session-format.md

@@ -351,11 +351,11 @@ The retained tool result contains bounded text (up to 48 KiB) and no executor-pr
 
 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.
 
-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 the end of the output. Only `content` is sent to the model.
+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.
 
 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. Source flags survive further clipping. Missing shell metadata is left unspecified. The renderer sanitizes terminal control sequences and applies separate display row limits.
+`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.
 
 A shell completion's `details` can look like this:
 

package/docs/settings.md

@@ -142,7 +142,7 @@ Version checks read the latest `@astralyn/pi` version from npm. Set `PI_SKIP_VER
 |---------|------|---------|-------------|
 | `compaction.enabled` | boolean | `true` | Enable auto-compaction |
 | `compaction.triggerPercent` | number | `85` | Percentage of the context window that triggers auto-compaction (clamped to 20–95) |
-| `compaction.reserveTokens` | number | derived | Fixed reserve below the context window; overrides `triggerPercent` |
+| `compaction.reserveTokens` | number | derived | Free context tokens below which automatic compaction starts; overrides `triggerPercent` |
 | `compaction.keepRecentTokens` | number | `20000` | Recent-message retention target, capped at half the trigger line when the reserve is derived |
 | `compaction.modelOverrides` | object | - | Per-model `reserveTokens` / `keepRecentTokens` overrides keyed by exact `"provider/modelId"` |
 
@@ -156,7 +156,7 @@ Version checks read the latest `@astralyn/pi` version from npm. Set `PI_SKIP_VER
 }
 ```
 
-Compaction triggers at `contextWindow − reserveTokens`. Unless `reserveTokens` is set, the reserve is derived from `triggerPercent` for the active model's window, so large-window models compact at 85% usage instead of upstream's ~98%. Setting `reserveTokens` restores a fixed reserve.
+Compaction triggers at `contextWindow − reserveTokens`. Unless `reserveTokens` is set, the reserve is derived from `triggerPercent` for the active model's window, so large-window models compact at 85% usage instead of upstream's ~98%. Setting `reserveTokens` restores a fixed reserve. Either way, summarization uses the model's output limit rather than the reserve.
 
 The retention target shrinks with a derived reserve without changing the saved settings. Whole messages and tool-call/result groups can exceed the retention target. See [Compaction](compaction.md#how-it-works) for the budget rules and examples.
 

package/docs/tui.md

@@ -105,6 +105,77 @@ const result = await ctx.ui.custom<string | null>((tui, theme, keybindings, done
 
 The factory receives Pi's current `TUI`, semantic `Theme`, and configured `KeybindingsManager`. It may return a component synchronously or as a promise. The `custom()` promise resolves only when the component calls `done(result)`.
 
+
+### Build a minimal custom screen
+
+This complete extension shows the custom-component lifecycle: render within the supplied width, use injected keybindings, invalidate cached output after state changes, request a render, and finish through `done()`.
+
+```typescript
+import type { ExtensionAPI } from "@astralyn/pi";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("pick-target", {
+    description: "Pick a deployment target",
+    handler: async (_args, ctx) => {
+      if (ctx.mode !== "tui") {
+        ctx.ui.notify("pick-target requires interactive mode", "error");
+        return;
+      }
+
+      const choices = ["development", "staging", "production"];
+      const selected = await ctx.ui.custom<string | undefined>((tui, theme, keybindings, done) => {
+        let selectedIndex = 0;
+        let cachedWidth: number | undefined;
+        let cachedLines: string[] | undefined;
+
+        const invalidate = () => {
+          cachedWidth = undefined;
+          cachedLines = undefined;
+        };
+
+        return {
+          render(width: number): string[] {
+            if (cachedLines && cachedWidth === width) return cachedLines;
+
+            cachedWidth = width;
+            cachedLines = [
+              theme.fg("accent", "Choose a deployment target"),
+              ...choices.map((choice, index) => `${index === selectedIndex ? "> " : "  "}${choice}`),
+              theme.fg("dim", "up/down move, enter selects, escape cancels"),
+            ].map((line) => truncateToWidth(line, width));
+            return cachedLines;
+          },
+          handleInput(data: string): void {
+            if (keybindings.matches(data, "tui.select.up")) {
+              selectedIndex = (selectedIndex - 1 + choices.length) % choices.length;
+            } else if (keybindings.matches(data, "tui.select.down")) {
+              selectedIndex = (selectedIndex + 1) % choices.length;
+            } else if (keybindings.matches(data, "tui.select.confirm")) {
+              done(choices[selectedIndex]);
+              return;
+            } else if (keybindings.matches(data, "tui.select.cancel")) {
+              done(undefined);
+              return;
+            } else {
+              return;
+            }
+
+            invalidate();
+            tui.requestRender();
+          },
+          invalidate,
+        };
+      });
+
+      if (selected) ctx.ui.notify(`Selected ${selected}`, "info");
+    },
+  });
+}
+```
+
+This component does not display a text cursor, so it does not need `Focusable`. A component containing `Input` or `Editor` must implement `Focusable` and propagate its `focused` value to that child.
+
 ### Disposal
 
 A component returned from `ctx.ui.custom()`, `setWidget()`, `setFooter()`, or `setHeader()` may also implement `dispose(): void`. Use it to stop timers, abort owned work, and unsubscribe listeners. Pi calls it after a custom component finishes, or when a widget, footer, or header is replaced or cleared.

package/docs/windows.md

@@ -8,10 +8,32 @@ Pi uses Git Bash by default on Windows. Checked locations (in order):
 
 For most users, [Git for Windows](https://git-scm.com/download/win) is sufficient.
 
+Pi resolves Bash in this order:
+
+1. `shellPath` from `~/.pi/agent/settings.json`
+2. Git Bash at `%ProgramFiles%\Git\bin\bash.exe`
+3. Git Bash at `%ProgramFiles(x86)%\Git\bin\bash.exe`
+4. `bash.exe` on `PATH`, including Cygwin, MSYS2, or legacy WSL Bash
+
+Start Pi and enter this command to verify the shell:
+
+```text
+!echo "$BASH_VERSION"
+```
+
+If Pi cannot find Bash, it reports the locations it checked. Install Git for Windows, set `shellPath`, or add Bash to `PATH`.
+
 ## PowerShell Tool
 
 The optional `powershell` tool runs commands through `pwsh.exe` when available, otherwise Windows PowerShell. It starts PowerShell with `-NoProfile -NonInteractive -ExecutionPolicy Bypass`. Administrator-enforced execution policies can still take precedence.
 
+PowerShell discovery checks these locations in order:
+
+1. `pwsh.exe` on `PATH`
+2. `%ProgramFiles%\PowerShell\7\pwsh.exe`
+3. `powershell.exe` on `PATH`
+4. `%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe`
+
 Use `defaultTools` to replace the model-facing `bash` tool:
 
 ```json
@@ -30,6 +52,12 @@ Or enable both while comparing behavior:
 
 The `!` and `!!` editor commands still use Bash.
 
+## WSL
+
+WSL path conversion on Windows and extra Git branch polling in WSL recognize `/mnt/<drive>`, not custom mount roots.
+
+When using the legacy WSL `bash.exe` launcher from Windows, Pi sends commands over stdin to avoid command-line quoting problems.
+
 ## Custom Bash Path
 
 ```json

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "1.3.0",
+      "version": "1.4.0",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-anthropic",
   "private": true,
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-gitlab-duo",
   "private": true,
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",