@agent-native/core 0.121.2 → 0.122.1

package/corpus/core/src/org/service-identity.ts

@@ -0,0 +1,60 @@
+/**
+ * Implicit org membership for synthetic service-token identities.
+ *
+ * Org service tokens authenticate as `svc-<name>@service.<orgId>` and are
+ * deliberately never inserted into `org_members` (see
+ * `mcp/actions/service-token-access.ts`), so any template that authorizes by
+ * looking up a physical membership row rejects them. The ownable/sharing layer
+ * already admits them via the signed `org_id` claim; this closes the gap for
+ * the role-lookup layer.
+ *
+ * Two constraints are load-bearing and must survive future edits:
+ *
+ * 1. The implicit role is always `member`, never admin or owner. Member-gated
+ *    actions (create/read org data) work; admin-gated ones (invite/remove
+ *    members, change roles, org settings, minting further service tokens) stay
+ *    closed, so a leaked service token cannot escalate.
+ * 2. `requestOrgId` must independently agree with the target org. The email
+ *    alone is not proof: a human account registered under a `@service.<orgId>`
+ *    address would otherwise mint itself membership. A signed-in user's request
+ *    org id is membership-derived through `getOrgContext`, so a non-member
+ *    cannot present the target org id, while a service token carries it in its
+ *    signed `org_id` claim.
+ */
+import type { OrgRole } from "./types.js";
+
+const SERVICE_IDENTITY_PATTERN = /^svc-([a-z0-9-]+)@service\.(.+)$/;
+
+/**
+ * Parse `svc-<name>@service.<orgId>` into its parts, or null when the address
+ * is not a service identity. Counterpart to `serviceIdentityEmail()` in
+ * `mcp/connect-store.ts`.
+ */
+export function parseServiceIdentityEmail(
+  email: string | null | undefined,
+): { serviceName: string; orgId: string } | null {
+  const trimmed = email?.trim();
+  if (!trimmed) return null;
+  const match = SERVICE_IDENTITY_PATTERN.exec(trimmed.toLowerCase());
+  if (!match) return null;
+  const orgId = trimmed.slice(trimmed.length - match[2].length);
+  if (!orgId) return null;
+  return { serviceName: match[1], orgId };
+}
+
+/**
+ * Resolve the implicit org role for a service-token caller, or null when the
+ * caller is not a service identity acting for the org it was minted against.
+ */
+export function implicitServiceOrgRole(params: {
+  email: string | null | undefined;
+  orgId: string | null | undefined;
+  requestOrgId: string | null | undefined;
+}): OrgRole | null {
+  const orgId = params.orgId?.trim();
+  if (!orgId) return null;
+  if (params.requestOrgId?.trim() !== orgId) return null;
+  const parsed = parseServiceIdentityEmail(params.email);
+  if (!parsed || parsed.orgId !== orgId) return null;
+  return "member";
+}

package/corpus/core/src/provider-api/index.ts

@@ -396,6 +396,7 @@ export interface ProviderApiConfig {
   placeholders?: readonly ProviderApiPlaceholder[];
   examples?: readonly ProviderApiExample[];
   notes?: readonly string[];
+  accessErrorGuidance?: string;
   corpusRecipes?: readonly ProviderApiCorpusRecipe[];
   templateUses?: readonly WorkspaceConnectionTemplateUse[];
 }
@@ -1326,6 +1327,11 @@ const PROVIDER_CONFIGS: Record<ProviderApiId, ProviderApiConfig> = {
     defaultHeaders: { "Notion-Version": "2026-03-11" },
     templateUses: ["analytics", "brain", "content", "dispatch"],
     examples: [{ label: "Search", method: "POST", path: "/search", body: {} }],
+    notes: [
+      "The name GET /users/me returns is the label whoever minted the token typed into Notion, so it often names an unrelated product or team. Call it the Notion-side integration label and never restate it as the workspace, app, or product the user is currently in.",
+    ],
+    accessErrorGuidance:
+      "Notion 401/403/404 on a specific page or database usually means that object was never shared with the integration, not that the id is wrong or the key is invalid. Fix: open the page or database in Notion, then ••• → Connections → add the integration. When naming the integration, describe it as the Notion-side integration label from GET /users/me and note that it may not match this app or workspace.",
     corpusRecipes: [
       {
         label: "Search a Notion data source with complete cursor coverage",
@@ -1624,6 +1630,7 @@ export function listProviderApiCatalog(
     defaultHeaders: config.defaultHeaders ?? {},
     examples: config.examples ?? [],
     notes: config.notes ?? [],
+    accessErrorGuidance: config.accessErrorGuidance ?? null,
     corpusRecipes: config.corpusRecipes ?? [],
     templateUses: config.templateUses ?? [],
   }));
@@ -1990,11 +1997,25 @@ export async function executeProviderApiRequest(
       ...(args.connectionId ? { connectionId: args.connectionId } : {}),
     },
     response,
-    guidance:
+    guidance: [
       "This was a raw provider API request. Use provider docs/spec URLs to choose endpoints and include method/path/status plus relevant filters in the methodology. Prefer this escape hatch whenever canned actions are too narrow.",
+      providerAccessErrorGuidance(config, response.status),
+    ]
+      .filter(Boolean)
+      .join(" "),
   };
 }
 
+const PROVIDER_ACCESS_ERROR_STATUSES = new Set([401, 403, 404]);
+
+function providerAccessErrorGuidance(
+  config: ProviderApiConfig,
+  status: number,
+): string | null {
+  if (!PROVIDER_ACCESS_ERROR_STATUSES.has(status)) return null;
+  return config.accessErrorGuidance ?? null;
+}
+
 /**
  * Resolve a provider OAuth token for a trusted server-side integration bridge
  * such as a CRM adapter or Google Picker. Callers must keep the result out of

package/corpus/core/src/scripts/docs/search.ts

@@ -143,7 +143,7 @@ function slugifyDocId(value: string): string {
 
 async function loadAgentBundleDocs(): Promise<DocFull[]> {
   try {
-    const { loadAgentsBundle, getRuntimeSkills } =
+    const { loadAgentsBundle, getRuntimeSkills, skillSubfileDocsSlug } =
       await import("../../server/agents-bundle.js");
     const bundle = await loadAgentsBundle();
     const docs: DocFull[] = [];
@@ -174,6 +174,17 @@ async function loadAgentBundleDocs(): Promise<DocFull[]> {
         description: skill.meta.description,
         body: skill.content,
       });
+      // Progressive-disclosure sub-files (e.g. `references/*.md`) get their
+      // own searchable/readable doc so the "also contains" pointers the
+      // skill prompt block advertises actually resolve to something.
+      for (const [relPath, content] of Object.entries(skill.files)) {
+        docs.push({
+          slug: skillSubfileDocsSlug(skill.meta.name, relPath),
+          title: `Skill: ${skill.meta.name} — ${relPath}`,
+          description: `Reference file from the "${skill.meta.name}" skill (${relPath}).`,
+          body: content,
+        });
+      }
     }
     return docs;
   } catch {

package/corpus/core/src/server/agent-chat/context-tools.ts

@@ -1,6 +1,11 @@
 import { ACTION_CHAT_UI_DATA_WIDGET_RENDERER } from "../../action-ui.js";
 import type { ActionEntry } from "../../agent/production-agent.js";
-import { dataWidgetResultSchema } from "../../data-widgets/index.js";
+import {
+  clampDataWidgetRows,
+  DATA_WIDGET_MAX_CHART_POINTS,
+  DATA_WIDGET_MAX_ROWS,
+  dataWidgetResultSchema,
+} from "../../data-widgets/index.js";
 import { getRequestRunContext } from "../request-context.js";
 
 // ---------------------------------------------------------------------------
@@ -559,8 +564,7 @@ export function createDataWidgetActionEntries(): Record<string, ActionEntry> {
         description: "Render a validated native data table or chart in chat.",
       },
       tool: {
-        description:
-          "Render a native Agent-Native chat data widget from compact, real data you already retrieved or the user provided. Use this for in-chat tables, charts, graphs, trends, and compact reports when no domain-specific action already returns a native widget. Never fabricate rows or metrics just to make a chart.",
+        description: `Render a native Agent-Native chat data widget from compact, real data you already retrieved or the user provided. Use this for in-chat tables, charts, graphs, trends, and compact reports when no domain-specific action already returns a native widget. Never fabricate rows or metrics just to make a chart. Rows travel as tool arguments you type out one token at a time, so this is only for already-summarized data: at most ${DATA_WIDGET_MAX_ROWS} table rows and ${DATA_WIDGET_MAX_CHART_POINTS} chart points (anything beyond that is dropped). For a larger result set, aggregate it first, or state the total and show only the top rows — never re-serialize a full query result here.`,
         parameters: {
           type: "object",
           properties: {
@@ -602,7 +606,8 @@ export function createDataWidgetActionEntries(): Record<string, ActionEntry> {
           required: ["widget"],
         },
       },
-      run: async (args) => dataWidgetResultSchema.parse(args),
+      run: async (args) =>
+        clampDataWidgetRows(dataWidgetResultSchema.parse(args)),
     },
   };
 }

package/corpus/core/src/server/agent-chat/framework-prompts.ts

@@ -15,7 +15,6 @@ import {
   FRAMEWORK_CONTEXT_SECTIONS,
 } from "./context-tools.js";
 import { lazyFs } from "./lazy-fs.js";
-import { compactPromptLine } from "./prompt-resources.js";
 
 // ---------------------------------------------------------------------------
 // Framework-level system prompt assembly (production/dev, full/compact),
@@ -23,8 +22,6 @@ import { compactPromptLine } from "./prompt-resources.js";
 // block, and the codebase file-tree walker used by a few dev-mode tools.
 // ---------------------------------------------------------------------------
 
-const MAX_ACTION_SUMMARY_DESCRIPTION_CHARS = 140;
-
 /**
  * Framework-level instructions injected into every agent's system prompt.
  * Prompt text lives in packages/core/src/server/prompts/ so this file stays
@@ -60,68 +57,30 @@ export function buildFrameworkPrompts(
   const extensionInstructionsFull = extensionToolsEnabled
     ? `### Generative UI and Extensions (Mini-Apps)
 
-In Act mode, if the user asks for generated interactive UI in chat, choose the smallest extension action that matches the lifetime:
-
-- For a **one-time inline UI** that answers the current chat turn (knobs, controls, pickers, calculators, temporary dashboards, visualizers), call \`render-inline-extension\` immediately with a self-contained Alpine.js HTML body. It renders inside the transcript and is not saved.
-- For a **reusable or saved UI** (an extension/widget/dashboard/calculator/mini-app the user can reopen from Extensions), call \`create-extension\` with a self-contained Alpine.js HTML body. It saves to the Extensions view and also renders inline in chat.
-- To **reuse an existing saved extension inline**, call \`show-extension-inline\` with its id, or a search string when the id is unknown.
-
-These are **NOT** source-code changes and do **NOT** go through \`connect-builder\`. Extensions are sandboxed mini-apps — no source files are touched, no PR is opened, no build is required. Saved extensions can be edited later via \`update-extension\`.
+In Act mode, if the user asks for generated interactive UI in chat, choose the smallest extension action for the lifetime: \`render-inline-extension\` (one-off, chat-only), \`create-extension\` (saved/reusable), \`show-extension-inline\` (reopen a saved one), or \`update-extension\` (edit an existing one) — call the right one directly, without a "let me build…" preamble. Each tool's own description covers its exact use case, arguments, and available helpers (appAction, dbQuery, extensionData, agentNative.ui.output, etc.). Extensions are sandboxed mini-apps, not source-code changes, and never go through \`connect-builder\`.
 
 If the app exposes native actions or instructions for dashboards, reports, analyses, charts, documents, decks, or other domain artifacts, use those app-native actions first. Choose an extension only when the user explicitly asks for an extension/custom mini-app, or when the app's native artifact format cannot faithfully express the requested interaction.
 
-Keep \`create-extension\` payloads compact enough to finish quickly. For complex extensions, create a useful working v1 first, then call \`update-extension\` with focused edits for refinements instead of trying to assemble one enormous initial tool input.
-
-Generated UI content can use appAction(), appFetch(), dbQuery(), extensionFetch(), extensionData, agentNative.ui.output(value, opts?), and agentNative.chat.send(...)/sendToAgentChat(...). Use appAction() for app data writes, and dbQuery() only for read-only inspection of known app SQL tables. It can receive chat inputs through slotContext/window.onSlotContext. Use agentNative.ui.output for passive current values from knobs, sliders, selections, and controls; it writes application state at \`inline-ui:<extensionId>:output\` scoped to the inline extension id returned by \`render-inline-extension\` or \`show-extension-inline\`. When the user later says "use that value", "apply the current setting", or similar, read it with \`readAppState("inline-ui:<id>:output")\` instead of asking them to send it again. Use agentNative.chat.send for visible submit/apply actions that should put a message into chat. Transient extensionData is browser-local and not agent-readable, synced, promoted, or garbage-collected; use application_state/appFetch, appAction, ui.output, or chat.send for anything the agent or app must observe. Use semantic Tailwind classes like bg-background, text-foreground, bg-primary, border-border, and text-muted-foreground so the UI inherits the parent app theme.
-
-If the user asks to change, edit, fix, style, rename, or add behavior to an existing extension/widget/dashboard/calculator/mini-app, use the current extension id from \`<current-screen>\` or \`<current-url>\` when present. Call \`get-extension\` only if you need to inspect its content, then call \`update-extension\` with exactly \`id\`, \`operation\`, and \`payloadJson\`; encode the operation payload as a JSON string and never send empty placeholder fields. After one content read, keep the body in working memory and use \`operation="edit"\` with focused \`edits\`/\`patches\` inside \`payloadJson\`; do not loop on repeated \`get-extension\` + \`run-code\` string scans before writing. For a data-only repair, preserve the existing layout, CSS, copy, and interactions. Use \`operation="replace"\` only when the user explicitly requests a broad visual rewrite or supplies a complete replacement body. Use \`operation="metadata"\` for name/description/icon, and use \`set-resource-visibility\` for sharing changes. If a focused patch fails, read the current body and change the target rather than retrying identical arguments. Use \`list-extensions\` only when no current id/name is available. Existing extension edits are SQL data updates, not source-code changes, even when the request says "change the UI" or "fix this". Do **NOT** call \`connect-builder\` for existing extension edits.
-
-In Act mode, when in doubt — if the request asks for a new small interactive utility and does not need reuse, choose \`render-inline-extension\`; if it mentions saving/reuse or asks for an extension/widget/dashboard/calculator/mini-app, choose \`create-extension\`. If it references an existing one or the current extension page, choose \`update-extension\`. Do **not** preface the call with planning text like "let me build the dashboard…" — just call the right extension action directly.
-
-Note: "extension" is the user-facing primitive (the sandboxed Alpine.js mini-app). Don't confuse it with the LLM concept of "tools" (function calls) — those are how you invoke ANY action, including \`create-extension\` itself.
-
-For existing extensions, use \`get-extension\` or \`update-extension\` directly when \`<current-screen>\` or \`<current-url>\` provides an \`extensionId\`. Use \`list-extensions\` only to browse or resolve an unknown name. If the user wants a shared extension removed only from their view, use \`hide-extension\` — do not query or mutate the legacy \`tools\` table directly.
-
-### Extensions vs. Code Changes — Pick the Right Path
-
-Route by the exact outcome, not by whether the user calls it an extension. Extensions render in their own sandboxed iframe, either on their own page or inside an existing named slot. They CANNOT change the host app's nav, restyle or inject elements into existing native components, replace built-in views, or render at an arbitrary location that has no slot.
+Editing an existing extension (fix, restyle, rename, add behavior) is a SQL data update — call \`update-extension\` directly using the extensionId from \`<current-screen>\`/\`<current-url>\` when present; never call \`connect-builder\` for it.
 
-<routing>
-| The request is for…                                              | Path                          |
-| ---------------------------------------------------------------- | ------------------------------ |
-| A one-off interactive answer inside chat (controls, picker, calculator, temporary visualizer) | \`render-inline-extension\` — inline only |
-| A new self-contained surface (widget, dashboard, calculator, viewer, list, tracker) | \`create-extension\` — ships instantly, no PR |
-| Loading a saved extension inside chat | \`show-extension-inline\` |
-| Editing an existing extension (fix, restyle, rename, add behavior) | \`update-extension\`           |
-| The host app's own chrome (nav bar, sidebar, layout, routes, shipped components, existing styles, business logic) | \`connect-builder\` — a real source-code change |
-| UI inside or beside a native component where no named slot exists | \`connect-builder\` — add the native UI or a suitable slot in source |
-| Ambiguous, satisfiable either way (e.g. "give me an unread view") | \`render-inline-extension\` for chat-only, \`create-extension\` for reusable |
-</routing>
+Extensions render only on their own page or inside an existing named slot; they cannot inject UI into arbitrary native components. If an extension could only approximate the request in a different location, do not silently downgrade the requirement and do not end with "extensions cannot do that." Briefly explain the boundary, then follow the normal source-code handoff so the app can still be customized fully.
 
-If an extension could only approximate the request in a different location, do not silently downgrade the requirement and do not end with "extensions cannot do that." Briefly explain the boundary, then follow the normal source-code handoff so the app can still be customized fully.
-
-Worked examples: "a widget showing unread emails grouped by sender", "a tracker for my newsletter subscriptions", "a custom kanban board with drag-and-drop rules the app does not have" → \`create-extension\`. "Add an Unread tab to the left navigation", "show local time beside every native Calendar attendee row", "make the subject lines wrap", "change the inbox grouping logic", "add a field to the compose form" → \`connect-builder\`.`
+For helper APIs, Alpine.js patterns, the extension-vs-code-change boundary, and worked examples, read the \`extensions\` and \`generative-ui\` skills.`
     : `### Extensions Disabled
 
 Extension creation and management tools are disabled for this app. Do not claim you can create, edit, hide, or delete Agent-Native extensions unless the template exposes its own typed action for that workflow. For requests that would otherwise be handled as an extension/widget/dashboard/calculator mini-app, explain that this app has disabled extension tools and use the app's available actions instead.`;
   const extensionInstructionsCompact = extensionToolsEnabled
     ? `### Generative UI and Extensions (Mini-Apps)
 
-In Act mode, if the user asks for generated interactive UI in chat, call \`render-inline-extension\` for one-time inline controls/knobs/calculators/visualizers that do not need saving. If the user asks for an **extension**, **widget**, **dashboard**, **calculator**, or **mini-app** that should be reusable or saved, call \`create-extension\` with a self-contained Alpine.js HTML body. To load a saved extension inline, call \`show-extension-inline\`. These are NOT code changes — extensions are sandboxed mini-apps. Do not preface with "let me build…" — just call the right extension action.
+In Act mode, choose the smallest extension action for the lifetime: \`render-inline-extension\` (one-off, chat-only), \`create-extension\` (saved/reusable), \`show-extension-inline\` (reopen a saved one), or \`update-extension\` (edit an existing one) — each tool's own description covers its use case and helpers. These are sandboxed mini-apps, not code changes; never route them through \`connect-builder\`. Do not preface with "let me build…" — just call the right extension action.
 
 Use app-native artifact actions first when they exist for dashboards, reports, analyses, charts, documents, decks, or similar domain artifacts. Pick \`create-extension\` only for explicit extension/custom mini-app requests or for behavior the native artifact format cannot support.
 
-Keep the first \`create-extension\` call compact and working. If the request is complex, create the v1 first and then refine with focused \`update-extension\` edits.
-
-Generated UI can read chat inputs from slotContext/window.onSlotContext, see/update app state through appFetch/appAction, use extensionData, record passive current values through agentNative.ui.output(value, opts?), and send visible results through agentNative.chat.send(...) or sendToAgentChat(...). ui.output writes \`inline-ui:<extensionId>:output\` in application state; when the user asks to use the current slider/selection/value, read \`readAppState("inline-ui:<id>:output")\`. Transient extensionData is browser-local only, so do not rely on it for values the agent or app must observe. Use semantic Tailwind theme classes.
-
-If the user asks to change, edit, fix, style, rename, or add behavior to an existing extension/widget/dashboard/calculator/mini-app, use the current extension id from \`<current-screen>\` or \`<current-url>\` when present. Call \`get-extension\` only if you need to inspect its content, then call \`update-extension\` with exactly \`id\`, \`operation\`, and \`payloadJson\`; encode the operation payload as a JSON string and never send empty placeholder fields. After one content read, use \`operation="edit"\` with focused \`edits\`/\`patches\` inside \`payloadJson\`; do not repeatedly re-read and scan the same HTML with \`run-code\` before writing. For a data-only repair, preserve the existing layout, CSS, copy, and interactions. Use \`operation="replace"\` only when the user explicitly requests a broad visual rewrite or supplies a complete replacement body. Use \`operation="metadata"\` for name/description/icon, and use \`set-resource-visibility\` for sharing changes. If a focused patch fails, read the current body and change the target rather than retrying identical arguments. Use \`list-extensions\` only when no current id/name is available. Existing extension edits are SQL data updates, not source-code changes. Do NOT call \`connect-builder\` for them.
+Editing an existing extension is a data update — call \`update-extension\` directly using the extensionId from \`<current-screen>\`/\`<current-url>\` when present; never \`connect-builder\`.
 
-For existing extensions, use \`get-extension\` or \`update-extension\` directly when \`<current-screen>\` or \`<current-url>\` provides an \`extensionId\`. Use \`list-extensions\` only to browse or resolve an unknown name. Use \`hide-extension\` when the user wants a shared extension removed only from their own view. Do not query the legacy \`tools\` table directly.
+Extensions can render only on their own page or in an existing named slot; they cannot inject UI into arbitrary native components. If the exact request changes host chrome, native components, layout, styles, routes, business logic, or needs placement where no slot exists, treat it as a source-code change and use the normal \`connect-builder\` flow even if the user called it an extension. Never stop at "extensions cannot do that" or silently offer a different placement; explain the boundary briefly and continue the code-change handoff.
 
-### Extensions vs. Code Changes — Pick the Right Path
-
-If the user wants a **one-off interactive answer in chat**, use \`render-inline-extension\`. If they want a **new reusable self-contained surface** (custom widget, dashboard, list, viewer, calculator), use \`create-extension\` — extensions ship instantly without a PR. Extensions can render only on their own page or in an existing named slot; they cannot inject UI into arbitrary native components. If the exact request changes host chrome, native components, layout, styles, routes, business logic, or needs placement where no slot exists, treat it as a source-code change and use the normal \`connect-builder\` flow even if the user called it an extension. Never stop at "extensions cannot do that" or silently offer a different placement; explain the boundary briefly and continue the code-change handoff.`
+See the \`extensions\` and \`generative-ui\` skills for helper APIs, Alpine.js patterns, and worked examples.`
     : `### Extensions Disabled
 
 Extension creation and management tools are disabled for this app. Do not claim you can create, edit, hide, or delete Agent-Native extensions unless the template exposes its own typed action for that workflow.`;
@@ -265,15 +224,20 @@ export async function buildSchemaBlock(
 
 /**
  * Generates a system prompt section describing registered template actions.
- * This helps the agent prefer template-specific actions over raw db-query/db-exec.
  *
  * Two output modes:
  *
  *   - `"tool"` — used in production, where template actions are registered
- *     as native Anthropic tools. Output reads `name(arg*: type; ...) — desc`.
+ *     as native Anthropic tools. The native tool schema already carries each
+ *     action's name, full description, and parameters, so this mode does NOT
+ *     re-list every action — it only surfaces what the tool list can't:
+ *     native-chat-widget annotations and a `tool-search` pointer for actions
+ *     omitted from the initial tool set.
  *   - `"cli"` — used in dev, where template actions are NOT registered as
  *     native tools and must be invoked via `bash(command="pnpm action ...")`.
- *     Output reads `pnpm action name --arg <type> [--opt <type>] — desc`.
+ *     This listing is load-bearing here (there is no tool schema to fall
+ *     back on), so it still emits the full
+ *     `pnpm action name --arg <type> [--opt <type>] — desc` line per action.
  */
 export function generateActionsPrompt(
   registry: Record<string, ActionEntry>,
@@ -294,23 +258,31 @@ export function generateActionsPrompt(
       : "";
 
   if (mode === "tool") {
-    const summaryLines = actionEntries.map(([name, entry]) => {
-      const desc = compactPromptLine(
-        entry.tool.description,
-        MAX_ACTION_SUMMARY_DESCRIPTION_CHARS,
+    // Native tool schemas already carry name + full description + params
+    // for every action, so this section only needs to surface what the tool
+    // list itself can't: which actions render a native chat widget, and
+    // which actions exist but aren't loaded as initial tools yet.
+    const widgetLines = actionEntries
+      .filter(([, entry]) => typeof entry.chatUI?.renderer === "string")
+      .map(
+        ([name, entry]) =>
+          `- \`${name}\` — Native chat widget: \`${entry.chatUI?.renderer ?? ""}\`.`,
       );
-      return `- \`${name}\` — ${desc}${nativeWidgetNote(entry)}`;
-    });
 
-    return `\n\n## Available Actions
-
-**Use these actions directly as tool calls.** They handle database access, validation, and business logic internally. The native tool schemas contain the full parameter details.
+    const sections: string[] = [];
+    if (widgetLines.length > 0) {
+      sections.push(
+        `**Actions that render a native chat widget** — call these directly for their table/chart/insights view instead of recreating it in prose:\n\n${widgetLines.join("\n")}`,
+      );
+    }
+    if (omittedActionCount > 0) {
+      sections.push(
+        `${omittedActionCount} less-common app action${omittedActionCount === 1 ? " is" : "s are"} available on demand. Use \`tool-search\` with a specific capability query to load the matching schemas when needed.`,
+      );
+    }
+    if (sections.length === 0) return "";
 
-${summaryLines.join("\n")}${
-      omittedActionCount > 0
-        ? `\n\n${omittedActionCount} less-common app action${omittedActionCount === 1 ? " is" : "s are"} available on demand. Use \`tool-search\` with a specific capability query to load the matching schemas when needed.`
-        : ""
-    }`;
+    return `\n\n## Available Actions\n\n${sections.join("\n\n")}`;
   }
 
   const lines = actionEntries.map(([name, entry]) => {

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -123,6 +123,7 @@ import {
   type ChatThreadScope,
   type ForkThreadSourceSnapshot,
 } from "../chat-threads/store.js";
+import { isCheckpointRestorePath } from "../checkpoints/route-match.js";
 import { createDbAdminAgentTools } from "../db-admin/agent-tools.js";
 import { isTransientDatabaseError } from "../db/client.js";
 import {
@@ -4770,11 +4771,9 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             }
           }
 
-          // POST /checkpoints — restore to a checkpoint
-          // h3 prefix-matches, so /checkpoints/restore hits this handler with
-          // event.path containing "/restore".
-          const remainder = (event.path || "").replace(/^\/+/, "");
-          if (method === "POST" && remainder.startsWith("restore")) {
+          // POST /checkpoints/restore — restore to a checkpoint.
+          const restorePath = event.path || event.node?.req?.url || "";
+          if (method === "POST" && isCheckpointRestorePath(restorePath)) {
             if (!canToggle) {
               setResponseStatus(event, 403);
               return { error: "Checkpoints only available in dev mode" };
@@ -4785,17 +4784,25 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             }
             const body = await readBody(event);
             const checkpointId = body?.checkpointId;
-            if (!checkpointId) {
+            const restoreRunId =
+              typeof body?.runId === "string" ? body.runId : "";
+            if (!checkpointId && !restoreRunId) {
               setResponseStatus(event, 400);
-              return { error: "checkpointId is required" };
+              return { error: "checkpointId or runId is required" };
             }
             try {
-              const { getCheckpointById } =
+              const { getCheckpointById, getCheckpointByRunId } =
                 await import("../checkpoints/store.js");
-              const checkpoint = await getCheckpointById(checkpointId);
+              const checkpoint = checkpointId
+                ? await getCheckpointById(checkpointId)
+                : await getCheckpointByRunId(restoreRunId);
               if (!checkpoint) {
                 setResponseStatus(event, 404);
-                return { error: "Checkpoint not found" };
+                return {
+                  error: restoreRunId
+                    ? "No checkpoint was saved for this turn, so there is nothing to restore."
+                    : "Checkpoint not found",
+                };
               }
               const owner = await getOwnerFromEvent(event);
               const thread = await getThread(checkpoint.threadId);

package/corpus/core/src/server/agents-bundle.ts

@@ -60,6 +60,16 @@ export interface Skill {
    * `ls` call. Empty array if the skill is single-file.
    */
   extraFiles: string[];
+  /**
+   * Text content of eligible sub-files (progressive-disclosure references),
+   * keyed by the same skill-dir-relative path used in `extraFiles`. Only
+   * populated for text extensions under the per-file/per-skill caps in
+   * `readSkillsDir` — files that exist but were skipped for size still show
+   * up in `extraFiles`, just not here. This is what makes reference content
+   * actually readable by the runtime agent (via docs-search); it is never
+   * injected into a prompt.
+   */
+  files: Record<string, string>;
 }
 
 export interface AgentsBundle {
@@ -176,6 +186,23 @@ const TEMPLATE_SKILLS_DIRS = [
   path.join(".agent", "skills"),
 ] as const;
 
+/**
+ * Extensions eligible to have their content inlined into `Skill.files`.
+ * Binary/asset sub-files (images, scripts, etc.) are always listed in
+ * `extraFiles` but never read into memory.
+ */
+const READABLE_SUBFILE_EXTENSIONS = new Set([".md", ".txt", ".json"]);
+/**
+ * Per-file and per-skill caps on inlined reference content. This content is
+ * bundled into the virtual module (and therefore the server bundle) for
+ * every deployment target, so it must stay small even though it's never
+ * added to a prompt — only fetched on demand via docs-search. Measured
+ * against this repo's skills (largest single sub-file ~20KB, largest
+ * per-skill sub-file total ~83KB), these caps have generous headroom.
+ */
+const MAX_SUBFILE_BYTES = 64 * 1024;
+const MAX_SKILL_FILES_BYTES = 256 * 1024;
+
 /**
  * Paths to a workspace-core's agent resources, for merging into a template's
  * bundle. All fields optional — pass null for any missing piece.
@@ -217,6 +244,8 @@ function readSkillsDir(
       if (skipExistingNames && out[name]) continue; // Template wins
 
       const extraFiles: string[] = [];
+      const files: Record<string, string> = {};
+      let skillFilesBytes = 0;
       try {
         const walk = (subdir: string, prefix: string) => {
           for (const e of fs.readdirSync(subdir, { withFileTypes: true })) {
@@ -229,6 +258,17 @@ function readSkillsDir(
               } catch {}
             } else if (e.isFile() && e.name !== "SKILL.md") {
               extraFiles.push(rel);
+              const ext = path.extname(e.name).toLowerCase();
+              if (!READABLE_SUBFILE_EXTENSIONS.has(ext)) continue;
+              try {
+                const stat = fs.statSync(abs);
+                if (stat.size > MAX_SUBFILE_BYTES) continue;
+                if (skillFilesBytes + stat.size > MAX_SKILL_FILES_BYTES) {
+                  continue;
+                }
+                files[rel] = fs.readFileSync(abs, "utf-8");
+                skillFilesBytes += stat.size;
+              } catch {}
             }
           }
         };
@@ -245,6 +285,7 @@ function readSkillsDir(
         content,
         dir: path.relative(rootForRelative, skillDirAbs).replace(/\\/g, "/"),
         extraFiles,
+        files,
       };
     } catch {
       // Skip unreadable skills
@@ -397,7 +438,7 @@ export function getDevelopmentSkills(bundle: AgentsBundle): Skill[] {
   );
 }
 
-function skillDocsSlug(name: string): string {
+export function skillDocsSlug(name: string): string {
   return `skill-${name
     .trim()
     .toLowerCase()
@@ -405,6 +446,28 @@ function skillDocsSlug(name: string): string {
     .replace(/^-+|-+$/g, "")}`;
 }
 
+function subfileSlugSuffix(relPath: string): string {
+  return relPath
+    .replace(/\.[^./]+$/, "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Slug docs-search resolves a skill sub-file (reference) content by. Kept in
+ * sync with the `skill-<name>--<subpath-slug>` docs it emits in
+ * `scripts/docs/search.ts` so the prompt hint always points at something the
+ * agent can actually read.
+ */
+export function skillSubfileDocsSlug(
+  skillName: string,
+  relPath: string,
+): string {
+  return `${skillDocsSlug(skillName)}--${subfileSlugSuffix(relPath)}`;
+}
+
 function generateSkillsPromptBlockForEntries(
   entries: Skill[],
   mode: "runtime" | "development",
@@ -412,10 +475,26 @@ function generateSkillsPromptBlockForEntries(
   if (entries.length === 0) return "";
 
   const lines = entries.map((s) => {
-    const extras =
-      s.extraFiles.length > 0
-        ? ` (also contains: ${s.extraFiles.join(", ")})`
-        : "";
+    let extras = "";
+    if (s.extraFiles.length > 0) {
+      if (mode === "runtime") {
+        const readable = s.extraFiles.filter((f) => f in s.files);
+        const unreadable = s.extraFiles.filter((f) => !(f in s.files));
+        const parts: string[] = [];
+        if (readable.length > 0) {
+          const refIds = readable.map((f) => subfileSlugSuffix(f)).join(", ");
+          parts.push(
+            `refs via docs-search --slug "${skillDocsSlug(s.meta.name)}--<ref>": ${refIds}`,
+          );
+        }
+        if (unreadable.length > 0) {
+          parts.push(`also contains: ${unreadable.join(", ")}`);
+        }
+        extras = ` (${parts.join("; ")})`;
+      } else {
+        extras = ` (also contains: ${s.extraFiles.join(", ")})`;
+      }
+    }
     const runtimeHint =
       mode === "runtime"
         ? ` Read with \`docs-search --slug "${skillDocsSlug(s.meta.name)}"\` before starting a task it applies to.`

package/corpus/core/src/server/auth.ts

@@ -81,7 +81,7 @@ import {
 } from "../mcp/route-paths.js";
 import { readBody } from "../server/h3-helpers.js";
 import { putSetting } from "../settings/store.js";
-import { DEFAULT_SSR_CACHE_HEADERS } from "../shared/cache-control.js";
+import { resolveSsrCacheHeaders } from "../shared/cache-control.js";
 import { extractOAuthStateAppId } from "../shared/oauth-state.js";
 import {
   AGENT_NATIVE_SOCIAL_IMAGE_ALT,
@@ -1658,8 +1658,9 @@ function loginHtmlResponse(loginHtml: string, event: H3Event): Response {
         // template roots do not invoke origin just to render anonymous login UI.
         // The login markup is env-INDEPENDENT (a Google-only app always renders
         // a working button); the analytics script is public build configuration,
-        // not user/session state. Never downgrade this to private/no-store.
-        ...DEFAULT_SSR_CACHE_HEADERS,
+        // not user/session state. Never vary this per request — the
+        // deployment-wide override inside the resolver is the only knob.
+        ...resolveSsrCacheHeaders(),
         "X-Robots-Tag": "noindex, nofollow",
       },
     },