@caupulican/pi-adaptative 0.81.43 → 0.85.0

package/docs/worker-profiles.md

@@ -0,0 +1,16 @@
+# Task worker profiles
+
+`profile_writer` lets the foreground orchestrator create the smallest worker profile needed for one bounded task. It does not edit user or project profile files.
+
+Task profiles are:
+
+- Derived only from an owner-authorized base profile.
+- Immutable and assigned a `task-...` ID by Pi.
+- Stored on the owning session branch, never shared across independent sessions.
+- Limited to 32 profiles per session.
+- Unable to add tools, resources, or budget beyond the base profile.
+- Limited to configured, authenticated, non-exhausted models and a thinking level that model supports.
+
+Use `profile_writer { action: "inspect" }` when the authorized bases or model combinations are unknown. Then call `create` with a concise task and only the fields that need narrowing. Pass the returned profile ID unchanged to `delegate`; never invent one.
+
+Workers cannot invoke `profile_writer`, recursively delegate, or expand their admitted contract. A resumed worker retains the exact profile, model, resources, and transcript admitted for that task.

package/examples/extensions/built-in-tool-renderer.ts

@@ -26,7 +26,13 @@
  */
 
 import type { BashToolDetails, EditToolDetails, ExtensionAPI, ReadToolDetails } from "@caupulican/pi-adaptative";
-import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@caupulican/pi-adaptative";
+import {
+	createBashTool,
+	createEditTool,
+	createReadTool,
+	createWriteTool,
+	FileMutationIntentController,
+} from "@caupulican/pi-adaptative";
 import { Text } from "@caupulican/pi-tui";
 
 export default function (pi: ExtensionAPI) {
@@ -151,7 +157,8 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	// --- Edit tool: show path and diff stats ---
-	const originalEdit = createEditTool(cwd);
+	const fileMutationIntents = new FileMutationIntentController();
+	const originalEdit = createEditTool(cwd, { intentController: fileMutationIntents });
 	pi.registerTool({
 		name: "edit",
 		label: "edit",
@@ -216,7 +223,7 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	// --- Write tool: show path and size ---
-	const originalWrite = createWriteTool(cwd);
+	const originalWrite = createWriteTool(cwd, { intentController: fileMutationIntents });
 	pi.registerTool({
 		name: "write",
 		label: "write",
@@ -230,8 +237,8 @@ export default function (pi: ExtensionAPI) {
 		renderCall(args, theme, _context) {
 			let text = theme.fg("toolTitle", theme.bold("write "));
 			text += theme.fg("accent", args.path);
-			const lineCount = args.content.split("\n").length;
-			text += theme.fg("dim", ` (${lineCount} lines)`);
+			const writeContent = args.action === "commit" && "content" in args ? args.content : undefined;
+			if (writeContent) text += theme.fg("dim", ` (${writeContent.length} characters)`);
 			return new Text(text, 0, 0);
 		},
 

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

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

package/examples/extensions/minimal-mode.ts

@@ -25,6 +25,7 @@ import {
 	createLsTool,
 	createReadTool,
 	createWriteTool,
+	FileMutationIntentController,
 } from "@caupulican/pi-adaptative";
 import { Text } from "@caupulican/pi-tui";
 import { homedir } from "os";
@@ -44,11 +45,12 @@ function shortenPath(path: string): string {
 const toolCache = new Map<string, ReturnType<typeof createBuiltInTools>>();
 
 function createBuiltInTools(cwd: string) {
+	const fileMutationIntents = new FileMutationIntentController();
 	return {
 		read: createReadTool(cwd),
 		bash: createBashTool(cwd),
-		edit: createEditTool(cwd),
-		write: createWriteTool(cwd),
+		edit: createEditTool(cwd, { intentController: fileMutationIntents }),
+		write: createWriteTool(cwd, { intentController: fileMutationIntents }),
 		find: createFindTool(cwd),
 		grep: createGrepTool(cwd),
 		ls: createLsTool(cwd),
@@ -167,8 +169,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "write",
 		label: "write",
-		description:
-			"Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.",
+		description: "Create a new file through path-only preflight. Existing paths are never overwritten.",
 		parameters: getBuiltInTools(process.cwd()).write.parameters,
 
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
@@ -179,10 +180,10 @@ export default function (pi: ExtensionAPI) {
 		renderCall(args, theme, _context) {
 			const path = shortenPath(args.path || "");
 			const pathDisplay = path ? theme.fg("accent", path) : theme.fg("toolOutput", "...");
-			const lineCount = args.content ? args.content.split("\n").length : 0;
-			const lineInfo = lineCount > 0 ? theme.fg("muted", ` (${lineCount} lines)`) : "";
+			const writeContent = args.action === "commit" && "content" in args ? args.content : undefined;
+			const sizeInfo = writeContent ? theme.fg("muted", ` (${writeContent.length} characters)`) : "";
 
-			return new Text(`${theme.fg("toolTitle", theme.bold("write"))} ${pathDisplay}${lineInfo}`, 0, 0);
+			return new Text(`${theme.fg("toolTitle", theme.bold("write"))} ${pathDisplay}${sizeInfo}`, 0, 0);
 		},
 
 		renderResult(result, { expanded }, theme, _context) {

package/examples/extensions/prompt-customizer.ts

@@ -37,12 +37,14 @@ function addToolGuidance(options: BuildSystemPromptOptions, basePrompt: string):
 
 	if (hasTool("edit")) {
 		parts.push(
-			"• Use the `edit` tool for precise text replacements in files. Match exact content including whitespace.",
+			"• Use `edit` action=prepare before generating precise replacements, then commit with the returned intent. Match exact content including whitespace.",
 		);
 	}
 
 	if (hasTool("write")) {
-		parts.push("• Use the `write` tool to create new files or overwrite existing ones completely.");
+		parts.push(
+			"• Use `write` action=prepare before generating content; commit creates a new file and never overwrites.",
+		);
 	}
 
 	if (options.skills && options.skills.length > 0) {

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

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-sandbox",
-	"version": "0.81.43",
+	"version": "0.85.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-sandbox",
-			"version": "0.81.43",
+			"version": "0.85.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": "0.81.43",
+	"version": "0.85.0",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/ssh.ts

@@ -10,10 +10,11 @@
  *
  * Requirements:
  *   - SSH key-based auth (no password prompts)
- *   - bash on remote
+ *   - bash and GNU coreutils (sha256sum, stat) on remote
  */
 
 import { spawn } from "node:child_process";
+import { constants } from "node:fs";
 import type { ExtensionAPI } from "@caupulican/pi-adaptative";
 import {
 	type BashOperations,
@@ -22,13 +23,20 @@ import {
 	createReadTool,
 	createWriteTool,
 	type EditOperations,
+	FileMutationIntentController,
+	type FileMutationIntentOperations,
+	type FilePathInspection,
 	type ReadOperations,
 	type WriteOperations,
 } from "@caupulican/pi-adaptative";
 
-function sshExec(remote: string, command: string): Promise<Buffer> {
+function shellQuote(value: string): string {
+	return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+function sshExec(remote: string, command: string, stdin?: string | Buffer): Promise<Buffer> {
 	return new Promise((resolve, reject) => {
-		const child = spawn("ssh", [remote, command], { stdio: ["ignore", "pipe", "pipe"] });
+		const child = spawn("ssh", [remote, command], { stdio: ["pipe", "pipe", "pipe"] });
 		const chunks: Buffer[] = [];
 		const errChunks: Buffer[] = [];
 		child.stdout.on("data", (data) => chunks.push(data));
@@ -41,17 +49,18 @@ function sshExec(remote: string, command: string): Promise<Buffer> {
 				resolve(Buffer.concat(chunks));
 			}
 		});
+		child.stdin.end(stdin);
 	});
 }
 
 function createRemoteReadOps(remote: string, remoteCwd: string, localCwd: string): ReadOperations {
 	const toRemote = (p: string) => p.replace(localCwd, remoteCwd);
 	return {
-		readFile: (p) => sshExec(remote, `cat ${JSON.stringify(toRemote(p))}`),
-		access: (p) => sshExec(remote, `test -r ${JSON.stringify(toRemote(p))}`).then(() => {}),
+		readFile: (p) => sshExec(remote, `cat -- ${shellQuote(toRemote(p))}`),
+		access: (p) => sshExec(remote, `test -r ${shellQuote(toRemote(p))}`).then(() => {}),
 		detectImageMimeType: async (p) => {
 			try {
-				const r = await sshExec(remote, `file --mime-type -b ${JSON.stringify(toRemote(p))}`);
+				const r = await sshExec(remote, `file --mime-type -b -- ${shellQuote(toRemote(p))}`);
 				const m = r.toString().trim();
 				return ["image/jpeg", "image/png", "image/gif", "image/webp"].includes(m) ? m : null;
 			} catch {
@@ -61,21 +70,86 @@ function createRemoteReadOps(remote: string, remoteCwd: string, localCwd: string
 	};
 }
 
+async function writeRemoteContent(remote: string, path: string, content: string, exclusive: boolean): Promise<void> {
+	const noClobber = exclusive ? "set -o noclobber; " : "";
+	await sshExec(remote, `${noClobber}cat > ${shellQuote(path)}`, content);
+}
+
 function createRemoteWriteOps(remote: string, remoteCwd: string, localCwd: string): WriteOperations {
 	const toRemote = (p: string) => p.replace(localCwd, remoteCwd);
 	return {
-		writeFile: async (p, content) => {
-			const b64 = Buffer.from(content).toString("base64");
-			await sshExec(remote, `echo ${JSON.stringify(b64)} | base64 -d > ${JSON.stringify(toRemote(p))}`);
-		},
-		mkdir: (dir) => sshExec(remote, `mkdir -p ${JSON.stringify(toRemote(dir))}`).then(() => {}),
+		createFile: (p, content) => writeRemoteContent(remote, toRemote(p), content, true),
+		mkdir: (dir) => sshExec(remote, `mkdir -p -- ${shellQuote(toRemote(dir))}`).then(() => {}),
 	};
 }
 
 function createRemoteEditOps(remote: string, remoteCwd: string, localCwd: string): EditOperations {
 	const r = createRemoteReadOps(remote, remoteCwd, localCwd);
-	const w = createRemoteWriteOps(remote, remoteCwd, localCwd);
-	return { readFile: r.readFile, access: r.access, writeFile: w.writeFile };
+	const toRemote = (p: string) => p.replace(localCwd, remoteCwd);
+	return {
+		readFile: r.readFile,
+		writeFile: (p, content) => writeRemoteContent(remote, toRemote(p), content, false),
+	};
+}
+
+function createRemoteIntentOps(remote: string, remoteCwd: string, localCwd: string): FileMutationIntentOperations {
+	const toRemote = (p: string) => p.replace(localCwd, remoteCwd);
+	return {
+		async inspect(p, followSymlinks): Promise<FilePathInspection | undefined> {
+			const path = shellQuote(toRemote(p));
+			const kind = followSymlinks
+				? `if [ -f ${path} ]; then printf 'file\\t'; elif [ -d ${path} ]; then printf 'directory\\t'; elif [ -e ${path} ]; then printf 'other\\t'; else exit 44; fi`
+				: `if [ -L ${path} ]; then printf 'other\\t'; elif [ -f ${path} ]; then printf 'file\\t'; elif [ -d ${path} ]; then printf 'directory\\t'; elif [ -e ${path} ]; then printf 'other\\t'; else exit 44; fi`;
+			const follow = followSymlinks ? "-L " : "";
+			try {
+				const output = (
+					await sshExec(
+						remote,
+						`${kind}; stat ${follow}--printf ${shellQuote("%d\\t%i\\t%f\\t%s\\t%y\\t%z")} -- ${path}`,
+					)
+				)
+					.toString("utf8")
+					.trimEnd();
+				const [entryKind, dev, ino, mode, size, mtimeMs, ctimeMs] = output.split("\t");
+				if (
+					(entryKind !== "file" && entryKind !== "directory" && entryKind !== "other") ||
+					!dev ||
+					!ino ||
+					!mode ||
+					!size ||
+					!mtimeMs ||
+					!ctimeMs
+				) {
+					throw new Error(`Unexpected remote stat response for ${p}`);
+				}
+				return { kind: entryKind, identity: { dev, ino, mode, size, mtimeMs, ctimeMs } };
+			} catch (error) {
+				if (String(error).includes("SSH failed (44)")) return undefined;
+				throw error;
+			}
+		},
+		access(p, mode) {
+			const path = shellQuote(toRemote(p));
+			const checks = [
+				mode & constants.R_OK ? `test -r ${path}` : undefined,
+				mode & constants.W_OK ? `test -w ${path}` : undefined,
+			].filter((check): check is string => check !== undefined);
+			return sshExec(remote, checks.length > 0 ? checks.join(" && ") : `test -e ${path}`).then(() => {});
+		},
+		copyFileExclusive(sourcePath, targetPath) {
+			return sshExec(
+				remote,
+				`set -o noclobber; cat -- ${shellQuote(toRemote(sourcePath))} > ${shellQuote(toRemote(targetPath))}`,
+			).then(() => {});
+		},
+		async hashFile(p) {
+			const output = await sshExec(remote, `sha256sum -- ${shellQuote(toRemote(p))}`);
+			const digest = output.toString("utf8").trim().split(/\s+/, 1)[0];
+			if (!digest || !/^[0-9a-f]{64}$/i.test(digest)) throw new Error(`Invalid remote sha256 for ${p}`);
+			return digest.toLowerCase();
+		},
+		removeFile: (p) => sshExec(remote, `rm -- ${shellQuote(toRemote(p))}`).then(() => {}),
+	};
 }
 
 function createRemoteBashOps(remote: string, remoteCwd: string, localCwd: string): BashOperations {
@@ -83,7 +157,7 @@ function createRemoteBashOps(remote: string, remoteCwd: string, localCwd: string
 	return {
 		exec: (command, cwd, { onData, signal, timeout }) =>
 			new Promise((resolve, reject) => {
-				const cmd = `cd ${JSON.stringify(toRemote(cwd))} && ${command}`;
+				const cmd = `cd ${shellQuote(toRemote(cwd))} && ${command}`;
 				const child = spawn("ssh", [remote, cmd], { stdio: ["ignore", "pipe", "pipe"] });
 				let timedOut = false;
 				const timer = timeout
@@ -115,15 +189,35 @@ export default function (pi: ExtensionAPI) {
 	pi.registerFlag("ssh", { description: "SSH remote: user@host or user@host:/path", type: "string" });
 
 	const localCwd = process.cwd();
+	const localFileMutationIntents = new FileMutationIntentController();
 	const localRead = createReadTool(localCwd);
-	const localWrite = createWriteTool(localCwd);
-	const localEdit = createEditTool(localCwd);
+	const localWrite = createWriteTool(localCwd, { intentController: localFileMutationIntents });
+	const localEdit = createEditTool(localCwd, { intentController: localFileMutationIntents });
 	const localBash = createBashTool(localCwd);
 
 	// Resolved lazily on session_start (CLI flags not available during factory)
 	let resolvedSsh: { remote: string; remoteCwd: string } | null = null;
+	let remoteFileTools: { write: ReturnType<typeof createWriteTool>; edit: ReturnType<typeof createEditTool> } | null =
+		null;
 
 	const getSsh = () => resolvedSsh;
+	const getRemoteFileTools = (ssh: { remote: string; remoteCwd: string }) => {
+		if (remoteFileTools) return remoteFileTools;
+		const intentController = new FileMutationIntentController({
+			operations: createRemoteIntentOps(ssh.remote, ssh.remoteCwd, localCwd),
+		});
+		remoteFileTools = {
+			write: createWriteTool(localCwd, {
+				operations: createRemoteWriteOps(ssh.remote, ssh.remoteCwd, localCwd),
+				intentController,
+			}),
+			edit: createEditTool(localCwd, {
+				operations: createRemoteEditOps(ssh.remote, ssh.remoteCwd, localCwd),
+				intentController,
+			}),
+		};
+		return remoteFileTools;
+	};
 
 	pi.registerTool({
 		...localRead,
@@ -144,10 +238,7 @@ export default function (pi: ExtensionAPI) {
 		async execute(id, params, signal, onUpdate, _ctx) {
 			const ssh = getSsh();
 			if (ssh) {
-				const tool = createWriteTool(localCwd, {
-					operations: createRemoteWriteOps(ssh.remote, ssh.remoteCwd, localCwd),
-				});
-				return tool.execute(id, params, signal, onUpdate);
+				return getRemoteFileTools(ssh).write.execute(id, params, signal, onUpdate);
 			}
 			return localWrite.execute(id, params, signal, onUpdate);
 		},
@@ -158,10 +249,7 @@ export default function (pi: ExtensionAPI) {
 		async execute(id, params, signal, onUpdate, _ctx) {
 			const ssh = getSsh();
 			if (ssh) {
-				const tool = createEditTool(localCwd, {
-					operations: createRemoteEditOps(ssh.remote, ssh.remoteCwd, localCwd),
-				});
-				return tool.execute(id, params, signal, onUpdate);
+				return getRemoteFileTools(ssh).edit.execute(id, params, signal, onUpdate);
 			}
 			return localEdit.execute(id, params, signal, onUpdate);
 		},
@@ -185,6 +273,7 @@ export default function (pi: ExtensionAPI) {
 		// Resolve SSH config now that CLI flags are available
 		const arg = pi.getFlag("ssh") as string | undefined;
 		if (arg) {
+			remoteFileTools = null;
 			if (arg.includes(":")) {
 				const [remote, path] = arg.split(":");
 				resolvedSsh = { remote, remoteCwd: path };

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

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-with-deps",
-  "version": "0.81.43",
+  "version": "0.85.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-with-deps",
-      "version": "0.81.43",
+      "version": "0.85.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": "0.81.43",
+  "version": "0.85.0",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",