@sensigo/realm-cli 0.38.0 → 0.40.0

package/dist/agent/drive-failure.d.ts

@@ -0,0 +1,62 @@
+import { type DriveFailureRecord, type RunStore } from '@sensigo/realm';
+/**
+ * Messages are capped so one enormous provider error cannot dominate a run record. Exported so
+ * run-agent's own validation mint uses THIS number rather than a second literal that could drift.
+ */
+export declare const MESSAGE_CAP = 500;
+/**
+ * What a provider attaches to an error it throws, when it knows more than the error itself says.
+ * A plain property on the SAME object, which is what survives every wrap point in the providers.
+ */
+export interface DriveCallPayload {
+    error_class?: DriveFailureRecord['error_class'];
+    attempts_sdk?: number;
+    elapsed_ms?: number;
+    last_observed_status?: number;
+    retry_after_observed_ms?: number;
+    declared_per_attempt_ms?: number;
+    derived_ceiling_ms?: number;
+}
+/**
+ * Walks the cause chain looking for an attached payload, PAYLOAD-FIRST and depth-bounded.
+ *
+ * The walk is the point: a provider's retry ladder wraps the original error in another one, so the
+ * payload that knows what actually happened is a `cause` or two down. Reading only the outermost
+ * error would classify every wrapped failure as `other`.
+ */
+export declare function findDriveCall(err: unknown): DriveCallPayload | undefined;
+export declare function classifyDriveError(err: unknown): DriveCallPayload & {
+    error_class: DriveFailureRecord['error_class'];
+};
+/**
+ * Builds the record for one failed attempt.
+ *
+ * TOTAL BY CONSTRUCTION, and this is not defensive habit — it closes a real hole. `buildEntry`
+ * runs OUTSIDE the fence's try at every chokepoint, and every step of it touches the thrown value:
+ * `classifyDriveError` reads `err.name` (a throwing getter throws here), `findDriveCall` does
+ * `'driveCall' in e` (a proxy with a `has` trap throws), and `sanitizeError` calls `String(err)`
+ * (a poisoned `toString` throws). A hostile thrown object would therefore make the MINT throw
+ * from inside a catch — replacing the operator's actual error with a secondary one, and at
+ * chokepoints (1)/(2) escalating it to (3), which would then re-mint against the WRONG error.
+ *
+ * So: the mint must never out-throw the failure it records. When the value cannot be rendered,
+ * the degraded entry below carries all six required fields and says plainly that it could not.
+ */
+export declare function buildEntry(err: unknown, step: string, provider: string, attemptStartedAt: number): DriveFailureRecord;
+/** The one loud line printed when a failure could not be recorded — never replaces the original. */
+export declare function lostLine(runId: string, entry: DriveFailureRecord): string;
+/**
+ * THE FENCE. Appends one entry to the run's drive-failure ring, and never lets its own failure
+ * become the operator's problem.
+ *
+ * Everything here is subordinate to one rule: this must never replace, hide, or crash on top of
+ * the operator's actual error. So a terminal run is a silent skip (the seal is already the
+ * visibility), a vanished run is a silent skip (disposal is the visibility), contention is
+ * retried, and anything else prints ONE line naming exactly what was lost.
+ *
+ * That line lands BESIDE the original, not always after it: chokepoints (1), (2) and (4) print
+ * their error first, so the lost line follows — but chokepoint (3) mints BEFORE its re-throw
+ * reaches the CLI's printer, so there the lost line comes first. Either way the operator has both.
+ */
+export declare function recordDriveFailure(store: Pick<RunStore, 'get' | 'update'>, runId: string, entry: DriveFailureRecord): Promise<void>;
+//# sourceMappingURL=drive-failure.d.ts.map

package/dist/agent/drive-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drive-failure.d.ts","sourceRoot":"","sources":["../../src/agent/drive-failure.ts"],"names":[],"mappings":"AAaA,OAAO,EAEL,KAAK,kBAAkB,EAEvB,KAAK,QAAQ,EACd,MAAM,gBAAgB,CAAC;AAKxB;;;GAGG;AACH,eAAO,MAAM,WAAW,MAAM,CAAC;AAM/B;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,kBAAkB,CAAC,aAAa,CAAC,CAAC;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CASxE;AAoDD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,GAAG;IACnE,WAAW,EAAE,kBAAkB,CAAC,aAAa,CAAC,CAAC;CAChD,CA4BA;AAqBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,MAAM,GACvB,kBAAkB,CAapB;AAuBD,oGAAoG;AACpG,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAEzE;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,GAAG,QAAQ,CAAC,EACvC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,IAAI,CAAC,CAmCf"}

package/dist/agent/drive-failure.js

@@ -0,0 +1,241 @@
+// drive-failure.ts — recording a failed drive attempt on the run (issue #401).
+//
+// THE PROBLEM. Any failure while `realm agent` drives a step — a connection error, a timeout, an
+// MCP discovery failure, a missing SDK, an engine throw mid-loop, a schema-rejection wedge — used
+// to write NOTHING to the store. The console said what happened and the process exited; the run
+// read healthy on every operator surface until `never_claimed_idle` noticed 24 hours later.
+//
+// THE INVARIANT this module serves: a failed drive attempt on an EXISTING run, whose process
+// survives to a catch inside `runAgent`, is visible on every operator surface within one minute.
+//
+// The write itself is what makes that true twice over: it records the failure AND, because
+// `update()` bumps `version`/`updated_at`, it resets the idle clock — so the run stops looking
+// untouched at exactly the moment it stopped being driven.
+import { WorkflowError, } from '@sensigo/realm';
+import { sanitizeError, extractHttpStatus } from './providers/agent-utils.js';
+/** At most this many entries are retained, most-recent-last. */
+const RING_CAP = 5;
+/**
+ * Messages are capped so one enormous provider error cannot dominate a run record. Exported so
+ * run-agent's own validation mint uses THIS number rather than a second literal that could drift.
+ */
+export const MESSAGE_CAP = 500;
+/** How deep the cause chain is walked looking for a payload. */
+const CAUSE_DEPTH = 8;
+/** How many times the fence re-reads and re-applies before giving up loudly. */
+const WRITE_ATTEMPTS = 3;
+/**
+ * Walks the cause chain looking for an attached payload, PAYLOAD-FIRST and depth-bounded.
+ *
+ * The walk is the point: a provider's retry ladder wraps the original error in another one, so the
+ * payload that knows what actually happened is a `cause` or two down. Reading only the outermost
+ * error would classify every wrapped failure as `other`.
+ */
+export function findDriveCall(err) {
+    let e = err;
+    for (let depth = 0; e != null && depth < CAUSE_DEPTH; depth++) {
+        if (typeof e === 'object' && 'driveCall' in e) {
+            return e.driveCall;
+        }
+        e = e.cause;
+    }
+    return undefined;
+}
+/**
+ * Classifies a thrown error, in strict precedence order.
+ *
+ * 1. an attached payload — the producer knew more than the error's shape says, so it wins;
+ * 2. the SDK's own error names — `APIConnectionTimeoutError` is a timeout even if a status is also
+ *    somehow present, which is why the name is checked before the status;
+ * 3. an HTTP status, which also carries the status VALUE forward as a discriminator;
+ * 4. `other`.
+ */
+const ERROR_CLASSES = new Set([
+    'connection_timeout',
+    'connection_error',
+    'api_status',
+    'sdk_missing',
+    'validation_rejected',
+    'aborted_by_budget',
+    'other',
+]);
+const NUMERIC_PAYLOAD_FIELDS = [
+    'attempts_sdk',
+    'elapsed_ms',
+    'last_observed_status',
+    'retry_after_observed_ms',
+    'declared_per_attempt_ms',
+    'derived_ceiling_ms',
+];
+/**
+ * Picks the known fields out of an attached payload, key-filtered and typeof-checked.
+ *
+ * The payload is an UNTYPED boundary into a record realm persists, so a raw spread would let any
+ * key a provider happened to attach land in the store forever. Filtering is per FIELD, not
+ * whole-payload: the numbers are measurements and are kept when they are numbers, while the class
+ * is a CLAIM — an out-of-union value is dropped and shape classification decides instead.
+ */
+function pickPayload(payload) {
+    const out = {};
+    for (const field of NUMERIC_PAYLOAD_FIELDS) {
+        const value = payload[field];
+        if (typeof value === 'number' && Number.isFinite(value))
+            out[field] = value;
+    }
+    const cls = payload['error_class'];
+    if (typeof cls === 'string' && ERROR_CLASSES.has(cls))
+        out['error_class'] = cls;
+    return out;
+}
+export function classifyDriveError(err) {
+    const payload = findDriveCall(err);
+    if (payload !== undefined) {
+        const picked = pickPayload(payload);
+        // A payload whose class did not survive the pick falls through to shape classification —
+        // the measurements it carried are still kept.
+        return { error_class: picked.error_class ?? shapeClassify(err), ...picked };
+    }
+    // `constructor.name`, not just `.name`: neither installed SDK sets `.name` on its error
+    // classes, so a real connection failure or request timeout reports `name === 'Error'` and was
+    // recorded as `other` — the two classes an operator most needs told apart from a hang, silently
+    // collapsed. `.name` is kept for wrappers that re-throw with a copied name. Deliberately NOT
+    // wrapped in try/catch: `buildEntry`'s own catch is this path's totality, and a hostile value
+    // that throws here is meant to reach it.
+    const name = err?.name;
+    const ctor = err?.constructor?.name;
+    if (name === 'APIConnectionTimeoutError' || ctor === 'APIConnectionTimeoutError') {
+        return { error_class: 'connection_timeout' };
+    }
+    if (name === 'APIConnectionError' || ctor === 'APIConnectionError') {
+        return { error_class: 'connection_error' };
+    }
+    const status = extractHttpStatus(err);
+    if (status !== undefined)
+        return { error_class: 'api_status', last_observed_status: status };
+    return { error_class: 'other' };
+}
+/**
+ * The class an error's SHAPE implies, for a payload whose own claim did not survive the pick.
+ *
+ * The same constructor check as the arm above, and the easiest of the three to overlook: a
+ * payload carrying measurements but no usable class lands here, so leaving it on `.name` would
+ * have kept the whole defect alive on that one path. Same totality boundary — `buildEntry`'s
+ * catch, not a guard here.
+ */
+function shapeClassify(err) {
+    const name = err?.name;
+    const ctor = err?.constructor?.name;
+    if (name === 'APIConnectionTimeoutError' || ctor === 'APIConnectionTimeoutError') {
+        return 'connection_timeout';
+    }
+    if (name === 'APIConnectionError' || ctor === 'APIConnectionError')
+        return 'connection_error';
+    if (extractHttpStatus(err) !== undefined)
+        return 'api_status';
+    return 'other';
+}
+/**
+ * Builds the record for one failed attempt.
+ *
+ * TOTAL BY CONSTRUCTION, and this is not defensive habit — it closes a real hole. `buildEntry`
+ * runs OUTSIDE the fence's try at every chokepoint, and every step of it touches the thrown value:
+ * `classifyDriveError` reads `err.name` (a throwing getter throws here), `findDriveCall` does
+ * `'driveCall' in e` (a proxy with a `has` trap throws), and `sanitizeError` calls `String(err)`
+ * (a poisoned `toString` throws). A hostile thrown object would therefore make the MINT throw
+ * from inside a catch — replacing the operator's actual error with a secondary one, and at
+ * chokepoints (1)/(2) escalating it to (3), which would then re-mint against the WRONG error.
+ *
+ * So: the mint must never out-throw the failure it records. When the value cannot be rendered,
+ * the degraded entry below carries all six required fields and says plainly that it could not.
+ */
+export function buildEntry(err, step, provider, attemptStartedAt) {
+    try {
+        return buildEntryUnsafe(err, step, provider, attemptStartedAt);
+    }
+    catch {
+        return {
+            at: new Date().toISOString(),
+            step,
+            provider,
+            error_class: 'other',
+            message: 'unrenderable thrown value',
+            elapsed_ms: Date.now() - attemptStartedAt,
+        };
+    }
+}
+function buildEntryUnsafe(err, step, provider, attemptStartedAt) {
+    const classified = classifyDriveError(err);
+    return {
+        at: new Date().toISOString(),
+        step,
+        provider,
+        message: sanitizeError(err).slice(0, MESSAGE_CAP),
+        // The spread goes ABOVE the computed span deliberately (issue #401): a payload key that is
+        // PRESENT but undefined-valued would otherwise clobber a real measurement with nothing. With
+        // this order the `??` below is the live protector of a payload's genuine 0ms span, which also
+        // makes an `||` there a caught mutant rather than an equivalent one.
+        ...classified,
+        elapsed_ms: classified.elapsed_ms ?? Date.now() - attemptStartedAt,
+    };
+}
+/** The one loud line printed when a failure could not be recorded — never replaces the original. */
+export function lostLine(runId, entry) {
+    return `⚠ drive-failure record LOST for run ${runId} (${entry.error_class} at ${entry.at}, step '${entry.step}'): ${entry.message}`;
+}
+function workflowErrorCode(err) {
+    return err instanceof WorkflowError ? err.code : undefined;
+}
+/**
+ * THE FENCE. Appends one entry to the run's drive-failure ring, and never lets its own failure
+ * become the operator's problem.
+ *
+ * Everything here is subordinate to one rule: this must never replace, hide, or crash on top of
+ * the operator's actual error. So a terminal run is a silent skip (the seal is already the
+ * visibility), a vanished run is a silent skip (disposal is the visibility), contention is
+ * retried, and anything else prints ONE line naming exactly what was lost.
+ *
+ * That line lands BESIDE the original, not always after it: chokepoints (1), (2) and (4) print
+ * their error first, so the lost line follows — but chokepoint (3) mints BEFORE its re-throw
+ * reaches the CLI's printer, so there the lost line comes first. Either way the operator has both.
+ */
+export async function recordDriveFailure(store, runId, entry) {
+    try {
+        for (let i = 0; i < WRITE_ATTEMPTS; i++) {
+            const run = await store.get(runId);
+            // A sealed run already tells its story; adding to it would be noise, and writing to it
+            // would reopen a settled record.
+            if (run.terminal_state)
+                return;
+            const prev = run.drive_failures;
+            const field = {
+                first_failed_at: prev?.first_failed_at ?? entry.at,
+                // Monotonic and OUTSIDE the ring: a run that failed forty times must not read as five.
+                total: (prev?.total ?? 0) + 1,
+                entries: [...(prev?.entries ?? []), entry].slice(-RING_CAP),
+            };
+            try {
+                // The record carries its own CAS version, read a few lines above. `update()` bumps
+                // version and updated_at — the latter is what resets the idle clock.
+                await store.update({ ...run, drive_failures: field });
+                return;
+            }
+            catch (err) {
+                const code = workflowErrorCode(err);
+                // Contention, either flavour: re-read and re-apply against the newer record.
+                if (code === 'STATE_SNAPSHOT_MISMATCH' || code === 'STATE_RUN_BUSY')
+                    continue;
+                if (code === 'STATE_RUN_NOT_FOUND')
+                    return; // concurrently purged — disposal is visibility
+                throw err;
+            }
+        }
+        // Lost to contention after every retry.
+        console.error(lostLine(runId, entry));
+    }
+    catch (err) {
+        if (workflowErrorCode(err) === 'STATE_RUN_NOT_FOUND')
+            return;
+        console.error(lostLine(runId, entry));
+    }
+}
+//# sourceMappingURL=drive-failure.js.map

package/dist/agent/drive-failure.js.map

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

package/dist/agent/providers/agent-utils.d.ts

@@ -16,6 +16,20 @@ export declare function setAdditionalRedactionValues(values: readonly string[]):
  * (manifest-secret) values. All literal values are redacted in ONE combined pass,
  * deduped and applied LONGEST-FIRST — a short value contained in a longer one can no
  * longer leave fragments of the longer value behind.
+ *
+ * EXCLUDED from the env sweep (issue #407): npm's own manifest metadata —
+ * `npm_package_*` (except `npm_package_config_*`) and `npm_lifecycle_*`. These are values npm
+ * copies OUT OF package.json, so treating them as secrets meant realm redacted its own name and
+ * version from its own error messages: under npm, `npm_package_name` is `"realm"`, and a message
+ * reading "realm agent requires…" shipped as "[REDACTED] agent requires…". Harmless while it was
+ * console-only; issue #401 persists these messages in the run record, which made the mangling
+ * durable evidence.
+ *
+ * `npm_package_config_*` deliberately STAYS redacted, and the lookahead that keeps it in is
+ * load-bearing: a package.json `config` block holds values the AUTHOR wrote, and npm exports them
+ * verbatim — a probe on this repo produced `npm_package_config_apitoken=SUPERSECRETVALUE123`.
+ * `npm_config_*` stays for the same reason. Widening this exclusion to all `npm_*` would leak
+ * exactly the values most likely to be secrets.
  */
 export declare function sanitizeError(err: unknown): string;
 /**
@@ -23,6 +37,32 @@ export declare function sanitizeError(err: unknown): string;
  * as sanitizeError to strip any tokens that upstream services may have echoed.
  */
 export declare function serializeToolResult(result: unknown): string;
+/** The `error` text for a Class-B result whose content carries no readable text at all. */
+export declare const CLASS_B_NO_TEXT_MARKER = "tool returned isError with no text content";
+/**
+ * Extracts the failure text from a POLITELY FAILED tool call — issue #345.
+ *
+ * MCP defines two ways a tool call fails. The transport can reject (Class A: an exception, which
+ * the providers' catch branch already records honestly), or the call can RETURN normally with
+ * `isError: true` inside the result (Class B: the polite failure the spec defines for a tool
+ * reporting its own error to the model). Class B used to be minted as a success — no `error`
+ * field, the failure text buried inside `result` — which made the record type's own doc contract
+ * false and made every tool-reliability count read failures as successes.
+ *
+ * Returns the sanitized failure text for a Class-B result, or `undefined` for anything else — so
+ * a caller writes `const err = classBError(raw)` and branches on presence.
+ *
+ * WHY `=== true` AND NOT TRUTHINESS. The SDK zod-validates every `callTool` response against
+ * `CallToolResultSchema`, where `isError` is `z.boolean().optional()`. A non-boolean `isError`
+ * fails that parse, the promise REJECTS, and the call lands in the catch branch as Class A —
+ * recorded WITH an `error` either way. So the spec-illegal world cannot reach this mint through
+ * the real transport, and a strict check cannot silently swallow a failure. (The fixture in the
+ * strict-boolean cell models a wire state that cannot occur; it exists to pin the choice, not a
+ * reachable case.) This premise breaks only if realm switches to
+ * `CompatibilityCallToolResultSchema` or talks to a raw transport that skips validation — if that
+ * ever happens, revisit this line first.
+ */
+export declare function classBError(rawResult: unknown): string | undefined;
 /** Splits "server_id:tool_name" into its components. Throws if the format is invalid. */
 export declare function parseNamespacedId(id: string): {
     serverId: string;
@@ -101,4 +141,96 @@ export declare function extractApiErrorFields(err: unknown): {
     api_param?: string | null;
     api_code?: string | null;
 };
+/** Realm's own retry count, passed EXPLICITLY to every SDK client. */
+export declare const MAX_RETRIES = 2;
+/** What a provider attaches to an error it throws, so a chokepoint can classify it precisely. */
+export interface DriveCallPayload {
+    error_class?: string;
+    /**
+     * Attempts the wrapper SAW COMPLETE. An attempt still in flight when the ceiling fired is not
+     * counted — so a pre-header hang records 0, truthfully: nothing came back.
+     */
+    attempts_sdk?: number;
+    elapsed_ms?: number;
+    last_observed_status?: number;
+    retry_after_observed_ms?: number;
+    declared_per_attempt_ms?: number;
+    derived_ceiling_ms?: number;
+}
+/** What one client's fetch wrapper has seen. Per-invocation, minted beside the client. */
+export interface WireCounters {
+    attempts: number;
+    lastStatus?: number;
+    lastRetryAfterMs?: number;
+}
+/** The clock one step drives under. */
+export interface LlmClock {
+    ceilingMs: number;
+    declaredPerAttemptMs?: number;
+    /**
+     * WHERE the per-attempt value came from. Set once, at run-agent's clock construction, and read
+     * only by the disclosure: it decides whether `declared_per_attempt_ms` is recorded at all (a
+     * default nobody chose is not a declaration) and which lever the abort message names.
+     *
+     * Absent on a hand-built clock — a unit cell, a caller that constructed one directly — and the
+     * message then names BOTH levers, because with no provenance either could be the live one.
+     */
+    perAttemptSource?: 'step' | 'flag' | 'default';
+}
+/**
+ * Derives the whole-create ceiling from a per-attempt value.
+ *
+ * `perAttempt × (MAX_RETRIES + 1)` covers every attempt the SDK will make, plus the backoff it
+ * sleeps between them, plus a download allowance so a large-but-progressing response is never
+ * killed for being large. The backoff term is the SDK's OWN schedule summed as an UPPER bound —
+ * its jitter only ever reduces the wait, so budgeting the un-jittered sum cannot cut short a
+ * retry the SDK scheduled for itself.
+ *
+ * A SERVER-DIRECTED wait is a different thing and is deliberately NOT budgeted. A `Retry-After`
+ * can ask for hours; the ceiling outranks it on purpose, which is the point of the bound rather
+ * than a gap in it.
+ */
+export declare function deriveLlmClock(perAttemptMs: number): LlmClock;
+/**
+ * Wraps `fetch` so realm can SEE what the SDK's retry ladder did — how many attempts it made, the
+ * last status, and any Retry-After the server asked for, in all three of its legal forms
+ * (`retry-after-ms`, a numeric `Retry-After`, an HTTP-date `Retry-After`).
+ *
+ * Observation only. Realm never honors a Retry-After: acting on it would be a scheduling decision
+ * this layer does not make, and recording it is what lets an operator tell a rate limit apart from
+ * a hang. The inner fetch is injectable so the wrapper is unit-testable without a socket.
+ */
+export declare function makeCountingFetch(counters: WireCounters, innerFetch?: typeof fetch): typeof fetch;
+/**
+ * Attaches a payload to an error, WITHOUT overwriting one that is already there.
+ *
+ * TOTAL. Both the probe and the assignment can throw on a value realm did not create — `in` runs
+ * a proxy's `has` trap, and assigning to a frozen object throws in strict mode. Either one would
+ * hand the caller the attacher's own TypeError in place of the failure it was trying to describe,
+ * which is the whole attribution chain defeated by the last link in it. An error that cannot be
+ * enriched still propagates, intact and unenriched; shape classification never needed the payload.
+ */
+export declare function attachDriveCall(err: unknown, payload: DriveCallPayload): void;
+/**
+ * Converts any thrown value to display text, TOTALLY.
+ *
+ * The chokepoints interpolate the thrown value into their console line BEFORE recording it, so a
+ * poisoned `toString` used to out-throw at the print — replacing the operator's error with a
+ * secondary one before the (already hardened) mint could run.
+ */
+export declare function safeErrorText(err: unknown): string;
+/**
+ * Runs ONE model create under realm's ceiling.
+ *
+ * Two mechanisms, because one is not enough. The timer is what bounds the wall clock; the abort is
+ * what actually stops work — but only as far as the SDK will let it. The SDK's sleep primitive is
+ * signal-aware, yet its retry site passes no signal, so a raced-out backoff sleep runs to
+ * completion in the worker. That is the ceiling's known reach, not a bug in it: an SDK bump that
+ * threads the signal there would make the race leg partially redundant, and it would still be
+ * earning its keep on the post-header body hang.
+ *
+ * Wraps the CREATE only. Client construction stays outside — that is where a missing SDK attaches
+ * its own payload, and this must never re-attribute it.
+ */
+export declare function driveCreate<T>(rawCreate: (body: Record<string, unknown>, opts: Record<string, unknown>) => Promise<T>, body: Record<string, unknown>, clock: LlmClock, counters: WireCounters): Promise<T>;
 //# sourceMappingURL=agent-utils.d.ts.map

package/dist/agent/providers/agent-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-utils.d.ts","sourceRoot":"","sources":["../../../src/agent/providers/agent-utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,2BAA2B,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AActF;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,wBAAwB,CAAC,EAAE,MAAM,EACjC,qBAAqB,CAAC,EAAE,OAAO,GAC9B,MAAM,CASR;AAUD,6EAA6E;AAC7E,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAE5E;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAqBlD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAG3D;AAED,yFAAyF;AACzF,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAMpF;AAqED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAQ9E;AAiBD;;;;;;GAMG;AACH,MAAM,WAAW,yBAA0B,SAAQ,2BAA2B;IAC5E;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,kBAAkB,EAAE,GAC9B,yBAAyB,EAAE,CA0C7B;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,yBAAyB,GAAG,MAAM,CAarF;AAED,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAItD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAMlE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG;IACnD,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAOA"}
+{"version":3,"file":"agent-utils.d.ts","sourceRoot":"","sources":["../../../src/agent/providers/agent-utils.ts"],"names":[],"mappings":"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"}