aec-agent 1.0.1 → 1.0.4

package/dist/components/tool-hub/built-in-tools/preview/list-apps-tool.js

@@ -0,0 +1,57 @@
+import { withSandbox } from "../workspace/workspace-helpers.js";
+import { APP_MANIFEST, APPS_DIR, readManifest, validAppName } from "./preview-helpers.js";
+/**
+ * list_apps (A-124) — the apps installed in the agent's workspace: every apps/<app>/
+ * folder with an app.json, with what it opens. The model checks it before open_in_app.
+ */
+export class ListAppsTool {
+    name = "tool:list-apps";
+    version = "1.0.0";
+    definition = {
+        name: "list_apps",
+        description: `List the apps installed in your workspace — each is a folder ${APPS_DIR}/<app>/ with an ${APP_MANIFEST} ` +
+            '({ "name", "description", "entry": "index.html", "opens": [".ifc"], "openUrl": "index.html?file={path}" }). ' +
+            "Use it to find an app that opens a file the user gave you, then call open_in_app.",
+        parameters: { type: "object", properties: {}, required: [] },
+        risk: "read-only",
+        sandboxOperation: "fs.read",
+    };
+    async execute(_args, context) {
+        return withSandbox("list_apps", context, async (env) => {
+            const dir = await env.stat(APPS_DIR);
+            if (!dir || dir.type !== "directory") {
+                return {
+                    content: `No apps installed — there is no ${APPS_DIR}/ folder. To install one, put a static web app in ` +
+                        `${APPS_DIR}/<app>/ with an ${APP_MANIFEST} that says which files it opens.`,
+                    metadata: { count: 0 },
+                };
+            }
+            const listing = await env.list(APPS_DIR);
+            const apps = [];
+            const lines = [];
+            for (const entry of listing.entries) {
+                if (entry.type !== "directory" || !validAppName(entry.name))
+                    continue;
+                const manifest = await readManifest(env, entry.name);
+                if (manifest === null)
+                    continue;
+                if (typeof manifest === "string") {
+                    lines.push(`${entry.name} · broken manifest: ${manifest}`);
+                    continue;
+                }
+                apps.push({ app: entry.name, ...manifest });
+                lines.push([
+                    `${entry.name}${manifest.name !== entry.name ? ` (${manifest.name})` : ""}`,
+                    manifest.opens.length ? `opens ${manifest.opens.join(", ")}` : "opens no files",
+                    `entry ${manifest.entry}`,
+                    ...(manifest.description ? [manifest.description] : []),
+                ].join(" · "));
+            }
+            if (lines.length === 0) {
+                return { content: `No apps installed — no folder in ${APPS_DIR}/ has an ${APP_MANIFEST}.`, metadata: { count: 0 } };
+            }
+            return { content: `${apps.length} app${apps.length === 1 ? "" : "s"}:\n${lines.join("\n")}`, metadata: { count: apps.length, apps } };
+        });
+    }
+}
+//# sourceMappingURL=list-apps-tool.js.map

package/dist/components/tool-hub/built-in-tools/preview/list-apps-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-apps-tool.js","sourceRoot":"","sources":["../../../../../src/components/tool-hub/built-in-tools/preview/list-apps-tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAE1F;;;GAGG;AACH,MAAM,OAAO,YAAY;IACd,IAAI,GAAG,gBAAgB,CAAC;IACxB,OAAO,GAAG,OAAO,CAAC;IAClB,UAAU,GAAmB;QACpC,IAAI,EAAE,WAAW;QACjB,WAAW,EACT,gEAAgE,QAAQ,mBAAmB,YAAY,GAAG;YAC1G,8GAA8G;YAC9G,mFAAmF;QACrF,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;QAC5D,IAAI,EAAE,WAAW;QACjB,gBAAgB,EAAE,SAAS;KAC5B,CAAC;IAEF,KAAK,CAAC,OAAO,CAAC,KAA8B,EAAE,OAAoB;QAChE,OAAO,WAAW,CAAC,WAAW,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACrD,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACrC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;gBACrC,OAAO;oBACL,OAAO,EACL,mCAAmC,QAAQ,oDAAoD;wBAC/F,GAAG,QAAQ,mBAAmB,YAAY,kCAAkC;oBAC9E,QAAQ,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE;iBACvB,CAAC;YACJ,CAAC;YACD,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACzC,MAAM,IAAI,GAAmC,EAAE,CAAC;YAChD,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;gBACpC,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC;oBAAE,SAAS;gBACtE,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;gBACrD,IAAI,QAAQ,KAAK,IAAI;oBAAE,SAAS;gBAChC,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;oBACjC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,uBAAuB,QAAQ,EAAE,CAAC,CAAC;oBAC3D,SAAS;gBACX,CAAC;gBACD,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;gBAC5C,KAAK,CAAC,IAAI,CACR;oBACE,GAAG,KAAK,CAAC,IAAI,GAAG,QAAQ,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;oBAC3E,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,gBAAgB;oBAC/E,SAAS,QAAQ,CAAC,KAAK,EAAE;oBACzB,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;iBACxD,CAAC,IAAI,CAAC,KAAK,CAAC,CACd,CAAC;YACJ,CAAC;YACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACvB,OAAO,EAAE,OAAO,EAAE,oCAAoC,QAAQ,YAAY,YAAY,GAAG,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YACtH,CAAC;YACD,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,OAAO,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC;QACxI,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/components/tool-hub/built-in-tools/preview/open-in-app-tool.d.ts

@@ -0,0 +1,15 @@
+import type { ToolContext, ToolDefinition, ToolHandler, ToolOutput } from "../../types.js";
+/**
+ * open_in_app (A-124) — open a workspace file (e.g. a model the user uploaded) in an app
+ * installed in apps/<app>/, or just start the app. Checks that the app and the file
+ * exist and that the app opens that kind of file, then returns a preview link to the
+ * app's page with the file's URL filled into its openUrl — the app fetches the file
+ * from the same preview origin.
+ */
+export declare class OpenInAppTool implements ToolHandler {
+    readonly name = "tool:open-in-app";
+    readonly version = "1.0.0";
+    readonly definition: ToolDefinition;
+    execute(args: Record<string, unknown>, context: ToolContext): Promise<ToolOutput>;
+}
+//# sourceMappingURL=open-in-app-tool.d.ts.map

package/dist/components/tool-hub/built-in-tools/preview/open-in-app-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-in-app-tool.d.ts","sourceRoot":"","sources":["../../../../../src/components/tool-hub/built-in-tools/preview/open-in-app-tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAc3F;;;;;;GAMG;AACH,qBAAa,aAAc,YAAW,WAAW;IAC/C,QAAQ,CAAC,IAAI,sBAAsB;IACnC,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,UAAU,EAAE,cAAc,CAejC;IAEI,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CA6CtF;CACF"}

package/dist/components/tool-hub/built-in-tools/preview/open-in-app-tool.js

@@ -0,0 +1,80 @@
+import { posix } from "node:path";
+import { citeLinkNote } from "../../tool-links.js";
+import { argError, stringArg, withSandbox } from "../workspace/workspace-helpers.js";
+import { APP_MANIFEST, APPS_DIR, extensionOf, previewLink, readManifest, relativeUrl, validAppName, workspaceRelative, } from "./preview-helpers.js";
+/**
+ * open_in_app (A-124) — open a workspace file (e.g. a model the user uploaded) in an app
+ * installed in apps/<app>/, or just start the app. Checks that the app and the file
+ * exist and that the app opens that kind of file, then returns a preview link to the
+ * app's page with the file's URL filled into its openUrl — the app fetches the file
+ * from the same preview origin.
+ */
+export class OpenInAppTool {
+    name = "tool:open-in-app";
+    version = "1.0.0";
+    definition = {
+        name: "open_in_app",
+        description: "Open a file from your workspace in one of your installed apps (see list_apps), shown live next to the chat — " +
+            'e.g. an IFC model the user uploaded (in "files/") in an IFC viewer. Leave out "file" to just start the app.',
+        parameters: {
+            type: "object",
+            properties: {
+                app: { type: "string", description: `The app's folder name in ${APPS_DIR}/` },
+                file: { type: "string", description: 'The workspace file to open, e.g. "files/tower-a.ifc"' },
+            },
+            required: ["app"],
+        },
+        risk: "read-only",
+        sandboxOperation: "fs.read",
+    };
+    async execute(args, context) {
+        const app = stringArg(args, "app")?.trim().replace(/^apps\//, "").replace(/\/+$/, "");
+        const file = stringArg(args, "file")?.trim();
+        if (!app)
+            return argError("open_in_app", '"app" is required — see list_apps');
+        if (!validAppName(app))
+            return argError("open_in_app", `"${app}" is not an app folder name`);
+        return withSandbox("open_in_app", context, async (env) => {
+            const manifest = await readManifest(env, app);
+            if (manifest === null) {
+                return argError("open_in_app", `No app "${app}" — there is no ${APPS_DIR}/${app}/${APP_MANIFEST}. Check list_apps.`);
+            }
+            if (typeof manifest === "string")
+                return argError("open_in_app", `The app "${app}" is broken: ${manifest}`);
+            const appDir = `${APPS_DIR}/${app}`;
+            const entry = await env.stat(posix.join(appDir, manifest.entry));
+            if (!entry || entry.type !== "file") {
+                return argError("open_in_app", `The app "${app}" has no ${manifest.entry} (its entry page)`);
+            }
+            if (!file) {
+                const link = previewLink(`${appDir}/${manifest.entry}`, manifest.name);
+                return {
+                    content: `${manifest.name} is open — the user sees it live next to the chat.${citeLinkNote(link)}`,
+                    link,
+                    metadata: { app, uri: link.uri },
+                };
+            }
+            const stat = await env.stat(file);
+            if (!stat)
+                return argError("open_in_app", `"${file}" does not exist`);
+            if (stat.type !== "file")
+                return argError("open_in_app", `"${file}" is a ${stat.type}, not a file`);
+            const ext = extensionOf(stat.path);
+            if (manifest.opens.length === 0)
+                return argError("open_in_app", `${manifest.name} does not open files — leave out "file" to just start it`);
+            if (!manifest.opens.includes(ext)) {
+                return argError("open_in_app", `${manifest.name} opens ${manifest.opens.join(", ")} files, not "${ext || "(no extension)"}"`);
+            }
+            const fileRel = workspaceRelative(env, stat.path);
+            const [page, query = ""] = manifest.openUrl.split(/\?(.*)/s, 2);
+            const filled = query.replaceAll("{path}", encodeURIComponent(relativeUrl(appDir, fileRel)));
+            const link = previewLink(`${appDir}/${page}`, `${posix.basename(fileRel)} in ${manifest.name}`, filled);
+            return {
+                content: `${posix.basename(fileRel)} is open in ${manifest.name} — the user sees it live next to the chat.${citeLinkNote(link)}`,
+                link,
+                metadata: { app, file: stat.path, uri: link.uri },
+            };
+        });
+    }
+}
+//# sourceMappingURL=open-in-app-tool.js.map

package/dist/components/tool-hub/built-in-tools/preview/open-in-app-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-in-app-tool.js","sourceRoot":"","sources":["../../../../../src/components/tool-hub/built-in-tools/preview/open-in-app-tool.ts"],"names":[],"mappings":"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"}

package/dist/components/tool-hub/built-in-tools/preview/preview-helpers.d.ts

@@ -0,0 +1,53 @@
+import type { ToolResultLink } from "../../../../kernel/types.js";
+import type { SandboxView } from "../../../sandbox-hub/types/sandbox.js";
+/** Folder of the agent's workspace that holds apps, one per sub-folder. */
+export declare const APPS_DIR = "apps";
+/** The manifest file of an app: apps/<app>/app.json. */
+export declare const APP_MANIFEST = "app.json";
+/** What a folder preview opens. */
+export declare const INDEX_FILE = "index.html";
+/** apps/<app>/app.json — what list_apps shows and open_in_app follows. */
+export interface AppManifest {
+    /** Display name (default: the folder name). */
+    name: string;
+    description?: string;
+    /** The page that starts the app, relative to its folder (default index.html). */
+    entry: string;
+    /** File extensions the app opens, e.g. [".ifc"]; empty = it opens no files. */
+    opens: string[];
+    /**
+     * How to open a file: a URL relative to the app folder with {path} in its query where
+     * the file goes, e.g. "index.html?file={path}". Default: "<entry>?file={path}". {path}
+     * becomes the file's URL relative to the app folder, so the app can fetch() it as is
+     * after reading the parameter (URLSearchParams decodes it once).
+     */
+    openUrl: string;
+}
+/** The workspace path of `logical` relative to the working directory ("" = the working directory). */
+export declare function workspaceRelative(env: SandboxView, logical: string): string;
+/** Percent-encode each segment of a relative path (keeps the slashes). */
+export declare function encodePath(rel: string): string;
+/** A-133: whether a workspace path is an image the chat can show inside a reply. */
+export declare function isImageFile(rel: string): boolean;
+/**
+ * A-133: appended to the preview of an image instead of citeLinkNote — asks the model to
+ * show the image inside its reply as markdown (![name](preview://...)), which the chat
+ * renders as the image itself; a click still opens it in the Preview panel.
+ */
+export declare function embedImageNote(link: ToolResultLink): string;
+/** The preview link of a workspace-relative path, with an optional query ("file=..."). */
+export declare function previewLink(rel: string, name: string, query?: string): ToolResultLink;
+/** An app folder name: one path segment, no dot-files. */
+export declare function validAppName(app: string): boolean;
+/**
+ * Read and check apps/<app>/app.json. A missing manifest is null; a broken one is an
+ * error message (string) the tools report back.
+ */
+export declare function readManifest(env: SandboxView, app: string): Promise<AppManifest | string | null>;
+/** ".IFC" / "ifc" -> ".ifc". */
+export declare function normalizeExtension(ext: string): string;
+/** The extension of a file name, lower-case with its dot ("" when it has none). */
+export declare function extensionOf(name: string): string;
+/** The URL of `fileRel` relative to the app folder `appRel` (both workspace-relative), percent-encoded. */
+export declare function relativeUrl(fromDir: string, fileRel: string): string;
+//# sourceMappingURL=preview-helpers.d.ts.map

package/dist/components/tool-hub/built-in-tools/preview/preview-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-helpers.d.ts","sourceRoot":"","sources":["../../../../../src/components/tool-hub/built-in-tools/preview/preview-helpers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAC;AAOzE,2EAA2E;AAC3E,eAAO,MAAM,QAAQ,SAAS,CAAC;AAC/B,wDAAwD;AACxD,eAAO,MAAM,YAAY,aAAa,CAAC;AACvC,mCAAmC;AACnC,eAAO,MAAM,UAAU,eAAe,CAAC;AAEvC,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sGAAsG;AACtG,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAG3E;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAKD,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAE3D;AAED,0FAA0F;AAC1F,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,cAAc,CAErF;AAED,0DAA0D;AAC1D,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,MAAM,GAAG,IAAI,CAAC,CA+BtG;AAED,gCAAgC;AAChC,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED,2GAA2G;AAC3G,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpE"}

package/dist/components/tool-hub/built-in-tools/preview/preview-helpers.js

@@ -0,0 +1,100 @@
+import { posix } from "node:path";
+// A-124: shared plumbing of the preview tools. A preview link is a ToolResult.link (A-132)
+// with a "preview://<workspace path>[?query]" URI: the path is relative to the agent's
+// working directory, and the host turns it into a signed URL on its preview origin when
+// the user opens it — so the link in a saved conversation never expires.
+/** Folder of the agent's workspace that holds apps, one per sub-folder. */
+export const APPS_DIR = "apps";
+/** The manifest file of an app: apps/<app>/app.json. */
+export const APP_MANIFEST = "app.json";
+/** What a folder preview opens. */
+export const INDEX_FILE = "index.html";
+/** The workspace path of `logical` relative to the working directory ("" = the working directory). */
+export function workspaceRelative(env, logical) {
+    const rel = posix.relative(env.workingDir, logical);
+    return rel.startsWith("..") ? logical.replace(/^\/+/, "") : rel;
+}
+/** Percent-encode each segment of a relative path (keeps the slashes). */
+export function encodePath(rel) {
+    return rel.split("/").map((part) => encodeURIComponent(part)).join("/");
+}
+/** A-133: files the chat shows inline in a reply as an image, by extension. */
+const IMAGE_FILE = /\.(png|jpe?g|gif|webp|avif|svg|bmp|ico)$/i;
+/** A-133: whether a workspace path is an image the chat can show inside a reply. */
+export function isImageFile(rel) {
+    return IMAGE_FILE.test(rel);
+}
+/**
+ * A-133: appended to the preview of an image instead of citeLinkNote — asks the model to
+ * show the image inside its reply as markdown (![name](preview://...)), which the chat
+ * renders as the image itself; a click still opens it in the Preview panel.
+ */
+export function embedImageNote(link) {
+    return `\nIt is an image: to show it inside your reply, write ![${link.name}](${link.uri}) on its own line.`;
+}
+/** The preview link of a workspace-relative path, with an optional query ("file=..."). */
+export function previewLink(rel, name, query) {
+    return { uri: `preview://${encodePath(rel)}${query ? `?${query}` : ""}`, name, type: "preview" };
+}
+/** An app folder name: one path segment, no dot-files. */
+export function validAppName(app) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(app) && !app.includes("..");
+}
+/**
+ * Read and check apps/<app>/app.json. A missing manifest is null; a broken one is an
+ * error message (string) the tools report back.
+ */
+export async function readManifest(env, app) {
+    const path = `${APPS_DIR}/${app}/${APP_MANIFEST}`;
+    const stat = await env.stat(path);
+    if (!stat)
+        return null;
+    if (stat.type !== "file")
+        return `${path} is not a file`;
+    const file = await env.readFile(path, { maxBytes: 64 * 1024 });
+    let raw;
+    try {
+        raw = JSON.parse(file.content);
+    }
+    catch (error) {
+        return `${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return `${path} must be a JSON object`;
+    const m = raw;
+    const entry = typeof m["entry"] === "string" && m["entry"].trim() ? m["entry"].trim().replace(/^\.?\/+/, "") : INDEX_FILE;
+    if (entry.split("/").includes(".."))
+        return `${path}: "entry" must stay inside the app folder`;
+    const opens = Array.isArray(m["opens"])
+        ? m["opens"].filter((x) => typeof x === "string" && x.trim() !== "").map((x) => normalizeExtension(x))
+        : [];
+    // {path} goes in the query ("viewer.html?model={path}"); anything else falls back to the default.
+    const given = typeof m["openUrl"] === "string" ? m["openUrl"].trim().replace(/^\.?\/+/, "") : "";
+    const queryAt = given.indexOf("?");
+    const openUrl = queryAt > 0 && given.indexOf("{path}") > queryAt ? given : `${entry}?file={path}`;
+    if (openUrl.split("?")[0].split("/").includes(".."))
+        return `${path}: "openUrl" must stay inside the app folder`;
+    return {
+        name: typeof m["name"] === "string" && m["name"].trim() ? m["name"].trim() : app,
+        ...(typeof m["description"] === "string" && m["description"].trim() ? { description: m["description"].trim() } : {}),
+        entry,
+        opens,
+        openUrl,
+    };
+}
+/** ".IFC" / "ifc" -> ".ifc". */
+export function normalizeExtension(ext) {
+    const e = ext.trim().toLowerCase();
+    return e.startsWith(".") ? e : `.${e}`;
+}
+/** The extension of a file name, lower-case with its dot ("" when it has none). */
+export function extensionOf(name) {
+    const base = posix.basename(name);
+    const dot = base.lastIndexOf(".");
+    return dot > 0 ? base.slice(dot).toLowerCase() : "";
+}
+/** The URL of `fileRel` relative to the app folder `appRel` (both workspace-relative), percent-encoded. */
+export function relativeUrl(fromDir, fileRel) {
+    return encodePath(posix.relative(fromDir, fileRel));
+}
+//# sourceMappingURL=preview-helpers.js.map

package/dist/components/tool-hub/built-in-tools/preview/preview-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-helpers.js","sourceRoot":"","sources":["../../../../../src/components/tool-hub/built-in-tools/preview/preview-helpers.ts"],"names":[],"mappings":"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"}

package/dist/components/tool-hub/built-in-tools/preview/preview-tool.d.ts

@@ -0,0 +1,14 @@
+import type { ToolContext, ToolDefinition, ToolHandler, ToolOutput } from "../../types.js";
+/**
+ * preview (A-124) — show the user a web page from the workspace, live: an HTML file, or a
+ * folder with an index.html (a site or browser game with its CSS, scripts, images and
+ * other assets). Returns a preview link (ToolResult.link) the chat opens next to the
+ * conversation, served from the agent's sandbox on a separate origin.
+ */
+export declare class PreviewTool implements ToolHandler {
+    readonly name = "tool:preview";
+    readonly version = "1.0.0";
+    readonly definition: ToolDefinition;
+    execute(args: Record<string, unknown>, context: ToolContext): Promise<ToolOutput>;
+}
+//# sourceMappingURL=preview-tool.d.ts.map

package/dist/components/tool-hub/built-in-tools/preview/preview-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-tool.d.ts","sourceRoot":"","sources":["../../../../../src/components/tool-hub/built-in-tools/preview/preview-tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAK3F;;;;;GAKG;AACH,qBAAa,WAAY,YAAW,WAAW;IAC7C,QAAQ,CAAC,IAAI,kBAAkB;IAC/B,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,UAAU,EAAE,cAAc,CAiBjC;IAEI,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CA2BtF;CACF"}

package/dist/components/tool-hub/built-in-tools/preview/preview-tool.js

@@ -0,0 +1,63 @@
+import { posix } from "node:path";
+import { citeLinkNote } from "../../tool-links.js";
+import { argError, stringArg, withSandbox } from "../workspace/workspace-helpers.js";
+import { INDEX_FILE, embedImageNote, isImageFile, previewLink, workspaceRelative } from "./preview-helpers.js";
+/**
+ * preview (A-124) — show the user a web page from the workspace, live: an HTML file, or a
+ * folder with an index.html (a site or browser game with its CSS, scripts, images and
+ * other assets). Returns a preview link (ToolResult.link) the chat opens next to the
+ * conversation, served from the agent's sandbox on a separate origin.
+ */
+export class PreviewTool {
+    name = "tool:preview";
+    version = "1.0.0";
+    definition = {
+        name: "preview",
+        description: "Show the user a web page from your workspace in a live preview next to the chat: an HTML file, " +
+            "or a folder that has an index.html (a website or browser game with its CSS, scripts, images and other " +
+            "files — keep them in the same folder and use relative links). Use it after you build or change a page. " +
+            "Images, PDFs and other files the browser can show work too. For an image, the result also tells you how " +
+            "to show it inside your reply.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: 'The HTML file or folder to preview, e.g. "sites/landing" or "game/index.html"' },
+            },
+            required: ["path"],
+        },
+        risk: "read-only",
+        sandboxOperation: "fs.read",
+    };
+    async execute(args, context) {
+        const path = stringArg(args, "path")?.trim();
+        if (!path)
+            return argError("preview", '"path" is required — the HTML file or folder to show');
+        return withSandbox("preview", context, async (env) => {
+            const stat = await env.stat(path);
+            if (!stat)
+                return argError("preview", `"${path}" does not exist — write the page first`);
+            let target = stat.path;
+            if (stat.type === "directory") {
+                const index = await env.stat(posix.join(stat.path, INDEX_FILE));
+                if (!index || index.type !== "file") {
+                    return argError("preview", `"${path}" is a folder without an ${INDEX_FILE} — pass the HTML file to show`);
+                }
+                target = index.path;
+            }
+            else if (stat.type !== "file") {
+                return argError("preview", `"${path}" is a ${stat.type}, not a file or folder`);
+            }
+            const rel = workspaceRelative(env, target);
+            const shown = stat.type === "directory" ? workspaceRelative(env, stat.path) || "workspace" : rel;
+            const link = previewLink(rel, posix.basename(shown));
+            // A-133: an image can be shown inside the reply itself.
+            const note = isImageFile(rel) ? embedImageNote(link) : citeLinkNote(link);
+            return {
+                content: `The preview of ${shown} is ready — the user sees it live next to the chat.${note}`,
+                link,
+                metadata: { path: target, uri: link.uri },
+            };
+        });
+    }
+}
+//# sourceMappingURL=preview-tool.js.map

package/dist/components/tool-hub/built-in-tools/preview/preview-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-tool.js","sourceRoot":"","sources":["../../../../../src/components/tool-hub/built-in-tools/preview/preview-tool.ts"],"names":[],"mappings":"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"}

package/dist/components/tool-hub/built-in-tools/preview/service-tools.d.ts

@@ -0,0 +1,33 @@
+import type { ToolResultLink } from "../../../../kernel/types.js";
+import type { ToolContext, ToolDefinition, ToolHandler, ToolOutput } from "../../types.js";
+/** The link of a service (its root page). */
+export declare function serviceLink(name: string): ToolResultLink;
+/** start_service — start a dev server and show it live. */
+export declare class StartServiceTool implements ToolHandler {
+    readonly name = "tool:start-service";
+    readonly version = "1.0.0";
+    readonly definition: ToolDefinition;
+    execute(args: Record<string, unknown>, context: ToolContext): Promise<ToolOutput>;
+}
+/** stop_service — stop a running service. */
+export declare class StopServiceTool implements ToolHandler {
+    readonly name = "tool:stop-service";
+    readonly version = "1.0.0";
+    readonly definition: ToolDefinition;
+    execute(args: Record<string, unknown>, context: ToolContext): Promise<ToolOutput>;
+}
+/** list_services — the agent's services and their state. */
+export declare class ListServicesTool implements ToolHandler {
+    readonly name = "tool:list-services";
+    readonly version = "1.0.0";
+    readonly definition: ToolDefinition;
+    execute(_args: Record<string, unknown>, context: ToolContext): Promise<ToolOutput>;
+}
+/** service_logs — the end of a service's output. */
+export declare class ServiceLogsTool implements ToolHandler {
+    readonly name = "tool:service-logs";
+    readonly version = "1.0.0";
+    readonly definition: ToolDefinition;
+    execute(args: Record<string, unknown>, context: ToolContext): Promise<ToolOutput>;
+}
+//# sourceMappingURL=service-tools.d.ts.map

package/dist/components/tool-hub/built-in-tools/preview/service-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-tools.d.ts","sourceRoot":"","sources":["../../../../../src/components/tool-hub/built-in-tools/preview/service-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAa3F,6CAA6C;AAC7C,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAExD;AAuBD,2DAA2D;AAC3D,qBAAa,gBAAiB,YAAW,WAAW;IAClD,QAAQ,CAAC,IAAI,wBAAwB;IACrC,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,UAAU,EAAE,cAAc,CAoBjC;IAEI,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAmCtF;CACF;AAED,6CAA6C;AAC7C,qBAAa,eAAgB,YAAW,WAAW;IACjD,QAAQ,CAAC,IAAI,uBAAuB;IACpC,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,UAAU,EAAE,cAAc,CAUjC;IAEI,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAStF;CACF;AAED,4DAA4D;AAC5D,qBAAa,gBAAiB,YAAW,WAAW;IAClD,QAAQ,CAAC,IAAI,wBAAwB;IACrC,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,UAAU,EAAE,cAAc,CAMjC;IAEI,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAUvF;CACF;AAED,oDAAoD;AACpD,qBAAa,eAAgB,YAAW,WAAW;IACjD,QAAQ,CAAC,IAAI,uBAAuB;IACpC,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,UAAU,EAAE,cAAc,CAajC;IAEI,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAatF;CACF"}