@agent-native/core 0.203.0 → 0.203.1-nightly-20261007183952

package/dist/action.d.ts

@@ -36,6 +36,8 @@ export interface ActionRunContext {
     attachments?: AgentChatAttachment[];
     signal?: AbortSignal;
     actionName?: string;
+    /** Present only on frontend GETs authorized by a scoped directory-widget read capability. */
+    mcpDirectoryWidgetReadOnly?: true;
     threadId?: string;
     runId?: string;
     turnId?: string;
@@ -67,6 +69,38 @@ export interface FailOptions {
     details?: Record<string, unknown>;
 }
 export declare function fail(message: string, options?: FailOptions): never;
+/**
+ * What a write action verified about its own effect. An action opts in by
+ * returning a plain-object result with a reserved `_receipt: WriteReceipt`.
+ * The agent loop reads it before the result is stringified and truncated, so
+ * the final answer is reconciled with what the write did instead of with the
+ * model's reading of a JSON string.
+ *
+ * - `changed: false`: nothing was written (a no-op); not a completed side effect.
+ * - `verified: true`: the effect was observed. `false`: it was checked and did
+ *   not hold. `"unverified"`: it could not be checked.
+ * - `subject`: the stable target of the write, such as a dashboard id. Later
+ *   receipts from the same action with the same subject that are `changed` and
+ *   `verified: true` supersede this one, so a no-op that was then fixed does
+ *   not flag the answer. A receipt with failing checks is superseded only when
+ *   those later receipts carry an `ok` check with the same `id` for every
+ *   check that failed here, because a verified write speaks only for what it
+ *   checked. Without a subject a receipt is never superseded.
+ * - Bounds, enforced by the loop: summary and subject 200 chars, 8 checks, 5
+ *   warnings.
+ */
+export interface WriteReceipt {
+    changed: boolean;
+    verified: true | false | "unverified";
+    summary: string;
+    subject?: string;
+    checks?: Array<{
+        id: string;
+        ok: boolean;
+        detail?: string;
+    }>;
+    warnings?: string[];
+}
 export declare class AgentActionStopError extends Error {
     readonly agentNativeStop = true;
     readonly errorCode?: string;

package/dist/agent/clip-text.d.ts

@@ -0,0 +1,4 @@
+/** At most the first `max` UTF-16 units of `text`, never ending inside a surrogate pair. */
+export declare function clipHead(text: string, max: number): string;
+/** At most the last `max` UTF-16 units of `text`, never starting inside a surrogate pair. */
+export declare function clipTail(text: string, max: number): string;

package/dist/agent/clip-text.js

@@ -0,0 +1,17 @@
+// Provider APIs reject a request whose JSON holds half a surrogate pair, so a
+// clip that lands inside an emoji must drop the half instead of keeping it.
+const isHighSurrogate = (unit) => unit >= 0xd800 && unit <= 0xdbff;
+const isLowSurrogate = (unit) => unit >= 0xdc00 && unit <= 0xdfff;
+/** At most the first `max` UTF-16 units of `text`, never ending inside a surrogate pair. */
+export function clipHead(text, max) {
+    if (text.length <= max)
+        return text;
+    return text.slice(0, isHighSurrogate(text.charCodeAt(max - 1)) ? max - 1 : max);
+}
+/** At most the last `max` UTF-16 units of `text`, never starting inside a surrogate pair. */
+export function clipTail(text, max) {
+    if (text.length <= max)
+        return text;
+    const start = text.length - max;
+    return text.slice(isLowSurrogate(text.charCodeAt(start)) ? start + 1 : start);
+}

package/dist/agent/follow-up-suggestions.d.ts

@@ -1,11 +1,25 @@
 import type { AgentSuggestion } from "@agent-native/agentkit/protocol";
 import { z } from "zod";
-import type { EngineTool } from "./engine/types.js";
+import type { EngineMessage, EngineTool } from "./engine/types.js";
 export declare const FOLLOW_UP_SUGGESTIONS_TOOL_NAME = "suggest-follow-ups";
 export declare const FOLLOW_UP_SUGGESTIONS_MAX_OUTPUT_TOKENS = 1024;
 export declare const FOLLOW_UP_SUGGESTIONS_INSTRUCTION: string;
+export declare const FOLLOW_UP_SUGGESTIONS_COMPLETION_SYSTEM_PROMPT = "You write follow-up suggestions for a conversation between a user and an AI agent inside an app. You only record them by calling suggest-follow-ups.";
 export declare const FOLLOW_UP_SUGGESTIONS_COMPLETION_INSTRUCTION: string;
-export type FollowUpSuggestionsFailure = "budget_exhausted" | "iteration_limit" | "interrupted" | "context_error" | "processor_error" | "provider_error" | "invalid_or_missing";
+/**
+ * The completion call sends a different tools array than the turn did, so it
+ * can never read the turn's prompt cache. It carries a bounded digest of the
+ * turn instead of re-prefilling the whole conversation at full price. The
+ * digest keeps the shape of a finished turn (request, reply, then the
+ * instruction as the last user message) so role alternation is valid for every
+ * provider and the instruction stays the message a prefix match finds.
+ */
+export declare function buildFollowUpCompletionMessages(input: {
+    requestText?: string;
+    replyText: string;
+    toolNames: readonly string[];
+}): EngineMessage[];
+export type FollowUpSuggestionsFailure = "budget_exhausted" | "iteration_limit" | "interrupted" | "processor_error" | "provider_error" | "invalid_or_missing";
 declare const followUpSuggestionsSchema: z.ZodObject<{
     suggestions: z.ZodArray<z.ZodObject<{
         label: z.ZodString;

package/dist/agent/follow-up-suggestions.js

@@ -1,10 +1,78 @@
 import { z } from "zod";
+import { clipHead, clipTail } from "./clip-text.js";
 export const FOLLOW_UP_SUGGESTIONS_TOOL_NAME = "suggest-follow-ups";
 export const FOLLOW_UP_SUGGESTIONS_MAX_OUTPUT_TOKENS = 1024;
 export const FOLLOW_UP_SUGGESTIONS_INSTRUCTION = "Before finishing this turn, evaluate useful next actions grounded in the user's request, conversation, app workflow/current context, and observed results. " +
     "Record your decision with suggest-follow-ups: zero to three meaningful next intents, or an empty list when none is warranted. Do not fill a quota or repeat completed work.";
-export const FOLLOW_UP_SUGGESTIONS_COMPLETION_INSTRUCTION = "The final reply above has already been delivered. Complete only its missing follow-up metadata by calling suggest-follow-ups once, using the conversation, current app context, and completed results. " +
+export const FOLLOW_UP_SUGGESTIONS_COMPLETION_SYSTEM_PROMPT = "You write follow-up suggestions for a conversation between a user and an AI agent inside an app. You only record them by calling suggest-follow-ups.";
+export const FOLLOW_UP_SUGGESTIONS_COMPLETION_INSTRUCTION = "The final reply above has already been delivered. Complete only its missing follow-up metadata by calling suggest-follow-ups once, using the request, reply, and tools used above. " +
     "An empty list is valid when no useful next action exists. Do not repeat the reply, perform more work, or call other tools.";
+// The ask sits at the end of a long pasted document and a long reply's
+// conclusions sit at the end, so a clip keeps the tail.
+const COMPLETION_REQUEST_HEAD_CHARS = 500;
+const COMPLETION_REQUEST_TAIL_CHARS = 1_500;
+const COMPLETION_REPLY_TAIL_CHARS = 4_000;
+const MAX_COMPLETION_TOOL_NAMES = 30;
+function clipMiddle(text, head, tail) {
+    return text.length > head + tail
+        ? `${clipHead(text, head)}\n…\n${clipTail(text, tail)}`
+        : text;
+}
+// Providers reject an empty first user message or an empty assistant text, so a
+// turn with no request text or no reply text still sends a stated absence.
+const NO_REQUEST_TEXT = "(No request text was recorded for this turn.)";
+const NO_REPLY_TEXT = "(The reply had no text.)";
+/**
+ * The completion call sends a different tools array than the turn did, so it
+ * can never read the turn's prompt cache. It carries a bounded digest of the
+ * turn instead of re-prefilling the whole conversation at full price. The
+ * digest keeps the shape of a finished turn (request, reply, then the
+ * instruction as the last user message) so role alternation is valid for every
+ * provider and the instruction stays the message a prefix match finds.
+ */
+export function buildFollowUpCompletionMessages(input) {
+    const requestText = input.requestText?.trim();
+    const replyText = input.replyText.trim();
+    const toolNames = [...new Set(input.toolNames)]
+        .filter((name) => name !== FOLLOW_UP_SUGGESTIONS_TOOL_NAME)
+        .slice(0, MAX_COMPLETION_TOOL_NAMES);
+    const request = [
+        requestText
+            ? `<user-request>\n${clipMiddle(requestText, COMPLETION_REQUEST_HEAD_CHARS, COMPLETION_REQUEST_TAIL_CHARS)}\n</user-request>`
+            : "",
+        toolNames.length > 0
+            ? `<tools-used>${toolNames.join(", ")}</tools-used>`
+            : "",
+    ].filter(Boolean);
+    return [
+        {
+            role: "user",
+            content: [
+                {
+                    type: "text",
+                    text: request.length > 0 ? request.join("\n\n") : NO_REQUEST_TEXT,
+                },
+            ],
+        },
+        {
+            role: "assistant",
+            content: [
+                {
+                    type: "text",
+                    text: replyText
+                        ? clipMiddle(replyText, 0, COMPLETION_REPLY_TAIL_CHARS)
+                        : NO_REPLY_TEXT,
+                },
+            ],
+        },
+        {
+            role: "user",
+            content: [
+                { type: "text", text: FOLLOW_UP_SUGGESTIONS_COMPLETION_INSTRUCTION },
+            ],
+        },
+    ];
+}
 const followUpSuggestionsSchema = z
     .strictObject({
     suggestions: z

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

@@ -1,7 +1,7 @@
 import type { EventHandler as H3EventHandler } from "h3";
 import "../authorization/check-action.js";
 import type { Task } from "../a2a/types.js";
-import { type ActionAutomationContext, type ActionCaller } from "../action.js";
+import { type ActionAutomationContext, type ActionCaller, type WriteReceipt } from "../action.js";
 import { type ArtifactReceipt } from "../artifacts/detect.js";
 import type { AgentNativeHarnessSetting } from "../config.js";
 import { type CredentialProvenance } from "../credentials/index.js";
@@ -19,6 +19,7 @@ import { subscribeToRun, getActiveRunForThread, getActiveRunForThreadAsync, getR
 import type { ActiveRun } from "./run-manager.js";
 import { type AgentTurnInitiator, insertRun, isTurnAborted, markRunAborted, updateRunHeartbeat, updateRunStatusIfRunning, setRunError, setRunTerminalReason, claimBackgroundRun, readBackgroundRunClaim, recordRunDiagnostic, countRunsForTurn } from "./run-store.js";
 import { type AgentActionScope, ActionTool, AgentChatAttachment, AgentChatEvent, AgentFileMutationProof, AgentChatReference, AgentChatStructuredMessage } from "./types.js";
+import { type ToolWriteReceipt } from "./write-receipts.js";
 export { PROVIDER_TO_ENV };
 /**
  * Grace window + poll interval for the foreground circuit-breaker that confirms
@@ -394,6 +395,12 @@ export interface AgentLoopUsage {
     engineName?: string;
     model: string;
     llmCalls?: number;
+    /** Wall time and input tokens of the end-of-turn follow-up suggestions call. */
+    followUpMs?: number;
+    followUpInputTokens?: number;
+    /** Write receipts this run with `verified` other than true / with `changed: false`. */
+    receiptUnverifiedCount?: number;
+    receiptChangedFalseCount?: number;
     /**
      * True once the engine reported at least one real `usage` event for this
      * run. The token fields above start at 0 and are only ever incremented —
@@ -404,6 +411,12 @@ export interface AgentLoopUsage {
     usageReported?: boolean;
     firstEngineEventAtMs?: number;
 }
+/**
+ * Folds one loop attempt's usage into a running total. Every wrapper that
+ * re-enters `runAgentLoop` merges through this, so a field added to
+ * `AgentLoopUsage` cannot be reported by the loop and dropped by a wrapper.
+ */
+export declare function mergeAgentLoopUsage(total: AgentLoopUsage, next: AgentLoopUsage): void;
 export type AgentLoopOutcome = {
     state: "completed";
 } | {
@@ -428,7 +441,10 @@ export interface AgentLoopToolResultSummary {
     content: string;
     isError: boolean;
     artifacts?: ArtifactReceipt[];
+    /** The action's `_receipt`, read before the result was truncated. */
+    receipt?: WriteReceipt;
 }
+export type { ToolWriteReceipt };
 export interface AgentLoopFinalResponseGuardContext {
     messages: EngineMessage[];
     requestText?: string;
@@ -436,6 +452,8 @@ export interface AgentLoopFinalResponseGuardContext {
     text: string;
     toolCalls: AgentLoopToolCallSummary[];
     toolResults: AgentLoopToolResultSummary[];
+    /** Every write receipt this turn; set by the loop, absent only in hand-built contexts. */
+    receipts?: ToolWriteReceipt[];
     retryCount: number;
     executionMode: AgentExecutionMode;
 }
@@ -792,7 +810,7 @@ export declare function resolveAgentRequestReasoningEffort({ model, requestEffor
     requestEffort?: unknown;
     configuredEffort?: ReasoningEffort;
 }): ReasoningEffort | undefined;
-export type AgentModelSelectionSource = "request" | "configured" | "stored" | "default";
+export type AgentModelSelectionSource = "request" | "configured" | "stored" | "default" | "provider-selection-fallback";
 export declare function resolveAgentModelSelection(options: {
     requestModel?: string | null;
     configuredModel?: string | null;