pi-namespace-patch 1.2.0-namespace.2 → 1.4.0-namespace.1

package/docs/tui.md

@@ -65,6 +65,76 @@ Regular mode leaves mouse input to the terminal because the terminal owns scroll
 
 `ctx.ui.custom()` temporarily gives one component control of the interactive area and resolves when that component calls the supplied completion callback.
 
+### 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 "@earendil-works/pi-coding-agent";
+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.
+
 Pass `overlay: true` to draw above existing content. Overlay options control size, anchors, offsets, margins, and responsive visibility. An overlay handle can change focus or temporarily hide and show the overlay with `setHidden()` while the interaction remains active.
 
 Focused overlays retain input ownership across ordinary renders. If another component should receive input while an overlay remains visible, explicitly release or redirect focus through the handle.

package/docs/usage.md

@@ -79,7 +79,7 @@ Use `!!` when you want to run a command without sending its output to the model.
 
 Press `Ctrl+X` or run `/copy` to copy the last assistant response. Use `/export` to save the session as HTML or JSONL.
 
-Use `/share` to upload the session and get a viewer link. With Radius authentication, the artifact is visible to your Radius organization. Otherwise, Pi creates a private GitHub gist through the GitHub CLI. Review the session first because it can contain prompts, tool output, file contents, and credentials exposed during the conversation.
+Use `/share` to upload the session and get a viewer link. By default, Radius authentication makes the artifact visible to your Radius organization; otherwise, Pi creates a private GitHub gist through the GitHub CLI. The [`sessionShareDestination`](settings.md#sessions-and-context) setting can force either destination. Review the session first because it can contain prompts, tool output, file contents, and credentials exposed during the conversation.
 
 ## Adjust the terminal
 

package/docs/windows.md

@@ -19,8 +19,9 @@ For most native Windows users, installing [Git for Windows](https://git-scm.com/
 Pi resolves Bash in this order:
 
 1. `shellPath` from `~/.pi/agent/settings.json`
-2. Git Bash under `Program Files` or `Program Files (x86)`
-3. `bash.exe` on `PATH`, including Cygwin, MSYS2, or legacy WSL Bash
+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:
 
@@ -34,6 +35,13 @@ If Pi cannot find Bash, it reports the locations it checked. Install Git for Win
 
 The optional `powershell` tool runs commands through `pwsh.exe` when available, then falls back to 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`
+
 To replace the model-facing `bash` tool with `powershell`, add this to `~/.pi/agent/settings.json`:
 
 ```json
@@ -48,6 +56,12 @@ Restart Pi, then ask it to run a harmless PowerShell command. The `!` and `!!` e
 
 See [Settings](settings.md#tools) for other tool combinations.
 
+## 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.
+
 ## Use a custom Bash executable
 
 Set `shellPath` when Bash is installed somewhere Pi does not discover automatically:

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

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "1.2.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.2.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.2.0",
+  "version": "1.4.0",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/gondolin/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-gondolin",
-	"version": "1.2.0",
+	"version": "1.4.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-gondolin",
-			"version": "1.2.0",
+			"version": "1.4.0",
 			"dependencies": {
 				"@earendil-works/gondolin": "0.12.0"
 			}

package/examples/extensions/gondolin/package.json

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

package/examples/extensions/minimal-mode.ts

@@ -25,6 +25,7 @@ import {
 	createLsToolDefinition,
 	createReadToolDefinition,
 	createWriteToolDefinition,
+	formatReadLineRange,
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { homedir } from "os";
@@ -65,11 +66,9 @@ export default function (pi: ExtensionAPI) {
 			const path = shortenPath(args.path || "");
 			let pathDisplay = path ? theme.fg("accent", path) : theme.fg("toolOutput", "...");
 
-			// Show line range if specified
-			if (args.offset !== undefined || args.limit !== undefined) {
-				const startLine = args.offset ?? 1;
-				const endLine = args.limit !== undefined ? startLine + args.limit - 1 : "";
-				pathDisplay += theme.fg("warning", `:${startLine}${endLine ? `-${endLine}` : ""}`);
+			const lineRange = formatReadLineRange(args.offset, args.limit);
+			if (lineRange) {
+				pathDisplay += theme.fg("warning", lineRange);
 			}
 
 			return new Text(`${theme.fg("toolTitle", theme.bold("read"))} ${pathDisplay}`, 0, 0);

package/examples/extensions/sandbox/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-sandbox",
-	"version": "1.2.0",
+	"version": "1.4.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-sandbox",
-			"version": "1.2.0",
+			"version": "1.4.0",
 			"dependencies": {
 				"@anthropic-ai/sandbox-runtime": "^0.0.26"
 			}

package/examples/extensions/sandbox/package.json

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

package/examples/extensions/subagent/index.ts

@@ -22,6 +22,7 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import {
 	CONFIG_DIR_NAME,
 	type ExtensionAPI,
+	formatReadLineRange,
 	getAgentDir,
 	getMarkdownTheme,
 	withFileMutationQueue,
@@ -87,13 +88,10 @@ function formatToolCall(
 		case "read": {
 			const rawPath = (args.file_path || args.path || "...") as string;
 			const filePath = shortenPath(rawPath);
-			const offset = args.offset as number | undefined;
-			const limit = args.limit as number | undefined;
+			const lineRange = formatReadLineRange(args.offset, args.limit);
 			let text = themeFg("accent", filePath);
-			if (offset !== undefined || limit !== undefined) {
-				const startLine = offset ?? 1;
-				const endLine = limit !== undefined ? startLine + limit - 1 : "";
-				text += themeFg("warning", `:${startLine}${endLine ? `-${endLine}` : ""}`);
+			if (lineRange) {
+				text += themeFg("warning", lineRange);
 			}
 			return themeFg("muted", "read ") + text;
 		}

package/examples/extensions/with-deps/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-with-deps",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-with-deps",
-      "version": "1.2.0",
+      "version": "1.4.0",
       "dependencies": {
         "ms": "^2.1.3"
       },

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-with-deps",
   "private": true,
-  "version": "1.2.0",
+  "version": "1.4.0",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-namespace-patch",
-	"version": "1.2.0-namespace.2",
+	"version": "1.4.0-namespace.1",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management — maskshell fork build with the pi.namespace patch (earendil-works/pi#8834)",
 	"type": "module",
 	"piConfig": {
@@ -37,14 +37,15 @@
 		"copy-binary-assets": "shx cp package.json dist/ && shx cp README.md dist/ && shx cp CHANGELOG.md dist/ && shx mkdir -p dist/theme && shx cp src/modes/interactive/theme/*.json dist/theme/ && shx mkdir -p dist/assets && shx cp src/modes/interactive/assets/*.png dist/assets/ && shx mkdir -p dist/export-html/vendor && shx cp src/core/export-html/template.html dist/export-html/ && shx cp src/core/export-html/vendor/*.js dist/export-html/vendor/ && shx cp -r docs dist/ && shx cp -r examples dist/ && shx cp ../../node_modules/@silvia-odwyer/photon-node/photon_rs_bg.wasm dist/",
 		"test": "vitest --run",
 		"generate:schemas": "node --import ./src/experimental/source-resolver.ts scripts/generate-schemas.ts",
+		"generate:references": "node --import ./src/experimental/source-resolver.ts scripts/generate-references.ts",
 		"prepublishOnly": "npm run clean && npm run build"
 	},
 	"dependencies": {
-		"@earendil-works/pi-agent-core": "^1.2.0",
-		"@earendil-works/pi-ai": "^1.2.0",
-		"@earendil-works/pi-codemode": "^1.2.0",
-		"@earendil-works/pi-mcp": "^1.2.0",
-		"@earendil-works/pi-tui": "^1.2.0",
+		"@earendil-works/pi-agent-core": "1.4.0+namespace.1",
+		"@earendil-works/pi-ai": "1.4.0+namespace.1",
+		"@earendil-works/pi-codemode": "1.4.0+namespace.1",
+		"@earendil-works/pi-mcp": "1.4.0+namespace.1",
+		"@earendil-works/pi-tui": "1.4.0+namespace.1",
 		"@silvia-odwyer/photon-node": "0.3.4",
 		"brace-expansion": "5.0.12",
 		"chalk": "6.0.0",

package/schemas/models.schema.json

@@ -18,23 +18,28 @@
           "properties": {
             "name": {
               "type": "string",
-              "minLength": 1
+              "minLength": 1,
+              "description": "Display name."
             },
             "baseUrl": {
               "type": "string",
-              "minLength": 1
+              "minLength": 1,
+              "description": "API base URL. Also applies to the provider's built-in models."
             },
             "apiKey": {
               "type": "string",
-              "minLength": 1
+              "minLength": 1,
+              "description": "Literal key, \"$NAME\" environment interpolation, or \"!command\" output."
             },
             "api": {
               "type": "string",
-              "minLength": 1
+              "minLength": 1,
+              "description": "API for the provider's models, such as \"openai-completions\", \"openai-responses\", \"anthropic-messages\", or \"google-generative-ai\"."
             },
             "oauth": {
               "type": "string",
-              "const": "radius"
+              "const": "radius",
+              "description": "OAuth login flow. Requires baseUrl."
             },
             "headers": {
               "type": "object",
@@ -42,14 +47,17 @@
                 "^.*$": {
                   "type": "string"
                 }
-              }
+              },
+              "description": "Request headers. Values resolve like apiKey."
             },
             "compat": {
               "$ref": "#/$defs/ProviderCompat",
               "description": "Provider and model compatibility overrides."
             },
             "authHeader": {
-              "type": "boolean"
+              "type": "boolean",
+              "default": false,
+              "description": "Whether to send the resolved API key as Authorization: Bearer."
             },
             "models": {
               "type": "array",
@@ -61,25 +69,32 @@
                 "properties": {
                   "id": {
                     "type": "string",
-                    "minLength": 1
+                    "minLength": 1,
+                    "description": "Model ID sent to the API."
                   },
                   "name": {
                     "type": "string",
-                    "minLength": 1
+                    "minLength": 1,
+                    "description": "Display name, also matched by --model patterns."
                   },
                   "api": {
                     "type": "string",
-                    "minLength": 1
+                    "minLength": 1,
+                    "description": "Overrides the provider api."
                   },
                   "baseUrl": {
                     "type": "string",
-                    "minLength": 1
+                    "minLength": 1,
+                    "description": "Overrides the provider baseUrl."
                   },
                   "reasoning": {
-                    "type": "boolean"
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Whether the model supports thinking."
                   },
                   "thinkingLevelMap": {
-                    "$ref": "#/$defs/ThinkingLevelMap"
+                    "$ref": "#/$defs/ThinkingLevelMap",
+                    "description": "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": {
                     "type": "array",
@@ -88,7 +103,10 @@
                         "text",
                         "image"
                       ]
-                    }
+                    },
+                    "default": [
+                      "text"
+                    ]
                   },
                   "inputLimits": {
                     "$ref": "#/$defs/ModelInputLimits"
@@ -98,21 +116,26 @@
                   },
                   "promptCache": {
                     "$ref": "#/$defs/ModelPromptCache",
-                    "description": "Best-effort prompt cache lifetime in seconds for each retention tier. A missing tier means the lifetime is unknown, so Pi does not warm it."
+                    "description": "Best-effort prompt cache lifetime in seconds for the short and long retention tiers. Pi warms only tiers with a known lifetime."
                   },
                   "contextWindow": {
                     "type": "number",
-                    "exclusiveMinimum": 0
+                    "exclusiveMinimum": 0,
+                    "default": 128000,
+                    "description": "Context window in tokens."
                   },
                   "maxTokens": {
                     "type": "number",
-                    "exclusiveMinimum": 0
+                    "exclusiveMinimum": 0,
+                    "default": 16384,
+                    "description": "Maximum output tokens."
                   },
                   "samplingParams": {
                     "type": "object",
                     "patternProperties": {
                       "^.*$": {}
-                    }
+                    },
+                    "description": "Fields merged into every request body. Applies only to OpenAI-compatible APIs."
                   },
                   "samplingParamsByThinkingLevel": {
                     "type": "object",
@@ -159,7 +182,8 @@
                           "^.*$": {}
                         }
                       }
-                    }
+                    },
+                    "description": "samplingParams per thinking level, merged over samplingParams."
                   },
                   "headers": {
                     "type": "object",
@@ -167,7 +191,8 @@
                       "^.*$": {
                         "type": "string"
                       }
-                    }
+                    },
+                    "description": "Request headers. Values resolve like apiKey."
                   },
                   "compat": {
                     "$ref": "#/$defs/ProviderCompat",
@@ -184,13 +209,16 @@
                   "properties": {
                     "name": {
                       "type": "string",
-                      "minLength": 1
+                      "minLength": 1,
+                      "description": "Display name, also matched by --model patterns."
                     },
                     "reasoning": {
-                      "type": "boolean"
+                      "type": "boolean",
+                      "description": "Whether the model supports thinking."
                     },
                     "thinkingLevelMap": {
-                      "$ref": "#/$defs/ThinkingLevelMap"
+                      "$ref": "#/$defs/ThinkingLevelMap",
+                      "description": "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": {
                       "type": "array",
@@ -263,21 +291,24 @@
                     },
                     "promptCache": {
                       "$ref": "#/$defs/ModelPromptCache",
-                      "description": "Best-effort prompt cache lifetime in seconds for each retention tier. A missing tier means the lifetime is unknown, so Pi does not warm it."
+                      "description": "Best-effort prompt cache lifetime in seconds for the short and long retention tiers. Pi warms only tiers with a known lifetime."
                     },
                     "contextWindow": {
                       "type": "number",
-                      "exclusiveMinimum": 0
+                      "exclusiveMinimum": 0,
+                      "description": "Context window in tokens."
                     },
                     "maxTokens": {
                       "type": "number",
-                      "exclusiveMinimum": 0
+                      "exclusiveMinimum": 0,
+                      "description": "Maximum output tokens."
                     },
                     "samplingParams": {
                       "type": "object",
                       "patternProperties": {
                         "^.*$": {}
-                      }
+                      },
+                      "description": "Fields merged into every request body. Applies only to OpenAI-compatible APIs."
                     },
                     "samplingParamsByThinkingLevel": {
                       "type": "object",
@@ -324,7 +355,8 @@
                             "^.*$": {}
                           }
                         }
-                      }
+                      },
+                      "description": "samplingParams per thinking level, merged over samplingParams."
                     },
                     "headers": {
                       "type": "object",
@@ -332,7 +364,8 @@
                         "^.*$": {
                           "type": "string"
                         }
-                      }
+                      },
+                      "description": "Request headers. Values resolve like apiKey."
                     },
                     "compat": {
                       "$ref": "#/$defs/ProviderCompat",
@@ -1003,6 +1036,11 @@
           "description": "Whether the model accepts prompt_cache_options. Older OpenAI models reject the parameter.",
           "default": false
         },
+        "supportsMidConvoEffort": {
+          "type": "boolean",
+          "description": "Whether thinking level changes are sent inside the conversation instead of changing the request's effort, so a change keeps the prompt cache. Used by the anthropic-messages and openai-responses APIs.",
+          "default": false
+        },
         "supportsMaxOutputTokens": {
           "type": "boolean",
           "description": "Whether the provider accepts max_output_tokens. Some Codex-protocol gateways reject it.",
@@ -1038,11 +1076,6 @@
           "description": "Whether the provider supports Anthropic strict tool schemas. Generated Anthropic models enable it explicitly.",
           "default": false
         },
-        "supportsMidConvoEffort": {
-          "type": "boolean",
-          "description": "Whether the exact model transport supports effort-only system messages and thinking binding controls.",
-          "default": false
-        },
         "supportsMidConvoToolChanges": {
           "type": "boolean",
           "description": "Whether the exact model accepts mid-conversation tool_addition and tool_removal blocks. Requires supportsMidConvoSystemMessages.",
@@ -1074,6 +1107,27 @@
           },
           "maxItems": 3,
           "description": "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."
+        },
+        "imageInput": {
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "assets"
+            },
+            {
+              "type": "string",
+              "const": "images"
+            },
+            {
+              "type": "string",
+              "const": "state-image-urls"
+            }
+          ],
+          "description": "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": {
+          "type": "boolean",
+          "description": "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."
         }
       },
       "additionalProperties": true

package/schemas/settings.schema.json

@@ -50,6 +50,24 @@
       ],
       "default": "auto"
     },
+    "sessionShareDestination": {
+      "anyOf": [
+        {
+          "type": "string",
+          "const": "auto"
+        },
+        {
+          "type": "string",
+          "const": "gist"
+        },
+        {
+          "type": "string",
+          "const": "radius"
+        }
+      ],
+      "description": "Destination used by /share. \"auto\" uses Radius when authenticated and otherwise creates a GitHub gist.",
+      "default": "auto"
+    },
     "steeringMode": {
       "anyOf": [
         {