feat: v2 - ai assistant web worker scaffolding

knip.json

@@ -1,6 +1,7 @@
 {
   "$schema": "https://unpkg.com/knip@5/schema.json",
   "tags": ["-@public"],
+  "entry": ["src/agent/worker.ts"],
   "ignore": [
     "src/api/**",
     "src/components/ui/**",

package.json

@@ -89,6 +89,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
+    "comlink": "^4.4.2",
     "date-fns": "^4.3.0",
     "dexie": "^4.4.2",
     "dexie-react-hooks": "^4.4.0",

src/agent/types.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared types between the worker and the main thread.
+ */
+
+export interface AgentResponse {
+  answer: string;
+  threadId: string;
+  componentReferences: Record<string, { name: string; yamlText: string }>;
+}

src/agent/worker.ts

@@ -0,0 +1,86 @@
+/**
+ * Web Worker entry point for the in-browser agent.
+ *
+ * A placeholder `ask()` that echoes the user's message — it
+ * proves the bundling, lazy-spawn, and Comlink round-trip are working
+ * end-to-end before we wire the LLM and the tool bridge.
+ *
+ * The `globalThis.process` stub below covers an unguarded
+ * `process.env.X` read in `@openai/agents-core` v0.4.x
+ * (`runner/sessionPersistence.mjs` reads
+ * `process.env.OPENAI_AGENTS__DEBUG_SAVE_SESSION` without a
+ * `typeof process` guard) that would otherwise throw
+ * `ReferenceError: process is not defined` on every turn that
+ * persists session state. The stub deliberately omits `.on` /
+ * `.exit` so the SDK's `typeof process.on === 'function'` checks
+ * still skip the Node-only branches and we do not pretend to be
+ * Node. It is inlined here (rather than living in a separate
+ * polyfill file) so Rolldown's worker bundle does not tree-shake
+ * the side-effect import, and so it runs in both `vite build` and
+ * `vite serve` (dev) modes, which `worker.rolldownOptions.define`
+ * would not.
+ */
+const __workerGlobal = globalThis as { process?: { env?: unknown } };
+if (typeof __workerGlobal.process === "undefined") {
+  __workerGlobal.process = { env: {} };
+}
+// Anchor: keep Rolldown from tree-shaking the assignment above. In
+// `vite build` Vite statically replaces `process.env` with `{}`, so the
+// rest of the bundle never reads `globalThis.process` and Rolldown
+// would otherwise treat the write as dead. Throwing on a hasOwnProperty
+// check forces the write to be observable.
+if (!Object.prototype.hasOwnProperty.call(globalThis, "process")) {
+  throw new Error("Tangle agent worker: globalThis.process polyfill failed");
+}
+
+import * as Comlink from "comlink";
+
+import type { AgentResponse } from "./types";
+
+export interface AskParams {
+  message: string;
+  threadId?: string;
+}
+
+export interface AgentWorkerApi {
+  ask(params: AskParams): Promise<AgentResponse>;
+  ping(): Promise<"pong">;
+}
+
+let emitStatus: (status: { text: string }) => void = () => {};
+
+function generateThreadId(): string {
+  return `thread-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+const api: AgentWorkerApi = {
+  async ping() {
+    return "pong";
+  },
+
+  async ask({ message, threadId }) {
+    /**
+     * todo: replace with actual AI response.
+     */
+    return {
+      answer: `Worker echo: ${message}`,
+      threadId: threadId ?? generateThreadId(),
+      componentReferences: {},
+    };
+  },
+};
+
+/**
+ * Initialization entry point. Called once by the main thread immediately
+ * after spawning the worker. Splits init from ask() so future bridge /
+ * skill plumbing has an explicit lifecycle hook.
+ */
+export function init(onStatus: (status: { text: string }) => void): void {
+  emitStatus = onStatus;
+  // TODO: read `emitStatus` from the dispatcher's observability hooks;
+  // until then this no-op read keeps `noUnusedLocals` quiet without
+  // dropping the assignment that locks in the init() contract.
+  void emitStatus;
+}
+
+Comlink.expose({ ...api, init });

src/routes/v2/pages/Editor/components/AiChat/agentClient.ts

@@ -0,0 +1,76 @@
+/**
+ * Main-thread client for the in-browser agent worker.
+ *
+ * Spawns a single Web Worker (lazy, on first use), wires it up over
+ * Comlink, and exposes a typed `ask()` method that the AI Chat store
+ * calls.
+ */
+import * as Comlink from "comlink";
+
+import type { AgentResponse } from "@/agent/types";
+import type { AgentWorkerApi } from "@/agent/worker";
+
+interface WorkerExports extends AgentWorkerApi {
+  init(onStatus: (status: { text: string }) => void): void;
+}
+
+interface InitDeps {
+  onStatus: (status: { text: string }) => void;
+}
+
+interface AskOptions {
+  message: string;
+  threadId?: string;
+}
+
+class AgentClient {
+  private worker: Worker | null = null;
+  private remote: Comlink.Remote<WorkerExports> | null = null;
+  private initPromise: Promise<void> | null = null;
+
+  private async ensureInit(
+    deps: InitDeps,
+  ): Promise<Comlink.Remote<WorkerExports>> {
+    if (!this.worker) {
+      this.worker = new Worker(new URL("@/agent/worker.ts", import.meta.url), {
+        type: "module",
+        name: "tangle-agent",
+      });
+      this.remote = Comlink.wrap<WorkerExports>(this.worker);
+    }
+    if (!this.remote) {
+      throw new Error("Worker remote was not created");
+    }
+    if (!this.initPromise) {
+      // Pass onStatus as a top-level Comlink-proxied arg.
+      // Each new one must stay a separate top-level argument because Comlink only applies its proxy
+      // transfer handler to top-level argument values, it does not
+      // recursively walk into properties of an object arg.
+      //
+      // Wrapping proxied values in a single object would cause structured-clone
+      // of the methods and fail.
+      this.initPromise = this.remote.init(Comlink.proxy(deps.onStatus));
+    }
+    await this.initPromise;
+    return this.remote;
+  }
+
+  async ask(deps: InitDeps, options: AskOptions): Promise<AgentResponse> {
+    const remote = await this.ensureInit(deps);
+    return remote.ask(options);
+  }
+
+  terminate(): void {
+    this.worker?.terminate();
+    this.worker = null;
+    this.remote = null;
+    this.initPromise = null;
+  }
+}
+
+let singleton: AgentClient | null = null;
+
+export function getAgentClient(): AgentClient {
+  if (!singleton) singleton = new AgentClient();
+  return singleton;
+}

src/routes/v2/pages/Editor/components/AiChat/aiChatStore.ts

@@ -2,6 +2,7 @@ import { action, makeObservable, observable, runInAction } from "mobx";
 
 import { getErrorMessage } from "@/utils/string";
 
+import { getAgentClient } from "./agentClient";
 import type { ChatMessage } from "./aiChat.types";
 
 function generateMessageId(): string {
@@ -15,9 +16,6 @@ interface SendMessageOptions {
 /**
  * Stores AI chat state (messages, thread, pending status) outside the
  * React component tree so it survives window minimize / hide / unmount.
- *
- * PR 1: `sendMessage` is a stub that appends a hardcoded assistant echo.
- * The real worker / LLM round-trip lands in PR 2 / PR 3.
  */
 export class AiChatStore {
   @observable.shallow accessor messages: ChatMessage[] = [];
@@ -55,17 +53,30 @@ export class AiChatStore {
     });
 
     try {
-      /**
-       * Echo the user's message back to the user.
-       * TODO: replace with actual AI response.
-       */
+      const client = getAgentClient();
+      const response = await client.ask(
+        {
+          onStatus: (status) => {
+            runInAction(() => {
+              this.thinkingText = status.text;
+            });
+          },
+        },
+        {
+          message: prompt,
+          ...(this.threadId && { threadId: this.threadId }),
+        },
+      );
+
       runInAction(() => {
+        this.thinkingText = null;
+        this.threadId = response.threadId;
         this.messages = [
           ...this.messages,
           {
             id: generateMessageId(),
             role: "assistant",
-            content: `${prompt}`,
+            content: response.answer,
           },
         ];
       });

vite.config.js

@@ -74,6 +74,13 @@ export default defineConfig(({ mode }) => {
       },
     },
     assetsInclude: ["**/*.yaml", "**/*.py"],
+    // The agent runs in a Web Worker. The `@openai/agents-core/_shims`
+    // alias and matching plugin land in PR 3 alongside the SDK
+    // dependency itself; PR 2 only needs ESM output for the worker
+    // bundle so dynamic `import.meta.url` resolves correctly.
+    worker: {
+      format: "es",
+    },
     test: {
       globals: true,
       environment: "jsdom",