@alexanderolsen/create-deepagent 0.1.0

package/registry/frameworks/next/components/Subagents.tsx

@@ -0,0 +1,120 @@
+"use client";
+
+import { useMemo } from "react";
+
+import type { BaseMessage } from "@langchain/core/messages";
+import type { SubagentDiscoverySnapshot } from "@langchain/langgraph-sdk/stream";
+import { useMessages, useStreamContext } from "@langchain/react";
+
+import type { Agent } from "@/lib/agent";
+import { MessageThread } from "./MessageThread";
+import { StreamingIndicator } from "./StreamingIndicator";
+
+export type SubagentStatus = SubagentDiscoverySnapshot["status"];
+
+/** Lightweight model for a subagent card, derived from a `task` tool call. */
+export type SubagentCard = {
+  /** The `task` tool-call id — also the subagent discovery key. */
+  id: string;
+  name: string;
+  task?: string;
+  status: SubagentStatus;
+  /** Whether a discovery snapshot exists yet (i.e. the card can be opened). */
+  openable: boolean;
+};
+
+function statusLabel(status: SubagentStatus) {
+  if (status === "running") return "Running";
+  if (status === "complete") return "Complete";
+  return "Error";
+}
+
+/** The task prompt is shown separately; skip the matching human message. */
+function omitTaskHumanMessage(
+  messages: BaseMessage[],
+  taskInput?: string,
+): BaseMessage[] {
+  const task = taskInput?.trim();
+  if (!task) return messages;
+  return messages.filter(
+    (message) => message.type !== "human" || message.text?.trim() !== task,
+  );
+}
+
+/**
+ * Compact, clickable subagent cards showing only the name and task prompt.
+ * Rendered inline where the coordinator spawned the subagents. Selecting one
+ * drills into its dedicated chat view.
+ */
+export function SubagentList({
+  cards,
+  onOpen,
+}: {
+  cards: SubagentCard[];
+  onOpen: (id: string) => void;
+}) {
+  if (cards.length === 0) return null;
+
+  return (
+    <div aria-label="Subagents" className="subagent-list">
+      {cards.map((card) => (
+        <button
+          className="subagent-chip"
+          disabled={!card.openable}
+          key={card.id}
+          onClick={() => card.openable && onOpen(card.id)}
+          type="button"
+        >
+          <span className="subagent-chip-head">
+            <span className="subagent-chip-name">{card.name}</span>
+            <span className={`subagent-status status-${card.status}`}>
+              {statusLabel(card.status)}
+            </span>
+          </span>
+          {card.task ? (
+            <span className="subagent-chip-task">{card.task}</span>
+          ) : null}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * The chat interface for a single subagent.
+ *
+ * `useMessages` is scoped to the subagent's namespace, so its tokens, tool
+ * calls, and results stream independently from the root conversation.
+ */
+export function SubagentDetail({
+  snapshot,
+}: {
+  snapshot: SubagentDiscoverySnapshot;
+}) {
+  const stream = useStreamContext<Agent>();
+  const messages = useMessages(stream, snapshot);
+  const visibleMessages = useMemo(
+    () => omitTaskHumanMessage(messages, snapshot.taskInput),
+    [messages, snapshot.taskInput],
+  );
+
+  return (
+    <>
+      {snapshot.taskInput ? (
+        <div className="subagent-prompt">
+          <span>Task</span>
+          <p>{snapshot.taskInput}</p>
+        </div>
+      ) : null}
+
+      <MessageThread
+        isLoading={snapshot.status === "running"}
+        messages={visibleMessages}
+      />
+
+      {snapshot.status === "running" && visibleMessages.length === 0 ? (
+        <StreamingIndicator />
+      ) : null}
+    </>
+  );
+}

package/registry/frameworks/next/components/ThemeIcons.tsx

@@ -0,0 +1,31 @@
+export function SunIcon() {
+  return (
+    <svg
+      aria-hidden
+      fill="none"
+      stroke="currentColor"
+      strokeLinecap="round"
+      strokeWidth="1.5"
+      viewBox="0 0 24 24"
+    >
+      <circle cx="12" cy="12" r="4" />
+      <path d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M4.93 19.07l1.41-1.41M17.66 6.34l1.41-1.41" />
+    </svg>
+  );
+}
+
+export function MoonIcon() {
+  return (
+    <svg
+      aria-hidden
+      fill="none"
+      stroke="currentColor"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      strokeWidth="1.5"
+      viewBox="0 0 24 24"
+    >
+      <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
+    </svg>
+  );
+}

package/registry/frameworks/next/components/ThreadHistory.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+import type { ThreadSummary } from "@/lib/chat/threads-client";
+
+function formatTime(updatedAt: string | null) {
+  if (!updatedAt) return "";
+  const date = new Date(updatedAt);
+  if (Number.isNaN(date.getTime())) return "";
+  return date.toLocaleString(undefined, {
+    month: "short",
+    day: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+  });
+}
+
+export function ThreadHistory({
+  threads,
+  activeThreadId,
+  onSelect,
+  onCreate,
+  onDelete,
+}: {
+  threads: ThreadSummary[];
+  activeThreadId: string;
+  onSelect: (threadId: string) => void;
+  onCreate: () => void;
+  onDelete: (threadId: string) => void;
+}) {
+  return (
+    <aside aria-label="Thread history" className="sidebar">
+      <div className="sidebar-head">
+        <span className="eyebrow">History</span>
+        <button className="new-thread" onClick={onCreate} type="button">
+          + New
+        </button>
+      </div>
+
+      <ul className="thread-list">
+        {threads.length === 0 ? (
+          <li className="thread-empty">No conversations yet.</li>
+        ) : null}
+        {threads.map((thread) => (
+          <li
+            className={`thread-item ${
+              thread.id === activeThreadId ? "active" : ""
+            }`}
+            key={thread.id}
+          >
+            <button
+              className="thread-open"
+              onClick={() => onSelect(thread.id)}
+              type="button"
+            >
+              <span className="thread-title">{thread.title}</span>
+              <span className="thread-time">
+                {formatTime(thread.updatedAt)}
+              </span>
+            </button>
+            <button
+              aria-label="Delete conversation"
+              className="thread-delete"
+              onClick={() => onDelete(thread.id)}
+              type="button"
+            >
+              ×
+            </button>
+          </li>
+        ))}
+      </ul>
+    </aside>
+  );
+}

package/registry/frameworks/next/components/ToolCall.tsx

@@ -0,0 +1,89 @@
+"use client";
+
+import { useState } from "react";
+
+export type ToolCallStatus = "running" | "complete" | "error";
+
+export type ToolCallView = {
+  id: string;
+  name: string;
+  args: Record<string, unknown>;
+  output?: string;
+  status: ToolCallStatus;
+};
+
+function stringifyArgs(args: Record<string, unknown>) {
+  try {
+    return JSON.stringify(args, null, 2);
+  } catch {
+    return String(args);
+  }
+}
+
+function statusLabel(status: ToolCallStatus) {
+  if (status === "running") return "Running";
+  if (status === "error") return "Error";
+  return "Done";
+}
+
+function ToolIcon() {
+  return (
+    <svg
+      aria-hidden
+      fill="none"
+      stroke="currentColor"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      strokeWidth="1.6"
+      viewBox="0 0 24 24"
+    >
+      <path d="M14.7 6.3a4 4 0 0 1-5.4 5.4L4 17v3h3l5.3-5.3a4 4 0 0 1 5.4-5.4l-2.7 2.7-1.4-1.4 2.7-2.7a4 4 0 0 0-1.6.4z" />
+    </svg>
+  );
+}
+
+/**
+ * A subtle, collapsible representation of a single tool call: an icon, the
+ * tool name, and its status. Expanding reveals the stringified input (args)
+ * and output (the tool result).
+ */
+export function ToolCall({ call }: { call: ToolCallView }) {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div className={`toolcall status-${call.status}`}>
+      <button
+        aria-expanded={open}
+        className="toolcall-head"
+        onClick={() => setOpen((value) => !value)}
+        type="button"
+      >
+        <span className="toolcall-icon">
+          <ToolIcon />
+        </span>
+        <span className="toolcall-name">{call.name}</span>
+        <span className={`subagent-status status-${call.status}`}>
+          {statusLabel(call.status)}
+        </span>
+        <span aria-hidden className="toolcall-chevron">
+          {open ? "▾" : "▸"}
+        </span>
+      </button>
+
+      {open ? (
+        <div className="toolcall-body">
+          <div className="toolcall-section">
+            <span>Input</span>
+            <pre>{stringifyArgs(call.args)}</pre>
+          </div>
+          {call.output != null && call.output !== "" ? (
+            <div className="toolcall-section">
+              <span>Output</span>
+              <pre>{call.output}</pre>
+            </div>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/registry/frameworks/next/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

package/registry/frameworks/next/lib/agent/index.ts

@@ -0,0 +1,95 @@
+import "server-only";
+
+import { MemorySaver } from "@langchain/langgraph";
+import { ChatOpenAI } from "@langchain/openai";
+import { createDeepAgent } from "deepagents";
+
+import { stripReasoningReplay } from "./middleware";
+import { calculator, searchWeb } from "./tools";
+
+/**
+ * A "deep agent" coordinator with two subagents.
+ *
+ * `createDeepAgent` gives the coordinator a built-in `task` tool that it uses
+ * to delegate work to named subagents. Each delegated `task` call runs as a
+ * namespaced sub-run, so the Agent Streaming Protocol relays its `messages`
+ * and `tools` events under a subagent namespace. The `@langchain/react` SDK
+ * surfaces those as `stream.subagents`, which the UI renders in dedicated
+ * cards.
+ *
+ * A concrete `ChatOpenAI` instance is passed as the model (instead of a model
+ * string) so `langchain`'s string-based `initChatModel` lookup does not have to
+ * resolve `@langchain/openai` under the package manager's layout.
+ *
+ * Reasoning summaries are enabled on the coordinator: over the Responses API,
+ * OpenAI returns reasoning *summaries* (not raw chain-of-thought) as
+ * `{ type: "reasoning" }` standard content blocks. These stream through the
+ * `messages` channel and the UI renders them in a collapsible "Thinking"
+ * section.
+ *
+ * The tool-using subagents deliberately use a plain (non-Responses) model. The
+ * Responses API replays prior reasoning items by id on each tool-loop step, and
+ * deep-agent subagent history can surface those items with empty ids
+ * (`400 Invalid 'input[..].id': ''`). Keeping subagents on standard
+ * chat-completions tool calling avoids that, while the orchestrator — which
+ * only delegates via the `task` tool — keeps its reasoning summaries.
+ *
+ * The agent is compiled with an in-memory `MemorySaver` checkpointer so the
+ * backend can persist and rehydrate per-thread conversation state. Swap this
+ * for a durable checkpointer (Postgres, SQLite, …) before deploying — see the
+ * note in `lib/server/registry.ts`.
+ */
+const coordinatorModel = new ChatOpenAI({
+  model: "gpt-5.4-mini",
+  reasoning: { effort: "low", summary: "auto" },
+});
+
+const subagentModel = new ChatOpenAI({ model: "gpt-5.4-mini" });
+
+/**
+ * In-memory checkpointer — the single source of truth for threads.
+ *
+ * Exported so the server can enumerate threads (via `checkpointer.storage`) and
+ * delete them (`checkpointer.deleteThread`). It is process-local and volatile:
+ * restarting the server clears every thread.
+ */
+export const checkpointer = new MemorySaver();
+
+export const agent = createDeepAgent({
+  model: coordinatorModel,
+  middleware: [stripReasoningReplay],
+  checkpointer,
+  subagents: [
+    {
+      name: "researcher",
+      description:
+        "Researches a topic using the search_web tool and reports concise findings.",
+      tools: [searchWeb],
+      model: subagentModel,
+      systemPrompt:
+        "You are the researcher subagent. Use the search_web tool to look up " +
+        "the requested topic, then summarize the findings in two or three " +
+        "sentences. Always call search_web at least once before answering.",
+    },
+    {
+      name: "math-whiz",
+      description:
+        "Performs calculations using the calculator tool and explains the result.",
+      tools: [calculator],
+      model: subagentModel,
+      systemPrompt:
+        "You are the math-whiz subagent. Use the calculator tool to evaluate " +
+        "the requested expression, then state the result clearly. Always call " +
+        "the calculator tool before answering.",
+    },
+  ],
+  systemPrompt:
+    "You are a helpful coordinator. When a request involves looking something " +
+    "up, delegate it to the `researcher` subagent. When it involves math, " +
+    "delegate it to the `math-whiz` subagent. You may run both subagents for a " +
+    "single request. After the subagents respond, combine their results into a " +
+    "short, clearly labeled final answer.",
+});
+
+/** The compiled agent type, re-exported for `useStreamContext<typeof agent>()`. */
+export type Agent = typeof agent;

package/registry/frameworks/next/lib/agent/middleware.ts

@@ -0,0 +1,40 @@
+import "server-only";
+
+import { AIMessage, type BaseMessage } from "@langchain/core/messages";
+import { createMiddleware } from "langchain";
+
+/**
+ * Rebuild prior assistant messages so the Responses API doesn't replay stale
+ * item ids.
+ *
+ * Over the Responses API, `@langchain/openai` replays an assistant turn either
+ * from `response_metadata.output` (the raw response items) or by reconstructing
+ * items from `additional_kwargs` — both of which carry ids (reasoning items,
+ * function-call items). After a round-trip through the checkpointer those ids
+ * can come back empty, and OpenAI rejects the next call with
+ * `400 Invalid 'input[..].id': ''`.
+ *
+ * We rebuild each prior assistant message from just its `content` and
+ * `tool_calls`. Tool calls keep their `call_id` (the valid pairing key), the
+ * converter emits clean items with no stale ids, and reasoning items are
+ * dropped from the model *input*. State is untouched, so the UI still renders
+ * each turn's reasoning; the model simply produces fresh reasoning per turn and
+ * never receives the old items back.
+ */
+function sanitizeForReplay(message: BaseMessage): BaseMessage {
+  if (!AIMessage.isInstance(message)) return message;
+
+  return new AIMessage({
+    id: message.id,
+    content: message.content,
+    tool_calls: message.tool_calls,
+    invalid_tool_calls: message.invalid_tool_calls,
+    usage_metadata: message.usage_metadata,
+  });
+}
+
+export const stripReasoningReplay = createMiddleware({
+  name: "StripReasoningReplay",
+  wrapModelCall: async (request, handler) =>
+    handler({ ...request, messages: request.messages.map(sanitizeForReplay) }),
+});

package/registry/frameworks/next/lib/agent/tools.ts

@@ -0,0 +1,66 @@
+import "server-only";
+
+import { tool } from "langchain";
+import { z } from "zod";
+
+/**
+ * Mock tools used to demonstrate message and tool-call streaming.
+ *
+ * Both tools are intentionally fake so the example runs offline. What matters
+ * is that the agent (and its subagents) emit real tool-call deltas on the
+ * `messages` channel and tool results as `ToolMessage`s, which the UI renders.
+ */
+
+export const searchWeb = tool(
+  async ({ query }) => {
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    return JSON.stringify({
+      results: [
+        {
+          title: `Result for: ${query}`,
+          snippet:
+            "LangGraph streaming sends token deltas on the messages channel " +
+            "and tool lifecycle events on the tools channel.",
+        },
+      ],
+    });
+  },
+  {
+    name: "search_web",
+    description: "Search the web for information about a topic.",
+    schema: z.object({ query: z.string().describe("Search query.") }),
+  },
+);
+
+/** Demo-only arithmetic evaluator restricted to numbers and basic operators. */
+function evaluateExpression(expression: string): number {
+  if (!/^[\d+\-*/().\s]+$/.test(expression)) {
+    throw new Error("Only basic arithmetic is supported.");
+  }
+  const compute = new Function(
+    `"use strict"; return (${expression});`,
+  ) as () => unknown;
+  const result = compute();
+  if (typeof result !== "number" || !Number.isFinite(result)) {
+    throw new Error("Expression did not evaluate to a finite number.");
+  }
+  return result;
+}
+
+export const calculator = tool(
+  async ({ expression }) => {
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    try {
+      return String(evaluateExpression(expression));
+    } catch (error) {
+      return `Error evaluating: ${expression} (${String(error)})`;
+    }
+  },
+  {
+    name: "calculator",
+    description: "Evaluate a math expression.",
+    schema: z.object({
+      expression: z.string().describe("Math expression to evaluate."),
+    }),
+  },
+);

package/registry/frameworks/next/lib/chat/threads-client.ts

@@ -0,0 +1,57 @@
+/**
+ * Browser-side thread helpers.
+ *
+ * The server (the agent's in-memory checkpointer) is the single source of truth
+ * for threads. There is no client-side cache: the sidebar is always fetched
+ * from the API, and restarting the server clears every thread.
+ */
+
+import { Client } from "@langchain/langgraph-sdk/client";
+
+/** LangGraph SDK base URL. Route handlers live under `/api/threads/...`. */
+export function getApiUrl(): string {
+  return `${window.location.origin}/api`;
+}
+
+/** Summary of a thread for the history sidebar (mirrors the server type). */
+export type ThreadSummary = {
+  id: string;
+  title: string;
+  updatedAt: string | null;
+};
+
+/** Fetch every thread from the server, newest first. */
+export async function fetchThreads(): Promise<ThreadSummary[]> {
+  const response = await fetch(`${getApiUrl()}/threads`, { cache: "no-store" });
+  if (!response.ok) return [];
+  return (await response.json()) as ThreadSummary[];
+}
+
+/**
+ * Create the thread row server-side so hydration does not 404.
+ *
+ * Calls `GET /threads/:id/state` and, on 404, bootstraps with
+ * `POST /threads/:id/state` and empty `messages`.
+ */
+async function ensureThreadExists(threadId: string) {
+  const client = new Client({ apiUrl: getApiUrl() });
+  try {
+    await client.threads.getState(threadId);
+  } catch (error) {
+    const status = (error as { status?: number })?.status;
+    if (status !== 404) throw error;
+    await client.threads.updateState(threadId, { values: { messages: [] } });
+  }
+}
+
+/** Mint a new thread and bootstrap its checkpoint on the server. */
+export async function createThread(): Promise<string> {
+  const id = crypto.randomUUID();
+  await ensureThreadExists(id);
+  return id;
+}
+
+/** Delete a thread (session + checkpointed state) on the server. */
+export async function deleteThread(threadId: string): Promise<void> {
+  await fetch(`${getApiUrl()}/threads/${threadId}`, { method: "DELETE" });
+}

package/registry/frameworks/next/lib/server/registry.ts

@@ -0,0 +1,57 @@
+import "server-only";
+
+import { agent, checkpointer } from "@/lib/agent";
+import { LocalThreadSession } from "./session";
+
+/**
+ * Process-local registry for the agent and its per-thread sessions.
+ *
+ * Next.js route handlers are stateless per request, and the dev server
+ * re-evaluates modules on hot reload. Stashing the agent and the session map on
+ * `globalThis` keeps a single agent instance (and therefore a single
+ * `MemorySaver` checkpointer) alive across requests and reloads, so a thread's
+ * conversation state survives between the `/state`, `/commands`, and `/stream`
+ * calls that make up one turn.
+ *
+ * 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 `lib/agent/index.ts` and this store change.
+ */
+type Registry = {
+  sessions: Map<string, LocalThreadSession>;
+};
+
+const globalForRegistry = globalThis as unknown as {
+  __agentRegistry?: Registry;
+};
+
+const registry: Registry = (globalForRegistry.__agentRegistry ??= {
+  sessions: new Map(),
+});
+
+/** 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 = registry.sessions.get(threadId);
+  if (session == null) {
+    session = new LocalThreadSession(agent, threadId);
+    registry.sessions.set(threadId, session);
+  }
+  return session;
+}
+
+/** Delete a thread: remove its session and its checkpointed state. */
+export async function deleteThread(threadId: string): Promise<void> {
+  registry.sessions.delete(threadId);
+  await checkpointer.deleteThread(threadId);
+}

package/registry/frameworks/next/lib/server/serialize.ts

@@ -0,0 +1,32 @@
+import "server-only";
+
+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;
+}