@audienti/cli 0.2.0-exora.1 → 0.2.0-exora.10

package/cli/audienti.mjs

@@ -1,18 +1,21 @@
 #!/usr/bin/env node
 import { isAssignmentCommand, assignmentCli } from './assignment.mjs';
+import { playbookHelp } from './playbook-help.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 [--workspace ID] [--profile PATH] (connect: the user only; returns a sign-in link)
+                  audienti sender managed plan MANAGED_ACCOUNT_ID --plan free|premium_career|premium_business|premium_all_in_one|sales_navigator_core|sales_navigator_advanced|recruiter_lite|none [--workspace ID]  (the user only; sets the connection note length; none clears it)
 Prospecting: audienti prospecting settings show|save|accounts|account-show|account-save|history [--profile PATH]
 Usage: audienti whoami [--json]
        audienti workspace assignments list [--workspace ID]
        audienti workspace prospect assignment get/set --prospect-id ID [--file INPUT.json]
        audienti workspace routing-rules get/replace [--file INPUT.json]
        audienti workspace routing apply --file INPUT.json
-       audienti workspace prospect experiment-fit get --prospect-id ID --experiment-id ID
+       audienti workspace prospect campaign-fit get --prospect-id ID --campaign-id ID
        audienti workspace prospect fit-override set/clear --file INPUT.json
        audienti workspace prospect move --file INPUT.json
        audienti workspace member remove --file INPUT.json
@@ -23,60 +26,144 @@ Required environment:
   AUDIENTI_API_TOKEN  Account API token (create it from your Account page)
 
 Use HTTPS for remote hosts. Local HTTP is supported on loopback only.
-Agent commands: agent connect --name NAME|poll|cancel|list|revoke ID --profile PATH
+Agent commands: agent connect --name NAME [--write (ask for Allow workspace changes up front)] [--capabilities find,enrich,expand,research,engage,sync,notify,approve]|poll|cancel|list|revoke ID --profile PATH
 Owner permission change: agent permission ID --scope workspace:read|workspace:access --profile USER_PROFILE
-Agent capabilities: agent capabilities report --file REPORT.json --profile AGENT_PROFILE
+Owner capability change: agent capabilities ID --set find,enrich,expand,research,engage,sync,notify,approve --profile USER_PROFILE (agents are refused outside this set)
+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 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 [--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; done or skip again with a new --note corrects the note of a finished task)
+Attachments: audienti attachments upload FILE [--duration SECONDS]  (store an image or voice note, get its id for content.attachments)
+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|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] [--request-id UUID] --workspace ID
            prospects contacts get|retire PERSON CONTACT --workspace ID
            prospects suppression get|set ID --workspace ID
-Qualification: experiments 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 [--experiment ID] [--approach-version 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; the secret records who read it last and when)
+           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]
+           workspace usage summary|callers|calls [--after ID] [--caller user:ID|agent:ID|key:ID] [--status all|succeeded|failed|pending]|call ID [--workspace ID]  (paid tool use, last 30 days, and single calls)
+           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
+Campaign summary: campaign summary [--workspace ID]  (campaign counts per state, and per campaign its audience, offer, playbook, goal stage, people, engaged and at-goal counts)
+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)
+Target companies: campaign targets CAMPAIGN_ID [--limit N --after CURSOR]  (reads the companies people must work at to join)
+                  campaign targets CAMPAIGN_ID --add acme.com,linkedin.com/company/globex [--remove old.com] | --set FILE|-  (one company per line; saves a new revision)
+Playbooks: playbook list [--archived] [--limit N --cursor ID]|actions|show ID [--revision N]|save --file REQUEST.json|archive ID|restore ID|delete ID|progress PARTICIPATION_ID|record --file REQUEST.json|suggest --file REQUEST.json|suggestions|decide --file REQUEST.json  (audienti playbook SUBCOMMAND --help for the request shape)
+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] [--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|invite|invitations|use
-Invitation commands: workspace invitation show|accept|retry|cancel ID
+Workspace commands: workspace init|list|create|show|search|invite|invitations|use
+Notifications: workspace notifications --workspace ID [--unread-only true] [--cursor FILE.json]
+Read state: workspace notification-read --workspace ID --key KEY --read true|false [--through OBSERVED_AT]
+Search: workspace search --workspace ID --query TEXT [--people-only true] [--recent FILE.json]
+Invitation commands: workspace invitation show|accept|decline|retry|cancel ID
 Options: --workspace ID --name NAME --request-id UUID --email EMAIL --generation N
-Optional private profile: --profile PATH (outside this repository)
+Optional private profile: --profile PATH (outside this repository), or the AUDIENTI_PROFILE variable. --profile wins.
 Save an environment token: profile save --scope account:read|workspace:access|agents:manage --profile PATH
 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: 'linkedin', url: 'https://www.linkedin.com/in/jane-doe' }, 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[0] === 'playbook' && args.slice(1).some(value => value === '--help' || value === '-h')) { console.log(playbookHelp(args[1]?.startsWith('-') ? undefined : args[1])); return; }
+  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;}
   if(args[0]==='prospects'&&args[1]==='replies'){const {accountRepliesCli}=await import('./account-replies.mjs');await accountRepliesCli(args);return;}
   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;}
   if(args[0]==='work'&&args[1]==='changes'){const {workFeedbackCli}=await import('./work-feedback.mjs');await workFeedbackCli(args);return;}
   if(args[0]==='work'){const {workCli}=await import('./work.mjs');await workCli(args);return;}
-  if(['prospects','experiments'].includes(args[0])){const {discoveryCli}=await import('./discovery.mjs');await discoveryCli(args);return;}
-  if(['approach','analytics','connections'].includes(args[0])){const {progressCli}=await import('./progress.mjs');await progressCli(args);return;}
-  if(args[0]==='experiment'){const {experimentCli}=await import('./experiments.mjs');await experimentCli(args);return;}
+  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(['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]==='attachments'){const {attachmentsCli}=await import('./attachments.mjs');await attachmentsCli(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; }
@@ -90,12 +177,18 @@ 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);
+  } else if (args[0] === 'whoami' && profileIndex < 0 && process.env.AUDIENTI_PROFILE && !(process.env.AUDIENTI_API_URL && process.env.AUDIENTI_API_TOKEN)) {
+    // The profile named by AUDIENTI_PROFILE (#448), unless the URL and token are in the environment.
+    const { configuration } = await import('./workspaces.mjs');
+    profileConfig = configuration(undefined, 'account:read');
+    if (!profileConfig.token) throw new Error('whoami needs a human account token, and AUDIENTI_PROFILE holds none. Agents confirm their connection with: audienti workspace list');
   }
   if (args[0] !== 'whoami' || args.length > 2 || (args[1] && args[1] !== '--json')) throw new Error('Unknown command or option. Use audienti --help.');
   const rawUrl = profileConfig ? profileConfig.url : process.env.AUDIENTI_API_URL;
   const token = profileConfig ? profileConfig.token : process.env.AUDIENTI_API_TOKEN;
-  if (!rawUrl || !token) throw new Error('Set AUDIENTI_API_URL and AUDIENTI_API_TOKEN. Create a token from your Account page.');
+  if (!rawUrl || !token) throw new Error('Set AUDIENTI_API_URL and AUDIENTI_API_TOKEN, or pass --profile PATH (or set AUDIENTI_PROFILE) to a profile with an account:read token. Create a token from your Account page.');
   let base;
   try { base = new URL(rawUrl); } catch { throw new Error('AUDIENTI_API_URL must be a valid API base URL.'); }
   if (base.username || base.password || base.search || base.hash) throw new Error('The API URL must not contain credentials, query parameters, or a fragment.');
@@ -121,4 +214,4 @@ async function main() {
   console.log(args[1] === '--json' ? JSON.stringify({ data: profile }) : `${profile.email ?? profile.username ?? profile.id}\nAccount ID: ${profile.id}`);
 }
 
-main().catch(error => { console.error(error.toJSON ? JSON.stringify({ error: error.toJSON() }) : `Audienti: ${error.message}`); process.exitCode = 1; });
+main().catch(error => { console.error(JSON.stringify({ error: error.toJSON ? error.toJSON() : { code: 'client_error', message: error.message } })); process.exitCode = 1; });

package/cli/audit-operations.mjs

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+const query = a => new URLSearchParams(Object.entries(a).filter(([k, v]) => k !== 'workspaceId' && v !== undefined).map(([k, v]) => [k, String(v)]));
+export const auditOperations = {
+ workspace_audit_log_list: {
+  schema: z.object({
+   workspaceId: z.string().uuid().optional(),
+   actor: z.enum(['person', 'agent']).optional(),
+   category: z.enum(['guardrails', 'budgets', 'approvals', 'suppression', 'members', 'agents']).optional(),
+   since: z.string().datetime().optional(),
+   until: z.string().datetime().optional(),
+   cursor: z.string().max(500).optional(),
+   limit: z.number().int().min(1).max(200).optional(),
+  }).strict(),
+  method: 'GET', path: a => `/workspaces/${a.workspaceId}/audit-events?${query(a)}`, scoped: true,
+  description: 'List the read-only workspace audit log: who changed guardrails, budgets, approvals, suppression, members and agent access, newest first. Admin only. Page with cursor.',
+ },
+};

package/cli/audit.mjs

@@ -0,0 +1,39 @@
+import { callWorkspace, configuration } from './workspaces.mjs';
+
+const UNITS = { m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
+export function sinceToIso(value, now = Date.now()) {
+ const match = /^(\d{1,4})([mhdw])$/.exec(value);
+ if (match) return new Date(now - Number(match[1]) * UNITS[match[2]]).toISOString();
+ const date = new Date(value);
+ if (Number.isNaN(date.getTime())) throw Error('--since must look like 7d, 12h or an ISO date.');
+ return date.toISOString();
+}
+const cell = value => /[",\n\r]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+export function auditCsv(items) {
+ const rows = items.map(item => [item.at, item.actor?.kind ?? '', item.actor?.name ?? '', item.category, item.action, item.summary, item.object?.label ?? '', item.object?.href ?? '']);
+ return [['when', 'actor_kind', 'actor', 'category', 'action', 'summary', 'object', 'link'], ...rows].map(row => row.map(cell).join(',')).join('\n') + '\n';
+}
+export async function auditCli(args) {
+ const flags = {}, positions = [];
+ for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === '--json') continue;
+  if (!arg.startsWith('--')) { positions.push(arg); continue; }
+  const key = arg.slice(2);
+  if (!['workspace', 'profile', 'since', 'until', 'actor', 'category', 'limit', 'cursor', 'format'].includes(key) || Object.hasOwn(flags, key) || i + 1 >= args.length) throw Error(`Invalid flag --${key}.`);
+  flags[key] = args[++i];
+ }
+ if (positions.length !== 2 || positions[1] !== 'list') throw Error('Use audit list [--workspace ID] [--since 7d] [--actor agent|person] [--format json|csv].');
+ if (flags.actor && !['agent', 'person'].includes(flags.actor)) throw Error('--actor must be agent or person.');
+ if (flags.format && !['json', 'csv'].includes(flags.format)) throw Error('--format must be json or csv.');
+ const input = { workspaceId: flags.workspace };
+ if (flags.actor) input.actor = flags.actor;
+ if (flags.category) input.category = flags.category;
+ if (flags.since) input.since = sinceToIso(flags.since);
+ if (flags.until) input.until = sinceToIso(flags.until);
+ if (flags.cursor) input.cursor = flags.cursor;
+ if (flags.limit) { input.limit = Number(flags.limit); if (!Number.isInteger(input.limit)) throw Error('--limit must be a whole number.'); }
+ const result = await callWorkspace('workspace_audit_log_list', input, configuration(flags.profile));
+ if (flags.format === 'csv') { process.stdout.write(auditCsv((result?.data ?? result)?.items ?? [])); return; }
+ console.log(JSON.stringify(result));
+}

package/cli/budget-operations.mjs

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+const workspace = { workspaceId: z.string().uuid().optional() };
+const cap = z.number().int().min(0).max(10000000).nullable();
+export const budgetOperations = {
+ workspace_budgets_get: { schema: z.object(workspace).strict(), method: 'GET', path: a => `/workspaces/${a.workspaceId}/budgets`, scoped: true, description: 'Read spend budgets: credits used this UTC month, each agent’s monthly cap (null means unlimited), the cap for newly registered agents, what happens at a cap and the 80% warning switch (Operator and email) and the ten latest alerts.' },
+ workspace_budget_alerts: { schema: z.object({ ...workspace, limit: z.number().int().min(1).max(200).optional() }).strict(), method: 'GET', path: a => `/workspaces/${a.workspaceId}/budget-alerts${a.limit ? `?limit=${a.limit}` : ''}`, scoped: true, description: 'List recent low-credit and budget alerts, newest first. Workspace credits and each agent’s monthly cap alert once per UTC month at 80% and at 100%; owners and admins are emailed and see them in Operator.' },
+ workspace_budgets_set: { schema: z.object({ ...workspace, agentCaps: z.array(z.object({ agentId: z.string().uuid(), monthlyCap: cap }).strict()).max(200).optional(), newAgentCap: cap.optional(), atLimit: z.enum(['pause', 'ask']).optional(), alert80: z.boolean().optional(), expectedVersion: z.number().int().min(0).optional() }).strict(), method: 'POST', path: a => `/workspaces/${a.workspaceId}/budgets`, body: ({ workspaceId, ...rest }) => rest, scoped: true, description: 'Change spend budgets. Send only the fields to change; null removes a cap. Admin only and only a person: an agent cannot raise its own cap. An agent at its cap gets budget_exceeded on hosted tool calls until the month resets or the cap is raised.' },
+};

package/cli/budgets.mjs

@@ -0,0 +1,34 @@
+import { callWorkspace, configuration } from './workspaces.mjs';
+const cap = (name, value) => {
+ if (value === 'none' || value === 'unlimited') return null;
+ if (!/^\d+$/.test(value ?? '')) throw Error(`--${name} needs a whole number of credits, or "none" for no cap.`);
+ return Number(value);
+};
+export async function budgetsCli(args) {
+ const flags = {}, positions = [];
+ for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === '--json') continue;
+  if (!arg.startsWith('--')) { positions.push(arg); continue; }
+  const key = arg.slice(2);
+  if (!['workspace', 'profile', 'agent', 'cap', 'new-agent-cap', 'at-limit', 'alert80', 'limit'].includes(key) || Object.hasOwn(flags, key) || i + 1 >= args.length) throw Error(`Invalid flag --${key}.`);
+  flags[key] = args[++i];
+ }
+ if (positions.length !== 2 || positions[0] !== 'budgets' || !['show', 'set', 'alerts'].includes(positions[1])) throw Error('Use budgets show|set|alerts --workspace ID. See audienti help.');
+ const input = { workspaceId: flags.workspace };
+ let name = 'workspace_budgets_get';
+ if (positions[1] === 'alerts') {
+  name = 'workspace_budget_alerts';
+  if (flags.limit !== undefined) { if (!/^\d+$/.test(flags.limit) || Number(flags.limit) < 1 || Number(flags.limit) > 200) throw Error('--limit is a whole number from 1 to 200.'); input.limit = Number(flags.limit); }
+ }
+ if (positions[1] === 'set') {
+  name = 'workspace_budgets_set';
+  if ((flags.agent === undefined) !== (flags.cap === undefined)) throw Error('--agent and --cap go together.');
+  if (flags.agent) input.agentCaps = [{ agentId: flags.agent, monthlyCap: cap('cap', flags.cap) }];
+  if (flags['new-agent-cap'] !== undefined) input.newAgentCap = cap('new-agent-cap', flags['new-agent-cap']);
+  if (flags['at-limit'] !== undefined) { if (!['pause', 'ask'].includes(flags['at-limit'])) throw Error('--at-limit is pause or ask.'); input.atLimit = flags['at-limit']; }
+  if (flags.alert80 !== undefined) { if (!['on', 'off'].includes(flags.alert80)) throw Error('--alert80 is on or off.'); input.alert80 = flags.alert80 === 'on'; }
+  if (Object.keys(input).length < 2) throw Error('Nothing to change. Use --agent ID --cap N, --new-agent-cap N, --at-limit pause|ask or --alert80 on|off.');
+ }
+ console.log(JSON.stringify(await callWorkspace(name, input, configuration(flags.profile))));
+}

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

@@ -0,0 +1,30 @@
+import {z} from 'zod';
+const uuid=z.string().uuid(),workspace={workspaceId:uuid.optional()},locator={...workspace,campaignId:uuid};
+const state=z.enum(['Draft','Preparing','Active','Paused','Closing','Archived']);
+const signalBase={id:uuid,scope:z.enum(['company','person']),details:z.string().optional()};
+const signal=z.discriminatedUnion('kind',[
+ z.object({...signalBase,kind:z.literal('research'),question:z.string(),expected:z.boolean().optional()}).strict(),
+ 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(),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(),method:z.enum(['signals','listen','track-audience','track-engagement','custom']).optional(),findingInstructions:z.string().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(),
+]).optional(),channels:z.array(z.enum(['email','linkedin'])).optional(),approvalMode:z.literal('manual').optional(),contentOpsEnabled:z.boolean().optional(),schedule:z.object({startAt:z.string().nullable().optional(),endAt:z.string().nullable().optional(),maxCompanies:z.number().int().nullable().optional()}).strict().optional()}).strict();
+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, 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 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_targets_get:{schema:z.object({...locator,limit:z.number().int().min(1).max(500).optional(),after:z.string().regex(/^\d{1,7}$/).optional()}).strict(),method:'GET',path:a=>detail(a)+'/targets?'+qs(a),scoped:true,description:'Read a Campaign\'s target companies in pages of up to 500: domains and LinkedIn company URLs. Only people whose current company is one of them can join.'},
+ campaign_targets_change:{schema:z.object({...locator,expectedRevision:z.number().int().positive(),add:z.array(z.string()).optional(),remove:z.array(z.string()).optional(),set:z.array(z.string()).optional()}).strict().refine(a=>(a.set===undefined)!==(a.add===undefined&&a.remove===undefined),{message:'Send set, or add and or remove.'}),method:'POST',path:a=>detail(a)+'/targets',body:a=>({expectedRevision:a.expectedRevision,...Object.fromEntries(['add','remove','set'].filter(k=>a[k]!==undefined).map(k=>[k,a[k]]))}),scoped:true,description:'Change a Campaign\'s target companies: add or remove domains (acme.com) and LinkedIn company URLs, or replace them all with set. Saves a new Campaign revision; an empty set removes the targets.'},
+ 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},
+};

package/cli/campaigns.mjs

@@ -0,0 +1,61 @@
+import {callWorkspace,configuration} from './workspaces.mjs';
+import {readJsonFile} from './json-file.mjs';
+export async function campaignCli(args){
+ const position=[],flags={};for(let i=0;i<args.length;i++){
+  if(!args[i].startsWith('--')){position.push(args[i]);continue}
+  const key=args[i].slice(2);if(!['profile','workspace','file','request-id','expected-revision','revision','archived','limit','after','q','state','operation','expected-state','reason','per-day','count','max-credits','url','add','remove','set'].includes(key)||!args[i+1]||args[i+1].startsWith('--')||Object.hasOwn(flags,key))throw new Error('Unknown or incomplete campaign option.');
+  flags[key]=args[++i];
+ }
+ const command=position[1];
+ if(command==='find'){
+  if(position.length!==3)throw new Error('Use campaign find ID --count N --max-credits C.');
+  if(!/^\d{1,3}$/.test(flags.count??'')||Number(flags.count)<1||Number(flags.count)>500)throw new Error('Set --count to how many fits to find, from 1 to 500.');
+  if(flags['max-credits']===undefined)throw new Error('Set --max-credits to the most credits this run may spend.');
+  const {findCampaignProspects,parseCredits}=await import('./campaign-find.mjs');
+  const config=configuration(flags.profile);
+  const report=await findCampaignProspects((operation,input)=>callWorkspace(operation,input,config),{workspaceId:flags.workspace,campaignId:position[2],count:Number(flags.count),maxCredits:parseCredits(flags['max-credits'])},{progress:step=>console.error(JSON.stringify(step))});
+  console.log(JSON.stringify({data:report}));return;
+ }
+ if(command==='check'){
+  if(position.length!==3||!flags.url)throw new Error('Use campaign check ID --url LINKEDIN_URL [--request-id UUID].');
+  const {randomUUID}=await import('node:crypto');
+  console.log(JSON.stringify(await callWorkspace('campaign_prospect_check',{workspaceId:flags.workspace,campaignId:position[2],url:flags.url,requestId:flags['request-id']??randomUUID()},configuration(flags.profile))));return;
+ }
+ if(command==='targets'){
+  if(position.length!==3)throw new Error('Use campaign targets ID [--add a.com,b.com] [--remove a.com] [--set FILE|-] [--expected-revision N].');
+  const config=configuration(flags.profile),input={workspaceId:flags.workspace,campaignId:position[2]};
+  const change=['add','remove','set'].some(k=>flags[k]!==undefined);
+  if(!change){if(flags.limit!==undefined)input.limit=Number(flags.limit);if(flags.after)input.after=flags.after;console.log(JSON.stringify(await callWorkspace('campaign_targets_get',input,config)));return;}
+  if(flags.set!==undefined&&(flags.add!==undefined||flags.remove!==undefined))throw new Error('Use --set on its own, or --add and --remove.');
+  const split=v=>v.split(',').map(x=>x.trim()).filter(Boolean);
+  if(flags.add!==undefined)input.add=split(flags.add);
+  if(flags.remove!==undefined)input.remove=split(flags.remove);
+  if(flags.set!==undefined){const {readFileSync}=await import('node:fs');input.set=readFileSync(flags.set==='-'?0:flags.set,'utf8').split(/\r?\n/).map(x=>x.trim()).filter(x=>x&&!x.startsWith('#'));}
+  input.expectedRevision=flags['expected-revision']!==undefined?Number(flags['expected-revision']):(await callWorkspace('campaign_targets_get',{workspaceId:flags.workspace,campaignId:position[2],limit:1},config)).data.revision;
+  console.log(JSON.stringify(await callWorkspace('campaign_targets_change',input,config)));return;
+ }
+ if(command==='summary'){
+  if(position.length!==2)throw new Error('Use campaign summary [--workspace ID].');
+  console.log(JSON.stringify(await callWorkspace('campaign_summary',{workspaceId:flags.workspace},configuration(flags.profile))));return;
+ }
+ const name={list:'campaign_list',show:'campaign_get',create:'campaign_create',update:'campaign_update',transition:'campaign_transition',successor:'campaign_successor',events:'campaign_events',pace:flags['per-day']===undefined&&flags['max-credits']===undefined?'campaign_pace_get':'campaign_pace_set'}[command];
+ if(!name||position.length!==(['list','create'].includes(command)?2:3))throw new Error('Use campaign list|summary|show ID|create|update ID|transition ID|successor ID|events ID|pace ID [--per-day N|derived] [--max-credits C|none]|find ID --count N --max-credits C|check ID --url URL|targets ID [--add|--remove|--set].');
+ if(flags['per-day']!==undefined&&command!=='pace')throw new Error('Set the pace with campaign pace ID --per-day N|derived, after the campaign is saved.');
+ const input={workspaceId:flags.workspace};
+ if(position[2])input.campaignId=position[2];
+ if(['list','events'].includes(command)){
+  if(flags.archived!==undefined&&!['true','false'].includes(flags.archived))throw new Error('Archived must be true or false.');
+  if(flags.archived!==undefined)input.archived=flags.archived==='true';
+  if(flags.limit!==undefined)input.limit=Number(flags.limit);
+  if(flags.after)input.after=flags.after;
+  if(flags.q!==undefined)input.q=flags.q;if(flags.state!==undefined)input.state=flags.state;
+ }
+ if(command==='show'&&flags.revision!==undefined)input.revision=Number(flags.revision);
+ if(['create','update','successor'].includes(command)){if(!flags.file)throw new Error('Supply --file PATH containing Campaign fields.');input.fields=readJsonFile(flags.file,65536,'Campaign file');}
+ if(['create','successor'].includes(command))input.requestId=flags['request-id'];
+ if(['update','successor'].includes(command))input.expectedRevision=Number(flags['expected-revision']);
+ if(command==='transition'){input.operation=flags.operation;input.expectedState=flags['expected-state'];if(flags.reason!==undefined)input.reason=flags.reason;}
+ if(command==='pace'&&flags['per-day']!==undefined){const v=flags['per-day'];if(v!=='derived'&&!/^\d+$/.test(v))throw new Error('Pace must be a whole number of people a day, or derived.');input.perDay=v==='derived'?v:Number(v);}
+ if(command==='pace'&&flags['max-credits']!==undefined){const v=flags['max-credits'];if(v!=='none'&&!/^\d+$/.test(v))throw new Error('The credit cap must be a whole number of credits a day, or none.');input.maxCredits=v==='none'?null:Number(v);}
+ console.log(JSON.stringify(await callWorkspace(name,input,configuration(flags.profile))));
+}