@sema-agent/client-core 0.101.0 → 0.103.0

package/dist/seatContract.js

@@ -5,6 +5,7 @@ import { SETTINGS_MODEL_API_WORDS } from "./generated/settingsSchemaTables.js";
 import { PROBE_VERDICTS } from "./modelCapabilityProbe.js";
 import { guardedRead, ownDataField, ownDataRefusalKeyOf, ownSendableField, readOwnDataValue } from "./ownKey.js";
 import { MCP_LIVENESS_STATES } from "./mcpLiveness.js";
+import { THINKING_LATCH_EVENTS, THINKING_LATCH_ROW_WORDS } from "./thinkingLatchWords.js";
 const bad = (reason, field) => field === undefined ? { reason } : { reason, field };
 const nested = (prefix, verdict) => {
     const path = verdict.field === undefined
@@ -158,8 +159,10 @@ const oneOfRule = (label, words) => ruleOf(label, (v) => typeof v === "string" &
 const R_STR = ruleOf("string", (v) => typeof v === "string");
 const R_NONEMPTY = ruleOf("non-empty string", (v) => typeof v === "string" && v.length > 0);
 const R_BOOL = ruleOf("boolean", (v) => typeof v === "boolean");
+const R_THINKING_LATCH_ROW = oneOfRule("latch word", THINKING_LATCH_ROW_WORDS);
 const R_TRUE = ruleOf("true", (v) => v === true);
 const R_NUM = ruleOf("finite number", (v) => typeof v === "number" && Number.isFinite(v));
+const R_NUM0 = ruleOf("finite non-negative number", (v) => typeof v === "number" && Number.isFinite(v) && v >= 0);
 const R_INT0 = ruleOf("non-negative integer", (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0);
 const R_INT1 = ruleOf("positive integer", (v) => typeof v === "number" && Number.isSafeInteger(v) && v > 0);
 const keyWords = (k) => k
@@ -354,7 +357,7 @@ export function readSeatStreamDelta(message) {
         return Object.freeze({ kind: "malformed" });
     }
 }
-export const SEAT_CAPABILITY_NAMES = Object.freeze(["pickFolder", "rewind", "recents", "patchSession", "devices", "engineTarget", "onboard", "mcpToolToggles"]);
+export const SEAT_CAPABILITY_NAMES = Object.freeze(["pickFolder", "rewind", "recents", "patchSession", "devices", "engineTarget", "onboard", "mcpToolToggles", "thinkingLatch"]);
 const notReported = () => Object.freeze({ kind: "not_reported" });
 const malformedReading = () => Object.freeze({ kind: "malformed" });
 const reported = (available) => Object.freeze({ kind: "reported", available });
@@ -430,6 +433,7 @@ const SEAT_CAPABILITY_PHRASES = Object.freeze({
     engineTarget: Object.freeze({ action: "Switching engines", ability: "switch engines", support: "engine-switching support" }),
     onboard: Object.freeze({ action: "Model setup", ability: "add models", support: "model-setup support" }),
     mcpToolToggles: Object.freeze({ action: "Per-tool switching", ability: "toggle tools", support: "per-tool switches" }),
+    thinkingLatch: Object.freeze({ action: "Switching thinking", ability: "switch thinking", support: "thinking-switch support" }),
 });
 export function seatCapabilityUnavailableDetail(name, reading) {
     const phrase = Object.hasOwn(SEAT_CAPABILITY_PHRASES, name)
@@ -556,6 +560,7 @@ export const SEAT_TURN_SETTINGS_ORIGINS = Object.freeze({
 export const SEAT_REWIND_INTENT_KEYS = ["mode", "targetMessageUuid"];
 export const ATTACHMENT_UPLOAD_REQUEST_KEYS = ["name", "mimeType", "bytes"];
 export const SESSION_ROW_PATCH_REQUEST_KEYS = Object.freeze(["sessionId", "title", "pinned"]);
+const SET_THINKING_LATCH_REQUEST_KEYS = Object.freeze(["sessionId", "event"]);
 export const SESSION_SEARCH_RESULT_KEYS = ["sessionId", "title", "matches"];
 export const GET_TRANSCRIPT_RESULT_KEYS = ["sessionId", "messages"];
 const DEVICE_REFUSED_SPEC = { status: reqF(R_INT0), errorCode: optF(R_STR), message: optF(R_STR) };
@@ -878,6 +883,11 @@ function mcpPanelLivenessArms() {
     return arms;
 }
 const MCP_PANEL_LIVENESS_VIEW = armsRule("mcp liveness", "state", mcpPanelLivenessArms());
+const MCP_PANEL_AUTHORIZATION = shapeRule("mcp authorization", {
+    reason: reqF(R_NONEMPTY),
+    authorizeUrl: optF(R_NONEMPTY),
+    resourceMetadataUrl: optF(R_NONEMPTY),
+});
 const MCP_PANEL_LEG_ENTRY = shapeRule("leg entry", {
     name: reqF(R_NONEMPTY),
     status: reqF(R_NONEMPTY),
@@ -888,6 +898,8 @@ const MCP_PANEL_LEG_ENTRY = shapeRule("leg entry", {
     httpStatus: optF(R_NUM),
     liveness: optF(MCP_PANEL_LIVENESS_VIEW),
     livenessUnreadable: optF(R_TRUE),
+    authorization: optF(MCP_PANEL_AUTHORIZATION),
+    authorizationUnreadable: optF(R_TRUE),
 });
 const MCP_PANEL_LAST_LEG = shapeRule("last leg", {
     runId: reqF(R_NONEMPTY),
@@ -971,6 +983,12 @@ const checkLocalSessionRecord = seatCheck((s) => {
     if (!isAbsent(pinned) && typeof pinned !== "boolean") {
         return bad("pinned must be a boolean when present (absent = not pinned or unknown)", "pinned");
     }
+    const latch = own(s, "thinkingLatch");
+    if (!isAbsent(latch)) {
+        const verdict = R_THINKING_LATCH_ROW.test(latch, "thinkingLatch");
+        if (verdict !== true)
+            return verdict;
+    }
     return true;
 });
 export function isLocalSessionRecord(s) {
@@ -1059,6 +1077,8 @@ const RETRY_COMMON_SPEC = {
     providerConditionSource: optF(R_STR),
     elapsedMs: optF(R_NUM),
     timeoutMs: optF(R_NUM),
+    sleptMs: optF(R_NUM0),
+    waitSegment: optF(R_NONEMPTY),
 };
 const RETRY_STATUS = armsRule("retry status", "kind", {
     stalled: { ...RETRY_COMMON_SPEC, detail: optF(R_STR) },
@@ -1438,6 +1458,14 @@ export const checkSessionRowPatchRequest = seatCheck((v) => {
 export function isSessionRowPatchRequest(v) {
     return checkSessionRowPatchRequest(v) === true;
 }
+const checkSetThinkingLatchShape = seatShapeCheck(shapeRule("latch request", {
+    sessionId: reqF(R_NONEMPTY),
+    event: reqF(oneOfRule("latch event", THINKING_LATCH_EVENTS)),
+}));
+export const checkSetThinkingLatchRequest = seatCheck((v) => isPlainRecord(v) ? checkSetThinkingLatchShape(v) : bad("setThinkingLatch request is not a plain object"));
+export function isSetThinkingLatchRequest(v) {
+    return checkSetThinkingLatchRequest(v) === true;
+}
 const checkSendMessageAck = seatCheck((v) => {
     if (!isPlainRecord(v))
         return bad("sendMessage ack is not a plain object");
@@ -1609,6 +1637,7 @@ export const LOCAL_SESSIONS_SPEC = {
         readSessionMcpPanel: { kind: "invoke", check: checkSessionMcpPanelResult },
         listMcpToolToggles: { kind: "invoke", check: checkMcpToolTogglesResult },
         setMcpToolToggle: { kind: "invoke", check: checkOkAck },
+        setThinkingLatch: { kind: "invoke", check: checkOkAck },
         onEvent: { kind: "event", check: checkLocalSessionEvent },
         onToolPermissionRequest: { kind: "event", check: checkToolPermissionRequest },
     },
@@ -1656,6 +1685,7 @@ export const SEAT_METHOD_NAMES = [
     "readSessionMcpPanel",
     "listMcpToolToggles",
     "setMcpToolToggle",
+    "setThinkingLatch",
     "onEvent",
     "onToolPermissionRequest",
 ];
@@ -1714,6 +1744,7 @@ export const LOCAL_SESSION_RECORD_KEYS = [
     "queuedMessages",
     "parked",
     "pinned",
+    "thinkingLatch",
 ];
 export const SEND_MESSAGE_REQUEST_KEYS = [
     "sessionId",
@@ -1758,7 +1789,7 @@ export const SEAT_VALIDATOR_KEY_COVERAGE = {
     LocalSessionRecord: {
         guard: "isLocalSessionRecord",
         check: checkLocalSessionRecord,
-        validated: ["sessionId", "engineSessionId", "model", "title", "cwd", "isRunning", "createdAt", "lastActivityAt", "queuedMessages", "parked", "pinned"],
+        validated: ["sessionId", "engineSessionId", "model", "title", "cwd", "isRunning", "createdAt", "lastActivityAt", "queuedMessages", "parked", "pinned", "thinkingLatch"],
         unchecked: [],
     },
     ToolPermissionRequest: {
@@ -1882,6 +1913,12 @@ export const SEAT_VALIDATOR_KEY_COVERAGE = {
         validated: ["sessionId", "title", "pinned"],
         unchecked: [],
     },
+    SetThinkingLatchRequest: {
+        guard: "isSetThinkingLatchRequest",
+        check: checkSetThinkingLatchRequest,
+        validated: ["sessionId", "event"],
+        unchecked: [],
+    },
     ApplyModelConfigResult: {
         check: checkApplyModelConfigResult,
         validated: ["ok", "requiresRestart", "reason", "detail"],
@@ -1935,7 +1972,7 @@ export const SEAT_VALIDATOR_KEY_COVERAGE = {
     },
     SeatCapabilitiesState: {
         check: checkSeatCapabilitiesState,
-        validated: ["pickFolder", "rewind", "recents", "patchSession", "devices", "engineTarget", "onboard", "mcpToolToggles"],
+        validated: ["pickFolder", "rewind", "recents", "patchSession", "devices", "engineTarget", "onboard", "mcpToolToggles", "thinkingLatch"],
         unchecked: [],
     },
     RecentFoldersResult: {
@@ -2006,7 +2043,7 @@ export const SEAT_VALIDATOR_COVERAGE_EXEMPT = [
     {
         label: "PickFolderResult",
         check: checkPickFolderResult,
-        why: "载荷是**串或 null**(选中的路径 / 用户取消,CC-469),没有键面 ⇒ `keyof` 覆盖表在它身上无从谈起。判别力由 run-seat-wave2-test.mjs ST1-1 承担:认 null 与非空串、拒空串 / 数 / undefined / 对象 / 布尔五形。",
+        why: "载荷是**串或 null**(选中的路径 / 用户取消,CC-469),没有键面 ⇒ `keyof` 覆盖表在它身上无从谈起。判别力由对应的座位契约测试套承担:认 null 与非空串、拒空串 / 数 / undefined / 对象 / 布尔五形。",
     },
     {
         label: "BooleanAck",
@@ -2017,10 +2054,10 @@ export const SEAT_VALIDATOR_COVERAGE_EXEMPT = [
         label: "LaneProof",
         check: (v) => checkLaneProof(v, "laneProof"),
         why: "判别式联合:必填键面随 `lane` 臂而变(subagent 要 parentToolCallId、workflow 要 via+key),而覆盖表的方法是「一个最小合法体 + 逐键投毒」—— 那套方法在它身上没有判别力(main 臂对另外两臂的伴随位本来就不该拒,投毒过了不代表漏校)。" +
-            "🔴 FIX④(2026-08-07 订正):本条此前自称判别力由「F 段**逐臂**投毒(空对象 / 非对象 / **未登记车道词**)」承担 —— 全树实扫,那三样里只有**空对象**与**非对象**真的存在(run-seat-contract-keys-test.mjs F 段)," +
+            "🔴 (2026-08-07 订正)本条此前自称判别力由「**逐臂**投毒(空对象 / 非对象 / **未登记车道词**)」承担 —— 全树实扫,那三样里只有**空对象**与**非对象**真的存在(座位契约键测试套的逐臂投毒段)," +
             "「未登记车道词」实际只钉了 `lane: 7`(非串,证明不了闭集成员判定在场),「逐臂」(subagent 缺 parentToolCallId / workflow 缺 via+key)则是**零覆盖**。也就是说这条豁免曾经拿三件不存在的判据给自己背书。" +
             "现势(判据锚在真存在的东西上):① `LANE_PROOF_LANE_TUPLE` ⇄ seam.ts 车道联合的双向 `Covers`(本文件 `_seatContractPins`,加车道不跟 ⇒ 编译红);" +
-            "② run-client-core-pure-test.mjs **FIX7 段 ④** —— 未登记车道词 / subagent 缺伴随位 / workflow 缺 via 或 key 三条投毒 + 两条逐臂正控 + 一条「main 臂不被过紧误拒」负控,全部直接喂本条的 `check`。",
+            "② 本包纯测试套的投毒段 —— 未登记车道词 / subagent 缺伴随位 / workflow 缺 via 或 key 三条投毒 + 两条逐臂正控 + 一条「main 臂不被过紧误拒」负控,全部直接喂本条的 `check`。",
     },
 ];
 const _seatContractPins = [
@@ -2050,6 +2087,8 @@ const _seatContractPins = [
     true, true, true,
     true,
     true, true, true,
+    true, true, true, true, true, true,
+    true, true, true,
     true, true,
 ];
 void _seatContractPins;

package/dist/sessionBackground.d.ts

@@ -0,0 +1,165 @@
+import type { AgentClient, AgentEvent, TaskRequest } from '@sema-agent/sdk';
+import { type EnvLike } from './hostEnv.js';
+import type { UiLanguage } from './env/uiLanguage.js';
+export type SessionBackgroundableReading = {
+    readonly kind: 'advertised';
+} | {
+    readonly kind: 'declined';
+} | {
+    readonly kind: 'not_reported';
+} | {
+    readonly kind: 'unreadable';
+} | {
+    readonly kind: 'unobserved';
+};
+export declare function projectSessionBackgroundable(caps: {} | null | undefined): SessionBackgroundableReading | undefined;
+export declare function readSessionBackgroundable(baseUrl?: string | undefined): SessionBackgroundableReading;
+export type InteractiveEngineLane = 'self-spawned' | 'external';
+export interface InteractiveEngineWireInit {
+    readonly baseUrl: string;
+    readonly lane: InteractiveEngineLane;
+    readonly tasks: Pick<AgentClient['tasks'], 'stream'>;
+    readonly runs: Pick<AgentClient['runs'], 'events' | 'get'>;
+}
+export interface InteractiveEngineWire {
+    readonly baseUrl: string;
+    readonly lane: InteractiveEngineLane;
+}
+type SdkStreamOptions = Parameters<AgentClient['tasks']['stream']>[1];
+type SdkEventsOptions = NonNullable<Parameters<AgentClient['runs']['events']>[1]>;
+type SdkGetOptions = NonNullable<Parameters<AgentClient['runs']['get']>[1]>;
+type SdkRunRecord = Awaited<ReturnType<AgentClient['runs']['get']>>;
+export type OpeningPhase = 'opening' | 'bound' | 'running' | 'ended-unstarted' | 'finished' | 'stream-ended' | 'handing-off' | 'handed-off' | 'engine-ended';
+export interface OpeningRecordView {
+    readonly phase: OpeningPhase;
+    readonly inconsistent: boolean;
+    readonly capsGenAtBind: number | undefined;
+    readonly stopRequested: boolean;
+    readonly stamped: boolean;
+    readonly postureReason: InteractiveDetachPostureReason;
+    readonly proof: 'loopback-self-spawned' | 'none';
+    readonly taskId: string | undefined;
+    readonly sessionId: string | undefined;
+    readonly openAsks: ReadonlyMap<string, number | undefined>;
+    readonly askUnacked: boolean;
+}
+export interface OpeningRecord extends OpeningRecordView {
+    readonly openingId: number;
+    readonly sessionKey: string | undefined;
+    phase: OpeningPhase;
+    inconsistent: boolean;
+    capsGenAtBind: number | undefined;
+    stopRequested: boolean;
+    stamped: boolean;
+    postureReason: InteractiveDetachPostureReason;
+    proof: 'loopback-self-spawned' | 'none';
+    taskId: string | undefined;
+    sessionId: string | undefined;
+    readonly openAsks: Map<string, number | undefined>;
+    askUnacked: boolean;
+    replay: boolean;
+    readonly tear: (reason: string) => void;
+}
+export interface HandedOffEntry {
+    readonly taskId: string;
+    readonly sessionKey: string;
+    state: 'running' | 'ended' | 'unconfirmed';
+    readonly stop: (cause: 'disposed' | 'engine-ended') => void;
+    readonly reconcile: () => void;
+}
+export interface WireState {
+    retired: boolean;
+    readonly baseUrl: string;
+    readonly lane: InteractiveEngineLane;
+    readonly stream: (req: TaskRequest, opts: SdkStreamOptions) => AsyncGenerator<AgentEvent>;
+    readonly events: (taskId: string, opts: SdkEventsOptions) => AsyncGenerator<AgentEvent>;
+    readonly get: (taskId: string, opts: SdkGetOptions) => Promise<SdkRunRecord>;
+    readonly bySession: Map<string, OpeningRecord>;
+    readonly byTask: Map<string, OpeningRecord>;
+    readonly order: OpeningRecord[];
+    readonly handedOff: Map<string, HandedOffEntry>;
+    nextOpeningId: number;
+}
+export declare const OPENING_RECORD_CAP = 256;
+export type OwnSlot = {
+    readonly state: 'absent';
+} | {
+    readonly state: 'unreadable';
+} | {
+    readonly state: 'data';
+    readonly value: {} | null;
+};
+export declare function ownSlotOf(o: object, key: string): OwnSlot;
+export declare function wireStateOf(wire: InteractiveEngineWire | null | undefined): WireState | undefined;
+export declare function interactiveEngineWire(init: InteractiveEngineWireInit): InteractiveEngineWire | undefined;
+export declare function retireInteractiveEngineWire(wire: InteractiveEngineWire): void;
+export interface InteractiveOpeningInput {
+    readonly sessionKey: string;
+    readonly reattachable: boolean;
+    readonly env?: EnvLike;
+}
+export type InteractiveDetachPostureReason = 'self-spawned' | 'unreadable-input' | 'retired-wire' | 'env-off' | 'not-reattachable' | 'declined' | 'unacknowledged' | 'not_reported' | 'unobserved' | 'unreadable' | 'durable-off-400';
+export interface InteractiveDetachPosture {
+    readonly stamp: boolean;
+    readonly reason: InteractiveDetachPostureReason;
+}
+export declare function interactiveDetachPosture(wire: InteractiveEngineWire, input: InteractiveOpeningInput): InteractiveDetachPosture;
+export type InteractiveStreamOptions = {
+    transientOk: true;
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+    onResponse?: (res: Response) => void;
+    idempotencyKey?: string | null;
+    heartbeatGraceMs?: number;
+};
+export declare function streamInteractiveRun(wire: InteractiveEngineWire, req: TaskRequest, opts: InteractiveStreamOptions, input: InteractiveOpeningInput): AsyncGenerator<AgentEvent>;
+export type BackgroundHandoffVerdict = {
+    readonly verdict: 'eligible';
+    readonly taskId: string;
+} | {
+    readonly verdict: 'ineligible';
+    readonly reason: BackgroundHandoffRefusal;
+    readonly cause?: InteractiveDetachPostureReason;
+} | {
+    readonly verdict: 'unknown';
+    readonly reason: BackgroundHandoffUnknown;
+};
+export type BackgroundHandoffRefusal = 'no-run' | 'stream-ended' | 'already-handed-off' | 'finished' | 'engine-replaced' | 'stopping' | 'not-stamped' | 'declined' | 'not-started' | 'awaiting-user';
+export type BackgroundHandoffUnknown = 'unreadable-input' | 'capability-unconfirmed' | 'detach-unconfirmed' | 'awaiting-user-unattributable';
+export interface HoldOwnerView {
+    readonly taskId: string | undefined;
+    readonly sessionId: string | undefined;
+}
+export interface HandoffJudgeFacts {
+    readonly inputReadable: boolean;
+    readonly wirePresent: boolean;
+    readonly wireRecognized: boolean;
+    readonly rec: OpeningRecordView | undefined;
+    readonly capability: SessionBackgroundableReading['kind'];
+    readonly capsGenerationNow: number | undefined;
+    readonly holds: readonly HoldOwnerView[];
+    readonly nowMs: number;
+}
+export declare function handoffVerdictOf(f: HandoffJudgeFacts): BackgroundHandoffVerdict;
+export interface HandoffJudgeInput {
+    readonly wire: InteractiveEngineWire | undefined;
+    readonly sessionKey: string;
+}
+export interface JudgedHandoff {
+    readonly verdict: BackgroundHandoffVerdict;
+    readonly rec: OpeningRecord | undefined;
+    readonly state: WireState | undefined;
+}
+export declare function judgeHandoff(input: HandoffJudgeInput | null | undefined): JudgedHandoff;
+export declare function backgroundHandoffEligibility(input: {
+    readonly wire: InteractiveEngineWire | undefined;
+    readonly sessionKey: string;
+}): BackgroundHandoffVerdict;
+export declare function backgroundHandoffSentence(v: BackgroundHandoffVerdict, lang?: UiLanguage): string | undefined;
+export interface InteractiveStopFacts {
+    readonly detachArmed: boolean;
+    readonly handedOff: boolean;
+}
+export declare function interactiveStopFacts(wire: InteractiveEngineWire | undefined, taskId: string): InteractiveStopFacts;
+export declare function noteInteractiveStopRequested(wire: InteractiveEngineWire, taskId: string): 'withheld' | 'proceed';
+export {};