agentfootprint 10.3.0 → 10.4.0

package/dist/esm/core/agent/toolEffects.d.ts

@@ -1,210 +0,0 @@
-/**
- * toolEffects — the typed tool-effects channel (9.19.0). ONE owner of the
- * result-envelope grammar: the two effect kinds, the outcome-status
- * vocabulary, the envelope recognizer, and the instruction-lease shapes.
- *
- * THE LAW this module implements: *push mandatory procedure; pull optional
- * knowledge; never let arbitrary text promote itself into control authority.*
- * Before this channel, a tool that wanted to steer the run had exactly one
- * medium — its result STRING — and any convention riding it ("ROUTE:billing")
- * was arbitrary text one prompt-injection away from control authority. The
- * envelope replaces the convention with DATA the framework validates:
- *
- *   • `propose-transition` — the typed replacement for string routing
- *     markers. The GRAPH decides: an accepted proposal moves the cursor like
- *     a declared edge (a same-batch declared edge still wins — the
- *     `reroute_superseded` precedent), a refusal is teaching and recorded.
- *     Proposals come from TOOLS — deterministic code the author shipped — so
- *     they are framework-tier evidence: admitted under every posture
- *     (`assist`/`guard`/`rails`), but always reachability-checked against
- *     the graph's own law. An unreachable target is refused, out loud.
- *
- *   • `require-instruction` — pushes a REGISTERED instruction (a skill body
- *     or a declared snippet) into the next iteration(s) per a delivery
- *     lease. `read_skill` stays the pull door; this is the push door, and it
- *     can only push what was registered at build — an unknown id is refused,
- *     never improvised.
- *
- * Beside the effects rides an optional `status` — the outcome-status
- * normalization: `'denied'` must never route like `'success'`, so route
- * edges can key on MEANING (`onToolStatus`) instead of parsing prose.
- *
- * RECOGNITION IS STRICT, and the strictness is the zero-cost guarantee.
- * A value is an envelope iff it is a plain object whose keys are a subset of
- * `{ content, effects, status }`, `content` is present, `effects` is an
- * array, and EVERY element carries one of the two known `kind`s (an empty
- * `effects: []` needs a valid `status` to say anything at all). Everything
- * else — every shape any tool has ever returned — takes the exact path it
- * always took, byte for byte. The two `kind` strings are therefore RESERVED
- * vocabulary on the tool-result wire; a recognized envelope whose fields are
- * malformed is refused teachingly (recorded), never half-applied.
- */
-/**
- * The outcome words, re-exported under the names they have always had.
- *
- * They are DECLARED in `lib/injection-engine/toolOutcome.ts` (9.34.0) — a
- * zero-import leaf — because a skill-graph route edge keys on them
- * (`onToolStatus`) and `InjectionContext.toolResults[].status` is typed by
- * them. Leaving the declaration here meant the graph's own context type
- * reached into the agent loop for one string union, which points the
- * dependency backwards: the loop depends on the graph, never the reverse.
- *
- * This module remains the owner of the ENVELOPE grammar below — the two
- * effect kinds, the recognizer, the lease shapes — all of which are
- * genuinely loop-side. Only the vocabulary moved down.
- */
-export type { ToolResultStatus } from '../../lib/injection-engine/toolOutcome.js';
-export { TOOL_RESULT_STATUSES } from '../../lib/injection-engine/toolOutcome.js';
-import type { ToolResultStatus } from '../../lib/injection-engine/toolOutcome.js';
-/** A tool proposes moving the skill-graph cursor. The graph decides. */
-export interface ProposeTransitionEffect {
-    readonly kind: 'propose-transition';
-    /** The skill node to move to. Reachability-checked against the graph's
-     *  own law (`reachableSkills(cursor)`); unreachable = teaching refusal. */
-    readonly targetSkillId: string;
-    /** Why — goes on the record (`tools.effect`), never optional: a routing
-     *  proposal with no reason is exactly the arbitrary authority this
-     *  channel exists to replace. */
-    readonly reason: string;
-}
-/** How long a pushed instruction stays delivered. */
-export type InstructionDeliveryLease = 'next-call' | 'until-skill-exit';
-/** A tool pushes a registered instruction into the coming iteration(s). */
-export interface RequireInstructionEffect {
-    readonly kind: 'require-instruction';
-    /** A REGISTERED injection id (a skill or an instruction). Unknown ids are
-     *  refused teachingly — the push door serves the declared catalog only. */
-    readonly instructionId: string;
-    /** `'next-call'` — exactly the next LLM call; `'until-skill-exit'` — every
-     *  call while the tenure that granted it holds (the skill the cursor was
-     *  on when the tool returned). */
-    readonly deliveryLease: InstructionDeliveryLease;
-}
-/** The typed effects a tool result may carry. Two kinds — deliberately. */
-export type ProposedEffect = ProposeTransitionEffect | RequireInstructionEffect;
-/**
- * What a tool handler returns to opt into the channel:
- * `{ content, effects, status? }`. `content` is what the model reads (any
- * value — strings pass through, objects stringify exactly as a bare return
- * would). Returning anything else keeps today's path, byte for byte.
- *
- * `effects` is REQUIRED — it is the envelope marker itself. The recognizer
- * refuses to treat a value without an `effects` array as an envelope (that
- * strictness IS the zero-cost guarantee: `{ content, status: 'success' }`
- * is a shape a domain object could already have), so the type says exactly
- * what the recognizer accepts. Status-only is spelled `effects: []` — the
- * explicit marker when only `status` matters.
- */
-export interface ToolResultEnvelope {
-    readonly content: unknown;
-    readonly effects: readonly ProposedEffect[];
-    readonly status?: ToolResultStatus;
-}
-/** A recognized envelope, read: content unwrapped, VALID effects listed,
- *  malformed ones named (one teaching entry per bad effect). */
-export interface ReadToolResultEnvelope {
-    readonly content: unknown;
-    readonly effects: readonly ProposedEffect[];
-    readonly status?: ToolResultStatus;
-    /** Effects that carried a known `kind` with malformed fields — refused
-     *  loudly (recorded + a teaching sentence), never half-applied. */
-    readonly malformed: ReadonlyArray<{
-        readonly kind: ProposedEffect['kind'];
-        readonly refusalReason: string;
-    }>;
-}
-/**
- * Recognize (or decline to recognize) a tool's return value as an effects
- * envelope. `undefined` = not an envelope: the caller keeps today's path
- * untouched. See the module header for the exact recognition rule and why
- * it is strict.
- */
-export declare function readToolResultEnvelope(result: unknown): ReadToolResultEnvelope | undefined;
-/**
- * Name the ONE near-miss a tool author is likeliest to write: a status-only
- * envelope with the `effects` marker left off — `{ content, status: 'denied' }`.
- * That shape is NOT an envelope (recognition demands the `effects` array;
- * see `ToolResultEnvelope`), and it stays data byte-for-byte — but a value
- * whose only keys are envelope keys AND whose `status` speaks the closed
- * outcome vocabulary is far more likely a dropped `effects: []` than a
- * coincidence, and letting it route like an undeclared result with no word
- * of why would be accepted-and-silently-wrong. Returns the teaching sentence
- * for the caller's dev-mode warning; `undefined` for every other value.
- * Diagnosis only — never changes what any value does.
- */
-export declare function explainStatusOnlyNearMiss(result: unknown): string | undefined;
-/**
- * The transition proposal the tool-calls stage ACCEPTED this iteration —
- * validated (graph mounted, target reachable), first-accepted-wins across
- * the batch. One-shot BY DATA, not by clearing writes: it is stamped with
- * the iteration that granted it, and the Evaluate stage honors it exactly
- * once — on the following iteration — so nothing ever has to write the key
- * back to undefined (zero-cost stays zero for agents that never see one).
- */
-export interface PendingToolTransition {
-    readonly targetSkillId: string;
-    /** The proposing tool — provenance for the record. */
-    readonly toolName: string;
-    readonly toolCallId?: string;
-    /** The effect's own declared reason. */
-    readonly reason: string;
-    /** The ReAct iteration whose batch granted it (valid for iteration + 1). */
-    readonly iteration: number;
-}
-/**
- * One granted `require-instruction` lease. Validity is COMPUTED, never
- * mutated: `'next-call'` serves exactly the Evaluate pass of
- * `iteration + 1`; `'until-skill-exit'` serves every pass while the tenant
- * that granted it (`skillId`) still holds the tenure.
- *
- * Death is PERMANENT, and the Evaluate tenure sweep is what makes it so:
- * `skillId === tenant` alone cannot tell "still holding the tenure" from
- * "re-entered the skill later" (a cyclic graph makes both real), so the
- * Evaluate stage prunes dead leases on EVERY pass — the same pass a tenure
- * ends, the leases it granted leave the record, and a cursor that comes back
- * finds nothing to resurrect. The tool-calls stage also prunes when it
- * appends a new grant (keeps mid-batch arrays tight), but the sweep is the
- * law's owner: it runs whether or not anything new was granted.
- */
-export interface InstructionLease {
-    readonly instructionId: string;
-    readonly deliveryLease: InstructionDeliveryLease;
-    /** The tenure that granted it (advanced cursor, else the activation tail);
-     *  absent when no tenant existed at grant. `'until-skill-exit'` compares
-     *  the CURRENT tenant against this — both-undefined still matches. */
-    readonly skillId?: string;
-    /** The granting tool — provenance for the record. */
-    readonly toolName: string;
-    readonly toolCallId?: string;
-    /** The ReAct iteration whose batch granted it. */
-    readonly iteration: number;
-}
-/** Who holds the tenure — the advanced cursor on graph agents, else the tail
- *  of `activatedInjectionIds` (the shipped `activeSkillId` notion the step
- *  pointer's re-key already uses). */
-export declare function tenantOf(cursor: string | undefined, activatedInjectionIds: readonly string[] | undefined): string | undefined;
-/**
- * The lease-served injection ids for ONE Evaluate pass — pure. `iteration`
- * is the pass being composed; `tenant` is who holds the tenure on it (the
- * ADVANCED cursor — a lease dies the same pass its tenure ends).
- *
- * `skillId === tenant` is a sound "tenure still holds" test ONLY because the
- * Evaluate tenure sweep (`pruneLeases`, every pass) removes a dead lease the
- * pass its tenure ends — so a cursor that re-enters the granting skill later
- * finds nothing to match, instead of resurrecting an ended grant.
- */
-export declare function activeLeaseIds(leases: readonly InstructionLease[] | undefined, iteration: number, tenant: string | undefined): readonly string[];
-/**
- * Drop leases that can never serve again. `iteration` is the CURRENT pass;
- * a `'next-call'` lease older than the previous iteration is spent, and an
- * `'until-skill-exit'` lease whose tenant is no longer current is dead.
- *
- * TWO call sites, one law. The Evaluate stage sweeps on EVERY pass (writing
- * the survivors under `nextInstructionLeases`, the cursor's alias round
- * trip) — that sweep is what makes death permanent: it records the death the
- * same pass the tenure ends, before any later pass could see the cursor
- * re-enter the granting skill and mistake re-entry for an unbroken tenure.
- * The tool-calls stage also prunes when it appends a new grant, so a
- * mid-batch array never carries spent leases into the commit.
- */
-export declare function pruneLeases(leases: readonly InstructionLease[] | undefined, iteration: number, currentTenant: string | undefined): readonly InstructionLease[];

package/dist/esm/core/agent/toolEffects.js

@@ -1,227 +0,0 @@
-/**
- * toolEffects — the typed tool-effects channel (9.19.0). ONE owner of the
- * result-envelope grammar: the two effect kinds, the outcome-status
- * vocabulary, the envelope recognizer, and the instruction-lease shapes.
- *
- * THE LAW this module implements: *push mandatory procedure; pull optional
- * knowledge; never let arbitrary text promote itself into control authority.*
- * Before this channel, a tool that wanted to steer the run had exactly one
- * medium — its result STRING — and any convention riding it ("ROUTE:billing")
- * was arbitrary text one prompt-injection away from control authority. The
- * envelope replaces the convention with DATA the framework validates:
- *
- *   • `propose-transition` — the typed replacement for string routing
- *     markers. The GRAPH decides: an accepted proposal moves the cursor like
- *     a declared edge (a same-batch declared edge still wins — the
- *     `reroute_superseded` precedent), a refusal is teaching and recorded.
- *     Proposals come from TOOLS — deterministic code the author shipped — so
- *     they are framework-tier evidence: admitted under every posture
- *     (`assist`/`guard`/`rails`), but always reachability-checked against
- *     the graph's own law. An unreachable target is refused, out loud.
- *
- *   • `require-instruction` — pushes a REGISTERED instruction (a skill body
- *     or a declared snippet) into the next iteration(s) per a delivery
- *     lease. `read_skill` stays the pull door; this is the push door, and it
- *     can only push what was registered at build — an unknown id is refused,
- *     never improvised.
- *
- * Beside the effects rides an optional `status` — the outcome-status
- * normalization: `'denied'` must never route like `'success'`, so route
- * edges can key on MEANING (`onToolStatus`) instead of parsing prose.
- *
- * RECOGNITION IS STRICT, and the strictness is the zero-cost guarantee.
- * A value is an envelope iff it is a plain object whose keys are a subset of
- * `{ content, effects, status }`, `content` is present, `effects` is an
- * array, and EVERY element carries one of the two known `kind`s (an empty
- * `effects: []` needs a valid `status` to say anything at all). Everything
- * else — every shape any tool has ever returned — takes the exact path it
- * always took, byte for byte. The two `kind` strings are therefore RESERVED
- * vocabulary on the tool-result wire; a recognized envelope whose fields are
- * malformed is refused teachingly (recorded), never half-applied.
- */
-export { TOOL_RESULT_STATUSES } from '../../lib/injection-engine/toolOutcome.js';
-import { TOOL_RESULT_STATUSES } from '../../lib/injection-engine/toolOutcome.js';
-// ─── Recognition + validation ──────────────────────────────────────────
-const ENVELOPE_KEYS = new Set(['content', 'effects', 'status']);
-const EFFECT_KINDS = new Set(['propose-transition', 'require-instruction']);
-function isToolResultStatus(v) {
-    return typeof v === 'string' && TOOL_RESULT_STATUSES.includes(v);
-}
-/**
- * Recognize (or decline to recognize) a tool's return value as an effects
- * envelope. `undefined` = not an envelope: the caller keeps today's path
- * untouched. See the module header for the exact recognition rule and why
- * it is strict.
- */
-export function readToolResultEnvelope(result) {
-    if (typeof result !== 'object' || result === null || Array.isArray(result))
-        return undefined;
-    const record = result;
-    const keys = Object.keys(record);
-    if (!keys.every((k) => ENVELOPE_KEYS.has(k)))
-        return undefined;
-    if (!('content' in record))
-        return undefined;
-    const rawEffects = record.effects;
-    if (!Array.isArray(rawEffects))
-        return undefined;
-    // Every element must speak the reserved vocabulary, or the whole value is
-    // data (a domain object that happens to have an `effects` array must keep
-    // its bytes). An EMPTY effects array is an envelope only when the status
-    // says something — `{ content, effects: [] }` alone declares nothing.
-    const allKnownKinds = rawEffects.every((e) => typeof e === 'object' &&
-        e !== null &&
-        EFFECT_KINDS.has(e.kind));
-    if (!allKnownKinds)
-        return undefined;
-    const status = record.status;
-    if (status !== undefined && !isToolResultStatus(status))
-        return undefined;
-    if (rawEffects.length === 0 && status === undefined)
-        return undefined;
-    const effects = [];
-    const malformed = [];
-    rawEffects.forEach((raw, i) => {
-        const e = raw;
-        const n = i + 1;
-        if (e.kind === 'propose-transition') {
-            if (typeof e.targetSkillId !== 'string' || e.targetSkillId.trim().length === 0) {
-                malformed.push({
-                    kind: 'propose-transition',
-                    refusalReason: `effect ${n} (propose-transition) names no targetSkillId — the proposal was ` +
-                        `refused. A transition proposal is { kind: 'propose-transition', targetSkillId, ` +
-                        `reason }.`,
-                });
-                return;
-            }
-            if (typeof e.reason !== 'string' || e.reason.trim().length === 0) {
-                malformed.push({
-                    kind: 'propose-transition',
-                    refusalReason: `effect ${n} (propose-transition → '${String(e.targetSkillId)}') carries no ` +
-                        `reason — refused. The reason goes on the record; a routing proposal without ` +
-                        `one is the arbitrary authority this channel replaces.`,
-                });
-                return;
-            }
-            effects.push({
-                kind: 'propose-transition',
-                targetSkillId: e.targetSkillId,
-                reason: e.reason,
-            });
-            return;
-        }
-        // require-instruction
-        if (typeof e.instructionId !== 'string' || e.instructionId.trim().length === 0) {
-            malformed.push({
-                kind: 'require-instruction',
-                refusalReason: `effect ${n} (require-instruction) names no instructionId — refused. It is ` +
-                    `{ kind: 'require-instruction', instructionId, deliveryLease: 'next-call' | ` +
-                    `'until-skill-exit' }.`,
-            });
-            return;
-        }
-        if (e.deliveryLease !== 'next-call' && e.deliveryLease !== 'until-skill-exit') {
-            malformed.push({
-                kind: 'require-instruction',
-                refusalReason: `effect ${n} (require-instruction '${String(e.instructionId)}') has deliveryLease ` +
-                    `'${String(e.deliveryLease)}', which is not a lease this library has — refused. ` +
-                    `The two are 'next-call' (exactly the next LLM call) and 'until-skill-exit' ` +
-                    `(every call while the granting tenure holds).`,
-            });
-            return;
-        }
-        effects.push({
-            kind: 'require-instruction',
-            instructionId: e.instructionId,
-            deliveryLease: e.deliveryLease,
-        });
-    });
-    return {
-        content: record.content,
-        effects,
-        ...(status !== undefined && { status: status }),
-        malformed,
-    };
-}
-/**
- * Name the ONE near-miss a tool author is likeliest to write: a status-only
- * envelope with the `effects` marker left off — `{ content, status: 'denied' }`.
- * That shape is NOT an envelope (recognition demands the `effects` array;
- * see `ToolResultEnvelope`), and it stays data byte-for-byte — but a value
- * whose only keys are envelope keys AND whose `status` speaks the closed
- * outcome vocabulary is far more likely a dropped `effects: []` than a
- * coincidence, and letting it route like an undeclared result with no word
- * of why would be accepted-and-silently-wrong. Returns the teaching sentence
- * for the caller's dev-mode warning; `undefined` for every other value.
- * Diagnosis only — never changes what any value does.
- */
-export function explainStatusOnlyNearMiss(result) {
-    if (typeof result !== 'object' || result === null || Array.isArray(result))
-        return undefined;
-    const record = result;
-    const keys = Object.keys(record);
-    if (!keys.every((k) => ENVELOPE_KEYS.has(k)))
-        return undefined;
-    if (!('content' in record) || 'effects' in record)
-        return undefined;
-    if (!isToolResultStatus(record.status))
-        return undefined;
-    return (`the result { content, status: '${record.status}' } looks like a status-only ` +
-        `envelope missing its marker — an envelope REQUIRES the effects array, so this ` +
-        `value was treated as data: the status was not recorded and no onToolStatus edge ` +
-        `can fire on it. Opt in with { content, effects: [], status: '${record.status}' }, ` +
-        `or rename the keys if this is a domain object.`);
-}
-/** Who holds the tenure — the advanced cursor on graph agents, else the tail
- *  of `activatedInjectionIds` (the shipped `activeSkillId` notion the step
- *  pointer's re-key already uses). */
-export function tenantOf(cursor, activatedInjectionIds) {
-    if (cursor !== undefined)
-        return cursor;
-    const activated = activatedInjectionIds ?? [];
-    return activated[activated.length - 1];
-}
-/**
- * The lease-served injection ids for ONE Evaluate pass — pure. `iteration`
- * is the pass being composed; `tenant` is who holds the tenure on it (the
- * ADVANCED cursor — a lease dies the same pass its tenure ends).
- *
- * `skillId === tenant` is a sound "tenure still holds" test ONLY because the
- * Evaluate tenure sweep (`pruneLeases`, every pass) removes a dead lease the
- * pass its tenure ends — so a cursor that re-enters the granting skill later
- * finds nothing to match, instead of resurrecting an ended grant.
- */
-export function activeLeaseIds(leases, iteration, tenant) {
-    if (leases === undefined || leases.length === 0)
-        return [];
-    const ids = [];
-    for (const lease of leases) {
-        const live = lease.deliveryLease === 'next-call'
-            ? lease.iteration + 1 === iteration
-            : lease.skillId === tenant;
-        if (live && !ids.includes(lease.instructionId))
-            ids.push(lease.instructionId);
-    }
-    return ids;
-}
-/**
- * Drop leases that can never serve again. `iteration` is the CURRENT pass;
- * a `'next-call'` lease older than the previous iteration is spent, and an
- * `'until-skill-exit'` lease whose tenant is no longer current is dead.
- *
- * TWO call sites, one law. The Evaluate stage sweeps on EVERY pass (writing
- * the survivors under `nextInstructionLeases`, the cursor's alias round
- * trip) — that sweep is what makes death permanent: it records the death the
- * same pass the tenure ends, before any later pass could see the cursor
- * re-enter the granting skill and mistake re-entry for an unbroken tenure.
- * The tool-calls stage also prunes when it appends a new grant, so a
- * mid-batch array never carries spent leases into the commit.
- */
-export function pruneLeases(leases, iteration, currentTenant) {
-    if (leases === undefined || leases.length === 0)
-        return [];
-    return leases.filter((lease) => lease.deliveryLease === 'next-call'
-        ? lease.iteration + 1 > iteration
-        : lease.skillId === currentTenant);
-}
-//# sourceMappingURL=toolEffects.js.map

package/dist/esm/core/agent/toolEffects.js.map

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

package/dist/esm/core/askComponent.js.map

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

package/dist/esm/core/humanizeLLMError.d.ts

@@ -1,23 +0,0 @@
-/**
- * humanizeLLMError — turn a raw provider/SDK error into a plain-language
- * sentence a NON-developer can act on.
- *
- * agentfootprint targets vibe-coding / non-developer builders. A raw
- * "[browser-anthropic] Failed to fetch" or "401 Unauthorized" means
- * nothing to them. This maps the common failure shapes to a friendly,
- * actionable message. The raw error is preserved on `.cause` (and via
- * `wrapLLMError`) so developers can still dig in.
- *
- * Pure + dependency-light: string/shape matching only. Extend the cases
- * as new provider failure modes surface — keep each message short and
- * tell the user what to DO.
- */
-/** Map a thrown provider/SDK error to a friendly, actionable sentence. */
-export declare function humanizeLLMError(err: unknown): string;
-/**
- * Wrap a raw provider error in a fresh Error whose `.message` is the
- * humanized sentence, preserving the original on `.cause` for developers
- * (and "Copy for LLM"). Re-throw this from the LLM call site so the
- * friendly message flows through onError → onRunFailed → the monitor.
- */
-export declare function wrapLLMError(err: unknown): Error;

package/dist/esm/core/humanizeLLMError.js

@@ -1,65 +0,0 @@
-/**
- * humanizeLLMError — turn a raw provider/SDK error into a plain-language
- * sentence a NON-developer can act on.
- *
- * agentfootprint targets vibe-coding / non-developer builders. A raw
- * "[browser-anthropic] Failed to fetch" or "401 Unauthorized" means
- * nothing to them. This maps the common failure shapes to a friendly,
- * actionable message. The raw error is preserved on `.cause` (and via
- * `wrapLLMError`) so developers can still dig in.
- *
- * Pure + dependency-light: string/shape matching only. Extend the cases
- * as new provider failure modes surface — keep each message short and
- * tell the user what to DO.
- */
-/** Map a thrown provider/SDK error to a friendly, actionable sentence. */
-export function humanizeLLMError(err) {
-    const e = (err ?? {});
-    const raw = (e.message ?? String(err ?? '')).toString();
-    const status = e.status ?? e.statusCode;
-    const lc = raw.toLowerCase();
-    // Network / unreachable — the most common "Failed to fetch" case.
-    // "connection error" is the Stainless SDKs' APIConnectionError message
-    // (@anthropic-ai/sdk, openai v4/v5) — it carries NO status code.
-    if (/failed to fetch|fetch failed|network ?error|connection error|enotfound|eai_again|econnrefused|econnreset|socket hang up|load failed/i.test(raw)) {
-        return "Couldn't reach the AI model. Check your internet connection, and that the provider/API key is set up correctly.";
-    }
-    // Auth — missing/invalid API key (or, for Bedrock, IAM/model access:
-    // AccessDeniedException says "You don't have access to the model..."
-    // with the status only under $metadata, which we never see).
-    if (status === 401 ||
-        status === 403 ||
-        /unauthorized|forbidden|api[ _-]?key|authentication|invalid x-api-key|permission|access denied|don.?t have access/i.test(lc)) {
-        return 'The AI provider rejected the request — the API key looks missing or invalid. Add or fix it in Settings.';
-    }
-    // Rate limit.
-    if (status === 429 || /rate.?limit|too many requests|quota/i.test(lc)) {
-        return 'The AI provider is busy (rate limit / quota). Wait a moment, then try again.';
-    }
-    // Timeout.
-    if (/timeout|timed out|etimedout|deadline/i.test(lc)) {
-        return 'The AI model took too long to respond. Try again — if it keeps happening, simplify the request.';
-    }
-    // Transient server-side (5xx).
-    if (typeof status === 'number' && status >= 500 && status < 600) {
-        return 'The AI provider had a temporary problem on their end. Try again in a moment.';
-    }
-    // Bad request — usually a model name or payload issue.
-    if (status === 400 || /not found|no such model|invalid model|model.*not/i.test(lc)) {
-        return 'The AI request was rejected — the model name or request may be wrong. Check the model in the code.';
-    }
-    // Fallback: keep the raw text but frame it so it doesn't read as a crash.
-    return raw ? `The AI call failed: ${raw}` : 'The AI call failed for an unknown reason.';
-}
-/**
- * Wrap a raw provider error in a fresh Error whose `.message` is the
- * humanized sentence, preserving the original on `.cause` for developers
- * (and "Copy for LLM"). Re-throw this from the LLM call site so the
- * friendly message flows through onError → onRunFailed → the monitor.
- */
-export function wrapLLMError(err) {
-    const friendly = humanizeLLMError(err);
-    // `cause` keeps the raw error for devs; non-devs see only `.message`.
-    return new Error(friendly, err instanceof Error ? { cause: err } : undefined);
-}
-//# sourceMappingURL=humanizeLLMError.js.map

package/dist/esm/core/humanizeLLMError.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"humanizeLLMError.js","sourceRoot":"","sources":["../../../src/core/humanizeLLMError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAUH,0EAA0E;AAC1E,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAAc,CAAC;IACnC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,IAAI,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;IACxD,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,UAAU,CAAC;IACxC,MAAM,EAAE,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IAE7B,kEAAkE;IAClE,uEAAuE;IACvE,iEAAiE;IACjE,IACE,sIAAsI,CAAC,IAAI,CACzI,GAAG,CACJ,EACD,CAAC;QACD,OAAO,iHAAiH,CAAC;IAC3H,CAAC;IAED,qEAAqE;IACrE,qEAAqE;IACrE,6DAA6D;IAC7D,IACE,MAAM,KAAK,GAAG;QACd,MAAM,KAAK,GAAG;QACd,mHAAmH,CAAC,IAAI,CACtH,EAAE,CACH,EACD,CAAC;QACD,OAAO,yGAAyG,CAAC;IACnH,CAAC;IAED,cAAc;IACd,IAAI,MAAM,KAAK,GAAG,IAAI,sCAAsC,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QACtE,OAAO,8EAA8E,CAAC;IACxF,CAAC;IAED,WAAW;IACX,IAAI,uCAAuC,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QACrD,OAAO,iGAAiG,CAAC;IAC3G,CAAC;IAED,+BAA+B;IAC/B,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG,EAAE,CAAC;QAChE,OAAO,8EAA8E,CAAC;IACxF,CAAC;IAED,uDAAuD;IACvD,IAAI,MAAM,KAAK,GAAG,IAAI,mDAAmD,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QACnF,OAAO,oGAAoG,CAAC;IAC9G,CAAC;IAED,0EAA0E;IAC1E,OAAO,GAAG,CAAC,CAAC,CAAC,uBAAuB,GAAG,EAAE,CAAC,CAAC,CAAC,2CAA2C,CAAC;AAC1F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,MAAM,QAAQ,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACvC,sEAAsE;IACtE,OAAO,IAAI,KAAK,CAAC,QAAQ,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AAChF,CAAC"}