@sema-agent/client-core 0.3.0 → 0.4.0

package/dist/classifierVerdictWire.js

@@ -0,0 +1,76 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/classifierVerdictWire.ts 的
+ * **判定半场**搬入(帧识别 + 文案),`surfaceClassifierDeny()` 的**执行半场**留宿主
+ * (它写 Ink `AppState.notifications` 并 lazy `require('../utils/autoModeDenials.js')`——
+ * 两者都是 TUI/Node 私有面,进不了端无关包)。
+ * 🔴 本文件零模块级可变状态(只有常量),故不受 B1「写读口必须同实例」纪律约束:壳侧留
+ * 执行半场、判定走本包,是安全的拆缝(B6 T35/T36/T44 同款「判定半场搬入」姿势)。
+ * 逐字纪律:CLASSIFIER_DENY_SIGNATURE / NOTICE_REASON_MAX(80)/ 通知行三段格式一字节不改。
+ */
+/**
+ * src/sema/classifierVerdictWire.ts — auto-mode 分类器裁决帧的壳侧消费(分类器批3 壳半场,黑板 [907])。
+ *
+ * WIRE 形状(gap-check 2026-07-16 实勘,core 1.279 dist 亲核):
+ *   引擎侧分类器 block(core hooks.js runToolGate)→ decision = deny + decisionReason:"classifier",
+ *   permissionDenied 钩子收 source:"classifier"(server 1.209 只作 metrics 计量,不出独立 deny 帧)——
+ *   壳能看见的唯一 wire 事实 = `tool_end` 帧:
+ *     { type:'tool_end', isError:true, output: [{type:'text', text:'<system-reminder>\n
+ *       auto-mode classifier blocked this call[: <reason>|: [<category>]]\n</system-reminder>'}] }
+ *   (core hooks.js L138 deny message 逐字 + formatHookFeedback 包 system-reminder;
+ *    agent-loop createErrorToolResult 落 content 数组;runtask toolOutputFrom 原样上 wire。)
+ *   ⇒ 消费面按此签名结构性识别,等价于「deny 帧带 source:'classifier'」的判定(签名字符串是
+ *   core 的机器产文面,非模型作文——模型 echo 不会以该签名做 tool_end 错误体开头)。
+ *
+ * 🔴 fail-soft 铁律:识别不中一律静默走原路,绝不伤害事件流。
+ * 🔴 UNTRUSTED:reason 为分类器(模型)产文,只渲染绝不回喂;通知行截断 ≤80(207 同款)。
+ */
+/** core hooks.js 分类器 deny message 的机器签名(逐字锚;lockstep:core 改文案这里必须跟)。 */
+export const CLASSIFIER_DENY_SIGNATURE = 'auto-mode classifier blocked this call';
+/** 通知 reason 段截断(CC 207 L696763 同款 80 → 79+…)。 */
+const NOTICE_REASON_MAX = 80;
+/** wire tool_end.output → 文本(string / content 块数组 / {content} 三形;识别用,轻量本地版)。 */
+function textFromWireOutput(output) {
+    if (typeof output === 'string')
+        return output;
+    const blocks = Array.isArray(output)
+        ? output
+        : output !== null && typeof output === 'object' && Array.isArray(output.content)
+            ? (output.content)
+            : undefined;
+    if (!blocks)
+        return undefined;
+    const texts = blocks
+        .map(b => (b !== null && typeof b === 'object' && typeof b.text === 'string' ? b.text : undefined))
+        .filter((t) => t !== undefined);
+    return texts.length > 0 ? texts.join('\n') : undefined;
+}
+/** 去 <system-reminder> 包裹(formatHookFeedback 逆变换;不包裹则原样)。 */
+function unwrapSystemReminder(text) {
+    const m = /^\s*<system-reminder>\s*\n?([\s\S]*?)\n?\s*<\/system-reminder>\s*$/.exec(text);
+    return m ? m[1] : text;
+}
+/**
+ * 结构性识别一张 tool_end 帧是否为分类器 deny 裁决帧。
+ * 判定 = isError:true ∧ 错误体(去包裹后)以 core 机器签名开头。识别不中 ⇒ undefined(原路)。
+ */
+export function classifierDenyFromToolEnd(ev) {
+    if (!ev || ev.type !== 'tool_end' || ev.isError !== true)
+        return undefined;
+    const raw = textFromWireOutput(ev.output);
+    if (raw === undefined)
+        return undefined;
+    const message = unwrapSystemReminder(raw).trim();
+    if (!message.startsWith(CLASSIFIER_DENY_SIGNATURE))
+        return undefined;
+    const tail = message.slice(CLASSIFIER_DENY_SIGNATURE.length);
+    const reason = tail.startsWith(': ') ? tail.slice(2).trim() : undefined;
+    return { message, ...(reason !== undefined && reason.length > 0 ? { reason } : {}) };
+}
+/** 通知行文案(exported for tests;CC 207 三段 text 化)。 */
+export function classifierDenyNoticeText(toolName, reason) {
+    let r = reason ?? '';
+    if (r.length > NOTICE_REASON_MAX)
+        r = `${r.slice(0, NOTICE_REASON_MAX - 1)}…`;
+    const name = toolName.length > 0 ? toolName.toLowerCase() : 'tool';
+    return `${name} denied by auto mode${r ? ` · ${r}` : ''} · /permissions`;
+}

package/dist/clientContextWireCaps.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/clientContextWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/clientContextWireCaps.ts — PURE projection: the user's LOCAL identity facts (time zone + optional
+ * email) → the `TaskRequest.clientContext` object the SERVICE relays to core `TaskSpec.clientContext`.
+ *
+ * THE GAP THIS CLOSES (design/112, core/search AI 2026-06-30 — core 1.181): the worker container runs UTC and
+ * knows neither the user's time zone nor their identity. Without this, core renders the `# Environment` block's
+ * "today" in CONTAINER time (UTC) — a TOB-fleet user in Asia/Tokyo sees the wrong date, and the model has no
+ * email to attribute work. core 1.181 added the seam `TaskSpec.clientContext?: { timeZone?, userEmail? }`; the
+ * CLIENT half is the shell stamping the user's real IANA zone (+ email when known) onto every request, so core
+ * localizes "today" to the user's zone and ANNOTATES it (e.g. `(Asia/Tokyo)`); absent ⇒ core annotates `(UTC)`.
+ *
+ * SECURITY/CONTRACT (core 1.186 hardening, blackboard 2026-06-30):
+ *   - The `locale` field was a DEAD (zero-consumer) field in 1.181 and was DELETED in 1.186 — we NEVER set it
+ *     (only `timeZone` + `userEmail` actually drive rendering). An invalid IANA zone is core's problem to
+ *     validate (1.186: a malformed zone falls back to UTC + `(UTC)` rather than lying); the shell just forwards
+ *     what `Intl` resolved (always a valid zone on a real host).
+ *   - `userEmail` is benign identity metadata, NOT a secret/token (TaskRequest secret discipline still holds —
+ *     no tokens cross here). Sourced from `SEMA_USER_EMAIL` only when the shell actually knows it; absent ⇒ omit.
+ *
+ * PURE — no module-scope IO of its OWN beyond the caller-supplied `timeZone` + `env`, so it bundles + unit-tests
+ * without the heavy settings/Intl graph (the caller passes the cached `getTimeZone()` from utils/intl). Mirrors
+ * the other *WireCaps projection modules (selfOrchestration/webSearch).
+ */
+import { type EnvLike } from './hostEnv.js';
+/** The env key the shell reads for the user's email (optional). SEMA_-namespaced. */
+export declare const USER_EMAIL_ENV: "SEMA_USER_EMAIL";
+/** The `clientContext` shape the SDK exposes (core 1.186: ONLY timeZone + userEmail are live fields). */
+export interface ClientContext {
+    timeZone?: string;
+    userEmail?: string;
+}
+/**
+ * Build the `{ clientContext }` partial for `toTaskRequest` to spread.
+ *   - `timeZone`: the caller's resolved IANA zone (utils/intl `getTimeZone()` — always a valid zone on a host).
+ *     Omitted only if the host has no resolvable zone (degenerate stripped-ICU) so core annotates `(UTC)`.
+ *   - `userEmail`: trimmed `SEMA_USER_EMAIL`, only when non-empty. Never the empty string (that would read as a
+ *     present-but-blank email to core). Absent env ⇒ omitted.
+ * Returns `{}` (no `clientContext` key) only when BOTH are absent, so a zone-less + email-less host keeps the
+ * request shape unchanged (core defaults to UTC annotation).
+ */
+export declare function clientContextField(timeZone: string | undefined, env?: EnvLike): {
+    clientContext?: ClientContext;
+};

package/dist/clientContextWireCaps.js

@@ -0,0 +1,48 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/clientContextWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/clientContextWireCaps.ts — PURE projection: the user's LOCAL identity facts (time zone + optional
+ * email) → the `TaskRequest.clientContext` object the SERVICE relays to core `TaskSpec.clientContext`.
+ *
+ * THE GAP THIS CLOSES (design/112, core/search AI 2026-06-30 — core 1.181): the worker container runs UTC and
+ * knows neither the user's time zone nor their identity. Without this, core renders the `# Environment` block's
+ * "today" in CONTAINER time (UTC) — a TOB-fleet user in Asia/Tokyo sees the wrong date, and the model has no
+ * email to attribute work. core 1.181 added the seam `TaskSpec.clientContext?: { timeZone?, userEmail? }`; the
+ * CLIENT half is the shell stamping the user's real IANA zone (+ email when known) onto every request, so core
+ * localizes "today" to the user's zone and ANNOTATES it (e.g. `(Asia/Tokyo)`); absent ⇒ core annotates `(UTC)`.
+ *
+ * SECURITY/CONTRACT (core 1.186 hardening, blackboard 2026-06-30):
+ *   - The `locale` field was a DEAD (zero-consumer) field in 1.181 and was DELETED in 1.186 — we NEVER set it
+ *     (only `timeZone` + `userEmail` actually drive rendering). An invalid IANA zone is core's problem to
+ *     validate (1.186: a malformed zone falls back to UTC + `(UTC)` rather than lying); the shell just forwards
+ *     what `Intl` resolved (always a valid zone on a real host).
+ *   - `userEmail` is benign identity metadata, NOT a secret/token (TaskRequest secret discipline still holds —
+ *     no tokens cross here). Sourced from `SEMA_USER_EMAIL` only when the shell actually knows it; absent ⇒ omit.
+ *
+ * PURE — no module-scope IO of its OWN beyond the caller-supplied `timeZone` + `env`, so it bundles + unit-tests
+ * without the heavy settings/Intl graph (the caller passes the cached `getTimeZone()` from utils/intl). Mirrors
+ * the other *WireCaps projection modules (selfOrchestration/webSearch).
+ */
+import { hostEnv } from './hostEnv.js';
+/** The env key the shell reads for the user's email (optional). SEMA_-namespaced. */
+export const USER_EMAIL_ENV = 'SEMA_USER_EMAIL';
+/**
+ * Build the `{ clientContext }` partial for `toTaskRequest` to spread.
+ *   - `timeZone`: the caller's resolved IANA zone (utils/intl `getTimeZone()` — always a valid zone on a host).
+ *     Omitted only if the host has no resolvable zone (degenerate stripped-ICU) so core annotates `(UTC)`.
+ *   - `userEmail`: trimmed `SEMA_USER_EMAIL`, only when non-empty. Never the empty string (that would read as a
+ *     present-but-blank email to core). Absent env ⇒ omitted.
+ * Returns `{}` (no `clientContext` key) only when BOTH are absent, so a zone-less + email-less host keeps the
+ * request shape unchanged (core defaults to UTC annotation).
+ */
+export function clientContextField(timeZone, env = hostEnv()) {
+    const rawEmail = env[USER_EMAIL_ENV];
+    const userEmail = typeof rawEmail === 'string' ? rawEmail.trim() : '';
+    const tz = typeof timeZone === 'string' ? timeZone.trim() : '';
+    const ctx = {
+        ...(tz ? { timeZone: tz } : {}),
+        ...(userEmail ? { userEmail } : {}),
+    };
+    return Object.keys(ctx).length > 0 ? { clientContext: ctx } : {};
+}

package/dist/cloudConfigWireCaps.d.ts

@@ -0,0 +1,110 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/cloudConfigWireCaps.ts 搬入(依赖 mcpWireCaps/skillsWireCaps,同批)。
+ */
+/**
+ * src/sema/cloudConfigWireCaps.ts — PURE projections for the CLOUD CONFIG WIRE (P2): the registry's
+ * GET /api/v1/effective body → the same wire shapes the LOCAL loaders produce, so flipping the
+ * config-source switch swaps the SOURCE without changing a single downstream contract:
+ *
+ *   config.mcp.servers   → `McpServerSpec[]`   (== mcpWire loadMcpSpecs output → TaskRequest.mcpServers)
+ *   config.skills.skills → `SkillSpec[]`       (== skillsWire loadSkillSpecs output → TaskRequest.skills;
+ *                                               the v1 wire is a MANIFEST — content replaced by contentHash —
+ *                                               so the body is injected via `resolveBody(contentHash)`)
+ *   config.models        → config.d/models.json document (registry-core ModelsConfig IS the engine's
+ *                                               FileConfigStore models.json shape — verbatim passthrough,
+ *                                               written to a SHADOW config.d root, never the user's own)
+ *   rosters              → names only (v1 thinnest seam: display + reference; the /api/v1/effective wire
+ *                                               STRIPS rosters — registry-core resolve-roster `shipped()` —
+ *                                               so the IO half pulls the domain raw when it can)
+ *
+ * SECRET BOUNDARY: the registry NEVER ships secret values — mcp transports carry `envRefs`/`headerRefs`
+ * (target key → an ENV NAME) and models carry `apiKeyEnv`. The projection resolves env-NAME refs against the
+ * SHELL's env (the engine child inherits it), and reports the names that resolve to nothing so callers can warn.
+ *
+ * Split from cloudConfigWire.ts (the IO half: token/fetch/cache/shadow-write) so this file is esbuild-bundleable
+ * alone for the assertion suite — it imports only erased types + the sibling pure caps modules.
+ */
+import type { SkillSpec } from '@sema-agent/sdk';
+import type { McpServerSpec } from './mcpWireCaps.js';
+import type { EnvLike } from './hostEnv.js';
+/** The SDK wire shape TaskRequest.mcpServers carries (the SDK barrel doesn't re-export McpServerSpec by
+ *  name — derive it from TaskRequest so this stays the EXACT wire type, never a drifting copy). */
+export type { McpServerSpec };
+type Rec = Record<string, unknown>;
+/** Env lookup shape (process.env or a test fixture). */
+export type { EnvLike };
+export interface CloudMcpProjection {
+    specs: McpServerSpec[];
+    /** env NAMES referenced by envRefs/headerRefs that resolve to nothing in `env` (the ref is DROPPED —
+     *  fail-closed on the value, loud in the caller's warning line). */
+    missingEnv: string[];
+}
+/**
+ * Project the registry's mcp domain (`config.mcp.servers`, registry-core McpServerSpec — the CENTER shape
+ * with envRefs/headerRefs) → the SDK/core wire `McpServerSpec[]` (real env/header VALUES, resolved from the
+ * shell env). Disabled servers are skipped; unknown transport kinds are skipped (never mis-mapped); the
+ * result is capped at MCP_CAPS.items exactly like the local `.mcp.json` projection.
+ */
+export declare function cloudMcpToSpecs(servers: unknown, env: EnvLike): CloudMcpProjection;
+/**
+ * Project the /api/v1/effective skills MANIFEST (content replaced by `contentHash` — registry-core
+ * toSkillsManifest) → the capped wire `SkillSpec[]`. `resolveBody(contentHash)` supplies each body (the IO
+ * half caches bodies by hash; null ⇒ the skill is SKIPPED — a nameless/bodyless SkillSpec is a 400). Same
+ * caps + dedupe as the local projection (skillsWireCaps), so the wire is well-formed by construction.
+ */
+export declare function cloudSkillsToSpecs(manifestSkills: unknown, resolveBody: (contentHash: string) => string | null): SkillSpec[];
+/**
+ * The registry's models domain (registry-core ModelsConfig) IS the engine's `config.d/models.json` contract
+ * (the same zod schema parses both — engine CONFIG_PROVIDER=local FileConfigStore lane), so the projection is
+ * a VALIDATION-LITE PASSTHROUGH: keep exactly {models, roles, atModelAllowlist}, drop everything else, and
+ * return null when there is no well-formed models array (caller then writes an empty catalog — engine
+ * semantics: no enabled models ⇒ env-catalog fallback).
+ */
+export declare function cloudModelsToDoc(models: unknown): Rec | null;
+/** ENABLED model names in a models doc (banner/status display + "did the cloud catalog apply" checks). */
+export declare function cloudModelNames(doc: Rec | null): string[];
+/** `apiKeyEnv` NAMES referenced by enabled models that resolve to nothing in `env` — the engine child would
+ *  route those models with no key (a mid-session 401 the user can't diagnose); callers warn up front. */
+export declare function cloudModelMissingKeyEnv(doc: Rec | null, env: EnvLike): string[];
+export interface CloudSessionMirrorProjection {
+    engineUrl: string;
+    required: boolean;
+}
+export interface CloudExecutionProjection {
+    required: boolean;
+    allowedLanes: string[];
+    /** registry-core 0.10.1 `execution.sessionMirror`(附B 单C):org 默认会话镜像目标两层配置。
+     *  null = 未下发/形状不对(INERT — 缺省零行为差;misshapen 绝不猜出一个镜像目标)。 */
+    sessionMirror: CloudSessionMirrorProjection | null;
+}
+/** Project the registry's execution domain (registry-core 0.8 ExecutionPolicy — `{required, allowedLanes}`,
+ *  allowedLanes = OPEN string vocab, [580]④; 0.10.1 adds `sessionMirror{engineUrl, required}` — additive).
+ *  Defensive like every other projection: a missing/misshapen domain (an 0.7 registry) yields the schema
+ *  defaults `{required:false, allowedLanes:["host"], sessionMirror:null}` — never a throw, never an
+ *  accidental lock-ON, and never a guessed mirror target (engineUrl must be a non-empty string or the
+ *  whole sessionMirror is dropped: a mirror carries session content + a Bearer, we don't improvise one). */
+export declare function cloudExecutionToPolicy(execution: unknown): CloudExecutionProjection;
+/** Roster names from a rosters domain value ({rosters:[{name,…}]}). The /api/v1/effective wire strips
+ *  rosters (control-plane only), so the IO half feeds this from the raw scoped domain GET when readable. */
+export declare function cloudRosterNames(rostersValue: unknown): string[];
+export interface CloudProjection {
+    mcp: McpServerSpec[];
+    skills: SkillSpec[];
+    /** The shadow config.d/models.json document (null = registry shipped no well-formed models domain). */
+    modelsDoc: Rec | null;
+    modelNames: string[];
+    rosterNames: string[];
+    /** env NAMES referenced by the cloud config (mcp refs + model apiKeyEnv) missing from the shell env. */
+    missingEnv: string[];
+    scope: string;
+    /** Skills present in the manifest whose body could not be resolved (skipped on the wire). */
+    skillsMissingBody: string[];
+    /** S3 execution-lane policy ([580]① / registry-core 0.8). Consumed by the sandbox policy-lock seam;
+     *  ⚠️ client-enforced ADVISORY (P5=A) — the engine gate is service [580]. */
+    execution: CloudExecutionProjection;
+}
+/**
+ * Project one /api/v1/effective BODY (fresh or cached — the fallback path MUST produce the identical shape)
+ * into everything the shell consumes. Pure: bodies + env are injected.
+ */
+export declare function projectEffectiveBody(body: unknown, skillBodies: Record<string, string>, env: EnvLike, rostersValue?: unknown): CloudProjection;

package/dist/cloudConfigWireCaps.js

@@ -0,0 +1,228 @@
+import { MCP_CAPS } from './mcpWireCaps.js';
+import { SKILL_CAPS, toCappedSpec } from './skillsWireCaps.js';
+const asRec = (v) => (typeof v === 'object' && v !== null && !Array.isArray(v) ? v : undefined);
+const asArr = (v) => (Array.isArray(v) ? v : []);
+const asStr = (v) => (typeof v === 'string' && v.length > 0 ? v : undefined);
+/**
+ * Project the registry's mcp domain (`config.mcp.servers`, registry-core McpServerSpec — the CENTER shape
+ * with envRefs/headerRefs) → the SDK/core wire `McpServerSpec[]` (real env/header VALUES, resolved from the
+ * shell env). Disabled servers are skipped; unknown transport kinds are skipped (never mis-mapped); the
+ * result is capped at MCP_CAPS.items exactly like the local `.mcp.json` projection.
+ */
+export function cloudMcpToSpecs(servers, env) {
+    const specs = [];
+    const missingEnv = [];
+    for (const raw of asArr(servers)) {
+        if (specs.length >= MCP_CAPS.items)
+            break;
+        const s = asRec(raw);
+        if (!s || s.enabled === false)
+            continue;
+        const name = asStr(s.name);
+        const t = asRec(s.transport);
+        if (!name || !t)
+            continue;
+        let transport = null;
+        if (t.kind === 'stdio') {
+            const command = asStr(t.command);
+            if (!command)
+                continue;
+            // envRefs: target ENV key → ENV NAME holding the value (center never stores the secret). Resolve
+            // against the shell env — the engine child inherits it, so stdio spawn sees the same values.
+            const envOut = {};
+            for (const [target, ref] of Object.entries(asRec(t.envRefs) ?? {})) {
+                const refName = asStr(ref);
+                if (!refName)
+                    continue;
+                const v = env[refName];
+                if (v === undefined || v === '')
+                    missingEnv.push(refName);
+                else
+                    envOut[target] = v;
+            }
+            const args = asArr(t.args).filter((a) => typeof a === 'string');
+            transport = {
+                kind: 'stdio',
+                command,
+                ...(args.length > 0 ? { args } : {}),
+                ...(Object.keys(envOut).length > 0 ? { env: envOut } : {}),
+            };
+        }
+        else if (t.kind === 'http') {
+            const url = asStr(t.url);
+            if (!url)
+                continue;
+            const headers = {};
+            for (const [headerName, ref] of Object.entries(asRec(t.headerRefs) ?? {})) {
+                const refName = asStr(ref);
+                if (!refName)
+                    continue;
+                const v = env[refName];
+                if (v === undefined || v === '')
+                    missingEnv.push(refName);
+                else
+                    headers[headerName] = v;
+            }
+            const principalHeader = asStr(t.principalHeader);
+            transport = {
+                kind: 'http',
+                url,
+                ...(Object.keys(headers).length > 0 ? { headers } : {}),
+                ...(principalHeader ? { principalHeader } : {}),
+            };
+        }
+        else {
+            continue; // unknown transport kind — skip, never mis-map (same posture as the local sse/ws skip)
+        }
+        const allowTools = asArr(s.allowTools).filter((a) => typeof a === 'string');
+        specs.push({
+            name,
+            transport,
+            ...(allowTools.length > 0 ? { allowTools } : {}),
+            ...(s.elicitation === true ? { elicitation: true } : {}),
+        });
+    }
+    return { specs, missingEnv: [...new Set(missingEnv)] };
+}
+// ── skills: config.skills.skills (MANIFEST) + bodies → SkillSpec[] ───────────────────────────────────────
+/**
+ * Project the /api/v1/effective skills MANIFEST (content replaced by `contentHash` — registry-core
+ * toSkillsManifest) → the capped wire `SkillSpec[]`. `resolveBody(contentHash)` supplies each body (the IO
+ * half caches bodies by hash; null ⇒ the skill is SKIPPED — a nameless/bodyless SkillSpec is a 400). Same
+ * caps + dedupe as the local projection (skillsWireCaps), so the wire is well-formed by construction.
+ */
+export function cloudSkillsToSpecs(manifestSkills, resolveBody) {
+    const specs = [];
+    const seen = new Set();
+    for (const raw of asArr(manifestSkills)) {
+        if (specs.length >= SKILL_CAPS.items)
+            break;
+        const s = asRec(raw);
+        if (!s || s.enabled === false)
+            continue;
+        const name = asStr(s.name);
+        const hash = asStr(s.contentHash);
+        if (!name || !hash)
+            continue;
+        const body = resolveBody(hash);
+        if (!body)
+            continue;
+        const spec = toCappedSpec(name, asStr(s.description) ?? '', '', body);
+        if (!spec || seen.has(spec.name))
+            continue;
+        seen.add(spec.name);
+        specs.push(spec);
+    }
+    return specs;
+}
+// ── models: config.models → shadow config.d/models.json document ─────────────────────────────────────────
+/**
+ * The registry's models domain (registry-core ModelsConfig) IS the engine's `config.d/models.json` contract
+ * (the same zod schema parses both — engine CONFIG_PROVIDER=local FileConfigStore lane), so the projection is
+ * a VALIDATION-LITE PASSTHROUGH: keep exactly {models, roles, atModelAllowlist}, drop everything else, and
+ * return null when there is no well-formed models array (caller then writes an empty catalog — engine
+ * semantics: no enabled models ⇒ env-catalog fallback).
+ */
+export function cloudModelsToDoc(models) {
+    const m = asRec(models);
+    if (!m || !Array.isArray(m.models))
+        return null;
+    const entries = m.models.filter((e) => {
+        const r = asRec(e);
+        return !!r && !!asStr(r.name) && !!asStr(r.id);
+    });
+    return {
+        models: entries,
+        ...(asRec(m.roles) ? { roles: m.roles } : {}),
+        ...(Array.isArray(m.atModelAllowlist) ? { atModelAllowlist: m.atModelAllowlist } : {}),
+    };
+}
+/** ENABLED model names in a models doc (banner/status display + "did the cloud catalog apply" checks). */
+export function cloudModelNames(doc) {
+    if (!doc)
+        return [];
+    return asArr(doc.models)
+        .map((e) => {
+        const r = asRec(e);
+        return r && r.enabled !== false ? asStr(r.name) : undefined;
+    })
+        .filter((n) => !!n);
+}
+/** `apiKeyEnv` NAMES referenced by enabled models that resolve to nothing in `env` — the engine child would
+ *  route those models with no key (a mid-session 401 the user can't diagnose); callers warn up front. */
+export function cloudModelMissingKeyEnv(doc, env) {
+    if (!doc)
+        return [];
+    const out = new Set();
+    for (const e of asArr(doc.models)) {
+        const r = asRec(e);
+        if (!r || r.enabled === false)
+            continue;
+        const ref = asStr(r.apiKeyEnv);
+        if (ref && (env[ref] === undefined || env[ref] === ''))
+            out.add(ref);
+    }
+    return [...out];
+}
+/** Project the registry's execution domain (registry-core 0.8 ExecutionPolicy — `{required, allowedLanes}`,
+ *  allowedLanes = OPEN string vocab, [580]④; 0.10.1 adds `sessionMirror{engineUrl, required}` — additive).
+ *  Defensive like every other projection: a missing/misshapen domain (an 0.7 registry) yields the schema
+ *  defaults `{required:false, allowedLanes:["host"], sessionMirror:null}` — never a throw, never an
+ *  accidental lock-ON, and never a guessed mirror target (engineUrl must be a non-empty string or the
+ *  whole sessionMirror is dropped: a mirror carries session content + a Bearer, we don't improvise one). */
+export function cloudExecutionToPolicy(execution) {
+    const e = asRec(execution);
+    const lanes = asArr(e?.allowedLanes).filter((l) => typeof l === 'string' && l.length > 0);
+    const m = asRec(e?.sessionMirror);
+    const mirrorUrl = asStr(m?.engineUrl);
+    return {
+        required: e?.required === true,
+        allowedLanes: lanes.length > 0 ? lanes : ['host'],
+        // trailing-slash normalization matches engineTarget.normalizeEngineUrl (origin/no-op comparisons downstream)
+        sessionMirror: mirrorUrl ? { engineUrl: mirrorUrl.replace(/\/+$/, ''), required: m?.required === true } : null,
+    };
+}
+// ── rosters: v1 thinnest seam (names for display / model-order reference) ────────────────────────────────
+/** Roster names from a rosters domain value ({rosters:[{name,…}]}). The /api/v1/effective wire strips
+ *  rosters (control-plane only), so the IO half feeds this from the raw scoped domain GET when readable. */
+export function cloudRosterNames(rostersValue) {
+    const r = asRec(rostersValue);
+    return asArr(r?.rosters)
+        .map((e) => asStr(asRec(e)?.name))
+        .filter((n) => !!n);
+}
+/**
+ * Project one /api/v1/effective BODY (fresh or cached — the fallback path MUST produce the identical shape)
+ * into everything the shell consumes. Pure: bodies + env are injected.
+ */
+export function projectEffectiveBody(body, skillBodies, env, rostersValue) {
+    const b = asRec(body) ?? {};
+    const config = asRec(b.config) ?? {};
+    const mcpDomain = asRec(config.mcp);
+    const skillsDomain = asRec(config.skills);
+    const { specs: mcp, missingEnv: mcpMissing } = cloudMcpToSpecs(mcpDomain?.servers, env);
+    const manifest = asArr(skillsDomain?.skills);
+    const skills = cloudSkillsToSpecs(manifest, (hash) => skillBodies[hash] ?? null);
+    const skillsMissingBody = manifest
+        .map((raw) => {
+        const s = asRec(raw);
+        if (!s || s.enabled === false)
+            return undefined;
+        const name = asStr(s.name);
+        const hash = asStr(s.contentHash);
+        return name && hash && skillBodies[hash] === undefined ? name : undefined;
+    })
+        .filter((n) => !!n);
+    const modelsDoc = cloudModelsToDoc(config.models);
+    return {
+        mcp,
+        skills,
+        modelsDoc,
+        modelNames: cloudModelNames(modelsDoc),
+        rosterNames: cloudRosterNames(rostersValue),
+        missingEnv: [...new Set([...mcpMissing, ...cloudModelMissingKeyEnv(modelsDoc, env)])],
+        scope: asStr(b.scope) ?? 'global',
+        skillsMissingBody,
+        execution: cloudExecutionToPolicy(config.execution),
+    };
+}