@agent-native/core 0.189.0 → 0.190.0-nightly-20260925215540

package/dist/server/agent-chat/prompt-resources.js

@@ -1,9 +1,9 @@
-import { rankJevCandidates, } from "../../agent/jev-tool-prefetch.js";
+import { JEV_TIMEOUT_MS, rankJevCandidatesWithStatus, } from "../../agent/jev-tool-prefetch.js";
 import { frameworkGroupEnabled, } from "../../framework-tools.js";
 import { getFrontmatterValue, getSkillNameFromPath, parseFrontmatter, } from "../../resources/metadata.js";
 import { ensurePersonalDefaults, isWorkspaceResourceOwner, organizationIdFromResourceOwner, resourceGet, resourceGetByPath, resourceList, resourceListAccessible, SHARED_OWNER, sharedResourceOwner, WORKSPACE_OWNER, workspaceResourceOwner, } from "../../resources/store.js";
 import { discoverAgents } from "../agent-discovery.js";
-import { getRequestOrgId } from "../request-context.js";
+import { getRequestOrgId, getRequestRunContext } from "../request-context.js";
 import { isRuntimeVisibleScope, parseSkillFrontmatter, } from "./skill-frontmatter.js";
 // ---------------------------------------------------------------------------
 // System-prompt resource loading: AGENTS.md, instructions/*.md, skills
@@ -81,7 +81,12 @@ const PROMPT_INSTRUCTION_SUMMARY_LIMIT = 20;
 const PROMPT_SUMMARY_DESCRIPTION_MAX_CHARS = 180;
 const JEV_CONTEXT_ITEM_MAX_CHARS = 10_000;
 const JEV_CONTEXT_TOTAL_MAX_CHARS = 24_000;
-const JEV_CONTEXT_PREFIX = "<jev-prefetched-context>\nJev ranked these skills for this task. Mandatory AGENTS.md instructions remain authoritative. Treat these sources as task-specific guidance and use the existing tools to read anything else you need.\n\n";
+const JEV_MEMORY_CANDIDATE_LIMIT = 8;
+const JEV_MEMORY_SELECTION_LIMIT = 2;
+const JEV_MEMORY_DESCRIPTION_MAX_CHARS = 240;
+const JEV_PRELOAD_BUDGET_MS = 1_300;
+const MIN_ANALYTICS_REFERENCE_SIMILARITY = 0.35;
+const JEV_CONTEXT_PREFIX = "<jev-prefetched-context>\nThese bounded context sources were selected for this task. Mandatory AGENTS.md instructions remain authoritative. Treat stored memories as prior context and verify time-sensitive facts. For Analytics, use a matching preloaded reference first; otherwise make your first tool call search-analytics-query-catalog. Treat references as examples and definitions, then run a live query before reporting values.\n\n";
 const JEV_CONTEXT_SUFFIX = "\n</jev-prefetched-context>";
 const JEV_CONTEXT_SEPARATOR = "\n\n";
 const JEV_CONTEXT_WRAPPER_OVERHEAD_CHARS = JEV_CONTEXT_PREFIX.length + JEV_CONTEXT_SUFFIX.length;
@@ -597,9 +602,12 @@ async function loadResourceIndexForPrompt(owner, scope, orgId) {
         : "Shared app/organization reference resources are available for app-specific or team context.";
     return `<workspace-resources scope="${scope}">\n${label} ${resourceToolHint("read", `\`path: <path>\` and \`scope: "${scope}"\` when a task may depend on them`)} Do not assume their contents without reading the relevant file.\n\n${lines.join("\n")}\n</workspace-resources>`;
 }
-async function collectJevPromptCandidates() {
-    // Do not send SQL resource names, paths, or descriptions to Jev. They are
-    // user-authored metadata and can contain customer/project information.
+async function collectJevPromptCandidates(signal) {
+    // Jev receives the current request and recent user turns, short skill and
+    // memory summaries, and bounded Analytics labels with metric definitions,
+    // source/table names, or dashboard/panel details. These may be sensitive
+    // user-authored metadata. Keep assistant text/results, tool payloads,
+    // resource IDs/paths, memory/skill bodies, and full query SQL out of ranking.
     const candidates = [];
     let nextId = 0;
     const add = (candidate) => {
@@ -612,16 +620,18 @@ async function collectJevPromptCandidates() {
             ...candidate,
             id: `context-${nextId++}`,
             description,
-            metadata: {
-                kind: candidate.kind,
+            metadata: candidate.metadata ?? {
+                kind: candidate.kind ?? "skill",
                 scope: candidate.scope,
             },
         });
     };
     try {
         const { getRuntimeSkills, loadAgentsBundle } = await import("../agents-bundle.js");
+        signal.throwIfAborted();
         const bundle = await loadAgentsBundle();
         for (const skill of getRuntimeSkills(bundle)) {
+            signal.throwIfAborted();
             add({
                 kind: "skill",
                 name: skill.meta.name,
@@ -637,34 +647,381 @@ async function collectJevPromptCandidates() {
     }
     return candidates;
 }
+function parseMemoryIndex(content) {
+    const entries = [];
+    for (const line of content.split("\n")) {
+        const match = /^\s*-\s+\[([^\]]+)\]\(([^)]+\.md)\)\s*[—-]\s*(.+)$/.exec(line);
+        if (!match)
+            continue;
+        const [, name, linkedPath, description] = match;
+        if (!name ||
+            !linkedPath ||
+            !description ||
+            linkedPath.includes("..") ||
+            /[\\/]/.test(linkedPath.replace(/^memory\//, ""))) {
+            continue;
+        }
+        const path = linkedPath.startsWith("memory/")
+            ? linkedPath
+            : `memory/${linkedPath}`;
+        entries.push({ name, path, description });
+    }
+    return entries;
+}
+function memoryRelevanceScore(request, text) {
+    const searchable = text.toLowerCase();
+    const terms = new Set(request.toLowerCase().match(/[a-z0-9]{3,}/g) ?? []);
+    let score = 0;
+    for (const term of terms) {
+        if (searchable.includes(term))
+            score += Math.min(term.length, 8);
+    }
+    return score;
+}
+async function collectJevMemoryPromptCandidates(input) {
+    if (!input.owner || input.owner === SHARED_OWNER) {
+        return { candidates: [], fallbackIds: [] };
+    }
+    try {
+        input.signal.throwIfAborted();
+        const index = await resourceGetByPath(input.owner, "memory/MEMORY.md", {
+            orgId: input.orgId,
+        });
+        input.signal.throwIfAborted();
+        if (!index?.content)
+            return { candidates: [], fallbackIds: [] };
+        const memories = parseMemoryIndex(index.content)
+            .filter((memory) => memory.path !== "memory/MEMORY.md")
+            .map((memory, index) => ({
+            ...memory,
+            updatedAt: index,
+            score: memoryRelevanceScore(input.request, `${memory.name} ${memory.description}`),
+        }))
+            .sort((a, b) => b.score - a.score ||
+            b.updatedAt - a.updatedAt ||
+            a.path.localeCompare(b.path))
+            .slice(0, JEV_MEMORY_CANDIDATE_LIMIT);
+        const candidates = memories.map((memory, index) => ({
+            id: `personal-memory-${index}`,
+            kind: "memory",
+            description: `Personal memory: ${compactPromptLine(memory.description, JEV_MEMORY_DESCRIPTION_MAX_CHARS)}`,
+            metadata: { kind: "personal-memory", scope: "personal" },
+            name: memory.name,
+            scope: "personal",
+            path: memory.path,
+            content: "",
+        }));
+        const fallback = memories.find((memory) => memory.score >= 5);
+        const fallbackIndex = fallback ? memories.indexOf(fallback) : -1;
+        return {
+            candidates,
+            fallbackIds: fallbackIndex >= 0 ? [`personal-memory-${fallbackIndex}`] : [],
+        };
+    }
+    catch (error) {
+        console.warn("[agent] Jev memory context unavailable; continuing with the normal memory index.", error instanceof Error ? error.message : "unknown error");
+        return { candidates: [], fallbackIds: [] };
+    }
+}
+async function withinPromptBudget(work, deadlineAt) {
+    const remaining = deadlineAt - Date.now();
+    if (remaining <= 0)
+        return { status: "expired" };
+    const controller = new AbortController();
+    let timeout;
+    const result = await Promise.race([
+        Promise.resolve()
+            .then(() => work(controller.signal))
+            .then((value) => ({ status: "completed", value }), (error) => ({ status: "failed", error })),
+        new Promise((resolve) => {
+            timeout = setTimeout(() => {
+                controller.abort();
+                resolve({ status: "expired" });
+            }, remaining);
+        }),
+    ]);
+    if (timeout)
+        clearTimeout(timeout);
+    if (result.status === "failed") {
+        if (controller.signal.aborted)
+            return { status: "expired" };
+        throw result.error;
+    }
+    return result;
+}
+async function loadSelectedMemoryBodies(input) {
+    if (!input.owner || input.owner === SHARED_OWNER)
+        return input.candidates;
+    const selected = new Set(input.selectedIds);
+    const memories = input.candidates.filter((candidate) => selected.has(candidate.id) &&
+        candidate.kind === "memory" &&
+        Boolean(candidate.path));
+    if (memories.length === 0)
+        return input.candidates;
+    let loaded;
+    try {
+        loaded = await withinPromptBudget(async (signal) => {
+            const entries = [];
+            for (const candidate of memories) {
+                signal.throwIfAborted();
+                const resource = await resourceGetByPath(input.owner, candidate.path, { orgId: input.orgId });
+                signal.throwIfAborted();
+                entries.push(resource?.content.trim()
+                    ? { id: candidate.id, content: resource.content }
+                    : null);
+            }
+            return entries;
+        }, input.deadlineAt);
+    }
+    catch (error) {
+        console.warn("[agent] Selected memory bodies unavailable; continuing without them.", error instanceof Error ? error.message : "unknown error");
+        return input.candidates;
+    }
+    if (loaded.status === "expired")
+        return input.candidates;
+    const contentById = new Map(loaded.value.flatMap((entry) => (entry ? [[entry.id, entry.content]] : [])));
+    return input.candidates.map((candidate) => ({
+        ...candidate,
+        content: contentById.get(candidate.id) ?? candidate.content,
+    }));
+}
+function trackAnalyticsJevContext(input) {
+    if (input.appId !== "analytics")
+        return;
+    const selected = new Set(input.selectedIds);
+    const kinds = ["analytics-reference", "memory", "skill"];
+    const properties = {
+        jev_configured: input.jevConfigured,
+        jev_status: input.status,
+        selection_source: input.source,
+        candidate_count: input.candidates.length,
+        selected_count: selected.size,
+    };
+    for (const kind of kinds) {
+        const field = kind.replaceAll("-", "_");
+        properties[`candidate_${field}_count`] = input.candidates.filter((candidate) => candidate.metadata?.kind === kind || candidate.kind === kind).length;
+        properties[`selected_${field}_count`] = input.candidates.filter((candidate) => selected.has(candidate.id) &&
+            (candidate.metadata?.kind === kind || candidate.kind === kind)).length;
+    }
+    void import("../../tracking/registry.js")
+        .then(({ track }) => track("jev_context_prefetch", properties))
+        .catch(() => { });
+}
+function recordAnalyticsPreloadedReferenceCount(input) {
+    if (input.appId !== "analytics")
+        return;
+    const context = getRequestRunContext();
+    if (!context)
+        return;
+    context.analyticsJevPrefetch = {
+        preloadedReferenceCount: input.candidates.filter((candidate) => input.injectedIds.has(candidate.id) &&
+            (candidate.metadata?.kind === "analytics-reference" ||
+                candidate.kind === "analytics-reference")).length,
+    };
+}
 /** Rank and inline a few optional context sources before the first model call. */
 export async function preloadJevContextForPrompt(options) {
     const request = options.request.trim();
     const apiKey = options.apiKey?.trim();
     const personalApiKey = options.personalApiKey?.trim();
-    if (!request ||
-        (!apiKey && !personalApiKey && !options.builderAuth) ||
-        options.maxChars === 0) {
+    if (!request || options.maxChars === 0 || options.dispatchToBackground) {
         return "";
     }
-    const candidates = await collectJevPromptCandidates();
-    const selectedIds = await rankJevCandidates({
-        request,
-        apiKey,
-        personalApiKey,
-        builderAuth: options.builderAuth,
+    const deadlineAt = options.contextPrefetchDeadlineAt ?? Date.now() + JEV_PRELOAD_BUDGET_MS;
+    const hasJev = Boolean(apiKey || personalApiKey || options.builderAuth);
+    let runtimeCandidates = [];
+    let memoryContext = { candidates: [], fallbackIds: [] };
+    if (hasJev) {
+        try {
+            const collection = await withinPromptBudget((signal) => Promise.all([
+                collectJevPromptCandidates(signal),
+                collectJevMemoryPromptCandidates({
+                    owner: options.owner,
+                    orgId: options.orgId,
+                    request,
+                    signal,
+                }),
+            ]), deadlineAt);
+            if (collection.status === "completed") {
+                runtimeCandidates = collection.value[0];
+                memoryContext = collection.value[1];
+            }
+            else {
+                console.warn("[agent] Jev context candidates exceeded the preload budget; keeping Analytics retrieval fallback.");
+            }
+        }
+        catch (error) {
+            console.warn("[agent] Jev context candidates unavailable; keeping Analytics retrieval fallback.", error instanceof Error ? error.message : "unknown error");
+        }
+    }
+    const candidates = [
+        ...runtimeCandidates,
+        ...memoryContext.candidates,
+        ...(options.candidates ?? []),
+    ];
+    if (candidates.length === 0) {
+        trackAnalyticsJevContext({
+            appId: options.appId,
+            jevConfigured: hasJev,
+            status: "no_candidates",
+            source: "none",
+            candidates,
+            selectedIds: [],
+        });
+        return "";
+    }
+    const categoryFor = (candidate) => {
+        const kind = candidate.metadata?.kind ?? candidate.kind;
+        if (kind === "analytics-reference")
+            return "analytics-reference";
+        if (kind === "memory" || kind === "personal-memory")
+            return "memory";
+        return "skill";
+    };
+    const categories = ["skill", "memory", "analytics-reference"];
+    const candidatesByCategory = new Map(categories.map((category) => [
+        category,
+        candidates.filter((candidate) => categoryFor(candidate) === category),
+    ]));
+    const rankings = new Map();
+    if (hasJev) {
+        const rankAllCandidates = (signal) => Promise.all(categories.map(async (category) => {
+            const group = candidatesByCategory.get(category) ?? [];
+            if (group.length === 0)
+                return [category, null];
+            const rank = await rankJevCandidatesWithStatus({
+                request,
+                apiKey,
+                personalApiKey,
+                builderAuth: options.builderAuth,
+                candidates: group,
+                candidateStateKey: `candidate_${category.replaceAll("-", "_")}`,
+                answerKey: `best_${category.replaceAll("-", "_")}`,
+                signal,
+                timeoutMs: Math.min(JEV_TIMEOUT_MS, deadlineAt - Date.now()),
+                question: category === "skill"
+                    ? "Which skills are relevant to this task? Choose at most 3."
+                    : category === "memory"
+                        ? "Which prior user memories are important for this task? Choose at most 2 based only on their short summaries."
+                        : "Which Analytics data-dictionary entries or dashboard panels best match this request? Choose at most 2; references are examples, not live results.",
+                limit: category === "skill" ? 3 : JEV_MEMORY_SELECTION_LIMIT,
+            });
+            const groupIds = new Set(group.map((candidate) => candidate.id));
+            const ids = rank.ids.filter((id) => groupIds.has(id));
+            return [
+                category,
+                ids.length === 0 && rank.status === "selected"
+                    ? { status: "no-match", ids: [] }
+                    : { ...rank, ids },
+            ];
+        }));
+        try {
+            const ranked = await withinPromptBudget(rankAllCandidates, deadlineAt);
+            if (ranked.status === "completed") {
+                for (const [category, result] of ranked.value) {
+                    if (result)
+                        rankings.set(category, result);
+                }
+            }
+            else {
+                console.warn("[agent] Jev ranking exceeded the preload budget; using bounded retrieval fallbacks.");
+            }
+        }
+        catch (error) {
+            console.warn("[agent] Jev ranking unavailable; using bounded retrieval fallbacks.", error instanceof Error ? error.message : "unknown error");
+        }
+    }
+    const jevSelectedIds = [...rankings.values()]
+        .filter((result) => result.status === "selected")
+        .flatMap((result) => result.ids);
+    const selected = new Set(jevSelectedIds);
+    const analyticsCandidates = candidatesByCategory.get("analytics-reference") ?? [];
+    const highSimilarityReferenceIds = analyticsCandidates
+        .filter((candidate) => {
+        const similarity = Number(candidate.metadata?.similarity);
+        return (Number.isFinite(similarity) &&
+            similarity >= MIN_ANALYTICS_REFERENCE_SIMILARITY);
+    })
+        .slice(0, 1)
+        .map((candidate) => candidate.id);
+    const referenceRanking = rankings.get("analytics-reference");
+    if (analyticsCandidates.length > 0 &&
+        !analyticsCandidates.some((candidate) => selected.has(candidate.id))) {
+        if (!hasJev) {
+            for (const id of options.fallbackCandidateIds ?? [])
+                selected.add(id);
+        }
+        else if (highSimilarityReferenceIds.length > 0) {
+            for (const id of highSimilarityReferenceIds)
+                selected.add(id);
+        }
+        else if (!referenceRanking || referenceRanking.status === "unavailable") {
+            for (const id of options.fallbackCandidateIds ?? [])
+                selected.add(id);
+        }
+    }
+    const memoryRanking = rankings.get("memory");
+    if (hasJev &&
+        (!memoryRanking || memoryRanking.status === "unavailable") &&
+        memoryContext.fallbackIds.length > 0) {
+        for (const id of memoryContext.fallbackIds)
+            selected.add(id);
+    }
+    const selectionPriority = {
+        "analytics-reference": 0,
+        memory: 1,
+        skill: 2,
+    };
+    let selectedIds = candidates
+        .filter((candidate) => selected.has(candidate.id))
+        .sort((left, right) => selectionPriority[categoryFor(left)] -
+        selectionPriority[categoryFor(right)])
+        .map((candidate) => candidate.id);
+    const rankingStatuses = [...rankings.values()].map((result) => result.status);
+    const status = rankingStatuses.includes("selected")
+        ? "selected"
+        : rankings.size > 0 &&
+            rankingStatuses.every((value) => value === "no-match")
+            ? "no-match"
+            : "unavailable";
+    const selectionSource = jevSelectedIds.length
+        ? selectedIds.length > jevSelectedIds.length
+            ? "jev+fallback"
+            : "jev"
+        : selectedIds.length
+            ? "fallback"
+            : "none";
+    const withMemoryBodies = await loadSelectedMemoryBodies({
+        candidates,
+        selectedIds,
+        owner: options.owner,
+        orgId: options.orgId,
+        deadlineAt,
+    });
+    const bodyById = new Map(withMemoryBodies.map((candidate) => [candidate.id, candidate]));
+    candidates.splice(0, candidates.length, ...withMemoryBodies);
+    selectedIds = selectedIds.filter((id) => bodyById.get(id)?.content.trim());
+    trackAnalyticsJevContext({
+        appId: options.appId,
+        jevConfigured: hasJev,
+        status,
+        source: selectionSource,
         candidates,
-        candidateStateKey: "candidate_context",
-        answerKey: "best_context",
-        question: "Which skills or reference resources should be loaded into the agent context first for this task? Pick the most useful source; probabilities may be used to keep a small ranked shortlist.",
-        limit: 3,
+        selectedIds,
     });
-    if (selectedIds.length === 0)
+    if (selectedIds.length === 0) {
+        recordAnalyticsPreloadedReferenceCount({
+            appId: options.appId,
+            candidates,
+            injectedIds: new Set(),
+        });
         return "";
+    }
     const maxItemChars = options.compact ? 6_000 : JEV_CONTEXT_ITEM_MAX_CHARS;
     const maxTotalChars = Math.min(options.compact ? 16_000 : JEV_CONTEXT_TOTAL_MAX_CHARS, Math.max(0, options.maxChars ?? Number.POSITIVE_INFINITY));
     const contentBudget = Math.max(0, maxTotalChars - JEV_CONTEXT_WRAPPER_OVERHEAD_CHARS);
     const blocks = [];
+    const injectedIds = new Set();
     let usedChars = 0;
     for (const id of selectedIds) {
         const candidate = candidates.find((item) => item.id === id);
@@ -697,8 +1054,14 @@ export async function preloadJevContextForPrompt(options) {
         if (block.length > remaining)
             break;
         blocks.push(block);
+        injectedIds.add(candidate.id);
         usedChars += separatorChars + block.length;
     }
+    recordAnalyticsPreloadedReferenceCount({
+        appId: options.appId,
+        candidates,
+        injectedIds,
+    });
     if (blocks.length === 0)
         return "";
     return `${JEV_CONTEXT_PREFIX}${escapeJevContextFence(blocks.join(JEV_CONTEXT_SEPARATOR))}${JEV_CONTEXT_SUFFIX}`;

package/dist/server/agent-chat-plugin.d.ts

@@ -1,5 +1,5 @@
 import type { Message as A2AMessage } from "../a2a/types.js";
-import { type ActionEntry } from "../agent/production-agent.js";
+import { type ActionEntry, type AgentActionSurfaceDetails, type AgentActionSurfaceResolution } from "../agent/production-agent.js";
 import type { ActiveRun } from "../agent/run-manager.js";
 import type { AgentChatEvent, AgentChatScope } from "../agent/types.js";
 import type { ResolvedKeyReference } from "../secrets/substitution.js";
@@ -41,6 +41,7 @@ export { scheduledTriggerAvailability };
 export { shouldDisableRecurringJobsRuntime };
 export { finalizeClaimedAgentChatProcessRunFailure };
 export declare function runPostAgentTurnAutosave(callback: AgentChatPluginOptions["onAgentTurnComplete"] | undefined, scope: AgentChatScope | null | undefined, run: ActiveRun): Promise<void>;
+export declare function runPostAgentRunComplete(callback: AgentChatPluginOptions["onAgentRunComplete"] | undefined, scope: AgentChatScope | null | undefined, run: ActiveRun): Promise<void>;
 export declare function runPreAgentTurnAutosave(callback: AgentChatPluginOptions["onAgentTurnStart"] | undefined, scope: AgentChatScope | null | undefined, run: Pick<ActiveRun, "threadId" | "runId">): Promise<void>;
 /**
  * The model this mount runs with, when the caller does not pass one per request.
@@ -73,6 +74,7 @@ export declare function filterRuntimeActionsToSurface(actions: Record<string, Ac
  * teaching the model names it cannot call. */
 export declare function filterFrameworkPromptToSurface(prompt: string, actions: Record<string, ActionEntry>, allowedActionNames?: readonly string[]): string;
 export declare function resolveProductionCodeExecutionForActionSurface(mode: "off" | "sandboxed" | "trusted", hasRequestScopedSurface: boolean): "off" | "sandboxed" | "trusted";
+export declare function resolveObservabilityReviewSummaryActionSurface(details: AgentActionSurfaceDetails, resolveHostSurface?: (details: AgentActionSurfaceDetails) => AgentActionSurfaceResolution | Promise<AgentActionSurfaceResolution>): Promise<AgentActionSurfaceResolution>;
 /**
  * Abort reasons that mean a human asked to stop, so `/runs/:id/abort` escalates
  * to a turn-wide abort. Watchdog reasons (`no_progress`, `auto_stuck_retry`)