@synap-core/workspace-templates 0.12.0 → 0.23.0

package/capabilities/unipile-linkedin.capability.json

@@ -0,0 +1,471 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "unipile-linkedin",
+    "name": "Unipile — LinkedIn & Messaging",
+    "description": "Search LinkedIn, view profiles, send connection requests and first messages, and read or reply to conversations on LinkedIn, WhatsApp, Telegram and Instagram through Unipile. Needs a Unipile v2 API key and a connected account.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": false
+  },
+  "spec": {
+    "key": "unipile-linkedin",
+    "name": "Unipile — Messaging & LinkedIn",
+    "description": "Unified messaging + LinkedIn outreach via Unipile API v2 (API-key connector). Stores the Unipile v2 API key in the vault and registers one HTTP tool against the SINGLE global v2 host https://api.unipile.com/v2 (no per-tenant DSN — v2 removed it), authenticating with the X-API-KEY header. Skills: (a) provider-agnostic messaging — list accounts, list conversations, list messages, send into an existing thread, start a chat with one person on any account (unipile_start_chat) (works for LinkedIn/WhatsApp/Telegram/Instagram); (b) LinkedIn-specific — search people (read + persist variants), get a profile, send a connection request (v2 relation-request), start a NEW conversation (cold outreach via the CLASSIC_PRIMARY inbox), list relations + sent invitations, list the company pages an account administers (linkedin_list_company_pages), publish a post now (unipile_publish_post, the publish_post intent, one action per account from unipile_list_accounts). v2 notes baked in: account_id is a PATH segment (/{account_id}/...), send endpoints carry a /send suffix, LinkedIn cold-outreach uses /inboxes/CLASSIC_PRIMARY/chats/send with users_ids, invitations are /users/me/relation-requests, search is split per resource, and list envelopes are { data, total_count, next_cursor }. PRECONDITION: a Unipile v2 account (dashboardv2.unipile.com — v1 keys do NOT authenticate) with at least one connected provider account. Provider-agnostic skills take an explicit accountId (call unipile_list_accounts first). A pod app reaches unipile_send_message, unipile_start_chat, linkedin_send_first_message (send_message; the last one by the person's LinkedIn profile, 1st-degree connections only), linkedin_send_invite (request_connection, by their profile) and unipile_publish_post (publish_post) through their inputMaps: one action per account unipile_list_accounts lists, the recipient resolved by the pod ($to). LinkedIn skills take an accountId too: no skill code carries an install-time value, so the pod can update every install to a new version of this template. Skills call the tool by NAME via callProvider('unipile_linkedin', ...); the dispatcher injects the vaulted X-API-KEY server-side. key/tool name kept as unipile-linkedin/unipile_linkedin for backward compat with existing installs.",
+    "params": [
+      {
+        "name": "unipileApiKey",
+        "label": "Unipile v2 API key",
+        "type": "text",
+        "required": true,
+        "description": "The Unipile v2 X-API-KEY (from dashboardv2.unipile.com — a v1 key will NOT work against api.unipile.com/v2). Stored server-encrypted in the vault; never persisted in the template."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "unipileApiKeySecret",
+        "name": "{{name}} Unipile API key",
+        "value": "{{unipileApiKey}}",
+        "type": "api_key",
+        "description": "Unipile v2 X-API-KEY for the connector."
+      }
+    ],
+    "tools": [
+      {
+        "name": "unipile_linkedin",
+        "kind": "api",
+        "description": "Authenticated HTTP access to the Unipile v2 API at the single global host https://api.unipile.com/v2 (no DSN). The applier injects the vaulted key into the X-API-KEY header; its credentialRef is remapped to the runtime vault://<id> at apply time.",
+        "credentialRef": "unipileApiKeySecret",
+        "executor": "is-agent",
+        "config": {
+          "baseUrl": "https://api.unipile.com/v2",
+          "auth": {
+            "in": "header",
+            "name": "X-API-KEY",
+            "prefix": ""
+          }
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "unipile_create_hosted_auth",
+        "intent": "connect_account",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Mints a Unipile hosted-auth link so a user can CONNECT a provider account (LinkedIn/Google/Telegram) — the account-onboarding primitive. Lets a product run its 'Connect' flow WITHOUT holding the Unipile key (it stays vaulted). Args: { providers: string[] (e.g. ['linkedin']), redirectUri: string, expiresOn?: string (ISO), state?: string, name?: string }. Returns { link }.",
+        "requires": [
+          "unipile_linkedin"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "providers": "array",
+          "redirectUri": "string",
+          "expiresOn": "string?",
+          "state": "string?",
+          "name": "string?"
+        },
+        "code": "// Mint a Unipile v2 hosted-auth link so a user can connect a provider account\n// (LinkedIn/Google/Telegram) WITHOUT the consuming product ever holding the\n// Unipile key — the key stays vaulted here and is injected server-side. This is\n// what lets the Arch's \"Connect LinkedIn\" flow run key-free. POST /v2/auth/link.\nconst providers = Array.isArray(args?.providers)\n  ? args.providers\n  : (args?.providers ? [String(args.providers)] : []);\nconst redirectUri = String(args?.redirectUri ?? '').trim();\nconst expiresOn = String(args?.expiresOn ?? '').trim();\nconst state = typeof args?.state === 'string' ? args.state : undefined;\nif (!providers.length) throw new Error('unipile_create_hosted_auth: providers is required');\nif (!redirectUri) throw new Error('unipile_create_hosted_auth: redirectUri is required');\n\nconst body = { providers, redirect_uri: redirectUri };\nif (expiresOn) body.expires_on = expiresOn;\nif (state) body.state = state;\nif (typeof args?.name === 'string' && args.name) body.name = args.name;\n\nconst res = await callProvider('unipile_linkedin', 'POST', '/auth/link', body);\nconst ok = res?.status ? res.status >= 200 && res.status < 300 : true;\nif (!ok) throw new Error(`unipile_create_hosted_auth: provider rejected (status ${res?.status ?? 'unknown'})`);\nconst payload = res?.body ?? res;\nreturn { link: payload?.link ?? payload?.url ?? null };\n",
+        "metadata": {
+          "verbType": "read"
+        }
+      },
+      {
+        "name": "unipile_get_account",
+        "intent": "fetch_record",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Fetches one connected account by id (v2 GET /accounts/{id}). Pure read — verify a just-connected account exists before persisting it. Args: { accountId: string }.",
+        "requires": [
+          "unipile_linkedin"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "accountId": "string"
+        },
+        "code": "// Fetch one connected account by id (v2 GET /accounts/{id}). Pure read — used to\n// verify a just-connected account materialized before the product persists it.\nconst accountId = String(args?.accountId ?? '').trim();\nif (!accountId) throw new Error('unipile_get_account: accountId is required');\nconst res = await callProvider('unipile_linkedin', 'GET', `/accounts/${encodeURIComponent(accountId)}`);\nreturn res?.body ?? res;\n"
+      },
+      {
+        "name": "unipile_list_accounts",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Lists every Unipile-connected account (LinkedIn, WhatsApp, Telegram, Instagram, Google, Outlook, IMAP) with its id, provider (lowercase: linkedin, instagram, whatsapp, telegram, google, outlook, imap), name and status. No args. Call this FIRST to discover which accountId to pass to the other skills. Read-only: the account source of the send verbs, so a pod app sees one action per account.",
+        "requires": [
+          "unipile_linkedin"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "metadata": {
+          "readOnly": true
+        },
+        "parameters": {},
+        "providerSpec": {
+          "tool": "unipile_linkedin",
+          "method": "GET",
+          "pathTemplate": "/accounts/",
+          "responseShape": {
+            "collectionPath": "data",
+            "collectionAs": "accounts",
+            "item": {
+              "id": "id",
+              "name": "name",
+              "provider": "provider",
+              "status": "status"
+            }
+          }
+        }
+      },
+      {
+        "name": "unipile_list_conversations",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Lists conversations (chats) for one connected account, any provider. Args: { accountId: string (from unipile_list_accounts), cursor?: string }. v2: account_id is a path segment.",
+        "requires": [
+          "unipile_linkedin"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "accountId": "string",
+          "cursor": "string?"
+        },
+        "providerSpec": {
+          "tool": "unipile_linkedin",
+          "method": "GET",
+          "pathTemplate": "/{{accountId}}/inboxes/CLASSIC_PRIMARY/chats",
+          "responseShape": {
+            "collectionPath": "data",
+            "collectionAs": "conversations",
+            "scalar": {
+              "cursor": "payload.next_cursor"
+            }
+          },
+          "query": {
+            "limit": "25",
+            "cursor": "{{cursor}}"
+          }
+        }
+      },
+      {
+        "name": "unipile_list_messages",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Lists the messages in one conversation thread. Args: { threadId: string (from unipile_list_conversations), accountId: string }. v2: both ids are path segments.",
+        "requires": [
+          "unipile_linkedin"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "threadId": "string",
+          "accountId": "string"
+        },
+        "providerSpec": {
+          "tool": "unipile_linkedin",
+          "method": "GET",
+          "pathTemplate": "/{{accountId}}/chats/{{threadId}}/messages",
+          "responseShape": {
+            "collectionPath": "data",
+            "collectionAs": "messages",
+            "scalar": {
+              "cursor": "payload.next_cursor"
+            }
+          },
+          "query": {
+            "limit": "25"
+          }
+        }
+      },
+      {
+        "name": "unipile_send_message",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Sends a message into an EXISTING conversation thread on any connected account (LinkedIn, WhatsApp, Telegram), then notes it (proposal-gated). Args: { threadId: string, accountId: string, text: string }. Not the send_message intent: a message to a person goes through the pod's send door (messaging.send), which files it in their channel; this verb stays an agent tool call.",
+        "requires": [
+          "unipile_linkedin"
+        ],
+        "executionMode": "async",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "threadId": "string",
+          "accountId": "string",
+          "text": "string"
+        },
+        "code": "// Send a message into an EXISTING chat, then record a note. Executor wraps this\n// body as (async function(args, context){ <code> }); use args directly and\n// `return`. callProvider runs the tool by NAME — the dispatcher injects the\n// vaulted X-API-KEY; propose.entity routes the write through governance.\n// v2: account_id is a PATH segment and the endpoint gained a /send suffix.\nconst threadId = String(args?.threadId ?? '').trim();\nconst accountId = String(args?.accountId ?? '').trim();\nconst text = String(args?.text ?? '').trim();\nif (!threadId) throw new Error('unipile_send_message: threadId is required');\nif (!accountId) throw new Error('unipile_send_message: accountId is required');\nif (!text) throw new Error('unipile_send_message: text is required');\n\nconst res = await callProvider('unipile_linkedin', 'POST', `/${encodeURIComponent(accountId)}/chats/${encodeURIComponent(threadId)}/messages/send`, { text });\nif (res?.proposed === true) {\n  return { success: false, proposed: true, proposalId: res?.proposalId ?? null, threadId };\n}\nconst ok = res?.status ? res.status >= 200 && res.status < 300 : true;\n// A non-2xx MUST throw. Returning { success:false } resolves the caller's\n// promise, so the Arch records the message as sent, consumes the account's daily\n// quota and marks the lead contacted — for a message the provider rejected.\nif (!ok) throw new Error(`unipile_send_message: provider rejected the send (status ${res?.status ?? 'unknown'}) for thread ${threadId}`);\nconst payload = res?.body ?? res;\nawait propose.entity({\n  profileSlug: 'note',\n  title: `Message sent in thread ${threadId}`,\n  properties: { action: 'unipile_send_message', threadId, accountId, text, messageId: payload?.message_id ?? null, status: res?.status ?? null, success: ok, provenance: 'connector', provider: 'unipile' },\n  reasoning: 'Recorded the outbound message for the activity timeline.'\n});\nreturn { success: ok, threadId, messageId: payload?.message_id ?? null, status: res?.status ?? null };\n"
+      },
+      {
+        "name": "unipile_start_chat",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Starts a 1to1 chat with one person on ANY connected account (LinkedIn, Instagram, WhatsApp, Telegram) and sends the first message, then notes it (proposal-gated). v2 POST /{account_id}/chats/send; LinkedIn goes through its CLASSIC_PRIMARY inbox (/inboxes/CLASSIC_PRIMARY/chats/send). On LinkedIn, a person you already talk to gets the message in that chat. Use unipile_send_message to answer in a chat you know. Args: { accountId: string (from unipile_list_accounts), attendeeId: string (the person's id on that provider: LinkedIn user id, Instagram messaging id, WhatsApp id), text: string, provider?: string (the account's provider; looked up when omitted) }. Returns { chatId, messageId }. Not the send_message intent: a message to a person goes through the pod's send door (messaging.send), which files it in their channel; this verb stays an agent tool call.",
+        "requires": [
+          "unipile_linkedin"
+        ],
+        "executionMode": "async",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "accountId": "string",
+          "attendeeId": "string",
+          "text": "string",
+          "provider": "string?"
+        },
+        "code": "// Start a 1to1 chat with one person on ANY connected account and send the\n// first message, then record a note. v2 (OpenAPI 2.62.0): POST\n// /{account_id}/chats/send, or for a provider that uses inboxes (LinkedIn\n// Classic: CLASSIC_PRIMARY, the only inbox allowed to initiate)\n// POST /{account_id}/inboxes/CLASSIC_PRIMARY/chats/send. users_ids is ONE\n// id as a string: an array, even of one id, asks for a group chat. Instagram\n// takes the person's messaging identifier. On LinkedIn, starting a chat with\n// someone you already talk to adds the message to that chat.\nconst accountId = String(args?.accountId ?? '').trim();\nconst attendeeId = String(args?.attendeeId ?? '').trim();\nconst text = String(args?.text ?? '').trim();\nlet provider = String(args?.provider ?? '').trim().toLowerCase();\nif (!accountId) throw new Error('unipile_start_chat: accountId is required — call unipile_list_accounts first to find it.');\nif (!attendeeId) throw new Error('unipile_start_chat: attendeeId (the person\\'s id on that provider) is required');\nif (!text) throw new Error('unipile_start_chat: text is required');\n\nconst account = encodeURIComponent(accountId);\nif (!provider) {\n  const acc = await callProvider('unipile_linkedin', 'GET', `/accounts/${account}`);\n  provider = String((acc?.body ?? acc)?.provider ?? '').toLowerCase();\n}\nconst path = provider === 'linkedin' ? `/${account}/inboxes/CLASSIC_PRIMARY/chats/send` : `/${account}/chats/send`;\nconst res = await callProvider('unipile_linkedin', 'POST', path, { text, users_ids: attendeeId });\nif (res?.proposed === true) {\n  return { success: false, proposed: true, proposalId: res?.proposalId ?? null, attendeeId };\n}\nconst ok = res?.status ? res.status >= 200 && res.status < 300 : true;\nif (!ok) throw new Error(`unipile_start_chat: provider rejected the send (status ${res?.status ?? 'unknown'}) for ${attendeeId}`);\nconst payload = res?.body ?? res;\nawait propose.entity({\n  profileSlug: 'note',\n  title: `Message sent -> ${attendeeId}`,\n  properties: { action: 'unipile_start_chat', attendeeId, accountId, provider: 'unipile', accountProvider: provider || null, text, chatId: payload?.chat_id ?? null, messageId: payload?.message_id ?? null, status: res?.status ?? null, success: ok, provenance: 'connector' },\n  reasoning: 'Recorded the opening outbound message for the activity timeline.'\n});\nreturn { success: ok, attendeeId, chatId: payload?.chat_id ?? null, messageId: payload?.message_id ?? null, status: res?.status ?? null };\n"
+      },
+      {
+        "name": "linkedin_capture_profiles",
+        "intent": "capture_into_pod",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Searches LinkedIn people via Unipile and PROPOSES each match as a person entity (proposal-gated). Use linkedin_search_people to read without persisting. Args: { keywords: string, accountId: string (from unipile_list_accounts), limit?: number, profileSlug?: string (default person) }.",
+        "requires": [
+          "unipile_linkedin"
+        ],
+        "executionMode": "async",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "keywords": "string",
+          "accountId": "string",
+          "limit": "number?",
+          "profileSlug": "string?"
+        },
+        "code": "// LinkedIn people search via Unipile, proposed as person entities. See\n// linkedin_search_people for the v2 endpoint shape; this variant PERSISTS each\n// match (so its name carries no read token -> classified `write` -> proposed).\nconst accountId = String(args?.accountId ?? '').trim();\nconst keywords = String(args?.keywords ?? '').trim();\nconst limit = Number(args?.limit ?? 10);\nif (!accountId) throw new Error('linkedin_capture_profiles: accountId is required — call unipile_list_accounts first to find yours, then pass it as accountId.');\nif (!keywords) throw new Error('linkedin_capture_profiles: keywords is required');\n\nconst qs = new URLSearchParams({ offset: '0', limit: String(limit) });\nconst res = await callProvider('unipile_linkedin', 'POST', `/${encodeURIComponent(accountId)}/linkedin/search/people?${qs.toString()}`, { keywords });\nconst payload = res?.body ?? res;\nconst items = Array.isArray(payload?.data) ? payload.data : (Array.isArray(payload) ? payload : []);\n\nconst profileSlug = String(args?.profileSlug ?? '').trim() || 'person';\nlet proposed = 0;\nfor (const p of items.slice(0, limit)) {\n  // v2 PeopleSearchResult: display_name, id (provider-native), public_identifier,\n  // headline, location, profile_url.\n  const name = String(p?.display_name ?? [p?.first_name, p?.last_name].filter(Boolean).join(' ') ?? 'LinkedIn profile').trim() || 'LinkedIn profile';\n  await propose.entity({\n    profileSlug,\n    title: name,\n    properties: {\n      headline: p?.headline ?? null,\n      location: p?.location ?? null,\n      linkedinProviderId: p?.id ?? null,\n      publicIdentifier: p?.public_identifier ?? null,\n      profileUrl: p?.profile_url ?? null,\n      provenance: 'connector', provider: 'unipile'\n    },\n    reasoning: `LinkedIn profile matched search \"${keywords}\" via Unipile.`\n  });\n  proposed += 1;\n}\nreturn { proposed, keywords };\n"
+      },
+      {
+        "name": "linkedin_send_invite",
+        "intent": "request_connection",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Sends a LinkedIn connection request (v2 relation-request) via Unipile, then notes it (proposal-gated). Takes their public identifier (profile URL slug) or member id and looks them up first; refuses someone already connected or with a request pending, and a note over 300 characters. Args: { providerId: string, accountId: string (from unipile_list_accounts), message?: string }.",
+        "requires": [
+          "unipile_linkedin"
+        ],
+        "executionMode": "async",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "providerId": "string",
+          "accountId": "string",
+          "message": "string?"
+        },
+        "inputMap": {
+          "params": {
+            "providerId": "$to.linkedin.publicIdentifier",
+            "accountId": "$account.id",
+            "message": "$.text"
+          },
+          "accounts": {
+            "verb": "unipile_list_accounts",
+            "id": "id",
+            "label": "name",
+            "provider": "provider"
+          }
+        },
+        "code": "// Send a LinkedIn connection request, then record a note. v2: invitations are\n// \"relation requests\" — POST /{account_id}/users/me/relation-requests, and the\n// target field is user_id (v1 provider_id). The `providerId` PARAM name is kept\n// so callers/transport don't change.\n// The person may be given by their public identifier (the slug of their profile\n// URL, what a pod app's `to` resolves to) or their member id: either is looked\n// up first (GET /{account}/users/{id}; the visit is not notified) for the member\n// id the request needs. Someone already connected, or with a request already\n// pending, is refused before anything is sent. LinkedIn caps the note at 300\n// characters, so a longer one is refused here rather than by LinkedIn.\nconst accountId = String(args?.accountId ?? '').trim();\nconst target = String(args?.providerId ?? '').trim();\nconst message = typeof args?.message === 'string' && args.message.trim() ? args.message.trim() : undefined;\nif (!accountId) throw new Error('linkedin_send_invite: accountId is required — call unipile_list_accounts first to find yours.');\nif (!target) throw new Error('linkedin_send_invite: providerId (their LinkedIn public identifier or member id) is required');\nif (message && message.length > 300) throw new Error(`linkedin_send_invite: a connection note is at most 300 characters on LinkedIn (this one is ${message.length}).`);\n\nconst account = encodeURIComponent(accountId);\nconst found = await callProvider('unipile_linkedin', 'GET', `/${account}/users/${encodeURIComponent(target)}?variant=linkedin_classic`);\nif (found?.proposed === true) {\n  return { success: false, proposed: true, proposalId: found?.proposalId ?? null, providerId: target };\n}\nif (found?.status && (found.status < 200 || found.status >= 300)) throw new Error(`linkedin_send_invite: LinkedIn has no profile for ${target} (status ${found.status}).`);\nconst profile = found?.body ?? found ?? {};\nconst userId = String(profile.provider_id ?? profile.id ?? '').trim();\nif (!userId) throw new Error(`linkedin_send_invite: LinkedIn gave no member id for ${target}.`);\nconst distance = String(profile.network_distance ?? profile.specifics?.linkedin?.network_distance ?? '').toUpperCase();\nconst name = [profile.first_name, profile.last_name].filter(Boolean).join(' ') || target;\nif (distance === 'FIRST_DEGREE' || distance === 'DISTANCE_1') throw new Error(`linkedin_send_invite: ${name} is already one of your LinkedIn connections: send them the message instead.`);\nconst invitation = profile.invitation ?? profile.specifics?.linkedin?.invitation ?? null;\nif (invitation && String(invitation.status ?? '').toUpperCase() === 'PENDING') throw new Error(`linkedin_send_invite: a connection request with ${name} is already pending.`);\n\nconst body = { user_id: userId };\nif (message) body.message = message;\nconst res = await callProvider('unipile_linkedin', 'POST', `/${account}/users/me/relation-requests`, body);\n// GOVERNANCE GUARD: a proposal-gated call returns { proposed:true } and has NOT\n// been sent — never record a not-sent invitation as sent.\nif (res?.proposed === true) {\n  return { success: false, proposed: true, proposalId: res?.proposalId ?? null, providerId: userId };\n}\n// v2 returns 201 on success.\nconst ok = res?.status ? res.status >= 200 && res.status < 300 : true;\nif (!ok) throw new Error(`linkedin_send_invite: provider rejected the invitation (status ${res?.status ?? 'unknown'}) for ${name}`);\nconst payload = res?.body ?? res;\nawait propose.entity({\n  profileSlug: 'note',\n  title: `LinkedIn invitation sent -> ${name}`,\n  properties: { action: 'linkedin_send_invite', providerId: userId, publicIdentifier: profile.public_identifier ?? null, networkDistance: distance || null, message: message ?? null, relationRequestId: payload?.id ?? null, status: res?.status ?? null, success: ok, provenance: 'connector', provider: 'unipile' },\n  reasoning: 'Recorded the outbound LinkedIn connection request for the activity timeline.'\n});\nreturn { success: ok, providerId: userId, relationRequestId: payload?.id ?? null, status: res?.status ?? null };"
+      },
+      {
+        "name": "linkedin_search_people",
+        "intent": "find_people",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Searches LinkedIn people via Unipile and RETURNS the matches inline. Pure read -> runs INSTANTLY (no approval). Use to qualify/enrich a lead in-flow; use linkedin_capture_profiles to persist. Args: { keywords: string, accountId: string (from unipile_list_accounts), limit?: number }.",
+        "requires": [
+          "unipile_linkedin"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "keywords": "string",
+          "accountId": "string",
+          "limit": "number?"
+        },
+        "code": "// Pure-read LinkedIn people search — returns raw v2 rows, writes NOTHING (keeps\n// it classified `read` -> governance `auto`, so an agent enriches a lead inline).\n// v2: search is split per resource (/linkedin/search/people); account_id is a\n// path segment; offset+limit are query params; filters go in the JSON body.\nconst accountId = String(args?.accountId ?? '').trim();\nconst keywords = String(args?.keywords ?? '').trim();\nconst limit = Number(args?.limit ?? 10);\nif (!accountId) throw new Error('linkedin_search_people: accountId is required — call unipile_list_accounts first to find yours.');\nif (!keywords) throw new Error('linkedin_search_people: keywords is required');\n\nconst qs = new URLSearchParams({ offset: '0', limit: String(limit) });\nconst res = await callProvider('unipile_linkedin', 'POST', `/${encodeURIComponent(accountId)}/linkedin/search/people?${qs.toString()}`, { keywords });\nconst payload = res?.body ?? res;\n// v2 envelope: { data: [...], total_count, next_cursor }.\nconst items = Array.isArray(payload?.data) ? payload.data : (Array.isArray(payload) ? payload : []);\nconst results = items.slice(0, limit);\nreturn { count: results.length, keywords, results };\n"
+      },
+      {
+        "name": "linkedin_get_profile",
+        "intent": "enrich_entity",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Fetches one full LinkedIn profile by user id or public identifier, sections expanded. Pure read -> runs instantly. The enrichment primitive. Args: { identifier: string, accountId: string (from unipile_list_accounts) }.",
+        "requires": [
+          "unipile_linkedin"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "identifier": "string",
+          "accountId": "string"
+        },
+        "code": "// Fetch a single LinkedIn profile. Pure read (GET, no propose.entity) -> the\n// catalog classifies it `read` -> governance `auto`, so enrichment runs inline.\n// v2: account_id is a path segment; sections use with_sections (was\n// linkedin_sections) with a linkedin_ prefix; variant selects the product API.\nconst accountId = String(args?.accountId ?? '').trim();\nconst identifier = String(args?.identifier ?? '').trim();\nif (!accountId) throw new Error('linkedin_get_profile: accountId is required — call unipile_list_accounts first to find yours.');\nif (!identifier) throw new Error('linkedin_get_profile: identifier (a LinkedIn provider_id or public identifier) is required');\n\nconst qs = new URLSearchParams({ variant: 'linkedin_classic' });\nqs.append('with_sections', 'linkedin_*');\nconst res = await callProvider('unipile_linkedin', 'GET', `/${encodeURIComponent(accountId)}/users/${encodeURIComponent(identifier)}?${qs.toString()}`);\n// Return the RAW v2 UserProfile. Note v2 renames: headline->description,\n// summary->bio, provider_id->id, and LinkedIn extras live under specifics.linkedin.\nreturn res?.body ?? res;\n"
+      },
+      {
+        "name": "linkedin_send_first_message",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Sends a LinkedIn message to one person: starts the conversation, or adds to the one you have. Takes their public identifier (profile URL slug) or member id, looks them up, and refuses anyone who is not a 1st-degree connection before sending. Proposal-gated. Args: { attendeeId: string, text: string, accountId: string (from unipile_list_accounts) }. Not the send_message intent: a message to a person goes through the pod's send door (messaging.send), which files it in their channel; this verb stays an agent tool call.",
+        "requires": [
+          "unipile_linkedin"
+        ],
+        "executionMode": "async",
+        "timeoutSeconds": 60,
+        "parameters": {
+          "attendeeId": "string",
+          "text": "string",
+          "accountId": "string"
+        },
+        "code": "// Send a LinkedIn message to one person: starts the conversation, or adds to the\n// one you already have with them (v2: LinkedIn is inbox-based and CLASSIC_PRIMARY\n// is the inbox allowed to initiate; users_ids is ONE id as a string, an array\n// asks Unipile for a group chat).\n// The recipient may be their public identifier (the slug of their profile URL,\n// what a pod app's `to` resolves to) or their LinkedIn member id. Either is\n// looked up first (GET /{account}/users/{id}; the visit is not notified), which\n// gives the member id the send needs and the network distance: LinkedIn lets you\n// message only your connections (InMail aside), so anyone else is refused BEFORE\n// anything is sent, with what to do instead. An unknown distance never blocks.\nconst accountId = String(args?.accountId ?? '').trim();\nconst attendee = String(args?.attendeeId ?? '').trim();\nconst text = String(args?.text ?? '').trim();\nif (!accountId) throw new Error('linkedin_send_first_message: accountId is required — call unipile_list_accounts first to find yours.');\nif (!attendee) throw new Error('linkedin_send_first_message: attendeeId (their LinkedIn public identifier or member id) is required');\nif (!text) throw new Error('linkedin_send_first_message: text is required');\n\nconst account = encodeURIComponent(accountId);\nconst found = await callProvider('unipile_linkedin', 'GET', `/${account}/users/${encodeURIComponent(attendee)}?variant=linkedin_classic`);\nif (found?.proposed === true) {\n  return { success: false, proposed: true, proposalId: found?.proposalId ?? null, attendeeId: attendee };\n}\nif (found?.status && (found.status < 200 || found.status >= 300)) throw new Error(`linkedin_send_first_message: LinkedIn has no profile for ${attendee} (status ${found.status}).`);\nconst profile = found?.body ?? found ?? {};\nconst memberId = String(profile.provider_id ?? profile.id ?? '').trim();\nif (!memberId) throw new Error(`linkedin_send_first_message: LinkedIn gave no member id for ${attendee}.`);\nconst distance = String(profile.network_distance ?? profile.specifics?.linkedin?.network_distance ?? '').toUpperCase();\nconst name = [profile.first_name, profile.last_name].filter(Boolean).join(' ') || attendee;\nif (['SECOND_DEGREE', 'THIRD_DEGREE', 'OUT_OF_NETWORK', 'DISTANCE_2', 'DISTANCE_3'].includes(distance)) {\n  throw new Error(`linkedin_send_first_message: ${name} is not one of your LinkedIn connections yet (${distance}). Send a connection request first, then the message once they accept.`);\n}\n\nconst res = await callProvider('unipile_linkedin', 'POST', `/${account}/inboxes/CLASSIC_PRIMARY/chats/send`, { text, users_ids: memberId });\nif (res?.proposed === true) {\n  return { success: false, proposed: true, proposalId: res?.proposalId ?? null, attendeeId: memberId };\n}\nconst ok = res?.status ? res.status >= 200 && res.status < 300 : true;\nif (!ok) throw new Error(`linkedin_send_first_message: provider rejected the send (status ${res?.status ?? 'unknown'}) for ${name}`);\nconst payload = res?.body ?? res;\nawait propose.entity({\n  profileSlug: 'note',\n  title: `LinkedIn message sent -> ${name}`,\n  properties: { action: 'linkedin_send_first_message', attendeeId: memberId, publicIdentifier: profile.public_identifier ?? null, networkDistance: distance || null, accountId, text, chatId: payload?.chat_id ?? null, status: res?.status ?? null, success: ok, provenance: 'connector', provider: 'unipile' },\n  reasoning: 'Recorded the outbound LinkedIn message for the activity timeline.'\n});\nreturn { success: ok, attendeeId: memberId, networkDistance: distance || null, chatId: payload?.chat_id ?? null, status: res?.status ?? null };"
+      },
+      {
+        "name": "linkedin_list_relations",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Lists the 1st-degree LinkedIn connections of a connected account, cursor-paginated. Read-only. Args: { accountId: string, cursor?: string }. v2: GET /{account_id}/users/me/relations.",
+        "requires": [
+          "unipile_linkedin"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "accountId": "string",
+          "cursor": "string?"
+        },
+        "providerSpec": {
+          "tool": "unipile_linkedin",
+          "method": "GET",
+          "pathTemplate": "/{{accountId}}/users/me/relations",
+          "responseShape": {
+            "collectionPath": "data",
+            "collectionAs": "relations",
+            "scalar": {
+              "cursor": "payload.next_cursor"
+            }
+          },
+          "query": {
+            "limit": "100",
+            "cursor": "{{cursor}}"
+          }
+        }
+      },
+      {
+        "name": "linkedin_list_invitations",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Lists SENT LinkedIn connection requests (v2 pending relation-requests). Diffing this over time is how you detect an accepted invitation. Read-only. Args: { accountId: string, cursor?: string }. v2 requires type=sent (hardcoded here).",
+        "requires": [
+          "unipile_linkedin"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "accountId": "string",
+          "cursor": "string?"
+        },
+        "providerSpec": {
+          "tool": "unipile_linkedin",
+          "method": "GET",
+          "pathTemplate": "/{{accountId}}/users/me/relation-requests",
+          "responseShape": {
+            "collectionPath": "data",
+            "collectionAs": "invitations",
+            "scalar": {
+              "cursor": "payload.next_cursor"
+            }
+          },
+          "query": {
+            "type": "sent",
+            "limit": "100",
+            "cursor": "{{cursor}}"
+          }
+        }
+      },
+      {
+        "name": "linkedin_list_company_pages",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Lists the LinkedIn company pages a connected LinkedIn account administers, with each page's id (what unipile_publish_post takes as postAs to post as that page) and name. Read-only. Args: { accountId: string }. v2: GET /{account_id}/linkedin/company/pages.",
+        "requires": [
+          "unipile_linkedin"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "metadata": {
+          "readOnly": true
+        },
+        "parameters": {
+          "accountId": "string"
+        },
+        "providerSpec": {
+          "tool": "unipile_linkedin",
+          "method": "GET",
+          "pathTemplate": "/{{accountId}}/linkedin/company/pages",
+          "responseShape": {
+            "collectionPath": "data",
+            "collectionAs": "pages",
+            "item": {
+              "id": "id",
+              "name": "name"
+            }
+          }
+        }
+      },
+      {
+        "name": "unipile_publish_post",
+        "intent": "publish_post",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Publishes a post now from one connected account (v2 POST /{account_id}/posts). Text alone is sent as JSON; with media (images or videos, pod files sent as bytes) a multipart form with one attachments[i] part per file. Unipile has no scheduling: the post goes out when the run is approved. LinkedIn takes text with or without media, may post as a company page the account administers (postAs, Unipile's post_as: a page id from linkedin_list_company_pages) and may repost a post (quotedPostId, Unipile's quoted_post_id: with no text a plain repost, with text a quote); Instagram needs at least one image or video and has neither; WhatsApp, Telegram and mail accounts have no posts and are refused. Args: { accountId: string (from unipile_list_accounts), text: string (may be empty for a plain repost), provider?: string, media?: pod file ids, postAs?: string, quotedPostId?: string }. Returns { postId, shareUrl, attachments }.",
+        "requires": [
+          "unipile_linkedin"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 120,
+        "metadata": {
+          "verbType": "write"
+        },
+        "parameters": {
+          "accountId": "string",
+          "text": "string",
+          "provider": "string?",
+          "media": "file[]:bytes?",
+          "postAs": "string?",
+          "quotedPostId": "string?"
+        },
+        "inputMap": {
+          "params": {
+            "text": "$.text",
+            "accountId": "$account.id",
+            "provider": "$account.provider",
+            "media": "$.media"
+          },
+          "accounts": {
+            "verb": "unipile_list_accounts",
+            "id": "id",
+            "label": "name",
+            "provider": "provider"
+          }
+        },
+        "code": "// Publish a post now from one connected account (v2 POST /{account_id}/posts).\n// Text alone goes as JSON. With media, a multipart form: `media` is\n// `file[]:bytes`, so this code holds one handle per pod file and the pod\n// streams the bytes into each `attachments[i]` part (Unipile's field naming\n// for files). Unipile has no scheduling: the post goes out when the run is\n// approved. A non-2xx throws, so a refused post is never reported as sent.\n// LinkedIn only: `postAs` posts as a company page the account administers\n// (Unipile's post_as), `quotedPostId` reposts that post (quoted_post_id; with\n// no text a plain repost, with text a quote). Both are left out when empty.\nconst accountId = String(args?.accountId ?? '').trim();\nconst text = String(args?.text ?? '').trim();\nconst provider = String(args?.provider ?? '').trim().toLowerCase();\nconst media = Array.isArray(args?.media) ? args.media : (args?.media ? [args.media] : []);\nconst postAs = String(args?.postAs ?? '').trim();\nconst quotedPostId = String(args?.quotedPostId ?? '').trim();\nif (!accountId) throw new Error('unipile_publish_post: accountId is required (from unipile_list_accounts)');\nif (!text && !quotedPostId) throw new Error('unipile_publish_post: text is required');\nif (provider && provider !== 'linkedin' && provider !== 'instagram') {\n  throw new Error(`unipile_publish_post: a ${provider} account has no posts; publish from a LinkedIn or Instagram account`);\n}\nif (provider === 'instagram' && (postAs || quotedPostId)) {\n  throw new Error('unipile_publish_post: Instagram has no company page post or repost; send the post itself');\n}\nif (provider === 'instagram' && media.length === 0) {\n  throw new Error('unipile_publish_post: Instagram needs at least one image or video in media');\n}\n\nconst fields = { text };\nif (postAs) fields.post_as = postAs;\nif (quotedPostId) fields.quoted_post_id = quotedPostId;\nconst path = `/${encodeURIComponent(accountId)}/posts`;\nlet res;\nif (media.length > 0) {\n  const form = { ...fields };\n  media.forEach((file, n) => { form[`attachments[${n}]`] = file; });\n  res = await callProvider('unipile_linkedin', 'POST', path, form, { multipart: true });\n} else {\n  res = await callProvider('unipile_linkedin', 'POST', path, fields);\n}\nif (res?.proposed === true) {\n  return { success: false, proposed: true, proposalId: res?.proposalId ?? null };\n}\nconst ok = res?.status ? res.status >= 200 && res.status < 300 : true;\nif (!ok) throw new Error(`unipile_publish_post: provider rejected the post (status ${res?.status ?? 'unknown'})`);\nconst payload = res?.body ?? res;\nreturn { postId: payload?.id ?? null, shareUrl: payload?.share_url ?? null, attachments: media.length };\n"
+      }
+    ],
+    "provides": [
+      "connect_account",
+      "fetch_record",
+      "list_records",
+      "capture_into_pod",
+      "request_connection",
+      "find_people",
+      "enrich_entity",
+      "publish_post"
+    ]
+  },
+  "dependencies": []
+}