@sema-agent/client-core 0.100.0 → 0.102.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
@@ -62,7 +63,7 @@ const firstAccessorPath = (root) => {
             const at = path === "" ? k : `${path}.${k}`;
             if (!Object.hasOwn(d, "value"))
                 return at;
-            stack.push([d.value, at]);
+            Object.defineProperty(stack, stack.length, { value: [d.value, at], writable: true, enumerable: true, configurable: true });
         }
     }
     return undefined;
@@ -158,6 +159,7 @@ 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_INT0 = ruleOf("non-negative integer", (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0);
@@ -197,7 +199,7 @@ const firstSecretKeyPath = (root, allow) => {
             const at = isArr && /^[0-9]+$/.test(k) ? `${path}[${k}]` : pathAt(path, k);
             if (isSecretKeyName(k) && !allow.has(at))
                 return at;
-            stack.push([d.value, at]);
+            Object.defineProperty(stack, stack.length, { value: [d.value, at], writable: true, enumerable: true, configurable: true });
         }
     }
     return undefined;
@@ -251,22 +253,49 @@ const SEAT_EVENT_TYPE_TUPLE = [
     "subagent_content",
 ];
 export const SEAT_EVENT_TYPES = Object.freeze(SEAT_EVENT_TYPE_TUPLE);
-const CHROME_EVENT_KIND_TUPLE = [
-    "panel_task",
-    "notification_terminal",
-    "prompt_suggestions",
-    "subagent_lifecycle",
-    "text_segment_end",
-    "thinking_segment_end",
-    "retry_status",
-    "context_usage",
-    "last_turn_usage",
-    "bgshell_register",
-    "bgshell_settle",
-    "memory_saved",
-    "result_replayed",
-    "tool_parked",
-];
+const CHROME_ARM_SEAT_ROUTE = {
+    panel_task: "seat",
+    notification_terminal: "seat",
+    prompt_suggestions: "seat",
+    subagent_lifecycle: "seat",
+    text_segment_end: "seat",
+    thinking_segment_end: "seat",
+    retry_status: "seat",
+    context_usage: "seat",
+    last_turn_usage: "seat",
+    bgshell_register: "seat",
+    bgshell_settle: "seat",
+    memory_saved: "seat",
+    result_replayed: "seat",
+    tool_parked: "seat",
+    compaction_started: "seat",
+    compaction_outcome: "seat",
+    engine_notice: "seat",
+    workflow_notification_enqueue: "host",
+    plan_review_park: "host",
+    approval_request: "host",
+    approval_revoke: "host",
+    task_ledger_sync: "host",
+    inline_task_stats: "host",
+    stream_delta: "host",
+    thinking_activity: "host",
+    request_start: "host",
+    response_metrics: "host",
+    attachment: "host",
+    subagent_turn_usage: "host",
+    run_cost_reconciled: "host",
+    message_committed: "host",
+    human_input: "host",
+    tool_roster_delta: "host",
+    subagent_started: "host",
+    prompt_assembled: "host",
+    tool_disclosure: "host",
+    tool_progress: "host",
+    wiring_manifest: "host",
+    suspended_reopened: "host",
+    result_text_diverged: "host",
+};
+const CHROME_EVENT_KIND_TUPLE = Object.keys(CHROME_ARM_SEAT_ROUTE).filter((k) => CHROME_ARM_SEAT_ROUTE[k] === "seat");
 export const CHROME_EVENT_KINDS = Object.freeze(CHROME_EVENT_KIND_TUPLE);
 const LANE_PROOF_LANE_TUPLE = ["main", "subagent", "workflow"];
 export const SEAT_CHROME_ENVELOPE_KEYS = ["kind", "laneProof"];
@@ -327,7 +356,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 });
@@ -340,7 +369,7 @@ export function seatCapability(state, name) {
         const desc = Object.getOwnPropertyDescriptor(state, name);
         if (desc === undefined)
             return notReported();
-        if (!("value" in desc))
+        if (!Object.hasOwn(desc, "value"))
             return malformedReading();
         const v = desc.value;
         if (v === undefined)
@@ -403,6 +432,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)
@@ -529,6 +559,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) };
@@ -944,6 +975,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) {
@@ -1084,9 +1121,11 @@ const SEAT_CHROME_PAYLOAD_SPECS = {
         registration: reqF(shapeRule("registration", {
             kind: reqF(oneOfRule("registration kind", ["register"])),
             taskId: reqF(R_NONEMPTY),
+            toolUseId: optF(R_NONEMPTY),
             command: reqF(R_STR),
             description: optF(R_STR),
             receipt: reqF(R_STR),
+            outputFile: optF(R_NONEMPTY),
             source: reqF(oneOfRule("registration source", ["bash", "monitor"])),
         })),
     },
@@ -1409,6 +1448,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");
@@ -1580,6 +1627,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 },
     },
@@ -1627,6 +1675,7 @@ export const SEAT_METHOD_NAMES = [
     "readSessionMcpPanel",
     "listMcpToolToggles",
     "setMcpToolToggle",
+    "setThinkingLatch",
     "onEvent",
     "onToolPermissionRequest",
 ];
@@ -1685,6 +1734,7 @@ export const LOCAL_SESSION_RECORD_KEYS = [
     "queuedMessages",
     "parked",
     "pinned",
+    "thinkingLatch",
 ];
 export const SEND_MESSAGE_REQUEST_KEYS = [
     "sessionId",
@@ -1729,7 +1779,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: {
@@ -1853,6 +1903,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"],
@@ -1906,7 +1962,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: {
@@ -1977,7 +2033,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",
@@ -1988,10 +2044,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 = [
@@ -2021,5 +2077,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/selfOrchestrationDenial.js

@@ -43,7 +43,7 @@ function ownRead(o, key) {
         const d = Object.getOwnPropertyDescriptor(o, key);
         if (d === undefined)
             return ABSENT;
-        if ('get' in d || 'set' in d)
+        if (Object.hasOwn(d, 'get') || Object.hasOwn(d, 'set'))
             return ACCESSOR;
         return { kind: 'data', value: d.value };
     }

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 {};