@nylorun/runtime 0.9.0-beta → 0.10.0-beta

package/dist/tenant/paths.js

@@ -0,0 +1,65 @@
+import { existsSync, mkdirSync, realpathSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { isTenantId } from "@nylorun/core/compatibility";
+function ensureDir(path) {
+    mkdirSync(path, { recursive: true });
+    return realpathSync(path);
+}
+function assertContained(parent, child) {
+    const root = parent.endsWith(sep) ? parent : parent + sep;
+    if (child !== parent && !child.startsWith(root)) {
+        throw new Error(`Path ${child} escapes host tenants root ${parent}`);
+    }
+}
+/** Host layout under NYLORUN_HOME / ~/.nylorun. */
+export function hostPaths(hostRoot) {
+    const root = resolve(hostRoot);
+    return {
+        root,
+        config: join(root, "host.json"),
+        state: join(root, "host-state.json"),
+        credentials: join(root, "host-credentials.json"),
+        log: join(root, "runtime.log"),
+        home: join(root, "home"),
+        tmp: join(root, "tmp"),
+        runtime: join(root, "runtime"),
+        tenants: join(root, "tenants"),
+        trash: join(root, "trash"),
+    };
+}
+/**
+ * Absolute Tenant paths under `<hostRoot>/tenants/<tenantId>/`.
+ * Validates the id and asserts containment after realpath.
+ *
+ * Basenames frozen here for Wave 0 (design Rev 3 absent):
+ * `tenant.json`, `tenant.sqlite`, `.runtime-lock`, `vault-kek`,
+ * `home/`, `tmp/`, `.migration/`, `sandboxes/`, `plugin-data/`, `logs/tenant.log`.
+ */
+export function tenantPaths(hostRoot, tenantId) {
+    if (!isTenantId(tenantId)) {
+        throw new Error(`Invalid tenant id: ${String(tenantId)}`);
+    }
+    const host = hostPaths(hostRoot);
+    const tenantsRoot = ensureDir(host.tenants);
+    const root = join(tenantsRoot, tenantId);
+    // Containment before the Tenant directory exists: resolve under real tenants root.
+    const resolvedRoot = resolve(tenantsRoot, tenantId);
+    assertContained(tenantsRoot, resolvedRoot);
+    if (existsSync(root)) {
+        assertContained(tenantsRoot, realpathSync(root));
+    }
+    return {
+        root: resolvedRoot,
+        envelope: join(resolvedRoot, "tenant.json"),
+        database: join(resolvedRoot, "tenant.sqlite"),
+        lock: join(resolvedRoot, ".runtime-lock"),
+        kek: join(resolvedRoot, "vault-kek"),
+        home: join(resolvedRoot, "home"),
+        tmp: join(resolvedRoot, "tmp"),
+        migration: join(resolvedRoot, ".migration"),
+        sandboxes: join(resolvedRoot, "sandboxes"),
+        pluginData: join(resolvedRoot, "plugin-data"),
+        logs: join(resolvedRoot, "logs"),
+        log: join(resolvedRoot, "logs", "tenant.log"),
+    };
+}

package/dist/tenant/pool.d.ts

@@ -0,0 +1,10 @@
+/** Run async work over items with a fixed concurrency limit. */
+export declare function mapPool<T, R>(items: readonly T[], concurrency: number, worker: (item: T, index: number) => Promise<R>): Promise<R[]>;
+export declare class TimeoutError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Race a promise against a timeout. On timeout the late result is handed to
+ * `onLate` (Risk R6: mark quarantined and close a late handle).
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, onLate?: (late: Promise<T>) => void): Promise<T>;

package/dist/tenant/pool.js

@@ -0,0 +1,54 @@
+/** Run async work over items with a fixed concurrency limit. */
+export async function mapPool(items, concurrency, worker) {
+    if (items.length === 0)
+        return [];
+    const limit = Math.max(1, Math.min(concurrency, items.length));
+    const results = new Array(items.length);
+    let next = 0;
+    async function run() {
+        for (;;) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            results[index] = await worker(items[index], index);
+        }
+    }
+    await Promise.all(Array.from({ length: limit }, () => run()));
+    return results;
+}
+export class TimeoutError extends Error {
+    constructor(message = "operation timed out") {
+        super(message);
+        this.name = "TimeoutError";
+    }
+}
+/**
+ * Race a promise against a timeout. On timeout the late result is handed to
+ * `onLate` (Risk R6: mark quarantined and close a late handle).
+ */
+export async function withTimeout(promise, timeoutMs, onLate) {
+    let timer;
+    let timedOut = false;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            timedOut = true;
+            reject(new TimeoutError(`timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    try {
+        const result = await Promise.race([promise, timeout]);
+        return result;
+    }
+    catch (error) {
+        if (timedOut && onLate) {
+            onLate(promise.then((value) => value, (lateError) => {
+                throw lateError;
+            }));
+        }
+        throw error;
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}

package/dist/tenant/principals.d.ts

@@ -0,0 +1,17 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { BootstrapPrincipal } from "./types.js";
+export interface PrincipalRow {
+    id: string;
+    role: "application";
+    tokenHash: string;
+    idempotencyKey: string | null;
+    createdAt: string;
+}
+/**
+ * Writes the application principal and idempotency key in one transaction.
+ * Exported for WS-B's `TenantStore.create` (A3).
+ */
+export declare function bootstrapPrincipal(db: DatabaseSync, bootstrap: BootstrapPrincipal): void;
+export declare function findPrincipalByTokenHash(db: DatabaseSync, tokenHash: string): PrincipalRow | undefined;
+export declare function applicationTokenHashes(db: DatabaseSync): readonly string[];
+export declare function isApplicationTokenHash(db: DatabaseSync, tokenHash: string): boolean;

package/dist/tenant/principals.js

@@ -0,0 +1,44 @@
+/**
+ * Writes the application principal and idempotency key in one transaction.
+ * Exported for WS-B's `TenantStore.create` (A3).
+ */
+export function bootstrapPrincipal(db, bootstrap) {
+    const now = new Date().toISOString();
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        db.prepare(`INSERT INTO principals(id, role, token_hash, idempotency_key, created_at)
+       VALUES(?, 'application', ?, ?, ?)`).run(bootstrap.principalId, bootstrap.credentialHash, bootstrap.idempotencyKey, now);
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}
+export function findPrincipalByTokenHash(db, tokenHash) {
+    const row = db
+        .prepare(`SELECT id, role, token_hash, idempotency_key, created_at
+       FROM principals WHERE token_hash = ?`)
+        .get(tokenHash);
+    if (!row)
+        return undefined;
+    return {
+        id: String(row.id),
+        role: "application",
+        tokenHash: String(row.token_hash),
+        idempotencyKey: row.idempotency_key == null ? null : String(row.idempotency_key),
+        createdAt: String(row.created_at),
+    };
+}
+export function applicationTokenHashes(db) {
+    return db
+        .prepare(`SELECT token_hash FROM principals WHERE role = 'application'`)
+        .all()
+        .map((row) => String(row.token_hash));
+}
+export function isApplicationTokenHash(db, tokenHash) {
+    const row = db
+        .prepare(`SELECT 1 AS ok FROM principals WHERE role = 'application' AND token_hash = ?`)
+        .get(tokenHash);
+    return !!row;
+}

package/dist/tenant/quarantine-error.d.ts

@@ -0,0 +1,6 @@
+import type { Quarantine } from "./types.js";
+/** Typed quarantine raised while opening a Tenant Runtime (A7). */
+export declare class QuarantineError extends Error {
+    readonly quarantine: Quarantine;
+    constructor(code: Quarantine["code"], message: string, repair?: string, extra?: Pick<Quarantine, "lockPath" | "lockPid">);
+}

package/dist/tenant/quarantine-error.js

@@ -0,0 +1,15 @@
+/** Typed quarantine raised while opening a Tenant Runtime (A7). */
+export class QuarantineError extends Error {
+    quarantine;
+    constructor(code, message, repair = "nylorun tenant status", extra) {
+        super(message);
+        this.name = "QuarantineError";
+        this.quarantine = {
+            code,
+            message,
+            repair,
+            ...(extra?.lockPath === undefined ? {} : { lockPath: extra.lockPath }),
+            ...(extra?.lockPid === undefined ? {} : { lockPid: extra.lockPid }),
+        };
+    }
+}

package/dist/tenant/quarantine.d.ts

@@ -0,0 +1,35 @@
+import type { Quarantine } from "./types.js";
+/** Typed quarantine failure thrown by stores and migration. */
+export declare class QuarantineError extends Error implements Quarantine {
+    readonly code: Quarantine["code"];
+    readonly repair: string;
+    readonly lockPath?: string;
+    readonly lockPid?: number;
+    constructor(fields: Quarantine);
+    toQuarantine(): Quarantine;
+}
+export declare function isQuarantineError(error: unknown): error is QuarantineError;
+export declare function asQuarantine(error: unknown): Quarantine | undefined;
+/** CLI-facing repair strings for every quarantine code (B9). */
+export declare function repairFor(code: Quarantine["code"], detail?: {
+    tenantId?: string;
+    lockPath?: string;
+    lockPid?: number;
+    migrationPath?: string;
+}): string;
+export declare function quarantine(code: Quarantine["code"], message: string, detail?: {
+    tenantId?: string;
+    lockPath?: string;
+    lockPid?: number;
+    migrationPath?: string;
+}): QuarantineError;
+/** Conflict when create bootstrap material does not match an existing Tenant (HTTP 409). */
+export declare class TenantConflictError extends Error {
+    readonly statusCode: 409;
+    constructor(message?: string);
+}
+/** Delete refused because the Tenant still has live work (HTTP 409). */
+export declare class TenantBusyError extends Error {
+    readonly statusCode: 409;
+    constructor(message?: string);
+}

package/dist/tenant/quarantine.js

@@ -0,0 +1,94 @@
+/** Typed quarantine failure thrown by stores and migration. */
+export class QuarantineError extends Error {
+    code;
+    repair;
+    lockPath;
+    lockPid;
+    constructor(fields) {
+        super(fields.message);
+        this.name = "QuarantineError";
+        this.code = fields.code;
+        this.repair = fields.repair;
+        if (fields.lockPath !== undefined)
+            this.lockPath = fields.lockPath;
+        if (fields.lockPid !== undefined)
+            this.lockPid = fields.lockPid;
+    }
+    toQuarantine() {
+        return {
+            code: this.code,
+            message: this.message,
+            repair: this.repair,
+            ...(this.lockPath !== undefined ? { lockPath: this.lockPath } : {}),
+            ...(this.lockPid !== undefined ? { lockPid: this.lockPid } : {}),
+        };
+    }
+}
+export function isQuarantineError(error) {
+    return error instanceof QuarantineError;
+}
+export function asQuarantine(error) {
+    if (isQuarantineError(error))
+        return error.toQuarantine();
+    if (error &&
+        typeof error === "object" &&
+        "code" in error &&
+        "message" in error &&
+        "repair" in error) {
+        return error;
+    }
+    return undefined;
+}
+/** CLI-facing repair strings for every quarantine code (B9). */
+export function repairFor(code, detail = {}) {
+    const id = detail.tenantId ? ` ${detail.tenantId}` : "";
+    switch (code) {
+        case "locked":
+            return (`nylorun tenant status${id}` +
+                (detail.lockPath !== undefined && detail.lockPid !== undefined
+                    ? ` — stop pid ${detail.lockPid} holding ${detail.lockPath}, or remove a stale lock`
+                    : " — resolve the .runtime-lock conflict"));
+        case "kek-missing":
+            return `nylorun tenant status${id} — restore vault-kek for this Tenant (ciphertext cannot be opened without it)`;
+        case "corrupt":
+            return `nylorun tenant status${id} — repair or restore the Tenant directory from backup`;
+        case "schema-too-new":
+            return `nylorun runtime restart` +
+                `${id ? ` — Tenant${id} needs a newer Host` : " — Host schema is older than this Tenant"}`;
+        case "migration-failed":
+            return detail.migrationPath
+                ? `restore ${detail.migrationPath} over the Tenant files, then nylorun tenant status${id}`
+                : `nylorun tenant status${id} — restore from .migration/ snapshot, then retry`;
+        case "envelope-invalid":
+            return `nylorun tenant status${id} — fix or replace tenant.json so its id matches the directory name`;
+        case "open-timeout":
+            return `nylorun tenant status${id} — open timed out; inspect locks and SQLite, then retry`;
+        case "open-failed":
+            return `nylorun tenant status${id} — inspect Tenant logs and repair before the Host retries open`;
+    }
+}
+export function quarantine(code, message, detail = {}) {
+    return new QuarantineError({
+        code,
+        message,
+        repair: repairFor(code, detail),
+        ...(detail.lockPath !== undefined ? { lockPath: detail.lockPath } : {}),
+        ...(detail.lockPid !== undefined ? { lockPid: detail.lockPid } : {}),
+    });
+}
+/** Conflict when create bootstrap material does not match an existing Tenant (HTTP 409). */
+export class TenantConflictError extends Error {
+    statusCode = 409;
+    constructor(message = "Tenant already exists with different bootstrap material") {
+        super(message);
+        this.name = "TenantConflictError";
+    }
+}
+/** Delete refused because the Tenant still has live work (HTTP 409). */
+export class TenantBusyError extends Error {
+    statusCode = 409;
+    constructor(message = "Tenant has live work; pass activeWork=drain|cancel or retry later") {
+        super(message);
+        this.name = "TenantBusyError";
+    }
+}

package/dist/tenant/reset.d.ts

@@ -0,0 +1,21 @@
+import type { Store } from "../core/store.js";
+import type { ExecutorRegistry } from "../core/executors.js";
+import type { SandboxManager } from "../sandbox/manager.js";
+import type { TenantPaths } from "./types.js";
+export type ResetScope = "sessions" | "sandboxes" | "all";
+export interface ResetTenantContext {
+    store: Store;
+    registry: ExecutorRegistry;
+    sandbox: SandboxManager;
+    paths: TenantPaths;
+    /** Clear in-memory session observers after DB wipe. */
+    clearSessionState: () => void;
+    /** Clear executor SSE streams when registrations are removed. */
+    clearExecutorStreams: () => void;
+}
+/**
+ * Reset Tenant durable state for `scope` (A17).
+ * Caller must have already drained (`activeWork`). Runs SQLite work in one
+ * transaction, then filesystem rename+delete for sandboxes / log as needed.
+ */
+export declare function resetTenant(ctx: ResetTenantContext, scope: ResetScope): Promise<void>;

package/dist/tenant/reset.js

@@ -0,0 +1,125 @@
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+const SESSION_TABLES = [
+    "sessions",
+    "commands",
+    "checkpoints",
+    "effects",
+    "actions",
+];
+/**
+ * Rename `dir` to a sibling, delete the sibling, recreate an empty `dir`.
+ * Failure before rename leaves the original intact; after rename the empty
+ * target is restored so the Tenant layout stays valid (A17).
+ */
+function replaceDirectory(dir) {
+    mkdirSync(dir, { recursive: true });
+    const sibling = `${dir}.resetting`;
+    if (existsSync(sibling))
+        rmSync(sibling, { recursive: true, force: true });
+    renameSync(dir, sibling);
+    try {
+        mkdirSync(dir, { recursive: true });
+        rmSync(sibling, { recursive: true, force: true });
+    }
+    catch (error) {
+        // Best-effort restore if recreation failed.
+        if (!existsSync(dir) && existsSync(sibling)) {
+            try {
+                renameSync(sibling, dir);
+            }
+            catch {
+                /* leave sibling for operator inspection */
+            }
+        }
+        throw error;
+    }
+}
+function clearSessionTables(store) {
+    for (const table of SESSION_TABLES) {
+        store.db.prepare(`DELETE FROM ${table}`).run();
+    }
+    store.db.prepare("DELETE FROM events").run();
+}
+function clearSandboxRows(store) {
+    store.db.prepare("DELETE FROM sandboxes").run();
+}
+function clearDefinitions(store) {
+    store.db.prepare("DELETE FROM definitions").run();
+}
+function clearExecutors(store, registry) {
+    for (const row of registry.list())
+        registry.remove(row.agentId);
+    store.db.prepare("DELETE FROM executors").run();
+}
+/** Delete user-scoped vaults; keep the host vault (model credentials). */
+function clearUserVaults(store) {
+    const userVaults = store.db
+        .prepare(`SELECT id FROM vaults WHERE scope != 'host'`)
+        .all();
+    for (const vault of userVaults) {
+        store.db
+            .prepare(`DELETE FROM vault_credentials WHERE vault_id=?`)
+            .run(vault.id);
+        store.db.prepare(`DELETE FROM vaults WHERE id=?`).run(vault.id);
+    }
+    // Drop audit / idempotency rows that referenced user vaults only when all.
+    // Keep host-model idempotency so seed replay stays stable.
+}
+/**
+ * Reset Tenant durable state for `scope` (A17).
+ * Caller must have already drained (`activeWork`). Runs SQLite work in one
+ * transaction, then filesystem rename+delete for sandboxes / log as needed.
+ */
+export async function resetTenant(ctx, scope) {
+    const clearSessions = scope === "sessions" || scope === "all";
+    const clearSandboxes = scope === "sandboxes" || scope === "all";
+    const clearAll = scope === "all";
+    if (clearSandboxes) {
+        await ctx.sandbox.reconcile(() => false);
+    }
+    ctx.store.tx(() => {
+        if (clearSessions)
+            clearSessionTables(ctx.store);
+        if (clearSandboxes)
+            clearSandboxRows(ctx.store);
+        if (clearAll) {
+            clearDefinitions(ctx.store);
+            clearExecutors(ctx.store, ctx.registry);
+            clearUserVaults(ctx.store);
+        }
+    });
+    if (clearSessions)
+        ctx.clearSessionState();
+    if (clearAll)
+        ctx.clearExecutorStreams();
+    if (clearSandboxes)
+        replaceDirectory(ctx.paths.sandboxes);
+    if (clearAll) {
+        mkdirSync(ctx.paths.logs, { recursive: true });
+        const logSibling = join(ctx.paths.logs, "tenant.log.resetting");
+        if (existsSync(ctx.paths.log)) {
+            if (existsSync(logSibling))
+                rmSync(logSibling, { force: true });
+            renameSync(ctx.paths.log, logSibling);
+            try {
+                writeFileSync(ctx.paths.log, "");
+                rmSync(logSibling, { force: true });
+            }
+            catch (error) {
+                if (!existsSync(ctx.paths.log) && existsSync(logSibling)) {
+                    try {
+                        renameSync(logSibling, ctx.paths.log);
+                    }
+                    catch {
+                        /* leave sibling */
+                    }
+                }
+                throw error;
+            }
+        }
+        else {
+            writeFileSync(ctx.paths.log, "");
+        }
+    }
+}

package/dist/tenant/runtime.d.ts

@@ -0,0 +1,80 @@
+import { type ServerResponse, type IncomingMessage } from "node:http";
+import { type ModelProvider } from "../core/provider.js";
+import type { TenantConfig, TenantHandle, TenantSummary } from "./types.js";
+import type { TenantEnvelope } from "@nylorun/core/contracts";
+import { type AuthorizeResult } from "../vault/service.js";
+/** TENANTS-CCR: test/injection hooks until TenantConfig gains them. */
+export type TenantOpenHooks = {
+    modelProvider?: ModelProvider;
+    vaultKek?: Buffer | string | null;
+    /** When true, create the KEK file on first vault write (tests / new Tenants). */
+    createKekIfMissing?: boolean;
+};
+export declare class TenantRuntime implements TenantHandle {
+    private readonly config;
+    private readonly store;
+    private readonly vault;
+    private kek;
+    private readonly kekPath;
+    private readonly running;
+    private readonly pending;
+    private readonly observers;
+    private readonly executorStreams;
+    private readonly registry;
+    private readonly mcp;
+    private readonly sandbox;
+    private closing;
+    private closed;
+    private readonly lockPath?;
+    private readonly timer;
+    private readonly modelProvider;
+    private readonly useVaultModel;
+    private readonly createKekIfMissing;
+    private readonly flowLimits;
+    readonly envelope: TenantEnvelope;
+    private constructor();
+    static open(config: TenantConfig, hooks?: TenantOpenHooks): Promise<TenantRuntime>;
+    private session;
+    private publish;
+    private send;
+    private notify;
+    /**
+     * Manifest v4 replaced beforeModelCall/afterModelCall with scoped hooks. Turns started under
+     * an older manifest cannot continue, and their hook actions no longer parse, so end them.
+     */
+    private retireLegacyHooks;
+    private expireClaims;
+    private schedule;
+    private execute;
+    private invokeModel;
+    private resolveEffect;
+    /** Journal and dispatch a new flow effect (agent / tool node / fn / verify). */
+    private resolveNewFlowEffect;
+    private scope;
+    private scoped;
+    private requireApplication;
+    private sandboxRouteDeps;
+    private body;
+    private command;
+    private sse;
+    handle(request: IncomingMessage, response: ServerResponse, _url?: URL): Promise<void>;
+    private view;
+    private prepareMcp;
+    private callMcpTool;
+    private callSandboxTool;
+    authorize(sessionId: string, request: {
+        url: string;
+        serverName?: string;
+    }): Promise<AuthorizeResult>;
+    private ensureKek;
+    private dispatchTenant;
+    private dispatchVault;
+    summary(): TenantSummary;
+    drain(activeWork: "drain" | "cancel", timeoutMs?: number): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * Open a Tenant Runtime from an explicit `TenantConfig`. No listen() (A1).
+ * Implements `OpenTenantRuntime`.
+ */
+export declare function openTenantRuntime(config: TenantConfig, hooks?: TenantOpenHooks): Promise<TenantHandle>;