Merge branch 'main' into fix(webapp)-bug-with-task-search

Author: samejr

.github/workflows/publish-docs.yml

@@ -0,0 +1,36 @@
+name: 📚 Publish docs
+
+on:
+  push:
+    tags:
+      - "docs-release-*"
+
+# Only needs to move the docs-live ref; Mintlify's GitHub app deploys from it.
+permissions:
+  contents: write
+
+concurrency:
+  group: publish-docs
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 📥 Checkout tagged commit
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: 🔗 Check for broken links
+        working-directory: ./docs
+        run: npx mintlify@4.0.393 broken-links
+
+      - name: 🚀 Fast-forward docs-live to the tagged commit
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh api -X PATCH \
+            "repos/${{ github.repository }}/git/refs/heads/docs-live" \
+            -f sha="${{ github.sha }}" \
+            -F force=false

.server-changes/vercel-sync-reserved-env-vars.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: fix
+---
+
+Fix Vercel env var sync and onboarding preview leaking reserved `TRIGGER_*` keys.

apps/webapp/app/models/vercelIntegration.server.ts

@@ -27,6 +27,7 @@ import {
   envTypeToVercelTarget,
 } from "~/v3/vercel/vercelProjectIntegrationSchema";
 import { EnvironmentVariablesRepository } from "~/v3/environmentVariables/environmentVariablesRepository.server";
+import { isReservedForExternalSync } from "~/v3/environmentVariableRules.server";
 import {
   callVercelWithRecovery,
   wrapVercelCallWithRecovery,
@@ -1350,10 +1351,9 @@ export class VercelIntegrationRepository {
           for (const mapping of envMapping) {
             const iterResult = await ResultAsync.fromPromise(
               (async () => {
-                // Build filter to avoid decrypting vars that will be filtered out anyway
-                const excludeKeys = new Set(["TRIGGER_SECRET_KEY", "TRIGGER_VERSION"]);
+                // Exclude reserved keys before decrypting (a reserved-only batch gets rejected).
                 const shouldIncludeKey = (key: string) =>
-                  !excludeKeys.has(key) &&
+                  !isReservedForExternalSync(key) &&
                   shouldSyncEnvVar(params.syncEnvVarsMapping, key, mapping.triggerEnvType as TriggerEnvironmentType);
 
                 const envVarsResult = await this.getVercelEnvironmentVariableValues(
@@ -1399,7 +1399,7 @@ export class VercelIntegrationRepository {
                   if (envVar.isSecret) {
                     return false;
                   }
-                  if (envVar.key === "TRIGGER_SECRET_KEY" || envVar.key === "TRIGGER_VERSION") {
+                  if (isReservedForExternalSync(envVar.key)) {
                     return false;
                   }
                   return shouldSyncEnvVar(

apps/webapp/app/presenters/v3/VercelSettingsPresenter.server.ts

@@ -10,6 +10,7 @@ import {
 } from "~/models/vercelIntegration.server";
 import { type GitHubAppInstallation } from "~/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.github";
 import { EnvironmentVariablesRepository } from "~/v3/environmentVariables/environmentVariablesRepository.server";
+import { isReservedForExternalSync } from "~/v3/environmentVariableRules.server";
 import {
   VercelProjectIntegrationDataSchema,
   VercelProjectIntegrationData,
@@ -567,12 +568,11 @@ export class VercelSettingsPresenter extends BasePresenter {
         const projectEnvVars = projectEnvVarsResult.isOk() ? projectEnvVarsResult.value : [];
         const sharedEnvVars = sharedEnvVarsResult.isOk() ? sharedEnvVarsResult.value : [];
 
-        // Filter out TRIGGER_SECRET_KEY and TRIGGER_VERSION (managed by Trigger.dev) and merge project + shared env vars
-        const excludedKeys = new Set(["TRIGGER_SECRET_KEY", "TRIGGER_VERSION"]);
+        // Hide platform-managed reserved keys from the onboarding preview.
         const projectEnvVarKeys = new Set(projectEnvVars.map((v) => v.key));
         const mergedEnvVars: VercelEnvironmentVariable[] = [
           ...projectEnvVars
-            .filter((v) => !excludedKeys.has(v.key))
+            .filter((v) => !isReservedForExternalSync(v.key))
             .map((v) => {
               const envVar = { ...v };
               if (vercelEnvironmentId && (v as any).customEnvironmentIds?.includes(vercelEnvironmentId)) {
@@ -581,7 +581,7 @@ export class VercelSettingsPresenter extends BasePresenter {
               return envVar;
             }),
           ...sharedEnvVars
-            .filter((v) => !projectEnvVarKeys.has(v.key) && !excludedKeys.has(v.key))
+            .filter((v) => !projectEnvVarKeys.has(v.key) && !isReservedForExternalSync(v.key))
             .map((v) => {
               const envVar = {
                 id: v.id,

apps/webapp/app/v3/environmentVariableRules.server.ts

@@ -10,29 +10,37 @@ const blacklistedVariables: VariableRule[] = [
   { type: "exact", key: "TRIGGER_API_URL" },
 ];
 
+const additionalExternalSyncReservedKeys = ["TRIGGER_VERSION", "TRIGGER_PREVIEW_BRANCH"];
+
+export function isBlacklistedVariable(key: string): boolean {
+  const whitelisted = blacklistedVariables.find((bv) => bv.type === "whitelist" && bv.key === key);
+  if (whitelisted) {
+    return false;
+  }
+
+  const exact = blacklistedVariables.find((bv) => bv.type === "exact" && bv.key === key);
+  if (exact) {
+    return true;
+  }
+
+  const prefix = blacklistedVariables.find(
+    (bv) => bv.type === "prefix" && key.startsWith(bv.prefix)
+  );
+  if (prefix) {
+    return true;
+  }
+
+  return false;
+}
+
+// Keys that must never be synced from an external integration (e.g. Vercel). Superset of
+// the repository blacklist so submitting a reserved key doesn't get the whole batch rejected.
+export function isReservedForExternalSync(key: string): boolean {
+  return isBlacklistedVariable(key) || additionalExternalSyncReservedKeys.includes(key);
+}
+
 export function removeBlacklistedVariables(
   variables: EnvironmentVariable[]
 ): EnvironmentVariable[] {
-  return variables.filter((v) => {
-    const whitelisted = blacklistedVariables.find(
-      (bv) => bv.type === "whitelist" && bv.key === v.key
-    );
-    if (whitelisted) {
-      return true;
-    }
-
-    const exact = blacklistedVariables.find((bv) => bv.type === "exact" && bv.key === v.key);
-    if (exact) {
-      return false;
-    }
-
-    const prefix = blacklistedVariables.find(
-      (bv) => bv.type === "prefix" && v.key.startsWith(bv.prefix)
-    );
-    if (prefix) {
-      return false;
-    }
-
-    return true;
-  });
+  return variables.filter((v) => !isBlacklistedVariable(v.key));
 }

apps/webapp/test/environmentVariableRules.test.ts

@@ -1,6 +1,10 @@
 import { describe, it, expect } from "vitest";
 import type { EnvironmentVariable } from "../app/v3/environmentVariables/repository";
-import { removeBlacklistedVariables } from "~/v3/environmentVariableRules.server";
+import {
+  isBlacklistedVariable,
+  isReservedForExternalSync,
+  removeBlacklistedVariables,
+} from "~/v3/environmentVariableRules.server";
 
 describe("removeBlacklistedVariables", () => {
   it("should remove exact match blacklisted variables", () => {
@@ -68,3 +72,32 @@ describe("removeBlacklistedVariables", () => {
     ]);
   });
 });
+
+describe("isBlacklistedVariable", () => {
+  it("blacklists the platform-managed keys", () => {
+    expect(isBlacklistedVariable("TRIGGER_SECRET_KEY")).toBe(true);
+    expect(isBlacklistedVariable("TRIGGER_API_URL")).toBe(true);
+  });
+
+  it("allows ordinary user keys", () => {
+    expect(isBlacklistedVariable("DATABASE_URL")).toBe(false);
+    expect(isBlacklistedVariable("MY_API_KEY")).toBe(false);
+  });
+});
+
+describe("isReservedForExternalSync", () => {
+  it("reserves every key the repository would reject", () => {
+    expect(isReservedForExternalSync("TRIGGER_SECRET_KEY")).toBe(true);
+    expect(isReservedForExternalSync("TRIGGER_API_URL")).toBe(true);
+  });
+
+  it("reserves deploy-managed keys that are not blacklisted", () => {
+    expect(isReservedForExternalSync("TRIGGER_VERSION")).toBe(true);
+    expect(isReservedForExternalSync("TRIGGER_PREVIEW_BRANCH")).toBe(true);
+  });
+
+  it("does not reserve ordinary user keys", () => {
+    expect(isReservedForExternalSync("DATABASE_URL")).toBe(false);
+    expect(isReservedForExternalSync("MY_API_KEY")).toBe(false);
+  });
+});

docs/ai-chat/custom-agents.mdx

@@ -114,10 +114,11 @@ Each turn yielded by the iterator provides:
 | `continuation`      | `boolean`                         | Whether this is a continuation run                       |
 | `previousTurnUsage` | `LanguageModelUsage \| undefined` | Token usage from the previous turn (undefined on turn 0) |
 | `totalUsage`        | `LanguageModelUsage`              | Cumulative token usage across all completed turns        |
+| `handover`          | `{ isFinal: boolean } \| null`    | The [`chat.headStart`](/ai-chat/fast-starts#handover-with-custom-agents) handover for this turn (turn 0 only); `null` otherwise |
 
 | Method                        | Description                                                                                                |
 | ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `turn.complete(source)`       | Pipe stream, capture response, accumulate, and signal turn-complete                                        |
+| `turn.complete(source?)`      | Pipe stream, capture response, accumulate, and signal turn-complete. Call with no source on a final head-start handover (`turn.handover.isFinal`), where the warm step-1 partial is already the response |
 | `turn.done()`                 | Signal turn-complete only (when you have piped manually)                                                     |
 | `turn.addResponse(response)`  | Add a response to the accumulator manually                                                                 |
 | `turn.setMessages(uiMessages)`| Replace the accumulated messages — continuation seeding and on-demand compaction                           |

docs/ai-chat/fast-starts.mdx

@@ -108,7 +108,7 @@ if (payload.trigger === "preload") {
 
 ## Head Start
 
-Head Start runs step 1's LLM call in your warm server process while the chat.agent run boots in parallel. The user sees one continuous turn: text first from your server, then a clean handover to the agent for tool execution and any further steps.
+Head Start runs step 1's LLM call in your warm server process while the agent run boots in parallel. The user sees one continuous turn: text first from your server, then a clean handover to the agent for tool execution and any further steps. The agent you hand off to can be a `chat.agent`, a `chat.customAgent`, or a `chat.createSession` loop (see [Handover with custom agents](#handover-with-custom-agents)).
 
 `chat.headStart` returns a standard [Web Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) handler — `(req: Request) => Promise<Response>` — so it slots into any runtime that speaks Web Fetch.
 
@@ -545,16 +545,86 @@ Head Start composes with [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemes
 
 Your hydrate hook shapes **model context**, not the transcript — dropping reasoning-only entries or unresolved tool rows from the returned chain is fine and does not affect what `onTurnComplete` persists or what the UI renders.
 
+### Handover with custom agents
+
+The route handler is backend-agnostic: `agentId` can point at a `chat.agent`, a [`chat.customAgent`](/ai-chat/custom-agents), or a [`chat.createSession`](/ai-chat/custom-agents#managed-loop-chatcreatesession) loop. With `chat.agent` the handover is consumed for you (the steps above). The two hand-rolled backends consume it explicitly on turn 0.
+
+#### chat.createSession
+
+The turn iterator surfaces the handover as `turn.handover`. On a final (pure-text) handover, call `turn.complete()` with no source to finalize the warm partial without streaming; otherwise stream as usual. The iterator threads the spliced partial as `originalMessages` for you, so a resumed tool round merges into the handed-over assistant.
+
+```ts trigger/chat.ts
+for await (const turn of session) {
+  // Pure-text handover (isFinal): step 1 already IS the response.
+  const result = turn.handover?.isFinal
+    ? undefined
+    : streamText({
+        model: anthropic("claude-sonnet-4-6"),
+        messages: turn.messages,
+        abortSignal: turn.signal,
+        stopWhen: stepCountIs(10),
+      });
+
+  await turn.complete(result); // no source on a final handover
+}
+```
+
+#### chat.customAgent
+
+In a hand-rolled loop, call `conversation.consumeHandover({ payload })` at the top of turn 0. It waits for the handover signal, seeds prior history from `payload.headStartMessages`, splices the warm step-1 partial into the accumulator, and returns `{ isFinal, skipped }`.
+
+```ts trigger/chat.ts
+// Turn 0, gated on a head-start run:
+if (turn === 0 && payload.trigger === "handover-prepare") {
+  const { isFinal, skipped } = await conversation.consumeHandover({ payload });
+  if (skipped) return; // not a head-start run, or the warm handler aborted — exit
+  if (!isFinal) {
+    // The partial carries a pending tool call. Run step 2 to execute it,
+    // passing originalMessages so the tool output merges into the
+    // handed-over assistant instead of starting a new message.
+    const result = streamText({
+      model: anthropic("claude-sonnet-4-6"),
+      messages: conversation.modelMessages,
+      stopWhen: stepCountIs(10),
+    });
+    const response = await chat.pipeAndCapture(result, {
+      originalMessages: conversation.uiMessages,
+    });
+    if (response) await conversation.addResponse(response);
+  }
+  await chat.writeTurnComplete(); // on isFinal the warm partial is already the response
+  return;
+}
+```
+
+Gate the call on `trigger === "handover-prepare"` — `consumeHandover` consumes the warm handover, not a normal first message. See [Custom agents](/ai-chat/custom-agents) for the full loop (continuation seeding, stop handling, persistence). The lower-level `chat.waitForHandover({ payload })` and `accumulator.applyHandover(signal)` are exported if you need to wait and splice in separate steps.
+
+<Note>
+  Always pass `originalMessages: conversation.uiMessages` to `pipeAndCapture` in a custom loop. It keeps assistant message IDs stable across turns and lets a tool-approval or handover resume merge into the trailing assistant — the same threading `chat.agent` does internally.
+</Note>
+
 ### The `chat.headStart` API
 
 ```ts
 chat.headStart<TTools>({
-  agentId: string,                       // The chat.agent({ id }) you're handing off to
+  agentId: string,                       // The chat.agent / chat.customAgent id you're handing off to
   run: (args: HeadStartRunArgs<TTools>) => Promise<StreamTextResult<any, any>>,
   idleTimeoutInSeconds?: number,         // How long the agent waits for the handover signal. Default: 60
+  triggerConfig?: Partial<SessionTriggerConfig>, // Run options for the handover-prepare run
 }): (req: Request) => Promise<Response>
 ```
 
+`triggerConfig` sets run options on the auto-triggered handover-prepare run: `tags`, `queue`, `machine`, `maxAttempts`, `maxDuration`, `region`, and `lockToVersion`. The `chat:{chatId}` tag is prepended automatically. Because the session is created once on the first head-start turn (idempotent on the chat id), this is the only place to set those options for a head-start chat's lifetime, mirroring what [`chat.createStartSessionAction`](/ai-chat/sessions) sets for the direct-trigger path.
+
+```ts lib/chat-handler.ts
+export const chatHandler = chat.headStart({
+  agentId: "my-chat",
+  triggerConfig: { tags: ["org:acme"], queue: "chat", machine: "small-2x" },
+  run: async ({ chat: helper }) =>
+    streamText({ ...helper.toStreamTextOptions({ tools: headStartTools }), model, system }),
+});
+```
+
 The `run` callback receives:
 
 - `messages: UIMessage[]` — user messages parsed from the request body.
@@ -599,3 +669,4 @@ This is **not** a stock `useChat` `endpoint` — it's not the canonical request
 - [`chat.headStart` factory and types](/ai-chat/reference) — full signatures for `HeadStartRunArgs`, `HeadStartChatHelper`, `HeadStartSession`, `HeadStartHandlerOptions`.
 - [`headStart` transport option](/ai-chat/reference#triggerchattransport-options) — alongside `accessToken`, `startSession`, etc.
 - [`onPreload` hook](/ai-chat/lifecycle-hooks#onpreload) — the backend hook that fires when a run is preloaded.
+- [Custom agents](/ai-chat/custom-agents) — the `chat.customAgent` and `chat.createSession` loops that `consumeHandover` / `turn.handover` plug into.

docs/ai-chat/patterns/tool-result-auditing.mdx

@@ -112,12 +112,11 @@ await auditLog.upsert({
 ## What `extractNewToolResults` returns
 
 ```ts
-type ExtractedToolResult = {
+type ChatNewToolResult = {
   toolCallId: string;
   toolName: string;
-  input: unknown;       // The arguments the model passed when calling the tool
-  output?: unknown;     // The tool's return value (output-available state)
-  errorText?: string;   // Error message (output-error state)
+  output: unknown;      // The tool's return value (carries the resolved value; in output-error state see errorText)
+  errorText?: string;   // Set iff the part is in output-error state
 };
 ```