@musashishao/folderforge 1.2.0

package/dist/tools/git-tools.js

@@ -0,0 +1,371 @@
+import { simpleGit } from 'simple-git';
+import { defineTool } from './registry.js';
+import { GIT_STATUS_OUTPUT_SCHEMA } from './output-schemas.js';
+function git(ctx) {
+    return simpleGit({ baseDir: ctx.projectRoot });
+}
+export function gitTools() {
+    return [
+        defineTool({
+            name: 'git_status',
+            description: 'Show git branch and changed/staged/unstaged files.',
+            group: 'git',
+            mutates: false,
+            inputSchema: { type: 'object', properties: {} },
+            outputSchema: GIT_STATUS_OUTPUT_SCHEMA,
+            handler: async (_a, ctx) => {
+                const s = await git(ctx).status();
+                return {
+                    ok: true,
+                    data: {
+                        branch: s.current,
+                        ahead: s.ahead,
+                        behind: s.behind,
+                        staged: s.staged,
+                        modified: s.modified,
+                        not_added: s.not_added,
+                        deleted: s.deleted,
+                        conflicted: s.conflicted,
+                        clean: s.isClean(),
+                    },
+                };
+            },
+        }),
+        defineTool({
+            name: 'git_diff',
+            description: 'Show diff for the working tree, staged changes, or a specific file.',
+            group: 'git',
+            mutates: false,
+            inputSchema: {
+                type: 'object',
+                properties: { staged: { type: 'boolean' }, file: { type: 'string' } },
+            },
+            handler: async (args, ctx) => {
+                const opts = [];
+                if (args.staged)
+                    opts.push('--cached');
+                if (args.file)
+                    opts.push('--', String(args.file));
+                const diff = await git(ctx).diff(opts);
+                return { ok: true, data: { diff: ctx.container.policy.secret.redact(diff) } };
+            },
+        }),
+        defineTool({
+            name: 'git_log',
+            description: 'Show recent commits.',
+            group: 'git',
+            mutates: false,
+            inputSchema: { type: 'object', properties: { limit: { type: 'number' } } },
+            handler: async (args, ctx) => {
+                const log = await git(ctx).log({ maxCount: Number(args.limit ?? 20) });
+                return {
+                    ok: true,
+                    data: {
+                        commits: log.all.map((c) => ({ hash: c.hash.slice(0, 8), date: c.date, message: c.message, author: c.author_name })),
+                    },
+                };
+            },
+        }),
+        defineTool({
+            name: 'git_branch',
+            description: 'List branches or create a new one.',
+            group: 'git',
+            mutates: false,
+            inputSchema: { type: 'object', properties: { create: { type: 'string' } } },
+            handler: async (args, ctx) => {
+                if (args.create) {
+                    await git(ctx).checkoutLocalBranch(String(args.create));
+                    return { ok: true, data: { created: String(args.create) } };
+                }
+                const b = await git(ctx).branchLocal();
+                return { ok: true, data: { current: b.current, branches: b.all } };
+            },
+        }),
+        defineTool({
+            name: 'git_checkout',
+            description: 'Switch to an existing branch.',
+            group: 'git',
+            mutates: true,
+            inputSchema: { type: 'object', properties: { branch: { type: 'string' } }, required: ['branch'] },
+            handler: async (args, ctx) => {
+                await git(ctx).checkout(String(args.branch));
+                return { ok: true, data: { branch: String(args.branch) } };
+            },
+        }),
+        defineTool({
+            name: 'git_add',
+            description: 'Stage files for commit. Requires approval in safe mode.',
+            group: 'git',
+            mutates: true,
+            inputSchema: { type: 'object', properties: { files: { type: 'array', items: { type: 'string' } } }, required: ['files'] },
+            handler: async (args, ctx) => {
+                await git(ctx).add(args.files);
+                return { ok: true, data: { staged: args.files } };
+            },
+        }),
+        defineTool({
+            name: 'git_commit',
+            description: 'Commit staged files. Requires approval.',
+            group: 'git',
+            mutates: true,
+            inputSchema: { type: 'object', properties: { message: { type: 'string' } }, required: ['message'] },
+            handler: async (args, ctx) => {
+                const res = await git(ctx).commit(String(args.message));
+                return { ok: true, data: { commit: res.commit, summary: res.summary } };
+            },
+        }),
+        defineTool({
+            name: 'git_push',
+            description: 'Push commits. CRITICAL; denied unless danger mode + approval. Force push disabled.',
+            group: 'git',
+            mutates: true,
+            inputSchema: { type: 'object', properties: { remote: { type: 'string' }, branch: { type: 'string' } } },
+            handler: async (args, ctx) => {
+                const remote = String(args.remote ?? 'origin');
+                const branch = args.branch ? String(args.branch) : undefined;
+                // P8 - elicitation: pushing is irreversible from the local side
+                // (publishes commits to a shared remote). When the client supports
+                // interactive input, confirm the exact remote/branch before pushing.
+                // Clients without the capability see `elicitInput === undefined` and
+                // the push proceeds (policy/approval already gate it upstream).
+                if (ctx.control?.elicitInput) {
+                    const status = await git(ctx).status();
+                    const target = branch ?? status.current ?? 'current branch';
+                    const ahead = status.ahead ?? 0;
+                    const res = await ctx.control.elicitInput({
+                        message: `Push ${ahead} commit(s) to ${remote}/${target}? This publishes them to the shared remote.`,
+                        requestedSchema: {
+                            type: 'object',
+                            properties: {
+                                confirm: {
+                                    type: 'boolean',
+                                    description: 'Confirm the push.',
+                                },
+                            },
+                            required: ['confirm'],
+                        },
+                    });
+                    if (res.action !== 'accept' || res.content?.confirm !== true) {
+                        return { ok: false, error: `git_push cancelled by user (${res.action}).` };
+                    }
+                }
+                // P4 - progress: report a tick before and after the network call so a
+                // client that sent a progressToken sees the long push advance.
+                await ctx.control?.reportProgress?.(0, 1, `Pushing to ${remote}...`);
+                await git(ctx).push(remote, branch);
+                await ctx.control?.reportProgress?.(1, 1, 'Push complete.');
+                return { ok: true, data: { pushed: true, remote, branch: branch ?? null } };
+            },
+        }),
+        defineTool({
+            name: 'git_reset',
+            description: 'Reset staged changes (soft/mixed only). CRITICAL; hard reset disabled.',
+            group: 'git',
+            mutates: true,
+            inputSchema: { type: 'object', properties: { mode: { type: 'string', enum: ['soft', 'mixed'] } } },
+            handler: async (args, ctx) => {
+                const mode = String(args.mode ?? 'mixed');
+                if (mode === 'hard' && !ctx.config.git.allowResetHard) {
+                    return { ok: false, error: 'Hard reset is disabled by configuration.' };
+                }
+                // P8 - elicitation: when the connected client supports it, confirm this
+                // destructive reset interactively before touching the index. Clients
+                // without the capability see `elicitInput === undefined` and the reset
+                // proceeds non-interactively (policy/approval already gate it upstream).
+                if (ctx.control?.elicitInput) {
+                    const status = await git(ctx).status();
+                    const res = await ctx.control.elicitInput({
+                        message: `Reset (--${mode}) will unstage ${status.staged.length} file(s) on branch ${status.current}. Continue?`,
+                        requestedSchema: {
+                            type: 'object',
+                            properties: {
+                                confirm: {
+                                    type: 'boolean',
+                                    description: 'Confirm the reset.',
+                                },
+                            },
+                            required: ['confirm'],
+                        },
+                    });
+                    if (res.action !== 'accept' || res.content?.confirm !== true) {
+                        return { ok: false, error: `git_reset cancelled by user (${res.action}).` };
+                    }
+                }
+                await git(ctx).reset([`--${mode}`]);
+                return { ok: true, data: { reset: mode } };
+            },
+        }),
+        defineTool({
+            name: 'git_fetch',
+            description: 'Fetch updates from a remote without touching the working tree. Updates ' +
+                'remote-tracking refs only; safe and non-destructive.',
+            group: 'git',
+            mutates: true,
+            annotations: { openWorldHint: true },
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    remote: { type: 'string', description: 'Remote name (default origin).' },
+                    branch: { type: 'string', description: 'Specific branch to fetch (default all).' },
+                    prune: { type: 'boolean', description: 'Prune deleted remote-tracking branches.' },
+                },
+            },
+            handler: async (args, ctx) => {
+                const remote = String(args.remote ?? 'origin');
+                const branch = args.branch ? String(args.branch) : undefined;
+                const opts = args.prune ? ['--prune'] : [];
+                await ctx.control?.reportProgress?.(0, 1, `Fetching from ${remote}...`);
+                const res = await git(ctx).fetch(remote, branch, opts);
+                await ctx.control?.reportProgress?.(1, 1, 'Fetch complete.');
+                return {
+                    ok: true,
+                    data: {
+                        remote,
+                        branch: branch ?? null,
+                        updated: res.updated ?? [],
+                        deleted: res.deleted ?? [],
+                    },
+                };
+            },
+        }),
+        defineTool({
+            name: 'git_pull',
+            description: 'Pull and integrate changes from a remote into the current branch. HIGH ' +
+                'risk: may rewrite working-tree files and produce merge conflicts. ' +
+                'Confirms interactively when the client supports elicitation.',
+            group: 'git',
+            mutates: true,
+            annotations: { openWorldHint: true },
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    remote: { type: 'string', description: 'Remote name (default origin).' },
+                    branch: { type: 'string', description: 'Branch to pull (default current upstream).' },
+                    rebase: { type: 'boolean', description: 'Use --rebase instead of merge.' },
+                },
+            },
+            handler: async (args, ctx) => {
+                const remote = String(args.remote ?? 'origin');
+                const branch = args.branch ? String(args.branch) : undefined;
+                const rebase = args.rebase === true;
+                // P8 - elicitation: a pull can overwrite local files and create
+                // conflicts, so confirm before integrating when the client supports it.
+                // Clients without the capability proceed (policy/approval gate upstream).
+                if (ctx.control?.elicitInput) {
+                    const status = await git(ctx).status();
+                    const target = branch ?? status.tracking ?? status.current ?? 'upstream';
+                    const dirty = !status.isClean();
+                    const res = await ctx.control.elicitInput({
+                        message: `Pull from ${remote}/${target} into ${status.current}` +
+                            `${rebase ? ' (rebase)' : ''}? ` +
+                            `${dirty ? 'Your working tree has uncommitted changes. ' : ''}` +
+                            'This may modify local files.',
+                        requestedSchema: {
+                            type: 'object',
+                            properties: {
+                                confirm: { type: 'boolean', description: 'Confirm the pull.' },
+                            },
+                            required: ['confirm'],
+                        },
+                    });
+                    if (res.action !== 'accept' || res.content?.confirm !== true) {
+                        return { ok: false, error: `git_pull cancelled by user (${res.action}).` };
+                    }
+                }
+                const opts = {};
+                if (rebase)
+                    opts['--rebase'] = null;
+                await ctx.control?.reportProgress?.(0, 1, `Pulling from ${remote}...`);
+                const summary = await git(ctx).pull(remote, branch, opts);
+                await ctx.control?.reportProgress?.(1, 1, 'Pull complete.');
+                return {
+                    ok: true,
+                    data: {
+                        remote,
+                        branch: branch ?? null,
+                        rebase,
+                        changes: summary.summary?.changes ?? 0,
+                        insertions: summary.summary?.insertions ?? 0,
+                        deletions: summary.summary?.deletions ?? 0,
+                        files: summary.files ?? [],
+                    },
+                };
+            },
+        }),
+        defineTool({
+            name: 'git_stash',
+            description: 'Save, restore, list, or drop stashed changes. op: push (default) | pop | ' +
+                'apply | list | drop. Hard data loss is avoided (no stash clear).',
+            group: 'git',
+            mutates: true,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    op: {
+                        type: 'string',
+                        enum: ['push', 'pop', 'apply', 'list', 'drop'],
+                        description: 'Stash operation (default push).',
+                    },
+                    message: { type: 'string', description: 'Optional label when op=push.' },
+                    index: { type: 'number', description: 'Stash index for pop/apply/drop (default 0).' },
+                    includeUntracked: { type: 'boolean', description: 'Include untracked files when op=push.' },
+                },
+            },
+            handler: async (args, ctx) => {
+                const op = String(args.op ?? 'push');
+                const g = git(ctx);
+                if (op === 'list') {
+                    const list = await g.stashList();
+                    return {
+                        ok: true,
+                        data: {
+                            op,
+                            count: list.total,
+                            entries: list.all.map((e) => ({ hash: e.hash.slice(0, 8), message: e.message })),
+                        },
+                    };
+                }
+                if (op === 'push') {
+                    const opts = ['push'];
+                    if (args.includeUntracked)
+                        opts.push('--include-untracked');
+                    if (args.message)
+                        opts.push('-m', String(args.message));
+                    const out = await g.stash(opts);
+                    return { ok: true, data: { op, result: out.trim() } };
+                }
+                if (op === 'pop' || op === 'apply' || op === 'drop') {
+                    const index = Number(args.index ?? 0);
+                    if (!Number.isInteger(index) || index < 0) {
+                        return { ok: false, error: `Invalid stash index: ${args.index}` };
+                    }
+                    const out = await g.stash([op, `stash@{${index}}`]);
+                    return { ok: true, data: { op, index, result: out.trim() } };
+                }
+                return { ok: false, error: `Unknown stash op: ${op}` };
+            },
+        }),
+        defineTool({
+            name: 'git_show',
+            description: 'Show a commit by ref (read-only).',
+            group: 'git',
+            mutates: false,
+            inputSchema: { type: 'object', properties: { ref: { type: 'string' } }, required: ['ref'] },
+            handler: async (args, ctx) => {
+                const out = await git(ctx).show([String(args.ref)]);
+                return { ok: true, data: { content: ctx.container.policy.secret.redact(out) } };
+            },
+        }),
+        defineTool({
+            name: 'git_blame',
+            description: 'Show blame for a file (read-only).',
+            group: 'git',
+            mutates: false,
+            inputSchema: { type: 'object', properties: { file: { type: 'string' } }, required: ['file'] },
+            handler: async (args, ctx) => {
+                const out = await git(ctx).raw(['blame', String(args.file)]);
+                return { ok: true, data: { blame: out.slice(0, 50000) } };
+            },
+        }),
+    ];
+}

package/dist/tools/index.js

@@ -0,0 +1,63 @@
+import { ToolRegistry } from './registry.js';
+import { workspaceTools } from './workspace-tools.js';
+import { fileTools } from './file-tools.js';
+import { searchTools } from './search-tools.js';
+import { terminalTools } from './terminal-tools.js';
+import { processTools } from './process-tools.js';
+import { gitTools } from './git-tools.js';
+import { buildTools } from './build-tools.js';
+import { memoryTools } from './memory-tools.js';
+import { securityTools } from './security-tools.js';
+import { codeTools } from './code-tools.js';
+import { browserTools } from './browser-tools.js';
+import { dbTools } from './db-tools.js';
+import { pkgTools } from './pkg-tools.js';
+import { formatTools } from './format-tools.js';
+import { coverageTools } from './coverage-tools.js';
+import { buildAdapterTools } from './adapter-tools.js';
+/**
+ * Build the full tool registry with every group registered.
+ */
+export function buildRegistry(container) {
+    const registry = new ToolRegistry(container);
+    registry.registerAll([
+        ...workspaceTools(),
+        ...fileTools(),
+        ...searchTools(),
+        ...terminalTools(),
+        ...processTools(),
+        ...gitTools(),
+        ...buildTools(),
+        ...memoryTools(),
+        ...securityTools(),
+        ...codeTools(),
+        ...browserTools(),
+        ...dbTools(),
+        ...pkgTools(),
+        ...formatTools(),
+        ...coverageTools(),
+    ]);
+    // Expose the registry on the container so routing tools (workspace_route)
+    // can switch the active tool subset at runtime.
+    container.registry = registry;
+    return registry;
+}
+/**
+ * Discover and register tools exposed by enabled child MCP adapters (Serena,
+ * Playwright, ...). Each child tool is namespaced (e.g. `serena__find_symbol`)
+ * and routed through the normal policy + audit pipeline. Safe to call once after
+ * {@link buildRegistry}; a no-op when no adapters are enabled.
+ */
+export async function registerAdapterTools(container, registry) {
+    const adapterTools = await buildAdapterTools(container);
+    registry.registerAll(adapterTools);
+    return adapterTools.length;
+}
+/**
+ * Curated tool subsets for task-based routing (section 9 of the spec).
+ */
+export const TASK_PRESETS = {
+    explore: ['workspace_status', 'search_text', 'search_files', 'code_find_symbol', 'code_symbols_overview', 'file_read'],
+    run_ui: ['process_start', 'process_read', 'browser_open', 'browser_snapshot', 'browser_console', 'browser_network'],
+    fix_tests: ['run_test', 'code_diagnostics', 'file_patch', 'file_edit_block', 'shell_exec', 'git_diff'],
+};

package/dist/tools/memory-tools.js

@@ -0,0 +1,54 @@
+import { defineTool } from './registry.js';
+export function memoryTools() {
+    return [
+        defineTool({
+            name: 'memory_list',
+            description: 'List project memory files.',
+            group: 'memory',
+            mutates: false,
+            inputSchema: { type: 'object', properties: {} },
+            handler: async (_a, ctx) => ({ ok: true, data: { memories: ctx.container.workspace.getMemory().list() } }),
+        }),
+        defineTool({
+            name: 'memory_read',
+            description: 'Read a project memory file by name.',
+            group: 'memory',
+            mutates: false,
+            inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+            handler: async (args, ctx) => ({
+                ok: true,
+                data: { content: ctx.container.workspace.getMemory().read(String(args.name)) },
+            }),
+        }),
+        defineTool({
+            name: 'memory_write',
+            description: 'Create or overwrite a project memory file.',
+            group: 'memory',
+            mutates: true,
+            inputSchema: {
+                type: 'object',
+                properties: { name: { type: 'string' }, content: { type: 'string' } },
+                required: ['name', 'content'],
+            },
+            handler: async (args, ctx) => {
+                const path = ctx.container.workspace.getMemory().write(String(args.name), String(args.content));
+                return { ok: true, data: { path } };
+            },
+        }),
+        defineTool({
+            name: 'memory_update',
+            description: 'Append content to an existing project memory file.',
+            group: 'memory',
+            mutates: true,
+            inputSchema: {
+                type: 'object',
+                properties: { name: { type: 'string' }, append: { type: 'string' } },
+                required: ['name', 'append'],
+            },
+            handler: async (args, ctx) => {
+                const path = ctx.container.workspace.getMemory().update(String(args.name), String(args.append));
+                return { ok: true, data: { path } };
+            },
+        }),
+    ];
+}

package/dist/tools/output-schemas.js

@@ -0,0 +1,100 @@
+/**
+ * Reusable JSON-Schema fragments for tool `outputSchema` declarations
+ * (roadmap Q1 - typed structured output). These describe the shape of the
+ * `data` payload a tool returns on success so MCP clients can validate the
+ * `structuredContent` field advertised by the server.
+ *
+ * Keeping them centralized means the schema and the handler stay close and a
+ * single source documents the structured contract for the four "high-value"
+ * tools called out in the roadmap: run_test, code_diagnostics, git_status,
+ * db_query_readonly.
+ */
+const errorItem = {
+    type: 'object',
+    properties: {
+        file: { type: 'string' },
+        line: { type: 'integer' },
+        column: { type: 'integer' },
+        severity: { type: 'string', enum: ['error', 'warning', 'info'] },
+        message: { type: 'string' },
+        code: { type: 'string' },
+    },
+};
+/** Output of run_test / run_lint / run_typecheck / run_build (runScript). */
+export const RUN_SCRIPT_OUTPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        command: { type: 'string', description: 'The resolved command that was executed.' },
+        exitCode: { type: ['integer', 'null'], description: 'Process exit code (0 = success).' },
+        stdout: { type: 'string' },
+        stderr: { type: 'string' },
+        errors: {
+            type: 'array',
+            description: 'Structured failures parsed from the output.',
+            items: errorItem,
+        },
+    },
+    required: ['command', 'exitCode', 'errors'],
+};
+/** Output of code_diagnostics. */
+export const DIAGNOSTICS_OUTPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        diagnostics: { type: 'array', items: errorItem },
+        count: { type: 'integer' },
+        source: {
+            type: 'string',
+            description: 'Backend that produced the diagnostics (e.g. "lsp" or "regex").',
+        },
+    },
+    required: ['diagnostics'],
+};
+/** Output of git_status. */
+export const GIT_STATUS_OUTPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        branch: { type: ['string', 'null'] },
+        ahead: { type: 'integer' },
+        behind: { type: 'integer' },
+        clean: { type: 'boolean' },
+        staged: { type: 'array', items: { type: 'string' } },
+        modified: { type: 'array', items: { type: 'string' } },
+        not_added: { type: 'array', items: { type: 'string' } },
+        deleted: { type: 'array', items: { type: 'string' } },
+        conflicted: { type: 'array', items: { type: 'string' } },
+    },
+};
+/** Output of db_query_readonly. */
+export const DB_QUERY_OUTPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        rows: {
+            type: 'array',
+            description: 'Result rows; each row is a column->value object.',
+            items: { type: 'object', additionalProperties: true },
+        },
+    },
+    required: ['rows'],
+};
+/** Output of run_coverage. */
+export const COVERAGE_OUTPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        command: { type: 'string' },
+        exitCode: { type: ['integer', 'null'] },
+        summary: {
+            type: ['object', 'null'],
+            description: 'Coverage percentages (lines/branches/functions/statements).',
+            properties: {
+                lines: { type: 'number' },
+                branches: { type: 'number' },
+                functions: { type: 'number' },
+                statements: { type: 'number' },
+            },
+        },
+        errors: { type: 'array', items: errorItem },
+        stdout: { type: 'string' },
+        stderr: { type: 'string' },
+    },
+    required: ['command', 'exitCode'],
+};

package/dist/tools/pagination.js

@@ -0,0 +1,92 @@
+/**
+ * Shared pagination & truncation helpers (roadmap Q3 - token efficiency).
+ *
+ * Large read-style tool outputs (search hits, logs, file bodies) can blow an
+ * agent's context window. These helpers give every reading tool a consistent
+ * `offset` / `limit` / `maxBytes` contract and a uniform truncation envelope so
+ * the agent always knows whether more data is available and how to fetch it.
+ *
+ * Conventions:
+ *  - `offset` is 0-based; `limit` caps the number of returned items.
+ *  - `maxBytes` caps the UTF-8 byte size of a returned string body.
+ *  - When output is cut short, the tool sets `truncated: true` and returns a
+ *    `nextOffset` (for item lists) so the caller can page forward.
+ */
+/** Default and ceiling page sizes; tools may override the default. */
+export const DEFAULT_LIMIT = 100;
+export const MAX_LIMIT = 1000;
+/** Coerce a raw arg into a non-negative integer, or fall back. */
+export function toInt(value, fallback) {
+    const n = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(n) || n < 0)
+        return fallback;
+    return Math.floor(n);
+}
+/** Read and normalize pagination params from a raw args object. */
+export function readPageParams(args, defaultLimit = DEFAULT_LIMIT) {
+    const offset = toInt(args.offset, 0);
+    const limit = Math.min(toInt(args.limit, defaultLimit) || defaultLimit, MAX_LIMIT);
+    const maxBytes = args.maxBytes === undefined ? undefined : toInt(args.maxBytes, 0) || undefined;
+    return maxBytes === undefined ? { offset, limit } : { offset, limit, maxBytes };
+}
+/** Slice an array into a {@link Page} envelope. */
+export function paginate(all, offset, limit) {
+    const total = all.length;
+    const start = Math.min(offset, total);
+    const end = Math.min(start + limit, total);
+    const items = all.slice(start, end);
+    const truncated = end < total;
+    return {
+        items,
+        total,
+        offset: start,
+        count: items.length,
+        truncated,
+        nextOffset: truncated ? end : null,
+    };
+}
+/**
+ * Truncate a string to at most `maxBytes` UTF-8 bytes without splitting a
+ * multi-byte character. Returns the original string untouched when it fits or
+ * when `maxBytes` is undefined.
+ */
+export function truncateBytes(text, maxBytes) {
+    const buf = Buffer.from(text, 'utf8');
+    const totalBytes = buf.length;
+    if (maxBytes === undefined || totalBytes <= maxBytes) {
+        return { text, truncated: false, totalBytes, returnedBytes: totalBytes };
+    }
+    // Step back to a UTF-8 character boundary (continuation bytes are 0b10xxxxxx).
+    let end = maxBytes;
+    while (end > 0 && ((buf[end] ?? 0) & 0xc0) === 0x80)
+        end--;
+    const slice = buf.subarray(0, end);
+    return {
+        text: slice.toString('utf8'),
+        truncated: true,
+        totalBytes,
+        returnedBytes: slice.length,
+    };
+}
+/**
+ * JSON-Schema fragment for the shared pagination inputs. Spread into a tool's
+ * `inputSchema.properties` so every reading tool documents the same contract.
+ */
+export const PAGE_INPUT_SCHEMA = {
+    offset: {
+        type: 'integer',
+        minimum: 0,
+        description: '0-based index of the first item to return (default 0).',
+    },
+    limit: {
+        type: 'integer',
+        minimum: 1,
+        maximum: MAX_LIMIT,
+        description: `Maximum number of items to return (default ${DEFAULT_LIMIT}).`,
+    },
+    maxBytes: {
+        type: 'integer',
+        minimum: 1,
+        description: 'Cap the UTF-8 byte size of large string output.',
+    },
+};