@caupulican/pi-adaptative 0.81.39 → 0.81.40

package/docs/work-directory.md

@@ -22,7 +22,7 @@ The default per-tenant retention policy is 30 days, 64 inactive runs, 512 MiB, 1
 
 ## Repository API
 
-Extensions and internal code can use the public helpers:
+Harness internals and programmatic SDK integrations can use the low-level public helpers:
 
 ```ts
 import { acquireWorkRun, getProcessWorkRun, pruneWorkTenant } from "@caupulican/pi-adaptative";
@@ -34,9 +34,11 @@ import { acquireWorkRun, getProcessWorkRun, pruneWorkTenant } from "@caupulican/
 
 Use a named run only for transient coordination that must be shared across Pi processes. Use a generated run for commands, reports, downloads, tests, benchmarks, probes, and output spills.
 
+Packaged extensions should use `pi.getStorage("extension-name").acquireWorkRun()` instead. It binds work to one extension namespace, releases leases automatically on failure/unload, and clamps extension-selected retention to the harness ceiling. Calling `getStorage()` alone creates no directories. Durable extension state and rebuildable extension cache similarly live under `state/extensions/<namespace>/` and `cache/extensions/<namespace>/`; see [extensions.md](extensions.md#pigetstoragenamespace).
+
 ## Not transient
 
-Configuration and durable user data stay outside `work/`: `settings.json`, `auth.json`, `models.json`, `sessions/`, `state/`, `skills/`, `extensions/`, `prompts/`, `themes/`, profiles, backups, and managed binaries.
+Configuration and durable user data stay outside `work/`: `settings.json`, `auth.json`, `models.json`, `sessions/`, `state/`, `skills/`, `extensions/`, `prompts/`, `themes/`, profiles, backups, and managed binaries. Directory overlays are contained under `profiles/directories/`; explicit configuration snapshots are contained under `state/backups/config/`.
 
 Do not put Automata memory or its graph in Pi's work directory. Automata remains an external memory system.
 
@@ -51,20 +53,29 @@ straggler:
 ```text
 ~/.pi/agent/
   auth.json settings.json models.json keybindings.json MEMORY.md USER.md SYSTEM.md …   user config/memory (root)
+  okf-memory/                                                                          authored memory (root)
   skills/ extensions/ prompts/ themes/ profiles/                                       user resources (root)
+    profiles/directories/<workspace-hash>/settings.json                                directory overlays
   state/     durable machine state: model adaptation/fitness, tool-performance,        -- stateDir/stateFile
-             learning observations, trust decisions (trust.json), failure corpus, …
+             learning observations, trust decisions, failure corpus, config backups, …
+    state/backups/config/                                                              explicit config snapshots
+    state/extensions/<namespace>/                                                      extension durable state
   cache/     rebuildable, safe to delete: tool-path probes, jiti transform cache, uv    -- cacheDir/cacheFile
+    cache/extensions/<namespace>/                                                      extension rebuildable cache
   bin/       managed executable helpers (fd, rg)                                       -- binDir (legacy getBinDir accessor)
   work/      transient/scratch (this document)                                         -- re-exported from agent-paths.ts
+    work/extensions/<namespace>/<run-id>/                                              extension leased work
   runtimes/<kind>  models/<kind>  sessions/  npm/  git/  worktrees/                    -- runtimesDir/modelsDir/sessionsDir/npmDir/gitDir/worktreesDir
 ```
 
 `state/` holds durable history — deleting it loses real data, not just cache. `cache/` is always safe
 to delete; the next run re-probes or recomputes it. A startup migration (`migrateAgentDirLayout`,
 `src/migrations.ts`, run before any store/trust read) relocates confirmed root-level stragglers into
-their canonical location — currently just `trust.json` into `state/` — idempotently and without ever
-overwriting an already-migrated target. `resource-profiles/` intentionally stays at the agent-directory
-root rather than moving under `state/`: it's surfaced in two user-visible profile-menu description
-strings, and moving it needs those updated in the same change (tracked open in the bug ledger, not a
-silent gap).
+their canonical locations: `trust.json` into `state/`, `backups/` into `state/backups/config/`, and
+`resource-profiles/` into `profiles/directories/`. Obsolete root `auto-learn/` and `tmp/` trees are
+preserved under `state/legacy-layout/`, where they cannot compete with live config/resources. Whole
+roots move atomically when possible; literal Windows `auth.json:Zone.Identifier` sidecars move there
+too. Partial migrations scan a bounded number of top-level entries and preserve collisions under
+`state/migration-conflicts/` instead of overwriting either copy.
+
+`pi doctor` performs a bounded, read-only scan of the agent directory root. It stays silent for the canonical config, memory, resource, and storage entries above and warns about external or legacy root writers. The audit never relocates or deletes unknown data.

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

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

package/examples/extensions/question.ts

@@ -1,264 +1,53 @@
 /**
- * Question Tool - Single question with options
- * Full custom UI: options list + inline editor for "Type something..."
- * Escape in editor returns to options, Escape in options cancels
+ * Single-question compatibility example.
+ *
+ * The interaction itself is native and shared with ask_question; this extension only adapts the
+ * older one-question parameter shape so example code cannot drift into a second UI implementation.
  */
 
-import type { ExtensionAPI } from "@caupulican/pi-adaptative";
-import { Editor, type EditorTheme, Key, matchesKey, Text, truncateToWidth } from "@caupulican/pi-tui";
+import { createAskQuestionToolDefinition, type ExtensionAPI } from "@caupulican/pi-adaptative";
 import { Type } from "typebox";
 
-interface OptionWithDesc {
-	label: string;
-	description?: string;
-}
-
-type DisplayOption = OptionWithDesc & { isOther?: boolean };
-
-interface QuestionDetails {
-	question: string;
-	options: string[];
-	answer: string | null;
-	wasCustom?: boolean;
-}
-
-// Options with labels and optional descriptions
-const OptionSchema = Type.Object({
+const optionSchema = Type.Object({
 	label: Type.String({ description: "Display label for the option" }),
-	description: Type.Optional(Type.String({ description: "Optional description shown below label" })),
+	description: Type.Optional(Type.String({ description: "Description shown below the label" })),
 });
 
-const QuestionParams = Type.Object({
+const paramsSchema = Type.Object({
 	question: Type.String({ description: "The question to ask the user" }),
-	options: Type.Array(OptionSchema, { description: "Options for the user to choose from" }),
+	options: Type.Array(optionSchema, { description: "Options for the user to choose from" }),
 });
 
 export default function question(pi: ExtensionAPI) {
+	const native = createAskQuestionToolDefinition({ name: "question", label: "Question" });
 	pi.registerTool({
-		name: "question",
-		label: "Question",
-		description: "Ask the user a question and let them pick from options. Use when you need user input to proceed.",
-		parameters: QuestionParams,
-
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			if (!ctx.hasUI) {
-				return {
-					content: [{ type: "text", text: "Error: UI not available (running in non-interactive mode)" }],
-					details: {
-						question: params.question,
-						options: params.options.map((o) => o.label),
-						answer: null,
-					} as QuestionDetails,
-				};
-			}
-
-			if (params.options.length === 0) {
-				return {
-					content: [{ type: "text", text: "Error: No options provided" }],
-					details: { question: params.question, options: [], answer: null } as QuestionDetails,
-				};
-			}
-
-			const allOptions: DisplayOption[] = [...params.options, { label: "Type something.", isOther: true }];
-
-			const result = await ctx.ui.custom<{ answer: string; wasCustom: boolean; index?: number } | null>(
-				(tui, theme, _kb, done) => {
-					let optionIndex = 0;
-					let editMode = false;
-					let cachedLines: string[] | undefined;
-
-					const editorTheme: EditorTheme = {
-						borderColor: (s) => theme.fg("accent", s),
-						selectList: {
-							selectedPrefix: (t) => theme.fg("accent", t),
-							selectedText: (t) => theme.fg("accent", t),
-							description: (t) => theme.fg("muted", t),
-							scrollInfo: (t) => theme.fg("dim", t),
-							noMatch: (t) => theme.fg("warning", t),
-						},
-					};
-					const editor = new Editor(tui, editorTheme);
-
-					editor.onSubmit = (value) => {
-						const trimmed = value.trim();
-						if (trimmed) {
-							done({ answer: trimmed, wasCustom: true });
-						} else {
-							editMode = false;
-							editor.setText("");
-							refresh();
-						}
-					};
-
-					function refresh() {
-						cachedLines = undefined;
-						tui.requestRender();
-					}
-
-					function handleInput(data: string) {
-						if (editMode) {
-							if (matchesKey(data, Key.escape)) {
-								editMode = false;
-								editor.setText("");
-								refresh();
-								return;
-							}
-							editor.handleInput(data);
-							refresh();
-							return;
-						}
-
-						if (matchesKey(data, Key.up)) {
-							optionIndex = Math.max(0, optionIndex - 1);
-							refresh();
-							return;
-						}
-						if (matchesKey(data, Key.down)) {
-							optionIndex = Math.min(allOptions.length - 1, optionIndex + 1);
-							refresh();
-							return;
-						}
-
-						if (matchesKey(data, Key.enter)) {
-							const selected = allOptions[optionIndex];
-							if (selected.isOther) {
-								editMode = true;
-								refresh();
-							} else {
-								done({ answer: selected.label, wasCustom: false, index: optionIndex + 1 });
-							}
-							return;
-						}
-
-						if (matchesKey(data, Key.escape)) {
-							done(null);
-						}
-					}
-
-					function render(width: number): string[] {
-						if (cachedLines) return cachedLines;
-
-						const lines: string[] = [];
-						const add = (s: string) => lines.push(truncateToWidth(s, width));
-
-						add(theme.fg("accent", "─".repeat(width)));
-						add(theme.fg("text", ` ${params.question}`));
-						lines.push("");
-
-						for (let i = 0; i < allOptions.length; i++) {
-							const opt = allOptions[i];
-							const selected = i === optionIndex;
-							const isOther = opt.isOther === true;
-							const prefix = selected ? theme.fg("accent", "> ") : "  ";
-
-							if (isOther && editMode) {
-								add(prefix + theme.fg("accent", `${i + 1}. ${opt.label} ✎`));
-							} else if (selected) {
-								add(prefix + theme.fg("accent", `${i + 1}. ${opt.label}`));
-							} else {
-								add(`  ${theme.fg("text", `${i + 1}. ${opt.label}`)}`);
-							}
-
-							// Show description if present
-							if (opt.description) {
-								add(`     ${theme.fg("muted", opt.description)}`);
-							}
-						}
-
-						if (editMode) {
-							lines.push("");
-							add(theme.fg("muted", " Your answer:"));
-							for (const line of editor.render(width - 2)) {
-								add(` ${line}`);
-							}
-						}
-
-						lines.push("");
-						if (editMode) {
-							add(theme.fg("dim", " Enter to submit • Esc to go back"));
-						} else {
-							add(theme.fg("dim", " ↑↓ navigate • Enter to select • Esc to cancel"));
-						}
-						add(theme.fg("accent", "─".repeat(width)));
-
-						cachedLines = lines;
-						return lines;
-					}
-
-					return {
-						render,
-						invalidate: () => {
-							cachedLines = undefined;
+		name: native.name,
+		label: native.label,
+		description: native.description,
+		promptSnippet: native.promptSnippet,
+		promptGuidelines: native.promptGuidelines,
+		executionMode: native.executionMode,
+		parameters: paramsSchema,
+		async execute(toolCallId, params, signal, _onUpdate, ctx) {
+			return native.execute(
+				toolCallId,
+				{
+					questions: [
+						{
+							id: "question",
+							header: "Question",
+							question: params.question,
+							options: params.options.map((option) => ({
+								label: option.label,
+								description: option.description ?? `Choose ${option.label}.`,
+							})),
 						},
-						handleInput,
-					};
+					],
 				},
+				signal,
+				undefined,
+				ctx,
 			);
-
-			// Build simple options list for details
-			const simpleOptions = params.options.map((o) => o.label);
-
-			if (!result) {
-				return {
-					content: [{ type: "text", text: "User cancelled the selection" }],
-					details: { question: params.question, options: simpleOptions, answer: null } as QuestionDetails,
-				};
-			}
-
-			if (result.wasCustom) {
-				return {
-					content: [{ type: "text", text: `User wrote: ${result.answer}` }],
-					details: {
-						question: params.question,
-						options: simpleOptions,
-						answer: result.answer,
-						wasCustom: true,
-					} as QuestionDetails,
-				};
-			}
-			return {
-				content: [{ type: "text", text: `User selected: ${result.index}. ${result.answer}` }],
-				details: {
-					question: params.question,
-					options: simpleOptions,
-					answer: result.answer,
-					wasCustom: false,
-				} as QuestionDetails,
-			};
-		},
-
-		renderCall(args, theme, _context) {
-			let text = theme.fg("toolTitle", theme.bold("question ")) + theme.fg("muted", args.question);
-			const opts = Array.isArray(args.options) ? args.options : [];
-			if (opts.length) {
-				const labels = opts.map((o: OptionWithDesc) => o.label);
-				const numbered = [...labels, "Type something."].map((o, i) => `${i + 1}. ${o}`);
-				text += `\n${theme.fg("dim", `  Options: ${numbered.join(", ")}`)}`;
-			}
-			return new Text(text, 0, 0);
-		},
-
-		renderResult(result, _options, theme, _context) {
-			const details = result.details as QuestionDetails | undefined;
-			if (!details) {
-				const text = result.content[0];
-				return new Text(text?.type === "text" ? text.text : "", 0, 0);
-			}
-
-			if (details.answer === null) {
-				return new Text(theme.fg("warning", "Cancelled"), 0, 0);
-			}
-
-			if (details.wasCustom) {
-				return new Text(
-					theme.fg("success", "✓ ") + theme.fg("muted", "(wrote) ") + theme.fg("accent", details.answer),
-					0,
-					0,
-				);
-			}
-			const idx = details.options.indexOf(details.answer) + 1;
-			const display = idx > 0 ? `${idx}. ${details.answer}` : details.answer;
-			return new Text(theme.fg("success", "✓ ") + theme.fg("accent", display), 0, 0);
 		},
 	});
 }