@agent-native/core 0.212.0-nightly-20261021064625 → 0.212.0

package/dist/a2a/app-profile.d.ts

@@ -0,0 +1,4 @@
+import type { AgentProfileMetadata } from "../shared/agent-profile.js";
+import type { AgentSkill } from "./types.js";
+/** Add app examples only to the one skill whose own wording clearly matches. */
+export declare function addAgentProfileExamples<T extends AgentSkill>(skills: T[], profile: AgentProfileMetadata | null): T[];

package/dist/a2a/app-profile.js

@@ -0,0 +1,95 @@
+const PROFILE_EXAMPLE_STOP_WORDS = new Set([
+    "a",
+    "an",
+    "and",
+    "for",
+    "from",
+    "in",
+    "into",
+    "me",
+    "my",
+    "of",
+    "on",
+    "or",
+    "the",
+    "this",
+    "to",
+    "with",
+]);
+const PROFILE_WORD_ALIASES = {
+    build: "generate",
+    create: "generate",
+    link: "url",
+    make: "generate",
+};
+const manifestExamples = new WeakMap();
+function profileWords(value) {
+    return new Set(value
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((word) => word && !PROFILE_EXAMPLE_STOP_WORDS.has(word))
+        .map((word) => PROFILE_WORD_ALIASES[word] ?? word));
+}
+/** Add app examples only to the one skill whose own wording clearly matches. */
+export function addAgentProfileExamples(skills, profile) {
+    if (!skills.length)
+        return skills;
+    const manifestSkills = skills.map((skill) => {
+        const examples = manifestExamples.get(skill);
+        if (examples === undefined && !manifestExamples.has(skill))
+            return skill;
+        const { examples: _derivedExamples, ...rest } = skill;
+        return {
+            ...rest,
+            ...(examples ? { examples } : {}),
+        };
+    });
+    if (!profile?.whenToUse?.length)
+        return manifestSkills;
+    const examplesBySkill = new Map();
+    for (const example of profile.whenToUse) {
+        const words = profileWords(example);
+        let bestSkill;
+        let bestScore = 0;
+        let runnerUpScore = 0;
+        let tied = false;
+        for (const skill of manifestSkills) {
+            const skillWords = profileWords(`${skill.id} ${skill.name} ${skill.description}`);
+            let score = 0;
+            for (const word of words)
+                if (skillWords.has(word))
+                    score += 1;
+            if (score > bestScore) {
+                runnerUpScore = bestScore;
+                bestSkill = skill;
+                bestScore = score;
+                tied = false;
+            }
+            else if (score === bestScore && score > 1) {
+                tied = true;
+            }
+            else if (score > runnerUpScore) {
+                runnerUpScore = score;
+            }
+        }
+        if (!bestSkill || tied || bestScore - runnerUpScore < 2)
+            continue;
+        const examples = examplesBySkill.get(bestSkill.id) ?? [];
+        examples.push(example);
+        examplesBySkill.set(bestSkill.id, examples);
+    }
+    return manifestSkills.map((skill) => {
+        const examples = examplesBySkill.get(skill.id);
+        if (!examples?.length)
+            return skill;
+        const updated = {
+            ...skill,
+            examples: [
+                ...(skill.examples ?? []),
+                ...examples.filter((example) => !skill.examples?.includes(example)),
+            ],
+        };
+        manifestExamples.set(updated, skill.examples);
+        return updated;
+    });
+}

package/dist/a2a/server.d.ts

@@ -47,6 +47,7 @@ export declare function verifyA2AToken(token: string, event?: any, audienceOptio
     globalSecretOnly?: boolean;
     /** Only use this explicitly configured credential; never fall back. */
     verificationSecret?: string;
+    requireAudience?: boolean;
 }): Promise<A2ATokenPayload>;
 export type A2ATokenFailureCause = "malformed" | "secret-missing" | "audience-unresolvable" | "audience" | "issuer" | "expired" | "signature" | "invalid-claims" | "mcp-credential" | "missing-subject" | "org-binding" | "org-lookup-failed" | "undetermined";
 /**

package/dist/a2a/server.js

@@ -15,6 +15,7 @@ import { publicFrameworkPath } from "../server/framework-route-prefix.js";
 import { readBody } from "../server/h3-helpers.js";
 import { isSameOriginRequest } from "../server/request-origin.js";
 import { generateAgentCard } from "./agent-card.js";
+import { addAgentProfileExamples } from "./app-profile.js";
 import { canonicalA2AAudience } from "./audience.js";
 import { hasConfiguredA2ASecret, isA2AProductionRuntime, } from "./auth-policy.js";
 import { handleJsonRpcH3, processA2ATaskFromQueue } from "./handlers.js";
@@ -301,8 +302,12 @@ async function verifyA2ATokenInternal(token, event, audienceOptions) {
     //   it was minted from", which `jose.jwtVerify` validates exactly when
     //   `issuer` is supplied as a string. Backward-compat: when the token
     //   has no `iss`, we skip the check.
+    const hasAudience = unverifiedPayload && typeof unverifiedPayload.aud !== "undefined";
+    if (audienceOptions?.requireAudience && !hasAudience) {
+        return { payload: { email: null, orgDomain: null } };
+    }
     const verifyOptions = {};
-    if (unverifiedPayload && typeof unverifiedPayload.aud !== "undefined") {
+    if (hasAudience) {
         // Fail closed: the token was minted for a specific audience, but this
         // receiver can't derive its own expected audience (no APP_URL/URL and no
         // usable request host). Accepting here would let a correctly-signed token
@@ -416,12 +421,17 @@ export function mountA2A(nitroApp, config, routePrefix = "/_agent-native") {
             setResponseStatus(event, 405);
             return { error: "Method not allowed" };
         }
+        setResponseHeader(event, "cache-control", "private, no-store");
         const protocol = getRequestHeader(event, "x-forwarded-proto") ||
             (event.url?.protocol?.replace(":", "") ?? "http");
         const host = getRequestHeader(event, "host") ?? "localhost";
         const baseUrl = `${protocol}://${host}`;
         let skills = filterPublicAgentCardSkills(config);
-        if (config.authenticatedSkills?.length) {
+        let description = config.description;
+        let profileResolved = false;
+        if (config.authenticatedSkills?.length ||
+            config.resolveAuthenticatedProfile ||
+            config.resolvePublicProfile) {
             const bearer = extractBearerToken(getRequestHeader(event, "authorization"));
             if (bearer) {
                 try {
@@ -430,9 +440,26 @@ export function mountA2A(nitroApp, config, routePrefix = "/_agent-native") {
                         allowBaseAudience: true,
                     });
                     if (payload.email) {
-                        skills = tokenHasAudienceClaim(bearer)
-                            ? config.authenticatedSkills
-                            : config.authenticatedSkills.filter((skill) => !isDirectReadSkill(skill));
+                        if (config.authenticatedSkills?.length) {
+                            skills = tokenHasAudienceClaim(bearer)
+                                ? config.authenticatedSkills
+                                : config.authenticatedSkills.filter((skill) => !isDirectReadSkill(skill));
+                        }
+                        let profile;
+                        try {
+                            profile = await config.resolveAuthenticatedProfile?.({
+                                userEmail: payload.email,
+                                ...(payload.orgId ? { orgId: payload.orgId } : {}),
+                            });
+                        }
+                        catch {
+                            console.warn("[a2a] authenticated profile resolution failed");
+                        }
+                        if (profile) {
+                            description = profile.description ?? description;
+                            skills = addAgentProfileExamples(skills, profile);
+                            profileResolved = true;
+                        }
                     }
                 }
                 catch (error) {
@@ -446,7 +473,19 @@ export function mountA2A(nitroApp, config, routePrefix = "/_agent-native") {
                 }
             }
         }
-        return generateAgentCard({ ...config, skills }, baseUrl, publicFrameworkPath(`${routePrefix}/a2a`));
+        if (!profileResolved) {
+            try {
+                const profile = await config.resolvePublicProfile?.();
+                if (profile) {
+                    description = profile.description ?? description;
+                    skills = addAgentProfileExamples(skills, profile);
+                }
+            }
+            catch {
+                console.warn("[a2a] public profile resolution failed");
+            }
+        }
+        return generateAgentCard({ ...config, description, skills }, baseUrl, publicFrameworkPath(`${routePrefix}/a2a`));
     }));
     // Human-only continuation for consequential A2A tool calls. The opaque id
     // is a lookup handle, not authorization: every read and mutation also

package/dist/a2a/types.d.ts

@@ -1,4 +1,5 @@
 import type { PublicAgentActionConfig } from "../action.js";
+import type { AgentProfileMetadata } from "../shared/agent-profile.js";
 export type { A2AAgentActivityPhase, A2AAgentActivitySnapshot, A2AAgentActivityState, A2AAgentActivityToolCall, A2AAgentActivityToolStatus, } from "./activity.js";
 export interface TextPart {
     type: "text";
@@ -191,6 +192,11 @@ export interface A2AConfig {
     version?: string;
     skills: AgentSkill[];
     authenticatedSkills?: AgentSkill[];
+    resolvePublicProfile?: () => Promise<AgentProfileMetadata>;
+    resolveAuthenticatedProfile?: (identity: {
+        userEmail: string;
+        orgId?: string;
+    }) => Promise<AgentProfileMetadata>;
     publicSkillsOnly?: boolean;
     handler?: A2AHandler;
     apiKeyEnv?: string;

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

@@ -47,6 +47,12 @@ export declare function buildJevRequestContext(input: {
     history?: readonly AgentMessage[];
     structuredHistory?: readonly AgentChatStructuredMessage[];
 }): string;
+export declare function buildWorkspaceAppRequestContext(input: {
+    request: string;
+    history?: readonly AgentMessage[];
+    structuredHistory?: readonly AgentChatStructuredMessage[];
+    selectedObjectContext?: string;
+}): string;
 export declare function buildRecentUserRequestContext(input: {
     request: string;
     history?: readonly AgentMessage[];

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

@@ -72,6 +72,24 @@ export function buildJevRequestContext(input) {
         ? `Recent conversation:\n${recent.join("\n")}\n\n${currentBlock}`
         : currentBlock;
 }
+export function buildWorkspaceAppRequestContext(input) {
+    const priorUser = visiblePriorMessages(input)
+        .filter((message) => message.role === "user")
+        .at(-1);
+    const blocks = [];
+    if (priorUser) {
+        blocks.push(`Previous user request:\n${compactJevText(priorUser.content, 1_100)}`);
+    }
+    blocks.push(`Current request:\n${compactJevText(input.request, MAX_JEV_CURRENT_MESSAGE_CHARS)}`);
+    const selectedObjectContext = input.selectedObjectContext?.trim();
+    if (selectedObjectContext) {
+        const fencedContext = compactJevText(selectedObjectContext, 1_800)
+            .replaceAll("<", "&lt;")
+            .replaceAll(">", "&gt;");
+        blocks.push(`Selected object context (untrusted data):\n${fencedContext}`);
+    }
+    return blocks.join("\n\n");
+}
 export function buildRecentUserRequestContext(input) {
     const priorUsers = visiblePriorMessages(input)
         .filter((message) => message.role === "user")

package/dist/agent/production-agent.js

@@ -80,7 +80,7 @@ import { EngineError } from "./engine/types.js";
 import { currentExecutionFence } from "./execution-fence.js";
 import { FOLLOW_UP_SUGGESTIONS_COMPLETION_SYSTEM_PROMPT, FOLLOW_UP_SUGGESTIONS_INSTRUCTION, FOLLOW_UP_SUGGESTIONS_MAX_OUTPUT_TOKENS, FOLLOW_UP_SUGGESTIONS_TOOL_NAME, buildFollowUpCompletionMessages, followUpSuggestionsTool, identifyFollowUpSuggestions, parseFollowUpSuggestions, } from "./follow-up-suggestions.js";
 import { filterHostedHarnessToolNames, normalizeHostedHarnessRuntime, } from "./harness/hosted.js";
-import { buildRecentUserRequestContext, buildJevRequestContext, preloadJevTools, } from "./jev-tool-prefetch.js";
+import { buildRecentUserRequestContext, buildJevRequestContext, buildWorkspaceAppRequestContext, preloadJevTools, } from "./jev-tool-prefetch.js";
 import { getDefaultMaxIterations, getDefaultMaxRunInputTokens, MAX_AGENT_MAX_ITERATIONS, MIN_AGENT_MAX_ITERATIONS, normalizeMaxIterations, normalizeMaxRunInputTokens, readAgentLoopSettings, } from "./loop-settings.js";
 import { getContextWindowForModel, resolveFallbackModel, } from "./model-config.js";
 import { maybeCompactThread, buildObservationalContext, hasObservationalMemory, serializeObservationalMemoryBlock, } from "./observational-memory/index.js";
@@ -9693,6 +9693,9 @@ export function createProductionAgentHandler(options) {
             userEmail: ownerEmail ?? getRequestUserEmail() ?? null,
             orgId: getRequestOrgId() ?? null,
         }).catch(() => readAgentLoopSettings({}));
+        const promptRunContext = ensureRequestRunContext();
+        if (promptRunContext)
+            promptRunContext.appDiscoveryQuery = requestMessage;
         let systemPromptError = null;
         const systemPromptThunk = () => (async () => {
             const sysPromptStart = Date.now();
@@ -10016,6 +10019,12 @@ export function createProductionAgentHandler(options) {
             withoutUnavailableNote(screenBlock) +
             withoutUnavailableNote(urlBlock) +
             withoutUnavailableNote(selectionBlock);
+        const workspaceAppRequest = buildWorkspaceAppRequestContext({
+            request: requestMessage,
+            history: requestHistory,
+            structuredHistory: requestStructuredHistory,
+            selectedObjectContext: withoutUnavailableNote(selectionBlock),
+        });
         const screenStatus = worstContextStatus(...Object.values(screenStatuses));
         const surfacedActionRegistry = requestMode === "plan"
             ? createPlanModeActionRegistry(surfacedRequestActions)
@@ -10056,7 +10065,10 @@ export function createProductionAgentHandler(options) {
             }),
             preloadJevContextWithStatus({
                 request: jevRequestContext,
+                appRequest: workspaceAppRequest,
                 appId: options.appId,
+                selfAppId: options.appId,
+                workspaceAppsEnabled: Boolean(requestActions["call-agent"]),
                 owner: ownerEmail ?? undefined,
                 orgId: getRequestOrgId() ?? null,
                 apiKey: jevContextCredentials.apiKey,
@@ -10074,6 +10086,12 @@ export function createProductionAgentHandler(options) {
         const jevContext = jevPreload.context;
         if (jevContext)
             systemPrompt = `${systemPrompt}\n\n${jevContext}`;
+        if (jevPreload.relevantAppsContext) {
+            systemPrompt = `${systemPrompt}\n\n${jevPreload.relevantAppsContext}`;
+        }
+        if (runContext && jevPreload.appSelection) {
+            runContext.appDiscoverySelection = jevPreload.appSelection;
+        }
         const prefetchStatus = worstContextStatus(jevPreload.status, preparedReferenceStatus);
         if (runContext) {
             runContext.contextStatus = {
@@ -10101,6 +10119,17 @@ export function createProductionAgentHandler(options) {
                     },
                 ])
                 : []),
+            ...(jevPreload.relevantAppsContext
+                ? await buildSystemManifestSections([
+                    {
+                        label: "Relevant workspace apps",
+                        provenance: "runtime-context",
+                        governance: "inherited",
+                        content: jevPreload.relevantAppsContext,
+                        sourceRef: { scope: "workspace-apps" },
+                    },
+                ])
+                : []),
             ...(requestTools.length > 0
                 ? await buildSystemManifestSections([
                     {

package/dist/automation/index.d.ts

@@ -139,8 +139,8 @@ export declare function createAutomationCallbackHandler(runtime: AutomationRunti
     duplicate?: undefined;
     eventId?: undefined;
 } | {
-    error?: undefined;
     accepted: boolean;
     duplicate: boolean;
     eventId: string;
+    error?: undefined;
 }>;

package/dist/collab/awareness.d.ts

@@ -38,19 +38,19 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
     error: string;
     states?: undefined;
 } | {
+    error?: undefined;
     states: {
         clientId: number;
         state: string;
     }[];
-    error?: undefined;
 }>>;
 export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
     users?: undefined;
 } | {
+    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
-    error?: undefined;
 }>>;

package/dist/collab/index.d.ts

@@ -1,6 +1,6 @@
 export { loadYDocState, loadYDocVersion, hasCollabState, deleteCollabState, uint8ArrayToBase64, base64ToUint8Array, strictBase64ToUint8Array, CollabStateMalformedError, type CollabStateMalformedReason, } from "./storage.js";
 export { createBoundedTaskRunner, measureBoundedPayload, BoundedTaskError, BOUNDED_TASK_GLOBAL, type BoundedTaskErrorCode, type BoundedTaskRunner, type BoundedTaskRunnerOptions, type BoundedTaskRunnerStats, type BoundedTaskSource, } from "./bounded-tasks.js";
-export { bundleBoundedTaskSource, type BundleBoundedTaskSourceOptions, type BundledBoundedTaskSource, } from "./bounded-task-bundle.js";
+export type { BundleBoundedTaskSourceOptions, BundledBoundedTaskSource, } from "./bounded-task-bundle.js";
 export { defineLiveCopy, releaseLiveCopy, LiveCopyError, LIVE_COPY_DEFAULT_FIELD, type LiveCopyBinding, type LiveCopyCommit, type LiveCopyErrorCode, type LiveCopyOptions, type LiveCopyOutcome, type LiveCopyPersistOutcome, } from "./live-copy.js";
 export { CollabBaseVersionConflictError, getDoc, saveYDocState, withPreparedYDocMutation, applyUpdate, seedXmlFragmentIfEmpty, applyText, getText, getState, getIncUpdate, seedFromText, releaseDoc, searchAndReplace, applyJson, applyPatchOps, getJson, seedFromJson, readLiveCopy, mutateLiveCopy, seedLiveCopy, type PreparedYDocMutationLease, type LiveCopyRead, type MutateLiveCopyOptions, type LiveCopyCallChange, type LiveCopyMutationResult, type SeedLiveCopyOptions, type LiveCopySeedResult, } from "./ydoc-manager.js";
 export { searchAndReplaceInYXml, extractTextFromYXml } from "./xml-ops.js";

package/dist/collab/index.js

@@ -1,6 +1,5 @@
 export { loadYDocState, loadYDocVersion, hasCollabState, deleteCollabState, uint8ArrayToBase64, base64ToUint8Array, strictBase64ToUint8Array, CollabStateMalformedError, } from "./storage.js";
 export { createBoundedTaskRunner, measureBoundedPayload, BoundedTaskError, BOUNDED_TASK_GLOBAL, } from "./bounded-tasks.js";
-export { bundleBoundedTaskSource, } from "./bounded-task-bundle.js";
 export { defineLiveCopy, releaseLiveCopy, LiveCopyError, LIVE_COPY_DEFAULT_FIELD, } from "./live-copy.js";
 export { CollabBaseVersionConflictError, getDoc, saveYDocState, withPreparedYDocMutation, applyUpdate, seedXmlFragmentIfEmpty, applyText, getText, getState, getIncUpdate, seedFromText, releaseDoc, searchAndReplace, applyJson, applyPatchOps, getJson, seedFromJson, readLiveCopy, mutateLiveCopy, seedLiveCopy, } from "./ydoc-manager.js";
 export { searchAndReplaceInYXml, extractTextFromYXml } from "./xml-ops.js";

package/dist/deploy/workspace-deploy.js

@@ -8,6 +8,7 @@ import { INTEGRATION_RECOVERY_RUNTIME_MARKER, INTEGRATION_RETRY_SWEEP_PATH, INTE
 import { RECURRING_JOBS_SWEEP_PATH, RECURRING_JOBS_SWEEP_TOKEN_SUBJECT, } from "../jobs/scheduler-dispatch.js";
 import { findWorkspaceRoot } from "../scripts/utils.js";
 import { BUILTIN_AGENTS_ENV_KEY, workspaceBuiltinAgentsJson, } from "../server/builtin-agents.js";
+import { parseAgentProfileMetadataFields } from "../shared/agent-profile.js";
 import { normalizeFrameworkRoutePrefix } from "../shared/framework-route-prefix.js";
 import { DEFAULT_WORKSPACE_APP_AUDIENCE, normalizeWorkspaceAppHomePath, normalizeWorkspaceAppAudience, normalizeWorkspaceAppPathList, workspaceAppAudienceFromPackageJson, workspaceAppRouteAccessFromPackageJson, } from "../shared/workspace-app-audience.js";
 import { DISPATCH_WORKSPACE_ROOT_REDIRECTS, isValidWorkspaceAppIdFormat, } from "../shared/workspace-app-id.js";
@@ -1412,10 +1413,41 @@ async function readWorkspaceAppManifest(workspaceRoot, apps, appsDir) {
         const packageRouteAccess = workspaceAppRouteAccessFromPackageJson(pkg);
         const publicPaths = packageRouteAccess.publicPaths ?? explicit?.publicPaths ?? [];
         const protectedPaths = packageRouteAccess.protectedPaths ?? explicit?.protectedPaths ?? [];
+        const agentNative = pkg?.["agent-native"];
+        const profile = parseAgentProfileMetadataFields({
+            description: pkg?.description,
+            ...(agentNative &&
+                typeof agentNative === "object" &&
+                ("whenToUse" in agentNative || "aliases" in agentNative)
+                ? {
+                    ...("whenToUse" in agentNative
+                        ? { whenToUse: agentNative.whenToUse }
+                        : {}),
+                    ...("aliases" in agentNative
+                        ? { aliases: agentNative.aliases }
+                        : {}),
+                }
+                : {}),
+        });
+        if (profile.invalidFields.length) {
+            console.warn(`[workspace] Ignoring invalid agent profile metadata in ${app}: ${profile.invalidFields.join(", ")}`);
+        }
         entries.push({
             id: app,
             name: pkg?.displayName || titleCase(app),
-            description: pkg?.description || "",
+            description: profile.metadata.description ?? "",
+            ...(profile.metadata.whenToUse || profile.metadata.aliases
+                ? {
+                    "agent-native": {
+                        ...(profile.metadata.whenToUse
+                            ? { whenToUse: profile.metadata.whenToUse }
+                            : {}),
+                        ...(profile.metadata.aliases
+                            ? { aliases: profile.metadata.aliases }
+                            : {}),
+                    },
+                }
+                : {}),
             path: appPath,
             homePath: normalizeWorkspaceAppHomePath(explicit?.homePath ??
                 configuredHomePath ??

package/dist/extensions/url-safety.js

@@ -26,12 +26,10 @@ function isPrivateIpv4(a, b, c = 0, d = 0) {
         return true;
     if (a === 100 && b >= 64 && b <= 127)
         return true;
-    if (a === 192 && b === 0)
+    if (a === 192 && b === 0 && (c === 0 || c === 2))
         return true;
     if (a === 198 && (b === 18 || b === 19))
         return true;
-    if (a === 192 && b === 0 && c === 2)
-        return true;
     if (a === 198 && b === 51 && c === 100)
         return true;
     if (a === 203 && b === 0 && c === 113)
@@ -64,9 +62,9 @@ function isPrivateHost(hostname) {
     }
     if (METADATA_HOSTS.includes(host))
         return true;
-    if (/^f[cd]/.test(host) || /^fe[89ab]/.test(host))
+    if (host.includes(":") && (/^f[cd]/.test(host) || /^fe[89ab]/.test(host)))
         return true;
-    if (/^ff/i.test(host))
+    if (host.includes(":") && /^ff/i.test(host))
         return true;
     const v4mappedDotted = host.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
     if (v4mappedDotted) {

package/dist/file-upload/actions/upload-image.d.ts

@@ -42,8 +42,8 @@ declare const _default: import("../../action.js").ActionDefinition<{
     url: string;
     id: string;
     provider: string;
-    configured?: undefined;
     error?: undefined;
+    configured?: undefined;
 } | {
     url?: undefined;
     id?: undefined;