@agent-native/core 0.92.12 → 0.93.0

package/corpus/core/src/jobs/scheduler.ts

@@ -1,3 +1,4 @@
+import { collectFinalResponseTextFromAgentEvents } from "../a2a/response-text.js";
 import {
   getStoredModelForEngine,
   normalizeModelForEngine,
@@ -13,6 +14,7 @@ import {
 import { startRun, resolveRunSoftTimeoutMs } from "../agent/run-manager.js";
 import { createThread } from "../chat-threads/store.js";
 import {
+  organizationIdFromResourceOwner,
   resourceListAllOwners,
   resourcePut,
   type Resource,
@@ -32,6 +34,12 @@ export interface JobFrontmatter {
   lastStatus?: "success" | "error" | "running" | "skipped";
   lastError?: string;
   nextRun?: string;
+  originScopeId?: string;
+  deliveryPlatform?: string;
+  deliveryDestination?: string;
+  deliveryThreadRef?: string;
+  deliveryTenantId?: string;
+  model?: string;
 }
 
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
@@ -101,6 +109,24 @@ export function parseJobFrontmatter(content: string): {
       case "nextRun":
         meta.nextRun = value;
         break;
+      case "originScopeId":
+        meta.originScopeId = value;
+        break;
+      case "deliveryPlatform":
+        meta.deliveryPlatform = value;
+        break;
+      case "deliveryDestination":
+        meta.deliveryDestination = value;
+        break;
+      case "deliveryThreadRef":
+        meta.deliveryThreadRef = value;
+        break;
+      case "deliveryTenantId":
+        meta.deliveryTenantId = value;
+        break;
+      case "model":
+        meta.model = value;
+        break;
     }
   }
 
@@ -128,6 +154,16 @@ export function buildJobContent(meta: JobFrontmatter, body: string): string {
     lines.push(`lastError: "${escaped}"`);
   }
   if (meta.nextRun) lines.push(`nextRun: ${meta.nextRun}`);
+  if (meta.originScopeId) lines.push(`originScopeId: ${meta.originScopeId}`);
+  if (meta.deliveryPlatform)
+    lines.push(`deliveryPlatform: ${meta.deliveryPlatform}`);
+  if (meta.deliveryDestination)
+    lines.push(`deliveryDestination: ${meta.deliveryDestination}`);
+  if (meta.deliveryThreadRef)
+    lines.push(`deliveryThreadRef: ${meta.deliveryThreadRef}`);
+  if (meta.deliveryTenantId)
+    lines.push(`deliveryTenantId: ${meta.deliveryTenantId}`);
+  if (meta.model) lines.push(`model: ${meta.model}`);
   lines.push(`---`);
   lines.push("");
   lines.push(body);
@@ -297,7 +333,12 @@ async function isJobRunAsStillValid(
 ): Promise<{ ok: boolean; reason?: string }> {
   // Shared-owner sentinel isn't a real user (used by jobs run as the
   // workspace identity).
-  if (jobUserEmail === "__shared__") return { ok: true };
+  if (
+    jobUserEmail === "__shared__" ||
+    organizationIdFromResourceOwner(jobUserEmail)
+  ) {
+    return { ok: true };
+  }
   try {
     const { getDbExec } = await import("../db/client.js");
     const db = getDbExec();
@@ -390,7 +431,36 @@ async function executeJob(
   await updateResource(resource, meta, body);
 
   await runWithRequestContext(
-    { userEmail: jobUserEmail, orgId: jobOrgId },
+    {
+      userEmail: jobUserEmail,
+      orgId: jobOrgId,
+      ...(meta.originScopeId &&
+      meta.deliveryPlatform &&
+      meta.deliveryDestination
+        ? {
+            isIntegrationCaller: true,
+            integration: {
+              taskId: `job:${jobName}:${now.getTime()}`,
+              scopeId: meta.originScopeId,
+              principalType: "service" as const,
+              incoming: {
+                platform: meta.deliveryPlatform,
+                externalThreadId: `${meta.deliveryTenantId || "unknown"}:${meta.deliveryDestination}:${meta.deliveryThreadRef || "root"}`,
+                text: "",
+                tenantId: meta.deliveryTenantId,
+                integrationScopeId: meta.originScopeId,
+                platformContext: {
+                  channelId: meta.deliveryDestination,
+                  threadTs: meta.deliveryThreadRef,
+                  teamId: meta.deliveryTenantId,
+                },
+                threadRef: meta.deliveryThreadRef,
+                timestamp: now.getTime(),
+              },
+            },
+          }
+        : {}),
+    },
     async () => {
       try {
         const actions = deps.getActions();
@@ -408,6 +478,7 @@ async function executeJob(
             appId: deps.appId,
           }));
         const modelCandidate =
+          meta.model ??
           deps.model ??
           (await getStoredModelForEngine(engine, { appId: deps.appId })) ??
           engine.defaultModel;
@@ -454,6 +525,7 @@ async function executeJob(
         const jobUsageRef: {
           current: Awaited<ReturnType<typeof runAgentLoop>> | null;
         } = { current: null };
+        let responseText = "";
         await new Promise<void>((resolve, reject) => {
           const activeRun = startRun(
             runId,
@@ -482,6 +554,9 @@ async function executeJob(
                 hardAbortTimer = null;
               }
               if (run.status === "completed") {
+                responseText = collectFinalResponseTextFromAgentEvents(
+                  (run.events ?? []).map((event) => event.event),
+                );
                 resolve();
               } else {
                 reject(new Error(`Job run ended with status: ${run.status}`));
@@ -515,6 +590,29 @@ async function executeJob(
 
         if (jobError) throw jobError;
 
+        if (
+          responseText.trim() &&
+          meta.deliveryPlatform &&
+          meta.deliveryDestination
+        ) {
+          const { getDefaultAdapter } =
+            await import("../integrations/adapters/index.js");
+          const adapter = getDefaultAdapter(meta.deliveryPlatform);
+          if (!adapter?.sendMessageToTarget) {
+            throw new Error(
+              `Recurring job delivery is not supported for ${meta.deliveryPlatform}`,
+            );
+          }
+          await adapter.sendMessageToTarget(
+            adapter.formatAgentResponse(responseText),
+            {
+              destination: meta.deliveryDestination,
+              threadRef: meta.deliveryThreadRef ?? null,
+              tenantId: meta.deliveryTenantId,
+            },
+          );
+        }
+
         const jobUsage = jobUsageRef.current;
         if (
           jobUsage &&

package/corpus/core/src/jobs/tools.ts

@@ -5,11 +5,14 @@ import {
   resourceGetByPath,
   resourceList,
   resourceDelete,
+  organizationIdFromResourceOwner,
+  sharedResourceOwner,
   SHARED_OWNER,
 } from "../resources/store.js";
 import {
   getRequestUserEmail,
   getRequestOrgId,
+  getIntegrationRequestContext,
 } from "../server/request-context.js";
 import { isValidCron, nextOccurrence, describeCron } from "./cron.js";
 import {
@@ -24,6 +27,10 @@ function getOwner(): string {
   return email;
 }
 
+function getSharedOwner(): string {
+  return sharedResourceOwner(getRequestOrgId());
+}
+
 /**
  * Determine if the current request's user is an org owner/admin in the
  * given org. Used to allow privileged users to update or delete shared
@@ -65,7 +72,8 @@ async function authorizeJobMutation(
   resourceOwner: string,
   meta: JobFrontmatter,
 ): Promise<string | null> {
-  if (resourceOwner !== SHARED_OWNER) {
+  const resourceOrgId = organizationIdFromResourceOwner(resourceOwner);
+  if (resourceOwner !== SHARED_OWNER && !resourceOrgId) {
     // Personal-scope job — owner is the request's user. resourceGetByPath is
     // already scoped to the caller, so we know meta.createdBy must match.
     return null;
@@ -76,7 +84,7 @@ async function authorizeJobMutation(
 
   // Allow org owners/admins to manage shared jobs created by other members.
   const isAdmin = await isCurrentUserOrgAdmin(
-    meta.orgId ?? getRequestOrgId() ?? undefined,
+    resourceOrgId ?? meta.orgId ?? getRequestOrgId() ?? undefined,
   );
   if (isAdmin) return null;
 
@@ -84,7 +92,7 @@ async function authorizeJobMutation(
 }
 
 async function runCreate(args: Record<string, any>): Promise<string> {
-  const { name, schedule, instructions, scope, runAs } = args;
+  const { name, schedule, instructions, scope, runAs, model } = args;
 
   if (!name || !schedule || !instructions) {
     return JSON.stringify({
@@ -98,10 +106,13 @@ async function runCreate(args: Record<string, any>): Promise<string> {
     });
   }
 
-  const owner = scope === "personal" ? getOwner() : SHARED_OWNER;
+  const owner = scope === "personal" ? getOwner() : getSharedOwner();
   const path = `jobs/${name}.md`;
   const now = new Date();
   const next = nextOccurrence(schedule, now);
+  const integration = getIntegrationRequestContext();
+  const channelId = integration?.incoming.platformContext.channelId;
+  const threadRef = integration?.incoming.threadRef;
 
   const meta: JobFrontmatter = {
     schedule,
@@ -110,6 +121,20 @@ async function runCreate(args: Record<string, any>): Promise<string> {
     orgId: getRequestOrgId() || undefined,
     runAs: runAs === "shared" ? "shared" : "creator",
     nextRun: next.toISOString(),
+    ...(integration?.scopeId ? { originScopeId: integration.scopeId } : {}),
+    ...(integration?.incoming.platform
+      ? { deliveryPlatform: integration.incoming.platform }
+      : {}),
+    ...(typeof channelId === "string"
+      ? { deliveryDestination: channelId }
+      : {}),
+    ...(typeof threadRef === "string" ? { deliveryThreadRef: threadRef } : {}),
+    ...(integration?.incoming.tenantId
+      ? { deliveryTenantId: integration.incoming.tenantId }
+      : {}),
+    ...(typeof model === "string" && model.trim()
+      ? { model: model.trim() }
+      : {}),
   };
 
   const content = buildJobContent(meta, instructions);
@@ -128,10 +153,11 @@ async function runCreate(args: Record<string, any>): Promise<string> {
 
 async function runList(args: Record<string, any>): Promise<string> {
   const owner = getOwner();
+  const sharedOwner = getSharedOwner();
   // Fetch only current user's and shared jobs (not other users')
   const [personal, shared] = await Promise.all([
     resourceList(owner, "jobs/"),
-    resourceList(SHARED_OWNER, "jobs/"),
+    resourceList(sharedOwner, "jobs/"),
   ]);
   let resources = [...personal, ...shared];
   if (args.scope === "personal") resources = personal;
@@ -146,7 +172,7 @@ async function runList(args: Record<string, any>): Promise<string> {
       return {
         name: r.path.replace(/^jobs\//, "").replace(/\.md$/, ""),
         path: r.path,
-        scope: r.owner === SHARED_OWNER ? "shared" : "personal",
+        scope: r.owner === sharedOwner ? "shared" : "personal",
         schedule: meta.schedule,
         scheduleDescription: meta.schedule ? describeCron(meta.schedule) : "",
         enabled: meta.enabled,
@@ -154,6 +180,10 @@ async function runList(args: Record<string, any>): Promise<string> {
         lastStatus: meta.lastStatus || null,
         lastError: meta.lastError || null,
         nextRun: meta.nextRun || null,
+        originScopeId: meta.originScopeId || null,
+        deliveryPlatform: meta.deliveryPlatform || null,
+        deliveryDestination: meta.deliveryDestination || null,
+        model: meta.model || null,
       };
     }),
   );
@@ -166,11 +196,11 @@ async function runList(args: Record<string, any>): Promise<string> {
 }
 
 async function runUpdate(args: Record<string, any>): Promise<string> {
-  const { name, schedule, instructions, enabled, scope, runAs } = args;
+  const { name, schedule, instructions, enabled, scope, runAs, model } = args;
   const path = `jobs/${name}.md`;
 
   // Try to find the resource
-  let resource = await resourceGetByPath(SHARED_OWNER, path);
+  let resource = await resourceGetByPath(getSharedOwner(), path);
   if (!resource && scope !== "shared") {
     resource = await resourceGetByPath(getOwner(), path);
   }
@@ -211,6 +241,7 @@ async function runUpdate(args: Record<string, any>): Promise<string> {
   if (runAs === "creator" || runAs === "shared") {
     meta.runAs = runAs;
   }
+  if (typeof model === "string" && model.trim()) meta.model = model.trim();
 
   const newBody = instructions || body;
   const content = buildJobContent(meta, newBody);
@@ -230,7 +261,7 @@ async function runDelete(args: Record<string, any>): Promise<string> {
   const { name, scope } = args;
   const path = `jobs/${name}.md`;
 
-  let resource = await resourceGetByPath(SHARED_OWNER, path);
+  let resource = await resourceGetByPath(getSharedOwner(), path);
   if (!resource && scope !== "shared") {
     resource = await resourceGetByPath(getOwner(), path);
   }
@@ -306,6 +337,11 @@ Cron format is 5 fields: minute hour day-of-month month day-of-week. Common patt
                 "Who shared jobs execute as: creator or shared. Default: creator. Used with create and update.",
               enum: ["creator", "shared"],
             },
+            model: {
+              type: "string",
+              description:
+                "Optional model id for this routine. The channel/app/engine default is used when omitted.",
+            },
           },
           required: ["action"],
         },

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 };
 }