@agent-native/core 0.152.0 → 0.153.0

package/corpus/templates/tasks/.agents/skills/turn-into-app/references/spreadsheet-source.md

@@ -0,0 +1,148 @@
+# Spreadsheet source review
+
+Use this reference after a workbook upload or Google Sheets link is supplied to
+`/turn-into-app`. It defines the bounded review contract before app creation.
+
+## 1. Establish the source boundary
+
+Record the source before interpreting it:
+
+| Field        | Record                                                                            |
+| ------------ | --------------------------------------------------------------------------------- |
+| Source kind  | `xlsx`, `xls`, `csv`, or Google Sheets URL                                        |
+| Provenance   | Original file name or spreadsheet ID and URL; never credentials or workbook bytes |
+| Access       | Upload preview, authenticated provider read, or unavailable                       |
+| Coverage     | Worksheet names, selected range(s), row/column bounds, and sample counts          |
+| Completeness | Complete within the requested bound, partial, truncated, unreadable, or empty     |
+| Refresh      | One-time snapshot or live refreshable source                                      |
+
+For an uploaded XLS/XLSX file, the framework preview contains worksheet names,
+dimensions, and representative displayed values within bounds. It does not
+currently preserve cell fills or font colors in that text preview. Treat the
+original workbook as the formatting authority only when a tool actually returns
+cell formatting metadata. Never describe a text-only upload as style-verified.
+
+For a Google Sheets URL:
+
+1. Parse the spreadsheet ID and preserve the original URL as provenance.
+2. Use the authenticated `google_drive` provider path. Inspect
+   `provider-api-catalog` first, use `provider-api-docs` if the endpoint or
+   fields are uncertain, and then call `provider-api-request`.
+3. Read spreadsheet metadata and only bounded worksheet/range data. Request
+   formatting metadata when the I/O decision depends on colors, including
+   `userEnteredFormat.backgroundColor` and
+   `userEnteredFormat.textFormat.foregroundColor` where the provider supports
+   it. Do not use a public export URL to bypass access.
+4. Preserve the spreadsheet ID, worksheet title, A1 range, account/connection
+   choice without secrets, row limits, and refresh behavior in the brief.
+
+Keep provider responses bounded. For large sheets, stage or save the response
+and reduce it with the available dataset/code tools. A failed page, truncated
+response, or unavailable connection is not an empty sheet.
+
+## 2. Infer cells and ranges, then show the evidence
+
+Classify source material into three separate buckets. Include representative
+cell addresses or ranges and the evidence behind each classification.
+
+| Bucket             | Default signal                                                                                                     | App treatment                                                          |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| Inputs             | Yellow cell background, editable assumptions, user-entered constants, or labels such as `assumption` / `driver`    | Editable controls or bounded source parameters                         |
+| Outputs            | Blue text, formula-derived result cells, summary blocks, or labels such as `forecast` / `recommendation`           | Read-only results, charts, recommendations, exports, or review actions |
+| Static historicals | Black text used intentionally for prior-period/source records, raw rows, or labels such as `actual` / `historical` | Read-only context; never turn into editable inputs by default          |
+
+These are conventions, not permission to guess. A default black font with no
+explicit style metadata is not enough to label a range as historical. Resolve
+conflicts using labels, formulas, neighboring headers, repeated patterns, and
+the user's stated goal. If the evidence still conflicts, lower confidence and
+ask the user to confirm the proposed mapping.
+
+Keep source cells and app behavior distinct:
+
+- `Source inputs` are the workbook cells or ranges the user is expected to
+  change or refresh.
+- `Source outputs` are the workbook cells or ranges the source already derives
+  or presents.
+- `Static historicals` are context the app may filter, compare, or summarize,
+  but should not edit.
+- `App outputs` are the new app's visible results, saved records, exports,
+  alerts, or downstream handoffs. Do not invent these until the repeatable job
+  or user confirmation makes them clear.
+
+## 3. Offer candidate apps, not a tab dump
+
+Group related worksheets into candidate repeatable jobs. A candidate should
+have a recognizable user, trigger, inputs, transformation or judgment, and
+outputs. Utility tabs such as lookups, raw imports, instructions, pivots, and
+calculation helpers can support a candidate without becoming destinations.
+
+Present a compact Q&A review with multi-select options. In generated app code,
+use `askUserQuestion` from `@agent-native/core/client/agent-chat` with
+`allowMultiple: true`, stable candidate IDs as option values, and
+`allowFreeText: true` for corrections. It renders inline in the agent panel;
+do not build a custom modal. Each option should fit in a scannable row or
+choice card:
+
+```text
+Candidate: Pipeline forecast
+Uses: Assumptions, Historical Pipeline, Forecast
+Inputs: yellow assumptions in Assumptions!B4:B12 (high confidence)
+Outputs: blue forecast summary in Forecast!B3:H10 (medium confidence)
+Historical context: Historical Pipeline!A1:K500
+Question: Confirm that forecast assumptions should be editable?
+```
+
+Mark the strongest recommendation with `recommended: true`, but do not silently
+select it. Let the user select none, one, or several candidates, correct a
+proposed tab/range, or answer the unresolved question. Keep each question to
+2-4 grouped candidate jobs; for a larger workbook, group related tabs into
+jobs rather than showing a tab dump or asking a separate question for every
+worksheet. If there is only one high-confidence candidate, keep the review
+compact and ask for confirmation only when the I/O mapping or source access is
+unclear.
+
+When several candidates are selected, pass a stable candidate ID, display name,
+source worksheet/ranges, I/O mapping, confidence, and confirmation status for
+each. The generated app should expose them as separate named left-navigation
+destinations or tabs, not merge them into an opaque dashboard and not create a
+separate workspace app for every worksheet.
+
+## 4. Confirm before building or publishing
+
+The confirmation view is a source-integrity checkpoint, not a product-design
+questionnaire. Show:
+
+- the source file or spreadsheet ID and snapshot/live choice;
+- selected candidate destinations and their source tabs/ranges;
+- editable inputs, read-only outputs, and static historical context;
+- the evidence and confidence for each mapping;
+- truncation, unreadable, missing-connection, and refresh limitations;
+- the app outputs/actions that will be created.
+
+Use clear actions such as `Confirm and build`, `Edit mapping`, and `Use a
+different source`. If the host has a structured question or multi-select UI,
+use it. Otherwise, ask one concise assistant message that presents the same
+options and requires an explicit confirmation/correction before handoff.
+
+After confirmation, the online host may call
+`start-workspace-app-creation`; the Builder run itself remains autonomous and
+must record any remaining non-blocking assumptions. In a local generated app,
+persist the confirmation state in SQL/application state and keep the user on
+the review surface while the agent builds. Never claim a full import, live
+refresh, or output write until the corresponding source/action has succeeded.
+
+## 5. Failure and recovery states
+
+Keep these states distinct in the review and in the handoff:
+
+- `unreadable` - parser/provider could not read the source;
+- `partial` - only some worksheets, ranges, rows, or pages were read;
+- `truncated` - the bounded preview ended before full coverage;
+- `empty` - the requested readable range contains no values;
+- `not-connected` - authenticated Google access is required but unavailable;
+- `confirmed` - the user approved the candidate and I/O mapping.
+
+For unreadable or not-connected sources, request a CSV/XLSX export or the
+required connection. For partial or truncated sources, continue only with a
+clearly bounded snapshot or ask for a narrower range. Do not coerce any of
+these states into a successful empty source.

package/corpus/templates/tasks/.agents/skills/workspace-conventions/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: workspace-conventions
+description: >-
+  Shared conventions for a multi-app Agent Native workspace: finding
+  version-matched framework docs and source, shared vs app-owned code, file and
+  blob storage, env and secrets, agent scratch files, and Dispatch Resources.
+  Use when working across workspace apps, storing files or credentials, or
+  looking up framework APIs.
+scope: dev
+---
+
+# Workspace Conventions
+
+The long-form detail behind the workspace `AGENTS.md` core rules. Read this
+before adding shared code, storing files or secrets, creating workspace
+resources, or looking up framework APIs.
+
+## Framework Docs Lookup
+
+Read `agent-native-docs` for the lookup workflow (`framework-search` first, then
+the focused `docs-search` / `source-search` readers, and the `rg` fallback).
+
+The workspace-specific slugs it does not list are `workspace` and
+`multi-app-workspace`. Feature flags and other specialized workflows are
+optional; read their skill only when the app uses them. Use package docs for framework APIs,
+the package corpus for reusable framework/template patterns, and this
+`AGENTS.md` plus `.agents/skills/` for workspace-specific conventions.
+
+Before building common workspace or agent UI, read `agent-native-toolkit` to
+inventory existing public kits and installed package seams. Read
+`customizing-agent-native` before adapting shared UI. Use the supported
+ladder: configure → compose → eject the smallest unit → propose a shared seam.
+Preview before `--apply`, commit `agent-native.ejections.json`, and never edit
+`node_modules` or eject protected runtime contracts.
+
+## Shared Conventions
+
+- All AI/LLM behavior goes through the app's agent chat. UI and server code
+  must not call model providers, AI SDK `generateText()` / `streamText()`, or
+  other inline LLM APIs directly. Use `sendToAgentChat()` for local app-agent
+  work, including hidden `context` and `submit: false` prefill/review flows.
+  Keep actions deterministic and focused. If a workflow is framed as research,
+  analysis, generation, recommendation, or synthesis, let the agent
+  orchestrate provider/data actions in the open AgentSidebar instead of hiding
+  the work in one opaque action or a separate follow-up textbox.
+  Only use `useAgentChatContext`, `setAgentChatContextItem`,
+  `listAgentChatContext`, `removeAgentChatContextItem`, and
+  `clearAgentChatContext` when UI needs two-way sync with staged context chips.
+  Read `.agents/skills/delegate-to-agent/SKILL.md` before building agent-driven
+  UI or "AI" features.
+- Put shared code in `packages/shared` only when multiple apps need it.
+- Keep app-specific screens, actions, state, and skills inside `apps/<app>`.
+- SQL is for structured records, metadata, references, and searchable text. Store
+  large files/blob payloads (base64, `data:` URLs, images, video/audio, PDFs,
+  ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
+  storage and persist only URLs, ids, or handles.
+- Store shared runtime configuration in the workspace root `.env`; use
+  `apps/<app>/.env` only for app-specific overrides. Never hardcode API keys,
+  tokens, webhook URLs, signing secrets, private Builder/internal data, customer
+  data, or credential-looking literals in source, docs, prompts, fixtures,
+  application state, action responses, or generated app content. Use
+  secrets/OAuth/runtime configuration and obvious placeholders in examples.
+- Each app deploys its own `/*` page function, and that function ships whatever
+  the app's server bundle depends on — including a dependency only a background
+  job uses. Before an app takes on a heavy runtime (headless browser, ffmpeg,
+  media processing, ML), read `.agents/skills/performance/SKILL.md` §9 and keep
+  that work in a background function or job. A dependency belonging to one app
+  does not belong in `packages/shared`.
+- Prefer framework defaults until the workspace has a real custom rule,
+  component, plugin, action, or skill to share.
+- Keep the Workspace files view for user-authored or user-requested resources.
+  Agents may create hidden `agent_scratch` resources for temporary working
+  notes, scripts, task plans, or intermediate outputs, but should promote them
+  to normal workspace visibility only when the user explicitly asks to keep or
+  manage the file.
+- Runtime-editable global resources can be managed from Dispatch Resources.
+  Use `AGENTS.md` or `instructions/<slug>.md` for always-on guardrails,
+  `skills/<slug>/SKILL.md` for workspace skills, `context/<slug>.md` for
+  personas/positioning/messaging/company facts/brand guidelines, and
+  `agents/<slug>.md` for custom agent profiles. Scope them to All apps when
+  every workspace app should inherit them. All-app resources are inherited at
+  runtime; do not copy or sync them into individual apps.
+
+## Related Skills
+
+- **adding-workspace-apps** — Creating and mounting a new app under `apps/`.
+- **agent-native-docs** — The full docs and source-corpus lookup workflow.
+- **agent-native-toolkit** — Inventory of shared workspace and agent UI.
+- **customizing-agent-native** — The configure → compose → eject ladder.
+- **delegate-to-agent** — Routing every AI feature through the agent chat.
+- **performance** — Load cost, and (§9) cold-start artifact size per app.
+- **secrets** — Registering API keys and service credentials.
+- **storing-data** — Where structured data and large payloads belong.

package/corpus/templates/tasks/app/components/custom-fields/FieldsPage.tsx

@@ -30,10 +30,7 @@ export function FieldsPage() {
 
   return (
     <div className="mx-auto flex h-full min-h-0 w-full max-w-5xl flex-col gap-6 overflow-hidden p-4 md:p-6">
-      <PageHeader
-        title={t("fields.pageTitle")}
-        description={t("fields.pageDescription")}
-      />
+      <PageHeader title={t("fields.pageTitle")} />
 
       <FieldsList
         activeFieldId={activeFieldId}

package/corpus/templates/tasks/app/components/inbox/InboxList.tsx

@@ -99,7 +99,6 @@ export function InboxList({
     <>
       <ListViewHeader
         title={t("inbox.pageTitle")}
-        description={t("inbox.pageDescription")}
         isPending={isPending}
         showSelectToggle={items.length > 0}
         selection={selection}

package/corpus/templates/tasks/app/components/inbox/InboxListPage.tsx

@@ -18,7 +18,6 @@ export function InboxListPage() {
         <>
           <ListViewHeader
             title={t("inbox.pageTitle")}
-            description={t("inbox.pageDescription")}
             isPending={false}
             showSelectToggle={false}
             selection={null}

package/corpus/templates/tasks/app/components/shared/ListViewHeader.tsx

@@ -9,7 +9,6 @@ import { Switch } from "@/components/ui/switch";
 
 export interface ListViewHeaderProps<T extends { id: string }> {
   title: string;
-  description: string;
   isPending: boolean;
   showSelectToggle: boolean;
   selection: ListSelection<T> | null;
@@ -21,7 +20,6 @@ export interface ListViewHeaderProps<T extends { id: string }> {
 
 export function ListViewHeader<T extends { id: string }>({
   title,
-  description,
   isPending,
   showSelectToggle,
   selection,
@@ -39,7 +37,6 @@ export function ListViewHeader<T extends { id: string }>({
   return (
     <PageHeader
       title={title}
-      description={description}
       actions={
         hasActions ? (
           <>

package/corpus/templates/tasks/app/components/shared/PageHeader.tsx

@@ -2,15 +2,13 @@ import type { ReactNode } from "react";
 
 export function PageHeader({
   title,
-  description,
   actions,
 }: {
   title: string;
-  description: string;
   actions?: ReactNode;
 }) {
   return (
-    <header className="shrink-0 space-y-1">
+    <header className="shrink-0">
       <div className="flex items-center justify-between gap-3">
         <h1 className="min-w-0 truncate text-2xl font-semibold tracking-tight">
           {title}
@@ -19,7 +17,6 @@ export function PageHeader({
           <div className="flex shrink-0 items-center gap-2">{actions}</div>
         ) : null}
       </div>
-      <p className="text-sm text-muted-foreground">{description}</p>
     </header>
   );
 }

package/corpus/templates/tasks/app/components/tasks/TaskList.tsx

@@ -186,7 +186,6 @@ export function TaskList({
         <div className="flex min-h-0 flex-col gap-6 overflow-hidden">
           <ListViewHeader
             title={t("tasks.pageTitle")}
-            description={t("tasks.pageDescription")}
             isPending={isPending}
             showSelectToggle={hasTasks}
             selection={selection}

package/corpus/templates/tasks/app/components/tasks/TaskListPage.tsx

@@ -87,7 +87,6 @@ export function TaskListPage() {
         <>
           <ListViewHeader
             title={t("tasks.pageTitle")}
-            description={t("tasks.pageDescription")}
             isPending={false}
             showSelectToggle={false}
             selection={null}

package/dist/agent/engine/ai-sdk-engine.js

@@ -422,6 +422,11 @@ class AISDKEngine {
             // A step can finish having announced a tool call it never delivered.
             // Assemble it from its deltas, or report it in-band, rather than ending
             // the turn as if the model never asked for it.
+            for (const part of assistantContent) {
+                if (part.type === "tool-call") {
+                    observeStreamedToolInput(toolInputs, part);
+                }
+            }
             for (const recovered of finalizeStreamedToolInputs(toolInputs, assistantContent.flatMap((part) => part.type === "tool-call" ? [part.id] : []))) {
                 if (recovered.type === "tool-call") {
                     assistantContent.push({

package/dist/agent/engine/anthropic-engine.js

@@ -169,6 +169,14 @@ class AnthropicEngine {
             }
             const finalMessage = await apiStream.finalMessage();
             const assistantContent = anthropicContentToEngine(finalMessage.content);
+            // The final content can carry the same tool call with an empty input
+            // even though the stream already delivered complete argument deltas.
+            // Reconcile that copy before marking its id delivered.
+            for (const part of assistantContent) {
+                if (part.type === "tool-call") {
+                    observeStreamedToolInput(toolInputs, part);
+                }
+            }
             // A tool call the stream announced but the final message never carried
             // would otherwise vanish, leaving the turn claiming an action it never
             // ran. Recover it from its deltas, or tell the model in-band.

package/dist/agent/engine/registry.js

@@ -574,9 +574,14 @@ async function apiKeyBelongsToDifferentProvider(apiKey, selectedEntry) {
     }
     return false;
 }
-async function engineCreateConfigForEntry(entry, apiKey, extra, preferResolvedCredential = false, apiKeyEnvVar, credentialIdentity) {
+async function engineCreateConfigForEntry(entry, apiKey, extra, credentialResolution = "explicit", apiKeyEnvVar, credentialIdentity) {
     const safeExtra = { ...(extra ?? {}) };
     let matchingApiKey = apiKey;
+    if (matchingApiKey === undefined &&
+        typeof safeExtra.apiKey === "string" &&
+        safeExtra.apiKey.trim()) {
+        matchingApiKey = safeExtra.apiKey;
+    }
     // A declared provenance settles the question without inspecting values: a
     // credential issued for another provider's env var is never this entry's
     // key, so drop it on explicit branches too. Value comparison below cannot
@@ -586,14 +591,14 @@ async function engineCreateConfigForEntry(entry, apiKey, extra, preferResolvedCr
         !entry.requiredEnvVars.includes(apiKeyEnvVar)) {
         matchingApiKey = undefined;
     }
-    // Automatic engine selection must also select that engine's credential.
-    // Callers historically passed one untagged "active" key before the registry
-    // chose an engine, which could hand an Anthropic key to an app-default
-    // OpenAI engine (or vice versa). Explicit engineOption branches retain their
-    // paired key. Automatic branches replace only a key proven to belong to a
-    // different configured provider; opaque caller-supplied keys keep the public
-    // `ResolveEngineConfig.apiKey` contract.
-    if (preferResolvedCredential &&
+    // Engine selection must also select that engine's credential. Callers
+    // historically passed one untagged "active" key before the registry chose
+    // an engine, which could hand an Anthropic key to an OpenAI engine (or vice
+    // versa). Explicit engine options can also arrive without a key when the
+    // owner resolver missed a shared vault row, so resolve those missing keys at
+    // this construction boundary too. Opaque caller-supplied keys remain intact
+    // unless they are proven to belong to another configured provider.
+    if ((credentialResolution === "automatic" || matchingApiKey === undefined) &&
         entry.name !== "builder" &&
         entry.requiredEnvVars.length > 0) {
         let resolvedMatchingCredential;
@@ -616,8 +621,8 @@ async function engineCreateConfigForEntry(entry, apiKey, extra, preferResolvedCr
         if (matchingApiKey === undefined || suppliedKeyBelongsElsewhere) {
             // Keep deploy-only credentials implicit so provider SDKs retain their
             // established env-fallback behavior. Scoped credentials must be passed
-            // explicitly. A proven different-provider key is replaced or cleared;
-            // an opaque caller-supplied key is preserved by the branch above.
+            // explicitly. Automatic selection replaces a proven
+            // different-provider key; an opaque explicit key is left untouched.
             matchingApiKey =
                 resolvedMatchingCredential && !matchingCredentialUsesDeployFallback
                     ? resolvedMatchingCredential
@@ -820,7 +825,7 @@ export async function resolveEngine(config) {
         if (!entry)
             throw new Error(`[agent-engine] Unknown engine: "${name}". Registered: ${[..._registry.keys()].join(", ")}`);
         assertAgentEnginePackageInstalled(entry);
-        return entry.create(await engineCreateConfigForEntry(entry, apiKey, engineConfig, false, apiKeyEnvVar, credentialIdentity));
+        return entry.create(await engineCreateConfigForEntry(entry, apiKey, engineConfig, "explicit", apiKeyEnvVar, credentialIdentity));
     }
     // 3. Explicit string name from options
     if (typeof engineOption === "string") {
@@ -828,7 +833,7 @@ export async function resolveEngine(config) {
         if (!entry)
             throw new Error(`[agent-engine] Unknown engine: "${engineOption}". Registered: ${[..._registry.keys()].join(", ")}`);
         assertAgentEnginePackageInstalled(entry);
-        return entry.create(await engineCreateConfigForEntry(entry, apiKey, undefined, false, apiKeyEnvVar, credentialIdentity));
+        return entry.create(await engineCreateConfigForEntry(entry, apiKey, undefined, "explicit", apiKeyEnvVar, credentialIdentity));
     }
     // 4. Env var — explicit engine name override
     const envEngine = process.env.AGENT_ENGINE;
@@ -836,7 +841,7 @@ export async function resolveEngine(config) {
         const entry = _registry.get(envEngine);
         if (entry) {
             assertAgentEnginePackageInstalled(entry);
-            return entry.create(await engineCreateConfigForEntry(entry, apiKey, undefined, true, apiKeyEnvVar, credentialIdentity));
+            return entry.create(await engineCreateConfigForEntry(entry, apiKey, undefined, "automatic", apiKeyEnvVar, credentialIdentity));
         }
     }
     const appDefault = await getAgentAppModelDefaultForCurrentRequest(appId);
@@ -846,7 +851,7 @@ export async function resolveEngine(config) {
             (await isStoredEngineUsableForRequest(appDefault, entry, {
                 credentialIdentity,
             }))) {
-            return entry.create(await engineCreateConfigForEntry(entry, apiKey, undefined, true, apiKeyEnvVar, credentialIdentity));
+            return entry.create(await engineCreateConfigForEntry(entry, apiKey, undefined, "automatic", apiKeyEnvVar, credentialIdentity));
         }
     }
     let stored = null;
@@ -873,25 +878,25 @@ export async function resolveEngine(config) {
             (await isStoredEngineUsableForRequest(storedRaw, entry, {
                 credentialIdentity,
             }))) {
-            return entry.create(await engineCreateConfigForEntry(entry, apiKey, stripInlineApiKeyConfig(storedConfig), true, apiKeyEnvVar, credentialIdentity));
+            return entry.create(await engineCreateConfigForEntry(entry, apiKey, stripInlineApiKeyConfig(storedConfig), "automatic", apiKeyEnvVar, credentialIdentity));
         }
     }
     if (detectedFromUser) {
-        return detectedFromUser.create(await engineCreateConfigForEntry(detectedFromUser, apiKey, undefined, true, apiKeyEnvVar, credentialIdentity));
+        return detectedFromUser.create(await engineCreateConfigForEntry(detectedFromUser, apiKey, undefined, "automatic", apiKeyEnvVar, credentialIdentity));
     }
     // 8. Auto-detect from any provider env var — so just dropping a key in
     // .env works without also setting AGENT_ENGINE. Skip keys with active
     // auth-failure markers so a rejected deploy key cannot permanently win.
     const detected = await detectEngineFromEnvForRequest();
     if (detected) {
-        return detected.create(await engineCreateConfigForEntry(detected, apiKey, undefined, true, apiKeyEnvVar, credentialIdentity));
+        return detected.create(await engineCreateConfigForEntry(detected, apiKey, undefined, "automatic", apiKeyEnvVar, credentialIdentity));
     }
     // 9. Default: anthropic
     const anthropicEntry = _registry.get("anthropic");
     if (!anthropicEntry) {
         throw new Error("[agent-engine] Default Anthropic engine is not registered. Did builtin.ts fail to load?");
     }
-    return anthropicEntry.create(await engineCreateConfigForEntry(anthropicEntry, apiKey, undefined, true, apiKeyEnvVar, credentialIdentity));
+    return anthropicEntry.create(await engineCreateConfigForEntry(anthropicEntry, apiKey, undefined, "automatic", apiKeyEnvVar, credentialIdentity));
 }
 /**
  * Read the user-selected model for an engine from the `agent-engine` setting.

package/dist/agent/engine/translate-anthropic.js

@@ -503,7 +503,19 @@ export function observeStreamedToolInput(state, event) {
         state.byId.set(id, { name: event.name ?? "", text, delivered: false });
         return;
     }
-    if (event.type === "tool-call" || event.type === "tool-call-error") {
+    if (event.type === "tool-call") {
+        // Non-empty terminal input remains authoritative. Some gateways emit the
+        // complete argument JSON as deltas but follow it with an empty terminal
+        // input, so recover the already-complete stream in that case.
+        if (isEmptyToolInput(event.input)) {
+            const streamedInput = parseStreamedToolInput(state.byId.get(event.id)?.text ?? "");
+            if (streamedInput !== undefined)
+                event.input = streamedInput;
+        }
+        markStreamedToolInputDelivered(state, event.id);
+        return;
+    }
+    if (event.type === "tool-call-error") {
         markStreamedToolInputDelivered(state, event.id);
     }
 }
@@ -555,6 +567,9 @@ function parseStreamedToolInput(text) {
         return undefined;
     }
 }
+function isEmptyToolInput(input) {
+    return input == null || (isRecord(input) && Object.keys(input).length === 0);
+}
 // ---------------------------------------------------------------------------
 // Build tool_result blocks to append to messages after tool dispatch
 // ---------------------------------------------------------------------------

package/dist/agent/production-agent.d.ts

@@ -235,6 +235,14 @@ export interface ActionEntry {
      * `needsApproval` option. See `packages/core/docs/content/actions.mdx`.
      */
     needsApproval?: boolean | ((args: any, ctx?: import("../action.js").ActionRunContext) => boolean | Promise<boolean>);
+    /**
+     * The action hands control back to the user: once it succeeds the loop stops
+     * the turn instead of asking the model for another step, and any remaining
+     * tool calls in the same assistant message do not execute. Only for actions
+     * whose whole purpose is to wait on a human (`ask-question`) — telling the
+     * model to stop in the tool result does not make it stop.
+     */
+    endsTurn?: boolean;
     /** Which framework tool group contributed this action. Set by the framework,
      *  never by an app: apps own their action names, and a tagged action is one
      *  the app can switch off wholesale through `frameworkTools`. Tagged actions

package/dist/agent/production-agent.js

@@ -3823,6 +3823,23 @@ export async function runAgentLoop(opts) {
         emptyFinalResponseRetries = 0;
         flushUnstreamedAssistantText();
         let requestedActionStop = null;
+        // An `endsTurn` action ran and handed control to the user. Distinct from
+        // `requestedActionStop`, which also covers failure stops that must not
+        // suppress the remaining tool calls.
+        let turnYieldedToUser = false;
+        // Called by every path that completes a tool call successfully — a fresh
+        // invocation, a journal replay, a ledger recovery. A replayed
+        // `ask-question` that skipped this would let the resumed run ask a second
+        // time over the card the user is already looking at.
+        const noteToolCallSucceeded = (actionEntry) => {
+            if (actionEntry.endsTurn !== true)
+                return;
+            turnYieldedToUser = true;
+            requestedActionStop ??= {
+                message: "Waiting for your answer before continuing.",
+                errorCode: "awaiting-user-input",
+            };
+        };
         const noteRepeatedToolCall = (toolName, input) => {
             const key = toolCallCacheKey(toolName, input);
             const count = (repeatedToolCalls.get(key) ?? 0) + 1;
@@ -4167,6 +4184,7 @@ export async function runAgentLoop(opts) {
                         completedSideEffect: true,
                     });
                     recordToolResult(result, false);
+                    noteToolCallSucceeded(actionEntry);
                     return {
                         type: "tool-result",
                         toolCallId: toolCall.id,
@@ -4220,6 +4238,7 @@ export async function runAgentLoop(opts) {
                             ...(actionEntry.chatUI ? { chatUI: actionEntry.chatUI } : {}),
                         });
                         recordToolResult(result, false);
+                        noteToolCallSucceeded(actionEntry);
                         return {
                             type: "tool-result",
                             toolCallId: toolCall.id,
@@ -4645,6 +4664,7 @@ export async function runAgentLoop(opts) {
                 });
                 recordToolResult(result, isError);
                 if (!isError) {
+                    noteToolCallSucceeded(actionEntry);
                     if (cacheKey) {
                         readOnlyToolResultCache.set(cacheKey, result);
                     }
@@ -4715,7 +4735,46 @@ export async function runAgentLoop(opts) {
             parallelBatchKind = null;
             toolResultParts.push(...(await Promise.all(batch.map(runToolCall))));
         };
+        // An `endsTurn` action already handed control to the user, so the rest of
+        // this assistant message belongs to a turn that is over. Report those calls
+        // as not executed rather than running them: a second `ask-question` would
+        // overwrite the first one's card before anyone could answer it.
+        const skipToolCallAfterYield = (toolCall) => {
+            const result = `Not executed: ${toolCall.name} was called after an action that ends the turn. ` +
+                `The turn is paused for the user's answer — call it again on a later turn if still needed.`;
+            send({
+                type: "tool_start",
+                id: toolCall.id,
+                tool: toolCall.name,
+                input: toolCall.input,
+            });
+            send({
+                type: "tool_done",
+                id: toolCall.id,
+                tool: toolCall.name,
+                input: toolCall.input,
+                result,
+                completedSideEffect: false,
+            });
+            toolResultHistory.push({
+                name: toolCall.name,
+                content: result,
+                isError: false,
+            });
+            return {
+                type: "tool-result",
+                toolCallId: toolCall.id,
+                toolName: toolCall.name,
+                toolInput: JSON.stringify(toolCall.input ?? {}),
+                content: result,
+            };
+        };
         for (const toolCall of toolCallParts) {
+            if (turnYieldedToUser) {
+                await flushParallelBatch();
+                toolResultParts.push(skipToolCallAfterYield(toolCall));
+                continue;
+            }
             const batchKind = getParallelBatchKind(toolCall);
             if (batchKind) {
                 if (parallelBatchKind && parallelBatchKind !== batchKind) {
@@ -4829,6 +4888,13 @@ export async function runAgentLoop(opts) {
             message: terminalActionStop.message,
         });
     }
+    else if (terminalActionStop?.errorCode === "awaiting-user-input") {
+        reportOutcome({
+            state: "input_required",
+            code: "awaiting_user_input",
+            message: terminalActionStop.message,
+        });
+    }
     else if (terminalActionStop) {
         reportOutcome({
             state: "failed",

package/dist/automations/service.d.ts

@@ -1,6 +1,8 @@
 import { type JobFrontmatter } from "../jobs/frontmatter.js";
 import { type Resource } from "../resources/store.js";
 export type AutomationScope = "personal" | "organization";
+/** Conservative default for new scheduled automations when no cadence is given. */
+export declare const DEFAULT_AUTOMATION_SCHEDULE = "0 * * * *";
 export interface AutomationActor {
     userEmail: string;
     orgId?: string | null;