@ai-agent-forge/agent-forge 0.85.0

package/dist/plugins/mcp-http.js

@@ -0,0 +1,176 @@
+export function createMcpHttpTransport(options) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const retryLimit = options.retryLimit ?? 2;
+    const baseRetryMs = options.baseRetryMs ?? 100;
+    const maxRetryMs = options.maxRetryMs ?? 1_600;
+    const now = options.now ?? (() => Date.now());
+    const sleep = options.sleep ?? (() => undefined);
+    const events = [];
+    let nextId = 1;
+    let closed = false;
+    const record = (event) => {
+        events.push(event);
+        options.onEvent?.(event);
+    };
+    const postOnce = async (body, requestOptions) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), requestOptions?.timeoutMs ?? timeoutMs);
+        try {
+            const response = await fetch(options.url, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    accept: "application/json, text/event-stream",
+                    ...(options.headers ?? {}),
+                },
+                body,
+                signal: controller.signal,
+            });
+            const text = await response.text();
+            return { status: response.status, text };
+        }
+        catch (error) {
+            const reason = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+            return { status: "connect_error", reason };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    const postWithRetry = async (body, requestOptions) => {
+        for (let attempt = 1;; attempt += 1) {
+            const response = await postOnce(body, requestOptions);
+            if (response.status !== "connect_error" && response.status < 500 && response.status !== 429) {
+                record({ kind: "response", at: now(), detail: `HTTP ${response.status}`, attempt });
+                return response;
+            }
+            const reason = response.status === "connect_error" ? response.reason : `HTTP ${response.status}`;
+            if (attempt > retryLimit) {
+                record({
+                    kind: "transport_error",
+                    at: now(),
+                    detail: `giving up after ${attempt - 1} retries: ${reason}`,
+                    attempt,
+                });
+                throw new Error(`MCP HTTP transport error: ${reason}`);
+            }
+            const waitedMs = Math.min(baseRetryMs * 2 ** (attempt - 1), maxRetryMs);
+            record({
+                kind: "retry",
+                at: now(),
+                detail: `attempt ${attempt} failed (${reason}); waiting ${waitedMs}ms`,
+                attempt,
+            });
+            await sleep(waitedMs);
+            if (attempt === 1 && response.status === "connect_error") {
+                record({ kind: "reconnect", at: now(), detail: "re-establishing HTTP connection", attempt });
+            }
+        }
+    };
+    const rpc = async (method, params, requestOptions) => {
+        if (closed)
+            throw new Error("MCP HTTP transport is closed");
+        const id = nextId;
+        nextId += 1;
+        const body = JSON.stringify({ jsonrpc: "2.0", id, method, ...(params === undefined ? {} : { params }) });
+        const response = await postWithRetry(body, requestOptions);
+        if (response.status !== 200) {
+            throw new Error(`MCP HTTP transport returned HTTP ${response.status}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(response.text);
+        }
+        catch (error) {
+            throw new Error(
+            // v8 ignore next -- JSON.parse 只会抛出 Error 对象
+            `MCP HTTP transport returned non-JSON body: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (parsed.error !== undefined) {
+            throw new Error(`MCP error ${parsed.error.code ?? ""}: ${parsed.error.message ?? "unknown error"}`);
+        }
+        return parsed.result;
+    };
+    return {
+        async request(method, params, requestOptions) {
+            return rpc(method, params, requestOptions);
+        },
+        async notify(method, params) {
+            await postWithRetry(JSON.stringify({ jsonrpc: "2.0", method, ...(params === undefined ? {} : { params }) }), undefined);
+        },
+        async close() {
+            closed = true;
+        },
+        events() {
+            return Object.freeze([...events]);
+        },
+    };
+}
+function normalizeToolResult(result) {
+    if (result && typeof result === "object" && Array.isArray(result.content)) {
+        const { content, details } = result;
+        return { content, details };
+    }
+    if (result === undefined)
+        return { content: [{ type: "text", text: "" }] };
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+}
+/**
+ * Configuration-driven entry for remote MCP servers: wires
+ * createMcpHttpTransport into the same plugin shape as the generated stdio
+ * bridge (initialize/tools/list handshake, one registerTool per remote tool,
+ * dual call convention). Tool call policy stays host-owned; the plugin only
+ * forwards requests and maps results. The suite MCP registration pool
+ * materializes url-configured servers through this entry; optional `headers`
+ * are forwarded verbatim to the transport (credential note there).
+ */
+export function createMcpHttpServerPlugin(config) {
+    return async (api) => {
+        const transport = createMcpHttpTransport({ url: config.url, headers: config.headers });
+        try {
+            await transport.request("initialize", {
+                protocolVersion: "2024-11-05",
+                capabilities: {},
+                clientInfo: { name: "agent-forge-mcp-pool", version: "0.1.0" },
+            });
+            await transport.notify("notifications/initialized");
+            const listing = (await transport.request("tools/list"));
+            if (!listing || !Array.isArray(listing.tools)) {
+                throw new Error("MCP tools/list result must contain tools[]");
+            }
+            for (const tool of listing.tools) {
+                const candidate = tool;
+                if (!candidate || typeof candidate.name !== "string" || !candidate.name) {
+                    throw new Error("MCP tool requires a non-empty name");
+                }
+                api.registerTool({
+                    name: candidate.name,
+                    label: candidate.name,
+                    description: typeof candidate.description === "string" ? candidate.description : `MCP tool: ${candidate.name}`,
+                    parameters: candidate.inputSchema && typeof candidate.inputSchema === "object"
+                        ? candidate.inputSchema
+                        : { type: "object", properties: {} },
+                    execute: async (toolCallId, params, signal) => {
+                        // Dual call convention: the session passes (toolCallId, params,
+                        // signal); the runtime's invokeTool passes the input as the
+                        // single first argument.
+                        const singleArgCall = params === undefined && typeof toolCallId !== "string";
+                        const input = singleArgCall ? toolCallId : params;
+                        const result = await transport.request("tools/call", { name: candidate.name, arguments: input || {} }, singleArgCall ? undefined : { signal });
+                        return normalizeToolResult(result);
+                    },
+                });
+            }
+            return {
+                dispose() {
+                    transport.close();
+                },
+            };
+        }
+        catch (error) {
+            transport.close();
+            throw error;
+        }
+    };
+}
+//# sourceMappingURL=mcp-http.js.map

package/dist/plugins/mcp-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-http.js","sourceRoot":"","sources":["../../src/plugins/mcp-http.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * MCP HTTP transport (4.3) — a streamable-HTTP MCP transport implementing the\n * same transport interface as the stdio plugin, plus observable retry.\n *\n * Retries apply ONLY to requests the server could not have started (connect\n * errors, 5xx, 429) — a completed response (any JSON-RPC reply) is never\n * re-sent, keeping calls idempotent from the caller's perspective. Every\n * transport error, retry attempt, and reconnect is reported through the\n * `onEvent` callback so callers can observe what happened. CLI\n * productization is out of scope.\n */\n/**\n * Per-request options for MCP transports. Defined here rather than imported\n * from the mcp-stdio example so production src never depends on examples/\n * (统一修复轮 C reverse-dependency fix); structurally identical to the\n * example's own declaration, which stays self-contained.\n */\nexport interface McpRequestOptions {\n\tsignal?: AbortSignal;\n\ttimeoutMs?: number;\n}\n\nexport interface McpHttpTransportEventV1 {\n\treadonly kind: \"connect\" | \"transport_error\" | \"retry\" | \"reconnect\" | \"response\";\n\treadonly at: number;\n\treadonly detail: string;\n\treadonly attempt?: number;\n}\n\nexport interface McpHttpTransportOptionsV1 {\n\treadonly url: string;\n\treadonly timeoutMs?: number;\n\treadonly retryLimit?: number;\n\treadonly baseRetryMs?: number;\n\treadonly maxRetryMs?: number;\n\treadonly now?: () => number;\n\treadonly sleep?: (ms: number) => Promise<void> | void;\n\treadonly onEvent?: (event: McpHttpTransportEventV1) => void;\n\t/**\n\t * Extra request headers merged after the transport defaults on every\n\t * outbound request (initialize / notifications/initialized / tools/list /\n\t * tools/call), so user values can override the defaults — the\n\t * `Authorization: Bearer ...` case for hosted remote MCP servers. Values\n\t * are sent verbatim (never case-normalized). They may carry credentials:\n\t * the suite MCP pool materializes them into the generated plugin entry\n\t * below `<agentDir>/mcp/pool/`, which sits inside the same local-machine\n\t * data boundary as `auth.json` (docs/design/产品价值度量与数据边界登记.md\n\t * §2.1 本机数据).\n\t */\n\treadonly headers?: Readonly<Record<string, string>>;\n}\n\n/** Structurally compatible with the stdio plugin's transport interface. */\nexport interface McpHttpTransportV1 {\n\trequest(method: string, params?: unknown, options?: McpRequestOptions): Promise<unknown>;\n\tnotify(method: string, params?: unknown): Promise<void> | void;\n\tclose(): Promise<void> | void;\n\tevents(): readonly McpHttpTransportEventV1[];\n}\n\ninterface JsonRpcResponse {\n\tid?: number | string | null;\n\tresult?: unknown;\n\terror?: { code?: number; message?: string };\n}\n\nexport function createMcpHttpTransport(options: McpHttpTransportOptionsV1): McpHttpTransportV1 {\n\tconst timeoutMs = options.timeoutMs ?? 10_000;\n\tconst retryLimit = options.retryLimit ?? 2;\n\tconst baseRetryMs = options.baseRetryMs ?? 100;\n\tconst maxRetryMs = options.maxRetryMs ?? 1_600;\n\tconst now = options.now ?? (() => Date.now());\n\tconst sleep = options.sleep ?? (() => undefined);\n\tconst events: McpHttpTransportEventV1[] = [];\n\tlet nextId = 1;\n\tlet closed = false;\n\n\tconst record = (event: McpHttpTransportEventV1): void => {\n\t\tevents.push(event);\n\t\toptions.onEvent?.(event);\n\t};\n\n\tconst postOnce = async (\n\t\tbody: string,\n\t\trequestOptions: McpRequestOptions | undefined,\n\t): Promise<{ status: number; text: string } | { status: \"connect_error\"; reason: string }> => {\n\t\tconst controller = new AbortController();\n\t\tconst timer = setTimeout(() => controller.abort(), requestOptions?.timeoutMs ?? timeoutMs);\n\t\ttry {\n\t\t\tconst response = await fetch(options.url, {\n\t\t\t\tmethod: \"POST\",\n\t\t\t\theaders: {\n\t\t\t\t\t\"content-type\": \"application/json\",\n\t\t\t\t\taccept: \"application/json, text/event-stream\",\n\t\t\t\t\t...(options.headers ?? {}),\n\t\t\t\t},\n\t\t\t\tbody,\n\t\t\t\tsignal: controller.signal,\n\t\t\t});\n\t\t\tconst text = await response.text();\n\t\t\treturn { status: response.status, text };\n\t\t} catch (error) {\n\t\t\tconst reason = error instanceof Error ? `${error.name}: ${error.message}` : String(error);\n\t\t\treturn { status: \"connect_error\", reason };\n\t\t} finally {\n\t\t\tclearTimeout(timer);\n\t\t}\n\t};\n\n\tconst postWithRetry = async (\n\t\tbody: string,\n\t\trequestOptions?: McpRequestOptions,\n\t): Promise<{ status: number; text: string }> => {\n\t\tfor (let attempt = 1; ; attempt += 1) {\n\t\t\tconst response = await postOnce(body, requestOptions);\n\t\t\tif (response.status !== \"connect_error\" && response.status < 500 && response.status !== 429) {\n\t\t\t\trecord({ kind: \"response\", at: now(), detail: `HTTP ${response.status}`, attempt });\n\t\t\t\treturn response;\n\t\t\t}\n\t\t\tconst reason = response.status === \"connect_error\" ? response.reason : `HTTP ${response.status}`;\n\t\t\tif (attempt > retryLimit) {\n\t\t\t\trecord({\n\t\t\t\t\tkind: \"transport_error\",\n\t\t\t\t\tat: now(),\n\t\t\t\t\tdetail: `giving up after ${attempt - 1} retries: ${reason}`,\n\t\t\t\t\tattempt,\n\t\t\t\t});\n\t\t\t\tthrow new Error(`MCP HTTP transport error: ${reason}`);\n\t\t\t}\n\t\t\tconst waitedMs = Math.min(baseRetryMs * 2 ** (attempt - 1), maxRetryMs);\n\t\t\trecord({\n\t\t\t\tkind: \"retry\",\n\t\t\t\tat: now(),\n\t\t\t\tdetail: `attempt ${attempt} failed (${reason}); waiting ${waitedMs}ms`,\n\t\t\t\tattempt,\n\t\t\t});\n\t\t\tawait sleep(waitedMs);\n\t\t\tif (attempt === 1 && response.status === \"connect_error\") {\n\t\t\t\trecord({ kind: \"reconnect\", at: now(), detail: \"re-establishing HTTP connection\", attempt });\n\t\t\t}\n\t\t}\n\t};\n\n\tconst rpc = async (method: string, params?: unknown, requestOptions?: McpRequestOptions): Promise<unknown> => {\n\t\tif (closed) throw new Error(\"MCP HTTP transport is closed\");\n\t\tconst id = nextId;\n\t\tnextId += 1;\n\t\tconst body = JSON.stringify({ jsonrpc: \"2.0\", id, method, ...(params === undefined ? {} : { params }) });\n\t\tconst response = await postWithRetry(body, requestOptions);\n\t\tif (response.status !== 200) {\n\t\t\tthrow new Error(`MCP HTTP transport returned HTTP ${response.status}`);\n\t\t}\n\t\tlet parsed: JsonRpcResponse;\n\t\ttry {\n\t\t\tparsed = JSON.parse(response.text) as JsonRpcResponse;\n\t\t} catch (error) {\n\t\t\tthrow new Error(\n\t\t\t\t// v8 ignore next -- JSON.parse 只会抛出 Error 对象\n\t\t\t\t`MCP HTTP transport returned non-JSON body: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t);\n\t\t}\n\t\tif (parsed.error !== undefined) {\n\t\t\tthrow new Error(`MCP error ${parsed.error.code ?? \"\"}: ${parsed.error.message ?? \"unknown error\"}`);\n\t\t}\n\t\treturn parsed.result;\n\t};\n\n\treturn {\n\t\tasync request(method, params, requestOptions) {\n\t\t\treturn rpc(method, params, requestOptions);\n\t\t},\n\t\tasync notify(method, params) {\n\t\t\tawait postWithRetry(\n\t\t\t\tJSON.stringify({ jsonrpc: \"2.0\", method, ...(params === undefined ? {} : { params }) }),\n\t\t\t\tundefined,\n\t\t\t);\n\t\t},\n\t\tasync close() {\n\t\t\tclosed = true;\n\t\t},\n\t\tevents() {\n\t\t\treturn Object.freeze([...events]);\n\t\t},\n\t};\n}\n\n/** Minimal api surface the HTTP server plugin relies on (capability registerTool). */\nexport interface McpHttpServerPluginApiV1 {\n\tregisterTool(definition: unknown): unknown;\n}\n\nfunction normalizeToolResult(result: unknown): { content: unknown[]; details?: unknown } {\n\tif (result && typeof result === \"object\" && Array.isArray((result as { content?: unknown }).content)) {\n\t\tconst { content, details } = result as { content: unknown[]; details?: unknown };\n\t\treturn { content, details };\n\t}\n\tif (result === undefined) return { content: [{ type: \"text\", text: \"\" }] };\n\treturn { content: [{ type: \"text\", text: JSON.stringify(result) }] };\n}\n\n/**\n * Configuration-driven entry for remote MCP servers: wires\n * createMcpHttpTransport into the same plugin shape as the generated stdio\n * bridge (initialize/tools/list handshake, one registerTool per remote tool,\n * dual call convention). Tool call policy stays host-owned; the plugin only\n * forwards requests and maps results. The suite MCP registration pool\n * materializes url-configured servers through this entry; optional `headers`\n * are forwarded verbatim to the transport (credential note there).\n */\nexport function createMcpHttpServerPlugin(config: {\n\turl: string;\n\t/** Forwarded to the transport verbatim; see McpHttpTransportOptionsV1.headers for the credential note. */\n\theaders?: Readonly<Record<string, string>>;\n}): (api: McpHttpServerPluginApiV1) => Promise<{ dispose(): void }> {\n\treturn async (api) => {\n\t\tconst transport = createMcpHttpTransport({ url: config.url, headers: config.headers });\n\t\ttry {\n\t\t\tawait transport.request(\"initialize\", {\n\t\t\t\tprotocolVersion: \"2024-11-05\",\n\t\t\t\tcapabilities: {},\n\t\t\t\tclientInfo: { name: \"agent-forge-mcp-pool\", version: \"0.1.0\" },\n\t\t\t});\n\t\t\tawait transport.notify(\"notifications/initialized\");\n\t\t\tconst listing = (await transport.request(\"tools/list\")) as { tools?: unknown };\n\t\t\tif (!listing || !Array.isArray(listing.tools)) {\n\t\t\t\tthrow new Error(\"MCP tools/list result must contain tools[]\");\n\t\t\t}\n\t\t\tfor (const tool of listing.tools) {\n\t\t\t\tconst candidate = tool as { name?: unknown; description?: unknown; inputSchema?: unknown };\n\t\t\t\tif (!candidate || typeof candidate.name !== \"string\" || !candidate.name) {\n\t\t\t\t\tthrow new Error(\"MCP tool requires a non-empty name\");\n\t\t\t\t}\n\t\t\t\tapi.registerTool({\n\t\t\t\t\tname: candidate.name,\n\t\t\t\t\tlabel: candidate.name,\n\t\t\t\t\tdescription:\n\t\t\t\t\t\ttypeof candidate.description === \"string\" ? candidate.description : `MCP tool: ${candidate.name}`,\n\t\t\t\t\tparameters:\n\t\t\t\t\t\tcandidate.inputSchema && typeof candidate.inputSchema === \"object\"\n\t\t\t\t\t\t\t? candidate.inputSchema\n\t\t\t\t\t\t\t: { type: \"object\", properties: {} },\n\t\t\t\t\texecute: async (toolCallId: string, params: unknown, signal?: AbortSignal) => {\n\t\t\t\t\t\t// Dual call convention: the session passes (toolCallId, params,\n\t\t\t\t\t\t// signal); the runtime's invokeTool passes the input as the\n\t\t\t\t\t\t// single first argument.\n\t\t\t\t\t\tconst singleArgCall = params === undefined && typeof toolCallId !== \"string\";\n\t\t\t\t\t\tconst input = singleArgCall ? toolCallId : params;\n\t\t\t\t\t\tconst result = await transport.request(\n\t\t\t\t\t\t\t\"tools/call\",\n\t\t\t\t\t\t\t{ name: candidate.name as string, arguments: input || {} },\n\t\t\t\t\t\t\tsingleArgCall ? undefined : { signal },\n\t\t\t\t\t\t);\n\t\t\t\t\t\treturn normalizeToolResult(result);\n\t\t\t\t\t},\n\t\t\t\t});\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tdispose() {\n\t\t\t\t\ttransport.close();\n\t\t\t\t},\n\t\t\t};\n\t\t} catch (error) {\n\t\t\ttransport.close();\n\t\t\tthrow error;\n\t\t}\n\t};\n}\n"]}

package/dist/plugins/observability-types.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Backward-compatibility shim: the first-party observability plugin's public
+ * contracts moved to `@agent-forge/plugin-sdk` (D-075 S4 second batch; the
+ * plugin implementation itself moved to `plugins/observability`). This module
+ * re-exports the SDK surface so existing intra-host imports and the host's
+ * public exports keep resolving unchanged.
+ */
+export { type HostOutputSurfaceV1, type MetricsCancelLatencySampledV1, type MetricsMemoryRecallSampledV1, type MetricsNotSampledV1, type MetricsSnapshotV1, type MetricsTokensSampledV1, type MetricsToolErrorsV1, type MetricsTurnsV1, type MetricsWindowV1, type ObservabilityExportSinkV1, type ObservabilityHostAdapterV1, type ObservabilityJournalEntryV1, type ObservabilityJournalStatsV1, type ObservabilityLogLevel, type ObservabilityMetricsOptions, type ObservabilityPlugin, type ObservabilityPluginFacadeV1, type ObservabilityProblemReportCountsV1, type ObservabilityProblemReportErrorV1, type ObservabilityProblemReportSessionV1, type ObservabilityProblemReportTailEntryV1, type ObservabilityQueryFilterV1, type ObservabilityTraceStepV1, type ObservabilityTraceTimelineV1, type OtlpExportOptionsV1, type ProblemReportV1, TRACE_KINDS_V1, type TraceKindV1, type TraceRecordV1, type TraceSinkOptionsV1, } from "@agent-forge/plugin-sdk";
+//# sourceMappingURL=observability-types.d.ts.map

package/dist/plugins/observability-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability-types.d.ts","sourceRoot":"","sources":["../../src/plugins/observability-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACN,KAAK,mBAAmB,EACxB,KAAK,6BAA6B,EAClC,KAAK,4BAA4B,EACjC,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,EAChC,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,mBAAmB,EACxB,KAAK,2BAA2B,EAChC,KAAK,kCAAkC,EACvC,KAAK,iCAAiC,EACtC,KAAK,mCAAmC,EACxC,KAAK,qCAAqC,EAC1C,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAC7B,KAAK,4BAA4B,EACjC,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,kBAAkB,GACvB,MAAM,yBAAyB,CAAC","sourcesContent":["/**\n * Backward-compatibility shim: the first-party observability plugin's public\n * contracts moved to `@agent-forge/plugin-sdk` (D-075 S4 second batch; the\n * plugin implementation itself moved to `plugins/observability`). This module\n * re-exports the SDK surface so existing intra-host imports and the host's\n * public exports keep resolving unchanged.\n */\n\nexport {\n\ttype HostOutputSurfaceV1,\n\ttype MetricsCancelLatencySampledV1,\n\ttype MetricsMemoryRecallSampledV1,\n\ttype MetricsNotSampledV1,\n\ttype MetricsSnapshotV1,\n\ttype MetricsTokensSampledV1,\n\ttype MetricsToolErrorsV1,\n\ttype MetricsTurnsV1,\n\ttype MetricsWindowV1,\n\ttype ObservabilityExportSinkV1,\n\ttype ObservabilityHostAdapterV1,\n\ttype ObservabilityJournalEntryV1,\n\ttype ObservabilityJournalStatsV1,\n\ttype ObservabilityLogLevel,\n\ttype ObservabilityMetricsOptions,\n\ttype ObservabilityPlugin,\n\ttype ObservabilityPluginFacadeV1,\n\ttype ObservabilityProblemReportCountsV1,\n\ttype ObservabilityProblemReportErrorV1,\n\ttype ObservabilityProblemReportSessionV1,\n\ttype ObservabilityProblemReportTailEntryV1,\n\ttype ObservabilityQueryFilterV1,\n\ttype ObservabilityTraceStepV1,\n\ttype ObservabilityTraceTimelineV1,\n\ttype OtlpExportOptionsV1,\n\ttype ProblemReportV1,\n\tTRACE_KINDS_V1,\n\ttype TraceKindV1,\n\ttype TraceRecordV1,\n\ttype TraceSinkOptionsV1,\n} from \"@agent-forge/plugin-sdk\";\n"]}

package/dist/plugins/observability-types.js

@@ -0,0 +1,9 @@
+/**
+ * Backward-compatibility shim: the first-party observability plugin's public
+ * contracts moved to `@agent-forge/plugin-sdk` (D-075 S4 second batch; the
+ * plugin implementation itself moved to `plugins/observability`). This module
+ * re-exports the SDK surface so existing intra-host imports and the host's
+ * public exports keep resolving unchanged.
+ */
+export { TRACE_KINDS_V1, } from "@agent-forge/plugin-sdk";
+//# sourceMappingURL=observability-types.js.map

package/dist/plugins/observability-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability-types.js","sourceRoot":"","sources":["../../src/plugins/observability-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EA2BN,cAAc,GAId,MAAM,yBAAyB,CAAC","sourcesContent":["/**\n * Backward-compatibility shim: the first-party observability plugin's public\n * contracts moved to `@agent-forge/plugin-sdk` (D-075 S4 second batch; the\n * plugin implementation itself moved to `plugins/observability`). This module\n * re-exports the SDK surface so existing intra-host imports and the host's\n * public exports keep resolving unchanged.\n */\n\nexport {\n\ttype HostOutputSurfaceV1,\n\ttype MetricsCancelLatencySampledV1,\n\ttype MetricsMemoryRecallSampledV1,\n\ttype MetricsNotSampledV1,\n\ttype MetricsSnapshotV1,\n\ttype MetricsTokensSampledV1,\n\ttype MetricsToolErrorsV1,\n\ttype MetricsTurnsV1,\n\ttype MetricsWindowV1,\n\ttype ObservabilityExportSinkV1,\n\ttype ObservabilityHostAdapterV1,\n\ttype ObservabilityJournalEntryV1,\n\ttype ObservabilityJournalStatsV1,\n\ttype ObservabilityLogLevel,\n\ttype ObservabilityMetricsOptions,\n\ttype ObservabilityPlugin,\n\ttype ObservabilityPluginFacadeV1,\n\ttype ObservabilityProblemReportCountsV1,\n\ttype ObservabilityProblemReportErrorV1,\n\ttype ObservabilityProblemReportSessionV1,\n\ttype ObservabilityProblemReportTailEntryV1,\n\ttype ObservabilityQueryFilterV1,\n\ttype ObservabilityTraceStepV1,\n\ttype ObservabilityTraceTimelineV1,\n\ttype OtlpExportOptionsV1,\n\ttype ProblemReportV1,\n\tTRACE_KINDS_V1,\n\ttype TraceKindV1,\n\ttype TraceRecordV1,\n\ttype TraceSinkOptionsV1,\n} from \"@agent-forge/plugin-sdk\";\n"]}

package/dist/plugins/plugin-host.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Plugin host lifecycle (7.1) — an independent host that owns plugin
+ * start/stop/dispose ordering, resource boundaries, and error aggregation.
+ *
+ * Start runs plugins in registration order; a failing plugin is aggregated
+ * (the host continues with the rest) and the host reports
+ * started/partial/failed explicitly. Dispose runs in REVERSE order, marks
+ * every plugin, releases declared resources, and aggregates disposal errors
+ * — a plugin that throws on dispose cannot silently skip the others, and
+ * the host flags any resource (timer, handle, file) its owner did not
+ * release. Kernel-side safety policy is never added here (7.1 excludes it).
+ * Supervisor, heartbeat, restart, and backpressure are 7.2.
+ */
+export interface PluginHostResourceV1 {
+    readonly name: string;
+    release(): void | Promise<void>;
+}
+export interface HostedPluginV1 {
+    readonly pluginId: string;
+    start?: () => void | Promise<void>;
+    dispose?: () => void | Promise<void>;
+    /** Declares resources this plugin owns; the host checks their release. */
+    resources?: () => readonly PluginHostResourceV1[];
+}
+export type PluginHostStateV1 = "created" | "started" | "partial" | "failed" | "disposed";
+export interface PluginHostErrorV1 {
+    readonly pluginId: string;
+    readonly phase: "start" | "dispose";
+    readonly message: string;
+}
+export interface PluginHostV1 {
+    start(): Promise<{
+        readonly state: "started" | "partial" | "failed";
+        readonly errors: readonly PluginHostErrorV1[];
+    }>;
+    dispose(): Promise<{
+        readonly errors: readonly PluginHostErrorV1[];
+        readonly leakedResources: readonly string[];
+    }>;
+    readonly state: PluginHostStateV1;
+    readonly errors: readonly PluginHostErrorV1[];
+}
+export declare function createPluginHost(options: {
+    readonly plugins: readonly HostedPluginV1[];
+}): PluginHostV1;
+//# sourceMappingURL=plugin-host.d.ts.map

package/dist/plugins/plugin-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-host.d.ts","sourceRoot":"","sources":["../../src/plugins/plugin-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,OAAO,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,SAAS,oBAAoB,EAAE,CAAC;CAClD;AAED,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE1F,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC5B,KAAK,IAAI,OAAO,CAAC;QAChB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;QACjD,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;KAC9C,CAAC,CAAC;IACH,OAAO,IAAI,OAAO,CAAC;QAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;QAAC,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACnH,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC9C;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAA;CAAE,GAAG,YAAY,CAwEvG","sourcesContent":["/**\n * Plugin host lifecycle (7.1) — an independent host that owns plugin\n * start/stop/dispose ordering, resource boundaries, and error aggregation.\n *\n * Start runs plugins in registration order; a failing plugin is aggregated\n * (the host continues with the rest) and the host reports\n * started/partial/failed explicitly. Dispose runs in REVERSE order, marks\n * every plugin, releases declared resources, and aggregates disposal errors\n * — a plugin that throws on dispose cannot silently skip the others, and\n * the host flags any resource (timer, handle, file) its owner did not\n * release. Kernel-side safety policy is never added here (7.1 excludes it).\n * Supervisor, heartbeat, restart, and backpressure are 7.2.\n */\nexport interface PluginHostResourceV1 {\n\treadonly name: string;\n\trelease(): void | Promise<void>;\n}\n\nexport interface HostedPluginV1 {\n\treadonly pluginId: string;\n\tstart?: () => void | Promise<void>;\n\tdispose?: () => void | Promise<void>;\n\t/** Declares resources this plugin owns; the host checks their release. */\n\tresources?: () => readonly PluginHostResourceV1[];\n}\n\nexport type PluginHostStateV1 = \"created\" | \"started\" | \"partial\" | \"failed\" | \"disposed\";\n\nexport interface PluginHostErrorV1 {\n\treadonly pluginId: string;\n\treadonly phase: \"start\" | \"dispose\";\n\treadonly message: string;\n}\n\nexport interface PluginHostV1 {\n\tstart(): Promise<{\n\t\treadonly state: \"started\" | \"partial\" | \"failed\";\n\t\treadonly errors: readonly PluginHostErrorV1[];\n\t}>;\n\tdispose(): Promise<{ readonly errors: readonly PluginHostErrorV1[]; readonly leakedResources: readonly string[] }>;\n\treadonly state: PluginHostStateV1;\n\treadonly errors: readonly PluginHostErrorV1[];\n}\n\nexport function createPluginHost(options: { readonly plugins: readonly HostedPluginV1[] }): PluginHostV1 {\n\tconst plugins = [...options.plugins];\n\tconst errors: PluginHostErrorV1[] = [];\n\t// Wrapped in an object: cross-closure writes to a `let` trip tsgo's\n\t// control-flow narrowing here (tsc accepts it; tsgo does not).\n\tconst stateRef: { current: PluginHostStateV1 } = { current: \"created\" };\n\n\tconst messageOf = (error: unknown): string => (error instanceof Error ? error.message : String(error));\n\n\treturn {\n\t\tget state() {\n\t\t\treturn stateRef.current;\n\t\t},\n\t\tget errors() {\n\t\t\treturn Object.freeze([...errors]);\n\t\t},\n\t\tasync start() {\n\t\t\tlet failures = 0;\n\t\t\tfor (const plugin of plugins) {\n\t\t\t\tif (!plugin.start) continue;\n\t\t\t\ttry {\n\t\t\t\t\tawait plugin.start();\n\t\t\t\t} catch (error) {\n\t\t\t\t\tfailures += 1;\n\t\t\t\t\terrors.push({ pluginId: plugin.pluginId, phase: \"start\", message: messageOf(error) });\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (failures === 0) {\n\t\t\t\tstateRef.current = \"started\";\n\t\t\t\treturn { state: \"started\", errors: Object.freeze([...errors]) };\n\t\t\t} else if (failures === plugins.length) {\n\t\t\t\tstateRef.current = \"failed\";\n\t\t\t\treturn { state: \"failed\", errors: Object.freeze([...errors]) };\n\t\t\t} else {\n\t\t\t\tstateRef.current = \"partial\";\n\t\t\t\treturn { state: \"partial\", errors: Object.freeze([...errors]) };\n\t\t\t}\n\t\t},\n\t\tasync dispose() {\n\t\t\tif (stateRef.current === \"disposed\") {\n\t\t\t\treturn { errors: Object.freeze([...errors]), leakedResources: Object.freeze([]) };\n\t\t\t}\n\t\t\tfor (const plugin of [...plugins].reverse()) {\n\t\t\t\tif (!plugin.dispose) continue;\n\t\t\t\ttry {\n\t\t\t\t\tawait plugin.dispose();\n\t\t\t\t} catch (error) {\n\t\t\t\t\terrors.push({ pluginId: plugin.pluginId, phase: \"dispose\", message: messageOf(error) });\n\t\t\t\t}\n\t\t\t}\n\t\t\t// Resources still declared at this point were NOT released by their\n\t\t\t// owner plugin; the host force-releases them and reports them as leaked.\n\t\t\tconst leaked: string[] = [];\n\t\t\tfor (const plugin of plugins) {\n\t\t\t\tif (!plugin.resources) continue;\n\t\t\t\tfor (const resource of plugin.resources()) {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tawait resource.release();\n\t\t\t\t\t} catch (error) {\n\t\t\t\t\t\terrors.push({\n\t\t\t\t\t\t\tpluginId: plugin.pluginId,\n\t\t\t\t\t\t\tphase: \"dispose\",\n\t\t\t\t\t\t\tmessage: `resource ${resource.name}: ${messageOf(error)}`,\n\t\t\t\t\t\t});\n\t\t\t\t\t}\n\t\t\t\t\tleaked.push(`${plugin.pluginId}/${resource.name}`);\n\t\t\t\t}\n\t\t\t}\n\t\t\tstateRef.current = \"disposed\";\n\t\t\treturn { errors: Object.freeze([...errors]), leakedResources: Object.freeze(leaked) };\n\t\t},\n\t};\n}\n"]}

package/dist/plugins/plugin-host.js

@@ -0,0 +1,80 @@
+export function createPluginHost(options) {
+    const plugins = [...options.plugins];
+    const errors = [];
+    // Wrapped in an object: cross-closure writes to a `let` trip tsgo's
+    // control-flow narrowing here (tsc accepts it; tsgo does not).
+    const stateRef = { current: "created" };
+    const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+    return {
+        get state() {
+            return stateRef.current;
+        },
+        get errors() {
+            return Object.freeze([...errors]);
+        },
+        async start() {
+            let failures = 0;
+            for (const plugin of plugins) {
+                if (!plugin.start)
+                    continue;
+                try {
+                    await plugin.start();
+                }
+                catch (error) {
+                    failures += 1;
+                    errors.push({ pluginId: plugin.pluginId, phase: "start", message: messageOf(error) });
+                }
+            }
+            if (failures === 0) {
+                stateRef.current = "started";
+                return { state: "started", errors: Object.freeze([...errors]) };
+            }
+            else if (failures === plugins.length) {
+                stateRef.current = "failed";
+                return { state: "failed", errors: Object.freeze([...errors]) };
+            }
+            else {
+                stateRef.current = "partial";
+                return { state: "partial", errors: Object.freeze([...errors]) };
+            }
+        },
+        async dispose() {
+            if (stateRef.current === "disposed") {
+                return { errors: Object.freeze([...errors]), leakedResources: Object.freeze([]) };
+            }
+            for (const plugin of [...plugins].reverse()) {
+                if (!plugin.dispose)
+                    continue;
+                try {
+                    await plugin.dispose();
+                }
+                catch (error) {
+                    errors.push({ pluginId: plugin.pluginId, phase: "dispose", message: messageOf(error) });
+                }
+            }
+            // Resources still declared at this point were NOT released by their
+            // owner plugin; the host force-releases them and reports them as leaked.
+            const leaked = [];
+            for (const plugin of plugins) {
+                if (!plugin.resources)
+                    continue;
+                for (const resource of plugin.resources()) {
+                    try {
+                        await resource.release();
+                    }
+                    catch (error) {
+                        errors.push({
+                            pluginId: plugin.pluginId,
+                            phase: "dispose",
+                            message: `resource ${resource.name}: ${messageOf(error)}`,
+                        });
+                    }
+                    leaked.push(`${plugin.pluginId}/${resource.name}`);
+                }
+            }
+            stateRef.current = "disposed";
+            return { errors: Object.freeze([...errors]), leakedResources: Object.freeze(leaked) };
+        },
+    };
+}
+//# sourceMappingURL=plugin-host.js.map

package/dist/plugins/plugin-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-host.js","sourceRoot":"","sources":["../../src/plugins/plugin-host.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Plugin host lifecycle (7.1) — an independent host that owns plugin\n * start/stop/dispose ordering, resource boundaries, and error aggregation.\n *\n * Start runs plugins in registration order; a failing plugin is aggregated\n * (the host continues with the rest) and the host reports\n * started/partial/failed explicitly. Dispose runs in REVERSE order, marks\n * every plugin, releases declared resources, and aggregates disposal errors\n * — a plugin that throws on dispose cannot silently skip the others, and\n * the host flags any resource (timer, handle, file) its owner did not\n * release. Kernel-side safety policy is never added here (7.1 excludes it).\n * Supervisor, heartbeat, restart, and backpressure are 7.2.\n */\nexport interface PluginHostResourceV1 {\n\treadonly name: string;\n\trelease(): void | Promise<void>;\n}\n\nexport interface HostedPluginV1 {\n\treadonly pluginId: string;\n\tstart?: () => void | Promise<void>;\n\tdispose?: () => void | Promise<void>;\n\t/** Declares resources this plugin owns; the host checks their release. */\n\tresources?: () => readonly PluginHostResourceV1[];\n}\n\nexport type PluginHostStateV1 = \"created\" | \"started\" | \"partial\" | \"failed\" | \"disposed\";\n\nexport interface PluginHostErrorV1 {\n\treadonly pluginId: string;\n\treadonly phase: \"start\" | \"dispose\";\n\treadonly message: string;\n}\n\nexport interface PluginHostV1 {\n\tstart(): Promise<{\n\t\treadonly state: \"started\" | \"partial\" | \"failed\";\n\t\treadonly errors: readonly PluginHostErrorV1[];\n\t}>;\n\tdispose(): Promise<{ readonly errors: readonly PluginHostErrorV1[]; readonly leakedResources: readonly string[] }>;\n\treadonly state: PluginHostStateV1;\n\treadonly errors: readonly PluginHostErrorV1[];\n}\n\nexport function createPluginHost(options: { readonly plugins: readonly HostedPluginV1[] }): PluginHostV1 {\n\tconst plugins = [...options.plugins];\n\tconst errors: PluginHostErrorV1[] = [];\n\t// Wrapped in an object: cross-closure writes to a `let` trip tsgo's\n\t// control-flow narrowing here (tsc accepts it; tsgo does not).\n\tconst stateRef: { current: PluginHostStateV1 } = { current: \"created\" };\n\n\tconst messageOf = (error: unknown): string => (error instanceof Error ? error.message : String(error));\n\n\treturn {\n\t\tget state() {\n\t\t\treturn stateRef.current;\n\t\t},\n\t\tget errors() {\n\t\t\treturn Object.freeze([...errors]);\n\t\t},\n\t\tasync start() {\n\t\t\tlet failures = 0;\n\t\t\tfor (const plugin of plugins) {\n\t\t\t\tif (!plugin.start) continue;\n\t\t\t\ttry {\n\t\t\t\t\tawait plugin.start();\n\t\t\t\t} catch (error) {\n\t\t\t\t\tfailures += 1;\n\t\t\t\t\terrors.push({ pluginId: plugin.pluginId, phase: \"start\", message: messageOf(error) });\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (failures === 0) {\n\t\t\t\tstateRef.current = \"started\";\n\t\t\t\treturn { state: \"started\", errors: Object.freeze([...errors]) };\n\t\t\t} else if (failures === plugins.length) {\n\t\t\t\tstateRef.current = \"failed\";\n\t\t\t\treturn { state: \"failed\", errors: Object.freeze([...errors]) };\n\t\t\t} else {\n\t\t\t\tstateRef.current = \"partial\";\n\t\t\t\treturn { state: \"partial\", errors: Object.freeze([...errors]) };\n\t\t\t}\n\t\t},\n\t\tasync dispose() {\n\t\t\tif (stateRef.current === \"disposed\") {\n\t\t\t\treturn { errors: Object.freeze([...errors]), leakedResources: Object.freeze([]) };\n\t\t\t}\n\t\t\tfor (const plugin of [...plugins].reverse()) {\n\t\t\t\tif (!plugin.dispose) continue;\n\t\t\t\ttry {\n\t\t\t\t\tawait plugin.dispose();\n\t\t\t\t} catch (error) {\n\t\t\t\t\terrors.push({ pluginId: plugin.pluginId, phase: \"dispose\", message: messageOf(error) });\n\t\t\t\t}\n\t\t\t}\n\t\t\t// Resources still declared at this point were NOT released by their\n\t\t\t// owner plugin; the host force-releases them and reports them as leaked.\n\t\t\tconst leaked: string[] = [];\n\t\t\tfor (const plugin of plugins) {\n\t\t\t\tif (!plugin.resources) continue;\n\t\t\t\tfor (const resource of plugin.resources()) {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tawait resource.release();\n\t\t\t\t\t} catch (error) {\n\t\t\t\t\t\terrors.push({\n\t\t\t\t\t\t\tpluginId: plugin.pluginId,\n\t\t\t\t\t\t\tphase: \"dispose\",\n\t\t\t\t\t\t\tmessage: `resource ${resource.name}: ${messageOf(error)}`,\n\t\t\t\t\t\t});\n\t\t\t\t\t}\n\t\t\t\t\tleaked.push(`${plugin.pluginId}/${resource.name}`);\n\t\t\t\t}\n\t\t\t}\n\t\t\tstateRef.current = \"disposed\";\n\t\t\treturn { errors: Object.freeze([...errors]), leakedResources: Object.freeze(leaked) };\n\t\t},\n\t};\n}\n"]}

package/dist/plugins/plugin-supervisor.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Plugin supervisor (7.2) — heartbeat, restart, and backpressure over the
+ * 7.1 plugin host, all deterministic (clock and sleep are injected; there
+ * are no hidden timers).
+ *
+ * Heartbeat: every supervised plugin must report a beat before
+ * `heartbeatIntervalMs` elapses since its last beat, checked only by an
+ * explicit `tick()`. A missed beat marks the plugin unhealthy and triggers
+ * a restart policy (bounded attempts with exponential backoff). Restart:
+ * the supervisor re-invokes the plugin's start with the recorded attempt
+ * number; a plugin exceeding `restartLimit` ends in a terminal
+ * `exhausted` health. Backpressure: an internal event queue with a hard
+ * cap — enqueueing beyond the cap fails closed with `queue_full` instead of
+ * growing unbounded. Fault injection is trivially the caller's job: the
+ * tests simulate missed beats and crashes directly. Supply-chain signing is
+ * 7.3.
+ */
+import type { HostedPluginV1 } from "./plugin-host.ts";
+export interface SupervisorPolicyV1 {
+    readonly heartbeatIntervalMs: number;
+    readonly restartLimit: number;
+    readonly baseRestartMs: number;
+    readonly queueCap: number;
+}
+export type PluginHealthV1 = "healthy" | "unhealthy" | "exhausted" | "stopped";
+export interface SupervisorEntryV1 {
+    readonly pluginId: string;
+    readonly health: PluginHealthV1;
+    readonly restarts: number;
+    readonly lastBeatAt: number;
+    readonly nextRestartAllowedAt?: number;
+}
+export type SupervisorEventV1 = {
+    readonly kind: "beat";
+    readonly pluginId: string;
+    readonly at: number;
+} | {
+    readonly kind: "unhealthy";
+    readonly pluginId: string;
+    readonly at: number;
+} | {
+    readonly kind: "restart";
+    readonly pluginId: string;
+    readonly at: number;
+    readonly attempt: number;
+} | {
+    readonly kind: "exhausted";
+    readonly pluginId: string;
+    readonly at: number;
+    readonly attempts: number;
+} | {
+    readonly kind: "queue_full";
+    readonly at: number;
+};
+export interface PluginSupervisorV1 {
+    supervise(plugin: HostedPluginV1): void;
+    beat(pluginId: string): void;
+    tick(at: number): void;
+    restart(pluginId: string): {
+        readonly status: "restarted" | "exhausted" | "unknown";
+        readonly attempt?: number;
+    };
+    enqueue(event: string): {
+        readonly status: "enqueued" | "queue_full";
+        readonly size: number;
+    };
+    drain(): readonly string[];
+    health(): readonly SupervisorEntryV1[];
+    readonly queueSize: number;
+}
+export declare function createPluginSupervisor(options: {
+    readonly policy: SupervisorPolicyV1;
+    readonly plugins: readonly HostedPluginV1[];
+    readonly now?: () => number;
+    readonly restartPlugin?: (pluginId: string, attempt: number) => Promise<void> | void;
+}): PluginSupervisorV1;
+//# sourceMappingURL=plugin-supervisor.d.ts.map

package/dist/plugins/plugin-supervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-supervisor.d.ts","sourceRoot":"","sources":["../../src/plugins/plugin-supervisor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Plugin supervisor (7.2) — heartbeat, restart, and backpressure over the\n * 7.1 plugin host, all deterministic (clock and sleep are injected; there\n * are no hidden timers).\n *\n * Heartbeat: every supervised plugin must report a beat before\n * `heartbeatIntervalMs` elapses since its last beat, checked only by an\n * explicit `tick()`. A missed beat marks the plugin unhealthy and triggers\n * a restart policy (bounded attempts with exponential backoff). Restart:\n * the supervisor re-invokes the plugin's start with the recorded attempt\n * number; a plugin exceeding `restartLimit` ends in a terminal\n * `exhausted` health. Backpressure: an internal event queue with a hard\n * cap — enqueueing beyond the cap fails closed with `queue_full` instead of\n * growing unbounded. Fault injection is trivially the caller's job: the\n * tests simulate missed beats and crashes directly. Supply-chain signing is\n * 7.3.\n */\nimport type { HostedPluginV1 } from \"./plugin-host.ts\";\n\nexport interface SupervisorPolicyV1 {\n\treadonly heartbeatIntervalMs: number;\n\treadonly restartLimit: number;\n\treadonly baseRestartMs: number;\n\treadonly queueCap: number;\n}\n\nexport type PluginHealthV1 = \"healthy\" | \"unhealthy\" | \"exhausted\" | \"stopped\";\n\nexport interface SupervisorEntryV1 {\n\treadonly pluginId: string;\n\treadonly health: PluginHealthV1;\n\treadonly restarts: number;\n\treadonly lastBeatAt: number;\n\treadonly nextRestartAllowedAt?: number;\n}\n\nexport type SupervisorEventV1 =\n\t| { readonly kind: \"beat\"; readonly pluginId: string; readonly at: number }\n\t| { readonly kind: \"unhealthy\"; readonly pluginId: string; readonly at: number }\n\t| { readonly kind: \"restart\"; readonly pluginId: string; readonly at: number; readonly attempt: number }\n\t| { readonly kind: \"exhausted\"; readonly pluginId: string; readonly at: number; readonly attempts: number }\n\t| { readonly kind: \"queue_full\"; readonly at: number };\n\nexport interface PluginSupervisorV1 {\n\tsupervise(plugin: HostedPluginV1): void;\n\tbeat(pluginId: string): void;\n\ttick(at: number): void;\n\trestart(pluginId: string): { readonly status: \"restarted\" | \"exhausted\" | \"unknown\"; readonly attempt?: number };\n\tenqueue(event: string): { readonly status: \"enqueued\" | \"queue_full\"; readonly size: number };\n\tdrain(): readonly string[];\n\thealth(): readonly SupervisorEntryV1[];\n\treadonly queueSize: number;\n}\n\nexport function createPluginSupervisor(options: {\n\treadonly policy: SupervisorPolicyV1;\n\treadonly plugins: readonly HostedPluginV1[];\n\treadonly now?: () => number;\n\treadonly restartPlugin?: (pluginId: string, attempt: number) => Promise<void> | void;\n}): PluginSupervisorV1 {\n\tconst policy = options.policy;\n\tconst now = options.now ?? (() => 0);\n\n\tinterface Entry {\n\t\tpluginId: string;\n\t\thealth: PluginHealthV1;\n\t\trestarts: number;\n\t\tlastBeatAt: number;\n\t\tnextRestartAllowedAt?: number;\n\t}\n\tconst entries = new Map<string, Entry>();\n\tconst events: SupervisorEventV1[] = [];\n\tconst queue: string[] = [];\n\n\tfor (const plugin of options.plugins) {\n\t\tentries.set(plugin.pluginId, {\n\t\t\tpluginId: plugin.pluginId,\n\t\t\thealth: \"healthy\",\n\t\t\trestarts: 0,\n\t\t\tlastBeatAt: now(),\n\t\t});\n\t}\n\n\treturn {\n\t\tsupervise(plugin) {\n\t\t\tentries.set(plugin.pluginId, {\n\t\t\t\tpluginId: plugin.pluginId,\n\t\t\t\thealth: \"healthy\",\n\t\t\t\trestarts: 0,\n\t\t\t\tlastBeatAt: now(),\n\t\t\t});\n\t\t},\n\t\tbeat(pluginId) {\n\t\t\tconst entry = entries.get(pluginId);\n\t\t\tif (!entry) throw new Error(`Unknown supervised plugin: ${pluginId}`);\n\t\t\tentry.lastBeatAt = now();\n\t\t\tentry.health = \"healthy\";\n\t\t\tevents.push({ kind: \"beat\", pluginId, at: entry.lastBeatAt });\n\t\t},\n\t\ttick(at) {\n\t\t\tfor (const entry of entries.values()) {\n\t\t\t\tif (entry.health !== \"unhealthy\" && at - entry.lastBeatAt > policy.heartbeatIntervalMs) {\n\t\t\t\t\tentry.health = \"unhealthy\";\n\t\t\t\t\tevents.push({ kind: \"unhealthy\", pluginId: entry.pluginId, at });\n\t\t\t\t}\n\t\t\t}\n\t\t},\n\t\trestart(pluginId) {\n\t\t\tconst entry = entries.get(pluginId);\n\t\t\tif (!entry) return { status: \"unknown\" as const };\n\t\t\tif (entry.health === \"exhausted\") return { status: \"exhausted\" as const, attempts: entry.restarts };\n\t\t\tif (entry.nextRestartAllowedAt !== undefined && now() < entry.nextRestartAllowedAt) {\n\t\t\t\treturn { status: \"restarted\" as const, attempt: entry.restarts };\n\t\t\t}\n\t\t\tentry.restarts += 1;\n\t\t\tif (entry.restarts > policy.restartLimit) {\n\t\t\t\tentry.health = \"exhausted\";\n\t\t\t\tevents.push({ kind: \"exhausted\", pluginId, at: now(), attempts: entry.restarts - 1 });\n\t\t\t\treturn { status: \"exhausted\" as const, attempts: entry.restarts - 1 };\n\t\t\t}\n\t\t\tvoid options.restartPlugin?.(pluginId, entry.restarts);\n\t\t\tentry.health = \"healthy\";\n\t\t\tentry.lastBeatAt = now();\n\t\t\tconst backoff = Math.min(policy.baseRestartMs * 2 ** (entry.restarts - 1), Number.MAX_SAFE_INTEGER);\n\t\t\tentry.nextRestartAllowedAt = now() + backoff;\n\t\t\tevents.push({ kind: \"restart\", pluginId, at: now(), attempt: entry.restarts });\n\t\t\treturn { status: \"restarted\", attempt: entry.restarts };\n\t\t},\n\t\tenqueue(event) {\n\t\t\tif (queue.length >= policy.queueCap) {\n\t\t\t\tevents.push({ kind: \"queue_full\", at: now() });\n\t\t\t\treturn { status: \"queue_full\", size: queue.length };\n\t\t\t}\n\t\t\tqueue.push(event);\n\t\t\treturn { status: \"enqueued\", size: queue.length };\n\t\t},\n\t\tdrain() {\n\t\t\treturn Object.freeze(queue.splice(0, queue.length));\n\t\t},\n\t\thealth() {\n\t\t\treturn Object.freeze([...entries.values()].map((entry) => ({ ...entry })));\n\t\t},\n\t\tget queueSize() {\n\t\t\treturn queue.length;\n\t\t},\n\t};\n}\n"]}

package/dist/plugins/plugin-supervisor.js

@@ -0,0 +1,82 @@
+export function createPluginSupervisor(options) {
+    const policy = options.policy;
+    const now = options.now ?? (() => 0);
+    const entries = new Map();
+    const events = [];
+    const queue = [];
+    for (const plugin of options.plugins) {
+        entries.set(plugin.pluginId, {
+            pluginId: plugin.pluginId,
+            health: "healthy",
+            restarts: 0,
+            lastBeatAt: now(),
+        });
+    }
+    return {
+        supervise(plugin) {
+            entries.set(plugin.pluginId, {
+                pluginId: plugin.pluginId,
+                health: "healthy",
+                restarts: 0,
+                lastBeatAt: now(),
+            });
+        },
+        beat(pluginId) {
+            const entry = entries.get(pluginId);
+            if (!entry)
+                throw new Error(`Unknown supervised plugin: ${pluginId}`);
+            entry.lastBeatAt = now();
+            entry.health = "healthy";
+            events.push({ kind: "beat", pluginId, at: entry.lastBeatAt });
+        },
+        tick(at) {
+            for (const entry of entries.values()) {
+                if (entry.health !== "unhealthy" && at - entry.lastBeatAt > policy.heartbeatIntervalMs) {
+                    entry.health = "unhealthy";
+                    events.push({ kind: "unhealthy", pluginId: entry.pluginId, at });
+                }
+            }
+        },
+        restart(pluginId) {
+            const entry = entries.get(pluginId);
+            if (!entry)
+                return { status: "unknown" };
+            if (entry.health === "exhausted")
+                return { status: "exhausted", attempts: entry.restarts };
+            if (entry.nextRestartAllowedAt !== undefined && now() < entry.nextRestartAllowedAt) {
+                return { status: "restarted", attempt: entry.restarts };
+            }
+            entry.restarts += 1;
+            if (entry.restarts > policy.restartLimit) {
+                entry.health = "exhausted";
+                events.push({ kind: "exhausted", pluginId, at: now(), attempts: entry.restarts - 1 });
+                return { status: "exhausted", attempts: entry.restarts - 1 };
+            }
+            void options.restartPlugin?.(pluginId, entry.restarts);
+            entry.health = "healthy";
+            entry.lastBeatAt = now();
+            const backoff = Math.min(policy.baseRestartMs * 2 ** (entry.restarts - 1), Number.MAX_SAFE_INTEGER);
+            entry.nextRestartAllowedAt = now() + backoff;
+            events.push({ kind: "restart", pluginId, at: now(), attempt: entry.restarts });
+            return { status: "restarted", attempt: entry.restarts };
+        },
+        enqueue(event) {
+            if (queue.length >= policy.queueCap) {
+                events.push({ kind: "queue_full", at: now() });
+                return { status: "queue_full", size: queue.length };
+            }
+            queue.push(event);
+            return { status: "enqueued", size: queue.length };
+        },
+        drain() {
+            return Object.freeze(queue.splice(0, queue.length));
+        },
+        health() {
+            return Object.freeze([...entries.values()].map((entry) => ({ ...entry })));
+        },
+        get queueSize() {
+            return queue.length;
+        },
+    };
+}
+//# sourceMappingURL=plugin-supervisor.js.map

package/dist/plugins/plugin-supervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-supervisor.js","sourceRoot":"","sources":["../../src/plugins/plugin-supervisor.ts"],"names":[],"mappings":"AAsDA,MAAM,UAAU,sBAAsB,CAAC,OAKtC,EAAsB;IACtB,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC9B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IASrC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAiB,CAAC;IACzC,MAAM,MAAM,GAAwB,EAAE,CAAC;IACvC,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACtC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE;YAC5B,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,MAAM,EAAE,SAAS;YACjB,QAAQ,EAAE,CAAC;YACX,UAAU,EAAE,GAAG,EAAE;SACjB,CAAC,CAAC;IACJ,CAAC;IAED,OAAO;QACN,SAAS,CAAC,MAAM,EAAE;YACjB,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE;gBAC5B,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,MAAM,EAAE,SAAS;gBACjB,QAAQ,EAAE,CAAC;gBACX,UAAU,EAAE,GAAG,EAAE;aACjB,CAAC,CAAC;QAAA,CACH;QACD,IAAI,CAAC,QAAQ,EAAE;YACd,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACpC,IAAI,CAAC,KAAK;gBAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,QAAQ,EAAE,CAAC,CAAC;YACtE,KAAK,CAAC,UAAU,GAAG,GAAG,EAAE,CAAC;YACzB,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC;YACzB,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC;QAAA,CAC9D;QACD,IAAI,CAAC,EAAE,EAAE;YACR,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;gBACtC,IAAI,KAAK,CAAC,MAAM,KAAK,WAAW,IAAI,EAAE,GAAG,KAAK,CAAC,UAAU,GAAG,MAAM,CAAC,mBAAmB,EAAE,CAAC;oBACxF,KAAK,CAAC,MAAM,GAAG,WAAW,CAAC;oBAC3B,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;gBAClE,CAAC;YACF,CAAC;QAAA,CACD;QACD,OAAO,CAAC,QAAQ,EAAE;YACjB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACpC,IAAI,CAAC,KAAK;gBAAE,OAAO,EAAE,MAAM,EAAE,SAAkB,EAAE,CAAC;YAClD,IAAI,KAAK,CAAC,MAAM,KAAK,WAAW;gBAAE,OAAO,EAAE,MAAM,EAAE,WAAoB,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;YACpG,IAAI,KAAK,CAAC,oBAAoB,KAAK,SAAS,IAAI,GAAG,EAAE,GAAG,KAAK,CAAC,oBAAoB,EAAE,CAAC;gBACpF,OAAO,EAAE,MAAM,EAAE,WAAoB,EAAE,OAAO,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;YAClE,CAAC;YACD,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAC;YACpB,IAAI,KAAK,CAAC,QAAQ,GAAG,MAAM,CAAC,YAAY,EAAE,CAAC;gBAC1C,KAAK,CAAC,MAAM,GAAG,WAAW,CAAC;gBAC3B,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC,CAAC;gBACtF,OAAO,EAAE,MAAM,EAAE,WAAoB,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;YACvE,CAAC;YACD,KAAK,OAAO,CAAC,aAAa,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;YACvD,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC;YACzB,KAAK,CAAC,UAAU,GAAG,GAAG,EAAE,CAAC;YACzB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,aAAa,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,gBAAgB,CAAC,CAAC;YACpG,KAAK,CAAC,oBAAoB,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC;YAC7C,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;YAC/E,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;QAAA,CACxD;QACD,OAAO,CAAC,KAAK,EAAE;YACd,IAAI,KAAK,CAAC,MAAM,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;gBACrC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;gBAC/C,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;YACrD,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAClB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;QAAA,CAClD;QACD,KAAK,GAAG;YACP,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QAAA,CACpD;QACD,MAAM,GAAG;YACR,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;QAAA,CAC3E;QACD,IAAI,SAAS,GAAG;YACf,OAAO,KAAK,CAAC,MAAM,CAAC;QAAA,CACpB;KACD,CAAC;AAAA,CACF","sourcesContent":["/**\n * Plugin supervisor (7.2) — heartbeat, restart, and backpressure over the\n * 7.1 plugin host, all deterministic (clock and sleep are injected; there\n * are no hidden timers).\n *\n * Heartbeat: every supervised plugin must report a beat before\n * `heartbeatIntervalMs` elapses since its last beat, checked only by an\n * explicit `tick()`. A missed beat marks the plugin unhealthy and triggers\n * a restart policy (bounded attempts with exponential backoff). Restart:\n * the supervisor re-invokes the plugin's start with the recorded attempt\n * number; a plugin exceeding `restartLimit` ends in a terminal\n * `exhausted` health. Backpressure: an internal event queue with a hard\n * cap — enqueueing beyond the cap fails closed with `queue_full` instead of\n * growing unbounded. Fault injection is trivially the caller's job: the\n * tests simulate missed beats and crashes directly. Supply-chain signing is\n * 7.3.\n */\nimport type { HostedPluginV1 } from \"./plugin-host.ts\";\n\nexport interface SupervisorPolicyV1 {\n\treadonly heartbeatIntervalMs: number;\n\treadonly restartLimit: number;\n\treadonly baseRestartMs: number;\n\treadonly queueCap: number;\n}\n\nexport type PluginHealthV1 = \"healthy\" | \"unhealthy\" | \"exhausted\" | \"stopped\";\n\nexport interface SupervisorEntryV1 {\n\treadonly pluginId: string;\n\treadonly health: PluginHealthV1;\n\treadonly restarts: number;\n\treadonly lastBeatAt: number;\n\treadonly nextRestartAllowedAt?: number;\n}\n\nexport type SupervisorEventV1 =\n\t| { readonly kind: \"beat\"; readonly pluginId: string; readonly at: number }\n\t| { readonly kind: \"unhealthy\"; readonly pluginId: string; readonly at: number }\n\t| { readonly kind: \"restart\"; readonly pluginId: string; readonly at: number; readonly attempt: number }\n\t| { readonly kind: \"exhausted\"; readonly pluginId: string; readonly at: number; readonly attempts: number }\n\t| { readonly kind: \"queue_full\"; readonly at: number };\n\nexport interface PluginSupervisorV1 {\n\tsupervise(plugin: HostedPluginV1): void;\n\tbeat(pluginId: string): void;\n\ttick(at: number): void;\n\trestart(pluginId: string): { readonly status: \"restarted\" | \"exhausted\" | \"unknown\"; readonly attempt?: number };\n\tenqueue(event: string): { readonly status: \"enqueued\" | \"queue_full\"; readonly size: number };\n\tdrain(): readonly string[];\n\thealth(): readonly SupervisorEntryV1[];\n\treadonly queueSize: number;\n}\n\nexport function createPluginSupervisor(options: {\n\treadonly policy: SupervisorPolicyV1;\n\treadonly plugins: readonly HostedPluginV1[];\n\treadonly now?: () => number;\n\treadonly restartPlugin?: (pluginId: string, attempt: number) => Promise<void> | void;\n}): PluginSupervisorV1 {\n\tconst policy = options.policy;\n\tconst now = options.now ?? (() => 0);\n\n\tinterface Entry {\n\t\tpluginId: string;\n\t\thealth: PluginHealthV1;\n\t\trestarts: number;\n\t\tlastBeatAt: number;\n\t\tnextRestartAllowedAt?: number;\n\t}\n\tconst entries = new Map<string, Entry>();\n\tconst events: SupervisorEventV1[] = [];\n\tconst queue: string[] = [];\n\n\tfor (const plugin of options.plugins) {\n\t\tentries.set(plugin.pluginId, {\n\t\t\tpluginId: plugin.pluginId,\n\t\t\thealth: \"healthy\",\n\t\t\trestarts: 0,\n\t\t\tlastBeatAt: now(),\n\t\t});\n\t}\n\n\treturn {\n\t\tsupervise(plugin) {\n\t\t\tentries.set(plugin.pluginId, {\n\t\t\t\tpluginId: plugin.pluginId,\n\t\t\t\thealth: \"healthy\",\n\t\t\t\trestarts: 0,\n\t\t\t\tlastBeatAt: now(),\n\t\t\t});\n\t\t},\n\t\tbeat(pluginId) {\n\t\t\tconst entry = entries.get(pluginId);\n\t\t\tif (!entry) throw new Error(`Unknown supervised plugin: ${pluginId}`);\n\t\t\tentry.lastBeatAt = now();\n\t\t\tentry.health = \"healthy\";\n\t\t\tevents.push({ kind: \"beat\", pluginId, at: entry.lastBeatAt });\n\t\t},\n\t\ttick(at) {\n\t\t\tfor (const entry of entries.values()) {\n\t\t\t\tif (entry.health !== \"unhealthy\" && at - entry.lastBeatAt > policy.heartbeatIntervalMs) {\n\t\t\t\t\tentry.health = \"unhealthy\";\n\t\t\t\t\tevents.push({ kind: \"unhealthy\", pluginId: entry.pluginId, at });\n\t\t\t\t}\n\t\t\t}\n\t\t},\n\t\trestart(pluginId) {\n\t\t\tconst entry = entries.get(pluginId);\n\t\t\tif (!entry) return { status: \"unknown\" as const };\n\t\t\tif (entry.health === \"exhausted\") return { status: \"exhausted\" as const, attempts: entry.restarts };\n\t\t\tif (entry.nextRestartAllowedAt !== undefined && now() < entry.nextRestartAllowedAt) {\n\t\t\t\treturn { status: \"restarted\" as const, attempt: entry.restarts };\n\t\t\t}\n\t\t\tentry.restarts += 1;\n\t\t\tif (entry.restarts > policy.restartLimit) {\n\t\t\t\tentry.health = \"exhausted\";\n\t\t\t\tevents.push({ kind: \"exhausted\", pluginId, at: now(), attempts: entry.restarts - 1 });\n\t\t\t\treturn { status: \"exhausted\" as const, attempts: entry.restarts - 1 };\n\t\t\t}\n\t\t\tvoid options.restartPlugin?.(pluginId, entry.restarts);\n\t\t\tentry.health = \"healthy\";\n\t\t\tentry.lastBeatAt = now();\n\t\t\tconst backoff = Math.min(policy.baseRestartMs * 2 ** (entry.restarts - 1), Number.MAX_SAFE_INTEGER);\n\t\t\tentry.nextRestartAllowedAt = now() + backoff;\n\t\t\tevents.push({ kind: \"restart\", pluginId, at: now(), attempt: entry.restarts });\n\t\t\treturn { status: \"restarted\", attempt: entry.restarts };\n\t\t},\n\t\tenqueue(event) {\n\t\t\tif (queue.length >= policy.queueCap) {\n\t\t\t\tevents.push({ kind: \"queue_full\", at: now() });\n\t\t\t\treturn { status: \"queue_full\", size: queue.length };\n\t\t\t}\n\t\t\tqueue.push(event);\n\t\t\treturn { status: \"enqueued\", size: queue.length };\n\t\t},\n\t\tdrain() {\n\t\t\treturn Object.freeze(queue.splice(0, queue.length));\n\t\t},\n\t\thealth() {\n\t\t\treturn Object.freeze([...entries.values()].map((entry) => ({ ...entry })));\n\t\t},\n\t\tget queueSize() {\n\t\t\treturn queue.length;\n\t\t},\n\t};\n}\n"]}