@sema-agent/client-core 0.11.5 → 0.11.7

package/dist/index.d.ts

@@ -216,3 +216,4 @@ export * from './hitl/planReviewWire.js';
 export * from './hitl/approvalsFeed.js';
 export * from './compensations.js';
 export * from './request/printNotification.js';
+export * from './seatContract.js';

package/dist/index.js

@@ -279,3 +279,13 @@ export * from './compensations.js';
 // 去重键**不出第二个名字**:print 侧那份手写算法废除,直接用 `taskNotificationDedupKeyFromWire`。
 // 请求面同批补上可执行判据 `unregisteredRequestKeys`(见 request/taskRequest.ts 文件末)。
 export * from './request/printNotification.js';
+// ── B18 批:desktop/web 座位 IPC 契约单一真源(design/159,2026-07-29)────────────────────────
+// 修的是一条**静默漂移通道**:同一份座位契约此前有两份声明(desktop `shared/localSessions.ts`
+// 15 型生产端 / web `lib/desktop/local-sessions-transport.ts` 9 型 `Seat*` 消费端),两边名字零重合
+// ⇒ 编译器永远不会告诉你它们漂了。实测已漂,其中 `LocalSessionEvent.outcome` 在 web 镜像里整位
+// 缺席 = [1947] 红③ 一直销不掉账的机制原因(宿主发了词,消费端连接词的位都没有)。
+// 🔴 纯类型 + 常量 + 纯谓词,**零 import** —— portability 门的三个 EXPECTED_PACKAGES 一个字不变。
+// 🔴 防再漂钉在文件末:`LocalSessionsApi` 的 verb/store 名由类型结构式派生 → 名字常量(编译期钉)
+//    → `LOCAL_SESSIONS_SPEC` 键集(run-seat-contract-keys-test 运行期对账)。加 verb 忘了加 SPEC
+//    的后果不是报错而是 preload 不注册 channel、渲染端读到 undefined(假 affordance 家族)。
+export * from './seatContract.js';

package/dist/request/taskRequest.d.ts

@@ -79,6 +79,8 @@ export interface TaskRequestInput {
     promptProfile?: string;
     enableFork?: boolean;
     attachments?: Record<string, unknown>;
+    /** 预上传附件句柄(`uploadAttachment` 回执 id)。空数组 = 没带附件 ⇒ 整键不 stamp。 */
+    attachmentIds?: readonly string[];
     finalVerification?: boolean;
     limits?: Record<string, unknown>;
     interactiveTools?: false;

package/dist/request/taskRequest.js

@@ -28,7 +28,12 @@ export const REQUEST_FIELD_MATRIX = [
     { field: 'finalVerification', lanes: ['print'], live: true, why: 'P1-1 终验:无人值守车道才需要引擎自证;交互 REPL 由人当场看结果。#106 裁 B(让位+告知)后交互面默认关' },
     { field: 'limits', lanes: ['print'], live: true, why: 'P2-3-b:`-p` 的预算护栏(--max-* flag 族),交互 REPL 由人随时 Esc' },
     { field: 'interactiveTools', lanes: ['print'], live: true, why: '[909]B 件3:无人值守 stamp false,从 roster 源头灭掉 AskUserQuestion/plan 门。交互车道 stamp false 等于自废武功' },
-    // ── TUI 独有 ────────────────────────────────────────────────────────────────────────────────
+    // ── interactive 车道独有 ────────────────────────────────────────────────────────────────────
+    // ⚠️ 「interactive」**不等于**「TUI」:web 的 BFF lane 也报 `interactive`
+    //    (`sema-web-client` `WEB_REQUEST_LANE`)。下面多数条目的理由写的是壳的 TUI 面 —— 它们是
+    //    B4 从壳的三个构造器逐行读出来的,那时这条车道只有壳一个消费者。`attachmentIds` 是**反过来**
+    //    的第一条:它今天只有 web/desktop 在发,壳反而没有这个入口。别把本节读成「壳独有」。
+    { field: 'attachmentIds', lanes: ['interactive'], live: true, why: '附件**字节通道**(uploadAttachment 回执 id;server ≥1.289 绑定会话并把文件物化进 run 的 attachments/)。有上传入口的端才有 id 可引用:web/desktop 有,壳走 images / 本地文件路径,`-p` 车道连 uploadAttachment 都没有 ⇒ print 缺席是**没有来源**,不是漏。🔴 与上面的 `attachments` 同名不同物(那是 turn 边界的配置键),两条永远不许合并' },
     { field: 'settings.ultracode', lanes: ['interactive'], live: true, why: 'design/111:sticky `/effort ultracode` 拨盘 + 当轮关键词嗅探,两个来源都只在交互面存在', gap: true },
     { field: 'systemPrompt', lanes: ['interactive'], live: false, why: 'CC QueryParams.systemPrompt;print 腿的 params 没有这一位' },
     { field: 'reasoningEffort', lanes: ['interactive'], live: false, why: '`/effort` 拨盘存在 AppState,print 无 AppState', gap: true },
@@ -106,6 +111,10 @@ export function buildTaskRequest(input, lane) {
         ...(on('promptProfile', input.promptProfile) ? { promptProfile: input.promptProfile } : {}),
         ...(on('enableFork', input.enableFork) ? { enableFork: input.enableFork } : {}),
         ...(on('attachments', input.attachments) ? { attachments: input.attachments } : {}),
+        // 空数组按 `images` 同款处理:没带附件与「带了 0 个附件」在 wire 上是同一件事,发小的那个。
+        ...(on('attachmentIds', input.attachmentIds) && (input.attachmentIds?.length ?? 0) > 0
+            ? { attachmentIds: [...(input.attachmentIds ?? [])] }
+            : {}),
         ...(on('clientContext', input.clientContext) ? { clientContext: input.clientContext } : {}),
         ...(on('scratchpadDir', input.scratchpadDir) ? { scratchpadDir: input.scratchpadDir } : {}),
         ...(on('finalVerification', input.finalVerification)

package/dist/seatContract.d.ts

@@ -0,0 +1,486 @@
+/**
+ * seatContract — desktop/web **座位 IPC 契约的单一真源**(design/159 B18,2026-07-29)。
+ *
+ * 搬迁前的形:同一份契约有**两份声明**,而且跨仓名字零重合 ——
+ *   · `sema-desktop/src/shared/localSessions.ts`  = 15 个类型 + 3 个词表常量 + 6 个校验器 + SPEC(生产端)
+ *   · `sema-web-client/ui/lib/desktop/local-sessions-transport.ts` = 9 个 `Seat*` 本地重声明(消费端)
+ * 两边名字不同 ⇒ **编译器永远不会告诉你它们漂了**。实测已经漂了(见下「漂移清单」),其中
+ * `LocalSessionEvent.outcome` 那一条是真 bug:宿主发了词、消费端的镜像里根本没有这个位,
+ * 于是「拒绝 / TTL 到点 / 人点了允许」在屏上长得一模一样 —— 正是 localSessions 自己在
+ * 「接缝记账」里写下的第 1 条,它一直没被销账的原因就是没有任何机制会让它红。
+ *
+ * 落点为什么是本包:desktop 与 web 都已经依赖 `@sema-agent/client-core`(0.11.5),而本文件是
+ * **纯类型 + 常量 + 纯谓词**,零值级 import、零 Node 内建 ⇒ 不动本包的可移植闭包(portability 门的
+ * `EXPECTED_PACKAGES_INDEX` 一个字不变)。
+ * ⚠️ 唯一一条 `import type`(`./effortWire.js` 的 `ReasoningEffort`)是**类型边**:portability 门
+ * 走值级传递闭包时按规则剥掉 type-only import(门里 `/^\s*type\b/` 那一跳),bundle 里一个字节都
+ * 不多。写成 import 而不是就地复刻那七档,是因为「座位闭集」与「wire 投影闭集」必须是**同一套词**
+ * ——复刻一份就等于埋一条只有真用户能发现的漂移(拨盘上的档在座位 lane 上静默到不了引擎)。
+ *
+ * ── 搬迁时按「真源为准」收敛的漂移(逐条,web 侧镜像 → 本文件)────────────────────────────
+ *  🔴 D1 `LocalSessionEvent.outcome` —— web 镜像整位缺席 ⇒ `tool_permission_resolved` 只会清面,
+ *      不会告诉用户为什么工具没跑。**真 bug**,本批只做「位补回来」;把词渲成可见痕迹是渲染面的活。
+ *  D2 `SendMessageRequest.permissionMode` —— web 镜像是裸 `string`,真源是闭集 `PermissionModeIntent`,
+ *      而宿主入站门 `requireOptionalPermissionMode` 是**会抛的闭集门**。今日两边词表逐字相等
+ *      (web `ComposerMode` 五档 ≡ `PERMISSION_MODE_INTENTS` 五档,已核),所以是**潜伏**不是现症:
+ *      ComposerMode 哪天加一档,裸 string 一路放行到宿主门口才抛。收敛成闭集后当天编译红。
+ *  D3 `AttachmentUploadReceipt.sha256` / `ToolPermissionRequest.createdAt` / `StartSessionOptions.cwd`
+ *      / `.excludeTools` / `LocalSessionRecord.queuedMessages`·`model`·`engineSessionId` ——
+ *      web 镜像缺位。都是「没接线」不是「接错线」(web 侧今日无消费点,已核),收敛后位在、待接。
+ *  D4 `LocalSessionEvent.request` —— 真源有这个位,**宿主从不发**(session-host 零处写 `request:`);
+ *      web 镜像没有它反而与运行时事实一致。真源保留该位(CC `fQe` 的 form 位),记在这里免得
+ *      下一棒把「web 没有」当成漏。
+ *  D5 `EipcStoreClient.getStateSync` web 侧是 optional、真源是 required;`SeatSessionDirectoryRow.createdAt`
+ *      web 侧 optional、真源 required。两条都是「更弱」方向,收敛到真源即可(宿主校验器
+ *      `isLocalSessionRecord` 本来就要求 createdAt 在场,运行时保证一直成立)。
+ *  · web 侧**没有**镜像、因而至今拿不到的面:队列三动词 / setFocusedSession / setModel /
+ *    focusedSessionState / settingsState / `CHROME_EVENT_KINDS` / `ATTACHMENT_IDS_PER_TASK_CAP`。
+ *    本文件导出后它们对 web 首次可见(接不接线是渲染面的决定)。
+ *
+ * ── 沿革(以下正文自 sema-desktop/src/shared/localSessions.ts 逐字迁入)──────────────────────
+ * LocalSessions — the desktop host's session service contract, FORM-ported from the CC desktop
+ * app's `claude.web / LocalSessions` eipc interface (212 methods there; FIRST BATCH here = the four
+ * families clay scoped: session lifecycle / event subscription / interrupt / approvals).
+ *
+ * Naming: CC ns `claude.web` → `sema.web` (brand table). Method names kept verbatim where the CC
+ * method exists (`start`/`stop`/`interrupt`/`sendMessage`/`onEvent`/`onToolPermissionRequest`/
+ * `respondToToolPermission` are all real CC LocalSessions methods — see the 854-channel census).
+ *
+ * Event payload contract: ported in FORM from CC's `onEvent` runtime validator `fQe`
+ * (unpack `.vite/build/index.chunk-CnWKsyE_.js:369773`). The load-bearing property we keep
+ * byte-faithful ([1832] axiom 2, independently proven by CC's own code): on an otherwise
+ * fully-schema'd IPC surface, the `message`/`messages` fields (= CC session-vocabulary SDKMessage
+ * bodies, our transcript plane) are UNVALIDATED passthrough positions, while every other field is a
+ * neutral typed position. Our implementation体 differs (sema wire via @sema-agent/sdk +
+ * @sema-agent/client-core), the contract shape does not.
+ */
+import type { ReasoningEffort } from "./effortWire.js";
+export type EipcMethodKind = "invoke" | "event";
+export interface EipcMethodSpec {
+    kind: EipcMethodKind;
+    /** invoke: validates the impl's RESULT before it crosses back to the renderer (CC's outbound
+     *  schema gate — `Result from method "<m>" in interface "<S>" failed to pass validation`).
+     *  event: validates the PAYLOAD before `webContents.send` (CC's dispatcher-side validator, the
+     *  `fQe` position for `LocalSessions.onEvent`). Absent = any result/payload passes (CC has
+     *  `void`-returning methods with trivially-true validators). */
+    validate?: (value: unknown) => boolean;
+}
+export interface EipcStoreSpec {
+    /** Validates the STATE payload both on read replies and on update pushes (fail-closed like the
+     *  method gates). Absent = any state passes. */
+    validate?: (state: unknown) => boolean;
+}
+export interface EipcServiceSpec {
+    ns: string;
+    service: string;
+    methods: Record<string, EipcMethodSpec>;
+    /** `$store$` reactive states owned by this service (CC codegen form; see eipcStoreChannel). */
+    stores?: Record<string, EipcStoreSpec>;
+}
+/** Neutral session record (CC's `session` position is schema-gated by `aM`; ours is this shape). */
+export interface LocalSessionRecord {
+    /** Host-minted stable session id — the id every event carries (CC form: sessionId on every event). */
+    sessionId: string;
+    /** Engine (service)-minted session id, known after the first reply; absent before it. */
+    engineSessionId?: string;
+    model?: string;
+    title?: string;
+    isRunning: boolean;
+    createdAt: string;
+    lastActivityAt?: string;
+    /** Host-side deferred queue (CC `deferredSends` seat, in submit order — drives the queued-message
+     *  bar). Present (possibly empty) whenever the host projects the record during a running turn. */
+    queuedMessages?: Array<{
+        uuid: string;
+        text: string;
+    }>;
+}
+/** HITL request row (CC's `request` position is schema-gated by `S1`; ours is this shape, projected
+ *  from the sema wire's PendingCheckpoint — see session-host). */
+export interface ToolPermissionRequest {
+    /** Stable request key — echo back on respondToToolPermission. FOUR id domains, prefix-tagged
+     *  (the prefix is what routes the decision back to the right wire verb — see session-host):
+     *   `live:<approvalId>`               = LIVE in-band tool-approval face (frame rides the token
+     *                                       stream; unanswered → engine fail-CLOSED deny at its TTL);
+     *   `durable:<engineSessionId>:<callId>` = the durable checkpoint class (approvals inbox);
+     *   `question:<questionId>`           = LIVE `AskUserQuestion` (the agent's own structured ask;
+     *                                       unanswered → engine fail-OPEN: the model takes the
+     *                                       headless default `{answers:[]}` at the 5-min TTL, which is
+     *                                       why leaving this family unrendered is silent, [1947] 红④);
+     *   `elicit:<elicitationId>`          = LIVE inbound-MCP elicitation (a server asks the user for
+     *                                       form input mid-tool-call).
+     *  The three LIVE domains are same-replica + non-durable: a late/duplicate decision 404s, which the
+     *  host treats as "already released" (dismiss), never as a retryable error. */
+    requestId: string;
+    sessionId: string;
+    /** For the two ask families this is the CC tool vocabulary name the renderer branches on:
+     *  `AskUserQuestion` (question domain) / `McpElicitation` (elicit domain). */
+    toolName?: string | null;
+    /** The ENGINE's tool-call id (`call_…`) — the SAME id the assistant message's `tool_use` block
+     *  carries, so a renderer can key the approval onto the tool card that actually raised it.
+     *  Present on tool-approval rows from server ≥1.307; `null` when the wire did not offer one
+     *  (old server, or the ask families, which have no tool call of their own). NEVER synthesized. */
+    toolCallId?: string | null;
+    /** UNTRUSTED, service-redacted tool args / question payload (render-only, never re-fed). */
+    input?: unknown;
+    /** UNTRUSTED, service-redacted engine ask text (live face only) — display only. */
+    message?: string;
+    /** design/80 D-1 TOCTOU binding pair (durable face only) — echo VERBATIM into the decision.
+     *  🔴 出站**只读**位:回程的 verbatim 回显由宿主自己的登记表做(session-host 的
+     *  `row.boundCallId/boundInputHash`),`ToolPermissionDecision` 因此没有对应席位 —— 渲染端
+     *  拿到它只为展示,绝不需要(也不该)自己回传。 */
+    boundCallId?: string;
+    boundInputHash?: string;
+    createdAt?: number;
+}
+export interface LocalSessionEvent {
+    type: string;
+    sessionId: string;
+    /** 🔴 transcript-plane passthrough (SDKMessage body) — deliberately UNVALIDATED (fQe posture). */
+    message?: unknown;
+    /** 🔴 transcript-plane passthrough batch — array-checked only, elements unvalidated (fQe posture). */
+    messages?: unknown[];
+    error?: string;
+    errorCategory?: string;
+    code?: number;
+    /** CC `fQe` 的 form 位。🔴 **本宿主从不发这个位**(session-host 零处写 `request:`;HITL 行走
+     *  独立的 `onToolPermissionRequest` 通道)—— 位保留是为了与 CC 的 fQe 逐位同形,消费端不该
+     *  为它写分支(见文件头 D4)。 */
+    request?: ToolPermissionRequest;
+    data?: string;
+    sources?: string[];
+    permissionMode?: string;
+    session?: LocalSessionRecord;
+    userMessageUuid?: string;
+    hasPreClearSession?: boolean;
+    /** On `tool_permission_resolved`: which request settled (so a native notification for it can be
+     *  dismissed — CC `closePermissionNotification(requestId)`). */
+    requestId?: string;
+    /**
+     * On `tool_permission_resolved`: HOW it settled ([1947] 红③). Without this the renderer only ever
+     * learned that a card should disappear — a TTL expiry, a disconnect-settle and a human's own
+     * "allow" were indistinguishable, so a REFUSAL rendered as a card silently vanishing and the user
+     * was never told why the tool did not run.
+     *
+     * Words currently emitted (see HITL_RESOLUTION_OUTCOMES): the tool-approval wire's own
+     * `allowed`/`denied`/`expired`, the question wire's `answered`/`unanswered`, the elicitation
+     * wire's `accept`/`decline`/`cancel`. ABSENT is meaningful and honest: the durable inbox sweep
+     * learns only that a row is gone, never why.
+     *
+     * 🔴 Validated as a plain string, NOT against a closed set, deliberately: the words originate on
+     * the wire, and a fail-closed gate keyed to today's vocabulary would DROP THE WHOLE EVENT (card
+     * stuck on screen forever) the day the server adds an outcome word. Renderers branch on the words
+     * they know and treat an unknown one as "settled, reason unknown".
+     */
+    outcome?: string;
+    /** On `chrome_event`: one client-core ChromeEvent arm (the NEUTRAL typed chrome vocabulary —
+     *  [1832] axiom 2's non-transcript half). Only the renderer-wired arm kinds cross the wire
+     *  (see CHROME_EVENT_KINDS); the outbound gate checks kind membership + the laneProof discipline. */
+    chrome?: {
+        kind: string;
+        laneProof?: unknown;
+        [k: string]: unknown;
+    };
+}
+/**
+ * The resolution words the host currently puts on `tool_permission_resolved.outcome` ([1947] 红③).
+ * DOCUMENTARY + test anchor only — the gate does NOT enforce membership (see the field's doc: a
+ * closed set would fail-close the whole event on the day the wire grows a word). Grouped by family:
+ *  - tool approval (wire `ToolApprovalFrame.outcome`, + our own settle sweep): allowed/denied/expired
+ *  - question      (wire `QuestionFrame.outcome`):                             answered/unanswered
+ *  - elicitation   (wire `ElicitationFrame.action`):                           accept/decline/cancel
+ */
+export declare const HITL_RESOLUTION_OUTCOMES: readonly string[];
+/**
+ * 接缝记账 — what the HOST now guarantees vs what a RENDERER still owes ([1947] 红③/红④ split).
+ *
+ * The host half is done and pinned by desktop's `scripts/run-hitl-frame-transit-fence-test.mjs`:
+ * every live ask family reaches `onToolPermissionRequest` with its own requestId domain, every
+ * resolution reaches `onEvent` with an `outcome`, and every decision routes to the right wire verb.
+ *
+ * The renderer half is where these become VISIBLE, and until it lands the data is present but
+ * unread (stating it plainly so nobody reads "the host emits it" as "the user sees it"):
+ *  1. `tool_permission_resolved.outcome` — an `expired` / `denied` / `unanswered` resolution must
+ *     leave a visible refusal trace. Today the seat transport clears the surface and drops the
+ *     word, so a refusal is still indistinguishable from an approval on screen.
+ *     🔴 B18(2026-07-29)查明这条一直不销账的**机制原因**:web 侧的镜像类型里连 `outcome` 这个
+ *     位都没有,所以「没读」在两边都编译得过。本批把位收进真源 = 让它至少可见于类型面。
+ *  2. `toolCallId` — now real (not null), so an approval can be anchored to the tool card that
+ *     raised it instead of "the most recent tool_start" (an anchor that lands on the wrong card
+ *     when a prior tool is still running).
+ *  3. `question:` rows need NO new renderer code: they arrive as `toolName: "AskUserQuestion"` with
+ *     `input.questions`, which is exactly what the seat's ask-user-question surface already reads,
+ *     and its answer envelope is exactly what this host expects back.
+ *  4. 座位 wire 补齐批 (2026-07-28) closed two entries that used to live here as "如实,未做":
+ *     `permissionMode` now has a seat on `sendMessage` (was: the composer's Plan badge never
+ *     crossed and the turn ran with the engine default), and the attachment BYTE channel exists
+ *     (`uploadAttachment` + `sendMessage.attachmentIds`) — so a seat renderer no longer has to
+ *     simulate "attachment ready" for a file nothing received. What is still NOT here, stated
+ *     plainly: plan REVISE feedback text (the decide face has no `reason` seat, so revise maps to
+ *     a bare deny) and a per-session `permissionMode` write (the wire's is per-TURN only).
+ *  5. `elicit:` rows have no dedicated surface yet: they fall through to the generic approval card,
+ *     which shows the MCP server's prompt and can accept/decline but CANNOT collect form values.
+ *     A real form surface (built from `input.requestedSchema`) is the renderer's remaining piece;
+ *     until then an approve carries no content — the host never invents form values. That generic
+ *     card also offers "Always allow (this session)", which this domain has no concept of: the host
+ *     ignores `remember` here rather than pretend, so the renderer should hide that control for
+ *     `elicit:` rows (a button that changes nothing is the false-affordance family again).
+ */
+/** Chrome arms wired to the renderer position (batch 4); other arms stay host-side on the ring. */
+export declare const CHROME_EVENT_KINDS: readonly string[];
+export interface StartSessionOptions {
+    model?: string;
+    title?: string;
+    /** Working directory for the session's hand tools (TaskRequest.cwd). Default = a per-session dir
+     *  under the host's workspace base. A UI that picks a project directory passes it here — CC desktop
+     *  form (session.cwd / worktreePath). Honored only on the local host-adapter engine. */
+    cwd?: string;
+    /** Wire TRUE-UNMOUNT list (TaskRequest.excludeTools, server ≥1.221): named tools' schemas never
+     *  reach the model for ANY turn of this session. Tighten-only. */
+    excludeTools?: string[];
+}
+/**
+ * PERMISSION MODE INTENT — the RAW mode the composer is showing, carried verbatim to the engine as
+ * `TaskRequest.permissionMode` (SDK types.d.ts:259; the SERVICE interprets it, axis-aware and
+ * tighten-only: `plan` ⇒ mount `present_plan` + read-only hands = CC EnterPlanMode).
+ *
+ * 🔴 Why this seat exists at all (红批注 web#1): without it, a user who switched the composer to
+ * Plan mode inside the desktop seat got a turn that ran with the engine's DEFAULT mode — the badge
+ * said "plan", the engine was never told, and the agent happily edited files. A mode the UI shows
+ * but never sends is the false-affordance family with teeth.
+ *
+ * The vocabulary is the wire's own (identical to the web client's `ComposerMode`), so the seat
+ * passes the word through unchanged rather than re-deriving core fields locally — one interpretation
+ * across TUI + web + desktop. 🔴 B18 起 web 侧的镜像位也是这个闭集(此前是裸 `string`):
+ * ComposerMode 加一档而宿主闭集门不认的那天,红在编译期而不是用户提交那一刻。
+ */
+export type PermissionModeIntent = "default" | "plan" | "acceptEdits" | "bypassPermissions" | "auto";
+/** The closed set the inbound gate checks. CLOSED deliberately, unlike `outcome` above: this word
+ *  ORIGINATES in our own renderer and goes OUT to a wire that 400s on anything else, so an unknown
+ *  value is a local bug we want reported at the door — not an unknown future wire word we must
+ *  tolerate. (The direction of travel is what decides open vs closed, not the field's shape.) */
+export declare const PERMISSION_MODE_INTENTS: readonly PermissionModeIntent[];
+/** Per-task attachment cap — the server's own limit (`attachmentIds` > 16 ⇒ 400). Gated here so the
+ *  seat gets a precise local error instead of a wire 400 halfway through a turn. */
+export declare const ATTACHMENT_IDS_PER_TASK_CAP = 16;
+/** The per-turn `reasoningEffort` accept-set — core's ThinkingLevel tiers, re-exported from the
+ *  package's own wire projection (`effortWire.ReasoningEffort`) rather than re-typed here.
+ *
+ *  CLOSED for the same reason `PERMISSION_MODE_INTENTS` is: the word ORIGINATES in our own composer
+ *  and travels OUT to a wire that 400s (fail-loud) on an unknown tier — so an unknown value is a
+ *  local bug we want reported at the seat's door, not a future wire word to tolerate. `ultracode` is
+ *  deliberately NOT a tier here: in CC it is a standalone `settings.ultracode` preset boolean that
+ *  COEXISTS with `xhigh` (see `SeatTurnSettings`), and folding it into this axis is exactly how the
+ *  orchestration axis gets eaten by the reasoning axis. */
+export declare const SEAT_REASONING_EFFORTS: readonly ReasoningEffort[];
+/** The `settings` sub-object a seat turn may carry. A CLOSED set with its own name list + pin,
+ *  exactly like the top-level request: `SEND_MESSAGE_REQUEST_KEYS` checks `keyof SendMessageRequest`
+ *  (top-level names), so a dotted `"settings.ultracode"` entry could never be pinned by `Covers` —
+ *  the shape that stays consistent with the existing closed sets is one top-level key plus a nested
+ *  closed set of its own. */
+export interface SeatTurnSettings {
+    /** CC's `settings.ultracode` PRESET boolean (max thinking × workflow orchestration, service ≥1.48.0
+     *  reads `body.settings.ultracode` and expands it). NOT a seventh effort tier — the dial separately
+     *  coerces the reasoning axis to `xhigh`, and collapsing the two loses the orchestration half
+     *  (`ultracodeWireCaps` in this package records that semantics verbatim). */
+    ultracode?: boolean;
+}
+export declare const SEAT_TURN_SETTINGS_KEYS: readonly ["ultracode"];
+export interface SendMessageRequest {
+    sessionId: string;
+    text: string;
+    model?: string;
+    /** Client-supplied echo key for the user message (CC form: userMessageUuid); minted if absent. */
+    userMessageUuid?: string;
+    /** Composer permission mode for THIS turn → `TaskRequest.permissionMode`. Omit/`default` ⇒ no stamp. */
+    permissionMode?: PermissionModeIntent;
+    /** Pre-uploaded attachment handles (`uploadAttachment` receipts) → `TaskRequest.attachmentIds`.
+     *  Bytes never ride this call: they went up once through the dedicated verb and the engine
+     *  materializes them into the run's `attachments/` dir. */
+    attachmentIds?: string[];
+    /** Per-turn `/effort` dial pick → `TaskRequest.reasoningEffort`. Omit ⇒ the engine's own default.
+     *  Closed set (`SEAT_REASONING_EFFORTS`) — gate it at the host's door, not at the wire.
+     *
+     *  🔴 Why this position exists (web 收编第一批, 2026-07-29): it did NOT, and the absence was
+     *  STRUCTURAL — the seat lane's only payload is this closed-set interface, so the composer's effort
+     *  dial had nowhere to put the user's pick and the web client honestly disabled the control on the
+     *  desktop seat lane. "The control is missing" was the visible symptom; the missing wire position
+     *  was the cause. */
+    reasoningEffort?: ReasoningEffort;
+    /** Keep this turn's background processes alive past the turn boundary → `TaskRequest.
+     *  retainBackgroundProcesses`. Same structural-absence story as `reasoningEffort` above; the
+     *  shell's lane defaults it ON (2026-07-26 flip), so a seat that cannot send it is not "defaulting
+     *  to the same thing" — it is letting the ENGINE's default decide, which is a different decision. */
+    retainBackgroundProcesses?: boolean;
+    /** Per-turn settings sub-object → `TaskRequest.settings`. Closed shape (`SeatTurnSettings`);
+     *  today's only member is the `ultracode` preset boolean. */
+    settings?: SeatTurnSettings;
+}
+/** `uploadAttachment` receipt — the SDK's `AttachmentInfo` verbatim (server POST /v1/attachments 201).
+ *  `name` is the SERVER's sanitized basename, not the local filename: it is the name the engine
+ *  materializes, so the renderer must display THAT one. */
+export interface AttachmentUploadReceipt {
+    id: string;
+    name: string;
+    mime: string;
+    sha256: string;
+    sizeBytes: number;
+}
+/** One row of the seat's model catalog (`GET /v1/models`, non-secret projection: the service already
+ *  strips baseUrl/apiKey/headers). `contextWindow`/`maxOutputTokens` are soft-degrade extras. */
+export interface SeatModelInfo {
+    id: string;
+    name?: string;
+    provider?: string;
+    contextWindow?: number;
+    maxOutputTokens?: number;
+}
+/** `listModels` envelope. `defaultId` = the deployment's resolved default model id (display only —
+ *  the per-turn choice always rides `sendMessage({model})`). */
+export interface SeatModelCatalog {
+    models: SeatModelInfo[];
+    defaultId?: string;
+}
+export interface SendMessageAck {
+    sessionId: string;
+    userMessageUuid: string;
+    /** true = a turn was running, the message entered the deferred queue (CC sendMessage semantics)
+     *  instead of starting a turn; absent/false = the turn started immediately. */
+    queued?: boolean;
+}
+/**
+ * One decision, four wire verbs — the requestId's domain picks which (session-host routes it):
+ *  `live:`     → POST /v1/tool-approvals/:id/respond   (allow | allow_session | deny)
+ *  `durable:`  → POST /v1/approvals/:sessionId/decide  (+ the TOCTOU binding pair, echoed verbatim)
+ *  `question:` → POST /v1/questions/:id/respond        (approve ⇒ `answer`; deny ⇒ `{answers:[]}`,
+ *                the wire's own NO_HUMAN — releases the ask NOW instead of hanging it to its TTL)
+ *  `elicit:`   → POST /v1/elicitations/:id/respond     (approve ⇒ accept + `updatedInput` as the
+ *                form content; deny ⇒ decline)
+ */
+export interface ToolPermissionDecision {
+    sessionId: string;
+    requestId: string;
+    decision: "approve" | "deny";
+    /** AskUserQuestion answer (approve only) — `{answers:[{header, selected: string[], note?}]}`,
+     *  keyed by the question's HEADER, `selected` echoing the EXACT option labels the user saw (core
+     *  fences `selected ⊆ options`). Malformed shapes are refused at the door, never coerced: a
+     *  silently emptied answer is the user's choice being thrown away without anyone noticing. */
+    answer?: unknown;
+    /** Approve-with-edit rewritten args (design/37 last-wins). On the `elicit:` domain this position
+     *  carries the submitted FORM CONTENT — a flat record of `string|number|boolean|string[]`
+     *  (the only shape the wire accepts; anything else is refused, not filtered). */
+    updatedInput?: unknown;
+    /** "Don't ask again this session" (approve only). */
+    remember?: "session";
+}
+/** Renderer-side `$store$` client (CC form: read + subscribe; `update` channel is the push). */
+export interface EipcStoreClient<T> {
+    getState(): Promise<T>;
+    getStateSync(): T;
+    onStateChange(cb: (state: T) => void): () => void;
+}
+export interface SettingsState {
+    defaultModel: string | null;
+    engineVersion?: string;
+    dataRoot?: string;
+}
+export interface SessionSearchResult {
+    sessionId: string;
+    title?: string;
+    matches: Array<{
+        snippet: string;
+    }>;
+}
+/** Renderer-facing surface exposed by the mainView preload as `sema.web.LocalSessions`. */
+export interface LocalSessionsApi {
+    start(opts?: StartSessionOptions): Promise<LocalSessionRecord>;
+    sendMessage(req: SendMessageRequest): Promise<SendMessageAck>;
+    interrupt(req: {
+        sessionId: string;
+    }): Promise<{
+        interrupted: boolean;
+    }>;
+    stop(req: {
+        sessionId: string;
+    }): Promise<{
+        stopped: boolean;
+    }>;
+    respondToToolPermission(req: ToolPermissionDecision): Promise<{
+        ok: boolean;
+    }>;
+    /** Queue family (CC LocalSessionManager semantics; booleans, false = too-late/no-op form). */
+    cancelQueuedMessage(sessionId: string, userMessageUuid: string): Promise<boolean>;
+    /** CC signature: (sessionId, uuid, TARGET uuid) — position the message relative to the target
+     *  (after it when moving down, before it when moving up); NOT an index. */
+    reorderQueuedMessage(sessionId: string, userMessageUuid: string, targetUserMessageUuid: string): Promise<boolean>;
+    promoteQueuedMessage(sessionId: string, userMessageUuid: string): Promise<boolean>;
+    /** CC census verbs (batch 4). setFocusedSession(null) clears focus. */
+    setFocusedSession(sessionId: string | null): Promise<{
+        ok: boolean;
+    }>;
+    setModel(sessionId: string, model: string): Promise<boolean>;
+    getTranscript(sessionId: string): Promise<{
+        sessionId: string;
+        messages: unknown[];
+    }>;
+    searchSessions(query: string): Promise<{
+        results: SessionSearchResult[];
+    }>;
+    /** Attachment BYTE channel (红批注 web#1 的另一半). Upload first, then reference the receipt id
+     *  from `sendMessage({attachmentIds})`. Rejects (413/415/501 → thrown typed error) surface to the
+     *  renderer as-is: a shelf row that says "ready" for a file the engine never received is the
+     *  same lie as a mode badge that never crossed the wire. */
+    uploadAttachment(req: {
+        name: string;
+        mimeType?: string;
+        bytes: Uint8Array;
+    }): Promise<AttachmentUploadReceipt>;
+    /** Read-only model catalog (engine `GET /v1/models`). Empty `models` = the deployment offers no
+     *  catalog; the renderer must degrade honestly rather than fall back to a fixture list. */
+    listModels(): Promise<SeatModelCatalog>;
+    onEvent(cb: (ev: LocalSessionEvent) => void): () => void;
+    onToolPermissionRequest(cb: (req: ToolPermissionRequest) => void): () => void;
+    /** `$store$` reactive states (read + subscribe; writes go through the verbs above). */
+    sessionsStateStore: EipcStoreClient<{
+        sessions: LocalSessionRecord[];
+    }>;
+    focusedSessionStateStore: EipcStoreClient<{
+        sessionId: string | null;
+    }>;
+    settingsStateStore: EipcStoreClient<SettingsState>;
+}
+export declare function isLocalSessionRecord(s: unknown): s is LocalSessionRecord;
+export declare function isToolPermissionRequest(r: unknown): r is ToolPermissionRequest;
+/**
+ * onEvent payload validator — line-for-line FORM port of CC's `fQe`
+ * (`.vite/build/index.chunk-CnWKsyE_.js:369773`). Field-by-field mapping:
+ *  - `type`/`sessionId`: required strings (same);
+ *  - `message`: CC's minified source reads `typeof e.message<"u"` inside a comma expression whose
+ *    value is discarded — i.e. NO validation, a deliberate transcript-plane passthrough. Same here.
+ *  - `messages`: array-checked, elements `every(t=>!0)` (constant true) — array shape only. Same here.
+ *  - `error`/`errorCategory`: optional strings (same); `code`: optional number (same);
+ *  - `request`: CC gates with `S1` (ToolPermissionRequest schema) → our isToolPermissionRequest;
+ *  - `session`: CC gates with `aM` (SessionRecord schema) → our isLocalSessionRecord;
+ *  - `data`: optional string / `sources`: optional string[] / `permissionMode`: optional string /
+ *    `userMessageUuid`: optional string / `hasPreClearSession`: optional boolean (same);
+ *  - CC fields we do not emit in this batch (`tccFolderKind`/`initializationStatus`/`fsFile`/
+ *    `localMcpServers`/`refusalFallbackPrompt`) are not carried — their positions return when the
+ *    corresponding service families are ported.
+ */
+export declare function isLocalSessionEvent(v: unknown): v is LocalSessionEvent;
+export declare function isAttachmentUploadReceipt(v: unknown): v is AttachmentUploadReceipt;
+export declare function isSeatModelCatalog(v: unknown): v is SeatModelCatalog;
+export declare function isSendMessageAck(v: unknown): v is SendMessageAck;
+export declare const LOCAL_SESSIONS_SPEC: EipcServiceSpec;
+/** verb 名清单 = `LOCAL_SESSIONS_SPEC.methods` 应有的键集(逐元素相等,门里断言)。 */
+export declare const SEAT_METHOD_NAMES: readonly ["start", "sendMessage", "interrupt", "stop", "respondToToolPermission", "cancelQueuedMessage", "reorderQueuedMessage", "promoteQueuedMessage", "setFocusedSession", "setModel", "getTranscript", "searchSessions", "uploadAttachment", "listModels", "onEvent", "onToolPermissionRequest"];
+/** `$store$` 属性名清单;SPEC 的 store 键 + `"Store"` 必须逐条等于这里的名字(门里断言)。 */
+export declare const SEAT_STORE_PROPS: readonly ["sessionsStateStore", "focusedSessionStateStore", "settingsStateStore"];
+/** 事件式(main→renderer push)的 verb —— SPEC 里 `kind: "event"` 的那一撮,门里逐元素对账。 */
+export declare const SEAT_EVENT_METHOD_NAMES: readonly ["onEvent", "onToolPermissionRequest"];
+export declare const LOCAL_SESSION_EVENT_KEYS: readonly ["type", "sessionId", "message", "messages", "error", "errorCategory", "code", "request", "data", "sources", "permissionMode", "session", "userMessageUuid", "hasPreClearSession", "requestId", "outcome", "chrome"];
+export declare const TOOL_PERMISSION_REQUEST_KEYS: readonly ["requestId", "sessionId", "toolName", "toolCallId", "input", "message", "boundCallId", "boundInputHash", "createdAt"];
+export declare const LOCAL_SESSION_RECORD_KEYS: readonly ["sessionId", "engineSessionId", "model", "title", "isRunning", "createdAt", "lastActivityAt", "queuedMessages"];
+export declare const SEND_MESSAGE_REQUEST_KEYS: readonly ["sessionId", "text", "model", "userMessageUuid", "permissionMode", "attachmentIds", "reasoningEffort", "retainBackgroundProcesses", "settings"];
+export declare const TOOL_PERMISSION_DECISION_KEYS: readonly ["sessionId", "requestId", "decision", "answer", "updatedInput", "remember"];
+export declare const START_SESSION_OPTION_KEYS: readonly ["model", "title", "cwd", "excludeTools"];

package/dist/seatContract.js

@@ -0,0 +1,427 @@
+/**
+ * seatContract — desktop/web **座位 IPC 契约的单一真源**(design/159 B18,2026-07-29)。
+ *
+ * 搬迁前的形:同一份契约有**两份声明**,而且跨仓名字零重合 ——
+ *   · `sema-desktop/src/shared/localSessions.ts`  = 15 个类型 + 3 个词表常量 + 6 个校验器 + SPEC(生产端)
+ *   · `sema-web-client/ui/lib/desktop/local-sessions-transport.ts` = 9 个 `Seat*` 本地重声明(消费端)
+ * 两边名字不同 ⇒ **编译器永远不会告诉你它们漂了**。实测已经漂了(见下「漂移清单」),其中
+ * `LocalSessionEvent.outcome` 那一条是真 bug:宿主发了词、消费端的镜像里根本没有这个位,
+ * 于是「拒绝 / TTL 到点 / 人点了允许」在屏上长得一模一样 —— 正是 localSessions 自己在
+ * 「接缝记账」里写下的第 1 条,它一直没被销账的原因就是没有任何机制会让它红。
+ *
+ * 落点为什么是本包:desktop 与 web 都已经依赖 `@sema-agent/client-core`(0.11.5),而本文件是
+ * **纯类型 + 常量 + 纯谓词**,零值级 import、零 Node 内建 ⇒ 不动本包的可移植闭包(portability 门的
+ * `EXPECTED_PACKAGES_INDEX` 一个字不变)。
+ * ⚠️ 唯一一条 `import type`(`./effortWire.js` 的 `ReasoningEffort`)是**类型边**:portability 门
+ * 走值级传递闭包时按规则剥掉 type-only import(门里 `/^\s*type\b/` 那一跳),bundle 里一个字节都
+ * 不多。写成 import 而不是就地复刻那七档,是因为「座位闭集」与「wire 投影闭集」必须是**同一套词**
+ * ——复刻一份就等于埋一条只有真用户能发现的漂移(拨盘上的档在座位 lane 上静默到不了引擎)。
+ *
+ * ── 搬迁时按「真源为准」收敛的漂移(逐条,web 侧镜像 → 本文件)────────────────────────────
+ *  🔴 D1 `LocalSessionEvent.outcome` —— web 镜像整位缺席 ⇒ `tool_permission_resolved` 只会清面,
+ *      不会告诉用户为什么工具没跑。**真 bug**,本批只做「位补回来」;把词渲成可见痕迹是渲染面的活。
+ *  D2 `SendMessageRequest.permissionMode` —— web 镜像是裸 `string`,真源是闭集 `PermissionModeIntent`,
+ *      而宿主入站门 `requireOptionalPermissionMode` 是**会抛的闭集门**。今日两边词表逐字相等
+ *      (web `ComposerMode` 五档 ≡ `PERMISSION_MODE_INTENTS` 五档,已核),所以是**潜伏**不是现症:
+ *      ComposerMode 哪天加一档,裸 string 一路放行到宿主门口才抛。收敛成闭集后当天编译红。
+ *  D3 `AttachmentUploadReceipt.sha256` / `ToolPermissionRequest.createdAt` / `StartSessionOptions.cwd`
+ *      / `.excludeTools` / `LocalSessionRecord.queuedMessages`·`model`·`engineSessionId` ——
+ *      web 镜像缺位。都是「没接线」不是「接错线」(web 侧今日无消费点,已核),收敛后位在、待接。
+ *  D4 `LocalSessionEvent.request` —— 真源有这个位,**宿主从不发**(session-host 零处写 `request:`);
+ *      web 镜像没有它反而与运行时事实一致。真源保留该位(CC `fQe` 的 form 位),记在这里免得
+ *      下一棒把「web 没有」当成漏。
+ *  D5 `EipcStoreClient.getStateSync` web 侧是 optional、真源是 required;`SeatSessionDirectoryRow.createdAt`
+ *      web 侧 optional、真源 required。两条都是「更弱」方向,收敛到真源即可(宿主校验器
+ *      `isLocalSessionRecord` 本来就要求 createdAt 在场,运行时保证一直成立)。
+ *  · web 侧**没有**镜像、因而至今拿不到的面:队列三动词 / setFocusedSession / setModel /
+ *    focusedSessionState / settingsState / `CHROME_EVENT_KINDS` / `ATTACHMENT_IDS_PER_TASK_CAP`。
+ *    本文件导出后它们对 web 首次可见(接不接线是渲染面的决定)。
+ *
+ * ── 沿革(以下正文自 sema-desktop/src/shared/localSessions.ts 逐字迁入)──────────────────────
+ * LocalSessions — the desktop host's session service contract, FORM-ported from the CC desktop
+ * app's `claude.web / LocalSessions` eipc interface (212 methods there; FIRST BATCH here = the four
+ * families clay scoped: session lifecycle / event subscription / interrupt / approvals).
+ *
+ * Naming: CC ns `claude.web` → `sema.web` (brand table). Method names kept verbatim where the CC
+ * method exists (`start`/`stop`/`interrupt`/`sendMessage`/`onEvent`/`onToolPermissionRequest`/
+ * `respondToToolPermission` are all real CC LocalSessions methods — see the 854-channel census).
+ *
+ * Event payload contract: ported in FORM from CC's `onEvent` runtime validator `fQe`
+ * (unpack `.vite/build/index.chunk-CnWKsyE_.js:369773`). The load-bearing property we keep
+ * byte-faithful ([1832] axiom 2, independently proven by CC's own code): on an otherwise
+ * fully-schema'd IPC surface, the `message`/`messages` fields (= CC session-vocabulary SDKMessage
+ * bodies, our transcript plane) are UNVALIDATED passthrough positions, while every other field is a
+ * neutral typed position. Our implementation体 differs (sema wire via @sema-agent/sdk +
+ * @sema-agent/client-core), the contract shape does not.
+ */
+/**
+ * The resolution words the host currently puts on `tool_permission_resolved.outcome` ([1947] 红③).
+ * DOCUMENTARY + test anchor only — the gate does NOT enforce membership (see the field's doc: a
+ * closed set would fail-close the whole event on the day the wire grows a word). Grouped by family:
+ *  - tool approval (wire `ToolApprovalFrame.outcome`, + our own settle sweep): allowed/denied/expired
+ *  - question      (wire `QuestionFrame.outcome`):                             answered/unanswered
+ *  - elicitation   (wire `ElicitationFrame.action`):                           accept/decline/cancel
+ */
+export const HITL_RESOLUTION_OUTCOMES = [
+    "allowed",
+    "denied",
+    "expired",
+    "answered",
+    "unanswered",
+    "accept",
+    "decline",
+    "cancel",
+];
+/**
+ * 接缝记账 — what the HOST now guarantees vs what a RENDERER still owes ([1947] 红③/红④ split).
+ *
+ * The host half is done and pinned by desktop's `scripts/run-hitl-frame-transit-fence-test.mjs`:
+ * every live ask family reaches `onToolPermissionRequest` with its own requestId domain, every
+ * resolution reaches `onEvent` with an `outcome`, and every decision routes to the right wire verb.
+ *
+ * The renderer half is where these become VISIBLE, and until it lands the data is present but
+ * unread (stating it plainly so nobody reads "the host emits it" as "the user sees it"):
+ *  1. `tool_permission_resolved.outcome` — an `expired` / `denied` / `unanswered` resolution must
+ *     leave a visible refusal trace. Today the seat transport clears the surface and drops the
+ *     word, so a refusal is still indistinguishable from an approval on screen.
+ *     🔴 B18(2026-07-29)查明这条一直不销账的**机制原因**:web 侧的镜像类型里连 `outcome` 这个
+ *     位都没有,所以「没读」在两边都编译得过。本批把位收进真源 = 让它至少可见于类型面。
+ *  2. `toolCallId` — now real (not null), so an approval can be anchored to the tool card that
+ *     raised it instead of "the most recent tool_start" (an anchor that lands on the wrong card
+ *     when a prior tool is still running).
+ *  3. `question:` rows need NO new renderer code: they arrive as `toolName: "AskUserQuestion"` with
+ *     `input.questions`, which is exactly what the seat's ask-user-question surface already reads,
+ *     and its answer envelope is exactly what this host expects back.
+ *  4. 座位 wire 补齐批 (2026-07-28) closed two entries that used to live here as "如实,未做":
+ *     `permissionMode` now has a seat on `sendMessage` (was: the composer's Plan badge never
+ *     crossed and the turn ran with the engine default), and the attachment BYTE channel exists
+ *     (`uploadAttachment` + `sendMessage.attachmentIds`) — so a seat renderer no longer has to
+ *     simulate "attachment ready" for a file nothing received. What is still NOT here, stated
+ *     plainly: plan REVISE feedback text (the decide face has no `reason` seat, so revise maps to
+ *     a bare deny) and a per-session `permissionMode` write (the wire's is per-TURN only).
+ *  5. `elicit:` rows have no dedicated surface yet: they fall through to the generic approval card,
+ *     which shows the MCP server's prompt and can accept/decline but CANNOT collect form values.
+ *     A real form surface (built from `input.requestedSchema`) is the renderer's remaining piece;
+ *     until then an approve carries no content — the host never invents form values. That generic
+ *     card also offers "Always allow (this session)", which this domain has no concept of: the host
+ *     ignores `remember` here rather than pretend, so the renderer should hide that control for
+ *     `elicit:` rows (a button that changes nothing is the false-affordance family again).
+ */
+/** Chrome arms wired to the renderer position (batch 4); other arms stay host-side on the ring. */
+export const CHROME_EVENT_KINDS = [
+    "panel_task",
+    "notification_terminal",
+    "prompt_suggestions",
+    "subagent_lifecycle",
+];
+/** The closed set the inbound gate checks. CLOSED deliberately, unlike `outcome` above: this word
+ *  ORIGINATES in our own renderer and goes OUT to a wire that 400s on anything else, so an unknown
+ *  value is a local bug we want reported at the door — not an unknown future wire word we must
+ *  tolerate. (The direction of travel is what decides open vs closed, not the field's shape.) */
+export const PERMISSION_MODE_INTENTS = [
+    "default",
+    "plan",
+    "acceptEdits",
+    "bypassPermissions",
+    "auto",
+];
+/** Per-task attachment cap — the server's own limit (`attachmentIds` > 16 ⇒ 400). Gated here so the
+ *  seat gets a precise local error instead of a wire 400 halfway through a turn. */
+export const ATTACHMENT_IDS_PER_TASK_CAP = 16;
+/** The per-turn `reasoningEffort` accept-set — core's ThinkingLevel tiers, re-exported from the
+ *  package's own wire projection (`effortWire.ReasoningEffort`) rather than re-typed here.
+ *
+ *  CLOSED for the same reason `PERMISSION_MODE_INTENTS` is: the word ORIGINATES in our own composer
+ *  and travels OUT to a wire that 400s (fail-loud) on an unknown tier — so an unknown value is a
+ *  local bug we want reported at the seat's door, not a future wire word to tolerate. `ultracode` is
+ *  deliberately NOT a tier here: in CC it is a standalone `settings.ultracode` preset boolean that
+ *  COEXISTS with `xhigh` (see `SeatTurnSettings`), and folding it into this axis is exactly how the
+ *  orchestration axis gets eaten by the reasoning axis. */
+export const SEAT_REASONING_EFFORTS = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+];
+export const SEAT_TURN_SETTINGS_KEYS = ["ultracode"];
+// ───────────────────────────── validators (CC dual-gate posture) ─────────────────────────────
+export function isLocalSessionRecord(s) {
+    const e = s;
+    return !(!e ||
+        typeof e !== "object" ||
+        typeof e.sessionId !== "string" ||
+        (typeof e.engineSessionId !== "undefined" && typeof e.engineSessionId !== "string") ||
+        (typeof e.model !== "undefined" && typeof e.model !== "string") ||
+        (typeof e.title !== "undefined" && typeof e.title !== "string") ||
+        typeof e.isRunning !== "boolean" ||
+        typeof e.createdAt !== "string" ||
+        (typeof e.lastActivityAt !== "undefined" && typeof e.lastActivityAt !== "string") ||
+        (typeof e.queuedMessages !== "undefined" &&
+            !(Array.isArray(e.queuedMessages) &&
+                e.queuedMessages.every((q) => !!q && typeof q.uuid === "string" && typeof q.text === "string"))));
+}
+export function isToolPermissionRequest(r) {
+    const e = r;
+    return !(!e ||
+        typeof e !== "object" ||
+        typeof e.requestId !== "string" ||
+        typeof e.sessionId !== "string" ||
+        (typeof e.toolName !== "undefined" && e.toolName !== null && typeof e.toolName !== "string") ||
+        (typeof e.toolCallId !== "undefined" && e.toolCallId !== null && typeof e.toolCallId !== "string") ||
+        // `input` is the untrusted redacted payload — passthrough (render-only), like CC's request args.
+        (typeof e.message !== "undefined" && typeof e.message !== "string") ||
+        (typeof e.boundCallId !== "undefined" && typeof e.boundCallId !== "string") ||
+        (typeof e.boundInputHash !== "undefined" && typeof e.boundInputHash !== "string") ||
+        (typeof e.createdAt !== "undefined" && typeof e.createdAt !== "number"));
+}
+/**
+ * onEvent payload validator — line-for-line FORM port of CC's `fQe`
+ * (`.vite/build/index.chunk-CnWKsyE_.js:369773`). Field-by-field mapping:
+ *  - `type`/`sessionId`: required strings (same);
+ *  - `message`: CC's minified source reads `typeof e.message<"u"` inside a comma expression whose
+ *    value is discarded — i.e. NO validation, a deliberate transcript-plane passthrough. Same here.
+ *  - `messages`: array-checked, elements `every(t=>!0)` (constant true) — array shape only. Same here.
+ *  - `error`/`errorCategory`: optional strings (same); `code`: optional number (same);
+ *  - `request`: CC gates with `S1` (ToolPermissionRequest schema) → our isToolPermissionRequest;
+ *  - `session`: CC gates with `aM` (SessionRecord schema) → our isLocalSessionRecord;
+ *  - `data`: optional string / `sources`: optional string[] / `permissionMode`: optional string /
+ *    `userMessageUuid`: optional string / `hasPreClearSession`: optional boolean (same);
+ *  - CC fields we do not emit in this batch (`tccFolderKind`/`initializationStatus`/`fsFile`/
+ *    `localMcpServers`/`refusalFallbackPrompt`) are not carried — their positions return when the
+ *    corresponding service families are ported.
+ */
+export function isLocalSessionEvent(v) {
+    const e = v;
+    return !(!e ||
+        typeof e !== "object" ||
+        typeof e.type !== "string" ||
+        typeof e.sessionId !== "string" ||
+        // `message`: intentionally unvalidated passthrough (see doc above — CC fQe does the same).
+        (typeof e.messages !== "undefined" && !Array.isArray(e.messages)) ||
+        (typeof e.error !== "undefined" && typeof e.error !== "string") ||
+        (typeof e.errorCategory !== "undefined" && typeof e.errorCategory !== "string") ||
+        (typeof e.code !== "undefined" && typeof e.code !== "number") ||
+        (typeof e.request !== "undefined" && !isToolPermissionRequest(e.request)) ||
+        (typeof e.data !== "undefined" && typeof e.data !== "string") ||
+        (typeof e.sources !== "undefined" &&
+            !(Array.isArray(e.sources) && e.sources.every((t) => typeof t === "string"))) ||
+        (typeof e.permissionMode !== "undefined" && typeof e.permissionMode !== "string") ||
+        (typeof e.session !== "undefined" && !isLocalSessionRecord(e.session)) ||
+        (typeof e.userMessageUuid !== "undefined" && typeof e.userMessageUuid !== "string") ||
+        (typeof e.hasPreClearSession !== "undefined" && typeof e.hasPreClearSession !== "boolean") ||
+        (typeof e.requestId !== "undefined" && typeof e.requestId !== "string") ||
+        // `outcome`: type-checked only, NOT membership-checked (see the field doc — an unknown future
+        // wire word must reach the renderer as "settled, reason unknown", never take the event down).
+        (typeof e.outcome !== "undefined" && typeof e.outcome !== "string") ||
+        (typeof e.chrome !== "undefined" &&
+            !(!!e.chrome &&
+                typeof e.chrome === "object" &&
+                typeof e.chrome.kind === "string" &&
+                CHROME_EVENT_KINDS.includes(e.chrome.kind) &&
+                // lane discipline first-class ([1617] family): a chrome arm always carries its LaneProof.
+                !!e.chrome.laneProof)));
+}
+export function isAttachmentUploadReceipt(v) {
+    const e = v;
+    return !(!e ||
+        typeof e !== "object" ||
+        typeof e.id !== "string" ||
+        typeof e.name !== "string" ||
+        typeof e.mime !== "string" ||
+        typeof e.sha256 !== "string" ||
+        typeof e.sizeBytes !== "number");
+}
+export function isSeatModelCatalog(v) {
+    const e = v;
+    return !(!e ||
+        typeof e !== "object" ||
+        !Array.isArray(e.models) ||
+        !e.models.every((m) => !!m &&
+            typeof m === "object" &&
+            typeof m.id === "string" &&
+            ["undefined", "string"].includes(typeof m.name) &&
+            ["undefined", "string"].includes(typeof m.provider) &&
+            ["undefined", "number"].includes(typeof m.contextWindow) &&
+            ["undefined", "number"].includes(typeof m.maxOutputTokens)) ||
+        (typeof e.defaultId !== "undefined" && typeof e.defaultId !== "string"));
+}
+export function isSendMessageAck(v) {
+    const e = v;
+    return !(!e ||
+        typeof e !== "object" ||
+        typeof e.sessionId !== "string" ||
+        typeof e.userMessageUuid !== "string" ||
+        (typeof e.queued !== "undefined" && typeof e.queued !== "boolean"));
+}
+// ───────────────────────────── service spec (eipc registration table) ─────────────────────────────
+export const LOCAL_SESSIONS_SPEC = {
+    ns: "sema.web",
+    service: "LocalSessions",
+    methods: {
+        start: { kind: "invoke", validate: isLocalSessionRecord },
+        sendMessage: { kind: "invoke", validate: isSendMessageAck },
+        interrupt: {
+            kind: "invoke",
+            validate: (v) => !!v && typeof v.interrupted === "boolean",
+        },
+        stop: {
+            kind: "invoke",
+            validate: (v) => !!v && typeof v.stopped === "boolean",
+        },
+        respondToToolPermission: {
+            kind: "invoke",
+            validate: (v) => !!v && typeof v.ok === "boolean",
+        },
+        // Queue family — CC returns bare booleans (false = too-late/no-op), same here.
+        cancelQueuedMessage: { kind: "invoke", validate: (v) => typeof v === "boolean" },
+        reorderQueuedMessage: { kind: "invoke", validate: (v) => typeof v === "boolean" },
+        promoteQueuedMessage: { kind: "invoke", validate: (v) => typeof v === "boolean" },
+        setFocusedSession: {
+            kind: "invoke",
+            validate: (v) => !!v && typeof v.ok === "boolean",
+        },
+        setModel: { kind: "invoke", validate: (v) => typeof v === "boolean" },
+        getTranscript: {
+            kind: "invoke",
+            // messages = the transcript-plane passthrough batch (fQe `messages` posture: array-checked,
+            // elements deliberately unvalidated — they are CC SDKMessage bodies).
+            validate: (v) => !!v &&
+                typeof v.sessionId === "string" &&
+                Array.isArray(v.messages),
+        },
+        searchSessions: {
+            kind: "invoke",
+            validate: (v) => !!v &&
+                Array.isArray(v.results) &&
+                v.results.every((r) => !!r &&
+                    typeof r.sessionId === "string" &&
+                    Array.isArray(r.matches) &&
+                    r.matches.every((m) => !!m && typeof m.snippet === "string")),
+        },
+        uploadAttachment: { kind: "invoke", validate: isAttachmentUploadReceipt },
+        listModels: { kind: "invoke", validate: isSeatModelCatalog },
+        onEvent: { kind: "event", validate: isLocalSessionEvent },
+        onToolPermissionRequest: { kind: "event", validate: isToolPermissionRequest },
+    },
+    stores: {
+        sessionsState: {
+            validate: (v) => !!v &&
+                Array.isArray(v.sessions) &&
+                v.sessions.every((s) => isLocalSessionRecord(s)),
+        },
+        focusedSessionState: {
+            validate: (v) => {
+                const s = v;
+                return !!v && (s.sessionId === null || typeof s.sessionId === "string");
+            },
+        },
+        settingsState: {
+            validate: (v) => {
+                const s = v;
+                return (!!v &&
+                    (s.defaultModel === null || typeof s.defaultModel === "string") &&
+                    (typeof s.engineVersion === "undefined" || typeof s.engineVersion === "string") &&
+                    (typeof s.dataRoot === "undefined" || typeof s.dataRoot === "string"));
+            },
+        },
+    },
+};
+/** verb 名清单 = `LOCAL_SESSIONS_SPEC.methods` 应有的键集(逐元素相等,门里断言)。 */
+export const SEAT_METHOD_NAMES = [
+    "start",
+    "sendMessage",
+    "interrupt",
+    "stop",
+    "respondToToolPermission",
+    "cancelQueuedMessage",
+    "reorderQueuedMessage",
+    "promoteQueuedMessage",
+    "setFocusedSession",
+    "setModel",
+    "getTranscript",
+    "searchSessions",
+    "uploadAttachment",
+    "listModels",
+    "onEvent",
+    "onToolPermissionRequest",
+];
+/** `$store$` 属性名清单;SPEC 的 store 键 + `"Store"` 必须逐条等于这里的名字(门里断言)。 */
+export const SEAT_STORE_PROPS = [
+    "sessionsStateStore",
+    "focusedSessionStateStore",
+    "settingsStateStore",
+];
+/** 事件式(main→renderer push)的 verb —— SPEC 里 `kind: "event"` 的那一撮,门里逐元素对账。 */
+export const SEAT_EVENT_METHOD_NAMES = ["onEvent", "onToolPermissionRequest"];
+// ── payload 键集镜像(与各自 interface 之间有类型钉,不可能漂)────────────────────────────────
+export const LOCAL_SESSION_EVENT_KEYS = [
+    "type",
+    "sessionId",
+    "message",
+    "messages",
+    "error",
+    "errorCategory",
+    "code",
+    "request",
+    "data",
+    "sources",
+    "permissionMode",
+    "session",
+    "userMessageUuid",
+    "hasPreClearSession",
+    "requestId",
+    "outcome",
+    "chrome",
+];
+export const TOOL_PERMISSION_REQUEST_KEYS = [
+    "requestId",
+    "sessionId",
+    "toolName",
+    "toolCallId",
+    "input",
+    "message",
+    "boundCallId",
+    "boundInputHash",
+    "createdAt",
+];
+export const LOCAL_SESSION_RECORD_KEYS = [
+    "sessionId",
+    "engineSessionId",
+    "model",
+    "title",
+    "isRunning",
+    "createdAt",
+    "lastActivityAt",
+    "queuedMessages",
+];
+export const SEND_MESSAGE_REQUEST_KEYS = [
+    "sessionId",
+    "text",
+    "model",
+    "userMessageUuid",
+    "permissionMode",
+    "attachmentIds",
+    // 2026-07-29(web 收编第一批②):三位补齐。此前座位 lane **结构性**拿不到它们 —— 闭集就是
+    // 载体本身,不在集里 = 那个决定在这条 lane 上根本没有位置可放。
+    "reasoningEffort",
+    "retainBackgroundProcesses",
+    "settings",
+];
+export const TOOL_PERMISSION_DECISION_KEYS = [
+    "sessionId",
+    "requestId",
+    "decision",
+    "answer",
+    "updatedInput",
+    "remember",
+];
+export const START_SESSION_OPTION_KEYS = ["model", "title", "cwd", "excludeTools"];
+const _seatContractPins = [
+    true, true, true, true, true, true, true, true, true,
+    true, true, true, true, true, true, true, true,
+    true, true,
+];
+void _seatContractPins;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/client-core",
-  "version": "0.11.5",
+  "version": "0.11.7",
   "description": "Client-side session runtime shared by every sema human client (TUI / web / desktop): sema wire frames (AgentEvent) -> CC session vocabulary (SDKMessage) with dual-plane output (transcript/chrome), deterministic transcript ids, lane discipline as a type, and the notification/dedup ledgers. Every CC-skin shape is collected here so the wire itself stays neutral. Blackboard [1832] design axioms; [1651]/[1652]/[1653] signed seam design. Renamed from @sema-agent/wire-cc-adapter (0.1.x).",
   "license": "MIT",
   "type": "module",