@agent-native/core 0.129.2 → 0.130.1

package/corpus/core/src/integrations/task-queue-stats.ts

@@ -8,6 +8,7 @@
  * columns before the SELECTs execute.
  */
 import { getDbExec } from "../db/client.js";
+import { ensureA2AContinuationsTable } from "./a2a-continuations-store.js";
 import { ensurePendingTasksTable } from "./pending-tasks-store.js";
 
 export interface RecentFailure {
@@ -23,6 +24,18 @@ export interface TaskQueueStats {
   completed_last_hour: number;
   failed_last_hour: number;
   oldest_pending_age_seconds: number;
+  waiting_campaigns: number;
+  active_a2a_continuations: number;
+  oldest_active_a2a_age_seconds: number;
+  terminal_a2a_without_delivery: number;
+  recent_a2a_orphans: Array<{
+    continuation_id: string;
+    integration_task_id: string;
+    status: string;
+    attempts: number;
+    age_seconds: number;
+    reason_class: string;
+  }>;
   recent_failures: RecentFailure[];
   recent_tasks: Array<{
     id: string;
@@ -46,6 +59,11 @@ const ZERO_STATS: TaskQueueStats = {
   completed_last_hour: 0,
   failed_last_hour: 0,
   oldest_pending_age_seconds: 0,
+  waiting_campaigns: 0,
+  active_a2a_continuations: 0,
+  oldest_active_a2a_age_seconds: 0,
+  terminal_a2a_without_delivery: 0,
+  recent_a2a_orphans: [],
   recent_failures: [],
   recent_tasks: [],
 };
@@ -66,11 +84,14 @@ export async function getTaskQueueStats(
   scope: TaskQueueStatsScope,
 ): Promise<TaskQueueStats> {
   await ensurePendingTasksTable();
+  await ensureA2AContinuationsTable();
   const client = getDbExec();
   const now = Date.now();
   const oneHourAgo = now - 60 * 60 * 1000;
   const scopeSql = `owner_email = ?
               AND ((org_id IS NULL AND CAST(? AS TEXT) IS NULL) OR org_id = ?)`;
+  const joinedScopeSql = `t.owner_email = ?
+              AND ((t.org_id IS NULL AND CAST(? AS TEXT) IS NULL) OR t.org_id = ?)`;
   const scopeArgs = [scope.ownerEmail, scope.orgId, scope.orgId];
 
   try {
@@ -178,6 +199,17 @@ export async function getTaskQueueStats(
         ),
       }),
     );
+    const waitingCampaigns = await readWaitingCampaignCount(
+      client,
+      joinedScopeSql,
+      scopeArgs,
+    );
+    const a2aStats = await readA2AContinuationStats(
+      client,
+      joinedScopeSql,
+      scopeArgs,
+      now,
+    );
 
     return {
       pending,
@@ -185,6 +217,8 @@ export async function getTaskQueueStats(
       completed_last_hour: completedLastHour,
       failed_last_hour: failedLastHour,
       oldest_pending_age_seconds: oldestPendingAgeSeconds,
+      waiting_campaigns: waitingCampaigns,
+      ...a2aStats,
       recent_failures: recentFailures,
       recent_tasks: recentTasks,
     };
@@ -195,3 +229,115 @@ export async function getTaskQueueStats(
     throw err;
   }
 }
+
+async function readWaitingCampaignCount(
+  client: ReturnType<typeof getDbExec>,
+  scopeSql: string,
+  scopeArgs: Array<string | null>,
+): Promise<number> {
+  try {
+    const result = await client.execute({
+      sql: `SELECT COUNT(*) AS c
+              FROM integration_campaigns c
+              INNER JOIN integration_pending_tasks t
+                ON t.id = c.integration_task_id
+             WHERE ${scopeSql}
+               AND c.status = 'waiting'`,
+      args: scopeArgs,
+    });
+    return Number(result.rows[0]?.c ?? 0);
+  } catch (err) {
+    if (isMissingTableError(err)) return 0;
+    throw err;
+  }
+}
+
+async function readA2AContinuationStats(
+  client: ReturnType<typeof getDbExec>,
+  scopeSql: string,
+  scopeArgs: Array<string | null>,
+  now: number,
+): Promise<
+  Pick<
+    TaskQueueStats,
+    | "active_a2a_continuations"
+    | "oldest_active_a2a_age_seconds"
+    | "terminal_a2a_without_delivery"
+    | "recent_a2a_orphans"
+  >
+> {
+  try {
+    const live = await client.execute({
+      sql: `SELECT
+                   COUNT(CASE WHEN c.status IN ('pending', 'processing', 'delivering') THEN 1 END) AS active_count,
+                   MIN(CASE WHEN c.status IN ('pending', 'processing', 'delivering') THEN c.created_at END) AS oldest_created_at,
+                   COUNT(CASE WHEN c.status IN ('completed', 'failed')
+                         AND c.terminal_delivery_confirmed_at IS NULL THEN 1 END) AS orphan_count
+              FROM integration_a2a_continuations c
+              INNER JOIN integration_pending_tasks t
+                ON t.id = c.integration_task_id
+             WHERE ${scopeSql}`,
+      args: scopeArgs,
+    });
+    const orphaned = await client.execute({
+      sql: `SELECT c.id, c.integration_task_id, c.status, c.attempts,
+                   c.created_at, c.error_message
+              FROM integration_a2a_continuations c
+              INNER JOIN integration_pending_tasks t
+                ON t.id = c.integration_task_id
+             WHERE ${scopeSql}
+               AND c.status IN ('completed', 'failed')
+               AND c.terminal_delivery_confirmed_at IS NULL
+             ORDER BY c.updated_at DESC
+             LIMIT 5`,
+      args: scopeArgs,
+    });
+    const activeCount = Number(live.rows[0]?.active_count ?? 0);
+    const orphanCount = Number(live.rows[0]?.orphan_count ?? 0);
+    const oldestCreatedAt = Number(live.rows[0]?.oldest_created_at ?? now);
+    const recentOrphans = (orphaned.rows as Array<Record<string, unknown>>).map(
+      (row) => ({
+        continuation_id: String(row.id ?? ""),
+        integration_task_id: String(row.integration_task_id ?? ""),
+        status: String(row.status ?? ""),
+        attempts: Number(row.attempts ?? 0),
+        age_seconds: Math.max(
+          0,
+          Math.floor((now - Number(row.created_at ?? now)) / 1000),
+        ),
+        reason_class: classifyA2AOrphanReason(row.error_message),
+      }),
+    );
+    return {
+      active_a2a_continuations: activeCount,
+      oldest_active_a2a_age_seconds:
+        activeCount > 0
+          ? Math.max(0, Math.floor((now - oldestCreatedAt) / 1000))
+          : 0,
+      terminal_a2a_without_delivery: orphanCount,
+      recent_a2a_orphans: recentOrphans,
+    };
+  } catch (err) {
+    if (isMissingTableError(err)) {
+      return {
+        active_a2a_continuations: 0,
+        oldest_active_a2a_age_seconds: 0,
+        terminal_a2a_without_delivery: 0,
+        recent_a2a_orphans: [],
+      };
+    }
+    throw err;
+  }
+}
+
+function classifyA2AOrphanReason(value: unknown): string {
+  const message = String(value ?? "");
+  if (!message) return "missing_terminal_delivery";
+  if (/timeout|timed out|abort/i.test(message)) return "timeout";
+  if (/token|secret|auth|credential/i.test(message)) return "authentication";
+  if (/database|sql|store|persist/i.test(message)) return "persistence";
+  if (/slack|provider|deliver|stream|response/i.test(message)) {
+    return "provider_delivery";
+  }
+  return "processor_failure";
+}

package/corpus/core/src/integrations/types.ts

@@ -134,6 +134,19 @@ export interface PlatformDeliveryReceipt {
   messageRefs?: string[];
 }
 
+export interface PlatformDeliveryOptions {
+  /** Provider-owned message reference that should be updated in place. */
+  placeholderRef?: string;
+  /** Stable logical delivery key for provider-side retry reconciliation. */
+  idempotencyKey?: string;
+  /** Earliest provider timestamp (epoch ms) that can contain this delivery. */
+  reconcileAfter?: number;
+  /** Abort provider I/O before the caller releases its durable delivery claim. */
+  signal?: AbortSignal;
+  /** Do not fall back to a fresh post if the stable target cannot be updated. */
+  strictTargetRef?: boolean;
+}
+
 /**
  * Proactive outbound message target for a platform.
  * Used when the agent needs to send to a saved destination instead of replying
@@ -201,12 +214,20 @@ export interface PlatformRunProgress {
    * credentials, or provider payload.
    */
   ref?: PlatformRunProgressRef;
+  /** Stable provider message target that can receive the terminal answer. */
+  responseTargetRef?: string;
   /** Receive normalized agent events. Implementations should throttle writes. */
-  onEvent(event: AgentChatEvent): Promise<void> | void;
+  onEvent(
+    event: AgentChatEvent,
+    opts?: { signal?: AbortSignal },
+  ): Promise<void> | void;
   /** Finalize the provider-native progress surface with the answer. */
-  complete(message: OutgoingMessage): Promise<void | PlatformDeliveryReceipt>;
+  complete(
+    message: OutgoingMessage,
+    opts?: { signal?: AbortSignal },
+  ): Promise<void | PlatformDeliveryReceipt>;
   /** Mark the provider-native surface failed and leave a retryable explanation. */
-  fail?(message: string): Promise<void>;
+  fail?(message: string, opts?: { signal?: AbortSignal }): Promise<void>;
 }
 
 /**
@@ -322,7 +343,7 @@ export interface PlatformAdapter {
   sendResponse(
     message: OutgoingMessage,
     context: IncomingMessage,
-    opts?: { placeholderRef?: string },
+    opts?: PlatformDeliveryOptions,
   ): Promise<void | PlatformDeliveryReceipt>;
 
   /**

package/corpus/core/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,
@@ -63,7 +67,8 @@ import {
 import { runWithRequestContext } from "../server/request-context.js";
 import { normalizeReasoningEffortForRequest } from "../shared/reasoning-effort.js";
 import { A2A_CONTINUATION_QUEUED_MARKER } from "./a2a-continuation-marker.js";
-import { hasActiveA2AContinuationsForIntegrationTask } from "./a2a-continuations-store.js";
+import { reconcileTerminalA2AParentIfDisabled } from "./a2a-continuation-processor.js";
+import { getA2AContinuationTaskOutcome } from "./a2a-continuations-store.js";
 import {
   clearIntegrationAwaitingInput,
   setIntegrationAwaitingInput,
@@ -1082,10 +1087,22 @@ async function processIncomingMessage(
           JSON.parse(campaign.row.checkpoint).waitingForA2A === true;
       } catch {}
       if (waitingForA2A) {
-        const activeA2A = await hasActiveA2AContinuationsForIntegrationTask(
-          opts.taskId,
-        );
-        if (activeA2A) {
+        const a2aOutcome = await getA2AContinuationTaskOutcome(opts.taskId);
+        if (a2aOutcome !== "terminal-delivered") {
+          if (
+            a2aOutcome === "terminal-without-delivery" &&
+            (await reconcileTerminalA2AParentIfDisabled(opts.taskId))
+          ) {
+            await releaseApplicableIntegrationBudgets(
+              budgetReservations.reservations,
+            );
+            return { status: "campaign-failed" };
+          }
+          if (a2aOutcome !== "active") {
+            console.warn(
+              `[integrations] Waiting campaign ${campaign.row.id} has A2A outcome ${a2aOutcome} without terminal delivery proof`,
+            );
+          }
           const waiting = await waitForA2AIntegrationCampaign(campaign.row.id, {
             runId: campaign.runId,
             leaseToken: campaign.leaseToken,
@@ -1211,6 +1228,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 +1320,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 +1886,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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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