@alexanderolsen/create-deepagent 0.1.0

package/registry/frameworks/nuxt/server/api/threads/[threadId]/state.get.ts

@@ -0,0 +1,22 @@
+/**
+ * `GET /api/threads/:threadId/state`.
+ *
+ * Reads checkpointed thread state. Returns 404 when the thread has no
+ * checkpoint yet so the LangGraph SDK can bootstrap it before the first run.
+ */
+
+import { getAgent } from "../../../utils/runtime";
+import { ThreadNotFoundError, getThreadState } from "../../../utils/threads";
+
+export default defineEventHandler(async (event) => {
+  const threadId = getRouterParam(event, "threadId") ?? "local";
+  try {
+    return await getThreadState(getAgent().graph, threadId);
+  } catch (error) {
+    if (error instanceof ThreadNotFoundError) {
+      setResponseStatus(event, 404);
+      return { error: "not_found", message: error.message };
+    }
+    throw error;
+  }
+});

package/registry/frameworks/nuxt/server/api/threads/[threadId]/state.post.ts

@@ -0,0 +1,32 @@
+/**
+ * `POST /api/threads/:threadId/state`.
+ *
+ * Creates or updates checkpointed thread state. Used by the browser bootstrap
+ * and by the SDK when hydrating or editing conversation history.
+ */
+
+import { getAgent } from "../../../utils/runtime";
+import { updateThreadState } from "../../../utils/threads";
+
+type StateUpdateBody = {
+  values?: Record<string, unknown> | null;
+  checkpoint?: Record<string, unknown> | null;
+  as_node?: string;
+};
+
+export default defineEventHandler(async (event) => {
+  const threadId = getRouterParam(event, "threadId") ?? "local";
+  const body = await readBody<StateUpdateBody>(event).catch(
+    () => ({}) as StateUpdateBody,
+  );
+  try {
+    return await updateThreadState(getAgent().graph, threadId, {
+      values: body.values ?? null,
+      checkpoint: body.checkpoint ?? null,
+      asNode: body.as_node,
+    });
+  } catch (error) {
+    setResponseStatus(event, 422);
+    return { error: "invalid_state_update", message: String(error) };
+  }
+});

package/registry/frameworks/nuxt/server/api/threads/[threadId]/stream.post.ts

@@ -0,0 +1,24 @@
+/**
+ * `POST /api/threads/:threadId/stream`.
+ *
+ * The request body is a connection-scoped `SubscribeParams` filter. The
+ * response is an SSE stream that first replays matching buffered events and
+ * then stays attached for live events from the same thread.
+ */
+
+import type { SubscribeParams } from "@langchain/protocol";
+
+import { getSession } from "../../../utils/runtime";
+
+export default defineEventHandler(async (event) => {
+  const threadId = getRouterParam(event, "threadId") ?? "local";
+  const params = await readBody<SubscribeParams>(event);
+
+  setResponseHeader(event, "content-type", "text/event-stream");
+  setResponseHeader(event, "cache-control", "no-cache");
+  setResponseHeader(event, "connection", "keep-alive");
+  // Disable proxy buffering so SSE frames flush immediately.
+  setResponseHeader(event, "x-accel-buffering", "no");
+
+  return getSession(threadId).stream(params);
+});

package/registry/frameworks/nuxt/server/api/threads/index.get.ts

@@ -0,0 +1,13 @@
+/**
+ * `GET /api/threads` — list every thread known to the checkpointer.
+ *
+ * The agent's in-memory `MemorySaver` is the single source of truth, so the
+ * sidebar is always derived from it (no client-side cache).
+ */
+
+import { getAgent, getCheckpointer } from "../../utils/runtime";
+import { listThreads } from "../../utils/threads";
+
+export default defineEventHandler(async () => {
+  return listThreads(getAgent().graph, getCheckpointer());
+});

package/registry/frameworks/nuxt/server/utils/runtime.ts

@@ -0,0 +1,42 @@
+import { agent, checkpointer } from "../agent";
+import { LocalThreadSession } from "./session";
+
+/**
+ * Process-local registry for the agent and its per-thread sessions.
+ *
+ * Under Nuxt the Agent Streaming Protocol is served by Nitro route handlers, so
+ * the shared agent + session registry is a module singleton instead of a
+ * standalone Hono server.
+ *
+ * NOTE: This is in-memory and process-local. A serverless/multi-instance
+ * deployment needs a durable checkpointer (Postgres, SQLite, …) and a shared
+ * session/replay store. The wiring here stays the same; only the checkpointer
+ * in `server/agent/index.ts` and this store change.
+ */
+const sessions = new Map<string, LocalThreadSession>();
+
+/** The shared, compiled agent (and its checkpointer). */
+export function getAgent() {
+  return agent;
+}
+
+/** The shared checkpointer — the single source of truth for threads. */
+export function getCheckpointer() {
+  return checkpointer;
+}
+
+/** Get or create the process-local session for a thread. */
+export function getSession(threadId: string): LocalThreadSession {
+  let session = sessions.get(threadId);
+  if (session == null) {
+    session = new LocalThreadSession(agent, threadId);
+    sessions.set(threadId, session);
+  }
+  return session;
+}
+
+/** Delete a thread: remove its session and its checkpointed state. */
+export async function deleteThread(threadId: string): Promise<void> {
+  sessions.delete(threadId);
+  await checkpointer.deleteThread(threadId);
+}

package/registry/frameworks/nuxt/server/utils/serialize.ts

@@ -0,0 +1,30 @@
+import { BaseMessage } from "@langchain/core/messages";
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/**
+ * Recursively replace LangChain message instances with plain protocol dicts.
+ *
+ * Uses {@link BaseMessage.isInstance} and {@link BaseMessage.toDict} from
+ * `@langchain/core/messages` — the canonical LangChain serialization primitive.
+ * Message instances surface in `values`/`updates` stream data and in the
+ * checkpointer state snapshot returned by the thread-state routes, often nested
+ * under `messages`.
+ */
+export function sanitizeForJson(value: unknown): unknown {
+  if (BaseMessage.isInstance(value)) {
+    const { type, data } = value.toDict();
+    return sanitizeForJson({ ...data, type });
+  }
+  if (Array.isArray(value)) return value.map(sanitizeForJson);
+  if (isRecord(value)) {
+    const result: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(value)) {
+      result[key] = sanitizeForJson(item);
+    }
+    return result;
+  }
+  return value;
+}

package/registry/frameworks/nuxt/server/utils/session.ts

@@ -0,0 +1,210 @@
+import type { ReactAgent } from "langchain";
+// `StreamChannel` buffers events; `matchesSubscription` is the shared protocol
+// predicate from `@langchain/langgraph/stream` — the same one langgraph-api
+// uses, so this custom transport stays aligned with the production server.
+import {
+  StreamChannel,
+  matchesSubscription,
+  type ProtocolEvent,
+} from "@langchain/langgraph/stream";
+import type {
+  Command,
+  CommandResponse,
+  ErrorResponse,
+  SubscribeParams,
+} from "@langchain/protocol";
+
+import { isRecord, sanitizeForJson } from "./serialize";
+
+// `ReactAgent<any>` accepts both `createAgent` results and `DeepAgent`
+// instances (which carry a specific, non-default type config).
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyReactAgent = ReactAgent<any>;
+
+type AgentRunInput = Parameters<AnyReactAgent["streamEvents"]>[0];
+
+/**
+ * Make an event safe to `JSON.stringify` onto the SSE wire.
+ *
+ * Only the protocol payload (`params.data`) and any `params.interrupts` can
+ * carry LangChain message instances, so those are the fields we sanitize into
+ * the plain, role-keyed protocol message shape the SDK expects.
+ */
+function sanitizeEvent(event: ProtocolEvent): ProtocolEvent {
+  const params = event.params as Record<string, unknown>;
+  const sanitizedParams: Record<string, unknown> = {
+    ...params,
+    data: sanitizeForJson(params.data),
+  };
+  if ("interrupts" in params) {
+    sanitizedParams.interrupts = sanitizeForJson(params.interrupts);
+  }
+  return { ...event, params: sanitizedParams } as ProtocolEvent;
+}
+
+/**
+ * Encode an Agent Protocol event as a Server-Sent Event frame.
+ *
+ * When available, `event_id` is mirrored into the SSE `id:` field for
+ * transport-level reconnection. The SDK primarily deduplicates by `event_id`
+ * and replays by `seq`; if an event has no `event_id`, this example falls back
+ * to `seq` as a stable frame id.
+ */
+function encodeSse(event: ProtocolEvent) {
+  const eventId = (event as { event_id?: string }).event_id;
+  const id = eventId ?? (typeof event.seq === "number" ? `${event.seq}` : "");
+  const idLine = id ? `id: ${id}\n` : "";
+  return new TextEncoder().encode(
+    `${idLine}event: message\ndata: ${JSON.stringify(event)}\n\n`,
+  );
+}
+
+/**
+ * Minimal in-memory Agent Streaming Protocol session for the example.
+ *
+ * This class is the server-side counterpart to `HttpAgentServerAdapter`:
+ *
+ * - `POST /threads/:thread_id/commands` sends a JSON `Command` and receives a
+ *   `CommandResponse` or `ErrorResponse`.
+ * - `POST /threads/:thread_id/stream` opens a connection-scoped SSE
+ *   subscription described by `SubscribeParams`.
+ * - Events are buffered by `seq` and replayed to later subscriptions, enabling
+ *   the SDK to rotate streams as subscriptions widen or narrow.
+ *
+ * The implementation is intentionally small and process-local. It is suitable
+ * for this example and for understanding the protocol shape, but production
+ * servers should persist threads, enforce concurrency policies, and coordinate
+ * replay buffers across workers.
+ */
+export class LocalThreadSession {
+  readonly #agent: AnyReactAgent;
+  readonly #threadId: string;
+
+  /**
+   * Per-thread protocol event log.
+   *
+   * A {@link StreamChannel} is LangGraph's buffered, append-only stream with
+   * independent per-consumer cursors. Every event ever published stays
+   * buffered, and each SSE subscription gets its own cursor via
+   * {@link StreamChannel.iterate}, so buffered replay and live delivery are the
+   * same iteration.
+   */
+  readonly #log = StreamChannel.local<ProtocolEvent>();
+
+  /** Monotonic seq across all runs on this thread (graph runs reset at 0). */
+  #nextSeq = 0;
+
+  #activeRun:
+    | {
+        abort(reason?: unknown): void;
+      }
+    | undefined;
+
+  constructor(agent: AnyReactAgent, threadId: string) {
+    this.#agent = agent;
+    this.#threadId = threadId;
+  }
+
+  /**
+   * Handle a thread command sent to the Agent Protocol `/commands` endpoint.
+   *
+   * The SDK sends `run.start` to start or resume a graph run on the current
+   * thread. This starts the in-process v3 stream and immediately returns a
+   * success response containing a generated `run_id`, while streamed events
+   * flow asynchronously through active `/stream` subscriptions.
+   */
+  async handleCommand(
+    command: Command,
+  ): Promise<CommandResponse | ErrorResponse> {
+    if (command.method !== "run.start") {
+      return {
+        type: "error",
+        id: command.id,
+        error: "unknown_command",
+        message: `Unsupported command: ${command.method}`,
+      } as ErrorResponse;
+    }
+
+    const params = isRecord(command.params)
+      ? (command.params as { input?: unknown })
+      : {};
+    const runId = crypto.randomUUID();
+    void this.#startRun(params.input as AgentRunInput, runId);
+
+    return {
+      type: "success",
+      id: command.id,
+      result: { run_id: runId },
+    } as CommandResponse;
+  }
+
+  /**
+   * Open a connection-scoped SSE subscription for this thread.
+   *
+   * The returned `ReadableStream` first replays buffered events matching the
+   * requested `channels`, `namespaces`, `depth`, and optional `since` cursor,
+   * then stays attached for live events. Closing the HTTP connection releases
+   * this subscription's event-log cursor.
+   */
+  stream(params: SubscribeParams) {
+    const cursor = this.#log.iterate();
+
+    return new ReadableStream<Uint8Array>({
+      pull: async (controller) => {
+        // Scan forward until we find an event matching this subscription's
+        // filter, enqueue exactly one frame, and return so the channel honors
+        // the consumer's backpressure. `cursor.next()` resolves immediately for
+        // buffered events and suspends once the live edge is reached.
+        for (;;) {
+          const { value: event, done } = await cursor.next();
+          if (done) {
+            controller.close();
+            return;
+          }
+          if (matchesSubscription(event, params)) {
+            controller.enqueue(encodeSse(event));
+            return;
+          }
+        }
+      },
+      cancel: () => {
+        void cursor.return?.(undefined);
+      },
+    });
+  }
+
+  #publish(rawEvent: ProtocolEvent) {
+    const seq = this.#nextSeq;
+    this.#nextSeq += 1;
+    const event = sanitizeEvent({
+      ...rawEvent,
+      type: "event",
+      seq,
+    } as ProtocolEvent);
+    this.#log.push(event);
+  }
+
+  async #startRun(input: AgentRunInput, runId: string) {
+    this.#activeRun?.abort("Starting a new run.");
+    // Thread the `thread_id` / `run_id` into the run config so the checkpointer
+    // persists conversation state per thread and downstream events carry the
+    // run identity.
+    const run = await this.#agent.streamEvents(input, {
+      version: "v3",
+      configurable: { thread_id: this.#threadId, run_id: runId },
+    });
+    this.#activeRun = run;
+
+    try {
+      for await (const rawEvent of run) {
+        this.#publish(rawEvent as ProtocolEvent);
+      }
+    } catch (error) {
+      console.error(error);
+    } finally {
+      if (this.#activeRun === run) {
+        this.#activeRun = undefined;
+      }
+    }
+  }
+}