create-langgraph-app 1.5.0 → 1.5.2

package/README.md

@@ -2,8 +2,6 @@
 
 Interactive CLI to scaffold a new LangGraph multi-agent project in seconds.
 
-## Usage
-
 ```bash
 npx create-langgraph-app
 ```
@@ -11,28 +9,68 @@ npx create-langgraph-app
 ## What it does
 
 1. Asks for your project name
-2. Lets you pick an LLM provider (OpenAI, Anthropic, Google, Groq, DeepSeek, Ollama)
+2. Lets you pick an LLM provider — OpenAI, Anthropic, Google, Groq, DeepSeek, or Ollama
 3. Lets you select which agent patterns to include:
-   - **Supervisor** — central coordinator + worker agents
+   - **Supervisor** — central coordinator delegating to worker agents
    - **Swarm** — peer-to-peer agent handoffs
    - **Human-in-the-Loop** — approval before dangerous actions
-   - **Structured Output** — typed JSON responses
-   - **RAG** — retrieval-augmented generation
-4. Generates a ready-to-run project with only the patterns you selected
+   - **Structured Output** — typed JSON responses validated by Zod
+   - **RAG** — retrieval-augmented generation over an in-memory vector store
+4. Generates a ready-to-run project containing only the patterns you picked
 5. Installs dependencies
 
+## What you get
+
+```
+src/
+├── config/      env validation, LLM factory, embeddings (with RAG)
+├── agents/      makeAgent() and the helpers your patterns need
+├── apps/        one file per selected pattern
+├── tools/       retrieval tool + vector store (with RAG)
+├── server.ts    Fastify server — invoke, stream, resume, threads
+└── index.ts     CLI demo running each pattern
+tests/           offline tests that need no API key
+```
+
+Everything is built on LangChain's `createAgent` — the **subagents** pattern for
+supervisors, **handoffs** for swarms. No deprecated packages.
+
+## RAG and embeddings
+
+Selecting RAG generates a working implementation: chunking, embedding,
+cosine-similarity search, and a retrieval tool the agent calls before answering.
+Swap `SAMPLE_DOCS` in `src/tools/rag.ts` for your own documents.
+
+Embeddings are a separate capability from chat. OpenAI, Google and Ollama have
+their own; **Anthropic, Groq and DeepSeek do not**, so those projects use OpenAI
+embeddings and need `OPENAI_API_KEY` in addition to the chat provider's key. The
+generated `.env` says so, and `EMBEDDINGS_MODEL` overrides the model.
+
+To run RAG with no API key at all, scaffold with Ollama.
+
+If embeddings are unavailable, only RAG is affected — the other patterns and
+routes keep working, and the server logs why `/rag` is disabled.
+
 ## Development
 
 ```bash
 cd create-langgraph-app
 npm install
-npm run dev  # Run locally
+npm run dev      # run the CLI locally
+npm run build    # typecheck and emit dist/
 ```
 
-## Publishing
+Generated projects are compiled in CI, so a change that breaks the output fails
+the build. See `tests/scaffolder/` in the [starter kit](https://github.com/ac12644/langgraph-starter-kit).
+
+## Releasing
+
+Publishing is automated. Bump the version in `package.json`, then push a
+matching `cli-v*` tag:
 
 ```bash
-cd create-langgraph-app
-npm run build
-npm publish
+git tag -a cli-v1.5.0 -m "create-langgraph-app v1.5.0"
+git push origin cli-v1.5.0
 ```
+
+The `Publish CLI to npm` workflow builds and publishes with provenance.

package/dist/create.js

@@ -477,27 +477,54 @@ ${imports}
 interface AppGraph {
   invoke(input: unknown, config?: unknown): Promise<{ messages: BaseMessage[] } & Record<string, unknown>>;
   stream(input: unknown, config?: unknown): Promise<AsyncIterable<[unknown, { langgraph_node?: string } | undefined]>>;
-  getState(config: unknown): Promise<{ values?: unknown; next?: string[]; tasks?: unknown[] } | undefined>;
+  getState(config: unknown): Promise<ThreadState | undefined>;
+}
+interface ThreadState {
+  values?: unknown;
+  next?: string[];
+  tasks?: { interrupts?: { value?: unknown }[] }[];
+  createdAt?: string | null;
 }
 const asApp = (g: unknown) => g as AppGraph;
 
+/** What each pending interrupt() was given. Empty when the thread isn't paused. */
+function pendingInterrupts(state: ThreadState | undefined): unknown[] {
+  return (state?.tasks ?? []).flatMap((t) => t.interrupts ?? []).map((i) => i.value);
+}
+
 function httpError(status: number, message: string) {
   return Object.assign(new Error(message), { statusCode: status });
 }
 
+// \`system\` is excluded: the app owns its system prompt, and accepting one
+// from the request lets any caller override it.
+const CLIENT_ROLES = ["user", "assistant"];
+
 /** Reject malformed bodies before they reach the agent. */
 function validateMessages(raw: unknown): { role: string; content: string }[] {
-  if (raw === undefined) return [];
   if (!Array.isArray(raw)) throw httpError(400, '"messages" must be an array');
+  if (raw.length === 0) throw httpError(400, '"messages" must not be empty');
   return raw.map((m, i) => {
     const { role, content } = (m ?? {}) as Record<string, unknown>;
     if (typeof role !== "string" || typeof content !== "string") {
       throw httpError(400, \`messages[\${i}] needs string "role" and "content"\`);
     }
+    if (!CLIENT_ROLES.includes(role)) {
+      throw httpError(400, \`messages[\${i}].role must be one of: \${CLIENT_ROLES.join(", ")}\`);
+    }
     return { role, content };
   });
 }
 
+/** Defaults to "default"; anything but a non-empty string is a 400, not a 500. */
+function validateThreadId(raw: unknown): string {
+  if (raw === undefined) return "default";
+  if (typeof raw !== "string" || raw.trim() === "") {
+    throw httpError(400, '"thread_id" must be a non-empty string');
+  }
+  return raw;
+}
+
 const server = fastify({ logger: false });
 
 server.setErrorHandler(async (error: FastifyError, _req: FastifyRequest, reply: FastifyReply) => {
@@ -516,43 +543,64 @@ ${entries}${ragEntry}
     return app;
   };
 
+  // A thread that never ran still has a snapshot (values: {}); a checkpoint
+  // (createdAt) is what says it exists.
+  const getThread = async (app: AppGraph, thread_id: string) => {
+    const state = await app.getState({ configurable: { thread_id } });
+    if (!state?.createdAt) throw httpError(404, \`Thread "\${thread_id}" not found\`);
+    return state;
+  };
+
   server.post<{ Params: { app: string } }>("/:app/invoke", async (req, reply) => {
     const app = getApp(req.params.app);
-    const body = (req.body ?? {}) as { messages?: unknown; thread_id?: string };
+    const body = (req.body ?? {}) as { messages?: unknown; thread_id?: unknown };
     const messages = validateMessages(body.messages);
-    const thread_id = body.thread_id ?? "default";
+    const thread_id = validateThreadId(body.thread_id);
 
-    const result = await app.invoke({ messages }, { configurable: { thread_id } });
+    const config = { configurable: { thread_id } };
+    const result = await app.invoke({ messages }, config);
     const last = result.messages.at(-1);
     return reply.send({
       messages: result.messages,
       structuredResponse: (result as Record<string, unknown>).structuredResponse ?? null,
       lastMessage: typeof last?.content === "string" ? last.content : JSON.stringify(last?.content),
+      // Non-empty = paused for approval; answer via POST /:app/resume.
+      interrupts: pendingInterrupts(await app.getState(config)),
     });
   });
 
   server.post<{ Params: { app: string } }>("/:app/stream", async (req, reply) => {
     const app = getApp(req.params.app);
-    const body = (req.body ?? {}) as { messages?: unknown; thread_id?: string };
+    const body = (req.body ?? {}) as { messages?: unknown; thread_id?: unknown };
     const messages = validateMessages(body.messages);
-    const thread_id = body.thread_id ?? "default";
+    const thread_id = validateThreadId(body.thread_id);
 
     reply.raw.writeHead(200, {
       "Content-Type": "text/event-stream",
       "Cache-Control": "no-cache",
       Connection: "keep-alive",
     });
-    const send = (e: unknown) => reply.raw.write(\`data: \${JSON.stringify(e)}\\n\\n\`);
+    const controller = new AbortController();
+    reply.raw.on("close", () => {
+      if (!reply.raw.writableFinished) controller.abort();
+    });
+    const send = (e: unknown) => {
+      if (controller.signal.aborted) return;
+      reply.raw.write(\`data: \${JSON.stringify(e)}\\n\\n\`);
+    };
 
     try {
-      const stream = await app.stream({ messages }, { configurable: { thread_id }, streamMode: "messages" });
+      const stream = await app.stream({ messages }, { configurable: { thread_id }, streamMode: "messages", signal: controller.signal });
       for await (const [chunk, metadata] of stream) {
         if (chunk instanceof AIMessageChunk) {
           send({ type: "token", content: chunk.content, node: metadata?.langgraph_node ?? "unknown" });
         }
       }
+      const interrupts = pendingInterrupts(await app.getState({ configurable: { thread_id } }));
+      if (interrupts.length > 0) send({ type: "interrupt", content: interrupts });
       send({ type: "done" });
     } catch (err) {
+      if (controller.signal.aborted) return;
       send({ type: "error", content: err instanceof Error ? err.message : "Stream failed" });
     } finally {
       reply.raw.end();
@@ -561,24 +609,29 @@ ${entries}${ragEntry}
 
   server.post<{ Params: { app: string } }>("/:app/resume", async (req, reply) => {
     const app = getApp(req.params.app);
-    const body = (req.body ?? {}) as { thread_id?: string; decision?: string };
-    if (body.decision === undefined) {
-      return reply.status(400).send({ error: '"decision" field is required' });
+    const body = (req.body ?? {}) as { thread_id?: unknown; decision?: unknown };
+    const thread_id = validateThreadId(body.thread_id);
+    if (typeof body.decision !== "string") throw httpError(400, '"decision" must be a string');
+
+    // Resuming a thread that isn't paused is a silent no-op — refuse it so an
+    // approval UI can't report "approved" for something that never waited.
+    if (pendingInterrupts(await getThread(app, thread_id)).length === 0) {
+      throw httpError(409, \`Thread "\${thread_id}" is not waiting for a decision\`);
     }
-    const result = await app.invoke(new Command({ resume: body.decision }), {
-      configurable: { thread_id: body.thread_id ?? "default" },
-    });
+
+    const config = { configurable: { thread_id } };
+    const result = await app.invoke(new Command({ resume: body.decision }), config);
     const last = result.messages.at(-1);
     return reply.send({
       messages: result.messages,
       lastMessage: typeof last?.content === "string" ? last.content : JSON.stringify(last?.content),
+      // A resumed run can pause again (e.g. a second approval).
+      interrupts: pendingInterrupts(await app.getState(config)),
     });
   });
 
   server.get<{ Params: { app: string; threadId: string } }>("/:app/threads/:threadId", async (req, reply) => {
-    const app = getApp(req.params.app);
-    const state = await app.getState({ configurable: { thread_id: req.params.threadId } });
-    if (!state?.values) return reply.status(404).send({ error: "Thread not found" });
+    const state = await getThread(getApp(req.params.app), req.params.threadId);
     return reply.send({ values: state.values, next: state.next ?? [], tasks: state.tasks ?? [] });
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-langgraph-app",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Scaffold a new LangGraph multi-agent project in seconds",
   "type": "module",
   "bin": {