npm - @vellumai/assistant - Versions diffs - 0.4.37 → 0.4.41 - Mend

@vellumai/assistant 0.4.37 → 0.4.41

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (169) hide show

package/ARCHITECTURE.md +3 -3
package/README.md +13 -13
package/bun.lock +80 -24
package/docs/architecture/integrations.md +126 -128
package/docs/runbook-trusted-contacts.md +1 -1
package/docs/trusted-contact-access.md +12 -12
package/package.json +3 -1
package/src/__tests__/__snapshots__/ipc-snapshot.test.ts.snap +0 -14
package/src/__tests__/app-bundler.test.ts +209 -0
package/src/__tests__/app-compiler.test.ts +279 -0
package/src/__tests__/app-executors.test.ts +293 -483
package/src/__tests__/app-migration.test.ts +148 -0
package/src/__tests__/app-routes-csp.test.ts +202 -0
package/src/__tests__/avatar-e2e.test.ts +452 -0
package/src/__tests__/avatar-generator.test.ts +193 -0
package/src/__tests__/avatar-router.test.ts +186 -0
package/src/__tests__/browser-download-timeout.test.ts +28 -0
package/src/__tests__/bundled-skill-retrieval-guard.test.ts +9 -9
package/src/__tests__/call-domain.test.ts +3 -7
package/src/__tests__/credential-security-e2e.test.ts +19 -12
package/src/__tests__/credentials-cli.test.ts +30 -4
package/src/__tests__/guardian-verify-setup-skill-regression.test.ts +1 -1
package/src/__tests__/handlers-slack-config.test.ts +0 -72
package/src/__tests__/handlers-telegram-config.test.ts +19 -12
package/src/__tests__/handlers-twitter-config.test.ts +105 -48
package/src/__tests__/inbound-invite-redemption.test.ts +4 -4
package/src/__tests__/integration-status.test.ts +15 -5
package/src/__tests__/integrations-cli.test.ts +1 -1
package/src/__tests__/invite-redemption-service.test.ts +62 -7
package/src/__tests__/ipc-snapshot.test.ts +0 -8
package/src/__tests__/managed-avatar-client.test.ts +280 -0
package/src/__tests__/mcp-cli.test.ts +3 -3
package/src/__tests__/oauth-cli.test.ts +203 -0
package/src/__tests__/relay-server.test.ts +3 -3
package/src/__tests__/secret-onetime-send.test.ts +19 -12
package/src/__tests__/secure-keys.test.ts +78 -0
package/src/__tests__/session-messaging-secret-redirect.test.ts +3 -0
package/src/__tests__/slack-channel-config.test.ts +23 -16
package/src/__tests__/slack-share-routes.test.ts +263 -0
package/src/__tests__/sms-messaging-provider.test.ts +3 -1
package/src/__tests__/trusted-contact-lifecycle-notifications.test.ts +7 -7
package/src/__tests__/trusted-contact-multichannel.test.ts +3 -3
package/src/__tests__/trusted-contact-verification.test.ts +10 -10
package/src/__tests__/twilio-config.test.ts +15 -36
package/src/__tests__/twilio-provider.test.ts +4 -0
package/src/__tests__/twitter-auth-handler.test.ts +27 -14
package/src/__tests__/twitter-cli-error-shaping.test.ts +1 -1
package/src/__tests__/twitter-cli-routing.test.ts +38 -53
package/src/__tests__/twitter-oauth-client.test.ts +18 -47
package/src/__tests__/voice-invite-redemption.test.ts +27 -3
package/src/amazon/cart.ts +1 -1
package/src/amazon/client.ts +89 -7
package/src/approvals/guardian-request-resolvers.ts +2 -2
package/src/bundler/app-bundler.ts +77 -32
package/src/bundler/app-compiler.ts +195 -0
package/src/bundler/manifest.ts +1 -1
package/src/bundler/package-resolver.ts +185 -0
package/src/calls/call-domain.ts +4 -14
package/src/calls/relay-server.ts +2 -2
package/src/calls/twilio-config.ts +5 -24
package/src/calls/twilio-rest.ts +19 -5
package/src/cli/amazon.ts +74 -249
package/src/cli/audit.ts +2 -2
package/src/cli/autonomy.ts +9 -9
package/src/cli/channels.ts +5 -5
package/src/cli/completions.ts +27 -27
package/src/cli/config.ts +14 -14
package/src/cli/contacts.ts +27 -27
package/src/cli/credentials.ts +28 -28
package/src/cli/dev.ts +2 -2
package/src/cli/doctor.ts +2 -2
package/src/cli/email.ts +82 -82
package/src/cli/influencer.ts +13 -13
package/src/cli/integrations.ts +19 -144
package/src/cli/keys.ts +10 -10
package/src/cli/map.ts +4 -4
package/src/cli/mcp.ts +17 -17
package/src/cli/memory.ts +18 -18
package/src/cli/notifications.ts +13 -13
package/src/cli/oauth.ts +77 -0
package/src/cli/program.ts +2 -0
package/src/cli/sequence.ts +27 -27
package/src/cli/sessions.ts +12 -12
package/src/cli/trust.ts +8 -8
package/src/cli/twitter.ts +124 -70
package/src/config/bundled-skills/_shared/CLI_RETRIEVAL_PATTERN.md +1 -1
package/src/config/bundled-skills/agentmail/SKILL.md +34 -34
package/src/config/bundled-skills/amazon/SKILL.md +54 -54
package/src/config/bundled-skills/app-builder/SKILL.md +137 -3
package/src/config/bundled-skills/app-builder/tools/app-create.ts +10 -4
package/src/config/bundled-skills/configure-settings/SKILL.md +18 -18
package/src/config/bundled-skills/contacts/SKILL.md +12 -12
package/src/config/bundled-skills/doordash/lib/client.ts +7 -9
package/src/config/bundled-skills/email-setup/SKILL.md +4 -4
package/src/config/bundled-skills/frontend-design/icon.svg +16 -0
package/src/config/bundled-skills/google-oauth-setup/SKILL.md +143 -162
package/src/config/bundled-skills/guardian-verify-setup/SKILL.md +4 -4
package/src/config/bundled-skills/influencer/SKILL.md +13 -13
package/src/config/bundled-skills/mcp-setup/SKILL.md +11 -11
package/src/config/bundled-skills/phone-calls/SKILL.md +48 -54
package/src/config/bundled-skills/public-ingress/SKILL.md +6 -6
package/src/config/bundled-skills/slack-app-setup/SKILL.md +1 -1
package/src/config/bundled-skills/sms-setup/SKILL.md +3 -3
package/src/config/bundled-skills/telegram-setup/SKILL.md +2 -2
package/src/config/bundled-skills/twilio-setup/SKILL.md +136 -225
package/src/config/bundled-skills/twitter/SKILL.md +68 -44
package/src/config/bundled-skills/voice-setup/SKILL.md +2 -2
package/src/config/core-schema.ts +26 -0
package/src/config/env.ts +4 -0
package/src/config/feature-flag-registry.json +9 -1
package/src/config/schema.ts +8 -0
package/src/config/system-prompt.ts +6 -3
package/src/config/templates/BOOTSTRAP.md +7 -5
package/src/contacts/contacts-write.ts +5 -1
package/src/daemon/handlers/apps.ts +31 -4
package/src/daemon/handlers/config-ingress.ts +3 -3
package/src/daemon/handlers/config-integrations.ts +120 -49
package/src/daemon/handlers/config-slack-channel.ts +26 -7
package/src/daemon/handlers/config-slack.ts +1 -54
package/src/daemon/handlers/config-telegram.ts +28 -10
package/src/daemon/handlers/config.ts +1 -4
package/src/daemon/handlers/twitter-auth.ts +11 -4
package/src/daemon/ipc-contract/apps.ts +0 -13
package/src/daemon/ipc-contract-inventory.json +0 -2
package/src/daemon/lifecycle.ts +8 -1
package/src/daemon/session-messaging.ts +2 -2
package/src/daemon/tool-side-effects.ts +30 -0
package/src/email/providers/agentmail.ts +1 -1
package/src/email/providers/index.ts +1 -1
package/src/email/service.ts +1 -1
package/src/gallery/default-gallery.ts +538 -0
package/src/gallery/gallery-manifest.ts +5 -1
package/src/influencer/client.ts +8 -6
package/src/mcp/client.ts +1 -1
package/src/media/avatar-router.ts +99 -0
package/src/media/avatar-types.ts +60 -0
package/src/media/managed-avatar-client.ts +189 -0
package/src/memory/app-migration.ts +114 -0
package/src/memory/app-store.ts +11 -0
package/src/memory/qdrant-client.ts +1 -1
package/src/messaging/providers/slack/client.ts +12 -2
package/src/messaging/providers/sms/adapter.ts +6 -10
package/src/migrations/data-layout.ts +8 -1
package/src/oauth/token-persistence.ts +9 -6
package/src/runtime/assistant-scope.ts +5 -0
package/src/runtime/auth/route-policy.ts +4 -0
package/src/runtime/channel-readiness-service.ts +9 -4
package/src/runtime/gateway-internal-client.ts +11 -3
package/src/runtime/http-server.ts +2 -0
package/src/runtime/invite-redemption-service.ts +23 -13
package/src/runtime/middleware/twilio-validation.ts +2 -2
package/src/runtime/routes/app-routes.ts +131 -3
package/src/runtime/routes/inbound-stages/verification-intercept.ts +3 -3
package/src/runtime/routes/integration-routes.ts +2 -2
package/src/runtime/routes/slack-share-routes.ts +235 -0
package/src/runtime/routes/twilio-routes.ts +47 -34
package/src/schedule/integration-status.ts +2 -3
package/src/security/token-manager.ts +11 -3
package/src/tools/apps/executors.ts +116 -8
package/src/tools/browser/browser-manager.ts +30 -2
package/src/tools/browser/chrome-cdp.ts +31 -3
package/src/tools/credentials/vault.ts +9 -7
package/src/tools/executor.ts +4 -0
package/src/tools/system/avatar-generator.ts +55 -34
package/src/twitter/client.ts +1 -1
package/src/twitter/oauth-client.ts +31 -43
package/src/twitter/router.ts +25 -23
package/src/util/platform.ts +5 -0
package/src/slack/slack-webhook.ts +0 -66

package/src/__tests__/app-executors.test.ts CHANGED Viewed

@@ -1,631 +1,441 @@
 import { describe, expect, test } from "bun:test";
 import type { AppDefinition } from "../memory/app-store.js";
-import type { AppStore, ProxyResolver } from "../tools/apps/executors.js";
+import type { AppStore } from "../tools/apps/executors.js";
 import {
   executeAppCreate,
-  executeAppDelete,
   executeAppFileEdit,
   executeAppFileList,
   executeAppFileRead,
   executeAppFileWrite,
-  executeAppList,
-  executeAppQuery,
-  executeAppUpdate,
+  resolveAppFilePath,
 } from "../tools/apps/executors.js";
-import type { EditEngineResult } from "../tools/shared/filesystem/edit-engine.js";
 // ---------------------------------------------------------------------------
-// Mock factory
+// Helpers
 // ---------------------------------------------------------------------------
-function makeApp(overrides: Partial<AppDefinition> = {}): AppDefinition {
+function makeLegacyApp(overrides?: Partial<AppDefinition>): AppDefinition {
   return {
-    id: "app-1",
-    name: "Test App",
-    description: "A test app",
+    id: "legacy-app",
+    name: "Legacy App",
     schemaJson: "{}",
-    htmlDefinition: "<h1>Hi</h1>",
-    createdAt: 1000,
-    updatedAt: 2000,
+    htmlDefinition: "<html></html>",
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
     ...overrides,
   };
 }
-function makeMockStore(overrides: Partial<AppStore> = {}): AppStore {
+function makeMultifileApp(overrides?: Partial<AppDefinition>): AppDefinition {
   return {
-    getApp: () => makeApp(),
-    listApps: () => [makeApp()],
+    id: "multi-app",
+    name: "Multifile App",
+    schemaJson: "{}",
+    htmlDefinition: "",
+    formatVersion: 2,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    ...overrides,
+  };
+}
+/**
+ * Builds a minimal mock AppStore that tracks writes/edits/reads
+ * against an in-memory file map.
+ */
+function mockStore(
+  app: AppDefinition,
+  files: Record<string, string> = {},
+): AppStore {
+  return {
+    getApp: (id: string) => (id === app.id ? app : null),
+    listApps: () => [app],
     queryAppRecords: () => [],
-    listAppFiles: () => ["index.html"],
-    readAppFile: () => "<h1>Hi</h1>",
-    createApp: (params) =>
-      makeApp({ name: params.name, description: params.description }),
-    updateApp: (id, updates) => makeApp({ id, ...updates }),
+    listAppFiles: () => Object.keys(files).sort(),
+    readAppFile: (_appId: string, path: string) => {
+      if (!(path in files)) throw new Error(`File not found: ${path}`);
+      return files[path];
+    },
+    createApp: () => app,
+    updateApp: () => app,
     deleteApp: () => {},
-    writeAppFile: () => {},
-    editAppFile: () =>
-      ({
-        ok: true,
-        updatedContent: "new",
+    writeAppFile: (_appId: string, path: string, content: string) => {
+      files[path] = content;
+    },
+    editAppFile: (
+      _appId: string,
+      path: string,
+      oldStr: string,
+      newStr: string,
+      _replaceAll?: boolean,
+    ) => {
+      if (!(path in files)) throw new Error(`File not found: ${path}`);
+      const content = files[path];
+      if (!content.includes(oldStr)) {
+        return { ok: false as const, reason: "not_found" as const };
+      }
+      const updated = content.replace(oldStr, newStr);
+      files[path] = updated;
+      return {
+        ok: true as const,
+        updatedContent: updated,
         matchCount: 1,
-        matchMethod: "exact",
+        matchMethod: "exact" as const,
         similarity: 1,
-        actualOld: "old",
-        actualNew: "new",
-      }) as EditEngineResult,
-    ...overrides,
+        actualOld: oldStr,
+        actualNew: newStr,
+      };
+    },
   };
 }
 // ---------------------------------------------------------------------------
-// app_create
+// resolveAppFilePath
 // ---------------------------------------------------------------------------
-describe("executeAppCreate", () => {
-  test("creates an app and returns its definition", async () => {
-    const store = makeMockStore();
-    const result = await executeAppCreate(
-      { name: "My App", html: "<p>Hello</p>" },
-      store,
-    );
-    expect(result.isError).toBe(false);
-    const parsed = JSON.parse(result.content);
-    expect(parsed.name).toBe("My App");
-  });
-  test('defaults schema_json to "{}" when not provided', async () => {
-    let capturedSchema: string | undefined;
-    const store = makeMockStore({
-      createApp: (params) => {
-        capturedSchema = params.schemaJson;
-        return makeApp({ name: params.name });
-      },
-    });
-    await executeAppCreate({ name: "App", html: "<p/>" }, store);
-    expect(capturedSchema).toBe("{}");
+describe("resolveAppFilePath", () => {
+  test("prepends src/ for multifile app with plain path", () => {
+    const app = makeMultifileApp();
+    expect(resolveAppFilePath(app, "main.tsx")).toBe("src/main.tsx");
   });
-  test("passes schema_json through when provided", async () => {
-    let capturedSchema: string | undefined;
-    const store = makeMockStore({
-      createApp: (params) => {
-        capturedSchema = params.schemaJson;
-        return makeApp({ name: params.name });
-      },
-    });
-    await executeAppCreate(
-      { name: "App", html: "<p/>", schema_json: '{"type":"object"}' },
-      store,
+  test("prepends src/ for nested path in multifile app", () => {
+    const app = makeMultifileApp();
+    expect(resolveAppFilePath(app, "components/Header.tsx")).toBe(
+      "src/components/Header.tsx",
     );
-    expect(capturedSchema).toBe('{"type":"object"}');
   });
-  test("auto-opens the app when proxyToolResolver is provided", async () => {
-    const store = makeMockStore();
-    const proxy: ProxyResolver = async () => ({
-      content: "opened",
-      isError: false,
-    });
-    const result = await executeAppCreate(
-      { name: "Auto", html: "<p/>" },
-      store,
-      proxy,
-    );
-    expect(result.isError).toBe(false);
-    const parsed = JSON.parse(result.content);
-    expect(parsed.auto_opened).toBe(true);
-    expect(parsed.open_result).toBe("opened");
+  test("passes through src/ prefix unchanged for multifile app", () => {
+    const app = makeMultifileApp();
+    expect(resolveAppFilePath(app, "src/main.tsx")).toBe("src/main.tsx");
   });
-  test("returns auto_opened=false when proxy resolver throws", async () => {
-    const store = makeMockStore();
-    const proxy: ProxyResolver = async () => {
-      throw new Error("no client");
-    };
-    const result = await executeAppCreate(
-      { name: "Fail Open", html: "<p/>" },
-      store,
-      proxy,
-    );
-    expect(result.isError).toBe(false);
-    const parsed = JSON.parse(result.content);
-    expect(parsed.auto_opened).toBe(false);
-    expect(parsed.auto_open_error).toBe(
-      "Failed to auto-open app. Use app_open to open it manually.",
-    );
+  test("passes through dist/ prefix unchanged for multifile app", () => {
+    const app = makeMultifileApp();
+    expect(resolveAppFilePath(app, "dist/bundle.js")).toBe("dist/bundle.js");
   });
-  test("skips auto-open when auto_open is false", async () => {
-    let proxyCalled = false;
-    const store = makeMockStore();
-    const proxy: ProxyResolver = async () => {
-      proxyCalled = true;
-      return { content: "opened", isError: false };
-    };
-    const result = await executeAppCreate(
-      { name: "No Open", html: "<p/>", auto_open: false },
-      store,
-      proxy,
+  test("passes through records/ prefix unchanged for multifile app", () => {
+    const app = makeMultifileApp();
+    expect(resolveAppFilePath(app, "records/data.json")).toBe(
+      "records/data.json",
     );
-    expect(proxyCalled).toBe(false);
-    expect(result.isError).toBe(false);
-    const parsed = JSON.parse(result.content);
-    expect(parsed.auto_opened).toBeUndefined();
   });
-  test("skips auto-open when no proxyToolResolver", async () => {
-    const store = makeMockStore();
-    const result = await executeAppCreate(
-      { name: "No Proxy", html: "<p/>" },
-      store,
-    );
-    expect(result.isError).toBe(false);
-    const parsed = JSON.parse(result.content);
-    expect(parsed.auto_opened).toBeUndefined();
+  test("does not modify path for legacy app", () => {
+    const app = makeLegacyApp();
+    expect(resolveAppFilePath(app, "main.tsx")).toBe("main.tsx");
   });
-  test("passes pages through to store.createApp", async () => {
-    let capturedPages: Record<string, string> | undefined;
-    const store = makeMockStore({
-      createApp: (params) => {
-        capturedPages = params.pages;
-        return makeApp({ name: params.name });
-      },
-    });
-    await executeAppCreate(
-      { name: "Multi", html: "<p/>", pages: { "settings.html": "<div/>" } },
-      store,
-    );
-    expect(capturedPages).toEqual({ "settings.html": "<div/>" });
+  test("does not modify path for legacy app (formatVersion undefined)", () => {
+    const app = makeLegacyApp({ formatVersion: undefined });
+    expect(resolveAppFilePath(app, "styles.css")).toBe("styles.css");
   });
-  test("defaults html to minimal scaffold when omitted", async () => {
-    let capturedHtml: string | undefined;
-    const store = makeMockStore({
-      createApp: (params) => {
-        capturedHtml = params.htmlDefinition;
-        return makeApp({ name: params.name });
-      },
-    });
-    await executeAppCreate({ name: "No HTML" }, store);
-    expect(capturedHtml).toBe(
-      "<!DOCTYPE html><html><head></head><body></body></html>",
-    );
+  test("does not modify path for legacy app (formatVersion 1)", () => {
+    const app = makeLegacyApp({ formatVersion: 1 });
+    expect(resolveAppFilePath(app, "index.html")).toBe("index.html");
   });
-});
-// ---------------------------------------------------------------------------
-// app_list
-// ---------------------------------------------------------------------------
-describe("executeAppList", () => {
-  test("returns mapped list of apps", () => {
-    const store = makeMockStore({
-      listApps: () => [
-        makeApp({
-          id: "a1",
-          name: "First",
-          description: "desc1",
-          updatedAt: 100,
-        }),
-        makeApp({ id: "a2", name: "Second", updatedAt: 200 }),
-      ],
-    });
-    const result = executeAppList(store);
-    expect(result.isError).toBe(false);
-    const parsed = JSON.parse(result.content);
-    expect(parsed).toHaveLength(2);
-    expect(parsed[0]).toEqual({
-      id: "a1",
-      name: "First",
-      description: "desc1",
-      updatedAt: 100,
-    });
-    expect(parsed[1].id).toBe("a2");
-    // Should not include htmlDefinition or schemaJson
-    expect(parsed[0].htmlDefinition).toBeUndefined();
-    expect(parsed[0].schemaJson).toBeUndefined();
+  test("strips ./ prefix and prepends src/ for multifile app", () => {
+    const app = makeMultifileApp();
+    expect(resolveAppFilePath(app, "./main.tsx")).toBe("src/main.tsx");
   });
-  test("returns empty array when no apps exist", () => {
-    const store = makeMockStore({ listApps: () => [] });
-    const result = executeAppList(store);
-    expect(result.isError).toBe(false);
-    expect(JSON.parse(result.content)).toEqual([]);
+  test("strips ./ prefix for known top-level dir in multifile app", () => {
+    const app = makeMultifileApp();
+    expect(resolveAppFilePath(app, "./src/main.tsx")).toBe("src/main.tsx");
+    expect(resolveAppFilePath(app, "./dist/bundle.js")).toBe("dist/bundle.js");
+    expect(resolveAppFilePath(app, "./records/data.json")).toBe(
+      "records/data.json",
+    );
   });
 });
 // ---------------------------------------------------------------------------
-// app_query
+// executeAppFileWrite
 // ---------------------------------------------------------------------------
-describe("executeAppQuery", () => {
-  test("returns records for a given app", () => {
-    const records = [{ id: "r1", appId: "app-1", data: { x: 1 } }];
-    const store = makeMockStore({ queryAppRecords: () => records });
-    const result = executeAppQuery({ app_id: "app-1" }, store);
-    expect(result.isError).toBe(false);
-    expect(JSON.parse(result.content)).toEqual(records);
-  });
-  test("returns empty array when no records", () => {
-    const store = makeMockStore({ queryAppRecords: () => [] });
-    const result = executeAppQuery({ app_id: "app-1" }, store);
-    expect(result.isError).toBe(false);
-    expect(JSON.parse(result.content)).toEqual([]);
-  });
-});
-// ---------------------------------------------------------------------------
-// app_update
-// ---------------------------------------------------------------------------
+describe("executeAppFileWrite", () => {
+  test("resolves plain path to src/ for multifile app", () => {
+    const files: Record<string, string> = {};
+    const app = makeMultifileApp();
+    const store = mockStore(app, files);
-describe("executeAppUpdate", () => {
-  test("passes update fields through to store", () => {
-    let capturedUpdates: Record<string, unknown> = {};
-    const store = makeMockStore({
-      updateApp: (_id, updates) => {
-        capturedUpdates = updates;
-        return makeApp({ id: _id, ...updates });
-      },
-    });
-    const result = executeAppUpdate(
-      {
-        app_id: "app-1",
-        name: "New Name",
-        description: "New desc",
-        schema_json: '{"a":1}',
-        html: "<div/>",
-        pages: { "about.html": "<p/>" },
-      },
+    const result = executeAppFileWrite(
+      { app_id: app.id, path: "main.tsx", content: "export default 1;" },
       store,
     );
     expect(result.isError).toBe(false);
-    expect(capturedUpdates).toEqual({
-      name: "New Name",
-      description: "New desc",
-      schemaJson: '{"a":1}',
-      htmlDefinition: "<div/>",
-      pages: { "about.html": "<p/>" },
-    });
+    expect(JSON.parse(result.content).path).toBe("src/main.tsx");
+    expect(files["src/main.tsx"]).toBe("export default 1;");
   });
-  test("only includes provided fields in updates", () => {
-    let capturedUpdates: Record<string, unknown> = {};
-    const store = makeMockStore({
-      updateApp: (_id, updates) => {
-        capturedUpdates = updates;
-        return makeApp({ id: _id, ...updates });
-      },
-    });
-    executeAppUpdate({ app_id: "app-1", name: "Only Name" }, store);
-    expect(capturedUpdates).toEqual({ name: "Only Name" });
-    // html, description, schema_json, pages should NOT be in the updates
-    expect("htmlDefinition" in capturedUpdates).toBe(false);
-    expect("description" in capturedUpdates).toBe(false);
-    expect("schemaJson" in capturedUpdates).toBe(false);
-    expect("pages" in capturedUpdates).toBe(false);
-  });
+  test("passes through src/ path unchanged for multifile app", () => {
+    const files: Record<string, string> = {};
+    const app = makeMultifileApp();
+    const store = mockStore(app, files);
-  test("propagates store errors", () => {
-    const store = makeMockStore({
-      updateApp: () => {
-        throw new Error("App not found: bad-id");
-      },
-    });
-    expect(() => executeAppUpdate({ app_id: "bad-id" }, store)).toThrow(
-      "App not found: bad-id",
+    const result = executeAppFileWrite(
+      { app_id: app.id, path: "src/main.tsx", content: "export default 2;" },
+      store,
     );
-  });
-});
-// ---------------------------------------------------------------------------
-// app_delete
-// ---------------------------------------------------------------------------
-describe("executeAppDelete", () => {
-  test("deletes the app and returns confirmation", () => {
-    let deletedId: string | undefined;
-    const store = makeMockStore({
-      deleteApp: (id) => {
-        deletedId = id;
-      },
-    });
-    const result = executeAppDelete({ app_id: "app-1" }, store);
     expect(result.isError).toBe(false);
-    expect(JSON.parse(result.content)).toEqual({
-      deleted: true,
-      appId: "app-1",
-    });
-    expect(deletedId).toBe("app-1");
+    expect(JSON.parse(result.content).path).toBe("src/main.tsx");
+    expect(files["src/main.tsx"]).toBe("export default 2;");
   });
-});
-// ---------------------------------------------------------------------------
-// app_file_list
-// ---------------------------------------------------------------------------
+  test("does not modify path for legacy app", () => {
+    const files: Record<string, string> = {};
+    const app = makeLegacyApp();
+    const store = mockStore(app, files);
-describe("executeAppFileList", () => {
-  test("returns list of files", () => {
-    const store = makeMockStore({
-      listAppFiles: () => ["index.html", "styles.css", "js/app.js"],
-    });
-    const result = executeAppFileList({ app_id: "app-1" }, store);
-    expect(result.isError).toBe(false);
-    expect(JSON.parse(result.content)).toEqual([
-      "index.html",
-      "styles.css",
-      "js/app.js",
-    ]);
-  });
+    const result = executeAppFileWrite(
+      { app_id: app.id, path: "index.html", content: "<html></html>" },
+      store,
+    );
-  test("returns empty array when app has no files", () => {
-    const store = makeMockStore({ listAppFiles: () => [] });
-    const result = executeAppFileList({ app_id: "app-1" }, store);
     expect(result.isError).toBe(false);
-    expect(JSON.parse(result.content)).toEqual([]);
+    expect(JSON.parse(result.content).path).toBe("index.html");
+    expect(files["index.html"]).toBe("<html></html>");
   });
 });
 // ---------------------------------------------------------------------------
-// app_file_read
+// executeAppFileRead
 // ---------------------------------------------------------------------------
 describe("executeAppFileRead", () => {
-  test("returns formatted content with line numbers", () => {
-    const store = makeMockStore({
-      readAppFile: () => "line1\nline2\nline3",
-    });
-    const result = executeAppFileRead(
-      { app_id: "app-1", path: "index.html" },
-      store,
-    );
-    expect(result.isError).toBe(false);
-    expect(result.content).toBe("     1\tline1\n     2\tline2\n     3\tline3");
-  });
+  test("resolves plain path to src/ for multifile app", () => {
+    const app = makeMultifileApp();
+    const store = mockStore(app, { "src/main.tsx": "line1\nline2" });
-  test("applies offset parameter (1-based)", () => {
-    const store = makeMockStore({
-      readAppFile: () => "a\nb\nc\nd\ne",
-    });
     const result = executeAppFileRead(
-      { app_id: "app-1", path: "f.txt", offset: 3 },
+      { app_id: app.id, path: "main.tsx" },
       store,
     );
-    expect(result.isError).toBe(false);
-    // Lines 3, 4, 5
-    expect(result.content).toBe("     3\tc\n     4\td\n     5\te");
-  });
-  test("applies limit parameter", () => {
-    const store = makeMockStore({
-      readAppFile: () => "a\nb\nc\nd\ne",
-    });
-    const result = executeAppFileRead(
-      { app_id: "app-1", path: "f.txt", limit: 2 },
-      store,
-    );
     expect(result.isError).toBe(false);
-    expect(result.content).toBe("     1\ta\n     2\tb");
+    expect(result.content).toContain("line1");
   });
-  test("applies both offset and limit", () => {
-    const store = makeMockStore({
-      readAppFile: () => "a\nb\nc\nd\ne",
-    });
+  test("can read dist/ files explicitly for multifile app", () => {
+    const app = makeMultifileApp();
+    const store = mockStore(app, { "dist/bundle.js": "bundled code" });
     const result = executeAppFileRead(
-      { app_id: "app-1", path: "f.txt", offset: 2, limit: 2 },
+      { app_id: app.id, path: "dist/bundle.js" },
       store,
     );
     expect(result.isError).toBe(false);
-    expect(result.content).toBe("     2\tb\n     3\tc");
+    expect(result.content).toContain("bundled code");
   });
-  test("defaults offset to 1 when not provided", () => {
-    const store = makeMockStore({
-      readAppFile: () => "only",
-    });
+  test("does not modify path for legacy app", () => {
+    const app = makeLegacyApp();
+    const store = mockStore(app, { "index.html": "<html>hello</html>" });
     const result = executeAppFileRead(
-      { app_id: "app-1", path: "f.txt" },
+      { app_id: app.id, path: "index.html" },
       store,
     );
-    expect(result.content).toBe("     1\tonly");
-  });
-  test("propagates store errors (e.g. file not found)", () => {
-    const store = makeMockStore({
-      readAppFile: () => {
-        throw new Error("File not found: missing.txt");
-      },
-    });
-    expect(() =>
-      executeAppFileRead({ app_id: "app-1", path: "missing.txt" }, store),
-    ).toThrow("File not found: missing.txt");
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("<html>hello</html>");
   });
 });
 // ---------------------------------------------------------------------------
-// app_file_edit
+// executeAppFileEdit
 // ---------------------------------------------------------------------------
 describe("executeAppFileEdit", () => {
-  test("returns edit result from store", () => {
-    const editResult: EditEngineResult = {
-      ok: true,
-      updatedContent: "updated",
-      matchCount: 1,
-      matchMethod: "exact" as const,
-      similarity: 1,
-      actualOld: "old",
-      actualNew: "new",
-    };
-    const store = makeMockStore({ editAppFile: () => editResult });
+  test("resolves plain path to src/ for multifile app", () => {
+    const files = { "src/main.tsx": "const x = 1;" };
+    const app = makeMultifileApp();
+    const store = mockStore(app, files);
     const result = executeAppFileEdit(
       {
-        app_id: "app-1",
-        path: "index.html",
-        old_string: "old",
-        new_string: "new",
+        app_id: app.id,
+        path: "main.tsx",
+        old_string: "const x = 1;",
+        new_string: "const x = 2;",
       },
       store,
     );
     expect(result.isError).toBe(false);
-    expect(JSON.parse(result.content)).toEqual(editResult);
+    expect(files["src/main.tsx"]).toBe("const x = 2;");
   });
-  test("returns error when old_string is empty", () => {
-    const store = makeMockStore();
+  test("does not modify path for legacy app", () => {
+    const files = { "index.html": "<p>old</p>" };
+    const app = makeLegacyApp();
+    const store = mockStore(app, files);
     const result = executeAppFileEdit(
       {
-        app_id: "app-1",
+        app_id: app.id,
         path: "index.html",
-        old_string: "",
-        new_string: "new",
+        old_string: "<p>old</p>",
+        new_string: "<p>new</p>",
       },
       store,
     );
-    expect(result.isError).toBe(true);
-    expect(JSON.parse(result.content)).toEqual({
-      error: "old_string must not be empty",
-    });
+    expect(result.isError).toBe(false);
+    expect(files["index.html"]).toBe("<p>new</p>");
   });
+});
-  test("passes replace_all through to store", () => {
-    let capturedReplaceAll: boolean | undefined;
-    const store = makeMockStore({
-      editAppFile: (_appId, _path, _old, _new, replaceAll) => {
-        capturedReplaceAll = replaceAll;
-        return {
-          ok: true,
-          updatedContent: "",
-          matchCount: 1,
-          matchMethod: "exact" as const,
-          similarity: 1,
-          actualOld: "",
-          actualNew: "",
-        };
-      },
+// ---------------------------------------------------------------------------
+// executeAppFileList
+// ---------------------------------------------------------------------------
+describe("executeAppFileList", () => {
+  test("returns clean file paths and separate buildOutput for multifile app", () => {
+    const app = makeMultifileApp();
+    const store = mockStore(app, {
+      "src/main.tsx": "",
+      "src/components/Header.tsx": "",
+      "dist/index.html": "",
     });
-    executeAppFileEdit(
-      {
-        app_id: "app-1",
-        path: "f.txt",
-        old_string: "x",
-        new_string: "y",
-        replace_all: true,
-      },
-      store,
-    );
-    expect(capturedReplaceAll).toBe(true);
+    const result = executeAppFileList({ app_id: app.id }, store);
+    const parsed = JSON.parse(result.content) as {
+      files: string[];
+      buildOutput: string[];
+    };
+    // File paths must be clean — no annotations appended
+    expect(parsed.files).toContain("src/main.tsx");
+    expect(parsed.files).toContain("src/components/Header.tsx");
+    expect(parsed.files).toContain("dist/index.html");
+    expect(
+      parsed.files.every((f: string) => !f.includes("[build output]")),
+    ).toBe(true);
+    // Build output files listed separately
+    expect(parsed.buildOutput).toEqual(["dist/index.html"]);
   });
-  test("defaults replace_all to false", () => {
-    let capturedReplaceAll: boolean | undefined;
-    const store = makeMockStore({
-      editAppFile: (_appId, _path, _old, _new, replaceAll) => {
-        capturedReplaceAll = replaceAll;
-        return {
-          ok: true,
-          updatedContent: "",
-          matchCount: 1,
-          matchMethod: "exact" as const,
-          similarity: 1,
-          actualOld: "",
-          actualNew: "",
-        };
-      },
+  test("does not annotate files for legacy app", () => {
+    const app = makeLegacyApp();
+    const store = mockStore(app, {
+      "index.html": "",
+      "styles.css": "",
     });
-    executeAppFileEdit(
-      {
-        app_id: "app-1",
-        path: "f.txt",
-        old_string: "x",
-        new_string: "y",
-      },
-      store,
-    );
-    expect(capturedReplaceAll).toBe(false);
-  });
-  test("passes status through to result", () => {
-    const store = makeMockStore();
-    const result = executeAppFileEdit(
-      {
-        app_id: "app-1",
-        path: "f.txt",
-        old_string: "x",
-        new_string: "y",
-        status: "updating styles",
-      },
-      store,
+    const result = executeAppFileList({ app_id: app.id }, store);
+    const parsed = JSON.parse(result.content) as string[];
+    expect(parsed).toContain("index.html");
+    expect(parsed).toContain("styles.css");
+    expect(parsed.every((f: string) => !f.includes("[build output]"))).toBe(
+      true,
     );
-    expect(result.status).toBe("updating styles");
   });
 });
 // ---------------------------------------------------------------------------
-// app_file_write
+// executeAppCreate
 // ---------------------------------------------------------------------------
-describe("executeAppFileWrite", () => {
-  test("writes file and returns confirmation", () => {
-    let writtenPath: string | undefined;
-    let writtenContent: string | undefined;
-    const store = makeMockStore({
-      writeAppFile: (_appId, path, content) => {
-        writtenPath = path;
-        writtenContent = content;
+describe("executeAppCreate", () => {
+  test("flag off: creates legacy app with root index.html", async () => {
+    const files: Record<string, string> = {};
+    let createdParams: Record<string, unknown> | undefined;
+    const app = makeLegacyApp();
+    const store: AppStore = {
+      ...mockStore(app, files),
+      createApp: (params) => {
+        createdParams = params as unknown as Record<string, unknown>;
+        return app;
+      },
+    };
+    const result = await executeAppCreate(
+      {
+        name: "Test App",
+        html: "<html><body>Hello</body></html>",
       },
-    });
-    const result = executeAppFileWrite(
-      { app_id: "app-1", path: "new.html", content: "<div/>" },
       store,
     );
     expect(result.isError).toBe(false);
-    expect(JSON.parse(result.content)).toEqual({
-      written: true,
-      path: "new.html",
-    });
-    expect(writtenPath).toBe("new.html");
-    expect(writtenContent).toBe("<div/>");
+    // Legacy path: no formatVersion set, htmlDefinition is the provided html
+    expect(createdParams?.formatVersion).toBeUndefined();
+    expect(createdParams?.htmlDefinition).toBe(
+      "<html><body>Hello</body></html>",
+    );
+    // No src/ files should be written
+    expect(files["src/index.html"]).toBeUndefined();
+    expect(files["src/main.tsx"]).toBeUndefined();
   });
-  test("returns error when app is not found", () => {
-    const store = makeMockStore({ getApp: () => null });
-    const result = executeAppFileWrite(
-      { app_id: "missing", path: "f.txt", content: "hi" },
+  test("flag on: creates multifile app with src/ scaffold", async () => {
+    const files: Record<string, string> = {};
+    let createdParams: Record<string, unknown> | undefined;
+    const app = makeMultifileApp({ name: "New App" });
+    const store: AppStore = {
+      ...mockStore(app, files),
+      createApp: (params) => {
+        createdParams = params as unknown as Record<string, unknown>;
+        return app;
+      },
+    };
+    const result = await executeAppCreate(
+      {
+        name: "New App",
+        featureFlags: { multifileEnabled: true },
+      },
       store,
     );
-    expect(result.isError).toBe(true);
-    expect(JSON.parse(result.content)).toEqual({
-      error: "App 'missing' not found",
-    });
-  });
-  test("passes status through to result", () => {
-    const store = makeMockStore();
-    const result = executeAppFileWrite(
+    expect(result.isError).toBe(false);
+    // formatVersion 2 passed to createApp
+    expect(createdParams?.formatVersion).toBe(2);
+    // htmlDefinition should be empty for multifile apps
+    expect(createdParams?.htmlDefinition).toBe("");
+    // Scaffold files should be written
+    expect(files["src/index.html"]).toBeDefined();
+    expect(files["src/index.html"]).toContain("<title>New App</title>");
+    expect(files["src/index.html"]).toContain('<div id="app"></div>');
+    expect(files["src/main.tsx"]).toBeDefined();
+    expect(files["src/main.tsx"]).toContain("import { render } from 'preact'");
+    expect(files["src/main.tsx"]).toContain('{"Hello, New App!"}');
+  });
+  test("flag on with explicit html: uses provided html as src/index.html", async () => {
+    const files: Record<string, string> = {};
+    const app = makeMultifileApp({ name: "Custom App" });
+    const store: AppStore = {
+      ...mockStore(app, files),
+      createApp: () => app,
+    };
+    const customHtml =
+      '<!DOCTYPE html><html><head></head><body><div id="root"></div></body></html>';
+    const result = await executeAppCreate(
       {
-        app_id: "app-1",
-        path: "f.txt",
-        content: "hi",
-        status: "adding dark mode styles",
+        name: "Custom App",
+        html: customHtml,
+        featureFlags: { multifileEnabled: true },
       },
       store,
     );
-    expect(result.status).toBe("adding dark mode styles");
-  });
-  test("does not call writeAppFile when app not found", () => {
-    let writeCalled = false;
-    const store = makeMockStore({
-      getApp: () => null,
-      writeAppFile: () => {
-        writeCalled = true;
-      },
-    });
-    executeAppFileWrite({ app_id: "bad", path: "f.txt", content: "x" }, store);
-    expect(writeCalled).toBe(false);
+    expect(result.isError).toBe(false);
+    // Explicit HTML should be used instead of scaffold
+    expect(files["src/index.html"]).toBe(customHtml);
+    // main.tsx scaffold should still be written
+    expect(files["src/main.tsx"]).toBeDefined();
   });
 });