@ai-sdk/harness-pi 1.0.125 → 1.0.128

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-pi",
-  "version": "1.0.125",
+  "version": "1.0.128",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -26,8 +26,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/harness": "1.0.123",
-    "@ai-sdk/provider-utils": "5.0.47",
+    "@ai-sdk/harness": "1.0.126",
+    "@ai-sdk/provider-utils": "5.0.49",
     "@earendil-works/pi-ai": "0.74.2",
     "@earendil-works/pi-coding-agent": "^0.85.1",
     "pi-mcp-adapter": "2.12.1",
@@ -37,7 +37,7 @@
     "zod": "^3.25.76 || ^4.1.8"
   },
   "devDependencies": {
-    "@ai-sdk/sandbox-just-bash": "1.0.123",
+    "@ai-sdk/sandbox-just-bash": "1.0.126",
     "@types/node": "22.19.19",
     "@vercel/ai-tsconfig": "0.0.0",
     "tsup": "^8.5.1",

package/src/pi-harness.ts

@@ -74,9 +74,12 @@ const PI_BUILTIN_TOOLS = {
   read: commonTool('read', {
     nativeName: 'read',
     toolUseKind: 'readonly',
-    description: 'Read file contents.',
+    description:
+      'Read file contents. Output is limited to 2,000 lines or 50KB. Use offset and limit to read large files in pages.',
     inputSchema: z.object({
       file_path: z.string(),
+      offset: z.number().int().positive().optional(),
+      limit: z.number().int().positive().optional(),
     }),
   }),
   write: commonTool('write', {

package/src/pi-session.ts

@@ -50,6 +50,11 @@ import { getPiTerminalError, parseNativeEvent } from './pi-events';
 import { createPiModelResolver } from './pi-model-resolver';
 import { createPiPathMapper } from './pi-paths';
 import { createPiRemoteOps, type PiRemoteOps } from './pi-remote-ops';
+import {
+  formatPiReadToolOutput,
+  truncatePiToolOutputHead,
+  truncatePiToolOutputTail,
+} from './pi-tool-result';
 
 import {
   persistSessionFileToSandbox,
@@ -97,9 +102,10 @@ type PiMcpAdapterModule = {
 /*
  * Pi runs in this Node process, not behind an attachable in-sandbox bridge.
  * During a tool approval pause the Pi turn is still alive and blocked on the
- * custom tool promise, so detach must park that live session for the next
- * same-process resume instead of stopping it and resolving the promise as an
- * error. Cross-process resume still falls back to the persisted session file.
+ * custom tool promise, so in-process reattachment parks that live session for
+ * the next same-process resume instead of stopping it and resolving the
+ * promise as an error. Cross-process resume still falls back to the persisted
+ * session file.
  */
 const parkedPiSessions = new Map<
   string,
@@ -810,9 +816,8 @@ export async function createPiSession(
    * rerun's context carries the real outputs — without this, Pi's message
    * transform synthesizes an error result ("No result provided") for each
    * dangling call and the model continues as if the tool never answered. The
-   * serialized text matches what a live turn would have produced
-   * (`asPiToolResult(serializeToolOutput(...))`), so the model sees the same
-   * bytes either way.
+   * serialized and truncated text matches what a live turn would have
+   * produced, so the model sees the same result either way.
    */
   function appendDeliveredHostToolResults(): boolean {
     if (deliveredDanglingResults.size === 0 || resumeSessionFilePath == null) {
@@ -826,7 +831,13 @@ export async function createPiSession(
         toolCallId,
         toolName: delivered.toolName,
         content: [
-          { type: 'text', text: serializeToolOutput(delivered.output) },
+          {
+            type: 'text',
+            text: truncatePiToolOutputHead(
+              serializeToolOutput(delivered.output),
+              'Call the tool again with narrower parameters to inspect the omitted output.',
+            ),
+          },
         ],
         isError: delivered.isError,
         timestamp: Date.now(),
@@ -1570,7 +1581,10 @@ export async function createPiSession(
     doStop,
 
     doDetach: async (): Promise<HarnessV1ResumeSessionState> => {
-      if (activeTurn != null || pendingToolResults.size > 0) {
+      if (
+        input.settings.reattachInProcess !== false &&
+        (activeTurn != null || pendingToolResults.size > 0)
+      ) {
         parkedPiSessions.set(input.sessionId, {
           session: sessionImpl,
           input,
@@ -1602,6 +1616,7 @@ export async function createPiSession(
         throw new Error('Pi session has been stopped.');
       }
       if (
+        input.settings.reattachInProcess !== false &&
         activeTurn != null &&
         (pendingToolResults.size > 0 || pendingToolApprovals.size > 0)
       ) {
@@ -1640,8 +1655,11 @@ export async function createPiSession(
        */
       suspending = true;
       const turnToSuspend = activeTurn;
-      await turnToSuspend?.abort();
+      const abortingTurn = turnToSuspend?.abort();
       deferredRerun?.cancel();
+      settlePendingToolResults('Pi session suspended');
+      settlePendingToolApprovals('Pi session suspended');
+      await abortingTurn;
       await turnToSuspend?.done.catch(() => {});
 
       /*
@@ -1668,8 +1686,6 @@ export async function createPiSession(
 
       stopped = true;
       parkedPiSessions.delete(input.sessionId);
-      settlePendingToolResults('Pi session suspended');
-      settlePendingToolApprovals('Pi session suspended');
       await disposePiSession();
       workspaceVfs.unmount();
       await rm(hostRoot, { recursive: true, force: true });
@@ -1775,8 +1791,23 @@ function buildBuiltinToolDefinition(input: {
       return defineTool({
         name: 'read',
         label: 'read',
-        description: 'Read file contents.',
-        parameters: Type.Object({ file_path: Type.String() }),
+        description:
+          'Read file contents. Output is limited to 2,000 lines or 50KB. Use offset and limit to read large files in pages.',
+        parameters: Type.Object({
+          file_path: Type.String(),
+          offset: Type.Optional(
+            Type.Integer({
+              minimum: 1,
+              description: 'Line number to start reading from (1-indexed).',
+            }),
+          ),
+          limit: Type.Optional(
+            Type.Integer({
+              minimum: 1,
+              description: 'Maximum number of lines to read.',
+            }),
+          ),
+        }),
         async execute(toolCallId, params) {
           const denied = await maybeDenyPiBuiltinTool({
             toolCallId,
@@ -1785,7 +1816,14 @@ function buildBuiltinToolDefinition(input: {
           });
           if (denied) return denied;
           const buf = await input.remoteOps.readBuffer(params.file_path);
-          return asPiToolResult(buf.toString('utf8'));
+          return asPiToolResult(
+            formatPiReadToolOutput({
+              text: buf.toString('utf8'),
+              filePath: params.file_path,
+              offset: params.offset,
+              limit: params.limit,
+            }),
+          );
         },
       });
     case 'write':
@@ -1865,7 +1903,12 @@ function buildBuiltinToolDefinition(input: {
           const text = `${out}${
             result.exitCode != null ? `\n\n(exit ${result.exitCode})` : ''
           }`.trim();
-          return asPiToolResult(text);
+          return asPiToolResult(
+            truncatePiToolOutputTail(
+              text,
+              'Re-run the command with narrower output, or redirect it to a file and use read with offset and limit.',
+            ),
+          );
         },
       });
     case 'grep':
@@ -1890,7 +1933,12 @@ function buildBuiltinToolDefinition(input: {
           });
           if (denied) return denied;
           const out = await input.remoteOps.grepFiles(params.pattern, params);
-          return asPiToolResult(out);
+          return asPiToolResult(
+            truncatePiToolOutputHead(
+              out,
+              'Narrow the pattern or path, or read the matching file with offset and limit.',
+            ),
+          );
         },
       });
     case 'find':
@@ -1915,7 +1963,12 @@ function buildBuiltinToolDefinition(input: {
             params.path ?? '.',
             params.limit ?? 1_000,
           );
-          return asPiToolResult(matches.join('\n'));
+          return asPiToolResult(
+            truncatePiToolOutputHead(
+              matches.join('\n'),
+              'Narrow the pattern or search path to inspect the omitted matches.',
+            ),
+          );
         },
       });
     case 'ls':
@@ -1938,7 +1991,12 @@ function buildBuiltinToolDefinition(input: {
             params.path ?? '.',
             params.limit ?? 500,
           );
-          return asPiToolResult(entries.join('\n'));
+          return asPiToolResult(
+            truncatePiToolOutputHead(
+              entries.join('\n'),
+              'List a narrower directory path to inspect the omitted entries.',
+            ),
+          );
         },
       });
   }
@@ -1961,7 +2019,14 @@ function buildUserToolDefinition(
     async execute(toolCallId) {
       return new Promise<unknown>(resolve => {
         pending.set(toolCallId, { resolve });
-      }).then(output => asPiToolResult(serializeToolOutput(output)));
+      }).then(output =>
+        asPiToolResult(
+          truncatePiToolOutputHead(
+            serializeToolOutput(output),
+            'Call the tool again with narrower parameters to inspect the omitted output.',
+          ),
+        ),
+      );
     },
   });
 }

package/src/pi-tool-result.ts

@@ -0,0 +1,147 @@
+import {
+  DEFAULT_MAX_BYTES,
+  formatSize,
+  truncateHead,
+  truncateTail,
+  type TruncationResult,
+} from '@earendil-works/pi-coding-agent';
+
+type ReadToolOutputOptions = {
+  text: string;
+  filePath: string;
+  offset?: number;
+  limit?: number;
+};
+
+function joinContentAndNotice(content: string, notice: string): string {
+  return content.length > 0 ? `${content}\n\n[${notice}]` : `[${notice}]`;
+}
+
+function truncateUtf8Start(text: string, maxBytes: number): string {
+  const buffer = Buffer.from(text, 'utf8');
+  if (buffer.length <= maxBytes) return text;
+
+  let end = maxBytes;
+  while (end > 0 && (buffer[end] & 0xc0) === 0x80) {
+    end--;
+  }
+  return buffer.subarray(0, end).toString('utf8');
+}
+
+function formatHeadNotice(
+  truncation: TruncationResult,
+  continuation: string,
+): string {
+  const limit =
+    truncation.truncatedBy === 'bytes'
+      ? ` (${formatSize(truncation.maxBytes)} limit)`
+      : '';
+  return `Output truncated: showing the first ${truncation.outputLines} of ${truncation.totalLines} lines${limit}. ${continuation}`;
+}
+
+function formatTailNotice(
+  truncation: TruncationResult,
+  continuation: string,
+): string {
+  const limit =
+    truncation.truncatedBy === 'bytes'
+      ? ` (${formatSize(truncation.maxBytes)} limit)`
+      : '';
+  return `Output truncated: showing the last ${truncation.outputLines} of ${truncation.totalLines} lines${limit}. ${continuation}`;
+}
+
+export function truncatePiToolOutputHead(
+  text: string,
+  continuation: string,
+): string {
+  const truncation = truncateHead(text);
+  if (!truncation.truncated) return text;
+
+  if (truncation.firstLineExceedsLimit) {
+    const content = truncateUtf8Start(text, DEFAULT_MAX_BYTES);
+    return joinContentAndNotice(
+      content,
+      `Output truncated: showing the first ${formatSize(
+        Buffer.byteLength(content, 'utf8'),
+      )} of a ${formatSize(truncation.totalBytes)} line. ${continuation}`,
+    );
+  }
+
+  return joinContentAndNotice(
+    truncation.content,
+    formatHeadNotice(truncation, continuation),
+  );
+}
+
+export function truncatePiToolOutputTail(
+  text: string,
+  continuation: string,
+): string {
+  const truncation = truncateTail(text);
+  if (!truncation.truncated) return text;
+
+  return joinContentAndNotice(
+    truncation.content,
+    formatTailNotice(truncation, continuation),
+  );
+}
+
+export function formatPiReadToolOutput({
+  text,
+  filePath,
+  offset,
+  limit,
+}: ReadToolOutputOptions): string {
+  const allLines = text.split('\n');
+  const startLine = offset == null ? 0 : Math.max(0, Math.floor(offset) - 1);
+  const startLineDisplay = startLine + 1;
+
+  if (startLine >= allLines.length) {
+    throw new Error(
+      `Offset ${offset} is beyond end of file (${allLines.length} lines total)`,
+    );
+  }
+
+  const normalizedLimit =
+    limit == null ? undefined : Math.max(1, Math.floor(limit));
+  const endLine =
+    normalizedLimit == null
+      ? allLines.length
+      : Math.min(startLine + normalizedLimit, allLines.length);
+  const selectedContent = allLines.slice(startLine, endLine).join('\n');
+  const truncation = truncateHead(selectedContent);
+
+  if (truncation.firstLineExceedsLimit) {
+    const lineSize = formatSize(
+      Buffer.byteLength(allLines[startLine] ?? '', 'utf8'),
+    );
+    return `[Line ${startLineDisplay} is ${lineSize}, exceeds ${formatSize(
+      DEFAULT_MAX_BYTES,
+    )} limit. Use bash: sed -n '${startLineDisplay}p' ${filePath} | head -c ${DEFAULT_MAX_BYTES}]`;
+  }
+
+  if (truncation.truncated) {
+    const endLineDisplay =
+      startLineDisplay + Math.max(0, truncation.outputLines - 1);
+    const nextOffset = endLineDisplay + 1;
+    const limitNotice =
+      truncation.truncatedBy === 'bytes'
+        ? ` (${formatSize(DEFAULT_MAX_BYTES)} limit)`
+        : '';
+    return joinContentAndNotice(
+      truncation.content,
+      `Showing lines ${startLineDisplay}-${endLineDisplay} of ${allLines.length}${limitNotice}. Use offset=${nextOffset} to continue.`,
+    );
+  }
+
+  if (endLine < allLines.length) {
+    return joinContentAndNotice(
+      truncation.content,
+      `${allLines.length - endLine} more lines in file. Use offset=${
+        endLine + 1
+      } to continue.`,
+    );
+  }
+
+  return truncation.content;
+}