@glbgpt/cli 0.2.3 → 0.2.5

package/dist/src/core/progressGuard.js

@@ -0,0 +1,197 @@
+import { createHash } from 'node:crypto';
+const WARN_AT = 3;
+const PAUSE_AT = 5;
+const MAX_TRACKED_OPERATIONS = 256;
+const MUTATION_TOOLS = new Set(['write_file', 'edit_file', 'bash_kill']);
+const NOTICE_FIELDS = new Set(['repeated_call_notice', 'progress_notice', 'context_pruning_notice']);
+/**
+ * Per-turn evidence of repetition, not a judgment that the overall task is solved.
+ * Unrelated reads/planning do not erase a stalled operation. A changed result resets
+ * that operation; a successful new file mutation makes earlier observations stale.
+ * Store only bounded maps of hashes, never complete commands or tool output.
+ */
+export class ProgressGuard {
+    observations = new Map();
+    mutations = new Map();
+    observe(name, rawArgs, result) {
+        const args = parseArguments(rawArgs);
+        if (name === 'update_plan' || isRunningPoll(name, args, result))
+            return;
+        const argumentHash = fingerprint(args);
+        const substantive = Object.fromEntries(Object.entries(result).filter(([key]) => !NOTICE_FIELDS.has(key)));
+        const resultHash = fingerprint(substantive);
+        if (!argumentHash || !resultHash)
+            return; // Unserializable/deep values cannot be compared safely.
+        const failed = typeof result.error === 'string' || result.cancelled === true;
+        if (!failed && MUTATION_TOOLS.has(name)) {
+            // A write following an edit to the same file is new progress even when it
+            // restores an earlier payload. Compare with the latest mutation of that
+            // target, rather than the last invocation of each mutation tool.
+            const target = fingerprint(name === 'bash_kill'
+                ? { kind: 'task', task_id: args.task_id }
+                : { kind: 'file', path: args.path });
+            const mutation = `${name}:${argumentHash}`;
+            if (target && this.mutations.get(target) !== mutation) {
+                this.observations.clear();
+                remember(this.mutations, target, mutation);
+            }
+        }
+        let notice = this.record(`call:${fingerprint(name)}:${argumentHash}`, resultHash, name, 'same arguments and result', evidence(result));
+        if (name === 'bash' && typeof args.command === 'string') {
+            const scope = bashScope(args.command);
+            if (scope) {
+                const key = `bash-error:${scope}`;
+                if (typeof result.error === 'string' && result.error.trim()) {
+                    const diagnostic = bashDiagnostic(result.error);
+                    const diagnosticHash = fingerprint({ diagnostic, exit_code: result.exit_code, signal: result.signal });
+                    if (diagnosticHash) {
+                        const failure = this.record(key, diagnosticHash, name, 'same failure for the same command target', diagnostic);
+                        if (failure && (!notice || failure.kind === 'pause'))
+                            notice = failure;
+                    }
+                }
+                else if (!failed) {
+                    this.observations.delete(key);
+                }
+            }
+        }
+        return notice;
+    }
+    record(key, result, name, detail, sample) {
+        const prior = this.observations.get(key);
+        const count = prior?.result === result ? prior.count + 1 : 1;
+        remember(this.observations, key, { result, count });
+        if (count !== WARN_AT && count !== PAUSE_AT)
+            return;
+        const kind = count === PAUSE_AT ? 'pause' : 'warning';
+        return {
+            kind,
+            message: `${shortText(name)} has returned the ${detail} ${count} times without observable progress` +
+                `${sample ? `: ${shortText(sample)}` : '.'} ` +
+                (kind === 'pause'
+                    ? 'Further tool calls are paused so you can review the blocker and unfinished work.'
+                    : 'Change the approach before trying again; two more unchanged results will pause this turn.'),
+        };
+    }
+}
+function remember(map, key, value) {
+    map.delete(key);
+    map.set(key, value);
+    if (map.size > MAX_TRACKED_OPERATIONS)
+        map.delete(map.keys().next().value);
+}
+function parseArguments(raw) {
+    try {
+        const parsed = JSON.parse(raw || '{}');
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed))
+            return parsed;
+    }
+    catch { /* Invalid JSON can still repeat; preserve its identity below. */ }
+    return { unparsed_arguments: raw };
+}
+/** Hash all string bytes, including long output tails, without retaining/serializing a second copy. */
+function fingerprint(value) {
+    const hash = createHash('sha256');
+    const seen = new WeakSet();
+    let nodes = 0;
+    const visit = (item, depth) => {
+        if (++nodes > 20_000 || depth > 64)
+            throw new Error('Fingerprint limit');
+        if (item === null) {
+            hash.update('null;');
+            return;
+        }
+        if (typeof item !== 'object') {
+            const text = String(item);
+            hash.update(`${typeof item}:${Buffer.byteLength(text)}:`).update(text).update(';');
+            return;
+        }
+        if (seen.has(item))
+            throw new Error('Cyclic result');
+        seen.add(item);
+        if (Array.isArray(item)) {
+            hash.update('array[');
+            for (const child of item)
+                visit(child, depth + 1);
+        }
+        else {
+            const prototype = Object.getPrototypeOf(item);
+            if (prototype !== Object.prototype && prototype !== null)
+                throw new Error('Non-JSON result');
+            hash.update('object{');
+            for (const key of Object.keys(item).sort()) {
+                visit(key, depth + 1);
+                visit(item[key], depth + 1);
+            }
+        }
+        hash.update('};');
+        seen.delete(item);
+    };
+    try {
+        visit(value, 0);
+        return hash.digest('hex');
+    }
+    catch {
+        return;
+    }
+}
+function isRunningPoll(name, args, result) {
+    if (typeof result.error === 'string' || result.cancelled === true || typeof args.task_id !== 'string')
+        return false;
+    if (name === 'bash_output') {
+        // The current bash_output contract appends this exact status line to its output.
+        return result.status === 'running' ||
+            (typeof result.output === 'string' && /(?:^|\n)Status: running\s*$/.test(result.output));
+    }
+    // Only the actual media polling tool is exempt, never generate_* submissions or
+    // arbitrary tools that happen to include a status/task_id field.
+    return name === 'glbgpt_check_task' && result.status === 'generating';
+}
+/** A stable execution target for Python retries; unrelated scripts retain separate histories. */
+function bashScope(command) {
+    const firstLine = command.trim().split(/\r?\n/, 1)[0];
+    const tokens = firstLine.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+    const firstToken = tokens[0];
+    if (!firstToken)
+        return;
+    const executable = firstToken.split('/').at(-1) ?? '';
+    if (/^python(?:\d+(?:\.\d+)*)?$/.test(executable)) {
+        // Keep interpreter flags/module/script selection, but not inline source or heredoc body.
+        const target = [firstToken];
+        for (const token of tokens.slice(1)) {
+            if (token === '-c' || token === '-' || token.startsWith('<<')) {
+                target.push(token === '-c' ? '-c' : 'stdin');
+                return fingerprint(target);
+            }
+            target.push(token);
+            if (!token.startsWith('-'))
+                return fingerprint(target);
+        }
+    }
+    // For other commands, only identical first command lines share an error history.
+    // Exact invocation/result tracking above still handles their ordinary repetitions.
+    return fingerprint(firstLine);
+}
+function bashDiagnostic(error) {
+    const tail = error.slice(-16_384).replace(/\u001b\[[0-9;]*m/g, '');
+    const lines = tail.split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+    let diagnostic;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (/^[\w.]+(?:Error|Exception):\s*\S/.test(lines[i])) {
+            diagnostic = lines[i];
+            break;
+        }
+    }
+    return diagnostic ?? error.trim();
+}
+function evidence(result) {
+    for (const key of ['error', 'output', 'summary', 'content']) {
+        if (typeof result[key] === 'string')
+            return result[key];
+    }
+    return '';
+}
+function shortText(text) {
+    return text.slice(0, 300).replace(/\u001b\[[0-9;]*m/g, '').replace(/[\x00-\x1f\x7f]+/g, ' ').trim().slice(0, 180);
+}
+//# sourceMappingURL=progressGuard.js.map

package/dist/src/core/progressGuard.js.map

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

package/dist/src/core/runChat.d.ts

@@ -1,4 +1,5 @@
 import { ToolRegistry } from './toolRegistry.js';
+import type { TaskAssessment, PauseReason } from './types.js';
 import { type OutputSchemaSpec } from './structuredOutput.js';
 import type { ChatBackend, ContentPart, EngineEvent } from './types.js';
 /** One chat-only turn's result. `structured` is set when a response schema was requested. */
@@ -9,6 +10,7 @@ export interface ChatTurnResult {
         prompt_tokens: number;
         completion_tokens: number;
     };
+    task?: TaskAssessment;
 }
 export interface ChatTurnParams {
     backend: ChatBackend;
@@ -29,6 +31,8 @@ export interface ChatTurnParams {
     responseFormat?: unknown;
     /** Client-side tools available to this turn. Defaults to an empty registry (no tools). */
     registry?: ToolRegistry;
+    maxTurnTokens?: number;
+    assessTask?: () => Promise<TaskAssessment | undefined>;
 }
 /**
  * Run a single chat turn (client tools optional via `params.registry`; defaults to none)
@@ -40,3 +44,7 @@ export interface ChatTurnParams {
  * Throws on a backend/turn error or when structured output does not parse.
  */
 export declare function runChatTurn(params: ChatTurnParams, onEvent?: (event: EngineEvent) => void | Promise<void>): Promise<ChatTurnResult>;
+export declare class TurnPausedError extends Error {
+    readonly reason: PauseReason;
+    constructor(reason: PauseReason, message: string);
+}

package/dist/src/core/runChat.js

@@ -1,6 +1,7 @@
 import { Session } from './session.js';
 import { TurnLoop } from './turnLoop.js';
 import { ToolRegistry } from './toolRegistry.js';
+import { TurnTokenBudget } from './tokenBudget.js';
 import { newId } from './id.js';
 import { planStructuredOutput, planForMode, parseStructuredJson, stripSyntheticNulls, isResponseFormatRejection, } from './structuredOutput.js';
 /**
@@ -14,7 +15,8 @@ import { planStructuredOutput, planForMode, parseStructuredJson, stripSyntheticN
  */
 export async function runChatTurn(params, onEvent) {
     const plan = params.outputSchema ? planStructuredOutput(params.model, params.outputSchema) : undefined;
-    const first = await runOnce(params, plan, onEvent);
+    const tokenBudget = new TurnTokenBudget(params.maxTurnTokens);
+    const first = await runOnce(params, plan, tokenBudget, onEvent);
     const failure = first.thrown instanceof Error ? first.thrown.message : first.engineError;
     if (failure &&
         plan?.mode === 'json_schema' &&
@@ -25,7 +27,7 @@ export async function runChatTurn(params, onEvent) {
         // regardless of the flag, others lack json_schema entirely). Nothing streamed, the failed
         // call is refunded server-side → one retry in json_object mode with the schema in the prompt.
         const fallback = planForMode('json_object', params.outputSchema);
-        const second = await runOnce(params, fallback, onEvent);
+        const second = await runOnce(params, fallback, tokenBudget, onEvent);
         // Keep any usage the rejected request reported, matching the streamed usage events.
         // These are token totals, not a claim about whether the backend charged/refunded it.
         second.usage.prompt_tokens += first.usage.prompt_tokens;
@@ -34,7 +36,7 @@ export async function runChatTurn(params, onEvent) {
     }
     return finish(first, plan, params);
 }
-async function runOnce(params, plan, onEvent) {
+async function runOnce(params, plan, tokenBudget, onEvent) {
     const session = new Session({ id: newId(), model: params.model });
     const responseFormat = plan ? plan.responseFormat : params.responseFormat;
     const system = [params.system?.trim(), plan?.systemAddendum].filter((s) => !!s).join('\n\n');
@@ -63,6 +65,12 @@ async function runOnce(params, plan, onEvent) {
                     result.usage.prompt_tokens += event.promptTokens;
                     result.usage.completion_tokens += event.completionTokens;
                     break;
+                case 'turn_paused':
+                    result.paused = event;
+                    break;
+                case 'task_status':
+                    result.task = event.assessment;
+                    break;
                 case 'error':
                     result.engineError = event.message;
                     break;
@@ -71,7 +79,7 @@ async function runOnce(params, plan, onEvent) {
                 // turn_complete is implicit in runTurn resolving.
             }
             return onEvent?.(event);
-        }, { responseFormat });
+        }, { responseFormat, tokenBudget, assessTask: params.assessTask });
     }
     catch (err) {
         result.thrown = err;
@@ -79,6 +87,8 @@ async function runOnce(params, plan, onEvent) {
     return result;
 }
 function finish(r, plan, params) {
+    if (r.paused)
+        throw new TurnPausedError(r.paused.reason, r.paused.message);
     if (r.thrown !== undefined)
         throw r.thrown;
     if (r.engineError)
@@ -90,6 +100,14 @@ function finish(r, plan, params) {
         if (params.outputSchema)
             stripSyntheticNulls(structured, params.outputSchema.schema);
     }
-    return { content: r.content, structured, usage: r.usage };
+    return { content: r.content, structured, usage: r.usage, ...(r.task ? { task: r.task } : {}) };
+}
+export class TurnPausedError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = 'TurnPausedError';
+    }
 }
 //# sourceMappingURL=runChat.js.map

package/dist/src/core/runChat.js.map

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

package/dist/src/core/tokenBudget.d.ts

@@ -0,0 +1,45 @@
+import type { ChatChunk, ChatMessage, ChatRequest } from './types.js';
+export declare const DEFAULT_MAX_TURN_TOKENS = 200000;
+export declare const MIN_MAX_TURN_TOKENS = 1000;
+export declare const MAX_MAX_TURN_TOKENS = 10000000;
+export declare function parseMaxTurnTokens(value: string | number, source?: string): number;
+/** Explicit turn option > environment > saved configuration > the bounded default. */
+export declare function resolveMaxTurnTokens(override?: number): number;
+/**
+ * Approximate input size: text uses the same bytes/4 heuristic as context compaction;
+ * image parts use a bounded vision allowance instead of tokenizing their URL/base64.
+ * Include message framing, tool definitions and output schemas because they are resent
+ * on each request. Provider tokenization, image tokens and server prompts can differ.
+ */
+export declare function estimateRequestTokens(req: ChatRequest): number;
+export interface TokenBudgetSnapshot {
+    usedTokens: number;
+    limitTokens: number;
+    remainingTokens: number;
+    /** True when any missing provider usage was replaced by a local estimate. */
+    estimated: boolean;
+}
+export interface TokenBudgetPreflight extends TokenBudgetSnapshot {
+    allowed: boolean;
+    reason?: 'exhausted' | 'request_too_large';
+    estimatedPromptTokens: number;
+}
+/**
+ * Cumulative request-token protection for one user turn, including tool rounds and retries.
+ * Share this instance across retries; record each request once using its final usage snapshot.
+ * This pauses further requests, not an in-flight response, and is not a hard billing cap.
+ */
+export declare class TurnTokenBudget {
+    readonly limitTokens: number;
+    private usedTokens;
+    private estimated;
+    private warned;
+    constructor(limit?: number);
+    snapshot(): TokenBudgetSnapshot;
+    /** Check the exact request projection about to be sent, after pruning and any added prompts. */
+    preflight(req: ChatRequest): TokenBudgetPreflight;
+    /** Call once per model request, also on interruption/failure when some usage may be known. */
+    recordCall(req: ChatRequest, output: Pick<ChatMessage, 'content' | 'tool_calls'>, usage?: ChatChunk['usage']): TokenBudgetSnapshot;
+    /** Emit at most one warning per turn when cumulative usage reaches 80% of the limit. */
+    takeWarning(): TokenBudgetSnapshot | null;
+}

package/dist/src/core/tokenBudget.js

@@ -0,0 +1,111 @@
+import { getConfigValueSync } from '../config/configFile.js';
+import { estimateMessageTokens } from './compaction.js';
+export const DEFAULT_MAX_TURN_TOKENS = 200_000;
+export const MIN_MAX_TURN_TOKENS = 1_000;
+export const MAX_MAX_TURN_TOKENS = 10_000_000;
+// Cross-model headroom for one vision input, not a provider token formula or upper bound.
+// Actual image usage depends on the model, dimensions, detail and preprocessing, not the
+// compressed file size or base64 length. Keep each image's estimate bounded; count every
+// image separately and replace estimates with provider usage whenever it is available.
+const IMAGE_TOKEN_ESTIMATE = 16_384;
+const LOW_DETAIL_IMAGE_TOKEN_ESTIMATE = 4_096;
+export function parseMaxTurnTokens(value, source = 'max-turn-tokens') {
+    const raw = typeof value === 'string' ? value.trim() : value;
+    const parsed = typeof raw === 'string' && /^\d+$/.test(raw) ? Number(raw) : raw;
+    if (typeof parsed !== 'number' ||
+        !Number.isSafeInteger(parsed) ||
+        parsed < MIN_MAX_TURN_TOKENS ||
+        parsed > MAX_MAX_TURN_TOKENS) {
+        throw new Error(`${source} must be an integer between ${MIN_MAX_TURN_TOKENS} and ${MAX_MAX_TURN_TOKENS}.`);
+    }
+    return parsed;
+}
+/** Explicit turn option > environment > saved configuration > the bounded default. */
+export function resolveMaxTurnTokens(override) {
+    if (override !== undefined)
+        return parseMaxTurnTokens(override, 'maxTurnTokens');
+    const env = process.env.GLBGPT_MAX_TURN_TOKENS;
+    if (env !== undefined)
+        return parseMaxTurnTokens(env, 'GLBGPT_MAX_TURN_TOKENS');
+    const stored = getConfigValueSync('max-turn-tokens');
+    return stored === undefined ? DEFAULT_MAX_TURN_TOKENS : parseMaxTurnTokens(stored);
+}
+/**
+ * Approximate input size: text uses the same bytes/4 heuristic as context compaction;
+ * image parts use a bounded vision allowance instead of tokenizing their URL/base64.
+ * Include message framing, tool definitions and output schemas because they are resent
+ * on each request. Provider tokenization, image tokens and server prompts can differ.
+ */
+export function estimateRequestTokens(req) {
+    const messages = req.messages.reduce((sum, message) => sum + estimateBudgetMessageTokens(message) + 4, 3);
+    return messages + estimateJsonTokens(req.tools) + estimateJsonTokens(req.response_format);
+}
+/** Never serialize image content: a supported 8 MiB image is not millions of text tokens. */
+function estimateBudgetMessageTokens(message) {
+    if (!Array.isArray(message.content))
+        return estimateMessageTokens(message);
+    const toolTokens = estimateMessageTokens({ ...message, content: null });
+    return message.content.reduce((sum, part) => {
+        if (part.type === 'text')
+            return sum + estimateMessageTokens({ role: message.role, content: part.text });
+        // `detail` is optional on OpenAI-compatible image inputs; older CLI types omit it.
+        const lowDetail = 'detail' in part.image_url && part.image_url.detail === 'low';
+        return sum + (lowDetail ? LOW_DETAIL_IMAGE_TOKEN_ESTIMATE : IMAGE_TOKEN_ESTIMATE);
+    }, toolTokens);
+}
+function estimateJsonTokens(value) {
+    if (value === undefined || value === null)
+        return 0;
+    return Math.ceil(Buffer.byteLength(JSON.stringify(value), 'utf8') / 4);
+}
+/**
+ * Cumulative request-token protection for one user turn, including tool rounds and retries.
+ * Share this instance across retries; record each request once using its final usage snapshot.
+ * This pauses further requests, not an in-flight response, and is not a hard billing cap.
+ */
+export class TurnTokenBudget {
+    limitTokens;
+    usedTokens = 0;
+    estimated = false;
+    warned = false;
+    constructor(limit = resolveMaxTurnTokens()) {
+        this.limitTokens = parseMaxTurnTokens(limit, 'maxTurnTokens');
+    }
+    snapshot() {
+        return {
+            usedTokens: this.usedTokens,
+            limitTokens: this.limitTokens,
+            remainingTokens: Math.max(0, this.limitTokens - this.usedTokens),
+            estimated: this.estimated,
+        };
+    }
+    /** Check the exact request projection about to be sent, after pruning and any added prompts. */
+    preflight(req) {
+        const snapshot = this.snapshot();
+        const estimatedPromptTokens = estimateRequestTokens(req);
+        const reason = snapshot.remainingTokens === 0
+            ? 'exhausted'
+            : estimatedPromptTokens > snapshot.remainingTokens ? 'request_too_large' : undefined;
+        return { ...snapshot, estimatedPromptTokens, allowed: reason === undefined, ...(reason ? { reason } : {}) };
+    }
+    /** Call once per model request, also on interruption/failure when some usage may be known. */
+    recordCall(req, output, usage) {
+        const prompt = knownTokens(usage?.prompt_tokens);
+        const completion = knownTokens(usage?.completion_tokens);
+        this.estimated ||= prompt === undefined || completion === undefined;
+        this.usedTokens += (prompt ?? estimateRequestTokens(req)) +
+            (completion ?? estimateBudgetMessageTokens({ role: 'assistant', ...output }));
+        return this.snapshot();
+    }
+    /** Emit at most one warning per turn when cumulative usage reaches 80% of the limit. */
+    takeWarning() {
+        if (this.warned || this.usedTokens < this.limitTokens * 0.8)
+            return null;
+        this.warned = true;
+        return this.snapshot();
+    }
+}
+function knownTokens(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+//# sourceMappingURL=tokenBudget.js.map

package/dist/src/core/tokenBudget.js.map

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

package/dist/src/core/turnLoop.d.ts

@@ -1,6 +1,7 @@
-import type { ChatBackend, EngineEvent } from './types.js';
+import type { ChatBackend, EngineEvent, TaskAssessment } from './types.js';
 import type { Session } from './session.js';
 import type { ToolRegistry } from './toolRegistry.js';
+import { TurnTokenBudget } from './tokenBudget.js';
 /**
  * Event sink. A returned promise applies BACKPRESSURE on the streaming pump (pi A3):
  * consumeStream awaits it before pulling the next chunk, so a slow consumer (exec piping
@@ -16,6 +17,11 @@ export interface TurnOptions {
     includeGatedTools?: boolean;
     /** Hard cap on tool calls dispatched in this turn. Defaults to the configured max-tool-calls budget. */
     maxToolCalls?: number;
+    /** Shared across safe retries of a single user turn. */
+    tokenBudget?: TurnTokenBudget;
+    maxTurnTokens?: number;
+    /** Local, read-only delivery check. Never sends another model request. */
+    assessTask?: () => Promise<TaskAssessment | undefined>;
     /**
      * Steering (pi B2): called at each round boundary AFTER tool results are appended and
      * BEFORE the next model call. Returned items are appended as user messages, so text the