@earendil-works/pi-durable 0.99.0 → 0.99.2

package/dist/tools/read.js

@@ -0,0 +1,100 @@
+import { Type } from "typebox";
+import { getOrThrow } from "../env/index.js";
+import { characterEnd } from "../harness/output.js";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead } from "../truncate.js";
+import { requireEnv } from "./env.js";
+import { detectSupportedImageMimeType } from "./image.js";
+import { resolveReadToolPath } from "./path-utils.js";
+const readSchema = Type.Object({
+    path: Type.String({ description: "Path to the file to read (relative or absolute)" }),
+    offset: Type.Optional(Type.Number({ description: "Line number to start reading from (1-indexed)" })),
+    limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })),
+});
+/** Reads text files. Remarks about truncation and continuation are diagnostics; the content is only file text. */
+export function createReadTool() {
+    return {
+        name: "read",
+        description: `Read the contents of a text file. Output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete.`,
+        parameters: readSchema,
+        async execute(args, api, context) {
+            const { path, offset, limit } = args;
+            const env = requireEnv(api);
+            const absolutePath = await resolveReadToolPath(env, path, context);
+            const bytes = getOrThrow(await env.readBinaryFile(absolutePath, context));
+            const mimeType = detectSupportedImageMimeType(bytes);
+            if (mimeType) {
+                // Image content is not supported yet.
+                return {
+                    content: [],
+                    isError: true,
+                    diagnostics: [
+                        {
+                            severity: "error",
+                            code: "unsupported_image",
+                            message: `${path} is an image (${mimeType}); reading images is not supported`,
+                        },
+                    ],
+                };
+            }
+            const textContent = new TextDecoder().decode(bytes);
+            const allLines = textContent.split("\n");
+            const totalFileLines = allLines.length;
+            const startLine = offset ? Math.max(0, offset - 1) : 0;
+            const startLineDisplay = startLine + 1;
+            if (startLine >= allLines.length) {
+                throw new Error(`Offset ${offset} is beyond end of file (${allLines.length} lines total)`);
+            }
+            let selectedContent;
+            let userLimitedLines;
+            if (limit !== undefined) {
+                const endLine = Math.min(startLine + limit, allLines.length);
+                selectedContent = allLines.slice(startLine, endLine).join("\n");
+                userLimitedLines = endLine - startLine;
+            }
+            else {
+                selectedContent = allLines.slice(startLine).join("\n");
+            }
+            const { content: headText, ...truncation } = truncateHead(selectedContent);
+            const diagnostics = [];
+            let outputText = headText;
+            let details;
+            if (truncation.firstLineExceedsLimit) {
+                // Show the start of the line, cut at the byte limit on a character boundary.
+                const lineBytes = new TextEncoder().encode(allLines[startLine]);
+                const end = characterEnd(lineBytes, DEFAULT_MAX_BYTES);
+                outputText = new TextDecoder().decode(lineBytes.subarray(0, end));
+                diagnostics.push({
+                    severity: "warn",
+                    code: "truncated",
+                    message: `Line ${startLineDisplay} is ${formatSize(lineBytes.byteLength)}, exceeds the ${formatSize(DEFAULT_MAX_BYTES)} limit; showing its first ${formatSize(end)}. Use bash: sed -n '${startLineDisplay}p' ${path} | tail -c +${end + 1}`,
+                });
+                details = { truncation: { ...truncation, outputBytes: end, outputLines: 1 } };
+            }
+            else if (truncation.truncated) {
+                const endLineDisplay = startLineDisplay + truncation.outputLines - 1;
+                const nextOffset = endLineDisplay + 1;
+                const limitText = truncation.truncatedBy === "lines" ? "" : ` (${formatSize(DEFAULT_MAX_BYTES)} limit)`;
+                diagnostics.push({
+                    severity: "info",
+                    code: "truncated",
+                    message: `Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}${limitText}. Use offset=${nextOffset} to continue.`,
+                });
+                details = { truncation };
+            }
+            else if (userLimitedLines !== undefined && startLine + userLimitedLines < allLines.length) {
+                const remaining = allLines.length - (startLine + userLimitedLines);
+                const nextOffset = startLine + userLimitedLines + 1;
+                diagnostics.push({
+                    severity: "info",
+                    message: `${remaining} more lines in file. Use offset=${nextOffset} to continue.`,
+                });
+            }
+            return {
+                content: outputText === "" ? [] : [{ type: "text", text: outputText }],
+                ...(details === undefined ? {} : { details: details }),
+                diagnostics,
+            };
+        },
+    };
+}
+//# sourceMappingURL=read.js.map

package/dist/tools/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../src/tools/read.ts"],"names":[],"mappings":"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","sourcesContent":["import type { JsonValue } from \"@earendil-works/chord\";\nimport { type Static, Type } from \"typebox\";\nimport { getOrThrow } from \"../env/index.ts\";\nimport { characterEnd } from \"../harness/output.ts\";\nimport type { ToolDiagnostic, ToolRegistration } from \"../harness/types.ts\";\nimport { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, type TruncationResult, truncateHead } from \"../truncate.ts\";\nimport { requireEnv } from \"./env.ts\";\nimport { detectSupportedImageMimeType } from \"./image.ts\";\nimport { resolveReadToolPath } from \"./path-utils.ts\";\n\nconst readSchema = Type.Object({\n\tpath: Type.String({ description: \"Path to the file to read (relative or absolute)\" }),\n\toffset: Type.Optional(Type.Number({ description: \"Line number to start reading from (1-indexed)\" })),\n\tlimit: Type.Optional(Type.Number({ description: \"Maximum number of lines to read\" })),\n});\n\nexport type ReadToolInput = Static<typeof readSchema>;\n\nexport interface ReadToolDetails {\n\t/** How the shown text was cut; the text itself is the result content. */\n\ttruncation?: Omit<TruncationResult, \"content\">;\n}\n\n/** Reads text files. Remarks about truncation and continuation are diagnostics; the content is only file text. */\nexport function createReadTool(): ToolRegistration {\n\treturn {\n\t\tname: \"read\",\n\t\tdescription: `Read the contents of a text file. Output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete.`,\n\t\tparameters: readSchema,\n\t\tasync execute(args, api, context) {\n\t\t\tconst { path, offset, limit } = args as ReadToolInput;\n\t\t\tconst env = requireEnv(api);\n\t\t\tconst absolutePath = await resolveReadToolPath(env, path, context);\n\t\t\tconst bytes = getOrThrow(await env.readBinaryFile(absolutePath, context));\n\t\t\tconst mimeType = detectSupportedImageMimeType(bytes);\n\t\t\tif (mimeType) {\n\t\t\t\t// Image content is not supported yet.\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [],\n\t\t\t\t\tisError: true,\n\t\t\t\t\tdiagnostics: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tseverity: \"error\",\n\t\t\t\t\t\t\tcode: \"unsupported_image\",\n\t\t\t\t\t\t\tmessage: `${path} is an image (${mimeType}); reading images is not supported`,\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tconst textContent = new TextDecoder().decode(bytes);\n\t\t\tconst allLines = textContent.split(\"\\n\");\n\t\t\tconst totalFileLines = allLines.length;\n\t\t\tconst startLine = offset ? Math.max(0, offset - 1) : 0;\n\t\t\tconst startLineDisplay = startLine + 1;\n\t\t\tif (startLine >= allLines.length) {\n\t\t\t\tthrow new Error(`Offset ${offset} is beyond end of file (${allLines.length} lines total)`);\n\t\t\t}\n\n\t\t\tlet selectedContent: string;\n\t\t\tlet userLimitedLines: number | undefined;\n\t\t\tif (limit !== undefined) {\n\t\t\t\tconst endLine = Math.min(startLine + limit, allLines.length);\n\t\t\t\tselectedContent = allLines.slice(startLine, endLine).join(\"\\n\");\n\t\t\t\tuserLimitedLines = endLine - startLine;\n\t\t\t} else {\n\t\t\t\tselectedContent = allLines.slice(startLine).join(\"\\n\");\n\t\t\t}\n\n\t\t\tconst { content: headText, ...truncation } = truncateHead(selectedContent);\n\t\t\tconst diagnostics: ToolDiagnostic[] = [];\n\t\t\tlet outputText = headText;\n\t\t\tlet details: ReadToolDetails | undefined;\n\t\t\tif (truncation.firstLineExceedsLimit) {\n\t\t\t\t// Show the start of the line, cut at the byte limit on a character boundary.\n\t\t\t\tconst lineBytes = new TextEncoder().encode(allLines[startLine]);\n\t\t\t\tconst end = characterEnd(lineBytes, DEFAULT_MAX_BYTES);\n\t\t\t\toutputText = new TextDecoder().decode(lineBytes.subarray(0, end));\n\t\t\t\tdiagnostics.push({\n\t\t\t\t\tseverity: \"warn\",\n\t\t\t\t\tcode: \"truncated\",\n\t\t\t\t\tmessage: `Line ${startLineDisplay} is ${formatSize(lineBytes.byteLength)}, exceeds the ${formatSize(DEFAULT_MAX_BYTES)} limit; showing its first ${formatSize(end)}. Use bash: sed -n '${startLineDisplay}p' ${path} | tail -c +${end + 1}`,\n\t\t\t\t});\n\t\t\t\tdetails = { truncation: { ...truncation, outputBytes: end, outputLines: 1 } };\n\t\t\t} else if (truncation.truncated) {\n\t\t\t\tconst endLineDisplay = startLineDisplay + truncation.outputLines - 1;\n\t\t\t\tconst nextOffset = endLineDisplay + 1;\n\t\t\t\tconst limitText = truncation.truncatedBy === \"lines\" ? \"\" : ` (${formatSize(DEFAULT_MAX_BYTES)} limit)`;\n\t\t\t\tdiagnostics.push({\n\t\t\t\t\tseverity: \"info\",\n\t\t\t\t\tcode: \"truncated\",\n\t\t\t\t\tmessage: `Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}${limitText}. Use offset=${nextOffset} to continue.`,\n\t\t\t\t});\n\t\t\t\tdetails = { truncation };\n\t\t\t} else if (userLimitedLines !== undefined && startLine + userLimitedLines < allLines.length) {\n\t\t\t\tconst remaining = allLines.length - (startLine + userLimitedLines);\n\t\t\t\tconst nextOffset = startLine + userLimitedLines + 1;\n\t\t\t\tdiagnostics.push({\n\t\t\t\t\tseverity: \"info\",\n\t\t\t\t\tmessage: `${remaining} more lines in file. Use offset=${nextOffset} to continue.`,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\treturn {\n\t\t\t\tcontent: outputText === \"\" ? [] : [{ type: \"text\", text: outputText }],\n\t\t\t\t...(details === undefined ? {} : { details: details as unknown as JsonValue }),\n\t\t\t\tdiagnostics,\n\t\t\t};\n\t\t},\n\t};\n}\n"]}

package/dist/tools/write.d.ts

@@ -0,0 +1,10 @@
+import { type Static, Type } from "typebox";
+import type { ToolRegistration } from "../harness/types.ts";
+declare const writeSchema: Type.TObject<{
+    path: Type.TString;
+    content: Type.TString;
+}>;
+export type WriteToolInput = Static<typeof writeSchema>;
+export declare function createWriteTool(): ToolRegistration;
+export {};
+//# sourceMappingURL=write.d.ts.map

package/dist/tools/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/tools/write.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAK5D,QAAA,MAAM,WAAW;;;EAGf,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAExD,wBAAgB,eAAe,IAAI,gBAAgB,CAuBlD"}

package/dist/tools/write.js

@@ -0,0 +1,30 @@
+import { Type } from "typebox";
+import { getOrThrow } from "../env/index.js";
+import { requireEnv } from "./env.js";
+import { withFileMutationQueue } from "./file-mutation-queue.js";
+import { resolveToolPath } from "./path-utils.js";
+const writeSchema = Type.Object({
+    path: Type.String({ description: "Path to the file to write (relative or absolute)" }),
+    content: Type.String({ description: "Content to write to the file" }),
+});
+export function createWriteTool() {
+    return {
+        name: "write",
+        description: "Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.",
+        parameters: writeSchema,
+        async execute(args, api, context) {
+            const { path, content } = args;
+            const env = requireEnv(api);
+            const absolutePath = await resolveToolPath(env, path, context);
+            return withFileMutationQueue(env, absolutePath, async () => {
+                if (context.abortSignal?.aborted)
+                    throw new Error("Operation aborted");
+                getOrThrow(await env.writeFile(absolutePath, content, context));
+                if (context.abortSignal?.aborted)
+                    throw new Error("Operation aborted");
+                return { content: [{ type: "text", text: `Successfully wrote to ${path}` }] };
+            }, context);
+        },
+    };
+}
+//# sourceMappingURL=write.js.map

package/dist/tools/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../src/tools/write.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC;IAC/B,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,kDAAkD,EAAE,CAAC;IACtF,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,8BAA8B,EAAE,CAAC;CACrE,CAAC,CAAC;AAIH,MAAM,UAAU,eAAe;IAC9B,OAAO;QACN,IAAI,EAAE,OAAO;QACb,WAAW,EACV,iIAAiI;QAClI,UAAU,EAAE,WAAW;QACvB,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO;YAC/B,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAsB,CAAC;YACjD,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;YAC5B,MAAM,YAAY,GAAG,MAAM,eAAe,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;YAC/D,OAAO,qBAAqB,CAC3B,GAAG,EACH,YAAY,EACZ,KAAK,IAAI,EAAE;gBACV,IAAI,OAAO,CAAC,WAAW,EAAE,OAAO;oBAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;gBACvE,UAAU,CAAC,MAAM,GAAG,CAAC,SAAS,CAAC,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;gBAChE,IAAI,OAAO,CAAC,WAAW,EAAE,OAAO;oBAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;gBACvE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,yBAAyB,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC;YAC/E,CAAC,EACD,OAAO,CACP,CAAC;QACH,CAAC;KACD,CAAC;AACH,CAAC","sourcesContent":["import { type Static, Type } from \"typebox\";\nimport { getOrThrow } from \"../env/index.ts\";\nimport type { ToolRegistration } from \"../harness/types.ts\";\nimport { requireEnv } from \"./env.ts\";\nimport { withFileMutationQueue } from \"./file-mutation-queue.ts\";\nimport { resolveToolPath } from \"./path-utils.ts\";\n\nconst writeSchema = Type.Object({\n\tpath: Type.String({ description: \"Path to the file to write (relative or absolute)\" }),\n\tcontent: Type.String({ description: \"Content to write to the file\" }),\n});\n\nexport type WriteToolInput = Static<typeof writeSchema>;\n\nexport function createWriteTool(): ToolRegistration {\n\treturn {\n\t\tname: \"write\",\n\t\tdescription:\n\t\t\t\"Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.\",\n\t\tparameters: writeSchema,\n\t\tasync execute(args, api, context) {\n\t\t\tconst { path, content } = args as WriteToolInput;\n\t\t\tconst env = requireEnv(api);\n\t\t\tconst absolutePath = await resolveToolPath(env, path, context);\n\t\t\treturn withFileMutationQueue(\n\t\t\t\tenv,\n\t\t\t\tabsolutePath,\n\t\t\t\tasync () => {\n\t\t\t\t\tif (context.abortSignal?.aborted) throw new Error(\"Operation aborted\");\n\t\t\t\t\tgetOrThrow(await env.writeFile(absolutePath, content, context));\n\t\t\t\t\tif (context.abortSignal?.aborted) throw new Error(\"Operation aborted\");\n\t\t\t\t\treturn { content: [{ type: \"text\", text: `Successfully wrote to ${path}` }] };\n\t\t\t\t},\n\t\t\t\tcontext,\n\t\t\t);\n\t\t},\n\t};\n}\n"]}

package/dist/{env/utils/truncate.d.ts → truncate.d.ts}

@@ -5,11 +5,10 @@
  * - Line limit (default: 2000 lines)
  * - Byte limit (default: 50KB)
  *
- * Never returns partial lines (except bash tail truncation edge case).
+ * Never returns partial lines. Tool output streams are bounded by `src/harness/output.ts` instead.
  */
 export declare const DEFAULT_MAX_LINES = 2000;
 export declare const DEFAULT_MAX_BYTES: number;
-export declare const GREP_MAX_LINE_LENGTH = 500;
 export interface TruncationResult {
     /** The truncated content */
     content: string;
@@ -53,19 +52,4 @@ export declare function formatSize(bytes: number): string;
  * returns empty content with firstLineExceedsLimit=true.
  */
 export declare function truncateHead(content: string, options?: TruncationOptions): TruncationResult;
-/**
- * Truncate content from the tail (keep last N lines/bytes).
- * Suitable for bash output where you want to see the end (errors, final results).
- *
- * May return partial first line if the last line of original content exceeds byte limit.
- */
-export declare function truncateTail(content: string, options?: TruncationOptions): TruncationResult;
-/**
- * Truncate a single line to max characters, adding [truncated] suffix.
- * Used for grep match lines.
- */
-export declare function truncateLine(line: string, maxChars?: number): {
-    text: string;
-    wasTruncated: boolean;
-};
 //# sourceMappingURL=truncate.d.ts.map

package/dist/truncate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncate.d.ts","sourceRoot":"","sources":["../src/truncate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AACtC,eAAO,MAAM,iBAAiB,QAAY,CAAC;AAE3C,MAAM,WAAW,gBAAgB;IAChC,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,sEAAsE;IACtE,WAAW,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAAC;IACtC,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,eAAe,EAAE,OAAO,CAAC;IACzB,2EAA2E;IAC3E,qBAAqB,EAAE,OAAO,CAAC;IAC/B,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IACjC,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AASD,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA0BtD;AASD;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAgF/F"}

package/dist/truncate.js

@@ -0,0 +1,146 @@
+/**
+ * Shared truncation utilities for tool outputs.
+ *
+ * Truncation is based on two independent limits - whichever is hit first wins:
+ * - Line limit (default: 2000 lines)
+ * - Byte limit (default: 50KB)
+ *
+ * Never returns partial lines. Tool output streams are bounded by `src/harness/output.ts` instead.
+ */
+export const DEFAULT_MAX_LINES = 2000;
+export const DEFAULT_MAX_BYTES = 50 * 1024; // 50KB
+const runtimeBuffer = globalThis.Buffer;
+const nonAsciiPattern = /[^\x00-\x7f]/;
+export function utf8ByteLength(content) {
+    if (runtimeBuffer)
+        return runtimeBuffer.byteLength(content, "utf8");
+    const firstNonAscii = content.search(nonAsciiPattern);
+    if (firstNonAscii === -1)
+        return content.length;
+    let bytes = firstNonAscii;
+    for (let i = firstNonAscii; i < content.length; i++) {
+        const code = content.charCodeAt(i);
+        if (code <= 0x7f) {
+            bytes += 1;
+        }
+        else if (code <= 0x7ff) {
+            bytes += 2;
+        }
+        else if (code >= 0xd800 && code <= 0xdbff && i + 1 < content.length) {
+            const next = content.charCodeAt(i + 1);
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                bytes += 4;
+                i++;
+            }
+            else {
+                bytes += 3;
+            }
+        }
+        else {
+            bytes += 3;
+        }
+    }
+    return bytes;
+}
+function splitLinesForCounting(content) {
+    if (content.length === 0)
+        return [];
+    const lines = content.split("\n");
+    if (content.endsWith("\n"))
+        lines.pop();
+    return lines;
+}
+/**
+ * Format bytes as human-readable size.
+ */
+export function formatSize(bytes) {
+    if (bytes < 1024) {
+        return `${bytes}B`;
+    }
+    else if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    }
+    else {
+        return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+    }
+}
+/**
+ * Truncate content from the head (keep first N lines/bytes).
+ * Suitable for file reads where you want to see the beginning.
+ *
+ * Never returns partial lines. If first line exceeds byte limit,
+ * returns empty content with firstLineExceedsLimit=true.
+ */
+export function truncateHead(content, options = {}) {
+    const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const totalBytes = utf8ByteLength(content);
+    const lines = splitLinesForCounting(content);
+    const totalLines = lines.length;
+    // Check if no truncation needed
+    if (totalLines <= maxLines && totalBytes <= maxBytes) {
+        return {
+            content,
+            truncated: false,
+            truncatedBy: null,
+            totalLines,
+            totalBytes,
+            outputLines: totalLines,
+            outputBytes: totalBytes,
+            lastLinePartial: false,
+            firstLineExceedsLimit: false,
+            maxLines,
+            maxBytes,
+        };
+    }
+    // Check if first line alone exceeds byte limit
+    const firstLineBytes = utf8ByteLength(lines[0]);
+    if (firstLineBytes > maxBytes) {
+        return {
+            content: "",
+            truncated: true,
+            truncatedBy: "bytes",
+            totalLines,
+            totalBytes,
+            outputLines: 0,
+            outputBytes: 0,
+            lastLinePartial: false,
+            firstLineExceedsLimit: true,
+            maxLines,
+            maxBytes,
+        };
+    }
+    // Collect complete lines that fit
+    const outputLinesArr = [];
+    let outputBytesCount = 0;
+    let truncatedBy = "lines";
+    for (let i = 0; i < lines.length && i < maxLines; i++) {
+        const line = lines[i];
+        const lineBytes = utf8ByteLength(line) + (i > 0 ? 1 : 0); // +1 for newline
+        if (outputBytesCount + lineBytes > maxBytes) {
+            truncatedBy = "bytes";
+            break;
+        }
+        outputLinesArr.push(line);
+        outputBytesCount += lineBytes;
+    }
+    // Without a byte break, only omitted lines prove the line limit was reached; otherwise a trailing newline exceeded bytes.
+    if (truncatedBy !== "bytes")
+        truncatedBy = outputLinesArr.length < totalLines ? "lines" : "bytes";
+    const outputContent = outputLinesArr.join("\n");
+    const finalOutputBytes = utf8ByteLength(outputContent);
+    return {
+        content: outputContent,
+        truncated: true,
+        truncatedBy,
+        totalLines,
+        totalBytes,
+        outputLines: outputLinesArr.length,
+        outputBytes: finalOutputBytes,
+        lastLinePartial: false,
+        firstLineExceedsLimit: false,
+        maxLines,
+        maxBytes,
+    };
+}
+//# sourceMappingURL=truncate.js.map

package/dist/truncate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncate.js","sourceRoot":"","sources":["../src/truncate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared truncation utilities for tool outputs.\n *\n * Truncation is based on two independent limits - whichever is hit first wins:\n * - Line limit (default: 2000 lines)\n * - Byte limit (default: 50KB)\n *\n * Never returns partial lines. Tool output streams are bounded by `src/harness/output.ts` instead.\n */\n\nexport const DEFAULT_MAX_LINES = 2000;\nexport const DEFAULT_MAX_BYTES = 50 * 1024; // 50KB\n\nexport interface TruncationResult {\n\t/** The truncated content */\n\tcontent: string;\n\t/** Whether truncation occurred */\n\ttruncated: boolean;\n\t/** Which limit was hit: \"lines\", \"bytes\", or null if not truncated */\n\ttruncatedBy: \"lines\" | \"bytes\" | null;\n\t/** Total number of lines in the original content */\n\ttotalLines: number;\n\t/** Total number of bytes in the original content */\n\ttotalBytes: number;\n\t/** Number of complete lines in the truncated output */\n\toutputLines: number;\n\t/** Number of bytes in the truncated output */\n\toutputBytes: number;\n\t/** Whether the last line was partially truncated (only for tail truncation edge case) */\n\tlastLinePartial: boolean;\n\t/** Whether the first line exceeded the byte limit (for head truncation) */\n\tfirstLineExceedsLimit: boolean;\n\t/** The max lines limit that was applied */\n\tmaxLines: number;\n\t/** The max bytes limit that was applied */\n\tmaxBytes: number;\n}\n\nexport interface TruncationOptions {\n\t/** Maximum number of lines (default: 2000) */\n\tmaxLines?: number;\n\t/** Maximum number of bytes (default: 50KB) */\n\tmaxBytes?: number;\n}\n\ninterface RuntimeBuffer {\n\tbyteLength(content: string, encoding: \"utf8\"): number;\n}\n\nconst runtimeBuffer = (globalThis as { Buffer?: RuntimeBuffer }).Buffer;\nconst nonAsciiPattern = /[^\\x00-\\x7f]/;\n\nexport function utf8ByteLength(content: string): number {\n\tif (runtimeBuffer) return runtimeBuffer.byteLength(content, \"utf8\");\n\n\tconst firstNonAscii = content.search(nonAsciiPattern);\n\tif (firstNonAscii === -1) return content.length;\n\n\tlet bytes = firstNonAscii;\n\tfor (let i = firstNonAscii; i < content.length; i++) {\n\t\tconst code = content.charCodeAt(i);\n\t\tif (code <= 0x7f) {\n\t\t\tbytes += 1;\n\t\t} else if (code <= 0x7ff) {\n\t\t\tbytes += 2;\n\t\t} else if (code >= 0xd800 && code <= 0xdbff && i + 1 < content.length) {\n\t\t\tconst next = content.charCodeAt(i + 1);\n\t\t\tif (next >= 0xdc00 && next <= 0xdfff) {\n\t\t\t\tbytes += 4;\n\t\t\t\ti++;\n\t\t\t} else {\n\t\t\t\tbytes += 3;\n\t\t\t}\n\t\t} else {\n\t\t\tbytes += 3;\n\t\t}\n\t}\n\treturn bytes;\n}\n\nfunction splitLinesForCounting(content: string): string[] {\n\tif (content.length === 0) return [];\n\tconst lines = content.split(\"\\n\");\n\tif (content.endsWith(\"\\n\")) lines.pop();\n\treturn lines;\n}\n\n/**\n * Format bytes as human-readable size.\n */\nexport function formatSize(bytes: number): string {\n\tif (bytes < 1024) {\n\t\treturn `${bytes}B`;\n\t} else if (bytes < 1024 * 1024) {\n\t\treturn `${(bytes / 1024).toFixed(1)}KB`;\n\t} else {\n\t\treturn `${(bytes / (1024 * 1024)).toFixed(1)}MB`;\n\t}\n}\n\n/**\n * Truncate content from the head (keep first N lines/bytes).\n * Suitable for file reads where you want to see the beginning.\n *\n * Never returns partial lines. If first line exceeds byte limit,\n * returns empty content with firstLineExceedsLimit=true.\n */\nexport function truncateHead(content: string, options: TruncationOptions = {}): TruncationResult {\n\tconst maxLines = options.maxLines ?? DEFAULT_MAX_LINES;\n\tconst maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;\n\n\tconst totalBytes = utf8ByteLength(content);\n\tconst lines = splitLinesForCounting(content);\n\tconst totalLines = lines.length;\n\n\t// Check if no truncation needed\n\tif (totalLines <= maxLines && totalBytes <= maxBytes) {\n\t\treturn {\n\t\t\tcontent,\n\t\t\ttruncated: false,\n\t\t\ttruncatedBy: null,\n\t\t\ttotalLines,\n\t\t\ttotalBytes,\n\t\t\toutputLines: totalLines,\n\t\t\toutputBytes: totalBytes,\n\t\t\tlastLinePartial: false,\n\t\t\tfirstLineExceedsLimit: false,\n\t\t\tmaxLines,\n\t\t\tmaxBytes,\n\t\t};\n\t}\n\n\t// Check if first line alone exceeds byte limit\n\tconst firstLineBytes = utf8ByteLength(lines[0]);\n\tif (firstLineBytes > maxBytes) {\n\t\treturn {\n\t\t\tcontent: \"\",\n\t\t\ttruncated: true,\n\t\t\ttruncatedBy: \"bytes\",\n\t\t\ttotalLines,\n\t\t\ttotalBytes,\n\t\t\toutputLines: 0,\n\t\t\toutputBytes: 0,\n\t\t\tlastLinePartial: false,\n\t\t\tfirstLineExceedsLimit: true,\n\t\t\tmaxLines,\n\t\t\tmaxBytes,\n\t\t};\n\t}\n\n\t// Collect complete lines that fit\n\tconst outputLinesArr: string[] = [];\n\tlet outputBytesCount = 0;\n\tlet truncatedBy: \"lines\" | \"bytes\" = \"lines\";\n\n\tfor (let i = 0; i < lines.length && i < maxLines; i++) {\n\t\tconst line = lines[i];\n\t\tconst lineBytes = utf8ByteLength(line) + (i > 0 ? 1 : 0); // +1 for newline\n\n\t\tif (outputBytesCount + lineBytes > maxBytes) {\n\t\t\ttruncatedBy = \"bytes\";\n\t\t\tbreak;\n\t\t}\n\n\t\toutputLinesArr.push(line);\n\t\toutputBytesCount += lineBytes;\n\t}\n\n\t// Without a byte break, only omitted lines prove the line limit was reached; otherwise a trailing newline exceeded bytes.\n\tif (truncatedBy !== \"bytes\") truncatedBy = outputLinesArr.length < totalLines ? \"lines\" : \"bytes\";\n\n\tconst outputContent = outputLinesArr.join(\"\\n\");\n\tconst finalOutputBytes = utf8ByteLength(outputContent);\n\n\treturn {\n\t\tcontent: outputContent,\n\t\ttruncated: true,\n\t\ttruncatedBy,\n\t\ttotalLines,\n\t\ttotalBytes,\n\t\toutputLines: outputLinesArr.length,\n\t\toutputBytes: finalOutputBytes,\n\t\tlastLinePartial: false,\n\t\tfirstLineExceedsLimit: false,\n\t\tmaxLines,\n\t\tmaxBytes,\n\t};\n}\n"]}

package/dist/types.d.ts

@@ -1,7 +1,8 @@
 import type { AttachedReplicatedState, Context, Draft, JsonValue } from "@earendil-works/chord";
 import type { Op } from "@earendil-works/chord/delta";
 import type { Message, Models } from "@earendil-works/pi-ai";
-import type { ContextView, RegistrySnapshot } from "./harness/types.ts";
+import type { ExecutionEnv } from "./env/index.ts";
+import type { ContextView, ConversationHandle, RegistrySnapshot, SettledTask } from "./harness/types.ts";
 /** JSON object used as the root of every durable document. */
 export type JsonObject = {
     [key: string]: JsonValue;
@@ -104,27 +105,45 @@ export type RunningTask<I, S, R> = TaskRecord<I, S, R> & {
         readonly status: "running";
     }>;
 };
-/** Next state a task commits for itself: a replacement checkpoint or its terminal outcome. */
+/**
+ * Next state a task commits for itself: a replacement checkpoint, a wait, or its outcome. A returned `terminal` state is
+ * stored as `completing` while ordinary owned work below the task is live (spec §5.5).
+ */
 export type NextTaskState<S, R> = Extract<TaskState<S, R>, {
-    readonly status: "running" | "terminal";
+    readonly status: "running" | "waiting" | "terminal";
 }>;
 /**
  * Runs one checkpoint phase. It must commit a changed checkpoint or a terminal outcome through `runtime.commit()`;
  * returning without durable progress faults the task.
  */
 export type PhaseHandler<I, P, S, R, H extends object> = (task: RunningTask<I, P, R>, runtime: TaskRuntime<I, S, R, H>, context: Context) => Promise<void>;
+/** Dispatches one hook of a task to every matching registered handler, in registry order of the phase snapshot. */
+export interface HookRunner<H extends object> {
+    /**
+     * Call `invoke` with each matching handler named `name`. An ordinary throw from `invoke` is reported and the next
+     * handler runs; once the invocation is signalled, the error propagates. Composition happens inside `invoke`.
+     */
+    each<K extends keyof H>(name: K, invoke: (handler: NonNullable<H[K]>) => void | Promise<void>): Promise<void>;
+}
 /**
  * Operations of one task invocation. Every operation rejects after the invocation ends; watches acquired through it
- * stop at invocation end. `_H` is the task's hook map, consumed once the runtime gains its hook runner.
+ * stop at invocation end.
  */
-export interface TaskRuntime<I, S, R, _H extends object> extends DocumentObserver, DocumentReader {
+export interface TaskRuntime<I, S, R, H extends object> extends DocumentObserver, DocumentReader {
     readonly taskId: TaskId<R>;
     readonly conversationId: ConversationId;
-    /** Aborted when the run is signalled by `abortTask()` or the Harness closes. */
+    /**
+     * Aborted when the run is signalled by `abortTask()`, the Harness closes, or the invocation ends. Work still using it
+     * after the invocation ended, such as a detached wait, is cancelled; it could not write anything anyway.
+     */
     readonly signal: AbortSignal;
     /** Registry snapshot of the current phase; refreshed at every phase boundary. */
     readonly registry: RegistrySnapshot;
     readonly models: Models;
+    /** `HarnessOptions.env`; tools receive it as `api.env`. */
+    readonly env: ExecutionEnv | undefined;
+    /** Handlers registered for this task's name whose scope matches its conversation. */
+    readonly hooks: HookRunner<H>;
     /**
      * Commit on the Session line after rereading the task. Rejects when the task is terminal, the invocation ended, the
      * Harness is closing, or, in a run invocation, the task carries an abort mark. A returned state replaces the task's
@@ -136,6 +155,21 @@ export interface TaskRuntime<I, S, R, _H extends object> extends DocumentObserve
     memo<T extends JsonValue>(name: string, context: Context): Promise<T | undefined>;
     /** Store `candidate` unless a memo already exists; return the durable winner. */
     memo<T extends JsonValue>(name: string, candidate: T, context: Context): Promise<T>;
+    /** Committed task record. */
+    getTask<T>(id: TaskId<T>, context: Context): Promise<TaskRecord<JsonValue, JsonValue, T> | undefined>;
+    /** Resolve with the task's terminal receipt; rejects when the invocation ends. */
+    waitForTask<T>(id: TaskId<T>, context: Context): Promise<SettledTask<T>>;
+    /** Outcomes of terminal tasks, in order; rejects when one is missing or not terminal. Used after a wait. */
+    outcomes<T>(ids: readonly TaskId<T>[], context: Context): Promise<TaskOutcome<T>[]>;
+    /**
+     * Invocation-bound handle of an existing conversation, for example one this task owns; `undefined` when absent. Its
+     * operations and the submissions it returns reject after the invocation ends; admitted work stays durable.
+     */
+    conversation(id: ConversationId, context: Context): Promise<ConversationHandle | undefined>;
+    /** Committed entry visible from the task's conversation. */
+    entry(id: EntryId, context: Context): Promise<EntryRecord | undefined>;
+    /** Undefined when the entry is absent, not visible, or has another kind. */
+    entry<D extends JsonValue>(token: Entry<D>, id: EntryId, context: Context): Promise<TypedEntry<D> | undefined>;
     /** Committed raw active transcript and model context, optionally cut off at the visible entry `at`. */
     context(conversationId: ConversationId, context: Context, at?: EntryId): Promise<ContextView>;
     /** The Harness clock. */
@@ -176,13 +210,25 @@ export interface Task<I, S extends {
 }, R, H extends object> {
     readonly definition: TaskDefinition<I, S, R, H>;
 }
+/** Who owns a task: its conversation (a top-level task) or another task of the same conversation (a child task). */
+export type TaskOwnership = {
+    readonly kind: "conversation";
+} | {
+    readonly kind: "task";
+    readonly taskId: TaskId;
+};
+/** How a waiting task treats the tasks it waits on (spec §5.5). */
+export type JoinPolicy = "failFast" | "allSettled";
 /** Creation options for a durable task. */
 export type TaskOptions = {
-    /** Owning conversation; required for Session commits that are not bound to a conversation. */
+    /** Required: a task always names its owner (spec §5.5). */
+    readonly ownership: TaskOwnership;
+    /**
+     * Default: the owner task's conversation, or the transaction's bound conversation; required for conversation-owned
+     * tasks created by Session commits that are not bound to a conversation.
+     */
     readonly conversationId?: ConversationId;
-    /** Tasks that must be terminal before ordinary execution may begin. */
-    readonly after?: readonly TaskId[];
-    /** Excluded from ordinary idle waits and conversation aborts. */
+    /** Conversation-owned tasks only: excluded from ordinary idle waits, conversation aborts, and cascades. */
     readonly background?: boolean;
 };
 /** Ownership selected explicitly whenever a conversation is created. */
@@ -373,7 +419,7 @@ export type TaskOutcome<R> = {
 };
 /** Complete durable execution state of a task. */
 export type TaskState<S, R> = {
-    /** Eligible for scheduling when its dependencies are terminal. */
+    /** Eligible for scheduling. */
     readonly status: "pending";
     /** Complete durable state from which execution resumes. */
     readonly checkpoint: S;
@@ -384,6 +430,18 @@ export type TaskState<S, R> = {
     /** Complete durable state from which execution resumes. */
     readonly checkpoint: S;
     readonly outcome?: never;
+} | {
+    /** Parked without an invocation until every task in `on` is terminal; then resumes at `checkpoint`. */
+    readonly status: "waiting";
+    readonly checkpoint: S;
+    readonly on: readonly TaskId[];
+    readonly policy: JoinPolicy;
+    readonly outcome?: never;
+} | {
+    /** Outcome decided; becomes terminal once no ordinary owned work below is live. Runs no more code. */
+    readonly status: "completing";
+    readonly checkpoint?: never;
+    readonly outcome: TaskOutcome<R>;
 } | {
     /** Permanently settled durable result receipt. */
     readonly status: "terminal";
@@ -400,9 +458,9 @@ type TaskRecordBase<I, R> = {
     readonly version: number;
     /** Original task input retained while the task is live or terminal. */
     readonly input: I;
-    /** Tasks that must be terminal before ordinary execution may begin. */
-    readonly after: readonly TaskId[];
-    /** Whether this task is excluded from ordinary idle waits and conversation aborts. */
+    /** Owning task of a child task; absent for a task its conversation owns. Immutable. */
+    readonly owner?: TaskId;
+    /** Whether this conversation-owned task is excluded from ordinary idle waits, conversation aborts, and cascades. */
     readonly background: boolean;
     /** Durable abort mark checked before run-mode progress is committed. */
     readonly abortRequested: boolean;
@@ -410,13 +468,13 @@ type TaskRecordBase<I, R> = {
 /** Complete replacement record for one durable task state machine. */
 export type TaskRecord<I, S, R> = TaskRecordBase<I, R> & ({
     readonly state: Extract<TaskState<S, R>, {
-        readonly status: "pending" | "running";
+        readonly status: "pending" | "running" | "waiting";
     }>;
-    /** Small first-writer-wins values retained while the task is live. */
+    /** Small first-writer-wins values retained while the task can run. */
     readonly memos?: Readonly<Record<string, JsonValue>>;
 } | {
     readonly state: Extract<TaskState<S, R>, {
-        readonly status: "terminal";
+        readonly status: "completing" | "terminal";
     }>;
     readonly memos?: never;
 });
@@ -487,7 +545,7 @@ export type EntryQuery = {
 export type TaskQuery = {
     readonly conversationId?: ConversationId;
     readonly kind?: string;
-    readonly status?: "pending" | "running" | "terminal";
+    readonly status?: TaskState<JsonValue, JsonValue>["status"];
     readonly abortRequested?: boolean;
     readonly background?: boolean;
 };
@@ -606,6 +664,10 @@ export interface Tx {
     task(id: TaskId): Promise<TaskRecord<JsonValue, JsonValue, JsonValue> | undefined>;
     scanConversations(query: ConversationQuery, limit: number, cursor?: Cursor): Promise<Page<ConversationRecord, Cursor>>;
     scanEntries(query: EntryQuery, limit: number, cursor?: Cursor): Promise<Page<EntryRecord, Cursor>>;
+    /** Newest visible entry of the conversation that carries a `head`. */
+    latestHeadMarker(conversationId: ConversationId): Promise<(EntryRecord & {
+        readonly head: EntryId;
+    }) | undefined>;
     scanTasks(query: TaskQuery, limit: number, cursor?: Cursor): Promise<Page<TaskRecord<JsonValue, JsonValue, JsonValue>, Cursor>>;
     /** Create a conversation with explicitly selected ownership. */
     createConversation(options: {
@@ -621,13 +683,18 @@ export interface Tx {
     appendEntry<D extends JsonValue>(token: Entry<D>, conversationId: ConversationId, value: TypedEntryDraft<NoInfer<D>>): Promise<TypedEntry<D>>;
     createTask<I, S extends {
         phase: string;
-    }, R, H extends object>(task: Task<I, S, R, H>, input: I, options?: TaskOptions): Promise<TaskId<R>>;
+    }, R, H extends object>(task: Task<I, S, R, H>, input: I, options: TaskOptions): Promise<TaskId<R>>;
     /**
      * Settle a queued or placed submission; only a placed input can be answered, and a settled submission stays
      * unchanged. Resolved against this transaction's latest record of the submission, so it works after table writes.
      * Run tasks settle the inputs they answer.
      */
     settleSubmission(id: SubmissionId, settlement: SubmissionSettlement): void;
+    /**
+     * Place a queued submission at `entry`: an input becomes `placed`, a write `done`. Resolved like
+     * `settleSubmission()`. Inbox boundaries place the submissions they select.
+     */
+    placeSubmission(id: SubmissionId, entry: EntryId): void;
     doc<T extends JsonObject>(token: SessionDocToken<T>): Promise<Draft<T>>;
     doc<T extends JsonObject>(token: ConversationDocToken<T>, conversationId: ConversationId): Promise<Draft<T>>;
     doc<T extends JsonObject>(token: TaskDocToken<T>, taskId: TaskId): Promise<Draft<T>>;