@geminixiang/mikan 0.2.0

package/dist/tools/event.js

@@ -0,0 +1,138 @@
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Type } from "@sinclair/typebox";
+import * as log from "../log.js";
+const eventSchema = Type.Object({
+    label: Type.String({
+        description: "Brief description of the event you're scheduling (shown to user)",
+    }),
+    type: Type.Union([Type.Literal("immediate"), Type.Literal("one-shot"), Type.Literal("periodic")]),
+    text: Type.String({
+        description: "A self-contained task for the future run. Include the necessary context, tone, and constraints in the text itself because events do not inherit normal conversation history.",
+    }),
+    at: Type.Optional(Type.String({
+        description: "ISO 8601 timestamp with offset, required for one-shot events",
+    })),
+    schedule: Type.Optional(Type.String({
+        description: "Cron schedule, required for periodic events",
+    })),
+    timezone: Type.Optional(Type.String({
+        description: "IANA timezone, required for periodic events",
+    })),
+    filenamePrefix: Type.Optional(Type.String({
+        description: "Optional filename prefix for the event file",
+    })),
+});
+export class HostEventStore {
+    constructor(eventsDir) {
+        this.eventsDir = eventsDir;
+    }
+    static fromWorkspaceDir(workspaceDir) {
+        return new HostEventStore(join(workspaceDir, "events"));
+    }
+    async write(filename, payload) {
+        await mkdir(this.eventsDir, { recursive: true });
+        const filePath = join(this.eventsDir, filename);
+        await writeFile(filePath, JSON.stringify(payload) + "\n", "utf-8");
+        const fileStat = await stat(filePath);
+        return { path: filePath, size: fileStat.size };
+    }
+}
+export function createEventTool(eventStore) {
+    let eventContext = null;
+    const tool = {
+        name: "event",
+        label: "event",
+        description: "Schedule an immediate, one-shot, or periodic event for the current conversation. Write text as a self-contained task with any needed context, tone, or constraints because events do not inherit normal conversation history. This automatically writes to the correct events directory and fills the current platform, conversation, conversation kind, and requester userId.",
+        parameters: eventSchema,
+        execute: async (_toolCallId, params, signal) => {
+            if (signal?.aborted) {
+                throw new Error("Operation aborted");
+            }
+            if (!eventContext) {
+                throw new Error("Event context not configured");
+            }
+            const payload = buildEventPayload(params, eventContext);
+            const prefix = sanitizeFileSegment(params.filenamePrefix || payload.type || "event");
+            const filename = `${prefix}-${Date.now()}.json`;
+            log.logInfo(`Writing event file via control plane store: ${filename} (type=${payload.type}, platform=${payload.platform}, conversation=${payload.conversationId})`);
+            try {
+                const result = await eventStore.write(filename, payload);
+                log.logInfo(`Wrote event file via control plane store: ${result.path} (${result.size} bytes)`);
+            }
+            catch (err) {
+                log.logWarning(`Failed to write event file via control plane store: ${filename}`, String(err));
+                throw err;
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: payload.type === "periodic"
+                            ? `Scheduled periodic event ${filename} for ${payload.platform}/${payload.conversationId} (${payload.schedule} ${payload.timezone})`
+                            : payload.type === "one-shot"
+                                ? `Scheduled one-shot event ${filename} for ${payload.platform}/${payload.conversationId} at ${payload.at}`
+                                : `Queued immediate event ${filename} for ${payload.platform}/${payload.conversationId}`,
+                    },
+                ],
+                details: undefined,
+            };
+        },
+    };
+    return {
+        tool,
+        setEventContext: (context) => {
+            eventContext = context;
+        },
+    };
+}
+function buildEventPayload(params, context) {
+    const base = {
+        platform: context.platform,
+        conversationId: context.conversationId,
+        conversationKind: context.conversationKind,
+        userId: context.userId,
+        text: params.text,
+    };
+    if (params.type === "immediate") {
+        return {
+            ...base,
+            type: "immediate",
+        };
+    }
+    if (params.type === "one-shot") {
+        if (!params.at) {
+            throw new Error("`at` is required for one-shot events");
+        }
+        const atTime = new Date(params.at).getTime();
+        if (Number.isNaN(atTime)) {
+            throw new Error("`at` must be a valid ISO 8601 timestamp with UTC offset");
+        }
+        if (atTime <= Date.now()) {
+            throw new Error(`\`at\` must be in the future; got ${params.at} (now=${new Date().toISOString()}). Check the timezone offset.`);
+        }
+        // No sessionKey or threadTs: reminders should fire as top-level messages, not buried in old threads
+        return { ...base, type: "one-shot", at: params.at };
+    }
+    if (!params.schedule) {
+        throw new Error("`schedule` is required for periodic events");
+    }
+    if (!params.timezone) {
+        throw new Error("`timezone` is required for periodic events");
+    }
+    return {
+        ...base,
+        type: "periodic",
+        schedule: params.schedule,
+        timezone: params.timezone,
+    };
+}
+function sanitizeFileSegment(value) {
+    const sanitized = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return sanitized || "event";
+}
+//# sourceMappingURL=event.js.map

package/dist/tools/event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../../src/tools/event.ts"],"names":[],"mappings":"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","sourcesContent":["import { mkdir, stat, writeFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport type { AgentTool } from \"@earendil-works/pi-agent-core\";\nimport { Type } from \"@sinclair/typebox\";\nimport * as log from \"../log.js\";\n\nconst eventSchema = Type.Object({\n  label: Type.String({\n    description: \"Brief description of the event you're scheduling (shown to user)\",\n  }),\n  type: Type.Union([Type.Literal(\"immediate\"), Type.Literal(\"one-shot\"), Type.Literal(\"periodic\")]),\n  text: Type.String({\n    description:\n      \"A self-contained task for the future run. Include the necessary context, tone, and constraints in the text itself because events do not inherit normal conversation history.\",\n  }),\n  at: Type.Optional(\n    Type.String({\n      description: \"ISO 8601 timestamp with offset, required for one-shot events\",\n    }),\n  ),\n  schedule: Type.Optional(\n    Type.String({\n      description: \"Cron schedule, required for periodic events\",\n    }),\n  ),\n  timezone: Type.Optional(\n    Type.String({\n      description: \"IANA timezone, required for periodic events\",\n    }),\n  ),\n  filenamePrefix: Type.Optional(\n    Type.String({\n      description: \"Optional filename prefix for the event file\",\n    }),\n  ),\n});\n\ninterface EventToolContext {\n  platform: string;\n  conversationId: string;\n  conversationKind: \"direct\" | \"shared\";\n  userId: string;\n}\n\ntype EventToolParams = {\n  label: string;\n  type: \"immediate\" | \"one-shot\" | \"periodic\";\n  text: string;\n  at?: string;\n  schedule?: string;\n  timezone?: string;\n  filenamePrefix?: string;\n};\n\nexport type EventPayload =\n  | {\n      type: \"immediate\";\n      platform: string;\n      conversationId: string;\n      conversationKind: \"direct\" | \"shared\";\n      userId: string;\n      text: string;\n    }\n  | {\n      type: \"one-shot\";\n      platform: string;\n      conversationId: string;\n      conversationKind: \"direct\" | \"shared\";\n      userId: string;\n      text: string;\n      at: string;\n    }\n  | {\n      type: \"periodic\";\n      platform: string;\n      conversationId: string;\n      conversationKind: \"direct\" | \"shared\";\n      userId: string;\n      text: string;\n      schedule: string;\n      timezone: string;\n    };\n\nexport interface EventStore {\n  write(filename: string, payload: EventPayload): Promise<{ path: string; size: number }>;\n}\n\nexport class HostEventStore implements EventStore {\n  constructor(private readonly eventsDir: string) {}\n\n  static fromWorkspaceDir(workspaceDir: string): HostEventStore {\n    return new HostEventStore(join(workspaceDir, \"events\"));\n  }\n\n  async write(filename: string, payload: EventPayload): Promise<{ path: string; size: number }> {\n    await mkdir(this.eventsDir, { recursive: true });\n    const filePath = join(this.eventsDir, filename);\n    await writeFile(filePath, JSON.stringify(payload) + \"\\n\", \"utf-8\");\n    const fileStat = await stat(filePath);\n    return { path: filePath, size: fileStat.size };\n  }\n}\n\nexport function createEventTool(eventStore: EventStore): {\n  tool: AgentTool<typeof eventSchema>;\n  setEventContext: (context: EventToolContext) => void;\n} {\n  let eventContext: EventToolContext | null = null;\n\n  const tool: AgentTool<typeof eventSchema> = {\n    name: \"event\",\n    label: \"event\",\n    description:\n      \"Schedule an immediate, one-shot, or periodic event for the current conversation. Write text as a self-contained task with any needed context, tone, or constraints because events do not inherit normal conversation history. This automatically writes to the correct events directory and fills the current platform, conversation, conversation kind, and requester userId.\",\n    parameters: eventSchema,\n    execute: async (_toolCallId: string, params: EventToolParams, signal?: AbortSignal) => {\n      if (signal?.aborted) {\n        throw new Error(\"Operation aborted\");\n      }\n\n      if (!eventContext) {\n        throw new Error(\"Event context not configured\");\n      }\n\n      const payload = buildEventPayload(params, eventContext);\n      const prefix = sanitizeFileSegment(params.filenamePrefix || payload.type || \"event\");\n      const filename = `${prefix}-${Date.now()}.json`;\n\n      log.logInfo(\n        `Writing event file via control plane store: ${filename} (type=${payload.type}, platform=${payload.platform}, conversation=${payload.conversationId})`,\n      );\n\n      try {\n        const result = await eventStore.write(filename, payload);\n        log.logInfo(\n          `Wrote event file via control plane store: ${result.path} (${result.size} bytes)`,\n        );\n      } catch (err) {\n        log.logWarning(\n          `Failed to write event file via control plane store: ${filename}`,\n          String(err),\n        );\n        throw err;\n      }\n\n      return {\n        content: [\n          {\n            type: \"text\",\n            text:\n              payload.type === \"periodic\"\n                ? `Scheduled periodic event ${filename} for ${payload.platform}/${payload.conversationId} (${payload.schedule} ${payload.timezone})`\n                : payload.type === \"one-shot\"\n                  ? `Scheduled one-shot event ${filename} for ${payload.platform}/${payload.conversationId} at ${payload.at}`\n                  : `Queued immediate event ${filename} for ${payload.platform}/${payload.conversationId}`,\n          },\n        ],\n        details: undefined,\n      };\n    },\n  };\n\n  return {\n    tool,\n    setEventContext: (context: EventToolContext) => {\n      eventContext = context;\n    },\n  };\n}\n\nfunction buildEventPayload(params: EventToolParams, context: EventToolContext): EventPayload {\n  const base = {\n    platform: context.platform,\n    conversationId: context.conversationId,\n    conversationKind: context.conversationKind,\n    userId: context.userId,\n    text: params.text,\n  };\n\n  if (params.type === \"immediate\") {\n    return {\n      ...base,\n      type: \"immediate\",\n    };\n  }\n\n  if (params.type === \"one-shot\") {\n    if (!params.at) {\n      throw new Error(\"`at` is required for one-shot events\");\n    }\n\n    const atTime = new Date(params.at).getTime();\n    if (Number.isNaN(atTime)) {\n      throw new Error(\"`at` must be a valid ISO 8601 timestamp with UTC offset\");\n    }\n    if (atTime <= Date.now()) {\n      throw new Error(\n        `\\`at\\` must be in the future; got ${params.at} (now=${new Date().toISOString()}). Check the timezone offset.`,\n      );\n    }\n\n    // No sessionKey or threadTs: reminders should fire as top-level messages, not buried in old threads\n    return { ...base, type: \"one-shot\", at: params.at };\n  }\n\n  if (!params.schedule) {\n    throw new Error(\"`schedule` is required for periodic events\");\n  }\n  if (!params.timezone) {\n    throw new Error(\"`timezone` is required for periodic events\");\n  }\n  return {\n    ...base,\n    type: \"periodic\",\n    schedule: params.schedule,\n    timezone: params.timezone,\n  };\n}\n\nfunction sanitizeFileSegment(value: string): string {\n  const sanitized = value\n    .trim()\n    .toLowerCase()\n    .replace(/[^a-z0-9._-]+/g, \"-\")\n    .replace(/^-+|-+$/g, \"\");\n  return sanitized || \"event\";\n}\n"]}

package/dist/tools/index.d.ts

@@ -0,0 +1,14 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { TSchema } from "@sinclair/typebox";
+import type { Executor } from "../sandbox/index.js";
+export declare function createMikanTools(executor: Executor, workspaceDir: string): {
+    tools: AgentTool<TSchema>[];
+    setUploadFunction: (fn: (filePath: string, title?: string) => Promise<void>) => void;
+    setEventContext: (context: {
+        platform: string;
+        conversationId: string;
+        conversationKind: "direct" | "shared";
+        userId: string;
+    }) => void;
+};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAOpD,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,MAAM,GACnB;IACD,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;IAC5B,iBAAiB,EAAE,CAAC,EAAE,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;IACrF,eAAe,EAAE,CAAC,OAAO,EAAE;QACzB,QAAQ,EAAE,MAAM,CAAC;QACjB,cAAc,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,QAAQ,GAAG,QAAQ,CAAC;QACtC,MAAM,EAAE,MAAM,CAAC;KAChB,KAAK,IAAI,CAAC;CACZ,CAiBA","sourcesContent":["import type { AgentTool } from \"@earendil-works/pi-agent-core\";\nimport type { TSchema } from \"@sinclair/typebox\";\nimport { createAttachTool } from \"../adapters/slack/tools/attach.js\";\nimport type { Executor } from \"../sandbox/index.js\";\nimport { createBashTool } from \"./bash.js\";\nimport { createEditTool } from \"./edit.js\";\nimport { createEventTool, HostEventStore } from \"./event.js\";\nimport { createReadTool } from \"./read.js\";\nimport { createWriteTool } from \"./write.js\";\n\nexport function createMikanTools(\n  executor: Executor,\n  workspaceDir: string,\n): {\n  tools: AgentTool<TSchema>[];\n  setUploadFunction: (fn: (filePath: string, title?: string) => Promise<void>) => void;\n  setEventContext: (context: {\n    platform: string;\n    conversationId: string;\n    conversationKind: \"direct\" | \"shared\";\n    userId: string;\n  }) => void;\n} {\n  const { tool: attachTool, setUploadFunction } = createAttachTool();\n  const { tool: eventTool, setEventContext } = createEventTool(\n    HostEventStore.fromWorkspaceDir(workspaceDir),\n  );\n  return {\n    tools: [\n      createReadTool(executor),\n      createBashTool(executor),\n      createEditTool(executor),\n      createWriteTool(executor),\n      eventTool,\n      attachTool,\n    ],\n    setUploadFunction,\n    setEventContext,\n  };\n}\n"]}

package/dist/tools/index.js

@@ -0,0 +1,23 @@
+import { createAttachTool } from "../adapters/slack/tools/attach.js";
+import { createBashTool } from "./bash.js";
+import { createEditTool } from "./edit.js";
+import { createEventTool, HostEventStore } from "./event.js";
+import { createReadTool } from "./read.js";
+import { createWriteTool } from "./write.js";
+export function createMikanTools(executor, workspaceDir) {
+    const { tool: attachTool, setUploadFunction } = createAttachTool();
+    const { tool: eventTool, setEventContext } = createEventTool(HostEventStore.fromWorkspaceDir(workspaceDir));
+    return {
+        tools: [
+            createReadTool(executor),
+            createBashTool(executor),
+            createEditTool(executor),
+            createWriteTool(executor),
+            eventTool,
+            attachTool,
+        ],
+        setUploadFunction,
+        setEventContext,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAErE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,UAAU,gBAAgB,CAC9B,QAAkB,EAClB,YAAoB;IAWpB,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,iBAAiB,EAAE,GAAG,gBAAgB,EAAE,CAAC;IACnE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,eAAe,EAAE,GAAG,eAAe,CAC1D,cAAc,CAAC,gBAAgB,CAAC,YAAY,CAAC,CAC9C,CAAC;IACF,OAAO;QACL,KAAK,EAAE;YACL,cAAc,CAAC,QAAQ,CAAC;YACxB,cAAc,CAAC,QAAQ,CAAC;YACxB,cAAc,CAAC,QAAQ,CAAC;YACxB,eAAe,CAAC,QAAQ,CAAC;YACzB,SAAS;YACT,UAAU;SACX;QACD,iBAAiB;QACjB,eAAe;KAChB,CAAC;AACJ,CAAC","sourcesContent":["import type { AgentTool } from \"@earendil-works/pi-agent-core\";\nimport type { TSchema } from \"@sinclair/typebox\";\nimport { createAttachTool } from \"../adapters/slack/tools/attach.js\";\nimport type { Executor } from \"../sandbox/index.js\";\nimport { createBashTool } from \"./bash.js\";\nimport { createEditTool } from \"./edit.js\";\nimport { createEventTool, HostEventStore } from \"./event.js\";\nimport { createReadTool } from \"./read.js\";\nimport { createWriteTool } from \"./write.js\";\n\nexport function createMikanTools(\n  executor: Executor,\n  workspaceDir: string,\n): {\n  tools: AgentTool<TSchema>[];\n  setUploadFunction: (fn: (filePath: string, title?: string) => Promise<void>) => void;\n  setEventContext: (context: {\n    platform: string;\n    conversationId: string;\n    conversationKind: \"direct\" | \"shared\";\n    userId: string;\n  }) => void;\n} {\n  const { tool: attachTool, setUploadFunction } = createAttachTool();\n  const { tool: eventTool, setEventContext } = createEventTool(\n    HostEventStore.fromWorkspaceDir(workspaceDir),\n  );\n  return {\n    tools: [\n      createReadTool(executor),\n      createBashTool(executor),\n      createEditTool(executor),\n      createWriteTool(executor),\n      eventTool,\n      attachTool,\n    ],\n    setUploadFunction,\n    setEventContext,\n  };\n}\n"]}

package/dist/tools/read.d.ts

@@ -0,0 +1,11 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { Executor } from "../sandbox/index.js";
+declare const readSchema: import("@sinclair/typebox").TObject<{
+    label: import("@sinclair/typebox").TString;
+    path: import("@sinclair/typebox").TString;
+    offset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export declare function createReadTool(executor: Executor): AgentTool<typeof readSchema>;
+export {};
+//# sourceMappingURL=read.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/tools/read.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAI/D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AA4BpD,QAAA,MAAM,UAAU;;;;;EASd,CAAC;AAMH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CA0H/E","sourcesContent":["import type { AgentTool } from \"@earendil-works/pi-agent-core\";\nimport type { ImageContent, TextContent } from \"@earendil-works/pi-ai\";\nimport { Type } from \"@sinclair/typebox\";\nimport { extname } from \"path\";\nimport type { Executor } from \"../sandbox/index.js\";\nimport {\n  DEFAULT_MAX_BYTES,\n  DEFAULT_MAX_LINES,\n  formatSize,\n  type TruncationResult,\n  truncateHead,\n} from \"./truncate.js\";\n\n/**\n * Map of file extensions to MIME types for common image formats\n */\nconst IMAGE_MIME_TYPES: Record<string, string> = {\n  \".jpg\": \"image/jpeg\",\n  \".jpeg\": \"image/jpeg\",\n  \".png\": \"image/png\",\n  \".gif\": \"image/gif\",\n  \".webp\": \"image/webp\",\n};\n\n/**\n * Check if a file is an image based on its extension\n */\nfunction isImageFile(filePath: string): string | null {\n  const ext = extname(filePath).toLowerCase();\n  return IMAGE_MIME_TYPES[ext] || null;\n}\n\nconst readSchema = Type.Object({\n  label: Type.String({\n    description: \"Brief description of what you're reading and why (shown to user)\",\n  }),\n  path: Type.String({ description: \"Path to the file to read (relative or absolute)\" }),\n  offset: Type.Optional(\n    Type.Number({ description: \"Line number to start reading from (1-indexed)\" }),\n  ),\n  limit: Type.Optional(Type.Number({ description: \"Maximum number of lines to read\" })),\n});\n\ninterface ReadToolDetails {\n  truncation?: TruncationResult;\n}\n\nexport function createReadTool(executor: Executor): AgentTool<typeof readSchema> {\n  return {\n    name: \"read\",\n    label: \"read\",\n    description: `Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files.`,\n    parameters: readSchema,\n    execute: async (\n      _toolCallId: string,\n      { path, offset, limit }: { label: string; path: string; offset?: number; limit?: number },\n      signal?: AbortSignal,\n    ): Promise<{\n      content: (TextContent | ImageContent)[];\n      details: ReadToolDetails | undefined;\n    }> => {\n      const mimeType = isImageFile(path);\n\n      if (mimeType) {\n        // Read as image (binary) - use base64\n        const result = await executor.exec(`base64 < ${shellEscape(path)}`, { signal });\n        if (result.code !== 0) {\n          throw new Error(result.stderr || `Failed to read file: ${path}`);\n        }\n        const base64 = result.stdout.replace(/\\s/g, \"\"); // Remove whitespace from base64\n\n        return {\n          content: [\n            { type: \"text\", text: `Read image file [${mimeType}]` },\n            { type: \"image\", data: base64, mimeType },\n          ],\n          details: undefined,\n        };\n      }\n\n      // Get total line count first\n      const countResult = await executor.exec(`wc -l < ${shellEscape(path)}`, { signal });\n      if (countResult.code !== 0) {\n        throw new Error(countResult.stderr || `Failed to read file: ${path}`);\n      }\n      const totalFileLines = Number.parseInt(countResult.stdout.trim(), 10) + 1; // wc -l counts newlines, not lines\n\n      // Apply offset if specified (1-indexed)\n      const startLine = offset ? Math.max(1, offset) : 1;\n      const startLineDisplay = startLine;\n\n      // Check if offset is out of bounds\n      if (startLine > totalFileLines) {\n        throw new Error(`Offset ${offset} is beyond end of file (${totalFileLines} lines total)`);\n      }\n\n      // Read content with offset\n      let cmd: string;\n      if (startLine === 1) {\n        cmd = `cat ${shellEscape(path)}`;\n      } else {\n        cmd = `tail -n +${startLine} ${shellEscape(path)}`;\n      }\n\n      const result = await executor.exec(cmd, { signal });\n      if (result.code !== 0) {\n        throw new Error(result.stderr || `Failed to read file: ${path}`);\n      }\n\n      let selectedContent = result.stdout;\n      let userLimitedLines: number | undefined;\n\n      // Apply user limit if specified\n      if (limit !== undefined) {\n        const lines = selectedContent.split(\"\\n\");\n        const endLine = Math.min(limit, lines.length);\n        selectedContent = lines.slice(0, endLine).join(\"\\n\");\n        userLimitedLines = endLine;\n      }\n\n      // Apply truncation (respects both line and byte limits)\n      const truncation = truncateHead(selectedContent);\n\n      let outputText: string;\n      let details: ReadToolDetails | undefined;\n\n      if (truncation.firstLineExceedsLimit) {\n        // First line at offset exceeds 50KB - tell model to use bash\n        const firstLineSize = formatSize(\n          Buffer.byteLength(selectedContent.split(\"\\n\")[0], \"utf-8\"),\n        );\n        outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(DEFAULT_MAX_BYTES)} limit. Use bash: sed -n '${startLineDisplay}p' ${path} | head -c ${DEFAULT_MAX_BYTES}]`;\n        details = { truncation };\n      } else if (truncation.truncated) {\n        // Truncation occurred - build actionable notice\n        const endLineDisplay = startLineDisplay + truncation.outputLines - 1;\n        const nextOffset = endLineDisplay + 1;\n\n        outputText = truncation.content;\n\n        if (truncation.truncatedBy === \"lines\") {\n          outputText += `\\n\\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue]`;\n        } else {\n          outputText += `\\n\\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Use offset=${nextOffset} to continue]`;\n        }\n        details = { truncation };\n      } else if (userLimitedLines !== undefined) {\n        // User specified limit, check if there's more content\n        const linesFromStart = startLine - 1 + userLimitedLines;\n        if (linesFromStart < totalFileLines) {\n          const remaining = totalFileLines - linesFromStart;\n          const nextOffset = startLine + userLimitedLines;\n\n          outputText = truncation.content;\n          outputText += `\\n\\n[${remaining} more lines in file. Use offset=${nextOffset} to continue]`;\n        } else {\n          outputText = truncation.content;\n        }\n      } else {\n        // No truncation, no user limit exceeded\n        outputText = truncation.content;\n      }\n\n      return {\n        content: [{ type: \"text\", text: outputText }],\n        details,\n      };\n    },\n  };\n}\n\nfunction shellEscape(s: string): string {\n  return `'${s.replace(/'/g, \"'\\\\''\")}'`;\n}\n"]}

package/dist/tools/read.js

@@ -0,0 +1,136 @@
+import { Type } from "@sinclair/typebox";
+import { extname } from "path";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead, } from "./truncate.js";
+/**
+ * Map of file extensions to MIME types for common image formats
+ */
+const IMAGE_MIME_TYPES = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
+/**
+ * Check if a file is an image based on its extension
+ */
+function isImageFile(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    return IMAGE_MIME_TYPES[ext] || null;
+}
+const readSchema = Type.Object({
+    label: Type.String({
+        description: "Brief description of what you're reading and why (shown to user)",
+    }),
+    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" })),
+});
+export function createReadTool(executor) {
+    return {
+        name: "read",
+        label: "read",
+        description: `Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files.`,
+        parameters: readSchema,
+        execute: async (_toolCallId, { path, offset, limit }, signal) => {
+            const mimeType = isImageFile(path);
+            if (mimeType) {
+                // Read as image (binary) - use base64
+                const result = await executor.exec(`base64 < ${shellEscape(path)}`, { signal });
+                if (result.code !== 0) {
+                    throw new Error(result.stderr || `Failed to read file: ${path}`);
+                }
+                const base64 = result.stdout.replace(/\s/g, ""); // Remove whitespace from base64
+                return {
+                    content: [
+                        { type: "text", text: `Read image file [${mimeType}]` },
+                        { type: "image", data: base64, mimeType },
+                    ],
+                    details: undefined,
+                };
+            }
+            // Get total line count first
+            const countResult = await executor.exec(`wc -l < ${shellEscape(path)}`, { signal });
+            if (countResult.code !== 0) {
+                throw new Error(countResult.stderr || `Failed to read file: ${path}`);
+            }
+            const totalFileLines = Number.parseInt(countResult.stdout.trim(), 10) + 1; // wc -l counts newlines, not lines
+            // Apply offset if specified (1-indexed)
+            const startLine = offset ? Math.max(1, offset) : 1;
+            const startLineDisplay = startLine;
+            // Check if offset is out of bounds
+            if (startLine > totalFileLines) {
+                throw new Error(`Offset ${offset} is beyond end of file (${totalFileLines} lines total)`);
+            }
+            // Read content with offset
+            let cmd;
+            if (startLine === 1) {
+                cmd = `cat ${shellEscape(path)}`;
+            }
+            else {
+                cmd = `tail -n +${startLine} ${shellEscape(path)}`;
+            }
+            const result = await executor.exec(cmd, { signal });
+            if (result.code !== 0) {
+                throw new Error(result.stderr || `Failed to read file: ${path}`);
+            }
+            let selectedContent = result.stdout;
+            let userLimitedLines;
+            // Apply user limit if specified
+            if (limit !== undefined) {
+                const lines = selectedContent.split("\n");
+                const endLine = Math.min(limit, lines.length);
+                selectedContent = lines.slice(0, endLine).join("\n");
+                userLimitedLines = endLine;
+            }
+            // Apply truncation (respects both line and byte limits)
+            const truncation = truncateHead(selectedContent);
+            let outputText;
+            let details;
+            if (truncation.firstLineExceedsLimit) {
+                // First line at offset exceeds 50KB - tell model to use bash
+                const firstLineSize = formatSize(Buffer.byteLength(selectedContent.split("\n")[0], "utf-8"));
+                outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(DEFAULT_MAX_BYTES)} limit. Use bash: sed -n '${startLineDisplay}p' ${path} | head -c ${DEFAULT_MAX_BYTES}]`;
+                details = { truncation };
+            }
+            else if (truncation.truncated) {
+                // Truncation occurred - build actionable notice
+                const endLineDisplay = startLineDisplay + truncation.outputLines - 1;
+                const nextOffset = endLineDisplay + 1;
+                outputText = truncation.content;
+                if (truncation.truncatedBy === "lines") {
+                    outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue]`;
+                }
+                else {
+                    outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Use offset=${nextOffset} to continue]`;
+                }
+                details = { truncation };
+            }
+            else if (userLimitedLines !== undefined) {
+                // User specified limit, check if there's more content
+                const linesFromStart = startLine - 1 + userLimitedLines;
+                if (linesFromStart < totalFileLines) {
+                    const remaining = totalFileLines - linesFromStart;
+                    const nextOffset = startLine + userLimitedLines;
+                    outputText = truncation.content;
+                    outputText += `\n\n[${remaining} more lines in file. Use offset=${nextOffset} to continue]`;
+                }
+                else {
+                    outputText = truncation.content;
+                }
+            }
+            else {
+                // No truncation, no user limit exceeded
+                outputText = truncation.content;
+            }
+            return {
+                content: [{ type: "text", text: outputText }],
+                details,
+            };
+        },
+    };
+}
+function shellEscape(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+//# 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 { AgentTool } from \"@earendil-works/pi-agent-core\";\nimport type { ImageContent, TextContent } from \"@earendil-works/pi-ai\";\nimport { Type } from \"@sinclair/typebox\";\nimport { extname } from \"path\";\nimport type { Executor } from \"../sandbox/index.js\";\nimport {\n  DEFAULT_MAX_BYTES,\n  DEFAULT_MAX_LINES,\n  formatSize,\n  type TruncationResult,\n  truncateHead,\n} from \"./truncate.js\";\n\n/**\n * Map of file extensions to MIME types for common image formats\n */\nconst IMAGE_MIME_TYPES: Record<string, string> = {\n  \".jpg\": \"image/jpeg\",\n  \".jpeg\": \"image/jpeg\",\n  \".png\": \"image/png\",\n  \".gif\": \"image/gif\",\n  \".webp\": \"image/webp\",\n};\n\n/**\n * Check if a file is an image based on its extension\n */\nfunction isImageFile(filePath: string): string | null {\n  const ext = extname(filePath).toLowerCase();\n  return IMAGE_MIME_TYPES[ext] || null;\n}\n\nconst readSchema = Type.Object({\n  label: Type.String({\n    description: \"Brief description of what you're reading and why (shown to user)\",\n  }),\n  path: Type.String({ description: \"Path to the file to read (relative or absolute)\" }),\n  offset: Type.Optional(\n    Type.Number({ description: \"Line number to start reading from (1-indexed)\" }),\n  ),\n  limit: Type.Optional(Type.Number({ description: \"Maximum number of lines to read\" })),\n});\n\ninterface ReadToolDetails {\n  truncation?: TruncationResult;\n}\n\nexport function createReadTool(executor: Executor): AgentTool<typeof readSchema> {\n  return {\n    name: \"read\",\n    label: \"read\",\n    description: `Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files.`,\n    parameters: readSchema,\n    execute: async (\n      _toolCallId: string,\n      { path, offset, limit }: { label: string; path: string; offset?: number; limit?: number },\n      signal?: AbortSignal,\n    ): Promise<{\n      content: (TextContent | ImageContent)[];\n      details: ReadToolDetails | undefined;\n    }> => {\n      const mimeType = isImageFile(path);\n\n      if (mimeType) {\n        // Read as image (binary) - use base64\n        const result = await executor.exec(`base64 < ${shellEscape(path)}`, { signal });\n        if (result.code !== 0) {\n          throw new Error(result.stderr || `Failed to read file: ${path}`);\n        }\n        const base64 = result.stdout.replace(/\\s/g, \"\"); // Remove whitespace from base64\n\n        return {\n          content: [\n            { type: \"text\", text: `Read image file [${mimeType}]` },\n            { type: \"image\", data: base64, mimeType },\n          ],\n          details: undefined,\n        };\n      }\n\n      // Get total line count first\n      const countResult = await executor.exec(`wc -l < ${shellEscape(path)}`, { signal });\n      if (countResult.code !== 0) {\n        throw new Error(countResult.stderr || `Failed to read file: ${path}`);\n      }\n      const totalFileLines = Number.parseInt(countResult.stdout.trim(), 10) + 1; // wc -l counts newlines, not lines\n\n      // Apply offset if specified (1-indexed)\n      const startLine = offset ? Math.max(1, offset) : 1;\n      const startLineDisplay = startLine;\n\n      // Check if offset is out of bounds\n      if (startLine > totalFileLines) {\n        throw new Error(`Offset ${offset} is beyond end of file (${totalFileLines} lines total)`);\n      }\n\n      // Read content with offset\n      let cmd: string;\n      if (startLine === 1) {\n        cmd = `cat ${shellEscape(path)}`;\n      } else {\n        cmd = `tail -n +${startLine} ${shellEscape(path)}`;\n      }\n\n      const result = await executor.exec(cmd, { signal });\n      if (result.code !== 0) {\n        throw new Error(result.stderr || `Failed to read file: ${path}`);\n      }\n\n      let selectedContent = result.stdout;\n      let userLimitedLines: number | undefined;\n\n      // Apply user limit if specified\n      if (limit !== undefined) {\n        const lines = selectedContent.split(\"\\n\");\n        const endLine = Math.min(limit, lines.length);\n        selectedContent = lines.slice(0, endLine).join(\"\\n\");\n        userLimitedLines = endLine;\n      }\n\n      // Apply truncation (respects both line and byte limits)\n      const truncation = truncateHead(selectedContent);\n\n      let outputText: string;\n      let details: ReadToolDetails | undefined;\n\n      if (truncation.firstLineExceedsLimit) {\n        // First line at offset exceeds 50KB - tell model to use bash\n        const firstLineSize = formatSize(\n          Buffer.byteLength(selectedContent.split(\"\\n\")[0], \"utf-8\"),\n        );\n        outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(DEFAULT_MAX_BYTES)} limit. Use bash: sed -n '${startLineDisplay}p' ${path} | head -c ${DEFAULT_MAX_BYTES}]`;\n        details = { truncation };\n      } else if (truncation.truncated) {\n        // Truncation occurred - build actionable notice\n        const endLineDisplay = startLineDisplay + truncation.outputLines - 1;\n        const nextOffset = endLineDisplay + 1;\n\n        outputText = truncation.content;\n\n        if (truncation.truncatedBy === \"lines\") {\n          outputText += `\\n\\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue]`;\n        } else {\n          outputText += `\\n\\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Use offset=${nextOffset} to continue]`;\n        }\n        details = { truncation };\n      } else if (userLimitedLines !== undefined) {\n        // User specified limit, check if there's more content\n        const linesFromStart = startLine - 1 + userLimitedLines;\n        if (linesFromStart < totalFileLines) {\n          const remaining = totalFileLines - linesFromStart;\n          const nextOffset = startLine + userLimitedLines;\n\n          outputText = truncation.content;\n          outputText += `\\n\\n[${remaining} more lines in file. Use offset=${nextOffset} to continue]`;\n        } else {\n          outputText = truncation.content;\n        }\n      } else {\n        // No truncation, no user limit exceeded\n        outputText = truncation.content;\n      }\n\n      return {\n        content: [{ type: \"text\", text: outputText }],\n        details,\n      };\n    },\n  };\n}\n\nfunction shellEscape(s: string): string {\n  return `'${s.replace(/'/g, \"'\\\\''\")}'`;\n}\n"]}

package/dist/tools/truncate.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 (except bash tail truncation edge case).
+ */
+export declare const DEFAULT_MAX_LINES = 2000;
+export declare const DEFAULT_MAX_BYTES: number;
+export interface TruncationResult {
+    /** The truncated content */
+    content: string;
+    /** Whether truncation occurred */
+    truncated: boolean;
+    /** Which limit was hit: "lines", "bytes", or null if not truncated */
+    truncatedBy: "lines" | "bytes" | null;
+    /** Total number of lines in the original content */
+    totalLines: number;
+    /** Total number of bytes in the original content */
+    totalBytes: number;
+    /** Number of complete lines in the truncated output */
+    outputLines: number;
+    /** Number of bytes in the truncated output */
+    outputBytes: number;
+    /** Whether the last line was partially truncated (only for tail truncation edge case) */
+    lastLinePartial: boolean;
+    /** Whether the first line exceeded the byte limit (for head truncation) */
+    firstLineExceedsLimit: boolean;
+}
+export interface TruncationOptions {
+    /** Maximum number of lines (default: 2000) */
+    maxLines?: number;
+    /** Maximum number of bytes (default: 50KB) */
+    maxBytes?: number;
+}
+/**
+ * Format bytes as human-readable size.
+ */
+export declare function formatSize(bytes: number): string;
+/**
+ * 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 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;
+//# sourceMappingURL=truncate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"truncate.d.ts","sourceRoot":"","sources":["../../src/tools/truncate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AACtC,eAAO,MAAM,iBAAiB,QAAY,CAAC;AAE3C,MAAM,WAAW,gBAAgB;IAC/B,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;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;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,CA4E/F;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAqE/F","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 (except bash tail truncation edge case).\n */\n\nexport const DEFAULT_MAX_LINES = 2000;\nexport const DEFAULT_MAX_BYTES = 50 * 1024; // 50KB\n\nexport interface TruncationResult {\n  /** The truncated content */\n  content: string;\n  /** Whether truncation occurred */\n  truncated: boolean;\n  /** Which limit was hit: \"lines\", \"bytes\", or null if not truncated */\n  truncatedBy: \"lines\" | \"bytes\" | null;\n  /** Total number of lines in the original content */\n  totalLines: number;\n  /** Total number of bytes in the original content */\n  totalBytes: number;\n  /** Number of complete lines in the truncated output */\n  outputLines: number;\n  /** Number of bytes in the truncated output */\n  outputBytes: number;\n  /** Whether the last line was partially truncated (only for tail truncation edge case) */\n  lastLinePartial: boolean;\n  /** Whether the first line exceeded the byte limit (for head truncation) */\n  firstLineExceedsLimit: boolean;\n}\n\nexport interface TruncationOptions {\n  /** Maximum number of lines (default: 2000) */\n  maxLines?: number;\n  /** Maximum number of bytes (default: 50KB) */\n  maxBytes?: number;\n}\n\n/**\n * Format bytes as human-readable size.\n */\nexport function formatSize(bytes: number): string {\n  if (bytes < 1024) {\n    return `${bytes}B`;\n  } else if (bytes < 1024 * 1024) {\n    return `${(bytes / 1024).toFixed(1)}KB`;\n  } else {\n    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;\n  }\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  const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;\n  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;\n\n  const totalBytes = Buffer.byteLength(content, \"utf-8\");\n  const lines = content.split(\"\\n\");\n  const totalLines = lines.length;\n\n  // Check if no truncation needed\n  if (totalLines <= maxLines && totalBytes <= maxBytes) {\n    return {\n      content,\n      truncated: false,\n      truncatedBy: null,\n      totalLines,\n      totalBytes,\n      outputLines: totalLines,\n      outputBytes: totalBytes,\n      lastLinePartial: false,\n      firstLineExceedsLimit: false,\n    };\n  }\n\n  // Check if first line alone exceeds byte limit\n  const firstLineBytes = Buffer.byteLength(lines[0], \"utf-8\");\n  if (firstLineBytes > maxBytes) {\n    return {\n      content: \"\",\n      truncated: true,\n      truncatedBy: \"bytes\",\n      totalLines,\n      totalBytes,\n      outputLines: 0,\n      outputBytes: 0,\n      lastLinePartial: false,\n      firstLineExceedsLimit: true,\n    };\n  }\n\n  // Collect complete lines that fit\n  const outputLinesArr: string[] = [];\n  let outputBytesCount = 0;\n  let truncatedBy: \"lines\" | \"bytes\" = \"lines\";\n\n  for (let i = 0; i < lines.length && i < maxLines; i++) {\n    const line = lines[i];\n    const lineBytes = Buffer.byteLength(line, \"utf-8\") + (i > 0 ? 1 : 0); // +1 for newline\n\n    if (outputBytesCount + lineBytes > maxBytes) {\n      truncatedBy = \"bytes\";\n      break;\n    }\n\n    outputLinesArr.push(line);\n    outputBytesCount += lineBytes;\n  }\n\n  // If we exited due to line limit\n  if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {\n    truncatedBy = \"lines\";\n  }\n\n  const outputContent = outputLinesArr.join(\"\\n\");\n  const finalOutputBytes = Buffer.byteLength(outputContent, \"utf-8\");\n\n  return {\n    content: outputContent,\n    truncated: true,\n    truncatedBy,\n    totalLines,\n    totalBytes,\n    outputLines: outputLinesArr.length,\n    outputBytes: finalOutputBytes,\n    lastLinePartial: false,\n    firstLineExceedsLimit: false,\n  };\n}\n\n/**\n * Truncate content from the tail (keep last N lines/bytes).\n * Suitable for bash output where you want to see the end (errors, final results).\n *\n * May return partial first line if the last line of original content exceeds byte limit.\n */\nexport function truncateTail(content: string, options: TruncationOptions = {}): TruncationResult {\n  const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;\n  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;\n\n  const totalBytes = Buffer.byteLength(content, \"utf-8\");\n  const lines = content.split(\"\\n\");\n  const totalLines = lines.length;\n\n  // Check if no truncation needed\n  if (totalLines <= maxLines && totalBytes <= maxBytes) {\n    return {\n      content,\n      truncated: false,\n      truncatedBy: null,\n      totalLines,\n      totalBytes,\n      outputLines: totalLines,\n      outputBytes: totalBytes,\n      lastLinePartial: false,\n      firstLineExceedsLimit: false,\n    };\n  }\n\n  // Work backwards from the end\n  const outputLinesArr: string[] = [];\n  let outputBytesCount = 0;\n  let truncatedBy: \"lines\" | \"bytes\" = \"lines\";\n  let lastLinePartial = false;\n\n  for (let i = lines.length - 1; i >= 0 && outputLinesArr.length < maxLines; i--) {\n    const line = lines[i];\n    const lineBytes = Buffer.byteLength(line, \"utf-8\") + (outputLinesArr.length > 0 ? 1 : 0); // +1 for newline\n\n    if (outputBytesCount + lineBytes > maxBytes) {\n      truncatedBy = \"bytes\";\n      // Edge case: if we haven't added ANY lines yet and this line exceeds maxBytes,\n      // take the end of the line (partial)\n      if (outputLinesArr.length === 0) {\n        const truncatedLine = truncateStringToBytesFromEnd(line, maxBytes);\n        outputLinesArr.unshift(truncatedLine);\n        outputBytesCount = Buffer.byteLength(truncatedLine, \"utf-8\");\n        lastLinePartial = true;\n      }\n      break;\n    }\n\n    outputLinesArr.unshift(line);\n    outputBytesCount += lineBytes;\n  }\n\n  // If we exited due to line limit\n  if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {\n    truncatedBy = \"lines\";\n  }\n\n  const outputContent = outputLinesArr.join(\"\\n\");\n  const finalOutputBytes = Buffer.byteLength(outputContent, \"utf-8\");\n\n  return {\n    content: outputContent,\n    truncated: true,\n    truncatedBy,\n    totalLines,\n    totalBytes,\n    outputLines: outputLinesArr.length,\n    outputBytes: finalOutputBytes,\n    lastLinePartial,\n    firstLineExceedsLimit: false,\n  };\n}\n\n/**\n * Truncate a string to fit within a byte limit (from the end).\n * Handles multi-byte UTF-8 characters correctly.\n */\nfunction truncateStringToBytesFromEnd(str: string, maxBytes: number): string {\n  const buf = Buffer.from(str, \"utf-8\");\n  if (buf.length <= maxBytes) {\n    return str;\n  }\n\n  // Start from the end, skip maxBytes back\n  let start = buf.length - maxBytes;\n\n  // Find a valid UTF-8 boundary (start of a character)\n  while (start < buf.length && (buf[start] & 0xc0) === 0x80) {\n    start++;\n  }\n\n  return buf.slice(start).toString(\"utf-8\");\n}\n"]}