@sema-agent/client-core 0.98.0 → 0.100.0

package/dist/turnFailurePresentation.d.ts

@@ -1,4 +1,7 @@
+import type { UiLanguage } from './env/uiLanguage.js';
 import { type TurnWireErrorVerdict } from './wireErrorTriage.js';
+import { type LiveModelCatalog } from './liveModelCatalog.js';
+import type { TaskRequestLike } from './request/taskRequest.js';
 export type TurnFailureCategory = 'auth' | 'billing' | 'rate_limited' | 'invalid_request' | 'capability_unavailable' | 'timeout' | 'server_error' | 'connection_lost' | 'parked' | 'internal';
 export declare const TURN_FAILURE_CATEGORIES: readonly TurnFailureCategory[];
 export interface TurnFailureRetry {
@@ -15,11 +18,19 @@ export interface TurnFailurePresentation {
     readonly name?: string;
     readonly retry: TurnFailureRetry;
     readonly waitSec?: number;
+    readonly notes: readonly string[];
+    readonly waitNote?: string;
+}
+export interface TurnFailureNotesContext {
+    readonly requestedScenario?: string;
+    readonly sentRequest?: TaskRequestLike;
+    readonly modelCatalog?: LiveModelCatalog | null;
+    readonly nowMs?: number;
 }
 export declare function turnFailurePresentation(err: {} | null | undefined, evidence?: {
     readonly bound?: boolean;
     readonly reopened?: boolean;
-}): TurnFailurePresentation;
+}, notesCtx?: TurnFailureNotesContext, lang?: UiLanguage): TurnFailurePresentation;
 export type SeatTurnFailure = Pick<TurnFailurePresentation, 'category' | 'retry' | 'waitSec' | 'headline' | 'errorCode'>;
 export declare function seatTurnFailureOf(err: {} | null | undefined, evidence?: {
     readonly bound?: boolean;

package/dist/turnFailurePresentation.js

@@ -1,10 +1,19 @@
+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 { toolDeclarationRefusalFromError } from './wireRefusalCopy.js';
+import { admissionWallRefusalContent, admissionWallRefusalFromError, bodyShapeRefusalFromError, bodyShapeRefusalTouchesSettings, fleetLeaseUnavailableContent, fleetLeaseUnavailableFromError, hostPostureRefusalContent, hostPostureRefusalFromError, fieldLimitRefusalContent, fieldLimitRefusalFromError, toolDeclarationRefusalContent, toolDeclarationRefusalFromError, usageWindowExhaustedContent, usageWindowExhaustedFromError, userAttachmentRefusalFromError, } 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 { prepareRefusalCodeOf, prepareRefusalNoteOf } from './prepareRefusal.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,
@@ -18,12 +27,12 @@ const CATEGORY_TABLE = Object.freeze({
     internal: true,
 });
 export const TURN_FAILURE_CATEGORIES = Object.freeze(Object.keys(CATEGORY_TABLE));
-const TURN_FAILURE_HEADLINES = Object.freeze({
-    connection_lost_not_sent: 'The engine is unreachable — your message did not run. Check that the engine is up, then send it again.',
-    connection_lost: 'The connection to the engine was lost — it is not known whether your message ran. Check the run’s status, or reattach to it, before sending it again.',
-    timeout: 'The event stream went silent — the run may still be going on the engine. Check its status before sending again.',
-    parked: 'The event stream ended while the run had not reached a terminal state — the run is likely parked waiting for a decision, not crashed. Check its status and decide anything pending; the turn did not complete here.',
-    internal: 'This client hit an internal error — it is a bug in the client, not an engine outage, and the turn did not complete.',
+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');
@@ -88,43 +97,43 @@ function connectionLostBeforeSend(err, evidence) {
         return false;
     return typeof err === 'object' && err !== null && provablyNotSent(err);
 }
-export function turnFailurePresentation(err, evidence) {
+export function turnFailurePresentation(err, evidence, notesCtx, lang) {
     const verdict = classifyTurnWireError(err);
     let shape;
-    let headline;
+    let headlineKey;
     let detail;
     let name;
     if (verdict.kind === 'http') {
         shape = httpShapeOf(err, verdict);
         detail = verdict.message;
         if (shape.category === 'internal')
-            headline = TURN_FAILURE_HEADLINES.internal;
+            headlineKey = TURN_FAILURE_HEADLINE_KEYS.internal;
     }
     else if (verdict.kind === 'stream-ended-without-terminal') {
         shape = { category: 'parked', offer: false };
-        headline = TURN_FAILURE_HEADLINES.parked;
+        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 };
-        headline = notSent ? TURN_FAILURE_HEADLINES.connection_lost_not_sent : TURN_FAILURE_HEADLINES.connection_lost;
+        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 };
-        headline = TURN_FAILURE_HEADLINES.timeout;
+        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 };
-        headline = notSent ? TURN_FAILURE_HEADLINES.connection_lost_not_sent : TURN_FAILURE_HEADLINES.connection_lost;
+        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 };
-        headline = TURN_FAILURE_HEADLINES.internal;
+        headlineKey = TURN_FAILURE_HEADLINE_KEYS.internal;
         detail = verdict.detail;
         name = verdict.name;
     }
@@ -133,6 +142,8 @@ export function turnFailurePresentation(err, evidence) {
     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,
@@ -143,8 +154,202 @@ export function turnFailurePresentation(err, evidence) {
         ...(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, lang));
+        const hostPosture = quota || scenarioDeny || resumeRefusal || resumeReopen || resumeGone || storedRowWhere !== undefined ? null : hostPostureRefusalFromError(err, sentRequest);
+        if (hostPosture)
+            lines.push(hostPostureRefusalContent(hostPosture, lang));
+        const inheritEnv = hostPosture ? null : inheritEnvRefusalFromError(err, sentRequest);
+        if (inheritEnv)
+            lines.push(inheritEnvRefusalContent(inheritEnv, lang));
+        const bucket = inheritEnv ? null : fieldLimitRefusalFromError(err);
+        const toolDecl = toolDeclarationRefusalFromError(err);
+        if (toolDecl)
+            lines.push(toolDeclarationRefusalContent(toolDecl, lang));
+        const prepareCode = toolDecl ? undefined : prepareRefusalCodeOf(err);
+        const prepareNote = prepareCode === undefined ? undefined : prepareRefusalNoteOf(prepareCode, userAttachmentRefusalFromError(err) ?? undefined);
+        if (prepareNote !== undefined)
+            lines.push(prepareNote);
+        const wall = admissionWallRefusalFromError(err);
+        if (wall)
+            lines.push(admissionWallRefusalContent(wall));
+        const lease = fleetLeaseUnavailableFromError(err);
+        if (lease)
+            lines.push(fleetLeaseUnavailableContent(lease, lang));
+        const policyBlock = quota || scenarioDeny || resumeRefusal || resumeReopen || resumeGone || usageWindow || hostPosture ? null : resumePolicyBlockFromError(err);
+        if (policyBlock)
+            lines.push(resumePolicyBlockContent(policyBlock, lang));
+        if (bucket)
+            lines.push(fieldLimitRefusalContent(bucket, lang));
+        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 {

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';
 } | {
@@ -12,4 +13,13 @@ export type UserInvokedSkillsReading = {
 export declare function projectUserInvokedSkillsCapability(caps: unknown): UserInvokedSkillsReading | undefined;
 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;

package/dist/userInvokedSkillsCapability.js

@@ -1,6 +1,7 @@
 import { engineWireTarget } from './engineWireTarget.js';
 import { createEngineCapReader, unreadableReadingDetail } from './engineCapReader.js';
-import { ownDataField } from './ownKey.js';
+import { msg, renderMessage } from './i18n/translate.js';
+import { ownDataField, readOwnDataValue } from './ownKey.js';
 export function projectUserInvokedSkillsCapability(caps) {
     try {
         if (caps === null || typeof caps !== 'object' || Array.isArray(caps))
@@ -30,17 +31,40 @@ export function userInvokedSkillsAvailable(reading) {
         return 'no';
     return 'unknown';
 }
-export function userInvokedSkillsDoctorDetail(reading) {
+export function userInvokedSkillsDoctorDetail(reading, lang) {
+    const subject = msg('notice.capability.subject.userInvokedSkills');
     switch (reading.kind) {
         case 'unreadable':
-            return unreadableReadingDetail('user-invoked skills');
+            return unreadableReadingDetail(renderMessage(subject, lang), lang);
         case 'unobserved':
-            return 'user-invoked skills not observed — the engine reports it on /v1/capabilities (userInvokedSkills); this process has no usable capabilities reading cached for it (none received, the last one was unreadable, or the last one was discarded when the engine connection was reset; this process cannot tell which)';
+            return renderMessage(msg('notice.capability.unobserved', { subject, key: 'userInvokedSkills' }), lang);
         case 'not_reported':
-            return 'user-invoked skills not reported by this engine — the engine predates it, so naming skills on a request is refused (do not send the key)';
+            return renderMessage(msg('notice.capability.userInvokedSkills.notReported'), lang);
         case 'absent':
-            return 'user-invoked skills off on this deployment — naming skills on a request is not accepted';
+            return renderMessage(msg('notice.capability.userInvokedSkills.absent'), lang);
         case 'present':
-            return 'user-invoked skills on — skills the user names on a request take effect when the run starts';
+            return renderMessage(msg('notice.capability.userInvokedSkills.present'), lang);
     }
 }
+export function userInvokedSkillsDeclaration(names, reading) {
+    let named = false;
+    try {
+        named = Array.isArray(names) && names.length > 0;
+    }
+    catch {
+        named = false;
+    }
+    if (!named)
+        return { field: {} };
+    let kind;
+    try {
+        kind = reading !== null && typeof reading === 'object' ? readOwnDataValue(reading, 'kind') : undefined;
+    }
+    catch {
+        kind = undefined;
+    }
+    if (kind === 'present')
+        return { field: { userInvokedSkills: names } };
+    const cause = kind === 'absent' || kind === 'not_reported' || kind === 'unobserved' ? kind : 'unreadable';
+    return { field: {}, withheld: { cause } };
+}

package/dist/wireErrorTriage.d.ts

@@ -21,6 +21,13 @@ export declare function classifyTurnWireError(err: unknown): TurnWireErrorVerdic
 export declare function isWireTransportError(err: unknown): boolean;
 export declare function isPreStreamDrainingReject(err: unknown): boolean;
 export declare function effectiveWireErrorCode(err: unknown): string | undefined;
+export type NotFoundFailure = {
+    readonly kind: 'not_found';
+    readonly code: string;
+} | {
+    readonly kind: 'unknown_404';
+};
+export declare function isNotFoundFailure(e: {} | null | undefined): NotFoundFailure | false;
 export declare function corruptStoredRowWhere(err: unknown): string | undefined;
 export declare function corruptStoredRowContent(where: string): string;
 export declare function isResumeAtRejection(err: unknown): boolean;