@agent-native/core 0.129.1 → 0.130.0

package/src/integrations/webhook-handler.ts

@@ -35,7 +35,11 @@ import {
   appendDurableContinuationContext,
   runAgentLoopDirectWithSoftTimeout,
 } from "../agent/run-loop-with-resume.js";
-import { startRun, type ActiveRun } from "../agent/run-manager.js";
+import {
+  startRun,
+  type ActiveRun,
+  type StartRunOptions,
+} from "../agent/run-manager.js";
 import {
   buildCurrentTimeUserContext,
   buildRuntimeContextPrompt,
@@ -1211,6 +1215,26 @@ async function processIncomingMessage(
   let usage: Awaited<ReturnType<typeof runAgentLoop>> | null = null;
   let budgetsSettled = false;
 
+  // Populated once `resolvedModel`/`engine` are known inside the run
+  // callback below (stored-model + platform-default resolution can't happen
+  // until then) and read back by run-manager's terminal tracking event via
+  // this same object reference — `startRun` reads `options.model` only in
+  // its `.finally()`, after this callback has settled, so the mutation is
+  // guaranteed to land before it's read.
+  const runOptions: StartRunOptions = {
+    useHostedSoftTimeoutDefault: true,
+    backgroundFunction: isInBackgroundFunctionRuntime(),
+    ...(campaign
+      ? {
+          turnId: campaign.row.turnId,
+          noProgressTimeoutMs: INTEGRATION_CAMPAIGN_NO_PROGRESS_TIMEOUT_MS,
+        }
+      : {}),
+    // No userId here: `ownerEmail` is PII (email), which the terminal event
+    // must not carry.
+    attemptCount: opts.attempts,
+  };
+
   // Wait for the run to complete inside this fresh function execution.
   // We use a Promise so the processor endpoint can await the full lifecycle.
   return new Promise<ProcessIntegrationTaskResult>((resolve) => {
@@ -1283,6 +1307,8 @@ async function processIncomingMessage(
               engine,
               modelCandidate,
             );
+            runOptions.model = resolvedModel;
+            runOptions.engineName = engine.name;
 
             // Wrapper, not raw `runAgentLoop`: an integration turn has no
             // browser to re-POST a continuation, so a transport-level cut
@@ -1847,16 +1873,7 @@ async function processIncomingMessage(
       // chains) with no visible answer. `isInBackgroundFunctionRuntime()` is
       // the runtime proof — never a config guess — so the wider ceiling is
       // taken only where the ~60s synchronous wall genuinely does not apply.
-      {
-        useHostedSoftTimeoutDefault: true,
-        backgroundFunction: isInBackgroundFunctionRuntime(),
-        ...(campaign
-          ? {
-              turnId: campaign.row.turnId,
-              noProgressTimeoutMs: INTEGRATION_CAMPAIGN_NO_PROGRESS_TIMEOUT_MS,
-            }
-          : {}),
-      },
+      runOptions,
     );
   });
 }

package/src/jobs/scheduler.ts

@@ -692,6 +692,10 @@ async function executeJob(
               // streams a job, so it gets reaped mid-flight.
               dispatchMode: "background",
               // turnId defaults to runId — fine for single-turn jobs
+              // No userId here: `jobUserEmail` is PII (email), which the
+              // terminal event must not carry.
+              model,
+              engineName: engine.name,
             },
           );
 

package/src/localization/default-messages.ts

@@ -4,6 +4,9 @@
 // templates ship as verbatim copy-only scaffolding (.ts), so their compiled
 // .js never exists in dist.
 const messages = {
+  workspaceFile: {
+    download: "Download",
+  },
   home: {
     settingsTitle: "Settings",
     settingsDescription: "Language and agent preferences",
@@ -867,8 +870,6 @@ const messages = {
       "This provider usually requires an OAuth setup. Follow the provider docs, or add an Authorization header if your endpoint supports token-based access.",
     personal: "Personal",
     organization: "Organization",
-    orgNoOrg: "Join an organization to share MCP servers",
-    orgAdminOnly: "Only owners and admins can add org-scope servers",
     serverNameRequired: "Enter a server name before connecting with OAuth.",
     serverName: "Server name",
     url: "URL",

package/src/mcp/build-server.ts

@@ -70,6 +70,12 @@ import {
   verifyMcpOAuthAccessToken,
 } from "./oauth-token.js";
 
+const PRESERVE_MCP_OBJECT_RESULT = Symbol("preserveMcpObjectResult");
+
+type MCPActionEntry = ActionEntry & {
+  [PRESERVE_MCP_OBJECT_RESULT]?: true;
+};
+
 export interface MCPConfig {
   /** App name shown in MCP server info */
   name: string;
@@ -965,7 +971,16 @@ function mergeBuiltinTools(
   requestMeta?: MCPRequestMeta,
 ): Record<string, ActionEntry> {
   if (config.builtinCrossAppTools === false) return baseActions;
-  const builtins = getBuiltinCrossAppTools(config, requestMeta);
+  const builtins = getBuiltinCrossAppTools(config, requestMeta) as Record<
+    string,
+    MCPActionEntry
+  >;
+  // Async ask_app responses contain the opaque handle needed to poll the same
+  // task. Mark the actual framework builtin rather than matching by name: an
+  // app-defined ask_app overrides this entry and keeps normal concise output.
+  if (builtins.ask_app) {
+    builtins.ask_app[PRESERVE_MCP_OBJECT_RESULT] = true;
+  }
   const merged: Record<string, ActionEntry> = { ...builtins };
   // Template / app actions overwrite same-named builtins.
   for (const [name, entry] of Object.entries(baseActions)) {
@@ -2127,7 +2142,10 @@ export async function createMCPServerForRequest(
           const text = mcpAppResource
             ? conciseMcpAppToolText(name, resultForClient, structuredContent!)
             : conciseToolResultText(name, resultForClient, {
-                preserveObjectResult: entry.readOnly === true,
+                preserveObjectResult:
+                  entry.readOnly === true ||
+                  (entry as MCPActionEntry)[PRESERVE_MCP_OBJECT_RESULT] ===
+                    true,
               });
           const content: any[] = [{ type: "text", text }];
           if (block) content.push(block);

package/src/observability/traces.ts

@@ -74,12 +74,25 @@ function emitLlmGenerationTrackingEvent(args: {
   llmSpanId: string;
   engineName: string | undefined;
   model: string;
-  inputTokens: number;
-  outputTokens: number;
-  cacheReadTokens: number;
-  cacheWriteTokens: number;
-  costCentsX100: number;
+  /**
+   * Undefined means the engine never reported a usage figure for this run
+   * (e.g. killed for silence before any provider response arrived) — not
+   * that the count was zero. Callers must omit these from the emitted event
+   * rather than coerce to 0; a coerced 0 is indistinguishable from a real
+   * empty-input run and defeats analysis of failing runs by input size.
+   */
+  inputTokens: number | undefined;
+  outputTokens: number | undefined;
+  cacheReadTokens: number | undefined;
+  cacheWriteTokens: number | undefined;
+  /** Same "unknown vs zero" rule as the token fields — cost is derived from
+   *  them and is equally unmeasurable when they were never reported. */
+  costCentsX100: number | undefined;
   durationMs: number;
+  /** Elapsed ms from run start to the first non-heartbeat engine event.
+   *  Undefined when no such event ever arrived (the run never produced a
+   *  token before being aborted) — never coerced to 0. */
+  firstTokenMs: number | undefined;
   status: "success" | "error";
   errorMessage: string | null;
   toolCalls: number;
@@ -102,7 +115,14 @@ function emitLlmGenerationTrackingEvent(args: {
   modelSelectionSource?: string;
 }): void {
   const provider = llmProviderFromEngine(args.engineName, args.model);
-  const costUsd = costUsdFromCenticents(args.costCentsX100);
+  const costUsd =
+    args.costCentsX100 !== undefined
+      ? costUsdFromCenticents(args.costCentsX100)
+      : undefined;
+  const totalTokens =
+    args.inputTokens !== undefined && args.outputTokens !== undefined
+      ? args.inputTokens + args.outputTokens
+      : undefined;
   const error = args.errorMessage ?? undefined;
   const properties: Record<string, unknown> = {
     ...trackingIdentityProperties(),
@@ -116,12 +136,13 @@ function emitLlmGenerationTrackingEvent(args: {
     provider,
     input_tokens: args.inputTokens,
     output_tokens: args.outputTokens,
-    total_tokens: args.inputTokens + args.outputTokens,
+    total_tokens: totalTokens,
     cache_read_tokens: args.cacheReadTokens,
     cache_write_tokens: args.cacheWriteTokens,
     cost_cents_x100: args.costCentsX100,
     cost_usd: costUsd,
     duration_ms: args.durationMs,
+    time_to_first_token_ms: args.firstTokenMs,
     status: args.status,
     tool_calls: args.toolCalls,
     successful_tools: args.successfulTools,
@@ -643,6 +664,16 @@ export async function instrumentAgentLoop(opts: {
         cacheWriteTokens: 0,
         model: loopOpts.model,
       };
+      // The engine never reported a `usage` event for this run (killed for
+      // silence before any provider response, or the loop threw before
+      // returning). `generationUsage`'s token fields are placeholder zeros in
+      // that case, not measured values — the tracking event below must omit
+      // them rather than report a fabricated 0.
+      const usageReported = usage?.usageReported === true;
+      const firstTokenMs =
+        usage?.firstEngineEventAtMs !== undefined
+          ? Math.max(0, usage.firstEngineEventAtMs - runStart)
+          : undefined;
       const llmSpanId = spanId();
       const llmSpan: TraceSpan = {
         id: llmSpanId,
@@ -675,12 +706,17 @@ export async function instrumentAgentLoop(opts: {
             ? loopOpts.engine.name
             : undefined,
         model: generationUsage.model,
-        inputTokens: generationUsage.inputTokens,
-        outputTokens: generationUsage.outputTokens,
-        cacheReadTokens: generationUsage.cacheReadTokens,
-        cacheWriteTokens: generationUsage.cacheWriteTokens,
-        costCentsX100,
+        inputTokens: usageReported ? generationUsage.inputTokens : undefined,
+        outputTokens: usageReported ? generationUsage.outputTokens : undefined,
+        cacheReadTokens: usageReported
+          ? generationUsage.cacheReadTokens
+          : undefined,
+        cacheWriteTokens: usageReported
+          ? generationUsage.cacheWriteTokens
+          : undefined,
+        costCentsX100: usageReported ? costCentsX100 : undefined,
         durationMs: totalDurationMs,
+        firstTokenMs,
         status: runStatus,
         errorMessage,
         toolCalls: toolCallCount,

package/src/org/handlers.ts

@@ -47,6 +47,7 @@ import { setActiveOrgId } from "./active-org.js";
 import { getOrgContext, createOrganization } from "./context.js";
 import { isFreeEmailProvider } from "./free-email-providers.js";
 import type { OrgRole } from "./types.js";
+import { parseWorkspaceUrl } from "./workspace-url.js";
 
 function getInviteAppUrl(event: H3Event): string {
   return getAppProductionUrl(event);
@@ -108,16 +109,19 @@ export const getMyOrgHandler = defineEventHandler(async (event: H3Event) => {
   }
 
   let allowedDomain: string | null = null;
+  let workspaceUrl: string | null = null;
   let a2aSecretSet = false;
   if (ctx.orgId) {
     try {
       const adRes = await e.execute({
-        sql: `SELECT allowed_domain, a2a_secret FROM organizations WHERE id = ? LIMIT 1`,
+        sql: `SELECT allowed_domain, a2a_secret, workspace_url FROM organizations WHERE id = ? LIMIT 1`,
         args: [ctx.orgId],
       });
       if (adRes.rows[0]) {
         allowedDomain =
           String((adRes.rows[0] as any).allowed_domain ?? "") || null;
+        workspaceUrl =
+          String((adRes.rows[0] as any).workspace_url ?? "") || null;
         a2aSecretSet = Boolean(
           String((adRes.rows[0] as any).a2a_secret ?? "").trim(),
         );
@@ -156,6 +160,7 @@ export const getMyOrgHandler = defineEventHandler(async (event: H3Event) => {
     pendingInvitations,
     domainMatches,
     allowedDomain,
+    workspaceUrl,
     // Never serialize the A2A secret here. This route runs on every page load,
     // so the value would sit in JSON any script on the page can read, and it
     // signs the JWTs peers accept as first-party callers. Reveal is an explicit
@@ -954,6 +959,52 @@ export const setDomainHandler = defineEventHandler(async (event: H3Event) => {
   return { domain: raw };
 });
 
+/**
+ * PUT /_agent-native/org/workspace-url — set or clear the org's own workspace
+ * origin (owner/admin only).
+ *
+ * Members who reach a shared hosted app from the template catalog land in a
+ * different deployment than their team's workspace, with the same org name in
+ * the switcher, and read the empty app as broken rather than as somewhere
+ * else. Setting this points them home from wherever they land.
+ *
+ * Body: { url: string | null } — a full URL or bare host; stored as an origin.
+ */
+export const setWorkspaceUrlHandler = defineEventHandler(
+  async (event: H3Event) => {
+    const ctx = await getOrgContext(event);
+    if (!ctx.orgId) {
+      throw createError({ statusCode: 400, message: "No active organization" });
+    }
+    if (ctx.role !== "owner" && ctx.role !== "admin") {
+      throw createError({
+        statusCode: 403,
+        message: "Only owners and admins can set the workspace URL",
+      });
+    }
+
+    const body = await readBody(event);
+    const raw = typeof body?.url === "string" ? body.url.trim() : "";
+
+    let workspaceUrl: string | null = null;
+    if (raw) {
+      const parsed = parseWorkspaceUrl(raw);
+      if (!parsed.ok) {
+        throw createError({ statusCode: 400, message: parsed.reason });
+      }
+      workspaceUrl = parsed.url;
+    }
+
+    const e = await exec();
+    await e.execute({
+      sql: `UPDATE organizations SET workspace_url = ? WHERE id = ?`,
+      args: [workspaceUrl, ctx.orgId],
+    });
+
+    return { url: workspaceUrl };
+  },
+);
+
 /**
  * GET /_agent-native/org/a2a-secret — reveal the org's A2A secret
  * (owner/admin only). Separate from `/org/me` so the secret is only ever sent

package/src/org/migrations.ts

@@ -124,4 +124,8 @@ export const ORG_MIGRATIONS = [
     sql: `CREATE UNIQUE INDEX IF NOT EXISTS app_member_roles_org_app_lower_email_uidx
           ON app_member_roles (org_id, app_id, LOWER(email))`,
   },
+  {
+    version: 1013,
+    sql: `ALTER TABLE organizations ADD COLUMN IF NOT EXISTS workspace_url TEXT`,
+  },
 ];

package/src/org/plugin.ts

@@ -31,6 +31,7 @@ import {
   acceptInvitationHandler,
   joinByDomainHandler,
   setDomainHandler,
+  setWorkspaceUrlHandler,
   revealA2ASecretHandler,
   setA2ASecretHandler,
   syncA2ASecretHandler,
@@ -61,6 +62,7 @@ const ORG_PREFIX = `${FRAMEWORK_PREFIX}/org`;
  *   POST   /_agent-native/org/invitations/:id/accept      — accept an invitation
  *   POST   /_agent-native/org/join-by-domain              — join org via email domain match
  *   PUT    /_agent-native/org/domain                      — set/clear allowed email domain (owner/admin)
+ *   PUT    /_agent-native/org/workspace-url               — set/clear the org's workspace origin (owner/admin)
  *   GET    /_agent-native/org/a2a-secret                  — reveal A2A secret on demand (owner/admin)
  *   PUT    /_agent-native/org/a2a-secret                  — regenerate or set A2A secret (owner/admin)
  *   POST   /_agent-native/org/a2a-secret/sync             — push secret to all connected apps (owner/admin)
@@ -251,6 +253,18 @@ export function createOrgPlugin(): NitroPluginDef {
       }),
     );
 
+    // PUT /workspace-url
+    app.use(
+      `${ORG_PREFIX}/workspace-url`,
+      defineEventHandler(async (event: H3Event) => {
+        if (getMethod(event) !== "PUT") {
+          setResponseStatus(event, 405);
+          return { error: "Method not allowed" };
+        }
+        return setWorkspaceUrlHandler(event);
+      }),
+    );
+
     // PUT /switch
     app.use(
       `${ORG_PREFIX}/switch`,

package/src/org/schema.ts

@@ -7,6 +7,7 @@ export const organizations = table("organizations", {
   createdAt: integer("created_at").notNull(),
   allowedDomain: text("allowed_domain"),
   a2aSecret: text("a2a_secret"),
+  workspaceUrl: text("workspace_url"),
 });
 
 export const orgMembers = table("org_members", {

package/src/org/types.ts

@@ -38,6 +38,14 @@ export interface OrgInfo {
   pendingInvitations: OrgInvitationSummary[];
   domainMatches: DomainMatchOrg[];
   allowedDomain: string | null;
+  /**
+   * Origin of the org's own workspace deployment, when it runs one. Members
+   * who land on a different host (a shared hosted app reached from the
+   * template catalog) get pointed here instead of concluding their team's
+   * apps are missing. Null for the common case of an org with no separate
+   * workspace.
+   */
+  workspaceUrl: string | null;
   /**
    * Whether the active org has an A2A secret. The value itself is never part
    * of this payload — owners/admins fetch it on demand from

package/src/org/workspace-url.ts

@@ -0,0 +1,74 @@
+/**
+ * Parsing and comparison for `organizations.workspace_url` — the origin of an
+ * org's own workspace deployment.
+ *
+ * The value is set by an owner/admin and then rendered as a link target for
+ * every member of the org, so it is parsed at the trust boundary rather than
+ * on the way out: anything that is not an `http(s)` origin never reaches the
+ * database.
+ */
+
+export type ParsedWorkspaceUrl =
+  | { ok: true; url: string }
+  | { ok: false; reason: string };
+
+/**
+ * Normalize a workspace URL to a bare origin (`https://host[:port]`).
+ *
+ * Path, query, and hash are dropped: this points at a deployment, not a page,
+ * and keeping them would send members to a route that may not exist in the
+ * app they arrive at.
+ */
+export function parseWorkspaceUrl(raw: string): ParsedWorkspaceUrl {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return { ok: false, reason: "Workspace URL is empty" };
+  }
+
+  // Accept a bare host ("agent-workspace.builder.io") the way a browser bar
+  // does — otherwise the most natural thing to paste is rejected.
+  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)
+    ? trimmed
+    : `https://${trimmed}`;
+
+  let parsed: URL;
+  try {
+    parsed = new URL(withScheme);
+  } catch {
+    return { ok: false, reason: "Not a valid URL" };
+  }
+
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    return { ok: false, reason: "Workspace URL must be http or https" };
+  }
+  if (!parsed.hostname.includes(".") && parsed.hostname !== "localhost") {
+    return { ok: false, reason: "Workspace URL must include a full hostname" };
+  }
+
+  return { ok: true, url: parsed.origin };
+}
+
+/**
+ * Whether a member currently on `currentUrl` should be pointed at the org's
+ * workspace. False when the org has no workspace, when the stored value is
+ * unusable, or when they are already on it — including any subdomain-free
+ * port/scheme difference, which `URL.origin` compares exactly.
+ */
+export function shouldOfferWorkspace(
+  currentUrl: string,
+  workspaceUrl: string | null | undefined,
+): boolean {
+  if (!workspaceUrl) return false;
+
+  const parsed = parseWorkspaceUrl(workspaceUrl);
+  if (!parsed.ok) return false;
+
+  let currentOrigin: string;
+  try {
+    currentOrigin = new URL(currentUrl).origin;
+  } catch {
+    return false;
+  }
+
+  return currentOrigin !== parsed.url;
+}

package/src/resources/handlers.ts

@@ -72,6 +72,28 @@ function canReadOwner(
   );
 }
 
+function resourceDownloadDisposition(path: string): string {
+  const basename = path.replaceAll("\\", "/").split("/").pop()?.trim() || "";
+  const filename = Array.from(basename)
+    .slice(0, 180)
+    .map((character) => {
+      const codePoint = character.codePointAt(0) ?? 0;
+      return codePoint <= 31 || codePoint === 127 ? "_" : character;
+    })
+    .join("");
+  const safeFilename =
+    filename && filename !== "." && filename !== ".." ? filename : "download";
+  const asciiFilename = safeFilename
+    .replace(/[^\x20-\x7e]/g, "_")
+    .replace(/["\\]/g, "_");
+  const encodedFilename = encodeURIComponent(safeFilename).replace(
+    /['()*]/g,
+    (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+
+  return `attachment; filename="${asciiFilename}"; filename*=UTF-8''${encodedFilename}`;
+}
+
 function mergeScopedResources(
   primary: ResourceMeta[],
   inherited: ResourceMeta[],
@@ -398,9 +420,8 @@ async function enrichTreeNodes(nodes: TreeNode[]): Promise<void> {
 }
 
 /** GET /_agent-native/resources/:id — get single resource with content.
- *  If the request comes from an <img>/<video>/etc tag (Accept includes the
- *  resource's mime type, or query param `?raw` is set), return the raw binary
- *  with the correct Content-Type so the browser can render it inline. */
+ *  `?raw` returns the bytes inline; `?download=1` returns the same bytes as a
+ *  safe attachment. */
 export async function handleGetResource(event: any) {
   const id = getRouterParam(event, "id") || event.context.params?.id;
   if (!id) {
@@ -421,11 +442,11 @@ export async function handleGetResource(event: any) {
     return { error: "Resource not found" };
   }
 
-  // Serve raw binary when ?raw query param is set (used by <img> tags etc.)
   const query = getQuery(event);
   const wantsRaw = query.raw !== undefined;
+  const wantsDownload = query.download === "1";
 
-  if (wantsRaw && resource.content) {
+  if ((wantsRaw || wantsDownload) && typeof resource.content === "string") {
     const isText =
       resource.mimeType.startsWith("text/") ||
       resource.mimeType === "application/json";
@@ -435,6 +456,15 @@ export async function handleGetResource(event: any) {
 
     setResponseHeader(event, "Content-Type", resource.mimeType);
     setResponseHeader(event, "Content-Length", String(buf.length));
+    setResponseHeader(event, "Cache-Control", "private, no-store");
+    setResponseHeader(event, "X-Content-Type-Options", "nosniff");
+    if (wantsDownload) {
+      setResponseHeader(
+        event,
+        "Content-Disposition",
+        resourceDownloadDisposition(resource.path),
+      );
+    }
     return new Response(buf);
   }