@sema-agent/client-core 0.3.0 → 0.5.0

package/dist/modelBudgetRule.js

@@ -0,0 +1,73 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/modelBudgetRule.ts 逐字搬入(零依赖,纯规则)。
+ */
+/**
+ * modelBudgetRule.ts — max-output-tokens 中央规则(clay 2026-07-15 拍板,F2 maxTokens 裁决批)。
+ *
+ * 裁决(逐字):
+ *   · 上下文窗口:预设/家族表能匹配用匹配值;匹配不上默认 200000(FALLBACK_CONTEXT_WINDOW)。
+ *   · maxTokens 默认:32000;上下文窗口 ≥500000 → 64000;恒受两道封顶:
+ *       ① per-model 已知 cap(providerPresets 精确表,inferFamily 第①层命中带 perModelCap);
+ *       ② 上下文窗口 ÷ 4(向下取整)。
+ *   · UI 四档(超集):16K / 32K(默认)/ 64K / 128K;档位 > 上下文窗口÷4 的禁用/跳过
+ *     (例:128K 上下文 → 顶 32K;1M → 全档可用)。
+ *   · env 显式值恒赢:CLAUDE_CODE_MAX_OUTPUT_TOKENS 映射与显式 MODEL_MAX_TOKENS 既有行为不动
+ *     (本模块只算默认,不碰覆盖层 —— 见 ccConfigFallback.applyModelEnvFamilyFallback)。
+ *
+ * CC 对照锚(有意偏离,记忆档 max-tokens-ruling-deviate-cc):CC 2.1.207 per-model 表
+ * `max_output_tokens:{default:32000,upper:64000}`(源 13760)+ CLAUDE_CODE_MAX_OUTPUT_TOKENS env
+ * 钳制(源 529278),无 UI 档位、无 ÷4 封顶。sema 面对任意三方模型/网关,家族表大数直接当默认会
+ * 超供应商 cap(400)或单轮吃穿预算 —— 故默认收敛到 CC 口径 32K/64K,并加 ÷4 与 per-model 封顶;
+ * UI 档位是超集便利面。
+ *
+ * 注意:providerPresets.json 精确表 / modelFamilies.json 家族表的 maxTokens 字段【保留】——
+ * 只作 cap 参考(perModelCap / 显示),不再直接当默认 stamp 值。
+ */
+/** 裁决:预设/家族都匹配不上时的上下文窗口默认(=CC 的 200k 口径)。 */
+export const FALLBACK_CONTEXT_WINDOW = 200000;
+/** UI 四档(超集):16K / 32K(默认)/ 64K / 128K。十进制(与 CC 32000/64000 同基)。 */
+export const MAXTOK_TIERS = [16000, 32000, 64000, 128000];
+function normalizeCtx(contextWindow) {
+    return typeof contextWindow === 'number' && Number.isFinite(contextWindow) && contextWindow > 0
+        ? contextWindow
+        : FALLBACK_CONTEXT_WINDOW;
+}
+/**
+ * 默认 max tokens = min( ctx>=500000 ? 64000 : 32000 , floor(ctx/4) , perModelCap ?? ∞ )。
+ * contextWindow 传 null/undefined/非法 = 匹配不上 → 按 200000 算(→ 32000)。
+ */
+export function defaultMaxTokensFor(contextWindow, perModelCap) {
+    const ctx = normalizeCtx(contextWindow);
+    const base = ctx >= 500000 ? 64000 : 32000;
+    const quarter = Math.floor(ctx / 4);
+    const cap = typeof perModelCap === 'number' && Number.isFinite(perModelCap) && perModelCap > 0
+        ? perModelCap
+        : Infinity;
+    return Math.min(base, quarter, cap);
+}
+/**
+ * 该上下文窗口下可用的 UI 档位(> ctx÷4 的禁用/跳过)。可能为空(ctx < 64000,如 32K 上下文
+ * 连 16K 档都超 ÷4)—— UI 调用方对空列表降级(提示用 M 自由输入),规则函数不瞎补。
+ */
+export function tierChoicesFor(contextWindow) {
+    const ctx = normalizeCtx(contextWindow);
+    return MAXTOK_TIERS.filter(t => t <= ctx / 4);
+}
+/**
+ * 档位循环:当前值在档内 → 下一档(循环);不在档内(自由输入/家族值)→ 大于当前的最小档,
+ * 都不大于则回第一档(与 modelCtxOverride.nextStep 同语义)。无可用档 → null(调用方降级)。
+ */
+export function nextMaxTokTier(current, contextWindow) {
+    const tiers = tierChoicesFor(contextWindow);
+    if (tiers.length === 0)
+        return null;
+    if (typeof current === 'number') {
+        const i = tiers.findIndex(v => v === current);
+        if (i >= 0)
+            return tiers[(i + 1) % tiers.length];
+        for (const v of tiers)
+            if (v > current)
+                return v;
+    }
+    return tiers[0];
+}

package/dist/modelWireCaps.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/modelWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/modelWireCaps.ts — PURE per-turn /model projection (CC /model picker parity). seamQuery imports it.
+ *
+ * The mid-session model lives at `AppState`/`toolUseContext.options.mainLoopModel` (the /model picker writes it,
+ * query.ts). sema's engine ALREADY consumes a top-level `body.model` (service resolveTaskModel main.ts:1217 →
+ * core `TaskSpec.model`, catalog-gated, body.model wins over @mention wins over default). Without this wire a
+ * mid-session /model switch did NOTHING on the live engine (the survey's biggest functional hole). config-class
+ * intent → tighten/select only (the service catalog-gates an out-of-roster pick), so it rides the wire directly.
+ */
+export interface ModelField {
+    model?: string;
+}
+/** Project the client's selected model → the wire intent. Non-empty string carried verbatim; else no stamp. */
+export declare function modelFromAppState(model: string | undefined): ModelField;

package/dist/modelWireCaps.js

@@ -0,0 +1,16 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/modelWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/modelWireCaps.ts — PURE per-turn /model projection (CC /model picker parity). seamQuery imports it.
+ *
+ * The mid-session model lives at `AppState`/`toolUseContext.options.mainLoopModel` (the /model picker writes it,
+ * query.ts). sema's engine ALREADY consumes a top-level `body.model` (service resolveTaskModel main.ts:1217 →
+ * core `TaskSpec.model`, catalog-gated, body.model wins over @mention wins over default). Without this wire a
+ * mid-session /model switch did NOTHING on the live engine (the survey's biggest functional hole). config-class
+ * intent → tighten/select only (the service catalog-gates an out-of-roster pick), so it rides the wire directly.
+ */
+/** Project the client's selected model → the wire intent. Non-empty string carried verbatim; else no stamp. */
+export function modelFromAppState(model) {
+    return typeof model === 'string' && model.trim().length > 0 ? { model: model.trim() } : {};
+}

package/dist/notifications.d.ts

@@ -1,7 +1,3 @@
-/**
- * 通知投影纯函数(抽自 sema-cli engineTaskNotification/upstreamBridge 通知臂;
- * result 段纪律=cli #49 C1:帧带 result 必入 XML,core renderTaskNotificationXml 同名 tag 同段序)。
- */
 /**
  * ⚠️ 调用方契约(交叉复审 [MED] 登记):cli 原版在渲染前有两条默认值回填——
  *   summary 缺省 ⇒ `Background task "${taskId}" ${status}`;status 非串 ⇒ 'completed'。
@@ -53,3 +49,153 @@ export declare function taskNotificationDedupKey(n: {
     seq?: number | string;
     taskType?: string;
 }): string;
+/** 宿主队列条目的最小结构形(壳 QueuedCommand 的子集;本包只读这三个键)。 */
+export interface QueuedCommandLike {
+    mode?: unknown;
+    agentId?: unknown;
+    value?: unknown;
+}
+export interface NotificationQueuePort {
+    /** 壳 = messageQueueManager.enqueuePendingNotification(无显式优先级 ⇒ 队列缺省 'later')。 */
+    enqueuePendingNotification(command: {
+        value: string;
+        mode: 'task-notification';
+    }): void;
+    /** 壳 = messageQueueManager.removeByFilter;返回被摘掉的条目(数量是判据)。 */
+    removeByFilter(predicate: (cmd: QueuedCommandLike) => boolean): QueuedCommandLike[];
+}
+/** 宿主装配:壳侧 shim / web 宿主在**模块加载期**装(装之前的调用会计入 miss)。 */
+export declare function installNotificationQueuePort(port: NotificationQueuePort | null): void;
+/** 🔴 未注入队列口而发生的投递次数 —— 恒应为 0;>0 = 宿主装配漏了,通知已静默丢失。 */
+export declare function notificationQueuePortMisses(): number;
+/** 测试钩:清 port + miss 计数(不动台账,台账各有自己的 reset)。 */
+export declare function _resetNotificationQueuePortForTest(): void;
+/**
+ * B1(frame-lane-matrix 三节定谳)— Path A 回声到达时丢弃同 run 的 pending 队列条目。
+ * 双投机理:活跃 turn 内 Path B(workflow_complete/bg_notification/probe feeder →
+ * enqueuePendingNotification)先入队,Path A(引擎 server-side steer-inject 的
+ * task_notification 回声帧)随流到达——引擎侧模型已收到一遍;turn 收口 idle 排水若再
+ * auto-submit 队列条目 = 模型二收同一份 XML。壳撤不回引擎侧注入(跨进程),但能在
+ * drain 前把已被回声证实送达的同 run 队列条目丢掉。键空间 = 裸 taskId/runId(与
+ * notifiedRunIds/cardEnqueuedRunIds 同域);条目匹配按队列 XML 的 <task-id> 标签
+ * (enqueue 两族与 bridge 渲染同用 escapeXml,键形字节对齐)。仅主线程 task-notification
+ * 条目(agentId undefined);用户输入/其他模式绝不触碰。
+ */
+export declare function dropQueuedNotificationsForRun(taskId: string): number;
+/**
+ * Pre-seed the runId dedup WITHOUT enqueueing — the completion already reached the model in-band
+ * (clay 2026-07-04 复审:模型用 TaskOutput 轮询拿到 workflow 终态并当轮总结完;引擎 completion inbox
+ * 不知道"轮询已送达",下一次开流仍补发 workflow_complete —— 对模型是纯重复,还触发一轮"这是补发通知,
+ * 无需重复"的空转)。终态在 turn 内经过壳的投影(TaskOutput workflow 终态卡 / 引擎 server-side 已
+ * steer-inject 的 task_notification 帧)即预标记,Channel A 对同 runId 的补发直接丢弃。
+ */
+export declare function markEngineWorkflowNotified(runId: string): void;
+export declare function isWorkflowCompletionCardEnqueued(runId: string): boolean;
+type WorkflowStatusProbe = (runId: string) => Promise<{
+    terminal: boolean;
+    status: 'completed' | 'failed';
+    summary: string;
+} | null>;
+export declare function outstandingWorkflowCount(): number;
+/** headless(-p)退出门用([1340] BGB 分化案):**可送达**的 outstanding 数——probe 未装
+ *  (mock/离线)恒 0,print 驱动器不为永远等不到的通知悬置;probe 在装则 watcher 5s 节拍
+ *  必然送达或 TTL 放弃(2h 上界=run 蒸发极端形,与 CC 等本地 bg 任务的无界形同族)。 */
+export declare function outstandingDeliverableWorkflowCount(): number;
+export declare function subscribeOutstandingWorkflows(listener: () => void): () => void;
+/** liveClient 在构造会话 client 时注册(带正确 baseUrl/token/principal 的 workflows.get)。 */
+export declare function installWorkflowStatusProbe(probe: WorkflowStatusProbe): void;
+type BgTaskStatusProbe = (taskId: string) => Promise<{
+    terminal: boolean;
+    status: string;
+} | null>;
+export declare function installBgTaskStatusProbe(probe: BgTaskStatusProbe): void;
+/** bridge 在 Agent async_launched 回执(structured type:'agent')经过时登记。幂等;已通知不再登记。 */
+export declare function registerOutstandingBgTask(taskId: string, description: string): void;
+export declare function isOwnWorkflowRun(runId: string): boolean;
+/** 本壳亲手启动过的 workflow run 列表(Set 插入序 = 启动序;/workflows 命令的目标 run 选择用,
+ *  cmd-workflows.tsx——fleet source 无行可选时的兜底 id 源)。 */
+export declare function listOwnWorkflowRuns(): string[];
+/** bridge 在 run_workflow 回执(structured type:'workflow-run')经过时登记。幂等;已通知的不再登记。 */
+export declare function registerOutstandingWorkflowRun(runId: string): void;
+export interface EngineWorkflowCompletion {
+    runId: string;
+    status: 'completed' | 'failed';
+    summary: string;
+}
+export declare function enqueueBgChildNotification(n: {
+    taskId: string;
+    status: string;
+    /** bg 子代生命周期号(SendMessage 复活即 +1;service seq 字段)。去重键必须含 seq——
+     *  revive 周期(seq≥2)与首周期同 (taskId,status),不带 seq 会被首周期键吞掉
+     *  =「续派后完成通知永不上屏」(clay 图2 案根因,core1.355 复验帧实锤 2026-07-20)。 */
+    seq?: number;
+    summary?: string;
+}): void;
+export declare function enqueueEngineWorkflowNotification(c: EngineWorkflowCompletion): void;
+/** 测试钩(B2 新增,壳侧原文件没有):清空全部通知台账 + probe 槽 + watcher。
+ *  🔴 生产绝不调用 —— 台账是 process-lifetime 去重的唯一凭据,清了就会双投。 */
+export declare function _resetEngineTaskNotificationForTest(): void;
+/** 该 objective 是否为 task-notification 自动提交 turn 的注入 XML(整体即通知,非提及)。 */
+export declare function isTaskNotificationObjective(objective: unknown): boolean;
+/**
+ * 通知 turn → supplement 文案(非通知 turn → undefined,判别不扩散)。措辞英文、CC 报错语气
+ * (事实 + 出路,不惊悚)。status 从 XML `<status>` 读:completed 用定稿句;其余终态如实带
+ * status(通知可能报 failed/killed —— 谎称 completed 比不加更糟)。
+ */
+export declare function taskNotificationDeliverySupplement(objective: unknown): string | undefined;
+/**
+ * API-error 行文拆分(渲染层消费):尾部的 supplement 行(若在)分离出来渲 dim,main 保留原始
+ * error 字面渲红。无 supplement 的行原样返回 —— 既有 API-error 渲染路径零改变。
+ */
+export declare function splitApiErrorSupplement(text: string): {
+    main: string;
+    supplement?: string;
+};
+/** SSE 平铺 wire 形(server 1.280.0 http/server.js:6347-6355 直证;ownerScope/ownerSessionId 上 wire 前剥掉)。 */
+export interface HookNoticeWire {
+    type?: unknown;
+    kind?: unknown;
+    event?: unknown;
+    reason?: unknown;
+    detail?: unknown;
+    ts?: unknown;
+}
+export type HookNoticeReason = 'no_content' | 'unparsed' | 'skipped';
+/** ActiveGoal.lastNotice 的形(壳 state/AppStateStore.ts 同步声明)。 */
+export interface GoalHookNotice {
+    reason: HookNoticeReason;
+    detail?: string;
+    at: number;
+}
+/** 判定结果:ok=true 才交给宿主写 store;drop 原因供宿主打 SEMA_DEBUG 档(壳侧文案不变)。 */
+export type HookNoticeVerdict = {
+    ok: true;
+    notice: GoalHookNotice;
+    event: 'Stop';
+} | {
+    ok: false;
+    drop: 'not-hook-notice' | 'unknown-kind' | 'not-session-scoped' | 'non-stop-event';
+    kind?: string;
+    event?: string;
+    reason?: HookNoticeReason;
+};
+/**
+ * hook_notice 帧的判定本体(壳 ingestHookNoticeFrame 的判定半场逐字等价)。
+ * 🔴 归属镜像在**这里**做而不是在 fleetClient 里做 —— #105 变异普查(F3)定谳过:分发条件留在
+ * fleetClient 时,离线门只能 grep 源码,而 grep 对「把 'hook_notice' 改成 'hook_noticeZZZ'」
+ * 这类变异因注释碰撞+子串命中恒绿。提到这里后离线门直接**行为测本函数**。
+ */
+export declare function classifyHookNoticeFrame(frame: unknown, opts: {
+    sessionScoped: boolean;
+    now?: number;
+}): HookNoticeVerdict;
+/** 判别口:是不是 hook_notice 帧(宿主 fleet applyFrame 的分发条件;不是则继续走别的臂)。 */
+export declare function isHookNoticeFrame(frame: unknown): boolean;
+/**
+ * 「Last check」行的诚实文案([1790] 措辞纪律:「本轮未能评估,已放行」方向;detail 是 server
+ * 结构化日志同源的机器话,dim 展示原文比意译更可追责)。
+ */
+export declare function hookNoticeLastCheckText(n: GoalHookNotice): string;
+/** footer 通知条文案前缀(测试锁字面;宿主拼 ` (${reason})`)。 */
+export declare const HOOK_NOTICE_WARN_PREFIX = "Goal check: couldn't evaluate this turn \u2014 proceeded";
+export {};