@nylorun/agents 0.0.0-bootstrap → 0.3.0-beta

package/dist/execute-action.js

@@ -0,0 +1,190 @@
+import { implementationsFor, isToolError, normalizeToolDefinition, normalizedSchemasFor, } from "@nylorun/core/define";
+class Suspend {
+    outcome;
+    constructor(outcome) {
+        this.outcome = outcome;
+    }
+}
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : {};
+/** Executes code only after a host-issued claim. No engine dependency. */
+export async function executeAction(action, agent, signal) {
+    const impl = implementationsFor(agent)[action.capabilityId];
+    if (!impl)
+        throw new Error(`No capability ${action.capabilityId}`);
+    if (action.kind === "beforeModelCall") {
+        if (!impl.beforeModelCall)
+            throw new Error("Missing beforeModelCall implementation");
+        try {
+            return { value: (await impl.beforeModelCall(action.input)) ?? {} };
+        }
+        catch (error) {
+            return { value: { block: message(error) } };
+        }
+    }
+    if (action.kind === "afterModelCall") {
+        if (!impl.afterModelCall)
+            throw new Error("Missing afterModelCall implementation");
+        try {
+            return {
+                value: (await impl.afterModelCall(action.input, action.context)) ?? {},
+            };
+        }
+        catch (error) {
+            return { value: { block: message(error) } };
+        }
+    }
+    const raw = impl.tools?.[action.toolName ?? ""];
+    if (!raw)
+        throw new Error("Missing tool implementation");
+    const tool = normalizeToolDefinition(raw);
+    const schemas = normalizedSchemasFor(tool);
+    const input = schemas.inputSchema.validate(action.input);
+    if (!input.ok)
+        return {
+            value: {
+                kind: "failed",
+                code: "tool.invalid-input",
+                message: JSON.stringify(input.issues),
+            },
+        };
+    const ctx = action.context;
+    const state = { ...object(ctx.state) };
+    const statePatch = {};
+    const resume = object(ctx.resume);
+    const token = object(resume.token);
+    const memo = object(token._nylorun);
+    const steps = { ...object(memo.steps) };
+    const answers = { ...object(memo.answers) };
+    let waitIndex = 0;
+    let gateApproved = Boolean(memo.gateApproved) ||
+        Boolean(memo.approvalGate && resume.kind === "approval" && resume.approved);
+    const durableToken = (extra = {}) => ({
+        _nylorun: { steps, answers, waitIndex, gateApproved, ...extra },
+    });
+    const wait = async (kind, prompt, metadata) => {
+        const index = String(waitIndex++);
+        if (index in answers)
+            return answers[index];
+        if (!memo.approvalGate &&
+            resume.kind === kind &&
+            Number(memo.waitIndex ?? 0) === Number(index)) {
+            const answer = kind === "approval" ? Boolean(resume.approved) : resume.value;
+            answers[index] = answer;
+            return answer;
+        }
+        throw new Suspend({
+            kind: "interaction-required",
+            interaction: { kind, prompt, ...(metadata ? { metadata } : {}) },
+            token: {
+                _nylorun: { steps, answers, waitIndex: Number(index), gateApproved },
+            },
+        });
+    };
+    const context = {
+        executionId: String(ctx.executionId ?? action.sessionId),
+        turnId: String(ctx.turnId ?? action.turnId),
+        stepId: String(ctx.stepId ?? ""),
+        callId: String(ctx.callId ?? action.actionId),
+        invocationId: String(ctx.invocationId ?? action.actionId),
+        idempotencyKey: String(ctx.idempotencyKey ?? action.actionId),
+        signal,
+        info: ctx.info,
+        session: { id: action.sessionId },
+        ...(ctx.resume ? { resume: ctx.resume } : {}),
+        state: {
+            get: (key) => state[key],
+            set: (key, value) => {
+                state[key] = value;
+                statePatch[key] = value;
+            },
+            entries: () => ({ ...state }),
+        },
+        progress() {
+            /* Canonical events are host-owned; progress transport is deferred. */
+        },
+        ask: (prompt, options) => wait("response", prompt, options),
+        approve: (prompt) => wait("approval", prompt),
+        sleep: async (duration) => {
+            throw new Suspend({
+                kind: "deferred",
+                token: durableToken({ wait: { kind: "sleep", duration } }),
+            });
+        },
+        waitFor: async (event, options) => {
+            throw new Suspend({
+                kind: "deferred",
+                token: durableToken({ wait: { kind: "waitFor", event, ...options } }),
+            });
+        },
+        step: async (name, fn) => {
+            if (Object.prototype.hasOwnProperty.call(steps, name))
+                return steps[name];
+            signal.throwIfAborted();
+            const value = await fn();
+            // Memoized values are durable only with a persisted action outcome. Interrupted actions stay uncertain.
+            steps[name] = JSON.parse(JSON.stringify(value ?? null));
+            return value;
+        },
+    };
+    try {
+        signal.throwIfAborted();
+        if (tool.approval && !gateApproved) {
+            const approval = await tool.approval(input.value);
+            if (approval)
+                throw new Suspend({
+                    kind: "interaction-required",
+                    interaction: {
+                        kind: "approval",
+                        prompt: typeof approval === "string" ? approval : `Approve ${tool.name}?`,
+                    },
+                    token: durableToken({ approvalGate: true }),
+                });
+            gateApproved = true;
+        }
+        if (resume.kind === "approval" && resume.approved === false)
+            return { value: { kind: "denied", reason: "Approval denied" } };
+        const value = await tool.execute(input.value, context);
+        const tagged = object(value);
+        let outcome;
+        if ([
+            "completed",
+            "failed",
+            "denied",
+            "interaction-required",
+            "deferred",
+        ].includes(tagged.kind))
+            outcome = value;
+        else
+            outcome = { kind: "completed", output: value ?? null };
+        if (outcome.kind === "completed" && schemas.outputSchema) {
+            const parsed = schemas.outputSchema.validate(outcome.output);
+            outcome = parsed.ok
+                ? { ...outcome, output: parsed.value }
+                : {
+                    kind: "failed",
+                    code: "tool.invalid-output",
+                    message: JSON.stringify(parsed.issues),
+                };
+        }
+        return { value: outcome, statePatch };
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw signal.reason;
+        return {
+            value: error instanceof Suspend
+                ? error.outcome
+                : {
+                    kind: "failed",
+                    code: isToolError(error) ? error.code : "tool.execution-failed",
+                    message: message(error),
+                },
+            statePatch,
+        };
+    }
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/executor.d.ts

@@ -0,0 +1,15 @@
+import { type AgentSource } from "./client.js";
+import { type Destination } from "./http.js";
+export interface ConnectOptions {
+    agents: readonly AgentSource[];
+    runtime?: Destination;
+    implementationVersion?: string;
+    onError?: (error: unknown) => void;
+}
+export interface AgentConnection {
+    /** Settles after authenticated SSE is established and initial discovery succeeds. */
+    readonly ready: Promise<void>;
+    /** Abort subscriptions and leases. Running user code receives an AbortSignal. */
+    close(): Promise<void>;
+}
+export declare function connectAgents(options: ConnectOptions): AgentConnection;

package/dist/executor.js

@@ -0,0 +1,210 @@
+import { AgentManifestSchema, ActionSchema, ActionClaimResponseSchema, } from "@nylorun/core/contracts";
+import { assertNoMiddlewareClosures } from "./client.js";
+import { Transport, RuntimeError, delay, env, id, segment, } from "./http.js";
+import { readSSE } from "./sse.js";
+import { executeAction } from "./execute-action.js";
+export function connectAgents(options) {
+    const transport = new Transport(options.runtime, "executor");
+    const version = options.implementationVersion ??
+        env("NYLORUN_IMPLEMENTATION_VERSION") ??
+        "dev";
+    const agents = new Map();
+    for (const source of options.agents) {
+        const built = source.build?.() ?? source;
+        assertNoMiddlewareClosures(built);
+        AgentManifestSchema.parse(built.manifest);
+        if (agents.has(built.id))
+            throw new Error(`Duplicate connected agent ${built.id}`);
+        agents.set(built.id, built);
+    }
+    if (!agents.size)
+        throw new Error("connectAgents requires at least one agent");
+    const controller = new AbortController();
+    const signal = controller.signal;
+    const active = new Map();
+    let resolveReady;
+    let rejectReady;
+    const ready = new Promise((resolve, reject) => {
+        resolveReady = resolve;
+        rejectReady = reject;
+    });
+    // Avoid an unhandled rejection for callers that immediately close the handle.
+    void ready.catch(() => { });
+    const report = (error) => {
+        try {
+            options.onError?.(error);
+        }
+        catch { }
+    };
+    let discovering = false, dirty = false;
+    const discover = async () => {
+        dirty = true;
+        if (discovering)
+            return;
+        discovering = true;
+        try {
+            while (dirty && !signal.aborted) {
+                dirty = false;
+                const response = await transport.json("/v1/actions", "GET", undefined, signal);
+                for (const item of response.actions) {
+                    const action = ActionSchema.parse(item);
+                    const agent = agents.get(action.agentId);
+                    if (!agent || action.status !== "pending" || active.has(action.actionId))
+                        continue;
+                    const work = new AbortController();
+                    active.set(action.actionId, work);
+                    let delivered = false;
+                    void processAction(action, agent, work)
+                        .then(() => {
+                        delivered = true;
+                    })
+                        .catch((error) => {
+                        if (!signal.aborted)
+                            report(error);
+                    })
+                        .finally(() => {
+                        active.delete(action.actionId);
+                        // Completion-driven discovery drains bounded server pages without periodic polling.
+                        if (delivered && !signal.aborted)
+                            void discover().catch(report);
+                    });
+                }
+            }
+        }
+        finally {
+            discovering = false;
+        }
+    };
+    const processAction = async (action, agent, work) => {
+        const stop = () => work.abort(signal.reason);
+        signal.addEventListener("abort", stop, { once: true });
+        let renewal;
+        let renewing = true;
+        let wakeRenewal;
+        try {
+            const claim = ActionClaimResponseSchema.parse(await transport.json(`/v1/actions/${segment(action.actionId)}/claim`, "POST", {
+                requestId: id(),
+                implementationVersion: version,
+            }, work.signal));
+            if (claim.action.actionId !== action.actionId)
+                throw new Error("Claim definition mismatch");
+            let expires = Date.parse(claim.leaseExpiresAt);
+            renewal = (async () => {
+                while (renewing && !work.signal.aborted) {
+                    const remaining = expires - Date.now();
+                    if (!Number.isFinite(remaining) || remaining <= 0)
+                        throw new Error("Executor lease expired");
+                    await new Promise((resolve) => {
+                        const finish = () => {
+                            clearTimeout(timer);
+                            work.signal.removeEventListener("abort", finish);
+                            resolve();
+                        };
+                        const timer = setTimeout(finish, Math.max(50, Math.floor(remaining / 3)));
+                        wakeRenewal = finish;
+                        work.signal.addEventListener("abort", finish, { once: true });
+                    });
+                    if (!renewing || work.signal.aborted)
+                        return;
+                    const renewed = await transport.json(`/v1/actions/${segment(action.actionId)}/heartbeat`, "POST", {
+                        requestId: id(),
+                        claimId: claim.claimId,
+                        generation: claim.generation,
+                    }, work.signal);
+                    expires = Date.parse(renewed.leaseExpiresAt);
+                }
+            })().catch((error) => {
+                if (renewing && !work.signal.aborted) {
+                    work.abort(error);
+                    report(error);
+                }
+            });
+            const outcome = await executeAction(claim.action, agent, work.signal);
+            work.signal.throwIfAborted();
+            const command = {
+                type: "action_result",
+                requestId: id(),
+                idempotencyKey: `action:${action.actionId}:${claim.generation}`,
+                actionId: action.actionId,
+                claimId: claim.claimId,
+                generation: claim.generation,
+                outcome,
+            };
+            // Retrying delivery never re-invokes the tool/hook. Lost acknowledgements use the same receipt key.
+            for (let attempt = 0;; attempt++) {
+                try {
+                    await transport.json(`/v1/sessions/${segment(action.sessionId)}/commands`, "POST", command, work.signal);
+                    break;
+                }
+                catch (error) {
+                    if (work.signal.aborted ||
+                        attempt >= 4 ||
+                        (error instanceof RuntimeError &&
+                            error.status < 500 &&
+                            ![408, 429].includes(error.status)))
+                        throw error;
+                    await delay(Math.min(4000, 250 * 2 ** attempt), work.signal);
+                }
+            }
+        }
+        finally {
+            renewing = false;
+            wakeRenewal?.();
+            await renewal;
+            signal.removeEventListener("abort", stop);
+        }
+    };
+    const loop = (async () => {
+        let retry = 250;
+        while (!signal.aborted) {
+            const subscription = new AbortController();
+            const stop = () => subscription.abort(signal.reason);
+            signal.addEventListener("abort", stop, { once: true });
+            try {
+                const response = await transport.request("/v1/executors/connect", {
+                    signal: subscription.signal,
+                    headers: { Accept: "text/event-stream" },
+                });
+                if (!response.headers.get("content-type")?.includes("text/event-stream"))
+                    throw new Error("Executor endpoint did not return SSE");
+                // Subscription exists before initial discovery; notifications can safely accumulate in its stream.
+                await discover();
+                resolveReady();
+                for await (const frame of readSSE(response, subscription.signal)) {
+                    retry = 250;
+                    if (frame.event === "work_available" ||
+                        (frame.data && JSON.parse(frame.data).type === "work_available"))
+                        await discover();
+                }
+            }
+            catch (error) {
+                if (signal.aborted)
+                    break;
+                report(error);
+                if (error instanceof RuntimeError &&
+                    [400, 401, 403, 404].includes(error.status)) {
+                    rejectReady(error);
+                    controller.abort(error);
+                    break;
+                }
+            }
+            finally {
+                subscription.abort();
+                signal.removeEventListener("abort", stop);
+            }
+            if (!signal.aborted)
+                await delay(retry, signal).catch(() => { });
+            retry = Math.min(30000, retry * 2);
+        }
+        rejectReady(signal.reason ?? new Error("Executor connection closed"));
+    })();
+    return {
+        ready,
+        async close() {
+            controller.abort(new Error("Executor connection closed"));
+            for (const work of active.values())
+                work.abort(signal.reason);
+            await loop;
+        },
+    };
+}

package/dist/http.d.ts

@@ -0,0 +1,22 @@
+export interface Destination {
+    url?: string;
+    key?: string;
+    fetch?: typeof fetch;
+}
+export declare function env(name: string): string | undefined;
+export declare class RuntimeError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown);
+}
+export declare class Transport {
+    readonly url: string;
+    readonly key: string;
+    readonly fetcher: typeof fetch;
+    constructor(options?: Destination, role?: "server" | "executor");
+    request(path: string, init?: RequestInit): Promise<Response>;
+    json<T>(path: string, method?: string, body?: unknown, signal?: AbortSignal): Promise<T>;
+}
+export declare const id: () => `${string}-${string}-${string}-${string}-${string}`;
+export declare const segment: (value: string) => string;
+export declare function delay(ms: number, signal: AbortSignal): Promise<void>;

package/dist/http.js

@@ -0,0 +1,81 @@
+export function env(name) {
+    return typeof process !== "undefined" ? process.env[name] : undefined;
+}
+export class RuntimeError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`Runtime HTTP ${status}: ${JSON.stringify(body)}`);
+        this.status = status;
+        this.body = body;
+    }
+}
+export class Transport {
+    url;
+    key;
+    fetcher;
+    constructor(options = {}, role = "server") {
+        const url = options.url ?? env("NYLORUN_RUNTIME_URL");
+        const key = options.key ??
+            env(role === "server" ? "NYLORUN_SERVER_KEY" : "NYLORUN_EXECUTOR_KEY");
+        if (!url || !key)
+            throw new Error(`Set Runtime url and ${role} key explicitly or via NYLORUN_RUNTIME_URL / NYLORUN_${role.toUpperCase()}_KEY`);
+        const parsed = new URL(url);
+        if (!["http:", "https:"].includes(parsed.protocol))
+            throw new Error("Runtime requires an HTTP(S) URL");
+        this.url = url.replace(/\/$/, "");
+        this.key = key;
+        this.fetcher = options.fetch ?? globalThis.fetch;
+    }
+    async request(path, init = {}) {
+        const headers = new Headers(init.headers);
+        headers.set("Authorization", `Bearer ${this.key}`);
+        if (init.body)
+            headers.set("Content-Type", "application/json");
+        const response = await this.fetcher(this.url + path, {
+            ...init,
+            headers,
+            redirect: "error",
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            let body = text;
+            try {
+                body = JSON.parse(text);
+            }
+            catch { }
+            throw new RuntimeError(response.status, body);
+        }
+        return response;
+    }
+    async json(path, method = "GET", body, signal) {
+        const response = await this.request(path, {
+            method,
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            signal,
+        });
+        return response.status === 204
+            ? undefined
+            : response.json();
+    }
+}
+export const id = () => globalThis.crypto.randomUUID();
+export const segment = (value) => encodeURIComponent(value);
+export function delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const stop = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", stop);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", stop);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", stop, { once: true });
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError, capability, tool, defineSchema, ToolError, } from "@nylorun/core/define";
+export type { AgentOptions, AgentManifest, BuiltAgent, ToolDefinition, ToolExecutionContext, ToolOutcome, Patch, Decision, JsonValue, JsonObject, } from "@nylorun/core/define";
+export type { LiveEvent, SessionCommand, Action, ActionOutcome, CredentialInfo, CredentialSelection, VaultInfo, } from "@nylorun/core/contracts";
+export { AgentsClient, SessionClient, createClient } from "./client.js";
+export type { AgentSource, SessionView, CommandOptions } from "./client.js";
+export { connectAgents } from "./executor.js";
+export type { ConnectOptions, AgentConnection } from "./executor.js";
+export { RuntimeError } from "./http.js";
+export type { Destination } from "./http.js";
+export { plugin } from "./plugins/plugin.js";
+export type { PluginCapability } from "./plugins/plugin.js";
+export { loadPlugin, PluginError } from "./plugins/load.js";
+export type { LoadedPlugin, PluginDiagnostic } from "./plugins/load.js";
+export { prepareStdioLaunch, expandPluginPlaceholders } from "./plugins/launch.js";
+export type { StdioLaunch } from "./plugins/launch.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+// Definition authoring and wire contracts are the only harness runtime imports.
+export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError, capability, tool, defineSchema, ToolError, } from "@nylorun/core/define";
+export { AgentsClient, SessionClient, createClient } from "./client.js";
+export { connectAgents } from "./executor.js";
+export { RuntimeError } from "./http.js";
+export { plugin } from "./plugins/plugin.js";
+export { loadPlugin, PluginError } from "./plugins/load.js";
+export { prepareStdioLaunch, expandPluginPlaceholders } from "./plugins/launch.js";

package/dist/plugins/launch.d.ts

@@ -0,0 +1,17 @@
+import type { McpServerManifest } from "@nylorun/core/define";
+/** Single-pass replacement. Text inserted for a token is not scanned again. */
+export declare function expandPluginPlaceholders(value: string, pluginRoot: string, pluginData: string): string;
+export interface StdioLaunch {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+}
+export declare function prepareStdioLaunch(server: Extract<McpServerManifest, {
+    type: "stdio";
+}>, options: {
+    readonly pluginRoot: string;
+    readonly pluginData: string;
+    readonly baseEnv?: Readonly<Record<string, string | undefined>>;
+}): StdioLaunch;
+export declare function resolveContainedCwd(cwd: string, pluginRoot: string, pluginData: string): string;

package/dist/plugins/launch.js

@@ -0,0 +1,71 @@
+import { mkdirSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+const ROOT_TOKEN = "${PLUGIN_ROOT}";
+const DATA_TOKEN = "${PLUGIN_DATA}";
+/** Single-pass replacement. Text inserted for a token is not scanned again. */
+export function expandPluginPlaceholders(value, pluginRoot, pluginData) {
+    let out = "";
+    for (let index = 0; index < value.length;) {
+        if (value.startsWith(ROOT_TOKEN, index)) {
+            out += pluginRoot;
+            index += ROOT_TOKEN.length;
+            continue;
+        }
+        if (value.startsWith(DATA_TOKEN, index)) {
+            out += pluginData;
+            index += DATA_TOKEN.length;
+            continue;
+        }
+        out += value[index];
+        index += 1;
+    }
+    return out;
+}
+export function prepareStdioLaunch(server, options) {
+    const pluginRoot = options.pluginRoot;
+    const pluginData = options.pluginData;
+    mkdirSync(pluginData, { recursive: true });
+    const command = resolveCommand(server.command, pluginRoot);
+    const args = (server.args ?? []).map((arg) => expandPluginPlaceholders(arg, pluginRoot, pluginData));
+    const cwd = server.cwd
+        ? resolveContainedCwd(server.cwd, pluginRoot, pluginData)
+        : pluginRoot;
+    const env = {};
+    for (const [key, value] of Object.entries(options.baseEnv ?? {})) {
+        if (typeof value === "string")
+            setEnv(env, key, value);
+    }
+    for (const [key, value] of Object.entries(server.env ?? {}))
+        setEnv(env, key, expandPluginPlaceholders(value, pluginRoot, pluginData));
+    setEnv(env, "PLUGIN_ROOT", pluginRoot);
+    setEnv(env, "PLUGIN_DATA", pluginData);
+    return { command, args, cwd, env };
+}
+function resolveCommand(command, pluginRoot) {
+    if (command.startsWith("./"))
+        return resolve(pluginRoot, command);
+    return command;
+}
+export function resolveContainedCwd(cwd, pluginRoot, pluginData) {
+    const expanded = expandPluginPlaceholders(cwd, pluginRoot, pluginData);
+    const absolute = isAbsolute(expanded) ? expanded : resolve(pluginRoot, expanded);
+    const root = cwdTargetsData(cwd) ? pluginData : pluginRoot;
+    if (!isInside(root, absolute))
+        throw new Error(`Working directory escapes ${root}`);
+    return absolute;
+}
+function cwdTargetsData(cwd) {
+    return cwd === DATA_TOKEN || cwd.startsWith(`${DATA_TOKEN}/`);
+}
+function isInside(root, target) {
+    const rel = relative(root, target);
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+function setEnv(env, key, value) {
+    if (process.platform === "win32") {
+        const existing = Object.keys(env).find((name) => name.toLowerCase() === key.toLowerCase());
+        if (existing && existing !== key)
+            delete env[existing];
+    }
+    env[key] = value;
+}

package/dist/plugins/load.d.ts

@@ -0,0 +1,23 @@
+import type { McpServerManifest, SkillRecord } from "@nylorun/core/define";
+export declare const PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+export declare const MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+export interface PluginDiagnostic {
+    readonly severity: "info" | "warning";
+    readonly code: string;
+    readonly message: string;
+    readonly path?: string;
+}
+export declare class PluginError extends Error {
+    readonly code: string;
+    readonly diagnostics: readonly PluginDiagnostic[];
+    constructor(code: string, message: string, diagnostics?: readonly PluginDiagnostic[]);
+}
+export interface LoadedPlugin {
+    readonly root: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly skills: Readonly<Record<string, SkillRecord>>;
+    readonly mcpServers: Readonly<Record<string, McpServerManifest>>;
+    readonly diagnostics: readonly PluginDiagnostic[];
+}
+export declare function loadPlugin(directory: string): LoadedPlugin;