@happyvertical/smrt-app-shell 0.0.0-stage → 0.60.16

package/dist/lib/objects/AssistantThread.js

@@ -0,0 +1,44 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { field, SmrtCollection, SmrtObject, smrt, } from '@happyvertical/smrt-core';
+/**
+ * One assistant conversation (shell.db). Written only by the assistant's
+ * thread store (`$lib/server/assistant/threads`), owner scoped; no generated
+ * surface.
+ */
+let AssistantThread = class AssistantThread extends SmrtObject {
+    /** The owner's user id. */
+    ownerId = '';
+    title = '';
+    createdAt = '';
+    updatedAt = '';
+};
+__decorate([
+    field({ type: 'text' })
+], AssistantThread.prototype, "ownerId", void 0);
+__decorate([
+    field({ type: 'text' })
+], AssistantThread.prototype, "title", void 0);
+__decorate([
+    field({ type: 'text' })
+], AssistantThread.prototype, "createdAt", void 0);
+__decorate([
+    field({ type: 'text' })
+], AssistantThread.prototype, "updatedAt", void 0);
+AssistantThread = __decorate([
+    smrt({
+        tableName: 'assistant_threads',
+        api: false,
+        mcp: false,
+        cli: false,
+        conflictColumns: ['id'],
+    })
+], AssistantThread);
+export { AssistantThread };
+export class AssistantThreadCollection extends SmrtCollection {
+    static _itemClass = AssistantThread;
+}

package/dist/lib/objects/index.d.ts

@@ -0,0 +1,5 @@
+export { App, AppCollection } from './App.ts';
+export { Approval, ApprovalCollection } from './Approval.ts';
+export { AppVersion, AppVersionCollection } from './AppVersion.ts';
+export { AssistantMessage, AssistantMessageCollection, } from './AssistantMessage.ts';
+export { AssistantThread, AssistantThreadCollection, } from './AssistantThread.ts';

package/dist/lib/objects/index.js

@@ -0,0 +1,5 @@
+export { App, AppCollection } from "./App.js";
+export { Approval, ApprovalCollection } from "./Approval.js";
+export { AppVersion, AppVersionCollection } from "./AppVersion.js";
+export { AssistantMessage, AssistantMessageCollection, } from "./AssistantMessage.js";
+export { AssistantThread, AssistantThreadCollection, } from "./AssistantThread.js";

package/dist/lib/server/approvals.d.ts

@@ -0,0 +1,69 @@
+import type { Command, Plan } from '../../engine/index.ts';
+import { type Approval } from '../objects/Approval.ts';
+/** What an approval runs once the owner says yes. */
+export type ApprovalAction = {
+    kind: 'command';
+    command: Command;
+} | {
+    kind: 'tool';
+    name: string;
+    args: Record<string, unknown>;
+} | {
+    kind: 'rest';
+    method: string;
+    url: string;
+    body?: string;
+} | {
+    kind: 'record-delete';
+    model: string;
+    id: string;
+};
+/** The answer a refused-until-approved call gives instead of applying. */
+export interface PendingApproval {
+    status: 'pending_approval';
+    approvalId: string;
+    summary: string;
+    preview: unknown;
+}
+/** Run `fn`, collecting every approval `requestApproval` issues inside it. */
+export declare function collectIssuedApprovals<T>(fn: () => Promise<T>): Promise<{
+    value: T;
+    issued: PendingApproval[];
+}>;
+export interface ApprovalView {
+    id: string;
+    status: Approval['status'];
+    summary: string;
+    preview: unknown;
+    action: ApprovalAction | null;
+    requestedBy: string;
+    decidedBy: string;
+    decidedAt: string;
+    result: unknown;
+    createdAt: string;
+}
+export interface ApprovalOutcome {
+    id: string;
+    status: Approval['status'];
+    result?: unknown;
+    error?: string;
+}
+export declare function actionKey(action: ApprovalAction): string;
+/**
+ * Record a pending approval for `action`. An identical pending action reuses
+ * its row, so retrying a refused call never piles up cards.
+ */
+export declare function requestApproval(action: ApprovalAction, plan: Plan, requestedBy: string): Promise<PendingApproval>;
+/** One approval as stored, or null. */
+export declare function getApprovalView(id: string): Promise<ApprovalView | null>;
+export declare function listApprovalViews(filter?: {
+    status?: Approval['status'];
+}): Promise<ApprovalView[]>;
+export declare function pendingApprovalCount(): Promise<number>;
+/**
+ * Decide an approval. CALL ONLY FROM `Approval.decide` (which has checked the
+ * owner): this is the single place the engine's `approved: true` is set.
+ */
+/** The failure text when the host RETURNED an error instead of throwing. */
+export declare function returnedFailure(kind: string, result: unknown): string | undefined;
+export declare function decideApproval(id: string, approve: boolean, decidedBy: string): Promise<ApprovalOutcome>;

package/dist/lib/server/approvals.js

@@ -0,0 +1,239 @@
+// The approval gate. A risky builder command, app tool call or REST DELETE
+// does not run: it becomes an `Approval` row for the owner. Only
+// `decideApproval` (called from `Approval.decide`) ever passes the engine's
+// `approved: true`; nothing taken from a request body can set it.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash } from 'node:crypto';
+import { ApprovalCollection } from "../objects/Approval.js";
+import { publish } from "./events.js";
+import { getHost, getShellDb } from "./host.js";
+// Out-of-band record of the approvals a call issued. `requestApproval` is the
+// only writer, so a caller (the assistant's turn loop) can tell "this call
+// became an Approval" from a tool result whose text merely looks like one.
+const issuedScope = new AsyncLocalStorage();
+/** Run `fn`, collecting every approval `requestApproval` issues inside it. */
+export async function collectIssuedApprovals(fn) {
+    const issued = [];
+    const value = await issuedScope.run(issued, fn);
+    return { value, issued };
+}
+const MAX_RESULT_CHARS = 64_000;
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const o = value;
+        return `{${Object.keys(o)
+            .filter((k) => o[k] !== undefined)
+            .sort()
+            .map((k) => `${JSON.stringify(k)}:${canonical(o[k])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+export function actionKey(action) {
+    return createHash('sha256').update(canonical(action)).digest('hex');
+}
+function parseJson(text) {
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/** The ORM may hydrate a timestamp-looking text column as a Date. */
+function iso(value) {
+    return value instanceof Date ? value.toISOString() : String(value ?? '');
+}
+function view(row) {
+    return {
+        id: row.id,
+        status: row.status,
+        summary: row.summary,
+        preview: parseJson(row.preview),
+        action: parseJson(row.command),
+        requestedBy: row.requestedBy,
+        decidedBy: row.decidedBy,
+        decidedAt: iso(row.decidedAt),
+        result: parseJson(row.result),
+        createdAt: iso(row.createdAt),
+    };
+}
+async function approvals() {
+    return ApprovalCollection.create({ db: await getShellDb() });
+}
+/**
+ * Record a pending approval for `action`. An identical pending action reuses
+ * its row, so retrying a refused call never piles up cards.
+ */
+export async function requestApproval(action, plan, requestedBy) {
+    const key = actionKey(action);
+    const coll = await approvals();
+    const existing = (await coll.list({ where: { actionKey: key, status: 'pending' }, limit: 1 }))[0];
+    const row = existing ??
+        (await (async () => {
+            const created = await coll.create({
+                command: JSON.stringify(action),
+                actionKey: key,
+                summary: plan.summary,
+                // Flat: the Approval card reads `preview.model`, `preview.code`, ...
+                preview: JSON.stringify({
+                    ...(plan.preview ?? {}),
+                    ...(plan.affectedMethods
+                        ? { affectedMethods: plan.affectedMethods }
+                        : {}),
+                }),
+                status: 'pending',
+                requestedBy,
+                createdAt: new Date().toISOString(),
+            });
+            await created.save();
+            publish({
+                type: 'approval',
+                id: created.id,
+                status: 'pending',
+                summary: plan.summary,
+            });
+            return created;
+        })());
+    const v = view(row);
+    const pending = {
+        status: 'pending_approval',
+        approvalId: v.id,
+        summary: v.summary,
+        preview: v.preview,
+    };
+    issuedScope.getStore()?.push(pending);
+    return pending;
+}
+/** One approval as stored, or null. */
+export async function getApprovalView(id) {
+    const row = await (await approvals()).get(id);
+    return row ? view(row) : null;
+}
+export async function listApprovalViews(filter = {}) {
+    const coll = await approvals();
+    const rows = await coll.list({
+        ...(filter.status ? { where: { status: filter.status } } : {}),
+        limit: 500,
+    });
+    return rows.map(view).sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1));
+}
+export async function pendingApprovalCount() {
+    return (await listApprovalViews({ status: 'pending' })).length;
+}
+const inFlight = new Set();
+function isAction(v) {
+    const a = v;
+    if (!a || typeof a !== 'object')
+        return false;
+    if (a.kind === 'command')
+        return !!a.command && typeof a.command.type === 'string';
+    if (a.kind === 'tool')
+        return typeof a.name === 'string' && typeof a.args === 'object';
+    if (a.kind === 'rest')
+        return typeof a.method === 'string' && typeof a.url === 'string';
+    if (a.kind === 'record-delete')
+        return typeof a.model === 'string' && typeof a.id === 'string';
+    return false;
+}
+/**
+ * Decide an approval. CALL ONLY FROM `Approval.decide` (which has checked the
+ * owner): this is the single place the engine's `approved: true` is set.
+ */
+/** The failure text when the host RETURNED an error instead of throwing. */
+export function returnedFailure(kind, result) {
+    const r = result;
+    if (kind === 'tool' && r?.isError) {
+        const first = Array.isArray(r.content)
+            ? r.content[0]
+            : undefined;
+        return first?.text?.slice(0, 500) || 'the tool reported an error';
+    }
+    if (kind === 'rest' && typeof r?.status === 'number') {
+        if (r.status < 200 || r.status > 299) {
+            return `the request failed with status ${r.status}`;
+        }
+    }
+    return undefined;
+}
+export async function decideApproval(id, approve, decidedBy) {
+    const coll = await approvals();
+    const row = await coll.get(id);
+    if (!row)
+        throw new Error('approval not found');
+    if (row.status !== 'pending' || inFlight.has(id))
+        throw new Error(`approval is already ${row.status}`);
+    inFlight.add(id);
+    try {
+        const decidedAt = new Date().toISOString();
+        if (!approve) {
+            row.status = 'denied';
+            row.decidedBy = decidedBy;
+            row.decidedAt = decidedAt;
+            await row.save();
+            publish({
+                type: 'approval',
+                id,
+                status: 'denied',
+                summary: row.summary,
+            });
+            return { id, status: 'denied' };
+        }
+        const action = parseJson(row.command);
+        if (!isAction(action))
+            throw new Error('the stored action is invalid');
+        // Mark it taken before running anything: a second decide sees "approved".
+        row.status = 'approved';
+        row.decidedBy = decidedBy;
+        row.decidedAt = decidedAt;
+        await row.save();
+        let result;
+        let error;
+        try {
+            const host = await getHost();
+            if (action.kind === 'command')
+                result = await host.execute(action.command, {
+                    author: row.requestedBy || decidedBy,
+                    approved: true,
+                });
+            else if (action.kind === 'tool')
+                result = await host.callAppTool(action.name, action.args, {
+                    approved: true,
+                });
+            else if (action.kind === 'record-delete')
+                result = await host.remove(action.model, action.id);
+            else
+                result = await host.rest({ method: action.method, url: action.url, body: action.body }, { approved: true });
+            // The host reports some failures by returning them (a tool's isError,
+            // a non-2xx REST response) instead of throwing: they did not apply.
+            if (error === undefined)
+                error = returnedFailure(action.kind, result);
+        }
+        catch (e) {
+            error = e instanceof Error ? e.message : String(e);
+        }
+        row.status = error === undefined ? 'approved' : 'failed';
+        const text = JSON.stringify(error === undefined ? result : { error });
+        row.result =
+            text.length > MAX_RESULT_CHARS
+                ? JSON.stringify({ truncated: true })
+                : (text ?? '');
+        await row.save();
+        publish({
+            type: 'approval',
+            id,
+            status: row.status,
+            summary: row.summary,
+        });
+        return error === undefined
+            ? { id, status: 'approved', result }
+            : { id, status: 'failed', error };
+    }
+    finally {
+        inFlight.delete(id);
+    }
+}

package/dist/lib/server/builder.d.ts

@@ -0,0 +1,16 @@
+import { type Command, type ExecuteResult } from '../../engine/index.ts';
+import { type PendingApproval } from './approvals.ts';
+export type BuilderResult = ExecuteResult | PendingApproval;
+/** Run a command for `author`. Never passes `approved` (see approvals.ts). */
+export declare function runCommand(command: Command, author: string): Promise<BuilderResult>;
+/** Run an app tool; a risky one (`<model>_delete`) becomes an approval. */
+export declare function runAppTool(name: string, args: Record<string, unknown>, author: string): Promise<import("../../engine/host.ts").ToolResult | PendingApproval>;
+/** Pass a request to the app's generated REST; a DELETE becomes an approval. */
+export declare function runRest(req: {
+    method: string;
+    url: string;
+    body?: string;
+}, author: string): Promise<import("../../engine/host.ts").RestResult | PendingApproval>;
+export declare function isPending(x: unknown): x is PendingApproval;
+/** Delete a record: always an approval (nothing is deleted until decided). */
+export declare function requestRecordDelete(model: string, id: string, author: string): Promise<PendingApproval>;

package/dist/lib/server/builder.js

@@ -0,0 +1,71 @@
+// Builder operations: run an engine command, or, if it is risky, turn it into
+// an Approval and return `pending_approval` without changing anything.
+import { ApprovalRequiredError, } from "../../engine/index.js";
+import { requestApproval, } from "./approvals.js";
+import { getHost } from "./host.js";
+/** Run a command for `author`. Never passes `approved` (see approvals.ts). */
+export async function runCommand(command, author) {
+    const host = await getHost();
+    try {
+        return await host.execute(command, { author });
+    }
+    catch (e) {
+        if (e instanceof ApprovalRequiredError) {
+            // An undo is approved for the version it was planned against: if the app
+            // moves on first, approving it must not undo something else.
+            const version = e.plan.preview
+                ?.version;
+            const pinned = command.type === 'undo' && typeof version === 'number'
+                ? { type: 'undo', version }
+                : command;
+            return requestApproval({ kind: 'command', command: pinned }, e.plan, author);
+        }
+        throw e;
+    }
+}
+/** Run an app tool; a risky one (`<model>_delete`) becomes an approval. */
+export async function runAppTool(name, args, author) {
+    const host = await getHost();
+    try {
+        return await host.callAppTool(name, args);
+    }
+    catch (e) {
+        if (e instanceof ApprovalRequiredError)
+            return requestApproval({ kind: 'tool', name, args }, e.plan, author);
+        throw e;
+    }
+}
+/** Pass a request to the app's generated REST; a DELETE becomes an approval. */
+export async function runRest(req, author) {
+    const host = await getHost();
+    try {
+        return await host.rest(req);
+    }
+    catch (e) {
+        if (e instanceof ApprovalRequiredError) {
+            const action = {
+                kind: 'rest',
+                method: req.method.toUpperCase(),
+                url: req.url,
+                ...(req.body ? { body: req.body } : {}),
+            };
+            return requestApproval(action, e.plan, author);
+        }
+        throw e;
+    }
+}
+export function isPending(x) {
+    return (!!x &&
+        typeof x === 'object' &&
+        x.status === 'pending_approval');
+}
+/** Delete a record: always an approval (nothing is deleted until decided). */
+export async function requestRecordDelete(model, id, author) {
+    const host = await getHost();
+    const record = await host.get(model, id); // 404s for a missing record
+    return requestApproval({ kind: 'record-delete', model, id }, {
+        summary: `Delete ${model} record ${id}`,
+        risky: true,
+        preview: { model, id, record },
+    }, author);
+}

package/dist/lib/server/events.d.ts

@@ -0,0 +1,16 @@
+export type ShellEvent = {
+    type: 'changed';
+    version: number;
+    summary: string;
+} | {
+    type: 'records';
+    model: string | null;
+} | {
+    type: 'approval';
+    id: string;
+    status: 'pending' | 'approved' | 'denied' | 'failed';
+    summary: string;
+};
+export declare function publish(event: ShellEvent): void;
+/** Subscribe; returns the unsubscribe function. */
+export declare function subscribe(listener: (event: ShellEvent) => void): () => void;

package/dist/lib/server/events.js

@@ -0,0 +1,14 @@
+// A small in-process event bus for live updates. Host events ('changed',
+// 'records') and approval events are republished here; the SSE route
+// (`/api/events`) and the MCP route (list_changed) subscribe.
+import { EventEmitter } from 'node:events';
+const bus = new EventEmitter();
+bus.setMaxListeners(100);
+export function publish(event) {
+    bus.emit('event', event);
+}
+/** Subscribe; returns the unsubscribe function. */
+export function subscribe(listener) {
+    bus.on('event', listener);
+    return () => bus.off('event', listener);
+}

package/dist/lib/server/host.d.ts

@@ -0,0 +1,22 @@
+import type { DatabaseInterface } from '@happyvertical/sql';
+import { AppHost } from '../../engine/index.ts';
+export interface ShellContext {
+    /** The shell's database (shell.db: users, App, AppVersion, Approval). */
+    db: () => Promise<DatabaseInterface>;
+    /** The app-runtime data root. */
+    dataRoot: () => Promise<string>;
+    /** Override the app worker entry (tests; defaults to the engine's own). */
+    workerUrl?: URL | string;
+}
+export declare function configureShell(next: ShellContext): void;
+export declare function getShellDb(): Promise<DatabaseInterface>;
+/** The shell database once `getShellDb()` has resolved. For sync thunks. */
+export declare function shellDbSync(): DatabaseInterface;
+export declare function dataRoot(): Promise<string>;
+/** The one AppHost, opened on first use. */
+export declare function getHost(): Promise<AppHost>;
+/** The host if it is already open (sync, for list_changed wiring). */
+export declare function openHost(): AppHost | null;
+export declare function closeHost(): Promise<void>;
+/** Tests: forget everything. */
+export declare function resetShell(): Promise<void>;

package/dist/lib/server/host.js

@@ -0,0 +1,96 @@
+// Process-wide holders: where the shell gets its database, its data root and
+// the one `AppHost` (the user app's runtime). Everything server-side reaches
+// them through here, so tests can configure a temp directory and a SQLite
+// database without SvelteKit.
+//
+// Data layout: the host's `dataDir` is `<data root>/user-app`, a plain
+// directory inside the app-runtime data root, so the encrypted backup that
+// seals the root also seals app.db, snapshots and archives. No symlinks.
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AppHost } from "../../engine/index.js";
+import { publish } from "./events.js";
+import { ShellVersionStore } from "./version-store.js";
+let context = null;
+let syncDb = null;
+let hostPromise = null;
+let hostRef = null;
+let shutdownHooked = false;
+export function configureShell(next) {
+    context = next;
+}
+function requireContext() {
+    if (!context)
+        throw new Error('the shell is not configured (call configureShell first)');
+    return context;
+}
+export async function getShellDb() {
+    const db = await requireContext().db();
+    syncDb = db;
+    return db;
+}
+/** The shell database once `getShellDb()` has resolved. For sync thunks. */
+export function shellDbSync() {
+    if (!syncDb)
+        throw new Error('the shell database is not open yet');
+    return syncDb;
+}
+export function dataRoot() {
+    return requireContext().dataRoot();
+}
+function workerUrl() {
+    const configured = requireContext().workerUrl;
+    if (configured)
+        return configured;
+    // From source (dev, tests) the worker sits next to the engine; from a build
+    // it is the package's published engine worker.
+    const local = new URL('../../engine/app-worker.ts', import.meta.url);
+    if (existsSync(fileURLToPath(local)))
+        return local;
+    return new URL(import.meta.resolve('@happyvertical/smrt-app-shell/engine/worker'));
+}
+/** The one AppHost, opened on first use. */
+export function getHost() {
+    hostPromise ??= (async () => {
+        const db = await getShellDb();
+        const dir = join(await dataRoot(), 'user-app');
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const host = await AppHost.open(dir, {
+            store: new ShellVersionStore(db),
+            workerUrl: workerUrl(),
+        });
+        host.on('changed', (e) => publish({ type: 'changed', version: e.version, summary: e.summary }));
+        host.on('records', (e) => publish({ type: 'records', model: e.model }));
+        hostRef = host;
+        if (!shutdownHooked) {
+            shutdownHooked = true;
+            // adapter-node emits this on SIGTERM/SIGINT before exiting.
+            process.on('sveltekit:shutdown', () => {
+                void closeHost();
+            });
+        }
+        return host;
+    })();
+    hostPromise.catch(() => {
+        hostPromise = null; // let the next call retry
+    });
+    return hostPromise;
+}
+/** The host if it is already open (sync, for list_changed wiring). */
+export function openHost() {
+    return hostRef;
+}
+export async function closeHost() {
+    const pending = hostPromise;
+    hostPromise = null;
+    hostRef = null;
+    if (pending)
+        await (await pending.catch(() => null))?.close();
+}
+/** Tests: forget everything. */
+export async function resetShell() {
+    await closeHost();
+    context = null;
+    syncDb = null;
+}

package/dist/lib/server/owner.d.ts

@@ -0,0 +1,33 @@
+export interface Principal {
+    id: string;
+    tenantId: string;
+    scopes?: readonly string[];
+}
+export declare class PolicyError extends Error {
+    readonly status: 401 | 403;
+    constructor(status: 401 | 403, message: string);
+}
+export type OwnerCheck = (principal: Principal) => Promise<boolean>;
+/** Tests only: replace the database lookup. Pass null to restore it. */
+export declare function setOwnerCheck(check: OwnerCheck | null): void;
+export declare function isOwner(principal: Principal | null | undefined): Promise<boolean>;
+/** The principal, or a 401 (nobody) / 403 (somebody who is not the owner). */
+export declare function requireOwner(principal: Principal | null | undefined): Promise<Principal>;
+/** The principal of a SvelteKit request, from the verified session only. */
+export declare function principalFromLocals(locals: {
+    user?: {
+        id?: unknown;
+    } | null;
+    tenantId?: unknown;
+    permissions?: unknown;
+}): Principal | null;
+/** The principal of the running async scope (the session's tenant context). */
+export declare function currentPrincipal(): Principal | null;
+/** For model methods: the owner of the current scope, or a refusal. */
+export declare function assertOwner(): Promise<Principal>;
+/**
+ * Run `fn` inside the verified principal's tenant context, so the owner check
+ * in model methods (`assertOwner`) sees exactly the principal a route
+ * verified, whatever async context the route runs in.
+ */
+export declare function runAs<T>(principal: Principal, fn: () => Promise<T>): Promise<T>;