@nylorun/runtime 0.9.0-beta → 0.11.0-beta

package/dist/tenant/sessions.js

@@ -0,0 +1,149 @@
+/**
+ * Session and definition resources: `PUT/GET /v1/agents`, `PUT /v1/sessions/:id` (create or
+ * re-attach vaults), the session list and the session view. Reads use the store's typed
+ * queries; `PUT /v1/sessions/:id` runs in one transaction with the vault attachment checks.
+ */
+import { DefinitionDocumentSchema, } from "@nylorun/core/contracts";
+import { hashManifest } from "@nylorun/core/compatibility";
+import { aggregateWaits, isWorkflowManifest } from "../core/flow-host.js";
+import { canonical } from "../store/canonical.js";
+import { newStreamIncarnation } from "../streams/types.js";
+import { validateSandboxAttach } from "../core/sandbox-routes.js";
+import { sandboxLookup } from "./context.js";
+import { fail } from "./http.js";
+/** A session's creation identity: everything but the request id and vault attachments. */
+const sessionIdentity = (value) => {
+    const { requestId: _requestId, vaultIds: _vaultIds, credentialSelections: _selections, ...body } = value ?? {};
+    return canonical(body);
+};
+export async function listDefinitions(ctx) {
+    const definitions = await ctx.store.tx((t) => t.listDefinitions());
+    return {
+        agents: definitions.map((d) => ({
+            agentId: d.manifest.id,
+            manifest: d.manifest,
+            manifestHash: d.manifestHash,
+            implementationVersion: d.implementationVersion,
+        })),
+    };
+}
+export async function putDefinition(ctx, agentId, body) {
+    if (body.manifest.id !== agentId)
+        fail(400, "Agent id mismatch");
+    DefinitionDocumentSchema.parse(body.manifest);
+    const definition = {
+        ...body,
+        manifestHash: hashManifest(body.manifest),
+    };
+    await ctx.store.tx((t) => t.put("definitions", agentId, definition));
+    return {
+        agentId,
+        manifestHash: definition.manifestHash,
+        implementationVersion: body.implementationVersion,
+    };
+}
+export async function listSessions(ctx, agentId) {
+    const sessions = await ctx.store.tx((t) => t.listSessions(agentId === null ? {} : { agentId }));
+    return {
+        sessions: sessions.map((s) => ({
+            id: s.id,
+            agentId: s.agentId,
+            ownerUserId: s.ownerUserId,
+            status: s.status,
+            activeTurnId: s.activeTurnId,
+        })),
+    };
+}
+/** Create a session from its definition, or re-attach vaults to an identical one. */
+export function putSession(ctx, id, body) {
+    const vaultIds = body.vaultIds ?? [];
+    const credentialSelections = body.credentialSelections ?? [];
+    return ctx.store.tx(async (t) => {
+        const prior = await t.lockSession(id);
+        const definition = prior === undefined || body.sandbox
+            ? (await t.get("definitions", body.agentId)) ??
+                fail(404, "Definition not found")
+            : undefined;
+        const sandboxOwnerId = body.sandbox
+            ? validateSandboxAttach(body, (definition ?? prior).manifest, await sandboxLookup(t, body.sandbox.session))
+            : undefined;
+        await ctx.vault.assertAttachment(t, body.ownerUserId, vaultIds, credentialSelections);
+        if (prior) {
+            if (sessionIdentity(prior.creation) !== sessionIdentity(body))
+                fail(409, "Session already exists with different creation parameters");
+            prior.vaultIds = vaultIds;
+            prior.credentialSelections = credentialSelections;
+            prior.creation = body;
+            if (sandboxOwnerId !== undefined)
+                prior.sandboxOwnerId = sandboxOwnerId;
+            await t.put("sessions", id, prior);
+            await ctx.vault.recordAttachment(t, id, vaultIds);
+            return prior;
+        }
+        const created = {
+            id,
+            agentId: body.agentId,
+            ownerUserId: body.ownerUserId,
+            manifest: definition.manifest,
+            manifestHash: definition.manifestHash,
+            implementationVersion: definition.implementationVersion,
+            info: body.info,
+            status: "idle",
+            activeTurnId: null,
+            creation: body,
+            vaultIds,
+            credentialSelections,
+            pluginRoots: definition.pluginRoots ?? {},
+            ...(sandboxOwnerId !== undefined ? { sandboxOwnerId } : {}),
+            streamIncarnation: newStreamIncarnation(),
+        };
+        await t.put("sessions", id, created);
+        await ctx.vault.recordAttachment(t, id, vaultIds);
+        return created;
+    });
+}
+/** The session resource returned by `GET`/`PUT /v1/sessions/:id`. */
+export async function sessionView(t, s) {
+    let waits = Array.isArray(s.waits)
+        ? s.waits.map((call) => ({
+            invocationId: call.invocationId,
+            interaction: call.interaction,
+            wait: call.wait,
+            status: call.status,
+        }))
+        : s.waits;
+    if (isWorkflowManifest(s.manifest)) {
+        const aggregated = await aggregateWaits({ t, workflowSessionId: s.id });
+        if (aggregated.length > 0)
+            waits = aggregated;
+    }
+    const actions = await t.actionsForSession(s.id, {
+        statuses: ["pending", "claimed", "uncertain"],
+    });
+    const uncertain = await t.effectsForSession(s.id, {
+        statuses: ["uncertain"],
+    });
+    return {
+        id: s.id,
+        agentId: s.agentId,
+        ownerUserId: s.ownerUserId,
+        manifestHash: s.manifestHash,
+        implementationVersion: s.implementationVersion,
+        status: s.status,
+        activeTurnId: s.activeTurnId,
+        vaultIds: s.vaultIds ?? [],
+        credentialSelections: s.credentialSelections ?? [],
+        sandboxOwnerId: s.sandboxOwnerId ?? null,
+        mcpSnapshot: s.mcpSnapshot ?? null,
+        mcpDiagnostics: s.mcpDiagnostics ?? [],
+        waits,
+        error: s.error,
+        actions,
+        uncertainEffects: uncertain.map((e) => ({
+            effectId: e.request.effectId,
+            turnId: e.request.turnId,
+            kind: e.request.kind,
+            error: e.error,
+        })),
+    };
+}

package/dist/tenant/status.d.ts

@@ -0,0 +1,37 @@
+import type { SeedTenantConfigRequest, SeedTenantConfigResponse, TenantStatus } from "@nylorun/core/contracts";
+import type { SessionStore } from "../store/types.js";
+import type { ExecutorRegistry } from "../core/executors.js";
+import type { VaultService } from "../vault/service.js";
+import type { SandboxManager } from "../sandbox/manager.js";
+import type { TenantConfig } from "./types.js";
+import type { TenantEnvelope } from "@nylorun/core/contracts";
+import type { StuckInvocation } from "../execution/types.js";
+import type { StreamsStatus } from "./streams.js";
+export interface TenantStatusContext {
+    envelope: TenantEnvelope;
+    config: TenantConfig;
+    store: SessionStore;
+    registry: ExecutorRegistry;
+    vault: VaultService;
+    sandbox: SandboxManager;
+    closing: boolean;
+    modelConfigured: boolean;
+    executorStreams: Map<string, Set<unknown>>;
+    /**
+     * This Tenant's execution invocations that need an operator (`TenantExecution`). Absent
+     * when the execution cannot report them.
+     */
+    stuckInvocations?: () => Promise<StuckInvocation[]>;
+    /** This Tenant's Durable Streams status (`streamsStatus` in `streams.ts`). */
+    streamsStatus?: () => Promise<StreamsStatus>;
+}
+/** Build `TenantStatusSchema` with secrets redacted (A14). */
+export declare function buildTenantStatus(ctx: TenantStatusContext): Promise<TenantStatus>;
+/**
+ * Insert-if-absent Tenant configuration seed (A18).
+ * Response lists field names only; never secret values.
+ */
+export declare function seedTenantConfig(ctx: {
+    store: SessionStore;
+    vault: VaultService;
+}, body: SeedTenantConfigRequest): Promise<SeedTenantConfigResponse>;

package/dist/tenant/status.js

@@ -0,0 +1,130 @@
+import { FIXTURE_MODEL_SETTING, seedFixtureModel } from "./model-setting.js";
+/** How long status waits for the execution to list stuck invocations. */
+const STUCK_TIMEOUT_MS = 5000;
+/** `TenantStatus.execution`: paused and backing-off invocations, or why they are unknown. */
+async function executionStatus(stuckInvocations) {
+    let timer;
+    try {
+        const stuck = await Promise.race([
+            stuckInvocations(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error("Timed out listing stuck invocations")), STUCK_TIMEOUT_MS);
+            }),
+        ]);
+        return {
+            stuckInvocations: stuck.map((invocation) => ({
+                id: invocation.id,
+                status: invocation.status,
+                service: invocation.service,
+                handler: invocation.handler,
+                key: invocation.key,
+                retryCount: invocation.retryCount,
+                ...(invocation.lastFailure !== undefined
+                    ? { lastFailure: invocation.lastFailure }
+                    : {}),
+                ...(invocation.modifiedAt !== undefined
+                    ? { modifiedAt: invocation.modifiedAt }
+                    : {}),
+            })),
+        };
+    }
+    catch (error) {
+        return {
+            stuckInvocations: [],
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Build `TenantStatusSchema` with secrets redacted (A14). */
+export async function buildTenantStatus(ctx) {
+    const health = await ctx.store.health();
+    const { counts, definitions } = await ctx.store.tx(async (t) => ({
+        counts: await t.counts(),
+        definitions: await t.listDefinitions(),
+    }));
+    const [modelView, sandboxReport, execution, streams] = await Promise.all([
+        ctx.vault.getHostModel(),
+        ctx.sandbox.report(),
+        ctx.stuckInvocations ? executionStatus(ctx.stuckInvocations) : undefined,
+        ctx.streamsStatus?.(),
+    ]);
+    const definitionIds = new Set(definitions
+        .map((d) => d.manifest?.id)
+        .filter((id) => typeof id === "string"));
+    const executorIds = new Set(ctx.registry.list().map((e) => e.agentId));
+    const agentIds = new Set([...definitionIds, ...executorIds]);
+    const agents = [...agentIds].sort().map((agentId) => {
+        const record = ctx.registry.get(agentId);
+        return {
+            agentId,
+            registered: definitionIds.has(agentId),
+            connected: !!record &&
+                (ctx.executorStreams.get(record.tokenHash)?.size ?? 0) > 0,
+        };
+    });
+    return {
+        tenant: ctx.envelope,
+        path: ctx.config.paths.root,
+        checks: {
+            store: health.schemaVersion > 0,
+            scheduler: !ctx.closing,
+            model: ctx.modelConfigured || modelView.configured,
+            executors: true,
+            schema: health.ok,
+        },
+        model: modelView,
+        agents,
+        counts: {
+            sessions: counts.sessions,
+            runningSessions: counts.runningSessions,
+            pendingActions: counts.pendingActions,
+            uncertainEffects: counts.uncertainEffects,
+        },
+        sandbox: {
+            backend: sandboxReport.backend,
+            retained: counts.sandboxes,
+        },
+        ...(execution ? { execution } : {}),
+        ...(streams ? { streams } : {}),
+    };
+}
+/**
+ * Insert-if-absent Tenant configuration seed (A18).
+ * Response lists field names only; never secret values.
+ */
+export async function seedTenantConfig(ctx, body) {
+    const applied = [];
+    const kept = [];
+    const backend = body.sandbox?.backend;
+    if (backend) {
+        const inserted = await ctx.store.tx(async (t) => {
+            if ((await t.getSetting("sandbox.backend")) !== undefined)
+                return false;
+            await t.putSetting("sandbox.backend", backend);
+            return true;
+        });
+        (inserted ? applied : kept).push("sandbox.backend");
+    }
+    if (body.fixtureModel) {
+        const inserted = await ctx.store.tx((t) => seedFixtureModel(t));
+        (inserted ? applied : kept).push(FIXTURE_MODEL_SETTING);
+    }
+    if (body.model) {
+        const current = await ctx.vault.getHostModel();
+        if (current.configured) {
+            kept.push("model");
+        }
+        else {
+            await ctx.vault.putHostModel({
+                requestId: body.requestId,
+                idempotencyKey: `seed-model:${body.requestId}`,
+                ...body.model,
+            });
+            applied.push("model");
+        }
+    }
+    return { applied, kept };
+}

package/dist/tenant/store-memory.d.ts

@@ -0,0 +1,16 @@
+import type { SessionStore } from "../store/types.js";
+import { type Logger, type OpenTenantRuntime, type TenantConfig, type TenantStore } from "./types.js";
+export interface MemoryTenantStoreOptions {
+    /** When set, each Tenant's directory under this Host root lives as long as the Tenant. */
+    hostRoot?: string;
+    openRuntime: OpenTenantRuntime;
+    configFor: (tenantId: string) => TenantConfig;
+    logger?: Logger;
+}
+export type MemoryTenantStore = TenantStore & {
+    /** Test helper: current Tenant ids. */
+    ids(): string[];
+    /** Test helper: a Session Store on a Tenant's data, as another process would open it. */
+    sessionStore(id: string): SessionStore;
+};
+export declare function createMemoryTenantStore(options: MemoryTenantStoreOptions): MemoryTenantStore;

package/dist/tenant/store-memory.js

@@ -0,0 +1,111 @@
+/**
+ * An in-memory Tenant store for tests: each Tenant is a `MemoryStoreData` (its Session
+ * Store's data) and an envelope. It behaves like the Postgres store (`store-pg.ts`): the
+ * Tenant directory under the Host root, when one is given, is created with the Tenant and
+ * removed with it, and `open` hands the Tenant Runtime a fresh Session Store on the Tenant's
+ * data. Not a supported profile.
+ */
+import { mkdirSync, rmSync } from "node:fs";
+import { isTenantId } from "@nylorun/core/compatibility";
+import { MEMORY_SCHEMA_VERSION, MemorySessionStore, MemoryStoreData, } from "../store/memory.js";
+import { quarantine } from "./quarantine.js";
+import { parseEnvelope } from "./envelope.js";
+import { tenantPaths } from "./paths.js";
+import { bootstrapPrincipal, bootstrapPrincipalMatches } from "./principals.js";
+import { TenantNotFoundError, } from "./types.js";
+export function createMemoryTenantStore(options) {
+    const records = new Map();
+    function sessionStore(id, data) {
+        return new MemorySessionStore({
+            tenantId: id,
+            onError: (error) => options.logger?.error("post-commit step failed", {
+                message: error instanceof Error ? error.message : String(error),
+            }),
+        }, data);
+    }
+    function makeDirectory(id) {
+        if (!options.hostRoot)
+            return;
+        const p = tenantPaths(options.hostRoot, id);
+        mkdirSync(p.root, { recursive: true, mode: 0o700 });
+        for (const dir of [p.home, p.tmp, p.sandboxes, p.pluginData, p.logs])
+            mkdirSync(dir, { recursive: true });
+    }
+    function removeDirectory(id) {
+        if (options.hostRoot)
+            rmSync(tenantPaths(options.hostRoot, id).root, {
+                recursive: true,
+                force: true,
+            });
+    }
+    async function withStore(id, data, fn) {
+        const store = sessionStore(id, data);
+        try {
+            return await fn(store);
+        }
+        finally {
+            await store.close();
+        }
+    }
+    return {
+        ids() {
+            return [...records.keys()];
+        },
+        sessionStore(id) {
+            const record = records.get(id);
+            if (!record)
+                throw new TenantNotFoundError(id);
+            return sessionStore(id, record.data);
+        },
+        async enumerate() {
+            return [...records.keys()].filter(isTenantId).sort();
+        },
+        async readEnvelope(id) {
+            const record = records.get(id);
+            if (!record)
+                throw new TenantNotFoundError(id);
+            return parseEnvelope(record.envelope, id);
+        },
+        async create(envelope, bootstrap) {
+            const parsed = parseEnvelope({ ...envelope, schemaVersion: MEMORY_SCHEMA_VERSION }, envelope.id);
+            if (records.has(parsed.id))
+                return "exists";
+            makeDirectory(parsed.id);
+            const data = new MemoryStoreData();
+            await withStore(parsed.id, data, (store) => store.tx((t) => bootstrapPrincipal(t, bootstrap)));
+            records.set(parsed.id, { envelope: parsed, data });
+            return "created";
+        },
+        async bootstrapMatches(id, bootstrap) {
+            const record = records.get(id);
+            if (!record)
+                return false;
+            return withStore(id, record.data, (store) => store.tx((t) => bootstrapPrincipalMatches(t, bootstrap)));
+        },
+        async open(id) {
+            const record = records.get(id);
+            if (!record)
+                throw new TenantNotFoundError(id);
+            if (record.envelope.schemaVersion > MEMORY_SCHEMA_VERSION)
+                throw quarantine("schema-too-new", `Tenant schema version ${record.envelope.schemaVersion} is newer than this Runtime's ${MEMORY_SCHEMA_VERSION}`, { tenantId: id });
+            makeDirectory(id);
+            const store = sessionStore(id, record.data);
+            try {
+                return await options.openRuntime({ ...options.configFor(id), tenantId: id }, { store, envelope: record.envelope });
+            }
+            catch (error) {
+                await store.close().catch(() => undefined);
+                throw error;
+            }
+        },
+        async trash(id) {
+            records.delete(id);
+            removeDirectory(id);
+        },
+        async removePartial(id) {
+            if (records.has(id))
+                return;
+            removeDirectory(id);
+        },
+    };
+}

package/dist/tenant/store-pg.d.ts

@@ -0,0 +1,15 @@
+import type { PostgresClient } from "../store/postgres/connect.js";
+import type { Migration } from "../store/postgres/migrations/index.js";
+import { type Logger, type OpenTenantRuntime, type TenantConfig, type TenantStore } from "./types.js";
+export interface PostgresTenantStoreOptions {
+    hostRoot: string;
+    /** The Host's pool. The store never ends it. */
+    sql: PostgresClient;
+    /** Opens the Tenant Runtime on a store the catalog opened; the Runtime then owns it. */
+    openRuntime: OpenTenantRuntime;
+    configFor: (tenantId: string) => TenantConfig;
+    logger?: Logger;
+    /** Tests only: the migrations this Runtime knows. */
+    migrations?: readonly Migration[];
+}
+export declare function createPostgresTenantStore(options: PostgresTenantStoreOptions): TenantStore;

package/dist/tenant/store-pg.js

@@ -0,0 +1,140 @@
+/**
+ * The Tenant store over the Postgres Tenant catalog (architecture §8.1, §8.2).
+ *
+ * A Tenant exists when its schema `tenant_<id>` exists (`store/postgres/tenants.ts`); the
+ * envelope is a row in it, so this store keeps no registry. What stays on the Host root is
+ * the Tenant directory `tenants/<id>/`: the vault key (`vault-kek`), `plugin-data/`, `logs/`,
+ * and the private `home/`, `tmp/` and `sandboxes/`. It is created with the Tenant and removed
+ * with it; nothing in it says whether the Tenant exists.
+ *
+ * - `create` makes the directory, then creates, migrates and bootstraps the schema in one
+ *   transaction. A schema that already exists is `exists`; the module compares its bootstrap.
+ * - `open` migrates an older schema forward and opens the Tenant Runtime on the schema's
+ *   Session Store. A missing schema is `TenantNotFoundError`; a schema newer than this
+ *   Runtime, a failed migration, an unreadable envelope or vault ciphertext without its key
+ *   throws that quarantine. A failure outside the Tenant (Postgres unreachable, its sweep
+ *   not armed) is `TenantUnavailableError`, which the module does not cache.
+ * - `trash` drops the schema and removes the directory. There is no `trash/` copy: the key
+ *   is useless without the schema.
+ */
+import { mkdirSync, rmSync } from "node:fs";
+import { tenantSchemaName } from "../store/postgres/names.js";
+import { createPostgresTenantCatalog } from "../store/postgres/tenants.js";
+import { tenantPaths } from "./paths.js";
+import { QuarantineError, TenantConflictError } from "./quarantine.js";
+import { TenantNotFoundError, TenantUnavailableError, } from "./types.js";
+/** Repair instructions for a Postgres Tenant, naming its schema. */
+function repairFor(code, tenantId) {
+    const status = `nylo tenant status ${tenantId}`;
+    const schema = tenantSchemaName(tenantId);
+    switch (code) {
+        case "schema-too-new":
+            return `${status} — schema ${schema} was migrated by a newer Runtime; run that version or newer`;
+        case "migration-failed":
+            return `${status} — inspect the Runtime log for the failed migration of ${schema}, fix it, then restart the Runtime`;
+        case "envelope-invalid":
+            return `${status} — the tenant table of schema ${schema} is missing or invalid; restore the schema from a Postgres backup`;
+        case "kek-missing":
+            return `${status} — restore vault-kek under the Tenant directory (ciphertext cannot be opened without it)`;
+        default:
+            return `${status} — inspect the Runtime log and Postgres, then restart the Runtime`;
+    }
+}
+function unavailable(tenantId, cause) {
+    return cause instanceof TenantUnavailableError
+        ? cause
+        : new TenantUnavailableError(tenantId, { cause });
+}
+function quarantined(reason, tenantId) {
+    return new QuarantineError({ ...reason, repair: repairFor(reason.code, tenantId) });
+}
+export function createPostgresTenantStore(options) {
+    const catalog = createPostgresTenantCatalog({
+        sql: options.sql,
+        ...(options.migrations ? { migrations: options.migrations } : {}),
+        onError: (error) => options.logger?.error("post-commit step failed", {
+            message: error instanceof Error ? error.message : String(error),
+        }),
+    });
+    const paths = (id) => tenantPaths(options.hostRoot, id);
+    function makeDirectory(id) {
+        const p = paths(id);
+        mkdirSync(p.root, { recursive: true, mode: 0o700 });
+        for (const dir of [p.home, p.tmp, p.sandboxes, p.pluginData, p.logs])
+            mkdirSync(dir, { recursive: true });
+    }
+    async function readEnvelope(id) {
+        try {
+            return await catalog.readEnvelope(id);
+        }
+        catch (error) {
+            if (!(error instanceof QuarantineError))
+                throw unavailable(id, error);
+            // Dropped since it was listed (deleted by another process).
+            if (!(await catalog.tenantExists(id).catch(() => true)))
+                throw new TenantNotFoundError(id);
+            throw quarantined(error.toQuarantine(), id);
+        }
+    }
+    return {
+        enumerate: () => catalog.listTenantIds(),
+        readEnvelope,
+        async create(envelope, bootstrap) {
+            makeDirectory(envelope.id);
+            try {
+                const result = await catalog.createTenant({ envelope, principals: bootstrap });
+                return result.status;
+            }
+            catch (error) {
+                // An existing Tenant with other bootstrap material; the module reports the conflict.
+                if (error instanceof TenantConflictError)
+                    return "exists";
+                throw error;
+            }
+        },
+        bootstrapMatches: (id, bootstrap) => catalog.bootstrapMatches(id, bootstrap),
+        async open(id) {
+            const result = await catalog
+                .openTenant(id)
+                .catch((error) => {
+                throw unavailable(id, error);
+            });
+            if (result.status === "not-found")
+                throw new TenantNotFoundError(id);
+            if (result.status === "quarantined")
+                throw quarantined(result.reason, id);
+            if (result.migrated.from !== result.migrated.to)
+                options.logger?.info("tenant schema migrated", {
+                    tenantId: id,
+                    from: result.migrated.from,
+                    to: result.migrated.to,
+                });
+            try {
+                makeDirectory(id);
+                const config = options.configFor(id);
+                return await options.openRuntime({ ...config, tenantId: id }, { store: result.store, envelope: result.envelope });
+            }
+            catch (error) {
+                await result.store.close().catch(() => undefined);
+                // The Runtime's own quarantines (`kek-missing`) get this store's repair wording.
+                const reason = error?.quarantine;
+                if (reason)
+                    throw quarantined(reason, id);
+                if (error instanceof QuarantineError)
+                    throw error;
+                // Anything else failed outside the Tenant (Postgres, arming its sweep in Restate):
+                // the next use tries again rather than quarantining it.
+                throw unavailable(id, error);
+            }
+        },
+        async trash(id) {
+            await catalog.deleteTenant(id);
+            rmSync(paths(id).root, { recursive: true, force: true });
+        },
+        async removePartial(id) {
+            if (await catalog.tenantExists(id))
+                return;
+            rmSync(paths(id).root, { recursive: true, force: true });
+        },
+    };
+}