@columenlabs/lumen-ai 0.1.188 → 0.1.190

package/README.md

@@ -251,3 +251,24 @@ class Chat extends LumenAgent<Env> {
   protected undoWrite(card: AgentCard) { return assistant.undoChange(caller, card); }
 }
 ```
+
+## Workspaces: tabs over recipes, run again on demand
+
+`@columenlabs/lumen-ai/workspaces` is the server the kit's `WorkspacesSection` and `WorkspacePage` call. A workspace is a person's page of tabs; each tab is a table over a **frame**: the rows one **recipe** pulled, the recipe itself and the person's hand edits. A recipe is one call to one of the product's read tools (`{kind: 'call', fn: 'jobs.list', args}`), so running it again needs no model. Nothing runs on a timer: ↻ on a tab runs its recipe, ↻ in the header runs every tab one after another, each within 15 s (`RUN_MS`); a failed run keeps the last rows and says why.
+
+```ts
+import { createWorkspaces, doSql, workspaceMigrations, workspaceRoutes } from '@columenlabs/lumen-ai/workspaces';
+
+// In the store that holds the person's data (a Durable Object's SQLite, or D1 with d1Sql):
+for (const q of workspaceMigrations({ spaces: 'app_ws_spaces', frames: 'app_ws_frames' })) sql.exec(q);
+const store = createWorkspaces({
+  db: doSql(sql),
+  tables: { spaces: 'app_ws_spaces', frames: 'app_ws_frames' },
+  run: (recipe, { owner, signal }) => callReadTool(owner, recipe, signal), // the product's own tools, as the person
+});
+
+// In the Worker, at the assistant's api:
+const routes = workspaceRoutes({ base: '/api/assistant', owner: callerOf, store: () => store });
+```
+
+Budget: one frame is one row (at most 1.5 MB of rows, 10,000 rows, 50 columns), so a run writes one row; every read has a LIMIT (30 workspaces, 12 tabs each, 100 frames). Columns are typed from their values (number, date, text); a list of words, or short text from a small set, becomes a tags column (chips). The kit's `WorkspacesProvider` takes `recipes` to offer + New tab from a recipe in the tab bar.

package/dist/workspaces/frame.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Rows as a frame: a tool's answer (a list, or an object with a list field) flattened to typed
+ * columns, plus the person's hand edits put back after every run. Pure: no storage, no network.
+ */
+import { type FrameCell, type FrameColumn, type FrameEdit } from '@columenlabs/lumen-ui-types/frames';
+export type Row = Record<string, unknown>;
+/** A frame the person can read back: why it was refused, in words. */
+export declare class FrameError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+/** The rows of a value: a list's items, or its first list field, else the value as one row. */
+export declare function asRows(v: unknown): Row[];
+/** Rows as a frame: columns by first sight, each typed from its values. */
+export declare function toFrame(rows: Row[]): {
+    columns: FrameColumn[];
+    data: FrameCell[][];
+};
+/** A typed value for a column: numbers from numerals (a comma, %, $ or a true minus allowed). */
+export declare function coerce(col: FrameColumn, value: FrameCell): FrameCell;
+/** The latest edit per cell, newest last, at most FRAME_EDITS. */
+export declare function dedupeEdits(edits: FrameEdit[]): FrameEdit[];
+/**
+ * Puts the person's hand edits back onto new rows, by row index (a tab's rows come in the order
+ * the recipe gives them). An edit whose column or row is gone is dropped.
+ */
+export declare function applyEdits(columns: FrameColumn[], data: FrameCell[][], edits: FrameEdit[]): {
+    data: FrameCell[][];
+    edits: FrameEdit[];
+};

package/dist/workspaces/frame.js

@@ -0,0 +1,126 @@
+/**
+ * Rows as a frame: a tool's answer (a list, or an object with a list field) flattened to typed
+ * columns, plus the person's hand edits put back after every run. Pure: no storage, no network.
+ */
+import { FRAME_COLUMNS, FRAME_EDITS, FRAME_ROWS, columnKey, } from '@columenlabs/lumen-ui-types/frames';
+/** A frame the person can read back: why it was refused, in words. */
+export class FrameError extends Error {
+    status;
+    constructor(message, status = 422) {
+        super(message);
+        this.status = status;
+    }
+}
+/** The rows of a value: a list's items, or its first list field, else the value as one row. */
+export function asRows(v) {
+    const list = Array.isArray(v)
+        ? v
+        : v && typeof v === 'object'
+            ? (Object.values(v).find(Array.isArray) ?? [v])
+            : v === undefined || v === null
+                ? []
+                : [{ value: v }];
+    return list.map((r) => r && typeof r === 'object' && !Array.isArray(r) ? r : { value: r });
+}
+const ISO_DAY = /^\d{4}-\d{2}-\d{2}/;
+/** One cell: a list of short words becomes `a, b` (a tags column), anything else nested is JSON. */
+function cell(v) {
+    if (v === null || v === undefined)
+        return { v: null, list: false };
+    if (typeof v === 'number')
+        return { v: Number.isFinite(v) ? v : null, list: false };
+    if (typeof v === 'string')
+        return { v: v.slice(0, 2000), list: false };
+    if (typeof v === 'boolean')
+        return { v: v ? 'Yes' : 'No', list: false };
+    if (Array.isArray(v) && v.every((x) => typeof x === 'string'))
+        return { v: v.join(', ').slice(0, 500), list: true };
+    return { v: JSON.stringify(v).slice(0, 500), list: false };
+}
+/** Distinct values a text column may hold and still read as tags (stage, source, kind). */
+const TAG_DISTINCT = 12;
+/** Longest value a tag column holds. */
+const TAG_CHARS = 24;
+/** Rows as a frame: columns by first sight, each typed from its values. */
+export function toFrame(rows) {
+    if (rows.length > FRAME_ROWS)
+        throw new FrameError(`${rows.length.toLocaleString('en-US')} rows: a tab keeps at most ${FRAME_ROWS.toLocaleString('en-US')}. Filter first.`);
+    const names = [];
+    for (const r of rows)
+        for (const k of Object.keys(r))
+            if (!names.includes(k))
+                names.push(k);
+    if (names.length > FRAME_COLUMNS)
+        throw new FrameError(`${names.length} columns: a tab keeps at most ${FRAME_COLUMNS}. Ask for fewer fields.`);
+    const lists = new Set();
+    const data = rows.map((r) => names.map((n, i) => {
+        const c = cell(r[n]);
+        if (c.list)
+            lists.add(i);
+        return c.v;
+    }));
+    const taken = new Set();
+    const columns = names.map((label, i) => {
+        const values = data.map((d) => d[i]).filter((v) => v !== null);
+        const type = values.length && values.every((v) => typeof v === 'number')
+            ? 'number'
+            : values.length && values.every((v) => typeof v === 'string' && ISO_DAY.test(v))
+                ? 'date'
+                : 'text';
+        // Short values from a small set (or lists of words) read as coloured chips, not text.
+        const distinct = new Set(values);
+        const tags = type === 'text' &&
+            (lists.has(i) ||
+                (values.length >= 4 &&
+                    distinct.size <= TAG_DISTINCT &&
+                    distinct.size < values.length &&
+                    values.every((v) => String(v).length <= TAG_CHARS)));
+        return {
+            key: columnKey(label, taken),
+            label: label.slice(0, 40),
+            type,
+            format: type === 'number' ? 'number' : 'text',
+            ...(tags ? { tags: true } : {}),
+        };
+    });
+    return { columns, data };
+}
+/** A typed value for a column: numbers from numerals (a comma, %, $ or a true minus allowed). */
+export function coerce(col, value) {
+    if (value === null || value === '')
+        return null;
+    if (col.type !== 'number')
+        return typeof value === 'number' ? String(value) : value.slice(0, 2000);
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    const n = Number(value.replace(/[,$%\s]/g, '').replace('−', '-'));
+    if (!Number.isFinite(n))
+        throw new FrameError(`${col.label} holds numbers: "${value}" is not one.`);
+    return n;
+}
+/** The latest edit per cell, newest last, at most FRAME_EDITS. */
+export function dedupeEdits(edits) {
+    const seen = new Map();
+    for (const e of edits)
+        seen.set(`${e.column}\u0000${e.key ?? `#${e.row}`}`, e);
+    return [...seen.values()].slice(-FRAME_EDITS);
+}
+/**
+ * Puts the person's hand edits back onto new rows, by row index (a tab's rows come in the order
+ * the recipe gives them). An edit whose column or row is gone is dropped.
+ */
+export function applyEdits(columns, data, edits) {
+    if (!edits.length)
+        return { data, edits };
+    const rows = data.map((r) => [...r]);
+    const kept = [];
+    for (const e of edits) {
+        const col = columns.findIndex((c) => c.key === e.column);
+        const row = e.row === undefined ? undefined : rows[e.row];
+        if (col < 0 || !row)
+            continue;
+        row[col] = e.value;
+        kept.push(e);
+    }
+    return { data: rows, edits: kept };
+}

package/dist/workspaces/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Workspaces: a person's pages of tabs, each a table over rows a recipe pulled, run again on demand.
+ * `createWorkspaces` is the store (any SQLite), `workspaceRoutes` the HTTP the kit's pages call.
+ */
+export { FrameError, applyEdits, asRows, coerce, dedupeEdits, toFrame } from './frame.js';
+export type { Row } from './frame.js';
+export { FRAME_BYTES, MAX_FRAMES, MAX_TABS, MAX_WORKSPACES, RUN_MS, createWorkspaces, d1Sql, doSql, recipeText, workspaceMigrations, } from './store.js';
+export type { RecipeRunner, SqlRunner, WorkspaceRead, WorkspaceTables, Workspaces, WorkspacesOptions, } from './store.js';
+export { workspaceRoutes } from './routes.js';
+export type { WorkspaceRoutesOptions } from './routes.js';

package/dist/workspaces/index.js

@@ -0,0 +1,7 @@
+/**
+ * Workspaces: a person's pages of tabs, each a table over rows a recipe pulled, run again on demand.
+ * `createWorkspaces` is the store (any SQLite), `workspaceRoutes` the HTTP the kit's pages call.
+ */
+export { FrameError, applyEdits, asRows, coerce, dedupeEdits, toFrame } from './frame.js';
+export { FRAME_BYTES, MAX_FRAMES, MAX_TABS, MAX_WORKSPACES, RUN_MS, createWorkspaces, d1Sql, doSql, recipeText, workspaceMigrations, } from './store.js';
+export { workspaceRoutes } from './routes.js';

package/dist/workspaces/routes.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The HTTP routes the kit's workspace pages call (`WorkspacesSection`, `WorkspacePage` in
+ * `@columenlabs/lumen-ui`), as one fetch handler on Web `Request`/`Response`, mounted at the
+ * assistant's api (`/api/assistant`):
+ *
+ *   GET    /workspaces                    the caller's workspaces
+ *   POST   /workspaces {name, app?}       a new one
+ *   GET    /workspaces/:id                one, with its frames' heads
+ *   PATCH  /workspaces/:id {name?, app?}
+ *   DELETE /workspaces/:id
+ *   POST   /workspaces/:id/tabs {name, recipe}   a new tab from a recipe (runs it once)
+ *   POST   /workspaces/:id/refresh        runs every tab's recipe again, one after another
+ *   PUT    /workspaces/:id/tabs/:tab {name?, config?}
+ *   DELETE /workspaces/:id/tabs/:tab
+ *   GET    /frames                        every frame (for + Data)
+ *   GET    /frames/:id                    rows, meta and hand edits
+ *   POST   /frames/:id/refresh            runs its recipe again
+ *   GET|PUT /frames/:id/script            its recipe
+ *   PATCH  /frames/:id/cells {edits}      hand edits
+ *
+ * Every call needs a caller; writes must be same-origin JSON, since a signed-in browser session is
+ * a cookie and a foreign page must not reach a person's data.
+ */
+import { frameScriptSchema } from '@columenlabs/lumen-ui-types/frames';
+import { z } from 'zod';
+import type { Workspaces } from './store.js';
+type Awaitable<T> = T | Promise<T>;
+export interface WorkspaceRoutesOptions {
+    /** Where the routes are mounted (`/api/assistant`). */
+    base: string;
+    /** The store for this request (the caller's own). */
+    store: (req: Request) => Awaitable<Workspaces>;
+    /** The verified caller's owner id, or null (403). */
+    owner: (req: Request) => Awaitable<string | null>;
+    /** Which recipes this product runs; a recipe it refuses answers 422 with the reason. */
+    allow?: (recipe: z.infer<typeof frameScriptSchema>, req: Request) => Awaitable<string | null>;
+}
+export declare function workspaceRoutes(opts: WorkspaceRoutesOptions): (req: Request) => Promise<Response>;
+export {};

package/dist/workspaces/routes.js

@@ -0,0 +1,154 @@
+/**
+ * The HTTP routes the kit's workspace pages call (`WorkspacesSection`, `WorkspacePage` in
+ * `@columenlabs/lumen-ui`), as one fetch handler on Web `Request`/`Response`, mounted at the
+ * assistant's api (`/api/assistant`):
+ *
+ *   GET    /workspaces                    the caller's workspaces
+ *   POST   /workspaces {name, app?}       a new one
+ *   GET    /workspaces/:id                one, with its frames' heads
+ *   PATCH  /workspaces/:id {name?, app?}
+ *   DELETE /workspaces/:id
+ *   POST   /workspaces/:id/tabs {name, recipe}   a new tab from a recipe (runs it once)
+ *   POST   /workspaces/:id/refresh        runs every tab's recipe again, one after another
+ *   PUT    /workspaces/:id/tabs/:tab {name?, config?}
+ *   DELETE /workspaces/:id/tabs/:tab
+ *   GET    /frames                        every frame (for + Data)
+ *   GET    /frames/:id                    rows, meta and hand edits
+ *   POST   /frames/:id/refresh            runs its recipe again
+ *   GET|PUT /frames/:id/script            its recipe
+ *   PATCH  /frames/:id/cells {edits}      hand edits
+ *
+ * Every call needs a caller; writes must be same-origin JSON, since a signed-in browser session is
+ * a cookie and a foreign page must not reach a person's data.
+ */
+import { frameEditSchema, frameName, frameScriptSchema } from '@columenlabs/lumen-ui-types/frames';
+import { customViewConfigSchema } from '@columenlabs/lumen-ui-types/views';
+import { z } from 'zod';
+import { FrameError } from './frame.js';
+const HEADERS = { 'content-type': 'application/json', 'cache-control': 'no-store' };
+const json = (body, status = 200) => new Response(JSON.stringify(body), { status, headers: HEADERS });
+const fail = (error, status) => json({ error }, status);
+const createSchema = z.object({ name: frameName, app: z.string().max(40).optional() });
+const patchSchema = z.object({ name: frameName.optional(), app: z.string().max(40).optional() });
+const addTabSchema = z.object({ name: frameName, recipe: frameScriptSchema });
+const putTabSchema = z.object({
+    name: frameName.optional(),
+    config: customViewConfigSchema.nullable().optional(),
+});
+const cellsSchema = z.object({ edits: z.array(frameEditSchema).min(1).max(200) });
+const scriptSchema = z.object({ script: frameScriptSchema });
+export function workspaceRoutes(opts) {
+    const base = opts.base.replace(/\/$/, '');
+    return async (req) => {
+        const url = new URL(req.url);
+        if (!url.pathname.startsWith(base))
+            return fail('not_found', 404);
+        const parts = url.pathname
+            .slice(base.length)
+            .split('/')
+            .filter(Boolean)
+            .map(decodeURIComponent);
+        const owner = await opts.owner(req);
+        if (!owner)
+            return fail('forbidden', 403);
+        const write = req.method !== 'GET';
+        if (write) {
+            if (req.headers.get('origin') !== url.origin)
+                return fail('forbidden_origin', 403);
+            if (req.method !== 'DELETE' &&
+                !(req.headers.get('content-type') ?? '').toLowerCase().startsWith('application/json'))
+                return fail('json_only', 415);
+        }
+        const body = async (schema) => {
+            const parsed = schema.safeParse(await req.json().catch(() => null));
+            if (!parsed.success)
+                throw new FrameError(parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; '), 400);
+            return parsed.data;
+        };
+        const allowed = async (recipe) => {
+            if (recipe.kind !== 'call')
+                throw new FrameError('Recipes here are one call to an app tool.', 422);
+            const why = opts.allow ? await opts.allow(recipe, req) : null;
+            if (why)
+                throw new FrameError(why, 422);
+        };
+        try {
+            const s = await opts.store(req);
+            const [root, id, sub, tab] = parts;
+            const m = req.method;
+            if (root === 'workspaces') {
+                if (!id) {
+                    if (m === 'GET')
+                        return json(await s.list(owner));
+                    if (m === 'POST')
+                        return json(await s.create(owner, await body(createSchema)));
+                }
+                else if (!sub) {
+                    if (m === 'GET')
+                        return json(await s.read(owner, id));
+                    if (m === 'PATCH') {
+                        const p = await body(patchSchema);
+                        return json(await s.patch(owner, id, p));
+                    }
+                    if (m === 'DELETE') {
+                        await s.remove(owner, id);
+                        return json({ ok: true });
+                    }
+                }
+                else if (sub === 'refresh' && !tab && m === 'POST') {
+                    return json(await s.refreshAll(owner, id));
+                }
+                else if (sub === 'tabs') {
+                    if (!tab && m === 'POST') {
+                        const p = await body(addTabSchema);
+                        await allowed(p.recipe);
+                        return json(await s.addTab(owner, id, { name: p.name, recipe: p.recipe }));
+                    }
+                    if (tab && m === 'PUT') {
+                        const p = await body(putTabSchema);
+                        return json(await s.putTab(owner, id, tab, {
+                            name: p.name,
+                            // The schema checks the layout; the tab's name rides beside it.
+                            config: p.config,
+                        }));
+                    }
+                    if (tab && m === 'DELETE')
+                        return json(await s.removeTab(owner, id, tab));
+                }
+            }
+            if (root === 'frames') {
+                if (!id) {
+                    if (m === 'GET')
+                        return json(await s.frames(owner));
+                    if (m === 'POST')
+                        return fail('Your own columns are not offered here yet.', 501);
+                }
+                else if (!sub && m === 'GET') {
+                    return json(await s.frame(owner, id));
+                }
+                else if (sub === 'refresh' && m === 'POST') {
+                    return json(await s.refresh(owner, id));
+                }
+                else if (sub === 'script') {
+                    if (m === 'GET')
+                        return json(await s.script(owner, id));
+                    if (m === 'PUT') {
+                        const p = await body(scriptSchema);
+                        await allowed(p.script);
+                        return json(await s.setScript(owner, id, p.script));
+                    }
+                }
+                else if (sub === 'cells' && m === 'PATCH') {
+                    return json(await s.editCells(owner, id, (await body(cellsSchema)).edits));
+                }
+            }
+            return fail('not_found', 404);
+        }
+        catch (err) {
+            if (err instanceof FrameError)
+                return fail(err.message, err.status);
+            console.error(JSON.stringify({ event: 'workspaces_error', error: String(err) }));
+            return fail('Something went wrong.', 500);
+        }
+    };
+}

package/dist/workspaces/store.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Workspaces on the server: a person's pages of tabs, each tab a table over a frame (the rows one
+ * recipe pulled, the recipe that pulled them, and the person's hand edits). Any SQLite holds them:
+ * a Durable Object's own (`doSql`) or D1 (`d1Sql`). The product runs recipes (`run`): a recipe is a
+ * call to one of its read tools as the person, so running it again needs no model.
+ *
+ * Budget: a list reads at most `MAX_WORKSPACES` rows, a workspace one row plus its frames' heads,
+ * a frame one row. A run writes one row (the frame); nothing here runs on a timer.
+ *
+ * Tables (names from `tables`, so a store with a prefix rule keeps it):
+ *   spaces: owner, id, name, app, tabs (JSON), created_at, updated_at
+ *   frames: owner, id, name, head (JSON: meta + recipe), rows (JSON), edits (JSON), at
+ */
+import { type FrameChoice, type FrameData, type FrameEditInput, type FrameMeta, type FrameScript } from '@columenlabs/lumen-ui-types/frames';
+import type { CustomViewConfig } from '@columenlabs/lumen-ui-types/views';
+import type { Workspace, WorkspaceSummary } from '@columenlabs/lumen-ui-types/workspaces';
+type Row = Record<string, unknown>;
+/** The SQL a store needs: the same shape as `lumen-tasks`' `SqlRunner`, so one runner serves both. */
+export interface SqlRunner {
+    all(sql: string, ...args: unknown[]): Promise<Row[]>;
+    run(sql: string, ...args: unknown[]): Promise<void>;
+}
+/** A Durable Object's SQLite (`ctx.storage.sql`). */
+export declare function doSql(sql: {
+    exec(q: string, ...args: unknown[]): {
+        toArray(): unknown[];
+    };
+}): SqlRunner;
+/** A D1 database binding. */
+export declare function d1Sql(db: {
+    prepare(q: string): {
+        bind(...a: unknown[]): {
+            all(): Promise<{
+                results: unknown[];
+            }>;
+            run(): Promise<unknown>;
+        };
+    };
+}): SqlRunner;
+export declare const MAX_WORKSPACES = 30;
+export declare const MAX_TABS = 12;
+export declare const MAX_FRAMES = 100;
+/** Most bytes a frame's rows keep as JSON (a SQLite row holds 2 MB). */
+export declare const FRAME_BYTES = 1500000;
+/** How long one recipe run may take before it gives up (the tab keeps its last rows). */
+export declare const RUN_MS = 15000;
+export interface WorkspaceTables {
+    spaces: string;
+    frames: string;
+}
+/** The tables' SQL, for a store that runs its own migrations (a person store module). */
+export declare function workspaceMigrations(t?: WorkspaceTables): string[];
+/** What runs a recipe: the product calls its read tool as the person and gives back its answer. */
+export type RecipeRunner = (recipe: FrameScript, ctx: {
+    owner: string;
+    signal: AbortSignal;
+}) => Promise<unknown>;
+export interface WorkspacesOptions {
+    db: SqlRunner;
+    run: RecipeRunner;
+    /** The app new workspaces belong to (one-app products leave it). */
+    app?: string;
+    tables?: WorkspaceTables;
+    now?: () => number;
+}
+export type WorkspaceRead = Workspace & {
+    frames: Record<string, FrameMeta>;
+};
+/** The recipe's text as the person reads it: `jobs.list` and its arguments. */
+export declare function recipeText(s: FrameScript | null): string;
+export declare function createWorkspaces(opts: WorkspacesOptions): {
+    list(owner: string): Promise<{
+        workspaces: WorkspaceSummary[];
+    }>;
+    create(owner: string, p: {
+        name: string;
+        app?: string;
+    }): Promise<Workspace>;
+    read(owner: string, id: string): Promise<WorkspaceRead>;
+    patch(owner: string, id: string, p: {
+        name?: string;
+        app?: string;
+    }): Promise<Workspace>;
+    remove(owner: string, id: string): Promise<void>;
+    /** A new tab from a recipe: runs it once, keeps the rows as a frame, adds the tab. */
+    addTab(owner: string, id: string, p: {
+        name: string;
+        recipe: FrameScript;
+        by?: 'you' | 'assistant';
+    }): Promise<{
+        workspace: WorkspaceRead;
+        tab: string;
+    }>;
+    putTab(owner: string, id: string, tab: string, p: {
+        name?: string;
+        config?: CustomViewConfig | null;
+    }): Promise<Workspace>;
+    removeTab(owner: string, id: string, tab: string): Promise<Workspace>;
+    /** Runs every tab's recipe again, one after another; a failed one leaves its last rows. */
+    refreshAll(owner: string, id: string): Promise<{
+        ran: number;
+        failed: string[];
+        rows: number;
+    }>;
+    frames(owner: string): Promise<{
+        frames: FrameChoice[];
+    }>;
+    frame(owner: string, id: string): Promise<FrameData>;
+    refresh: (owner: string, id: string, by?: 'you' | 'assistant') => Promise<FrameData>;
+    script(owner: string, id: string): Promise<{
+        script: FrameScript | null;
+    }>;
+    /** A new recipe for a frame: kept only if it runs. */
+    setScript(owner: string, id: string, script: FrameScript): Promise<FrameData>;
+    editCells(owner: string, id: string, edits: FrameEditInput[]): Promise<FrameData>;
+};
+export type Workspaces = ReturnType<typeof createWorkspaces>;
+export {};

package/dist/workspaces/store.js

@@ -0,0 +1,381 @@
+/**
+ * Workspaces on the server: a person's pages of tabs, each tab a table over a frame (the rows one
+ * recipe pulled, the recipe that pulled them, and the person's hand edits). Any SQLite holds them:
+ * a Durable Object's own (`doSql`) or D1 (`d1Sql`). The product runs recipes (`run`): a recipe is a
+ * call to one of its read tools as the person, so running it again needs no model.
+ *
+ * Budget: a list reads at most `MAX_WORKSPACES` rows, a workspace one row plus its frames' heads,
+ * a frame one row. A run writes one row (the frame); nothing here runs on a timer.
+ *
+ * Tables (names from `tables`, so a store with a prefix rule keeps it):
+ *   spaces: owner, id, name, app, tabs (JSON), created_at, updated_at
+ *   frames: owner, id, name, head (JSON: meta + recipe), rows (JSON), edits (JSON), at
+ */
+import { FRAME_RUNS, } from '@columenlabs/lumen-ui-types/frames';
+import { FrameError, applyEdits, asRows, coerce, dedupeEdits, toFrame } from './frame.js';
+/** A Durable Object's SQLite (`ctx.storage.sql`). */
+export function doSql(sql) {
+    return {
+        all: async (q, ...a) => sql.exec(q, ...a).toArray(),
+        run: async (q, ...a) => {
+            sql.exec(q, ...a);
+        },
+    };
+}
+/** A D1 database binding. */
+export function d1Sql(db) {
+    return {
+        all: async (q, ...a) => (await db
+            .prepare(q)
+            .bind(...a)
+            .all()).results,
+        run: async (q, ...a) => {
+            await db
+                .prepare(q)
+                .bind(...a)
+                .run();
+        },
+    };
+}
+export const MAX_WORKSPACES = 30;
+export const MAX_TABS = 12;
+export const MAX_FRAMES = 100;
+/** Most bytes a frame's rows keep as JSON (a SQLite row holds 2 MB). */
+export const FRAME_BYTES = 1_500_000;
+/** How long one recipe run may take before it gives up (the tab keeps its last rows). */
+export const RUN_MS = 15_000;
+const TABLES = { spaces: 'ws_spaces', frames: 'ws_frames' };
+/** The tables' SQL, for a store that runs its own migrations (a person store module). */
+export function workspaceMigrations(t = TABLES) {
+    return [
+        `CREATE TABLE IF NOT EXISTS ${t.spaces} (owner TEXT NOT NULL, id TEXT NOT NULL, name TEXT NOT NULL, app TEXT NOT NULL, tabs TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, PRIMARY KEY (owner, id))`,
+        `CREATE TABLE IF NOT EXISTS ${t.frames} (owner TEXT NOT NULL, id TEXT NOT NULL, name TEXT NOT NULL, head TEXT NOT NULL, rows TEXT NOT NULL, edits TEXT NOT NULL, at TEXT NOT NULL, PRIMARY KEY (owner, id))`,
+    ];
+}
+const newId = (prefix) => `${prefix}_${crypto.randomUUID().replaceAll('-', '').slice(0, 16)}`;
+const parse = (v, d) => {
+    try {
+        return typeof v === 'string' ? JSON.parse(v) : d;
+    }
+    catch {
+        return d;
+    }
+};
+const metaOf = ({ script: _s, ...m }) => m;
+/** The recipe's text as the person reads it: `jobs.list` and its arguments. */
+export function recipeText(s) {
+    if (!s)
+        return 'nothing (rows written once)';
+    if (s.kind === 'call')
+        return `${s.fn} ${JSON.stringify(s.args)}`;
+    return s.kind === 'sql' ? 'a SQL query' : 'a script';
+}
+export function createWorkspaces(opts) {
+    const t = opts.tables ?? TABLES;
+    const now = () => new Date((opts.now ?? Date.now)()).toISOString();
+    const db = opts.db;
+    const spaceOf = (r) => ({
+        id: String(r.id),
+        name: String(r.name),
+        app: String(r.app),
+        tabs: parse(r.tabs, []),
+        created_at: String(r.created_at),
+        updated_at: String(r.updated_at),
+    });
+    async function getSpace(owner, id) {
+        const [r] = await db.all(`SELECT id, name, app, tabs, created_at, updated_at FROM ${t.spaces} WHERE owner = ? AND id = ? LIMIT 1`, owner, id);
+        if (!r)
+            throw new FrameError('No workspace with this id.', 404);
+        return spaceOf(r);
+    }
+    async function saveSpace(owner, w) {
+        const next = { ...w, updated_at: now() };
+        await db.run(`UPDATE ${t.spaces} SET name = ?, app = ?, tabs = ?, updated_at = ? WHERE owner = ? AND id = ?`, next.name, next.app, JSON.stringify(next.tabs), next.updated_at, owner, w.id);
+        return next;
+    }
+    async function heads(owner, ids) {
+        const out = new Map();
+        if (!ids.length)
+            return out;
+        const rows = await db.all(`SELECT id, head FROM ${t.frames} WHERE owner = ? AND id IN (${ids.map(() => '?').join(', ')}) LIMIT ${ids.length}`, owner, ...ids);
+        for (const r of rows)
+            out.set(String(r.id), parse(r.head, null));
+        return out;
+    }
+    async function getFrame(owner, id) {
+        const [r] = await db.all(`SELECT head, rows, edits FROM ${t.frames} WHERE owner = ? AND id = ? LIMIT 1`, owner, id);
+        if (!r)
+            throw new FrameError('No frame with this id.', 404);
+        const head = parse(r.head, null);
+        return {
+            head,
+            data: {
+                meta: metaOf(head),
+                rows: parse(r.rows, []),
+                edits: parse(r.edits, []),
+            },
+        };
+    }
+    async function writeFrame(owner, head, rows, edits) {
+        const body = JSON.stringify(rows);
+        if (body.length > FRAME_BYTES)
+            throw new FrameError('These rows are too big for one tab: ask the recipe for fewer rows or fields.');
+        await db.run(`INSERT INTO ${t.frames} (owner, id, name, head, rows, edits, at) VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT (owner, id) DO UPDATE SET name = excluded.name, head = excluded.head, rows = excluded.rows, edits = excluded.edits, at = excluded.at`, owner, head.id, head.name, JSON.stringify(head), body, JSON.stringify(edits), head.at);
+    }
+    /** Runs a recipe with a time limit, as the person. */
+    async function runRecipe(owner, recipe) {
+        const signal = AbortSignal.timeout(RUN_MS);
+        let timer;
+        try {
+            return await Promise.race([
+                opts.run(recipe, { owner, signal }),
+                new Promise((_, no) => {
+                    timer = setTimeout(() => no(new FrameError(`The recipe took over ${RUN_MS / 1000} s, so it stopped.`, 504)), RUN_MS);
+                }),
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Runs a frame's recipe and keeps the rows (hand edits put back). A failed run keeps the last
+     * good rows and says why on the frame; it throws so the caller can tell the person.
+     */
+    async function refresh(owner, id, by = 'you') {
+        const { head, data } = await getFrame(owner, id);
+        if (!head.script)
+            throw new FrameError('This tab was written once: it has no recipe to run.', 409);
+        return runInto(owner, head, data.edits ?? [], head.script, by, data.rows);
+    }
+    async function runInto(owner, head, edits, script, by, lastRows) {
+        const started = Date.now();
+        const at = now();
+        try {
+            const value = await runRecipe(owner, script);
+            const { columns, data } = toFrame(asRows(value));
+            const put = applyEdits(columns, data, edits);
+            const next = {
+                ...head,
+                columns,
+                rows: put.data.length,
+                at,
+                script,
+                error: undefined,
+                edited: put.edits.length || undefined,
+                runs: [
+                    { at, rows: put.data.length, ms: Date.now() - started, ok: true, by },
+                    ...(head.runs ?? []),
+                ].slice(0, FRAME_RUNS),
+            };
+            await writeFrame(owner, next, put.data, put.edits);
+            return { meta: metaOf(next), rows: put.data, edits: put.edits };
+        }
+        catch (err) {
+            // The product's runner speaks to the person (a tool that is not a read, a grant missing).
+            const error = (err instanceof Error && err.message ? err.message : 'The recipe failed.').slice(0, 300);
+            const failed = {
+                ...head,
+                error,
+                runs: [
+                    { at, rows: 0, ms: Date.now() - started, ok: false, by, error },
+                    ...(head.runs ?? []),
+                ].slice(0, FRAME_RUNS),
+            };
+            // A brand-new frame with no rows is not kept: the caller says why instead.
+            if (lastRows.length || head.runs?.length)
+                await writeFrame(owner, failed, lastRows, edits);
+            throw err instanceof FrameError ? err : new FrameError(error, 502);
+        }
+    }
+    async function dropFrameIfUnused(owner, frame) {
+        const rows = await db.all(`SELECT tabs FROM ${t.spaces} WHERE owner = ? LIMIT ${MAX_WORKSPACES}`, owner);
+        const used = rows.some((r) => parse(r.tabs, []).some((x) => 'frame' in x.source && x.source.frame === frame));
+        if (!used)
+            await db.run(`DELETE FROM ${t.frames} WHERE owner = ? AND id = ?`, owner, frame);
+    }
+    return {
+        async list(owner) {
+            const rows = await db.all(`SELECT id, name, app, tabs, created_at, updated_at FROM ${t.spaces} WHERE owner = ? ORDER BY updated_at DESC LIMIT ${MAX_WORKSPACES}`, owner);
+            return {
+                workspaces: rows.map((r) => {
+                    const w = spaceOf(r);
+                    return {
+                        id: w.id,
+                        name: w.name,
+                        app: w.app,
+                        updated_at: w.updated_at,
+                        tabs: w.tabs.map((x) => ({
+                            id: x.id,
+                            name: x.name,
+                            kind: 'frame' in x.source ? 'frame' : 'domain',
+                        })),
+                    };
+                }),
+            };
+        },
+        async create(owner, p) {
+            const [{ n } = { n: 0 }] = await db.all(`SELECT COUNT(*) AS n FROM (SELECT 1 FROM ${t.spaces} WHERE owner = ? LIMIT ${MAX_WORKSPACES})`, owner);
+            if (Number(n) >= MAX_WORKSPACES)
+                throw new FrameError(`You have ${MAX_WORKSPACES} workspaces, the most: delete one first.`, 409);
+            const at = now();
+            const w = {
+                id: newId('ws'),
+                name: p.name,
+                app: p.app ?? opts.app ?? 'app',
+                tabs: [],
+                created_at: at,
+                updated_at: at,
+            };
+            await db.run(`INSERT INTO ${t.spaces} (owner, id, name, app, tabs, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)`, owner, w.id, w.name, w.app, '[]', at, at);
+            return w;
+        },
+        async read(owner, id) {
+            const w = await getSpace(owner, id);
+            const ids = w.tabs.flatMap((x) => ('frame' in x.source ? [x.source.frame] : []));
+            const hs = await heads(owner, ids);
+            return { ...w, frames: Object.fromEntries([...hs].map(([k, h]) => [k, metaOf(h)])) };
+        },
+        async patch(owner, id, p) {
+            const w = await getSpace(owner, id);
+            return saveSpace(owner, {
+                ...w,
+                ...(p.name ? { name: p.name } : {}),
+                ...(p.app ? { app: p.app } : {}),
+            });
+        },
+        async remove(owner, id) {
+            const w = await getSpace(owner, id);
+            await db.run(`DELETE FROM ${t.spaces} WHERE owner = ? AND id = ?`, owner, id);
+            for (const x of w.tabs)
+                if ('frame' in x.source)
+                    await dropFrameIfUnused(owner, x.source.frame);
+        },
+        /** A new tab from a recipe: runs it once, keeps the rows as a frame, adds the tab. */
+        async addTab(owner, id, p) {
+            const w = await getSpace(owner, id);
+            if (w.tabs.length >= MAX_TABS)
+                throw new FrameError(`${w.name} has ${MAX_TABS} tabs, the most: delete one first.`, 409);
+            const [{ n } = { n: 0 }] = await db.all(`SELECT COUNT(*) AS n FROM (SELECT 1 FROM ${t.frames} WHERE owner = ? LIMIT ${MAX_FRAMES})`, owner);
+            if (Number(n) >= MAX_FRAMES)
+                throw new FrameError(`You keep ${MAX_FRAMES} tabs of data, the most: delete some first.`, 409);
+            const head = {
+                id: newId('fr'),
+                name: p.name,
+                columns: [],
+                rows: 0,
+                mode: 'live',
+                kind: 'snapshot',
+                at: now(),
+                origin: 'assistant',
+                script: p.recipe,
+            };
+            await runInto(owner, head, [], p.recipe, p.by ?? 'you', []);
+            const tab = {
+                id: newId('tb'),
+                name: p.name,
+                source: { frame: head.id },
+                config: null,
+            };
+            const saved = await saveSpace(owner, { ...w, tabs: [...w.tabs, tab] });
+            const hs = await heads(owner, saved.tabs.flatMap((x) => ('frame' in x.source ? [x.source.frame] : [])));
+            return {
+                workspace: {
+                    ...saved,
+                    frames: Object.fromEntries([...hs].map(([k, h]) => [k, metaOf(h)])),
+                },
+                tab: tab.id,
+            };
+        },
+        async putTab(owner, id, tab, p) {
+            const w = await getSpace(owner, id);
+            if (!w.tabs.some((x) => x.id === tab))
+                throw new FrameError('No tab with this id.', 404);
+            return saveSpace(owner, {
+                ...w,
+                tabs: w.tabs.map((x) => x.id === tab
+                    ? {
+                        ...x,
+                        ...(p.name ? { name: p.name } : {}),
+                        ...(p.config !== undefined ? { config: p.config } : {}),
+                    }
+                    : x),
+            });
+        },
+        async removeTab(owner, id, tab) {
+            const w = await getSpace(owner, id);
+            const gone = w.tabs.find((x) => x.id === tab);
+            if (!gone)
+                throw new FrameError('No tab with this id.', 404);
+            const saved = await saveSpace(owner, { ...w, tabs: w.tabs.filter((x) => x.id !== tab) });
+            if ('frame' in gone.source)
+                await dropFrameIfUnused(owner, gone.source.frame);
+            return saved;
+        },
+        /** Runs every tab's recipe again, one after another; a failed one leaves its last rows. */
+        async refreshAll(owner, id) {
+            const w = await getSpace(owner, id);
+            let ran = 0;
+            let rows = 0;
+            const failed = [];
+            for (const x of w.tabs) {
+                if (!('frame' in x.source))
+                    continue;
+                try {
+                    const d = await refresh(owner, x.source.frame);
+                    ran++;
+                    rows += d.meta.rows;
+                }
+                catch {
+                    failed.push(x.name);
+                }
+            }
+            return { ran, failed, rows };
+        },
+        async frames(owner) {
+            const rows = await db.all(`SELECT head FROM ${t.frames} WHERE owner = ? LIMIT ${MAX_FRAMES}`, owner);
+            return {
+                frames: rows.map((r) => {
+                    const h = parse(r.head, null);
+                    return {
+                        id: h.id,
+                        name: h.name,
+                        columns: h.columns,
+                        at: h.at,
+                        origin: h.origin ?? 'assistant',
+                    };
+                }),
+            };
+        },
+        async frame(owner, id) {
+            return (await getFrame(owner, id)).data;
+        },
+        refresh,
+        async script(owner, id) {
+            return { script: (await getFrame(owner, id)).head.script };
+        },
+        /** A new recipe for a frame: kept only if it runs. */
+        async setScript(owner, id, script) {
+            const { head, data } = await getFrame(owner, id);
+            return runInto(owner, head, data.edits ?? [], script, 'you', data.rows);
+        },
+        async editCells(owner, id, edits) {
+            const { head, data } = await getFrame(owner, id);
+            const at = now();
+            const add = edits.map((e) => {
+                const col = head.columns.find((c) => c.key === e.column);
+                if (!col)
+                    throw new FrameError(`No column ${e.column}.`);
+                if (e.row === undefined)
+                    throw new FrameError('An edit names its row.');
+                return { column: e.column, row: e.row, value: coerce(col, e.value), at };
+            });
+            const all = dedupeEdits([...(data.edits ?? []), ...add]);
+            const put = applyEdits(head.columns, data.rows, add);
+            const next = { ...head, edited: all.length || undefined };
+            await writeFrame(owner, next, put.data, all);
+            return { meta: metaOf(next), rows: put.data, edits: all };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ai",
-  "version": "0.1.188",
+  "version": "0.1.190",
   "description": "Lumen's assistant and agent parts: a chat assistant's server (Claude tiers, tools over MCP, the web, hand off, spend caps), serving an MCP server from a Worker, read-only tool sets and metered tool calls.",
   "license": "MIT",
   "type": "module",
@@ -22,6 +22,10 @@
     "./agent": {
       "types": "./dist/agent/index.d.ts",
       "default": "./dist/agent/index.js"
+    },
+    "./workspaces": {
+      "types": "./dist/workspaces/index.d.ts",
+      "default": "./dist/workspaces/index.js"
     }
   },
   "files": [
@@ -48,8 +52,8 @@
     "@ai-sdk/openai": "4.0.108",
     "@anthropic-ai/sdk": "0.133.0",
     "@cloudflare/think": "0.23.0",
-    "@columenlabs/lumen-ops": "0.1.188",
-    "@columenlabs/lumen-ui-types": "0.1.188",
+    "@columenlabs/lumen-ops": "0.1.190",
+    "@columenlabs/lumen-ui-types": "0.1.190",
     "agents": "0.32.0",
     "ai": "7.0.162",
     "just-bash": "3.6.0",