@agent-native/core 0.122.3 → 0.123.0

package/corpus/core/src/resources/handlers.ts

@@ -114,12 +114,8 @@ async function resolveEmail(event: any): Promise<string> {
 }
 
 async function resolveOrgId(event: any): Promise<string | null> {
-  try {
-    const ctx = await getOrgContext(event);
-    return ctx.orgId ?? null;
-  } catch {
-    return null;
-  }
+  const ctx = await getOrgContext(event);
+  return ctx.orgId ?? null;
 }
 
 /**

package/corpus/core/src/resources/script-helpers.ts

@@ -7,6 +7,7 @@
  */
 
 import {
+  getAmbientUserEmail,
   getRequestOrgId,
   getRequestUserEmail,
 } from "../server/request-context.js";
@@ -34,7 +35,7 @@ function getOwnerForScope(scope?: ResourceHelperScope): string {
   if (scope === "workspace") return WORKSPACE_OWNER;
   const userEmail = getRequestUserEmail();
   if (userEmail) return userEmail;
-  const cliEmail = process.env.AGENT_USER_EMAIL;
+  const cliEmail = getAmbientUserEmail();
   if (cliEmail) return cliEmail;
   throw new Error(
     "Resource access requires an authenticated request context or AGENT_USER_EMAIL env var",

package/corpus/core/src/scripts/chat/search-chats.ts

@@ -8,11 +8,14 @@
  */
 
 import { searchThreads, listThreads } from "../../chat-threads/store.js";
-import { getRequestUserEmail } from "../../server/request-context.js";
+import {
+  getAmbientUserEmail,
+  getRequestUserEmail,
+} from "../../server/request-context.js";
 import { parseArgs, fail } from "../utils.js";
 
 function getOwnerEmail(): string {
-  const email = getRequestUserEmail() ?? process.env.AGENT_USER_EMAIL;
+  const email = getRequestUserEmail() ?? getAmbientUserEmail();
   if (!email) {
     fail(
       "search-chats requires an authenticated user (request context or AGENT_USER_EMAIL env var).",

package/corpus/core/src/scripts/describe-workspace-apps.ts

@@ -0,0 +1,59 @@
+import type { ActionTool } from "../agent/types.js";
+import {
+  formatCapabilityDetail,
+  formatCapabilitySummary,
+  loadAllCapabilities,
+  loadCapabilities,
+  MAX_APPS,
+} from "../server/agent-capabilities.js";
+import { discoverAgents, findAgent } from "../server/agent-discovery.js";
+
+export const tool: ActionTool = {
+  description:
+    "Describe what the OTHER apps in this workspace can do for this app, read live from each peer's published A2A agent card. Use this before building a capability locally, before telling the user what is or is not possible across apps, and whenever the user asks which app they should use for something. Returns each peer's purpose plus the exact read-only action names callable through call-agent. Pass `app` for one peer's full capability list. This is generated from live deployments — never hand-maintain or cache a list of workspace apps in code, docs, or markdown.",
+  parameters: {
+    type: "object",
+    properties: {
+      app: {
+        type: "string",
+        description:
+          "Optional app id or name. When set, returns that one peer's full capability list instead of a summary of every peer.",
+      },
+    },
+  },
+};
+
+export async function run(
+  args: Record<string, unknown>,
+  _context?: unknown,
+  selfAppId?: string,
+): Promise<string> {
+  const requested = String(args.app ?? "").trim();
+
+  if (requested) {
+    const agent = await findAgent(requested, selfAppId);
+    if (!agent) {
+      const available = (await discoverAgents(selfAppId))
+        .map((peer) => peer.id)
+        .join(", ");
+      return `Error: no workspace app "${requested}". Available: ${available || "(none)"}`;
+    }
+    return formatCapabilityDetail(
+      await loadCapabilities(agent),
+      (appId) =>
+        `Call one with call-agent: agent="${appId}", action="<id above>", input={...}.`,
+    );
+  }
+
+  const agents = await discoverAgents(selfAppId);
+  if (agents.length === 0) {
+    return "No other apps are reachable from this one. This app is running standalone, so build the capability here rather than delegating.";
+  }
+
+  const shown = agents.slice(0, MAX_APPS);
+  return formatCapabilitySummary(
+    await loadAllCapabilities(shown),
+    agents.length - shown.length,
+    (appId) => `call describe-workspace-apps with app="${appId}"`,
+  );
+}

package/corpus/core/src/scripts/resources/delete-memory.ts

@@ -9,7 +9,10 @@ import {
   resourceGetByPath,
   resourceDeleteByPath,
 } from "../../resources/store.js";
-import { getRequestUserEmail } from "../../server/request-context.js";
+import {
+  getAmbientUserEmail,
+  getRequestUserEmail,
+} from "../../server/request-context.js";
 import { parseArgs, fail } from "../utils.js";
 
 export default async function deleteMemoryScript(
@@ -20,7 +23,7 @@ export default async function deleteMemoryScript(
   const name = parsed.name;
   if (!name) fail("--name is required (e.g. 'coding-style')");
 
-  const owner = getRequestUserEmail() ?? process.env.AGENT_USER_EMAIL;
+  const owner = getRequestUserEmail() ?? getAmbientUserEmail();
   if (!owner) {
     fail(
       "delete-memory requires an authenticated user (request context or AGENT_USER_EMAIL env var).",

package/corpus/core/src/scripts/resources/delete.ts

@@ -13,7 +13,10 @@ import {
   SHARED_OWNER,
   WORKSPACE_OWNER,
 } from "../../resources/store.js";
-import { getRequestUserEmail } from "../../server/request-context.js";
+import {
+  getAmbientUserEmail,
+  getRequestUserEmail,
+} from "../../server/request-context.js";
 import { parseArgs, fail } from "../utils.js";
 
 export default async function resourceDeleteScript(
@@ -51,7 +54,7 @@ Options:
   } else if (scope === "workspace") {
     owner = WORKSPACE_OWNER;
   } else {
-    const personalOwner = getRequestUserEmail() ?? process.env.AGENT_USER_EMAIL;
+    const personalOwner = getRequestUserEmail() ?? getAmbientUserEmail();
     if (!personalOwner) {
       fail(
         "resource-delete --scope=personal requires an authenticated user (request context or AGENT_USER_EMAIL env var).",

package/corpus/core/src/scripts/resources/effective.ts

@@ -12,7 +12,10 @@ import {
   ensurePersonalDefaults,
   resourceEffectiveContext,
 } from "../../resources/store.js";
-import { getRequestUserEmail } from "../../server/request-context.js";
+import {
+  getAmbientUserEmail,
+  getRequestUserEmail,
+} from "../../server/request-context.js";
 import { parseArgs, fail } from "../utils.js";
 
 export default async function resourceEffectiveScript(
@@ -35,7 +38,7 @@ Options:
     fail("--path is required. Example: --path instructions/guardrails.md");
   }
 
-  const owner = getRequestUserEmail() ?? process.env.AGENT_USER_EMAIL;
+  const owner = getRequestUserEmail() ?? getAmbientUserEmail();
   if (!owner) {
     fail(
       "resource-effective requires an authenticated user (request context or AGENT_USER_EMAIL env var).",

package/corpus/core/src/scripts/resources/list.ts

@@ -14,7 +14,10 @@ import {
   SHARED_OWNER,
   WORKSPACE_OWNER,
 } from "../../resources/store.js";
-import { getRequestUserEmail } from "../../server/request-context.js";
+import {
+  getAmbientUserEmail,
+  getRequestUserEmail,
+} from "../../server/request-context.js";
 import { parseArgs, fail } from "../utils.js";
 
 export default async function resourceListScript(
@@ -42,7 +45,7 @@ Options:
     parsed["include-agent-scratch"] === "true" ||
     parsed.includeAgentScratch === "true" ||
     parsed.includeScratch === "true";
-  const owner = getRequestUserEmail() ?? process.env.AGENT_USER_EMAIL;
+  const owner = getRequestUserEmail() ?? getAmbientUserEmail();
   if (!owner) {
     fail(
       "resource-list requires an authenticated user (request context or AGENT_USER_EMAIL env var).",

package/corpus/core/src/scripts/resources/read.ts

@@ -13,7 +13,10 @@ import {
   SHARED_OWNER,
   WORKSPACE_OWNER,
 } from "../../resources/store.js";
-import { getRequestUserEmail } from "../../server/request-context.js";
+import {
+  getAmbientUserEmail,
+  getRequestUserEmail,
+} from "../../server/request-context.js";
 import { parseArgs, fail } from "../utils.js";
 
 export default async function resourceReadScript(
@@ -38,7 +41,7 @@ Options:
   }
 
   const scope = parsed.scope;
-  const owner = getRequestUserEmail() ?? process.env.AGENT_USER_EMAIL;
+  const owner = getRequestUserEmail() ?? getAmbientUserEmail();
   if (!owner) {
     fail(
       "resource-read requires an authenticated user (request context or AGENT_USER_EMAIL env var).",

package/corpus/core/src/scripts/resources/save-memory.ts

@@ -7,7 +7,10 @@
  */
 
 import { resourcePut, resourceGetByPath } from "../../resources/store.js";
-import { getRequestUserEmail } from "../../server/request-context.js";
+import {
+  getAmbientUserEmail,
+  getRequestUserEmail,
+} from "../../server/request-context.js";
 import { parseArgs, fail } from "../utils.js";
 
 const VALID_TYPES = ["user", "feedback", "project", "reference"] as const;
@@ -32,7 +35,7 @@ export default async function saveMemoryScript(args: string[]): Promise<void> {
   const content = parsed.content;
   if (!content) fail("--content is required");
 
-  const owner = getRequestUserEmail() ?? process.env.AGENT_USER_EMAIL;
+  const owner = getRequestUserEmail() ?? getAmbientUserEmail();
   if (!owner) {
     fail(
       "save-memory requires an authenticated user (request context or AGENT_USER_EMAIL env var).",

package/corpus/core/src/scripts/resources/write.ts

@@ -15,7 +15,10 @@ import {
   type ResourceCreatedBy,
   type ResourceVisibility,
 } from "../../resources/store.js";
-import { getRequestUserEmail } from "../../server/request-context.js";
+import {
+  getAmbientUserEmail,
+  getRequestUserEmail,
+} from "../../server/request-context.js";
 import { parseArgs, fail } from "../utils.js";
 
 const EXTENSION_MIME_MAP: Record<string, string> = {
@@ -132,7 +135,7 @@ Options:
   } else if (scope === "workspace") {
     owner = WORKSPACE_OWNER;
   } else {
-    const personalOwner = getRequestUserEmail() ?? process.env.AGENT_USER_EMAIL;
+    const personalOwner = getRequestUserEmail() ?? getAmbientUserEmail();
     if (!personalOwner) {
       fail(
         "resource-write --scope=personal requires an authenticated user (request context or AGENT_USER_EMAIL env var).",

package/corpus/core/src/server/agent-capabilities.ts

@@ -0,0 +1,147 @@
+import { A2AClient } from "../a2a/client.js";
+import type { AgentSkill } from "../a2a/types.js";
+import { type DiscoveredAgent } from "./agent-discovery.js";
+
+/** Matches the `<available-apps>` prompt block so both surfaces agree. */
+export const MAX_APPS = 30;
+const MAX_SKILLS_IN_SUMMARY = 8;
+const MAX_SKILLS_IN_DETAIL = 60;
+const MAX_DESCRIPTION_CHARS = 240;
+const CARD_TIMEOUT_MS = 6_000;
+const CARD_CONCURRENCY = 8;
+
+export interface PeerCapabilities {
+  agent: DiscoveredAgent;
+  /** null distinguishes an unreachable card from a peer that exposes nothing. */
+  skills: AgentSkill[] | null;
+  cardDescription?: string;
+  error?: string;
+}
+
+function truncate(value: string, max: number): string {
+  const collapsed = value.replace(/\s+/g, " ").trim();
+  return collapsed.length > max ? `${collapsed.slice(0, max - 1)}…` : collapsed;
+}
+
+export async function loadCapabilities(
+  agent: DiscoveredAgent,
+): Promise<PeerCapabilities> {
+  try {
+    const card = await new A2AClient(agent.url).getAgentCard({
+      timeoutMs: CARD_TIMEOUT_MS,
+    });
+    return {
+      agent,
+      skills: Array.isArray(card.skills) ? card.skills : [],
+      cardDescription:
+        typeof card.description === "string" ? card.description : undefined,
+    };
+  } catch (error) {
+    return {
+      agent,
+      skills: null,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export async function loadAllCapabilities(
+  agents: DiscoveredAgent[],
+): Promise<PeerCapabilities[]> {
+  const results: PeerCapabilities[] = [];
+  for (let i = 0; i < agents.length; i += CARD_CONCURRENCY) {
+    results.push(
+      ...(await Promise.all(
+        agents.slice(i, i + CARD_CONCURRENCY).map(loadCapabilities),
+      )),
+    );
+  }
+  return results;
+}
+
+export function purposeOf(peer: PeerCapabilities): string {
+  // The manifest description comes from the app's own package.json and is
+  // authored; the card description is a generic template for auto-mounted
+  // apps, so it is only a fallback.
+  const manifest = peer.agent.description?.trim();
+  if (manifest) return truncate(manifest, MAX_DESCRIPTION_CHARS);
+  const card = peer.cardDescription?.trim();
+  return card
+    ? truncate(card, MAX_DESCRIPTION_CHARS)
+    : "(no description published)";
+}
+
+/**
+ * `detailHint` differs per surface: the agent tool tells the model to call
+ * itself again with an app id, the CLI tells the reader to pass `--app`.
+ */
+export function formatCapabilitySummary(
+  peers: PeerCapabilities[],
+  truncated: number,
+  detailHint: (appId: string) => string,
+): string {
+  const lines = peers.map((peer) => {
+    const header = `### ${peer.agent.name} (${peer.agent.id})\n${purposeOf(peer)}`;
+    if (peer.skills === null) {
+      return `${header}\nCapabilities: could not read agent card (${truncate(peer.error ?? "unreachable", 120)}). Delegate with a natural-language message instead of a direct action.`;
+    }
+    if (peer.skills.length === 0) {
+      return `${header}\nCapabilities: exposes no directly callable actions. Delegate with a natural-language message via call-agent.`;
+    }
+    const shown = peer.skills.slice(0, MAX_SKILLS_IN_SUMMARY);
+    const rest = peer.skills.length - shown.length;
+    return `${header}\nCallable actions: ${shown.map((skill) => skill.id).join(", ")}${
+      rest > 0 ? ` (+${rest} more — ${detailHint(peer.agent.id)})` : ""
+    }`;
+  });
+
+  return [
+    `${peers.length} other app${peers.length === 1 ? "" : "s"} reachable from this one over A2A.`,
+    truncated > 0
+      ? `(${truncated} additional app${truncated === 1 ? "" : "s"} not shown.)`
+      : "",
+    "",
+    lines.join("\n\n"),
+    "",
+    "Delegate with call-agent: pass action + input for a listed action, or message for open-ended work. Prefer the app that owns the data over rebuilding its capability here.",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+export function formatCapabilityDetail(
+  peer: PeerCapabilities,
+  callHint: (appId: string) => string,
+): string {
+  const header = `## ${peer.agent.name} (${peer.agent.id})\n${purposeOf(peer)}\nURL: ${peer.agent.url}`;
+
+  if (peer.skills === null) {
+    return `${header}\n\nIts agent card could not be read (${truncate(peer.error ?? "unreachable", 200)}), so its callable actions are unknown. It may still answer a natural-language call-agent message.`;
+  }
+  if (peer.skills.length === 0) {
+    return `${header}\n\nIt exposes no directly callable actions. Delegate with a natural-language call-agent message.`;
+  }
+
+  const shown = peer.skills.slice(0, MAX_SKILLS_IN_DETAIL);
+  const rest = peer.skills.length - shown.length;
+  const lines = shown.map(
+    (skill) =>
+      `- ${skill.id}${skill.readOnly ? "" : " (mutating)"}: ${
+        skill.description
+          ? truncate(skill.description, MAX_DESCRIPTION_CHARS)
+          : skill.name || "(no description)"
+      }`,
+  );
+
+  return [
+    header,
+    "",
+    "Callable actions:",
+    lines.join("\n"),
+    rest > 0 ? `(+${rest} more not shown.)` : "",
+    "",
+    callHint(peer.agent.id),
+  ]
+    .filter(Boolean)
+    .join("\n");
+}

package/corpus/core/src/server/agent-chat/framework-prompts.ts

@@ -99,21 +99,19 @@ If the current turn is in Plan mode, plan before anything gets written. This app
 
 ${extensionInstructionsFull}
 
-### Code Changes Not Available — Call \`connect-builder\` Immediately
+### Code Changes — Hand Off With \`connect-builder\`
 
 ${extensionConnectBuilderGuard}
 
-In Act mode, when the user asks you to change the UI, modify code, add a feature, fix a bug in the app itself, change styles, add a hook, create a component, add a route, add an integration, or anything else that requires editing source files — you MUST take exactly these steps, in order:
+In Act mode, a request that needs source-file edits — the UI chrome, a component, a route, styles, a hook, an integration, or a bug in the app itself — is a handoff, not a task you plan. Builder plans and edits in its own sandbox, so the exploration, file-mapping, and code all happen there rather than here.
 
-1. Briefly acknowledge the user's specific request in their own terms — one short clause naming what they asked for (e.g. "Got it — wider subject lines in the email list."). Do NOT restate the request verbatim, do NOT add a generic preamble, and do NOT promise outcomes. Skip this step entirely if the user already knows you're handing off (e.g. they said "send this to Builder").
-2. Call the \`connect-builder\` tool, passing the user's full request verbatim as the \`prompt\` argument. This renders an inline card. The returned \`builderEnabled\` flag is authoritative: \`true\` means Builder Cloud Agents can take the code-change handoff; \`false\` means this still requires a code change, but no Builder Cloud Agent can run from this workspace. If Builder is connected and \`builderEnabled\` is true, the card hands the prompt off to Builder's cloud agent on one click and returns a branch URL. If Builder is not connected and \`builderEnabled\` is true, it shows the Connect Builder flow. If \`builderEnabled\` is false, it still shows the card, but as a code-change fallback instead of a runnable cloud handoff.
-3. After the card renders, inspect the tool result and write one sentence that frames the next click around what the user just asked — not as a Builder pitch. If \`builderEnabled\` is true and the card can send, say something like "Click Send to Builder and it'll wire that up for you." If the user needs to connect first, say something like "Connect Builder once and it'll handle this and future changes." If \`builderEnabled\` is false, say: "This requires a code change. Edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way you like." Do NOT say "click Send to Builder", mention a branch URL, say the card is pre-loaded, or imply a Builder Cloud Agent can run when \`builderEnabled\` is false.
+Keep the whole turn to three beats:
 
-When \`builderEnabled\` is false, Builder Cloud Agents are not self-serve from Builder org settings. Do NOT tell the user to go to Builder org settings, beta features, "Cloud Agents", or "AI Agents" to enable them. The only allowed guidance is the card's code-change fallback: edit locally, use Agent Native Desktop, or use Builder.io to edit this code in the cloud and continue customizing the app any way you like.
+1. One short clause acknowledging what they asked for in their own terms ("Got it — wider subject lines in the email list."), skipped entirely when they already know you're handing off. No generic preamble, no promised outcomes.
+2. The \`connect-builder\` call, with the user's request verbatim as \`prompt\`.
+3. One sentence framing the next click around what they asked for rather than pitching Builder. Read \`builderEnabled\` from the result first; the tool's own description defines what each value lets you claim and offer.
 
-**Act-mode handoff — do exactly this:** The moment a code change is requested, call \`connect-builder\` with the user's verbatim request, then write one sentence framing the next click. That is the whole job: Builder plans and edits in its own sandbox, so the planning, file-mapping, and code all happen there, not here. Keep your turn to the call plus that one sentence — skip code exploration, implementation plans, \`resources\` writes of specs, and sub-agents (they have no code-editing tools either). You don't need filesystem access to recommend Builder, so don't reach for it or list tools you lack.
-
-Builder Cloud Agents are the recommended path when \`builderEnabled\` is true because they are one-click and run in the cloud. Local dev, Agent Native Desktop, and Builder.io cloud editing are the fallback when \`builderEnabled\` is false.
+Nothing else belongs in that turn: no code exploration, no implementation plan, no \`resources\` write of a spec, and no sub-agents (they have no code-editing tools either). You don't need filesystem access to hand off, so don't reach for it or list tools you lack.
 ${FRAMEWORK_CORE}`;
 
   const DEV_FRAMEWORK_PROMPT = `## Agent-Native Framework — Development Mode
@@ -123,12 +121,12 @@ You are an AI agent in an agent-native application, running in **development mod
 The agent and the UI are equal partners — everything the UI can do, you can do via tools/scripts, and vice versa. They share the same SQL database and stay in sync automatically.
 
 **In development mode, you have full local access — use it with senior-engineer judgment** (read before you edit, keep changes scoped, verify before you claim done):
-- Run any shell command via the \`bash\` tool (node, curl, pnpm, rg, git, etc.), including arbitrary code: \`bash({ command: 'node -e "console.log(1+1)"' })\`
+- Run any shell command via the \`bash\` tool (node, curl, pnpm, rg, git, etc.), including arbitrary code
 - Read and write any file on the filesystem; edit source, install packages, modify the app
 - Query and modify the database
 - Call external APIs (via bash with curl, or via scripts)
 
-When no dedicated tool/action exists for what you need, reach for \`bash\` — e.g. \`bash({ command: 'curl -s https://api.example.com/data' })\`.
+When no dedicated tool/action exists for what you need, reach for \`bash\`.
 
 **Template-specific actions are invoked via bash, NOT as direct tools.** In dev mode, the only tools registered as native tool calls are framework-level utilities (bash, read, edit, write, database, resources, chat, teams, jobs). Anything from the template's \`actions/\` directory must be run through bash: \`bash({ command: 'pnpm action <name> --arg value' })\`. The "Available Actions" section below shows the exact CLI syntax for each one — copy that command verbatim and pass it to \`bash\`. Do not try to call template actions by name as if they were tools; they will not appear in your tool list.
 
@@ -153,9 +151,9 @@ If the turn is in Plan mode, plan before anything gets written — including ${p
 
 ${extensionInstructionsCompact}
 
-### Code Changes — Call \`connect-builder\`
+### Code Changes — Hand Off With \`connect-builder\`
 
-In Act mode, when a request genuinely needs a source-code edit (per the rules above), do this in order: (1) briefly acknowledge the user's specific ask in their own terms — one short clause, no preamble — then (2) call \`connect-builder\` with the user's request as the \`prompt\`, then (3) inspect \`builderEnabled\` in the result and write one sentence framing the next click around what they asked for, not a Builder pitch. When \`builderEnabled\` is true, Builder Cloud Agents can take the handoff; when \`builderEnabled\` is false, say this requires a code change and they can edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way they like. Do NOT write code, list files, make plans, or spawn sub-agents. Mention \`npx agent-native create <app-name>\`, Agent Native Desktop, or the code-change fallback when Builder Cloud Agents aren't available. Never tell users to enable Builder Cloud Agents from Builder org settings, beta features, "Cloud Agents", or "AI Agents"; they are not self-serve there.
+In Act mode, a request that genuinely needs a source-code edit (per the rules above) is a handoff, not a task you plan. Keep the turn to three beats: (1) one short clause acknowledging their specific ask in their own terms, no preamble; (2) the \`connect-builder\` call with their request verbatim as \`prompt\`; (3) one sentence framing the next click around what they asked for, not a Builder pitch — read \`builderEnabled\` from the result first, and let the tool's own description tell you what each value lets you claim. Nothing else belongs in that turn: no code, no file lists, no plans, no sub-agents.
 ${FRAMEWORK_CORE_COMPACT}`;
 
   const DEV_FRAMEWORK_PROMPT_COMPACT = `## Agent-Native Framework — Development Mode