@teamvibe/poller 0.8.2-rc.1 → 0.8.3-rc.2

package/dist/classify-failed-iteration.d.ts

@@ -1,6 +1,8 @@
+import type { ClaudeQuotaFailure } from './claude-quota.js';
 export type KilledByPoller = 'timeout' | 'idle' | 'zombie' | 'network' | 'shutdown';
 export interface FailedIterationInput {
     error?: string;
+    quota?: ClaudeQuotaFailure;
     exitCode: number | null;
     killedByPoller?: KilledByPoller;
 }
@@ -12,5 +14,10 @@ export type FailedIterationDecision = {
     kind: 'error';
     text: string;
     reaction: string;
+} | {
+    kind: 'quota';
+    quota: ClaudeQuotaFailure;
+    text: string;
+    reaction: string;
 };
 export declare function classifyFailedIteration(result: FailedIterationInput): FailedIterationDecision;

package/dist/classify-failed-iteration.js

@@ -67,6 +67,14 @@ export function classifyFailedIteration(result) {
             };
         case 'timeout':
         case undefined: {
+            if (!result.killedByPoller && result.quota) {
+                const reset = result.quota.resetAt ? `Resets at ${result.quota.resetAt}.` : 'Reset time unavailable.';
+                return {
+                    kind: 'quota', quota: result.quota,
+                    text: `Claude subscription usage limit reached. ${reset} Your message is saved. After the quota pause ends, the next inbox sweep will retry the saved request.`,
+                    reaction: 'hourglass',
+                };
+            }
             // 'timeout' keeps the legacy ":warning: Session timed out after N
             // minutes..." surface unchanged (the error string is set by the
             // spawner). undefined = genuine failure → keep current behavior.

package/dist/claude-quota.d.ts

@@ -0,0 +1,15 @@
+import type { ClaudeQuotaWindow, ClaudeRateLimitInfo } from './claude-rate-limit.js';
+/** Safe metadata only; never carries CLI output or credential-bearing payloads. */
+export interface ClaudeQuotaFailure {
+    reason: 'usage_limit' | 'weekly_limit' | 'session_limit' | 'extra_usage';
+    window?: ClaudeQuotaWindow;
+    modelScope?: string;
+    resetAt?: string;
+}
+export interface ClaudeQuotaInput {
+    exitCode: number | null;
+    stderr?: string;
+    events?: readonly unknown[];
+    rateLimitInfo?: ClaudeRateLimitInfo;
+}
+export declare function parseClaudeQuotaFailure(input: ClaudeQuotaInput, now: Date): ClaudeQuotaFailure | undefined;

package/dist/claude-quota.js

@@ -0,0 +1,188 @@
+/*
+MIT License
+
+Copyright (c) 2025 Paperclip AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+// Selectively adapted from Paperclip AI (MIT), Copyright (c) 2025 Paperclip AI.
+// https://github.com/paperclipai/paperclip/blob/cc88b61c0918f45f6d3215f5d2d2368c88297046/packages/adapters/claude-local/src/server/parse.ts#L24-L30
+// Excludes generic rate limits, extra-usage suggestions and AWS service quotas.
+const QUOTA_RE = /(?:you(?:'|’)ve\s+hit\s+your\s+(?:(?:usage|weekly|session|sonnet|opus|haiku)\s+)?limit\b(?!\s+of\b)|session\s+limit\s+(?:reached|exceeded)|out\s+of\s+extra\s+usage|(?:claude\s+)?usage\s+(?:limit|cap)\s+reached|5[-\s]?hour\s+limit\s+reached|weekly\s+limit\s+reached)/i;
+function record(value) {
+    return value !== null && typeof value === 'object' ? value : {};
+}
+function errorText(value) {
+    if (typeof value === 'string')
+        return [value];
+    if (Array.isArray(value))
+        return value.flatMap(errorText);
+    if (value === null || typeof value !== 'object')
+        return [];
+    const obj = record(value);
+    // Read only known error fields; do not serialize arbitrary payloads.
+    return [...errorText(obj['message']), ...errorText(obj['error'])];
+}
+export function parseClaudeQuotaFailure(input, now) {
+    // stderr is CLI diagnostic evidence even when an error is followed by exit 0.
+    // Ordinary assistant prose is read only when explicitly marked as an error.
+    const texts = [input.stderr ?? ''];
+    for (const raw of input.events ?? []) {
+        const event = record(raw);
+        const subtype = typeof event['subtype'] === 'string' ? event['subtype'] : '';
+        if (event['type'] === 'result' && /^error_max_(?:turns|budget)/.test(subtype))
+            return undefined;
+        if (event['type'] === 'error' ||
+            (event['type'] === 'result' && (event['is_error'] === true || subtype.startsWith('error_')))) {
+            texts.push(...errorText(event['error']), ...errorText(event['errors']), ...errorText(event['result']), ...errorText(event['message']));
+        }
+        else if (event['type'] === 'assistant' && event['error']) {
+            texts.push(...errorText(event['error']));
+            const content = record(event['message'])['content'];
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    const item = record(block);
+                    if (item['type'] === 'text')
+                        texts.push(...errorText(item['text']));
+                }
+            }
+        }
+    }
+    const text = texts.join('\n');
+    if (/(?:login required|not logged in|please (?:log in|run (?:`?claude login`?|\/login))|invalid api key|failed to authenticate|invalid bearer token|authentication[_ -](?:failed|required|error)|unauthorized|(?:oauth|access|bearer) token (?:expired|invalid|revoked)|unknown session|no conversation found|reached max turns|max[_ -]turns)/i.test(text))
+        return undefined;
+    // Each candidate owns its reason, scope, window and reset. Split lines and
+    // repeated quota phrases so one diagnostic cannot donate another's reset.
+    const candidates = texts.flatMap(value => value.split('\n').flatMap(line => {
+        const matches = [...line.matchAll(new RegExp(QUOTA_RE.source, 'gi'))];
+        return matches.flatMap((match, index) => {
+            const diagnostic = line.slice(match.index, matches[index + 1]?.index);
+            // Request/token rates are transient even if the CLI calls them "usage".
+            if (/\b(?:requests?|tokens?)\s*(?:per\s+|a\s+|each\s+|\/)\s*(?:second|minute|hour|day|s\b|m\b)/i.test(diagnostic))
+                return [];
+            const evidence = match[0];
+            const reason = /weekly/i.test(evidence) ? 'weekly_limit'
+                : /session\s+limit/i.test(evidence) ? 'session_limit'
+                    : /out\s+of\s+extra\s+usage/i.test(evidence) ? 'extra_usage'
+                        : 'usage_limit';
+            // Scope is adjacent to this exhausted limit, never unrelated advice.
+            const model = diagnostic.slice(evidence.length).match(/^\s+(?:for|on)\s+(?:model\s+)?((?:claude-)?(?:sonnet|opus|haiku)(?:-\d+)*)(?![\w-])/i)?.[1]?.toLowerCase()
+                ?? evidence.match(/your\s+((?:claude-)?(?:sonnet|opus|haiku)(?:-\d+)*)\s+limit/i)?.[1]?.toLowerCase();
+            const window = reason === 'weekly_limit' ? 'seven_day'
+                : reason === 'session_limit' || /5[-\s]?hour/i.test(evidence) ? 'five_hour' : undefined;
+            const resetPrefix = diagnostic.slice(evidence.length).split(/\bresets?\b/i)[0] ?? '';
+            // Another named window/model before "resets" makes that reset unrelated
+            // or ambiguous. Strip only the directly attached model scope first.
+            const scopePrefix = resetPrefix.replace(/^\s+(?:for|on)\s+(?:model\s+)?(?:claude-)?(?:sonnet|opus|haiku)(?:-\d+)*(?![\w-])/i, '');
+            const unrelatedAllowance = /\b(?:5[-\s]?hour|five[-\s]?hour|weekly|seven[-\s]?day|session|(?:claude-)?(?:sonnet|opus|haiku)(?:-\d+)*)\b/i.test(scopePrefix);
+            const resetAt = unrelatedAllowance ? undefined : parseResetAt(diagnostic, now);
+            return [{ reason, ...(window ? { window } : {}), ...(model ? { modelScope: model } : {}), ...(resetAt ? { resetAt } : {}) }];
+        });
+    }));
+    // Detailed weekly evidence beats a generic message, but its unknown reset
+    // stays unknown; no search through the other candidates for a timestamp.
+    const quota = candidates.find(candidate => candidate.reason === 'weekly_limit') ?? candidates[0];
+    if (!quota)
+        return undefined;
+    // Global windows cannot establish the reset of a model-specific allowance.
+    // Prefer structured metadata for the exact text-classified window only.
+    const info = input.rateLimitInfo;
+    if (quota.window && !quota.modelScope && info) {
+        const matching = info.unifiedWindows?.[quota.window];
+        // An explicitly present window with an unknown reset stays unknown;
+        // never borrow the top-level reset in that case.
+        const seconds = matching ? matching.resetsAt
+            : info.rateLimitType === quota.window ? info.resetsAt : undefined;
+        if (seconds !== undefined && seconds * 1000 > now.getTime()) {
+            return { ...quota, resetAt: new Date(seconds * 1000).toISOString() };
+        }
+    }
+    return quota;
+}
+// Inspired by Paperclip's timezone helpers and reset extraction (MIT above):
+// https://github.com/paperclipai/paperclip/blob/cc88b61c0918f45f6d3215f5d2d2368c88297046/packages/adapters/claude-local/src/server/parse.ts#L547-L595 (and adjacent timezone helpers)
+// Unlike its local-clock fallback, unknown zones and DST folds stay unknown.
+function parseResetAt(text, now) {
+    if (!Number.isFinite(now.getTime()))
+        return undefined;
+    const reset = text.match(/\bresets?\s+(?:at\s+)?([^\n]+)/i)?.[1]?.trim();
+    if (!reset)
+        return undefined;
+    const iso = reset.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?(Z|[+-]\d{2}:\d{2})[.!]?$/i);
+    if (iso) {
+        const [, year, month, day, hour, minute, second, , zone] = iso;
+        const wall = Date.UTC(Number(year), Number(month) - 1, Number(day), Number(hour), Number(minute), Number(second));
+        const date = new Date(wall);
+        if (date.getUTCFullYear() !== Number(year) || date.getUTCMonth() + 1 !== Number(month) ||
+            date.getUTCDate() !== Number(day) || Number(hour) > 23 || Number(minute) > 59 || Number(second) > 59)
+            return undefined;
+        if (zone !== 'Z' && zone !== 'z' && (Number(zone.slice(1, 3)) > 23 || Number(zone.slice(4)) > 59))
+            return undefined;
+        const timestamp = Date.parse(reset.replace(/[.!]$/, ''));
+        return timestamp > now.getTime() ? new Date(timestamp).toISOString() : undefined;
+    }
+    const clock = reset.match(/^(\d{1,2})(?::(\d{2}))?\s*([ap])m\s*\(([^)]+)\)[.!]?$/i);
+    if (!clock)
+        return undefined;
+    const hour12 = Number(clock[1]);
+    const minute = Number(clock[2] ?? 0);
+    if (hour12 < 1 || hour12 > 12 || minute > 59)
+        return undefined;
+    const hour = hour12 % 12 + (clock[3].toLowerCase() === 'p' ? 12 : 0);
+    const hint = clock[4].trim();
+    // Abbreviations such as CST/EST are ambiguous, even if Intl accepts them.
+    const timeZone = /^(utc|gmt)$/i.test(hint) ? 'UTC' : hint.includes('/') ? hint : undefined;
+    if (!timeZone)
+        return undefined;
+    try {
+        const formatter = new Intl.DateTimeFormat('en-US', {
+            timeZone, hourCycle: 'h23', year: 'numeric', month: '2-digit', day: '2-digit',
+            hour: '2-digit', minute: '2-digit', second: '2-digit',
+        });
+        const wallTime = (timestamp) => {
+            const parts = Object.fromEntries(formatter.formatToParts(new Date(timestamp)).map(p => [p.type, p.value]));
+            return Date.UTC(Number(parts['year']), Number(parts['month']) - 1, Number(parts['day']), Number(parts['hour']), Number(parts['minute']), Number(parts['second']));
+        };
+        const localNow = new Date(wallTime(now.getTime()));
+        let target = Date.UTC(localNow.getUTCFullYear(), localNow.getUTCMonth(), localNow.getUTCDate(), hour, minute);
+        const resolve = (wall) => {
+            const candidates = new Set();
+            // Sample offsets on both sides of any DST transition, then verify each
+            // UTC candidate against the exact wall clock. Zero/multiple = unknown.
+            for (let hours = -36; hours <= 36; hours += 6) {
+                const sample = wall + hours * 3600000;
+                const candidate = wall - (wallTime(sample) - sample);
+                if (wallTime(candidate) === wall)
+                    candidates.add(candidate);
+            }
+            return candidates.size === 1 ? [...candidates][0] : undefined;
+        };
+        let timestamp = resolve(target);
+        if (timestamp === undefined)
+            return undefined;
+        if (timestamp <= now.getTime()) {
+            target += 86400000; // next calendar day in wall-clock coordinates
+            timestamp = resolve(target);
+        }
+        return timestamp !== undefined && timestamp > now.getTime() ? new Date(timestamp).toISOString() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/claude-rate-limit.d.ts

@@ -0,0 +1,19 @@
+/** Passive Claude Code stream metadata; status never establishes exhaustion. */
+export type ClaudeQuotaWindow = 'five_hour' | 'seven_day';
+export interface ClaudeRateLimitWindow {
+    /** Fraction from 0 to 1, not a percentage. */
+    utilization?: number;
+    /** Unix epoch seconds. */
+    resetsAt?: number;
+}
+export interface ClaudeRateLimitInfo extends ClaudeRateLimitWindow {
+    status?: string;
+    rateLimitType?: string;
+    unifiedWindows?: Partial<Record<ClaudeQuotaWindow, ClaudeRateLimitWindow>>;
+    overageStatus?: string;
+    overageDisabledReason?: string;
+    isUsingOverage?: boolean;
+    surpassedThreshold?: number;
+}
+/** Copies only recognized fields of the last rate_limit_info; never raw JSON. */
+export declare function parseClaudeRateLimitInfo(value: unknown): ClaudeRateLimitInfo | undefined;

package/dist/claude-rate-limit.js

@@ -0,0 +1,44 @@
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value : undefined;
+}
+function fraction(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+function epochSeconds(value) {
+    // Bound to supported calendar dates; reject milliseconds/string coercions.
+    return typeof value === 'number' && Number.isInteger(value) && value > 0 && value <= 253402300799;
+}
+function windowInfo(obj) {
+    return {
+        ...(fraction(obj['utilization']) ? { utilization: obj['utilization'] } : {}),
+        ...(epochSeconds(obj['resetsAt']) ? { resetsAt: obj['resetsAt'] } : {}),
+    };
+}
+/** Copies only recognized fields of the last rate_limit_info; never raw JSON. */
+export function parseClaudeRateLimitInfo(value) {
+    const obj = record(value);
+    if (!obj)
+        return undefined;
+    const result = windowInfo(obj);
+    for (const key of ['status', 'rateLimitType', 'overageStatus', 'overageDisabledReason']) {
+        if (typeof obj[key] === 'string')
+            result[key] = obj[key];
+    }
+    if (typeof obj['isUsingOverage'] === 'boolean')
+        result.isUsingOverage = obj['isUsingOverage'];
+    if (fraction(obj['surpassedThreshold']))
+        result.surpassedThreshold = obj['surpassedThreshold'];
+    const windows = record(obj['unifiedWindows']);
+    if (windows) {
+        const parsed = {};
+        for (const key of ['five_hour', 'seven_day']) {
+            const data = record(windows[key]);
+            if (data)
+                parsed[key] = windowInfo(data);
+        }
+        if (Object.keys(parsed).length)
+            result.unifiedWindows = parsed;
+    }
+    return result;
+}

package/dist/claude-spawner.d.ts

@@ -4,6 +4,10 @@ import { type SessionLogger } from './logger.js';
 import { type TypingIndicator } from './slack-client.js';
 import { type ResolvedModelConfig } from './config-client.js';
 import type { KilledByPoller } from './classify-failed-iteration.js';
+import { type ClaudeRateLimitInfo } from './claude-rate-limit.js';
+import { type ClaudeQuotaFailure } from './claude-quota.js';
+import { type PoolRuntimeOptions, type PoolAttempt } from './subscription-runtime.js';
+import type { SubscriptionAccount } from './subscription-pool-client.js';
 export declare function progressNotificationMarks(estimateMinutes: number): number[];
 export declare function computeCompactionKillDeadline(previousActivityTime: number, now: number, idleKillMs: number, graceMs: number): number;
 export interface ContextHintParams {
@@ -19,6 +23,11 @@ export interface ContextHintParams {
 }
 export declare function buildContextHint(p: ContextHintParams): Promise<string | undefined>;
 export interface SpawnResult {
+    poolAttempts?: readonly PoolAttempt[];
+    quota?: ClaudeQuotaFailure;
+    rateLimitInfo?: ClaudeRateLimitInfo;
+    /** Actual ID passed to this CLI attempt, including a failed first turn. */
+    attemptedSessionId?: string;
     success: boolean;
     output: string;
     exitCode: number | null;
@@ -165,6 +174,7 @@ export interface BuildSpawnEnvParams {
     teamvibePollerId: string;
     inboxThreadId: string;
     brainPath: string;
+    subscriptionAccount?: SubscriptionAccount;
 }
 /**
  * Pure construction of the env object passed to the spawned `claude` child
@@ -225,6 +235,8 @@ export declare function resolveTypingStatus(event: any, assistantText?: string):
  * createSession() placeholder forever and the thread's next message does
  * `--resume <id-claude-code-never-used>`, which fails 100% of the time.
  * (teamvibe.ai#77, DevGuru review round)
+ * Quota failures also report the attempted ID, even on the first turn, so
+ * later pool orchestration can continue that same session (#401).
  */
 export declare function finalizeSpawnResult(retryResult: SpawnResult, isFirstMessage: boolean, effectiveSessionId: string | undefined): SpawnResult & {
     newSessionId?: string;
@@ -232,6 +244,9 @@ export declare function finalizeSpawnResult(retryResult: SpawnResult, isFirstMes
 export declare function spawnClaudeCode(msg: TeamVibeQueueMessage, sessionLog: SessionLogger, cwd: string, sessionId?: string, isFirstMessage?: boolean, lastMessageTs?: string, onMessageSent?: () => void, typingIndicator?: TypingIndicator): Promise<SpawnResult & {
     newSessionId?: string;
 }>;
+export declare function spawnPoolClaudeCode(msg: TeamVibeQueueMessage, sessionLog: SessionLogger, cwd: string, sessionId?: string, isFirstMessage?: boolean, lastMessageTs?: string, onMessageSent?: () => void, typingIndicator?: TypingIndicator, poolRuntime?: PoolRuntimeOptions): Promise<SpawnResult & {
+    newSessionId?: string;
+}>;
 export declare function getActiveProcessCount(): number;
 export declare function getLastSessionEndTs(): number;
 /**