pi-shorthand 0.12.0 → 0.13.0

package/README.md

@@ -40,6 +40,8 @@ Programs edit a private workspace, with host files outside the repository kept r
 
 The `code` tool uses Pi's working directory by default. Pass `cwd` to target another checkout; relative paths are resolved from Pi's working directory. For example, when Pi starts in a bare worktree container, `cwd: "child"` targets its `child` worktree. The chosen directory must be inside a Git worktree.
 
+Scripts run by Pi's `codemode` tool can call `code` too. They get back what the run changed as data, not text.
+
 ## Without Pi
 
 The engine is published separately as [shorthand-code](https://github.com/sebinsua/shortsight/tree/main/packages/shorthand-code), with a `shorthand` command that runs a program from a file or stdin and prints the same result. See `shorthand --help`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-shorthand",
-	"version": "0.12.0",
+	"version": "0.13.0",
 	"description": "Pi tool for editing repositories with Bun programs, with first-class support for TypeScript and JavaScript.",
 	"keywords": [
 		"ast-grep",
@@ -26,7 +26,7 @@
 	],
 	"type": "module",
 	"dependencies": {
-		"shorthand-code": "0.12.0"
+		"shorthand-code": "0.13.0"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "*",

package/src/index.ts

@@ -22,7 +22,7 @@ import {
 } from "shorthand-code";
 import { callLine, resultLines, unstructuredResultText } from "./display.ts";
 
-const DESCRIPTION = `Edit repository files with a TypeScript program run by Bun. Best for changes across many files, repeated edits and semantic TypeScript renames or moves; a small change to one file is quicker as a direct edit. Top-level await and ordinary Bun/Node APIs work. Use repository-relative paths. Set cwd to a checkout path when Pi's working directory is outside the repository, such as a child worktree in a bare worktree container. The program runs in an isolated workspace; changes apply on successful exit by default and the tool reports the diff. Run tests, type-checks and builds separately afterward with the shell tool.
+const DESCRIPTION = `Edit repository files with a TypeScript program run by Bun. Best for changes across many files, repeated edits and semantic TypeScript renames or moves; a small change to one file is quicker as a direct edit. Top-level await and ordinary Bun/Node APIs work. Use repository-relative paths. Set cwd to a checkout path when Pi's working directory is outside the repository, such as a child worktree in a bare worktree container. The program runs in an isolated workspace; changes apply on successful exit by default and the tool reports the diff. Tests, type-checks and builds belong outside the program: in a shell call, or, when a codemode script calls code, later in that script.
 
 Common operations:
 - edit({ path, oldText, newText }) replaces exactly one literal occurrence; missing or ambiguous text is an error. Use text edits for known source, structural matching when it saves enumerating occurrences or preserves varying syntax.
@@ -51,6 +51,59 @@ export function codeDescription(graphAvailable: boolean): string {
 		: DESCRIPTION;
 }
 
+const paths = (description: string) => Type.Array(Type.String(), { description });
+
+/**
+ * What a script gets back from `code`, for example one run by Pi's codemode tool. The model still sees the text.
+ * A failed run resolves to this too, so a script checks `exitCode`.
+ */
+export const CODE_OUTPUT_SCHEMA = Type.Object({
+	exitCode: Type.Optional(
+		Type.Union([Type.Number(), Type.Null()], { description: "0 on success; null when the program was killed" }),
+	),
+	timedOut: Type.Optional(Type.Boolean()),
+	output: Type.Optional(Type.String({ description: "The program's stdout and stderr" })),
+	errorLine: Type.Optional(Type.String({ description: "On failure, the program line the error came from" })),
+	warnings: Type.Optional(Type.Array(Type.String(), { description: "Likely mistakes spotted before it ran" })),
+	changes: Type.Optional(
+		Type.Array(
+			Type.Object({
+				path: Type.String(),
+				kind: StringEnum(["added", "modified", "deleted"] as const),
+				patch: Type.String(),
+			}),
+		),
+	),
+	applied: Type.Optional(paths("Changed files written to the repository")),
+	conflicts: Type.Optional(paths("Files that changed outside the run while it ran; if any, nothing was applied")),
+	rolledBack: Type.Optional(paths("Changed files not kept after a failure")),
+	infrastructureError: Type.Optional(Type.String({ description: "Set, alone, when the program couldn't be run" })),
+});
+
+export function codeOutput(result: RunResult) {
+	const { exitCode, timedOut, output, errorLine, warnings, applied, conflicts, rolledBack } = result;
+	const changes = result.changes.map((change) => ({ path: change.path, kind: change.kind, patch: change.patch }));
+	return {
+		exitCode,
+		timedOut,
+		output,
+		...(errorLine === undefined ? {} : { errorLine }),
+		warnings,
+		changes,
+		applied,
+		conflicts,
+		rolledBack,
+	};
+}
+
+/**
+ * Base name of the temporary files that hold a large run's full diff or output. A call a codemode script makes has
+ * an id like `<parent id>/1`, and ids can hold `|`, so anything but a safe file-name character is replaced.
+ */
+export function spillName(toolCallId: string): string {
+	return `pi-shorthand-${toolCallId.replace(/[^\w.-]/g, "_")}`;
+}
+
 export default async function (pi: ExtensionAPI, findGraph: () => Promise<unknown> = sightreadAvailable) {
 	// The shorthand skill ships with shorthand-code, whose `shorthand --skill` prints it for other agents.
 	pi.on("resources_discover", () => ({ skillPaths: [SKILLS_DIRECTORY] }));
@@ -67,7 +120,7 @@ export default async function (pi: ExtensionAPI, findGraph: () => Promise<unknow
 		label: "Code",
 		description: codeDescription(graphAvailable),
 		promptSnippet:
-			"Make multi-file, repetitive or rename/move changes with one Bun program; a small change to one file is quicker as a direct edit. Run verification separately afterward",
+			"Make multi-file, repetitive or rename/move changes with one Bun program; a small change to one file is quicker as a direct edit. Keep verification outside the program",
 
 		parameters: Type.Object({
 			title: Type.String({ description: "A few words describing the change, shown to the user" }),
@@ -90,6 +143,7 @@ export default async function (pi: ExtensionAPI, findGraph: () => Promise<unknow
 				}),
 			),
 		}),
+		outputSchema: CODE_OUTPUT_SCHEMA,
 
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
 			// While it runs, show how long it's been going and the latest reported step.
@@ -122,6 +176,7 @@ export default async function (pi: ExtensionAPI, findGraph: () => Promise<unknow
 					isError: true,
 					content: [{ type: "text" as const, text: [error.message, ...diagnosticLines(error.diagnostics)].join("\n") }],
 					details: { infrastructureError: error.message, diagnostics: error.diagnostics },
+					structuredContent: { infrastructureError: error.message },
 				};
 			} finally {
 				clearInterval(progress);
@@ -130,10 +185,11 @@ export default async function (pi: ExtensionAPI, findGraph: () => Promise<unknow
 				content: [
 					{
 						type: "text",
-						text: textForModel(result, { name: `pi-shorthand-${toolCallId}`, truncateHead, truncateTail }),
+						text: textForModel(result, { name: spillName(toolCallId), truncateHead, truncateTail }),
 					},
 				],
 				details: result,
+				structuredContent: codeOutput(result),
 			};
 		},