@sema-agent/server 7.87.2 → 7.88.0

package/dist/http/routes/devices.js

@@ -1,8 +1,10 @@
 import { sendError, sendJson } from "../send.js";
 import { explicitOperatorOk, gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
-import { ssoVerifiedScope } from "../../security.js";
-import { assertDeviceIdShape, assertRootSessionIdShape, sameDeviceOwner, } from "../../device-store.js";
+import { DEVICE_PLATFORM_OS, DEVICE_PUBKEY_MAX_BYTES, DEVICE_TEXT_LIMITS, assertDeviceIdShape, assertDevicePubkeyShape, assertRootSessionIdShape, sameDeviceOwner, } from "../../device-store.js";
+import { DEFAULT_ENROLL_TOKEN_TTL_SEC } from "../../device-enrollment.js";
+import { deviceOwnerDomainOf } from "../device-placement.js";
+import { echoKeyName } from "../../request-key-closure.js";
 const DEVICE_NOT_FOUND_MESSAGE = "device not found";
 const NO_DEVICE_DOMAIN_MESSAGE = "device management needs a caller domain: this credential carries no verified tenant scope claim (registry auth-bridge JWT `scope`) and is not an explicit operator — connect through the registry auth bridge, or configure OPERATOR_PRINCIPALS";
 const DEVICE_LANE_REQUIRED_MESSAGE = "device management requires the device execution lane (REMOTE_EXEC=device with a SQL store backend) — this deployment has no device lane wired";
@@ -11,15 +13,6 @@ void _deviceRouteCodesPinned;
 function sendDeviceNotFound(res) {
     sendError(res, 404, "not_found.device", DEVICE_NOT_FOUND_MESSAGE);
 }
-export function deviceOwnerDomainOf(req, config) {
-    const subject = gatedPrincipal(req, config);
-    if (subject === undefined)
-        return undefined;
-    const tenant = ssoVerifiedScope(req);
-    if (tenant === undefined)
-        return undefined;
-    return { tenant, subject };
-}
 function wellFormedKey(assert, v) {
     try {
         assert(v);
@@ -40,11 +33,95 @@ function deviceListRow(row, online) {
 function boundDeviceOf(row) {
     return { deviceId: row.deviceId, rev: row.rev, boundAt: new Date(row.boundAtMs).toISOString() };
 }
+function sendDeviceRejection(res, rej) {
+    if (rej.retryAfterSec !== undefined)
+        res.setHeader("retry-after", String(rej.retryAfterSec));
+    sendError(res, rej.status, rej.code, rej.message);
+}
+function bodyKeyIssue(body, accepted) {
+    const extra = Object.keys(body).filter((k) => !accepted.includes(k)).map((k) => echoKeyName("", k)).sort();
+    if (extra.length === 0)
+        return null;
+    return `unknown key(s) in body: ${extra.join(", ")} — this endpoint accepts ${accepted.length === 0 ? "no body keys" : accepted.slice().sort().join(", ")} (a silently dropped key is a declaration that never existed)`;
+}
+async function readClosedBody(req, res, readJson, accepted) {
+    let body;
+    try {
+        body = await readJson(req);
+    }
+    catch {
+        sendError(res, 400, "request.invalid_json", "invalid JSON body");
+        return null;
+    }
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+        sendError(res, 400, "request.body_shape", "body must be a JSON object");
+        return null;
+    }
+    const issue = bodyKeyIssue(body, accepted);
+    if (issue !== null) {
+        sendError(res, 400, "request.body_shape", issue);
+        return null;
+    }
+    return body;
+}
+const ENROLL_BODY_KEYS = ["token", "pubkey", "platformOs", "platformArch", "displayName", "workspaceRoot"];
+function parseEnrollBody(res, body) {
+    const str = (k, required) => {
+        const v = body[k];
+        if (v === undefined)
+            return required ? (sendError(res, 400, "request.body_shape", `${k} is required`), null) : "";
+        if (typeof v !== "string")
+            return sendError(res, 400, "request.field_invalid", `${k} must be a string`), null;
+        return v;
+    };
+    const token = str("token", true);
+    if (token === null)
+        return null;
+    const pubkey = str("pubkey", true);
+    if (pubkey === null)
+        return null;
+    const platformArch = str("platformArch", false);
+    if (platformArch === null)
+        return null;
+    const displayName = str("displayName", false);
+    if (displayName === null)
+        return null;
+    const workspaceRoot = str("workspaceRoot", true);
+    if (workspaceRoot === null)
+        return null;
+    const os = DEVICE_PLATFORM_OS.find((o) => o === body.platformOs);
+    if (os === undefined) {
+        sendError(res, 400, "request.field_invalid", `platformOs must be one of ${DEVICE_PLATFORM_OS.join(" | ")} (v1 closed set — win32 is not supported yet, and is never silently accepted as a third value)`);
+        return null;
+    }
+    if (token.length === 0 || token.length > 256) {
+        sendError(res, 400, "request.field_invalid", "token must be a non-empty string of at most 256 characters");
+        return null;
+    }
+    if (!wellFormedKey(assertDevicePubkeyShape, pubkey)) {
+        sendError(res, 400, "request.field_invalid", `pubkey is not a valid device public key (byte-exact key: non-empty, no control characters or surrounding whitespace, at most ${DEVICE_PUBKEY_MAX_BYTES} bytes)`);
+        return null;
+    }
+    for (const [k, v, max] of [["displayName", displayName, DEVICE_TEXT_LIMITS.displayName], ["platformArch", platformArch, DEVICE_TEXT_LIMITS.platformArch], ["workspaceRoot", workspaceRoot, DEVICE_TEXT_LIMITS.workspaceRoot]]) {
+        if (Buffer.byteLength(v, "utf8") > max) {
+            sendError(res, 400, "request.field_invalid", `${k} exceeds the ${max}-byte column (a silently truncated value is a different value — refusing at the door)`);
+            return null;
+        }
+    }
+    if (workspaceRoot.length === 0) {
+        sendError(res, 400, "request.field_invalid", "workspaceRoot is required and must be non-empty (it is the device-side root every instruction resolves against)");
+        return null;
+    }
+    return { token: token, pubkey: pubkey, platformOs: os, platformArch: platformArch, displayName: displayName, workspaceRoot: workspaceRoot };
+}
 export async function handleDevices(req, res, match, ctx) {
     switch (match.decl.id) {
         case "devices-list":
         case "device-session":
         case "device-session-rebind":
+        case "device-enroll-tokens":
+        case "device-enroll":
+        case "device-revoke":
             break;
         default:
             return assertNever(match.decl.id);
@@ -58,7 +135,8 @@ export async function handleDevices(req, res, match, ctx) {
     }
     const store = deps.deviceStore;
     const hub = deps.deviceHub;
-    if (!store || !hub) {
+    const enrollment = deps.deviceEnrollment;
+    if (!store || !hub || !enrollment) {
         sendError(res, 501, "capability.device_lane_required", DEVICE_LANE_REQUIRED_MESSAGE);
         return;
     }
@@ -74,6 +152,88 @@ export async function handleDevices(req, res, match, ctx) {
         sendJson(res, 200, { devices: rows.filter((r) => r.status !== "revoked").map((r) => deviceListRow(r, online)) });
         return;
     }
+    if (match.decl.id === "device-enroll-tokens") {
+        if (domain === undefined) {
+            sendError(res, 403, "auth.forbidden", NO_DEVICE_DOMAIN_MESSAGE);
+            return;
+        }
+        if ((await readClosedBody(req, res, readJson, [])) === null)
+            return;
+        const ttlSeconds = (deps.config.remoteExec?.provider === "device" ? deps.config.remoteExec.enrollTokenTtlSec : undefined) ?? DEFAULT_ENROLL_TOKEN_TTL_SEC;
+        const issued = await enrollment.issueEnrollToken({ target: domain, createdBy: domain.subject, ttlSeconds });
+        if (!issued.ok) {
+            sendDeviceRejection(res, issued.reject);
+            return;
+        }
+        sendJson(res, 200, { token: issued.value.token, expiresAt: new Date(issued.value.row.expiresAtMs).toISOString(), ttlSec: ttlSeconds });
+        return;
+    }
+    if (match.decl.id === "device-enroll") {
+        if (domain === undefined) {
+            sendError(res, 403, "auth.forbidden", NO_DEVICE_DOMAIN_MESSAGE);
+            return;
+        }
+        const raw = await readClosedBody(req, res, readJson, ENROLL_BODY_KEYS);
+        if (raw === null)
+            return;
+        const body = parseEnrollBody(res, raw);
+        if (body === null)
+            return;
+        const outcome = await enrollment.enroll({
+            token: body.token,
+            requester: domain,
+            device: { displayName: body.displayName, platformOs: body.platformOs, platformArch: body.platformArch, pubkey: body.pubkey, workspaceRoot: body.workspaceRoot },
+        });
+        if (!outcome.ok) {
+            sendDeviceRejection(res, outcome.reject);
+            return;
+        }
+        sendJson(res, 200, { deviceId: outcome.value.device.deviceId });
+        return;
+    }
+    if (match.decl.id === "device-revoke") {
+        const decodedId = safeDecode(match.params.deviceId);
+        if (decodedId === null) {
+            sendError(res, 400, "request.path_malformed", "device id segment is not valid percent-encoding");
+            return;
+        }
+        if (!wellFormedKey(assertDeviceIdShape, decodedId)) {
+            sendError(res, 400, "request.id_invalid", "invalid device id segment (device keys are byte-exact: non-empty, no control characters or surrounding whitespace, at most 64 bytes)");
+            return;
+        }
+        if (!operator && domain === undefined) {
+            sendError(res, 403, "auth.forbidden", NO_DEVICE_DOMAIN_MESSAGE);
+            return;
+        }
+        const body = await readClosedBody(req, res, readJson, ["reason"]);
+        if (body === null)
+            return;
+        const reason = body.reason;
+        if (reason !== undefined && (typeof reason !== "string" || Buffer.byteLength(reason, "utf8") > DEVICE_TEXT_LIMITS.revokeReason)) {
+            sendError(res, 400, "request.field_invalid", `reason must be a string of at most ${DEVICE_TEXT_LIMITS.revokeReason} bytes (a silently truncated audit reason is a different reason)`);
+            return;
+        }
+        let owner;
+        if (operator) {
+            const row = await store.getDeviceUnscoped(decodedId);
+            if (!row) {
+                sendDeviceNotFound(res);
+                return;
+            }
+            owner = row.owner;
+        }
+        else {
+            owner = domain;
+        }
+        const revoked = await enrollment.revoke({ deviceId: decodedId, requester: owner, revokedBy: principal ?? owner.subject, reason: reason === undefined ? null : reason });
+        if (!revoked.ok) {
+            sendDeviceRejection(res, revoked.reject);
+            return;
+        }
+        await hub.fenceDevice(decodedId).catch((err) => deps.logger?.warn("device_revoke_fence_failed", { deviceId: decodedId, err: err instanceof Error ? err.message : String(err) }));
+        sendJson(res, 200, { deviceId: revoked.value.deviceId, status: revoked.value.status, ...(revoked.value.revokedAtMs !== null ? { revokedAt: new Date(revoked.value.revokedAtMs).toISOString() } : {}) });
+        return;
+    }
     const decoded = safeDecode(match.params.rootSessionId);
     if (decoded === null) {
         sendError(res, 400, "request.path_malformed", "session id segment is not valid percent-encoding");
@@ -164,6 +324,9 @@ export async function handleDevices(req, res, match, ctx) {
 }
 export const DEVICES_ROUTES = [
     { id: "devices-list", path: "/v1/devices", credentialGated: ["GET"], methods: ["GET"] },
+    { id: "device-enroll-tokens", path: "/v1/devices/enroll-tokens", credentialGated: ["POST"], methods: ["POST"] },
+    { id: "device-enroll", path: "/v1/devices/enroll", credentialGated: ["POST"], methods: ["POST"] },
+    { id: "device-revoke", pattern: /^\/v1\/devices\/(?<deviceId>[^/]+)\/revoke$/, label: "/v1/devices/:deviceId/revoke", methods: ["POST"] },
     { id: "device-session-rebind", pattern: /^\/v1\/devices\/sessions\/(?<rootSessionId>[^/]+)\/rebind$/, label: "/v1/devices/sessions/:id/rebind", methods: ["POST"] },
     { id: "device-session", pattern: /^\/v1\/devices\/sessions\/(?<rootSessionId>[^/]+)$/, label: "/v1/devices/sessions/:id", credentialGated: ["GET"], methods: ["GET"] },
     { prefix: "/v1/devices/", credentialGated: ["POST"] },

package/dist/http/routes/tasks.js

@@ -21,6 +21,7 @@ import { collectSsePreamble } from "../sse-log.js";
 import { buildApprovalPreamble, buildApprovalPreambleSseFrames } from "../../approval-card.js";
 import { createApprovalCardEmitter, resolveApprovalLeg, resolveStreamApprovalGate } from "../../tool-approval.js";
 import { buildActiveRunConflict, toDoneFrameResult } from "../active-run-conflict.js";
+import { commitPlacement, devicePlacementErrorBody } from "../device-placement.js";
 import { headerStr, gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
 import { failOpenTagForDroppedFrame, recordFailOpen } from "../../observability/fail-open.js";
 import { assertNever } from "../route-ctx.js";
@@ -226,6 +227,12 @@ export async function handleTasks(req, res, match, ctx) {
                         sseData(res, { type: "done", result: toDoneFrameResult(conflict) });
                         return { status: 409, body: conflict };
                     }
+                    const placementReject = await commitPlacement(deps, deps.runStore, tid, prepared.bindingIntent);
+                    if (placementReject) {
+                        const body = devicePlacementErrorBody(placementReject);
+                        sseData(res, { type: "done", result: { status: "failed", errorCode: body.errorCode, errorMessage: body.error } });
+                        return { status: placementReject.status, body };
+                    }
                     durableTaskId = tid;
                 }
                 if (prepared.spec.sessionId)
@@ -771,6 +778,9 @@ export async function handleTasks(req, res, match, ctx) {
                         recordResourceWindow(tid, prepared.spec.resourceSuspend);
                     if (!created.ok)
                         return { status: 409, body: await buildActiveRunConflict({ runStore: deps.runStore, checkpointStore: deps.checkpointStore, governance: deps.config, runStaleSec: deps.config.runStaleSec, turnActivity: readTurnActivityMs }, prepared.spec.sessionId, created.activeTaskId) };
+                    const placementReject = await commitPlacement(deps, deps.runStore, tid, prepared.bindingIntent);
+                    if (placementReject)
+                        return { status: placementReject.status, body: devicePlacementErrorBody(placementReject) };
                     deps.sessionTitler?.maybeTitle(prepared.spec.sessionId, prepared.spec.objective, typeof prepared.spec.model === "string" ? prepared.spec.model : prepared.spec.model?.id);
                     durableTaskId = tid;
                 }

package/dist/http/server.d.ts

@@ -304,6 +304,19 @@ export interface ServiceSeamDeps {
      * v2 换绑稿 §7)。
      */
     deviceStore?: import("../device-store.js").DeviceStore;
+    /**
+     * S-470(车C 余件):device lane 的**准入链**(`createDeviceEnrollment`)—— 管理面三个写动词
+     * (签发 / 注册 / 吊销)与首绑写协议(`commitPlacement`)的**唯一**判据属主。
+     *
+     * 🔴 为什么路由拿的是它而不是 {@link deviceStore}:enrollment 那一层持着两件路由造不出来的东西 ——
+     * ①跨副本限速座(`DeviceEnrollRateLimiter`,§7-T5 ⑤:端点车**必须**传一个,而它由 boot 从既有
+     * `RateGate` 适配);②反枚举拒绝的**单一铸造点**(四种 enrollment 失败理由在 wire 上逐字节同形)。
+     * 路由若绕过它直接打店,那两件就会在路由里被手抄第二份 —— 而手抄的那份迟早漏一臂。
+     *
+     * 与 {@link deviceStore} / {@link deviceHub} **同源装配**(`boot/device-lane.ts` 一处建齐三件),
+     * 所以三者的在场性是同一个事实;族内 501 谓词因此可以是「三件齐」这一句话。
+     */
+    deviceEnrollment?: import("../device-enrollment.js").DeviceEnrollment;
     /** Audit回溯: current context (+ summary) for a session, plus its owner. Enables GET /v1/sessions/:id. */
     sessionAudit?: (sessionId: string) => Promise<({
         owner: string | null;

package/dist/http/wire-types.d.ts

@@ -362,6 +362,21 @@ export interface TaskRequestBody {
      *  (a caller can't point a shared/cloud worker at an arbitrary host path). Validated absolute (prepareSpec 400s a
      *  relative cwd — it would silently resolve against the SERVICE process cwd). */
     cwd?: string;
+    /**
+     * S-470(device lane 首绑写协议,design `device-executor-lane-v2` §4.3.2)—— 这条**根会话**要执行在
+     * 哪台已注册的员工设备上(`POST /v1/devices/enroll` 返回的 `dev_<ulid>`)。
+     *
+     * 与 {@link cwd} **同级同信任姿势**:调用方供给、server 闸裁 —— 它不是身份,身份恒取验证过的
+     * 复合身份链;它只是「在我自己名下的设备里挑一台」。
+     *  · 仅 `REMOTE_EXEC=device` 的部署接受;其它车道收到它 = **400 响亮拒**(不静默忽略 —— 调用方会
+     *    以为自己指定了执行设备,而那条声明从未存在);
+     *  · 仅**根任务**提交携带(子代无条件继承根绑定,core 为 subagent/cascade/verify 另铸 sessionId);
+     *  · 首绑 = INSERT-if-absent CAS(并发单赢家);后续根提交:缺席 = 沿用绑定 / 携且同 = 幂等 /
+     *    携且异 = 403 `device.identity_mismatch`(**v1 无隐式重绑**,换设备走
+     *    `POST /v1/devices/sessions/:rootSessionId/rebind`);
+     *  · resume 家族(`/decide` / `/answer` / `/plan_review` / `/wake`)**不收**这个键:车道随树固定。
+     */
+    deviceId?: string;
     /** [ref] (CC `--add-dir`, core `TaskSpec.additionalDirectories`): extra host dirs the FILE tools may reach
      *  beyond the containment root. 🔒 Gated exactly like `cwd`/`shellEnv` — honored ONLY on the single-user host
      *  lane (`task-cwd.ts` `cwdHonored`); off that lane `boot/resolve-spec.ts` drops them with a loud

package/dist/model-route-url.d.ts

@@ -0,0 +1,15 @@
+/** 机读码(拼法随 `config.<键名蛇形>_*` 既有族:`config.model_provider_invalid` / `config.retention_policy_invalid`)。 */
+export declare const GATEWAY_URL_USERINFO_CODE = "config.gateway_url_userinfo";
+/** 这个 URL 带 userinfo(用户名或密码任一非空)吗?解析不动 ⇒ `false`(「不是 URL」由别的门管,本条只判凭据位)。 */
+export declare function urlCarriesUserinfo(raw: string): boolean;
+/**
+ * 模型路由 base URL 的拒因(`undefined` = 这一位合法)。
+ *
+ * 拒因四件齐:**码** + **哪个 env 键** + **洗过的 URL**(host/port/path 逐字,userinfo 与凭据参数成记号 ——
+ * 运维要靠 host 认出是哪一条路由,而密码一个字节都不许进启动错误)+ **出路一句**(点名真实旋钮)。
+ *
+ * @param envKey 出问题的那根 env 旋钮的名字(CSV 键上还带第几项)。
+ * @param credentialKnob 这条路由把凭据放哪儿 —— 出路一句点名的旋钮名。
+ */
+export declare function modelRouteUrlRefusal(envKey: string, raw: string, credentialKnob: string): string | undefined;
+//# sourceMappingURL=model-route-url.d.ts.map

package/dist/model-route-url.js

@@ -0,0 +1,19 @@
+import { buildDisplaySafeUrl } from "./trace/redact.js";
+export const GATEWAY_URL_USERINFO_CODE = "config.gateway_url_userinfo";
+export function urlCarriesUserinfo(raw) {
+    if (raw === "" || !URL.canParse(raw))
+        return false;
+    const u = new URL(raw);
+    return u.username !== "" || u.password !== "";
+}
+export function modelRouteUrlRefusal(envKey, raw, credentialKnob) {
+    if (!urlCarriesUserinfo(raw))
+        return undefined;
+    return (`env ${envKey} carries credentials in the URL userinfo (${buildDisplaySafeUrl(raw)}) [${GATEWAY_URL_USERINFO_CODE}] — ` +
+        "WHATWG forbids constructing a fetch Request from a URL with credentials, so EVERY model call on this route " +
+        "fails deterministically at request-construction time (it used to look like a slow network flake: the error was " +
+        "retried for ~3 minutes before surfacing). " +
+        `Put the credential in ${credentialKnob} (or the matching header knob) instead of the URL, and keep the URL to ` +
+        "scheme/host/port/path.");
+}
+//# sourceMappingURL=model-route-url.js.map

package/dist/request-key-closure.js

@@ -20,7 +20,7 @@ export function keyClosureClause(names, label) {
 const TASK_BODY_DECLARED_KEYS = [
     "a2aPeers", "acceptPartialRestore", "additionalDirectories", "additionalReadDirectories", "agents",
     "appendSystemPrompt", "attachmentIds", "attachments", "capabilitiesNeeded", "cascade", "clientContext",
-    "compaction", "compactionModel", "council", "cwd", "debate", "deferTools", "enableFork", "excludeTools",
+    "compaction", "compactionModel", "council", "cwd", "debate", "deferTools", "deviceId", "enableFork", "excludeTools",
     "finalVerification", "forwardSubagentEvents", "images", "interactiveTools", "jobId", "limits", "maxCostUsd",
     "maxTokens", "mcpServers", "memory", "memoryCapture", "memoryWrite", "model", "objective", "oneShot", "outputRetries",
     "outputSchema", "permissionMode", "projectId", "promptProfile", "reasoningEffort", "requireExistingSession",

package/dist/run-local.js

@@ -43,6 +43,7 @@ import { createKeyResolver } from "./key-resolver.js";
 import { createLogger } from "./observability/logger.js";
 import { createMetrics } from "./observability/metrics.js";
 import { installSecretEnvScrubRecorder } from "./observability/secret-env-scrub.js";
+import { buildDisplaySafeUrl } from "./trace/redact.js";
 export function parseArgs(argv) {
     let objective;
     let root;
@@ -299,7 +300,7 @@ export async function runLocal(argv, deps = {}) {
             ...(config.memorySync.maxPushEntries !== undefined ? { maxPushEntries: config.memorySync.maxPushEntries } : {}),
             ...(config.memorySync.maxPullEntries !== undefined ? { maxPullEntries: config.memorySync.maxPullEntries } : {}),
         });
-        logger.info("memory_sync_enabled", { url: config.memorySync.url, scope: config.memorySync.scope, cursorPath: memorySync.cursorPath });
+        logger.info("memory_sync_enabled", { url: buildDisplaySafeUrl(config.memorySync.url), scope: config.memorySync.scope, cursorPath: memorySync.cursorPath });
         memorySync.trigger("boot");
     }
     else if (config.memorySync) {

package/dist/sealed-key.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { chmod, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import _sodium from "libsodium-wrappers";
+import { buildDisplaySafeUrl } from "./trace/redact.js";
 export const SEALED_KEY_ALG = "libsodium-sealedbox-x25519";
 const SEAL_OVERHEAD_BYTES = 48;
 const BASE64_STRICT = /^[A-Za-z0-9+/]+={0,2}$/;
@@ -104,7 +105,7 @@ export async function reportExecutionPublicKey(opts) {
             alg: SEALED_KEY_ALG,
             createdAt: key.createdAt,
             why,
-            register: `POST ${baseUrl ?? "<registry>"}/api/config/execution-keys (admin token) body {"publicKey":"${key.publicKey}","publicKeyId":"${key.publicKeyId}"}`,
+            register: `POST ${baseUrl === undefined ? "<registry>" : buildDisplaySafeUrl(baseUrl)}/api/config/execution-keys (admin token) body {"publicKey":"${key.publicKey}","publicKeyId":"${key.publicKeyId}"}`,
             note: "until an admin registers this public key, web-pasted (sealed) api keys cannot target this host",
         });
     };

package/dist/security.d.ts

@@ -185,6 +185,12 @@ export declare class HttpError extends Error {
         extra?: Record<string, unknown>;
     });
 }
+/**
+ * 带机读码的 {@link HttpError} 的**构造点**。出门时这只码落在 wire 错误体的 `errorCode` 键上(`http/send.ts`),
+ * 从不以裸 `code` 键出现 —— 3.0.0 起 `errorCode` 是错误体唯一的机器判别键。`http/` 树里的模块经它抛带码错误,
+ * 不手写 `{ code }` 选项字面量(那一层有一道按行扫裸 `code:` 键的门,手写字面量与「真发了 legacy 键」同形)。
+ */
+export declare function createCodedHttpError(status: number, errorCode: string, message: string, extra?: Record<string, unknown>): HttpError;
 /**
  * Authorization context resolved per request, BEFORE building the TaskSpec. The service owns this —
  * identity and tenant scope come from the authenticated channel, **never from the request body**.

package/dist/security.js

@@ -39,6 +39,9 @@ export class HttpError extends Error {
             this.extra = opts.extra;
     }
 }
+export function createCodedHttpError(status, errorCode, message, extra) {
+    return new HttpError(status, message, extra === undefined ? { code: errorCode } : { code: errorCode, extra });
+}
 export function createAuthorizer(config, sessionStore) {
     return async ({ req, body }) => {
         const principal = verifiedPrincipal(req, config);

package/dist/trace/redact.d.ts

@@ -136,4 +136,24 @@ export declare function redactDeep(value: unknown): unknown;
  * owner-scoped, so this preview is only ever shown to the ask's own principal (or an operator inspecting it).
  */
 export declare function redactedPreview(value: unknown, cap?: number): string | null;
+/**
+ * 🔴 **配置型 URL 上日志 / 诊断面的唯一 display-safe 铸点**(S-475 件B;`build*` = 返回纯数据的一只纯函数)。
+ *
+ * 病(7.87.2 亲核):启动日志 `listening` 行把配置里的 URL 写**原值** —— `brain: brainSummary(config)` 里的
+ * `gateway: config.gatewayBaseUrl` 与同行的 `otel: config.otel.endpoint`,logger 不脱敏。部署若把凭据放在
+ * 网关 URL 的 userinfo / query 里,密码明文落 `engine-*.log`(日志的读者面比 run 错误文本更宽:它落盘、
+ * 被采集、进工单)。同类出口不止这两处,类级机器门在 `test/config-url-display-safe.test.ts`。
+ *
+ * **内部就调 {@link redactSecrets} —— 同一条 URL 律、同一张名表、同一批记号,零第二份实现**:
+ * 本函数自己只加两件事,两件都是**配置型 URL 特有**的:
+ *  ① **有效性闸**:配置里的那一位应当是一个**绝对 URL**。`new URL(raw)` 解析不动 ⇒ 这一位根本不是 URL
+ *     (裸 `host:port`、相对路径、手滑的散文),自由文本的 URL 律对它没有定界依据 ⇒ 返回**占位**
+ *     {@link DISPLAY_SAFE_URL_TOKEN},**不回落原值**([ref]:安全轴上的兜底必须 fail-closed 或响亮)。
+ *     成文代价:`MODEL_GATEWAY_BASEURL=127.0.0.1:8000` 这种缺 scheme 的配置在日志上变成 `«redacted:url»`
+ *     —— 而它在 `fetch` 那一侧本来就是必然失败的形(WHATWG 要求绝对 URL),日志上响亮一点方向一致。
+ *  ② **空串 = 未设**:里面没有凭据,原样回空串(不铸占位 —— 占位会让「没配」读成「配了但看不见」)。
+ * 解析成功后**不重建 URL**(`new URL(...).toString()` 会归一化路径/端口/大小写):保形是这条律的一半,
+ * 运维要靠 host / port / path / 非凭据参数逐字排障,所以回的是**原串经脱敏器**的结果。
+ */
+export declare function buildDisplaySafeUrl(raw: string): string;
 //# sourceMappingURL=redact.d.ts.map