@sema-agent/server 7.50.0 → 7.51.0

package/dist/config.js

@@ -11,6 +11,7 @@ import { DEFAULT_QUESTION_THROTTLE } from "./question.js";
 import { GIT_API_KINDS, isGitApiKind } from "./git-api-kind.js";
 import { RETENTION_MODES, MEMORY_CONSOLIDATION_MIN_INTERVAL_SEC } from "./config-types.js";
 import { normalizeSshFingerprint } from "./ssh-host-key.js";
+import { CONTROL_AND_BIDI_STRIP_RE } from "./text-bidi.js";
 export { RETENTION_MODES, MEMORY_CONSOLIDATION_MIN_INTERVAL_SEC } from "./config-types.js";
 function csv(name) {
     return (process.env[name] ?? "")
@@ -736,11 +737,17 @@ function parseDegradeOn(words) {
     }
     return words;
 }
+const PRESENTED_NAME_MAX = 160;
+function presentToolName(name) {
+    const clean = name.replace(CONTROL_AND_BIDI_STRIP_RE, "");
+    return clean.length <= PRESENTED_NAME_MAX ? clean : `${clean.slice(0, PRESENTED_NAME_MAX)}…(${name.length} chars)`;
+}
 function ccRuleFormGuidance(name) {
     if (!name.includes("(") && !name.includes(")"))
         return undefined;
-    return (`CC-form rule specifier — this list matches the WHOLE tool name verbatim, so it can only ever match a tool literally named "${name}". ` +
-        `Drop the parentheses to gate the tool itself ("${name.split("(")[0] ?? name}"); ` +
+    const shown = presentToolName(name);
+    return (`CC-form rule specifier — this list matches the WHOLE tool name verbatim, so it can only ever match a tool literally named "${shown}". ` +
+        `Drop the parentheses to gate the tool itself ("${presentToolName(name.split("(")[0] ?? name)}"); ` +
         `to decide per COMMAND use \`runtime.commandPolicy\` ({command, decision} — bare argv[0] names); ` +
         `to put every shell call behind an approval use MANUAL_MODE_SHELL_GATE=always`);
 }
@@ -783,7 +790,7 @@ export function findUnmatchableToolNames(names) {
         const ns = protocolOf(name);
         if (ns === undefined) {
             if (name.includes("__"))
-                out.push({ name, guidance: `pre-prefix short form — the live name carries a protocol prefix: ${PROTOCOL_TABLE.map((e) => `${e.prefix}${name}`).join(" or ")}` });
+                out.push({ name, guidance: `pre-prefix short form — the live name carries a protocol prefix: ${PROTOCOL_TABLE.map((e) => `${e.prefix}${presentToolName(name)}`).join(" or ")}` });
             continue;
         }
         if (ns.parse(name) === undefined) {
@@ -794,7 +801,7 @@ export function findUnmatchableToolNames(names) {
 }
 export function formatUnmatchableToolNames(source, bad) {
     return (`${source} names tool(s) that can never match a live tool (these lists are RAW whole-name comparisons — core 5.0.0 RB-476 removed the alias/auto-prefix folds): ` +
-        bad.map((b) => `${b.name} → ${b.guidance}`).join("; "));
+        bad.map((b) => `${presentToolName(b.name)} → ${b.guidance}`).join("; ")).replace(CONTROL_AND_BIDI_STRIP_RE, "");
 }
 function streamApprovalConfig() {
     const cfg = {
@@ -1277,10 +1284,11 @@ function parseOrchestrationDomain(ctx) {
                 adb: ["ADB_SERIAL"],
                 host: [],
                 "local-docker": ["DOCKER_IMAGE"],
+                device: [],
             };
-            const required = Object.hasOwn(REQUIRED_ENVS_BY_LANE, lane) ? REQUIRED_ENVS_BY_LANE[lane] : undefined;
+            const required = Object.entries(REQUIRED_ENVS_BY_LANE).find(([word]) => word === lane)?.[1];
             if (required === undefined) {
-                throw new Error(`REMOTE_EXEC="${lane}" is not an execution lane — valid: e2b | k8s | ssh | adb | host | local-docker. ` +
+                throw new Error(`REMOTE_EXEC="${lane}" is not an execution lane — valid: ${Object.keys(REQUIRED_ENVS_BY_LANE).join(" | ")}. ` +
                     `An unrecognized value used to fall through to the host/in-process lane silently; refusing to start instead (#157).`);
             }
             const missing = required.filter((name) => !process.env[name]);
@@ -1385,9 +1393,19 @@ function parseOrchestrationDomain(ctx) {
                                                         ...(process.env.DOCKER_SANDBOX_ENV ? { env: resolveEnvForward(process.env.DOCKER_SANDBOX_ENV) } : {}),
                                                     }
                                                     :
-                                                        process.env.CONFIG_PROVIDER === "local"
-                                                            ? { provider: "host" }
-                                                            : undefined,
+                                                        process.env.REMOTE_EXEC === "device"
+                                                            ? {
+                                                                provider: "device",
+                                                                ...((n) => (n !== undefined ? { deliveryTimeoutMs: n } : {}))(optNumEnvStrict("DEVICE_DELIVERY_TIMEOUT_MS")),
+                                                                ...((n) => (n !== undefined ? { reconnectGraceMs: n } : {}))(optNumEnvStrict("DEVICE_RECONNECT_GRACE_MS")),
+                                                                ...((n) => (n !== undefined ? { execTimeoutMs: n } : {}))(optNumEnvStrict("DEVICE_EXEC_TIMEOUT_MS")),
+                                                                ...((n) => (n !== undefined ? { maxInflightPerDevice: n } : {}))(optNumEnvStrict("DEVICE_MAX_INFLIGHT_PER_DEVICE")),
+                                                                ...(process.env.DEVICE_SUPERSEDE ? { supersede: enumEnv("DEVICE_SUPERSEDE", "stale_only", ["stale_only", "deny"]) } : {}),
+                                                            }
+                                                            :
+                                                                process.env.CONFIG_PROVIDER === "local"
+                                                                    ? { provider: "host" }
+                                                                    : undefined,
         worktreeIsolation: boolEnv("WORKTREE_ISOLATION_ENABLED", false) && process.env.WORKTREE_REPO_ROOT
             ? {
                 repoRoot: process.env.WORKTREE_REPO_ROOT,
@@ -1803,6 +1821,25 @@ export function loadConfig() {
             "push. Point the service at a durable store (DB_BACKEND=mysql|pg), or turn the leader off (unset LEADER_ENABLED) " +
             "(#193 车4 件2 / staleness ledger P1-9+P1-10 boot invariant)");
     }
+    {
+        const deviceLane = orchestration.remoteExec?.provider === "device";
+        const deviceSqlStore = (store.dbBackend === "mysql" && store.tidb !== undefined) || (store.dbBackend === "pg" && store.pg !== undefined);
+        if (deviceLane && !deviceSqlStore) {
+            throw new Error(`REMOTE_EXEC=device with DB_BACKEND=${store.dbBackend} and no SQL connection coordinates built is refused ` +
+                "[device-durable-store]: the device registry, the session↔device binding and the device audit trail are all " +
+                "SQL-backed — without a real SQL store the binding lives in this process only, so a restart forgets WHICH device " +
+                "a parked run must resume onto and a second replica cannot see it at all. Note DB_BACKEND alone is not enough: " +
+                "SESSION_BACKEND=memory (or auto with no MYSQL_HOST/PG_HOST) builds no coordinates at all. Configure a durable " +
+                "store (DB_BACKEND=mysql|pg + its *_HOST/*_USER/*_DATABASE), or unset REMOTE_EXEC " +
+                "(device-executor-lane-v2 §4.7 boot invariant)");
+        }
+        if (deviceLane && !dgDurable) {
+            throw new Error("REMOTE_EXEC=device without DURABLE_APPROVAL=true is refused [device-durable-approval]: a personal device goes " +
+                "offline (lid closed, network drop) at arbitrary points, so an in-flight approval that outlives the window MUST " +
+                "have a park exit — without the durable approval store there is none and the run is stuck with nowhere to persist. " +
+                "Set DURABLE_APPROVAL=true, or unset REMOTE_EXEC (device-executor-lane-v2 §4.7 boot invariant)");
+        }
+    }
     EXEC_LANE_NOTICE = buildExecLaneNotice(orchestration.remoteExec);
     return attachConfigGroups({
         ...store,

package/dist/device-enrollment.d.ts

@@ -0,0 +1,125 @@
+/**
+ * device lane 准入链(design/device-executor-lane-v2 §4.3.2 提交期准入 + §7-T5 enrollment 五件 +
+ * §7-T6 反枚举)—— **纯函数层**:没有 HTTP、没有 WS、没有 core 装配,只有「店 + 判据 → typed 判决」。
+ * 端点(`/v1/devices/*`、`GET /v1/device/ws`)由车A-3/车C 接;它们**必须**经由这里的判决,不得自建判据。
+ *
+ * ── 五件(§7-T5,逐条落在哪儿)────────────────────────────────────────────────────────────────────
+ *  ① TTL —— `DeviceStore.consumeEnrollToken` 的 CAS 谓词 `expires_at > NOW(3)`(**DB 时钟**,§4.6-F18)。
+ *  ② 绑定 principal —— 同一条 CAS 谓词里 `target_tenant/target_subject` 逐字节等值;不匹配 = 拒。
+ *  ③ 消费一次性 CAS —— `consumed_at IS NULL` 谓词 + `rev=rev+1`;**affected=0 时只有同 pubkey 放行**。
+ *  ④ 重用审计 —— 异 pubkey ⇒ `device_enroll_token_reuse` 审计行(告警级);principal 不符 ⇒
+ *     `device_identity_mismatch` 审计行。两条都在**拒绝之前**写,失败即整条请求失败(fail-closed:
+ *     审计写不进去 ≠ 放行)。
+ *  ⑤ 限速 —— {@link DeviceEnrollRateLimiter},注入式。缺席 = **不限速**,所以端点车必须传一个
+ *     (§7-T5 ⑤ 双限速);本层不替它兜底,也不假装限了。
+ *
+ * ── 反枚举(§4.8 + memory `anti-enum-404-ambiguity`)──────────────────────────────────────────────
+ * enrollment 的**全部**拒绝理由(token 不存在 / 过期 / principal 不符 / 被别的 pubkey 用过)在 wire
+ * 上是**同一个** `device.enrollment_invalid`;设备读面的「不存在」与「不是你的」是同一个
+ * `not_found.device`。细分只进审计。
+ *
+ * ── 吊销在途语义(§8-R4)──────────────────────────────────────────────────────────────────────────
+ * `revoked` 是终态:①绑定的 session 后续提交 = `device.revoked`(admitSession 步 2,**先于** presence
+ * 判定);②吊销同事务把连接租约作废并把 `conn_generation` 推进一格 ⇒ 在途连接的每一次带世代谓词的写
+ * 都会影响 0 行,设备侧因此立刻失权(§4.6 步 2);③重新 enrollment = 新 deviceId,不复活旧行。
+ */
+import { DEVICE_RATE_LIMIT_CODE, type DeviceErrorCode, type DeviceOwner, type DeviceRow, type DeviceSessionRow, type DeviceStore, type NewDeviceInput } from "./device-store.js";
+/** typed 拒绝 —— 端点层只负责把它翻成 HTTP(status 已在体内,不许调用方另算)。 */
+export interface DeviceRejection {
+    code: DeviceErrorCode | typeof DEVICE_RATE_LIMIT_CODE;
+    status: number;
+    message: string;
+    /** 限流专用:`Retry-After` 的秒值(附录 A 的 429 族纪律)。 */
+    retryAfterSec?: number;
+}
+export type DeviceOutcome<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reject: DeviceRejection;
+};
+/**
+ * 限速座(§7-T5 ⑤)。**fail-closed**:`check` 抛错 = 拒绝(不是放行)—— 限速器不可用时放行,正是
+ * token 撞库最想要的那一刻。
+ */
+export interface DeviceEnrollRateLimiter {
+    check(key: string): Promise<{
+        allowed: boolean;
+        retryAfterSec?: number;
+    }>;
+}
+export interface EnrollDeviceInput {
+    /** 明文 token(**只**在这里出现,落库前立刻摘要)。 */
+    token: string;
+    /** 请求方**验证过**的复合身份(SSO/凭据链产出,恒不取自可伪造头)。 */
+    requester: DeviceOwner;
+    /** 🔴 `deviceId` 与 `owner` **不在**这里:前者恒由 server 铸(调用方选 id = 让请求方挑自己的设备身份,
+     *  与 §6「server 铸 dev_<ulid>」相悖),后者恒取自**验证过的** requester —— 两个字段都不接受请求体供给。
+     *  测试要确定性 id ⇒ 注入 {@link DeviceEnrollmentDeps.mintId},不是从入参开一个口子。 */
+    device: Omit<NewDeviceInput, "deviceId" | "owner">;
+}
+export interface EnrollDeviceValue {
+    device: DeviceRow;
+    /** `true` = 幂等重放(响应丢失重试),`false` = 本次真注册。wire 上两者同为 200 + 同 deviceId。 */
+    replayed: boolean;
+}
+export interface AdmitSessionInput {
+    rootSessionId: string;
+    requester: DeviceOwner;
+    /** 提交体携带的 deviceId(§4.3.2:仅根任务携;缺席 = 沿用绑定)。 */
+    requestedDeviceId?: string;
+}
+export interface AdmitSessionValue {
+    deviceId: string;
+    device: DeviceRow;
+    /**
+     * 判决**当刻**的连接世代(§4.6 fencing token)。
+     *
+     * 🔴 **准入判决是一个快照,不是一把锁**(codex 对抗轮 F4,判真但归属下一车):`admitSession` 返回后、
+     * 调用方真正下发指令前,一次 `revokeDevice` 可以提交 —— 它会作废租约并把 `conn_generation` 推进一格,
+     * 但它**追不回**已经基于旧判决发出去的指令。这不是本层能关掉的窗(§6 注③ 刻意不落指令表,所以持久层
+     * 没有「派发」这个写点可以带谓词);设计给的答案是**在下发边界重新断言世代**(§4.6 步 2/3:每一次带
+     * `conn_generation = ?` 谓词的写影响 0 行 = 本连接已失权 ⇒ 停发并断连)。
+     * 本字段就是那个断言要用的值 —— 车A-3 的 WS 汇聚端**必须**拿它去 fence,拿不到就不要下发。
+     * 残余诚实:窗口上界 = 心跳周期(吊销后设备侧最迟一个心跳失败即失权),§8-R4 对已发指令的账面处置是
+     * 「在途结果帧丢弃 + 审计,对应调用按 outcome-unknown 收尾」。
+     */
+    connGeneration: number;
+}
+export interface DeviceEnrollment {
+    enroll(input: EnrollDeviceInput): Promise<DeviceOutcome<EnrollDeviceValue>>;
+    bindPlacement(input: {
+        rootSessionId: string;
+        deviceId: string;
+        requester: DeviceOwner;
+    }): Promise<DeviceOutcome<DeviceSessionRow>>;
+    admitSession(input: AdmitSessionInput): Promise<DeviceOutcome<AdmitSessionValue>>;
+    revoke(input: {
+        deviceId: string;
+        requester: DeviceOwner;
+        revokedBy: string;
+        reason?: string | null;
+    }): Promise<DeviceOutcome<DeviceRow>>;
+}
+export interface DeviceEnrollmentDeps {
+    store: DeviceStore;
+    /** 缺席 = 不限速(端点车必须传;见文件头注 ⑤)。 */
+    rateLimiter?: DeviceEnrollRateLimiter;
+    /** 测试可注入确定性铸造;默认 `mintDeviceId()`。 */
+    mintId?: () => string;
+}
+export declare function createDeviceEnrollment(deps: DeviceEnrollmentDeps): DeviceEnrollment;
+/**
+ * 进程内固定窗限速(§7-T5 ⑤ 的**默认**实现)。
+ *
+ * 🔴 诚实边界:这是**每副本**的窗。跨副本的真限速属主是既有的 `observability/rate-limit.ts` RateGate
+ * (SQL 后端),端点车把它适配成 {@link DeviceEnrollRateLimiter} 传进来即可 —— 本函数不假装自己是
+ * 那个东西,也不在多副本部署下声称有全局上界。
+ */
+export declare function createFixedWindowRateLimiter(opts: {
+    limit: number;
+    windowMs: number;
+    now?: () => number;
+}): DeviceEnrollRateLimiter;
+//# sourceMappingURL=device-enrollment.d.ts.map

package/dist/device-enrollment.js

@@ -0,0 +1,156 @@
+import { DEVICE_ERROR_CODES, DEVICE_ERROR_STATUS, DEVICE_RATE_LIMIT_CODE, assertDeviceIdShape, assertDeviceOwnerShape, assertDevicePubkeyShape, assertEnrollTokenHashShape, assertRootSessionIdShape, hashEnrollToken, mintDeviceId, } from "./device-store.js";
+function reject(code, message, extra) {
+    return { ok: false, reject: { code, status: DEVICE_ERROR_STATUS[code], message, ...(extra?.retryAfterSec === undefined ? {} : { retryAfterSec: extra.retryAfterSec }) } };
+}
+function rejectEnrollment() {
+    return reject(DEVICE_ERROR_CODES.ENROLLMENT_INVALID, "enrollment token is not valid for this request");
+}
+function rejectNotFound() {
+    return reject(DEVICE_ERROR_CODES.NOT_FOUND, "device not found");
+}
+export function createDeviceEnrollment(deps) {
+    const { store } = deps;
+    const mintId = deps.mintId ?? mintDeviceId;
+    async function rateGate(key) {
+        if (!deps.rateLimiter)
+            return null;
+        try {
+            const verdict = await deps.rateLimiter.check(key);
+            if (verdict.allowed)
+                return null;
+            return reject(DEVICE_RATE_LIMIT_CODE, "too many device enrollment attempts", { retryAfterSec: verdict.retryAfterSec ?? 1 });
+        }
+        catch (err) {
+            return reject(DEVICE_RATE_LIMIT_CODE, `device enrollment rate check unavailable (fail-closed): ${err instanceof Error ? err.message : String(err)}`, { retryAfterSec: 1 });
+        }
+    }
+    async function enroll(input) {
+        assertDeviceOwnerShape(input.requester);
+        assertDevicePubkeyShape(input.device.pubkey);
+        const limited = await rateGate(`enroll:${input.requester.tenant}\u0000${input.requester.subject}`);
+        if (limited)
+            return limited;
+        const tokenHash = hashEnrollToken(input.token);
+        assertEnrollTokenHashShape(tokenHash);
+        const deviceId = mintId();
+        assertDeviceIdShape(deviceId);
+        const result = await store.consumeEnrollToken({
+            tokenHash,
+            requester: input.requester,
+            device: { ...input.device, deviceId, owner: input.requester },
+        });
+        switch (result.outcome) {
+            case "enrolled":
+                return { ok: true, value: { device: result.device, replayed: false } };
+            case "replayed":
+                if (!result.device)
+                    return rejectEnrollment();
+                if (result.device.status === "revoked")
+                    return reject(DEVICE_ERROR_CODES.REVOKED, "device has been revoked");
+                return { ok: true, value: { device: result.device, replayed: true } };
+            case "token_reuse": {
+                const row = await store.getEnrollToken(tokenHash);
+                await store.appendAudit({
+                    event: "device_enroll_token_reuse",
+                    deviceId: row?.consumedDeviceId ?? null,
+                    owner: input.requester,
+                    detail: { consumedAtMs: row?.consumedAtMs ?? null, presentedPubkeyDiffers: true },
+                });
+                return rejectEnrollment();
+            }
+            case "principal_mismatch":
+                await store.appendAudit({ event: "device_identity_mismatch", deviceId: null, owner: input.requester, detail: { at: "enrollment", reason: "token target principal mismatch" } });
+                return rejectEnrollment();
+            case "expired":
+            case "unknown_token":
+                return rejectEnrollment();
+            case "pubkey_taken":
+                await store.appendAudit({ event: "device_identity_mismatch", deviceId: null, owner: input.requester, detail: { at: "enrollment", reason: "pubkey already bound to another device in this tenant" } });
+                return rejectEnrollment();
+        }
+    }
+    async function bindPlacement(input) {
+        assertRootSessionIdShape(input.rootSessionId);
+        assertDeviceIdShape(input.deviceId);
+        assertDeviceOwnerShape(input.requester);
+        const result = await store.bindSession({ rootSessionId: input.rootSessionId, deviceId: input.deviceId, owner: input.requester });
+        switch (result.outcome) {
+            case "bound":
+            case "idempotent":
+                return { ok: true, value: result.row };
+            case "conflict":
+                return reject(DEVICE_ERROR_CODES.CLAIM_CONFLICT, "this session is already bound to a different device");
+            case "device_not_found":
+                return rejectNotFound();
+            case "device_revoked":
+                return reject(DEVICE_ERROR_CODES.REVOKED, "device has been revoked");
+        }
+    }
+    async function admitSession(input) {
+        assertRootSessionIdShape(input.rootSessionId);
+        assertDeviceOwnerShape(input.requester);
+        if (input.requestedDeviceId !== undefined)
+            assertDeviceIdShape(input.requestedDeviceId);
+        const binding = await store.getSessionBinding(input.rootSessionId);
+        if (!binding)
+            return reject(DEVICE_ERROR_CODES.NOT_BOUND, "this session has no device binding");
+        if (binding.owner.tenant !== input.requester.tenant || binding.owner.subject !== input.requester.subject)
+            return rejectNotFound();
+        if (input.requestedDeviceId !== undefined && input.requestedDeviceId !== binding.deviceId) {
+            return reject(DEVICE_ERROR_CODES.IDENTITY_MISMATCH, "the requested device is not the one bound to this session");
+        }
+        const view = await store.readDeviceForAdmission(binding.deviceId, input.requester);
+        if (!view)
+            return rejectNotFound();
+        if (view.row.status === "revoked")
+            return reject(DEVICE_ERROR_CODES.REVOKED, "device has been revoked");
+        if (!view.online)
+            return reject(DEVICE_ERROR_CODES.OFFLINE, "device is not connected");
+        return { ok: true, value: { deviceId: binding.deviceId, device: view.row, connGeneration: view.row.connGeneration } };
+    }
+    async function revoke(input) {
+        assertDeviceIdShape(input.deviceId);
+        assertDeviceOwnerShape(input.requester);
+        const result = await store.revokeDevice({ deviceId: input.deviceId, owner: input.requester, revokedBy: input.revokedBy, reason: input.reason ?? null });
+        switch (result.outcome) {
+            case "revoked":
+            case "already_revoked":
+                return { ok: true, value: result.row };
+            case "not_found":
+                return rejectNotFound();
+        }
+    }
+    return { enroll, bindPlacement, admitSession, revoke };
+}
+export function createFixedWindowRateLimiter(opts) {
+    const now = opts.now ?? (() => Date.now());
+    const windows = new Map();
+    const MAX_WINDOWS = 10_000;
+    const prune = (t) => {
+        for (const [k, w] of windows)
+            if (t - w.startedAtMs >= opts.windowMs)
+                windows.delete(k);
+        if (windows.size <= MAX_WINDOWS)
+            return;
+        const victims = [...windows.entries()].sort((a, b) => a[1].startedAtMs - b[1].startedAtMs).slice(0, Math.floor(windows.size / 2));
+        for (const [k] of victims)
+            windows.delete(k);
+    };
+    return {
+        check: async (key) => {
+            const t = now();
+            if (windows.size >= MAX_WINDOWS)
+                prune(t);
+            const cur = windows.get(key);
+            if (!cur || t - cur.startedAtMs >= opts.windowMs) {
+                windows.set(key, { startedAtMs: t, count: 1 });
+                return { allowed: true };
+            }
+            cur.count += 1;
+            if (cur.count > opts.limit)
+                return { allowed: false, retryAfterSec: Math.max(1, Math.ceil((cur.startedAtMs + opts.windowMs - t) / 1000)) };
+            return { allowed: true };
+        },
+    };
+}
+//# sourceMappingURL=device-enrollment.js.map