@desplega.ai/agent-swarm 1.87.0 → 1.89.0

package/src/workflows/engine.ts

@@ -25,6 +25,10 @@ const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_ITERATIONS = Number(process.env.WORKFLOW_MAX_ITERATIONS) || 100;
 const MAX_STEPS_PER_RUN = Number(process.env.WORKFLOW_MAX_STEPS_PER_RUN) || 500;
 
+export interface WorkflowExecutionOptions {
+  requestedByUserId?: string;
+}
+
 /**
  * Error thrown when trigger data fails validation against a workflow's triggerSchema.
  */
@@ -50,6 +54,7 @@ export async function startWorkflowExecution(
   workflow: Workflow,
   triggerData: unknown,
   registry: ExecutorRegistry,
+  options: WorkflowExecutionOptions = {},
 ): Promise<string> {
   // Validate trigger data against triggerSchema (before any DB writes)
   if (workflow.triggerSchema) {
@@ -76,6 +81,9 @@ export async function startWorkflowExecution(
 
   // Resolve inputs and merge into initial context
   const ctx: Record<string, unknown> = { trigger: triggerData };
+  if (options.requestedByUserId) {
+    ctx.swarm = { requestedByUserId: options.requestedByUserId };
+  }
 
   // Inject workflow-level metadata for interpolation ({{workflow.dir}}, {{workflow.vcsRepo}})
   if (workflow.dir || workflow.vcsRepo) {
@@ -98,7 +106,16 @@ export async function startWorkflowExecution(
 
   const entryNodes = findEntryNodes(workflow.definition);
   const secretKeys = getSecretInputKeys(workflow.input);
-  await walkGraph(workflow.definition, runId, ctx, entryNodes, registry, workflow.id, secretKeys);
+  await walkGraph(
+    workflow.definition,
+    runId,
+    ctx,
+    entryNodes,
+    registry,
+    workflow.id,
+    secretKeys,
+    options,
+  );
   return runId;
 }
 
@@ -127,6 +144,7 @@ export async function walkGraph(
   registry: ExecutorRegistry,
   workflowId?: string,
   secretKeys: Set<string> = new Set(),
+  options: WorkflowExecutionOptions = {},
 ): Promise<void> {
   let nodeExecutionCount = 0;
   const completedNodeIds = new Set(getCompletedStepNodeIds(runId));
@@ -234,7 +252,7 @@ export async function walkGraph(
     // Execute all pending nodes in parallel
     const results = await Promise.all(
       pendingNodes.map((node) =>
-        executeStep(def, runId, ctx, node, registry, workflowId, secretKeys).catch(
+        executeStep(def, runId, ctx, node, registry, workflowId, secretKeys, options).catch(
           (_err): StepResult => ({
             outcome: "failed",
             successors: [],
@@ -385,6 +403,7 @@ async function executeStep(
   registry: ExecutorRegistry,
   workflowId?: string,
   secretKeys: Set<string> = new Set(),
+  options: WorkflowExecutionOptions = {},
 ): Promise<StepResult> {
   // Use iteration-aware idempotency key to support loops.
   // Count existing steps for this node to determine the current iteration.
@@ -438,6 +457,7 @@ async function executeStep(
     if (ctx.trigger !== undefined) interpolationCtx.trigger = ctx.trigger;
     if (ctx.input !== undefined) interpolationCtx.input = ctx.input;
     if (ctx.workflow !== undefined) interpolationCtx.workflow = ctx.workflow;
+    if (ctx.swarm !== undefined) interpolationCtx.swarm = ctx.swarm;
     // Resolve declared inputs
     for (const [localName, sourcePath] of Object.entries(node.inputs)) {
       const keys = sourcePath.split(".");
@@ -457,6 +477,7 @@ async function executeStep(
     if (ctx.trigger !== undefined) interpolationCtx.trigger = ctx.trigger;
     if (ctx.input !== undefined) interpolationCtx.input = ctx.input;
     if (ctx.workflow !== undefined) interpolationCtx.workflow = ctx.workflow;
+    if (ctx.swarm !== undefined) interpolationCtx.swarm = ctx.swarm;
   }
 
   // 3c. Validate resolved inputs against inputSchema if defined
@@ -492,6 +513,7 @@ async function executeStep(
     nodeId: node.id,
     workflowId: workflowId || "",
     dryRun: false,
+    requestedByUserId: options.requestedByUserId,
   };
 
   const timeoutMs =

package/src/workflows/executors/agent-task.ts

@@ -18,6 +18,7 @@ const AgentTaskConfigSchema = z.object({
   vcsRepo: z.string().min(1).optional(),
   model: z.string().min(1).optional(),
   parentTaskId: z.string().uuid().optional(),
+  requestedByUserId: z.string().optional(),
   outputSchema: z.record(z.string(), z.unknown()).optional(),
   followUpConfig: FollowUpConfigSchema.optional(),
 });
@@ -95,6 +96,7 @@ export class AgentTaskExecutor extends BaseExecutor<
         vcsRepo: effectiveVcsRepo,
         model: config.model,
         parentTaskId: config.parentTaskId,
+        requestedByUserId: config.requestedByUserId ?? meta.requestedByUserId,
         outputSchema: config.outputSchema,
         followUpConfig: config.followUpConfig,
         contextKey: workflowContextKey({ workflowRunId: meta.runId }),

package/src/x/composio.ts

@@ -0,0 +1,295 @@
+import { registerVolatileSecret, scrubObject, scrubSecrets } from "../utils/secret-scrubber";
+
+export const DEFAULT_COMPOSIO_BASE_URL = "https://backend.composio.dev/api/v3.1";
+export const COMPOSIO_HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"] as const;
+
+const HTTP_METHODS = new Set<string>(COMPOSIO_HTTP_METHODS);
+
+export type ComposioHttpMethod = (typeof COMPOSIO_HTTP_METHODS)[number];
+
+export interface ComposioRequestArgs {
+  baseUrl: string;
+  body?: unknown;
+  endpoint: string;
+  headers: Record<string, string>;
+  method: string;
+  query: Array<[string, string]>;
+  raw: boolean;
+  useOrgKey: boolean;
+}
+
+export interface ComposioRequestDeps {
+  env?: Record<string, string | undefined>;
+  fetch?: typeof fetch;
+}
+
+export interface ComposioExecutionResult {
+  body: unknown;
+  contentType: string | null;
+  error?: string;
+  formattedBody: string;
+  method: string;
+  ok: boolean;
+  status: number;
+  statusText: string;
+  text: string;
+  url: string;
+}
+
+export function parseComposioArgs(
+  argv: string[],
+  env: Record<string, string | undefined> = process.env,
+): ComposioRequestArgs {
+  const method = argv[0]?.toUpperCase();
+  if (!method || !HTTP_METHODS.has(method)) {
+    throw new Error(
+      "first argument after composio must be an HTTP method: GET, POST, PUT, PATCH, DELETE, or HEAD",
+    );
+  }
+
+  const endpoint = argv[1];
+  if (!endpoint || endpoint.startsWith("-")) {
+    throw new Error("endpoint path is required, e.g. /tools");
+  }
+  assertRelativeComposioPath(endpoint);
+
+  const parsed: ComposioRequestArgs = {
+    baseUrl: env.COMPOSIO_BASE_URL || DEFAULT_COMPOSIO_BASE_URL,
+    endpoint,
+    headers: {},
+    method,
+    query: [],
+    raw: false,
+    useOrgKey: false,
+  };
+
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i] ?? "";
+    if (arg === "--base-url") {
+      parsed.baseUrl = requiredValue(argv, ++i, "--base-url");
+    } else if (arg === "--body" || arg === "--data") {
+      parsed.body = parseJsonArg(requiredValue(argv, ++i, arg), arg);
+    } else if (arg === "--query" || arg === "-q") {
+      parsed.query.push(parsePair(requiredValue(argv, ++i, arg), arg));
+    } else if (arg === "--header" || arg === "-H") {
+      const [key, value] = parseHeader(requiredValue(argv, ++i, arg));
+      parsed.headers[key] = value;
+    } else if (arg === "--org") {
+      parsed.useOrgKey = true;
+    } else if (arg === "--raw") {
+      parsed.raw = true;
+    } else {
+      throw new Error(`unknown option: ${arg}`);
+    }
+  }
+
+  if ((method === "GET" || method === "HEAD") && parsed.body !== undefined) {
+    throw new Error(`${method} requests cannot include --body`);
+  }
+
+  return parsed;
+}
+
+export async function executeComposioRequest(
+  args: ComposioRequestArgs,
+  deps: ComposioRequestDeps = {},
+): Promise<ComposioExecutionResult> {
+  const env = deps.env ?? process.env;
+  const fetchImpl = deps.fetch ?? fetch;
+  const apiKey = args.useOrgKey ? env.COMPOSIO_ORG_API_KEY : env.COMPOSIO_API_KEY;
+  const keyName = args.useOrgKey ? "COMPOSIO_ORG_API_KEY" : "COMPOSIO_API_KEY";
+
+  if (!apiKey) {
+    return {
+      body: null,
+      contentType: null,
+      error: `${keyName} is required. Bun auto-loads .env when running the CLI.`,
+      formattedBody: "",
+      method: args.method,
+      ok: false,
+      status: 0,
+      statusText: "Missing API key",
+      text: "",
+      url: buildComposioUrl(args.baseUrl, args.endpoint, args.query),
+    };
+  }
+
+  registerVolatileSecret(apiKey, keyName);
+
+  const url = buildComposioUrl(args.baseUrl, args.endpoint, args.query);
+  const headers: Record<string, string> = {
+    ...args.headers,
+    [args.useOrgKey ? "x-org-api-key" : "x-api-key"]: apiKey,
+  };
+  if (args.body !== undefined && !headers["Content-Type"] && !headers["content-type"]) {
+    headers["Content-Type"] = "application/json";
+  }
+
+  let response: Response;
+  try {
+    response = await fetchImpl(url, {
+      body: args.body === undefined ? undefined : JSON.stringify(args.body),
+      headers,
+      method: args.method,
+    });
+  } catch (err) {
+    return {
+      body: null,
+      contentType: null,
+      error: `request failed: ${scrubSecrets(errorMessage(err))}`,
+      formattedBody: "",
+      method: args.method,
+      ok: false,
+      status: 0,
+      statusText: "Request failed",
+      text: "",
+      url,
+    };
+  }
+
+  const text = await response.text();
+  const contentType = response.headers.get("Content-Type");
+  const body = parseResponseBody(text, contentType);
+  const formattedBody = formatResponseBody(text, contentType, args.raw);
+
+  return {
+    body: scrubObject(body),
+    contentType,
+    formattedBody,
+    method: args.method,
+    ok: response.ok,
+    status: response.status,
+    statusText: response.statusText,
+    text: scrubSecrets(text),
+    url,
+  };
+}
+
+export function composioArgsFromParts(input: {
+  baseUrl?: string;
+  body?: unknown;
+  endpoint: string;
+  headers?: Record<string, string>;
+  method: ComposioHttpMethod | string;
+  query?: Array<[string, string]> | Record<string, string | number | boolean | null | undefined>;
+  raw?: boolean;
+  useOrgKey?: boolean;
+}): ComposioRequestArgs {
+  const method = input.method.toUpperCase();
+  if (!HTTP_METHODS.has(method)) {
+    throw new Error(`unsupported HTTP method: ${input.method}`);
+  }
+  if ((method === "GET" || method === "HEAD") && input.body !== undefined) {
+    throw new Error(`${method} requests cannot include a body`);
+  }
+  assertRelativeComposioPath(input.endpoint);
+
+  return {
+    baseUrl: input.baseUrl || process.env.COMPOSIO_BASE_URL || DEFAULT_COMPOSIO_BASE_URL,
+    body: input.body,
+    endpoint: input.endpoint,
+    headers: input.headers ?? {},
+    method,
+    query: normalizeQuery(input.query),
+    raw: input.raw ?? false,
+    useOrgKey: input.useOrgKey ?? false,
+  };
+}
+
+export function formatComposioResultForCli(result: ComposioExecutionResult): string {
+  if (result.formattedBody) return result.formattedBody;
+  return `HTTP ${result.status} ${result.statusText}`.trim();
+}
+
+function normalizeQuery(
+  query?: Array<[string, string]> | Record<string, string | number | boolean | null | undefined>,
+): Array<[string, string]> {
+  if (!query) return [];
+  if (Array.isArray(query)) return query;
+  const pairs: Array<[string, string]> = [];
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null) continue;
+    pairs.push([key, String(value)]);
+  }
+  return pairs;
+}
+
+function assertRelativeComposioPath(endpoint: string): void {
+  if (/^https?:\/\//i.test(endpoint)) {
+    throw new Error("endpoint must be a Composio API path, not an absolute URL");
+  }
+}
+
+function buildComposioUrl(
+  baseUrl: string,
+  endpoint: string,
+  query: Array<[string, string]>,
+): string {
+  const normalizedBase = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+  const cleanEndpoint = endpoint.replace(/^\/+/, "");
+  const url = new URL(cleanEndpoint, normalizedBase);
+  for (const [key, value] of query) {
+    url.searchParams.append(key, value);
+  }
+  return url.toString();
+}
+
+function formatResponseBody(text: string, contentType: string | null, raw: boolean): string {
+  if (raw) return scrubSecrets(text);
+  const body = parseResponseBody(text, contentType);
+  if (body === null || body === "") return "";
+  if (body !== text) return scrubSecrets(JSON.stringify(body, null, 2));
+  return scrubSecrets(text);
+}
+
+function parseResponseBody(text: string, contentType: string | null): unknown {
+  const trimmed = text.trim();
+  if (!trimmed) return "";
+  if (contentType?.includes("json") || trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+      return text;
+    }
+  }
+  return text;
+}
+
+function parseJsonArg(value: string, flag: string): unknown {
+  try {
+    return JSON.parse(value);
+  } catch (err) {
+    throw new Error(`${flag} must be valid JSON: ${errorMessage(err)}`);
+  }
+}
+
+function parsePair(raw: string, flag: string): [string, string] {
+  const index = raw.indexOf("=");
+  if (index <= 0) {
+    throw new Error(`${flag} must use key=value`);
+  }
+  return [raw.slice(0, index), raw.slice(index + 1)];
+}
+
+function parseHeader(raw: string): [string, string] {
+  const equalsIndex = raw.indexOf("=");
+  const colonIndex = raw.indexOf(":");
+  const index =
+    colonIndex > 0 && (equalsIndex === -1 || colonIndex < equalsIndex) ? colonIndex : equalsIndex;
+  if (index <= 0) {
+    throw new Error("--header must use Name=value or Name: value");
+  }
+  return [raw.slice(0, index).trim(), raw.slice(index + 1).trim()];
+}
+
+function requiredValue(argv: string[], index: number, flag: string): string {
+  const value = argv[index];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/templates/skills/artifacts/config.json

@@ -9,5 +9,6 @@
   "category": "skills",
   "placeholders": [],
   "runAllSeedersCandidate": true,
+  "systemDefault": true,
   "tags": ["artifacts", "evidence", "qa"]
 }

package/templates/skills/attio-interaction/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: attio-interaction
+description: "How to read and write your Attio CRM via the REST API v2: query/filter records, upsert companies/people/deals with matching_attribute, write notes and tasks, manage list entries, and handle webhooks. Auth via ATTIO_API_KEY (Bearer token). Use this skill whenever you need to interact with Attio CRM data from the swarm."
+user-invocable: false
+agentAutoTrigger: When asked to read from, write to, search, query, or update Attio CRM records, deals, companies, people, notes, tasks, or lists. Also when a task references Attio data such as pipeline, ICP scoring, lead enrichment, stale deals, CRM hygiene, deal handoffs, or logging an interaction to Attio.
+---
+
+# Attio Interaction (Read + Write)
+
+Use this skill to read and write your Attio CRM through the REST API v2. Every read or write is a direct API call; agent-swarm does not maintain a separate Attio sync.
+
+## TL;DR
+
+1. Resolve `ATTIO_API_KEY` from swarm config before making calls.
+2. Base URL: `https://api.attio.com/v2/`
+3. Use `Authorization: Bearer $ATTIO_API_KEY`, `Content-Type: application/json`, and `Accept: application/json`.
+4. Prefer upsert over create for People, Companies, and Deals: `PUT /v2/objects/{slug}/records` with `matching_attribute`.
+5. Rate limits: 100 reads/sec, 25 writes/sec. Pace write bursts to roughly 15-20/sec.
+6. Attribute values are arrays, even for scalar values: `[{ "value": 42 }]`, never `42`.
+
+## Authentication
+
+```bash
+ATTIO_API_KEY=$(get-config key="ATTIO_API_KEY" includeSecrets=true)
+
+curl -sS "https://api.attio.com/v2/objects" \
+  -H "Authorization: Bearer $ATTIO_API_KEY" \
+  -H "Accept: application/json"
+```
+
+If calls return `401`, re-fetch the key from config. If it still fails, notify the Lead; the key may need rotation. Do not retry silently.
+
+## Core object slugs
+
+| Object | API slug | Primary matching attribute |
+|---|---|---|
+| Companies | `companies` | `domains` |
+| People | `people` | `email_addresses` |
+| Deals | `deals` | Usually no global dedupe key; link to company/person records |
+
+Custom objects use their configured API slug. Discover them with `GET /v2/objects`.
+
+## Common operations
+
+### 1. Discover objects and slugs
+
+```bash
+curl -sS "https://api.attio.com/v2/objects" \
+  -H "Authorization: Bearer $ATTIO_API_KEY" \
+  -H "Accept: application/json" \
+  | jq '.data[] | {slug: .api_slug, name: .title}'
+```
+
+### 2. Query records with filters and pagination
+
+```bash
+curl -sS -X POST "https://api.attio.com/v2/objects/companies/records/query" \
+  -H "Authorization: Bearer $ATTIO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "filter": {
+      "stage": { "$not_equal": "Won" }
+    },
+    "limit": 100,
+    "offset": 0
+  }' | jq '.data[] | {record_id: .id.record_id, name: .values.name[0].value}'
+```
+
+Paginate by increasing `offset` until `data` is empty. For no filter, omit the `filter` key.
+
+### 3. Get a single record
+
+```bash
+curl -sS "https://api.attio.com/v2/objects/companies/records/{RECORD_ID}" \
+  -H "Authorization: Bearer $ATTIO_API_KEY" \
+  -H "Accept: application/json" \
+  | jq '.data.values'
+```
+
+### 4. Upsert a company by domain
+
+Use `PUT` with `matching_attribute`. It creates if not found and updates if found, so it is safe to call repeatedly.
+
+```bash
+curl -sS -X PUT "https://api.attio.com/v2/objects/companies/records" \
+  -H "Authorization: Bearer $ATTIO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "data": {
+      "values": {
+        "name": [{ "value": "Acme Corp" }],
+        "domains": [{ "domain": "acme.com" }],
+        "employee_count": [{ "value": 150 }]
+      }
+    },
+    "matching_attribute": "domains"
+  }' | jq '{record_id: .data.id.record_id}'
+```
+
+### 5. Upsert a person by email
+
+```bash
+curl -sS -X PUT "https://api.attio.com/v2/objects/people/records" \
+  -H "Authorization: Bearer $ATTIO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "data": {
+      "values": {
+        "name": [{ "first_name": "Jane", "last_name": "Doe" }],
+        "email_addresses": [{ "email_address": "jane@acme.com" }],
+        "job_title": [{ "value": "CTO" }]
+      }
+    },
+    "matching_attribute": "email_addresses"
+  }' | jq '{record_id: .data.id.record_id}'
+```
+
+### 6. Update specific attributes on an existing record
+
+```bash
+curl -sS -X PATCH "https://api.attio.com/v2/objects/companies/records/{RECORD_ID}" \
+  -H "Authorization: Bearer $ATTIO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "data": {
+      "values": {
+        "icp_score": [{ "value": 85 }],
+        "icp_tier": [{ "value": "Tier 1" }]
+      }
+    }
+  }'
+```
+
+### 7. Write a note to a record
+
+```bash
+curl -sS -X POST "https://api.attio.com/v2/notes" \
+  -H "Authorization: Bearer $ATTIO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "data": {
+      "parent_object": "companies",
+      "parent_record_id": "{RECORD_ID}",
+      "title": "Enrichment - 2026-06-02",
+      "content": "Employee count: 150. Funding stage: Series A. Tech stack: Node.js, React."
+    }
+  }' | jq '{note_id: .data.id.note_id}'
+```
+
+### 8. Create a task linked to a record
+
+```bash
+curl -sS "https://api.attio.com/v2/workspace_members" \
+  -H "Authorization: Bearer $ATTIO_API_KEY" \
+  -H "Accept: application/json" \
+  | jq '.data[] | {member_id: .id.workspace_member_id, name: .name, email: .email_address}'
+
+curl -sS -X POST "https://api.attio.com/v2/tasks" \
+  -H "Authorization: Bearer $ATTIO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "data": {
+      "content": "Follow up - no contact in 21 days",
+      "is_completed": false,
+      "assignees": [
+        { "referenced_actor_type": "workspace-member", "referenced_actor_id": "{MEMBER_ID}" }
+      ],
+      "linked_records": [
+        { "target_object": "deals", "target_record_id": "{DEAL_RECORD_ID}" }
+      ]
+    }
+  }' | jq '{task_id: .data.id.task_id}'
+```
+
+### 9. Post a comment on a record
+
+```bash
+curl -sS -X POST "https://api.attio.com/v2/comments" \
+  -H "Authorization: Bearer $ATTIO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "data": {
+      "record": { "target_object": "companies", "target_record_id": "{RECORD_ID}" },
+      "content": [
+        { "type": "text", "text": "Possible duplicate of acme-corp-old - please review and merge." }
+      ]
+    }
+  }' | jq '{comment_id: .data.id.comment_id}'
+```
+
+### 10. Query a list or pipeline view
+
+```bash
+curl -sS "https://api.attio.com/v2/lists" \
+  -H "Authorization: Bearer $ATTIO_API_KEY" \
+  -H "Accept: application/json" \
+  | jq '.data[] | {list_id: .id.list_id, name: .title}'
+
+curl -sS -X POST "https://api.attio.com/v2/lists/{LIST_ID}/entries/query" \
+  -H "Authorization: Bearer $ATTIO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{ "limit": 100, "offset": 0 }' \
+  | jq '.data[] | {entry_id: .id.entry_id, record_id: .record_id}'
+```
+
+### 11. Global search across objects
+
+```bash
+curl -sS -X POST "https://api.attio.com/v2/records/search" \
+  -H "Authorization: Bearer $ATTIO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{ "query": "acme", "limit": 10 }' \
+  | jq '.data[] | {object: .object_type, record_id: .id.record_id}'
+```
+
+## Webhooks
+
+Attio delivers webhooks at least once. Payloads contain IDs only, so always re-fetch the full record via `GET` before acting.
+
+Key event types:
+
+- `record.created`, `record.updated`, `record.deleted`
+- `list-entry.created`, `list-entry.updated`, `list-entry.deleted`
+- `note.created`
+- `task.created`, `task.completed`
+
+Webhook timeout is 5 seconds. Respond `200` immediately and do async processing in a follow-up swarm task.
+
+## Rate limits
+
+| Operation | Hard limit | Safe working rate |
+|---|---|---|
+| Reads | 100 req/sec | ~80 req/sec |
+| Writes | 25 req/sec | ~15-20 req/sec |
+
+Add `sleep 0.05` between write calls in loops. Attio does not provide a native batch endpoint for these operations.
+
+## Operational rules
+
+- Upsert first. Use `PUT /records` with `matching_attribute` for create-or-update. `POST /records` can create duplicates.
+- Re-fetch webhook records. Webhook payloads are event hints, not full source-of-truth records.
+- Values are arrays. Every attribute value must be wrapped in an array.
+- No merge endpoint. Attio has no API-level record merge; dedupe agents should flag duplicates as comments or tasks for human review.
+- Check config first. Fetch `ATTIO_API_KEY` via `get-config includeSecrets=true`; never hardcode it.
+
+## Error handling
+
+| Status | Likely cause | Action |
+|---|---|---|
+| 401 | API key invalid or expired | Re-fetch from config. If still failing, notify Lead for rotation. |
+| 403 | Key lacks permission | Check the Attio API key's workspace permissions. |
+| 404 | Wrong object slug or record ID | Re-discover slugs with `GET /v2/objects`. |
+| 400 | Malformed body | Ensure attribute values are wrapped in arrays. |
+| 422 | Validation or conflict error | Read the `errors` array for field-level details. |
+| 429 | Rate-limited | Back off and retry after `Retry-After` if provided. |
+
+## Worked example: stale deal reactivation
+
+```bash
+ATTIO_API_KEY=$(get-config key="ATTIO_API_KEY" includeSecrets=true)
+
+DEALS=$(curl -sS -X POST "https://api.attio.com/v2/objects/deals/records/query" \
+  -H "Authorization: Bearer $ATTIO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"filter": {"stage": {"$not_equal": "Won"}}, "limit": 200}')
+
+echo "$DEALS" | jq -r '.data[] | .id.record_id' | while read -r RECORD_ID; do
+  RECORD=$(curl -sS "https://api.attio.com/v2/objects/deals/records/$RECORD_ID" \
+    -H "Authorization: Bearer $ATTIO_API_KEY" \
+    -H "Accept: application/json")
+  # Compute staleness from the relevant date attribute. If stale, create a task.
+  sleep 0.05
+done
+```
+
+## Related references
+
+- Official Attio REST API docs: https://developers.attio.com/reference
+- Official Attio MCP overview: https://docs.attio.com/mcp/overview