@audienti/cli 0.2.0-exora.3 → 0.2.0-exora.5

package/README.md

@@ -1,11 +1,11 @@
 # Audienti CLI for Exora
 
-Use Node 24. This release connects agents to **https://exo.audienti.com**.
+Use Node 24. This release connects agents to **https://app.audienti.com**.
 The `exora` npm tag selects this client; the legacy `latest` tag is unchanged.
 
 ```sh
 npm install -g @audienti/cli@exora
-export AUDIENTI_API_URL=https://exo.audienti.com/api/v1
+export AUDIENTI_API_URL=https://api.audienti.com/api/v1
 audienti agent connect --name "My agent" --profile "$HOME/.audienti/exo-agent.json"
 ```
 

package/cli/account-reply-operations.mjs

@@ -5,6 +5,24 @@ const item = { ...scope, evidenceId: uuid };
 const status = z.enum(['needs_handling', 'handled', 'not_reply']);
 const outcome = z.enum(['response_recorded', 'closed_without_response', 'suppressed']);
 const limit = z.number().int().min(1).max(100);
+const classification = z.enum(['interested', 'question', 'later', 'out_of_office', 'stop', 'bounce', 'referral']);
+const slot = z.object({ start: z.string().describe('UTC start, ending in Z.'), end: z.string().describe('UTC end, ending in Z.'), timeZone: z.string().describe("The user's IANA time zone, for display.") }).strict();
+const draft = z.object({
+  type: z.enum(['email.send', 'linkedin.send']),
+  content: z.record(z.string(), z.unknown()).describe('Email: { subject, body }. LinkedIn: { body }.'),
+  recipient: z.record(z.string(), z.unknown()).describe('Email: { prospectId, email, contactId? }. LinkedIn: { prospectId, profileUrl, contactId? }. Bind contactId and senderAccountId, or the answer waits in Blocked.'),
+  sender: z.record(z.string(), z.unknown()).describe("{ provider, accountRef, senderAccountId? }: the assignee's mailbox or LinkedIn account the inbound came to."),
+  reason: z.string().describe('Why this answer, in one or two sentences.'),
+  slots: z.array(slot).min(1).max(6).optional().describe('Free times from your calendar tool that the answer offers. Leave out without a calendar; the answer then asks for a time.'),
+  skill: z.object({ id: z.string(), version: z.string() }).strict().optional(),
+}).strict();
+// Brief 12: what a stop, bounce or referral means, as a typed detail next to the classification it matches.
+const quote = z.string().meta({ minLength: 1, maxLength: 500 }).describe("The prospect's words, verbatim.");
+const result = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('email.bounce'), address: z.string().meta({ minLength: 3, maxLength: 320 }).describe('The address that bounced.'), kind: z.enum(['hard', 'soft']).describe('hard: the address does not exist or refuses mail. soft: a full mailbox or a temporary failure.'), evidence: z.string().meta({ minLength: 1, maxLength: 2000 }).describe('The bounce message, its status code and diagnostic.') }).strict().describe('Classification bounce. A hard bounce, or a second bounce, marks the address bounced and blocks it in every campaign.'),
+  z.object({ type: z.literal('reply.stop'), scope: z.enum(['person', 'company']).describe('company only when the prospect asked to stop for their whole company.'), quote }).strict().describe('Classification stop, with status handled and outcome suppressed. The person, or everyone at the company, is suppressed for good.'),
+  z.object({ type: z.literal('reply.referral'), name: z.string().meta({ minLength: 1, maxLength: 200 }).describe('The person the prospect named.'), title: z.string().meta({ maxLength: 200 }).optional(), email: z.string().meta({ maxLength: 320 }).optional(), linkedinUrl: z.string().meta({ maxLength: 500 }).optional(), quote }).strict().describe('Classification referral, with status needs_handling and the thank-you as the draft. The named person is checked against the audience before any contact.'),
+]);
 const root = a => `/workspaces/${a.workspaceId}/prospects/${a.prospectId}`;
 const detail = a => `${root(a)}/conversation-evidence/${a.evidenceId}/reply`;
 const query = (path, a, keys) => {
@@ -15,7 +33,12 @@ const query = (path, a, keys) => {
 export const accountReplyOperations = {
   workspace_reply_set: {
     schema: z.object({ ...item, requestId: uuid, expectedVersion: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER), status,
-      outcome: outcome.nullable().describe("Null for needs_handling/not_reply; a handling outcome is required for handled."), reason: z.string().meta({ minLength: 1, maxLength: 2000 }).describe("Required trimmed NFC reason, 1–2000 codepoints. Interior control characters including newline and tab are rejected."), responseEvidenceId: uuid.nullable().describe("Required for response_recorded; null otherwise. Must identify matching outbound account evidence.") }).strict().describe("Explicit inbound classification. needs_handling/not_reply require null outcome and responseEvidenceId. handled requires an outcome; response_recorded requires matching outbound evidence, closed_without_response an explicit closure reason, and suppressed active DNC or Reject."),
+      outcome: outcome.nullable().describe("Null for needs_handling/not_reply; a handling outcome is required for handled."), reason: z.string().meta({ minLength: 1, maxLength: 2000 }).describe("Required trimmed NFC reason, 1–2000 codepoints. Interior control characters including newline and tab are rejected."), responseEvidenceId: uuid.nullable().describe("Required for response_recorded; null otherwise. Must identify matching outbound account evidence."),
+      classification: classification.optional().describe("What the reply is. Records a replied event on the person's active campaigns, except for bounce and out_of_office."),
+      invite: z.literal(true).optional().describe("The prospect sent a calendar invite you have not processed yet. Requires a classification; a meetings.confirm task follows."),
+      draft: draft.optional().describe("Your drafted answer. Saved as a reply plan revision the user reviews in Operator; requires status needs_handling. Never sent until approved."),
+      result: result.optional().describe("Brief 12: the typed detail for a bounce, stop or referral. Its type must match the classification."),
+      meeting: z.object({ at: z.string().datetime(), source: z.enum(['sent_invite', 'received_invite']) }).strict().optional().describe("A booked meeting: when, and whether the user's calendar sent the invite or the prospect did. Records meeting_booked.") }).strict().describe("Explicit inbound classification. needs_handling/not_reply require null outcome and responseEvidenceId. handled requires an outcome; response_recorded requires matching outbound evidence, closed_without_response an explicit closure reason, and suppressed active DNC or Reject."),
     method: 'POST', scoped: true, path: detail,
     body: ({ workspaceId, prospectId, evidenceId, ...rest }) => rest,
   },

package/cli/agents.mjs

@@ -4,9 +4,18 @@ import {readJsonFile} from './json-file.mjs';
 
 export const agentManagementOperations = ['agent_list','agent_revoke','agent_permission','agent_capabilities_set','agent_capabilities_get','agent_inventory_get','agent_capability_sharing_get','agent_capability_sharing_set','agent_account_authorizations_get','agent_account_authorization_set'];
 const inventoryLabel=z.string().trim().min(1).max(80);
+// Capability rows (ADR 015). The server checks ids, providers and access against the catalog; the client checks the shape.
+const capabilityRow=z.object({capability:z.string().min(1).max(64),provider:z.string().min(1).max(32).optional(),via:z.string().min(1).max(140),account:z.string().min(1).max(200).optional(),access:z.enum(['read','write','send']),cost:z.enum(['owner','credits']).optional(),status:z.enum(['connected','needs_sign_in','unavailable']),limits:z.object({daily:z.number().int().min(0).max(100000).optional(),hourly:z.number().int().min(0).max(100000).optional()}).strict().optional(),identity:z.object({namespace:z.string().min(1).max(64),accountId:z.string().min(1).max(256)}).strict().optional()}).strict();
+// A LinkedIn seat's cadence, InMail and safe limits (brief 09); the server checks the bounds.
+const seatLimit=z.number().int().min(0).max(100000);
+const seatFacts={checkEverySeconds:z.number().int().min(3600).max(604800).optional(),inmail:z.object({available:z.boolean(),quotaPerMonth:seatLimit.optional()}).strict().optional(),limits:z.object({connectionRequestsPerDay:seatLimit.optional(),connectionRequestsPerWeek:seatLimit.optional(),messagesPerDay:seatLimit.optional(),inmailPerMonth:seatLimit.optional()}).strict().optional()};
+const accountEntry=z.object({capability:z.string(),tools:z.array(z.string()).min(1).max(8)}).strict();
+const accountReport=z.object({provider:z.enum(['email','linkedin']),accountRef:z.string().min(1).max(200),status:z.enum(['healthy','unavailable','disconnected']),accountIdentity:z.object({namespace:z.string(),accountId:z.string()}).strict().optional(),capabilities:z.array(accountEntry).max(16),...seatFacts}).strict();
+const capabilityReport=z.object({runtime:z.object({name:z.string().trim().min(1).max(80),model:z.string().trim().min(1).max(80).optional()}).strict(),capabilities:z.array(capabilityRow).max(64),seats:z.array(z.object({provider:z.literal('linkedin'),account:z.string().min(1).max(200),...seatFacts}).strict()).max(50).optional()}).strict();
+const eitherReport=z.union([capabilityReport,accountReport]);
 const inventoryEntry=z.object({category:z.enum(['web_search','web_browse','people_data','company_data','email','linkedin','social','crm','spreadsheet','docs','chat','calendar','tasks','files','code','scheduling','memory','other']),name:inventoryLabel,access:z.array(z.enum(['read','write','send'])).min(1).max(3),status:z.enum(['connected','needs_sign_in','unavailable']),via:inventoryLabel.optional(),tools:z.array(z.string().min(1).max(128)).max(16).optional()}).strict();
 export const agentOperations = {
- agent_inventory_report:{description:'Getting started step 2: report the tools and connectors this agent already has (search, mailboxes, CRM, sheets, chat, scheduling, memory). Replaces the whole inventory. List only what is already available; never connect anything new and never include credentials. Requires an active agent profile.',schema:z.object({runtime:z.object({name:inventoryLabel,model:inventoryLabel.optional()}).strict(),entries:z.array(inventoryEntry).max(64)}).strict()},
+ agent_inventory_report:{description:'Older shape, kept for one release; use agent_capabilities_report instead. Reports the tools and connectors this agent already has (search, mailboxes, CRM, sheets, chat, scheduling, memory). Replaces the whole inventory. List only what is already available; never connect anything new and never include credentials. Requires an active agent profile.',schema:z.object({runtime:z.object({name:inventoryLabel,model:inventoryLabel.optional()}).strict(),entries:z.array(inventoryEntry).max(64)}).strict()},
  agent_inventory_show:{description:'Read this agent\u2019s own reported tool inventory. Requires an active agent profile.',schema:z.object({}).strict()},
  agent_inventory_get:{schema:z.object({id:z.string().uuid()}).strict()},
  agent_account_authorizations_get:{schema:z.object({id:z.string().uuid()}).strict()},
@@ -14,7 +23,9 @@ export const agentOperations = {
  agent_account_authorization_set:{schema:z.object({id:z.string().uuid(),provider:z.enum(['email','linkedin']),accountRef:z.string().min(1).max(200),authorized:z.boolean()}).strict()},
  agent_capability_sharing_get: {schema:z.object({id:z.string().uuid()}).strict()},
  agent_capability_sharing_set: {schema:z.object({id:z.string().uuid(),provider:z.enum(['email','linkedin']),accountRef:z.string().min(1).max(200),workspaceId:z.string().uuid(),shared:z.boolean()}).strict()},
- agent_capabilities_report: {schema:z.object({provider:z.enum(['email','linkedin']),accountRef:z.string().min(1).max(200),status:z.enum(['healthy','unavailable','disconnected']),accountIdentity:z.object({namespace:z.string(),accountId:z.string()}).strict().optional(),capabilities:z.array(z.object({capability:z.string(),tools:z.array(z.string()).min(1).max(8)}).strict()).max(16)}).strict()},
+ // One object schema for MCP clients; callAgent then requires exactly one of the two report shapes.
+ agent_capabilities_report: {description:'Getting started step 2: report what this agent can do as capability rows ({ runtime, capabilities: [{ capability, provider?, via, account?, access, cost?, status, limits?, identity? }], seats?: [{ provider: "linkedin", account, checkEverySeconds?, inmail?, limits? }] }), ids from the capability catalog. A LinkedIn account sends only when its rows carry identity { namespace: "linkedin", accountId: the member id }; a mailbox without one is matched by its address. Replaces the previous report. The old per-account shape (provider, accountRef, status, capabilities) is still accepted. Never use via "audienti" and never include credentials. Requires an active agent profile.',schema:z.object({runtime:capabilityReport.shape.runtime.optional(),provider:accountReport.shape.provider.optional(),accountRef:accountReport.shape.accountRef.optional(),status:accountReport.shape.status.optional(),accountIdentity:accountReport.shape.accountIdentity,capabilities:z.array(z.union([capabilityRow,accountEntry])).max(64),seats:capabilityReport.shape.seats,...seatFacts}).strict(),shape:eitherReport},
+ agent_capabilities_list: {description:'Read what this agent can do now: its own capability rows plus Audienti hosted rows for the workspace (when the workspace has credits and the user approved the group). Uses the profile workspace unless workspaceId is given. Requires an active agent profile.',schema:z.object({workspaceId:z.string().uuid().optional()}).strict()},
  agent_capabilities_show: {schema:z.object({}).strict()},
  agent_capabilities_get: {schema:z.object({id:z.string().uuid()}).strict()},
  agent_permission: {schema:z.object({id:z.string().uuid(),scope:z.enum(['workspace:read','workspace:access'])}).strict()},
@@ -33,14 +44,17 @@ async function request(config, path, body, authenticated = false, method = body
  let result; try { result = await response.json(); } catch { throw new Error('The API returned an invalid response.'); }
  if (!response.ok) {
   const code = typeof result?.error?.code === 'string' && /^[a-z_]+$/.test(result.error.code) ? result.error.code : 'request_failed';
-  throw new WorkspaceRequestError(response.status, code, `Agent request failed: ${code} (HTTP ${response.status}).`);
+  // A refused report says why (ADR 015), with the same safety checks as the workspace client.
+  const message = result?.error?.message;
+  const detail = response.status === 400 && (code === 'validation_error' || code === 'hosted_via_reserved') && typeof message === 'string' && message.length <= 300 && !/[\u0000-\u001f\u007f]/.test(message) && !(config.token && message.includes(config.token)) ? ` ${message}` : '';
+  throw new WorkspaceRequestError(response.status, code, `Agent request failed: ${code} (HTTP ${response.status}).${detail}`);
  }
  if (!result || !Object.hasOwn(result, 'data')) throw new Error('The API returned an invalid response.');
  return result.data;
 }
 export async function callAgent(name, args, config, profilePath) {
  const input = agentOperations[name]?.schema.safeParse(args);
- if (!input?.success) throw new Error('Invalid agent command or arguments.');
+ if (!input?.success || (agentOperations[name].shape && !agentOperations[name].shape.safeParse(args).success)) throw new Error('Invalid agent command or arguments.');
  if (agentManagementOperations.includes(name) && (config.profile?.agent || config.profile?.pendingAgent)) throw new Error('Use a separate user management profile with an agents:manage token.');
  if(name==='agent_account_authorizations_get') return {data:await request(config,`/agents/${input.data.id}/account-authorizations`,undefined,true)};
  if(name==='agent_account_authorization_set') {const {id,...body}=input.data;return {data:await request(config,`/agents/${id}/account-authorizations`,body,true)};}
@@ -56,6 +70,11 @@ export async function callAgent(name, args, config, profilePath) {
   return {data:await request(config,'/agent-inventory',name==='agent_inventory_report' ? input.data : undefined,true,name==='agent_inventory_report' ? 'PUT' : 'GET')};
  }
  if (name === 'agent_capabilities_get') return {data:await request(config,`/agents/${input.data.id}/capabilities`,undefined,true)};
+ if (name === 'agent_capabilities_list') {
+  if (!config.profile?.agent || !/^agt_/.test(config.token ?? '')) throw new Error('Use an active agent profile for capability check-in and self readback.');
+  const workspaceId = input.data.workspaceId ?? config.workspaceId;
+  return {data:await request(config,`/agent-capabilities${workspaceId ? `?workspaceId=${encodeURIComponent(workspaceId)}` : ''}`,undefined,true)};
+ }
  if (name === 'agent_capabilities_show' || name === 'agent_capabilities_report') {
   if (!config.profile?.agent || !/^agt_/.test(config.token ?? '')) throw new Error('Use an active agent profile for capability check-in and self readback.');
   return {data:await request(config,'/agent-capabilities',name==='agent_capabilities_report' ? input.data : undefined,true,name==='agent_capabilities_report' ? 'PUT' : 'GET')};
@@ -76,7 +95,7 @@ export async function callAgent(name, args, config, profilePath) {
   if (!/^adc_[A-Za-z0-9_-]{43}$/.test(data.secret) || !/^agt_[A-Za-z0-9_-]{43}$/.test(data.credential) || !z.string().uuid().safeParse(data.id).success || !/^[A-F0-9]{4}-[A-F0-9]{4}$/.test(data.code)) throw new Error('Invalid connection response.');
   writeProfile(profilePath, { ...profile, url, pendingAgent: { id: data.id, secret: data.secret, credential: data.credential, expiresAt: data.expiresAt } });
   config.token = undefined; config.workspaceId = undefined;
-  return { data: { status: 'pending', id: data.id, code: data.code, approvalUrl: data.approvalUrl, approvalPath: `/agents/connect/${data.id}`, expiresAt: data.expiresAt, interval: 5, instructions: 'Open the approval URL, sign in, enter the matching code and approve. Then run agent poll with this profile.' } };
+  return { data: { status: 'pending', id: data.id, code: data.code, approvalUrl: data.approvalUrl, approvalPath: `/agents/connect/${data.id}`, expiresAt: data.expiresAt, interval: 5, instructions: 'Give your user the approval URL and the code, then run agent poll with this profile every interval seconds, in this same turn and without waiting for them to reply, until the status is active, denied or expired.' } };
  }
  const secret = profile.pendingAgent?.secret ?? profile.connectionSecret;
  if (!secret) throw new Error('No connection in this profile.');
@@ -90,9 +109,9 @@ export async function callAgent(name, args, config, profilePath) {
  return { data };
 }
 export async function agentCli(args) {
- const flags = {}; const positions = [];
+ const flags = {}; const positions = []; let json = false;
  for (let i = 0; i < args.length; i++) {
-  if (args[i] === '--json') continue;
+  if (args[i] === '--json') { json = true; continue; }
   if (args[i].startsWith('--')) {
    const key = args[i].slice(2);
    if (!['profile', 'name','capabilities','scope','file','id','provider','account','workspace','shared','authorized','set'].includes(key) || !args[i+1] || args[i+1].startsWith('--')) throw new Error('Unknown or incomplete agent option.');
@@ -107,7 +126,7 @@ export async function agentCli(args) {
   else throw new Error('Use agent accounts show [--id ID] or authorize --id ID --provider PROVIDER --account REF --authorized true|false.');
  }
  if (positions[1] === 'inventory') {
-  if (positions[2] === 'report' && flags.file && !flags.id) {name='agent_inventory_report';input=readJsonFile(flags.file,32768,'Inventory file');}
+  if (positions[2] === 'report' && flags.file && !flags.id) {name='agent_inventory_report';input=readJsonFile(flags.file,32768,'Inventory file');console.error('Notice: agent capabilities report --file PATH is the current command; inventory reports are translated into capability rows.');}
   else if (positions[2] === 'show' && !flags.file) {name=flags.id ? 'agent_inventory_get' : 'agent_inventory_show';input=flags.id ? {id:flags.id} : {};}
   else throw new Error('Use agent inventory report --file PATH or show [--id ID].');
  }
@@ -117,9 +136,22 @@ export async function agentCli(args) {
   else if (positions[2] === 'share' && flags.id && ['true','false'].includes(flags.shared)) {name='agent_capability_sharing_set';input={id:flags.id,provider:flags.provider,accountRef:flags.account,workspaceId:flags.workspace,shared:flags.shared==='true'};}
   else if (positions[2] === 'report'  && flags.file && !flags.id) {name='agent_capabilities_report';input=readCapabilityFile(flags.file);}
   else if (positions[2] === 'show' && !flags.file) {name=flags.id ? 'agent_capabilities_get' : 'agent_capabilities_show';input=flags.id ? {id:flags.id} : {};}
-  else throw new Error('Use agent capabilities report --file PATH or show [--id ID].');
+  else if (positions[2] === undefined && !flags.file && !flags.id) {name='agent_capabilities_list';input=flags.workspace ? {workspaceId:flags.workspace} : {};}
+  else throw new Error('Use agent capabilities [--workspace ID] [--json], report --file PATH or show [--id ID].');
  }
- console.log(JSON.stringify(await callAgent(name, input, configuration(flags.profile, agentManagementOperations.includes(name) ? 'agents:manage' : 'workspace:access'), flags.profile)));
+ const result = await callAgent(name, input, configuration(flags.profile, agentManagementOperations.includes(name) ? 'agents:manage' : 'workspace:access'), flags.profile);
+ console.log(name === 'agent_capabilities_list' && !json ? capabilityText(result.data) : JSON.stringify(result));
+}
+
+/** Plain text for agent capabilities: own rows that work now, then rows that work with Audienti hosted tools. */
+export function capabilityText(data) {
+ const rows = Array.isArray(data?.effective) ? data.effective : [];
+ const line = row => `  ${row.capability}${row.provider ? ` (${row.provider})` : ''} via ${row.via}${row.account ? `, account ${row.account}` : ''}${row.status === 'connected' ? '' : `, ${row.status.replaceAll('_', ' ')}`}${row.hostedTool ? `, ${row.hostedTool.id}${row.hostedTool.credits === undefined ? '' : ` about ${row.hostedTool.credits} credits a call`}` : ''}${row.stale ? ', stale' : ''}`;
+ const own = rows.filter(row => row.via !== 'audienti'), hosted = rows.filter(row => row.via === 'audienti');
+ return [
+  `Works now${data?.stale ? ' (report is over seven days old; report again)' : ''}:`, ...(own.length ? own.map(line) : ['  nothing reported yet: audienti agent capabilities report --file CAPABILITIES.json']),
+  'Works with Audienti tools:', ...(hosted.length ? hosted.map(line) : [data?.workspaceId ? '  none: the workspace has no credits or the user has not approved these groups' : '  pick a workspace to see them: --workspace ID']),
+ ].join('\n');
 }
 
 function readCapabilityFile(path) {return readJsonFile(path,32768,'Capability file');}

package/cli/audience-operations.mjs

@@ -13,7 +13,7 @@ export const audienceOperations={
  audience_update:{schema:z.object({...locator,expectedRevision:z.number().int(),fields}).strict(),method:'POST',path:a=>path(a)+`/${a.audienceId}/revisions`,body:a=>({expectedRevision:a.expectedRevision,fields:a.fields}),scoped:true},
  audience_archive:{schema:z.object(locator).strict(),method:'POST',path:a=>path(a)+`/${a.audienceId}/archive`,scoped:true},
  audience_restore:{schema:z.object(locator).strict(),method:'POST',path:a=>path(a)+`/${a.audienceId}/restore`,scoped:true},
- audience_summary:{schema:z.object({...workspace,audienceId:uuid.optional()}).strict(),method:'GET',path:a=>`/workspaces/${a.workspaceId}/audience-summary`+(a.audienceId?`?audienceId=${a.audienceId}`:''),scoped:true,description:'Counts of active and archived Audiences, the campaigns using each (with people, engaged and at-goal counts), and people found per Audience (recent means admitted in the last 7 days).'},
+ audience_summary:{schema:z.object({...workspace,audienceId:uuid.optional()}).strict(),method:'GET',path:a=>`/workspaces/${a.workspaceId}/audience-summary`+(a.audienceId?`?audienceId=${a.audienceId}`:''),scoped:true,description:'Counts of active and archived Audiences, the campaigns using each (with people, engaged and at-goal counts), and people found per Audience (recent means admitted in the last 7 days). With audienceId, sizes gives that Audience\'s approximate reachable size against the 1,000-person minimum (null when it cannot be estimated; sizePending while the estimate runs).'},
  audience_people:{schema:z.object(locator).strict(),method:'GET',path:a=>path(a)+`/${a.audienceId}/people`,scoped:true,description:'People found by any campaign on this Audience, newest first, at most 100, with their latest participation.'},
  audience_companies:{schema:z.object(locator).strict(),method:'GET',path:a=>path(a)+`/${a.audienceId}/companies`,scoped:true,description:'Companies where this Audience has found people, most people first, at most 100; withoutCompany counts people with no company.'},
  audience_fit_check_improve:{schema:z.object({...workspace,text:z.string().trim().min(1).max(5000)}).strict(),method:'POST',path:a=>`/workspaces/${a.workspaceId}/audience-fit-checks`,body:a=>({text:a.text}),scoped:true,description:'Review a smart rule (gut check) and suggest a clearer rewrite a reviewer can judge from a profile. Returns whether it is usable, what counts as a match and a contradiction, and the rewrite. Saves nothing.'},

package/cli/audienti.mjs

@@ -3,9 +3,10 @@ import { isAssignmentCommand, assignmentCli } from './assignment.mjs';
 // The CLI is an HTTP client. It has no database access or separate business rules.
 const args = process.argv.slice(2);
 const usage = `Profiles: audienti profiles list|search|get ID | match evaluate|apply SOURCE CANDIDATE | history RESOLUTION (saved workspace records)
-Skills: audienti skills list|show audienti|helper NAME --file INPUT.json|- [--json]
-Tools: audienti tools list|describe|decide|runs|balance [--help]
+Skills: audienti skills list [--compact]|show SKILL|read SKILL RESOURCE|helper NAME --file INPUT.json|- [--json]
+Tools: audienti call TOOL ['JSON'] | tools search "WORDS"|get TOOL|list|runs|balance [--help]
 Sender: audienti sender accounts list|get|alias|register|bind|unbind|state|automation|activity report [--profile PATH]
+Managed LinkedIn: audienti sender managed list|connect [--profile PATH] (connect: the user only; returns a sign-in link)
 Prospecting: audienti prospecting settings show|save|accounts|account-show|account-save|history [--profile PATH]
 Usage: audienti whoami [--json]
        audienti workspace assignments list [--workspace ID]
@@ -26,58 +27,66 @@ Use HTTPS for remote hosts. Local HTTP is supported on loopback only.
 Agent commands: agent connect --name NAME [--capabilities find,enrich,listen,approve]|poll|cancel|list|revoke ID --profile PATH
 Owner permission change: agent permission ID --scope workspace:read|workspace:access --profile USER_PROFILE
 Owner capability change: agent capabilities ID --set find,enrich,listen,approve --profile USER_PROFILE (agents are refused outside this set)
-Agent capabilities: agent capabilities report --file REPORT.json --profile AGENT_PROFILE
+Agent capabilities: agent capabilities report --file CAPABILITIES.json --profile AGENT_PROFILE (capability rows; the old per-account shape still works)
+What the agent can do: agent capabilities [--workspace ID] [--json] --profile AGENT_PROFILE (works now, and works with Audienti tools)
 Read capabilities: agent capabilities show [--id AGENT_ID] --profile PROFILE
-Getting started: skills show getting-started, then agent inventory report --file INVENTORY.json --profile AGENT_PROFILE
-Read tool inventory: agent inventory show [--id AGENT_ID] --profile PROFILE
+Getting started: skills show getting-started, then agent capabilities report --file CAPABILITIES.json --profile AGENT_PROFILE
+Read tool inventory: agent inventory show [--id AGENT_ID] --profile PROFILE (agent inventory report still works; capabilities report is current)
 Account authorization: agent accounts show [--id AGENT_ID] --profile PROFILE
 Authorize/revoke: agent accounts authorize --id AGENT_ID --provider email|linkedin --account REF --authorized true|false --profile OWNER_PROFILE
 Sharing: agent capabilities sharing --id AGENT_ID --profile OWNER_PROFILE
 Share/unshare: agent capabilities share --id AGENT_ID --provider email|linkedin --account REF --workspace ID --shared true|false --profile OWNER_PROFILE
 Team member: workspace member USER_ID [--workspace ID] --profile PROFILE
-Work execution: work execution claim|start|get PLAN --action ID; release|lookup --claim ID; report --attempt ID
+Work execution: work execution claim|start|send|get PLAN --action ID (send: managed LinkedIn accounts, --file with claimId and requestId); release|lookup --claim ID; report --attempt ID
 Work feedback: work changes request|list|get|respond|withdraw PLAN --workspace ID
-Work: work plan save|list|show|approve|withdraw-approval|cancel|eligibility
+Work: work plan save|list|show|approve|withdraw-approval|cancel|skip|eligibility
 Activity: work activity --workspace ID [--search TEXT] [--cursor-at ISO --cursor-id ID]
 Work list: work list --workspace ID [--order oldest|priority] [--queue review|blocked|activity]
+           a plan that only waits for its cadence is in neither review nor blocked; it returns to review when the wait ends
 Work writes: --file INPUT.json; human review needs a human workspace:access token
-Audiences: audience options --kind industries|locations|sizes|types|seniorities|titles|functions|industry_groups [--q TEXT]
+Audiences: audience options --kind industries|locations|sizes|types|seniorities|titles|functions [--q TEXT]
            audience list|show ID|create|update ID|archive ID|restore ID
            audience summary [--audience ID]|people ID|companies ID
            audience test ID --url LINKEDIN_URL --request-id UUID  (spends hosted credits unless the profile is saved)
 Files: file upload PATH --type MIME|list|prepare|register|download|delete ID (personal files, human token only)
-Queue: audienti queue [list]|next|claim ID|done ID [--note TEXT]|skip ID --note TEXT|release ID  (start here after you connect)
-Questions: audienti ask "QUESTION" [--context TEXT] [--option TEXT]... [--campaign ID] [--task ID]  (questions for your owner go to Operator, not chat)
+Queue: audienti queue [list]|next|claim ID [--note TEXT]|done ID [--note TEXT]|skip ID --note TEXT|release ID [--workspace ID]  (start here after you connect; without --workspace an agent reads every workspace its user approved it in)
+Outcome checks: audienti outcomes report TASK_ID --file RESULTS.json  (results for the people an outcomes.check task lists)
+Questions: audienti ask "QUESTION" [--context TEXT] [--option TEXT]... [--campaign ID] [--task ID]  (questions for your user go to Operator, not chat)
            audienti questions [list] [--state open|answered|withdrawn|all] | show ID | withdraw ID | answer ID --answer TEXT
-Rooms: audienti rooms directory|inbox|ack|send|thread|threads|create|list|retire|restore|redact|resume|pause|profile|hook|watch|wait (audienti rooms help)
+Rooms: audienti rooms directory|inbox|ack|send|thread|threads|create|list|read|retire|restore|redact|resume|pause|profile|hook|watch|wait (audienti rooms help)
+KV: audienti kv get KEY|set KEY VALUE [--json] [--nx] [--if-version N] [--ttl 7d|--expires-at TIME]|list [--prefix P]|search [--key TEXT] [--value TEXT]|delete KEY  (small state between runs; never credentials)
 Offers: offer list|show ID|create|update ID|archive ID|restore ID
 Offer options: --file FIELDS.json --request-id UUID --expected-revision N --revision N --archived true|false
   audienti prospects replies set|get|list PERSON --workspace ID [--evidence EVIDENCE] [--file INPUT.json]
 Account intake: prospects intake --workspace ID --file INPUT.json
                 prospects conversation append|list PERSON --workspace ID
-Discovery: prospects list|get ID|observation create|citation create|evidence create
-           prospects contacts list|record PERSON --workspace ID
+Discovery: prospects list|get ID|timeline ID [--limit N]|observation create|citation create|evidence create
+           prospects contacts list|record PERSON [--file INPUT.json] --workspace ID
            prospects contacts get|retire PERSON CONTACT --workspace ID
            prospects suppression get|set ID --workspace ID
            guardrails show|pause|resume --workspace ID
            dnc list|add VALUE|remove VALUE --workspace ID
            dnc import --file LIST.csv --workspace ID  (at most 5,000 rows; reports added, skipped and invalid rows)
            dnc export [--output FILE.csv] --workspace ID
+           secret list [--workspace ID]  (names only)
+           secret get NAME [--workspace ID] [--json]  (prints the value; every read is logged)
            budgets show --workspace ID
            budgets alerts --workspace ID [--limit N]
            usage breakdown [--workspace ID] [--since month|7d|30d|90d] [--by tool|provider|model|caller|day] [--format json|csv]
            audit list [--workspace ID] [--since 7d] [--actor agent|person] [--category NAME] [--format json|csv]
            budgets set --workspace ID [--agent ID --cap N|none] [--new-agent-cap N|none] [--at-limit pause|ask] [--alert80 on|off]  (alert80 covers Operator and email at 80%)
 Qualification: campaigns qualification submit --file INPUT.json
-Approaches: approach list|show ID|save --file REQUEST.json|progress ID|record --file REQUEST.json
-Analytics: analytics show --from ISO --to ISO [--campaign ID] [--approach-version ID] [--format json|csv]
+Find prospects: campaign find CAMPAIGN_ID --count N --max-credits C  (searches with the audience filters, checks each person, admits only fits; stops at N fits or the credit cap and reports the spend)
+                campaign check CAMPAIGN_ID --url LINKEDIN_URL [--request-id UUID]  (checks one person the same way; reuse the request ID after an interruption)
+Playbooks: playbook list|show ID|save --file REQUEST.json|progress ID|record --file REQUEST.json
+Analytics: analytics show --from ISO --to ISO [--campaign ID] [--playbook-version ID] [--format json|csv]
            analytics outbound [--workspace ID] [--days N | --from ISO --to ISO] [--by sender|action|day] [--format json|csv]
            analytics activity [--workspace ID] [--days N | --from ISO --to ISO] [--format json|csv]
            analytics cohorts [--workspace ID] [--stage goal|KEY] [--cohorts N] [--horizon N] [filters] [--format json|csv]
            analytics aging [--workspace ID] [--threshold-days N] [filters] [--format json|csv]
            analytics filters [--workspace ID]  (lists campaign, owner, offer, audience and tag values)
            (filters: --campaign ID --owner ID --offer ID --audience ID --tag TAG; also accepted by analytics show)
-Pipeline: pipeline show [--campaign ID] [--approach-version ID]
+Pipeline: pipeline show [--campaign ID] [--playbook-version ID]
 Connections: connections list|register --file REQUEST.json|report --file REQUEST.json
 Discovery writes use --file INPUT.json, --workspace ID and stable --request-id UUID
 Workspace commands: workspace init|list|create|show|search|invite|invitations|use
@@ -92,7 +101,30 @@ Start local MCP stdio server: mcp
 --json writes the API response envelope.
 `;
 
+// Example inputs for the commands that save prospects, so `--help` shows a working shape.
+const examples = {
+  'prospects observation create': { requestId: 'UUID', kind: 'person', source: { provider: 'web', url: 'https://example.com/team/jane' }, fields: { name: 'Jane Doe', title: 'VP Sales', imageUrl: 'https://media.licdn.com/dms/image/PHOTO_ID' }, provenance: { url: 'https://example.com/team/jane' }, observedAt: '2026-01-01T00:00:00Z', skill: { id: 'signal-prospect-research', version: '1' } },
+  'prospects citation create': { requestId: 'UUID', source: { kind: 'prospect', id: 'PERSON_PROSPECT_ID' }, target: { kind: 'prospect', id: 'COMPANY_PROSPECT_ID' }, edgeType: 'works_at', roles: [{ roleId: 'role-1', title: 'VP Sales', current: true, observedAt: '2026-01-01T00:00:00Z' }] },
+  'prospects evidence create': { requestId: 'UUID', subject: { kind: 'person', prospectId: 'PROSPECT_ID' }, campaignId: 'CAMPAIGN_ID', campaignRevision: 1, kind: 'interpretation', data: { conclusion: 'Leads a 40-person sales team', reason: 'Team page lists her as VP Sales' }, sourceUrl: 'https://example.com/team', observedAt: '2026-01-01T00:00:00Z', skill: { id: 'signal-prospect-research', version: '1' } },
+  'prospects contacts record': { kind: 'email|linkedin|mobile|phone', value: 'jane@example.com, or +15551234567 for a mobile or a direct office phone', reason: 'Published on https://example.com/contact', requestId: 'UUID', provenance: { observationId: 'OBSERVATION_ID' } },
+  'campaigns qualification submit': { requestId: 'UUID', campaignId: 'CAMPAIGN_ID', campaignRevision: 1, prospectId: 'PERSON_PROSPECT_ID', companyProspectId: 'COMPANY_PROSPECT_ID', companyIcp: { status: 'pass|fail|unverified', evidenceIds: ['COMPANY_EVIDENCE_ID'] }, personIcp: { status: 'pass|fail|unverified', evidenceIds: ['PERSON_EVIDENCE_ID'] }, signal: { status: 'match|no_match|unverified|not_required', evidenceIds: [] }, fit: { status: 'high|moderate|low|no_fit|unscored', evidenceIds: ['PERSON_EVIDENCE_ID'], reason: 'why' }, skill: { id: 'signal-prospect-research', version: '1' } },
+};
+
+function commandHelp() {
+  const words = args.slice(0, args.findIndex(value => value.startsWith('-'))).filter(Boolean);
+  const lines = usage.split('\n');
+  let shown = [];
+  for (let n = Math.min(words.length, 2); n > 0 && shown.length === 0; n--) {
+    const prefix = words.slice(0, n).join(' ');
+    shown = lines.filter(line => line.includes(prefix));
+  }
+  console.log(shown.length ? shown.map(line => line.trim()).join('\n') : usage);
+  const example = Object.entries(examples).find(([command]) => words.join(' ').startsWith(command));
+  if (example) console.log(`\nExample --file INPUT.json for ${example[0]}:\n${JSON.stringify(example[1], null, 1)}\nSteps and rules: the "Save prospects and contacts" section of llms.txt.`);
+}
+
 async function main() {
+  if (args.length > 1 && args.slice(1).some(value => value === '--help' || value === '-h') && !['tools', 'call', 'skills'].includes(args[0])) { commandHelp(); return; }
   if(args[0]==='prospects'&&['intake','conversation'].includes(args[1])){const {accountIntakeCli}=await import('./account-intake.mjs');await accountIntakeCli(args);return;}
   if(args[0]==='sender'){const {senderAccountsCli}=await import('./sender-accounts.mjs');await senderAccountsCli(args);return;}
   if(args[0]==='prospecting'){const {prospectingSettingsCli}=await import('./prospecting-settings.mjs');await prospectingSettingsCli(args);return;}
@@ -100,9 +132,11 @@ async function main() {
   if(args[0]==='prospects'&&args[1]==='contacts'){const {recipientsCli}=await import('./recipients.mjs');await recipientsCli(args);return;}
   if(args[0]==='usage'){const {usageCli}=await import('./usage.mjs');await usageCli(args);return;}
   if(args[0]==='audit'){const {auditCli}=await import('./audit.mjs');await auditCli(args);return;}
+  if(args[0]==='secret'||args[0]==='secrets'){const {secretsCli}=await import('./secrets.mjs');await secretsCli(args);return;}
   if(args[0]==='budgets'){const {budgetsCli}=await import('./budgets.mjs');await budgetsCli(args);return;}
   if(args[0]==='guardrails'||args[0]==='dnc'){const {guardrailsCli}=await import('./guardrails.mjs');await guardrailsCli(args);return;}
   if(args[0]==='prospects'&&args[1]==='suppression'){const {suppressionCli}=await import('./suppression.mjs');await suppressionCli(args);return;}
+  if(args[0]==='call'){const {callCli}=await import('./tools.mjs');await callCli(args);return;}
   if(args[0]==='tools'){const {toolsCli}=await import('./tools.mjs');await toolsCli(args);return;}
   if(['topics','posts'].includes(args[0])){const {contentCli}=await import('./content.mjs');await contentCli(args);return;}
   if(args[0]==='work'&&args[1]==='execution'){const {workExecutionCli}=await import('./work-execution.mjs');await workExecutionCli(args);return;}
@@ -111,14 +145,16 @@ async function main() {
   if(['prospects','campaigns'].includes(args[0])){const {discoveryCli}=await import('./discovery.mjs');await discoveryCli(args);return;}
   if(args[0]==='analytics'&&['cohorts','aging','filters'].includes(args[1])){const {cohortCli}=await import('./cohorts.mjs');await cohortCli(args);return;}
   if(args[0]==='analytics'&&['outbound','activity'].includes(args[1])){const {outboundCli}=await import('./outbound.mjs');await outboundCli(args);return;}
-  if(['approach','analytics','pipeline','connections'].includes(args[0])){const {progressCli}=await import('./progress.mjs');await progressCli(args);return;}
+  if(['playbook','analytics','pipeline','connections'].includes(args[0])){const {progressCli}=await import('./progress.mjs');await progressCli(args);return;}
   if(args[0]==='campaign'){const {campaignCli}=await import('./campaigns.mjs');await campaignCli(args);return;}
   if(args[0]==='audience'){const {audienceCli}=await import('./audiences.mjs');await audienceCli(args);return;}
   if(args[0]==='file'){const {fileCli}=await import('./files.mjs');await fileCli(args);return;}
   if(args[0]==='ask'){const {askCli}=await import('./questions.mjs');await askCli(args);return;}
   if(args[0]==='questions'){const {questionsCli}=await import('./questions.mjs');await questionsCli(args);return;}
   if(args[0]==='queue'){const {queueCli}=await import('./queue.mjs');await queueCli(args);return;}
+  if(args[0]==='outcomes'){const {outcomesCli}=await import('./outcomes.mjs');await outcomesCli(args);return;}
   if(args[0]==='rooms'){const {roomsCli}=await import('./rooms.mjs');await roomsCli(args);return;}
+  if(args[0]==='kv'){const {kvCli}=await import('./kv.mjs');await kvCli(args);return;}
   if(args[0]==='offer'){const {offerCli}=await import('./offers.mjs');await offerCli(args);return;}
   if (args[0] === 'agent') { const { agentCli } = await import('./agents.mjs'); await agentCli(args); return; }
   if (isAssignmentCommand(args)) { await assignmentCli(args); return; }
@@ -132,6 +168,7 @@ async function main() {
   if (args[0] === 'whoami' && profileIndex > 0 && args[profileIndex + 1]) {
     const { configuration } = await import('./workspaces.mjs');
     profileConfig = configuration(args[profileIndex + 1], 'account:read');
+    if (!profileConfig.token) throw new Error('whoami needs a human account token. Agents confirm their connection with: audienti workspace list --profile PATH');
     args.splice(profileIndex, 2);
   }
   if (args[0] !== 'whoami' || args.length > 2 || (args[1] && args[1] !== '--json')) throw new Error('Unknown command or option. Use audienti --help.');

package/cli/campaign-find.mjs

@@ -0,0 +1,155 @@
+import {randomUUID} from 'node:crypto';
+import {HostedResponseUnknown} from './workspaces.mjs';
+// #257: find N prospects for a Campaign. Searches LinkedIn with the Audience filters, then asks the server
+// to check each new person. The server fetches, runs the rules and records the result; this file only
+// drives the loop and adds up the spend. Amounts are pico USD (1 credit = 10,000,000,000).
+export const PICO_PER_CREDIT=10_000_000_000n;
+// Waits before each retry of a check whose outcome is unknown, in milliseconds.
+const RECOVERY_WAITS=[2000,5000,15000];
+const OUTCOMES=['fit','held','not_fit','already_found'];
+// Only a definite answer lets the run go on. A check that is still open, a lost response or a server
+// error may still be paying, so the same request ID is retried; anything else unexpected stops the run.
+const pending=error=>error instanceof HostedResponseUnknown||error?.code==='check_running'||error?.status>=500&&!['tool_unavailable','history_policy_unavailable'].includes(error?.code);
+// A refusal about this one person (a bad URL, no LinkedIn profile) is final, and the run moves on.
+const skippable=error=>[400,404,422].includes(error?.status);
+const MAX_SEARCHES=12,MAX_PAGES=10;
+const positive=list=>(list??[]).filter(item=>!item.negative);
+const numeric=value=>typeof value==='string'&&/^\d{1,20}$/.test(value);
+// A charge the server reported for one request. Charges are cumulative per request ID, so the largest one
+// seen across attempts is the request's charge so far.
+const reportedCharge=value=>numeric(value)?BigInt(value):0n;
+
+/** One profiles.search input per title, location and keyword combination the Audience and Campaign name. */
+export function planSearches(audience,signals=[]){
+ const titles=positive(audience.person?.currentTitles).map(item=>item.name).filter(Boolean).slice(0,5);
+ // #281: the people search has no company region filter, so with no person location the company's region is
+ // searched as where the person is. Without it the search pays to check people anywhere in the world.
+ const places=positive(audience.person?.locations).length?positive(audience.person?.locations):positive(audience.company?.locations);
+ const locations=places.slice(0,3).map(item=>numeric(item.providerId)?{geoId:item.providerId}:{location:item.name});
+ // #322: the search takes 20 industry ids at a time, so a longer list is split across searches, never cut.
+ const industryIds=[...new Set(positive(audience.company?.industries).map(item=>item.providerId).filter(numeric))];
+ const industryChunks=[];for(let i=0;i<industryIds.length;i+=20)industryChunks.push(industryIds.slice(i,i+20));
+ // A topic signal is a keyword people use; research and profile signals are judged after the fetch, not searched.
+ const queries=[...new Set([audience.discoveryKeyword,...signals.filter(signal=>signal.kind==='topic').map(signal=>signal.topic)].map(value=>value?.trim()).filter(Boolean))].slice(0,3);
+ // At most MAX_SEARCHES title, place and keyword combinations. Each one is searched across every industry chunk, so
+ // a long industry list never pushes a title out of the plan. The credit cap still bounds what the searches cost.
+ const combos=[];
+ for(const title of titles.length?titles:[undefined])for(const place of locations.length?locations:[{}])for(const query of queries.length?queries:[undefined])combos.push({kind:'person',...(title?{title}:{}),...place,...(query?{query}:{})});
+ const searches=[];
+ for(const combo of combos.slice(0,MAX_SEARCHES))for(const ids of industryChunks.length?industryChunks:[undefined]){
+  const input={...combo,...(ids?{industryIds:ids}:{})};
+  if(input.title||input.query||input.geoId||input.location||input.industryIds)searches.push(input);
+ }
+ return searches;
+}
+
+export function parseCredits(value){
+ if(typeof value!=='string'||!/^\d{1,7}(\.\d{1,4})?$/.test(value))throw new Error('Set --max-credits to a number of credits, like 50 or 12.5.');
+ const [whole,fraction='']=value.split('.');
+ return BigInt(whole)*PICO_PER_CREDIT+BigInt(fraction.padEnd(4,'0'))*(PICO_PER_CREDIT/10_000n);
+}
+export const credits=pico=>{const whole=pico/PICO_PER_CREDIT,rest=(pico%PICO_PER_CREDIT)*10_000n/PICO_PER_CREDIT;return rest?`${whole}.${rest.toString().padStart(4,'0').replace(/0+$/,'')}`:`${whole}`;};
+const charged=data=>data?.billing?.status==='charged'&&/^\d+$/.test(data.billing.amount??'')?BigInt(data.billing.amount):0n;
+// A search is final once its outcome is known and its charge has settled.
+const searchSettled=data=>['succeeded','failed','rejected'].includes(data?.status)&&(data.billing?.status==='not_charged'||charged(data)>0n||data.billing?.status==='charged'&&data.billing.amount==='0');
+const personUrl=url=>typeof url==='string'&&/^https:\/\/([a-z]{2,3}\.)?(www\.)?linkedin\.com\/in\//i.test(url);
+
+async function settled(call,workspaceId,data,wait){
+ for(let tries=0;data?.operationId&&!searchSettled(data)&&data.status!=='uncertain'&&tries<30;tries++){await wait(2000);data=(await call('tools_runs_get',{workspaceId,operationId:data.operationId})).data;}
+ return data;
+}
+
+/**
+ * Searches and checks until `count` new fits are found, the searches run out, or the next paid call could pass
+ * `maxCredits`. A search runs only when its published price fits what is left. Each check sends what is left as
+ * `maxCharge`, and the server refuses a check whose worst case (both profile fetches paid) could pass it.
+ */
+export async function findCampaignProspects(call,{workspaceId,campaignId,count,maxCredits},{wait=ms=>new Promise(resolve=>setTimeout(resolve,ms)),progress=()=>{}}={}){
+ const {data:campaign}=await call('campaign_get',{workspaceId,campaignId});
+ const fields=campaign.revision.fields;
+ if(!['Draft','Preparing','Active'].includes(campaign.campaign.state))throw new Error('This campaign is not finding prospects. Pick a Draft, Preparing or Active campaign.');
+ const {data:audience}=await call('audience_get',{workspaceId,audienceId:fields.audienceId,revision:fields.audienceRevision});
+ // #322: the search cannot apply an older audience's industry group, so it would pay to check people in any
+ // industry. Refuse before any paid call; named industries are searched.
+ const company=audience.revision.fields.company;
+ if(company?.industryGroups?.length&&!positive(company.industries).length)throw new Error("This campaign's audience uses an older industry group, which the LinkedIn search cannot apply. Name the industries in the audience instead (audienti audience options --kind industries --q TEXT), then try again.");
+ const searches=planSearches(audience.revision.fields,fields.signals);
+ // #323: rules that will reject people (a named title below the seniority floor) are shown before the first paid call.
+ const warnings=audience.revision.warnings??[];
+ for(const warning of warnings)progress({warning});
+ if(!searches.length)throw new Error("This campaign's audience has no title, location, industry or keyword to search by. Add one, then try again.");
+ const {data:tool}=await call('tools_get',{workspaceId,tool:'profiles.search'});
+ if(!/^\d{1,20}$/.test(tool?.price?.picoUsd??''))throw new Error('The LinkedIn search has no fixed price right now, so the credit cap cannot be kept. Try again later.');
+ const searchPrice=BigInt(tool.price.picoUsd);
+ const report={campaignId,state:campaign.campaign.state,target:count,maxCredits:credits(maxCredits),spentCredits:'0',spent:'0',searches:0,checked:0,fit:0,held:0,notFit:0,alreadyFound:0,failed:0,stoppedBecause:'searches_exhausted',fits:[],heldPeople:[],...(warnings.length?{audienceWarnings:warnings}:{})};
+ let spent=0n;const seen=new Set();
+ const finish=reason=>{report.stoppedBecause=reason;report.spent=spent.toString();report.spentCredits=credits(spent);return report;};
+ // The check may have paid more than it reported; the rest is recovered with the same request ID.
+ const unknown=(url,requestId,error)=>{report.unknownCheck={url,requestId,code:error?.code??'response_unknown'};return finish('outcome_unknown');};
+ for(const input of searches){
+  for(let page=1;page&&page<=MAX_PAGES;){
+   if(report.fit>=count)return finish('count_reached');
+   if(spent+searchPrice>maxCredits)return finish('credit_cap');
+   // Search results are not saved as People; only a person the check fetches joins People.
+   // Nothing else pays until this search has settled: a search still running, uncertain or with a charge not
+   // yet final is retried with the same request ID, and if it never settles the run stops and names it.
+   const search={workspaceId,requestId:randomUUID(),input:{...input,...(page>1?{page}:{}),saveProfiles:false}};
+   let data=null,failure=null,paid=0n;
+   for(let attempt=0;;attempt++){
+    try{data=await settled(call,workspaceId,(await call('tools_profiles_search',search)).data,wait);failure=null;}
+    catch(error){if(!pending(error))throw error;failure=error;}
+    if(!failure&&charged(data)>paid)paid=charged(data);
+    if(!failure&&searchSettled(data))break;
+    if(attempt>=RECOVERY_WAITS.length){
+     spent+=paid;report.searches++;
+     report.unknownSearch={requestId:search.requestId,operationId:data?.operationId??null,code:failure?.code??data?.error?.code??data?.status??'response_unknown'};
+     return finish('outcome_unknown');
+    }
+    await wait(RECOVERY_WAITS[attempt]);
+   }
+   spent+=paid;report.searches++;
+   if(data?.status!=='succeeded'){if(data?.error?.code==='insufficient_credits')return finish('no_credits');break;}
+   const items=(data.result?.items??[]).filter(item=>personUrl(item.url)&&!seen.has(item.url));
+   for(const item of items){
+    seen.add(item.url);
+    if(report.fit>=count)return finish('count_reached');
+    if(spent>=maxCredits)return finish('credit_cap');
+    // Nothing else pays until this check has a definite answer. The same request ID replays the stored
+    // outcome and charge; if no definite answer comes, the run stops and names the check to recover.
+    const args={workspaceId,campaignId,url:item.url,requestId:randomUUID(),maxCharge:(maxCredits-spent).toString()};
+    // Every attempt's reported charge is kept, and the largest is counted once on every way out.
+    let result,failure,paid=0n;
+    for(let attempt=0;;attempt++){
+     try{result=(await call('campaign_prospect_check',args)).data;failure=null;}
+     catch(error){result=null;failure=error;}
+     const reported=reportedCharge(failure?failure.charged:result?.charged);
+     if(reported>paid)paid=reported;
+     if(!failure&&!OUTCOMES.includes(result?.outcome)){failure={code:'invalid_response'};break;}
+     if(!failure||!pending(failure)||attempt>=RECOVERY_WAITS.length)break;
+     await wait(RECOVERY_WAITS[attempt]);
+    }
+    spent+=paid;
+    if(failure){
+     const error=failure;
+     if(pending(error)||error.code==='invalid_response')return unknown(item.url,args.requestId,error);
+     if(error.code==='check_over_budget')return finish('credit_cap');
+     if(error.status===402)return finish('no_credits');
+     if(error.code==='campaign_not_active')return finish('campaign_not_active');
+     if(['tool_unavailable','history_policy_unavailable'].includes(error.code))return finish('tool_unavailable');
+     if(!skippable(error))return unknown(item.url,args.requestId,error);
+     report.failed++;progress({url:item.url,outcome:'failed',code:error.code,spent:credits(spent)});continue;
+    }
+    report.checked++;
+    const who={prospectId:result.prospectId,url:item.url,name:item.name??null,reason:result.assessment?.fit?.reason??null};
+    if(result.outcome==='fit'){report.fit++;report.fits.push({...who,admission:result.assessment?.admission});}
+    else if(result.outcome==='held'){report.held++;report.heldPeople.push({...who,reason:result.assessment?.reason??null});}
+    else if(result.outcome==='not_fit')report.notFit++;
+    else report.alreadyFound++;
+    progress({url:item.url,outcome:result.outcome,spent:credits(spent)});
+   }
+   // Follow the next page even when this one had only people already seen; MAX_PAGES still bounds it.
+   page=data.result?.nextPage>page?data.result.nextPage:0;
+  }
+ }
+ return finish(report.fit>=count?'count_reached':'searches_exhausted');
+}

package/cli/campaign-operations.mjs

@@ -7,7 +7,7 @@ const signal=z.discriminatedUnion('kind',[
  z.object({...signalBase,kind:z.literal('topic'),topic:z.string()}).strict(),
  z.object({...signalBase,kind:z.literal('profile'),url:z.string(),track:z.enum(['audience','activity']).optional(),interactions:z.array(z.enum(['comments','reactions'])).optional()}).strict(),
 ]);
-const fields=z.object({name:z.string(),audienceId:uuid,audienceRevision:z.number().int(),offerId:uuid,offerRevision:z.number().int(),premise:z.string().optional(),approach:z.string().optional(),approachPin:z.object({id:uuid,revision:z.number().int().positive()}).strict().optional(),notes:z.string().optional(),ownerUserId:uuid.nullable().optional(),tags:z.array(z.string()).optional(),signalMatch:z.enum(['any','all']).optional(),signals:z.array(signal).optional(),targets:z.discriminatedUnion('kind',[
+const fields=z.object({name:z.string(),audienceId:uuid,audienceRevision:z.number().int(),offerId:uuid,offerRevision:z.number().int(),premise:z.string().optional(),playbookPin:z.object({id:uuid,revision:z.number().int().positive()}).strict().optional(),notes:z.string().optional(),ownerUserId:uuid.nullable().optional(),tags:z.array(z.string()).optional(),signalMatch:z.enum(['any','all']).optional(),signals:z.array(signal).optional(),targets:z.discriminatedUnion('kind',[
  z.object({kind:z.literal('none'),values:z.array(z.never())}).strict(),
  z.object({kind:z.literal('companies'),values:z.array(z.object({type:z.enum(['domain','linkedin-company']),value:z.string()}).strict())}).strict(),
  z.object({kind:z.literal('people'),values:z.array(z.object({type:z.literal('linkedin-person'),value:z.string()}).strict())}).strict(),
@@ -15,12 +15,15 @@ const fields=z.object({name:z.string(),audienceId:uuid,audienceRevision:z.number
 const path=a=>`/workspaces/${a.workspaceId}/campaigns`,detail=a=>path(a)+`/${a.campaignId}`;
 const qs=a=>new URLSearchParams(Object.fromEntries(Object.entries(a).filter(([k,v])=>!['workspaceId','campaignId'].includes(k)&&v!==undefined).map(([k,v])=>[k,String(v)])));
 export const campaignOperations={
- campaign_summary:{schema:z.object({...workspace}).strict(),method:'GET',path:a=>`/workspaces/${a.workspaceId}/campaign-summary`,scoped:true,description:'Counts of Campaigns per state, and per Campaign its Audience, offer, approach, goal stage, methods, people, engaged and at-goal counts since start.'},
+ campaign_summary:{schema:z.object({...workspace}).strict(),method:'GET',path:a=>`/workspaces/${a.workspaceId}/campaign-summary`,scoped:true,description:'Counts of Campaigns per state, and per Campaign its Audience, offer, playbook, goal stage, methods, people, engaged and at-goal counts since start.'},
  campaign_list:{schema:z.object({...workspace,state:state.optional(),archived:z.boolean().optional(),q:z.string().optional(),limit:z.number().int().optional(),after:uuid.optional()}).strict(),method:'GET',path:a=>path(a)+'?'+qs(a),scoped:true},
  campaign_get:{schema:z.object({...locator,revision:z.number().int().optional()}).strict(),method:'GET',path:a=>detail(a)+'?'+qs(a),scoped:true},
  campaign_events:{schema:z.object({...locator,limit:z.number().int().optional(),after:uuid.optional()}).strict(),method:'GET',path:a=>detail(a)+'/events?'+qs(a),scoped:true},
  campaign_create:{schema:z.object({...workspace,requestId:uuid,fields}).strict(),method:'POST',path,body:a=>({requestId:a.requestId,fields:a.fields}),scoped:true},
  campaign_update:{schema:z.object({...locator,expectedRevision:z.number().int(),fields}).strict(),method:'POST',path:a=>detail(a)+'/revisions',body:a=>({expectedRevision:a.expectedRevision,fields:a.fields}),scoped:true},
- campaign_transition:{schema:z.object({...locator,expectedState:state,operation:z.enum(['prepare','activate','pause','resume','close','archive','restore']),reason:z.string().optional()}).strict(),method:'POST',path:a=>detail(a)+'/transitions',body:a=>({expectedState:a.expectedState,operation:a.operation,...(a.reason===undefined?{}:{reason:a.reason})}),scoped:true,description:'Move a Campaign through its lifecycle. prepare: Draft to Preparing (signal tracking and prospect finding run, no engagement). activate: Draft or Preparing to Active (finding and engagement run). pause: stop automation. resume: back to the paused state. close: Active to Closing (finding stops, engagement continues). archive: stop everything and hide it. restore: Archived to Paused, or Draft for a draft. Agents do not start or activate campaigns; the owner does.'},
+ campaign_transition:{schema:z.object({...locator,expectedState:state,operation:z.enum(['prepare','activate','pause','resume','close','archive','restore']),reason:z.string().optional()}).strict(),method:'POST',path:a=>detail(a)+'/transitions',body:a=>({expectedState:a.expectedState,operation:a.operation,...(a.reason===undefined?{}:{reason:a.reason})}),scoped:true,description:'Move a Campaign through its lifecycle. prepare: Draft to Preparing (signal tracking and prospect finding run, no engagement). activate: Draft or Preparing to Active (finding and engagement run). pause: stop automation. resume: back to the paused state. close: Active to Closing (finding stops, engagement continues). archive: stop everything and hide it. restore: Archived to Paused, or Draft for a draft. Agents do not start or activate campaigns; the user does. A campaign that cannot run is refused with campaign_not_ready and its missing items in blockers.'},
+ campaign_pace_get:{schema:z.object({...locator}).strict(),method:'GET',path:a=>detail(a)+'/pace',scoped:true,description:'Read a Campaign pace: new people a day. Derived is 25 a day per confirmed LinkedIn account, each capped by its reported connection-request limit; an email-only Campaign uses its own number, 50 by default, within mailbox limits. The reply names the LinkedIn accounts, the weekly figure and the expected daily credits for hosted lookups.'},
+ campaign_pace_set:{schema:z.object({...locator,perDay:z.union([z.number().int().min(1).max(1000),z.literal('derived')]).optional(),maxCredits:z.number().int().min(1).max(100000).nullable().optional()}).strict().refine(a=>a.perDay!==undefined||a.maxCredits!==undefined,{message:'Send perDay, maxCredits or both.'}),method:'POST',path:a=>detail(a)+'/pace',body:a=>({...(a.perDay===undefined?{}:{perDay:a.perDay}),...(a.maxCredits===undefined?{}:{maxCredits:a.maxCredits})}),scoped:true,description:'Save a Campaign pace. Pass the number the user gave, or "derived" to follow the confirmed sending accounts. An owner number stays until changed and is still capped by LinkedIn account and mailbox limits. maxCredits saves the credits a day the user approved for finding (null removes it); each day\'s find task carries it.'},
+ campaign_prospect_check:{schema:z.object({...locator,url:z.string().max(1024),requestId:uuid,maxCharge:z.string().regex(/^\d{1,20}$/).optional()}).strict(),method:'POST',path:a=>detail(a)+'/prospect-checks',body:a=>({url:a.url,requestId:a.requestId,...(a.maxCharge!==undefined?{maxCharge:a.maxCharge}:{})}),scoped:true,recoverable:true,timeoutMs:90000,description:'Check one LinkedIn person URL for a Campaign and record the result. Fetches the person and current company (saved profiles are reused free; otherwise each fetch spends hosted credits), runs the pinned Audience rules and records a qualification with the profiles as evidence. outcome fit: admitted, or shortlisted while the Campaign is a Draft. held: an agent must judge a smart rule, a signal or an undecided rule. not_fit: a rule failed. already_found: already in or shortlisted for this Campaign; nothing written. charged and balance are pico USD (1 credit = 10,000,000,000). Generate requestId once and reuse it after an interruption so a retry never pays twice.'},
  campaign_successor:{schema:z.object({...locator,requestId:uuid,expectedRevision:z.number().int(),fields}).strict(),method:'POST',path:a=>detail(a)+'/successors',body:a=>({requestId:a.requestId,expectedRevision:a.expectedRevision,fields:a.fields}),scoped:true},
 };