@botlearn-course/daemon 0.0.13 → 0.0.14

package/dist/mcp/course-skills-server.js

@@ -0,0 +1,439 @@
+import { chmodSync, lstatSync, mkdtempSync, rmSync, } from "node:fs";
+import net from "node:net";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { RuntimeSkillProviderError, safeReferencePath, } from "../runtime-skills.js";
+const DEFAULT_PROTOCOL_VERSION = "2024-11-05";
+const MAX_REQUEST_LINE_BYTES = 32 * 1024;
+const MAX_REFERENCE_BYTES_PER_ACTIVATION = 1024 * 1024;
+const TOOLS = [
+    {
+        name: "list",
+        description: "List the immutable BotLearn Course Skills authorized for this activation.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "load",
+        description: "Load the locked SKILL.md for one authorized Course Skill before following it.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ref: { type: "string", minLength: 5, maxLength: 240 },
+            },
+            required: ["ref"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "load_reference",
+        description: "Load one relative reference path from a Course Skill already loaded in this activation.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ref: { type: "string", minLength: 5, maxLength: 240 },
+                path: { type: "string", minLength: 1, maxLength: 240 },
+            },
+            required: ["ref", "path"],
+            additionalProperties: false,
+        },
+    },
+];
+export class CourseSkillsMcpRuntime {
+    options;
+    grantsByRef;
+    loadedSkills = new Map();
+    loadedReferences = new Map();
+    referenceBytes = 0;
+    constructor(options) {
+        this.options = options;
+        this.grantsByRef = new Map(options.prepared.catalog.map((entry) => [entry.ref, entry]));
+    }
+    async emitAppliedEvents() {
+        for (const entry of this.options.prepared.catalog) {
+            await this.emit(entry, "applied");
+        }
+    }
+    async handle(request) {
+        if (request.id === undefined)
+            return null;
+        const id = responseId(request.id);
+        if (request.jsonrpc !== "2.0" || typeof request.method !== "string") {
+            return { jsonrpc: "2.0", id, error: { code: -32600, message: "Invalid Request" } };
+        }
+        if (request.method === "initialize") {
+            const requested = request.params && typeof request.params === "object"
+                ? request.params.protocolVersion
+                : undefined;
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: {
+                    protocolVersion: typeof requested === "string" && requested.length > 0
+                        ? requested
+                        : DEFAULT_PROTOCOL_VERSION,
+                    capabilities: { tools: {} },
+                    serverInfo: { name: "botlearn-course-skills", version: "0.1.0" },
+                },
+            };
+        }
+        if (request.method === "tools/list") {
+            return { jsonrpc: "2.0", id, result: { tools: TOOLS } };
+        }
+        if (request.method !== "tools/call") {
+            return { jsonrpc: "2.0", id, error: { code: -32601, message: "Method not found" } };
+        }
+        const params = objectValue(request.params);
+        const name = params && typeof params.name === "string" ? params.name : "";
+        const args = params ? objectValue(params.arguments) : null;
+        try {
+            if (name === "list") {
+                requireExactArguments(args, []);
+                return toolSuccess(id, "skill_catalog_listed", {
+                    skills: this.options.prepared.catalog.map((entry) => ({
+                        ref: entry.ref,
+                        digest: entry.digest,
+                        name: entry.name,
+                        description: entry.description,
+                        version: entry.version,
+                        requiredCapabilities: entry.requiredCapabilities,
+                    })),
+                });
+            }
+            if (name === "load") {
+                requireExactArguments(args, ["ref"]);
+                const ref = requiredArgument(args, "ref");
+                return toolSuccess(id, "skill_loaded", await this.loadSkill(ref));
+            }
+            if (name === "load_reference") {
+                requireExactArguments(args, ["ref", "path"]);
+                const ref = requiredArgument(args, "ref");
+                const referencePath = requiredArgument(args, "path");
+                return toolSuccess(id, "skill_reference_loaded", await this.loadReference(ref, referencePath));
+            }
+            return toolFailure(id, "unknown_tool");
+        }
+        catch (error) {
+            return toolFailure(id, safeRuntimeErrorCode(error));
+        }
+    }
+    async loadSkill(ref) {
+        const entry = this.requireGrant(ref);
+        const cached = this.loadedSkills.get(ref);
+        if (cached)
+            return cached;
+        const pending = (async () => {
+            await this.emit(entry, "selected");
+            try {
+                const loaded = await this.options.prepared.provider.loadSkill(ref);
+                await this.emit(entry, "loaded", {
+                    bytes: loaded.bytes,
+                    truncated: loaded.truncated,
+                });
+                return loaded;
+            }
+            catch (error) {
+                await this.emitLoadFailed(entry, error);
+                throw error;
+            }
+        })();
+        this.loadedSkills.set(ref, pending);
+        try {
+            return await pending;
+        }
+        catch (error) {
+            this.loadedSkills.delete(ref);
+            throw error;
+        }
+    }
+    async loadReference(ref, referencePath) {
+        const entry = this.requireGrant(ref);
+        let safePath;
+        try {
+            safePath = safeReferencePath(referencePath);
+        }
+        catch (error) {
+            await this.emitLoadFailed(entry, error);
+            throw error;
+        }
+        const selected = this.loadedSkills.get(ref);
+        if (!selected) {
+            const error = new RuntimeSkillProviderError("skill_not_selected", "Load the Skill before loading one of its references");
+            await this.emitLoadFailed(entry, error);
+            throw error;
+        }
+        // Presence in the cache only means load(ref) was selected. A parallel MCP
+        // request must not read references until the locked main content has
+        // actually passed Provider identity validation.
+        await selected;
+        const key = `${ref}\0${safePath}`;
+        const cached = this.loadedReferences.get(key);
+        if (cached)
+            return cached;
+        const pending = (async () => {
+            try {
+                const loaded = await this.options.prepared.provider.loadReference(ref, safePath);
+                if (loaded.bytes > MAX_REFERENCE_BYTES_PER_ACTIVATION - this.referenceBytes) {
+                    throw new RuntimeSkillProviderError("skill_load_budget_exceeded", "Course Skill reference read budget exceeded");
+                }
+                this.referenceBytes += loaded.bytes;
+                await this.emit(entry, "reference_loaded", {
+                    bytes: loaded.bytes,
+                    truncated: loaded.truncated,
+                });
+                return loaded;
+            }
+            catch (error) {
+                await this.emitLoadFailed(entry, error);
+                throw error;
+            }
+        })();
+        this.loadedReferences.set(key, pending);
+        try {
+            return await pending;
+        }
+        catch (error) {
+            this.loadedReferences.delete(key);
+            throw error;
+        }
+    }
+    requireGrant(ref) {
+        const entry = this.grantsByRef.get(ref);
+        if (!entry) {
+            throw new RuntimeSkillProviderError("skill_not_eligible", "Skill is not eligible for the current activation");
+        }
+        return entry;
+    }
+    async emit(entry, state, fields = {}) {
+        await this.options.onEvent({
+            schema_version: "agent-skill-event/0.1",
+            kind: "skill_event",
+            state,
+            ref: entry.ref,
+            digest: entry.digest,
+            load_mode: "mcp",
+            ...fields,
+        });
+    }
+    async emitLoadFailed(entry, error) {
+        await this.options.onEvent({
+            schema_version: "agent-skill-event/0.1",
+            kind: "skill_event",
+            state: "load_failed",
+            ref: entry.ref,
+            digest: entry.digest,
+            load_mode: "mcp",
+            code: safeRuntimeErrorCode(error),
+        });
+    }
+}
+export async function startCourseSkillsMcpServer(options) {
+    const managedRoot = resolveManagedSkillsRoot(options.managedRoot);
+    const dir = mkdtempSync(path.join(managedRoot ?? tmpdir(), "botlearn-skills-mcp-"));
+    const socketPath = path.join(dir, "server.sock");
+    const runtime = new CourseSkillsMcpRuntime(options);
+    const sockets = new Set();
+    const server = net.createServer((socket) => {
+        sockets.add(socket);
+        socket.on("close", () => sockets.delete(socket));
+        socket.on("error", () => socket.destroy());
+        serveSocket(socket, runtime);
+    });
+    try {
+        if (managedRoot)
+            chmodSync(dir, 0o750);
+        await listen(server, socketPath);
+        chmodSync(socketPath, managedRoot ? 0o660 : 0o600);
+    }
+    catch (error) {
+        await closeServer(server, sockets);
+        rmSync(dir, { recursive: true, force: true });
+        throw error;
+    }
+    let closed = false;
+    let applied;
+    return {
+        socketPath,
+        catalog: options.prepared.catalog,
+        markApplied() {
+            applied ??= runtime.emitAppliedEvents();
+            return applied;
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            await closeServer(server, sockets);
+            rmSync(dir, { recursive: true, force: true });
+        },
+    };
+}
+function serveSocket(socket, runtime) {
+    socket.setEncoding("utf8");
+    let buffer = "";
+    let chain = Promise.resolve();
+    socket.on("data", (chunk) => {
+        buffer += chunk;
+        if (Buffer.byteLength(buffer, "utf8") > MAX_REQUEST_LINE_BYTES) {
+            socket.destroy();
+            return;
+        }
+        let newline;
+        while ((newline = buffer.indexOf("\n")) >= 0) {
+            const line = buffer.slice(0, newline);
+            buffer = buffer.slice(newline + 1);
+            if (!line.trim())
+                continue;
+            chain = chain.then(async () => {
+                let response;
+                try {
+                    response = await runtime.handle(JSON.parse(line));
+                }
+                catch {
+                    response = {
+                        jsonrpc: "2.0",
+                        id: null,
+                        error: { code: -32700, message: "Parse error" },
+                    };
+                }
+                if (response && !socket.destroyed) {
+                    socket.write(`${JSON.stringify(response)}\n`);
+                }
+            }).catch(() => {
+                socket.destroy();
+            });
+        }
+    });
+}
+function responseId(value) {
+    return typeof value === "string" || typeof value === "number" || value === null
+        ? value
+        : null;
+}
+function toolSuccess(id, code, data) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        schemaVersion: "tool-result/0.1",
+                        ok: true,
+                        code,
+                        data,
+                        evidence: [],
+                    }),
+                }],
+            isError: false,
+        },
+    };
+}
+function toolFailure(id, code) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        schemaVersion: "tool-result/0.1",
+                        ok: false,
+                        code,
+                        error: { message: "Course Skill request failed" },
+                        evidence: [],
+                    }),
+                }],
+            isError: true,
+        },
+    };
+}
+function objectValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function requireExactArguments(args, keys) {
+    if (keys.length === 0 && args === null)
+        return;
+    if (!args || Object.keys(args).length !== keys.length) {
+        throw new RuntimeSkillProviderError("skill_request_invalid", "Course Skill tool arguments are invalid");
+    }
+    const allowed = new Set(keys);
+    if (Object.keys(args).some((key) => !allowed.has(key))) {
+        throw new RuntimeSkillProviderError("skill_request_invalid", "Course Skill tool arguments are invalid");
+    }
+}
+function requiredArgument(args, key) {
+    const value = args?.[key];
+    if (typeof value !== "string"
+        || value.length < 1
+        || Buffer.byteLength(value, "utf8") > 240) {
+        throw new RuntimeSkillProviderError("skill_request_invalid", "Course Skill tool arguments are invalid");
+    }
+    return value;
+}
+function safeRuntimeErrorCode(error) {
+    if (error instanceof RuntimeSkillProviderError
+        && /^[a-z][a-z0-9_]{2,79}$/.test(error.code)) {
+        return error.code;
+    }
+    return "skill_load_failed";
+}
+function resolveManagedSkillsRoot(explicit) {
+    if (explicit === null)
+        return null;
+    let root = explicit?.trim();
+    if (root === undefined) {
+        const managedRuntime = process.env.BOTLEARN_RUNTIME_USER?.trim()
+            || process.env.BOTLEARN_RUNTIME_LAUNCH_MODE?.trim();
+        if (!managedRuntime)
+            return null;
+        root = process.env.BOTLEARN_AGENT_SERVICE_PROFILE_ROOT?.trim();
+        if (!root) {
+            throw new RuntimeSkillProviderError("skill_provider_runtime_boundary_invalid", "Managed runtime is missing its profile root");
+        }
+    }
+    if (!root || !path.isAbsolute(root)) {
+        throw new RuntimeSkillProviderError("skill_provider_runtime_boundary_invalid", "Managed Course Skill root must be absolute");
+    }
+    try {
+        const stat = lstatSync(root);
+        const currentUid = process.getuid?.();
+        if (!stat.isDirectory()
+            || stat.isSymbolicLink()
+            || (currentUid !== undefined && stat.uid !== currentUid)
+            || (stat.mode & 0o022) !== 0) {
+            throw new Error("unsafe root");
+        }
+    }
+    catch {
+        throw new RuntimeSkillProviderError("skill_provider_runtime_boundary_invalid", "Managed Course Skill root is unavailable");
+    }
+    return root;
+}
+function listen(server, socketPath) {
+    return new Promise((resolve, reject) => {
+        const onError = (error) => {
+            server.off("listening", onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            server.off("error", onError);
+            resolve();
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(socketPath);
+    });
+}
+function closeServer(server, sockets) {
+    for (const socket of sockets)
+        socket.destroy();
+    if (!server.listening)
+        return Promise.resolve();
+    return new Promise((resolve) => server.close(() => resolve()));
+}

package/dist/run-dispatcher.d.ts

@@ -1,6 +1,7 @@
 import { type ScanLimits } from "./file-candidates.js";
 import { type InputAttachmentGrant } from "./input-attachments.js";
 import { type Logger } from "./log.js";
+import type { PreparedRuntimeSkillProvider } from "./runtime-skills.js";
 import { type CourseRuntimeProfile, type CourseRuntime, type RunEvent, type RunStartPayload } from "./types.js";
 export interface RunDispatcherOptions {
     defaultRuntimeId?: string;
@@ -17,6 +18,7 @@ export interface PreparedPersistentTurn {
     contextRevision: number;
     runtimeEnv?: NodeJS.ProcessEnv;
     inputAttachmentGrant?: InputAttachmentGrant;
+    skillProvider?: PreparedRuntimeSkillProvider;
 }
 export interface PersistentSessionExecution {
     prepareTurn(payload: RunStartPayload): PreparedPersistentTurn;

package/dist/run-dispatcher.js

@@ -9,6 +9,7 @@ import { missingRunCapabilities } from "./runtime-capabilities.js";
 import { RunQueue } from "./run-queue.js";
 import { applyRunRuntimeProfile, cleanupRunRuntimeProfile, RuntimeProfileApplyError, runtimeProfileInstructions, } from "./runtime-profile.js";
 import { TranscriptWriter } from "./transcript.js";
+import { buildToolObservation } from "./tool-observation.js";
 import { RuntimeExecutionError, } from "./types.js";
 import { ensureRunWorkspace, transcriptPath } from "./workspace.js";
 // 与 runtimes/index.ts 的 DEFAULT_RUNTIME_ID 保持一致（此处不 import registry，避免拉入全部 adapter）。
@@ -24,7 +25,8 @@ const CONTENT_FLUSH_INTERVAL_MS = 100;
 const AGENT_STREAM_SCHEMA_VERSION = "agent-stream/0.1";
 const SAFE_TOOL_NAME = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,79}$/;
 const SAFE_FAILURE_CODE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$/;
-const FAILURE_DIAGNOSTIC_SCHEMA_VERSION = "botlearn-agent-run-failure/1";
+const SAFE_FAILURE_MODEL = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,159}$/;
+const FAILURE_DIAGNOSTIC_SCHEMA_VERSION = "botlearn-agent-run-failure/2";
 function wireFailureDiagnostic(runtime, error, message) {
     const failure = error instanceof RuntimeExecutionError ? error.failure : undefined;
     const info = errorInfo(error);
@@ -52,6 +54,29 @@ function wireFailureDiagnostic(runtime, error, message) {
     if (typeof errorName === "string" && SAFE_FAILURE_CODE.test(errorName)) {
         diagnostic.error_name = errorName;
     }
+    if (typeof failure?.error_code === "string" && SAFE_FAILURE_CODE.test(failure.error_code)) {
+        diagnostic.error_code = failure.error_code;
+    }
+    if (typeof failure?.model === "string" && SAFE_FAILURE_MODEL.test(failure.model)) {
+        diagnostic.model = failure.model;
+    }
+    if (failure?.completion) {
+        diagnostic.completion = {
+            assistant_message_count: Math.max(0, Math.min(10_000, Math.floor(failure.completion.assistant_message_count))),
+            reasoning_message_count: Math.max(0, Math.min(10_000, Math.floor(failure.completion.reasoning_message_count))),
+            assistant_content_present: Boolean(failure.completion.assistant_content_present),
+            reasoning_content_present: Boolean(failure.completion.reasoning_content_present),
+            tool_call_count: Math.max(0, Math.min(10_000, Math.floor(failure.completion.tool_call_count))),
+            ...(typeof failure.completion.turn_status === "string"
+                && SAFE_FAILURE_CODE.test(failure.completion.turn_status)
+                ? { turn_status: failure.completion.turn_status }
+                : {}),
+            ...(typeof failure.completion.finish_reason === "string"
+                && SAFE_FAILURE_CODE.test(failure.completion.finish_reason)
+                ? { finish_reason: failure.completion.finish_reason }
+                : {}),
+        };
+    }
     if (typeof failure?.stderr_tail === "string" && failure.stderr_tail) {
         diagnostic.stderr_tail = sanitizeRuntimeFailureText(failure.stderr_tail, 8192);
     }
@@ -207,6 +232,7 @@ export class RunDispatcher {
             const providerReported = inputTokens !== undefined
                 || runtimeUsage.cached_input_tokens !== undefined
                 || outputTokens !== undefined
+                || runtimeUsage.reasoning_tokens !== undefined
                 || runtimeUsage.cost_usd !== undefined;
             return {
                 schema_version: "agent-run-usage/0.1",
@@ -278,7 +304,6 @@ export class RunDispatcher {
                     agentRunId: runId,
                     traceId,
                     runtime: runtimeId,
-                    model: payload.runtime.model,
                     status: event.type,
                     errorType: event.payload?.error_type,
                 });
@@ -491,6 +516,23 @@ export class RunDispatcher {
                 });
             };
             const sink = {
+                skillEvent: async (event) => {
+                    await flushContent();
+                    await queueStreamEvent({
+                        type: "run.block",
+                        payload: {
+                            schema_version: event.schema_version,
+                            kind: event.kind,
+                            state: event.state,
+                            ref: event.ref,
+                            digest: event.digest,
+                            load_mode: event.load_mode,
+                            ...(event.bytes !== undefined ? { bytes: event.bytes } : {}),
+                            ...(event.truncated !== undefined ? { truncated: event.truncated } : {}),
+                            ...(event.code !== undefined ? { code: event.code } : {}),
+                        },
+                    });
+                },
                 progressDispositions: async (dispositions) => {
                     progressDisposition.invalid += dispositions.invalid;
                     progressDisposition.deduplicated += dispositions.deduplicated;
@@ -622,6 +664,13 @@ export class RunDispatcher {
                     if (block.kind === "tool_call") {
                         lastReportedKind = block.kind;
                         lastReasoningPhase = null;
+                        const observation = buildToolObservation(block, runtime.id, workspaceDir);
+                        if (observation) {
+                            await send({
+                                type: "run.observation",
+                                payload: observation,
+                            });
+                        }
                         await queueStreamEvent({
                             type: "run.block",
                             payload: {
@@ -639,6 +688,13 @@ export class RunDispatcher {
                     if (block.kind === "tool_result") {
                         lastReportedKind = block.kind;
                         lastReasoningPhase = null;
+                        const observation = buildToolObservation(block, runtime.id, workspaceDir);
+                        if (observation) {
+                            await send({
+                                type: "run.observation",
+                                payload: observation,
+                            });
+                        }
                         await queueStreamEvent({
                             type: "run.block",
                             payload: {
@@ -693,6 +749,9 @@ export class RunDispatcher {
                             ...(persistentTurn.runtimeEnv
                                 ? { runtimeEnv: persistentTurn.runtimeEnv }
                                 : {}),
+                            ...(persistentTurn.skillProvider
+                                ? { skillProvider: persistentTurn.skillProvider }
+                                : {}),
                         }
                         : {}),
                 }, sink, controller.signal);

package/dist/runtime-capabilities.d.ts

@@ -1,3 +1,4 @@
 import type { RunStartPayload } from "./types.js";
+export declare function runtimeSupportsCourseSkills(runtimeId: string): boolean;
 export declare function availableRunCapabilities(payload: RunStartPayload, workspaceDir: string): string[];
 export declare function missingRunCapabilities(payload: RunStartPayload, workspaceDir: string): string[];

package/dist/runtime-capabilities.js

@@ -9,6 +9,10 @@ const WEB_SEARCH_RUNTIMES = new Set([
     "hermes-agent",
     "fake",
 ]);
+const COURSE_SKILL_RUNTIMES = new Set(["deepseek-tui"]);
+export function runtimeSupportsCourseSkills(runtimeId) {
+    return COURSE_SKILL_RUNTIMES.has(runtimeId);
+}
 export function availableRunCapabilities(payload, workspaceDir) {
     const capabilities = new Set();
     const probePath = path.join(workspaceDir, `.botlearn-write-probe-${process.pid}-${randomUUID()}`);

package/dist/runtime-skills.d.ts

@@ -0,0 +1,93 @@
+export declare const COURSE_SKILLS_BINDING_SCHEMA: "course-skills-binding/0.1";
+export declare const COURSE_SKILLS_PROTOCOL: "course-skills/0.1";
+export declare const COURSE_SKILLS_CALL_SCHEMA: "course-skills-call/0.1";
+export interface RuntimeSkillGrant {
+    assetVersionId: string;
+    ref: string;
+    digest: string;
+}
+export interface RuntimeSkillProviderBinding {
+    schemaVersion: typeof COURSE_SKILLS_BINDING_SCHEMA;
+    protocol: typeof COURSE_SKILLS_PROTOCOL;
+    endpoint: string;
+    bearerToken: string;
+    expiresAt: string;
+    effectiveSkillGrants: RuntimeSkillGrant[];
+}
+export interface RuntimeSkillCatalogEntry extends RuntimeSkillGrant {
+    name: string;
+    description: string;
+    version: string;
+    requiredCapabilities: string[];
+}
+export interface RuntimeLoadedSkill {
+    ref: string;
+    digest: string;
+    content: string;
+    bytes: number;
+    truncated: boolean;
+}
+export interface RuntimeSkillReference extends RuntimeLoadedSkill {
+    path: string;
+}
+export interface RuntimeSkillProvider {
+    listEligibleSkills(): Promise<RuntimeSkillCatalogEntry[]>;
+    loadSkill(ref: string): Promise<RuntimeLoadedSkill>;
+    loadReference(ref: string, referencePath: string): Promise<RuntimeSkillReference>;
+}
+export interface PreparedRuntimeSkillProvider {
+    binding: RuntimeSkillProviderBinding;
+    provider: RuntimeSkillProvider;
+    catalog: RuntimeSkillCatalogEntry[];
+}
+export type RuntimeSkillEventState = "applied" | "selected" | "loaded" | "reference_loaded" | "load_failed";
+export interface RuntimeSkillEvent {
+    schema_version: "agent-skill-event/0.1";
+    kind: "skill_event";
+    state: RuntimeSkillEventState;
+    ref: string;
+    digest: string;
+    load_mode: "mcp";
+    bytes?: number;
+    truncated?: boolean;
+    code?: string;
+}
+export declare class RuntimeSkillProviderError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export type RuntimeSkillProviderFactory = (rawBinding: unknown) => Promise<PreparedRuntimeSkillProvider>;
+interface RuntimeSkillBindingParseOptions {
+    allowInsecureLoopbackForTests?: boolean;
+}
+export declare function parseRuntimeSkillProviderBinding(raw: unknown, now?: number, options?: RuntimeSkillBindingParseOptions): RuntimeSkillProviderBinding;
+/**
+ * Parse only the stable grant identity of a replayed binding.
+ *
+ * Credential values remain the first accepted activation snapshot, so replay validation
+ * deliberately checks their shape but not their endpoint/expiry semantics.
+ */
+export declare function parseRuntimeSkillProviderGrantSet(raw: unknown): RuntimeSkillGrant[];
+export declare function prepareRuntimeSkillProvider(rawBinding: unknown, options?: {
+    fetchFn?: typeof fetch;
+    now?: () => number;
+    /** Tests only: production bindings must use HTTPS. */
+    allowInsecureLoopbackForTests?: boolean;
+}): Promise<PreparedRuntimeSkillProvider>;
+export declare class HttpRuntimeSkillProvider implements RuntimeSkillProvider {
+    private readonly binding;
+    private readonly fetchFn;
+    private readonly now;
+    private readonly grantsByRef;
+    constructor(binding: RuntimeSkillProviderBinding, options?: {
+        fetchFn?: typeof fetch;
+        now?: () => number;
+    });
+    listEligibleSkills(): Promise<RuntimeSkillCatalogEntry[]>;
+    loadSkill(ref: string): Promise<RuntimeLoadedSkill>;
+    loadReference(ref: string, referencePath: string): Promise<RuntimeSkillReference>;
+    private requireEligible;
+    private call;
+}
+export declare function safeReferencePath(value: unknown): string;
+export {};