fix(vercel): Add queue consumer source (#501)

Add a concrete Vercel queue consumer source for durable conversation
work so Vercel's `functions` entry matches an actual root `api/` file
during deployment validation. The source delegates to `server.ts`,
keeping queue delivery on the same Junior app wiring as the rest of the
runtime.

**Scaffold Contract**

`junior init` now writes the queue consumer source alongside
`vercel.json`, and the example app has a test that the trigger points to
a concrete file and routes through the app. The deploy guide now calls
out both the heartbeat cron and queue trigger entries.

Validated with targeted Junior tests, docs checks, the example Nitro
build with snapshot warmup skipped, and the example app typecheck.

Co-authored-by: GPT-5 Codex <codex@openai.com>

Author: dcramer

apps/example/api/internal/agent/continue.ts

@@ -0,0 +1,3 @@
+import app from "../../../server.ts";
+
+export const POST = (request: Request) => app.fetch(request);

packages/docs/src/content/docs/start-here/deploy-to-vercel.md

@@ -41,9 +41,9 @@ The scaffolded `package.json` includes the production build script:
 
 Keep the Vercel build command as `pnpm build`. `junior snapshot create` prepares sandbox runtime dependencies declared by enabled plugins before request handling starts.
 
-## Enable the heartbeat cron
+## Keep Vercel runtime entries
 
-Junior uses a one-minute internal heartbeat to run trusted plugin heartbeats and recover stale agent dispatches. The scheduler plugin uses this heartbeat when scheduled tasks are enabled. The scaffolded `vercel.json` should include this cron:
+Junior uses a one-minute internal heartbeat to run trusted plugin heartbeats and recover stale agent dispatches. The scheduler plugin uses this heartbeat when scheduled tasks are enabled. The scaffolded `vercel.json` should include these runtime entries:
 
 ```json title="vercel.json"
 {
@@ -54,11 +54,24 @@ Junior uses a one-minute internal heartbeat to run trusted plugin heartbeats and
       "path": "/api/internal/heartbeat",
       "schedule": "* * * * *"
     }
-  ]
+  ],
+  "functions": {
+    "api/internal/agent/continue.ts": {
+      "maxDuration": 300,
+      "experimentalTriggers": [
+        {
+          "type": "queue/v2beta",
+          "topic": "junior_conversation_work"
+        }
+      ]
+    }
+  }
 }
 ```
 
-If you maintain `vercel.json` manually, keep the `/api/internal/heartbeat` cron entry. The endpoint returns `401` unless the incoming Vercel Cron request has a bearer token that matches `CRON_SECRET`.
+If you maintain `vercel.json` manually, keep the `/api/internal/heartbeat` cron entry and the queue trigger for `api/internal/agent/continue.ts`. The scaffolded `api/internal/agent/continue.ts` file delegates queue delivery to `server.ts`, and Vercel requires the `functions` key to match a concrete source file.
+
+The heartbeat endpoint returns `401` unless the incoming Vercel Cron request has a bearer token that matches `CRON_SECRET`.
 
 ## Configure production environment
 

packages/docs/src/content/docs/start-here/quickstart.md

@@ -32,7 +32,7 @@ cd my-bot
 pnpm install
 ```
 
-`junior init` creates the app entrypoint, Nitro/Vite config, Vercel config, CI workflow, app context files, local plugin and skill directories, and `.env.example`.
+`junior init` creates the app entrypoint, Nitro/Vite config, Vercel config, Vercel queue consumer source, CI workflow, app context files, local plugin and skill directories, and `.env.example`.
 
 The generated `app/` files have separate jobs:
 

packages/junior/src/cli/init.ts

@@ -17,6 +17,18 @@ export default app;
   );
 }
 
+function writeQueueConsumerEntry(targetDir: string): void {
+  const queueConsumerDir = path.join(targetDir, "api", "internal", "agent");
+  fs.mkdirSync(queueConsumerDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(queueConsumerDir, "continue.ts"),
+    `import app from "../../../server.ts";
+
+export const POST = (request: Request) => app.fetch(request);
+`,
+  );
+}
+
 function writeNitroConfig(targetDir: string): void {
   fs.writeFileSync(
     path.join(targetDir, "nitro.config.ts"),
@@ -188,6 +200,7 @@ SENTRY_ORG_SLUG=
   );
 
   writeServerEntry(target);
+  writeQueueConsumerEntry(target);
   writeNitroConfig(target);
   writeViteConfig(target);
   writeVercelJson(target);

packages/junior/tests/integration/example-build-discovery.test.ts

@@ -10,6 +10,10 @@ const originalCwd = process.cwd();
 const repoRoot = path.resolve(import.meta.dirname, "../../../..");
 const exampleRoot = path.join(repoRoot, "apps/example");
 const exampleEntry = path.join(exampleRoot, "server.ts");
+const exampleQueueConsumerEntry = path.join(
+  exampleRoot,
+  "api/internal/agent/continue.ts",
+);
 const examplePluginsModule = path.join(exampleRoot, "plugins.ts");
 const exampleDashboardConfig = path.join(exampleRoot, "dashboard.ts");
 const exampleRequire = createRequire(exampleEntry);
@@ -82,6 +86,13 @@ async function importExampleApp() {
   };
 }
 
+async function importExampleQueueConsumer() {
+  const href = `${pathToFileURL(exampleQueueConsumerEntry).href}?t=${Date.now()}`;
+  return (await import(href)) as {
+    POST: (request: Request) => Promise<Response>;
+  };
+}
+
 async function importExampleDashboardConfig() {
   const href = `${pathToFileURL(exampleDashboardConfig).href}?t=${Date.now()}`;
   return (await import(href)) as {
@@ -152,6 +163,27 @@ describe.sequential("example build discovery integration", () => {
     expect(await oauth.text()).toContain("missing required parameters");
   }, 15_000);
 
+  it("routes the concrete Vercel queue consumer source through the app", async () => {
+    process.chdir(exampleRoot);
+    process.env.JUNIOR_PLUGIN_PACKAGES = JSON.stringify(
+      await getExamplePluginPackages(),
+    );
+
+    const { POST } = await importExampleQueueConsumer();
+    const response = await POST(
+      new Request("http://localhost/api/internal/agent/continue", {
+        method: "POST",
+        body: "{}",
+        headers: {
+          "content-type": "application/json",
+        },
+      }),
+    );
+
+    expect(response.status).toBe(400);
+    expect(await response.text()).toContain("Invalid content type");
+  }, 15_000);
+
   it("does not expose discovery state from the public example app", async () => {
     const packageNames = await getExamplePluginPackages();
     process.chdir(exampleRoot);

packages/junior/tests/unit/cli/init-cli.test.ts

@@ -26,6 +26,11 @@ describe("init cli", () => {
 
     expect(fs.existsSync(path.join(target, "package.json"))).toBe(true);
     expect(fs.existsSync(path.join(target, "server.ts"))).toBe(true);
+    expect(
+      fs.existsSync(
+        path.join(target, "api", "internal", "agent", "continue.ts"),
+      ),
+    ).toBe(true);
     expect(fs.existsSync(path.join(target, "vercel.json"))).toBe(true);
     expect(fs.existsSync(path.join(target, "nitro.config.ts"))).toBe(true);
     expect(fs.existsSync(path.join(target, "vite.config.ts"))).toBe(true);

packages/junior/tests/unit/vercel.test.ts

@@ -50,6 +50,17 @@ describe("juniorVercelConfig", () => {
 
     expect(config).toEqual(juniorVercelConfig());
   });
+
+  it("keeps the example queue trigger pointed at a concrete function source", () => {
+    const config = juniorVercelConfig();
+    const functionSources = Object.keys(config.functions as object);
+
+    for (const source of functionSources) {
+      expect(
+        fs.existsSync(path.join(WORKSPACE_ROOT, "apps/example", source)),
+      ).toBe(true);
+    }
+  });
 });
 
 describe("resolveConversationWorkVisibilityTimeoutSeconds", () => {