@agent-native/core 0.169.1 → 0.170.0

package/dist/observability/traces.js

@@ -24,6 +24,37 @@ function llmProviderFromEngine(engineName, model) {
 function costUsdFromCenticents(value) {
     return Math.round((value / 10_000) * 1_000_000) / 1_000_000;
 }
+/**
+ * Wall-clock time covered by these intervals, counting overlap once.
+ *
+ * Tools run concurrently, so summing durations reports more elapsed time than
+ * actually passed — enough to drive a derived remainder to zero on a parallel
+ * fan-out.
+ */
+function coveredDurationMs(intervals) {
+    if (intervals.length === 0)
+        return 0;
+    const sorted = [...intervals].sort((a, b) => a.start - b.start);
+    let covered = 0;
+    let { start: openStart, end: openEnd } = sorted[0];
+    for (const { start, end } of sorted.slice(1)) {
+        if (start > openEnd) {
+            covered += openEnd - openStart;
+            openStart = start;
+            openEnd = end;
+        }
+        else if (end > openEnd) {
+            openEnd = end;
+        }
+    }
+    return covered + (openEnd - openStart);
+}
+function spanIntervals(spans) {
+    return spans.map((s) => ({
+        start: s.createdAt,
+        end: s.createdAt + Math.max(0, s.durationMs),
+    }));
+}
 /**
  * Project run metadata onto flat PostHog trace properties.
  *
@@ -144,7 +175,7 @@ function emitLlmGenerationTrackingEvent(args) {
         $ai_provider: provider,
         $ai_input_tokens: args.inputTokens,
         $ai_output_tokens: args.outputTokens,
-        $ai_latency: Math.round((args.durationMs / 1000) * 1000) / 1000,
+        $ai_latency: Math.round(args.llmDurationMs) / 1000,
         $ai_is_error: args.status === "error",
         $ai_error: args.status === "error"
             ? toAiErrorDetail(error, {
@@ -153,16 +184,24 @@ function emitLlmGenerationTrackingEvent(args) {
                 retryable: terminalRetryable,
             })
             : undefined,
+        // Every engine here streams (`messages.stream`, `streamText`, gateway SSE),
+        // which is also what makes `$ai_time_to_first_token` meaningful.
+        $ai_stream: true,
         $ai_cache_read_input_tokens: args.cacheReadTokens,
         $ai_cache_creation_input_tokens: args.cacheWriteTokens,
-        $ai_request_count: 1,
+        $ai_request_count: args.llmCallCount,
         $ai_total_cost_usd: costUsd,
         $ai_input: args.aiInput,
         $ai_output_choices: args.aiOutputChoices,
         $ai_tools: args.aiTools,
-        $ai_input_truncated: args.aiInputTruncated || undefined,
-        $ai_output_truncated: args.aiOutputTruncated || undefined,
-        $ai_time_to_first_token: args.firstTokenMs,
+        input_truncated: args.aiInputTruncated || undefined,
+        output_truncated: args.aiOutputTruncated || undefined,
+        latency_source: args.llmDurationMeasured ? "measured" : "derived",
+        // Seconds, per PostHog's schema — `time_to_first_token_ms` above is the
+        // millisecond field this framework's own dashboards read.
+        $ai_time_to_first_token: args.firstTokenMs === undefined
+            ? undefined
+            : Math.round(args.firstTokenMs) / 1000,
         $session_id: args.browserSessionId,
     };
     if (args.experimentAssignments?.length) {
@@ -188,6 +227,7 @@ function emitLlmGenerationTrackingEvent(args) {
             .then(({ track }) => {
             track("$ai_generation", properties, {
                 userId: args.userId ?? undefined,
+                occurredAt: args.createdAt,
             });
         })
             .catch(() => { });
@@ -212,6 +252,10 @@ function emitLlmGenerationTrackingEvent(args) {
  */
 function buildGenerationContent(args) {
     const { config } = args;
+    // `$ai_input` is the conversation, not the system prompt. PostHog accepts a
+    // `system` role, but the prompt is app configuration rather than content and
+    // is near-identical on every run — shipping it would repeat kilobytes on each
+    // generation for no analytical gain.
     const input = config.capturePrompts
         ? boundAiContent(redactSensitiveFields(args.messages))
         : undefined;
@@ -364,6 +408,13 @@ export async function instrumentAgentLoop(opts) {
     let toolCallCount = 0;
     let successfulTools = 0;
     let failedTools = 0;
+    // One `model_stream` start/end bracket is emitted per LLM round-trip, and it
+    // closes before any tool of that turn is started — so these intervals ARE the
+    // model's wall clock, not an estimate of it. Recording them is what lets the
+    // generation report a measured `$ai_latency` instead of backing tool time out
+    // of the run duration.
+    const modelStreamIntervals = [];
+    let modelStreamOpenedAt = null;
     // Track in-flight OTel tool spans so they're all ended even if the loop
     // throws before a matching `tool_done` arrives.
     const openOtelToolSpans = new Set();
@@ -447,6 +498,20 @@ export async function instrumentAgentLoop(opts) {
                 runStatus = "error";
                 errorMessage = "Missing API key";
             }
+            if (event.type === "model_stream") {
+                // The emitter brackets these itself, so a repeated start or an
+                // unmatched end is a no-op here rather than a fabricated interval.
+                if (event.status === "start") {
+                    modelStreamOpenedAt ??= Date.now();
+                }
+                else if (modelStreamOpenedAt !== null) {
+                    modelStreamIntervals.push({
+                        start: modelStreamOpenedAt,
+                        end: Date.now(),
+                    });
+                    modelStreamOpenedAt = null;
+                }
+            }
             if (event.type === "tool_start") {
                 const counter = toolInvocationCounter++;
                 const sid = spanId();
@@ -563,6 +628,25 @@ export async function instrumentAgentLoop(opts) {
                 else if (pending) {
                     pending.endResult = otelEndResult;
                 }
+                const spanMetadataFields = {};
+                if (config.captureToolArgs && pending) {
+                    // Strip Authorization/api-key/token-shaped values before persisting
+                    // (M14 in the MCP/A2A audit). Tool-runtime execution still sees the
+                    // unredacted input — only the long-lived span row is sanitized.
+                    spanMetadataFields.input = redactSensitiveFields(pending.input);
+                }
+                // A failed tool's content reaches the span through `errorMessage`; a
+                // successful one had nowhere to go, so every healthy tool span shipped
+                // an input and no output — indistinguishable from a tool that returned
+                // nothing. Same redaction and truncation as the error path.
+                if (!isError &&
+                    config.captureToolResults &&
+                    typeof event.result === "string") {
+                    spanMetadataFields.output = truncateToolErrorMessage(redactToolErrorMessage(event.result));
+                }
+                const spanMetadata = Object.keys(spanMetadataFields).length
+                    ? spanMetadataFields
+                    : null;
                 const span = {
                     id: pending?.spanId ?? spanId(),
                     runId,
@@ -579,16 +663,11 @@ export async function instrumentAgentLoop(opts) {
                     durationMs: pending ? Math.max(0, finishedAt - pending.startMs) : 0,
                     status: isError ? "error" : "success",
                     errorMessage: isError ? event.result : null,
-                    metadata: config.captureToolArgs && pending
-                        ? // Strip Authorization/api-key/token-shaped values before
-                            // persisting (M14 in the MCP/A2A audit). Tool-runtime
-                            // execution still sees the unredacted input — only the
-                            // long-lived span row is sanitized.
-                            {
-                                input: redactSensitiveFields(pending.input),
-                            }
-                        : null,
-                    createdAt: Date.now(),
+                    metadata: spanMetadata,
+                    // The span's start, not its completion: `durationMs` is measured from
+                    // here, so stamping the end instead places the tool after the run
+                    // ended in any timeline that plots start + duration.
+                    createdAt: pending?.startMs ?? finishedAt,
                 };
                 spans.push(span);
             }
@@ -629,6 +708,19 @@ export async function instrumentAgentLoop(opts) {
         try {
             const runEnd = Date.now();
             const totalDurationMs = runEnd - runStart;
+            // The loop threw or was killed mid-stream, so no `end` ever arrived. The
+            // model was still running when the run stopped, so the interval closes at
+            // the run's end rather than being dropped.
+            if (modelStreamOpenedAt !== null) {
+                modelStreamIntervals.push({ start: modelStreamOpenedAt, end: runEnd });
+                modelStreamOpenedAt = null;
+            }
+            // Undefined means the engine never bracketed its model calls, NOT that
+            // the model took no time — the two must stay distinguishable, because
+            // only the first may fall back to backing tool time out of the run.
+            const measuredModelDurationMs = modelStreamIntervals.length
+                ? coveredDurationMs(modelStreamIntervals)
+                : undefined;
             if (pendingTools.size > 0) {
                 if (runStatus === "success") {
                     runStatus = "error";
@@ -681,7 +773,7 @@ export async function instrumentAgentLoop(opts) {
                         status: "error",
                         errorMessage: interruptedMessage,
                         metadata: null,
-                        createdAt: runEnd,
+                        createdAt: pending.startMs,
                     });
                 }
                 pendingTools.clear();
@@ -712,6 +804,15 @@ export async function instrumentAgentLoop(opts) {
                         message: `Agent run was cut off before finishing (${cutOffReason}).`,
                     }
                     : undefined);
+            const collectedToolSpans = spans.filter((s) => s.spanType === "tool_call");
+            // Resolved before the generation event, not just before the span events:
+            // the generation's latency is the run minus the tool time PostHog will
+            // actually see, so it has to be computed against the same set. Tools
+            // dropped by `captureLlmSpans` or the per-run cap have no sibling span to
+            // hold their time, and subtracting them would lose it from the trace.
+            const emittedToolSpans = (config.captureLlmSpans ? collectedToolSpans : []).slice(0, MAX_AI_SPANS_PER_RUN);
+            const droppedToolSpans = (config.captureLlmSpans ? collectedToolSpans.length : 0) -
+                emittedToolSpans.length;
             let llmCallCount = 0;
             if (usage || runStatus === "error") {
                 llmCallCount =
@@ -736,12 +837,23 @@ export async function instrumentAgentLoop(opts) {
                     ? Math.max(0, usage.firstEngineEventAtMs - runStart)
                     : undefined;
                 const llmSpanId = spanId();
+                const generationToolSpans = collectedToolSpans;
+                // Measured model time when the engine bracketed its round-trips.
+                //
+                // The fallback backs tool time out of the run instead, which is an
+                // estimate and behaves like one: it has to net out overlapping tools,
+                // skip tools PostHog will not receive, and clamp at zero. Engines that
+                // report `model_stream` need none of that, so `latency_source` records
+                // which of the two a given `$ai_latency` came from.
+                const llmDurationMs = measuredModelDurationMs ??
+                    Math.max(0, totalDurationMs -
+                        coveredDurationMs(spanIntervals(emittedToolSpans)));
                 const generationContent = buildGenerationContent({
                     config,
                     messages: loopOpts.messages,
                     tools: loopOpts.tools,
                     assistantText: assistantTextParts.join(""),
-                    toolSpans: spans.filter((s) => s.spanType === "tool_call"),
+                    toolSpans: generationToolSpans,
                 });
                 const llmSpan = {
                     id: llmSpanId,
@@ -785,6 +897,9 @@ export async function instrumentAgentLoop(opts) {
                         : undefined,
                     costCentsX100: usageReported ? costCentsX100 : undefined,
                     durationMs: totalDurationMs,
+                    llmDurationMs,
+                    llmDurationMeasured: measuredModelDurationMs !== undefined,
+                    llmCallCount,
                     firstTokenMs,
                     status: runStatus,
                     errorMessage,
@@ -844,11 +959,22 @@ export async function instrumentAgentLoop(opts) {
                 const provider = llmProviderFromEngine(typeof loopOpts.engine?.name === "string"
                     ? loopOpts.engine.name
                     : undefined, usage?.model ?? loopOpts.model);
-                const toolSpans = config.captureLlmSpans
-                    ? spans.filter((s) => s.spanType === "tool_call")
-                    : [];
-                const emittedToolSpans = toolSpans.slice(0, MAX_AI_SPANS_PER_RUN);
-                const droppedToolSpans = toolSpans.length - emittedToolSpans.length;
+                // PostHog reads a trace's input/output state ONLY from the `$ai_trace`
+                // event — never from its children — so a trace whose detail view should
+                // show what the run was asked and what it answered has to carry them
+                // here. Gated on `capturePrompts` and omitted, not emptied, when off.
+                const traceInputState = config.capturePrompts
+                    ? redactSensitiveFields(loopOpts.messages)
+                    : undefined;
+                const traceAssistantText = assistantTextParts.join("");
+                const traceOutputState = config.capturePrompts && traceAssistantText
+                    ? [
+                        {
+                            role: "assistant",
+                            content: redactToolErrorMessage(traceAssistantText),
+                        },
+                    ]
+                    : undefined;
                 emitAiTraceEvent({
                     runId,
                     threadId,
@@ -856,7 +982,7 @@ export async function instrumentAgentLoop(opts) {
                     spanName,
                     model: usage?.model ?? loopOpts.model,
                     provider,
-                    latencySeconds: Math.round(totalDurationMs) / 1000,
+                    durationMs: totalDurationMs,
                     isError: runStatus === "error",
                     error: aiError,
                     inputTokens: usage?.usageReported ? usage.inputTokens : undefined,
@@ -866,6 +992,8 @@ export async function instrumentAgentLoop(opts) {
                         : undefined,
                     createdAt: runStart,
                     browserSessionId,
+                    inputState: traceInputState,
+                    outputState: traceOutputState,
                     extraProperties: {
                         ...trackingIdentityProperties(),
                         source: "agent_observability",
@@ -879,8 +1007,8 @@ export async function instrumentAgentLoop(opts) {
                         // A truncated run must not read as a complete one.
                         ...(droppedToolSpans > 0
                             ? {
-                                $ai_spans_dropped: droppedToolSpans,
-                                $ai_spans_emitted: emittedToolSpans.length,
+                                spans_dropped: droppedToolSpans,
+                                spans_emitted: emittedToolSpans.length,
                             }
                             : {}),
                     },
@@ -911,10 +1039,12 @@ export async function instrumentAgentLoop(opts) {
                             : undefined,
                         createdAt: span.createdAt,
                         browserSessionId,
-                        // `metadata.input` is already redacted and only present when
-                        // `captureToolArgs` is on; absent stays absent.
+                        // `metadata.input` / `metadata.output` are already redacted and
+                        // only present when `captureToolArgs` / `captureToolResults` are
+                        // on; absent stays absent.
                         inputState: span.metadata?.input,
-                        outputState: toolErrorMessage,
+                        outputState: toolErrorMessage ??
+                            span.metadata?.output,
                         extraProperties: {
                             ...trackingIdentityProperties(),
                             source: "agent_observability",

package/dist/onboarding/app-profile.js

@@ -292,8 +292,8 @@ const PROFILES = {
                 label: "Gmail",
                 required: true,
                 builderIncluded: false,
-                keySummary: "Google OAuth client ID and secret",
-                why: "Mail needs OAuth access to read, send, and organize the mailbox.",
+                keySummary: "Connect Gmail with OAuth",
+                why: "Mail uses the workspace's managed Google connection; no key is pasted here.",
             },
             {
                 id: "attachment-storage",

package/dist/onboarding/plugin.js

@@ -13,6 +13,7 @@ import { deleteCookie, defineEventHandler, getCookie, getMethod, getQuery, setRe
 import { appStateGet, appStatePut } from "../application-state/store.js";
 import { getOrgContext } from "../org/context.js";
 import { getSession } from "../server/auth.js";
+import { CredentialStoreUnavailableError } from "../server/credential-provider.js";
 import { awaitBootstrap, getH3App, markDefaultPluginProvided, } from "../server/framework-request-handler.js";
 import { runWithRequestContext } from "../server/request-context.js";
 import { FIRST_RUN_ONBOARDING_COMPLETED_KEY, FIRST_RUN_ONBOARDING_COOKIE, FIRST_RUN_ONBOARDING_ELIGIBLE_KEY, } from "../shared/first-run-onboarding.js";
@@ -57,7 +58,11 @@ async function serializeSteps(context, options = {}) {
     // chain of credential/settings reads — walking them one at a time made this
     // route cost the SUM of every step's round trips against a remote database
     // instead of the slowest one. `Promise.all` preserves `steps` order.
-    return Promise.all(steps.map(async (step) => {
+    const serialized = await Promise.all(steps.map(async (step) => {
+        if (!options.preview && step.isAvailable) {
+            if (!(await step.isAvailable(context)))
+                return null;
+        }
         let complete = false;
         if (!options.preview) {
             try {
@@ -80,6 +85,7 @@ async function serializeSteps(context, options = {}) {
             methods: step.methods,
         };
     }));
+    return serialized.filter((step) => step !== null);
 }
 function withOnboardingRequestContext(context, fn) {
     return runWithRequestContext({
@@ -180,7 +186,9 @@ export function createOnboardingPlugin(options = {}) {
                     };
                 });
             }
-            catch {
+            catch (error) {
+                if (error instanceof CredentialStoreUnavailableError)
+                    throw error;
                 return { dismissed: false, allComplete: false };
             }
         }));

package/dist/onboarding/types.d.ts

@@ -66,6 +66,8 @@ export interface OnboardingStep {
     /** Required steps block onboarding dismissal when incomplete. */
     required?: boolean;
     methods: OnboardingMethod[];
+    /** Hide the step when its backing capability is not configured. */
+    isAvailable?: (context?: OnboardingResolveContext) => boolean | Promise<boolean>;
     /** Resolver — called on every `GET /_agent-native/onboarding/steps` request. */
     isComplete: (context?: OnboardingResolveContext) => boolean | Promise<boolean>;
 }

package/dist/provider-api/actions/custom-provider-registration.d.ts

@@ -93,8 +93,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     label?: undefined;
     message?: undefined;
 } | {
-    id?: undefined;
     count?: undefined;
+    id?: undefined;
     deleted?: undefined;
     providers?: undefined;
     found: boolean;

package/dist/provider-api/actions/provider-api.d.ts

@@ -311,9 +311,9 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         notes?: string | undefined;
         scope?: "org" | "user" | undefined;
     }, {
+        id?: undefined;
         message?: undefined;
         deleted?: undefined;
-        id?: undefined;
         provider?: undefined;
         providers: {
             id: string;
@@ -329,10 +329,10 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         registered?: undefined;
         label?: undefined;
     } | {
+        id?: undefined;
         message?: undefined;
         deleted?: undefined;
         count?: undefined;
-        id?: undefined;
         providers?: undefined;
         found: boolean;
         provider: import("../custom-registry.js").CustomProviderConfig;

package/dist/provider-api/index.js

@@ -436,6 +436,7 @@ const PROVIDER_CONFIGS = {
             type: "oauth-bearer",
             oauthProvider: "google",
             tokenLabel: "Google OAuth token",
+            workspaceProvider: "gmail",
         },
         credentialKeys: ["GOOGLE_OAUTH_ACCOUNT"],
         docsUrls: ["https://developers.google.com/gmail/api/reference/rest"],
@@ -587,6 +588,7 @@ const PROVIDER_CONFIGS = {
             type: "oauth-bearer",
             oauthProvider: "google",
             tokenLabel: "Google OAuth token",
+            workspaceProvider: "google_calendar",
         },
         credentialKeys: ["GOOGLE_OAUTH_ACCOUNT"],
         docsUrls: ["https://developers.google.com/calendar/api/v3/reference"],

package/dist/resources/store.js

@@ -359,15 +359,19 @@ function physicalWorkspaceResourceId(id) {
         : null;
 }
 function rowToGrantedWorkspaceResource(row) {
+    const contentLoaded = Object.prototype.hasOwnProperty.call(row, "content");
     const content = String(row.content ?? "");
     const path = String(row.path ?? "");
+    const size = contentLoaded
+        ? Buffer.byteLength(content, "utf8")
+        : Number(row.content_size ?? 0);
     return {
         id: syntheticWorkspaceResourceId(String(row.id)),
         path,
         owner: WORKSPACE_OWNER,
         content,
         mimeType: workspaceResourceMimeType(path),
-        size: Buffer.byteLength(content, "utf8"),
+        size: Number.isFinite(size) ? size : 0,
         createdAt: Number(row.created_at ?? Date.now()),
         updatedAt: Number(row.updated_at ?? Date.now()),
         createdBy: "system",
@@ -480,7 +484,7 @@ function mergeResourceMetas(primary, inherited) {
     }
     return merged;
 }
-async function selectGrantedWorkspaceResourceRows(input) {
+async function selectGrantedWorkspaceResourceRows(input, options = {}) {
     const appId = currentWorkspaceAppId(input.workspaceAppId);
     const { userEmail, orgId } = requestScopedResourceIdentity(input);
     if (!appId || (!userEmail && !orgId))
@@ -507,6 +511,9 @@ async function selectGrantedWorkspaceResourceRows(input) {
         conditions.push("wr.owner_email = ?", "wr.org_id IS NULL", "wg.owner_email = ?", "wg.org_id IS NULL");
         args.push(userEmail, userEmail);
     }
+    const contentSelect = options.includeContent === false
+        ? `${isPostgres() ? "octet_length(wr.content)" : "length(CAST(wr.content AS BLOB))"} AS content_size`
+        : "wr.content";
     const client = getDbExec();
     const { rows } = await client.execute({
         sql: `
@@ -516,7 +523,7 @@ async function selectGrantedWorkspaceResourceRows(input) {
         wr.name,
         wr.description,
         wr.path,
-        wr.content,
+        ${contentSelect},
         wr.created_at,
         wr.updated_at,
         wg.id AS grant_id,
@@ -532,7 +539,9 @@ async function selectGrantedWorkspaceResourceRows(input) {
 }
 async function grantedWorkspaceResources(input) {
     try {
-        const rows = await selectGrantedWorkspaceResourceRows(input);
+        const rows = await selectGrantedWorkspaceResourceRows(input, {
+            includeContent: false,
+        });
         return rows.map(rowToGrantedWorkspaceResource);
     }
     catch {

package/dist/scripts/agent-engines/list-agent-engines.js

@@ -70,8 +70,29 @@ export async function run(args = {}) {
     const currentModel = currentEntry && !envUnavailable
         ? normalizeModelForEngine(currentEntry, currentModelCandidate ?? currentEntry.defaultModel, { preserveCustomModels })
         : (currentModelCandidate ?? DEFAULT_MODEL);
-    const result = {
-        engines: engines.map((e) => ({
+    // Readiness has to be resolved here: `requiredEnvVars` alone cannot see
+    // vault-stored keys or the deploy-injected Builder gateway lane, so a client
+    // that re-derives it from env keys marks working engines unconfigured.
+    const engineEntries = await Promise.all(engines.map(async (e) => {
+        // Resolved per engine, not across the set: one provider whose credential
+        // store is momentarily unreadable must not reject the whole listing. The
+        // chat refresh catches that rejection and renders an empty catalog, so a
+        // single unrelated provider would make every engine unselectable — the
+        // exact symptom this readiness plumbing exists to fix.
+        //
+        // A read error is its own state, left as `configured: undefined` so the
+        // client falls back to its env heuristic. Folding it into `false` would
+        // claim the engine needs an API key when nobody actually knows.
+        let configured;
+        let configuredError;
+        try {
+            configured = await isStoredEngineUsableForRequest({ engine: e.name, model: e.defaultModel }, e);
+        }
+        catch (error) {
+            configuredError =
+                error instanceof Error ? error.message : String(error);
+        }
+        return {
             name: e.name,
             label: e.label,
             description: e.description,
@@ -81,7 +102,12 @@ export async function run(args = {}) {
             requiredEnvVars: e.requiredEnvVars,
             installPackage: e.installPackage,
             packageInstalled: isAgentEnginePackageInstalled(e),
-        })),
+            configured,
+            configuredError,
+        };
+    }));
+    const result = {
+        engines: engineEntries,
         current: envUnavailable
             ? null
             : {

package/dist/secrets/register-framework-secrets.js

@@ -27,7 +27,7 @@ export function registerFrameworkSecrets() {
             id: "google_drive",
             credentialPrefix: "GOOGLE",
             oauthProvider: "google",
-            label: "Google Drive",
+            label: "Google Workspace",
             docsUrl: "https://developers.google.com/identity/protocols/oauth2/web-server",
         },
         {

package/dist/server/action-discovery.js

@@ -163,6 +163,11 @@ function preserveActionFlags(entry) {
     const out = {};
     if (typeof entry.agentTool === "boolean")
         out.agentTool = entry.agentTool;
+    if (typeof entry.mcpTool === "boolean")
+        out.mcpTool = entry.mcpTool;
+    if (typeof entry.deferLoading === "boolean") {
+        out.deferLoading = entry.deferLoading;
+    }
     if (typeof entry.requiresAuth === "boolean") {
         out.requiresAuth = entry.requiresAuth;
     }

package/dist/server/agent-chat/action-filters-a2a.d.ts

@@ -13,6 +13,18 @@ export declare function filterReadOnlyActions(actions: Record<string, ActionEntr
  *  list (in-app assistant, MCP, A2A, job/trigger runners) or actions prompt.
  *  Default-allow: only an explicit `false` is excluded. */
 export declare function filterAgentTools(actions: Record<string, ActionEntry>): Record<string, ActionEntry>;
+/**
+ * The MCP-only actions: `agentTool: false` paired with an explicit
+ * `mcpTool: true`.
+ *
+ * `filterAgentTools` drops these, which is right for every in-app surface and
+ * wrong for the two external ones. Rather than have the MCP and A2A mounts
+ * read the unfiltered registry — and re-derive which agent-hidden actions are
+ * safe to serve — the plugin re-merges exactly this set into those two mounts.
+ * A caller that wants "everything external" merges this with the agent surface;
+ * nobody has to remember which raw fields make an action MCP-only.
+ */
+export declare function filterMcpOnlyActions(actions: Record<string, ActionEntry>): Record<string, ActionEntry>;
 export declare function filterPublicAgentActions(actions: Record<string, ActionEntry>): Record<string, ActionEntry>;
 /**
  * True when an action takes a free-form query or program as input — raw SQL, a
@@ -137,15 +149,27 @@ export declare function createA2AEngineToolSurface(availableTools: EngineTool[],
 export declare function isSelectedA2AReceiver(selectedReceiverApp: string | undefined, appId: string | undefined): boolean;
 export declare function buildSelectedA2AReceiverContext(appId: string): string;
 /**
- * The first-request tool catalog: an explicit `initialToolNames` verbatim, or
- * the app's OWN actions by default.
+ * The first-request tool catalog, in precedence order:
+ *
+ *  1. An explicit `initialToolNames`, plus every action that declares
+ *     `deferLoading: false`. The configured list stays authoritative — an
+ *     action it names is never dropped by a `deferLoading: true` — so a
+ *     template can annotate its actions before deleting the array, not after.
+ *  2. Otherwise, the actions that declared `deferLoading: false`, if any did.
+ *  3. Otherwise, the app's OWN actions, minus any marked `deferLoading: true`.
+ *
+ * Step 2 is what makes `deferLoading` a replacement for the array rather than
+ * a second copy of it: opting a few starter actions out of deferral on an app
+ * with no configured list defers everything else, instead of leaving the whole
+ * registry in and the annotation decorative.
  *
  * "Its own actions" excludes the framework kits. They arrive in this same
  * registry through `autoDiscoverActions` -> `mergeCoreSharingActions`, so the
  * plain `Object.keys` default promoted ~45 sharing/review/history/flag schemas
  * into every app's first request whether or not the app had those surfaces. They
  * remain in `availableTools` and are still found by `tool-search`; an app that
- * wants one on turn one names it in `initialToolNames`.
+ * wants one on turn one sets `deferLoading: false` or names it in
+ * `initialToolNames`.
  */
 export declare function resolveInitialToolNames(templateActions: Record<string, ActionEntry>, configured?: string[]): string[];
 export {};