@synoikia/core 0.1.0

package/dist/plugins/supervisor.d.ts

@@ -0,0 +1,50 @@
+import type { InitParams } from '@synoikia/plugin-sdk';
+import { PluginProcess } from './process.js';
+import type { SpawnOptions } from './process.js';
+/**
+ * Keeps one plugin instance's child process alive (design §4.4): spawn → `init` → ready. On an
+ * unexpected exit the instance goes to `error` and restarts with exponential backoff. A crashed or
+ * restarting plugin never makes the gate fail open: callers just get `PluginUnavailableError`.
+ */
+export type InstanceStatus = 'stopped' | 'starting' | 'ready' | 'error';
+export interface SupervisorOptions extends SpawnOptions {
+    /** Called on every start with this instance's config and freshly decrypted secrets. */
+    loadInit: () => Omit<InitParams, 'sdkVersion' | 'instanceId'>;
+    onStatus?: (status: InstanceStatus, error?: string) => void;
+    onLog?: (level: string, message: string) => void;
+    onCatalogChanged?: (reason?: string) => void;
+    initTimeoutMs?: number;
+    backoff?: {
+        initialMs: number;
+        maxMs: number;
+    };
+}
+export declare class PluginSupervisor {
+    private readonly opts;
+    private proc?;
+    private _status;
+    private stopping;
+    private restartTimer?;
+    private attempt;
+    private generation;
+    private queue;
+    constructor(opts: SupervisorOptions);
+    get status(): InstanceStatus;
+    /** The live process for RPC calls. Throws unless the instance is ready. */
+    get client(): PluginProcess;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Restart now (e.g. after the admin changed the connection config or secrets). */
+    restart(): Promise<void>;
+    /**
+     * Lifecycle changes run one at a time, so concurrent restarts can't leave two children alive and a
+     * stop can't be undone by a start that was already under way.
+     */
+    private serial;
+    /** Supersedes whatever is in flight at once: a child still in `init` is killed, not waited for. */
+    private halt;
+    private shutdown;
+    private setStatus;
+    private spawn;
+    private scheduleRestart;
+}

package/dist/plugins/supervisor.js

@@ -0,0 +1,125 @@
+import { SDK_VERSION } from '@synoikia/plugin-sdk';
+import { PluginProcess, PluginUnavailableError } from './process.js';
+export class PluginSupervisor {
+    opts;
+    proc;
+    _status = 'stopped';
+    stopping = false;
+    restartTimer;
+    attempt = 0;
+    generation = 0;
+    queue = Promise.resolve();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    get status() {
+        return this._status;
+    }
+    /** The live process for RPC calls. Throws unless the instance is ready. */
+    get client() {
+        if (this._status !== 'ready' || !this.proc?.running)
+            throw new PluginUnavailableError();
+        return this.proc;
+    }
+    async start() {
+        return this.serial(async () => {
+            this.stopping = false;
+            if (this.proc)
+                return; // already running or starting
+            await this.spawn();
+        });
+    }
+    async stop() {
+        this.halt();
+        return this.serial(() => this.shutdown());
+    }
+    /** Restart now (e.g. after the admin changed the connection config or secrets). */
+    async restart() {
+        this.halt();
+        return this.serial(async () => {
+            await this.shutdown();
+            this.attempt = 0;
+            this.stopping = false;
+            await this.spawn();
+        });
+    }
+    /**
+     * Lifecycle changes run one at a time, so concurrent restarts can't leave two children alive and a
+     * stop can't be undone by a start that was already under way.
+     */
+    serial(fn) {
+        const run = this.queue.then(fn);
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
+    /** Supersedes whatever is in flight at once: a child still in `init` is killed, not waited for. */
+    halt() {
+        this.stopping = true;
+        this.generation++;
+        clearTimeout(this.restartTimer);
+        if (this._status === 'starting')
+            this.proc?.kill();
+    }
+    async shutdown() {
+        this.stopping = true;
+        this.generation++;
+        clearTimeout(this.restartTimer);
+        const proc = this.proc;
+        this.proc = undefined;
+        await proc?.stop();
+        this.setStatus('stopped');
+    }
+    setStatus(status, error) {
+        this._status = status;
+        this.opts.onStatus?.(status, error);
+    }
+    async spawn() {
+        const generation = ++this.generation;
+        this.setStatus('starting');
+        const proc = new PluginProcess(this.opts);
+        this.proc = proc;
+        proc.on('log', (level, message) => this.opts.onLog?.(level, message));
+        proc.on('catalogChanged', (reason) => this.opts.onCatalogChanged?.(reason));
+        proc.on('exit', (code, signal) => {
+            if (this.stopping || generation !== this.generation)
+                return;
+            this.scheduleRestart(`plugin exited unexpectedly (${signal ?? `code ${code}`})`);
+        });
+        try {
+            proc.start();
+            await proc.call('init', { ...this.opts.loadInit(), instanceId: this.opts.instanceId, sdkVersion: SDK_VERSION }, this.opts.initTimeoutMs ?? 30_000);
+        }
+        catch (err) {
+            proc.kill();
+            if (generation !== this.generation)
+                return;
+            this.scheduleRestart(`init failed: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        if (generation !== this.generation) {
+            // Superseded (stopped or restarted) during init: this child must not outlive its turn.
+            proc.kill();
+            return;
+        }
+        this.attempt = 0;
+        this.setStatus('ready');
+    }
+    scheduleRestart(reason) {
+        if (this.stopping)
+            return;
+        this.generation++;
+        this.proc = undefined;
+        this.setStatus('error', reason);
+        const { initialMs, maxMs } = this.opts.backoff ?? { initialMs: 1000, maxMs: 60_000 };
+        const delay = Math.min(maxMs, initialMs * 2 ** this.attempt++);
+        clearTimeout(this.restartTimer);
+        const generation = this.generation;
+        this.restartTimer = setTimeout(() => {
+            void this.serial(async () => {
+                if (!this.stopping && generation === this.generation)
+                    await this.spawn();
+            });
+        }, delay);
+    }
+}
+//# sourceMappingURL=supervisor.js.map

package/dist/plugins/supervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../../src/plugins/supervisor.ts"],"names":[],"mappings":"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"}

package/dist/runtime/index.d.ts

@@ -0,0 +1,28 @@
+import type { CallerContext, GateDeps, InstanceRuntime } from '../gate/pipeline.js';
+import type { SandboxResult } from '../sandbox/index.js';
+/**
+ * The two MCP tools' engines (design §5.1–§5.2). The MCP transport layer (phase 14) only has to
+ * turn a tool call into `executeCode` / `searchCode` and the result back into tool output.
+ */
+/**
+ * Caps on sandbox work (design §5.2): `executePerMinute` counts `execute` and `search` runs per
+ * principal and instance, and only so many isolates (up to `memoryMb` each) run at once per instance
+ * and in total. Over either cap the run is refused before an isolate is created.
+ */
+export declare const SANDBOX_CONCURRENCY: {
+    perInstance: number;
+    total: number;
+};
+/** Scripts running now, across all instances (shutdown waits for cancelled ones to return). */
+export declare const sandboxesRunning: () => number;
+export declare function executeCode(deps: GateDeps, rt: InstanceRuntime, caller: CallerContext, code: string, signal?: AbortSignal): Promise<SandboxResult>;
+export interface CatalogFindQuery {
+    text?: string;
+    group?: string;
+    tag?: string;
+    kind?: string;
+    classification?: 'read' | 'write' | 'locked';
+    includeDisabled?: boolean;
+    limit?: number;
+}
+export declare function searchCode(deps: GateDeps, rt: InstanceRuntime, caller: CallerContext, code: string, _signal?: AbortSignal): Promise<SandboxResult>;

package/dist/runtime/index.js

@@ -0,0 +1,248 @@
+import { randomUUID } from 'node:crypto';
+import { and, asc, eq } from 'drizzle-orm';
+import { writeAudit } from '../audit.js';
+import { accessInput, listGroups } from '../catalog/groups.js';
+import { findRegistryEntries } from '../catalog/registry.js';
+import { guides, operationGroups, operations } from '../db/schema.js';
+import { effectiveAccess } from '../gate/access.js';
+import { currentGuide, issueAttestationKey } from '../gate/attestation.js';
+import { createGateBindings, principalKey } from '../gate/pipeline.js';
+import { BindingError, runInSandbox } from '../sandbox/index.js';
+/**
+ * The two MCP tools' engines (design §5.1–§5.2). The MCP transport layer (phase 14) only has to
+ * turn a tool call into `executeCode` / `searchCode` and the result back into tool output.
+ */
+/**
+ * Caps on sandbox work (design §5.2): `executePerMinute` counts `execute` and `search` runs per
+ * principal and instance, and only so many isolates (up to `memoryMb` each) run at once per instance
+ * and in total. Over either cap the run is refused before an isolate is created.
+ */
+export const SANDBOX_CONCURRENCY = { perInstance: 4, total: 16 };
+const running = new Map();
+let runningTotal = 0;
+/** Scripts running now, across all instances (shutdown waits for cancelled ones to return). */
+export const sandboxesRunning = () => runningTotal;
+function admit(deps, rt, caller) {
+    const who = principalKey(caller);
+    if (!deps.limiter.take(`run:${rt.instanceId}:${who}`, rt.settings.executePerMinute, 60_000)) {
+        return {
+            ok: false,
+            error: { code: 'RATE_LIMITED', message: 'Too many search/execute calls; slow down' },
+            logs: [],
+        };
+    }
+    const here = running.get(rt.instanceId) ?? 0;
+    if (here >= SANDBOX_CONCURRENCY.perInstance || runningTotal >= SANDBOX_CONCURRENCY.total) {
+        return { ok: false, error: { code: 'BUSY', message: 'Too many scripts are running; try again shortly' }, logs: [] };
+    }
+    running.set(rt.instanceId, here + 1);
+    runningTotal++;
+    return () => {
+        running.set(rt.instanceId, (running.get(rt.instanceId) ?? 1) - 1);
+        runningTotal--;
+    };
+}
+export async function executeCode(deps, rt, caller, code, signal) {
+    const release = admit(deps, rt, caller);
+    if (typeof release !== 'function')
+        return release;
+    // Ends with the sandbox (return, error or timeout) or earlier, when the request or session goes away.
+    const run = new AbortController();
+    const stop = () => run.abort();
+    signal?.addEventListener('abort', stop);
+    if (signal?.aborted)
+        stop();
+    try {
+        return await runInSandbox({
+            code,
+            bindings: createGateBindings(deps, rt, caller, run.signal),
+            limits: rt.settings.sandbox,
+            // Each gated call's result was already redacted; this covers anything the script derived or logged.
+            redact: rt.redact,
+        });
+    }
+    finally {
+        stop();
+        signal?.removeEventListener('abort', stop);
+        release();
+    }
+}
+function describeOp(op, groupKey, access) {
+    return {
+        key: op.key,
+        displayName: op.displayName ?? undefined,
+        group: groupKey,
+        classification: op.locked ? 'locked' : op.classification,
+        // Whether a call runs straight away, waits for a human, or is auto-approved at level `write`.
+        approval: access.reachable
+            ? { run: 'none', approve: 'required', auto: 'auto' }[access.mode]
+            : op.locked || op.classification === 'write'
+                ? 'required'
+                : 'none',
+        typedConfirmation: op.typedConfirmation,
+        attestationRequired: op.attestationRequired,
+        summary: op.docs?.summary,
+        ...(access.reachable ? {} : { disabled: true, reason: access.reason }),
+    };
+}
+function catalogBindings(db, instanceId, principal) {
+    const load = () => {
+        const groups = new Map(db
+            .select()
+            .from(operationGroups)
+            .where(eq(operationGroups.instanceId, instanceId))
+            .all()
+            .map((g) => [g.id, g]));
+        const ops = db
+            .select()
+            .from(operations)
+            .where(and(eq(operations.instanceId, instanceId), eq(operations.stale, false)))
+            .orderBy(asc(operations.key))
+            .all();
+        return { groups, ops };
+    };
+    const accessOf = (op, groups) => effectiveAccess(accessInput(op), groups.get(op.groupId), principal);
+    return {
+        find: async ([rawQuery]) => {
+            const q = (rawQuery ?? {});
+            const text = q.text?.toLowerCase();
+            const limit = Math.min(Math.max(1, Number(q.limit) || 50), 200);
+            const { groups, ops } = load();
+            const out = [];
+            for (const op of ops) {
+                const group = groups.get(op.groupId);
+                const access = accessOf(op, groups);
+                if (!access.reachable && !q.includeDisabled)
+                    continue;
+                if (q.group && group?.key !== q.group)
+                    continue;
+                if (q.tag && op.tag !== q.tag)
+                    continue;
+                if (q.kind && op.kind !== q.kind)
+                    continue;
+                const cls = op.locked ? 'locked' : op.classification;
+                if (q.classification && cls !== q.classification)
+                    continue;
+                if (text) {
+                    const hay = [op.key, op.displayName, op.docs?.summary]
+                        .join(' ')
+                        .toLowerCase();
+                    if (!hay.includes(text))
+                        continue;
+                }
+                out.push(describeOp(op, group?.key, access));
+                if (out.length >= limit)
+                    break;
+            }
+            return out;
+        },
+        get: async ([key]) => {
+            const { groups, ops } = load();
+            const op = ops.find((o) => o.key === key);
+            if (!op)
+                return null;
+            const access = accessOf(op, groups);
+            return { ...describeOp(op, groups.get(op.groupId)?.key, access), paramsSchema: op.paramsSchema, docs: op.docs };
+        },
+        groups: async () => listGroups(db, instanceId).filter((g) => !g.stale),
+    };
+}
+/**
+ * `guides.get(key)`: fetches the plugin's current best-practice guide, records its version, and
+ * hands out the attestation key `execute` must present from the same MCP session (HA §3.6). Revising
+ * a guide rotates the key. Every read is audited: the key attests that this session was shown it.
+ */
+function guideBindings(deps, rt, caller) {
+    return {
+        get: async ([key]) => {
+            const op = deps.db
+                .select()
+                .from(operations)
+                .where(and(eq(operations.instanceId, rt.instanceId), eq(operations.key, String(key)), eq(operations.stale, false)))
+                .get();
+            if (!op)
+                throw new BindingError('UNKNOWN_OPERATION', `${String(key)} is not in the catalog`);
+            if (!op.attestationRequired)
+                return { key: op.key, required: false };
+            let guide;
+            try {
+                guide = await rt.plugin().call('getGuide', { key: op.key });
+            }
+            catch {
+                throw new BindingError('PLUGIN_ERROR', `Could not load the guide for ${op.key}`);
+            }
+            const current = currentGuide(deps.db, rt.instanceId, op.id);
+            if (!current || current.version !== guide.version || current.content !== guide.content) {
+                deps.db
+                    .insert(guides)
+                    .values({
+                    id: randomUUID(),
+                    instanceId: rt.instanceId,
+                    operationId: op.id,
+                    version: guide.version,
+                    content: guide.content,
+                    fetchedAt: deps.now?.() ?? new Date(),
+                })
+                    .run();
+            }
+            writeAudit(deps.db, {
+                kind: 'search',
+                instanceId: rt.instanceId,
+                operationKey: op.key,
+                decision: 'guide_read',
+                actorKind: 'mcp_client',
+                actorId: caller.client.id ?? null,
+                detail: { guideVersion: guide.version, mcpSessionId: caller.mcpSessionId ?? null },
+            }, deps.now?.() ?? new Date());
+            return {
+                key: op.key,
+                required: true,
+                version: guide.version,
+                content: guide.content,
+                best_practice_key: issueAttestationKey(deps.attestationKey, rt.instanceId, op.key, guide.version, caller.mcpSessionId),
+            };
+        },
+    };
+}
+function searchBindings(deps, rt, caller) {
+    const bindings = {
+        catalog: catalogBindings(deps.db, rt.instanceId, caller.principal),
+    };
+    if (rt.manifest.capabilities.registry) {
+        bindings.registry = {
+            find: async ([q]) => 
+            // Mirrored upstream attributes can hold tokens (HA camera `access_token`): redact at the source.
+            rt.redact(findRegistryEntries(deps.db, rt.instanceId, (q ?? {}))),
+        };
+    }
+    if (rt.manifest.capabilities.attestation)
+        bindings.guides = guideBindings(deps, rt, caller);
+    return bindings;
+}
+export async function searchCode(deps, rt, caller, code, _signal) {
+    const release = admit(deps, rt, caller);
+    if (typeof release !== 'function')
+        return release;
+    let result;
+    try {
+        result = await runInSandbox({
+            code,
+            bindings: searchBindings(deps, rt, caller),
+            limits: rt.settings.sandbox,
+            redact: rt.redact,
+        });
+    }
+    finally {
+        release();
+    }
+    writeAudit(deps.db, {
+        kind: 'search',
+        instanceId: rt.instanceId,
+        actorKind: 'mcp_client',
+        actorId: caller.client.id,
+        resultStatus: result.ok ? 'ok' : 'error',
+        detail: result.ok ? { truncated: result.truncated } : { error: result.error.code },
+    }, deps.now?.() ?? new Date());
+    return result;
+}
+//# sourceMappingURL=index.js.map

package/dist/runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Runs model-authored code in a fresh V8 isolate (design §5.4). The isolate has no Node APIs at all:
+ * the only way out is the host functions passed in `bindings`. Values cross the boundary as JSON.
+ *
+ * `code` is the body of an async function: it may `await` bindings and should `return` its result.
+ */
+export interface SandboxLimits {
+    /** Wall-clock budget for sandbox activity. Time a binding spends paused (human approval) is excluded. */
+    timeoutMs: number;
+    memoryMb: number;
+    /** Maximum size of the JSON-encoded result; larger results are truncated with a marker. */
+    maxResultBytes: number;
+    maxLogBytes: number;
+}
+export declare const DEFAULT_LIMITS: SandboxLimits;
+/** Thrown by a binding to surface a structured error (`err.code`) inside the sandbox. */
+export declare class BindingError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Lets a binding stop the sandbox clock while it waits on something slow and human, like approval. */
+export interface BudgetControl {
+    pause(): void;
+    resume(): void;
+    /** Milliseconds of sandbox budget left. */
+    remainingMs(): number;
+}
+export type Binding = (args: unknown[], budget: BudgetControl) => Promise<unknown>;
+export interface SandboxRun {
+    code: string;
+    /** `{ truenas: { call: fn } }` becomes `truenas.call(...)` inside the sandbox. */
+    bindings: Record<string, Record<string, Binding>>;
+    limits?: Partial<SandboxLimits>;
+    /**
+     * Applied to everything that leaves the sandbox — the result (before it is size-capped), every
+     * `console.log` argument and error messages — so nothing the code derives or prints escapes redaction.
+     */
+    redact?: (value: unknown) => unknown;
+}
+export type SandboxResult = {
+    ok: true;
+    value: unknown;
+    truncated: boolean;
+    logs: string[];
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+    logs: string[];
+};
+export declare function runInSandbox(run: SandboxRun): Promise<SandboxResult>;