@agent-native/core 0.204.0 → 0.204.1-nightly-20261008034100

package/dist/action.js

@@ -82,9 +82,13 @@ export const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
 export const MCP_APP_RESOURCE_URI_META_KEY = "ui/resourceUri";
 export function defineAction(options) {
     const hasSchema = options.schema && "~standard" in options.schema;
+    // Converting a schema to JSON Schema is the dominant module-scope cost of an
+    // action-heavy app's cold start, so convert only the schema the agent sees.
     let toolParameters;
     if (hasSchema) {
-        toolParameters = schemaToJsonSchema(options.schema, options.description);
+        toolParameters = schemaToJsonSchema(options.agentInputSchema && "~standard" in options.agentInputSchema
+            ? options.agentInputSchema
+            : options.schema, options.description);
     }
     else if (options.parameters) {
         toolParameters = {
@@ -92,11 +96,6 @@ export function defineAction(options) {
             properties: options.parameters,
         };
     }
-    if (hasSchema &&
-        options.agentInputSchema &&
-        "~standard" in options.agentInputSchema) {
-        toolParameters = schemaToJsonSchema(options.agentInputSchema, options.description);
-    }
     const guardedRun = typeof options.authorize === "function" || options.access
         ? wrapRunWithAccess(options.run, options.access, options.authorize)
         : options.run;

package/dist/agent/auto-continue.d.ts

@@ -13,6 +13,12 @@ export declare const MAX_AUTO_CONTINUES_PER_TURN = 3;
 export declare const AUTO_CONTINUE_FRESHNESS_MS: number;
 /** Request metadata naming the stopped run an automatic continuation resumes. */
 export declare const AUTO_CONTINUE_OF_RUN_METADATA_KEY = "agentNativeAutoContinueOfRunId";
+/**
+ * Request metadata naming the stopped run a person chose to continue. Like an
+ * automatic continuation it stays in the stopped run's turn, so the turn's
+ * journal of finished steps keeps applying; unlike one it has no cap.
+ */
+export declare const CONTINUE_OF_RUN_METADATA_KEY = "agentNativeContinueOfRunId";
 export declare const AUTO_CONTINUE_PROMPT = "Continue from where you left off.";
 export declare const AUTO_CONTINUE_REFUSAL_CODES: readonly [
 /** The turn used its automatic continuations, or its wall-clock budget. */
@@ -20,6 +26,11 @@ export declare const AUTO_CONTINUE_REFUSAL_CODES: readonly [
 /** The named run is not the turn's newest fresh time-limit stop. */
 "auto_continue_unavailable"];
 export type AutoContinueRefusalCode = (typeof AUTO_CONTINUE_REFUSAL_CODES)[number];
+/** The named run is not the turn's newest run, or it did not stop unfinished. */
+export declare const CONTINUE_UNAVAILABLE_CODE = "continue_unavailable";
+export type ContinueRefusalCode = AutoContinueRefusalCode | typeof CONTINUE_UNAVAILABLE_CODE;
+/** Who asked to continue a stopped run. */
+export type ContinueTrigger = "auto" | "manual";
 /**
  * The only stops a turn continues from on its own: the server cut the run at
  * its time limit. Errors, stops, cancellations, refusals, and credential or
@@ -29,6 +40,15 @@ export declare function isTimeLimitStop(run: {
     readonly status: string;
     readonly terminalReason?: string | null;
 }): boolean;
+/**
+ * A run that ended before it finished for any reason other than a person
+ * stopping it: a time limit, a crash, or an error. These are the runs a
+ * person can continue in the same turn.
+ */
+export declare function isUnfinishedStop(run: {
+    readonly status: string;
+    readonly terminalReason?: string | null;
+}): boolean;
 /** A turn as its run rows record it; the rows are the durable count. */
 export interface TurnRunState {
     readonly newest: {
@@ -55,3 +75,18 @@ export declare function admitAutoContinue(input: {
     admit: false;
     code: AutoContinueRefusalCode;
 };
+/**
+ * Whether a person may continue `stoppedRunId` in its own turn. Only the
+ * thread's newest stop qualifies: once anything newer ran, in this turn or a
+ * later one, continuing the older stop would redo work that already moved on.
+ */
+export declare function admitManualContinue(input: {
+    readonly turn: TurnRunState | null;
+    readonly stoppedRunId: string;
+    readonly laterTurnStarted: boolean;
+}): {
+    admit: true;
+} | {
+    admit: false;
+    code: ContinueRefusalCode;
+};

package/dist/agent/auto-continue.js

@@ -1,4 +1,5 @@
 import { MAX_TURN_WALL_CLOCK_MS } from "../app-config/run-lifecycle-invariants.js";
+import { isRequestedStopAbortReason } from "./abort-reasons.js";
 /**
  * Automatic continuations of one user turn after the server stopped it at its
  * run time limit. Each one replays the turn's context to the model and runs up
@@ -14,6 +15,12 @@ export const MAX_AUTO_CONTINUES_PER_TURN = 3;
 export const AUTO_CONTINUE_FRESHNESS_MS = 10 * 60_000;
 /** Request metadata naming the stopped run an automatic continuation resumes. */
 export const AUTO_CONTINUE_OF_RUN_METADATA_KEY = "agentNativeAutoContinueOfRunId";
+/**
+ * Request metadata naming the stopped run a person chose to continue. Like an
+ * automatic continuation it stays in the stopped run's turn, so the turn's
+ * journal of finished steps keeps applying; unlike one it has no cap.
+ */
+export const CONTINUE_OF_RUN_METADATA_KEY = "agentNativeContinueOfRunId";
 // i18n-ignore: Internal continuation instruction sent to the agent, never shown as product copy.
 export const AUTO_CONTINUE_PROMPT = "Continue from where you left off.";
 export const AUTO_CONTINUE_REFUSAL_CODES = [
@@ -22,6 +29,8 @@ export const AUTO_CONTINUE_REFUSAL_CODES = [
     /** The named run is not the turn's newest fresh time-limit stop. */
     "auto_continue_unavailable",
 ];
+/** The named run is not the turn's newest run, or it did not stop unfinished. */
+export const CONTINUE_UNAVAILABLE_CODE = "continue_unavailable";
 /**
  * The only stops a turn continues from on its own: the server cut the run at
  * its time limit. Errors, stops, cancellations, refusals, and credential or
@@ -30,6 +39,19 @@ export const AUTO_CONTINUE_REFUSAL_CODES = [
 export function isTimeLimitStop(run) {
     return run.status === "truncated" && run.terminalReason === "run_timeout";
 }
+/**
+ * A run that ended before it finished for any reason other than a person
+ * stopping it: a time limit, a crash, or an error. These are the runs a
+ * person can continue in the same turn.
+ */
+export function isUnfinishedStop(run) {
+    if (run.status === "truncated" || run.status === "errored")
+        return true;
+    if (run.status !== "aborted")
+        return false;
+    const reason = run.terminalReason?.trim() ?? "";
+    return !isRequestedStopAbortReason(reason.startsWith("aborted:") ? reason.slice("aborted:".length) : reason);
+}
 /**
  * Whether the turn may start another run that continues `stoppedRunId`. Read
  * from the turn's rows, so a reload or a second tab gets the same answer.
@@ -51,3 +73,19 @@ export function admitAutoContinue(input) {
     }
     return { admit: true };
 }
+/**
+ * Whether a person may continue `stoppedRunId` in its own turn. Only the
+ * thread's newest stop qualifies: once anything newer ran, in this turn or a
+ * later one, continuing the older stop would redo work that already moved on.
+ */
+export function admitManualContinue(input) {
+    const newest = input.turn?.newest;
+    if (input.laterTurnStarted ||
+        !newest ||
+        newest.id !== input.stoppedRunId ||
+        newest.completedAt === null ||
+        !isUnfinishedStop(newest)) {
+        return { admit: false, code: CONTINUE_UNAVAILABLE_CODE };
+    }
+    return { admit: true };
+}

package/dist/agent/connection-required-note.d.ts

@@ -0,0 +1,52 @@
+import type { AgentChatEvent } from "./types.js";
+type ConnectionRequired = Extract<AgentChatEvent, {
+    type: "connection_required";
+}>;
+/** A connection request's message, plus who can unblock it when that is known. */
+export declare function connectionRequiredMessage(message: string, reason: ConnectionRequired["reason"]): string;
+export interface ThreadConnectionRequest {
+    request: ConnectionRequired;
+    /** How many of the thread's newer runs came after the one that asked. */
+    runsAgo: number;
+}
+/**
+ * The connection requests among a thread's recent runs for one organization
+ * (`null` for none), newest first. Provider connections are per organization
+ * and a thread can be reused across them, so another org's request is neither
+ * a note nor a slot in the window. The turn's initiator row is the only record
+ * of a run's org, so a run without one has no provable org and is left out.
+ * Throws when the ledger can't be read.
+ */
+export declare function readThreadConnectionRequests(threadId: string, options: {
+    orgId: string | null;
+    excludeRunId?: string;
+}): Promise<ThreadConnectionRequest[]>;
+export type PriorConnectionNote = {
+    status: "none";
+} | {
+    status: "connected";
+} | {
+    status: "blocked";
+    note: string;
+} | {
+    status: "unreadable";
+    error: string;
+};
+/** The context note a resolved state adds to the turn, or "" when it adds none. */
+export declare function priorConnectionContextNote(prior: PriorConnectionNote): string;
+/**
+ * The note that keeps a thread's next run from retrying a provider whose
+ * connection request ended an earlier run in the same organization. A request
+ * drops out once a workspace connection for that provider is available again,
+ * or, when nothing can re-check it, after a couple of runs. A ledger that can't
+ * be read in time is reported rather than read as "no request".
+ */
+export declare function resolvePriorConnectionNote(input: {
+    threadId: string;
+    /** The current run's organization; `null` when it has none. */
+    orgId: string | null;
+    appId?: string;
+    excludeRunId?: string;
+    timeoutMs?: number;
+}): Promise<PriorConnectionNote>;
+export {};

package/dist/agent/connection-required-note.js

@@ -0,0 +1,187 @@
+import { getDbExec } from "../db/client.js";
+import { resolveWorkspaceConnectionForApp } from "../workspace-connections/store.js";
+import { ensureRunTables } from "./run-store.js";
+/**
+ * A run that ended `connection_required` leaves no mark on its `agent_runs`
+ * row, so the event ledger is the only durable record. The lookup is bounded
+ * by run count and age so it stays cheap and an old request ages out. Turn-abort
+ * marker rows are bookkeeping, not runs, and must not use up the window.
+ */
+const CONNECTION_REQUEST_RUN_WINDOW = 8;
+const CONNECTION_REQUEST_MAX_AGE_MS = 6 * 60 * 60 * 1000;
+const MAX_REQUEST_EVENT_ROWS = 16;
+/** A request nothing can re-check outlives only this many runs. */
+const UNVERIFIABLE_REQUEST_RUNS = 2;
+const MAX_NOTE_PROVIDERS = 3;
+/** Longer than this and the read costs the user more than the note saves. */
+const PRIOR_CONNECTION_READ_TIMEOUT_MS = 400;
+const REMEDY_BY_REASON = {
+    connect: "If you cannot connect it yourself, ask a workspace admin to connect it for the workspace.",
+    grant: "Ask a workspace admin to grant this app access to the existing connection.",
+    admin_required: "Only a workspace admin can do this; ask one to connect it.",
+};
+/** A connection request's message, plus who can unblock it when that is known. */
+export function connectionRequiredMessage(message, reason) {
+    const remedy = REMEDY_BY_REASON[reason];
+    if (!remedy || /workspace admin/i.test(message))
+        return message;
+    return `${message} ${remedy}`;
+}
+/**
+ * Provider ids come from provider adapters and A2A peers, and the note lands in
+ * the user turn. Quoting or stripping a free-text name makes the note's shape
+ * safe, not its content, so only a plain identifier is ever echoed; anything
+ * else is "an external provider".
+ */
+const PROVIDER_ID = /^[A-Za-z0-9][\w.:-]{0,63}$/;
+const UNNAMED_PROVIDER = "an external provider";
+function noteProviderName(request) {
+    return typeof request.provider === "string" &&
+        PROVIDER_ID.test(request.provider)
+        ? `"${request.provider}"`
+        : UNNAMED_PROVIDER;
+}
+/**
+ * The connection requests among a thread's recent runs for one organization
+ * (`null` for none), newest first. Provider connections are per organization
+ * and a thread can be reused across them, so another org's request is neither
+ * a note nor a slot in the window. The turn's initiator row is the only record
+ * of a run's org, so a run without one has no provable org and is left out.
+ * Throws when the ledger can't be read.
+ */
+export async function readThreadConnectionRequests(threadId, options) {
+    await ensureRunTables();
+    const db = getDbExec();
+    const { rows: runRows } = await db.execute({
+        sql: `SELECT r.id FROM agent_runs r
+          JOIN agent_turn_initiators i
+            ON i.thread_id = r.thread_id
+           AND i.turn_id = COALESCE(r.turn_id, r.id)
+          WHERE r.thread_id = ?
+            AND r.started_at >= ?
+            AND r.dispatch_mode IS DISTINCT FROM 'turn-abort'
+            AND r.id <> ?
+            AND ${options.orgId ? "i.org_id = ?" : "i.org_id IS NULL"}
+          ORDER BY r.started_at DESC
+          LIMIT ?`,
+        args: [
+            threadId,
+            Date.now() - CONNECTION_REQUEST_MAX_AGE_MS,
+            options.excludeRunId ?? "",
+            ...(options.orgId ? [options.orgId] : []),
+            CONNECTION_REQUEST_RUN_WINDOW,
+        ],
+    });
+    const runIds = runRows.map((row) => row.id);
+    if (runIds.length === 0)
+        return [];
+    const { rows } = await db.execute({
+        sql: `SELECT run_id, event_data
+          FROM agent_run_events
+          WHERE run_id IN (${runIds.map(() => "?").join(", ")})
+            AND event_data LIKE '{"type":"connection_required"%' /* guard:allow-blob-predicate — scoped to one thread's last 8 runs in 6h by the (run_id, seq) key; the marker has no column of its own, so a column plus backfill is the follow-up */
+          ORDER BY event_at DESC NULLS LAST, seq DESC
+          LIMIT ?`,
+        args: [...runIds, MAX_REQUEST_EVENT_ROWS],
+    });
+    const found = [];
+    for (const row of rows) {
+        if (!row.event_data)
+            continue;
+        const request = JSON.parse(row.event_data);
+        if (request.type === "connection_required") {
+            found.push({ request, runsAgo: runIds.indexOf(row.run_id) });
+        }
+    }
+    return found.sort((a, b) => a.runsAgo - b.runsAgo);
+}
+const PRIOR_CONNECTION_UNREADABLE_NOTE = "\n\n<context-note>Prior-run connection state could not be read this turn; if a provider call returns connection_required, stop and tell the user instead of retrying.</context-note>";
+/** The context note a resolved state adds to the turn, or "" when it adds none. */
+export function priorConnectionContextNote(prior) {
+    if (prior.status === "blocked")
+        return prior.note;
+    if (prior.status === "unreadable")
+        return PRIOR_CONNECTION_UNREADABLE_NOTE;
+    return "";
+}
+// `request.detail` and `source.label` are peer-supplied free text: stripping
+// characters does not make an instruction inert, so neither reaches the note.
+function priorConnectionNote(requests) {
+    const many = requests.length > 1;
+    return (`\n\n<context-note>${requests.map(noteProviderName).join(", ")} ${many ? "were" : "was"} not connected for this workspace when last tried in this thread. ` +
+        `Do not call ${many ? "them" : "it"} again unless the user says ${many ? "they are" : "it is"} now connected; use another connected source that can answer the request, or tell the user who can connect ${many ? "them" : "it"}.</context-note>`);
+}
+async function resolveNote(input) {
+    const appIdFor = (request) => request.appId ?? input.appId;
+    const canRecheck = (request) => request.source?.kind === "workspace_connection" && !!appIdFor(request);
+    // One entry per named provider, newest first: each run's failure names a
+    // different provider, and a note about only the latest sends the model to
+    // the one before it. Providers with no plain id share one unnamed entry.
+    const seen = new Set();
+    const candidates = (await readThreadConnectionRequests(input.threadId, {
+        orgId: input.orgId,
+        excludeRunId: input.excludeRunId,
+    }))
+        .filter(({ request }) => {
+        const key = noteProviderName(request).toLowerCase();
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    })
+        .filter(({ request, runsAgo }) => canRecheck(request) || runsAgo < UNVERIFIABLE_REQUEST_RUNS)
+        .slice(0, MAX_NOTE_PROVIDERS);
+    if (candidates.length === 0)
+        return { status: "none" };
+    const stillBlocked = await Promise.all(candidates.map(async ({ request }) => {
+        if (!canRecheck(request))
+            return true;
+        try {
+            const resolved = await resolveWorkspaceConnectionForApp({
+                appId: appIdFor(request),
+                provider: request.provider,
+                requireConnected: true,
+            });
+            return !resolved.available;
+        }
+        catch (error) {
+            console.warn("[agent-chat] could not re-check workspace connection; keeping the earlier request:", error instanceof Error ? error.message : String(error));
+            return true;
+        }
+    }));
+    const blocked = candidates.filter((_, index) => stillBlocked[index]);
+    if (blocked.length === 0)
+        return { status: "connected" };
+    return {
+        status: "blocked",
+        note: priorConnectionNote(blocked.map(({ request }) => request)),
+    };
+}
+/**
+ * The note that keeps a thread's next run from retrying a provider whose
+ * connection request ended an earlier run in the same organization. A request
+ * drops out once a workspace connection for that provider is available again,
+ * or, when nothing can re-check it, after a couple of runs. A ledger that can't
+ * be read in time is reported rather than read as "no request".
+ */
+export async function resolvePriorConnectionNote(input) {
+    const timeoutMs = input.timeoutMs ?? PRIOR_CONNECTION_READ_TIMEOUT_MS;
+    const unreadable = (error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn("[agent-chat] prior connection request unreadable:", message);
+        return { status: "unreadable", error: message };
+    };
+    let timer;
+    const timedOut = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(unreadable(`timed out after ${timeoutMs}ms`)), timeoutMs);
+    });
+    try {
+        return await Promise.race([resolveNote(input), timedOut]);
+    }
+    catch (error) {
+        return unreadable(error);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/agent/jev-tool-prefetch.d.ts

@@ -35,7 +35,11 @@ export interface JevRankCandidatesOptions {
     timeoutMs?: number;
 }
 export interface JevCandidateRanking {
-    status: "selected" | "no-match" | "unavailable";
+    /**
+     * `unavailable` means there was nothing to rank against (no key, no
+     * candidates); `failed` and `timed_out` mean a ranking was attempted and lost.
+     */
+    status: "selected" | "no-match" | "unavailable" | "failed" | "timed_out";
     ids: string[];
 }
 export declare function buildJevRequestContext(input: {

package/dist/agent/jev-tool-prefetch.js

@@ -104,11 +104,13 @@ export async function rankJevCandidatesWithStatus(options) {
     const builderAuth = options.builderAuth;
     if (!request ||
         (!apiKey && !builderAuth) ||
-        options.candidates.length === 0 ||
-        options.signal?.aborted ||
-        (options.timeoutMs !== undefined && options.timeoutMs <= 0)) {
+        options.candidates.length === 0) {
         return { status: "unavailable", ids: [] };
     }
+    if (options.signal?.aborted ||
+        (options.timeoutMs !== undefined && options.timeoutMs <= 0)) {
+        return { status: "timed_out", ids: [] };
+    }
     const candidates = shortlistJevCandidates(request, options.candidates);
     if (candidates.length === 0)
         return { status: "unavailable", ids: [] };
@@ -161,7 +163,7 @@ export async function rankJevCandidatesWithStatus(options) {
             !Number.isFinite(noMatchProbability) ||
             noMatchProbability < 0 ||
             noMatchProbability > 1) {
-            return { status: "unavailable", ids: [] };
+            return { status: "failed", ids: [] };
         }
         for (const candidate of candidates) {
             const probability = probabilities[candidate.id];
@@ -170,7 +172,7 @@ export async function rankJevCandidatesWithStatus(options) {
                     !Number.isFinite(probability) ||
                     probability < 0 ||
                     probability > 1)) {
-                return { status: "unavailable", ids: [] };
+                return { status: "failed", ids: [] };
             }
         }
         const ids = candidates
@@ -191,9 +193,20 @@ export async function rankJevCandidatesWithStatus(options) {
         if (error instanceof OptionalPeerDependencyError)
             throw error;
         console.warn("[agent] Jev context prefetch unavailable; continuing with the existing context.", error instanceof Error ? error.message : "unknown error");
-        return { status: "unavailable", ids: [] };
+        return {
+            status: isJevTimeout(error, options.signal) ? "timed_out" : "failed",
+            ids: [],
+        };
     }
 }
+function isJevTimeout(error, signal) {
+    if (signal?.aborted)
+        return true;
+    return (error instanceof Error &&
+        (error.name === "AbortError" ||
+            error.name === "TimeoutError" ||
+            /\btime(?:d)?[ -]?out\b/i.test(error.message)));
+}
 export function shortlistJevCandidates(request, candidates) {
     if (candidates.length <= MAX_JEV_CANDIDATES)
         return [...candidates];

package/dist/agent/previous-turn-note.d.ts

@@ -0,0 +1,9 @@
+/**
+ * What a new turn needs to know when the turn before it stopped unfinished.
+ * A new turn sees earlier turns as text only, and a turn cut off mid-tool may
+ * have no text at all, so without this a "continue" redoes every step. The
+ * record comes from the run ledger, which a crash cannot lose the way it can
+ * lose the thread's saved reply. Null when the previous turn finished, never
+ * started, or ran no tools; a caution, not null, when that cannot be read.
+ */
+export declare function loadStoppedPreviousTurnNote(threadId: string, turnId: string): Promise<string | null>;

package/dist/agent/previous-turn-note.js

@@ -0,0 +1,48 @@
+import { captureError } from "../server/capture-error.js";
+import { loadPriorTurnToolCallJournal } from "./engine/tool-call-journal-seed.js";
+import { getPreviousTurnNewestRun } from "./run-store.js";
+import { buildResumeJournalNote } from "./tool-call-journal.js";
+// i18n-ignore: Internal model context, never shown as product copy.
+const STOPPED_TURN_INTRO = "Your previous reply in this conversation stopped before it finished, so the history above does not show the tool calls it made. Unless the user asks you to redo something, treat the record below as what already happened and do not repeat a completed step.";
+// i18n-ignore: Internal model context, never shown as product copy.
+const STOPPED_TURN_UNREADABLE = "Your previous reply in this conversation stopped before it finished, and its record of tool calls could not be read. Some of its actions may already have run: before repeating anything with a side effect (sending, charging, creating, deleting), check whether it already happened.";
+// i18n-ignore: Internal model context, never shown as product copy.
+const PREVIOUS_TURN_UNCHECKED = "Whether your previous reply in this conversation finished could not be checked. Before repeating anything with a side effect (sending, charging, creating, deleting), check whether it already happened.";
+/**
+ * What a new turn needs to know when the turn before it stopped unfinished.
+ * A new turn sees earlier turns as text only, and a turn cut off mid-tool may
+ * have no text at all, so without this a "continue" redoes every step. The
+ * record comes from the run ledger, which a crash cannot lose the way it can
+ * lose the thread's saved reply. Null when the previous turn finished, never
+ * started, or ran no tools; a caution, not null, when that cannot be read.
+ */
+export async function loadStoppedPreviousTurnNote(threadId, turnId) {
+    let previous;
+    try {
+        previous = await getPreviousTurnNewestRun(threadId, turnId);
+    }
+    catch (error) {
+        captureError(error, {
+            tags: { source: "agent-chat", failureClass: "previous-turn-note" },
+            extra: { threadId, turnId },
+        });
+        return `<previous-turn-stopped>
+${PREVIOUS_TURN_UNCHECKED}
+</previous-turn-stopped>`;
+    }
+    if (!previous ||
+        previous.status === "completed" ||
+        previous.status === "running") {
+        return null;
+    }
+    const journal = await loadPriorTurnToolCallJournal(threadId, previous.turnId);
+    if (journal.status === "unreadable") {
+        return `<previous-turn-stopped>\n${STOPPED_TURN_UNREADABLE}\n</previous-turn-stopped>`;
+    }
+    const record = journal.toolCallJournal
+        ? buildResumeJournalNote(journal.toolCallJournal)
+        : null;
+    return record
+        ? `<previous-turn-stopped>\n${STOPPED_TURN_INTRO}\n\n${record}\n</previous-turn-stopped>`
+        : null;
+}

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

@@ -9,6 +9,7 @@ import { type JevPromptContextCandidate } from "../server/agent-chat/prompt-reso
 import { type BuilderGatewayAuth } from "../server/credential-provider.js";
 import { fireInternalDispatch } from "../server/self-dispatch.js";
 import { type RefusedTurnRetryContext } from "../shared/agent-chat-run-not-started.js";
+import { type ContextStatus } from "../shared/context-status.js";
 import { type ReasoningEffort } from "../shared/reasoning-effort.js";
 import type { TrackingMeta } from "../tracking/registry.js";
 import { type ResolveEngineConfig } from "./engine/index.js";
@@ -171,6 +172,8 @@ export interface ActionEntry {
     deferLoading?: boolean;
     publicAgent?: import("../action.js").PublicAgentActionConfig;
     readOnly?: boolean;
+    /** Bookkeeping writes still need replay protection, but cannot confirm automation work. */
+    confirmsAutomationWork?: boolean;
     grounding?: boolean;
     allowInPlanMode?: boolean;
     planMode?: import("../action.js").ActionPlanModeConfig<any>;
@@ -238,6 +241,19 @@ export declare function createPlanModeActionRegistry(actions: Record<string, Act
 type AgentRunTrackingSource = Pick<TrackingMeta, "userId" | "authUserId" | "anonymousId" | "sessionId"> & {
     isSyntheticTraffic?: boolean;
 };
+export interface PreparedAgentRequest {
+    message?: string;
+    displayMessage?: string;
+    attachments?: AgentChatAttachment[];
+    jevPromptCandidates?: JevPromptContextCandidate[];
+    jevFallbackCandidateIds?: string[];
+    /**
+     * Whether the app's own reference retrieval reached the model. Omit it to
+     * report nothing; `timed_out` and `failed` tell the model it is working
+     * without references it would normally have.
+     */
+    status?: ContextStatus;
+}
 export interface ProductionAgentOptions {
     actions?: Record<string, ActionEntry>;
     /** @deprecated Use `actions` instead */
@@ -301,19 +317,7 @@ export interface ProductionAgentOptions {
         dispatchToBackground: boolean;
         isBackgroundWorker?: boolean;
         mode: AgentExecutionMode;
-    }) => void | {
-        message?: string;
-        displayMessage?: string;
-        attachments?: AgentChatAttachment[];
-        jevPromptCandidates?: JevPromptContextCandidate[];
-        jevFallbackCandidateIds?: string[];
-    } | Promise<void | {
-        message?: string;
-        displayMessage?: string;
-        attachments?: AgentChatAttachment[];
-        jevPromptCandidates?: JevPromptContextCandidate[];
-        jevFallbackCandidateIds?: string[];
-    }>;
+    }) => void | PreparedAgentRequest | Promise<void | PreparedAgentRequest>;
     resolveActionSurface?: (details: AgentActionSurfaceDetails) => AgentActionSurfaceResolution | Promise<AgentActionSurfaceResolution>;
     runSoftTimeoutMs?: number;
     runNoProgressTimeoutMs?: number;