@agent-native/core 0.92.12 → 0.94.0

package/corpus/core/src/provider-api/index.ts

@@ -53,6 +53,7 @@ export const PROVIDER_API_IDS = [
   "amplitude",
   "apollo",
   "bigquery",
+  "clay",
   "commonroom",
   "dataforseo",
   "ga4",
@@ -647,6 +648,56 @@ const PROVIDER_CONFIGS: Record<ProviderApiId, ProviderApiConfig> = {
       },
     ],
   },
+  clay: {
+    id: "clay",
+    label: "Clay Public API",
+    defaultBaseUrl: "https://api.clay.com/public/v0",
+    auth: {
+      type: "api-key-header",
+      key: "CLAY_PUBLIC_API_KEY",
+      header: "clay-api-key",
+    },
+    credentialKeys: ["CLAY_PUBLIC_API_KEY"],
+    docsUrls: [
+      "https://developers.clay.com/llms.txt",
+      "https://developers.clay.com/public-api/authentication",
+      "https://developers.clay.com/concepts/execution-model.md",
+    ],
+    specUrls: ["https://developers.clay.com/openapi.json"],
+    templateUses: ["analytics"],
+    examples: [
+      {
+        label: "Get authenticated user and workspace",
+        method: "GET",
+        path: "/me",
+      },
+      {
+        label: "List people search filter fields",
+        method: "GET",
+        path: "/search/filters-mode/fields",
+        query: { source_type: "people" },
+      },
+      {
+        label: "Create a people search",
+        method: "POST",
+        path: "/search/filters-mode",
+        body: {
+          source_type: "people",
+          filters: {
+            job_title_keywords: ["software engineer"],
+            location_cities_include: ["New York"],
+          },
+        },
+      },
+    ],
+    notes: [
+      "Clay is a GTM provider API capability, not a messaging channel.",
+      "The Public API key is tied to a Clay user and workspace. It is separate from the optional local clay CLI/MCP session created by clay login; hosted Agent Native access does not require that plugin session.",
+      "Search results use a stateful forward-only iterator: repeat POST /search/filters-mode/{search_id}/run while has_more is true.",
+      "The Tables API is query-only, requires an Enterprise plan, and needs a known table id; the Public API does not list, create, or update tables.",
+      "Routine runs are asynchronous. Start a run, then poll the documented results endpoint or use a verified completion webhook.",
+    ],
+  },
   commonroom: {
     id: "commonroom",
     label: "Common Room",
@@ -789,10 +840,25 @@ const PROVIDER_CONFIGS: Record<ProviderApiId, ProviderApiConfig> = {
       header: "X-Figma-Token",
     },
     credentialKeys: ["FIGMA_ACCESS_TOKEN"],
-    docsUrls: ["https://www.figma.com/developers/api"],
+    docsUrls: [
+      "https://developers.figma.com/docs/rest-api/",
+      "https://developers.figma.com/docs/rest-api/scopes/",
+      "https://developers.figma.com/docs/rest-api/file-endpoints/",
+    ],
     allowedHostSuffixes: ["figma.com"],
     templateUses: ["design"],
     examples: [
+      {
+        label: "Get file document",
+        method: "GET",
+        path: "/files/{fileKey}",
+      },
+      {
+        label: "Get exact file nodes",
+        method: "GET",
+        path: "/files/{fileKey}/nodes",
+        query: { ids: "1:2" },
+      },
       {
         label: "List file components",
         method: "GET",
@@ -805,6 +871,11 @@ const PROVIDER_CONFIGS: Record<ProviderApiId, ProviderApiConfig> = {
         query: { ids: "1:2", format: "svg" },
       },
     ],
+    notes: [
+      "Personal access tokens should include current_user:read for validation and file_content:read for file/node imports. Add library_content:read for file libraries, team_library_content:read for team libraries, or library_assets:read for individual published assets only when needed.",
+      "Enterprise Variables endpoints require file_variables:read; writes additionally require file_variables:write, a Full seat, and edit access.",
+      "The REST API cannot create arbitrary canvas frames or layers. Use Figma's official OAuth MCP write tools when connected, or export a Design selection as Figma-compatible SVG for visual handoff.",
+    ],
   },
   gmail: {
     id: "gmail",

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

@@ -38,6 +38,8 @@ import {
   ensurePersonalDefaults,
   canWriteLocalWorkspaceResourcePath,
   isLocalWorkspaceResourceId,
+  organizationIdFromResourceOwner,
+  sharedResourceOwner,
   SHARED_OWNER,
   WORKSPACE_OWNER,
   type ResourceMeta,
@@ -48,7 +50,7 @@ import {
 // ---------------------------------------------------------------------------
 
 async function resolveOwner(event: any, shared?: boolean): Promise<string> {
-  if (shared) return SHARED_OWNER;
+  if (shared) return sharedResourceOwner(await resolveOrgId(event));
   const session = await getSession(event);
   if (!session?.email) {
     throw createError({ statusCode: 401, statusMessage: "Unauthenticated" });
@@ -56,8 +58,51 @@ async function resolveOwner(event: any, shared?: boolean): Promise<string> {
   return session.email;
 }
 
-function canReadOwner(owner: string, email: string): boolean {
-  return owner === email || owner === SHARED_OWNER || owner === WORKSPACE_OWNER;
+function canReadOwner(
+  owner: string,
+  email: string,
+  orgId?: string | null,
+): boolean {
+  const ownerOrgId = organizationIdFromResourceOwner(owner);
+  return (
+    owner === email ||
+    owner === SHARED_OWNER ||
+    owner === WORKSPACE_OWNER ||
+    (!!ownerOrgId && ownerOrgId === orgId)
+  );
+}
+
+function mergeScopedResources(
+  primary: ResourceMeta[],
+  inherited: ResourceMeta[],
+): ResourceMeta[] {
+  const seen = new Set(primary.map((resource) => resource.path));
+  return [
+    ...primary,
+    ...inherited.filter((resource) => !seen.has(resource.path)),
+  ];
+}
+
+async function listSharedResources(
+  orgId: string | null,
+  prefix?: string,
+  options?: Parameters<typeof resourceList>[2],
+): Promise<ResourceMeta[]> {
+  const organizationOwner = sharedResourceOwner(orgId);
+  if (organizationOwner === SHARED_OWNER) {
+    return options
+      ? resourceList(SHARED_OWNER, prefix, options)
+      : resourceList(SHARED_OWNER, prefix);
+  }
+  const [organization, legacyAppDefaults] = await Promise.all([
+    options
+      ? resourceList(organizationOwner, prefix, options)
+      : resourceList(organizationOwner, prefix),
+    options
+      ? resourceList(SHARED_OWNER, prefix, options)
+      : resourceList(SHARED_OWNER, prefix),
+  ]);
+  return mergeScopedResources(organization, legacyAppDefaults);
 }
 
 async function resolveEmail(event: any): Promise<string> {
@@ -215,9 +260,7 @@ export async function handleListResources(event: any) {
   } else if (scope === "workspace") {
     resources = await resourceList(WORKSPACE_OWNER, prefix, scopedListOptions);
   } else if (scope === "shared") {
-    resources = localListOptions
-      ? await resourceList(SHARED_OWNER, prefix, localListOptions)
-      : await resourceList(SHARED_OWNER, prefix);
+    resources = await listSharedResources(orgId, prefix, localListOptions);
   } else {
     // "all" — personal + organization/shared + inherited workspace
     resources = await resourceListAccessible(email, prefix, scopedListOptions);
@@ -256,9 +299,7 @@ export async function handleGetResourceTree(event: any) {
       scopedListOptions,
     );
   } else if (scope === "shared") {
-    resources = localListOptions
-      ? await resourceList(SHARED_OWNER, undefined, localListOptions)
-      : await resourceList(SHARED_OWNER);
+    resources = await listSharedResources(orgId, undefined, localListOptions);
   } else {
     resources = await resourceListAccessible(
       email,
@@ -379,7 +420,7 @@ export async function handleGetResource(event: any) {
     return { error: "Resource not found" };
   }
 
-  if (!canReadOwner(resource.owner, email)) {
+  if (!canReadOwner(resource.owner, email, orgId)) {
     setResponseStatus(event, 404);
     return { error: "Resource not found" };
   }
@@ -473,7 +514,8 @@ export async function handleUpdateResource(event: any) {
 
   // Ownership check: only the owner (or shared resource editors) can update
   const email = await resolveEmail(event);
-  if (!canReadOwner(existing.owner, email)) {
+  const orgId = await resolveOrgId(event);
+  if (!canReadOwner(existing.owner, email, orgId)) {
     setResponseStatus(event, 404);
     return { error: "Resource not found" };
   }
@@ -483,12 +525,29 @@ export async function handleUpdateResource(event: any) {
     setResponseStatus(event, 403);
     return { error: "Workspace resources are managed from Dispatch" };
   }
-  if (existing.owner === SHARED_OWNER) {
+  const existingOrganizationId = organizationIdFromResourceOwner(
+    existing.owner,
+  );
+  if (existing.owner === SHARED_OWNER || existingOrganizationId) {
     await assertCanEditShared(event);
   }
 
   const body = await readBody(event);
   const nextPath = body.path ?? existing.path;
+  const activeSharedOwner = sharedResourceOwner(orgId);
+
+  // Existing `__shared__` rows are legacy app defaults. In an organization,
+  // editing one creates an organization override instead of mutating the
+  // fallback seen by every tenant in the deployment.
+  if (existing.owner === SHARED_OWNER && activeSharedOwner !== SHARED_OWNER) {
+    return resourcePut(
+      activeSharedOwner,
+      nextPath,
+      body.content ?? existing.content,
+      body.mimeType ?? existing.mimeType,
+      body.metadata !== undefined ? { metadata: body.metadata } : undefined,
+    );
+  }
 
   if (
     isLocalWorkspaceResource &&
@@ -547,7 +606,8 @@ export async function handleDeleteResource(event: any) {
 
   // Ownership check: only the owner (or shared resource editors) can delete
   const email = await resolveEmail(event);
-  if (!canReadOwner(existing.owner, email)) {
+  const orgId = await resolveOrgId(event);
+  if (!canReadOwner(existing.owner, email, orgId)) {
     setResponseStatus(event, 404);
     return { error: "Resource not found" };
   }
@@ -558,10 +618,24 @@ export async function handleDeleteResource(event: any) {
     setResponseStatus(event, 403);
     return { error: "Workspace resources are managed from Dispatch" };
   }
-  if (existing.owner === SHARED_OWNER) {
+  const existingOrganizationId = organizationIdFromResourceOwner(
+    existing.owner,
+  );
+  if (existing.owner === SHARED_OWNER || existingOrganizationId) {
     await assertCanEditShared(event);
   }
 
+  if (
+    existing.owner === SHARED_OWNER &&
+    sharedResourceOwner(orgId) !== SHARED_OWNER
+  ) {
+    setResponseStatus(event, 403);
+    return {
+      error:
+        "This is an inherited app default. Create an organization override instead of deleting it.",
+    };
+  }
+
   await resourceDelete(id);
   return { ok: true };
 }

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

@@ -6,10 +6,14 @@
  * require a real identity; there is no dev-mode fallback.
  */
 
-import { getRequestUserEmail } from "../server/request-context.js";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "../server/request-context.js";
 import {
   SHARED_OWNER,
   WORKSPACE_OWNER,
+  sharedResourceOwner,
   resourceGetByPath,
   resourcePut,
   resourceDeleteByPath,
@@ -26,7 +30,7 @@ import {
 type ResourceHelperScope = "personal" | "shared" | "workspace";
 
 function getOwnerForScope(scope?: ResourceHelperScope): string {
-  if (scope === "shared") return SHARED_OWNER;
+  if (scope === "shared") return sharedResourceOwner(getRequestOrgId());
   if (scope === "workspace") return WORKSPACE_OWNER;
   const userEmail = getRequestUserEmail();
   if (userEmail) return userEmail;
@@ -50,7 +54,11 @@ export async function readResource(
 ): Promise<string | null> {
   const owner = getOwnerForScope(resolveScope(options));
   const resource = await resourceGetByPath(owner, path);
-  return resource ? resource.content : null;
+  if (resource) return resource.content;
+  if (resolveScope(options) === "shared" && owner !== SHARED_OWNER) {
+    return (await resourceGetByPath(SHARED_OWNER, path))?.content ?? null;
+  }
+  return null;
 }
 
 export async function writeResource(
@@ -107,9 +115,21 @@ export async function listResources(
   },
 ): Promise<ResourceMeta[]> {
   const owner = getOwnerForScope(resolveScope(options));
-  return options?.includeAgentScratch
+  const resources = options?.includeAgentScratch
     ? resourceList(owner, prefix, { includeAgentScratch: true })
     : resourceList(owner, prefix);
+  const primary = await resources;
+  if (resolveScope(options) !== "shared" || owner === SHARED_OWNER) {
+    return primary;
+  }
+  const inherited = options?.includeAgentScratch
+    ? await resourceList(SHARED_OWNER, prefix, { includeAgentScratch: true })
+    : await resourceList(SHARED_OWNER, prefix);
+  const seen = new Set(primary.map((resource) => resource.path));
+  return [
+    ...primary,
+    ...inherited.filter((resource) => !seen.has(resource.path)),
+  ];
 }
 
 export async function listAllResources(
@@ -117,9 +137,15 @@ export async function listAllResources(
   options?: { includeAgentScratch?: boolean },
 ): Promise<ResourceMeta[]> {
   const userEmail = getOwnerForScope("personal");
+  const orgId = getRequestOrgId();
   return options?.includeAgentScratch
-    ? resourceListAccessible(userEmail, prefix, { includeAgentScratch: true })
-    : resourceListAccessible(userEmail, prefix);
+    ? resourceListAccessible(userEmail, prefix, {
+        includeAgentScratch: true,
+        ...(orgId ? { orgId } : {}),
+      })
+    : orgId
+      ? resourceListAccessible(userEmail, prefix, { orgId })
+      : resourceListAccessible(userEmail, prefix);
 }
 
 export async function getEffectiveResourceContext(
@@ -127,5 +153,8 @@ export async function getEffectiveResourceContext(
 ): Promise<EffectiveResourceContext> {
   const userEmail = getOwnerForScope("personal");
   await ensurePersonalDefaults(userEmail);
-  return resourceEffectiveContext(userEmail, path);
+  const orgId = getRequestOrgId();
+  return orgId
+    ? resourceEffectiveContext(userEmail, path, { userEmail, orgId })
+    : resourceEffectiveContext(userEmail, path);
 }

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

@@ -30,6 +30,38 @@ import { emitResourceChange, emitResourceDelete } from "./emitter.js";
 
 export const SHARED_OWNER = "__shared__";
 export const WORKSPACE_OWNER = "__workspace__";
+const ORGANIZATION_OWNER_PREFIX = "__organization__:";
+
+/**
+ * Encode an organization id into the existing resource owner key. This keeps
+ * organization resources isolated without a destructive resources-table
+ * migration, while preserving the legacy `__shared__` owner as the app-wide
+ * default/fallback used by older deployments and solo mode.
+ */
+export function organizationResourceOwner(orgId: string): string {
+  const normalized = orgId.trim();
+  if (!normalized) {
+    throw new Error("organizationResourceOwner requires a non-empty orgId");
+  }
+  return `${ORGANIZATION_OWNER_PREFIX}${encodeURIComponent(normalized)}`;
+}
+
+export function organizationIdFromResourceOwner(owner: string): string | null {
+  if (!owner.startsWith(ORGANIZATION_OWNER_PREFIX)) return null;
+  const encoded = owner.slice(ORGANIZATION_OWNER_PREFIX.length);
+  if (!encoded) return null;
+  try {
+    return decodeURIComponent(encoded);
+  } catch {
+    return null;
+  }
+}
+
+/** Active organization scope, with the legacy app-shared owner as solo fallback. */
+export function sharedResourceOwner(orgId?: string | null): string {
+  const activeOrgId = orgId === undefined ? (getRequestOrgId() ?? null) : orgId;
+  return activeOrgId ? organizationResourceOwner(activeOrgId) : SHARED_OWNER;
+}
 
 function escapeLike(value: string): string {
   return value.replace(/[!%_]/g, (char) => `!${char}`);
@@ -1430,59 +1462,28 @@ export async function resourceListAccessible(
   pathPrefix?: string,
   options?: ResourceListOptions,
 ): Promise<ResourceMeta[]> {
-  await ensureTable();
-  const client = getDbExec();
-  await cleanupExpiredAgentScratchResources(client);
-  const visibilitySql = scratchFilterSql(options);
-
-  if (pathPrefix) {
-    const { rows } = await client.execute({
-      sql: `SELECT ${RESOURCE_META_SELECT} FROM resources WHERE owner = ? AND path LIKE ? ESCAPE '!'${visibilitySql}
-            UNION
-            SELECT ${RESOURCE_META_SELECT} FROM resources WHERE owner = ? AND path LIKE ? ESCAPE '!'${visibilitySql}
-            UNION
-            SELECT ${RESOURCE_META_SELECT} FROM resources WHERE owner = ? AND path LIKE ? ESCAPE '!'${visibilitySql}`,
-      args: [
-        userEmail,
-        prefixLike(pathPrefix),
-        SHARED_OWNER,
-        prefixLike(pathPrefix),
-        WORKSPACE_OWNER,
-        prefixLike(pathPrefix),
-      ],
-    });
-    const resources = rows.map(rowToMeta);
-    const local = await localWorkspaceResourceMetas(pathPrefix);
-    const granted = await grantedWorkspaceResources({
-      pathPrefix,
-      workspaceAppId: options?.workspaceAppId,
+  const organizationOwner = sharedResourceOwner(options?.orgId);
+  const [personal, organization, legacyShared, workspace] = await Promise.all([
+    resourceList(userEmail, pathPrefix, options),
+    organizationOwner === SHARED_OWNER
+      ? Promise.resolve([])
+      : resourceList(organizationOwner, pathPrefix, options),
+    resourceList(SHARED_OWNER, pathPrefix, options),
+    resourceList(WORKSPACE_OWNER, pathPrefix, {
+      ...options,
       userEmail,
-      orgId: options?.orgId,
-    });
-    return mergeResourceMetas(
-      local,
-      mergeResourceMetas(resources, granted.map(resourceToMeta)),
-    );
-  }
+    }),
+  ]);
 
-  const { rows } = await client.execute({
-    sql: `SELECT ${RESOURCE_META_SELECT} FROM resources WHERE owner = ?${visibilitySql}
-          UNION
-          SELECT ${RESOURCE_META_SELECT} FROM resources WHERE owner = ?${visibilitySql}
-          UNION
-          SELECT ${RESOURCE_META_SELECT} FROM resources WHERE owner = ?${visibilitySql}`,
-    args: [userEmail, SHARED_OWNER, WORKSPACE_OWNER],
-  });
-  const resources = rows.map(rowToMeta);
-  const local = await localWorkspaceResourceMetas();
-  const granted = await grantedWorkspaceResources({
-    workspaceAppId: options?.workspaceAppId,
-    userEmail,
-    orgId: options?.orgId,
-  });
+  // Later layers are inherited fallbacks. A personal resource wins over an
+  // organization resource, which wins over the legacy app-shared default,
+  // which wins over the workspace default.
   return mergeResourceMetas(
-    local,
-    mergeResourceMetas(resources, granted.map(resourceToMeta)),
+    personal,
+    mergeResourceMetas(
+      organization,
+      mergeResourceMetas(legacyShared, workspace),
+    ),
   );
 }
 
@@ -1497,7 +1498,13 @@ export async function resourceEffectiveContext(
     ...options,
     userEmail,
   });
-  const shared = await resourceGetByPath(SHARED_OWNER, path);
+  const organizationOwner = sharedResourceOwner(options?.orgId);
+  const organization =
+    organizationOwner === SHARED_OWNER
+      ? null
+      : await resourceGetByPath(organizationOwner, path);
+  const legacyShared = await resourceGetByPath(SHARED_OWNER, path);
+  const shared = organization ?? legacyShared;
   const personal = await resourceGetByPath(userEmail, path);
   const effective = personal ?? shared ?? workspace ?? null;
   const effectiveScope: ResourceInheritanceScope | null = personal
@@ -1525,7 +1532,7 @@ export async function resourceEffectiveContext(
     {
       scope: "shared",
       label: "Organization/app override",
-      owner: SHARED_OWNER,
+      owner: organizationOwner,
       resource: shared,
       canWrite: true,
     },

package/corpus/core/src/scripts/call-agent.ts

@@ -6,6 +6,7 @@ import {
   shouldPreferGlobalA2ASecret,
   signA2AToken,
 } from "../a2a/client.js";
+import type { Task } from "../a2a/types.js";
 import {
   formatLlmCredentialErrorMessage,
   isLlmCredentialError,
@@ -62,6 +63,26 @@ function getIntegrationCallTimeoutMs(): number | undefined {
   return DEFAULT_SERVERLESS_INTEGRATION_A2A_TIMEOUT_MS;
 }
 
+function integrationSourceContextHint(): string {
+  const integration = getIntegrationRequestContext();
+  const incoming = integration?.incoming;
+  if (incoming?.platform !== "slack" || !incoming.sourceUrl) return "";
+
+  try {
+    const sourceUrl = new URL(incoming.sourceUrl);
+    const isSlackHost =
+      sourceUrl.hostname === "slack.com" ||
+      sourceUrl.hostname.endsWith(".slack.com");
+    if (sourceUrl.protocol !== "https:" || !isSlackHost) return "";
+    return (
+      `\n\n[Source Slack thread: ${sourceUrl.toString()} ` +
+      "Preserve this exact URL as request provenance when creating an intake record or other artifact.]"
+    );
+  } catch {
+    return "";
+  }
+}
+
 function formatDownstreamLlmCredentialFailure(
   agentName: string,
   value: unknown,
@@ -125,7 +146,7 @@ export async function run(
   // suspenders with the receiver hint — but it works against any current
   // deployment, no redeploy required.
   const messageWithHint =
-    `${message}\n\n` +
+    `${message}${integrationSourceContextHint()}\n\n` +
     `[Note: this request comes from another app via A2A. The caller cannot see your local UI, deck list, or navigation — only the literal text you put in your reply. ` +
     `If you create or reference a deck/document/design/dashboard, include its FULLY-QUALIFIED URL (e.g. ${agent.url}/deck/<id>) in your reply, not a relative path. ` +
     `Use only artifact IDs and URL paths returned by successful actions — never invent slugs, IDs, or hosts.]`;
@@ -224,6 +245,70 @@ export async function run(
       // trade-off is we lose progressive in-UI text streaming for cross-app
       // A2A calls, but the receiving agent's full response still surfaces via
       // the tool_result event below.
+      //
+      // That trade-off has a second-order cost: callAgent()'s poll (see
+      // A2AClient.sendAndWait in a2a/client.ts) can legitimately run for
+      // minutes with nothing emitted to the parent between the "start" event
+      // above and "done" below. On the parent run, that silence freezes
+      // `last_progress_at` — shouldBumpProgressForEvent in
+      // agent/run-manager.ts treats a stream of literally nothing as no
+      // progress — which trips the client's stuck-detector
+      // (DEFAULT_STUCK_THRESHOLD_MS = 90_000 in
+      // client/use-run-stuck-detection.ts) and the server's stale-run sweep
+      // (BACKGROUND_RUN_STALE_MS = 90_000 in agent/run-store.ts). In
+      // production this handed users a "still working, no progress" Retry
+      // button that aborted a perfectly healthy call and re-ran the sub-agent
+      // from scratch.
+      //
+      // Fix: surface the REAL remote liveness the poll already gathers. The
+      // A2A poll round-trips to the remote agent every ~2s and gets back a
+      // task with `status.state` (see A2AClient.sendAndWait / `onUpdate`). We
+      // emit an `agent_call_progress` event ONLY from that callback, and ONLY
+      // when a poll actually succeeds AND reports an actively-working state.
+      // Crucially this is NOT a timer: if the remote hangs or dies, the poll
+      // fetch throws, `onUpdate` stops firing, we emit nothing, and the
+      // stuck-detector correctly surfaces its banner. A wall-clock heartbeat
+      // would instead keep a dead sub-agent looking alive forever — trading a
+      // false stuck-positive for a worse false stuck-negative.
+      //
+      // Throttle: the poll runs every ~2s but both thresholds above are 90s,
+      // so emitting per-poll would be ~45 events per stuck-window. We coalesce
+      // to at most one emission per 30s — a 3x margin under 90s, so at least
+      // two land inside either window even with jitter, without flooding.
+      //
+      // Shape: a dedicated `agent_call_progress` event type (see
+      // agent/types.ts), not an extra `agent_call` status. `agent_call`
+      // consumers (production-agent.ts's step summarizer, slack.ts's task
+      // cards) render any status that isn't "start"/"done" as a failure, so a
+      // "progress" status would surface an in-flight tick as an error. A
+      // distinct type is instead ignored gracefully everywhere: the run-event
+      // switches fall to their `default`, the client if-chains fall through,
+      // and sse-event-processor returns `{action:"continue"}`. It still counts
+      // as real progress in shouldBumpProgressForEvent (any non-special event
+      // type does), which is the whole point.
+      const PROGRESS_MIN_INTERVAL_MS = 30_000;
+      // Terminal states resolve the poll; "input-required" means the remote is
+      // blocked waiting on us, not making progress. Only actively-working
+      // states count as liveness worth surfacing.
+      const ACTIVELY_WORKING_STATES = new Set(["working", "submitted"]);
+      const callStartedAt = Date.now();
+      let lastProgressEmitAt = callStartedAt;
+      const onRemotePollUpdate = (task: Task) => {
+        const state = task?.status?.state;
+        if (!state || !ACTIVELY_WORKING_STATES.has(state)) return;
+        const now = Date.now();
+        if (now - lastProgressEmitAt < PROGRESS_MIN_INTERVAL_MS) return;
+        lastProgressEmitAt = now;
+        const detail = extractRemoteProgressDetail(task);
+        context.send!({
+          type: "agent_call_progress",
+          agent: agent.name,
+          state,
+          elapsedSeconds: Math.round((now - callStartedAt) / 1000),
+          ...(detail ? { detail } : {}),
+        });
+      };
+
       try {
         // Apply a polling cap ONLY for integration-platform callers on
         // serverless hosts. Normal chat, local Node, self-hosted Node, and
@@ -235,6 +320,7 @@ export async function run(
           userEmail: callerEmail,
           orgDomain: callerOrgDomain,
           orgSecret: callerOrgSecret,
+          onUpdate: onRemotePollUpdate,
           ...(callTimeoutMs ? { timeoutMs: callTimeoutMs } : {}),
         });
         responseText =
@@ -364,6 +450,26 @@ async function enqueueIntegrationContinuationIfPossible(
   }
 }
 
+// Pull a short human-readable detail from a polled A2A task's status message,
+// when the remote includes one, so the progress event can surface a real
+// signal (e.g. "Generating hero image…") instead of a bare elapsed counter.
+// Bounded so a chatty remote can't push a large payload through the event.
+const MAX_PROGRESS_DETAIL_CHARS = 200;
+function extractRemoteProgressDetail(task: Task): string | undefined {
+  const parts = task.status?.message?.parts;
+  if (!parts) return undefined;
+  const text = parts
+    .filter((p): p is { type: "text"; text: string } => p.type === "text")
+    .map((p) => p.text)
+    .join(" ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!text) return undefined;
+  return text.length > MAX_PROGRESS_DETAIL_CHARS
+    ? `${text.slice(0, MAX_PROGRESS_DETAIL_CHARS - 1)}…`
+    : text;
+}
+
 function getA2ATaskTimeoutTaskId(err: unknown): string | null {
   if (err instanceof A2ATaskTimeoutError) return err.taskId;