@mininglamp-oss/octo-runtime-client 0.0.0-stage → 1.1.11

package/dist/startup-diagnostics.js

@@ -0,0 +1,371 @@
+import { STARTUP_CATALOG } from "./startup-catalog.js";
+export { STARTUP_CATALOG } from "./startup-catalog.js";
+/** CLI 继续提供 #306 的 startup 字段；恢复建议始终来自同一 catalog。 */
+export function startupPathDiagnostic(diagnostic) {
+    if (!/^(HOME_|IPC_ENDPOINT_)/.test(diagnostic.rootCode))
+        return undefined;
+    const { path, resource, operation, systemCode, endpoint, measured, limit, unit } = diagnostic.context;
+    return {
+        domain: "startup",
+        code: diagnostic.rootCode,
+        resource: resource ?? "home",
+        operation: operation ?? "validate-input",
+        action: diagnostic.actions.join(" "),
+        ...(path !== undefined ? { path } : {}),
+        ...(systemCode !== undefined ? { systemCode } : {}),
+        ...(endpoint !== undefined ? { endpoint } : {}),
+        ...(measured !== undefined ? { measured } : {}),
+        ...(limit !== undefined ? { limit } : {}),
+        ...(unit !== undefined ? { unit } : {})
+    };
+}
+/** 保持原类型/message/code/cause，仅在可扩展错误上增加安全诊断；冻结错误可由调用边界直接投影。 */
+export function withStartupContext(error, location, classification) {
+    try {
+        if (error instanceof Error && Object.isExtensible(error) && !Object.hasOwn(error, "diagnostic"))
+            Object.defineProperty(error, "diagnostic", {
+                value: describeStartupError(classification ? { code: classification, cause: error } : error, location)
+            });
+    }
+    catch {
+        // 不可信代理/不可写对象不能让诊断遮盖原错误。
+    }
+    return error;
+}
+const phases = new Set([
+    "created",
+    "initializing",
+    "ready",
+    "closing",
+    "closed",
+    "failed"
+]);
+const wrappers = new Set([
+    "SERVICE_INITIALIZATION_FAILED",
+    "KERNEL_START_CLEANUP_INCOMPLETE",
+    "COMMAND_FAILED"
+]);
+const object = (value) => value !== null && (typeof value === "object" || typeof value === "function") ? value : undefined;
+// 不执行 getter/toJSON；代理或损坏对象按未知处理，错误投影本身不能覆盖启动失败。
+function own(value, key) {
+    try {
+        return object(value) ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function arrayItems(value, maximum) {
+    try {
+        if (!Array.isArray(value))
+            return undefined;
+        const length = own(value, "length");
+        if (typeof length !== "number" || !Number.isSafeInteger(length) || length < 0)
+            return undefined;
+        return Array.from({ length: Math.min(length, maximum) }, (_, index) => own(value, String(index)));
+    }
+    catch {
+        return undefined;
+    }
+}
+const codeOf = (value) => typeof value === "string" && /^[A-Z][A-Z0-9_]{1,100}$/.test(value) ? value : undefined;
+const errorCode = (value) => codeOf(own(value, "code")) ?? codeOf(own(value, "message"));
+/** 文本与 JSON 同用确定性规范化：去控制字符，去 URL 认证/query/hash 和显式敏感赋值。 */
+export function safeStartupValue(value, maximum = 32768) {
+    const truncated = value.length > maximum;
+    return (value
+        .slice(0, maximum)
+        .replace(/[\p{Cc}\p{Cf}]/gu, " ")
+        // 完整标量交给 URL parser，不能在 userinfo 的空格/引号处切开并泄漏后缀。
+        // 截断过的 URL 不再猜 authority；内联模块载荷整体隐藏。前缀锚点限制回溯。
+        .replace(/(^|[^a-z0-9+.-])((?:data:|[a-z][a-z0-9+.-]*:\/\/)[\s\S]*)/gi, (match, prefix) => {
+        const selected = match.slice(prefix.length);
+        if (/^data:/i.test(selected))
+            return prefix + "[redacted-inline-module]";
+        if (truncated ||
+            /[\s"<>]/u.test(selected) ||
+            selected.indexOf("://", selected.indexOf("://") + 3) !== -1)
+            return prefix + "[redacted-url]";
+        try {
+            const url = new URL(selected);
+            url.username = "";
+            url.password = "";
+            url.search = "";
+            url.hash = "";
+            return prefix + url.toString();
+        }
+        catch {
+            return prefix + "[redacted-url]";
+        }
+    })
+        .replace(/\bBearer\s+[^\s,;]+/gi, "Bearer [redacted]")
+        .replace(/\b(?:sk-|bf_)[A-Za-z0-9_-]{8,}/g, "[redacted]")
+        .replace(
+    // 资源标量没有可靠的凭据结束语法，带引号或含标点的值也保守隐藏余段。
+    /\b(?:token|secret|password|authorization|api[_-]?key)\s*[:=][\s\S]*/gi, "[redacted]"));
+}
+function safeContext(value) {
+    const result = {};
+    for (const key of [
+        "path",
+        "resource",
+        "operation",
+        "configKey",
+        "endpoint",
+        "executable",
+        "module",
+        "systemCode"
+    ]) {
+        const field = own(value, key);
+        if (typeof field === "string")
+            result[key] = safeStartupValue(field, ["path", "endpoint", "executable", "module"].includes(key) ? 32768 : 256);
+    }
+    for (const key of ["measured", "limit"]) {
+        const field = own(value, key);
+        if (typeof field === "number" && Number.isSafeInteger(field) && field >= 0)
+            result[key] = field;
+    }
+    const unit = own(value, "unit");
+    if (unit === "utf8-bytes" || unit === "utf16-units")
+        result.unit = unit;
+    return result;
+}
+function safeCleanup(value) {
+    const complete = own(value, "complete"), errors = arrayItems(own(value, "errors"), 32), pending = arrayItems(own(value, "pendingResources"), 32);
+    if (typeof complete !== "boolean" || !errors || !pending)
+        return undefined;
+    return {
+        complete,
+        errors: errors.map((item) => ({
+            resource: safeStartupValue(typeof own(item, "resource") === "string" ? own(item, "resource") : "unknown", 256),
+            code: codeOf(own(item, "code")) ?? "STARTUP_UNKNOWN"
+        })),
+        pendingResources: pending.map((item) => typeof item === "string" ? safeStartupValue(item, 256) : "unknown")
+    };
+}
+function safeCause(value) {
+    const component = own(value, "component"), phase = own(value, "phase");
+    const cleanup = safeCleanup(own(value, "cleanup"));
+    return {
+        code: codeOf(own(value, "code")) ?? "STARTUP_UNKNOWN",
+        context: safeContext(own(value, "context")),
+        ...(typeof component === "string" ? { component: safeStartupValue(component, 128) } : {}),
+        ...(typeof phase === "string" && phases.has(phase)
+            ? { phase: phase }
+            : {}),
+        ...(cleanup ? { cleanup } : {})
+    };
+}
+/**
+ * 在失败调用边界投影启动事实；不依赖 IPC/Run，不改变原错误、退出码或清理行为。
+ * cause/aggregate 按主失败优先有界遍历（16 节点/6 层）；循环和原始异常正文均不输出。
+ */
+export function describeStartupError(error, location = { component: "host", phase: "created" }) {
+    const existing = restoreStartupDiagnostic(own(error, "diagnostic"));
+    if (existing)
+        return existing;
+    const seen = new Set();
+    const causes = [];
+    let truncated = false;
+    let cleanup;
+    let visited = 0;
+    const visit = (value, depth, inherited = {}) => {
+        if (depth > 6 || visited >= 16) {
+            truncated = true;
+            return undefined;
+        }
+        const reference = object(value);
+        if (!reference)
+            return undefined;
+        if (seen.has(reference)) {
+            truncated = true;
+            return undefined;
+        }
+        seen.add(reference);
+        visited++;
+        const diagnostic = own(value, "diagnostic");
+        const embedded = own(diagnostic, "domain") === "startup" ? diagnostic : undefined;
+        const nodeCleanup = safeCleanup(own(value, "cleanup")) ?? safeCleanup(own(embedded, "cleanup"));
+        cleanup ??= nodeCleanup;
+        const code = errorCode(value) ?? codeOf(own(embedded, "code"));
+        const context = {
+            ...inherited,
+            ...safeContext(own(value, "startupContext")),
+            ...safeContext(embedded),
+            ...safeContext(own(embedded, "context"))
+        };
+        // Node 系统错误字段是实际 IO 事实；spawn 的 path 是可执行文件，不能误建议 mkdir。
+        const syscall = own(value, "syscall"), path = own(value, "path"), address = own(value, "address");
+        if (typeof syscall === "string")
+            context.operation ??= safeStartupValue(syscall, 256);
+        if (typeof path === "string") {
+            if (typeof syscall === "string" && syscall.startsWith("spawn")) {
+                context.executable ??= safeStartupValue(path);
+                context.resource ??= "executable";
+            }
+            else
+                context.path ??= safeStartupValue(path);
+        }
+        if (typeof address === "string")
+            context.endpoint ??= safeStartupValue(address);
+        if (code && /^(E[A-Z0-9]+|UV_[A-Z0-9_]+)$/.test(code))
+            context.systemCode ??= code;
+        const current = code
+            ? safeCause({
+                code,
+                context,
+                component: own(embedded, "component"),
+                phase: own(embedded, "phase"),
+                cleanup: nodeCleanup
+            })
+            : undefined;
+        if (current)
+            causes.push(current);
+        let child;
+        const rawErrors = own(value, "errors");
+        const errors = arrayItems(rawErrors, 16);
+        if (errors) {
+            for (let i = 0; i < errors.length; i++) {
+                const found = visit(errors[i], depth + 1, context);
+                if (i === 0)
+                    child = found ?? { code: "STARTUP_UNKNOWN", context };
+            }
+            // 所有分支都必须遍历以保留清理失败；不能被 ??= 短路。
+            if (Number(own(rawErrors, "length")) > 16)
+                truncated = true;
+        }
+        const cause = own(value, "cause");
+        const nested = cause === undefined ? undefined : visit(cause, depth + 1, context);
+        const savedRoot = codeOf(own(embedded, "rootCode"));
+        // 后台回读只有白名单诊断而没有原始 cause；保留已确认根因及清理事实，不反序列化异常。
+        if (!errors && cause === undefined && savedRoot) {
+            const savedCauses = arrayItems(own(embedded, "causes"), 15);
+            if (savedCauses) {
+                for (const item of savedCauses) {
+                    visit({
+                        code: codeOf(own(item, "code")),
+                        startupContext: safeContext(own(item, "context")),
+                        cleanup: safeCleanup(own(item, "cleanup")),
+                        diagnostic: {
+                            domain: "startup",
+                            component: own(item, "component"),
+                            phase: own(item, "phase")
+                        }
+                    }, depth + 1);
+                }
+            }
+            return { code: savedRoot, context };
+        }
+        const primary = child ?? nested;
+        // Home/端点所有者已验证的资源分类比系统 errno 更精确；errno 仍保留在 context/causes。
+        // 初始化/加载包装不能采用此规则，否则会再次遮盖真正根因。
+        if (current &&
+            STARTUP_CATALOG[current.code] &&
+            /^(HOME_|IPC_ENDPOINT_|ENDPOINT_|ORPHAN_)/.test(current.code))
+            return { code: current.code, context: { ...context, ...primary?.context } };
+        return primary ?? (current && !wrappers.has(current.code) ? current : undefined);
+    };
+    const root = visit(error, 0);
+    const embedded = own(error, "diagnostic");
+    const component = typeof own(embedded, "component") === "string"
+        ? own(embedded, "component")
+        : location.component;
+    const phase = own(embedded, "phase");
+    const context = {
+        ...safeContext(location.context),
+        ...safeContext(own(embedded, "context")),
+        ...(root?.context ?? {})
+    };
+    const code = errorCode(error) ?? codeOf(own(embedded, "code")) ?? "STARTUP_UNKNOWN";
+    const rootCode = root?.code ?? (wrappers.has(code) ? "STARTUP_UNKNOWN" : code);
+    return buildDiagnostic({
+        code,
+        rootCode,
+        component: safeStartupValue(component, 128),
+        phase: typeof phase === "string" && phases.has(phase)
+            ? phase
+            : location.phase,
+        context,
+        causes,
+        ...(cleanup ? { cleanup } : {}),
+        truncated
+    });
+}
+function buildDiagnostic(facts) {
+    const { rootCode } = facts;
+    const catalog = STARTUP_CATALOG[rootCode] ?? STARTUP_CATALOG.STARTUP_UNKNOWN;
+    const context = safeContext({
+        ...(catalog.configKey ? { configKey: catalog.configKey } : {}),
+        ...facts.context
+    });
+    const details = Object.entries(context)
+        .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+        .join(", ");
+    let action = catalog.action;
+    if (rootCode === "ENOENT" && context.executable)
+        action = `Check that executable ${JSON.stringify(context.executable)} is installed and the host's selected working directory exists. Correct the executable or working directory configuration, then retry. Creating a directory does not provide an executable.`;
+    else if (rootCode === "ENOENT" && context.resource === "directory")
+        action = `Correct the configured directory ${JSON.stringify(context.path ?? "unknown")}, or create it if this is the intended location, then retry.`;
+    else if (["HOME_NOT_FOUND", "HOME_NOT_DIRECTORY"].includes(rootCode) &&
+        context.resource &&
+        context.resource !== "home" &&
+        context.resource !== "home-probe")
+        action = `Inspect the reported ${JSON.stringify(context.resource)} path and its parent directory. Correct the host's resource selection or prepare its required parent directory, then retry. Do not create a replacement Runtime Home or delete an unrelated resource.`;
+    if (context.configKey)
+        action += ` Check configuration key ${JSON.stringify(context.configKey)}.`;
+    return {
+        ...facts,
+        domain: "startup",
+        context,
+        summary: catalog.summary,
+        explanation: `${catalog.summary}${details ? ` Observed: ${details}.` : " No further safe resource facts were recorded."}`,
+        actions: [action],
+        retryable: catalog.retryable,
+        userActionRequired: !catalog.retryable
+    };
+}
+/** 可读投影只消费已净化的共享结构；SDK 可直接按 rootCode/context 分支。 */
+export function formatStartupDiagnostic(diagnostic) {
+    const nested = diagnostic.causes
+        .filter((cause) => cause.cleanup && !cause.cleanup.complete)
+        .map((cause) => `\nCause cleanup [${cause.code}]${cause.component ? ` (${cause.component})` : ""}: incomplete; pending: ${cause.cleanup?.pendingResources.join(", ") || "none"}`)
+        .join("");
+    return `[${diagnostic.code}] ${diagnostic.explanation}\nComponent: ${diagnostic.component}; phase: ${diagnostic.phase}; root: ${diagnostic.rootCode}\n${diagnostic.actions.map((action) => `Action: ${action}`).join("\n")}${diagnostic.cleanup ? `\nCleanup: ${diagnostic.cleanup.complete ? "complete" : "incomplete"}; pending: ${diagnostic.cleanup.pendingResources.join(", ") || "none"}` : ""}${nested}${diagnostic.truncated ? "\nDetails: additional causes were omitted by diagnostic limits." : ""}`;
+}
+/** 持久化/JSON 是不可信边界：仅重建码、位置、资源和清理，文案始终重新来自当前 catalog。 */
+export function restoreStartupDiagnostic(value) {
+    const code = codeOf(own(value, "code")), rootCode = codeOf(own(value, "rootCode"));
+    const component = own(value, "component"), phase = own(value, "phase"), causes = arrayItems(own(value, "causes"), 16);
+    if (own(value, "domain") !== "startup" ||
+        !code ||
+        !rootCode ||
+        typeof component !== "string" ||
+        typeof phase !== "string" ||
+        !phases.has(phase) ||
+        !causes)
+        return undefined;
+    const context = safeContext(own(value, "context"));
+    const cleanup = safeCleanup(own(value, "cleanup"));
+    return buildDiagnostic({
+        code,
+        rootCode,
+        component: safeStartupValue(component, 128),
+        phase: phase,
+        context,
+        causes: causes.map(safeCause),
+        ...(cleanup ? { cleanup } : {}),
+        truncated: own(value, "truncated") === true || Number(own(own(value, "causes"), "length")) > 16
+    });
+}
+/** 仅供启动边界补充已确认的位置事实；cause 保留给本地深度排障，公开输出用 diagnostic。 */
+export class StartupError extends Error {
+    code;
+    diagnostic;
+    constructor(code, location, cause) {
+        super(code, { cause });
+        this.name = "StartupError";
+        this.code = code;
+        Object.defineProperty(this, "startupContext", { value: location.context });
+        this.diagnostic = describeStartupError(this, location);
+    }
+}

package/dist/submission-error.d.ts

@@ -0,0 +1,10 @@
+import { KernelError } from "./types.js";
+/** 包内接纳检查专用；当前 client 在请求写出前拒绝时创建证据。 */
+export declare function admissionClosedError(): KernelError;
+/** 仅实际 invoke RPC 的拒绝响应、且实例和专用证据均匹配，才标记未进入执行源。 */
+export declare function markSubmissionRejected(error: unknown, instance: string): void;
+/**
+ * 判断本模块验证的未执行拒绝；包装、序列化及同名错误均返回 false。
+ * 只证明本次未进入执行源，不证明此前业务尝试没有执行，也不授权自动重放。
+ */
+export declare function isInvocationNotSubmitted(error: unknown): boolean;

package/dist/submission-error.js

@@ -0,0 +1,23 @@
+import { KernelError } from "./types.js";
+const notSubmitted = new WeakSet();
+/** 包内接纳检查专用；当前 client 在请求写出前拒绝时创建证据。 */
+export function admissionClosedError() {
+    const error = new KernelError("CLIENT_INVOCATION_ADMISSION_CLOSED");
+    notSubmitted.add(error);
+    return error;
+}
+/** 仅实际 invoke RPC 的拒绝响应、且实例和专用证据均匹配，才标记未进入执行源。 */
+export function markSubmissionRejected(error, instance) {
+    if (error instanceof KernelError &&
+        ["KERNEL_UNAVAILABLE", "WORKER_RESTART_EXHAUSTED"].includes(error.code) &&
+        error.data?.invocation_not_submitted === true &&
+        error.data.kernel_instance_id === instance)
+        notSubmitted.add(error);
+}
+/**
+ * 判断本模块验证的未执行拒绝；包装、序列化及同名错误均返回 false。
+ * 只证明本次未进入执行源，不证明此前业务尝试没有执行，也不授权自动重放。
+ */
+export function isInvocationNotSubmitted(error) {
+    return error instanceof KernelError && notSubmitted.has(error);
+}

package/dist/types.d.ts

@@ -0,0 +1,72 @@
+import type { KernelLookupKey, KernelRunRef, KernelRunSnapshot, KernelStatus, InvokeInput, InvokeEnvironment, InputInvoke, HostFrame, InteractionResponse, NativeInteractionResponse } from "@mininglamp-oss/octo-runtime-protocol";
+import type { HostedAdapterMetadata } from "@mininglamp-oss/octo-runtime-protocol";
+export type LookupKey = KernelLookupKey;
+export type RunRef = KernelRunRef;
+export type RunSnapshot = KernelRunSnapshot;
+export type { KernelStatus };
+export interface KernelInvocationRecord {
+    readonly key: LookupKey;
+    readonly ref?: RunRef;
+    readonly phase: "admitting" | "accepted" | "acceptance_unknown" | "unobserved";
+    readonly cancellation: "none" | "requested" | "acknowledged" | "unknown";
+    readonly lastSeq: number;
+    readonly observationError?: string;
+}
+/** 只确认本 client 登记的执行是否排空；不代表卡片投递或业务 dispose 已完成。 */
+export interface KernelInvocationDrainResult {
+    readonly complete: boolean;
+    readonly unresolved: readonly KernelInvocationRecord[];
+}
+export interface KernelInvocationLifecycle {
+    /** 身份与观察状态的副本，不缓存消息正文；结果未知的执行仍保留在列表中。 */
+    snapshot(): readonly KernelInvocationRecord[];
+    /** 同步关闭 invoke 接纳；已有执行仍可取消、查询和消费尾流。 */
+    stopAdmission(): void;
+    /** 共享 Date.now() 毫秒绝对期限；首次调用确定预算，后续调用复用同一排空结果。 */
+    drain(options: {
+        deadline: number;
+        reason: string;
+    }): Promise<KernelInvocationDrainResult>;
+}
+/**
+ * 附着到独立 Kernel 的客户端，不拥有 Kernel 进程。
+ * 常规接入使用 invoke；owner 退出时先 stopAdmission，再并行 drain 与业务收尾，最后 close。
+ * submit/subscribe 是低层入口，调用方自行保存 RunRef、管理取消与尾流，不自动登记为 invoke。
+ */
+export interface KernelClient {
+    readonly topology: "kernel-ipc";
+    readonly ownership: "attached";
+    /** 开始消费才提交；signal 请求取消但保留尾流，提前结束迭代则仅停止观察。 */
+    readonly invoke: InputInvoke;
+    readonly invocations: KernelInvocationLifecycle;
+    /** 仅操作当前 client 的 invoke 登记；accepted 是取消受理，不是终态或清理完成。 */
+    cancelInvocation(invocationId: string, reason?: string): Promise<{
+        accepted: boolean;
+    }>;
+    respondInteraction(invocationId: string, response: InteractionResponse): Promise<void>;
+    respondNativeInteraction(invocationId: string, response: NativeInteractionResponse): Promise<void>;
+    status(): Promise<KernelStatus>;
+    list(): Promise<HostedAdapterMetadata[]>;
+    /** 接纳后由 Kernel 持续驱动执行；ACK 丢失只查原身份，不重复执行。 */
+    submit(input: InvokeInput, environment?: InvokeEnvironment): Promise<{
+        ref: RunRef;
+    }>;
+    /** 按完整 LookupKey 查询原执行；指定 expectedInstance 可拒绝服务重启后的同名身份。 */
+    get(key: LookupKey, expectedInstance?: string): Promise<RunSnapshot>;
+    /** 从 afterSeq 之后观察同一执行；signal 只关闭订阅，游标过期/身份变化须交给调用方处理。 */
+    subscribe(ref: RunRef, afterSeq?: number, signal?: AbortSignal): AsyncGenerator<HostFrame>;
+    /** 显式控制原 RunRef；ACK 丢失报结果未知，不能自动重试可能已受理的控制动作。 */
+    cancel(ref: RunRef, reason?: string): Promise<{
+        accepted: boolean;
+    }>;
+    /** 交互响应必须匹配原引用和协议模式，过期/未知的响应不能改投其他 Run。 */
+    respond(ref: RunRef, response: InteractionResponse): Promise<void>;
+    respondNative(ref: RunRef, response: NativeInteractionResponse): Promise<void>;
+    /** 释放本 client 的连接和控制请求，不取消已接纳 Run，也不关闭共享 Kernel。 */
+    close(): void;
+}
+export declare class KernelError extends Error {
+    readonly code: string;
+    readonly data?: Record<string, unknown> | undefined;
+    constructor(code: string, data?: Record<string, unknown> | undefined);
+}

package/dist/types.js

@@ -0,0 +1,10 @@
+export class KernelError extends Error {
+    code;
+    data;
+    constructor(code, data) {
+        super(code);
+        this.code = code;
+        this.data = data;
+        this.name = "KernelError";
+    }
+}

package/node_modules/@mininglamp-oss/octo-runtime-protocol/dist/actmode.d.ts

@@ -0,0 +1,4 @@
+import type { ContextEnvelope, ExecutionEvidence } from "./generated/protocol-types.js";
+/** 只读取本轮已解析的显式意图；不补默认、不读取历史会话。 */
+export declare function contextActmode(context: ContextEnvelope): "default" | "plan" | undefined;
+export declare function assertExecutionEvidence(value: unknown): asserts value is ExecutionEvidence;

package/node_modules/@mininglamp-oss/octo-runtime-protocol/dist/actmode.js

@@ -0,0 +1,36 @@
+/** 只读取本轮已解析的显式意图；不补默认、不读取历史会话。 */
+export function contextActmode(context) {
+    const item = context.items.find((item) => item.namespace === "octo.execution" && item.name === "actmode");
+    if (!item)
+        return undefined;
+    if (item.payload.mode !== "default" && item.payload.mode !== "plan")
+        throw new TypeError("CONTEXT_SCHEMA_INVALID");
+    return item.payload.mode;
+}
+export function assertExecutionEvidence(value) {
+    if (!record(value) ||
+        Object.keys(value).some((key) => key !== "actmode") ||
+        !record(value.actmode))
+        throw new TypeError("EXECUTION_EVIDENCE_INVALID");
+    const mode = value.actmode;
+    if (Object.keys(mode).some((key) => !["requested", "effective", "status", "nativeMode", "reason"].includes(key)) ||
+        (mode.requested !== "default" && mode.requested !== "plan") ||
+        !["default", "plan", null].includes(mode.effective) ||
+        (mode.status !== "applied" && mode.status !== "fallback" && mode.status !== "unknown") ||
+        (mode.nativeMode !== undefined && (typeof mode.nativeMode !== "string" || !mode.nativeMode)) ||
+        (mode.reason !== undefined &&
+            mode.reason !== "provider_unsupported" &&
+            mode.reason !== "adapter_unmapped" &&
+            mode.reason !== "provider_unconfirmed") ||
+        (mode.status === "applied" &&
+            (mode.effective !== mode.requested || mode.reason !== undefined)) ||
+        (mode.status === "fallback" &&
+            (mode.effective !== "default" ||
+                (mode.reason !== "provider_unsupported" && mode.reason !== "adapter_unmapped"))) ||
+        (mode.status === "unknown" &&
+            (mode.effective !== null || mode.reason !== "provider_unconfirmed")))
+        throw new TypeError("EXECUTION_EVIDENCE_INVALID");
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/node_modules/@mininglamp-oss/octo-runtime-protocol/dist/adapter-metadata.d.ts

@@ -0,0 +1,7 @@
+import type { AdapterProtocolSupport } from "./run-protocol.js";
+import type { HostedAdapterMetadataWire } from "./generated/protocol-types.js";
+/** 宿主注册及执行时使用的完整元数据；编写时的可选默认值须由 Adapter 工厂先补齐。 */
+export type HostedAdapterMetadata = Pick<HostedAdapterMetadataWire, "workspace" | "type" | "agentSources" | "processModel" | "transport" | "providerVersion" | "providerPath" | "available" | "unavailableReason"> & {
+    /** wire 可省略的编写输入不能放宽 Core 注册合同。 */
+    protocolSupport: AdapterProtocolSupport;
+};

package/node_modules/@mininglamp-oss/octo-runtime-protocol/dist/adapter-metadata.js

@@ -0,0 +1 @@
+export {};

package/node_modules/@mininglamp-oss/octo-runtime-protocol/dist/browser.d.ts

@@ -0,0 +1,7 @@
+export type * from "./generated/protocol-types.js";
+export * from "./questions.js";
+export * from "./context.js";
+export * from "./model-context.js";
+export * from "./execution-plan.js";
+export * from "./context-configuration.js";
+export * from "./context-catalog.js";

package/node_modules/@mininglamp-oss/octo-runtime-protocol/dist/browser.js

@@ -0,0 +1,6 @@
+export * from "./questions.js";
+export * from "./context.js";
+export * from "./model-context.js";
+export * from "./execution-plan.js";
+export * from "./context-configuration.js";
+export * from "./context-catalog.js";

package/node_modules/@mininglamp-oss/octo-runtime-protocol/dist/context-catalog.d.ts

@@ -0,0 +1,11 @@
+export interface ContextTypeDefinition {
+    readonly namespace: string;
+    readonly name: string;
+    readonly schemaRef: string;
+    readonly persistent: boolean;
+    readonly trustedOnly: boolean;
+}
+/** Built-in schema and execution-configuration classification; no processing stages. */
+export declare const CONTEXT_TYPE_CATALOG: readonly ContextTypeDefinition[];
+export declare function contextTypeDefinition(namespace: string, name: string): ContextTypeDefinition;
+export declare function findContextTypeDefinition(namespace: string, name: string): ContextTypeDefinition | undefined;

package/node_modules/@mininglamp-oss/octo-runtime-protocol/dist/context-catalog.js

@@ -0,0 +1,33 @@
+function entry(namespace, name, schema, persistent, trustedOnly = false) {
+    return Object.freeze({
+        namespace,
+        name,
+        schemaRef: `#/definitions/${schema}`,
+        persistent,
+        trustedOnly
+    });
+}
+/** Built-in schema and execution-configuration classification; no processing stages. */
+export const CONTEXT_TYPE_CATALOG = Object.freeze([
+    entry("octo.execution", "adapter", "ContextAdapterPayload", true),
+    entry("octo.execution", "model", "ContextModelPayload", true),
+    entry("octo.execution", "actmode", "ContextActmodePayload", true),
+    entry("octo.execution", "workspace", "ContextWorkspacePayload", true),
+    entry("octo.execution", "envs", "ContextEnvsPayload", true),
+    entry("octo.execution", "mcp", "ContextMcpPayload", true),
+    entry("octo.execution", "limits", "ContextLimitsPayload", true),
+    entry("octo.runtime", "selection", "ContextRuntimeSelectionPayload", true),
+    entry("octo.security", "approval_policy", "ContextApprovalPolicyPayload", true),
+    entry("octo.content", "inline", "ContextInlinePayload", false),
+    entry("octo.content", "references", "ContextReferencesPayload", false),
+    entry("octo.control", "instructions", "ContextInstructionsPayload", true, true)
+]);
+export function contextTypeDefinition(namespace, name) {
+    const definition = findContextTypeDefinition(namespace, name);
+    if (!definition)
+        throw new TypeError(`CONTEXT_TYPE_UNSUPPORTED: ${namespace}/${name}`);
+    return definition;
+}
+export function findContextTypeDefinition(namespace, name) {
+    return CONTEXT_TYPE_CATALOG.find((item) => item.namespace === namespace && item.name === name);
+}

package/node_modules/@mininglamp-oss/octo-runtime-protocol/dist/context-configuration.d.ts

@@ -0,0 +1,5 @@
+import type { ContextConfiguration, ContextEnvelope } from "./generated/protocol-types.js";
+/** 校验可持久化配置；身份、资源权限和强制来源仍由 Worker 验证。 */
+export declare function assertContextConfiguration(value: unknown): asserts value is ContextConfiguration;
+/** Agent mandatory values are authoritative; request differences are overwritten. */
+export declare function resolveContextConfiguration(configuration: ContextConfiguration, request: ContextEnvelope): ContextEnvelope;