@glbgpt/cli 0.1.0-test.5 → 0.1.0

package/dist/src/fs/index.d.ts

@@ -0,0 +1,8 @@
+/** Public surface of the fs read tools (phase A). */
+import type { ClientTool } from '../core/types.js';
+export { workspaceRoot } from './workspaceGuard.js';
+export { MAX_TOOL_CALLS_PER_TURN } from './limits.js';
+/** The four read-only tools, jailed to `root`. Registration order = model-visible order. */
+/** The fs tool names — source of truth for context pruning's "prunable" check. */
+export declare const FS_TOOL_NAMES: ReadonlySet<string>;
+export declare function createFsTools(root: string): ClientTool[];

package/dist/src/fs/index.js

@@ -0,0 +1,13 @@
+import { createReadFileTool } from './readFileTool.js';
+import { createListDirTool } from './listDirTool.js';
+import { createGlobTool } from './globTool.js';
+import { createGrepTool } from './grepTool.js';
+export { workspaceRoot } from './workspaceGuard.js';
+export { MAX_TOOL_CALLS_PER_TURN } from './limits.js';
+/** The four read-only tools, jailed to `root`. Registration order = model-visible order. */
+/** The fs tool names — source of truth for context pruning's "prunable" check. */
+export const FS_TOOL_NAMES = new Set(['read_file', 'list_dir', 'glob', 'grep']);
+export function createFsTools(root) {
+    return [createReadFileTool(root), createListDirTool(root), createGlobTool(root), createGrepTool(root)];
+}
+//# sourceMappingURL=index.js.map

package/dist/src/fs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/fs/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAEtD,4FAA4F;AAC5F,kFAAkF;AAClF,MAAM,CAAC,MAAM,aAAa,GAAwB,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAErG,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,iBAAiB,CAAC,IAAI,CAAC,EAAE,cAAc,CAAC,IAAI,CAAC,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;AACzG,CAAC"}

package/dist/src/fs/limits.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Every cap and over-limit behavior for the fs read tools, in one auditable place.
+ * These are BILLING decisions, not implementation details, and the policy splits
+ * by content cost (2026-07-19 revision, Claude Code parity):
+ * - READ content (expensive, thousands of tokens): over-limit = ERROR (~100 bytes)
+ *   — inherited from Claude Code's reverted experiment (#21841): truncation
+ *   lowered tool error rates but RAISED mean token cost.
+ * - DISCOVERY results (cheap path/match lists): over-limit = TRUNCATE + note —
+ *   erroring only wasted the model a retry round-trip.
+ */
+export declare const MAX_FILE_SIZE_BYTES: number;
+export declare const MAX_RANGED_FILE_SIZE_BYTES: number;
+export declare const MAX_READ_LINES = 2000;
+export declare const MAX_READ_OUTPUT_BYTES: number;
+export declare const MAX_LINE_CHARS = 2000;
+export declare const MAX_DIR_ENTRIES = 200;
+export declare const MAX_GLOB_RESULTS = 100;
+export declare const MAX_GLOB_SCAN = 2000;
+export declare const MAX_GREP_MATCHES = 100;
+export declare const MAX_GREP_LINE_CHARS = 200;
+export declare const GREP_TIMEOUT_MS = 5000;
+export declare const MAX_TOOL_CALLS_PER_TURN = 15;
+/** Directory names never listed, walked, or matched (noise + huge). */
+export declare const IGNORED_DIRS: Set<string>;
+/** File names never listed or matched. */
+export declare const IGNORED_FILES: Set<string>;
+export declare const BUDGET_EXHAUSTED_MESSAGE = "Tool budget for this turn is exhausted. Summarize with what you have.";
+export declare const PRUNE_TRIGGER_TOKENS = 30000;
+export declare const PRUNE_KEEP_RECENT = 3;
+export declare const PRUNE_MIN_CONTENT_BYTES = 200;
+export declare const PRUNE_PLACEHOLDER = "[Old tool result cleared to save context \u2014 re-run the tool if needed.]";
+export declare const DEFAULT_SESSION_MAX_CREDITS = 4000;
+export declare const MEDIA_GRACE_WAIT_MS = 45000;
+export declare const MEDIA_POLL_HINT_SECONDS = 0;

package/dist/src/fs/limits.js

@@ -0,0 +1,74 @@
+/**
+ * Every cap and over-limit behavior for the fs read tools, in one auditable place.
+ * These are BILLING decisions, not implementation details, and the policy splits
+ * by content cost (2026-07-19 revision, Claude Code parity):
+ * - READ content (expensive, thousands of tokens): over-limit = ERROR (~100 bytes)
+ *   — inherited from Claude Code's reverted experiment (#21841): truncation
+ *   lowered tool error rates but RAISED mean token cost.
+ * - DISCOVERY results (cheap path/match lists): over-limit = TRUNCATE + note —
+ *   erroring only wasted the model a retry round-trip.
+ */
+export const MAX_FILE_SIZE_BYTES = 1024 * 1024; // read_file / grep skip-threshold
+export const MAX_RANGED_FILE_SIZE_BYTES = 8 * 1024 * 1024; // absolute ceiling — refuse even range reads above this
+// NOTE 2026-07-19: the old DEFAULT_READ_LINES (1000-line default-read error) was removed.
+// Dogfood showed it costs MORE than it saves: the model reads the whole file anyway via
+// error + N range reads (4 round-trips for a 2226-line file). Default reads are now bounded
+// by MAX_FILE_SIZE_BYTES (pre-read) and MAX_READ_OUTPUT_BYTES (post-build) only —
+// Claude Code FileReadTool parity. Over-limit=error stays for READ content (expensive);
+// discovery tools (glob/grep) truncate with a note instead (cheap path lists).
+export const MAX_READ_LINES = 2000; // read_file explicit-limit ceiling
+// 100KB ≈ 25k tokens — Claude Code FileReadTool's output-token cap, live-validated
+// 2026-07-19: the old 256KB cap let a 118KB package-lock.json burn ~33k tokens
+// that then sat in the session context, re-billed on every subsequent turn.
+export const MAX_READ_OUTPUT_BYTES = 100 * 1024; // hard output ceiling for any read_file call
+export const MAX_LINE_CHARS = 2000; // single line cap (truncated with marker)
+export const MAX_DIR_ENTRIES = 200; // list_dir
+export const MAX_GLOB_RESULTS = 100; // glob: shown results (over-cap truncates with a note)
+export const MAX_GLOB_SCAN = 2000; // glob: hard bound on matches collected before sorting
+export const MAX_GREP_MATCHES = 100; // grep
+export const MAX_GREP_LINE_CHARS = 200; // grep match line preview cap
+// grep executes MODEL-supplied regex; JS RegExp backtracks, so an evil pattern
+// ((a+)+$) can hang V8 forever. Matching therefore runs inside a vm script whose
+// timeout (V8 TerminateExecution) interrupts even mid-backtrack — verified live
+// 2026-07-20. The budget is per grep CALL, and because vm runs synchronously it
+// also bounds the worst-case main-thread stall: Claude Code allows 20s but its
+// ripgrep runs out-of-process; in-process, 5s keeps a frozen TUI recoverable.
+export const GREP_TIMEOUT_MS = 5_000;
+export const MAX_TOOL_CALLS_PER_TURN = 15; // TurnLoop budget (counts ALL tools)
+/** Directory names never listed, walked, or matched (noise + huge). */
+export const IGNORED_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    '.next',
+    '__pycache__',
+    '.venv',
+]);
+/** File names never listed or matched. */
+export const IGNORED_FILES = new Set(['.DS_Store']);
+export const BUDGET_EXHAUSTED_MESSAGE = 'Tool budget for this turn is exhausted. Summarize with what you have.';
+// --- Context pruning (microcompact, spec 2026-07-19-context-pruning-design.md) ---
+// Trigger-based batch clearing, NEVER a sliding window: editing an old message
+// invalidates the upstream prompt cache from that point, so continuous pruning
+// would re-bill the whole suffix at full upstream price every turn. User-facing
+// billing is flat per prompt_tokens (verified in yanfa UsageCapture/settlement),
+// so pruning is pure user savings; cache stability protects latency and margin.
+export const PRUNE_TRIGGER_TOKENS = 30_000; // last prompt_tokens above this → prune batch
+export const PRUNE_KEEP_RECENT = 3; // most recent fs results kept intact
+export const PRUNE_MIN_CONTENT_BYTES = 200; // smaller results are cheaper kept than cleared
+export const PRUNE_PLACEHOLDER = '[Old tool result cleared to save context — re-run the tool if needed.]';
+// --- Unattended media budget (spec 2026-07-19-mcp-media-tools-design.md) ---
+// MCP and exec have no human confirmation dialog; the session budget IS the spend
+// control. 4000 ≈ ten default-model images (400 each) or 2-3 mid-range videos
+// (500-1500 each) — measured live via `--estimate` on 2026-07-19.
+export const DEFAULT_SESSION_MAX_CREDITS = 4000;
+// Server-side wait slices: generate AND check_task each absorb up to this much waiting
+// before answering "generating". Real-client finding (2026-07-20, headless Claude Code):
+// agents without a sleep capability END THEIR TURN when told to wait between polls,
+// orphaning the paid task — so the server waits and the agent re-calls immediately
+// (poll hint 0). 45s slices stay inside conservative client timeouts; Claude Code's own
+// MCP tool timeout defaults to ~27.8h, but other clients are far stingier.
+export const MEDIA_GRACE_WAIT_MS = 45_000;
+export const MEDIA_POLL_HINT_SECONDS = 0; // re-call immediately — the server does the waiting
+//# sourceMappingURL=limits.js.map

package/dist/src/fs/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../../src/fs/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,kCAAkC;AAClF,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,wDAAwD;AACnH,0FAA0F;AAC1F,wFAAwF;AACxF,4FAA4F;AAC5F,kFAAkF;AAClF,wFAAwF;AACxF,+EAA+E;AAC/E,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC,CAAC,mCAAmC;AACvE,mFAAmF;AACnF,+EAA+E;AAC/E,4EAA4E;AAC5E,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,6CAA6C;AAC9F,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC,CAAC,0CAA0C;AAC9E,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC,CAAC,WAAW;AAC/C,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC,CAAC,uDAAuD;AAC5F,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC,CAAC,uDAAuD;AAC1F,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC,CAAC,OAAO;AAC5C,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC,CAAC,8BAA8B;AACtE,+EAA+E;AAC/E,iFAAiF;AACjF,gFAAgF;AAChF,gFAAgF;AAChF,+EAA+E;AAC/E,8EAA8E;AAC9E,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC;AACrC,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC,CAAC,qCAAqC;AAEhF,uEAAuE;AACvE,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC;IAClC,cAAc;IACd,MAAM;IACN,MAAM;IACN,OAAO;IACP,OAAO;IACP,aAAa;IACb,OAAO;CACR,CAAC,CAAC;AACH,0CAA0C;AAC1C,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;AAEpD,MAAM,CAAC,MAAM,wBAAwB,GACnC,uEAAuE,CAAC;AAE1E,oFAAoF;AACpF,+EAA+E;AAC/E,+EAA+E;AAC/E,gFAAgF;AAChF,iFAAiF;AACjF,gFAAgF;AAChF,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,CAAC,8CAA8C;AAC1F,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,CAAC,qCAAqC;AACzE,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC,CAAC,gDAAgD;AAC5F,MAAM,CAAC,MAAM,iBAAiB,GAC5B,wEAAwE,CAAC;AAE3E,8EAA8E;AAC9E,kFAAkF;AAClF,8EAA8E;AAC9E,kEAAkE;AAClE,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC;AAChD,uFAAuF;AACvF,yFAAyF;AACzF,oFAAoF;AACpF,mFAAmF;AACnF,wFAAwF;AACxF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAC1C,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,CAAC,oDAAoD"}

package/dist/src/fs/listDirTool.d.ts

@@ -0,0 +1,2 @@
+import type { ClientTool } from '../core/types.js';
+export declare function createListDirTool(root: string): ClientTool;

package/dist/src/fs/listDirTool.js

@@ -0,0 +1,68 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { GuardError, resolveInWorkspace, sanitizeFsError } from './workspaceGuard.js';
+import { IGNORED_DIRS, IGNORED_FILES, MAX_DIR_ENTRIES } from './limits.js';
+/** 14 → "14B", 2048 → "2.0KB", 3145728 → "3.0MB". */
+function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+export function createListDirTool(root) {
+    return {
+        name: 'list_dir',
+        readOnly: true,
+        description: 'List the entries of a directory inside the workspace (the directory the CLI was started in). ' +
+            'Directories are suffixed with "/"; files include their size, so questions like "the largest file" ' +
+            'are answerable directly. Common noise (node_modules, .git, dist) is omitted. ' +
+            'Use this to explore before reading files.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Directory to list, relative to the workspace root. Defaults to ".".',
+                },
+            },
+        },
+        async execute(args) {
+            const userPath = typeof args.path === 'string' && args.path.trim() ? args.path : '.';
+            try {
+                const dir = await resolveInWorkspace(root, userPath);
+                const stat = await fs.stat(dir);
+                if (!stat.isDirectory())
+                    return { error: `Not a directory: ${userPath}` };
+                const entries = (await fs.readdir(dir, { withFileTypes: true }))
+                    .filter((e) => !(e.isDirectory() ? IGNORED_DIRS.has(e.name) : IGNORED_FILES.has(e.name)));
+                if (entries.length > MAX_DIR_ENTRIES) {
+                    return {
+                        error: `Directory has ${entries.length} entries (>${MAX_DIR_ENTRIES}). List a subdirectory or use glob with a narrower pattern.`,
+                    };
+                }
+                entries.sort((a, b) => a.isDirectory() === b.isDirectory() ? a.name.localeCompare(b.name) : a.isDirectory() ? -1 : 1);
+                const lines = await Promise.all(entries.map(async (e) => {
+                    if (e.isDirectory())
+                        return `${e.name}/`;
+                    try {
+                        const s = await fs.stat(path.join(dir, e.name));
+                        return `${e.name}  ${formatSize(s.size)}`;
+                    }
+                    catch {
+                        // Dangling symlink or a file deleted mid-listing: name only, never fatal.
+                        return e.name;
+                    }
+                }));
+                return { summary: `${lines.length} entries`, content: lines.join('\n') };
+            }
+            catch (err) {
+                if (err instanceof GuardError)
+                    return { error: err.message };
+                const message = err instanceof Error ? err.message : String(err);
+                return { error: `list_dir failed: ${sanitizeFsError(message, root)}` };
+            }
+        },
+    };
+}
+//# sourceMappingURL=listDirTool.js.map

package/dist/src/fs/listDirTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listDirTool.js","sourceRoot":"","sources":["../../../src/fs/listDirTool.ts"],"names":[],"mappings":"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"}

package/dist/src/fs/readFileTool.d.ts

@@ -0,0 +1,2 @@
+import type { ClientTool } from '../core/types.js';
+export declare function createReadFileTool(root: string): ClientTool;

package/dist/src/fs/readFileTool.js

@@ -0,0 +1,102 @@
+import { promises as fs } from 'node:fs';
+import { GuardError, resolveInWorkspace, sanitizeFsError } from './workspaceGuard.js';
+import { MAX_FILE_SIZE_BYTES, MAX_LINE_CHARS, MAX_RANGED_FILE_SIZE_BYTES, MAX_READ_LINES, MAX_READ_OUTPUT_BYTES, } from './limits.js';
+/** NUL byte in the first 8KB → treat as binary (same heuristic as git). */
+function looksBinary(buf) {
+    return buf.subarray(0, 8192).includes(0);
+}
+export function createReadFileTool(root) {
+    return {
+        name: 'read_file',
+        readOnly: true,
+        description: 'Read a text file inside the workspace. Returns numbered lines ("cat -n" style) so you can cite line numbers. ' +
+            'Reads the whole file by default when it fits (file up to 1MB, output up to 100KB); for bigger files ' +
+            `read a range with offset/limit (up to ${MAX_READ_LINES} lines per read; range reads work on files up to 8MB). ` +
+            'For machine-generated files (lockfiles, minified bundles, large logs) read a small range or grep ' +
+            'instead of the whole file — their bulk rarely helps and the tokens are wasted. ' +
+            'Binary files cannot be read — images can be attached instead (@path in the TUI, --image in exec).',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path relative to the workspace root.' },
+                offset: { type: 'number', description: '1-based first line to read (default 1).' },
+                limit: {
+                    type: 'number',
+                    description: `Max lines to return (up to ${MAX_READ_LINES}). Omit to read the whole file.`,
+                },
+            },
+            required: ['path'],
+        },
+        async execute(args) {
+            if (typeof args.path !== 'string' || !args.path.trim()) {
+                return { error: 'Missing required "path" argument.' };
+            }
+            const explicitLimit = typeof args.limit === 'number' && args.limit > 0;
+            const offset = typeof args.offset === 'number' && args.offset >= 1 ? Math.floor(args.offset) : 1;
+            const limit = explicitLimit ? Math.floor(args.limit) : undefined;
+            if (explicitLimit && limit !== undefined && limit > MAX_READ_LINES) {
+                return {
+                    error: `Requested ${limit} lines (max ${MAX_READ_LINES} per read). Read in chunks with offset/limit.`,
+                };
+            }
+            try {
+                const file = await resolveInWorkspace(root, args.path);
+                const stat = await fs.stat(file);
+                if (stat.isDirectory())
+                    return { error: `Is a directory, not a file: ${args.path}` };
+                // A FIFO/socket/device would make fs.readFile hang forever waiting for a peer — and
+                // dispatch here is not abortable. Reject anything that isn't a plain file up front.
+                if (!stat.isFile())
+                    return { error: `Not a regular file: ${args.path}` };
+                if (explicitLimit) {
+                    if (stat.size > MAX_RANGED_FILE_SIZE_BYTES) {
+                        return {
+                            error: `File is ${stat.size} bytes (>8MB) — too large even for range reads. Use grep to locate the relevant part.`,
+                        };
+                    }
+                }
+                else if (stat.size > MAX_FILE_SIZE_BYTES) {
+                    return {
+                        error: `File is ${stat.size} bytes (>1MB limit). Use grep to find the relevant part, or read a line range with offset/limit.`,
+                    };
+                }
+                const buf = await fs.readFile(file);
+                if (looksBinary(buf)) {
+                    return {
+                        error: 'Binary file (not text). If this is an image, attach it instead (@path in the TUI, --image in exec).',
+                    };
+                }
+                const all = buf.toString('utf8').split('\n');
+                // Trailing newline produces a phantom empty last element; drop it.
+                if (all.length > 1 && all[all.length - 1] === '')
+                    all.pop();
+                // No default line-count gate: a default read returns the whole file, bounded by the
+                // 1MB pre-read and 100KB output checks. Erroring at N lines just forced the model
+                // into error + multiple range reads for the same total tokens (2026-07-19 dogfood).
+                const slice = limit === undefined ? all.slice(offset - 1) : all.slice(offset - 1, offset - 1 + limit);
+                if (slice.length === 0)
+                    return { error: `Offset ${offset} is past the end (${all.length} lines).` };
+                const content = slice
+                    .map((line, i) => {
+                    const text = line.length > MAX_LINE_CHARS ? `${line.slice(0, MAX_LINE_CHARS)}… [line truncated]` : line;
+                    return `${String(offset + i).padStart(6)}\t${text}`;
+                })
+                    .join('\n');
+                const outputBytes = Buffer.byteLength(content, 'utf8');
+                if (outputBytes > MAX_READ_OUTPUT_BYTES) {
+                    return {
+                        error: `This range is ${outputBytes} bytes (max ${MAX_READ_OUTPUT_BYTES} per read). Request a smaller range with offset/limit.`,
+                    };
+                }
+                return { summary: `${slice.length} lines`, content };
+            }
+            catch (err) {
+                if (err instanceof GuardError)
+                    return { error: err.message };
+                const message = err instanceof Error ? err.message : String(err);
+                return { error: `read_file failed: ${sanitizeFsError(message, root)}` };
+            }
+        },
+    };
+}
+//# sourceMappingURL=readFileTool.js.map

package/dist/src/fs/readFileTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readFileTool.js","sourceRoot":"","sources":["../../../src/fs/readFileTool.ts"],"names":[],"mappings":"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"}

package/dist/src/fs/walk.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Depth-first file walker shared by glob and grep. Yields regular files only,
+ * with workspace-relative paths. Skips IGNORED_DIRS/IGNORED_FILES. Symlinks —
+ * file or directory — are never yielded or followed (Dirent.isFile() is false
+ * for them): consumers read yielded paths directly without a guard re-check,
+ * so a yielded symlink could leak content from outside the workspace.
+ */
+export declare function walkFiles(root: string, startDir: string): AsyncGenerator<{
+    abs: string;
+    rel: string;
+}>;

package/dist/src/fs/walk.js

@@ -0,0 +1,38 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { IGNORED_DIRS, IGNORED_FILES } from './limits.js';
+/**
+ * Depth-first file walker shared by glob and grep. Yields regular files only,
+ * with workspace-relative paths. Skips IGNORED_DIRS/IGNORED_FILES. Symlinks —
+ * file or directory — are never yielded or followed (Dirent.isFile() is false
+ * for them): consumers read yielded paths directly without a guard re-check,
+ * so a yielded symlink could leak content from outside the workspace.
+ */
+export async function* walkFiles(root, startDir) {
+    let entries;
+    try {
+        entries = await fs.readdir(startDir, { withFileTypes: true });
+    }
+    catch {
+        // An unreadable directory (EPERM/EACCES on macOS ~/.Trash, vanished mid-walk)
+        // is skipped, not fatal — a home-dir workspace is full of these and one must
+        // not kill the whole glob/grep call (2026-07-19 TUI smoke finding).
+        return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+        const abs = path.join(startDir, e.name);
+        if (e.isDirectory()) {
+            if (IGNORED_DIRS.has(e.name))
+                continue;
+            yield* walkFiles(root, abs);
+        }
+        else if (e.isFile()) {
+            if (IGNORED_FILES.has(e.name))
+                continue;
+            yield { abs, rel: path.relative(root, abs) };
+        }
+        // symlinks (isSymbolicLink) are intentionally not followed here
+    }
+}
+//# sourceMappingURL=walk.js.map

package/dist/src/fs/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../../../src/fs/walk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,SAAS,CAC9B,IAAY,EACZ,QAAgB;IAEhB,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,8EAA8E;QAC9E,6EAA6E;QAC7E,oEAAoE;QACpE,OAAO;IACT,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACrD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;YACpB,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;gBAAE,SAAS;YACvC,KAAK,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC9B,CAAC;aAAM,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;YACtB,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;gBAAE,SAAS;YACxC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;QAC/C,CAAC;QACD,gEAAgE;IAClE,CAAC;AACH,CAAC"}

package/dist/src/fs/workspaceGuard.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The ONLY safety module for the fs read tools. Every path a tool touches goes
+ * through resolveInWorkspace(); the tools themselves contain zero safety code.
+ * Phase-B write tools MUST route through this same gate.
+ */
+/** A path-safety violation or lookup failure, with a model-readable message. */
+export declare class GuardError extends Error {
+}
+/** The workspace root: realpath of the CLI start directory, anchored ONCE at startup. */
+export declare function workspaceRoot(cwd?: string): Promise<string>;
+/**
+ * Resolve a user/model-supplied path and prove it stays inside the workspace.
+ *
+ * Order matters: resolve against root -> realpath (follows symlinks) -> prefix
+ * check WITH a trailing separator (so `/ws-evil` cannot pass as `/ws`). The
+ * denial message never echoes the resolved real path — that would leak
+ * outside-workspace structure to the model.
+ */
+export declare function resolveInWorkspace(root: string, userPath: string): Promise<string>;
+/**
+ * Strip the workspace root out of a raw error message before it reaches the model. Node fs
+ * errors embed the absolute path (e.g. `EACCES: permission denied, open '/Users/eric/proj/f'`),
+ * which would otherwise leak the local machine's directory layout and username to the backend.
+ * Used by every tool's generic catch-all — GuardError messages never need this, they are
+ * already written to omit the resolved real path (see DENIED above).
+ */
+export declare function sanitizeFsError(message: string, root: string): string;

package/dist/src/fs/workspaceGuard.js

@@ -0,0 +1,96 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+/**
+ * The ONLY safety module for the fs read tools. Every path a tool touches goes
+ * through resolveInWorkspace(); the tools themselves contain zero safety code.
+ * Phase-B write tools MUST route through this same gate.
+ */
+/** A path-safety violation or lookup failure, with a model-readable message. */
+export class GuardError extends Error {
+}
+const DENIED = 'Access denied: path is outside the workspace (CLI start directory)';
+/** The workspace root: realpath of the CLI start directory, anchored ONCE at startup. */
+export async function workspaceRoot(cwd = process.cwd()) {
+    return fs.realpath(cwd);
+}
+/**
+ * Walk up from `dir` to the nearest ancestor that actually exists on disk and
+ * return ITS realpath. Used by the ENOENT branch below: the lexical candidate
+ * cannot be trusted for the containment check because a directory component
+ * partway up the path may itself be a symlink pointing outside the
+ * workspace — realpath-ing only the missing leaf would miss that.
+ */
+async function nearestExistingAncestorRealpath(dir) {
+    for (;;) {
+        try {
+            return await fs.realpath(dir);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT') {
+                throw err;
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir) {
+                // Reached the filesystem root without finding an existing ancestor.
+                throw err;
+            }
+            dir = parent;
+        }
+    }
+}
+/**
+ * Resolve a user/model-supplied path and prove it stays inside the workspace.
+ *
+ * Order matters: resolve against root -> realpath (follows symlinks) -> prefix
+ * check WITH a trailing separator (so `/ws-evil` cannot pass as `/ws`). The
+ * denial message never echoes the resolved real path — that would leak
+ * outside-workspace structure to the model.
+ */
+export async function resolveInWorkspace(root, userPath) {
+    const candidate = path.resolve(root, userPath);
+    let real;
+    try {
+        real = await fs.realpath(candidate);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            // Read-only tools never need nonexistent paths — but only say "not found"
+            // when the path would have been INSIDE the workspace; otherwise deny, so
+            // probing outside paths cannot distinguish "missing" from "forbidden".
+            //
+            // The lexical `candidate` is not trustworthy for that decision: a
+            // directory earlier in the path may itself be a symlink escaping the
+            // workspace (e.g. `root/escapedir -> /outside`), in which case probing
+            // `escapedir/missing.txt` vs `escapedir/exists.txt` would otherwise leak
+            // whether files exist outside the workspace. So resolve the nearest
+            // ancestor that actually exists and judge containment from ITS realpath.
+            let ancestorReal;
+            try {
+                ancestorReal = await nearestExistingAncestorRealpath(path.dirname(candidate));
+            }
+            catch {
+                throw new GuardError(DENIED);
+            }
+            if (ancestorReal === root || ancestorReal.startsWith(root + path.sep)) {
+                throw new GuardError(`Not found: ${userPath}`);
+            }
+            throw new GuardError(DENIED);
+        }
+        throw new GuardError(`Cannot access: ${userPath}`);
+    }
+    if (real !== root && !real.startsWith(root + path.sep)) {
+        throw new GuardError(DENIED);
+    }
+    return real;
+}
+/**
+ * Strip the workspace root out of a raw error message before it reaches the model. Node fs
+ * errors embed the absolute path (e.g. `EACCES: permission denied, open '/Users/eric/proj/f'`),
+ * which would otherwise leak the local machine's directory layout and username to the backend.
+ * Used by every tool's generic catch-all — GuardError messages never need this, they are
+ * already written to omit the resolved real path (see DENIED above).
+ */
+export function sanitizeFsError(message, root) {
+    return message.split(root).join('.');
+}
+//# sourceMappingURL=workspaceGuard.js.map

package/dist/src/fs/workspaceGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceGuard.js","sourceRoot":"","sources":["../../../src/fs/workspaceGuard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;GAIG;AAEH,gFAAgF;AAChF,MAAM,OAAO,UAAW,SAAQ,KAAK;CAAG;AAExC,MAAM,MAAM,GACV,oEAAoE,CAAC;AAEvE,yFAAyF;AACzF,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAc,OAAO,CAAC,GAAG,EAAE;IAC7D,OAAO,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,+BAA+B,CAAC,GAAW;IACxD,SAAS,CAAC;QACR,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACrD,MAAM,GAAG,CAAC;YACZ,CAAC;YACD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACjC,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;gBACnB,oEAAoE;gBACpE,MAAM,GAAG,CAAC;YACZ,CAAC;YACD,GAAG,GAAG,MAAM,CAAC;QACf,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAY,EAAE,QAAgB;IACrE,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC/C,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACrD,0EAA0E;YAC1E,yEAAyE;YACzE,uEAAuE;YACvE,EAAE;YACF,kEAAkE;YAClE,qEAAqE;YACrE,uEAAuE;YACvE,yEAAyE;YACzE,oEAAoE;YACpE,yEAAyE;YACzE,IAAI,YAAoB,CAAC;YACzB,IAAI,CAAC;gBACH,YAAY,GAAG,MAAM,+BAA+B,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;YAChF,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;YAC/B,CAAC;YACD,IAAI,YAAY,KAAK,IAAI,IAAI,YAAY,CAAC,UAAU,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBACtE,MAAM,IAAI,UAAU,CAAC,cAAc,QAAQ,EAAE,CAAC,CAAC;YACjD,CAAC;YACD,MAAM,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;QAC/B,CAAC;QACD,MAAM,IAAI,UAAU,CAAC,kBAAkB,QAAQ,EAAE,CAAC,CAAC;IACrD,CAAC;IACD,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,IAAY;IAC3D,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACvC,CAAC"}

package/dist/src/index.js

@@ -2,6 +2,10 @@
 import { Command } from 'commander';
 import { basename } from 'node:path';
 import { VERSION } from './version.js';
+import { guardBrokenPipe } from './util/brokenPipe.js';
+// `glbgpt exec ... | head` must end quietly when the pipe closes, not crash (EPIPE).
+guardBrokenPipe(process.stdout);
+guardBrokenPipe(process.stderr);
 /**
  * glbgpt CLI entry (scaffold).
  *
@@ -15,6 +19,18 @@ const program = new Command();
 // The CLI installs two bins — `glbgpt` and its alias `globalgpt` — so help/usage should
 // name whichever the user actually invoked (fall back to the canonical name).
 const invokedName = process.argv[1] ? basename(process.argv[1]).replace(/\.js$/, '') : 'glbgpt';
+/**
+ * Parse the raw `--max-credits` flag value from commander. `undefined` (flag omitted) passes
+ * through unchanged; a provided value that isn't a non-negative integer is a usage error
+ * ('invalid') the caller must reject before running the command — 0 itself is valid and means
+ * "no media spending this session" (resolveMaxCredits/SessionBudget handle that).
+ */
+function parseMaxCreditsFlag(raw) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && Number.isInteger(n) && n >= 0 ? n : 'invalid';
+}
 program
     .name(invokedName === 'globalgpt' ? 'globalgpt' : 'glbgpt')
     .description('GlobalGPT in your terminal: chat, image and video generation.')
@@ -67,7 +83,14 @@ program
     .option('--json', 'Emit a single final result object to stdout')
     .option('--jsonl', 'Emit streaming protocol events, one JSON per line')
     .option('-o, --output-last-message <file>', 'Write the final message text to a file')
+    .option('--max-credits <n>', 'Session credit budget for media generation (default 4000; 0 disables media generation)')
     .action(async (prompt, opts) => {
+    const maxCredits = parseMaxCreditsFlag(opts.maxCredits);
+    if (maxCredits === 'invalid') {
+        console.error('Invalid --max-credits: must be a non-negative integer.');
+        process.exitCode = 1;
+        return;
+    }
     const { runExec } = await import('./commands/execCommand.js');
     const code = await runExec(prompt, {
         model: opts.model,
@@ -78,15 +101,36 @@ program
         json: opts.json,
         jsonl: opts.jsonl,
         outputLastMessage: opts.outputLastMessage,
+        maxCredits,
     });
     process.exitCode = code;
 });
 program
     .command('mcp')
-    .description('Run an MCP server (stdio) exposing GlobalGPT chat as a tool for external agents')
-    .action(async () => {
+    .description('Run an MCP server (stdio) exposing GlobalGPT chat and media generation to external agents')
+    .option('--max-credits <n>', 'Session credit budget for media generation (default 4000; 0 disables media generation)')
+    .action(async (opts) => {
+    const maxCredits = parseMaxCreditsFlag(opts.maxCredits);
+    if (maxCredits === 'invalid') {
+        console.error('Invalid --max-credits: must be a non-negative integer.');
+        process.exitCode = 1;
+        return;
+    }
     const { runMcpServer } = await import('./mcp/server.js');
-    await runMcpServer();
+    await runMcpServer({ maxCredits });
+});
+const skill = program.command('skill').description('Manage the bundled Agent Skills for coding agents');
+skill
+    .command('install')
+    .description('Install the bundled skills into your agent skill directories')
+    .option('--skill <name>', 'Install only this skill (default: all)')
+    .option('--copy', 'Copy files instead of symlinking')
+    .action(async (opts) => {
+    const { runSkillInstall } = await import('./commands/skillCommand.js');
+    process.exitCode = await runSkillInstall({
+        skill: opts.skill,
+        copy: opts.copy,
+    });
 });
 program
     .command('resume [target]')