@ocis/myagent-cli 0.2.0

package/dist/tools/paths.js

@@ -0,0 +1,124 @@
+// ---------------------------------------------------------------------------
+// Workspace path confinement for client tools.
+//
+// Lexical containment alone is not enough: a symlink inside the workspace can
+// point outside it. Resolution therefore realpaths every existing prefix and
+// re-checks containment on the real location before allowing a read or write.
+// `allowOutside` (--allow-outside) skips the checks entirely.
+//
+// Threat model: this is a guardrail against the agent's own path choices
+// (accidental or prompt-injected escapes), NOT a sandbox against a hostile
+// local process — the check and the subsequent open() are separate steps, so
+// a concurrent writer can swap a symlink in between (TOCTOU), and local_shell
+// can reach anywhere by construction anyway. Hardening to fd-based operations
+// (O_NOFOLLOW) would only ever matter for multi-user machines running
+// untrusted code alongside the CLI, which is out of scope.
+// ---------------------------------------------------------------------------
+import { realpath } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { optionalString } from "./types.js";
+export class PathOutsideWorkspaceError extends Error {
+    constructor(input) {
+        super(`Path "${input}" is outside the workspace. Pass --allow-outside to permit it.`);
+        this.name = "PathOutsideWorkspaceError";
+    }
+}
+export function isInside(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+/** Realpath the deepest existing ancestor of `absolute` (null when none exists). */
+async function realpathDeepestExisting(absolute) {
+    let current = absolute;
+    for (;;) {
+        try {
+            return await realpath(current);
+        }
+        catch {
+            const parent = dirname(current);
+            if (parent === current)
+                return null;
+            current = parent;
+        }
+    }
+}
+/**
+ * True when the path (or a symlink along it) escapes the workspace. Lexical
+ * containment alone is not enough: a symlink inside the workspace can point
+ * outside it, so every existing prefix is realpath-checked too.
+ */
+export async function pathEscapesWorkspace(input, workspace) {
+    const root = resolve(workspace);
+    const absolute = isAbsolute(input) ? resolve(input) : resolve(root, input);
+    if (!isInside(root, absolute))
+        return true;
+    const realWorkspace = await realpathDeepestExisting(root) ?? root;
+    const segments = relative(root, absolute).split(/[\\/]+/).filter(Boolean);
+    let probe = root;
+    for (const segment of segments) {
+        probe = join(probe, segment);
+        const real = await realpathDeepestExisting(probe);
+        if (!real)
+            break;
+        if (!isInside(realWorkspace, real))
+            return true;
+    }
+    return false;
+}
+/**
+ * Resolve a tool-supplied path to an absolute path inside `workspace`.
+ * Throws PathOutsideWorkspaceError when the path (or a symlink along it)
+ * escapes the workspace and `allowOutside` is false.
+ */
+export async function resolveToolPath(input, opts) {
+    const workspace = resolve(opts.workspace);
+    const absolute = isAbsolute(input) ? resolve(input) : resolve(workspace, input);
+    if (opts.allowOutside)
+        return absolute;
+    if (await pathEscapesWorkspace(input, workspace))
+        throw new PathOutsideWorkspaceError(input);
+    return absolute;
+}
+/** Workspace-relative display path (falls back to the absolute path). */
+export function displayPath(workspace, absolute) {
+    const rel = relative(resolve(workspace), absolute);
+    return rel && !rel.startsWith("..") ? rel : absolute;
+}
+/** Client tools whose `path` argument addresses the filesystem. */
+const PATH_TOOLS = new Set(["local_read", "local_write", "local_edit", "local_ls", "local_grep", "local_find"]);
+/** Local-side path arguments of a call (empty = it cannot touch the local fs structurally). */
+function localPathArgs(name, args) {
+    if (name === "local_transfer_files") {
+        // get writes `to` locally, put reads `from` locally, list has no local
+        // side. get's `to` defaults to the workspace path made relative
+        // (transferGet's `from.slice(1)` after normalization) — mirror that
+        // default here or an implicit destination escaping the workspace would
+        // skip the always-ask signal (the runtime confinement still blocks it,
+        // but the user would never be consulted).
+        if (args.direction === "get") {
+            const to = optionalString(args, "to") ?? optionalString(args, "from")?.replace(/^\/+/, "");
+            return to ? [to] : [];
+        }
+        if (args.direction === "put") {
+            const from = optionalString(args, "from");
+            return from ? [from] : [];
+        }
+        return [];
+    }
+    if (!PATH_TOOLS.has(name))
+        return [];
+    const path = optionalString(args, "path");
+    return path ? [path] : [];
+}
+/**
+ * Whether a tool request should be treated as reaching outside the workspace
+ * (and therefore asked about even in AUTO mode). Path-less tools like shell
+ * cannot be judged statically and are left to the approval mode.
+ */
+export async function toolRequestOutsideWorkspace(name, args, workspace) {
+    for (const path of localPathArgs(name, args)) {
+        if (await pathEscapesWorkspace(path, workspace))
+            return true;
+    }
+    return false;
+}

package/dist/tools/registry.d.ts

@@ -0,0 +1,13 @@
+import type { ToolDefinition, ToolHandler } from "./types.js";
+export declare function createAllTools(): ToolHandler[];
+export declare class ToolRegistry {
+    private readonly tools;
+    constructor(tools?: ToolHandler[]);
+    get(name: string): ToolHandler | undefined;
+    all(): ToolHandler[];
+    /**
+     * Every tool definition in registration order — the mode-independent
+     * advertised set (stable schemas preserve provider prompt caching).
+     */
+    allDefinitions(): ToolDefinition[];
+}

package/dist/tools/registry.js

@@ -0,0 +1,38 @@
+// -------------------------------------------------------------------
+// Tool registry — aggregation and definition lookup. The advertised set is
+// mode-independent (see agent/modes.ts), so registration order is stable.
+// -------------------------------------------------------------------
+import { fsTools } from "./fs.js";
+import { shellToolInstance } from "./shell.js";
+import { grepToolInstance } from "./grep.js";
+import { findToolInstance } from "./find.js";
+import { skillTool } from "./skills.js";
+import { todoTool } from "./todo.js";
+import { transferTool } from "./transfer.js";
+export function createAllTools() {
+    return [...fsTools, grepToolInstance, findToolInstance, shellToolInstance, skillTool, todoTool, transferTool];
+}
+export class ToolRegistry {
+    tools = new Map();
+    constructor(tools = createAllTools()) {
+        for (const tool of tools) {
+            const name = tool.definition.function.name;
+            if (this.tools.has(name))
+                throw new Error(`Duplicate tool name: ${name}`);
+            this.tools.set(name, tool);
+        }
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    all() {
+        return [...this.tools.values()];
+    }
+    /**
+     * Every tool definition in registration order — the mode-independent
+     * advertised set (stable schemas preserve provider prompt caching).
+     */
+    allDefinitions() {
+        return this.all().map((tool) => tool.definition);
+    }
+}

package/dist/tools/shell.d.ts

@@ -0,0 +1,2 @@
+import type { ToolHandler } from "./types.js";
+export declare const shellToolInstance: ToolHandler;

package/dist/tools/shell.js

@@ -0,0 +1,136 @@
+// ---------------------------------------------------------------------------
+// local_shell — shell execution on the user's machine, rooted at the workspace.
+//
+// Deliberately NOT named "bash": remote skill documents refer to the server's
+// bash tool, and the two must not be conflated (this one runs on the CLI host;
+// server-side instructions about services/daemons do not apply). The actual
+// interpreter is /bin/sh (cmd.exe on Windows), so "shell" is also accurate.
+//
+// Cwd is fixed to the workspace (a command can still `cd` away — the approval
+// layer and mode gating are the actual guardrails). Output is capped at 50KB
+// UTF-8-safely; timeout and abort both kill the process tree best-effort.
+// ---------------------------------------------------------------------------
+import { defineTool, optionalNumber, requireString } from "./types.js";
+import { truncateWithMarker } from "./truncate.js";
+import { spawnProcess } from "../runtime.js";
+const DEFAULT_TIMEOUT_MS = 120_000;
+const MAX_TIMEOUT_MS = 600_000;
+const MAX_OUTPUT_BYTES = 50 * 1024;
+/**
+ * Per-stream in-memory cap. The final output is truncated to 50KB anyway, but
+ * the read used to buffer the ENTIRE stream first — `yes | …` could hold
+ * gigabytes in memory across the whole timeout window. Past the cap the
+ * stream keeps draining (discarding) so the child still completes and its
+ * side effects land: killing on overflow would break legitimately noisy
+ * commands (builds, test suites) whose output nobody reads past the cap.
+ */
+const MAX_CAPTURE_BYTES = 1024 * 1024;
+async function readStream(stream) {
+    if (!stream)
+        return "";
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let text = "";
+    let seen = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (seen < MAX_CAPTURE_BYTES) {
+            seen += value.byteLength;
+            text += decoder.decode(value, { stream: true });
+        }
+        // Past the cap: drain and discard.
+    }
+    return text + decoder.decode();
+}
+const shellTool = defineTool({
+    name: "local_shell",
+    description: "Run a shell command in the workspace root, on the user's machine. This is the LOCAL shell — not the myagent server's bash tool (server-side skill instructions about services/daemons do not apply). State does not persist between calls (each runs in a fresh shell). Output is truncated at 50KB.",
+    parameters: {
+        type: "object",
+        properties: {
+            command: { type: "string", description: "Shell command to run." },
+            timeout: { type: "number", description: `Timeout in ms (default ${DEFAULT_TIMEOUT_MS}, max ${MAX_TIMEOUT_MS}).` },
+        },
+        required: ["command"],
+    },
+    mutating: true,
+    summarize: (args) => {
+        const command = String(args.command ?? "");
+        return `shell: ${command.length > 60 ? command.slice(0, 57) + "…" : command}`;
+    },
+    run: async (args, ctx) => {
+        const command = requireString(args, "command");
+        const timeout = Math.min(Math.max(optionalNumber(args, "timeout") ?? DEFAULT_TIMEOUT_MS, 1000), MAX_TIMEOUT_MS);
+        if (ctx.signal?.aborted)
+            throw new Error("Command aborted before execution.");
+        const shell = process.platform === "win32" ? [process.env.COMSPEC ?? "cmd.exe", "/c", command] : ["/bin/sh", "-c", command];
+        const detached = process.platform !== "win32";
+        const proc = spawnProcess(shell, {
+            cwd: ctx.workspace,
+            env: process.env,
+            stdout: "pipe",
+            stderr: "pipe",
+            stdin: "ignore",
+            // POSIX: a new process group lets us kill the whole pipeline (a bare
+            // proc.kill() only signals the shell, and grandchildren keep the pipes
+            // open, delaying the timeout unwind).
+            detached,
+        });
+        let timedOut = false;
+        let aborted = false;
+        let killTimer = null;
+        const kill = () => {
+            try {
+                if (detached && proc.pid)
+                    process.kill(-proc.pid, "SIGTERM");
+                else
+                    proc.kill();
+            }
+            catch { /* already gone */ }
+            // Escalate if the process ignores SIGTERM.
+            killTimer = setTimeout(() => {
+                try {
+                    if (detached && proc.pid)
+                        process.kill(-proc.pid, "SIGKILL");
+                    else
+                        proc.kill(9);
+                }
+                catch { /* gone */ }
+            }, 3000);
+            killTimer.unref?.();
+        };
+        const timer = setTimeout(() => { timedOut = true; kill(); }, timeout);
+        const onAbort = () => { aborted = true; kill(); };
+        ctx.signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+            const [stdout, stderr, exitCode] = await Promise.all([
+                readStream(proc.stdout),
+                readStream(proc.stderr),
+                proc.exited,
+            ]);
+            let output = stdout;
+            if (stderr)
+                output += (output ? "\n" : "") + stderr;
+            output = output.replace(/\n$/, "");
+            if (!output)
+                output = "(no output)";
+            output = truncateWithMarker(output, MAX_OUTPUT_BYTES);
+            if (timedOut)
+                output += `\n[timeout after ${timeout}ms]`;
+            else if (aborted)
+                output += "\n[aborted]";
+            else if (exitCode !== 0)
+                output += `\n[exit code: ${exitCode}]`;
+            return output;
+        }
+        finally {
+            clearTimeout(timer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            ctx.signal?.removeEventListener("abort", onAbort);
+        }
+    },
+});
+export const shellToolInstance = shellTool;

package/dist/tools/skills.d.ts

@@ -0,0 +1,2 @@
+import type { ToolHandler } from "./types.js";
+export declare const skillTool: ToolHandler;

package/dist/tools/skills.js

@@ -0,0 +1,36 @@
+// -------------------------------------------------------------------
+// load_local_skill — load one local SKILL.md by name.
+// -------------------------------------------------------------------
+import { join } from "node:path";
+import { defineTool, optionalString } from "./types.js";
+import { discoverSkills, formatSkillList } from "../skills/discovery.js";
+const loadSkillTool = defineTool({
+    name: "load_local_skill",
+    description: "Load a skill from the user's machine by name and return its full instructions plus bundled file paths. The available skill catalog is in the system prompt; call this when a task matches a skill.",
+    parameters: {
+        type: "object",
+        properties: {
+            name: { type: "string", description: "Skill name from the available_skills catalog." },
+        },
+        required: ["name"],
+    },
+    summarize: (args) => `load skill ${String(args.name ?? "")}`,
+    run: async (args, ctx) => {
+        const skills = await discoverSkills(ctx.skillDirs);
+        const name = optionalString(args, "name");
+        if (!name) {
+            return `Available skills:\n${formatSkillList(skills)}\n\nCall again with a name to load one.`;
+        }
+        const skill = skills.find((s) => s.name === name);
+        if (!skill) {
+            const available = skills.map((s) => s.name).join(", ") || "none";
+            throw new Error(`No local skill named "${name}". Available: ${available}`);
+        }
+        const bundled = skill.files.filter((f) => f !== "SKILL.md");
+        const filesNote = bundled.length > 0
+            ? `\n\nBundled files (read with local_read using the path shown):\n${bundled.map((f) => `- ${join(skill.dir, f)}`).join("\n")}`
+            : "";
+        return skill.md + filesNote;
+    },
+});
+export const skillTool = loadSkillTool;

package/dist/tools/todo.d.ts

@@ -0,0 +1,2 @@
+import type { ToolHandler } from "./types.js";
+export declare const todoTool: ToolHandler;

package/dist/tools/todo.js

@@ -0,0 +1,43 @@
+// -------------------------------------------------------------------
+// local_update_todo — the agent's task checklist.
+//
+// The whole list is sent on every call (same contract as myagent-studio);
+// the CLI renders it in the TODO panel and persists it per session.
+// -------------------------------------------------------------------
+import { defineTool } from "./types.js";
+import { parseTodoItems } from "../agent/todo.js";
+const updateTodoTool = defineTool({
+    name: "local_update_todo",
+    description: "Update the session's TODO list. Send the ENTIRE list every time (it replaces the previous one). Use for multi-step work; mark the current item in_progress before starting it and completed immediately after finishing. Include it in the SAME assistant turn as your other tool calls (parallel tool calling) — a todo-only turn wastes a model round-trip.",
+    parameters: {
+        type: "object",
+        properties: {
+            todos: {
+                type: "array",
+                description: "The full list, in order.",
+                items: {
+                    type: "object",
+                    properties: {
+                        content: { type: "string", description: "Task description." },
+                        status: { type: "string", enum: ["pending", "in_progress", "completed"] },
+                    },
+                    required: ["content", "status"],
+                },
+            },
+        },
+        required: ["todos"],
+    },
+    summarize: (args) => {
+        const list = Array.isArray(args.todos) ? args.todos : [];
+        return `todo (${list.length} items)`;
+    },
+    run: async (args, ctx) => {
+        const items = parseTodoItems(args.todos);
+        ctx.todos.replace(items);
+        const done = items.filter((t) => t.status === "completed").length;
+        const current = items.find((t) => t.status === "in_progress");
+        return `Todo list updated (${done}/${items.length} completed)` +
+            (current ? ` — in progress: ${current.content}` : "");
+    },
+});
+export const todoTool = updateTodoTool;

package/dist/tools/transfer.d.ts

@@ -0,0 +1,2 @@
+import type { ToolHandler } from "./types.js";
+export declare const transferTool: ToolHandler;

package/dist/tools/transfer.js

@@ -0,0 +1,145 @@
+// ---------------------------------------------------------------------------
+// local_transfer_files — single-file transfers between the user's machine and
+// the myagent workspace, plus workspace directory listing.
+//
+// Uses the integration workspace API (/integrations/<id>/workspace/*) with the
+// same API key the rest of the client uses; the server resolves and confines
+// every workspace path. The local side goes through the usual workspace
+// confinement (resolveToolPath) so outside paths need --allow-outside /
+// approval.
+//
+//   get  workspace -> local   (writes the machine: plan mode refuses, ASK asks)
+//   put  local -> workspace   (no machine side effects: plan-safe)
+//   list workspace directory  (read-only)
+//
+// File content never enters the model transcript — every direction returns a
+// one-line status. Both write directions overwrite silently.
+// ---------------------------------------------------------------------------
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
+import { defineTool, optionalString, requireString } from "./types.js";
+import { displayPath, resolveToolPath } from "./paths.js";
+import { isBinaryBuffer } from "./binary.js";
+/**
+ * Client-side upload cap: the server rejects requests whose Content-Length
+ * exceeds 50 MB, and base64 inflates the payload by 4/3 — so the source file
+ * must stay below ~37 MB to fit.
+ */
+const PUT_MAX_LOCAL_BYTES = 37 * 1024 * 1024;
+/** Directory listings are capped so a huge workspace cannot flood the context. */
+const LIST_MAX_ENTRIES = 200;
+function formatBytes(size) {
+    if (size < 1024)
+        return `${size} B`;
+    if (size < 1024 * 1024)
+        return `${(size / 1024).toFixed(1)} KB`;
+    return `${(size / 1024 / 1024).toFixed(1)} MB`;
+}
+/** Workspace paths are API-side absolute — normalise to a single leading slash. */
+function normalizeWorkspacePath(path) {
+    return `/${path.replace(/^\/+/, "")}`.replace(/\/+$/, "") || "/";
+}
+/** `` `"from"` is required for this direction `` style errors. */
+function requireField(args, field, direction) {
+    const value = optionalString(args, field);
+    if (!value)
+        throw new Error(`Invalid arguments: "${field}" is required for direction "${direction}".`);
+    return value;
+}
+function clientOrThrow(ctx) {
+    if (!ctx.client)
+        throw new Error("Workspace transfer is unavailable: no API client in this context.");
+    return ctx.client;
+}
+async function transferGet(args, ctx) {
+    const client = clientOrThrow(ctx);
+    const from = normalizeWorkspacePath(requireField(args, "from", "get"));
+    // Default destination: the same relative path under the local workspace.
+    const to = optionalString(args, "to") ?? from.slice(1);
+    if (!to)
+        throw new Error('Invalid arguments: "to" must name a local destination file.');
+    const file = await client.workspaceRead(from, { signal: ctx.signal });
+    const data = file.binary ? Buffer.from(file.content, "base64") : Buffer.from(file.content, "utf-8");
+    const target = await resolveToolPath(to, ctx);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, data);
+    return `Saved ${formatBytes(data.length)} from workspace ${from} to ${displayPath(ctx.workspace, target)}${file.binary ? " (binary)" : ""}.`;
+}
+async function transferPut(args, ctx) {
+    const client = clientOrThrow(ctx);
+    const from = requireField(args, "from", "put");
+    const source = await resolveToolPath(from, ctx);
+    const info = await stat(source).catch(() => null);
+    if (!info)
+        throw new Error(`File not found: ${from}`);
+    if (info.isDirectory()) {
+        throw new Error(`"${from}" is a directory — only single files can be transferred (use direction "list" to browse the workspace, or loop per file).`);
+    }
+    if (info.size > PUT_MAX_LOCAL_BYTES) {
+        throw new Error(`File is too large (${formatBytes(info.size)}); the upload limit is ${formatBytes(PUT_MAX_LOCAL_BYTES)} after base64 encoding.`);
+    }
+    const buffer = await readFile(source);
+    const binary = isBinaryBuffer(buffer);
+    const to = normalizeWorkspacePath(optionalString(args, "to") ?? defaultWorkspacePath(source, ctx.workspace));
+    const result = await client.workspaceWrite(to, binary ? buffer.toString("base64") : buffer.toString("utf-8"), binary, { signal: ctx.signal });
+    return `Uploaded ${formatBytes(result.size || buffer.length)} from ${displayPath(ctx.workspace, source)} to workspace ${to}${binary ? " (binary)" : ""}.`;
+}
+/** Upload default: keep the file's workspace-relative path, else its basename. */
+function defaultWorkspacePath(source, workspace) {
+    const rel = relative(resolve(workspace), source);
+    return rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : basename(source);
+}
+async function transferList(args, ctx) {
+    const client = clientOrThrow(ctx);
+    const path = normalizeWorkspacePath(optionalString(args, "path") ?? "/");
+    const entries = await client.workspaceList(path, { signal: ctx.signal });
+    if (entries.length === 0)
+        return `${path} is empty.`;
+    const sorted = [...entries].sort((a, b) => a.name.localeCompare(b.name));
+    const shown = sorted.slice(0, LIST_MAX_ENTRIES);
+    const lines = shown.map((entry) => entry.type === "directory" ? `${entry.name}/ (dir)` : `${entry.name} (${formatBytes(entry.size)})`);
+    if (sorted.length > shown.length)
+        lines.push(`… (${sorted.length - shown.length} more)`);
+    return [`${path} — ${entries.length} entr${entries.length === 1 ? "y" : "ies"}:`, ...lines].join("\n");
+}
+export const transferTool = defineTool({
+    name: "local_transfer_files",
+    description: [
+        "Transfer single files between the user's machine and the myagent workspace, or list workspace directories.",
+        'direction "get": workspace → local (from = workspace path, to = local path, default: same relative path).',
+        'direction "put": local → workspace (from = local path, to = workspace path, default: its workspace-relative path).',
+        'direction "list": list a workspace directory (path, default "/").',
+        "Both write directions overwrite existing files. Single files only — use list and loop for directories.",
+    ].join(" "),
+    parameters: {
+        type: "object",
+        properties: {
+            direction: { type: "string", enum: ["get", "put", "list"], description: 'Transfer direction: "get" (download), "put" (upload), or "list".' },
+            from: { type: "string", description: 'get: workspace source path; put: local source path. Required for get/put.' },
+            to: { type: "string", description: "get: local destination (default: same relative path); put: workspace destination (default: workspace-relative path)." },
+            path: { type: "string", description: 'list: workspace directory to list (default "/").' },
+        },
+        required: ["direction"],
+    },
+    // Fail-safe default; the per-call hook narrows it to the mutating direction.
+    mutating: true,
+    isMutating: (args) => args.direction === "get",
+    summarize: (args) => {
+        const direction = optionalString(args, "direction") ?? "?";
+        if (direction === "list")
+            return `list ${optionalString(args, "path") ?? "/"}`;
+        const from = optionalString(args, "from") ?? "";
+        const to = optionalString(args, "to");
+        return to ? `${direction} ${from} → ${to}` : `${direction} ${from}`;
+    },
+    run: async (args, ctx) => {
+        const direction = requireString(args, "direction");
+        if (direction === "get")
+            return await transferGet(args, ctx);
+        if (direction === "put")
+            return await transferPut(args, ctx);
+        if (direction === "list")
+            return await transferList(args, ctx);
+        throw new Error(`Invalid arguments: "direction" must be one of get, put, list (got "${direction}").`);
+    },
+});

package/dist/tools/truncate.d.ts

@@ -0,0 +1,12 @@
+export interface TruncateResult {
+    text: string;
+    truncated: boolean;
+    removedBytes: number;
+}
+/**
+ * Truncate `text` to at most `maxBytes` UTF-8 bytes without splitting a code
+ * point. The result never exceeds the limit.
+ */
+export declare function truncateUtf8(text: string, maxBytes: number): TruncateResult;
+/** Truncate and append a standard marker when anything was removed. */
+export declare function truncateWithMarker(text: string, maxBytes: number): string;

package/dist/tools/truncate.js

@@ -0,0 +1,46 @@
+// ---------------------------------------------------------------------------
+// UTF-8-safe text truncation for tool output.
+// ---------------------------------------------------------------------------
+/** Byte length of a string in UTF-8 (without allocating a buffer). */
+function utf8Length(text) {
+    let bytes = 0;
+    for (const ch of text) {
+        const code = ch.codePointAt(0);
+        if (code <= 0x7f)
+            bytes += 1;
+        else if (code <= 0x7ff)
+            bytes += 2;
+        else if (code <= 0xffff)
+            bytes += 3;
+        else
+            bytes += 4;
+    }
+    return bytes;
+}
+/**
+ * Truncate `text` to at most `maxBytes` UTF-8 bytes without splitting a code
+ * point. The result never exceeds the limit.
+ */
+export function truncateUtf8(text, maxBytes) {
+    if (maxBytes < 0)
+        throw new Error("maxBytes must be >= 0");
+    let bytes = 0;
+    let endIndex = 0;
+    for (const ch of text) {
+        const code = ch.codePointAt(0);
+        const size = code <= 0x7f ? 1 : code <= 0x7ff ? 2 : code <= 0xffff ? 3 : 4;
+        if (bytes + size > maxBytes)
+            break;
+        bytes += size;
+        endIndex += ch.length;
+    }
+    if (endIndex >= text.length)
+        return { text, truncated: false, removedBytes: 0 };
+    const total = utf8Length(text);
+    return { text: text.slice(0, endIndex), truncated: true, removedBytes: total - bytes };
+}
+/** Truncate and append a standard marker when anything was removed. */
+export function truncateWithMarker(text, maxBytes) {
+    const result = truncateUtf8(text, maxBytes);
+    return result.truncated ? `${result.text}\n\n… [+${result.removedBytes} bytes truncated]` : text;
+}