@sema-agent/client-core 0.97.1 → 0.99.0

package/dist/turnFailurePresentation.js

@@ -0,0 +1,402 @@
+import { msg, renderMessage } from './i18n/translate.js';
+import { classifyTurnWireError, effectiveWireErrorCode, isPreStreamDrainingReject } from './wireErrorTriage.js';
+import { isSseIdleError } from './sseIdleTriage.js';
+import { isCodeClassifiedGateFailure } from './gateFailureCodes.js';
+import { CORRUPT_ROW_ERROR_CODE, CORRUPT_SESSION_ERROR_CODE, MEMORY_CONTROL_PLANE_CORRUPT, SCENARIO_ASSIGNMENT_UNKNOWN_ERROR_CODE } from './engineErrorCodes.js';
+import { bodyShapeRefusalFromError, bodyShapeRefusalTouchesSettings, fleetLeaseUnavailableContent, fleetLeaseUnavailableFromError, hostPostureRefusalContent, hostPostureRefusalFromError, settingsPermissionBucketRefusalContent, settingsPermissionBucketRefusalFromError, toolDeclarationRefusalContent, toolDeclarationRefusalFromError, usageWindowExhaustedContent, usageWindowExhaustedFromError, } from './wireRefusalCopy.js';
+import { THROWN_SLOT_UNREADABLE, readErrorNumber, readThrownSlot, wireFailureTextsOf } from './wireFailureShape.js';
+import { provablyNotSent } from './engineWireFor.js';
+import { corruptStoredRowContent, scenarioDenyFromError, scenarioNotAllowedContent } from './wireErrorTriage.js';
+import { checkpointUnsupportedVersionContent, checkpointUnsupportedVersionFromError, requireExistingSessionRefusalContent, requireExistingSessionRefusalFromError, resumeContextUnavailableContent, resumeContextUnavailableFromError, resumePolicyBlockContent, resumePolicyBlockFromError, resumeRefusalContent, resumeRefusalFromError, } from './resumeRefusalCopy.js';
+import { resumeReopenContent, resumeReopenFromError } from './hitl/suspendedReopen.js';
+import { isCorruptSessionError } from './corruptSession.js';
+import { corruptSessionContent } from './corruptSessionCopy.js';
+import { inheritEnvRefusalContent, inheritEnvRefusalFromError } from './inheritEnvWire.js';
+import { modelCandidateRejectedContent, modelCandidateRejectedOf } from './liveModelCatalog.js';
+const CATEGORY_TABLE = Object.freeze({
+    auth: true,
+    billing: true,
+    rate_limited: true,
+    invalid_request: true,
+    capability_unavailable: true,
+    timeout: true,
+    server_error: true,
+    connection_lost: true,
+    parked: true,
+    internal: true,
+});
+export const TURN_FAILURE_CATEGORIES = Object.freeze(Object.keys(CATEGORY_TABLE));
+const TURN_FAILURE_HEADLINE_KEYS = Object.freeze({
+    connection_lost_not_sent: 'notice.failure.headline.connectionLostNotSent',
+    connection_lost: 'notice.failure.headline.connectionLost',
+    timeout: 'notice.failure.headline.timeout',
+    parked: 'notice.failure.headline.parked',
+    internal: 'notice.failure.headline.internal',
+});
+function waitSecOf(err) {
+    const ms = readThrownSlot(err, 'retryAfterMs', 'data');
+    if (typeof ms === 'number' && Number.isFinite(ms) && ms > 0)
+        return Math.max(1, Math.ceil(ms / 1000));
+    if (typeof err === 'object' && err !== null) {
+        const bodySec = readErrorNumber(err, 'retryAfterSec');
+        if (typeof bodySec === 'number' && Number.isFinite(bodySec) && bodySec > 0)
+            return Math.max(1, Math.ceil(bodySec));
+        const detail = readThrownSlot(err, 'detail', 'data');
+        if (typeof detail === 'object' && detail !== null) {
+            const sec = readThrownSlot(detail, 'retryAfterSec', 'data');
+            if (typeof sec === 'number' && Number.isFinite(sec) && sec > 0)
+                return Math.max(1, Math.ceil(sec));
+        }
+    }
+    return undefined;
+}
+function isIdleWatchdog(err) {
+    try {
+        return isSseIdleError(err);
+    }
+    catch {
+        return false;
+    }
+}
+const DETERMINISTIC_SERVER_CODES = new Set([CORRUPT_SESSION_ERROR_CODE, CORRUPT_ROW_ERROR_CODE, SCENARIO_ASSIGNMENT_UNKNOWN_ERROR_CODE, MEMORY_CONTROL_PLANE_CORRUPT]);
+const BROWSER_FETCH_FAILURE = /\bfailed to fetch\b|\bnetworkerror\b|\bnetwork error\b|\bload failed\b/i;
+function httpShapeOf(err, verdict) {
+    const status = verdict.status;
+    const code = effectiveWireErrorCode(err) ?? verdict.errorCode;
+    if (verdict.sessionUnreadable === true || verdict.storedRowWhere !== undefined)
+        return { category: 'server_error', offer: false };
+    if (toolDeclarationRefusalFromError(err) !== null)
+        return { category: 'invalid_request', offer: false };
+    if (code !== undefined && DETERMINISTIC_SERVER_CODES.has(code))
+        return { category: 'server_error', offer: false };
+    if (code === 'quota_exhausted')
+        return { category: 'rate_limited', offer: false };
+    if (code === 'budget.precall' || code === 'budget.exceeded')
+        return { category: 'billing', offer: false };
+    if (code === 'draining' || verdict.leaseUnavailable === true || isPreStreamDrainingReject(err))
+        return { category: 'server_error', offer: true };
+    if (status === 501 || (code !== undefined && code.startsWith('capability.')))
+        return { category: 'capability_unavailable', offer: false };
+    if (status === 401 || status === 403)
+        return { category: 'auth', offer: false };
+    if (status === 402)
+        return { category: 'billing', offer: false };
+    if (status === 408)
+        return { category: 'timeout', offer: true };
+    if (status === 429)
+        return { category: 'rate_limited', offer: true };
+    if (status >= 500)
+        return { category: 'server_error', offer: true };
+    if (status >= 400)
+        return { category: 'invalid_request', offer: false };
+    return { category: 'internal', offer: false };
+}
+function connectionLostBeforeSend(err, evidence) {
+    if (readThrownSlot(evidence, 'bound', 'data') === true || readThrownSlot(evidence, 'reopened', 'data') === true)
+        return false;
+    return typeof err === 'object' && err !== null && provablyNotSent(err);
+}
+export function turnFailurePresentation(err, evidence, notesCtx, lang) {
+    const verdict = classifyTurnWireError(err);
+    let shape;
+    let headlineKey;
+    let detail;
+    let name;
+    if (verdict.kind === 'http') {
+        shape = httpShapeOf(err, verdict);
+        detail = verdict.message;
+        if (shape.category === 'internal')
+            headlineKey = TURN_FAILURE_HEADLINE_KEYS.internal;
+    }
+    else if (verdict.kind === 'stream-ended-without-terminal') {
+        shape = { category: 'parked', offer: false };
+        headlineKey = TURN_FAILURE_HEADLINE_KEYS.parked;
+        detail = wireFailureTextsOf(err).reason;
+    }
+    else if (verdict.kind === 'transport') {
+        const notSent = connectionLostBeforeSend(err, evidence);
+        shape = { category: 'connection_lost', offer: notSent };
+        headlineKey = notSent ? TURN_FAILURE_HEADLINE_KEYS.connection_lost_not_sent : TURN_FAILURE_HEADLINE_KEYS.connection_lost;
+        detail = verdict.detail;
+    }
+    else if (isIdleWatchdog(err)) {
+        shape = { category: 'timeout', offer: true };
+        headlineKey = TURN_FAILURE_HEADLINE_KEYS.timeout;
+        detail = verdict.detail;
+    }
+    else if (BROWSER_FETCH_FAILURE.test(verdict.detail)) {
+        const notSent = connectionLostBeforeSend(err, evidence);
+        shape = { category: 'connection_lost', offer: notSent };
+        headlineKey = notSent ? TURN_FAILURE_HEADLINE_KEYS.connection_lost_not_sent : TURN_FAILURE_HEADLINE_KEYS.connection_lost;
+        detail = verdict.detail;
+    }
+    else {
+        shape = { category: 'internal', offer: false };
+        headlineKey = TURN_FAILURE_HEADLINE_KEYS.internal;
+        detail = verdict.detail;
+        name = verdict.name;
+    }
+    const status = verdict.kind === 'http' ? verdict.status : undefined;
+    const errorCode = verdict.kind === 'http' ? (effectiveWireErrorCode(err) ?? verdict.errorCode) : undefined;
+    const wireRetriable = readThrownSlot(err, 'retriable', 'data') === true && !isCodeClassifiedGateFailure(errorCode, true);
+    const retry = wireRetriable && shape.category !== 'parked' ? { offer: true, basis: 'wire' } : { offer: shape.offer, basis: 'category' };
+    const waitSec = waitSecOf(err);
+    const chain = turnFailureNotesOf(err, verdict, notesCtx, waitSec, lang);
+    const headline = headlineKey !== undefined ? renderMessage(msg(headlineKey), lang) : undefined;
+    return Object.freeze({
+        category: shape.category,
+        kind: verdict.kind,
+        ...(status !== undefined ? { status } : {}),
+        ...(errorCode !== undefined ? { errorCode } : {}),
+        detail,
+        ...(headline !== undefined ? { headline } : {}),
+        ...(name !== undefined ? { name } : {}),
+        retry: Object.freeze(retry),
+        ...(waitSec !== undefined ? { waitSec } : {}),
+        notes: chain.notes,
+        ...(chain.waitNote !== undefined ? { waitNote: chain.waitNote } : {}),
+    });
+}
+function quotaDetailOf(err) {
+    if (readThrownSlot(err, 'status', 'data') !== 429 || readThrownSlot(err, 'errorCode', 'data') !== 'quota_exhausted')
+        return null;
+    const detail = readThrownSlot(err, 'detail', 'data');
+    const slot = (key) => (typeof detail === 'object' && detail !== null ? readThrownSlot(detail, key, 'data') : undefined);
+    const windowType = slot('windowType');
+    const remaining = slot('remaining');
+    const resetAt = slot('resetAt');
+    const isEstimate = slot('isEstimate');
+    const pool = slot('pool');
+    return {
+        ...(windowType === 'fiveHour' || windowType === 'weekly' || windowType === 'budget' ? { windowType } : {}),
+        ...(typeof remaining === 'number' && Number.isFinite(remaining) ? { remaining } : {}),
+        ...(typeof resetAt === 'string' || resetAt === null ? { resetAt } : {}),
+        ...(typeof isEstimate === 'boolean' ? { isEstimate } : {}),
+        ...(typeof pool === 'string' && pool.length > 0 ? { pool } : {}),
+    };
+}
+const MONTH_KEYS = [
+    'notice.failure.month.jan',
+    'notice.failure.month.feb',
+    'notice.failure.month.mar',
+    'notice.failure.month.apr',
+    'notice.failure.month.may',
+    'notice.failure.month.jun',
+    'notice.failure.month.jul',
+    'notice.failure.month.aug',
+    'notice.failure.month.sep',
+    'notice.failure.month.oct',
+    'notice.failure.month.nov',
+    'notice.failure.month.dec',
+];
+function quotaResetInstant(resetAtIso, nowMs, lang) {
+    const t = Date.parse(resetAtIso);
+    if (!Number.isFinite(t))
+        return undefined;
+    const d = new Date(t);
+    const now = new Date(nowMs);
+    const hm = `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`;
+    const sameDay = d.getFullYear() === now.getFullYear() && d.getMonth() === now.getMonth() && d.getDate() === now.getDate();
+    if (sameDay)
+        return hm;
+    const monthKey = MONTH_KEYS[d.getMonth()];
+    return renderMessage(msg('notice.failure.quota.instantOtherDay', { month: monthKey === undefined ? '' : msg(monthKey), day: d.getDate(), time: hm }), lang);
+}
+function quotaExhaustedLine(detail, nowMs, lang) {
+    const part = (key, params) => renderMessage(msg(key, params), lang);
+    const parts = [];
+    if (detail.windowType === 'fiveHour')
+        parts.push(part('notice.failure.quota.fiveHour'));
+    else if (detail.windowType === 'weekly')
+        parts.push(part('notice.failure.quota.weekly'));
+    else if (detail.windowType === 'budget') {
+        if (detail.pool === 'personal')
+            parts.push(part('notice.failure.quota.budgetPersonal'));
+        else if (detail.pool)
+            parts.push(part('notice.failure.quota.budgetPool', { pool: detail.pool }));
+        else
+            parts.push(part('notice.failure.quota.budget'));
+    }
+    else
+        parts.push(part('notice.failure.quota.usage'));
+    if (typeof detail.remaining === 'number' && Number.isFinite(detail.remaining)) {
+        parts.push(detail.windowType === 'budget'
+            ? part('notice.failure.quota.remainingBudget', { amount: `$${(detail.remaining / 1_000_000).toFixed(2)}` })
+            : part('notice.failure.quota.remainingTokens', { count: detail.remaining.toLocaleString('en-US') }));
+    }
+    const resetText = typeof detail.resetAt === 'string' ? quotaResetInstant(detail.resetAt, nowMs, lang) : undefined;
+    if (resetText)
+        parts.push(detail.isEstimate === false ? part('notice.failure.quota.resetAt', { time: resetText }) : part('notice.failure.quota.resetAround', { time: resetText }));
+    parts.push(part('notice.failure.quota.refresh'));
+    parts.push(part('notice.failure.quota.noBypass'));
+    return parts.join(part('notice.failure.quota.join'));
+}
+function protectiveSettingsAtRisk(sent, lang) {
+    const out = [];
+    const permsRaw = sent.permissions;
+    const perms = typeof permsRaw === 'object' && permsRaw !== null ? permsRaw : {};
+    const deny = Array.isArray(perms.deny) ? perms.deny.length : 0;
+    const ask = Array.isArray(perms.ask) ? perms.ask.length : 0;
+    if (deny > 0)
+        out.push(renderMessage(msg(deny === 1 ? 'notice.failure.settings.denyRules.one' : 'notice.failure.settings.denyRules.other', { count: deny }), lang));
+    if (ask > 0)
+        out.push(renderMessage(msg(ask === 1 ? 'notice.failure.settings.askRules.one' : 'notice.failure.settings.askRules.other', { count: ask }), lang));
+    if (perms.disableBypassPermissionsMode !== undefined)
+        out.push('permissions.disableBypassPermissionsMode');
+    if (perms.disableAutoMode !== undefined)
+        out.push('permissions.disableAutoMode');
+    if (typeof perms.defaultMode === 'string')
+        out.push('permissions.defaultMode');
+    return out;
+}
+function settingsBodyShapeNote(err, sentRequest, lang) {
+    if (readThrownSlot(err, 'status', 'data') !== 400 || readThrownSlot(err, 'errorCode', 'data') !== 'request.body_shape')
+        return undefined;
+    const touches = bodyShapeRefusalTouchesSettings(bodyShapeRefusalFromError(err), sentRequest);
+    if (touches === false)
+        return undefined;
+    const rawSettings = sentRequest === undefined ? undefined : readThrownSlot(sentRequest, 'settings', 'data');
+    if (typeof rawSettings !== 'object' || rawSettings === null || Array.isArray(rawSettings))
+        return undefined;
+    const sentSettings = rawSettings;
+    if (Object.keys(sentSettings).length === 0)
+        return undefined;
+    const lines = [renderMessage(msg('notice.failure.settings.lead'), lang)];
+    const atRisk = protectiveSettingsAtRisk(sentSettings, lang);
+    if (atRisk.length > 0) {
+        lines.push(renderMessage(msg('notice.failure.settings.safety', { risks: atRisk.join(renderMessage(msg('notice.failure.settings.riskJoin'), lang)) }), lang));
+        lines.push(renderMessage(msg('notice.failure.settings.stillLocal'), lang));
+    }
+    return lines.join('\n');
+}
+function isRefusedRequest(err) {
+    const status = readThrownSlot(err, 'status', 'data');
+    return typeof status === 'number' && status >= 400 && status < 500;
+}
+function waitSentence(sec, lang) {
+    return renderMessage(sec === 1 ? msg('notice.failure.wait.one') : msg('notice.failure.wait.other', { seconds: sec }), lang);
+}
+function turnFailureNotesOf(err, verdict, ctx, waitSec, lang) {
+    const lines = [];
+    try {
+        const sentRequest = ctx === undefined ? undefined : ctx.sentRequest;
+        const nowMs = ctx !== undefined && typeof ctx.nowMs === 'number' && Number.isFinite(ctx.nowMs) ? ctx.nowMs : Date.now();
+        const quota = quotaDetailOf(err);
+        if (quota)
+            lines.push(quotaExhaustedLine(quota, nowMs, lang));
+        const scenarioDeny = quota ? null : scenarioDenyFromError(err);
+        if (scenarioDeny)
+            lines.push(scenarioNotAllowedContent(scenarioDeny, ctx?.requestedScenario));
+        const resumeRefusal = quota || scenarioDeny ? null : resumeRefusalFromError(err);
+        if (resumeRefusal)
+            lines.push(resumeRefusalContent(resumeRefusal, lang));
+        const requireExisting = quota || scenarioDeny || resumeRefusal ? null : requireExistingSessionRefusalFromError(err);
+        if (requireExisting)
+            lines.push(requireExistingSessionRefusalContent(requireExisting, lang));
+        const resumeReopen = quota || scenarioDeny || resumeRefusal || requireExisting ? null : resumeReopenFromError(err);
+        if (resumeReopen)
+            lines.push(resumeReopenContent(resumeReopen, lang));
+        const resumeGone = quota || scenarioDeny || resumeRefusal || requireExisting || resumeReopen ? null : resumeContextUnavailableFromError(err);
+        if (resumeGone)
+            lines.push(resumeContextUnavailableContent(resumeGone, lang));
+        const checkpointUnsupported = quota || scenarioDeny || resumeRefusal || requireExisting || resumeReopen || resumeGone ? null : checkpointUnsupportedVersionFromError(err);
+        if (checkpointUnsupported)
+            lines.push(checkpointUnsupportedVersionContent(checkpointUnsupported, undefined, lang));
+        const storedRowWhere = quota || scenarioDeny || resumeRefusal || resumeReopen || resumeGone ? undefined : verdict.kind === 'http' ? verdict.storedRowWhere : undefined;
+        if (storedRowWhere !== undefined)
+            lines.push(corruptStoredRowContent(storedRowWhere));
+        if (storedRowWhere === undefined && isCorruptSessionError(err))
+            lines.push(corruptSessionContent(lang));
+        const usageWindow = quota || scenarioDeny || resumeRefusal || resumeReopen || resumeGone ? null : usageWindowExhaustedFromError(err);
+        if (usageWindow)
+            lines.push(usageWindowExhaustedContent(usageWindow));
+        const hostPosture = quota || scenarioDeny || resumeRefusal || resumeReopen || resumeGone || storedRowWhere !== undefined ? null : hostPostureRefusalFromError(err, sentRequest);
+        if (hostPosture)
+            lines.push(hostPostureRefusalContent(hostPosture));
+        const inheritEnv = hostPosture ? null : inheritEnvRefusalFromError(err, sentRequest);
+        if (inheritEnv)
+            lines.push(inheritEnvRefusalContent(inheritEnv, lang));
+        const bucket = inheritEnv ? null : settingsPermissionBucketRefusalFromError(err);
+        const toolDecl = toolDeclarationRefusalFromError(err);
+        if (toolDecl)
+            lines.push(toolDeclarationRefusalContent(toolDecl));
+        const lease = fleetLeaseUnavailableFromError(err);
+        if (lease)
+            lines.push(fleetLeaseUnavailableContent(lease));
+        const policyBlock = quota || scenarioDeny || resumeRefusal || resumeReopen || resumeGone || usageWindow || hostPosture ? null : resumePolicyBlockFromError(err);
+        if (policyBlock)
+            lines.push(resumePolicyBlockContent(policyBlock, lang));
+        if (bucket)
+            lines.push(settingsPermissionBucketRefusalContent(bucket));
+        const settingsRefusal = settingsBodyShapeNote(err, sentRequest, lang);
+        if (settingsRefusal !== undefined)
+            lines.push(settingsRefusal);
+        if (isRefusedRequest(err) && ctx !== undefined && ctx.modelCatalog !== undefined) {
+            const rejected = modelCandidateRejectedContent(modelCandidateRejectedOf(ctx.modelCatalog), lang);
+            if (rejected !== undefined)
+                lines.push(rejected);
+        }
+        return Object.freeze({ notes: Object.freeze(lines), ...(waitSec !== undefined && !lease && !usageWindow ? { waitNote: waitSentence(waitSec, lang) } : {}) });
+    }
+    catch {
+        return Object.freeze({ notes: Object.freeze(lines) });
+    }
+}
+export function seatTurnFailureOf(err, evidence) {
+    const p = turnFailurePresentation(err, evidence);
+    return {
+        category: p.category,
+        retry: { offer: p.retry.offer, basis: p.retry.basis },
+        ...(p.waitSec !== undefined ? { waitSec: p.waitSec } : {}),
+        ...(p.headline !== undefined ? { headline: p.headline } : {}),
+        ...(p.errorCode !== undefined ? { errorCode: p.errorCode } : {}),
+    };
+}
+function seatDataField(o, key) {
+    const v = readThrownSlot(o, key, 'data');
+    return v === THROWN_SLOT_UNREADABLE ? SEAT_UNREADABLE : v;
+}
+const SEAT_UNREADABLE = Symbol('seat-unreadable');
+export function readSeatTurnFailure(event) {
+    try {
+        return seatTurnFailureShapeOf(event);
+    }
+    catch {
+        return undefined;
+    }
+}
+function seatTurnFailureShapeOf(event) {
+    if (event === null || event === undefined || typeof event !== 'object' || Array.isArray(event))
+        return undefined;
+    if (seatDataField(event, 'type') !== 'error')
+        return undefined;
+    const raw = seatDataField(event, '_sema_turnFailure');
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const category = seatDataField(raw, 'category');
+    if (!TURN_FAILURE_CATEGORIES.includes(category))
+        return undefined;
+    const retry = seatDataField(raw, 'retry');
+    if (retry === null || typeof retry !== 'object' || Array.isArray(retry))
+        return undefined;
+    const offer = seatDataField(retry, 'offer');
+    const basis = seatDataField(retry, 'basis');
+    if (typeof offer !== 'boolean' || (basis !== 'wire' && basis !== 'category'))
+        return undefined;
+    const waitSec = seatDataField(raw, 'waitSec');
+    if (waitSec !== undefined && !(typeof waitSec === 'number' && Number.isInteger(waitSec) && waitSec >= 1))
+        return undefined;
+    const headline = seatDataField(raw, 'headline');
+    if (headline !== undefined && !(typeof headline === 'string' && headline.length > 0))
+        return undefined;
+    const errorCode = seatDataField(raw, 'errorCode');
+    if (errorCode !== undefined && !(typeof errorCode === 'string' && errorCode.length > 0))
+        return undefined;
+    return Object.freeze({
+        category: category,
+        retry: Object.freeze({ offer, basis }),
+        ...(waitSec !== undefined ? { waitSec } : {}),
+        ...(headline !== undefined ? { headline } : {}),
+        ...(errorCode !== undefined ? { errorCode } : {}),
+    });
+}

package/dist/usageAnalytics.js

@@ -1,3 +1,4 @@
+import { readThrownSlot, THROWN_SLOT_UNREADABLE } from './wireFailureShape.js';
 export const USAGE_SENTENCES = Object.freeze({
     analyticsUnavailable: 'Usage analytics aren’t available on this backend.',
     analyticsUnread: 'Usage analytics couldn’t be read just now.',
@@ -10,18 +11,12 @@ 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 {
+    const rawCode = readThrownSlot(e, 'errorCode', 'data');
+    const rawStatus = readThrownSlot(e, 'status', 'data');
+    if (rawCode === THROWN_SLOT_UNREADABLE || rawStatus === THROWN_SLOT_UNREADABLE)
         return { kind: 'failed', error: e };
-    }
+    const code = typeof rawCode === 'string' ? rawCode : undefined;
+    const status = typeof rawStatus === 'number' ? rawStatus : undefined;
     if (code !== undefined) {
         if (code.startsWith('capability.'))
             return { kind: 'unavailable', why: 'capability' };

package/dist/userAttachmentEnvelope.d.ts

@@ -78,5 +78,6 @@ export type UserAttachmentDescriptor = {
 };
 export declare function showAttachmentName(s: string): string;
 export declare function mintEnvelopeOf(d: DescriptorView, imageDelivery: 'attached' | 'not-attached'): string;
+export declare function seatTextOf(d: DescriptorView): string | undefined;
 export declare function mintReferenceOf(d: DescriptorView): string;
 export declare function mintUserAttachmentEnvelope(descriptor: UserAttachmentDescriptor): string;

package/dist/userAttachmentEnvelope.js

@@ -83,11 +83,7 @@ function mintText(d) {
         : `Full path: ${path} (lines ${d.startLine}–${d.startLine + n - 1} of ${d.totalLines}; the other lines are not included). The client read it from disk and copied those lines between the two fence lines below. ${dataNote(d.source, "the file's contents")}`;
     return fenced(anyEscaped ? [l1, l2, ESCAPE_NOTE] : [l1, l2], body);
 }
-function mintNotebook(d) {
-    const path = showAttachmentName(d.path);
-    const l1 = firstLine(d.source, 'a Jupyter notebook', d.name);
-    if (d.cells.length === 0)
-        return `${l1}\nFull path: ${path} (0 cells). The client read it from disk; it has no cells.`;
+function notebookBody(d) {
     let cellsWithImages = 0;
     let cellsWithOversized = 0;
     const parts = [];
@@ -113,9 +109,16 @@ function mintNotebook(d) {
         if (hasImage)
             cellsWithImages++;
     }
+    return { text: parts.join('\n'), cellsWithImages, cellsWithOversized };
+}
+function mintNotebook(d) {
+    const path = showAttachmentName(d.path);
+    const l1 = firstLine(d.source, 'a Jupyter notebook', d.name);
+    if (d.cells.length === 0)
+        return `${l1}\nFull path: ${path} (0 cells). The client read it from disk; it has no cells.`;
+    const { text, cellsWithImages, cellsWithOversized } = notebookBody(d);
     let anyEscaped = false;
-    const body = parts
-        .join('\n')
+    const body = text
         .split('\n')
         .map((line, i) => {
         const shown = showBodyLine(line);
@@ -281,6 +284,33 @@ function referenceSentence(d) {
     }
     return `The user mentioned the ${what} ${name} (${path}) in this message; its contents are not included here.`;
 }
+export function seatTextOf(d) {
+    let text;
+    switch (d.kind) {
+        case 'text':
+            if (d.source !== 'at-mention' || !d.complete || d.lines.length === 0)
+                return undefined;
+            text = d.lines.join('\n');
+            break;
+        case 'notebook': {
+            if (d.source !== 'at-mention' || d.cells.length === 0)
+                return undefined;
+            const body = notebookBody(d);
+            if (body.cellsWithImages > 0 || body.cellsWithOversized > 0)
+                return undefined;
+            text = body.text;
+            break;
+        }
+        case 'directory':
+            if (d.entries.length === 0 || d.totalEntries > d.entries.length)
+                return undefined;
+            text = d.entries.map(showAttachmentName).join('\n');
+            break;
+        default:
+            return undefined;
+    }
+    return text.length > 0 ? text : undefined;
+}
 export function mintReferenceOf(d) {
     return `${TAG_OPEN}${tagAttributes(d)} />\n${referenceSentence(d)}`;
 }

package/dist/userAttachmentSeat.d.ts

@@ -0,0 +1,21 @@
+export interface UserAttachmentSeatLimits {
+    readonly maxEntries: number;
+    readonly maxRenderedTextChars: number;
+}
+export interface UserAttachmentSeatPresent {
+    readonly kind: 'present';
+    readonly entries: readonly string[];
+    readonly kinds: readonly string[];
+    readonly supplies: readonly string[];
+    readonly limits: UserAttachmentSeatLimits;
+}
+export type UserAttachmentSeatReading = {
+    kind: 'unobserved';
+} | {
+    kind: 'unreadable';
+} | {
+    kind: 'not_reported';
+} | UserAttachmentSeatPresent;
+export declare function projectUserAttachmentSeatCapability(caps: {} | null | undefined): UserAttachmentSeatReading | undefined;
+export declare function observedUserAttachmentSeat(baseUrl?: string | undefined): UserAttachmentSeatReading;
+export declare function userAttachmentSeatAdmits(reading: UserAttachmentSeatReading | undefined): 'yes' | 'no' | 'unknown';

package/dist/userAttachmentSeat.js

@@ -0,0 +1,75 @@
+import { engineWireTarget } from './engineWireTarget.js';
+import { createEngineCapReader } from './engineCapReader.js';
+import { ownDataField, readOwnDataValue } from './ownKey.js';
+const _seatPin = [true, true];
+void _seatPin;
+function stringList(v) {
+    if (!Array.isArray(v))
+        return undefined;
+    const n = ownDataField(v, 'length');
+    if (typeof n !== 'number' || !Number.isSafeInteger(n) || n < 0)
+        return undefined;
+    const out = [];
+    for (let i = 0; i < n; i += 1) {
+        const d = Object.getOwnPropertyDescriptor(v, i);
+        if (d === undefined || !('value' in d) || typeof d.value !== 'string')
+            return undefined;
+        out.push(d.value);
+    }
+    return out;
+}
+const positiveInt = (v) => (typeof v === 'number' && Number.isSafeInteger(v) && v >= 1 ? v : undefined);
+const isPlainRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+export function projectUserAttachmentSeatCapability(caps) {
+    try {
+        if (!isPlainRecord(caps))
+            return undefined;
+        const seat = ownDataField(caps, 'userAttachments');
+        if (seat === undefined)
+            return { kind: 'not_reported' };
+        if (!isPlainRecord(seat))
+            return undefined;
+        const entries = stringList(ownDataField(seat, 'entries'));
+        const kinds = stringList(ownDataField(seat, 'kinds'));
+        const supplies = stringList(ownDataField(seat, 'supplies'));
+        const limits = ownDataField(seat, 'limits');
+        if (entries === undefined || kinds === undefined || supplies === undefined || !isPlainRecord(limits))
+            return undefined;
+        const maxEntries = positiveInt(ownDataField(limits, 'maxEntries'));
+        const maxRenderedTextChars = positiveInt(ownDataField(limits, 'maxRenderedTextChars'));
+        if (maxEntries === undefined || maxRenderedTextChars === undefined)
+            return undefined;
+        return { kind: 'present', entries, kinds, supplies, limits: { maxEntries, maxRenderedTextChars } };
+    }
+    catch {
+        return undefined;
+    }
+}
+const reader = createEngineCapReader({ name: 'userAttachments', project: projectUserAttachmentSeatCapability });
+export function observedUserAttachmentSeat(baseUrl = engineWireTarget()?.baseUrl) {
+    return reader.observed(baseUrl);
+}
+export function userAttachmentSeatAdmits(reading) {
+    try {
+        if (!isPlainRecord(reading))
+            return 'unknown';
+        const kind = readOwnDataValue(reading, 'kind');
+        if (kind === 'not_reported')
+            return 'no';
+        if (kind !== 'present')
+            return 'unknown';
+        const has = (key, word) => {
+            const list = stringList(readOwnDataValue(reading, key));
+            return list === undefined ? undefined : list.includes(word);
+        };
+        const objective = has('entries', 'objective');
+        const text = has('supplies', 'content_text');
+        const client = has('kinds', 'client_text');
+        if (objective === undefined || text === undefined || client === undefined)
+            return 'unknown';
+        return objective && text && client ? 'yes' : 'no';
+    }
+    catch {
+        return 'unknown';
+    }
+}

package/dist/userInvokedSkillsCapability.d.ts

@@ -1,3 +1,4 @@
+import type { UiLanguage } from './env/uiLanguage.js';
 export type UserInvokedSkillsReading = {
     kind: 'unobserved';
 } | {
@@ -10,9 +11,15 @@ export type UserInvokedSkillsReading = {
     kind: 'present';
 };
 export declare function projectUserInvokedSkillsCapability(caps: unknown): UserInvokedSkillsReading | undefined;
-export declare function noteEngineCapsForUserInvokedSkills(baseUrl: string, caps: unknown, opts?: {
-    generation?: number;
-}): void;
 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 userInvokedSkillsDoctorDetail(reading: UserInvokedSkillsReading, lang?: UiLanguage): string;
+export interface UserInvokedSkillsDeclaration {
+    readonly field: {
+        readonly userInvokedSkills?: readonly string[];
+    };
+    readonly withheld?: {
+        readonly cause: Exclude<UserInvokedSkillsReading['kind'], 'present'>;
+    };
+}
+export declare function userInvokedSkillsDeclaration(names: readonly string[] | null | undefined, reading: UserInvokedSkillsReading): UserInvokedSkillsDeclaration;