@mohou/contract 1.0.20

package/README.md

@@ -0,0 +1,10 @@
+---
+status: locked
+updated: 2026-10-01
+---
+
+# @mohou/contract
+
+Role: `definition`.
+
+App id parse, manifest resolve, `defineApp`, import side checks, `ctx` types, and failure codes. No I/O. Product catalog: [app surface](../../../docs/product/app-surface.md).

package/lib/types/app-id.d.ts

@@ -0,0 +1,10 @@
+import type { Branded } from '@mohou/values';
+/** Reverse-DNS app id admitted at this boundary. */
+export type AppId = Branded<'AppId'>;
+/**
+ * Admit an app id. Callers do not re-parse the brand.
+ * @param value - untrusted id text
+ * @returns the branded id
+ */
+export declare function parseAppId(value: string): AppId;
+//# sourceMappingURL=app-id.d.ts.map

package/lib/types/app-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-id.d.ts","sourceRoot":"","sources":["../../src/app-id.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAM5C,oDAAoD;AACpD,MAAM,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;AAEpC;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAK/C"}

package/lib/types/codes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Codes this definition emits. Other surfaces declare their own codes.
+ * Callers match `code`, not the message.
+ * @module @mohou/contract
+ */
+export declare const definitionCodes: readonly ["app-id-invalid", "manifest-invalid", "import-forbidden", "import-escape", "define-app-invalid"];
+/** A failure emitted by this definition. */
+export type DefinitionCode = (typeof definitionCodes)[number];
+/** Failure a caller branches on. The message is for a person. */
+export declare class ContractError extends Error {
+    readonly code: DefinitionCode;
+    /**
+     * @param code - one of {@link definitionCodes}
+     * @param message - human text; not the match key
+     * @param options - optional `cause` for the original failure
+     */
+    constructor(code: DefinitionCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=codes.d.ts.map

package/lib/types/codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../../src/codes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,eAAe,4GAMlB,CAAA;AAEV,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAA;AAE7D,iEAAiE;AACjE,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAE7B;;;;OAIG;gBACS,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKjF"}

package/lib/types/context.d.ts

@@ -0,0 +1,198 @@
+import type { AppId } from './app-id.ts';
+import type { AppWorkbench } from './workbench.ts';
+import { agentEventType, llmEventType } from './event-type.ts';
+/** A cell accepted by SQLite. */
+export type SqlValue = null | number | string | bigint | Uint8Array;
+/** One result row. Column names are the keys. */
+export interface SqlRow {
+    [column: string]: SqlValue;
+}
+/** Positional or named parameters. Named keys omit the sigil. */
+export type SqlParams = readonly SqlValue[] | Record<string, SqlValue>;
+/** The host-owned `kv` table. `query` and `run` cannot see it. */
+export interface AppKeyValueTable {
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/** One SQLite file. `kv()` is the key-value table. SQL is everything else. */
+export interface AppStorage {
+    kv(): AppKeyValueTable;
+    query(sql: string, params?: SqlParams): Promise<SqlRow[]>;
+    run(sql: string, params?: SqlParams): Promise<{
+        changes: number;
+        lastInsertRowid: number | bigint;
+    }>;
+    transaction<T>(work: (tx: AppStorage) => Promise<T>): Promise<T>;
+}
+/** `ctx.http` request. Object `body` is sent as JSON. */
+export interface AppHttpRequest {
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    query?: Record<string, string | number | boolean | null | undefined>;
+    body?: unknown;
+    timeout?: number;
+    signal?: AbortSignal;
+}
+/** `ctx.http` result. Never a platform `Response`. */
+export interface AppHttpResponse {
+    ok: boolean;
+    status: number;
+    headers: Record<string, string>;
+    text: string;
+    /** Parsed body when the content type contains json and parsing succeeds, otherwise null. */
+    json: unknown;
+}
+/** Options shared by `ctx.llm` and `ctx.agent`. Omitted limits use host policy. */
+export interface AppModelOptions {
+    provider?: string;
+    model?: string;
+    system?: string;
+    schema?: unknown;
+    maxTokens?: number;
+    /** Attempts in total, including the first. */
+    retryTimes?: number;
+    signal?: AbortSignal;
+}
+/** Why an agent turn ended. `kind` stays open so a provider can add a reason. */
+export interface AppAgentTurnEndReason {
+    kind: string;
+    error?: unknown;
+    reason?: unknown;
+}
+/** Observation only. The `ctx.agent` return stays a string. */
+export type AppAgentEvent = {
+    type: typeof agentEventType.status;
+    status: 'running' | 'idle';
+} | {
+    type: typeof agentEventType.textDelta;
+    text: string;
+} | {
+    type: typeof agentEventType.tool;
+    phase: 'start' | 'end';
+    name: string;
+    args?: unknown;
+    result?: unknown;
+} | {
+    type: typeof agentEventType.turn;
+    phase: 'start';
+    turn: number;
+} | {
+    type: typeof agentEventType.turn;
+    phase: 'end';
+    turn: number;
+    reason?: AppAgentTurnEndReason;
+} | {
+    type: typeof agentEventType.error;
+    message: string;
+} | {
+    type: typeof agentEventType.done;
+    text: string;
+};
+/** Observation for `ctx.llm` when `stream` is true. The return stays a string. */
+export type AppLlmEvent = {
+    type: typeof llmEventType.status;
+    status: 'running' | 'idle';
+} | {
+    type: typeof llmEventType.textDelta;
+    text: string;
+} | {
+    type: typeof llmEventType.error;
+    message: string;
+} | {
+    type: typeof llmEventType.done;
+    text: string;
+};
+/** `ctx.llm` options. `stream` defaults to false. */
+export interface AppLlmOptions extends AppModelOptions {
+    /** When true, the call returns a stream the method reads with `for await`. It does not reach the UI by itself. */
+    stream?: boolean;
+}
+/** `ctx.agent` options. `stream` defaults to false. */
+export interface AppAgentOptions extends AppModelOptions {
+    /** When true, the call returns a stream the method reads with `for await`. It does not reach the UI by itself. */
+    stream?: boolean;
+    maxIterations?: number;
+    cwdType?: 'app' | 'process' | 'temp' | 'custom';
+    cwd?: string;
+}
+/** Public host policy visible to an app. No secrets. */
+export interface AppConfig {
+    theme: 'light' | 'dark' | 'system';
+    palette: string;
+    locale: string;
+    chatLanguage: string;
+    hostPort: number;
+    llm: {
+        provider: string;
+        model: string;
+    } | null;
+}
+/** One OS snapshot. `loadavg` is null where the OS does not provide it. */
+export interface AppSystemMetrics {
+    platform: string;
+    arch: string;
+    hostname: string;
+    uptimeSec: number;
+    loadavg: {
+        '1m': number;
+        '5m': number;
+        '15m': number;
+    } | null;
+    memory: {
+        total: number;
+        free: number;
+        used: number;
+        usedRatio: number;
+    };
+    cpu: {
+        count: number;
+        model: string;
+        speedMHz: number;
+    };
+    collectedAt: string;
+}
+/** One secret, by the name the owner stored. Listing is not on this object. */
+export interface AppCredentials {
+    get(name: string): Promise<string | undefined>;
+}
+/** First argument of every `api` method. `State` is the object the author declared. */
+export interface AppContext<State extends object = Record<string, never>> {
+    appId: AppId;
+    appDir: string;
+    storage: AppStorage;
+    state: State;
+    credentials: AppCredentials;
+    config: AppConfig;
+    log(...args: unknown[]): void;
+    signal?: AbortSignal;
+    push(name: string, params?: unknown): void;
+    http(url: string | AppHttpRequest, opts?: Omit<AppHttpRequest, 'url'>): Promise<AppHttpResponse>;
+    bash(command: string): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    pwsh(command: string): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    system: {
+        metrics(): Promise<AppSystemMetrics>;
+    };
+    llm(prompt: string, opts: AppLlmOptions & {
+        stream: true;
+    }): AsyncIterable<AppLlmEvent> & Promise<string>;
+    llm(prompt: string, opts?: AppLlmOptions): Promise<string>;
+    agent(goal: string, opts: AppAgentOptions & {
+        stream: true;
+    }): AsyncIterable<AppAgentEvent> & Promise<string>;
+    agent(goal: string, opts?: AppAgentOptions): Promise<string>;
+    mcp(serverId: string, toolName: string, args?: Record<string, unknown>): Promise<unknown>;
+    /** Present only when the manifest kind is `workbench`. */
+    workbench?: AppWorkbench;
+}
+//# sourceMappingURL=context.d.ts.map

package/lib/types/context.d.ts.map

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

package/lib/types/define-app.d.ts

@@ -0,0 +1,25 @@
+import type { AppContext } from './context.ts';
+/** One backend method as the host calls it. `args` is the unchecked JSON. */
+export type AppApiMethod<State extends object = Record<string, never>> = (ctx: AppContext<State>, args: unknown) => unknown;
+/**
+ * Bound for a method `defineApp` accepts.
+ * A named `args` object is inferred from the method the author wrote.
+ * An unnamed parameter stays `any`: the host may pass any object.
+ * `defineApp` returns the inferred method, not this bound.
+ */
+type DeclaredMethod<State extends object> = (ctx: AppContext<State>, args?: any) => unknown;
+/** What `defineApp` accepts. `api` keeps the methods the author wrote. */
+export interface AppDefinition<State extends object = Record<string, never>> {
+    name: string;
+    description: string;
+    api: Record<string, DeclaredMethod<State>>;
+    state?: State;
+}
+/**
+ * Validate and return the same definition object.
+ * `State` is inferred from `state`. An omitted `state` has no keys.
+ * @param def - author declaration
+ */
+export declare function defineApp<State extends object, Definition extends AppDefinition<State>>(def: Definition & AppDefinition<State>): Definition;
+export {};
+//# sourceMappingURL=define-app.d.ts.map

package/lib/types/define-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-app.d.ts","sourceRoot":"","sources":["../../src/define-app.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAG9C,6EAA6E;AAC7E,MAAM,MAAM,YAAY,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CACvE,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,EACtB,IAAI,EAAE,OAAO,KACV,OAAO,CAAA;AAEZ;;;;;GAKG;AACH,KAAK,cAAc,CAAC,KAAK,SAAS,MAAM,IAAI,CAC1C,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,EAEtB,IAAI,CAAC,EAAE,GAAG,KACP,OAAO,CAAA;AAEZ,0EAA0E;AAC1E,MAAM,WAAW,aAAa,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;IACzE,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,CAAA;IAC1C,KAAK,CAAC,EAAE,KAAK,CAAA;CACd;AAMD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,SAAS,MAAM,EAAE,UAAU,SAAS,aAAa,CAAC,KAAK,CAAC,EACrF,GAAG,EAAE,UAAU,GAAG,aAAa,CAAC,KAAK,CAAC,GACrC,UAAU,CAWZ"}

package/lib/types/entries.d.ts

@@ -0,0 +1,16 @@
+/** Required files and side trees. Callers use these names; they do not spell them again. */
+export declare const appEntries: {
+    readonly manifest: "manifest.json";
+    readonly ui: "ui.tsx";
+    readonly backend: "main.api.ts";
+    readonly stylesheet: "ui.css";
+};
+/** Optional trees. `schema` is numbered SQL. `assets` is UI files loaded by URL. The others are import sides. */
+export declare const appTrees: {
+    readonly ui: "ui";
+    readonly api: "api";
+    readonly shared: "shared";
+    readonly schema: "schema";
+    readonly assets: "assets";
+};
+//# sourceMappingURL=entries.d.ts.map

package/lib/types/entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entries.d.ts","sourceRoot":"","sources":["../../src/entries.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,eAAO,MAAM,UAAU;;;;;CAKb,CAAA;AAEV,iHAAiH;AACjH,eAAO,MAAM,QAAQ;;;;;;CAMX,CAAA"}

package/lib/types/event-type.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Every `type` on `ctx.llm` when `stream` is true.
+ * `done` is that call's final string. The method return is not one of these.
+ */
+export declare const llmEventType: {
+    readonly status: "status";
+    readonly textDelta: "text-delta";
+    readonly error: "error";
+    readonly done: "done";
+};
+/**
+ * Every `type` on `ctx.agent` when `stream` is true.
+ * `done` is that call's final string. `tool` and `turn` are agent-only.
+ */
+export declare const agentEventType: {
+    readonly tool: "tool";
+    readonly turn: "turn";
+    readonly status: "status";
+    readonly textDelta: "text-delta";
+    readonly error: "error";
+    readonly done: "done";
+};
+/** Every `type` on either model stream. */
+export declare const eventType: {
+    readonly tool: "tool";
+    readonly turn: "turn";
+    readonly status: "status";
+    readonly textDelta: "text-delta";
+    readonly error: "error";
+    readonly done: "done";
+};
+export type LlmEventType = (typeof llmEventType)[keyof typeof llmEventType];
+export type AgentEventType = (typeof agentEventType)[keyof typeof agentEventType];
+export type EventType = (typeof eventType)[keyof typeof eventType];
+//# sourceMappingURL=event-type.d.ts.map

package/lib/types/event-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-type.d.ts","sourceRoot":"","sources":["../../src/event-type.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;CAKf,CAAA;AAEV;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;;;CAIjB,CAAA;AAEV,2CAA2C;AAC3C,eAAO,MAAM,SAAS;;;;;;;CAEZ,CAAA;AAEV,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAA;AAE3E,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAA;AAEjF,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAA"}

package/lib/types/imports.d.ts

@@ -0,0 +1,17 @@
+import { type DefinitionCode } from './codes.ts';
+/** Which side of the app is importing. */
+export type ImportSide = 'ui' | 'backend' | 'shared';
+/**
+ * Classify a relative or side-crossing import. Bare allowlist checks stay with the host table.
+ * @param specifier - the import specifier as written
+ * @param side - the file's side
+ * @returns a code when the specifier is illegal, otherwise undefined
+ */
+export declare function classifyImport(specifier: string, side: ImportSide, fromFile?: string): DefinitionCode | undefined;
+/**
+ * Throw when {@link classifyImport} returns a code.
+ * @param specifier - the import specifier as written
+ * @param side - the file's side
+ */
+export declare function assertImportAllowed(specifier: string, side: ImportSide): void;
+//# sourceMappingURL=imports.d.ts.map

package/lib/types/imports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imports.d.ts","sourceRoot":"","sources":["../../src/imports.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,YAAY,CAAA;AAG/D,0CAA0C;AAC1C,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,SAAS,GAAG,QAAQ,CAAA;AAsBpD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,SAAW,GAAG,cAAc,GAAG,SAAS,CAWnH;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CAI7E"}

package/lib/types/index.d.ts

@@ -0,0 +1,12 @@
+/** App definition: ids, manifest, imports, `defineApp`, `ctx`. No I/O. @module @mohou/contract */
+export declare const packageId: "@mohou/contract";
+export { parseAppId, type AppId } from './app-id.ts';
+export { appEntries, appTrees } from './entries.ts';
+export { resolveManifest, type Manifest } from './manifest.ts';
+export { builtinWorkbenchId, workbenchEntries, type AppListItem, type AppWorkbench, type WorkbenchEntry, } from './workbench.ts';
+export { assertImportAllowed, classifyImport, type ImportSide } from './imports.ts';
+export { defineApp, type AppApiMethod, type AppDefinition } from './define-app.ts';
+export { ContractError, definitionCodes, type DefinitionCode } from './codes.ts';
+export { agentEventType, eventType, llmEventType, type AgentEventType, type EventType, type LlmEventType } from './event-type.ts';
+export type { AppAgentEvent, AppAgentOptions, AppAgentTurnEndReason, AppConfig, AppContext, AppCredentials, AppHttpRequest, AppHttpResponse, AppKeyValueTable, AppLlmEvent, AppLlmOptions, AppModelOptions, AppStorage, AppSystemMetrics, SqlParams, SqlRow, SqlValue, } from './context.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAElG,eAAO,MAAM,SAAS,EAAG,iBAA0B,CAAA;AAEnD,OAAO,EAAE,UAAU,EAAE,KAAK,KAAK,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,eAAe,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC9D,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAA;AACnF,OAAO,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAClF,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAA;AAChF,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAA;AACjI,YAAY,EACV,aAAa,EACb,eAAe,EACf,qBAAqB,EACrB,SAAS,EACT,UAAU,EACV,cAAc,EACd,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,eAAe,EACf,UAAU,EACV,gBAAgB,EAChB,SAAS,EACT,MAAM,EACN,QAAQ,GACT,MAAM,cAAc,CAAA"}

package/lib/types/manifest.d.ts

@@ -0,0 +1,20 @@
+import { type AppId } from './app-id.ts';
+import { appEntries } from './entries.ts';
+/** Manifest fields the loader accepts. Acronym derivation is not done here. */
+export interface Manifest {
+    readonly id: AppId;
+    readonly name: string;
+    readonly description: string;
+    readonly version: string;
+    readonly entry: typeof appEntries.ui;
+    readonly acronym?: string;
+    readonly tags?: readonly string[];
+    readonly kind?: 'workbench';
+}
+/**
+ * Admit manifest JSON. `directoryName` is the app directory name, not a path.
+ * @param raw - parsed JSON, still untrusted
+ * @param directoryName - directory that contains the file
+ */
+export declare function resolveManifest(raw: unknown, directoryName: string): Manifest;
+//# sourceMappingURL=manifest.d.ts.map

package/lib/types/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/manifest.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,KAAK,KAAK,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEzC,+EAA+E;AAC/E,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,UAAU,CAAC,EAAE,CAAA;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAA;CAC5B;AAiBD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,GAAG,QAAQ,CA+B7E"}

package/lib/types/workbench.d.ts

@@ -0,0 +1,38 @@
+/** Builtin workbench id. `setDefaultWorkbench` of this id shows the panel library. */
+export declare const builtinWorkbenchId = "default";
+/** One app on the owner list. Omitted fields were not present. */
+export interface AppListItem {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly version: string;
+    readonly acronym: string;
+    readonly tags?: readonly string[];
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly activity?: {
+        readonly openCount: number;
+        readonly lastOpenedAt: string;
+    };
+    readonly kind?: 'workbench';
+}
+/** One workbench the slot can show. `default` is the one the slot will use. */
+export interface WorkbenchEntry {
+    readonly id: string;
+    readonly name: string;
+    readonly builtin: boolean;
+    readonly default: boolean;
+}
+/**
+ * Extra ctx on a workbench app. Absent on every other app.
+ * The methods do not read another app's files or storage, and they do not change settings.
+ */
+export interface AppWorkbench {
+    listApps(): Promise<readonly AppListItem[]>;
+    openApp(appId: string, title?: string): Promise<void>;
+    listWorkbenches(): Promise<readonly WorkbenchEntry[]>;
+    setDefaultWorkbench(id: string): Promise<void>;
+}
+/** One list for the builtin library and for `ctx.workbench.listWorkbenches`. */
+export declare function workbenchEntries(apps: readonly AppListItem[], storedId: string | undefined, builtinName: string): readonly WorkbenchEntry[];
+//# sourceMappingURL=workbench.d.ts.map

package/lib/types/workbench.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbench.d.ts","sourceRoot":"","sources":["../../src/workbench.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,eAAO,MAAM,kBAAkB,YAAY,CAAA;AAE3C,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAA;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAA;CAC5B;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,IAAI,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAA;IAC3C,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrD,eAAe,IAAI,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC,CAAA;IACrD,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/C;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,WAAW,EAAE,MAAM,GAClB,SAAS,cAAc,EAAE,CAe3B"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@mohou/contract",
+  "version": "1.0.20",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "lib/types",
+    "README.md",
+    "!**/*.tsbuildinfo"
+  ],
+  "main": "./src/index.ts",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./event-type": "./src/event-type.ts",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@mohou/values": "^1.0.20"
+  }
+}

package/src/app-id.ts

@@ -0,0 +1,20 @@
+import type { Branded } from '@mohou/values'
+
+import { ContractError } from './codes.ts'
+
+const appIdPattern = /^[a-z][a-z0-9-]*(\.[a-z0-9-]+)+$/
+
+/** Reverse-DNS app id admitted at this boundary. */
+export type AppId = Branded<'AppId'>
+
+/**
+ * Admit an app id. Callers do not re-parse the brand.
+ * @param value - untrusted id text
+ * @returns the branded id
+ */
+export function parseAppId(value: string): AppId {
+  if (!appIdPattern.test(value)) {
+    throw new ContractError('app-id-invalid', `app id is not reverse-DNS: ${value}`)
+  }
+  return value as AppId
+}

package/src/codes.ts

@@ -0,0 +1,32 @@
+/**
+ * Codes this definition emits. Other surfaces declare their own codes.
+ * Callers match `code`, not the message.
+ * @module @mohou/contract
+ */
+
+export const definitionCodes = [
+  'app-id-invalid',
+  'manifest-invalid',
+  'import-forbidden',
+  'import-escape',
+  'define-app-invalid',
+] as const
+
+/** A failure emitted by this definition. */
+export type DefinitionCode = (typeof definitionCodes)[number]
+
+/** Failure a caller branches on. The message is for a person. */
+export class ContractError extends Error {
+  readonly code: DefinitionCode
+
+  /**
+   * @param code - one of {@link definitionCodes}
+   * @param message - human text; not the match key
+   * @param options - optional `cause` for the original failure
+   */
+  constructor(code: DefinitionCode, message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'ContractError'
+    this.code = code
+  }
+}

package/src/context.ts

@@ -0,0 +1,154 @@
+import type { AppId } from './app-id.ts'
+import type { AppWorkbench } from './workbench.ts'
+
+import { agentEventType, llmEventType } from './event-type.ts'
+
+/** A cell accepted by SQLite. */
+export type SqlValue = null | number | string | bigint | Uint8Array
+
+/** One result row. Column names are the keys. */
+export interface SqlRow {
+  [column: string]: SqlValue
+}
+
+/** Positional or named parameters. Named keys omit the sigil. */
+export type SqlParams = readonly SqlValue[] | Record<string, SqlValue>
+
+/** The host-owned `kv` table. `query` and `run` cannot see it. */
+export interface AppKeyValueTable {
+  get(key: string): Promise<unknown>
+  set(key: string, value: unknown): Promise<void>
+  delete(key: string): Promise<void>
+  clear(): Promise<void>
+}
+
+/** One SQLite file. `kv()` is the key-value table. SQL is everything else. */
+export interface AppStorage {
+  kv(): AppKeyValueTable
+  query(sql: string, params?: SqlParams): Promise<SqlRow[]>
+  run(sql: string, params?: SqlParams): Promise<{ changes: number; lastInsertRowid: number | bigint }>
+  transaction<T>(work: (tx: AppStorage) => Promise<T>): Promise<T>
+}
+
+/** `ctx.http` request. Object `body` is sent as JSON. */
+export interface AppHttpRequest {
+  url: string
+  method?: string
+  headers?: Record<string, string>
+  query?: Record<string, string | number | boolean | null | undefined>
+  body?: unknown
+  timeout?: number
+  signal?: AbortSignal
+}
+
+/** `ctx.http` result. Never a platform `Response`. */
+export interface AppHttpResponse {
+  ok: boolean
+  status: number
+  headers: Record<string, string>
+  text: string
+  /** Parsed body when the content type contains json and parsing succeeds, otherwise null. */
+  json: unknown
+}
+
+/** Options shared by `ctx.llm` and `ctx.agent`. Omitted limits use host policy. */
+export interface AppModelOptions {
+  provider?: string
+  model?: string
+  system?: string
+  schema?: unknown
+  maxTokens?: number
+  /** Attempts in total, including the first. */
+  retryTimes?: number
+  signal?: AbortSignal
+}
+
+/** Why an agent turn ended. `kind` stays open so a provider can add a reason. */
+export interface AppAgentTurnEndReason {
+  kind: string
+  error?: unknown
+  reason?: unknown
+}
+
+/** Observation only. The `ctx.agent` return stays a string. */
+export type AppAgentEvent =
+  | { type: typeof agentEventType.status; status: 'running' | 'idle' }
+  | { type: typeof agentEventType.textDelta; text: string }
+  | { type: typeof agentEventType.tool; phase: 'start' | 'end'; name: string; args?: unknown; result?: unknown }
+  | { type: typeof agentEventType.turn; phase: 'start'; turn: number }
+  | { type: typeof agentEventType.turn; phase: 'end'; turn: number; reason?: AppAgentTurnEndReason }
+  | { type: typeof agentEventType.error; message: string }
+  | { type: typeof agentEventType.done; text: string }
+
+/** Observation for `ctx.llm` when `stream` is true. The return stays a string. */
+export type AppLlmEvent =
+  | { type: typeof llmEventType.status; status: 'running' | 'idle' }
+  | { type: typeof llmEventType.textDelta; text: string }
+  | { type: typeof llmEventType.error; message: string }
+  | { type: typeof llmEventType.done; text: string }
+
+/** `ctx.llm` options. `stream` defaults to false. */
+export interface AppLlmOptions extends AppModelOptions {
+  /** When true, the call returns a stream the method reads with `for await`. It does not reach the UI by itself. */
+  stream?: boolean
+}
+
+/** `ctx.agent` options. `stream` defaults to false. */
+export interface AppAgentOptions extends AppModelOptions {
+  /** When true, the call returns a stream the method reads with `for await`. It does not reach the UI by itself. */
+  stream?: boolean
+  maxIterations?: number
+  cwdType?: 'app' | 'process' | 'temp' | 'custom'
+  cwd?: string
+}
+
+/** Public host policy visible to an app. No secrets. */
+export interface AppConfig {
+  theme: 'light' | 'dark' | 'system'
+  palette: string
+  locale: string
+  chatLanguage: string
+  hostPort: number
+  llm: { provider: string; model: string } | null
+}
+
+/** One OS snapshot. `loadavg` is null where the OS does not provide it. */
+export interface AppSystemMetrics {
+  platform: string
+  arch: string
+  hostname: string
+  uptimeSec: number
+  loadavg: { '1m': number; '5m': number; '15m': number } | null
+  memory: { total: number; free: number; used: number; usedRatio: number }
+  cpu: { count: number; model: string; speedMHz: number }
+  collectedAt: string
+}
+
+/** One secret, by the name the owner stored. Listing is not on this object. */
+export interface AppCredentials {
+  get(name: string): Promise<string | undefined>
+}
+
+/** First argument of every `api` method. `State` is the object the author declared. */
+export interface AppContext<State extends object = Record<string, never>> {
+  appId: AppId
+  appDir: string
+  storage: AppStorage
+  state: State
+  credentials: AppCredentials
+  config: AppConfig
+  log(...args: unknown[]): void
+  signal?: AbortSignal
+  push(name: string, params?: unknown): void
+  http(url: string | AppHttpRequest, opts?: Omit<AppHttpRequest, 'url'>): Promise<AppHttpResponse>
+  bash(command: string): Promise<{ stdout: string; stderr: string; exitCode: number }>
+  pwsh(command: string): Promise<{ stdout: string; stderr: string; exitCode: number }>
+  system: { metrics(): Promise<AppSystemMetrics> }
+  llm(prompt: string, opts: AppLlmOptions & { stream: true }): AsyncIterable<AppLlmEvent> & Promise<string>
+  llm(prompt: string, opts?: AppLlmOptions): Promise<string>
+  agent(goal: string, opts: AppAgentOptions & { stream: true }): AsyncIterable<AppAgentEvent> & Promise<string>
+  agent(goal: string, opts?: AppAgentOptions): Promise<string>
+  mcp(serverId: string, toolName: string, args?: Record<string, unknown>): Promise<unknown>
+  /** Present only when the manifest kind is `workbench`. */
+  workbench?: AppWorkbench
+}

package/src/define-app.ts

@@ -0,0 +1,52 @@
+import type { AppContext } from './context.ts'
+import { ContractError } from './codes.ts'
+
+/** One backend method as the host calls it. `args` is the unchecked JSON. */
+export type AppApiMethod<State extends object = Record<string, never>> = (
+  ctx: AppContext<State>,
+  args: unknown,
+) => unknown
+
+/**
+ * Bound for a method `defineApp` accepts.
+ * A named `args` object is inferred from the method the author wrote.
+ * An unnamed parameter stays `any`: the host may pass any object.
+ * `defineApp` returns the inferred method, not this bound.
+ */
+type DeclaredMethod<State extends object> = (
+  ctx: AppContext<State>,
+  // oxlint-disable-next-line typescript/no-explicit-any -- unnamed args accept the unchecked object; a named object is inferred
+  args?: any,
+) => unknown
+
+/** What `defineApp` accepts. `api` keeps the methods the author wrote. */
+export interface AppDefinition<State extends object = Record<string, never>> {
+  name: string
+  description: string
+  api: Record<string, DeclaredMethod<State>>
+  state?: State
+}
+
+function isObject(value: unknown): value is object {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Validate and return the same definition object.
+ * `State` is inferred from `state`. An omitted `state` has no keys.
+ * @param def - author declaration
+ */
+export function defineApp<State extends object, Definition extends AppDefinition<State>>(
+  def: Definition & AppDefinition<State>,
+): Definition {
+  if (!def.name || !def.description) {
+    throw new ContractError('define-app-invalid', 'defineApp requires name and description')
+  }
+  if (!isObject(def.api)) {
+    throw new ContractError('define-app-invalid', 'defineApp.api must be an object')
+  }
+  if (def.state !== undefined && !isObject(def.state)) {
+    throw new ContractError('define-app-invalid', 'defineApp.state must be an object')
+  }
+  return def
+}

package/src/entries.ts

@@ -0,0 +1,16 @@
+/** Required files and side trees. Callers use these names; they do not spell them again. */
+export const appEntries = {
+  manifest: 'manifest.json',
+  ui: 'ui.tsx',
+  backend: 'main.api.ts',
+  stylesheet: 'ui.css',
+} as const
+
+/** Optional trees. `schema` is numbered SQL. `assets` is UI files loaded by URL. The others are import sides. */
+export const appTrees = {
+  ui: 'ui',
+  api: 'api',
+  shared: 'shared',
+  schema: 'schema',
+  assets: 'assets',
+} as const

package/src/event-type.ts

@@ -0,0 +1,31 @@
+/**
+ * Every `type` on `ctx.llm` when `stream` is true.
+ * `done` is that call's final string. The method return is not one of these.
+ */
+export const llmEventType = {
+  status: 'status',
+  textDelta: 'text-delta',
+  error: 'error',
+  done: 'done',
+} as const
+
+/**
+ * Every `type` on `ctx.agent` when `stream` is true.
+ * `done` is that call's final string. `tool` and `turn` are agent-only.
+ */
+export const agentEventType = {
+  ...llmEventType,
+  tool: 'tool',
+  turn: 'turn',
+} as const
+
+/** Every `type` on either model stream. */
+export const eventType = {
+  ...agentEventType,
+} as const
+
+export type LlmEventType = (typeof llmEventType)[keyof typeof llmEventType]
+
+export type AgentEventType = (typeof agentEventType)[keyof typeof agentEventType]
+
+export type EventType = (typeof eventType)[keyof typeof eventType]

package/src/imports.ts

@@ -0,0 +1,55 @@
+import { ContractError, type DefinitionCode } from './codes.ts'
+import { appEntries, appTrees } from './entries.ts'
+
+/** Which side of the app is importing. */
+export type ImportSide = 'ui' | 'backend' | 'shared'
+
+function crosses(specifier: string, tree: string): boolean {
+  return specifier === tree || specifier.startsWith(`${tree}/`) || specifier.includes(`/${tree}/`)
+}
+
+function escapesApp(specifier: string, fromFile: string): boolean {
+  if (specifier.startsWith('/') || /^[A-Za-z]:[\\/]/.test(specifier)) return true
+  if (!specifier.startsWith('.')) return false
+  const parts = fromFile.split('/').slice(0, -1).filter(part => part.length > 0)
+  for (const part of specifier.split('/')) {
+    if (part === '' || part === '.') continue
+    if (part === '..') {
+      if (parts.length === 0) return true
+      parts.pop()
+    } else {
+      parts.push(part)
+    }
+  }
+  return false
+}
+
+/**
+ * Classify a relative or side-crossing import. Bare allowlist checks stay with the host table.
+ * @param specifier - the import specifier as written
+ * @param side - the file's side
+ * @returns a code when the specifier is illegal, otherwise undefined
+ */
+export function classifyImport(specifier: string, side: ImportSide, fromFile = 'ui.tsx'): DefinitionCode | undefined {
+  if (escapesApp(specifier, fromFile)) return 'import-escape'
+  if (crosses(specifier, appTrees.assets)) return 'import-forbidden'
+  if (side === 'ui' && (specifier === appEntries.backend || crosses(specifier, appTrees.api))) {
+    return 'import-forbidden'
+  }
+  if (side === 'backend' && crosses(specifier, appTrees.ui)) return 'import-forbidden'
+  if (side === 'shared' && (crosses(specifier, appTrees.ui) || crosses(specifier, appTrees.api) || specifier === appEntries.backend)) {
+    return 'import-forbidden'
+  }
+  return undefined
+}
+
+/**
+ * Throw when {@link classifyImport} returns a code.
+ * @param specifier - the import specifier as written
+ * @param side - the file's side
+ */
+export function assertImportAllowed(specifier: string, side: ImportSide): void {
+  const code = classifyImport(specifier, side)
+  if (code === undefined) return
+  throw new ContractError(code, `${side} cannot import ${specifier}`)
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+/** App definition: ids, manifest, imports, `defineApp`, `ctx`. No I/O. @module @mohou/contract */
+
+export const packageId = '@mohou/contract' as const
+
+export { parseAppId, type AppId } from './app-id.ts'
+export { appEntries, appTrees } from './entries.ts'
+export { resolveManifest, type Manifest } from './manifest.ts'
+export {
+  builtinWorkbenchId,
+  workbenchEntries,
+  type AppListItem,
+  type AppWorkbench,
+  type WorkbenchEntry,
+} from './workbench.ts'
+export { assertImportAllowed, classifyImport, type ImportSide } from './imports.ts'
+export { defineApp, type AppApiMethod, type AppDefinition } from './define-app.ts'
+export { ContractError, definitionCodes, type DefinitionCode } from './codes.ts'
+export { agentEventType, eventType, llmEventType, type AgentEventType, type EventType, type LlmEventType } from './event-type.ts'
+export type {
+  AppAgentEvent,
+  AppAgentOptions,
+  AppAgentTurnEndReason,
+  AppConfig,
+  AppContext,
+  AppCredentials,
+  AppHttpRequest,
+  AppHttpResponse,
+  AppKeyValueTable,
+  AppLlmEvent,
+  AppLlmOptions,
+  AppModelOptions,
+  AppStorage,
+  AppSystemMetrics,
+  SqlParams,
+  SqlRow,
+  SqlValue,
+} from './context.ts'

package/src/manifest.ts

@@ -0,0 +1,97 @@
+import { ContractError } from './codes.ts'
+import { parseAppId, type AppId } from './app-id.ts'
+import { appEntries } from './entries.ts'
+
+/** Manifest fields the loader accepts. Acronym derivation is not done here. */
+export interface Manifest {
+  readonly id: AppId
+  readonly name: string
+  readonly description: string
+  readonly version: string
+  readonly entry: typeof appEntries.ui
+  readonly acronym?: string
+  readonly tags?: readonly string[]
+  readonly kind?: 'workbench'
+}
+
+const acronymToken = /^[\p{L}\p{N}]{2}$/u
+const tagToken = /^[a-z][a-z0-9-]*$/
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function requiredString(record: Record<string, unknown>, key: string): string {
+  const value = record[key]
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new ContractError('manifest-invalid', `manifest ${key} is required`)
+  }
+  return value
+}
+
+/**
+ * Admit manifest JSON. `directoryName` is the app directory name, not a path.
+ * @param raw - parsed JSON, still untrusted
+ * @param directoryName - directory that contains the file
+ */
+export function resolveManifest(raw: unknown, directoryName: string): Manifest {
+  if (!isRecord(raw)) {
+    throw new ContractError('manifest-invalid', 'manifest must be an object')
+  }
+  const name = requiredString(raw, 'name')
+  const description = requiredString(raw, 'description')
+  const version = requiredString(raw, 'version')
+  const entry = requiredString(raw, 'entry')
+  if (entry !== appEntries.ui) {
+    throw new ContractError('manifest-invalid', `manifest entry must be ${appEntries.ui}`)
+  }
+  const idText = requiredString(raw, 'id')
+  let id: AppId
+  try {
+    id = parseAppId(idText)
+  } catch (error) {
+    throw new ContractError('app-id-invalid', `app id is not reverse-DNS: ${idText}`, { cause: error })
+  }
+  if (id !== directoryName) {
+    throw new ContractError('app-id-invalid', `app id ${idText} does not match directory ${directoryName}`)
+  }
+  const acronym = resolveAcronym(raw.acronym)
+  const tags = resolveTags(raw.tags)
+  const kind = resolveKind(raw.kind)
+  const admitted = { id, name, description, version, entry: appEntries.ui }
+  return {
+    ...admitted,
+    ...acronym === undefined ? {} : { acronym },
+    ...tags === undefined ? {} : { tags },
+    ...kind === undefined ? {} : { kind },
+  }
+}
+
+function resolveAcronym(value: unknown): string | undefined {
+  if (value === undefined) return undefined
+  if (typeof value !== 'string' || !acronymToken.test(value)) {
+    throw new ContractError('manifest-invalid', 'manifest acronym must be two letters or digits')
+  }
+  return value
+}
+
+function resolveKind(value: unknown): 'workbench' | undefined {
+  if (value === undefined || value === 'app') return undefined
+  if (value === 'workbench') return 'workbench'
+  throw new ContractError('manifest-invalid', 'manifest kind must be app or workbench')
+}
+
+function resolveTags(value: unknown): readonly string[] | undefined {
+  if (value === undefined) return undefined
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new ContractError('manifest-invalid', 'manifest tags must be a non-empty list')
+  }
+  const tags: string[] = []
+  for (const tag of value) {
+    if (typeof tag !== 'string' || !tagToken.test(tag)) {
+      throw new ContractError('manifest-invalid', 'manifest tag must be a lowercase token')
+    }
+    if (!tags.includes(tag)) tags.push(tag)
+  }
+  return tags
+}

package/src/workbench.ts

@@ -0,0 +1,57 @@
+/** Builtin workbench id. `setDefaultWorkbench` of this id shows the panel library. */
+export const builtinWorkbenchId = 'default'
+
+/** One app on the owner list. Omitted fields were not present. */
+export interface AppListItem {
+  readonly id: string
+  readonly name: string
+  readonly description: string
+  readonly version: string
+  readonly acronym: string
+  readonly tags?: readonly string[]
+  readonly createdAt?: string
+  readonly updatedAt?: string
+  readonly activity?: { readonly openCount: number; readonly lastOpenedAt: string }
+  readonly kind?: 'workbench'
+}
+
+/** One workbench the slot can show. `default` is the one the slot will use. */
+export interface WorkbenchEntry {
+  readonly id: string
+  readonly name: string
+  readonly builtin: boolean
+  readonly default: boolean
+}
+
+/**
+ * Extra ctx on a workbench app. Absent on every other app.
+ * The methods do not read another app's files or storage, and they do not change settings.
+ */
+export interface AppWorkbench {
+  listApps(): Promise<readonly AppListItem[]>
+  openApp(appId: string, title?: string): Promise<void>
+  listWorkbenches(): Promise<readonly WorkbenchEntry[]>
+  setDefaultWorkbench(id: string): Promise<void>
+}
+
+/** One list for the builtin library and for `ctx.workbench.listWorkbenches`. */
+export function workbenchEntries(
+  apps: readonly AppListItem[],
+  storedId: string | undefined,
+  builtinName: string,
+): readonly WorkbenchEntry[] {
+  const active = storedId !== undefined
+    && storedId !== builtinWorkbenchId
+    && apps.some(app => app.id === storedId && app.kind === 'workbench')
+    ? storedId
+    : builtinWorkbenchId
+  return [
+    { id: builtinWorkbenchId, name: builtinName, builtin: true, default: active === builtinWorkbenchId },
+    ...apps.filter(app => app.kind === 'workbench').map(app => ({
+      id: app.id,
+      name: app.name,
+      builtin: false,
+      default: app.id === active,
+    })),
+  ]
+}