ns-kiro-core 0.2.3 → 0.3.1

package/dist/response-stream.js

@@ -2,7 +2,7 @@
 // ABOUTME: Owns framing and the stall timeouts; block assembly lives elsewhere.
 import { UniversalEventStreamMarshaller } from "@smithy/core/event-streams";
 import { debugEnabled, debugLog } from "./debug.js";
-import { parseKiroEvent } from "./event-parser.js";
+import { parseKiroEvent, parseKiroExceptionFrame } from "./event-parser.js";
 /** Longest gap between two frames before the response is treated as stalled. */
 export const IDLE_TIMEOUT = 300_000;
 const eventStreamMarshaller = new UniversalEventStreamMarshaller({
@@ -19,11 +19,18 @@ const eventStreamMarshaller = new UniversalEventStreamMarshaller({
  * A Kiro `error` frame ends the stream and is not yielded — it carries no
  * content, and every caller treats it as the same retryable failure as a
  * protocol error.
+ *
+ * A caller abort throws out of `frames` instead of reporting through
+ * `outcome`: the interrupt is not a retryable stream condition, and surfacing
+ * it as one would burn the retry budget on a cancelled turn. The throw
+ * propagates through the consuming generator to the host adapter, which maps
+ * it to an `aborted` stop reason.
  */
 export function readKiroEventStream(body, options) {
     const outcome = { firstTokenTimedOut: false, idleTimedOut: false, error: null };
     const idleTimeoutMs = options.idleTimeoutMs ?? IDLE_TIMEOUT;
     const bodyReader = body.getReader();
+    const callerSignal = options.signal;
     async function* frames() {
         let idleTimer = null;
         const resetIdle = () => {
@@ -34,6 +41,17 @@ export function readKiroEventStream(body, options) {
                 void bodyReader.cancel().catch(() => { });
             }, idleTimeoutMs);
         };
+        // Cancel the body read as soon as the caller aborts (e.g. user presses
+        // Esc mid-stream). Without this, the read loop below keeps consuming the
+        // event stream until the server finishes the response, which makes an
+        // interrupt appear to hang for the remainder of the generation.
+        const onCallerStreamAbort = () => {
+            void bodyReader.cancel().catch(() => { });
+        };
+        if (callerSignal?.aborted)
+            onCallerStreamAbort();
+        else
+            callerSignal?.addEventListener("abort", onCallerStreamAbort, { once: true });
         // Smithy's marshaller handles chunk reassembly, CRC validation, protocol
         // error/exception detection, and payload deserialization.
         const bodyIterable = {
@@ -57,6 +75,50 @@ export function readKiroEventStream(body, options) {
             if (!entry)
                 throw new Error("Received an empty event stream message");
             const [key, msg] = entry;
+            // The four error members of ChatResponseStream target `@error` shapes,
+            // so the service frames them as `:message-type: exception`. The
+            // marshaller keys those by `:exception-type` and throws whatever this
+            // callback returns, so returning the bare payload would discard the
+            // modeled class. Return an Error carrying the parsed detail instead.
+            if (msg.headers[":message-type"]?.value === "exception") {
+                // Parsed defensively, and BEFORE the shared parse below: an exception
+                // body that is empty or not JSON would otherwise throw a SyntaxError
+                // out of this deserializer, and the caller would report
+                // "Unexpected end of JSON input" with the modeled class gone — the
+                // exact loss this routing removes. The class lives in the header, so
+                // it survives a body we cannot read. The same-service client's own
+                // bridge takes this position too (sse-middleware.ts: "Non-JSON body:
+                // still throw a typed exception with a fallback message").
+                let parsedException = {};
+                try {
+                    const decoded = JSON.parse(utf8Decoder.decode(msg.body));
+                    if (decoded && typeof decoded === "object")
+                        parsedException = decoded;
+                }
+                catch {
+                    // Header-only classification below.
+                }
+                // An unmodeled member (a fifth error added server-side, or `$unknown`)
+                // still arrives keyed by `:exception-type`. Smithy's own fail-open path
+                // is unreachable here — it only triggers when the deserializer returns
+                // a `$unknown` property, which this one never does — so without a
+                // fallback the marshaller would throw the bare parsed body and the
+                // member name would be lost in exactly the way this routing exists to
+                // prevent. Synthesize the same typed shape with `kind: "unknown"`.
+                const data = parseKiroExceptionFrame(key, parsedException) ?? {
+                    error: key,
+                    kind: "unknown",
+                    ...(typeof parsedException.message === "string" ? { message: parsedException.message } : {}),
+                    ...(typeof parsedException.reason === "string" ? { reason: parsedException.reason } : {}),
+                    ...(typeof parsedException.retryAfterMilliseconds === "number"
+                        ? { retryAfterMilliseconds: parsedException.retryAfterMilliseconds }
+                        : {}),
+                };
+                const error = new Error(data.message ? `${data.error}: ${data.message}` : data.error);
+                error.name = data.error;
+                error.kiroError = data;
+                return { [key]: error };
+            }
             const parsed = JSON.parse(utf8Decoder.decode(msg.body));
             return { [key]: parsed };
         });
@@ -65,30 +127,54 @@ export function readKiroEventStream(body, options) {
         const FIRST_TOKEN_SENTINEL = Symbol("firstTokenTimeout");
         try {
             while (true) {
+                if (callerSignal?.aborted) {
+                    // Surface the abort instead of treating the cancelled read as a
+                    // retryable stream error; the adapter maps this to a stopReason of
+                    // "aborted".
+                    throw callerSignal.reason ?? new Error("Request aborted");
+                }
                 let iterResult;
                 try {
                     if (!gotFirstToken) {
                         const readPromise = iterator.next();
-                        const result = await Promise.race([
-                            readPromise,
-                            new Promise((resolve) => setTimeout(() => resolve(FIRST_TOKEN_SENTINEL), options.firstTokenTimeoutMs)),
-                        ]);
-                        if (result === FIRST_TOKEN_SENTINEL) {
-                            readPromise.catch(() => { }); // suppress dangling rejection
-                            void bodyReader.cancel().catch(() => { });
-                            outcome.firstTokenTimedOut = true;
-                            return;
+                        let firstTokenTimer;
+                        try {
+                            const result = await Promise.race([
+                                readPromise,
+                                new Promise((resolve) => {
+                                    firstTokenTimer = setTimeout(() => resolve(FIRST_TOKEN_SENTINEL), options.firstTokenTimeoutMs);
+                                }),
+                            ]);
+                            if (result === FIRST_TOKEN_SENTINEL) {
+                                readPromise.catch(() => { }); // suppress dangling rejection
+                                void bodyReader.cancel().catch(() => { });
+                                outcome.firstTokenTimedOut = true;
+                                return;
+                            }
+                            iterResult = result;
+                            gotFirstToken = true;
+                            resetIdle();
+                        }
+                        finally {
+                            // The losing timeout branch of the race must not keep a ref'd
+                            // timer alive until it fires: an uncleared 90 s handle holds the
+                            // Node event loop open long after a print-mode caller has
+                            // finished its turn (upstream #154).
+                            if (firstTokenTimer !== undefined)
+                                clearTimeout(firstTokenTimer);
                         }
-                        iterResult = result;
-                        gotFirstToken = true;
-                        resetIdle();
                     }
                     else {
                         iterResult = await iterator.next();
                     }
                 }
                 catch (e) {
-                    // Smithy throws on `:message-type` error/exception headers.
+                    // Smithy throws on `:message-type` error/exception headers. A modeled
+                    // exception frame arrives here as the Error built in the
+                    // deserializer above, with its parsed detail attached.
+                    const kiroError = e?.kiroError;
+                    if (kiroError)
+                        outcome.errorData = kiroError;
                     outcome.error =
                         e instanceof Error
                             ? e.message
@@ -99,23 +185,36 @@ export function readKiroEventStream(body, options) {
                 if (done)
                     return;
                 resetIdle();
-                const payload = Object.values(value)[0];
-                const event = parseKiroEvent(payload);
+                // The marshaller keys each frame by its modeled `ChatResponseStream`
+                // union member (from the `:event-type` header). Route on that key
+                // instead of guessing the member from which fields are populated.
+                const frameEntry = Object.entries(value)[0];
+                if (!frameEntry)
+                    continue;
+                const [frameKey, framePayload] = frameEntry;
+                const event = parseKiroEvent(frameKey, (framePayload ?? {}));
                 if (!event)
                     continue;
+                if (event.type === "ignored") {
+                    if (debugEnabled())
+                        debugLog("stream.events.ignored", [event.data.key]);
+                    continue;
+                }
                 if (debugEnabled())
                     debugLog("stream.events", [event]);
                 if (event.type === "error") {
                     outcome.error = event.data.message ? `${event.data.error}: ${event.data.message}` : event.data.error;
+                    outcome.errorData = event.data;
                     void bodyReader.cancel().catch(() => { });
                     return;
                 }
-                yield { event, payload };
+                yield { event, payload: framePayload };
             }
         }
         finally {
             if (idleTimer)
                 clearTimeout(idleTimer);
+            callerSignal?.removeEventListener("abort", onCallerStreamAbort);
         }
     }
     return { frames: frames(), outcome };

package/dist/response-stream.js.map

@@ -1 +1 @@
-{"version":3,"file":"response-stream.js","sourceRoot":"","sources":["../src/response-stream.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,gFAAgF;AAEhF,OAAO,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AAE5E,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAsB,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEvE,gFAAgF;AAChF,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC;AAEpC,MAAM,qBAAqB,GAAG,IAAI,8BAA8B,CAAC;IAC/D,WAAW,EAAE,CAAC,KAAiB,EAAE,EAAE,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC;IACnE,WAAW,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC;CAChE,CAAC,CAAC;AA8BH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAgC,EAChC,OAA+B;IAE/B,MAAM,OAAO,GAA2B,EAAE,kBAAkB,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACxG,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,YAAY,CAAC;IAC5D,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;IAEpC,KAAK,SAAS,CAAC,CAAC,MAAM;QACpB,IAAI,SAAS,GAAyC,IAAI,CAAC;QAC3D,MAAM,SAAS,GAAG,GAAG,EAAE;YACrB,IAAI,SAAS;gBAAE,YAAY,CAAC,SAAS,CAAC,CAAC;YACvC,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC1B,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;gBAC5B,KAAK,UAAU,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAC3C,CAAC,EAAE,aAAa,CAAC,CAAC;QACpB,CAAC,CAAC;QAEF,yEAAyE;QACzE,0DAA0D;QAC1D,MAAM,YAAY,GAA8B;YAC9C,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;gBAC3B,IAAI,CAAC;oBACH,OAAO,IAAI,EAAE,CAAC;wBACZ,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,UAAU,CAAC,IAAI,EAAE,CAAC;wBAChD,IAAI,IAAI;4BAAE,OAAO;wBACjB,MAAM,KAAK,CAAC;oBACd,CAAC;gBACH,CAAC;wBAAS,CAAC;oBACT,UAAU,CAAC,WAAW,EAAE,CAAC;gBAC3B,CAAC;YACH,CAAC;SACF,CAAC;QACF,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;QACtC,MAAM,WAAW,GAAG,qBAAqB,CAAC,WAAW,CAAC,YAAY,EAAE,KAAK,EAAE,KAA8B,EAAE,EAAE;YAC3G,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACvC,IAAI,CAAC,KAAK;gBAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;YACtE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC;YACzB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAA4B,CAAC;YACnF,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,MAAM,EAA6B,CAAC;QACtD,CAAC,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,aAAa,CAAC,EAA4C,CAAC;QAE/F,IAAI,aAAa,GAAG,KAAK,CAAC;QAC1B,MAAM,oBAAoB,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;QAEzD,IAAI,CAAC;YACH,OAAO,IAAI,EAAE,CAAC;gBACZ,IAAI,UAAmD,CAAC;gBACxD,IAAI,CAAC;oBACH,IAAI,CAAC,aAAa,EAAE,CAAC;wBACnB,MAAM,WAAW,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;wBACpC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;4BAChC,WAAW;4BACX,IAAI,OAAO,CAA8B,CAAC,OAAO,EAAE,EAAE,CACnD,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAC7E;yBACF,CAAC,CAAC;wBACH,IAAI,MAAM,KAAK,oBAAoB,EAAE,CAAC;4BACpC,WAAW,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,8BAA8B;4BAC3D,KAAK,UAAU,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;4BACzC,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;4BAClC,OAAO;wBACT,CAAC;wBACD,UAAU,GAAG,MAAiD,CAAC;wBAC/D,aAAa,GAAG,IAAI,CAAC;wBACrB,SAAS,EAAE,CAAC;oBACd,CAAC;yBAAM,CAAC;wBACN,UAAU,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;oBACrC,CAAC;gBACH,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,4DAA4D;oBAC5D,OAAO,CAAC,KAAK;wBACX,CAAC,YAAY,KAAK;4BAChB,CAAC,CAAC,CAAC,CAAC,OAAO;4BACX,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,sBAAsB,CAAC;oBACtG,OAAO;gBACT,CAAC;gBAED,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,UAAU,CAAC;gBACnC,IAAI,IAAI;oBAAE,OAAO;gBACjB,SAAS,EAAE,CAAC;gBACZ,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,KAAgC,CAAC,CAAC,CAAC,CAA4B,CAAC;gBAC9F,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;gBACtC,IAAI,CAAC,KAAK;oBAAE,SAAS;gBACrB,IAAI,YAAY,EAAE;oBAAE,QAAQ,CAAC,eAAe,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;gBACvD,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;oBAC3B,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;oBACrG,KAAK,UAAU,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;oBACzC,OAAO;gBACT,CAAC;gBACD,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;YAC3B,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,IAAI,SAAS;gBAAE,YAAY,CAAC,SAAS,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC;AACvC,CAAC"}
+{"version":3,"file":"response-stream.js","sourceRoot":"","sources":["../src/response-stream.ts"],"names":[],"mappings":"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"}

package/dist/stream.d.ts

@@ -1,5 +1,6 @@
 import { type KiroModel } from "./models.js";
 import type { KiroEffort, KiroMessage, KiroStreamEvent, KiroTool } from "./types.js";
+import { type KiroUsageTracking } from "./usage-tracking.js";
 /** One model call, fully assembled by the host adapter. */
 export interface KiroStreamRequest {
     model: KiroModel;
@@ -21,6 +22,12 @@ export interface KiroStreamRequest {
      * behaviour instead of retrying mid-response.
      */
     canDiscardEmittedBlocks?: boolean;
+    /**
+     * Opt-in usage estimates (credit→USD value, cache-read estimation). Absent
+     * means disabled; the core never reads a settings file on its own — the host
+     * resolves the policy and passes it here.
+     */
+    usageTracking?: KiroUsageTracking;
 }
 /** Reset profile resolution state — exported for stream tests. */
 export declare function resetProfileArnCache(resolved?: boolean): void;

package/dist/stream.js

@@ -1,8 +1,11 @@
 // ABOUTME: Core streaming integration for Kiro API requests and responses.
 // ABOUTME: Handles request building, retry logic, event parsing, and token counting.
-import { debugLog, formatSafeError, redactSensitiveText } from "./debug.js";
+import { createHash } from "node:crypto";
+import { applyCacheEstimate } from "./cache-estimator.js";
+import { debugEnabled, debugLog, formatSafeError, redactSensitiveText } from "./debug.js";
 import { buildKiroAdditionalModelRequestFields, clampKiroEffort, getKiroEffortConfig } from "./effort.js";
-import { getKiroEndpoints } from "./endpoints.js";
+import { getKiroEndpoints, getKiroRegionFromProfileArn } from "./endpoints.js";
+import { extractKiroReasonCode, KiroApiError, parseRetryAfterMs } from "./errors.js";
 import { getKiroCliCredentials, getKiroCliCredentialsAllowExpired, refreshViaKiroCli } from "./kiro-cli.js";
 import { invalidateKiroProfileArn, KiroManagementHttpError, resetKiroProfileArnCache, resolveKiroProfileArn, } from "./management.js";
 import { isCacheStale, resolveKiroModel, updateKiroModelsCache } from "./models.js";
@@ -13,6 +16,116 @@ import { readKiroEventStream } from "./response-stream.js";
 import { capacityRetryConfig, exponentialBackoff, extractKiroReason, firstTokenTimeoutForModel, isCapacityError, isNonRetryableBodyError, isTooBigError, KIRO_REASON_CODES, MAX_RETRY_DELAY, resolveRequestRateRetryDelay, retryConfig, } from "./retry.js";
 import { kiroTokenTypeHeaders } from "./token-type.js";
 import { abortableDelay, createResponseHeaderDeadline, logCapacityEvent } from "./transport.js";
+import { estimateKiroCreditCost, KIRO_USAGE_TRACKING_DISABLED } from "./usage-tracking.js";
+/**
+ * Pluralise an observed-attempt count for a diagnostic. The count is what was
+ * actually seen, not the configured retry budget: the two diverge whenever a
+ * 403 refresh, a timeout or a mid-stream error already spent part of the shared
+ * budget, and a diagnostic that exists to explain a silent failure must not
+ * itself assert something that did not happen.
+ *
+ * Deliberately not worded as "consecutive": the degenerate attempts need not be
+ * adjacent. A 403 credential refresh or a mid-stream error can land between two
+ * of them and spend the same shared budget, so an unqualified count is the only
+ * claim the counter can actually support.
+ */
+function describeAttempts(count) {
+    return count === 1 ? "1 attempt" : `${count} attempts`;
+}
+/**
+ * Cap for wire-derived echo text quoted into a persisted `errorMessage`. The
+ * echo pattern `/^\s*(continue|\.+)\s*$/i` admits an arbitrarily long run of
+ * dots, and this string is written into the stream's terminal diagnostic.
+ * Matches the 200-char cap used for raw tool input in the assembler's parse
+ * warning. Tool-name collections use their own whole-value policy in
+ * `describeDroppedToolNames`; they are never sliced into partial identities.
+ */
+const DIAGNOSTIC_QUOTE_LIMIT = 200;
+/**
+ * INVARIANT: no unbounded integer may be interpolated into a persisted
+ * `errorMessage`. Consumers classify that string by pattern-matching its text,
+ * and retryable-error predicates in the wild match bare `429|500|502|503|504`
+ * with NO word boundary. So a `(5000 chars total)` annotation makes a
+ * diagnostic that says "terminal, do not retry" read as a transient HTTP 500
+ * and get suppressed — precisely the silent failure these diagnostics exist to
+ * defeat, reintroduced by the diagnostic itself.
+ *
+ * Hence the truncation marker carries no length: the exact length goes to
+ * `console.warn`, which no classifier reads. The only integer these diagnostics
+ * interpolate is the observed-attempt count, bounded by `maxRetries + 1` = 4.
+ *
+ * Wire-derived tool names can carry the same trigger text, so they are encoded
+ * before entering this diagnostic. See `encodeToolNameForDiagnostic`.
+ */
+function clampForDiagnostic(text) {
+    return text.length <= DIAGNOSTIC_QUOTE_LIMIT ? text : `${text.slice(0, DIAGNOSTIC_QUOTE_LIMIT)}… (truncated)`;
+}
+/**
+ * Encode untrusted bytes without letting their text change how a consumer
+ * classifies the surrounding error. Each byte is represented by two letters,
+ * A through P, for its high and low nibbles. That alphabet contains no digits
+ * and cannot spell any alternative in a retryable-error predicate.
+ */
+function encodeBytesForDiagnostic(bytes) {
+    let encoded = "";
+    for (const byte of bytes) {
+        encoded += String.fromCharCode(65 + (byte >> 4), 65 + (byte & 0x0f));
+    }
+    return encoded;
+}
+/**
+ * Encode one tool-name identity reversibly from its UTF-16 code units. String
+ * names retain their exact value. A malformed non-string wire name is prefixed
+ * with its runtime type and JSON representation, so it stays distinguishable
+ * from a legitimate string with the same rendered text.
+ *
+ * Using `TextEncoder` here would replace an unpaired surrogate with U+FFFD,
+ * corrupting the only persisted identity of a dropped call; JSON permits that
+ * escaped shape and the event parser carries it through as a JavaScript string.
+ * Quoting any identity verbatim is unsafe: values such as `set_timeout` and
+ * `http500_probe` make a terminal diagnostic look transient to consumers.
+ */
+function encodeToolNameForDiagnostic(name) {
+    const identity = typeof name === "string" ? name : `${typeof name}:${JSON.stringify(name)}`;
+    let encoded = "";
+    for (let i = 0; i < identity.length; i++) {
+        const codeUnit = identity.charCodeAt(i);
+        encoded += String.fromCharCode(65 + (codeUnit >> 12), 65 + ((codeUnit >> 8) & 0x0f), 65 + ((codeUnit >> 4) & 0x0f), 65 + (codeUnit & 0x0f));
+    }
+    return encoded;
+}
+/**
+ * Describe the complete dropped-name set without unbounded output or partial
+ * identities. A set that fits is reversible name by name. If the complete set
+ * would exceed the diagnostic limit, replace all names with one SHA-256
+ * fingerprint. The explicit marker means no valid-looking name prefix can be
+ * mistaken for the whole identity, while the fingerprint still lets two
+ * records be compared exactly.
+ */
+function describeDroppedToolNames(names) {
+    const encoded = names.map((name) => `A-P:${encodeToolNameForDiagnostic(name)}`).join(", ");
+    if (encoded.length <= DIAGNOSTIC_QUOTE_LIMIT)
+        return encoded;
+    const digest = createHash("sha256").update(JSON.stringify(names)).digest();
+    return `A-P-DIGEST:${encodeBytesForDiagnostic(digest)} (tool identities fingerprinted)`;
+}
+/**
+ * What the turn's blocks look like, for the exhausted-empty-response
+ * diagnostic. "No text and no tool calls" does NOT imply empty content: a
+ * reasoning turn that emits only `thinkingText` and then ends is degenerate by
+ * that test while a thinking block still exists, and a `ThinkingTagParser`
+ * turn can leave a zero-length text block behind. Claiming `empty content`
+ * there would assert something not observed.
+ *
+ * Block TYPES only, never a count: a count is an unbounded integer, which the
+ * invariant above forbids.
+ */
+function describeReturnedContent(kinds) {
+    const unique = [...new Set(kinds)].sort();
+    if (unique.length === 0)
+        return "returning empty content";
+    return `returning only ${unique.join(" and ")} content`;
+}
 let skipProfileResolutionForTests = false;
 const TEST_PROFILE_ARN = "arn:aws:codewhisperer:us-east-1:000000000000:profile/test";
 /** Reset profile resolution state — exported for stream tests. */
@@ -37,7 +150,6 @@ export async function* streamKiro(request) {
     }
     let accessToken = initialAccessToken;
     const region = model.region ?? "us-east-1";
-    const endpoint = new URL("generateAssistantResponse", getKiroEndpoints(region).runtime).toString();
     let managementAuth = { accessToken, region };
     const cliCreds = getKiroCliCredentials() ?? getKiroCliCredentialsAllowExpired();
     const cliProfileArn = cliCreds?.access === accessToken ? cliCreds.profileArn : undefined;
@@ -65,10 +177,17 @@ export async function* streamKiro(request) {
             freshCreds.profileArn ||
                 (skipProfileResolutionForTests ? TEST_PROFILE_ARN : await resolveKiroProfileArn(managementAuth));
     }
+    // ListAvailableProfiles probes across regions (#104, #131), so an SSO login
+    // in one region can legitimately resolve a profile owned by another. The
+    // runtime host and the catalog have to follow the profile: sending a
+    // cross-region profile ARN to the runtime API fails the whole request with
+    // a generic `Improperly formed request.`.
+    let runtimeRegion = getKiroRegionFromProfileArn(profileArn) ?? region;
+    let endpoint = new URL("generateAssistantResponse", getKiroEndpoints(runtimeRegion).runtime).toString();
     // Refresh the catalog in the background when it has gone stale.
-    if (!process.env.VITEST && isCacheStale(region)) {
-        updateKiroModelsCache(accessToken, region, profileArn).catch((error) => {
-            console.warn(`[kiro-core] Failed to refresh Kiro model catalog in ${region}: ${formatSafeError(error)}`);
+    if (!process.env.VITEST && isCacheStale(runtimeRegion)) {
+        updateKiroModelsCache(accessToken, runtimeRegion, profileArn).catch((error) => {
+            console.warn(`[kiro-core] Failed to refresh Kiro model catalog in ${runtimeRegion}: ${formatSafeError(error)}`);
         });
     }
     const kiroModelId = resolveKiroModel(model.id, model.kiroModelId);
@@ -117,8 +236,30 @@ export async function* streamKiro(request) {
         systemPrompt = `<thinking_mode>enabled</thinking_mode><max_thinking_length>${budget}</max_thinking_length>${systemPrompt ? `\n${systemPrompt}` : ""}`;
     }
     const assembler = new KiroResponseAssembler(model, thinkingEnabled);
+    const usageTracking = request.usageTracking ?? KIRO_USAGE_TRACKING_DISABLED;
     let retryCount = 0;
     const maxRetries = 3;
+    /** Degenerate attempts, counted BY SHAPE. Both are counted separately from
+     *  `retryCount`, which is the shared retry budget also spent by 403 credential
+     *  refreshes, idle/first-token timeouts and mid-stream errors — so
+     *  `maxRetries + 1` is NOT the number of empty attempts, and reporting it as
+     *  such overstates what was observed.
+     *
+     *  Split rather than pooled because the two shapes are not interchangeable and
+     *  the exhaustion diagnostic is worded from the LAST attempt's shape only. The
+     *  model can echo on one attempt and return nothing on the next; a single
+     *  pooled counter would then make "returned no text ... on 4 attempts" out of
+     *  three empty attempts and one that did carry text, or claim four echoes from
+     *  one. Each diagnostic reports its own shape's count and, when the other shape
+     *  also occurred, names it separately. */
+    let emptyAttempts = 0;
+    let echoAttempts = 0;
+    // Cumulative provider-internal retry tallies reported on KiroApiError.
+    // `retryCount` cannot stand in for either: it is also consumed by stream
+    // errors, idle/first-token timeouts, and empty-response retries, and
+    // `capacityRetryCount` resets on every outer iteration.
+    let credentialRefreshTotal = 0;
+    let capacityRetryTotal = 0;
     const conversationId = request.sessionId ?? crypto.randomUUID();
     requestLoop: while (retryCount <= maxRetries) {
         if (signal?.aborted)
@@ -210,6 +351,7 @@ export async function* streamKiro(request) {
                 // Retry transient capacity errors with longer backoff.
                 if (isCapacityError(errText) && capacityRetryCount < capacityRetryConfig.maxRetries) {
                     capacityRetryCount++;
+                    capacityRetryTotal++;
                     const delayMs = exponentialBackoff(capacityRetryCount - 1, capacityRetryConfig.baseDelayMs, 30_000);
                     logCapacityEvent(`INSUFFICIENT_MODEL_CAPACITY — retrying in ${delayMs}ms (${capacityRetryCount}/${capacityRetryConfig.maxRetries})`);
                     await abortableDelay(delayMs, signal);
@@ -237,6 +379,7 @@ export async function* streamKiro(request) {
                 }
                 if (response.status === 403 && !isCapacityError(errText) && retryCount < maxRetries) {
                     retryCount++;
+                    credentialRefreshTotal++;
                     // Re-read the shared store first in case another process already
                     // rotated the token. If it still contains the rejected token, force
                     // kiro-cli to refresh before retrying runtime.
@@ -263,19 +406,35 @@ export async function* streamKiro(request) {
                         freshCreds?.profileArn ||
                             inheritedDesktopProfileArn ||
                             (skipProfileResolutionForTests ? TEST_PROFILE_ARN : await resolveKiroProfileArn(managementAuth));
+                    // A replacement credential can carry a profile in another region,
+                    // so re-pin the runtime host before retrying.
+                    runtimeRegion = getKiroRegionFromProfileArn(profileArn) ?? region;
+                    endpoint = new URL("generateAssistantResponse", getKiroEndpoints(runtimeRegion).runtime).toString();
                     await abortableDelay(exponentialBackoff(retryCount - 1, 500, MAX_RETRY_DELAY), signal);
                     break; // break inner loop, continue outer loop
                 }
                 // Known quota/capacity body markers must not be re-read by a host's own
-                // outer auto-retry as a generic retryable 429.
+                // outer auto-retry as a generic retryable 429. This covers both hard
+                // quota (MONTHLY_REQUEST_COUNT) and exhausted capacity retries
+                // (INSUFFICIENT_MODEL_CAPACITY).
+                //
+                // The three throws below carry identical `message` text to what this
+                // provider has always emitted — host adapters and downstream consumers
+                // string-match it. KiroApiError adds the classification as typed fields
+                // alongside that text; it never changes it.
+                const errorMeta = {
+                    reasonCode: extractKiroReasonCode(errText),
+                    retryAfterMs: parseRetryAfterMs(response.headers),
+                    providerAttempts: { credentialRefresh: credentialRefreshTotal, capacity: capacityRetryTotal },
+                };
                 if (isNonRetryableBodyError(errText) || isCapacityError(errText)) {
-                    throw new Error(`Kiro API error: ${errText || safeStatusText}`);
+                    throw new KiroApiError(`Kiro API error: ${errText || safeStatusText}`, response.status, errorMeta.reasonCode, errorMeta.retryAfterMs, errorMeta.providerAttempts);
                 }
                 // Phrase overflow so a host's context-overflow detector recognizes it.
                 if (isTooBigError(response.status, errText)) {
-                    throw new Error(`Kiro API error: context_length_exceeded (${response.status} ${errText})`);
+                    throw new KiroApiError(`Kiro API error: context_length_exceeded (${response.status} ${errText})`, response.status, errorMeta.reasonCode, errorMeta.retryAfterMs, errorMeta.providerAttempts);
                 }
-                throw new Error(`Kiro API error: ${response.status} ${safeStatusText} ${errText}`);
+                throw new KiroApiError(`Kiro API error: ${response.status} ${safeStatusText} ${errText}`, response.status, errorMeta.reasonCode, errorMeta.retryAfterMs, errorMeta.providerAttempts);
             }
             break; // success, break inner loop
         }
@@ -291,6 +450,7 @@ export async function* streamKiro(request) {
         assembler.beginAttempt();
         const { frames, outcome } = readKiroEventStream(response.body, {
             firstTokenTimeoutMs: model.firstTokenTimeout ?? firstTokenTimeoutForModel(model.id),
+            signal,
         });
         for await (const frame of frames) {
             assembler.handle(frame);
@@ -301,6 +461,23 @@ export async function* streamKiro(request) {
             // Timed out or received an error mid-stream: retry with backoff.
             if (retryCount < maxRetries) {
                 retryCount++;
+                if (outcome.errorData && debugEnabled()) {
+                    debugLog("stream.error.typed", [outcome.errorData]);
+                }
+                // The assembler outlives the retry loop, so anything the aborted
+                // attempt already emitted survives into the next one. A typed error
+                // frame (throttling/validation/serviceUnavailable) can arrive after
+                // partial text, which would otherwise concatenate the abandoned prefix
+                // onto the retried response. The degenerate-response retry below
+                // discards for the same reason. The usage figures are cleared by
+                // `beginAttempt` at the next loop top.
+                //
+                // The event protocol has no retraction event, so deltas already pushed
+                // for the abandoned attempt cannot be withdrawn. The signals a
+                // consumer does get are the `reset` event and the fresh `start`
+                // emitted for the retried attempt.
+                assembler.discard();
+                yield* assembler.takeEvents();
                 await abortableDelay(exponentialBackoff(retryCount - 1, 1000, MAX_RETRY_DELAY), signal);
                 continue;
             }
@@ -320,7 +497,13 @@ export async function* streamKiro(request) {
         // When tool calls *were* present but all got dropped (empty/unparseable
         // input), don't retry — the API did respond, it just sent malformed tool
         // calls. Retrying would likely produce the same result.
-        if (summary.isEmpty || summary.isEchoLoop) {
+        const degenerate = summary.isEmpty || summary.isEchoLoop;
+        if (summary.isEchoLoop)
+            echoAttempts++;
+        else if (degenerate)
+            emptyAttempts++;
+        let errorMessage;
+        if (degenerate) {
             // Retrying an echo loop means unsaying text already delivered, which only
             // a host that can discard emitted blocks may do. Elsewhere, go straight to
             // the terminal behaviour: strip the echo so the agent loop does not read
@@ -334,22 +517,69 @@ export async function* streamKiro(request) {
                 await abortableDelay(exponentialBackoff(retryCount - 1, 1000, MAX_RETRY_DELAY), signal);
                 continue;
             }
+            // Retries are spent (or the host cannot discard an echo) and the turn
+            // still carries nothing usable. The stopReason stays in the existing
+            // union — a new member would break every consumer — so the only channel
+            // that can say a turn failed while it still looks successful is the
+            // `errorMessage` carried on the terminal `done` event. Without it these
+            // turns are indistinguishable from an ordinary completion.
+            //
+            // Deliberately NOT worded as a transient/transport failure: this is
+            // terminal, so consumer retry classifiers must not match it and hand it
+            // another doomed attempt.
             if (summary.isEchoLoop) {
+                // Strip the echo text to prevent the agent loop from interpreting
+                // "Continue" as a continuation signal.
                 assembler.stripEcho();
-                console.warn(`[kiro-core] Echo loop — stripping "Continue" response`);
+                const alsoEmpty = emptyAttempts > 0 ? ` (plus ${describeAttempts(emptyAttempts)} with no text at all)` : "";
+                console.warn(`[kiro-core] Echo loop persisted across ${describeAttempts(echoAttempts)}${alsoEmpty} — stripping "Continue" response (${summary.responseText.length} chars)`);
+                errorMessage = `Kiro model echoed its own continuation prompt (${JSON.stringify(clampForDiagnostic(summary.responseText))}) on ${describeAttempts(echoAttempts)}${alsoEmpty} and emitted no tool calls; retry budget exhausted, text stripped, stopReason:"${summary.stopReason}"`;
             }
             else {
-                // The stop reason is still decided below, and an empty turn that never
-                // carried a contextUsage frame is reported as `length` rather than
-                // `stop` — say so, instead of promising a normal stop this branch does
-                // not actually guarantee.
-                console.warn(`[kiro-core] Empty response after ${maxRetries} retries — giving up on this turn`);
+                const alsoEchoed = echoAttempts > 0 ? ` (plus ${describeAttempts(echoAttempts)} that echoed the continuation prompt)` : "";
+                console.warn(`[kiro-core] Empty response on ${describeAttempts(emptyAttempts)}${alsoEchoed}, retry budget exhausted — returning stopReason:"${summary.stopReason}" to avoid agent loop stall`);
+                errorMessage = `Kiro returned no text and no tool calls on ${describeAttempts(emptyAttempts)}${alsoEchoed}; retry budget exhausted, ${describeReturnedContent(assembler.contentKinds())} with stopReason:"${summary.stopReason}"`;
             }
         }
-        const { stopReason, usage } = assembler.complete();
+        // A tool call the model DID make never reached the host: its arguments
+        // would not parse, so the assembler dropped it. Nothing else records this
+        // — `sawAnyToolCalls` is already true, which is exactly what suppresses the
+        // empty-response retry above and the text-dialect fallback — and the block
+        // stream simply lacks the call. Unlike the two exhaustion cases, this one
+        // is unrecoverable downstream: the call is gone before the events are
+        // persisted.
+        if (summary.droppedToolCalls.length > 0) {
+            const names = describeDroppedToolNames(summary.droppedToolCalls);
+            // The reversible names or whole-set fingerprint identify the drops, so
+            // the count is not printed: it is unbounded (a turn may carry any
+            // number of malformed calls) and unbounded or wire-controlled text
+            // here can collide with a consumer's retryable-error pattern.
+            const one = summary.droppedToolCalls.length === 1;
+            const dropDiagnostic = `Kiro sent ${one ? "a tool call" : "tool calls"} with unparseable arguments (${names}); ${one ? "it was" : "they were"} dropped and never reached the agent, stopReason:"${summary.stopReason}"`;
+            // Concatenation is defensive: today the two diagnostics are mutually
+            // exclusive, because any drop sets `sawAnyToolCalls` and `degenerate`
+            // requires `!sawAnyToolCalls`. Kept so that loosening either predicate
+            // appends rather than silently overwriting an exhaustion diagnostic.
+            errorMessage = errorMessage ? `${errorMessage}. ${dropDiagnostic}` : dropDiagnostic;
+        }
+        const { stopReason, usage, wireUsage, metering } = assembler.complete();
         yield* assembler.takeEvents();
+        if (!errorMessage) {
+            const estimatedRead = applyCacheEstimate(conversationId, usage, wireUsage, usageTracking);
+            if (estimatedRead > 0) {
+                debugLog("usage.estimate", {
+                    conversationId,
+                    estimatedRead,
+                    input: usage.input,
+                    cacheRead: usage.cacheRead,
+                });
+            }
+            const estimatedCost = estimateKiroCreditCost(usageTracking, metering);
+            if (estimatedCost !== undefined)
+                usage.cost.total = estimatedCost;
+        }
         yield { type: "usage", usage };
-        yield { type: "done", stopReason };
+        yield { type: "done", stopReason, ...(errorMessage ? { errorMessage } : {}) };
         return;
     }
 }