@sema-agent/client-core 0.62.1 → 0.63.0

package/dist/postureKnob.js

@@ -0,0 +1,174 @@
+import { capForDisplay } from './fleetTaskDesc.js';
+/**
+ * 一个旋钮的值是谁定的 —— 四词闭集,**顺序即优先序**(engine 侧是穷举 switch,加词在那里编译红)。
+ *   · `env` —— 这台机器的 env 变量钉的(部署主权,恒赢任何下发值);
+ *   · `center` —— 配置中心发布的(重启生效;本机写同名 env 即把这个键收回);
+ *   · `posture` —— 从**部署形**派生的(单用户 turnkey);
+ *   · `engine-default` —— 没人钉过,内建缺省在岗。
+ * 🔴 本包按**开集**读实际值(词表属主在引擎侧,加词不该让消费端把一个合法读数判没);这张表是
+ *    **优先序与判据**的真源,不是一道准入门。
+
+ * 🔴 形制:`Object.freeze` 的数组,**不是**只在类型面只读的 `readonly T[]` —— 后者一行 `.splice()`
+ *    就能改,而公面消费者拿到的正是这个实例(本仓已定谳的病形,同 `RESUME_RETRY_LATER_CODES`)。
+ */
+export const POSTURE_SOURCE_WORDS = Object.freeze(['env', 'center', 'posture', 'engine-default']);
+/**
+ * 「**运维显式表态过吗**」——只有 `env` / `center` 两词算数。
+ *
+ * 🔴 `posture` 派生出来的 `true` **不是**「有人要求过」:它是部署形状的推论,换一台机器就变。
+ *    把它读成表态,会让「运维明确开过这个开关」这句话在一台谁都没碰过的机器上为真。
+ * 🔴 表外词(开集逃生口)一律**不算**表态:读不懂的来源不是「有人钉过」的证据。
+ */
+export function postureSourceIsOperatorPinned(source) {
+    return source === 'env' || source === 'center';
+}
+/**
+ * 这根旋钮的来源词,**答不出来就答不出来**。
+ * 🔴 legacy 行(老 worker 的裸值)⇒ `undefined`:形上的占位值不是一次观测,交出去就是编答案。
+ */
+export function postureKnobSourceOf(knob) {
+    if (knob === undefined || knob.legacy === true)
+        return undefined;
+    return knob.source;
+}
+/** 旋钮 → 人话名。**唯一铸点**(三端共用一套词;别在各端的行装配里另起一份)。 */
+const KNOB_LABELS = Object.freeze({
+    durableApproval: 'durable approval',
+    streamAskWindowMs: 'approval window',
+    sessionAutoTitle: 'session auto-title',
+});
+/** `note` 上屏封长(UTF-16 单元,按**转义后**的长度算;与 readFace 那一格同值同理由)。 */
+const KNOB_NOTE_MAX = 256;
+/** `source` 上屏封长(同上)。 */
+const KNOB_WORD_MAX = 40;
+/** 一只 `{value, source, note}` 读数的公共窄读(值判据由调用方给)。坏形 ⇒ `undefined`。 */
+function readKnob(raw, valueOk) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return undefined;
+    const r = raw;
+    if (!valueOk(r.value))
+        return undefined;
+    if (typeof r.source !== 'string' || r.source.length === 0)
+        return undefined;
+    // `note` 允许空串(自由文本;空文本本身也是一句读数,不是「读不出」)。
+    if (typeof r.note !== 'string')
+        return undefined;
+    return { value: r.value, source: r.source, note: r.note };
+}
+const isBool = (v) => typeof v === 'boolean';
+/** 窗值:有限**非负**数(负窗在引擎侧是拒启门,一个负数读数是坏形不是事实)。 */
+const isWindowMs = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0;
+/**
+ * `wiring.serverGates` → 三旋钮读数;**畸形一律 `undefined`**,绝不抛出。
+ *
+ * 🔴 **判别锚是 `durableApproval`**:它是这一面上唯一**两代都在**的旋钮(老 worker 上是裸布尔,
+ *    新 worker 上是读数)。它读不出来 ⇒ 整段缺席 —— 一份没有主锚的旋钮面答不了运维要问的那一问,
+ *    而半段会被当成完整答案(与 `writeProtectionPosture` 缺 `source` ⇒ 整段缺席同一条纪律)。
+ * 🔴 **旁枝坏形只丢那一根**:`streamAskWindowMs` / `sessionAutoTitle` 各自独立,一根形坏不该把
+ *    另外两根一起藏起来(旁枝与主锚的处置刻意不同,理由见上一条)。
+ * 🔴 **缺席不铸默认**:另两根整键缺席时这两格就是缺席。铸 `300000` / `true` 会把「这台 worker
+ *    说不出来」渲成「它说了这个值」——那正是本面存在要根治的病。
+ * ⚠️ 「整键缺席(老 worker)」与「在场但形坏」在旁枝上折成同一个缺席;「为什么答不出来」不是
+ *    这一位该回答的(见 {@link postureKnobDetail} 的 `reachable` 段)。
+ */
+export function projectServerGateKnobs(wiring) {
+    if (typeof wiring !== 'object' || wiring === null || Array.isArray(wiring))
+        return undefined;
+    const sg = wiring.serverGates;
+    if (typeof sg !== 'object' || sg === null || Array.isArray(sg))
+        return undefined;
+    const g = sg;
+    const raw = g.durableApproval;
+    let durableApproval;
+    let legacy = false;
+    if (typeof raw === 'boolean') {
+        // 老 worker(<7.67.0)的裸布尔:折进同一只壳,但立 legacy 位。`source` 是形上的占位,
+        // **不是**一次观测 —— 机读走 `postureKnobSourceOf`(它对 legacy 行答 undefined)。
+        durableApproval = { value: raw, source: 'engine-default', note: '', legacy: true };
+        legacy = true;
+    }
+    else {
+        durableApproval = readKnob(raw, isBool);
+    }
+    if (durableApproval === undefined)
+        return undefined;
+    const streamAskWindowMs = readKnob(g.streamAskWindowMs, isWindowMs);
+    const sessionAutoTitle = readKnob(g.sessionAutoTitle, isBool);
+    return {
+        durableApproval,
+        ...(streamAskWindowMs !== undefined ? { streamAskWindowMs } : {}),
+        ...(sessionAutoTitle !== undefined ? { sessionAutoTitle } : {}),
+        legacy,
+    };
+}
+/**
+ * 毫秒 → 人话。
+ * 🔴 **只在整除时才升单位**:`90m` 比 `1.5h` 更不容易被读错,而 `5400000ms` 谁也读不出是一个半
+ *    小时。除不尽 ⇒ 原样报毫秒(诚实优于好看)。
+ */
+function humanMs(ms) {
+    // 天不单列:`24h` 比 `1d` 更贴近运维钉回时写的那个数(`STREAM_ASK_WINDOW_MS`),小时这一档
+    // 已经把它读成人话了。
+    if (ms > 0 && ms % 3600000 === 0)
+        return `${ms / 3600000}h`;
+    if (ms > 0 && ms % 60000 === 0)
+        return `${ms / 60000}m`;
+    if (ms > 0 && ms % 1000 === 0)
+        return `${ms / 1000}s`;
+    return `${ms}ms`;
+}
+/** 值 → 上屏词。布尔渲 `on`/`off`(`true`/`false` 是给机器读的);数值按毫秒渲人话。 */
+function knobValueWord(value) {
+    if (typeof value === 'boolean')
+        return value ? 'on' : 'off';
+    return humanMs(value);
+}
+/**
+ * 四态措辞的**唯一铸点**(三端共用一句话;别在各端的行装配里另写一遍 —— 与
+ * `readFacePostureDetail` / `writeProtectionDoctorDetail` 同一条纪律)。
+ *
+ * 🔴 四句刻意**逐字互异**(黑盒锚),对运维是四条不同的下一步:
+ *   ① 读数在场 —— `<旋钮> <值> (source: <来源> — <指路句>)`;
+ *   ② 读数在场但来自老 worker 的裸值(`legacy`)—— 报得出**值**,但逐字点明「这台 worker 说不出
+ *      是谁定的」;**句中不出现任何来源词**(冒称来源比不说更坏:它会让人以为查过了);
+ *   ③ `opts.reachable === false` —— 「未观测」:这一次进程没读到 operator 响应;
+ *   ④ `reachable:true` 但读数仍缺席 —— 「不报」:响应读到了,只是这一位读不出来。
+ *      **不武断咎为版本**:整键缺席(老引擎)与在场却形坏折成同一个缺席,句子不能替一种情形撒谎。
+ * 🔴 ③④ 两句**一个值都不报** —— 它们要是顺口说了 `off`,消费端就会把「读不出」当成「关着」。
+ *
+ * ⚠️ **数值一律按毫秒读**:本面今天唯一的数值旋钮就是那只毫秒窗(门里有一条对 sdk spec 的钉:
+ *    `ServerWiringGates` 上 `type: number` 的旋钮恰一根)。上游哪天加第二根非时长数值旋钮,那条
+ *    钉先红,免得这里的措辞开始对它撒谎。
+ */
+export function postureKnobDetail(knob, opts) {
+    // 🔴 **按自有属性查表**(同形族扫):键在型面上是闭三词,但本口吃的是运行期值 —— 一个 JS 调用方
+    //    塞进 `toString`,裸下标会命中 `Object.prototype` 上的函数并被拼进句子。读不出名字时退到
+    //    一个中性词:**名字读不出不该让「这根旋钮的值是什么」也一起说不出来**。
+    const label = Object.hasOwn(KNOB_LABELS, opts.knob) ? KNOB_LABELS[opts.knob] : 'posture knob';
+    if (knob !== undefined) {
+        const word = knobValueWord(knob.value);
+        if (knob.legacy === true) {
+            return `${label} ${word} (this worker does not report who set it — an engine below 7.67.0)`;
+        }
+        const source = capForDisplay(knob.source, KNOB_WORD_MAX);
+        const note = capForDisplay(knob.note, KNOB_NOTE_MAX);
+        return note.length > 0
+            ? `${label} ${word} (source: ${source} — ${note})`
+            : `${label} ${word} (source: ${source})`;
+    }
+    if (!opts.reachable) {
+        return `${label} not observed (this end could not read the engine's diagnostics)`;
+    }
+    return `${label} not reported by this engine (an engine below 7.67.0, or a response this end could not parse)`;
+}
+/**
+ * **编译期对账钉**(不出公面):sdk 的读数形必须能赋给本视图,`ServerWiringGates` 的三根旋钮
+ * 必须真是读数形 —— 上游改形时这一行是本包第一个红的地方。
+ *
+ * 🔴 反向**刻意不钉**(本视图不必能赋给 sdk 形):`source` 在本视图上放宽成任意 `string`(开集读),
+ * 那是**故意比铸点宽** —— 窄读域只许等于或宽于铸点域,钉反向会把这条纪律反过来判成错。
+ */
+const _postureKnobShapePin = (w) => w;
+void _postureKnobShapePin;
+const _serverGateKnobsShapePin = (g) => g;
+void _serverGateKnobsShapePin;

package/dist/steering.d.ts

@@ -50,7 +50,12 @@ export interface EngineTaskStatusAttachment {
     deltaSummary: null;
 }
 export type SteeringRenderable = SteeringInjectedAttachment | EngineTaskStatusAttachment;
-/** Default-arm label for a source this shell build predates. */
+/** Default-arm label for a source this shell build predates.
+ *
+ *  🔴 **按自有属性查表**(0.63.0 同形存量清剿;与 `gateVocabulary` / `permissionRuleIssue` /
+ *     `engineNoticeCodes` 三处同一条病形):`SOURCE_LABELS` 是对象表而 `source` **来自 wire**,
+ *     裸下标会命中 `Object.prototype` 上的成员 —— `steeringLabel('constructor')` 返回一个**函数**,
+ *     而 `??` 对函数不生效 ⇒ 它被原样拼进 attachment 的 label。默认臂在这一形上等于不存在。 */
 export declare function steeringLabel(source: string): string;
 /**
  * Project one `steering_injected` wire event into its renderable attachment(s). Always returns at

package/dist/steering.js

@@ -38,9 +38,17 @@ const SOURCE_LABELS = {
     background_tasks: 'Background tasks from before compaction announced to the model',
     tools_delta: 'Newly available tools announced to the model',
 };
-/** Default-arm label for a source this shell build predates. */
+/** Default-arm label for a source this shell build predates.
+ *
+ *  🔴 **按自有属性查表**(0.63.0 同形存量清剿;与 `gateVocabulary` / `permissionRuleIssue` /
+ *     `engineNoticeCodes` 三处同一条病形):`SOURCE_LABELS` 是对象表而 `source` **来自 wire**,
+ *     裸下标会命中 `Object.prototype` 上的成员 —— `steeringLabel('constructor')` 返回一个**函数**,
+ *     而 `??` 对函数不生效 ⇒ 它被原样拼进 attachment 的 label。默认臂在这一形上等于不存在。 */
 export function steeringLabel(source) {
-    return SOURCE_LABELS[source] ?? `Steering injected (${source})`;
+    const known = typeof source === 'string' && Object.hasOwn(SOURCE_LABELS, source)
+        ? SOURCE_LABELS[source]
+        : undefined;
+    return known ?? `Steering injected (${source})`;
 }
 /**
  * core turn-attachments.ts renderBackgroundTasks line shape (198 vbl VERBATIM phrases):

package/dist/subagentContentStore.d.ts

@@ -97,7 +97,11 @@ export interface SubagentContentEvent {
      *  「这一位是增量还是全文」变成读者要靠 `type` 去反推的事,而反推错的代价是内容重复上屏。 */
     text?: string | undefined;
     /** wire 上那一帧的**事件身份**(聚合两臂的幂等键;缺席 ⇒ 退回内容判据,见 publish 的两道闸)。
-     *  🔴 工具两臂**不读这一位**:那次调用的身份是 `toolCallId`,账本是 `items` 上那张卡。 */
+     *  🔴 工具两臂**不拿它当身份**:那次调用的身份是 `toolCallId`,账本是 `items` 上那张卡。
+     *  ⚠️ 但两臂**确实读它**(0.62.2 起):它是那张卡逐半的**阶段水位**({@link CardPhase} 的
+     *     `start` / `end`),回答「这一发比卡上现在承载的那一阶段新还是旧」。缺席是一个值 ——
+     *     身份缺席而内容真的变了 ⇒ 那一半的水位被清掉(判不出新旧就诚实地说判不出)。
+     *     旧注写的「工具两臂不读这一位」自 0.62.2 起不成立。 */
     eventId?: string | undefined;
     toolCallId?: string | undefined;
     toolName?: string | undefined;