thinkpool-pair 0.7.364 → 0.7.366

package/provider-resilience.mjs

@@ -1,356 +1 @@
-/*
- * Provider resilience policy primitives.
- *
- * This module never makes a network call or reads provider credentials. Phase 1
- * adds an injected same-target controller, but transport remains owned by the
- * Claude session and fallback remains unavailable.
- */
-import { isSecretFreeRoomPayload } from './runtime-contract.mjs'
-
-export const RESILIENCE_VERSION = 1
-export const MAX_NETWORK_ATTEMPTS = 3
-export const MAX_SAME_TARGET_ATTEMPTS = 2
-export const TRANSIENT_FAILURES = new Set(['timeout', 'network', 'rate_limit', 'overload', 'upstream_5xx'])
-const RETRYABLE = [...TRANSIENT_FAILURES]
-const TRACE_FIELDS = new Set(['traceId', 'turnRev', 'attempt', 'targetProviderId', 'targetProviderName', 'requestedModel', 'actualConfiguredModel', 'phase', 'outcome', 'failureClass', 'elapsedMs', 'retryAfterMs', 'fallbackFrom'])
-const OUTCOMES = new Set(['started', 'retrying', 'failed', 'fallback', 'succeeded', 'circuit_open', 'cap_blocked'])
-const TRACE_TEXT_FIELDS = new Set(['traceId', 'targetProviderId', 'targetProviderName', 'requestedModel', 'actualConfiguredModel', 'phase', 'failureClass', 'fallbackFrom'])
-const TRACE_URL_OR_PATH = /(?:[a-z][a-z0-9+.-]*:\/\/|(?:^|[\s"'(])\/(?:Users|home|private|tmp)\/|[a-z]:\\|\\\\)/i
-
-export const DEFAULT_RESILIENCE_POLICY = Object.freeze({
-  v: RESILIENCE_VERSION,
-  enabled: false,
-  timeoutMs: 90000,
-  maxAttempts: 2,
-  retryOn: RETRYABLE,
-  circuit: Object.freeze({ failureThreshold: 3, windowMs: 60000, cooldownMs: 30000 }),
-  fallback: Object.freeze([]),
-})
-
-const plainObject = (x) => !!x && typeof x === 'object' && !Array.isArray(x)
-const positiveInt = (x) => Number.isInteger(x) && x > 0
-const text = (x) => typeof x === 'string' && x.trim() ? x.trim() : null
-const safeTraceText = (value) => {
-  const normalized = text(value)
-  if (!normalized || normalized.length > 160 || TRACE_URL_OR_PATH.test(normalized)) return null
-  return isSecretFreeRoomPayload({ value: normalized }, 512) ? normalized : null
-}
-
-/**
- * Validate and canonicalize the non-secret provider policy. Missing policy is
- * the explicit observe-only default. Extra fields are discarded rather than
- * copied into a room-facing projection.
- */
-export function validateResiliencePolicy(input, { providers = [], primaryProviderId = null } = {}) {
-  if (input == null) return { ok: true, value: { ...DEFAULT_RESILIENCE_POLICY, retryOn: [...RETRYABLE], circuit: { ...DEFAULT_RESILIENCE_POLICY.circuit }, fallback: [] } }
-  if (!plainObject(input) || input.v !== RESILIENCE_VERSION) return { ok: false, error: 'unsupported resilience policy version' }
-  if (typeof input.enabled !== 'boolean') return { ok: false, error: 'enabled must be boolean' }
-  if (!Number.isInteger(input.timeoutMs) || input.timeoutMs < 30000 || input.timeoutMs > 120000) return { ok: false, error: 'timeoutMs must be 30000..120000' }
-  if (!positiveInt(input.maxAttempts)) return { ok: false, error: 'maxAttempts must be a positive integer' }
-  if (!Array.isArray(input.retryOn) || input.retryOn.some((x) => !TRANSIENT_FAILURES.has(x))) return { ok: false, error: 'retryOn contains an unsupported failure class' }
-  if (!plainObject(input.circuit) || !positiveInt(input.circuit.failureThreshold) || !positiveInt(input.circuit.windowMs) || !positiveInt(input.circuit.cooldownMs)) return { ok: false, error: 'invalid circuit policy' }
-  if (!Array.isArray(input.fallback)) return { ok: false, error: 'fallback must be an array' }
-  const fallback = []
-  for (const candidate of input.fallback) {
-    if (!plainObject(candidate) || !text(candidate.providerId) || !text(candidate.model) || candidate.allow !== true) return { ok: false, error: 'invalid fallback target' }
-    // Phase 0 stores only the conservative v1 declarations. A future UI may add
-    // explicit elevated consent, but it must not be smuggled in via this shape.
-    if (candidate.privacyClass !== 'same' || !['same', 'same-or-lower'].includes(candidate.costClass)) return { ok: false, error: 'fallback privacy/cost class is not eligible' }
-    if (primaryProviderId && candidate.providerId === primaryProviderId) return { ok: false, error: 'fallback cannot target itself' }
-    if (providers.length) {
-      const row = providers.find((provider) => provider?.id === candidate.providerId)
-      if (!row || row.id === 'anthropic' || row.model !== candidate.model) return { ok: false, error: 'fallback must name a registered exact provider/model target' }
-    }
-    fallback.push({ providerId: text(candidate.providerId), model: text(candidate.model), allow: true, privacyClass: candidate.privacyClass, costClass: candidate.costClass })
-  }
-  return {
-    ok: true,
-    value: {
-      v: RESILIENCE_VERSION,
-      enabled: input.enabled,
-      timeoutMs: input.timeoutMs,
-      // A malformed high value may never increase live network work.
-      maxAttempts: Math.min(input.maxAttempts, MAX_NETWORK_ATTEMPTS),
-      retryOn: [...new Set(input.retryOn)],
-      circuit: { failureThreshold: input.circuit.failureThreshold, windowMs: input.circuit.windowMs, cooldownMs: input.circuit.cooldownMs },
-      fallback,
-    },
-  }
-}
-
-/** Safe allowlist projection for local diagnostics / room-safe metadata. */
-export function resilienceProjection(input) {
-  const validated = validateResiliencePolicy(input)
-  if (!validated.ok) return null
-  const p = validated.value
-  return { v: p.v, enabled: p.enabled, timeoutMs: p.timeoutMs, maxAttempts: p.maxAttempts, retryOn: [...p.retryOn], circuit: { ...p.circuit }, fallback: p.fallback.map((x) => ({ ...x })) }
-}
-
-/** Coarse classification only. It intentionally does not return raw errors. */
-export function classifyProviderFailure(input = {}) {
-  const status = Number(input.status || input.statusCode || 0)
-  const code = String(input.code || '').toLowerCase()
-  const message = String(input.message || input.error?.message || '').toLowerCase()
-  if (input.aborted || /\babort(ed|error)?\b|cancelled|canceled/.test(`${code} ${message}`)) return 'user_abort'
-  if (input.permissionDenied || /permission denied|forbidden by policy|guardrail/.test(`${code} ${message}`)) return 'permission_denied'
-  if (status === 401 || status === 403 || /unauthori[sz]ed|invalid (api )?key|credential/.test(`${code} ${message}`)) return 'auth'
-  if (status === 429 || /rate.?limit/.test(`${code} ${message}`)) return 'rate_limit'
-  if (status === 529 || /overload|overloaded/.test(`${code} ${message}`)) return 'overload'
-  if (status >= 500 && status <= 599) return 'upstream_5xx'
-  if (/timeout|timed out|deadline exceeded|etimedout/.test(`${code} ${message}`)) return 'timeout'
-  if (/econnreset|enotfound|eai_again|socket|connection (closed|reset)|fetch failed|network error/.test(`${code} ${message}`)) return 'network'
-  if (status === 400 || /invalid model|unknown model/.test(`${code} ${message}`)) return 'invalid_model'
-  if (/context length|request too large|payload too large|too many tokens/.test(`${code} ${message}`)) return 'request_too_large'
-  if (status >= 400 && status < 500) return 'invalid_request'
-  return 'unknown'
-}
-
-export const isReplaySafe = ({ outputVisible = false, toolOutputVisible = false, aborted = false, permissionDenied = false, nonIdempotent = false } = {}) => !(outputVisible || toolOutputVisible || aborted || permissionDenied || nonIdempotent)
-
-/** Resolve only registered custom Claude targets with their exact configured model. */
-export function resolveAttemptTarget({ runtime = 'claude', providers = [], providerId, model } = {}) {
-  if (runtime !== 'claude' || !text(providerId) || !text(model)) return null
-  const provider = providers.find((p) => p && p.id === providerId && p.id !== 'anthropic' && p.model === model)
-  if (!provider) return null
-  return { providerId: provider.id, targetProviderName: text(provider.name) || provider.id, actualConfiguredModel: provider.model }
-}
-
-/** All eight Phase-2 eligibility gates in a pure, fail-closed form. */
-export function assessFallbackEligibility({ runtime = 'claude', providers = [], primary, candidate, policy, outputVisible = false, toolOutputVisible = false, aborted = false, permissionDenied = false, capAllowed = true, circuit = 'closed' } = {}) {
-  if (!isReplaySafe({ outputVisible, toolOutputVisible, aborted, permissionDenied })) return { ok: false, reason: 'replay_unsafe' }
-  if (circuit !== 'closed') return { ok: false, reason: 'circuit_open' }
-  if (!capAllowed) return { ok: false, reason: 'cap_blocked' }
-  const checked = validateResiliencePolicy(policy)
-  if (!checked.ok || !checked.value.enabled || runtime !== 'claude') return { ok: false, reason: 'policy_disabled' }
-  const target = resolveAttemptTarget({ runtime, providers, providerId: candidate?.providerId, model: candidate?.model })
-  if (!target) return { ok: false, reason: 'unknown_target' }
-  const configured = checked.value.fallback.find((x) => x.providerId === target.providerId && x.model === target.actualConfiguredModel)
-  if (!configured?.allow) return { ok: false, reason: 'not_explicitly_allowed' }
-  if (configured.privacyClass !== 'same' || !['same', 'same-or-lower'].includes(configured.costClass)) return { ok: false, reason: 'boundary_not_consented' }
-  if (primary?.providerId === target.providerId && primary?.actualConfiguredModel === target.actualConfiguredModel) return { ok: false, reason: 'same_target' }
-  return { ok: true, target, fallback: configured }
-}
-
-/** Local-only total-attempt accounting. It is intentionally not a retry engine. */
-export function createAttemptLedger({ maxAttempts = MAX_NETWORK_ATTEMPTS, traceId = 'local', turnRev = null, onRecord = null } = {}) {
-  const ceiling = Math.max(1, Math.min(Number.isInteger(maxAttempts) ? maxAttempts : 1, MAX_NETWORK_ATTEMPTS))
-  const records = []
-  const record = (entry = {}) => {
-    if (records.length >= ceiling) return null
-    const next = safeTraceRecord({ traceId, turnRev, attempt: Math.min(records.length + 1, ceiling), ...entry })
-    records.push(next)
-    try { onRecord?.(next) } catch { /* observation must never affect the session */ }
-    return next
-  }
-  return {
-    get ceiling() { return ceiling },
-    get attempts() { return records.length },
-    get records() { return records.map((x) => ({ ...x })) },
-    canSubmit() { return records.length < ceiling },
-    record,
-  }
-}
-
-/** Memory-only circuit breaker keyed by bridge/provider/exact-model. */
-export function createMemoryCircuit({ now = () => Date.now() } = {}) {
-  const states = new Map()
-  const keyOf = ({ bridgeHostId, providerId, model } = {}) => `${bridgeHostId || ''}\u0000${providerId || ''}\u0000${model || ''}`
-  const stateFor = (target) => states.get(keyOf(target)) || { failures: [], openUntil: 0, probing: false }
-  const put = (target, state) => states.set(keyOf(target), state)
-  return {
-    preflight(target) {
-      const state = stateFor(target); const t = now()
-      if (state.openUntil > t) return { ok: false, state: 'open' }
-      if (state.openUntil && state.openUntil <= t) {
-        if (state.probing) return { ok: false, state: 'half_open_busy' }
-        state.probing = true; put(target, state); return { ok: true, state: 'half_open' }
-      }
-      return { ok: true, state: 'closed' }
-    },
-    success(target) { states.delete(keyOf(target)) },
-    failure(target, policy, failureClass) {
-      if (!TRANSIENT_FAILURES.has(failureClass)) return { state: this.preflight(target).state, counted: false }
-      const state = stateFor(target); const t = now(); const circuit = policy?.circuit || DEFAULT_RESILIENCE_POLICY.circuit
-      if (state.probing) { state.probing = false; state.failures = []; state.openUntil = t + circuit.cooldownMs; put(target, state); return { state: 'open', counted: true } }
-      state.failures = state.failures.filter((at) => at > t - circuit.windowMs)
-      state.failures.push(t)
-      if (state.failures.length >= circuit.failureThreshold) state.openUntil = t + circuit.cooldownMs
-      put(target, state)
-      return { state: state.openUntil > t ? 'open' : 'closed', counted: true }
-    },
-    // Test/diagnostic-only metadata. Never returns credentials, URLs, or prompts.
-    snapshot(target) { const s = stateFor(target); return { failures: s.failures.length, openUntil: s.openUntil, probing: s.probing } },
-  }
-}
-
-/**
- * Apply the only authoritative provider-work cap currently available at the
- * bridge boundary. Ordinary/uncapped lanes remain admissible, but the result
- * names that absence explicitly so the host can record `cap_not_configured`
- * rather than pretending an approval occurred.
- */
-export function providerResilienceCapAdmission(budget) {
-  if (!budget || budget.capTokens == null) {
-    return { allowed: true, configured: false, reason: 'cap_not_configured' }
-  }
-  const capTokens = Number(budget.capTokens)
-  const spentTokens = Number(budget.spentTokens)
-  const allowed = Number.isFinite(capTokens)
-    && capTokens >= 0
-    && Number.isFinite(spentTokens)
-    && spentTokens >= 0
-    && budget.killed !== true
-    && spentTokens < capTokens
-  return { allowed, configured: true, reason: allowed ? 'within_cap' : 'cap_blocked' }
-}
-
-/**
- * Pure, injected Phase-1 controller for a single exact custom Claude target.
- *
- * The bridge/session integration owns transport and invokes this controller at
- * turn start, before each submission, after visible output, and at terminal
- * success/failure. It intentionally has no fallback path and cannot resolve a
- * built-in Anthropic target. A caller must inject both the authoritative cap
- * admission gate and the bridge-scoped memory circuit; missing or broken gates
- * deny the submission rather than guessing that it is safe.
- */
-export function createSameTargetResilienceController({
-  runtime = 'claude', providers = [], providerId, model, requestedModel = model,
-  policy, bridgeHostId = null, circuit, capGate, traceId = 'local', turnRev = null,
-  onRecord = null,
-} = {}) {
-  let checked
-  try { checked = validateResiliencePolicy(policy, { providers, primaryProviderId: providerId }) } catch { checked = { ok: false } }
-  let target = null
-  try { target = resolveAttemptTarget({ runtime, providers, providerId, model }) } catch { /* malformed registry is not retryable */ }
-  const configured = checked?.ok && checked.value.enabled && target && runtime === 'claude'
-  const circuitReady = !!circuit && typeof circuit.preflight === 'function' && typeof circuit.failure === 'function' && typeof circuit.success === 'function'
-  const ceiling = configured ? Math.min(checked.value.maxAttempts, MAX_SAME_TARGET_ATTEMPTS) : 0
-  const targetKey = target && { bridgeHostId, providerId: target.providerId, model: target.actualConfiguredModel }
-  const base = target && {
-    traceId,
-    turnRev,
-    targetProviderId: target.providerId,
-    targetProviderName: target.targetProviderName,
-    requestedModel,
-    actualConfiguredModel: target.actualConfiguredModel,
-    phase: 'same_target',
-  }
-  let started = false
-  let submissions = 0
-  let awaitingOutcome = false
-  let retryEligible = false
-  let outputVisible = false
-  let toolOutputVisible = false
-  let aborted = false
-  let permissionDenied = false
-  let finished = false
-
-  const makeRecord = (outcome, extra = {}, attempt = submissions) => safeTraceRecord({
-    ...base,
-    attempt: Math.max(1, attempt),
-    outcome,
-    ...extra,
-  })
-  const emit = (outcome, extra) => {
-    const record = makeRecord(outcome, extra)
-    try { onRecord?.(record) } catch { /* trace observers are never control flow */ }
-    return record
-  }
-  const blocked = (outcome = 'failed', extra) => ({ admitted: false, record: emit(outcome, extra) })
-  const replaySafe = () => isReplaySafe({ outputVisible, toolOutputVisible, aborted, permissionDenied })
-
-  return {
-    /** Mark the controller as belonging to this turn; no provider work occurs here. */
-    start() { started = true },
-
-    /** Once any assistant/tool output is visible, automatic replay is permanently disabled. */
-    visibleOutput({ tool = false } = {}) {
-      outputVisible = true
-      if (tool) toolOutputVisible = true
-      retryEligible = false
-    },
-
-    /**
-     * Admit exactly one upcoming submission. The cap gate is awaited before
-     * transport, and any false/unknown/throwing result denies the attempt.
-     */
-    async preflight() {
-      if (!started) started = true
-      if (!configured || !circuitReady || finished || awaitingOutcome || submissions >= ceiling) return blocked()
-      if (submissions > 0 && (!retryEligible || !replaySafe())) return blocked()
-      const pending = makeRecord(submissions === 0 ? 'started' : 'retrying', {}, submissions + 1)
-      let admitted = false
-      try {
-        const result = await capGate?.(pending)
-        admitted = result === true || result?.allowed === true
-      } catch { admitted = false }
-      if (!admitted) return blocked('cap_blocked')
-      let circuitState
-      try { circuitState = circuit.preflight(targetKey) } catch { return blocked() }
-      if (!circuitState?.ok) return blocked('circuit_open')
-      submissions += 1
-      awaitingOutcome = true
-      retryEligible = false
-      return { admitted: true, record: emit(submissions === 1 ? 'started' : 'retrying') }
-    },
-
-    /** Classify a raw transport failure locally and expose only a coarse trace. */
-    failure(input = {}) {
-      if (!awaitingOutcome || finished) return null
-      awaitingOutcome = false
-      const failureClass = classifyProviderFailure(input)
-      if (failureClass === 'user_abort') aborted = true
-      if (failureClass === 'permission_denied') permissionDenied = true
-      let circuitUsable = true
-      if (TRANSIENT_FAILURES.has(failureClass)) {
-        try {
-          const state = circuit.failure(targetKey, checked.value, failureClass)
-          if (state?.state === 'open') circuitUsable = false
-        } catch { circuitUsable = false }
-      }
-      retryEligible = circuitUsable && checked.value.retryOn.includes(failureClass) && replaySafe() && submissions < ceiling
-      return emit('failed', { failureClass })
-    },
-
-    /** Close/reset the injected circuit after a completed provider response. */
-    success() {
-      if (!awaitingOutcome || finished) return null
-      awaitingOutcome = false
-      finished = true
-      try { circuit.success(targetKey) } catch { /* a completed response is never replayed */ }
-      return emit('succeeded')
-    },
-  }
-}
-
-export function safeTraceRecord(input = {}) {
-  const out = {}
-  for (const key of TRACE_FIELDS) {
-    if (input[key] === undefined || input[key] === null) continue
-    if (TRACE_TEXT_FIELDS.has(key)) {
-      const value = safeTraceText(input[key])
-      if (value) out[key] = value
-    } else if (key === 'turnRev') {
-      if (Number.isSafeInteger(input[key]) && input[key] >= 0) out[key] = input[key]
-    } else out[key] = input[key]
-  }
-  out.attempt = Math.max(1, Math.min(Number(out.attempt) || 1, MAX_NETWORK_ATTEMPTS))
-  if (!OUTCOMES.has(out.outcome)) out.outcome = 'failed'
-  if (out.failureClass && !/^[a-z0-9_]+$/.test(String(out.failureClass))) delete out.failureClass
-  for (const key of ['elapsedMs', 'retryAfterMs']) if (out[key] != null) out[key] = Math.max(0, Math.floor(Number(out[key]) || 0))
-  return out
-}
-
-/** A room-safe line assembled exclusively from the allowlisted coarse record. */
-export function formatResilienceTrace(input) {
-  const r = safeTraceRecord(input)
-  const target = [r.targetProviderName || r.targetProviderId, r.actualConfiguredModel].filter(Boolean).join(' / ') || 'configured provider'
-  const failure = r.failureClass ? ` (${r.failureClass.replaceAll('_', ' ')})` : ''
-  if (r.outcome === 'retrying') return `${target} unavailable${failure} — retrying once before output (attempt ${r.attempt} of ${MAX_SAME_TARGET_ATTEMPTS}).`
-  if (r.outcome === 'circuit_open') return `${target} is temporarily unavailable; its local circuit is open.`
-  if (r.outcome === 'cap_blocked') return `Additional provider work was blocked by the applicable cap.`
-  if (r.outcome === 'succeeded') return `${target} completed.`
-  if (r.outcome === 'fallback') return `Configured fallback selected: ${target}.`
-  return `${target} failed${failure}.`
-}
+import{isSecretFreeRoomPayload as e}from"./runtime-contract.mjs";export const RESILIENCE_VERSION=1;export const MAX_NETWORK_ATTEMPTS=3;export const MAX_SAME_TARGET_ATTEMPTS=2;export const TRANSIENT_FAILURES=new Set(["timeout","network","rate_limit","overload","upstream_5xx"]);const t=[...TRANSIENT_FAILURES],r=new Set(["traceId","turnRev","attempt","targetProviderId","targetProviderName","requestedModel","actualConfiguredModel","phase","outcome","failureClass","elapsedMs","retryAfterMs","fallbackFrom"]),o=new Set(["started","retrying","failed","fallback","succeeded","circuit_open","cap_blocked"]),i=new Set(["traceId","targetProviderId","targetProviderName","requestedModel","actualConfiguredModel","phase","failureClass","fallbackFrom"]),a=/(?:[a-z][a-z0-9+.-]*:\/\/|(?:^|[\s"'(])\/(?:Users|home|private|tmp)\/|[a-z]:\\|\\\\)/i;export const DEFAULT_RESILIENCE_POLICY=Object.freeze({v:1,enabled:!1,timeoutMs:9e4,maxAttempts:2,retryOn:t,circuit:Object.freeze({failureThreshold:3,windowMs:6e4,cooldownMs:3e4}),fallback:Object.freeze([])});const n=e=>!!e&&"object"==typeof e&&!Array.isArray(e),l=e=>Number.isInteger(e)&&e>0,s=e=>"string"==typeof e&&e.trim()?e.trim():null,c=t=>{const r=s(t);return!r||r.length>160||a.test(r)?null:e({value:r},512)?r:null};export function validateResiliencePolicy(e,{providers:r=[],primaryProviderId:o=null}={}){if(null==e)return{ok:!0,value:{...DEFAULT_RESILIENCE_POLICY,retryOn:[...t],circuit:{...DEFAULT_RESILIENCE_POLICY.circuit},fallback:[]}};if(!n(e)||1!==e.v)return{ok:!1,error:"unsupported resilience policy version"};if("boolean"!=typeof e.enabled)return{ok:!1,error:"enabled must be boolean"};if(!Number.isInteger(e.timeoutMs)||e.timeoutMs<3e4||e.timeoutMs>12e4)return{ok:!1,error:"timeoutMs must be 30000..120000"};if(!l(e.maxAttempts))return{ok:!1,error:"maxAttempts must be a positive integer"};if(!Array.isArray(e.retryOn)||e.retryOn.some(e=>!TRANSIENT_FAILURES.has(e)))return{ok:!1,error:"retryOn contains an unsupported failure class"};if(!(n(e.circuit)&&l(e.circuit.failureThreshold)&&l(e.circuit.windowMs)&&l(e.circuit.cooldownMs)))return{ok:!1,error:"invalid circuit policy"};if(!Array.isArray(e.fallback))return{ok:!1,error:"fallback must be an array"};const i=[];for(const t of e.fallback){if(!n(t)||!s(t.providerId)||!s(t.model)||!0!==t.allow)return{ok:!1,error:"invalid fallback target"};if("same"!==t.privacyClass||!["same","same-or-lower"].includes(t.costClass))return{ok:!1,error:"fallback privacy/cost class is not eligible"};if(o&&t.providerId===o)return{ok:!1,error:"fallback cannot target itself"};if(r.length){const e=r.find(e=>e?.id===t.providerId);if(!e||"anthropic"===e.id||e.model!==t.model)return{ok:!1,error:"fallback must name a registered exact provider/model target"}}i.push({providerId:s(t.providerId),model:s(t.model),allow:!0,privacyClass:t.privacyClass,costClass:t.costClass})}return{ok:!0,value:{v:1,enabled:e.enabled,timeoutMs:e.timeoutMs,maxAttempts:Math.min(e.maxAttempts,3),retryOn:[...new Set(e.retryOn)],circuit:{failureThreshold:e.circuit.failureThreshold,windowMs:e.circuit.windowMs,cooldownMs:e.circuit.cooldownMs},fallback:i}}}export function resilienceProjection(e){const t=validateResiliencePolicy(e);if(!t.ok)return null;const r=t.value;return{v:r.v,enabled:r.enabled,timeoutMs:r.timeoutMs,maxAttempts:r.maxAttempts,retryOn:[...r.retryOn],circuit:{...r.circuit},fallback:r.fallback.map(e=>({...e}))}}export function classifyProviderFailure(e={}){const t=Number(e.status||e.statusCode||0),r=String(e.code||"").toLowerCase(),o=String(e.message||e.error?.message||"").toLowerCase();return e.aborted||/\babort(ed|error)?\b|cancelled|canceled/.test(`${r} ${o}`)?"user_abort":e.permissionDenied||/permission denied|forbidden by policy|guardrail/.test(`${r} ${o}`)?"permission_denied":401===t||403===t||/unauthori[sz]ed|invalid (api )?key|credential/.test(`${r} ${o}`)?"auth":429===t||/rate.?limit/.test(`${r} ${o}`)?"rate_limit":529===t||/overload|overloaded/.test(`${r} ${o}`)?"overload":t>=500&&t<=599?"upstream_5xx":/timeout|timed out|deadline exceeded|etimedout/.test(`${r} ${o}`)?"timeout":/econnreset|enotfound|eai_again|socket|connection (closed|reset)|fetch failed|network error/.test(`${r} ${o}`)?"network":400===t||/invalid model|unknown model/.test(`${r} ${o}`)?"invalid_model":/context length|request too large|payload too large|too many tokens/.test(`${r} ${o}`)?"request_too_large":t>=400&&t<500?"invalid_request":"unknown"}export const isReplaySafe=({outputVisible:e=!1,toolOutputVisible:t=!1,aborted:r=!1,permissionDenied:o=!1,nonIdempotent:i=!1}={})=>!(e||t||r||o||i);export function resolveAttemptTarget({runtime:e="claude",providers:t=[],providerId:r,model:o}={}){if("claude"!==e||!s(r)||!s(o))return null;const i=t.find(e=>e&&e.id===r&&"anthropic"!==e.id&&e.model===o);return i?{providerId:i.id,targetProviderName:s(i.name)||i.id,actualConfiguredModel:i.model}:null}export function assessFallbackEligibility({runtime:e="claude",providers:t=[],primary:r,candidate:o,policy:i,outputVisible:a=!1,toolOutputVisible:n=!1,aborted:l=!1,permissionDenied:s=!1,capAllowed:c=!0,circuit:u="closed"}={}){if(!isReplaySafe({outputVisible:a,toolOutputVisible:n,aborted:l,permissionDenied:s}))return{ok:!1,reason:"replay_unsafe"};if("closed"!==u)return{ok:!1,reason:"circuit_open"};if(!c)return{ok:!1,reason:"cap_blocked"};const d=validateResiliencePolicy(i);if(!d.ok||!d.value.enabled||"claude"!==e)return{ok:!1,reason:"policy_disabled"};const p=resolveAttemptTarget({runtime:e,providers:t,providerId:o?.providerId,model:o?.model});if(!p)return{ok:!1,reason:"unknown_target"};const f=d.value.fallback.find(e=>e.providerId===p.providerId&&e.model===p.actualConfiguredModel);return f?.allow?"same"===f.privacyClass&&["same","same-or-lower"].includes(f.costClass)?r?.providerId===p.providerId&&r?.actualConfiguredModel===p.actualConfiguredModel?{ok:!1,reason:"same_target"}:{ok:!0,target:p,fallback:f}:{ok:!1,reason:"boundary_not_consented"}:{ok:!1,reason:"not_explicitly_allowed"}}export function createAttemptLedger({maxAttempts:e=3,traceId:t="local",turnRev:r=null,onRecord:o=null}={}){const i=Math.max(1,Math.min(Number.isInteger(e)?e:1,3)),a=[];return{get ceiling(){return i},get attempts(){return a.length},get records(){return a.map(e=>({...e}))},canSubmit:()=>a.length<i,record:(e={})=>{if(a.length>=i)return null;const n=safeTraceRecord({traceId:t,turnRev:r,attempt:Math.min(a.length+1,i),...e});a.push(n);try{o?.(n)}catch{}return n}}}export function createMemoryCircuit({now:e=()=>Date.now()}={}){const t=new Map,r=({bridgeHostId:e,providerId:t,model:r}={})=>`${e||""}\0${t||""}\0${r||""}`,o=e=>t.get(r(e))||{failures:[],openUntil:0,probing:!1},i=(e,o)=>t.set(r(e),o);return{preflight(t){const r=o(t),a=e();return r.openUntil>a?{ok:!1,state:"open"}:r.openUntil&&r.openUntil<=a?r.probing?{ok:!1,state:"half_open_busy"}:(r.probing=!0,i(t,r),{ok:!0,state:"half_open"}):{ok:!0,state:"closed"}},success(e){t.delete(r(e))},failure(t,r,a){if(!TRANSIENT_FAILURES.has(a))return{state:this.preflight(t).state,counted:!1};const n=o(t),l=e(),s=r?.circuit||DEFAULT_RESILIENCE_POLICY.circuit;return n.probing?(n.probing=!1,n.failures=[],n.openUntil=l+s.cooldownMs,i(t,n),{state:"open",counted:!0}):(n.failures=n.failures.filter(e=>e>l-s.windowMs),n.failures.push(l),n.failures.length>=s.failureThreshold&&(n.openUntil=l+s.cooldownMs),i(t,n),{state:n.openUntil>l?"open":"closed",counted:!0})},snapshot(e){const t=o(e);return{failures:t.failures.length,openUntil:t.openUntil,probing:t.probing}}}}export function providerResilienceCapAdmission(e){if(!e||null==e.capTokens)return{allowed:!0,configured:!1,reason:"cap_not_configured"};const t=Number(e.capTokens),r=Number(e.spentTokens),o=Number.isFinite(t)&&t>=0&&Number.isFinite(r)&&r>=0&&!0!==e.killed&&r<t;return{allowed:o,configured:!0,reason:o?"within_cap":"cap_blocked"}}export function createSameTargetResilienceController({runtime:e="claude",providers:t=[],providerId:r,model:o,requestedModel:i=o,policy:a,bridgeHostId:n=null,circuit:l,capGate:s,traceId:c="local",turnRev:u=null,onRecord:d=null}={}){let p;try{p=validateResiliencePolicy(a,{providers:t,primaryProviderId:r})}catch{p={ok:!1}}let f=null;try{f=resolveAttemptTarget({runtime:e,providers:t,providerId:r,model:o})}catch{}const m=p?.ok&&p.value.enabled&&f&&"claude"===e,b=!!l&&"function"==typeof l.preflight&&"function"==typeof l.failure&&"function"==typeof l.success,v=m?Math.min(p.value.maxAttempts,2):0,g=f&&{bridgeHostId:n,providerId:f.providerId,model:f.actualConfiguredModel},y=f&&{traceId:c,turnRev:u,targetProviderId:f.providerId,targetProviderName:f.targetProviderName,requestedModel:i,actualConfiguredModel:f.actualConfiguredModel,phase:"same_target"};let k=!1,h=0,I=!1,_=!1,M=!1,w=!1,A=!1,C=!1,R=!1;const T=(e,t={},r=h)=>safeTraceRecord({...y,attempt:Math.max(1,r),outcome:e,...t}),x=(e,t)=>{const r=T(e,t);try{d?.(r)}catch{}return r},E=(e="failed",t)=>({admitted:!1,record:x(e,t)}),N=()=>isReplaySafe({outputVisible:M,toolOutputVisible:w,aborted:A,permissionDenied:C});return{start(){k=!0},visibleOutput({tool:e=!1}={}){M=!0,e&&(w=!0),_=!1},async preflight(){if(k||(k=!0),!m||!b||R||I||h>=v)return E();if(h>0&&(!_||!N()))return E();const e=T(0===h?"started":"retrying",{},h+1);let t,r=!1;try{const t=await(s?.(e));r=!0===t||!0===t?.allowed}catch{r=!1}if(!r)return E("cap_blocked");try{t=l.preflight(g)}catch{return E()}return t?.ok?(h+=1,I=!0,_=!1,{admitted:!0,record:x(1===h?"started":"retrying")}):E("circuit_open")},failure(e={}){if(!I||R)return null;I=!1;const t=classifyProviderFailure(e);"user_abort"===t&&(A=!0),"permission_denied"===t&&(C=!0);let r=!0;if(TRANSIENT_FAILURES.has(t))try{const e=l.failure(g,p.value,t);"open"===e?.state&&(r=!1)}catch{r=!1}return _=r&&p.value.retryOn.includes(t)&&N()&&h<v,x("failed",{failureClass:t})},success(){if(!I||R)return null;I=!1,R=!0;try{l.success(g)}catch{}return x("succeeded")}}}export function safeTraceRecord(e={}){const t={};for(const o of r)if(void 0!==e[o]&&null!==e[o])if(i.has(o)){const r=c(e[o]);r&&(t[o]=r)}else"turnRev"===o?Number.isSafeInteger(e[o])&&e[o]>=0&&(t[o]=e[o]):t[o]=e[o];t.attempt=Math.max(1,Math.min(Number(t.attempt)||1,3)),o.has(t.outcome)||(t.outcome="failed"),t.failureClass&&!/^[a-z0-9_]+$/.test(String(t.failureClass))&&delete t.failureClass;for(const e of["elapsedMs","retryAfterMs"])null!=t[e]&&(t[e]=Math.max(0,Math.floor(Number(t[e])||0)));return t}export function formatResilienceTrace(e){const t=safeTraceRecord(e),r=[t.targetProviderName||t.targetProviderId,t.actualConfiguredModel].filter(Boolean).join(" / ")||"configured provider",o=t.failureClass?` (${t.failureClass.replaceAll("_"," ")})`:"";return"retrying"===t.outcome?`${r} unavailable${o} — retrying once before output (attempt ${t.attempt} of 2).`:"circuit_open"===t.outcome?`${r} is temporarily unavailable; its local circuit is open.`:"cap_blocked"===t.outcome?"Additional provider work was blocked by the applicable cap.":"succeeded"===t.outcome?`${r} completed.`:"fallback"===t.outcome?`Configured fallback selected: ${r}.`:`${r} failed${o}.`}

package/provider.mjs

@@ -1,133 +1 @@
-/* ─────────────────────────────────────────────────────────────
-   provider.mjs — per-machine LLM provider choice for the ThinkPool
-   bridge. Lets a Code room run on ANY Anthropic-compatible endpoint
-   (Z.ai GLM, OpenRouter, a local proxy, …) instead of plain Anthropic,
-   INDEPENDENT of the launching shell. Why this exists: the launchd
-   service does NOT source ~/.zshrc, so a shell `export ANTHROPIC_*` can
-   never reach a serviced bridge — its spawned Claude children fall back
-   to the host's claude.ai login and hit the Anthropic spend wall.
-   provider.json is the bridge's OWN source of truth.
-
-   applyProviderEnv() runs once at the top of bridge.mjs (the universal
-   entry point), BEFORE any child is spawned. It sets ANTHROPIC_BASE_URL
-   / ANTHROPIC_AUTH_TOKEN / ANTHROPIC_MODEL on process.env. Because the
-   account-supervisor spawn (account.mjs) and the Agent-SDK env
-   (claude-session.mjs) both spread `...process.env`, the choice reaches
-   every code session with no other change. Default (no file, or
-   provider:"anthropic") = the host's regular Claude login, untouched.
-
-   CLI-agent-compatible ONLY. The bridge spawns the `claude` CLI, which
-   talks the Anthropic Messages API — so the base url MUST be an
-   Anthropic-compatible root (the SDK appends /v1/messages). An OpenAI-
-   style /v1/chat/completions endpoint will NOT work. Common roots:
-     Z.ai GLM    → https://api.z.ai/api/anthropic
-     OpenRouter  → https://openrouter.ai/api
-
-   CLI (dispatched from bridge.mjs):
-     npx thinkpool-pair provider                                            # show current
-     npx thinkpool-pair provider custom --base <url> --token <key> [--model <m>]   # any Anthropic-compatible endpoint
-     npx thinkpool-pair provider anthropic                                  # reset to Claude
-   ───────────────────────────────────────────────────────────── */
-import os from 'node:os'
-import fs from 'node:fs'
-import path from 'node:path'
-import { pairCli } from './command-guidance.mjs'
-
-const DIR = path.join(os.homedir(), '.thinkpool-pair')
-const FILE = path.join(DIR, 'provider.json')
-
-function ensureDir() { try { fs.mkdirSync(DIR, { recursive: true }) } catch { /* noop */ } }
-function opt(args, flag) { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : undefined }
-
-export function loadProvider() {
-  try { return JSON.parse(fs.readFileSync(FILE, 'utf8')) } catch { return null }
-}
-
-export function saveProvider(p) {
-  ensureDir()
-  fs.writeFileSync(FILE, JSON.stringify(p, null, 2), { mode: 0o600 })
-}
-
-/**
- * Merge the persisted provider choice (or TP_* env overrides) into
- * process.env. Call once at startup, before spawning any child. Idempotent.
- * A no-op for the default Anthropic provider — we only ever SET the custom
- * vars, never clobber a host's real Claude login env. Env vars win over the
- * file so a one-off launch can flip providers without writing anything.
- *
- * Provider-name-agnostic: any provider saved to provider.json (glm, custom,
- * a leftover openrouter file, …) is handled by one branch that only cares
- * that baseUrl/authToken are present.
- * @returns {{provider:string,baseUrl?:string,model?:string,source:string}}
- */
-export function applyProviderEnv() {
-  const cfg = loadProvider() || {}
-  const provider = (process.env.TP_PROVIDER || cfg.provider || 'anthropic').toLowerCase()
-  if (provider === 'anthropic' || !provider) return { provider: 'anthropic', source: 'default' }
-
-  const baseUrl   = process.env.TP_ANTHROPIC_BASE_URL   || cfg.baseUrl
-  const authToken = process.env.TP_ANTHROPIC_AUTH_TOKEN || cfg.authToken
-  const model     = process.env.TP_ANTHROPIC_MODEL      || cfg.model
-  if (!baseUrl || !authToken) {
-    process.stderr.write(`\n  ◇ provider "${provider}" is set but is missing baseUrl/authToken.\n    Finish setup:  ${pairCli('provider', 'custom', '--base', '<url>', '--token', '<key>')}\n    Falling back to regular Claude for now.\n`)
-    return { provider: 'anthropic', source: 'incomplete' }
-  }
-  process.env.ANTHROPIC_BASE_URL = baseUrl
-  process.env.ANTHROPIC_AUTH_TOKEN = authToken
-  if (model) process.env.ANTHROPIC_MODEL = model
-  return { provider, baseUrl, model, source: cfg.provider ? 'file' : 'env' }
-}
-
-/** CLI handler for `thinkpool-pair provider [...]`. */
-export async function runProvider(args) {
-  const sub = (args[0] || '').toLowerCase()
-
-  // ── show ──
-  if (!sub || sub === 'show' || sub === 'status') {
-    const cfg = loadProvider()
-    if (!cfg || cfg.provider === 'anthropic' || !cfg.provider) {
-      console.error('\n  ◆ provider: anthropic (regular Claude login) — the default.\n')
-    } else {
-      console.error(`\n  ◆ provider: ${cfg.provider}\n    base url: ${cfg.baseUrl || '(unset)'}\n    model:    ${cfg.model || '(unset)'}\n    token:    ${cfg.authToken ? cfg.authToken.slice(0, 8) + '…' : '(unset)'}\n`)
-    }
-    return
-  }
-
-  // ── reset to Anthropic ──
-  if (sub === 'anthropic' || sub === 'clear' || sub === 'reset') {
-    try { fs.unlinkSync(FILE) } catch { /* noop */ }
-    console.error('\n  ✓ provider reset to anthropic (regular Claude login).\n')
-    return
-  }
-
-  // ── any Anthropic-compatible endpoint ──
-  if (sub === 'custom') {
-    const token   = opt(args, '--token') || opt(args, '--key')
-    const baseUrl = opt(args, '--base')  || opt(args, '--base-url')
-    const model   = opt(args, '--model')
-    if (!token || !baseUrl) {
-      console.error(
-        '\n  ✗ custom needs --base <url> and --token <key>. [--model <name>] is optional.\n' +
-        '    The base url is the Anthropic-compatible root the SDK appends /v1/messages to:\n' +
-        '      Z.ai GLM    → https://api.z.ai/api/anthropic\n' +
-        '      OpenRouter  → https://openrouter.ai/api\n' +
-        '    Restart the bridge (or its launchd service) to apply.\n'
-      )
-      process.exit(1)
-    }
-    saveProvider({ provider: 'custom', baseUrl, authToken: token, model: model || undefined, savedAt: Date.now() })
-    console.error(`\n  ✓ provider set to custom.\n    base url: ${baseUrl}\n    model:    ${model || '(default)'}\n    token:    ${token.slice(0, 8)}…\n    Restart the bridge (or its launchd service) to apply.\n`)
-    return
-  }
-
-  console.error(
-    '\n  usage:\n' +
-    `    ${pairCli('provider')}                                            # show current\n` +
-    `    ${pairCli('provider', 'custom', '--base', '<url>', '--token', '<key>', '[--model <m>]')}   # any Anthropic-compatible endpoint\n` +
-    `    ${pairCli('provider', 'anthropic')}                                  # reset to Claude\n\n` +
-    '  common base urls (SDK appends /v1/messages):\n' +
-    '    Z.ai GLM    → https://api.z.ai/api/anthropic\n' +
-    '    OpenRouter  → https://openrouter.ai/api\n'
-  )
-  process.exit(1)
-}
+import e from"node:os";import r from"node:fs";import o from"node:path";import{pairCli as n}from"./command-guidance.mjs";const t=o.join(e.homedir(),".thinkpool-pair"),s=o.join(t,"provider.json");function i(e,r){const o=e.indexOf(r);return o>=0?e[o+1]:void 0}export function loadProvider(){try{return JSON.parse(r.readFileSync(s,"utf8"))}catch{return null}}export function saveProvider(e){!function(){try{r.mkdirSync(t,{recursive:!0})}catch{}}(),r.writeFileSync(s,JSON.stringify(e,null,2),{mode:384})}export function applyProviderEnv(){const e=loadProvider()||{},r=(process.env.TP_PROVIDER||e.provider||"anthropic").toLowerCase();if("anthropic"===r||!r)return{provider:"anthropic",source:"default"};const o=process.env.TP_ANTHROPIC_BASE_URL||e.baseUrl,t=process.env.TP_ANTHROPIC_AUTH_TOKEN||e.authToken,s=process.env.TP_ANTHROPIC_MODEL||e.model;return o&&t?(process.env.ANTHROPIC_BASE_URL=o,process.env.ANTHROPIC_AUTH_TOKEN=t,s&&(process.env.ANTHROPIC_MODEL=s),{provider:r,baseUrl:o,model:s,source:e.provider?"file":"env"}):(process.stderr.write(`\n  ◇ provider "${r}" is set but is missing baseUrl/authToken.\n    Finish setup:  ${n("provider","custom","--base","<url>","--token","<key>")}\n    Falling back to regular Claude for now.\n`),{provider:"anthropic",source:"incomplete"})}export async function runProvider(e){const o=(e[0]||"").toLowerCase();if(!o||"show"===o||"status"===o){const e=loadProvider();return void(e&&"anthropic"!==e.provider&&e.provider?console.error(`\n  ◆ provider: ${e.provider}\n    base url: ${e.baseUrl||"(unset)"}\n    model:    ${e.model||"(unset)"}\n    token:    ${e.authToken?e.authToken.slice(0,8)+"…":"(unset)"}\n`):console.error("\n  ◆ provider: anthropic (regular Claude login) — the default.\n"))}if("anthropic"!==o&&"clear"!==o&&"reset"!==o){if("custom"===o){const r=i(e,"--token")||i(e,"--key"),o=i(e,"--base")||i(e,"--base-url"),n=i(e,"--model");return r&&o||(console.error("\n  ✗ custom needs --base <url> and --token <key>. [--model <name>] is optional.\n    The base url is the Anthropic-compatible root the SDK appends /v1/messages to:\n      Z.ai GLM    → https://api.z.ai/api/anthropic\n      OpenRouter  → https://openrouter.ai/api\n    Restart the bridge (or its launchd service) to apply.\n"),process.exit(1)),saveProvider({provider:"custom",baseUrl:o,authToken:r,model:n||void 0,savedAt:Date.now()}),void console.error(`\n  ✓ provider set to custom.\n    base url: ${o}\n    model:    ${n||"(default)"}\n    token:    ${r.slice(0,8)}…\n    Restart the bridge (or its launchd service) to apply.\n`)}console.error(`\n  usage:\n    ${n("provider")}                                            # show current\n    ${n("provider","custom","--base","<url>","--token","<key>","[--model <m>]")}   # any Anthropic-compatible endpoint\n    ${n("provider","anthropic")}                                  # reset to Claude\n\n  common base urls (SDK appends /v1/messages):\n    Z.ai GLM    → https://api.z.ai/api/anthropic\n    OpenRouter  → https://openrouter.ai/api\n`),process.exit(1)}else{try{r.unlinkSync(s)}catch{}console.error("\n  ✓ provider reset to anthropic (regular Claude login).\n")}}