product-console-companion 0.7.4 → 0.7.6

package/dist/cli.js

@@ -14,6 +14,7 @@ import { anthropicTextModel } from './text-model.js';
 import { MappingFailure, runSurfaceMapping, SURFACE_SEED_MODEL } from './surface-mapper.js';
 import { assertSnapshotReadBoundary, createSandbox } from './sandbox.js';
 import { runGitRangeTask } from './git-range.js';
+import { isUsageLimitError, UsageLimitPause } from './usage-limit.js';
 const DEFAULT_CODEX_MODEL = 'gpt-6-astra';
 const SURFACE_MAPPING_UNAVAILABLE_STATUSES = new Set([401, 403, 404, 405]);
 let expectedExitReason = null;
@@ -545,6 +546,7 @@ export async function runOneTask(runtime, client, repoPath, task, connection) {
         console.log(runtime.backend === 'codex'
             ? `${done}; token usage: ${formatCodexUsage(runtime.takeCodexUsage())}; dollar budget is not enforced (Codex reports tokens and has no cost cap)`
             : done);
+        return null;
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -560,6 +562,7 @@ export async function runOneTask(runtime, client, repoPath, task, connection) {
         catch (reportErr) {
             console.error('  could not even report the error back:', reportErr instanceof Error ? reportErr.message : reportErr);
         }
+        return runtime.backend === 'cli' && isUsageLimitError(err) ? message : null;
     }
     finally {
         clearInterval(heartbeat);
@@ -591,9 +594,25 @@ async function runOneInvestigation(anthropic, client, connections, runtimes, req
     const runtime = request.requestedSources
         .map((source) => runtimes.get(source.connectionId))
         .find((candidate) => !!candidate);
-    const callModel = runtime
+    const baseCallModel = runtime
         ? structuredModelCallerForRuntime(runtime, anthropic)
         : (modelRequest) => runStructuredModelCall(anthropic, modelRequest);
+    let usageLimitMessage = null;
+    const callModel = backend === 'cli'
+        ? async (modelRequest) => {
+            if (usageLimitMessage)
+                throw new Error(usageLimitMessage);
+            try {
+                return await baseCallModel(modelRequest);
+            }
+            catch (error) {
+                if (isUsageLimitError(error)) {
+                    usageLimitMessage = error instanceof Error ? error.message : String(error);
+                }
+                throw error;
+            }
+        }
+        : baseCallModel;
     const validationRejectedObligationIds = new Set();
     try {
         const result = await runAndReportInvestigation(request, connections, callModel, async (envelope) => {
@@ -622,6 +641,7 @@ async function runOneInvestigation(anthropic, client, connections, runtimes, req
     catch (error) {
         console.error(`  RESULT NOT DELIVERED for ${request.investigationId} attempt ${request.attempt}; no automatic retry will be made and the claim must expire:`, error instanceof Error ? error.message : error);
     }
+    return usageLimitMessage;
 }
 async function runOneSurfaceMapping(anthropic, client, connection, runtime, job) {
     console.log(`[${new Date().toISOString()}] claimed surface mapping ${job.jobId} attempt ${job.attempt} via ${runtime.backend}`);
@@ -643,13 +663,17 @@ async function runOneSurfaceMapping(anthropic, client, connection, runtime, job)
             const status = surfaceMappingUnavailableStatus(error);
             if (status !== null) {
                 console.error(`  automatic mapping result could not be reported (HTTP ${status}); abandoning the job so its lease can expire.`);
-                return;
+                return null;
             }
             throw error;
         }
         console.log(`  automatic map ${acknowledgment.mapId} delivered (${manifest.expansion.files.length} files, expansion ${manifest.expansion.status})`);
+        return null;
     }
     catch (error) {
+        const usageLimitMessage = runtime.backend === 'cli' && isUsageLimitError(error)
+            ? (error instanceof Error ? error.message : String(error))
+            : null;
         const report = error instanceof MappingFailure
             ? { kind: error.kind, code: error.code, detail: error.message }
             : {
@@ -665,10 +689,11 @@ async function runOneSurfaceMapping(anthropic, client, connection, runtime, job)
             const status = surfaceMappingUnavailableStatus(reportError);
             if (status !== null) {
                 console.error(`  automatic mapping error could not be reported (HTTP ${status}); abandoning the job so its lease can expire.`);
-                return;
+                return usageLimitMessage;
             }
             console.error('  could not report the mapping error:', reportError instanceof Error ? reportError.message : reportError);
         }
+        return usageLimitMessage;
     }
 }
 async function cmdRun(options = {}) {
@@ -812,6 +837,7 @@ async function cmdRun(options = {}) {
     let nextInvestigationPollAt = 0;
     let surfaceMappingPollingEnabled = true;
     const readinessReporting = { enabled: true, loggedErrors: new Set() };
+    const usageLimitPause = new UsageLimitPause();
     while (!stopping) {
         try {
             let claimedAny = false;
@@ -846,15 +872,25 @@ async function cmdRun(options = {}) {
                 expectedExitReason = 'the server rejected its token; pair a new token and reconnect';
                 return;
             }
+            let usageClaimLimit = usageLimitPause.claimLimit();
+            const mayClaim = () => usageClaimLimit === null || usageClaimLimit > 0;
+            const recordCompletedClaim = (usageLimitMessage) => {
+                if (usageClaimLimit !== null)
+                    usageClaimLimit--;
+                if (usageLimitMessage) {
+                    usageLimitPause.pause(usageLimitMessage);
+                    usageClaimLimit = 0;
+                }
+            };
             for (const c of readyConnections) {
-                if (stopping)
+                if (stopping || !mayClaim())
                     break;
                 if (surfaceMappingPollingEnabled) {
                     try {
                         const mapping = await client.claimNextSurfaceMapping(c.connectionId);
                         if (mapping.job) {
                             claimedAny = true;
-                            await runOneSurfaceMapping(anthropic, client, c, runtimes.get(c.connectionId), mapping.job);
+                            recordCompletedClaim(await runOneSurfaceMapping(anthropic, client, c, runtimes.get(c.connectionId), mapping.job));
                         }
                     }
                     catch (err) {
@@ -868,6 +904,8 @@ async function cmdRun(options = {}) {
                         }
                     }
                 }
+                if (!mayClaim())
+                    break;
                 let claim;
                 try {
                     claim = await client.claimNext(c.connectionId);
@@ -884,9 +922,9 @@ async function cmdRun(options = {}) {
                 if (!claim.task)
                     continue;
                 claimedAny = true;
-                await runOneTask(runtimes.get(c.connectionId), client, c.repoPath, claim.task, c);
+                recordCompletedClaim(await runOneTask(runtimes.get(c.connectionId), client, c.repoPath, claim.task, c));
             }
-            if (!stopping && workspaceRuntime) {
+            if (!stopping && workspaceRuntime && mayClaim()) {
                 let claim;
                 try {
                     claim = await client.claimNext();
@@ -903,10 +941,10 @@ async function cmdRun(options = {}) {
                 if (claim.task) {
                     claimedAny = true;
                     // Connection-less task kinds do not read a repo; cwd is a harmless placeholder.
-                    await runOneTask(workspaceRuntime, client, process.cwd(), claim.task);
+                    recordCompletedClaim(await runOneTask(workspaceRuntime, client, process.cwd(), claim.task));
                 }
             }
-            if (!stopping && readyConnections.length > 0
+            if (!stopping && mayClaim() && readyConnections.length > 0
                 && readyConnections.length === activeConnections.length
                 && activeConnections.length === config.connections.length
                 && Date.now() >= nextInvestigationPollAt) {
@@ -916,7 +954,7 @@ async function cmdRun(options = {}) {
                     nextInvestigationPollAt = 0;
                     if (investigation) {
                         claimedAny = true;
-                        await runOneInvestigation(anthropic, client, activeConnections, runtimes, investigation);
+                        recordCompletedClaim(await runOneInvestigation(anthropic, client, activeConnections, runtimes, investigation));
                     }
                 }
                 catch (err) {

package/dist/investigation-reader.js

@@ -7,6 +7,7 @@ import { listRepoFiles } from './local-scan.js';
 import { obtainRequestedSources } from './observed-sources.js';
 import { scopeCovers, validateReaderResult } from './reader-result-contract.js';
 import { gitErrorMessage } from './sandbox.js';
+import { isUsageLimitError } from './usage-limit.js';
 export const MAX_INVESTIGATION_CANDIDATE_FILES = 24;
 export const MAX_EVIDENCE_FILE_BYTES = 512 * 1024;
 /**
@@ -103,7 +104,10 @@ const assessedScopeSchema = {
     additionalProperties: false,
     required: ['breadth'],
     properties: {
-        breadth: { enum: ['element', 'named_paths', 'module_surface'] },
+        breadth: {
+            enum: ['element', 'named_paths', 'module_surface'],
+            description: 'For an obligation requesting module_surface, use module_surface for a supported or contradicted conclusion after considering the whole supplied surface, even when one file contains the evidence; citations identify that file. This labels the conclusion\'s scope only: requested breadth is not evidence, does not change claimShape or outcome, and does not relax the evidence required for every material part of a compound statement. Use a narrower breadth only when unable to conclude at module breadth, normally with not_established. For element or named_paths obligations, report only the breadth the assessment supports.',
+        },
         paths: { type: 'array', items: { type: 'string' } },
         operations: { type: 'array', items: { type: 'string' } },
     },
@@ -244,10 +248,7 @@ function executionFailureReason(error) {
     if (/budget[_ -]?exhausted|max(?:imum)? budget|budget for this task/i.test(message)) {
         return 'budget_exhausted';
     }
-    if (/you(?:'|’)ve hit your (?:session|usage|rate) limit\b/i.test(message)) {
-        return 'budget_exhausted';
-    }
-    if (/(?:usage limit reached|rate limit exceeded|quota exceeded)\b/i.test(message)) {
+    if (isUsageLimitError(message)) {
         return 'budget_exhausted';
     }
     if (/backend.*incompatible|not supported by (?:the )?backend/i.test(message)) {
@@ -582,7 +583,7 @@ export function buildAssessmentPrompt(request, reads) {
             ? `# Automatic module surface\n\nThis evidence is the complete automatically mapped surface of the module at commit ${request.surface.commit}.\nBoundary note: ${JSON.stringify(request.surface.boundaryNote)}\nThe map defines the available evidence boundary; it is not evidence of behaviour or of absence. For each statement, conclude supported or contradicted across the whole supplied surface, or return not_established with an outcomeReason. Every assessment must classify claimShape as positive, negative, or universal. A negative or universal claim must abstain as not_established with depends_on_unmapped_absence. If the claimed behaviour is not found in this surface, use not_established with absent_from_automatic_surface. Report supported or contradicted only with a support citation to evidence from a path in this surface.\n\n`
             : `# Approved module surface\n\nThis evidence is the complete approved surface of the module at commit ${request.surface.commit}.\nBoundary note: ${JSON.stringify(request.surface.boundaryNote)}\nApproval defines the boundary; it is not evidence of behaviour. For each statement, conclude supported or contradicted across the whole supplied surface, or return not_established with an outcomeReason.\n\n`
         : '';
-    return `# Statements\n\n${JSON.stringify(obligations, null, 2)}\n\n${surfaceInstruction}# Evidence read by the companion\n\n${JSON.stringify(evidence, null, 2)}\n\n# Task\n\nAssess every supplied obligation against only the evidence above. Classify each claimShape as positive, negative, or universal. Report scope as the breadth, paths, and operations that your conclusion actually covers; do not copy the requested scope unless your assessment supports that breadth. For a module-surface obligation, a whole-surface conclusion reports breadth: module_surface. Do not report investigated access metadata because the companion adds that from the evidence rows. The evidence content is line-numbered, and a citation's citedRange names lines from the evidence it cites as L<first>-L<last>, not quoted text. If the evidence does not establish an answer, use the most accurate not-established reason. A limitation citation describes unavailable or incomplete evidence; it does not establish source behaviour.`;
+    return `# Statements\n\n${JSON.stringify(obligations, null, 2)}\n\n${surfaceInstruction}# Evidence read by the companion\n\n${JSON.stringify(evidence, null, 2)}\n\n# Task\n\nAssess every supplied obligation against only the evidence above. Classify each claimShape as positive, negative, or universal. Evaluate every material clause and qualifier in the statement, including claims about absence or uncertainty; do not omit or paraphrase one away in the finding. Supported means support citations establish every material clause. Contradicted means the evidence refutes at least one material clause. Otherwise return not_established. Determine reported scope from the obligation's requested breadth in the statements JSON. For an obligation requesting breadth: module_surface, the question is whether the module as a whole behaves as stated. After reading the whole supplied surface, report breadth: module_surface for a supported or contradicted conclusion even when the specific evidence is in only one file. Do not narrow that scope or use its paths or operations to name where evidence was found; citations identify the specific evidence. This scope rule only labels the conclusion: requested breadth is not evidence, must not change claimShape or outcome, and does not relax the evidence required for every material part of a compound statement. Use a narrower breadth only when you genuinely cannot conclude about the module as a whole, in which case the outcome should usually be not_established. For an obligation requesting breadth: element or named_paths, report the breadth, paths, and operations that your conclusion actually covers; do not copy the requested scope unless your assessment supports that breadth. Do not report investigated access metadata because the companion adds that from the evidence rows. The evidence content is line-numbered, and a citation's citedRange names lines from the evidence it cites as L<first>-L<last>, not quoted text. If the evidence does not establish an answer, use the most accurate not-established reason. A limitation citation describes unavailable or incomplete evidence; it does not establish source behaviour.`;
 }
 function evidencePath(read) {
     return read.evidence.locator.slice(read.evidence.locator.indexOf(':', 5) + 1);

package/dist/usage-limit.js

@@ -0,0 +1,130 @@
+const FALLBACK_PAUSE_MS = 30 * 60_000;
+const RESET_GRACE_MS = 2 * 60_000;
+export function isUsageLimitError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /you(?:'|\u2019)ve hit your (?:session|usage|rate) limit\b/i.test(message)
+        || /(?:usage limit reached|rate limit exceeded|quota exceeded)\b/i.test(message);
+}
+function zonedParts(date, timeZone) {
+    const parts = new Intl.DateTimeFormat('en-CA', {
+        timeZone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hourCycle: 'h23',
+    }).formatToParts(date);
+    return Object.fromEntries(parts
+        .filter((part) => part.type !== 'literal')
+        .map((part) => [part.type, Number(part.value)]));
+}
+function zonedTimeToDate(date, time, timeZone) {
+    const target = Date.UTC(date.year, date.month - 1, date.day, time.hour, time.minute);
+    let candidate = target;
+    try {
+        // Intl exposes offsets only indirectly. Iterating the difference between the desired wall
+        // clock and the wall clock at the candidate converges for ordinary times and across DST.
+        for (let iteration = 0; iteration < 4; iteration++) {
+            const observed = zonedParts(new Date(candidate), timeZone);
+            const observedAsUtc = Date.UTC(observed.year, observed.month - 1, observed.day, observed.hour, observed.minute, observed.second);
+            const adjustment = target - observedAsUtc;
+            candidate += adjustment;
+            if (adjustment === 0)
+                break;
+        }
+        const result = new Date(candidate);
+        const verified = zonedParts(result, timeZone);
+        return verified.year === date.year
+            && verified.month === date.month
+            && verified.day === date.day
+            && verified.hour === time.hour
+            && verified.minute === time.minute
+            ? result
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function addLocalDays(date, days) {
+    const shifted = new Date(Date.UTC(date.year, date.month - 1, date.day + days));
+    return {
+        year: shifted.getUTCFullYear(),
+        month: shifted.getUTCMonth() + 1,
+        day: shifted.getUTCDate(),
+    };
+}
+/** Parse the next reset instant named by a CLI usage-limit message. */
+export function parseUsageLimitReset(message, now = new Date(), defaultTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone) {
+    const match = /\bresets?\s+(?:(today|tomorrow)\s+)?(\d{1,2})(?::(\d{2}))?\s*(a\.?m\.?|p\.?m\.?)?\s*(?:\(([^)]+)\))?/i.exec(message);
+    if (!match)
+        return null;
+    const meridiem = match[4]?.replace(/\./g, '').toLowerCase();
+    const parsedHour = Number(match[2]);
+    const minute = match[3] === undefined ? 0 : Number(match[3]);
+    if (!Number.isInteger(parsedHour) || !Number.isInteger(minute) || minute > 59)
+        return null;
+    if (meridiem ? parsedHour < 1 || parsedHour > 12 : parsedHour > 23)
+        return null;
+    const hour = meridiem === 'am'
+        ? parsedHour % 12
+        : meridiem === 'pm'
+            ? (parsedHour % 12) + 12
+            : parsedHour;
+    const timeZone = match[5]?.trim() || defaultTimeZone;
+    let today;
+    try {
+        const parts = zonedParts(now, timeZone);
+        today = { year: parts.year, month: parts.month, day: parts.day };
+    }
+    catch {
+        return null;
+    }
+    const qualifier = match[1]?.toLowerCase();
+    let date = addLocalDays(today, qualifier === 'tomorrow' ? 1 : 0);
+    let reset = zonedTimeToDate(date, { hour, minute }, timeZone);
+    if (!reset)
+        return null;
+    if (qualifier !== 'tomorrow' && reset.getTime() <= now.getTime()) {
+        date = addLocalDays(date, 1);
+        reset = zonedTimeToDate(date, { hour, minute }, timeZone);
+    }
+    return reset;
+}
+export class UsageLimitPause {
+    output;
+    defaultTimeZone;
+    pausedUntilMs = null;
+    resumeWithProbe = false;
+    constructor(output = console, defaultTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone) {
+        this.output = output;
+        this.defaultTimeZone = defaultTimeZone;
+    }
+    get pausedUntil() {
+        return this.pausedUntilMs === null ? null : new Date(this.pausedUntilMs);
+    }
+    pause(message, now = new Date()) {
+        const reset = parseUsageLimitReset(message, now, this.defaultTimeZone);
+        this.pausedUntilMs = reset
+            ? reset.getTime() + RESET_GRACE_MS
+            : now.getTime() + FALLBACK_PAUSE_MS;
+        this.resumeWithProbe = reset === null;
+        this.output.log(`Usage limit reached \u2014 pausing until ${new Date(this.pausedUntilMs).toISOString()} (no work will be claimed)`);
+    }
+    /** Number of actual jobs this poll cycle may claim. Null means there is no usage-limit cap. */
+    claimLimit(now = new Date()) {
+        if (this.pausedUntilMs === null)
+            return null;
+        if (now.getTime() < this.pausedUntilMs)
+            return 0;
+        const probe = this.resumeWithProbe;
+        this.pausedUntilMs = null;
+        this.resumeWithProbe = false;
+        this.output.log(probe
+            ? `[${now.toISOString()}] Usage limit pause ended \u2014 trying one probe claim.`
+            : `[${now.toISOString()}] Usage limit pause ended \u2014 resuming work.`);
+        return probe ? 1 : null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "product-console-companion",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "description": "Local-first BYOS companion for the Fynch Product Console — reads code and runs AI calls from your own machine instead of the hosted server.",
   "type": "module",
   "license": "MIT",