@sema-agent/client-core 0.94.0 → 0.95.0

package/dist/usageAnalytics.d.ts

@@ -0,0 +1,146 @@
+import type { UsageAnalyticsParams, UsageBreakdown, UsageDimension, UsageGranularity, UsageMetric, UsageSeries, UsageSummary } from '@sema-agent/sdk';
+export declare const USAGE_SENTENCES: Readonly<{
+    analyticsUnavailable: "Usage analytics aren’t available on this backend.";
+    analyticsUnread: "Usage analytics couldn’t be read just now.";
+    modelsUnavailable: "Per-model usage breakdown isn't available on this backend.";
+    modelsUnread: "Per-model usage breakdown couldn’t be read just now.";
+}>;
+export interface UsageSummaryQuery extends UsageAnalyticsParams {
+    signal?: AbortSignal;
+}
+export interface UsageSeriesQuery extends UsageAnalyticsParams {
+    metric?: UsageMetric;
+    granularity?: UsageGranularity;
+    signal?: AbortSignal;
+}
+export interface UsageBreakdownQuery extends UsageAnalyticsParams {
+    dimension?: UsageDimension;
+    signal?: AbortSignal;
+}
+export interface UsageAnalyticsVerbs {
+    summary?: (opts?: UsageSummaryQuery) => Promise<UsageSummary>;
+    series?: (opts?: UsageSeriesQuery) => Promise<UsageSeries>;
+    breakdown?: (opts?: UsageBreakdownQuery) => Promise<UsageBreakdown>;
+}
+export interface UsageAnalyticsClientLike {
+    usage: UsageAnalyticsVerbs;
+}
+export interface UsageReadOptions {
+    from?: string | number;
+    to?: string | number;
+    principal?: string;
+    signal?: AbortSignal;
+}
+export interface UsageSeriesReadOptions extends UsageReadOptions {
+    metric?: UsageMetric;
+    granularity?: UsageGranularity;
+}
+export interface UsageBreakdownReadOptions extends UsageReadOptions {
+    dimension?: UsageDimension;
+}
+export type UsageBound = 'exact' | 'lower' | 'approximate';
+export type UsagePrecision = 'exact' | 'estimated';
+export interface UsageTotalsView {
+    tasks?: number;
+    tokensIn?: number;
+    tokensOut?: number;
+    cost?: number;
+    precision: UsagePrecision;
+}
+export interface UsageWindowView {
+    from?: string;
+    to?: string;
+    truncated: boolean;
+}
+export type UsageSummaryView = UsageWindowView & UsageTotalsView;
+export interface UsageSeriesPointView {
+    t: string;
+    v: number;
+    estimated?: boolean;
+}
+export interface UsageSeriesView extends UsageWindowView {
+    points: UsageSeriesPointView[];
+    unreadable: number;
+}
+export type UsageBreakdownRowView = UsageTotalsView & {
+    key: string;
+};
+export interface UsageBreakdownView extends UsageWindowView {
+    rows: UsageBreakdownRowView[];
+    unreadable: number;
+}
+export type UsageUnavailableWhy = 'capability' | 'feature' | 'route';
+export type UsageReadVerdict<T> = {
+    readonly kind: 'ok';
+    readonly value: T;
+} | {
+    readonly kind: 'unavailable';
+    readonly why: UsageUnavailableWhy;
+} | {
+    readonly kind: 'failed';
+    readonly error: unknown;
+};
+export declare function classifyUsageFailure(e: unknown): UsageReadVerdict<never>;
+export declare function projectUsageSummary(body: unknown): UsageSummaryView | undefined;
+export declare function projectUsageSeries(body: unknown): UsageSeriesView | undefined;
+export declare function projectUsageBreakdown(body: unknown): UsageBreakdownView | undefined;
+export declare function readUsageSummary(client: UsageAnalyticsClientLike, opts?: UsageReadOptions): Promise<UsageReadVerdict<UsageSummaryView>>;
+export declare function readUsageSeries(client: UsageAnalyticsClientLike, opts?: UsageSeriesReadOptions): Promise<UsageReadVerdict<UsageSeriesView>>;
+export declare function readUsageBreakdown(client: UsageAnalyticsClientLike, opts?: UsageBreakdownReadOptions): Promise<UsageReadVerdict<UsageBreakdownView>>;
+export interface UsageAmount {
+    readonly value: number;
+    readonly bound: UsageBound;
+}
+export declare function usageBoundPrefix(bound: UsageBound): '' | '≥' | '≈';
+export interface UsageHeatmapCell {
+    readonly date: string;
+    readonly tasks: number;
+}
+export type UsageUnavailableCause = 'no_backend_face' | 'read_failed';
+export type UsageModelsView = {
+    readonly state: 'available';
+    readonly rows: readonly UsageBreakdownRowView[];
+    readonly unreadable: number;
+} | {
+    readonly state: 'unavailable';
+    readonly cause: UsageUnavailableCause;
+    readonly sentence: string;
+};
+export interface UsageAnalyticsReadings {
+    readonly state: 'available' | 'estimated';
+    readonly truncated: boolean;
+    readonly runs?: number;
+    readonly tokens?: UsageAmount;
+    readonly cost?: UsageAmount;
+    readonly activeDays?: number;
+    readonly peakHourUtc?: number;
+    readonly favoriteModel?: string;
+    readonly heatmap: readonly UsageHeatmapCell[] | null;
+    readonly models: UsageModelsView;
+}
+export interface UsageAnalyticsUnavailable {
+    readonly state: 'unavailable';
+    readonly cause: UsageUnavailableCause;
+    readonly sentence: string;
+    readonly models: Extract<UsageModelsView, {
+        state: 'unavailable';
+    }>;
+}
+export type UsageAnalyticsView = UsageAnalyticsReadings | UsageAnalyticsUnavailable;
+export interface UsageAnalyticsInputs {
+    summary: UsageReadVerdict<UsageSummaryView>;
+    daySeries: UsageReadVerdict<UsageSeriesView>;
+    hourSeries: UsageReadVerdict<UsageSeriesView>;
+    modelBreakdown: UsageReadVerdict<UsageBreakdownView>;
+}
+export interface UsageAnalyticsWindow {
+    readonly from: number;
+    readonly to: number;
+}
+export type UsageRange = 'all' | '30d' | '7d';
+export declare const USAGE_HEATMAP_MAX_DAYS = 70;
+export declare function usageWindowOfRange(range: UsageRange, now: number): UsageAnalyticsWindow;
+export declare function projectUsageAnalytics(inputs: UsageAnalyticsInputs, window: UsageAnalyticsWindow): UsageAnalyticsView;
+export declare function readUsageAnalytics(client: UsageAnalyticsClientLike, window: UsageAnalyticsWindow, opts?: {
+    signal?: AbortSignal;
+}): Promise<UsageAnalyticsView>;

package/dist/usageAnalytics.js

@@ -0,0 +1,311 @@
+export const USAGE_SENTENCES = Object.freeze({
+    analyticsUnavailable: 'Usage analytics aren’t available on this backend.',
+    analyticsUnread: 'Usage analytics couldn’t be read just now.',
+    modelsUnavailable: "Per-model usage breakdown isn't available on this backend.",
+    modelsUnread: 'Per-model usage breakdown couldn’t be read just now.',
+});
+const _sdkClientIsAnInjection = [true];
+void _sdkClientIsAnInjection;
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const nonNeg = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0;
+const nonEmpty = (v) => typeof v === 'string' && v.length > 0;
+export function classifyUsageFailure(e) {
+    let code;
+    let status;
+    try {
+        const o = e;
+        const rawCode = o?.errorCode;
+        const rawStatus = o?.status;
+        code = typeof rawCode === 'string' ? rawCode : undefined;
+        status = typeof rawStatus === 'number' ? rawStatus : undefined;
+    }
+    catch {
+        return { kind: 'failed', error: e };
+    }
+    if (code !== undefined) {
+        if (code.startsWith('capability.'))
+            return { kind: 'unavailable', why: 'capability' };
+        if (code.startsWith('feature.'))
+            return { kind: 'unavailable', why: 'feature' };
+        if (code === 'not_found.route')
+            return { kind: 'unavailable', why: 'route' };
+        return { kind: 'failed', error: e };
+    }
+    if (status === 501)
+        return { kind: 'unavailable', why: 'capability' };
+    return { kind: 'failed', error: e };
+}
+function windowOf(o) {
+    const w = { truncated: o.truncated === true };
+    if (nonEmpty(o.from))
+        w.from = o.from;
+    if (nonEmpty(o.to))
+        w.to = o.to;
+    return w;
+}
+const precisionOf = (estimated) => (estimated === false ? 'exact' : 'estimated');
+const TOTAL_FIELDS = ['tasks', 'tokensIn', 'tokensOut', 'cost'];
+const TOTAL_WIRE_KEYS = Object.freeze({ tasks: 'tasks', tokensIn: 'tokensIn', tokensOut: 'tokensOut', cost: 'costUsd' });
+function totalsOf(o) {
+    const t = { precision: precisionOf(o.estimated) };
+    for (const field of TOTAL_FIELDS) {
+        const v = o[TOTAL_WIRE_KEYS[field]];
+        if (nonNeg(v))
+            t[field] = v;
+    }
+    return t;
+}
+export function projectUsageSummary(body) {
+    try {
+        if (!isRecord(body))
+            return undefined;
+        return { ...windowOf(body), ...totalsOf(body) };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function projectUsageSeries(body) {
+    try {
+        if (!isRecord(body))
+            return undefined;
+        const series = body.series;
+        if (!Array.isArray(series))
+            return undefined;
+        const points = [];
+        let unreadable = 0;
+        for (const raw of series) {
+            if (!isRecord(raw) || !nonEmpty(raw.t) || !nonNeg(raw.v)) {
+                unreadable++;
+                continue;
+            }
+            const p = { t: raw.t, v: raw.v };
+            if (typeof raw.estimated === 'boolean')
+                p.estimated = raw.estimated;
+            points.push(p);
+        }
+        return { ...windowOf(body), points, unreadable };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function projectUsageBreakdown(body) {
+    try {
+        if (!isRecord(body))
+            return undefined;
+        const breakdown = body.breakdown;
+        if (!Array.isArray(breakdown))
+            return undefined;
+        const rows = [];
+        let unreadable = 0;
+        for (const raw of breakdown) {
+            if (!isRecord(raw) || !nonEmpty(raw.key)) {
+                unreadable++;
+                continue;
+            }
+            rows.push({ key: raw.key, ...totalsOf(raw) });
+        }
+        return { ...windowOf(body), rows, unreadable };
+    }
+    catch {
+        return undefined;
+    }
+}
+function windowBag(opts) {
+    const bag = {};
+    if (opts.from !== undefined)
+        bag.from = opts.from;
+    if (opts.to !== undefined)
+        bag.to = opts.to;
+    if (opts.principal !== undefined)
+        bag.principal = opts.principal;
+    if (opts.signal !== undefined)
+        bag.signal = opts.signal;
+    return bag;
+}
+async function readOne(call, project, what) {
+    try {
+        const pending = call();
+        if (pending === undefined)
+            return { kind: 'unavailable', why: 'route' };
+        const view = project(await pending);
+        if (view === undefined)
+            return { kind: 'failed', error: new Error(`usage ${what}: malformed body`) };
+        return { kind: 'ok', value: view };
+    }
+    catch (e) {
+        return classifyUsageFailure(e);
+    }
+}
+export function readUsageSummary(client, opts = {}) {
+    return readOne(() => (typeof client?.usage?.summary === 'function' ? client.usage.summary(windowBag(opts)) : undefined), projectUsageSummary, 'summary');
+}
+export function readUsageSeries(client, opts = {}) {
+    return readOne(() => {
+        if (typeof client?.usage?.series !== 'function')
+            return undefined;
+        const bag = windowBag(opts);
+        if (opts.metric !== undefined)
+            bag.metric = opts.metric;
+        if (opts.granularity !== undefined)
+            bag.granularity = opts.granularity;
+        return client.usage.series(bag);
+    }, projectUsageSeries, 'series');
+}
+export function readUsageBreakdown(client, opts = {}) {
+    return readOne(() => {
+        if (typeof client?.usage?.breakdown !== 'function')
+            return undefined;
+        const bag = windowBag(opts);
+        if (opts.dimension !== undefined)
+            bag.dimension = opts.dimension;
+        return client.usage.breakdown(bag);
+    }, projectUsageBreakdown, 'breakdown');
+}
+export function usageBoundPrefix(bound) {
+    return bound === 'lower' ? '≥' : bound === 'approximate' ? '≈' : '';
+}
+const DAY_MS = 86_400_000;
+export const USAGE_HEATMAP_MAX_DAYS = 70;
+export function usageWindowOfRange(range, now) {
+    if (range === 'all')
+        return { from: 0, to: now };
+    const days = range === '30d' ? 30 : 7;
+    return { from: now - days * DAY_MS, to: now };
+}
+function unavailableCauseOf(v) {
+    return v.kind === 'unavailable' ? 'no_backend_face' : 'read_failed';
+}
+function modelsUnavailable(cause) {
+    return { state: 'unavailable', cause, sentence: cause === 'no_backend_face' ? USAGE_SENTENCES.modelsUnavailable : USAGE_SENTENCES.modelsUnread };
+}
+const DAY_KEY_RE = /^(\d{4})-(\d{2})-(\d{2})(?:[T ]|$)/;
+function dayKeyOf(iso) {
+    const m = DAY_KEY_RE.exec(iso);
+    if (m === null)
+        return undefined;
+    const y = Number(m[1]);
+    const mo = Number(m[2]);
+    const d = Number(m[3]);
+    const at = new Date(Date.UTC(y, mo - 1, d));
+    return at.getUTCFullYear() === y && at.getUTCMonth() === mo - 1 && at.getUTCDate() === d ? iso.slice(0, 10) : undefined;
+}
+const isWhole = (v) => v.unreadable === 0 && !v.truncated;
+function hourOfDayUtc(iso) {
+    const d = new Date(iso);
+    return Number.isNaN(d.getTime()) ? undefined : d.getUTCHours();
+}
+function peakHourOf(points) {
+    if (points.length === 0)
+        return undefined;
+    const perHour = new Array(24).fill(0);
+    for (const p of points) {
+        const h = hourOfDayUtc(p.t);
+        if (h === undefined)
+            return undefined;
+        perHour[h] = (perHour[h] ?? 0) + p.v;
+    }
+    let peakHour = -1;
+    let peakValue = -1;
+    perHour.forEach((value, h) => {
+        if (value > peakValue) {
+            peakValue = value;
+            peakHour = h;
+        }
+    });
+    return peakHour >= 0 && peakValue > 0 ? peakHour : undefined;
+}
+function heatmapOf(window, dayValues) {
+    if (!Number.isFinite(window.from) || !Number.isFinite(window.to))
+        return null;
+    const windowDays = Math.max(1, Math.round((window.to - window.from) / DAY_MS) + 1);
+    const days = Math.min(windowDays, USAGE_HEATMAP_MAX_DAYS);
+    const cells = [];
+    for (let i = days - 1; i >= 0; i--) {
+        const at = new Date(window.to - i * DAY_MS);
+        if (Number.isNaN(at.getTime()))
+            return null;
+        const key = at.toISOString().slice(0, 10);
+        cells.push({ date: key, tasks: dayValues.get(key) ?? 0 });
+    }
+    return cells;
+}
+export function projectUsageAnalytics(inputs, window) {
+    const s = inputs.summary;
+    if (s.kind !== 'ok') {
+        const cause = unavailableCauseOf(s);
+        return {
+            state: 'unavailable',
+            cause,
+            sentence: cause === 'no_backend_face' ? USAGE_SENTENCES.analyticsUnavailable : USAGE_SENTENCES.analyticsUnread,
+            models: modelsUnavailable(cause),
+        };
+    }
+    const sv = s.value;
+    const readings = {
+        state: sv.precision === 'estimated' ? 'estimated' : 'available',
+        truncated: sv.truncated,
+        heatmap: null,
+        models: modelsUnavailable('read_failed'),
+    };
+    if (sv.tasks !== undefined)
+        readings.runs = sv.tasks;
+    const exact = sv.precision === 'exact';
+    if (sv.tokensIn !== undefined && sv.tokensOut !== undefined) {
+        readings.tokens = { value: sv.tokensIn + sv.tokensOut, bound: !exact ? 'approximate' : sv.truncated ? 'lower' : 'exact' };
+    }
+    if (sv.cost !== undefined)
+        readings.cost = { value: sv.cost, bound: exact && !sv.truncated ? 'exact' : 'lower' };
+    const day = inputs.daySeries;
+    if (day.kind === 'ok' && isWhole(day.value)) {
+        const dayValues = new Map();
+        let allKeysReadable = true;
+        for (const p of day.value.points) {
+            const key = dayKeyOf(p.t);
+            if (key === undefined)
+                allKeysReadable = false;
+            else
+                dayValues.set(key, (dayValues.get(key) ?? 0) + p.v);
+        }
+        if (allKeysReadable) {
+            readings.activeDays = [...dayValues.values()].filter((v) => v > 0).length;
+            readings.heatmap = heatmapOf(window, dayValues);
+        }
+    }
+    const hour = inputs.hourSeries;
+    if (hour.kind === 'ok' && isWhole(hour.value)) {
+        const peak = peakHourOf(hour.value.points);
+        if (peak !== undefined)
+            readings.peakHourUtc = peak;
+    }
+    const br = inputs.modelBreakdown;
+    if (br.kind === 'ok') {
+        readings.models = { state: 'available', rows: br.value.rows, unreadable: br.value.unreadable };
+        if (isWhole(br.value)) {
+            let favorite;
+            for (const row of br.value.rows) {
+                if (row.tasks === undefined)
+                    continue;
+                if (favorite === undefined || row.tasks > (favorite.tasks ?? -1))
+                    favorite = row;
+            }
+            if (favorite !== undefined)
+                readings.favoriteModel = favorite.key;
+        }
+    }
+    else {
+        readings.models = modelsUnavailable(unavailableCauseOf(br));
+    }
+    return readings;
+}
+export async function readUsageAnalytics(client, window, opts = {}) {
+    const base = { from: window.from, to: window.to, ...(opts.signal ? { signal: opts.signal } : {}) };
+    const [summary, daySeries, hourSeries, modelBreakdown] = await Promise.all([
+        readUsageSummary(client, base),
+        readUsageSeries(client, { ...base, metric: 'tasks', granularity: 'day' }),
+        readUsageSeries(client, { ...base, metric: 'tasks', granularity: 'hour' }),
+        readUsageBreakdown(client, { ...base, dimension: 'model' }),
+    ]);
+    return projectUsageAnalytics({ summary, daySeries, hourSeries, modelBreakdown }, window);
+}

package/dist/userInvokedSkillsCapability.d.ts

@@ -14,5 +14,4 @@ export declare function noteEngineCapsForUserInvokedSkills(baseUrl: string, caps
 export declare function observedUserInvokedSkills(baseUrl?: string | undefined): UserInvokedSkillsReading;
 export declare function userInvokedSkillsAvailable(reading: UserInvokedSkillsReading): 'yes' | 'no' | 'unknown';
 export declare function userInvokedSkillsDoctorDetail(reading: UserInvokedSkillsReading): string;
-export declare function forgetUserInvokedSkillsReading(baseUrl: string | undefined): void;
 export declare function __resetUserInvokedSkillsReadingsForTests(): void;

package/dist/userInvokedSkillsCapability.js

@@ -1,12 +1,11 @@
 import { engineWireTarget } from './engineWireTarget.js';
 import { createEngineCapReader } from './engineCapReader.js';
+import { ownDataField } from './ownKey.js';
 export function projectUserInvokedSkillsCapability(caps) {
     try {
         if (caps === null || typeof caps !== 'object' || Array.isArray(caps))
             return undefined;
-        if (!Object.hasOwn(caps, 'userInvokedSkills'))
-            return { kind: 'not_reported' };
-        const v = caps.userInvokedSkills;
+        const v = ownDataField(caps, 'userInvokedSkills');
         if (v === undefined)
             return { kind: 'not_reported' };
         if (typeof v !== 'boolean')
@@ -47,9 +46,6 @@ export function userInvokedSkillsDoctorDetail(reading) {
             return 'user-invoked skills on — skills the user names on a request take effect when the run starts';
     }
 }
-export function forgetUserInvokedSkillsReading(baseUrl) {
-    reader.forget(baseUrl);
-}
 export function __resetUserInvokedSkillsReadingsForTests() {
     reader.__resetForTests();
 }

package/dist/webSearchBackendCapability.d.ts

@@ -18,5 +18,4 @@ export declare function noteEngineCapsForWebSearchBackend(baseUrl: string, caps:
 }): void;
 export declare function observedWebSearchBackend(baseUrl?: string | undefined): WebSearchBackendReading;
 export declare function webSearchBackendDoctorDetail(reading: WebSearchBackendReading): string;
-export declare function forgetWebSearchBackendReading(baseUrl: string | undefined): void;
 export declare function __resetWebSearchBackendReadingsForTests(): void;

package/dist/webSearchBackendCapability.js

@@ -1,6 +1,7 @@
 import { capForDisplay } from './fleetTaskDesc.js';
 import { engineWireTarget } from './engineWireTarget.js';
 import { createEngineCapReader } from './engineCapReader.js';
+import { ownDataField } from './ownKey.js';
 export const WEB_SEARCH_BACKEND_NONE = 'none';
 export function projectWebSearchBackendCapability(caps) {
     try {
@@ -8,14 +9,12 @@ export function projectWebSearchBackendCapability(caps) {
             return undefined;
         if (caps === null || typeof caps !== 'object' || Array.isArray(caps))
             return undefined;
-        if (!Object.hasOwn(caps, 'webSearch'))
-            return { kind: 'not_reported' };
-        const ws = caps.webSearch;
+        const ws = ownDataField(caps, 'webSearch');
         if (ws === undefined)
             return { kind: 'not_reported' };
         if (ws === null || typeof ws !== 'object' || Array.isArray(ws))
             return undefined;
-        const backend = ws.backend;
+        const backend = ownDataField(ws, 'backend');
         if (typeof backend !== 'string' || backend === '')
             return undefined;
         if (backend === WEB_SEARCH_BACKEND_NONE)
@@ -56,9 +55,6 @@ export function webSearchBackendDoctorDetail(reading) {
                 '(per-request overrides are not echoed here)');
     }
 }
-export function forgetWebSearchBackendReading(baseUrl) {
-    reader.forget(baseUrl);
-}
 export function __resetWebSearchBackendReadingsForTests() {
     reader.__resetForTests();
 }

package/dist/webSearchWireCaps.js

@@ -1,3 +1,4 @@
+import { SETTINGS_IS_HIERARCHICAL_URL } from './generated/settingsSchemaFns.js';
 import { hostEnv } from './hostEnv.js';
 export const WEBSEARCH_ENV = {
     provider: 'SEMA_WEBSEARCH_PROVIDER',
@@ -6,15 +7,6 @@ export const WEBSEARCH_ENV = {
     maxResults: 'SEMA_WEBSEARCH_MAX_RESULTS',
 };
 const isBlankText = (v) => v.trim() === '';
-function isHierarchicalUrl(raw) {
-    try {
-        const u = new URL(raw);
-        return u.href.startsWith(u.protocol + '//');
-    }
-    catch {
-        return false;
-    }
-}
 function judgeProvider(raw) {
     const word = typeof raw === 'string' ? raw.trim().toLowerCase() : undefined;
     if (word === 'brave' || word === 'tavily' || word === 'searxng')
@@ -71,7 +63,7 @@ function judgeEndpoint(raw) {
         return { ok: false, issue: ENDPOINT_ISSUE };
     if (isBlankText(raw))
         return { ok: true, value: undefined };
-    if (!isHierarchicalUrl(raw))
+    if (!SETTINGS_IS_HIERARCHICAL_URL(raw))
         return { ok: false, issue: ENDPOINT_ISSUE };
     const u = new URL(raw);
     return u.username !== '' || u.password !== ''
@@ -236,7 +228,7 @@ export function webSearchVerdictMessage(verdict, context = 'submit') {
         : `Web search is misconfigured: ${where} ${verdict.issue}. Requests will be refused until you ${fix}.`;
 }
 export function webSearchEndpointForDisplay(raw) {
-    if (typeof raw !== 'string' || !isHierarchicalUrl(raw))
+    if (typeof raw !== 'string' || !SETTINGS_IS_HIERARCHICAL_URL(raw))
         return undefined;
     try {
         const u = new URL(raw);

package/dist/wireFailureShape.d.ts

@@ -10,6 +10,9 @@ interface WireFailureShape {
     message: string;
     ownMessage?: string;
 }
+export declare const THROWN_SLOT_UNREADABLE: unique symbol;
+export declare function readThrownSlot(o: unknown, key: string, own?: boolean): unknown;
+export declare function thrownIsInstanceOf<C extends abstract new (...args: never[]) => unknown>(e: unknown, cls: C): e is InstanceType<C>;
 export declare function readErrorNumber(o: object, key: string): number | undefined;
 export declare function readErrorRecord(o: object, key: string): object | undefined;
 export declare function readErrorString(o: object, key: string): string | undefined;
@@ -21,4 +24,5 @@ export declare function wireFailureTextsOf(e: unknown): {
     reason: string;
     log: string;
 };
+export declare function readRefusalField(o: object): string | undefined;
 export {};

package/dist/wireFailureShape.js

@@ -1,9 +1,24 @@
-function readGuarded(o, key) {
+export const THROWN_SLOT_UNREADABLE = Symbol('thrown-slot-unreadable');
+export function readThrownSlot(o, key, own = false) {
     try {
+        if (own && !Object.hasOwn(o, key))
+            return undefined;
         return o[key];
     }
     catch {
-        return undefined;
+        return THROWN_SLOT_UNREADABLE;
+    }
+}
+function readGuarded(o, key) {
+    const v = readThrownSlot(o, key);
+    return v === THROWN_SLOT_UNREADABLE ? undefined : v;
+}
+export function thrownIsInstanceOf(e, cls) {
+    try {
+        return e instanceof cls;
+    }
+    catch {
+        return false;
     }
 }
 function readErrorSlot(obj, key, accept) {
@@ -189,3 +204,28 @@ export function wireFailureTextsOf(e) {
         return { reason: String(e), log };
     return { reason: WIRE_FAILURE_UNRENDERABLE_TEXT, log };
 }
+export function readRefusalField(o) {
+    const str = (rec) => {
+        let v;
+        try {
+            v = rec.field;
+        }
+        catch {
+            return undefined;
+        }
+        return typeof v === 'string' && v !== '' ? v : undefined;
+    };
+    let extra;
+    try {
+        extra = o.extra;
+    }
+    catch {
+        extra = undefined;
+    }
+    if (typeof extra === 'object' && extra !== null && !Array.isArray(extra)) {
+        const fromExtra = str(extra);
+        if (fromExtra !== undefined)
+            return fromExtra;
+    }
+    return str(o);
+}

package/dist/wireRefusalCopy.js

@@ -1,6 +1,6 @@
-import { readErrorNumber, readErrorRecord, readErrorStrictStringList, readErrorString, readErrorStringList } from './wireFailureShape.js';
+import { readErrorNumber, readErrorRecord, readErrorStrictStringList, readErrorString, readErrorStringList, readRefusalField } from './wireFailureShape.js';
 import { readOwnNonEmptyString } from './ownKey.js';
-import { ACTIVE_RUN_BUSY_ERROR_CODE, FLEET_LEASE_UNAVAILABLE, REQUEST_AUTONOMY_LANE_REFUSED, REQUEST_FIELD_CONFLICT, RESUME_POLICY_FOLD_CODE, SCENARIO_ASSIGNMENT_UNKNOWN_ERROR_CODE, USAGE_WINDOW_EXHAUSTED } from './engineErrorCodes.js';
+import { ACTIVE_RUN_BUSY_ERROR_CODE, FLEET_LEASE_UNAVAILABLE, REQUEST_AUTONOMY_LANE_REFUSED, REQUEST_FIELD_CONFLICT, RESUME_OUTCOME_INVALID, RESUME_POLICY_FOLD_CODE, SCENARIO_ASSIGNMENT_UNKNOWN_ERROR_CODE, USAGE_WINDOW_EXHAUSTED } from './engineErrorCodes.js';
 import { capForDisplay } from './fleetTaskDesc.js';
 import { effectiveWireErrorCode } from './wireErrorTriage.js';
 import { CORE_TOOL_DECLARATION_CODES } from './generated/engineFactTables.js';
@@ -184,23 +184,7 @@ export function scenarioAssignmentUnknownFromError(err) {
 const SETTLED_BY_NOT_IN_PROOF = 'settled_by_not_in_proof';
 const DECIDED_BY_NOT_IN_PROOF = 'decided_by_not_in_proof';
 const RETIRED_DECISION_KEY = 'settledBy';
-const RESUME_OUTCOME_INVALID = 'resume_outcome_invalid';
 const APPROVAL_NON_BINDING_FIELDS = new Set(['hostDecision', 'approver']);
-function readRefusalField(o) {
-    let extra;
-    try {
-        extra = o.extra;
-    }
-    catch {
-        extra = undefined;
-    }
-    if (typeof extra === 'object' && extra !== null && !Array.isArray(extra)) {
-        const fromExtra = readStringField(extra, 'field');
-        if (fromExtra !== undefined)
-            return fromExtra;
-    }
-    return readStringField(o, 'field');
-}
 export function denyAttributionRefusalFromError(err, sentAttributionKey) {
     try {
         if (err === null || typeof err !== 'object')