@sema-agent/client-core 0.90.0 → 0.92.0

package/dist/attachmentsWireCaps.js

@@ -1,6 +1,6 @@
 import { hostEnv } from './hostEnv.js';
 import { envFlagOff } from './envFlag.js';
-import { retiredAttachmentsKeyWhy } from './taskRequestWords.js';
+import { retiredAttachmentsKeyOf } from './taskRequestWords.js';
 export const ATTACHMENTS_ENV = 'SEMA_ATTACHMENTS';
 export const ATTACHMENTS_SPEC_KEYS = Object.freeze([
     'todoReminder',
@@ -48,25 +48,27 @@ function refuse(token, why) {
     const allowed = legalAttachmentsTokens();
     throw new AttachmentsSpecRefused(`${ATTACHMENTS_ENV}: refusing token "${token}" — ${why}. Legal tokens: ${allowed.join(' | ')}`, { token, why, allowed });
 }
-export function attachmentsForRequest(env = hostEnv()) {
-    const raw = (env[ATTACHMENTS_ENV] ?? '').trim().toLowerCase();
+function deny(kind, token, why, index, key) {
+    return { ok: false, refusal: { kind, token, why, entry: index + 1, key } };
+}
+function judgeAttachmentsEnv(raw) {
     if (envFlagOff(raw))
-        return allDefaultOnOff();
+        return { ok: true, spec: allDefaultOnOff() };
     const tokens = raw.split(',').map(t => t.trim()).filter(t => t.length > 0);
-    for (const token of tokens) {
-        const named = retiredAttachmentsKeyWhy(token);
+    for (const [i, token] of tokens.entries()) {
+        const named = retiredAttachmentsKeyOf(token);
         if (named !== undefined)
-            refuse(token, named);
+            return { ok: false, refusal: { kind: 'retired_key', token, why: named.why, entry: i + 1, key: named.key, retired: named } };
     }
     if (tokens.length === 0)
-        return { backgroundTasks: true, toolsDelta: true };
+        return { ok: true, spec: { backgroundTasks: true, toolsDelta: true } };
     if (tokens.length === 1 && (tokens[0] === 'full' || tokens[0] === 'all'))
-        return allLiteralTrue();
+        return { ok: true, spec: allLiteralTrue() };
     if (tokens.length === 1 && !isKnownToken(tokens[0])) {
-        return { backgroundTasks: true, toolsDelta: true };
+        return { ok: true, spec: { backgroundTasks: true, toolsDelta: true } };
     }
     const spec = {};
-    for (const token of tokens) {
+    for (const [i, token] of tokens.entries()) {
         if (token === 'full' || token === 'all') {
             Object.assign(spec, allLiteralTrue());
             continue;
@@ -79,11 +81,11 @@ export function attachmentsForRequest(env = hostEnv()) {
         if (token.startsWith('-')) {
             const key = canonicalKey(token.slice(1));
             if (key === undefined)
-                refuse(token, 'unknown attachments key');
+                return deny('unknown_key', token, 'unknown attachments key', i, undefined);
             if (!isDefaultOnKey(key)) {
-                refuse(token, `"${key}" belongs to the literal-true family whose OFF is "delete the key", not "send false" ` +
+                return deny('minus_on_literal_true_key', token, `"${key}" belongs to the literal-true family whose OFF is "delete the key", not "send false" ` +
                     '(core wire contract, board [479] ask-2) — simply do not turn it on. ' +
-                    `Only the core DEFAULT-ON keys (${ATTACHMENTS_DEFAULT_ON_KEYS.join(' / ')}) accept an explicit false`);
+                    `Only the core DEFAULT-ON keys (${ATTACHMENTS_DEFAULT_ON_KEYS.join(' / ')}) accept an explicit false`, i, key);
             }
             spec[key] = false;
             continue;
@@ -91,25 +93,76 @@ export function attachmentsForRequest(env = hostEnv()) {
         const [lhs, rhs] = splitAssign(token);
         if (rhs !== undefined) {
             if (canonicalKey(lhs) !== 'todoReminderMode')
-                refuse(token, 'only `todoReminderMode` takes a `key=value` form');
+                return deny('value_form_on_other_key', token, 'only `todoReminderMode` takes a `key=value` form', i, canonicalKey(lhs));
             const mode = TODO_REMINDER_MODES.find(v => v === rhs);
             if (mode === undefined)
-                refuse(token, `todoReminderMode must be one of ${TODO_REMINDER_MODES.join('|')}`);
+                return deny('todo_mode_bad_value', token, `todoReminderMode must be one of ${TODO_REMINDER_MODES.join('|')}`, i, 'todoReminderMode');
             spec.todoReminderMode = mode;
             continue;
         }
         const key = canonicalKey(lhs.startsWith('+') ? lhs.slice(1) : lhs);
         if (key === undefined)
-            refuse(token, 'unknown attachments key');
+            return deny('unknown_key', token, 'unknown attachments key', i, undefined);
         if (isDefaultOnOnlyKey(key)) {
-            refuse(token, `"${key}" is core DEFAULT-ON — turning it "on" is a no-op that would send a redundant true; ` +
-                `use "-${key}" to turn it OFF`);
+            return deny('plus_on_default_on_key', token, `"${key}" is core DEFAULT-ON — turning it "on" is a no-op that would send a redundant true; ` + `use "-${key}" to turn it OFF`, i, key);
         }
         if (key === 'todoReminderMode')
-            refuse(token, 'todoReminderMode needs a value: `todoReminderMode=baseline|off`');
+            return deny('todo_mode_needs_value', token, 'todoReminderMode needs a value: `todoReminderMode=baseline|off`', i, key);
         spec[key] = true;
     }
-    return spec;
+    return { ok: true, spec };
+}
+function envRawOf(env) {
+    return (env[ATTACHMENTS_ENV] ?? '').trim().toLowerCase();
+}
+export function attachmentsForRequest(env = hostEnv()) {
+    const judged = judgeAttachmentsEnv(envRawOf(env));
+    if (!judged.ok)
+        return refuse(judged.refusal.token, judged.refusal.why);
+    return judged.spec;
+}
+function attachmentsWayOut() {
+    const on = OPT_IN_KEYS.join(', ');
+    const off = ATTACHMENTS_DEFAULT_ON_KEYS.join(', ');
+    return (`Accepted writing is either the single word off on its own (every attachment off; it cannot be combined with other entries), or a comma-separated list of: ` +
+        `full or all (every opt-in attachment on), default, the name of an attachment to turn on (${on}), a leading minus to turn off one of ${off}, and todoReminderMode=${TODO_REMINDER_MODES.join(' or todoReminderMode=')}. ` +
+        `To drop the setting altogether, unset ${ATTACHMENTS_ENV}; the defaults then apply.`);
+}
+function attachmentsRefusalSentence(r) {
+    const head = `The attachments setting (${ATTACHMENTS_ENV}) cannot be used as it is set: entry ${r.entry} of the list`;
+    const key = r.key ?? '';
+    switch (r.kind) {
+        case 'retired_key':
+            return `${head} names "${key}", a key that no longer exists — ${r.retired?.because ?? 'it was retired'}, and a request carrying that key is refused by the server. Remove that entry${r.retired === undefined ? '' : `; ${r.retired.remedy}`}. ${attachmentsWayOut()}`;
+        case 'unknown_key':
+            return `${head} is not an attachment this version knows. ${attachmentsWayOut()}`;
+        case 'minus_on_literal_true_key':
+            return key === 'todoReminderMode'
+                ? `${head} puts a minus on todoReminderMode, which is a setting with a value rather than something to turn off — write todoReminderMode=${TODO_REMINDER_MODES.join(' or todoReminderMode=')}, or leave it out of the list. A minus only works on ${ATTACHMENTS_DEFAULT_ON_KEYS.join(', ')}, which are on by default. ${attachmentsWayOut()}`
+                : `${head} puts a minus on ${key}, and a minus cannot switch that attachment off — it is on only when it is named, or when full, all or default switches it on. A minus only works on ${ATTACHMENTS_DEFAULT_ON_KEYS.join(', ')}, which are on by default. To leave ${key} out, do not name it, and if full, all or default is what switches it on, list the attachments you want one by one instead. ${attachmentsWayOut()}`;
+        case 'plus_on_default_on_key':
+            return `${head} turns on ${key}, which is already on by default. To turn it off write -${key}; otherwise leave it out of the list. ${attachmentsWayOut()}`;
+        case 'value_form_on_other_key':
+            return `${head} uses a name=value form, and only todoReminderMode takes one. ${attachmentsWayOut()}`;
+        case 'todo_mode_bad_value':
+            return `${head} gives todoReminderMode a value it does not accept; the values are ${TODO_REMINDER_MODES.join(' and ')}. ${attachmentsWayOut()}`;
+        case 'todo_mode_needs_value':
+            return `${head} names todoReminderMode without a value; write todoReminderMode=${TODO_REMINDER_MODES.join(' or todoReminderMode=')}. ${attachmentsWayOut()}`;
+    }
+}
+function attachmentsUnreadableSentence() {
+    return `The attachments setting (${ATTACHMENTS_ENV}) could not be read as text, so it cannot be used as it is set. Set it to a plain comma-separated list, or unset it. ${attachmentsWayOut()}`;
+}
+export function attachmentsSubmitVerdict(env = hostEnv()) {
+    try {
+        const judged = judgeAttachmentsEnv(envRawOf(env));
+        if (judged.ok)
+            return { ok: true, attachments: judged.spec };
+        return { ok: false, sentence: attachmentsRefusalSentence(judged.refusal), refusedKey: judged.refusal.key };
+    }
+    catch {
+        return { ok: false, sentence: attachmentsUnreadableSentence(), refusedKey: undefined };
+    }
 }
 function allDefaultOnOff() {
     const out = {};

package/dist/autoModeUnavailable.js

@@ -1,4 +1,5 @@
-export const CLASSIFIER_DENY_CAUSES = Object.freeze(['unavailable', 'parse_error']);
+import { CORE_AUTO_MODE_UNAVAILABLE_CAUSES, CORE_CLASSIFIER_DENY_CAUSES } from './generated/engineFactTables.js';
+export const CLASSIFIER_DENY_CAUSES = CORE_CLASSIFIER_DENY_CAUSES;
 const DENY_CAUSE_SET = new Set(CLASSIFIER_DENY_CAUSES);
 export function isClassifierDenyCause(v) {
     return typeof v === 'string' && DENY_CAUSE_SET.has(v);
@@ -26,7 +27,7 @@ function gateRecordOf(v) {
         return undefined;
     return g;
 }
-export const AUTO_MODE_UNAVAILABLE_CAUSES = Object.freeze(['error', 'timeout']);
+export const AUTO_MODE_UNAVAILABLE_CAUSES = CORE_AUTO_MODE_UNAVAILABLE_CAUSES;
 const DENY_CAUSE_SENTENCES = Object.freeze({
     unavailable: 'denied because the auto-mode classifier could not run this round (the call may be retried later)',
     parse_error: 'denied because the auto-mode classifier answered outside its contract (its reply could not be parsed, so the call was blocked)',

package/dist/cloudConfigWireCaps.js

@@ -1,6 +1,7 @@
 import { MCP_CAPS } from './mcpWireCaps.js';
 import { toCappedSpec } from './skillsWireCaps.js';
 import { TIER_ORDER } from './model/tierVocabulary.js';
+import { SETTINGS_BUDGET_NUMBER_KEYS, SETTINGS_BUDGET_PER_MODEL_NUMBER_KEYS, SETTINGS_BUDGET_STRING_KEYS, SETTINGS_TIER_GROUP_NAME_RE, } from './generated/settingsSchemaTables.js';
 const asRec = (v) => (typeof v === 'object' && v !== null && !Array.isArray(v) ? v : undefined);
 const asArr = (v) => (Array.isArray(v) ? v : []);
 const asStr = (v) => (typeof v === 'string' && v.length > 0 ? v : undefined);
@@ -129,7 +130,7 @@ function withoutRegistryAnnotations(e) {
     return out;
 }
 const TIER_WORDS = TIER_ORDER;
-const TIER_GROUP_NAME = /^[a-z0-9][a-z0-9._-]*$/i;
+const TIER_GROUP_NAME = SETTINGS_TIER_GROUP_NAME_RE;
 const setOwn = (o, k, v) => {
     Object.defineProperty(o, k, { value: v, enumerable: true, writable: true, configurable: true });
 };
@@ -319,9 +320,9 @@ export function cloudRosterNames(rostersValue) {
         .map((e) => asStr(asRec(e)?.name))
         .filter((n) => !!n);
 }
-const BUDGET_NUMBER_KEYS = ['maxBudgetUsd', 'tpmLimit', 'rpmLimit', 'maxParallelRequests', 'maxRunCostUsd', 'maxIterations'];
-const BUDGET_STRING_KEYS = ['mode', 'budgetDuration', 'enforcement'];
-const PER_MODEL_NUMBER_KEYS = ['maxBudgetUsd', 'tpmLimit', 'rpmLimit'];
+const BUDGET_NUMBER_KEYS = SETTINGS_BUDGET_NUMBER_KEYS;
+const BUDGET_STRING_KEYS = SETTINGS_BUDGET_STRING_KEYS;
+const PER_MODEL_NUMBER_KEYS = SETTINGS_BUDGET_PER_MODEL_NUMBER_KEYS;
 const _budgetKeysCovered = true;
 const _budgetKeysReal = true;
 const _perModelKeysCovered = true;

package/dist/compensations.js

@@ -2,13 +2,12 @@ import { CHROME_ARMS } from './seam.js';
 export const MIGRATED_COMPENSATIONS = [
     {
         id: 'T32',
-        what: 'bindTaskCard —— 把引擎子代行绑到它的委派工具卡上(显式父 / FIFO 猜父 / 含糊即 unbound)',
+        what: 'bindTaskCard —— 子代行按 typed 父键绑到委派工具卡上(点名的卡不合格 / 父键缺席即 unbound)',
         disposition: 'in-library',
         libraryHalf: 'adapt.ts bindTaskCard()',
         chromeArm: null,
         hostHalf: null,
-        retireOn: 'P1-2 到货且达标线 ≥ server 1.290(typed parentToolCallId 在每条 tick 上恒在)后,' +
-            'FIFO 回落臂可删 —— 但只在**确认不再支持老引擎**时删,见 bindTaskCard 的 old-engine fallback 注释',
+        retireOn: null,
     },
     {
         id: 'T34',
@@ -26,7 +25,7 @@ export const MIGRATED_COMPENSATIONS = [
         libraryHalf: 'adapt.ts fireSubagentStart()(类型恒记 + 一生一次去重 + if-started 门)',
         chromeArm: 'subagent_lifecycle',
         hostHalf: '真执行用户 hook 进程(浏览器宿主根本不能执行 ⇒ 这一半必须留端)',
-        retireOn: 'G21 / P3a(引擎侧发正式的 subagent 生命周期事件)后,壳替 fire 整条退役',
+        retireOn: 'RL-32',
     },
     {
         id: 'T36',
@@ -35,7 +34,7 @@ export const MIGRATED_COMPENSATIONS = [
         libraryHalf: 'adapt.ts settlePanelTasks 的四个调用点(tool_end 关卡 / result / turn 末 / abort)',
         chromeArm: 'inline_task_stats',
         hostHalf: null,
-        retireOn: 'W6(引擎为每条子代发终态 tick)后,防御 sweep 降为纯兜底',
+        retireOn: 'RL-33',
     },
     {
         id: 'T44',
@@ -48,12 +47,12 @@ export const MIGRATED_COMPENSATIONS = [
     },
     {
         id: 'T47',
-        what: 'workflow lane 三级判据门 —— workflow 子代的 tick 绝不进前台 subagent lane',
+        what: 'workflow lane 判据门(帧带 workflowRunId)—— workflow 子代的 tick 绝不进前台 subagent lane',
         disposition: 'in-library',
-        libraryHalf: 'adapt.ts task_progress 臂的 workflowRunId / wa-id / workflow-card-parent 三级门',
+        libraryHalf: 'adapt.ts task_progress 臂的 workflowRunId 门',
         chromeArm: null,
         hostHalf: null,
-        retireOn: 'P1-2 到货后判据②③(形状嗅探 + 实例台账)可删,只留判据①(帧带 workflowRunId)',
+        retireOn: null,
     },
     {
         id: 'T48',
@@ -63,7 +62,7 @@ export const MIGRATED_COMPENSATIONS = [
         chromeArm: null,
         hostHalf: 'footer 行过滤 isFooterTaskRow/filterFooterTaskRows —— 含「丢弃所有无 parentId 顶层行」' +
             '这条**端专属决策**(主 run 头部行由端自己合成渲染),留 TUI',
-        retireOn: 'P1-2 到货后 fleet 行自带 parentToolCallId ⇒ 双生行不需要按尾段查',
+        retireOn: 'RL-35',
     },
     {
         id: 'T1',
@@ -83,8 +82,7 @@ export const MIGRATED_COMPENSATIONS = [
         libraryHalf: 'notifications.ts taskNotificationDedupKey + taskNotificationDedupKeyFromWire(裸 wire 入口)',
         chromeArm: null,
         hostHalf: null,
-        retireOn: 'P1-3 到货(帧带 completionId)⇒ 键改成**读** completionId,重算算法整条删;' +
-            '删之前要先有一批「同一完成在两条通道上 completionId 相同」的实测(否则换成了一把更差的键)',
+        retireOn: 'RL-36',
     },
     {
         id: 'T3',
@@ -95,8 +93,7 @@ export const MIGRATED_COMPENSATIONS = [
             'adapt.ts importLedgerFromTranscript(消费口)',
         chromeArm: null,
         hostHalf: null,
-        retireOn: 'P1-3 到货 ⇒ **回植仍要做**(crash 窗口客观存在),但不必再解 XML —— 转录里直接带 ' +
-            'completionId。所以退的是「XML 反解」这一段,不是整条回植',
+        retireOn: 'RL-37',
     },
     {
         id: 'T25',
@@ -106,7 +103,7 @@ export const MIGRATED_COMPENSATIONS = [
         libraryHalf: 'toolResult.ts 终态轮询卡臂的预 seed + notifications.markEngineWorkflowNotified',
         chromeArm: null,
         hostHalf: null,
-        retireOn: 'P1-3 到货 ⇒ 两个方向带同一个 completionId,预 seed 这一手(按 runId 抢跑)可删',
+        retireOn: 'RL-38',
     },
     {
         id: 'T53',
@@ -115,8 +112,7 @@ export const MIGRATED_COMPENSATIONS = [
         libraryHalf: 'adapt.ts task_notification / workflow_complete 两臂的四道门(逐道说明见本行上方注释)',
         chromeArm: null,
         hostHalf: null,
-        retireOn: 'P1-3 到货 ⇒ 降到「①渲染去重(键换 completionId)+ ④队列撤单」两道;②③ 删。' +
-            '🔴 判据不是「四变一」而是逐道过一遍上面那四行 —— 把 ④ 当成去重删掉会让队列里的旧条目重新上屏',
+        retireOn: 'RL-39',
     },
     {
         id: 'T49',
@@ -125,7 +121,7 @@ export const MIGRATED_COMPENSATIONS = [
         libraryHalf: 'adapt.ts task_progress 臂 registerSubagentAlias(explicitParent, taskId)',
         chromeArm: null,
         hostHalf: null,
-        retireOn: 'P1-2 到货后 content 帧自带 taskId ⇒ alias 学习整条可删',
+        retireOn: 'RL-40',
     },
 ];
 export function compensationSplitViolations() {

package/dist/controlRouter.d.ts

@@ -1,13 +1,11 @@
-import type { TaskRequest, RunReceipt, CancelAck, Scenario } from '@sema-agent/sdk';
+import type { TaskRequest, RunReceipt, CancelAck, Scenario, SteerPriority } from '@sema-agent/sdk';
+import { type SteerPriorityReading } from './steerPriorityCapability.js';
 export interface RunsResourceLike {
     create(req: TaskRequest, opts?: {
         idempotencyKey?: string | null;
         signal?: AbortSignal;
     }): Promise<RunReceipt>;
-    steer(taskId: string, steer: {
-        text: string;
-        mode?: 'all' | 'one-at-a-time';
-    }, opts?: {
+    steer(taskId: string, steer: SteerBodyInput, opts?: {
         signal?: AbortSignal;
     }): Promise<unknown>;
     cancel(taskId: string, opts?: {
@@ -17,17 +15,21 @@ export interface RunsResourceLike {
 export interface ControlClientLike {
     runs: RunsResourceLike;
 }
-export type ControlSafetyCode = 'not_running' | 'invalid_content' | 'queue_full' | 'duplicate_input_id' | 'ambiguous_target' | 'still_running' | 'blocked_by_hook' | 'ledger_unavailable' | 'steering_other' | 'cancel_lost_race' | 'cancel_run_not_running' | 'not_found';
+export type ControlSafetyCode = 'not_running' | 'invalid_content' | 'queue_full' | 'duplicate_input_id' | 'ambiguous_target' | 'still_running' | 'blocked_by_hook' | 'ledger_unavailable' | 'steering_other' | 'cancel_lost_race' | 'cancel_run_not_running' | 'not_found' | 'priority_not_applied' | 'steer_input_invalid';
 export declare class ControlSafetyError extends Error {
     readonly code: ControlSafetyCode;
     readonly cause?: unknown | undefined;
-    constructor(message: string, code: ControlSafetyCode, cause?: unknown | undefined);
+    readonly advice?: string;
+    readonly status?: number;
+    constructor(message: string, code: ControlSafetyCode, cause?: unknown | undefined, detail?: {
+        readonly advice?: string;
+        readonly status?: number;
+    });
 }
-export type QueuePriority = 'now' | 'next' | 'later';
-export interface QueuedCommand {
-    id: string;
-    text: string;
-    priority: QueuePriority;
+export interface ControlRouterSteerOptions {
+    signal?: AbortSignal;
+    priority?: SteerPriority;
+    steerPriority?: SteerPriorityReading;
 }
 export interface ControlRouterOptions {
     sessionId?: string;
@@ -42,8 +44,6 @@ export declare class ControlRouter {
     private readonly jobId;
     private readonly scenario;
     private readonly systemPrompt;
-    private readonly queue;
-    private seq;
     constructor(client: ControlClientLike, opts?: ControlRouterOptions);
     activeTaskId(): string | null;
     activeSessionId(): string | undefined;
@@ -51,19 +51,10 @@ export declare class ControlRouter {
         signal?: AbortSignal;
     }): Promise<RunReceipt>;
     private buildTaskRequest;
-    steer(text: string, mode?: 'all' | 'one-at-a-time', opts?: {
-        signal?: AbortSignal;
-    }): Promise<unknown>;
+    steer(text: string, mode?: 'all' | 'one-at-a-time', opts?: ControlRouterSteerOptions): Promise<unknown>;
     cancel(opts?: {
         signal?: AbortSignal;
     }): Promise<CancelAck>;
-    enqueue(text: string, priority?: QueuePriority): QueuedCommand;
-    dequeue(id: string): boolean;
-    pending(): readonly QueuedCommand[];
-    drainNext(opts?: {
-        signal?: AbortSignal;
-    }): Promise<RunReceipt | null>;
-    private nextId;
 }
 export interface ErrCodes {
     code?: string | undefined;
@@ -72,8 +63,24 @@ export interface ErrCodes {
 }
 export declare function errCodes(e: unknown): ErrCodes;
 export declare function steeringStatusIs4xx(e: object): boolean;
-export interface SteeringRefusedBeforeEngine {
+export interface SteerRefusalAdvice {
     safety: ControlSafetyCode;
     advice: string;
+    happened: string;
+    nextStep: string;
 }
+export type SteeringRefusedBeforeEngine = SteerRefusalAdvice;
 export declare function steeringRefusedBeforeEngine(e: object): SteeringRefusedBeforeEngine | undefined;
+export declare function steerRefusalAdviceOf(e: object): SteerRefusalAdvice | undefined;
+export interface SteerBody {
+    readonly text: string;
+    readonly mode?: 'all' | 'one-at-a-time';
+    readonly priority?: 'now' | 'later';
+}
+export interface SteerBodyInput {
+    text: string;
+    mode?: 'all' | 'one-at-a-time';
+    priority?: SteerPriority;
+}
+export declare const UNOBSERVED_STEER_PRIORITY: SteerPriorityReading;
+export declare function steerBodyOf(input: SteerBodyInput, reading: SteerPriorityReading): SteerBody;