@agent-native/core 0.153.4 → 0.153.6

package/dist/action.js

@@ -164,6 +164,9 @@ export function defineAction(options) {
             : {}),
         ...(typeof agentTool === "boolean" ? { agentTool } : {}),
         ...(typeof readOnly === "boolean" ? { readOnly } : {}),
+        ...(typeof options.grounding === "boolean"
+            ? { grounding: options.grounding }
+            : {}),
         ...(typeof options.allowInPlanMode === "boolean"
             ? { allowInPlanMode: options.allowInPlanMode }
             : {}),

package/dist/agent/engine/tool-call-journal-seed.d.ts

@@ -12,9 +12,33 @@ export interface PriorTurnToolCallSummary {
  * `PriorTurnToolCallSummary` for why this is a local shape, not an import. */
 export interface PriorTurnToolResultSummary {
     name: string;
+    /**
+     * Input of the `tool_start` this result was matched to, so the caller can
+     * rebuild the same `(tool, arguments)` breaker key its live counters use.
+     * Legacy `tool_done` events carry no input; those keep the positional
+     * FIFO-per-tool pairing documented in `tool-call-journal.ts`, so this is
+     * absent only when neither event carried one.
+     */
+    input?: unknown;
     content: string;
     isError: boolean;
 }
+/**
+ * Outcome of reading the per-turn ledger. `unreadable` is deliberately NOT the
+ * same value as a turn with no history: the repetition ledger, the read-only
+ * result cache and the write-replay hard block are all seeded from this read,
+ * so a swallowed ledger failure silently restores the per-chunk ceilings those
+ * mechanisms exist to remove.
+ */
+export type PriorTurnToolCallJournalRead = {
+    status: "read";
+    toolCallJournal: ToolCallJournal | null;
+    priorToolCalls: PriorTurnToolCallSummary[];
+    priorToolResults: PriorTurnToolResultSummary[];
+} | {
+    status: "unreadable";
+    error: string;
+};
 /**
  * Tool-call journal hard-block (resume safety). Snapshot the per-turn journal
  * ONCE here, before any tool runs in this chunk, so it reflects only PRIOR
@@ -25,9 +49,8 @@ export interface PriorTurnToolResultSummary {
  *
  * Loaded eagerly (not lazily mid-loop) so the current chunk's own
  * asynchronously-persisted tool_done events can never leak in and make a
- * same-chunk call wrongly short-circuit. Best-effort: any ledger failure
- * leaves the journal empty and all calls run normally. Fresh first-turn calls
- * see an empty journal and are unaffected.
+ * same-chunk call wrongly short-circuit. Fresh first-turn calls see an empty
+ * journal and are unaffected.
  *
  * Also returns the prior chunks' tool calls/results so the caller can seed
  * its own `toolCallHistory` / `toolResultHistory` accumulators — final
@@ -35,11 +58,5 @@ export interface PriorTurnToolResultSummary {
  * tools executed after the latest handoff. Otherwise a guard can reject a
  * grounded answer (or a successfully-created artifact) after the
  * evidence-producing query completed in a predecessor run.
- *
- * Moved verbatim out of `runAgentLoop`'s per-turn setup — behavior unchanged.
  */
-export declare function loadPriorTurnToolCallJournal(threadId: string | undefined, turnId?: string): Promise<{
-    toolCallJournal: ToolCallJournal | null;
-    priorToolCalls: PriorTurnToolCallSummary[];
-    priorToolResults: PriorTurnToolResultSummary[];
-}>;
+export declare function loadPriorTurnToolCallJournal(threadId: string | undefined, turnId?: string): Promise<PriorTurnToolCallJournalRead>;

package/dist/agent/engine/tool-call-journal-seed.js

@@ -1,5 +1,22 @@
 import { getCurrentTurnEventsForThread } from "../run-store.js";
 import { classifyToolCallJournal, } from "../tool-call-journal.js";
+const LEDGER_READ_RETRY_MS = 250;
+/**
+ * `unreadable` ends the turn with a stop the user sees, so a single pool
+ * timeout or connection blip must not produce one. One retry, because the
+ * failures worth surviving are transient and the caller is holding the whole
+ * turn open while we wait.
+ */
+async function readCurrentTurnEventsWithRetry(threadId, turnId) {
+    try {
+        return await getCurrentTurnEventsForThread(threadId, turnId);
+    }
+    catch (err) {
+        console.warn(`[tool-call-journal] per-turn ledger read failed for thread ${threadId}, retrying once: ${err instanceof Error ? err.message : String(err)}`);
+        await new Promise((resolve) => setTimeout(resolve, LEDGER_READ_RETRY_MS));
+        return await getCurrentTurnEventsForThread(threadId, turnId);
+    }
+}
 /**
  * Tool-call journal hard-block (resume safety). Snapshot the per-turn journal
  * ONCE here, before any tool runs in this chunk, so it reflects only PRIOR
@@ -10,9 +27,8 @@ import { classifyToolCallJournal, } from "../tool-call-journal.js";
  *
  * Loaded eagerly (not lazily mid-loop) so the current chunk's own
  * asynchronously-persisted tool_done events can never leak in and make a
- * same-chunk call wrongly short-circuit. Best-effort: any ledger failure
- * leaves the journal empty and all calls run normally. Fresh first-turn calls
- * see an empty journal and are unaffected.
+ * same-chunk call wrongly short-circuit. Fresh first-turn calls see an empty
+ * journal and are unaffected.
  *
  * Also returns the prior chunks' tool calls/results so the caller can seed
  * its own `toolCallHistory` / `toolResultHistory` accumulators — final
@@ -20,40 +36,55 @@ import { classifyToolCallJournal, } from "../tool-call-journal.js";
  * tools executed after the latest handoff. Otherwise a guard can reject a
  * grounded answer (or a successfully-created artifact) after the
  * evidence-producing query completed in a predecessor run.
- *
- * Moved verbatim out of `runAgentLoop`'s per-turn setup — behavior unchanged.
  */
 export async function loadPriorTurnToolCallJournal(threadId, turnId) {
-    const priorToolCalls = [];
-    const priorToolResults = [];
-    let toolCallJournal = null;
     if (!threadId) {
-        return { toolCallJournal, priorToolCalls, priorToolResults };
+        // No thread means no durable ledger exists for this turn at all — a true
+        // "no prior history", not a read that failed.
+        return {
+            status: "read",
+            toolCallJournal: null,
+            priorToolCalls: [],
+            priorToolResults: [],
+        };
     }
+    let priorEvents;
     try {
-        const priorEvents = await getCurrentTurnEventsForThread(threadId, turnId);
-        if (priorEvents.length > 0) {
-            for (const event of priorEvents) {
-                if (event.type === "tool_start") {
-                    priorToolCalls.push({
-                        name: event.tool,
-                        input: event.input,
-                    });
-                }
-                else if (event.type === "tool_done") {
-                    priorToolResults.push({
-                        name: event.tool,
-                        content: event.result,
-                        isError: event.isError === true,
-                    });
-                }
-            }
-            toolCallJournal = classifyToolCallJournal(priorEvents);
-        }
+        priorEvents = await readCurrentTurnEventsWithRetry(threadId, turnId);
     }
-    catch {
-        // Journal is a hardening layer, never a gate — a failed ledger read just
-        // means no hard-block this turn.
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        console.warn(`[tool-call-journal] per-turn ledger read failed for thread ${threadId}: ${error}`);
+        return { status: "unreadable", error };
+    }
+    const priorToolCalls = [];
+    const priorToolResults = [];
+    // Open `tool_start` inputs per tool, so a legacy `tool_done` with no input of
+    // its own can still be attributed to the arguments it ran with.
+    const openInputsByTool = new Map();
+    for (const event of priorEvents) {
+        if (event.type === "tool_start") {
+            priorToolCalls.push({ name: event.tool, input: event.input });
+            const queue = openInputsByTool.get(event.tool);
+            if (queue)
+                queue.push(event.input);
+            else
+                openInputsByTool.set(event.tool, [event.input]);
+        }
+        else if (event.type === "tool_done") {
+            const fifoInput = openInputsByTool.get(event.tool)?.shift();
+            priorToolResults.push({
+                name: event.tool,
+                input: event.input ?? fifoInput,
+                content: event.result,
+                isError: event.isError === true,
+            });
+        }
     }
-    return { toolCallJournal, priorToolCalls, priorToolResults };
+    return {
+        status: "read",
+        toolCallJournal: priorEvents.length > 0 ? classifyToolCallJournal(priorEvents) : null,
+        priorToolCalls,
+        priorToolResults,
+    };
 }

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

@@ -183,6 +183,8 @@ export interface ActionEntry {
     /** If true, completion does NOT trigger a screen-refresh change event.
      *  Set automatically by `defineAction` when `http.method === "GET"`. */
     readOnly?: boolean;
+    /** If true, a successful call returns evidence retrieved from a live source. */
+    grounding?: boolean;
     /** False keeps a read-only tool available in Act mode but hides/blocks it in
      *  Plan mode. Use for tools that perform substantive work even without
      *  mutating state. */
@@ -613,6 +615,21 @@ export declare const MAX_SAME_ERROR_ACROSS_ARGUMENTS = 6;
  * legitimate re-check after a write.
  */
 export declare const MAX_IDENTICAL_TOOL_CALLS = 8;
+/**
+ * A stop that ends the turn from inside the tool loop.
+ *
+ * `message` is the last thing the user reads, so it names the remedy in plain
+ * words and does not quote a raw provider/tool error; the raw error goes in
+ * `details`. Both retry sniffers now honour the `recoverable: false` these
+ * stops are sent with, so a stop that happens to say "timeout" is no longer
+ * auto-continued — but the prose still has one reader who cannot ignore it,
+ * and a pasted stack trace is not a remedy.
+ */
+export interface TerminalActionStop {
+    message: string;
+    errorCode?: string;
+    details?: string;
+}
 /**
  * Convert ActionEntry registry to EngineTool array.
  */
@@ -687,9 +704,31 @@ export declare function findApprovedStructuredToolCall(history: AgentChatStructu
     input: unknown;
     callId: string;
 } | undefined;
+/**
+ * Tool errors the model has no way to clear: the missing thing lives outside
+ * the turn (a credential, a role grant, a connected account, a runtime, the
+ * user's own approval). Every retry costs a full round-trip carrying the whole
+ * transcript and lands on the identical error, so these stop on the FIRST
+ * occurrence rather than after `MAX_SAME_ERROR_ACROSS_ARGUMENTS` of them.
+ *
+ * The distinction is the one `stopForBigQueryNotConfigured` draws in
+ * templates/analytics: a *configuration* gap is permanent for this turn, a
+ * *query* failure is not. Anything the model can act on — a stale read to
+ * rebase, a bad argument, a full quota it can free, a wrong dataset name, a
+ * statement timeout — must stay out of this list and keep its retries.
+ * Precision over recall: a wrong match kills a turn that would have succeeded,
+ * which is worse than one more retry.
+ */
+export declare function permanentPreconditionRemedy(message: string): string | null;
+/**
+ * Deliberately carries no running call count. This decline is recorded as a
+ * tool error, and the breakers key on that text: a message that reports its own
+ * tally ("already made 13 call(s)") mints a fresh key on every decline, so the
+ * decline that exists to stop a spiral becomes the one thing nothing can count.
+ * The fixed threshold below says the same thing without varying.
+ */
 export declare function repeatedSourceSweepGuardMessage(opts: {
     toolName: string;
-    priorCalls: number;
     threshold?: number;
     scope?: "tool" | "aggregate";
 }): string;