@sema-agent/server 7.146.0 → 7.148.0

package/dist/brain.d.ts

@@ -1,6 +1,6 @@
 import { type Brain, type BreakerState, type Model } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
-import { type SealedCustodyPoison } from "./key-resolver.js";
+import { type CredentialIdentity } from "./key-resolver.js";
 import { type RestartSliceCtx } from "./web-admin-client/restart-signal.js";
 /**
  * 配了快切层(failover ≥2 路 / 断路器)时,**每路**的重试上限。
@@ -62,24 +62,13 @@ export type DegradeRoutePlane = Pick<ServiceConfig, "degrade" | "models" | "gate
  */
 export declare function degradeTargetOf(config: Pick<ServiceConfig, "degrade" | "models">): Model | undefined;
 /**
- * [ref](R1):降级壳里目标自有凭据的**身份**(不是值)—— 与目标那只 Model 同一代,在 createBrain 组壳那一刻冻结。
- *  · `apiKeyEnv` —— 那一代给目标配的 env 变量**名**;壳每跳按这个名字现读值(同名轮换仍热;变量被删 ⇒ [ref] 起 `env_missing` 毒丸,跳响亮拒 —— 7.105.0 及以前是「与自有凭据缺席同一臂」、落网关 key 档)。
- *  · `sealed` —— 那一代托管密钥的解封产物(明文,或解不开时的毒丸;与 `config.modelApiKeys` 的值同型)。托管密钥的身份是它的密文;
- *    本进程的托管店在 boot 读一次、此后不变(`ensureSealedKeyStore`),同一密文恒解出同一产物 —— 所以持有那一代的产物就是持有
- *    那一代的身份(壳里没有密文与托管店,也不需要)。重贴 = 新 key = 新身份,要重启才进壳 —— `degrade-route` 指纹带它的身份摘要,
- *    所以重贴会签。🔴 明文是活秘密:只活在壳的闭包里,指纹只取摘要({@link degradeRouteFingerprint}),绝不进日志 / 序列化面。
- * 目标没有自有凭据 ⇒ `{}`。两张表至多一个条目有效(registry-core 互斥:带 sealedApiKey 的条目不落 modelApiKeyEnv)。
+ * [ref]:读出 `target`(降级壳焊的那只目标,{@link degradeTargetOf})此刻的凭据**身份**(不是值;读法是 key 链的 `credentialIdentityOf`,
+ * 与记忆整理席同一只)—— 唯一读法:createBrain 组壳时与目标 Model 一起冻结它,`degrade-route` 指纹的两侧读数与启动摘要同读它。
+ * 查的名字与序:目标真名、再 `degrade.to`(后者可能是 `default` 别名,两张 key 表按真名索引、env 车道的目录则反过来);每个名字上托管密钥压过 env 引用。
+ * 托管密钥重贴 = 新身份,要重启才进壳 —— 指纹带它的身份摘要,所以重贴会签。🔴 明文是活秘密:只活在壳的闭包里,指纹只取摘要,绝不进日志 / 序列化面。
+ * 目标没有自有凭据 ⇒ `{}`。
  */
-export interface DegradeCredentialIdentity {
-    readonly apiKeyEnv?: string;
-    readonly sealed?: string | SealedCustodyPoison;
-}
-/**
- * [ref]:读出 `target`(降级壳焊的那只目标,{@link degradeTargetOf})此刻的凭据身份 —— **唯一**读法:createBrain 组壳时冻结它,
- * `degrade-route` 指纹的两侧读数与启动摘要同读它。查表的键与序与修前 `fbOwnApiKey` 同:目标真名、再 `degrade.to`(后者可能是
- * `default` 别名,两张 key 表按真名索引、env 车道的目录则反过来);每个名字上托管密钥压过 env 引用(key-resolver 的序)。
- */
-export declare function degradeCredentialIdentityOf(config: Pick<ServiceConfig, "degrade" | "modelApiKeyEnv" | "modelApiKeys">, target: Pick<Model, "name">): DegradeCredentialIdentity;
+export declare function degradeCredentialIdentityOf(config: Pick<ServiceConfig, "degrade" | "modelApiKeyEnv" | "modelApiKeys">, target: Pick<Model, "name">): CredentialIdentity;
 /**
  * [ref]:降级壳的**路由指纹**(纯数据)—— `degrade-route` 重启片 `baked` / `current` 两侧读数的唯一读法。
  *

package/dist/brain.js

@@ -2,8 +2,7 @@ import { adjudicateModelRoute, createAnthropicBrain, createCircuitBreakerBrain,
 import { routeKeyOf } from "@sema-agent/core";
 import { buildDefaultResilience } from "./config-types.js";
 import { resolveModelApiKey } from "./key-resolver.js";
-import { createHash } from "node:crypto";
-import { isModelKeyPoison, modelKeyPoisonIdentity } from "./key-resolver.js";
+import { credentialIdentityFingerprint, credentialIdentityOf } from "./key-resolver.js";
 import { anthropicRouteRoot, brainLaneFor, mountRoutes, routeTableOf } from "./model-provider.js";
 import { openaiRouteBaseUrl } from "./model-route-endpoint.js";
 import { anthropicLaneCredentialOf, declaredCredential } from "./model-route-gap.js";
@@ -156,12 +155,9 @@ export function degradeTargetOf(config) {
 }
 export function degradeCredentialIdentityOf(config, target) {
     for (const name of config.degrade === undefined ? [target.name] : [target.name, config.degrade.to]) {
-        const sealed = config.modelApiKeys?.[name];
-        if (sealed !== undefined)
-            return { sealed };
-        const apiKeyEnv = config.modelApiKeyEnv?.[name];
-        if (apiKeyEnv !== undefined)
-            return { apiKeyEnv };
+        const identity = credentialIdentityOf(config, name);
+        if (identity.sealed !== undefined || identity.apiKeyEnv !== undefined)
+            return identity;
     }
     return {};
 }
@@ -175,17 +171,9 @@ function degradeWeldFingerprint(config, target, credential) {
     return {
         model: catalogEntryFingerprint(target),
         endpoint: openaiRouteBaseUrl(target.baseUrl, config.gatewayBaseUrl) ?? null,
-        apiKeyEnv: credential.apiKeyEnv ?? null,
-        sealedKey: sealedIdentityFingerprint(credential.sealed),
+        ...credentialIdentityFingerprint(credential),
     };
 }
-function sealedIdentityFingerprint(sealed) {
-    if (sealed === undefined)
-        return null;
-    if (isModelKeyPoison(sealed))
-        return { poisoned: modelKeyPoisonIdentity(sealed), reason: sealed.reason };
-    return { digest: createHash("sha256").update(sealed, "utf8").digest("hex").slice(0, 16) };
-}
 export function buildFailoverFirstByteNotice(config) {
     const r = config.resilience ?? DEFAULT_RESILIENCE;
     const fallbacks = config.gatewayFallbackUrls.length;

package/dist/budget.js

@@ -1,5 +1,5 @@
 import { isModelPriced, modelCostToPricing } from "@sema-agent/core";
-import { currentPrincipal } from "./observability/principal-context.js";
+import { currentPerson } from "./observability/principal-context.js";
 import { isPermissionRuleEventKind, permissionRuleEventWordOf } from "./observability/permission-rule-events.js";
 import { promptManifestRecordOf, configAssembledRecordOf } from "./observability/prompt-manifest.js";
 import { crossBoundaryTaintEventData } from "./trace/project.js";
@@ -85,9 +85,9 @@ export function createTracer(metrics, costQuota, modelUsage, fleetUsage, fleetLe
             metrics.inc("brain_calls_total", { provider: providerName(e.provider ?? "unknown"), model: modelId(e.model) });
             if (e.costMicroUsd) {
                 metrics.inc("model_cost_micro_usd_total", { model: modelId(e.model) }, e.costMicroUsd);
-                const principal = currentPrincipal();
-                if (principal)
-                    costQuota?.add(principal, e.costMicroUsd);
+                const person = currentPerson();
+                if (person)
+                    costQuota?.add(person, e.costMicroUsd);
             }
             else if (e.costMicroUsd === undefined) {
                 metrics.inc("brain_calls_unpriced_total", { model: modelId(e.model) });
@@ -96,8 +96,8 @@ export function createTracer(metrics, costQuota, modelUsage, fleetUsage, fleetLe
             const qwRaw = quotaWeightFor?.(e.model);
             const qw = typeof qwRaw === "number" && Number.isFinite(qwRaw) && qwRaw > 0 ? qwRaw : 1;
             const weightedTokens = Math.round((e.totalInputTokens + e.completionTokens) * qw);
-            fleetUsage?.record(currentPrincipal(), e.model, e.taskId, { inputTokens: e.totalInputTokens, outputTokens: e.completionTokens, ...(e.costMicroUsd !== undefined ? { costMicroUsd: e.costMicroUsd } : {}), weightedTokens, quotaWeightAtUse: qw });
-            fleetLease?.recordSpend(currentPrincipal(), { weightedTokens, ...(e.costMicroUsd !== undefined ? { costMicroUsd: e.costMicroUsd } : {}) });
+            fleetUsage?.record(currentPerson(), e.model, e.taskId, { inputTokens: e.totalInputTokens, outputTokens: e.completionTokens, ...(e.costMicroUsd !== undefined ? { costMicroUsd: e.costMicroUsd } : {}), weightedTokens, quotaWeightAtUse: qw });
+            fleetLease?.recordSpend(currentPerson(), { weightedTokens, ...(e.costMicroUsd !== undefined ? { costMicroUsd: e.costMicroUsd } : {}) });
             if (e.turn !== undefined) {
                 if (e.firstTokenMs !== undefined)
                     metrics.observe("brain_first_token_ms", e.firstTokenMs);

package/dist/capabilities/center-plugins.d.ts

@@ -60,10 +60,16 @@ export declare const PLUGIN_MANIFEST_MAX_BYTES: number;
  *  布局同族)。返回 ok:true+dir:undefined = 插件没有 skills 目录(可以只有 commands——那是 cli 壳的
  *  半场,worker 装 0 个 skill 不算失败);ok:false = 路径逃逸/manifest 本体畸形,整条拒装。
  *  manifest 臂分立(V2-⑦,原 broad-catch 是 fail-open):**不存在**=可选面,缺省 skills/;**存在但**
- *  本体逃逸根外/非普通文件/超界/读失败/JSON 坏 = ok:false 走既有 warning 面。 */
+ *  本体逃逸根外/非普通文件/超界/读失败/JSON 坏 = ok:false 走既有 warning 面。
+ *
+ *  `hooksModule`(ok:true 时同一趟顺带回报,**不**第二次读 manifest):这个插件带不带 hooks 模块 —— 入口有两个,任一在场即真:
+ *  ① manifest 本体是对象且**自有**顶层键 `hooks` 在场(内联对象或路径串都算;只判键在不在,值不判,嵌套里的 `hooks` 字样不算);
+ *  ② `hooks/hooks.json` 条目在场({@link hooksFileEntryMayBePresent},只问条目、不读内容)。
+ *  只是一条事实交给调用方去响(不改上面的装载判定一字:manifest 是非对象 JSON 时照旧可装、缺省 skills/)。 */
 export declare function resolvePluginSkillsRoot(cloneRoot: string): {
     ok: true;
     dir?: string;
+    hooksModule: boolean;
 } | {
     ok: false;
     reason: string;
@@ -97,6 +103,8 @@ export declare function materializablePlugins(eff: {
     url: string;
     sha?: string;
 }>;
+/** 中心 plugin 缓存根 `<数据根>/plugin-cache`(组合根传给 {@link applyCenterPlugins} 的 `cacheRoot` 与一次性迁移 M39 的名册同读这一只)。 */
+export declare function pluginCacheRootFor(dataRoot: string): string;
 /** 总入口(条款 3/7/8):逐条物化 + 装载 + 让位合并。materialize 盘位 = `<cacheRoot>/<name>/live`
  *  (成功后原子 rename 替换,失败保留旧盘位 = LKG)。 */
 export declare function applyCenterPlugins(baseline: LoadedSkill[], eff: {

package/dist/capabilities/center-plugins.js

@@ -2,9 +2,11 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { promises as fsp, realpathSync, existsSync, readFileSync, lstatSync, statSync } from "node:fs";
 import { join, resolve, isAbsolute, sep } from "node:path";
+import { ensureDir, hostOfUrl, HOST_UNREADABLE_SENTENCE } from "@sema-agent/core";
 import { assertConfined, loadSkills } from "./skills.js";
 import { buildDisplaySafeUrl, redactSecrets } from "../trace/redact.js";
 import { gitSubprocessEnv } from "../server-secret-env.js";
+import { errorCodeOf } from "../observability/err-text.js";
 const execFileP = promisify(execFile);
 export const MAX_PLUGIN_SOURCE_URL_CHARS = 2048;
 export const DEFAULT_PLUGIN_ALLOW_HOSTS = ["github.com"];
@@ -35,14 +37,12 @@ export function validatePluginDecl(decl, allowHosts) {
     if (!/^https:\/\//i.test(url)) {
         return { ok: false, name, reason: `plugin source must be an https:// URL (contract: https-only; got ${buildDisplaySafeUrl(url)})` };
     }
-    let host;
-    try {
-        host = new URL(url).hostname.toLowerCase();
-    }
-    catch {
-        return { ok: false, name, reason: "https url does not parse" };
+    const reading = hostOfUrl(url);
+    if ("unreadable" in reading) {
+        return { ok: false, name, reason: `plugin source url names no host this allowlist can judge — ${HOST_UNREADABLE_SENTENCE[reading.unreadable]}` };
     }
-    if (!allowHosts.some((h) => h.toLowerCase() === host)) {
+    const host = reading.host;
+    if (!allowHosts.some((h) => allowlistHostOf(h) === host)) {
         return { ok: false, name, reason: `host ${host} not in PLUGINS_ALLOW_HOSTS (default github.com; extend with a comma-separated https mirror domain list)` };
     }
     if (decl.sha !== undefined) {
@@ -53,6 +53,13 @@ export function validatePluginDecl(decl, allowHosts) {
     }
     return { ok: true, name, url };
 }
+function allowlistHostOf(entry) {
+    const bare = !/[/?#@\\\s]/.test(entry) && (entry.startsWith("[") ? entry.endsWith("]") : !entry.includes(":"));
+    if (!bare || entry === "")
+        return undefined;
+    const reading = hostOfUrl(`https://${entry}/`);
+    return "host" in reading ? reading.host : undefined;
+}
 export function gitClonePlan(o) {
     if (o.sha === undefined) {
         return { steps: [["clone", "--depth", "1", "--quiet", o.url, o.dest]] };
@@ -68,6 +75,7 @@ export function gitClonePlan(o) {
 export const PLUGIN_MANIFEST_MAX_BYTES = 64 * 1024;
 export function resolvePluginSkillsRoot(cloneRoot) {
     let skillsPath = "skills";
+    let manifestHasHooksKey = false;
     const rootReal = realpathSync(cloneRoot);
     const manifestPath = join(cloneRoot, ".claude-plugin", "plugin.json");
     let manifestPresent = false;
@@ -89,11 +97,13 @@ export function resolvePluginSkillsRoot(cloneRoot) {
             const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
             if (typeof manifest.skillsPath === "string" && manifest.skillsPath !== "")
                 skillsPath = manifest.skillsPath;
+            manifestHasHooksKey = Object.hasOwn(manifest, "hooks");
         }
         catch (e) {
             return { ok: false, reason: `plugin manifest rejected: ${e instanceof Error ? e.message : String(e)}` };
         }
     }
+    const hooksModule = manifestHasHooksKey || hooksFileEntryMayBePresent(cloneRoot);
     if (isAbsolute(skillsPath))
         return { ok: false, reason: `skillsPath must be relative (got ${skillsPath})` };
     const candidate = resolve(rootReal, skillsPath);
@@ -101,12 +111,22 @@ export function resolvePluginSkillsRoot(cloneRoot) {
         return { ok: false, reason: `skillsPath escapes the plugin root (${skillsPath})` };
     }
     if (!existsSync(candidate))
-        return { ok: true };
+        return { ok: true, hooksModule };
     const real = realpathSync(candidate);
     if (real !== rootReal && !real.startsWith(rootReal + sep)) {
         return { ok: false, reason: `skillsPath resolves outside the plugin root via symlink (${skillsPath})` };
     }
-    return { ok: true, dir: candidate };
+    return { ok: true, dir: candidate, hooksModule };
+}
+function hooksFileEntryMayBePresent(cloneRoot) {
+    try {
+        lstatSync(join(cloneRoot, "hooks", "hooks.json"));
+        return true;
+    }
+    catch (e) {
+        const code = errorCodeOf(e);
+        return code !== "ENOENT" && code !== "ENOTDIR";
+    }
 }
 const PLUGINS_DOMAIN_FAILURE_NAME = "(plugins domain)";
 function declaredPlugins(eff) {
@@ -132,6 +152,9 @@ export function materializablePlugins(eff, allowHosts) {
         return v.ok ? [{ name: v.name, url: v.url, ...(v.sha !== undefined ? { sha: v.sha } : {}) }] : [];
     });
 }
+export function pluginCacheRootFor(dataRoot) {
+    return join(dataRoot, "plugin-cache");
+}
 export async function applyCenterPlugins(baseline, eff, opts) {
     const shape = declaredPlugins(eff);
     const out = { skills: [...baseline], failures: [], letGo: [], lkgUsed: [] };
@@ -165,12 +188,12 @@ export async function applyCenterPlugins(baseline, eff, opts) {
         let materialized = false;
         try {
             await fsp.rm(staging, { recursive: true, force: true });
-            await fsp.mkdir(staging, { recursive: true });
+            ensureDir(staging);
             const plan = gitClonePlan({ url: v.url, dest: staging, sha: v.sha });
             for (const step of plan.steps)
                 await runGit(step);
             await fsp.rm(liveDir, { recursive: true, force: true });
-            await fsp.mkdir(join(opts.cacheRoot, v.name), { recursive: true });
+            ensureDir(join(opts.cacheRoot, v.name));
             await fsp.rename(staging, liveDir);
             materialized = true;
         }
@@ -194,6 +217,9 @@ export async function applyCenterPlugins(baseline, eff, opts) {
                 opts.logger?.warn("center_plugin_manifest_rejected", { plugin: v.name, reason: rootCheck.reason });
                 continue;
             }
+            if (rootCheck.hooksModule) {
+                opts.logger?.warn("center_plugin_hooks_not_loaded", { plugin: v.name, note: `engine does not load the hooks module of center plugin ${v.name}; skills are loaded` });
+            }
             if (!rootCheck.dir)
                 continue;
             const loaded = loadSkills(rootCheck.dir, { source: "center", confineTo: liveDir, toolsShareThisFilesystem: opts.toolsShareThisFilesystem, ...(opts.logger !== undefined ? { logger: opts.logger } : {}) });

package/dist/capabilities/center-wiring.js

@@ -1,4 +1,4 @@
-import { authBridgeIssuerOf } from "../auth-bridge.js";
+import { authBridgeIssuerOf } from "../identity-source.js";
 import { isDisclosableIdentity } from "@sema-agent/settings-schema";
 export const CENTER_ISSUER_WORDS = ["explicit", "fallback"];
 export function buildCenterWiring(f) {

package/dist/capabilities/composite-members.d.ts

@@ -41,13 +41,14 @@ export declare const COMPOSITE_CAPABILITY_MEMBERS: {
     readonly deviceExecutor: readonly ["enabled", "protocolVersion", "maxInflightPerDevice", "wsPath", "management", "relayUrl"];
     readonly fleet: readonly ["stream", "sessionScope", "observe", "resume", "bgNotifyFailClosed", "steerPriority", "hookFailureNotice", "leaseClient", "generationEcho"];
     readonly memoryEngine: readonly ["backend", "vectorMode"];
-    readonly store: readonly ["declared", "backend", "durable", "degradedReason", "sql"];
+    readonly store: readonly ["declared", "backend", "durability", "degradedReason", "sql"];
     readonly centerWiring: readonly ["effectivePull", "effectiveRevision", "lease", "leaseHealth", "failMode", "usageReport", "issuer", "worker", "caller"];
     readonly webSearch: readonly ["backend"];
     readonly background: readonly ["listFace", "exitFaces"];
     readonly taskSettings: readonly ["permissions", "permissionMode", "model", "outputStyle", "env", "hooks", "pluginHooks", "managedHookGroups", "httpHookAllowlists", "tightenOnlySeats", "approvalFrameFamilies", "autoCompactEnabled"];
     readonly settings: readonly ["permissions"];
-    readonly permissionModeAuto: readonly ["accepted", "classifierSeat", "entitlementSource", "armed", "reason", "model"];
+    readonly settingsContract: readonly ["version", "hookEntryFields"];
+    readonly permissionModeAuto: readonly ["accepted", "classifierSeat", "entitlementSource", "armed", "reason", "refusedBy", "model"];
     readonly writeProtection: readonly ["armed", "rows", "replaced"];
     readonly executionLane: readonly ["provider", "toolsOnThisHost", "isolated"];
     readonly retention: readonly ["mode", "maxAgeDays"];

package/dist/capabilities/composite-members.js

@@ -2,13 +2,14 @@ export const COMPOSITE_CAPABILITY_MEMBERS = {
     deviceExecutor: ["enabled", "protocolVersion", "maxInflightPerDevice", "wsPath", "management", "relayUrl"],
     fleet: ["stream", "sessionScope", "observe", "resume", "bgNotifyFailClosed", "steerPriority", "hookFailureNotice", "leaseClient", "generationEcho"],
     memoryEngine: ["backend", "vectorMode"],
-    store: ["declared", "backend", "durable", "degradedReason", "sql"],
+    store: ["declared", "backend", "durability", "degradedReason", "sql"],
     centerWiring: ["effectivePull", "effectiveRevision", "lease", "leaseHealth", "failMode", "usageReport", "issuer", "worker", "caller"],
     webSearch: ["backend"],
     background: ["listFace", "exitFaces"],
     taskSettings: ["permissions", "permissionMode", "model", "outputStyle", "env", "hooks", "pluginHooks", "managedHookGroups", "httpHookAllowlists", "tightenOnlySeats", "approvalFrameFamilies", "autoCompactEnabled"],
     settings: ["permissions"],
-    permissionModeAuto: ["accepted", "classifierSeat", "entitlementSource", "armed", "reason", "model"],
+    settingsContract: ["version", "hookEntryFields"],
+    permissionModeAuto: ["accepted", "classifierSeat", "entitlementSource", "armed", "reason", "refusedBy", "model"],
     writeProtection: ["armed", "rows", "replaced"],
     executionLane: ["provider", "toolsOnThisHost", "isolated"],
     retention: ["mode", "maxAgeDays"],

package/dist/capabilities/execution-lane.d.ts

@@ -1,6 +1,6 @@
-import { type ExecutionLane, type RemoteExecProvider } from "../execution-lane-caps.js";
+import { type ExecutionLane } from "../execution-lane-caps.js";
 export interface ExecutionLaneCapability {
-    /** 本部署的执行车道词(闭集 = {@link ExecutionLane} 八词;`REMOTE_EXEC` 未设 ⇒ `"in-process"`,见头注 [ref] 段)。 */
+    /** 本部署的执行车道词(闭集 = {@link ExecutionLane} 八词;合成之后恒是部署声明的那一条;无手 = 声明的 `"none"`,见头注)。 */
     readonly provider: ExecutionLane;
     /** 工具跑的那台机器就是本进程这台吗(= server 盘上的绝对路径对模型的工具有没有意义)。
      *  属主 = 部署形表行 `toolsOnThisHost`,与 `skills[].baseDir` 的铸点同一行。 */
@@ -11,13 +11,13 @@ export interface ExecutionLaneCapability {
 }
 /**
  * 部署席 → 消费端窄投影。形照 `projectWebSearchCapability` / `projectSqlEngineCapability`:
- * 不碰 config.ts(只从车道表模块取词与归一读口,那是叶),于是本模块是叶。
+ * 不碰 config.ts(只从车道表模块取能力位,那是叶),于是本模块是叶。
  *
- * 🔴 本处**不写**任何缺席折词([ref] 门 D):缺席归一只在 {@link executionLaneOf} 一处。
+ * 🔴 本处**不写**任何缺席折词([ref] 门 D):入参是已合成的配置,车道必在(没有声明的部署在合成步拒启)。
  */
 export declare function projectExecutionLaneCapability(config: {
-    readonly remoteExec?: {
-        readonly provider: RemoteExecProvider;
-    } | undefined;
+    readonly remoteExec: {
+        readonly provider: ExecutionLane;
+    };
 }): ExecutionLaneCapability;
 //# sourceMappingURL=execution-lane.d.ts.map

package/dist/capabilities/execution-lane.js

@@ -1,7 +1,7 @@
 import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
-import { executionLaneOf, laneIsolated, laneWiresExecutionEnv } from "../execution-lane-caps.js";
+import { laneIsolated, laneWiresExecutionEnv } from "../execution-lane-caps.js";
 export function projectExecutionLaneCapability(config) {
-    const lane = executionLaneOf(config.remoteExec?.provider);
+    const lane = config.remoteExec.provider;
     const handsWired = laneWiresExecutionEnv(lane);
     return {
         provider: lane,

package/dist/capabilities/hands-lane.d.ts

@@ -42,7 +42,7 @@ export declare function pickHandsRunner(hands: ScenarioHands, pair: HandsRunnerP
 /**
  * 一个场景在一台部署上起的 run **有没有工作区** —— core prepare 的 `handsEnabled`(`ownedEnv || deps.executionEnv`)在本仓的镜像,**唯一一只判官**。
  * 两个条件缺一不可:场景挂手({@link pickHandsRunner} 选有手 Runner,即带 `executionEnvFactory` 的那只)∧ 这台部署的执行车道有手
- * (`execution-lane-caps.ts` 的 `laneWiresExecutionEnv`:`in-process` 车道整台没有 factory)。引擎对 `userAttachments` 里 `path` 条目的拒
+ * (`execution-lane-caps.ts` 的 `laneWiresExecutionEnv`:`none` 车道整台没有 factory)。引擎对 `userAttachments` 里 `path` 条目的拒
  * (`config.user_attachment_invalid`「this run has no workspace」)与场景详情读面的 `attachmentSupplies` 都落在这一只的答案上。
  * **穷举 switch**:`ScenarioHands` 加词而此处不表态 = 编译红(与 {@link pickHandsRunner} 同一条纪律)。
  */

package/dist/capabilities/repo-tools.d.ts

@@ -27,6 +27,7 @@ export declare function createRepoClient(kind: GitApiKind, baseUrl: string, toke
 export declare class GiteaClient implements RepoReadClient {
     private readonly baseUrl;
     private readonly token?;
+    /** 出站出口:Git host 回重定向 ⇒ 拒(`token` 凭据头只去被判过的那个根),不是静默跟随。 */
     private readonly fetchImpl;
     constructor(baseUrl: string, token?: string | undefined, fetchImpl?: typeof fetch);
     private api;
@@ -51,6 +52,7 @@ export declare class GiteaClient implements RepoReadClient {
 export declare class GitHubClient implements RepoReadClient {
     private readonly baseUrl;
     private readonly token?;
+    /** 出站出口:Git host 回重定向 ⇒ 拒(Bearer 凭据只去被判过的那个根),不是静默跟随。 */
     private readonly fetchImpl;
     constructor(baseUrl: string, token?: string | undefined, fetchImpl?: typeof fetch);
     private api;

package/dist/capabilities/repo-tools.js

@@ -13,6 +13,8 @@ export function parseRepo(input) {
 const MAX_FILE_BYTES = 96 * 1024;
 const MAX_TREE_ENTRIES = 2000;
 const REQUEST_TIMEOUT_MS = 15_000;
+import { createEgressFetch } from "../egress-redirect.js";
+import { readUpstreamJson } from "../upstream-body.js";
 export { GIT_API_KINDS, isGitApiKind } from "../git-api-kind.js";
 const RepoInfoWire = z.looseObject({ default_branch: z.string().optional() });
 const TreeWire = z.looseObject({
@@ -32,7 +34,7 @@ function pathSegmentsRejectingTraversal(path) {
     }
     return segments;
 }
-export function createRepoClient(kind, baseUrl, token, fetchImpl = fetch) {
+export function createRepoClient(kind, baseUrl, token, fetchImpl) {
     switch (kind) {
         case "gitea":
             return new GiteaClient(baseUrl, token, fetchImpl);
@@ -48,10 +50,10 @@ export class GiteaClient {
     baseUrl;
     token;
     fetchImpl;
-    constructor(baseUrl, token, fetchImpl = fetch) {
+    constructor(baseUrl, token, fetchImpl) {
         this.baseUrl = baseUrl;
         this.token = token;
-        this.fetchImpl = fetchImpl;
+        this.fetchImpl = createEgressFetch("declare the final address as GIT_API_BASEURL", fetchImpl);
     }
     async api(path, accept = "application/json") {
         const headers = { accept };
@@ -66,12 +68,12 @@ export class GiteaClient {
         return res;
     }
     async defaultBranch({ owner, repo }) {
-        const info = RepoInfoWire.parse(await (await this.api(`/repos/${owner}/${repo}`)).json());
+        const info = RepoInfoWire.parse(await readUpstreamJson(await this.api(`/repos/${owner}/${repo}`)));
         return info.default_branch || "main";
     }
     async tree(coords, ref) {
         const { owner, repo } = coords;
-        const body = TreeWire.parse(await (await this.api(`/repos/${owner}/${repo}/git/trees/${encodeURIComponent(ref)}?recursive=true&per_page=${MAX_TREE_ENTRIES}`)).json());
+        const body = TreeWire.parse(await readUpstreamJson(await this.api(`/repos/${owner}/${repo}/git/trees/${encodeURIComponent(ref)}?recursive=true&per_page=${MAX_TREE_ENTRIES}`)));
         const paths = (body.tree ?? []).filter((e) => e.type === "blob").map((e) => e.path);
         return body.truncated
             ? [...paths, `…[truncated, tree has more than ${MAX_TREE_ENTRIES} entries]`]
@@ -80,7 +82,7 @@ export class GiteaClient {
     async readFile(coords, path, ref) {
         const { owner, repo } = coords;
         const segments = pathSegmentsRejectingTraversal(path);
-        const body = ContentsWire.parse(await (await this.api(`/repos/${owner}/${repo}/contents/${segments.map(encodeURIComponent).join("/")}?ref=${encodeURIComponent(ref)}`)).json());
+        const body = ContentsWire.parse(await readUpstreamJson(await this.api(`/repos/${owner}/${repo}/contents/${segments.map(encodeURIComponent).join("/")}?ref=${encodeURIComponent(ref)}`)));
         if (body.type !== "file" || body.content == null)
             throw new Error(`not a file: ${path}`);
         const text = body.encoding === "base64" ? Buffer.from(body.content, "base64").toString("utf8") : body.content;
@@ -99,10 +101,10 @@ export class GitHubClient {
     baseUrl;
     token;
     fetchImpl;
-    constructor(baseUrl, token, fetchImpl = fetch) {
+    constructor(baseUrl, token, fetchImpl) {
         this.baseUrl = baseUrl;
         this.token = token;
-        this.fetchImpl = fetchImpl;
+        this.fetchImpl = createEgressFetch("declare the final address as GIT_API_BASEURL", fetchImpl);
     }
     async api(path, accept = "application/vnd.github+json") {
         const headers = { accept, "x-github-api-version": "2022-11-28" };
@@ -117,12 +119,12 @@ export class GitHubClient {
         return res;
     }
     async defaultBranch({ owner, repo }) {
-        const info = RepoInfoWire.parse(await (await this.api(`/repos/${owner}/${repo}`)).json());
+        const info = RepoInfoWire.parse(await readUpstreamJson(await this.api(`/repos/${owner}/${repo}`)));
         return info.default_branch || "main";
     }
     async tree(coords, ref) {
         const { owner, repo } = coords;
-        const body = TreeWire.parse(await (await this.api(`/repos/${owner}/${repo}/git/trees/${encodeURIComponent(ref)}?recursive=1`)).json());
+        const body = TreeWire.parse(await readUpstreamJson(await this.api(`/repos/${owner}/${repo}/git/trees/${encodeURIComponent(ref)}?recursive=1`)));
         const paths = (body.tree ?? []).filter((e) => e.type === "blob").map((e) => e.path);
         if (paths.length > MAX_TREE_ENTRIES) {
             return [...paths.slice(0, MAX_TREE_ENTRIES), `…[truncated, tree has more than ${MAX_TREE_ENTRIES} entries]`];
@@ -134,7 +136,7 @@ export class GitHubClient {
     async readFile(coords, path, ref) {
         const { owner, repo } = coords;
         const segments = pathSegmentsRejectingTraversal(path);
-        const body = ContentsWire.parse(await (await this.api(`/repos/${owner}/${repo}/contents/${segments.map(encodeURIComponent).join("/")}?ref=${encodeURIComponent(ref)}`)).json());
+        const body = ContentsWire.parse(await readUpstreamJson(await this.api(`/repos/${owner}/${repo}/contents/${segments.map(encodeURIComponent).join("/")}?ref=${encodeURIComponent(ref)}`)));
         if (body.type !== "file" || body.content == null)
             throw new Error(`not a file: ${path}`);
         if (body.encoding === "none") {
@@ -147,7 +149,7 @@ export class GitHubClient {
     }
     async pullDiff(coords, index) {
         const { owner, repo } = coords;
-        const meta = PullMetaWire.parse(await (await this.api(`/repos/${owner}/${repo}/pulls/${index}`)).json());
+        const meta = PullMetaWire.parse(await readUpstreamJson(await this.api(`/repos/${owner}/${repo}/pulls/${index}`)));
         const res = await this.api(`/repos/${owner}/${repo}/pulls/${index}`, "application/vnd.github.v3.diff");
         let text = await res.text();
         const filesInDiff = (text.match(/^diff --git /gm) ?? []).length;

package/dist/capabilities/scenarios.d.ts

@@ -73,10 +73,9 @@ export declare function buildExcludeToolsSeat(scenarioExcludes: readonly string[
  */
 export interface ScenarioContext {
     /**
-     * 本请求的会话 id。属主 = `boot/resolve-spec.ts` 的 `auth.sessionId`(authorizer 解析 + 归属校验
-     * 过的那一只),**绝不是 `body.sessionId`** —— 后者是调用方自报串,拿它当会话级设施的分区键
-     * 等于让一个租户读另一个租户的清单(同 spec 组装处那条「sessionId comes from `auth`, NEVER the
-     * body」的逐字纪律)。
+     * 本请求的会话 id。属主 = `boot/resolve-spec.ts` 的 `root`(= `opts.execution.root`:authorizer 解析 + 归属校验
+     * 过的那一只,续跑 = checkpoint 的会话),**绝不是 `body.sessionId`** —— 后者是调用方自报串,拿它当会话级设施的分区键
+     * 等于让一个租户读另一个租户的清单(同 spec 组装处那条「根来自执行上下文,绝不来自请求体」的逐字纪律)。
      *
      * 缺席 = 这条调用形本来就没有会话(`parked-revive-surface.ts` 对不交座的行、boot 期那一次 Agent 工具探针、
      * `builtinScenarioDetails` 的工具名探针)。此时会话级设施退化为 per-call 实例 —— 不为它发明
@@ -105,7 +104,7 @@ export interface ScenarioDeps {
      *  could exfil via an arbitrary public URL; the SSRF floor only blocks internal). Single-user TOC keeps WebFetch. */
     requirePrincipal?: boolean;
     /**
-     * [ref]:这台部署的执行车道**有没有手**(`laneWiresExecutionEnv`;`REMOTE_EXEC` 未设 = `in-process` = 没有)。场景详情读面据它与场景自己的 `hands` 表态一起答
+     * [ref]:这台部署的执行车道**有没有手**(`laneWiresExecutionEnv`;声明 `REMOTE_EXEC=none` = 没有)。场景详情读面据它与场景自己的 `hands` 表态一起答
      * 「这个场景的 run 有没有工作区」({@link runHasWorkspace}),进而给出附件可受理供给集。**缺席按没有手读**(宁少说不多说:不广告一个会撞 400 的 `path`)。
      */
     handsLane?: boolean;
@@ -261,18 +260,6 @@ export declare const BUILTIN_SCENARIO_HANDS: {
     readonly scan: "none";
     readonly cowork: "full";
 };
-/**
- * [ref]:内建场景的**技能范围**(技能 `scenarios` 标签按哪个名字匹配)—— **全仓唯一声明处**:各场景工厂交进 `TaskSpec` 的技能与场景卡上的技能清单都按这张表取范围,
- * 再过同一只过滤(`skills.ts` 的 `skillsInScope`),两边因此恒为同一组技能。按 {@link BuiltinScenarioName} 键控 ⇒ 加 / 删一个内建场景而这里没跟 = 编译红。
- * `code` 的范围是 `default`:它与 default 共用一只工厂(工具 / 技能面恒等由构造保证),打了 `scenarios: code` 的技能不进 code 的 run。center 场景的范围是它自己的名字。
- */
-export declare const BUILTIN_SCENARIO_SKILL_SCOPE: {
-    readonly code: "default";
-    readonly default: "default";
-    readonly "code-review": "code-review";
-    readonly scan: "scan";
-    readonly cowork: "cowork";
-};
 /**
  * `branded` = 这台部署是不是品牌部署 —— 部署座挂品牌行读的同一只判官(`brand-identity.ts` `isBrandedDeployment`)交进来;没有默认值:每个调用点说出这件事实。
  * 品牌部署上,品牌行 `when.binding` 那张表里的场景(`BRAND_IDENTITY_SCENARIOS`)的 `promptSummary` 点名 Sema 产品身份 —— 读面说的就是模型收到的。
@@ -310,7 +297,6 @@ export type ScenarioAvailability = {
 export declare function scenarioAvailability(deps: Pick<ScenarioDeps, "repoClient">, toolset: string): ScenarioAvailability;
 /** 拒绝文案的唯一属主:闭集穷举 switch(新增原因词不在这里表态即编译红)。 */
 export declare function scenarioUnavailableMessage(reason: ScenarioUnavailableReason, scenarioLabel: string): string;
-export declare const SCENARIO_NAME_RE: RegExp;
 /**
  * Build the center-declared scenario overlay. Invalid specs are SKIPPED with a warning (never fail
  * boot — same posture as skills/teams); valid ones become scenarios keyed by name, ready to be merged
@@ -350,6 +336,16 @@ export interface ScenarioRuling {
     /** 纯场景名集合(principal/组名不上 wire);空 = 该 principal 无任何指派 = 无治理。 */
     allowlist: string[];
 }
+/**
+ * 一次中心裁定读数(`principalCaps.scenarioRuling` / `peekScenarioRuling` 的答)—— **三态,各恰一条出路**({@link gateScenarioRequest} 逐态判):
+ *  · {@link ScenarioRuling} —— 中心答了治理两键 ⇒ 按它执法(指派为缺省、白名单限点名);
+ *  · `undefined`(**缺席**)—— 这一问没有中心可问,或中心答了但不管场景:部署没接中心(无中心 / 干跑 / `run-local` / 嵌入方不给)、
+ *    匿名运行(无 principal,零中心往返)、旧中心不发治理两键 ⇒ 无治理,请求名或部署缺省;
+ *  · `"unavailable"`(**故障**)—— 部署接了中心、请求带 principal,而这一问答不出来:不可达 / 超时 / 答复读不出(非 2xx、体判坏、
+ *    回声不符、在飞期间凭据身份换了)/ 治理两键形不对 ⇒ 该 run 拒。这位主体此刻的指派与白名单不可知:缺省链可能比他的指派更宽,点名也判不了白名单。
+ * 缺席与故障的界画在「有没有中心可问」:读数的客户端只在部署接了中心时存在,没接中心的部署走不到故障态。
+ */
+export type ScenarioRulingRead = ScenarioRuling | "unavailable" | undefined;
 /**
  * 一个场景名的**来源**(闭集:新增一词 ⇒ {@link danglingScenarioRefusal} 的穷尽 switch 编译红)。
  *  · `ruling` —— 中心按主体指派的场景(`ScenarioRuling.scenario`);
@@ -373,17 +369,21 @@ export declare function danglingScenarioRefusal(name: string, source: ScenarioNa
 /**
  * resolveSpec 的执法入口(指派为默认、body.scenario 可换但限 allowlist)。返回本请求的
  * **在册**生效场景名 —— 返回值一定在 `known` 里:下游直接按它取场景,没有「未知名 → default」的回退臂。
+ * 读数 `ruling` 三态各一条出路({@link ScenarioRulingRead}),判序:
+ *
+ *   1. body.scenario 显式给出而不在册 ⇒ typed 400 `scenario_unknown`(调用方的错;词表面先于治理面,不等中心)。
+ *   2. 读数 `"unavailable"`(中心配了却答不出)⇒ 503 `state.scenario_assignment_unavailable`(体 `permanence: "transient"`:这一拍答不出,
+ *      不是准入策略 —— 续跑腿据它不折成 409 `resume_blocked_by_policy`,见 `http/checkpoint-ctx.ts` 的 `resumeAssemblyRefusalAnswer`),点名与不点名同拒 ——
+ *      这位主体的指派与白名单此刻不可知,缺省链不能替他答,点名也判不了白名单。运维日志一行 `scenario_assignment_unavailable`(`principal`;
+ *      取数失败本身由主体客户端的 `onError` 另记一行)。
+ *   3. body.scenario 显式给出(在册):白名单非空且集外 ⇒ typed 400 `scenario_not_allowed`(附 allowlist —— 机器码归 wire、人话归壳 / web);
+ *      集内,或白名单为空(缺席 / 中心答了「无指派」)⇒ 用户主动切换赢。
+ *   4. body.scenario 未给:ruling 胜者 ⇒ 指派为默认;无胜者(缺席 / `scenario: null`)⇒ defaultScenario。链上的名字不在册 ⇒ 503
+ *      `state.scenario_assignment_unknown`(部署的错 / 中心的错,不是调用方的错),**不**折 default({@link danglingScenarioRefusal})。
  *
- *   - body.scenario 显式给出:不在册 ⇒ typed 400 `scenario_unknown`(调用方的错);allowlist 非空且集外 ⇒ typed 拒绝
- *     (400 `scenario_not_allowed`,附 allowlist ——机器码归 wire、人话归壳/web);集内 ⇒ 用户主动切换赢。allowlist 为空
- *     (无 ruling / 该 principal 三层皆无指派 / caps 面故障)⇒ 无治理约束,现状放行(与「null 落兜底链」同一语义:分配面未覆盖 =
- *     不收紧,恒不比没有治理时更宽;caps 故障不把用户锁死在 default——场景切换不是权限放大面,fail-open
- *     到现状,与 workflows 面的 fail-closed 是刻意的 posture 差异,见 runtime-caps-resolver)。
- *   - body.scenario 未给:ruling 胜者 ⇒ 指派为默认;无胜者 ⇒ defaultScenario 现状链。链上的名字不在册 ⇒ 503
- *     `state.scenario_assignment_unknown`(部署的错 / 中心的错,不是调用方的错),**不**折 default
- *     ({@link danglingScenarioRefusal})。`principal` 只进那一行运维日志,不参与判定。
+ * `principal` 只进运维日志,不参与判定。
  */
-export declare function gateScenarioRequest(ruling: ScenarioRuling | undefined, bodyScenario: unknown, defaultScenario: string, known: readonly string[], logger?: Logger, principal?: string): string;
+export declare function gateScenarioRequest(ruling: ScenarioRulingRead, bodyScenario: unknown, defaultScenario: string, known: readonly string[], logger?: Logger, principal?: string): string;
 /**
  * 一条请求的场景名过门 —— {@link gateScenarioRequest} 的**唯一一处实参装配**。
  *
@@ -395,7 +395,8 @@ export declare function gateScenarioRequest(ruling: ScenarioRuling | undefined,
  *
  * 契约:`(principal, requested) => 在册的场景名`(返回值一定在册;被拒 ⇒ 抛 {@link gateScenarioRequest} 的那几只 typed 错,
  * 读口不改写)。`requested` 非串(缺席)⇒ 门走指派链(ruling 胜者,否则部署缺省),与 run 时同一读法。
- * `principalCaps` 缺席(无中心 / 干跑 / 嵌入方 / `run-local`)⇒ 无 ruling,门退回「请求名或部署缺省」那条现状链。
+ * `principalCaps` 缺席(无中心 / 干跑 / 嵌入方 / `run-local`)⇒ 读数恒缺席,门走「请求名或部署缺省」那条链;
+ * 在场 ⇒ 它的读数三态({@link ScenarioRulingRead})原样交门,故障态由门拒。
  */
 export interface ScenarioGateSources {
     readonly config: {
@@ -404,16 +405,20 @@ export interface ScenarioGateSources {
     /** 场景表(活引用):词表按调用时的自有键取,与表同生同灭。 */
     readonly scenarios: Readonly<Record<string, unknown>>;
     readonly principalCaps: {
-        scenarioRuling(principal: string | undefined): Promise<ScenarioRuling | undefined>;
-        peekScenarioRuling(principal: string | undefined): Promise<ScenarioRuling | undefined>;
+        scenarioRuling(principal: string | undefined): Promise<ScenarioRulingRead>;
+        peekScenarioRuling(principal: string | undefined): Promise<ScenarioRulingRead>;
     } | undefined;
     readonly logger?: Logger;
 }
-export type ScenarioGate = (principal: string | undefined, requested: unknown) => Promise<string>;
+export interface ScenarioGate {
+    (principal: string | undefined, requested: unknown): Promise<string>;
+    /** 在册词表 —— 门判「在不在册」读的**同一张**场景表的自有键(活读,不抄快照)。请求的场景头在分派层判在册读它(读面没有体,不过整只门)。 */
+    readonly known: () => readonly string[];
+}
 /**
- * 门问中心裁定走哪条腿(闭集;新增一词 ⇒ 下面的穷尽 `switch` 编译红)—— 与 `resolveRuntimeCaps` / `peekRuntimeCaps` 是同一对:
+ * 门问中心裁定走哪条腿(闭集;新增一词 ⇒ 下面的穷尽 `switch` 编译红)—— 与 `resolveRuntimeCaps` / `peekRuntimeCapsReading` 是同一对:
  *  · `enforce` —— 任务提交腿:中心裁定走执法腿,center 硬失败铸下的 fail-closed 降级项两腿都认;
- *  · `peek` —— 读面(`GET /v1/capabilities/mcp` 状态面、`GET /v1/sessions/:id/mcp` / `…/a2a` 两张会话面板):只读腿,同一只缓存 / 同一条抓取 / 同一份 fail-open 判决,但硬失败铸的降级项只对读面自己算数,
+ *  · `peek` —— 读面(`GET /v1/capabilities/mcp` 状态面、`GET /v1/sessions/:id/mcp` / `…/a2a` 两张会话面板):只读腿,同一只缓存 / 同一条抓取 / 同一份读数(中心答不出 ⇒ 读面同拒),但硬失败铸的降级项只对读面自己算数,
  *    不替这个主体的真提交留下 `{allowWorkflows:false, allowFork:false, autoMode:false}` 的短窗 deny(读面不许成为别人被拒的原因)。
  */
 export type ScenarioGateLeg = "enforce" | "peek";