@synoikia/core 0.1.0

package/dist/instances/manager.d.ts

@@ -0,0 +1,313 @@
+import type { SyncSummary } from '../catalog/sync.js';
+import type { SecretBox } from '../crypto/index.js';
+import type { Db } from '../db/index.js';
+import { pluginInstances, plugins } from '../db/schema.js';
+import type { CoreEvents } from '../events.js';
+import type { InstanceRuntime } from '../gate/pipeline.js';
+import type { InstanceStatus } from '../plugins/supervisor.js';
+import type { InstanceSettings } from './settings.js';
+/**
+ * Instance lifecycle (design §4, §10): creation and connection config (secrets encrypted), one
+ * supervised plugin child per enabled instance, and catalog/registry sync scheduling.
+ */
+export declare const AUTH_MODES: readonly ["external", "bearer", "oauth", "bearer+oauth"];
+export type AuthMode = (typeof AUTH_MODES)[number];
+type InstanceRow = typeof pluginInstances.$inferSelect;
+type PluginRow = typeof plugins.$inferSelect;
+export interface ManagerOptions {
+    db: Db;
+    secrets: SecretBox;
+    events: CoreEvents;
+    now?: () => Date;
+    /** Test hooks: faster restarts and shorter RPC/init timeouts. */
+    supervisor?: {
+        backoff?: {
+            initialMs: number;
+            maxMs: number;
+        };
+        initTimeoutMs?: number;
+        rpcTimeoutMs?: number;
+    };
+    /** How often a live session may trigger the cheap upstream version check. */
+    versionCheckIntervalMs?: number;
+}
+export interface CreateInstanceInput {
+    pluginId: string;
+    slug: string;
+    displayName?: string;
+    /** Config and secrets together, as the connection form submits them. */
+    connection: Record<string, unknown>;
+    authMode?: AuthMode | null;
+    settings?: unknown;
+    enabled?: boolean;
+}
+export interface Actor {
+    userId?: string;
+}
+export declare class InstanceManager {
+    private readonly opts;
+    private readonly live;
+    private readonly db;
+    private readonly now;
+    constructor(opts: ManagerOptions);
+    private row;
+    private plugin;
+    /** Resolves a plugin by row id or by manifest id (`truenas`). */
+    private pluginByAnyId;
+    list(): {
+        id: string;
+        slug: string;
+        displayName: string;
+        enabled: boolean;
+        authMode: "external" | "bearer" | "oauth" | "bearer+oauth" | null;
+        status: "stopped" | "starting" | "ready" | "error";
+        statusError: string | null;
+        upstreamVersion: string | null;
+        sourceRef: string | null;
+        lastSyncedAt: Date | null;
+        lastSyncStatus: string | null;
+        settings: {
+            approvalTimeoutMs: number;
+            formElicitationApprovals: "off" | "writes";
+            executePerMinute: number;
+            writesPerMinute: number;
+            sandbox: {
+                timeoutMs: number;
+                memoryMb: number;
+                maxResultBytes: number;
+            };
+            extraRedactKeys: string[];
+            syncMaxAgeMs: number;
+            memoryMb: number;
+        };
+        plugin: {
+            id: string;
+            pluginId: string;
+            name: string;
+            enabled: boolean;
+            status: "ok" | "invalid" | "incompatible";
+            labels: {
+                operation: string;
+                operations: string;
+            } | undefined;
+            attestation: boolean;
+        };
+    }[];
+    get(id: string): {
+        id: string;
+        slug: string;
+        displayName: string;
+        enabled: boolean;
+        authMode: "external" | "bearer" | "oauth" | "bearer+oauth" | null;
+        status: "stopped" | "starting" | "ready" | "error";
+        statusError: string | null;
+        upstreamVersion: string | null;
+        sourceRef: string | null;
+        lastSyncedAt: Date | null;
+        lastSyncStatus: string | null;
+        settings: {
+            approvalTimeoutMs: number;
+            formElicitationApprovals: "off" | "writes";
+            executePerMinute: number;
+            writesPerMinute: number;
+            sandbox: {
+                timeoutMs: number;
+                memoryMb: number;
+                maxResultBytes: number;
+            };
+            extraRedactKeys: string[];
+            syncMaxAgeMs: number;
+            memoryMb: number;
+        };
+        plugin: {
+            id: string;
+            pluginId: string;
+            name: string;
+            enabled: boolean;
+            status: "ok" | "invalid" | "incompatible";
+            labels: {
+                operation: string;
+                operations: string;
+            } | undefined;
+            attestation: boolean;
+        };
+    };
+    bySlug(slug: string): {
+        instance: InstanceRow;
+        plugin: PluginRow;
+    } | undefined;
+    private describe;
+    /** Whether the instance's endpoint should serve: instance and plugin enabled, plugin healthy. */
+    isServing(instance: InstanceRow, plugin: PluginRow): boolean;
+    settingsOf(instance: InstanceRow): InstanceSettings;
+    /**
+     * Scrubs an instance's secret values out of plugin/upstream error text before it is stored, audited
+     * or sent to notification channels (an init error can echo a config value or token).
+     */
+    private scrubError;
+    /** Startup step: removes stored instance settings fields the current schema rejects. */
+    normalizeStoredSettings(): string[];
+    /** Everything the gate needs for one instance. */
+    runtime(instanceId: string): InstanceRuntime;
+    status(instanceId: string): InstanceStatus;
+    private readSecrets;
+    private sealSecrets;
+    create(input: CreateInstanceInput, actor?: Actor): Promise<{
+        id: string;
+        slug: string;
+        displayName: string;
+        enabled: boolean;
+        authMode: "external" | "bearer" | "oauth" | "bearer+oauth" | null;
+        status: "stopped" | "starting" | "ready" | "error";
+        statusError: string | null;
+        upstreamVersion: string | null;
+        sourceRef: string | null;
+        lastSyncedAt: Date | null;
+        lastSyncStatus: string | null;
+        settings: {
+            approvalTimeoutMs: number;
+            formElicitationApprovals: "off" | "writes";
+            executePerMinute: number;
+            writesPerMinute: number;
+            sandbox: {
+                timeoutMs: number;
+                memoryMb: number;
+                maxResultBytes: number;
+            };
+            extraRedactKeys: string[];
+            syncMaxAgeMs: number;
+            memoryMb: number;
+        };
+        plugin: {
+            id: string;
+            pluginId: string;
+            name: string;
+            enabled: boolean;
+            status: "ok" | "invalid" | "incompatible";
+            labels: {
+                operation: string;
+                operations: string;
+            } | undefined;
+            attestation: boolean;
+        };
+    }>;
+    update(id: string, patch: {
+        displayName?: string;
+        slug?: string;
+        enabled?: boolean;
+        authMode?: AuthMode | null;
+        settings?: unknown;
+    }, actor?: Actor): Promise<{
+        id: string;
+        slug: string;
+        displayName: string;
+        enabled: boolean;
+        authMode: "external" | "bearer" | "oauth" | "bearer+oauth" | null;
+        status: "stopped" | "starting" | "ready" | "error";
+        statusError: string | null;
+        upstreamVersion: string | null;
+        sourceRef: string | null;
+        lastSyncedAt: Date | null;
+        lastSyncStatus: string | null;
+        settings: {
+            approvalTimeoutMs: number;
+            formElicitationApprovals: "off" | "writes";
+            executePerMinute: number;
+            writesPerMinute: number;
+            sandbox: {
+                timeoutMs: number;
+                memoryMb: number;
+                maxResultBytes: number;
+            };
+            extraRedactKeys: string[];
+            syncMaxAgeMs: number;
+            memoryMb: number;
+        };
+        plugin: {
+            id: string;
+            pluginId: string;
+            name: string;
+            enabled: boolean;
+            status: "ok" | "invalid" | "incompatible";
+            labels: {
+                operation: string;
+                operations: string;
+            } | undefined;
+            attestation: boolean;
+        };
+    }>;
+    remove(id: string, confirmSlug: string, actor?: Actor): Promise<void>;
+    getConnection(id: string): {
+        config: Record<string, unknown>;
+        secrets: Record<string, import("./connection.js").SecretSummary>;
+        schema: Record<string, unknown>;
+        ui: Record<string, {
+            widget?: "number" | "text" | "url" | "diff" | "select" | "secret" | "prefix" | "range" | "bool" | "multiselect" | "registry-picker" | undefined;
+            help?: string | undefined;
+            placeholder?: string | undefined;
+            optionsSource?: string | undefined;
+            showWhen?: {
+                field: string;
+                in: (string | number | boolean)[];
+            } | undefined;
+        }>;
+        help: string | undefined;
+    };
+    /** Replaces non-secret config; secrets follow the merge rules in `mergeSecrets`. Restarts the child. */
+    updateConnection(id: string, input: {
+        config: Record<string, unknown>;
+        secrets?: Record<string, string | null>;
+    }, actor?: Actor): Promise<{
+        config: Record<string, unknown>;
+        secrets: Record<string, import("./connection.js").SecretSummary>;
+        schema: Record<string, unknown>;
+        ui: Record<string, {
+            widget?: "number" | "text" | "url" | "diff" | "select" | "secret" | "prefix" | "range" | "bool" | "multiselect" | "registry-picker" | undefined;
+            help?: string | undefined;
+            placeholder?: string | undefined;
+            optionsSource?: string | undefined;
+            showWhen?: {
+                field: string;
+                in: (string | number | boolean)[];
+            } | undefined;
+        }>;
+        help: string | undefined;
+    }>;
+    /**
+     * "Test connection": runs `testConnection` in a throwaway child, so an unsaved candidate config
+     * can be tried without disturbing the running instance. Omitted secrets fall back to stored ones.
+     */
+    testConnection(id: string, candidate?: {
+        config: Record<string, unknown>;
+        secrets?: Record<string, string | null>;
+    }): Promise<{
+        ok: boolean;
+        message?: string | undefined;
+        upstreamVersion?: string | undefined;
+    }>;
+    setPluginEnabled(pluginRowId: string, enabled: boolean, actor?: Actor): Promise<void>;
+    /** Stops every running instance of a plugin (before its files are replaced). */
+    stopPlugin(pluginRowId: string): Promise<void>;
+    /** Starts every servable instance of a plugin and resyncs its catalog (after an install or update). */
+    startPlugin(pluginRowId: string): Promise<void>;
+    startAll(): Promise<void>;
+    stopAll(): Promise<void>;
+    private setStatus;
+    private start;
+    private stop;
+    private scheduleSync;
+    /** Full catalog (+ registry) sync. Concurrent callers share one run (per-instance mutex). */
+    syncNow(instanceId: string): Promise<SyncSummary>;
+    /**
+     * Called before serving MCP traffic (session start, and cheaply on each tool call):
+     * - never synced → sync now; failure means the endpoint can't serve (TN §2.2, per instance);
+     * - stale beyond `syncMaxAgeMs` → sync, but keep serving the last catalog if it fails;
+     * - otherwise compare the upstream version (throttled) and sync on a mismatch.
+     */
+    ensureFresh(instanceId: string, opts?: {
+        forceVersionCheck?: boolean;
+    }): Promise<void>;
+    /** Daily backstop (design §10): sync anything that hasn't synced in 24 h. */
+    syncStale(maxAgeMs?: number): Promise<void>;
+}
+export {};