@nodetool-ai/websocket 0.7.0-rc.23 → 0.8.2

package/dist/lib/document-model-interfaces.js

@@ -0,0 +1,296 @@
+/**
+ * The model interfaces a graph uses to reach the documents a director approves:
+ * storyboards and the entity library.
+ *
+ * They live here rather than in `session/model-interfaces.ts` so the CLI's
+ * local (no-server) runs get the same implementations — a `nodetool debug` run
+ * of a graph that recasts a board has to write the same rows the server does,
+ * or the harness proves nothing about the server.
+ */
+import { Asset, ImageDocument, Script, Storyboard, TimelineSequence, entityFromAsset } from "@nodetool-ai/models";
+import { ENTITY_METADATA_KEY, isRecord, readEntityMarker } from "@nodetool-ai/protocol";
+/** How many of the caller's image assets a library scan reads. */
+const ENTITY_ASSET_LIMIT = 1000;
+const norm = (value) => value.trim().toLowerCase();
+/**
+ * The entity row an upsert writes to: the one a previous run of the same graph
+ * made (`source.key`), else the one with the same kind and name in the same
+ * project. Null when neither exists and the entity is new.
+ *
+ * A caller that gives a key never lands on a row carrying a *different* key.
+ * Two SKUs of one product share a display name, so name matching would make the
+ * second SKU overwrite the first's descriptor, picture and key — and inherit
+ * its recast mapping. A row carrying no key of its own is still fair game: that
+ * is how an entity a person made by hand becomes the graph's on the first keyed
+ * run, instead of gaining a duplicate beside it.
+ */
+async function findUpsertTarget(args) {
+    const [assets] = await Asset.paginate(args.userId, {
+        contentType: "image",
+        projectId: args.projectId,
+        limit: ENTITY_ASSET_LIMIT
+    });
+    const markers = assets.map((asset) => [asset, readEntityMarker(asset.metadata)]);
+    const key = args.source?.key?.trim();
+    if (key) {
+        const bySource = markers.find(([, marker]) => marker?.source?.key === key);
+        if (bySource)
+            return bySource[0];
+    }
+    const name = norm(args.name);
+    const byName = markers.find(([, marker]) => !!marker &&
+        marker.kind === args.kind &&
+        norm(marker.name) === name &&
+        (!key || !marker.source?.key?.trim()));
+    return byName?.[0] ?? null;
+}
+/**
+ * Write the marker fields onto an asset's metadata and save it. Optional
+ * fields are left alone when the caller did not pass them, so a re-run that
+ * only knows the name and descriptor does not wipe a hand-written description.
+ */
+async function writeEntityMarker(asset, args) {
+    const refusal = Asset.systemEntityRefusal(asset);
+    if (refusal) {
+        throw new Error(refusal);
+    }
+    const raw = asset.metadata?.[ENTITY_METADATA_KEY];
+    const marker = isRecord(raw) ? { ...raw } : {};
+    marker["kind"] = args.kind;
+    marker["name"] = args.name;
+    marker["descriptor"] = args.descriptor;
+    if (args.description !== undefined)
+        marker["description"] = args.description;
+    if (args.tags !== undefined)
+        marker["tags"] = args.tags;
+    if (args.voiceId !== undefined) {
+        if (args.voiceId === null)
+            delete marker["voice_id"];
+        else
+            marker["voice_id"] = args.voiceId;
+    }
+    if (args.source !== undefined)
+        marker["source"] = { ...args.source };
+    // A swap points the entity's picture at another asset rather than moving the
+    // marker: the id boards and scripts store is the marker asset's, and moving
+    // it would leave every one of those references dangling.
+    if (args.imageAssetId && args.imageAssetId !== asset.id) {
+        marker["reference_asset_id"] = args.imageAssetId;
+    }
+    else {
+        delete marker["reference_asset_id"];
+    }
+    asset.metadata = { ...(asset.metadata ?? {}), [ENTITY_METADATA_KEY]: marker };
+    if (args.projectId) {
+        asset.project_id = args.projectId;
+    }
+    await asset.save();
+    const entity = entityFromAsset(asset);
+    if (!entity) {
+        throw new Error(`Entity marker on asset ${asset.id} was not readable`);
+    }
+    return entity;
+}
+/** Storyboards, mirroring the script trio: owner-scoped reads, CAS updates. */
+export function storyboardModelInterfaces() {
+    return {
+        getStoryboard: async ({ userId, id }) => {
+            const board = await Storyboard.findById(id);
+            if (!board || board.user_id !== userId)
+                return null;
+            return board.toResponse();
+        },
+        listStoryboards: async ({ userId, projectId, limit }) => {
+            const boards = projectId
+                ? await Storyboard.listByProject(projectId, userId, limit)
+                : await Storyboard.listByUser(userId, limit);
+            return boards.map((board) => board.toResponse());
+        },
+        // Scoped, not listed: `listStoryboards` answers with a window of the most
+        // recently updated rows, and a catalog batch bigger than that window would
+        // stop finding the copies it made and re-render them every pass.
+        findRecastStoryboard: async ({ userId, projectId, templateId, recastKey }) => {
+            const board = await Storyboard.findRecast({
+                userId,
+                projectId,
+                templateId,
+                recastKey
+            });
+            return board ? board.toResponse() : null;
+        },
+        createStoryboard: async ({ userId, name, projectId, document }) => {
+            const board = new Storyboard({
+                user_id: userId,
+                name: name ?? "Untitled storyboard",
+                project_id: projectId ?? "default",
+                document: JSON.stringify(document)
+            });
+            await board.save();
+            return board.toResponse();
+        },
+        updateStoryboard: async ({ userId, id, document, timelineId, baseUpdatedAt }) => {
+            const existing = await Storyboard.findById(id);
+            if (!existing || existing.user_id !== userId)
+                return null;
+            const fields = {};
+            if (document !== undefined)
+                fields.document = JSON.stringify(document);
+            if (timelineId !== undefined)
+                fields.timeline_id = timelineId;
+            const updated = await Storyboard.updateFieldsIfUnchanged(id, baseUpdatedAt ?? existing.updated_at, fields);
+            return updated ? updated.toResponse() : null;
+        }
+    };
+}
+/**
+ * The entity library. An entity is an image asset carrying a marker, so every
+ * read here is an owner-scoped asset read and every write is a metadata write —
+ * the same path the `entities` agent capability takes.
+ */
+export function entityModelInterfaces() {
+    return {
+        listEntities: async ({ userId, projectId, kind, tags, nameContains, limit }) => {
+            const [assets] = await Asset.paginate(userId, {
+                contentType: "image",
+                projectId,
+                limit: ENTITY_ASSET_LIMIT
+            });
+            const wanted = nameContains ? norm(nameContains) : "";
+            const matched = assets
+                .map((asset) => entityFromAsset(asset))
+                .filter((entity) => entity !== null)
+                .filter((entity) => {
+                if (kind && entity.kind !== kind)
+                    return false;
+                if (wanted && !norm(entity.name).includes(wanted))
+                    return false;
+                if (tags && tags.length > 0) {
+                    const own = entity.tags ?? [];
+                    if (!tags.every((tag) => own.includes(tag)))
+                        return false;
+                }
+                return true;
+            });
+            return limit !== undefined
+                ? matched.slice(0, Math.max(limit, 0))
+                : matched;
+        },
+        getEntity: async ({ userId, id }) => {
+            // An asset owned by someone else reads as missing, and an untagged one is
+            // not an entity — the library only sees assets carrying the marker.
+            const asset = await Asset.find(userId, id);
+            return asset ? entityFromAsset(asset) : null;
+        },
+        upsertEntity: async (args) => {
+            const asset = await Asset.find(args.userId, args.imageAssetId);
+            if (!asset) {
+                throw new Error(`Asset ${args.imageAssetId} was not found`);
+            }
+            if (!asset.content_type.startsWith("image/")) {
+                throw new Error(`${asset.name || asset.id} is a ${asset.content_type} asset; entities are image assets`);
+            }
+            const validatedArgs = { ...args, imageAssetId: asset.id };
+            const existing = await findUpsertTarget(validatedArgs);
+            if (existing) {
+                return {
+                    entity: await writeEntityMarker(existing, validatedArgs),
+                    created: false
+                };
+            }
+            return { entity: await writeEntityMarker(asset, validatedArgs), created: true };
+        }
+    };
+}
+/** All three groups, for a host installing the whole document surface. */
+/**
+ * Scripts and timeline sequences, owner-scoped with CAS updates.
+ *
+ * These live here rather than beside the server session because the CLI
+ * installs this module: without them `nodetool debug` cannot run a single
+ * `nodetool.script.*` or `nodetool.timeline.*` node, which is most of what the
+ * graph-resource fixtures do.
+ */
+export function scriptModelInterfaces() {
+    return {
+        getTimelineSequence: async ({ userId, id }) => {
+            const seq = await TimelineSequence.findById(id);
+            if (!seq || seq.user_id !== userId)
+                return null;
+            return seq.toTimelineSequence();
+        },
+        createTimelineSequence: async ({ userId, sequence }) => {
+            const seq = TimelineSequence.fromTimelineSequence(userId, sequence);
+            await seq.save();
+            return seq.toTimelineSequence();
+        },
+        updateTimelineSequence: async ({ userId, id, sequence }) => {
+            const existing = await TimelineSequence.findById(id);
+            if (!existing || existing.user_id !== userId)
+                return null;
+            const next = TimelineSequence.fromTimelineSequence(userId, sequence);
+            const updated = await TimelineSequence.updateFieldsIfUnchanged(id, next.updated_at, {
+                name: next.name,
+                fps: next.fps,
+                width: next.width,
+                height: next.height,
+                duration_ms: next.duration_ms,
+                document: next.document
+            });
+            return updated ? updated.toTimelineSequence() : null;
+        },
+        getScript: async ({ userId, id }) => {
+            const script = await Script.findById(id);
+            if (!script || script.user_id !== userId)
+                return null;
+            return script.toResponse();
+        },
+        createScript: async ({ userId, name, projectId, document }) => {
+            const script = new Script({
+                user_id: userId,
+                name: name ?? "Untitled script",
+                project_id: projectId ?? "default",
+                document: JSON.stringify(document)
+            });
+            await script.save();
+            return script.toResponse();
+        },
+        updateScript: async ({ userId, id, document, timelineId, baseUpdatedAt }) => {
+            const existing = await Script.findById(id);
+            if (!existing || existing.user_id !== userId)
+                return null;
+            const fields = {};
+            if (document !== undefined)
+                fields.document = JSON.stringify(document);
+            if (timelineId !== undefined)
+                fields.timeline_id = timelineId;
+            const updated = await Script.updateFieldsIfUnchanged(id, baseUpdatedAt ?? existing.updated_at, fields);
+            return updated ? updated.toResponse() : null;
+        }
+    };
+}
+export function documentModelInterfaces() {
+    return {
+        getImageDocument: async ({ userId, id }) => {
+            const doc = await ImageDocument.findById(id);
+            if (!doc || doc.user_id !== userId)
+                return null;
+            return doc.toResponse();
+        },
+        createImageDocument: async ({ userId, name, projectId, width, height, document }) => {
+            const doc = new ImageDocument({
+                user_id: userId,
+                project_id: projectId ?? "default",
+                name,
+                width,
+                height,
+                document: JSON.stringify(document)
+            });
+            await doc.save();
+            return doc.toResponse();
+        },
+        ...scriptModelInterfaces(),
+        ...storyboardModelInterfaces(),
+        ...entityModelInterfaces()
+    };
+}
+//# sourceMappingURL=document-model-interfaces.js.map

package/dist/lib/document-model-interfaces.js.map

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

package/dist/lib/env-config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Small helpers for reading numeric / boolean configuration from environment
+ * variables. Kept dependency-free so config modules can share them.
+ */
+/** Parse a positive integer env var, falling back when unset or invalid. */
+export declare function parseIntEnv(name: string, fallback: number): number;
+/** Parse a boolean env var. Truthy values: "1", "true", "yes", "on". */
+export declare function parseBoolEnv(name: string): boolean;
+//# sourceMappingURL=env-config.d.ts.map

package/dist/lib/env-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-config.d.ts","sourceRoot":"","sources":["../../src/lib/env-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKlE;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGlD"}

package/dist/lib/env-config.js

@@ -0,0 +1,18 @@
+/**
+ * Small helpers for reading numeric / boolean configuration from environment
+ * variables. Kept dependency-free so config modules can share them.
+ */
+/** Parse a positive integer env var, falling back when unset or invalid. */
+export function parseIntEnv(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === "")
+        return fallback;
+    const value = Number(raw);
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
+/** Parse a boolean env var. Truthy values: "1", "true", "yes", "on". */
+export function parseBoolEnv(name) {
+    const raw = process.env[name]?.toLowerCase().trim();
+    return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+//# sourceMappingURL=env-config.js.map

package/dist/lib/env-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-config.js","sourceRoot":"","sources":["../../src/lib/env-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,4EAA4E;AAC5E,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,QAAgB;IACxD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,QAAQ,CAAC;IACrD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC5E,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;IACpD,OAAO,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,KAAK,IAAI,GAAG,KAAK,IAAI,CAAC;AACxE,CAAC"}

package/dist/lib/example-apps.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The shipped example apps: curated `ApplicationBundle` files that install into
+ * a user's library as a real app plus the workflows it binds.
+ *
+ * The bundles live next to the example workflows
+ * (`packages/base-nodes/nodetool/examples/apps/*.app.json`, built by
+ * `scripts/build-example-apps.mjs`) and are read straight off disk — an example
+ * is a file, not a database row, so listing one needs no user and installing
+ * one is just {@link importApplicationBundle} with that file's contents.
+ */
+import { type ApplicationBundle } from "@nodetool-ai/app-runtime";
+import { type ApplicationResponse, type ExampleAppSummary } from "@nodetool-ai/protocol/api-schemas/applications.js";
+export type { ExampleAppSummary };
+export interface ExampleAppsOptions {
+    examplesDir?: string;
+    examplesAssetsFallbackDir?: string;
+    exampleAppsDir?: string;
+}
+/**
+ * Where the bundles live: an explicit override, else the `apps` sibling of the
+ * example workflows directory — the layout the monorepo and the packaged
+ * backend share.
+ */
+export declare function resolveExampleAppsDir(options: ExampleAppsOptions): string | null;
+/** Every shipped example app, sorted by slug. Invalid files are skipped. */
+export declare function listExampleApps(options: ExampleAppsOptions): ExampleAppSummary[];
+/** One example's full bundle, or null when the slug names nothing shipped. */
+export declare function getExampleAppBundle(options: ExampleAppsOptions, slug: string): ApplicationBundle | null;
+/**
+ * One example's summary, or null when the slug names nothing shipped — what a
+ * recipe naming an app resolves through, so a recipe cannot advertise an app
+ * this install does not have.
+ */
+export declare function getExampleAppSummary(options: ExampleAppsOptions, slug: string): ExampleAppSummary | null;
+/**
+ * Shipped examples leave language models unselected, and a few name a model
+ * of one provider. Pick the model a user can actually run: every language
+ * model that is unselected, or whose provider is not configured, becomes the
+ * first recommended model whose provider is. Models of configured providers,
+ * and every model when nothing recommended is configured, stay as shipped.
+ * Works on any JSON value that carries model references: a graph or a bundle.
+ */
+export declare function localizeLanguageModels<T>(value: T, configuredProviderIds: ReadonlySet<string>): T;
+/**
+ * Install an example app: create the app and the workflows it binds, through
+ * the same import path a user's own bundle file takes. Workflows carrying a
+ * `sourceId` are created once per user, so installing two examples that share a
+ * template — Photo Studio and Concept Studio both bind Image Enhance — leaves
+ * one workflow row that both apps point at.
+ */
+export declare function installExampleApp(userId: string, options: ExampleAppsOptions, slug: string, projectId?: string): Promise<ApplicationResponse>;
+//# sourceMappingURL=example-apps.d.ts.map

package/dist/lib/example-apps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-apps.d.ts","sourceRoot":"","sources":["../../src/lib/example-apps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACvB,MAAM,mDAAmD,CAAC;AAa3D,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAElC,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAiCD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,kBAAkB,GAC1B,MAAM,GAAG,IAAI,CAOf;AA+BD,4EAA4E;AAC5E,wBAAgB,eAAe,CAC7B,OAAO,EAAE,kBAAkB,GAC1B,iBAAiB,EAAE,CAkBrB;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,MAAM,GACX,iBAAiB,GAAG,IAAI,CAgB1B;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,MAAM,GACX,iBAAiB,GAAG,IAAI,CAG1B;AAKD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,KAAK,EAAE,CAAC,EACR,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAAC,GACzC,CAAC,CA+BH;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,mBAAmB,CAAC,CAgB9B"}

package/dist/lib/example-apps.js

@@ -0,0 +1,192 @@
+/**
+ * The shipped example apps: curated `ApplicationBundle` files that install into
+ * a user's library as a real app plus the workflows it binds.
+ *
+ * The bundles live next to the example workflows
+ * (`packages/base-nodes/nodetool/examples/apps/*.app.json`, built by
+ * `scripts/build-example-apps.mjs`) and are read straight off disk — an example
+ * is a file, not a database row, so listing one needs no user and installing
+ * one is just {@link importApplicationBundle} with that file's contents.
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import nodePath from "node:path";
+import { parseApplicationBundle } from "@nodetool-ai/app-runtime";
+import { importApplicationBundleInput } from "@nodetool-ai/protocol/api-schemas/applications.js";
+import { isModelSelected } from "@nodetool-ai/protocol";
+import { RECOMMENDED_MODELS } from "@nodetool-ai/runtime";
+import { loadConfiguredProviders } from "../configured-providers.js";
+import { ApiErrorCode } from "../error-codes.js";
+import { deriveExampleAssetsDir } from "../example-workflows.js";
+import { throwApiError } from "../trpc/error-formatter.js";
+import { importApplicationBundle } from "./applications-service.js";
+import { withCacheBuster } from "./example-thumbnail.js";
+const BUNDLE_SUFFIX = ".app.json";
+const EXAMPLES_THUMBNAILS_PREFIX = "/api/workflows/examples/thumbnails/";
+/**
+ * The gallery art an app is shown with: `<slug>.jpg` when the app ships its
+ * own art, else the JPG of the first workflow it binds, served through the
+ * example-workflow thumbnail route. Null when the examples directory is
+ * unknown or no such art ships.
+ */
+function thumbnailFor(bundle, slug, options) {
+    if (!options.examplesDir)
+        return null;
+    const assetsDir = deriveExampleAssetsDir(options.examplesDir, options.examplesAssetsFallbackDir);
+    // The app's own art wins over its first bound workflow's art.
+    const first = bundle.workflows[0];
+    const candidates = [`${slug}.jpg`, ...(first ? [`${first.name}.jpg`] : [])];
+    for (const jpgFile of candidates) {
+        const jpgPath = nodePath.join(assetsDir, jpgFile);
+        if (existsSync(jpgPath)) {
+            return withCacheBuster(`${EXAMPLES_THUMBNAILS_PREFIX}${encodeURIComponent(jpgFile)}`, jpgPath);
+        }
+    }
+    return null;
+}
+/**
+ * Where the bundles live: an explicit override, else the `apps` sibling of the
+ * example workflows directory — the layout the monorepo and the packaged
+ * backend share.
+ */
+export function resolveExampleAppsDir(options) {
+    if (options.exampleAppsDir) {
+        return existsSync(options.exampleAppsDir) ? options.exampleAppsDir : null;
+    }
+    if (!options.examplesDir)
+        return null;
+    const sibling = nodePath.join(nodePath.dirname(options.examplesDir), "apps");
+    return existsSync(sibling) ? sibling : null;
+}
+function readBundle(dir, file) {
+    // Callers only pass names that came out of readdirSync, but resolve and
+    // check containment anyway so no future caller can read outside the
+    // examples directory by passing a path-shaped name.
+    const root = nodePath.resolve(dir);
+    const target = nodePath.resolve(root, file);
+    if (target !== root && !target.startsWith(root + nodePath.sep))
+        return null;
+    try {
+        return parseApplicationBundle(JSON.parse(readFileSync(target, "utf8")));
+    }
+    catch {
+        return null;
+    }
+}
+const slugOf = (file) => file.slice(0, -BUNDLE_SUFFIX.length);
+const summarize = (bundle, slug, options) => ({
+    slug,
+    name: bundle.name,
+    description: bundle.description,
+    workflows: bundle.workflows.map((workflow) => workflow.name),
+    operationCount: bundle.app.operations.length,
+    thumbnailUrl: thumbnailFor(bundle, slug, options)
+});
+/** Every shipped example app, sorted by slug. Invalid files are skipped. */
+export function listExampleApps(options) {
+    const dir = resolveExampleAppsDir(options);
+    if (!dir)
+        return [];
+    let files;
+    try {
+        files = readdirSync(dir)
+            .filter((file) => file.endsWith(BUNDLE_SUFFIX))
+            .sort((a, b) => a.localeCompare(b));
+    }
+    catch {
+        return [];
+    }
+    const apps = [];
+    for (const file of files) {
+        const bundle = readBundle(dir, file);
+        if (!bundle)
+            continue;
+        apps.push(summarize(bundle, slugOf(file), options));
+    }
+    return apps;
+}
+/** One example's full bundle, or null when the slug names nothing shipped. */
+export function getExampleAppBundle(options, slug) {
+    const dir = resolveExampleAppsDir(options);
+    if (!dir)
+        return null;
+    // Match the slug against what is actually shipped instead of building a path
+    // out of it: the file name that reaches readBundle comes from the directory
+    // listing, so a path-shaped slug can only fail to match.
+    let file;
+    try {
+        file = readdirSync(dir).find((entry) => entry.endsWith(BUNDLE_SUFFIX) && slugOf(entry) === slug);
+    }
+    catch {
+        return null;
+    }
+    if (!file)
+        return null;
+    return readBundle(dir, file);
+}
+/**
+ * One example's summary, or null when the slug names nothing shipped — what a
+ * recipe naming an app resolves through, so a recipe cannot advertise an app
+ * this install does not have.
+ */
+export function getExampleAppSummary(options, slug) {
+    const bundle = getExampleAppBundle(options, slug);
+    return bundle ? summarize(bundle, slug, options) : null;
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Shipped examples leave language models unselected, and a few name a model
+ * of one provider. Pick the model a user can actually run: every language
+ * model that is unselected, or whose provider is not configured, becomes the
+ * first recommended model whose provider is. Models of configured providers,
+ * and every model when nothing recommended is configured, stay as shipped.
+ * Works on any JSON value that carries model references: a graph or a bundle.
+ */
+export function localizeLanguageModels(value, configuredProviderIds) {
+    const fallback = RECOMMENDED_MODELS.find((model) => model.type === "language_model" &&
+        model.provider !== undefined &&
+        configuredProviderIds.has(model.provider));
+    if (!fallback)
+        return value;
+    const replacement = {
+        type: "language_model",
+        provider: fallback.provider,
+        id: fallback.id,
+        name: fallback.name,
+        path: null,
+        supported_tasks: []
+    };
+    const swap = (node) => {
+        if (Array.isArray(node))
+            return node.map(swap);
+        if (!isRecord(node))
+            return node;
+        if (node.type === "language_model" &&
+            (!isModelSelected(node) ||
+                !configuredProviderIds.has(String(node.provider)))) {
+            return { ...replacement };
+        }
+        return Object.fromEntries(Object.entries(node).map(([key, inner]) => [key, swap(inner)]));
+    };
+    return swap(value);
+}
+/**
+ * Install an example app: create the app and the workflows it binds, through
+ * the same import path a user's own bundle file takes. Workflows carrying a
+ * `sourceId` are created once per user, so installing two examples that share a
+ * template — Photo Studio and Concept Studio both bind Image Enhance — leaves
+ * one workflow row that both apps point at.
+ */
+export async function installExampleApp(userId, options, slug, projectId) {
+    const shipped = getExampleAppBundle(options, slug);
+    if (!shipped) {
+        throwApiError(ApiErrorCode.NOT_FOUND, `No example app named "${slug}"`);
+    }
+    const configured = new Set(Object.keys(await loadConfiguredProviders(userId)));
+    const bundle = localizeLanguageModels(shipped, configured);
+    const importInput = { bundle };
+    if (projectId) {
+        importInput.projectId = projectId;
+    }
+    return importApplicationBundle(userId, importApplicationBundleInput.parse(importInput));
+}
+//# sourceMappingURL=example-apps.js.map

package/dist/lib/example-apps.js.map

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

package/dist/lib/example-games.d.ts

@@ -0,0 +1,5 @@
+import { installExampleGameAssets as installAssets, type ExampleGameOptions } from "@nodetool-ai/agents/game-examples";
+export { getExampleGameBundle, listExampleGames, readExampleGameFile, resolveExampleGamesDir, type ExampleGameBundle, type ExampleGameOptions } from "@nodetool-ai/agents/game-examples";
+/** Install the shared shipped bundle through the server's configured storage. */
+export declare function installExampleGameAssets(userId: string, projectId: string, options: ExampleGameOptions, slug: string): ReturnType<typeof installAssets>;
+//# sourceMappingURL=example-games.d.ts.map

package/dist/lib/example-games.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-games.d.ts","sourceRoot":"","sources":["../../src/lib/example-games.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,IAAI,aAAa,EAAwB,KAAK,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAK7I,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,KAAK,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAEzL,iFAAiF;AACjF,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAK7J"}

package/dist/lib/example-games.js

@@ -0,0 +1,13 @@
+import { installExampleGameAssets as installAssets, getExampleGameBundle } from "@nodetool-ai/agents/game-examples";
+import { ApiErrorCode } from "../error-codes.js";
+import { throwApiError } from "../trpc/error-formatter.js";
+import { getAssetAdapter } from "./storage.js";
+export { getExampleGameBundle, listExampleGames, readExampleGameFile, resolveExampleGamesDir } from "@nodetool-ai/agents/game-examples";
+/** Install the shared shipped bundle through the server's configured storage. */
+export async function installExampleGameAssets(userId, projectId, options, slug) {
+    if (!getExampleGameBundle(options, slug)) {
+        throwApiError(ApiErrorCode.NOT_FOUND, `No example game named "${slug}"`);
+    }
+    return installAssets(userId, projectId, options, slug, getAssetAdapter());
+}
+//# sourceMappingURL=example-games.js.map

package/dist/lib/example-games.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-games.js","sourceRoot":"","sources":["../../src/lib/example-games.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,IAAI,aAAa,EAAE,oBAAoB,EAA2B,MAAM,mCAAmC,CAAC;AAC7I,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,sBAAsB,EAAmD,MAAM,mCAAmC,CAAC;AAEzL,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,MAAc,EAAE,SAAiB,EAAE,OAA2B,EAAE,IAAY;IACzH,IAAI,CAAC,oBAAoB,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;QACzC,aAAa,CAAC,YAAY,CAAC,SAAS,EAAE,0BAA0B,IAAI,GAAG,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC,CAAC;AAC5E,CAAC"}