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

package/cli/agents.mjs

@@ -2,8 +2,13 @@ import { readProfile, writeProfile, validateUrl, configuration, WorkspaceRequest
 import { z } from 'zod';
 import {readJsonFile} from './json-file.mjs';
 
-export const agentManagementOperations = ['agent_list','agent_revoke','agent_permission','agent_capabilities_get','agent_capability_sharing_get','agent_capability_sharing_set','agent_account_authorizations_get','agent_account_authorization_set'];
+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);
+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_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()},
  agent_account_authorizations_show:{schema:z.object({}).strict()},
  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()},
@@ -13,7 +18,8 @@ export const agentOperations = {
  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()},
- agent_connect: { schema: z.object({ name: z.string().trim().min(1).max(80) }).strict() },
+ agent_capabilities_set: {schema:z.object({id:z.string().uuid(),capabilities:z.array(z.enum(['find','enrich','listen','approve'])).min(1).max(4)}).strict()},
+ agent_connect: { schema: z.object({ name: z.string().trim().min(1).max(80), capabilities: z.array(z.enum(['find','enrich','listen','approve'])).max(4).optional() }).strict() },
  agent_poll: { schema: z.object({}).strict() },
  agent_cancel: { schema: z.object({}).strict() },
  agent_list: { schema: z.object({}).strict() },
@@ -44,6 +50,11 @@ export async function callAgent(name, args, config, profilePath) {
  }
  if (name === 'agent_capability_sharing_get') return {data:await request(config,`/agents/${input.data.id}/capability-sharing`,undefined,true)};
  if (name === 'agent_capability_sharing_set') {const {id,...body}=input.data;return {data:await request(config,`/agents/${id}/capability-sharing`,body,true)};}
+ if (name === 'agent_inventory_get') return {data:await request(config,`/agents/${input.data.id}/inventory`,undefined,true)};
+ if (name === 'agent_inventory_show' || name === 'agent_inventory_report') {
+  if (!config.profile?.agent || !/^agt_/.test(config.token ?? '')) throw new Error('Use an active agent profile for tool inventory report and self readback.');
+  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_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.');
@@ -51,6 +62,7 @@ export async function callAgent(name, args, config, profilePath) {
  }
  if (name === 'agent_list') return { data: await request(config, '/agents', undefined, true) };
  if (name === 'agent_permission') return {data:await request(config, `/agents/${input.data.id}/permission`, {scope:input.data.scope}, true)};
+ if (name === 'agent_capabilities_set') return {data:await request(config, `/agents/${input.data.id}/approved-capabilities`, {capabilities:input.data.capabilities}, true)};
  if (name === 'agent_revoke') return { data: await request(config, `/agents/${input.data.id}/revoke`, {}, true) };
  if (!profilePath) throw new Error('Use a separate private --profile PATH for each agent.');
  const profile = readProfile(profilePath);
@@ -83,19 +95,25 @@ export async function agentCli(args) {
   if (args[i] === '--json') continue;
   if (args[i].startsWith('--')) {
    const key = args[i].slice(2);
-   if (!['profile', 'name','scope','file','id','provider','account','workspace','shared','authorized'].includes(key) || !args[i+1] || args[i+1].startsWith('--')) throw new Error('Unknown or incomplete agent option.');
+   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.');
    flags[key] = args[++i];
   } else positions.push(args[i]);
  }
  let name = `agent_${positions[1]}`;
- let input = positions[1] === 'permission' ? {id:positions[2],scope:flags.scope} : positions[1] === 'connect' ? { name: flags.name } : positions[1] === 'revoke' ? { id: positions[2] } : {};
+ let input = positions[1] === 'permission' ? {id:positions[2],scope:flags.scope} : positions[1] === 'connect' ? { name: flags.name, ...(flags.capabilities ? { capabilities: flags.capabilities.split(',').map(key => key.trim()).filter(Boolean) } : {}) } : positions[1] === 'revoke' ? { id: positions[2] } : {};
  if(positions[1]==='accounts') {
   if(positions[2]==='show') {name=flags.id ? 'agent_account_authorizations_get' : 'agent_account_authorizations_show';input=flags.id ? {id:flags.id} : {};}
   else if(positions[2]==='authorize' && ['true','false'].includes(flags.authorized)) {name='agent_account_authorization_set';input={id:flags.id,provider:flags.provider,accountRef:flags.account,authorized:flags.authorized==='true'};}
   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');}
+  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].');
+ }
  if (positions[1] === 'capabilities') {
-  if (positions[2] === 'sharing' && flags.id) {name='agent_capability_sharing_get';input={id:flags.id};}
+  if (flags.set !== undefined && positions[2]) {name='agent_capabilities_set';input={id:positions[2],capabilities:flags.set.split(',').map(key => key.trim()).filter(Boolean)};}
+  else  if (positions[2] === 'sharing' && flags.id) {name='agent_capability_sharing_get';input={id:flags.id};}
   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} : {};}

package/cli/approach-operations.mjs

@@ -13,10 +13,12 @@ const base=a=>`/workspaces/${a.workspaceId}`,query=(a,skip=[])=>new URLSearchPar
 export const approachOperations={
  approach_list:{schema:z.object({...scope,cursor:uuid.optional(),limit:z.number().int().min(1).max(100).optional()}).strict(),method:'GET',path:a=>`${base(a)}/approaches?${query(a)}`,scoped:true,description:'List immutable versioned approaches in the current workspace. Free CRM read.'},
  approach_get:{schema:z.object({...scope,id:uuid,revision:z.number().int().positive().optional()}).strict(),method:'GET',path:a=>`${base(a)}/approaches/${a.id}?${query(a,['id'])}`,scoped:true,description:'Read an approach version: stage plays, step waits, completion, goal, voice and agent rules. Instructions are executed by the external agent, never by a hosted sequence runner.'},
- approach_save:{schema:z.object({...scope,id:uuid.optional(),requestId:uuid,expectedRevision:z.number().int().nonnegative(),fields}).strict(),method:'POST',path:a=>`${base(a)}/approaches`,body:({workspaceId,...a})=>a,scoped:true,description:'Create or revise an approach with optimistic version and idempotent request. Does not change existing experiment or participation pins.'},
+ approach_save:{schema:z.object({...scope,id:uuid.optional(),requestId:uuid,expectedRevision:z.number().int().nonnegative(),fields}).strict(),method:'POST',path:a=>`${base(a)}/approaches`,body:({workspaceId,...a})=>a,scoped:true,description:'Create or revise an approach with optimistic version and idempotent request. Does not change existing campaign or participation pins.'},
+ workspace_pipeline_get:{schema:z.object({...scope,campaignId:uuid.optional(),pinId:uuid.optional()}).strict(),method:'GET',path:a=>`${base(a)}/pipeline?${query(a)}`,scoped:true,description:'Read the pipeline board: stages of one approach version, the people currently in each stage, and counts of people closed out through each off-ramp. Free CRM read.'},
  approach_progress_get:{schema:z.object({...scope,participationId:uuid}).strict(),method:'GET',path:a=>`${base(a)}/participations/${a.participationId}/progress`,scoped:true,description:'Read the participation’s admitted approach pin and recorded stage/outcome history.'},
  approach_progress_record:{schema:z.object({...scope,participationId:uuid,expectedVersion:z.number().int().nonnegative(),requestId:uuid,stageKey:uuid.optional(),offRampKey:uuid.optional(),finishStage:z.literal(true).optional(),reason:z.string().trim().min(1).max(2000),evidence:z.array(z.object({kind:z.enum(['observation','conversation']),id:uuid}).strict()).max(20)}).strict(),method:'POST',path:a=>`${base(a)}/participations/${a.participationId}/progress`,body:({workspaceId,participationId,...a})=>a,scoped:true,description:'Report a stage, off-ramp, or finishStage:true after externally completing the current play and waits. Finish resolves next/stay/off-ramp from the admitted version. Stored evidence required for agents; human-review and backward-move rules apply. Assigned owner/Admin only. Goal ends prospecting; post-goal forward reporting never reactivates. No send or provider call.'},
  approach_progress_suggest:{schema:z.object({...scope,participationId:uuid,expectedVersion:z.number().int().nonnegative(),requestId:uuid,stageKey:uuid.optional(),offRampKey:uuid.optional(),finishStage:z.literal(true).optional(),reason:z.string().trim().min(1).max(2000),evidence:z.array(z.object({kind:z.enum(['observation','conversation']),id:uuid}).strict()).max(20)}).strict(),method:'POST',path:a=>`${base(a)}/participations/${a.participationId}/suggestions`,body:({workspaceId,participationId,...a})=>a,scoped:true,description:'Suggest a pinned stage move, off-ramp or play completion for human review in Operator. Stored evidence required. Does not change progress or send anything. Assigned owner/Admin; current human approval revalidates progress.'},
+ approach_suggestion_decide:{schema:z.object({...scope,id:uuid,requestId:uuid,decision:z.enum(['approve','dismiss'])}).strict(),method:'POST',path:a=>`${base(a)}/approach-suggestions/${a.id}/decision`,body:({workspaceId,id,...a})=>a,scoped:true,description:'Approve or dismiss a pending stage suggestion. People only: the current owner or an Admin. Approving moves the participation to the suggested stage.'},
  approach_suggestions_list:{schema:z.object({...scope,cursor:uuid.optional(),limit:z.number().int().min(1).max(100).optional()}).strict(),method:'GET',path:a=>`${base(a)}/approach-suggestions?${query(a)}`,scoped:true,description:'List pending stage suggestions visible to the current owner or Admin. Humans approve or dismiss in Operator; agents cannot approve.'},
- workspace_analytics_get:{schema:z.object({...scope,experimentId:uuid.optional(),pinId:uuid.optional(),from:z.string().datetime(),to:z.string().datetime()}).strict(),method:'GET',path:a=>`${base(a)}/analytics?${query(a)}`,scoped:true,description:'Read UTC-period distinct outcomes and explicit stage events. Missing activity or cost attribution is not tracked, never fabricated zero. Maximum 366 days; narrow large scopes.'}
+ workspace_analytics_get:{schema:z.object({...scope,campaignId:uuid.optional(),ownerUserId:uuid.optional(),offerId:uuid.optional(),audienceId:uuid.optional(),tag:z.string().min(1).max(64).optional(),pinId:uuid.optional(),from:z.string().datetime(),to:z.string().datetime()}).strict(),method:'GET',path:a=>`${base(a)}/analytics?${query(a)}`,scoped:true,description:'Read UTC-period distinct outcomes and explicit stage events. Missing activity or cost attribution is not tracked, never fabricated zero. Optional filters: campaignId, ownerUserId (campaign owner), offerId, audienceId, tag (campaign tag); list the values with workspace_analytics_filters. Maximum 366 days; narrow large scopes.'}
 };

package/cli/assignment-operations.mjs

@@ -18,7 +18,7 @@ const location = z
   .strict();
 const criteria = z
   .object({
-    experimentIds: z.array(uuid).max(50).optional(),
+    campaignIds: z.array(uuid).max(50).optional(),
     companyLocations: z.array(location).max(50).optional(),
     personLocations: z.array(location).max(50).optional(),
     personTitles: z.array(z.string()).max(50).optional(),
@@ -38,7 +38,7 @@ const person = (a) => `${root(a)}/prospects/${a.prospectId}`;
 const omit = (a, keys) =>
   Object.fromEntries(Object.entries(a).filter(([k]) => !keys.includes(k)));
 const body = (a) => omit(a, ["workspaceId", "prospectId"]);
-function qs(a, keys = ["workspaceId", "prospectId", "experimentId"]) {
+function qs(a, keys = ["workspaceId", "prospectId", "campaignId"]) {
   const values = {};
   for (const [k, v] of Object.entries(omit(a, keys))) {
     if (v === undefined) continue;
@@ -56,7 +56,7 @@ export const assignmentOperations = {
         ...workspace,
         assignedToUserId: uuid.optional(),
         unassigned: z.boolean().optional(),
-        experimentId: uuid.optional(),
+        campaignId: uuid.optional(),
         search: z.string().optional(),
         cursor: uuid.optional(),
         limit: z.number().int().min(1).max(100).optional(),
@@ -81,17 +81,17 @@ export const assignmentOperations = {
     path: (a) => person(a) + "/assignment?" + qs(a),
     scoped: true,
   },
-  workspace_prospect_experiment_fit: {
+  workspace_prospect_campaign_fit: {
     schema: z
       .object({
         ...workspace,
         prospectId: uuid,
-        experimentId: uuid,
+        campaignId: uuid,
         overrides: page.optional(),
       })
       .strict(),
     method: "GET",
-    path: (a) => person(a) + `/experiments/${a.experimentId}/fit?` + qs(a),
+    path: (a) => person(a) + `/campaigns/${a.campaignId}/fit?` + qs(a),
     scoped: true,
   },
   workspace_prospect_assignment_set: {
@@ -133,7 +133,7 @@ export const assignmentOperations = {
       .object({
         ...request,
         prospectId: uuid,
-        experimentId: uuid.optional(),
+        campaignId: uuid.optional(),
         expectedAssignmentVersion: version,
         rulesVersion: version,
         outcomes: z
@@ -160,8 +160,8 @@ export const assignmentOperations = {
       .object({
         ...request,
         prospectId: uuid,
-        experimentId: uuid,
-        experimentRevision: z.number().int().positive(),
+        campaignId: uuid,
+        campaignRevision: z.number().int().positive(),
         expectedOverrideVersion: version,
         action: z.enum(["set", "clear"]),
         value: z.enum(["high", "moderate", "low", "no_fit"]).optional(),
@@ -179,9 +179,9 @@ export const assignmentOperations = {
         ...request,
         prospectId: uuid,
         expectedSourceParticipationId: uuid,
-        sourceExperimentId: uuid,
-        destinationExperimentId: uuid,
-        destinationExperimentRevision: z.number().int().positive(),
+        sourceCampaignId: uuid,
+        destinationCampaignId: uuid,
+        destinationCampaignRevision: z.number().int().positive(),
         destinationQualificationReceiptId: uuid,
         expectedAssignmentVersion: version,
         reason: z.string(),

package/cli/assignment.mjs

@@ -25,7 +25,7 @@ export async function assignmentCli(args) {
     "file",
     "request-id",
     "prospect-id",
-    "experiment-id",
+    "campaign-id",
     "assigned-to-user-id",
     "unassigned",
     "search",
@@ -54,8 +54,8 @@ export async function assignmentCli(args) {
     "workspace assignments list": "workspace_prospect_assignments",
     "workspace prospect assignment get": "workspace_prospect_assignment",
     "workspace prospect assignment set": "workspace_prospect_assignment_set",
-    "workspace prospect experiment-fit get":
-      "workspace_prospect_experiment_fit",
+    "workspace prospect campaign-fit get":
+      "workspace_prospect_campaign_fit",
     "workspace routing-rules get": "workspace_routing_rules_get",
     "workspace routing-rules replace": "workspace_routing_rules_replace",
     "workspace routing apply": "workspace_routing_apply",
@@ -68,12 +68,12 @@ export async function assignmentCli(args) {
   const name = names[command];
   if (!name)
     throw new Error(
-      "Unknown assignment command. Use workspace assignments list, prospect assignment get/set, routing-rules get/replace, routing apply, prospect experiment-fit get, prospect fit-override set/clear, prospect move, member remove, or leave. Mutations require --file INPUT.json.",
+      "Unknown assignment command. Use workspace assignments list, prospect assignment get/set, routing-rules get/replace, routing apply, prospect campaign-fit get, prospect fit-override set/clear, prospect move, member remove, or leave. Mutations require --file INPUT.json.",
     );
   const read = [
     "workspace_prospect_assignments",
     "workspace_prospect_assignment",
-    "workspace_prospect_experiment_fit",
+    "workspace_prospect_campaign_fit",
     "workspace_routing_rules_get",
   ].includes(name);
   let input = read ? {} : readJsonFile(flags.file, 65536, "Assignment file");
@@ -81,7 +81,7 @@ export async function assignmentCli(args) {
     ["workspace", "workspaceId"],
     ["request-id", "requestId"],
     ["prospect-id", "prospectId"],
-    ["experiment-id", "experimentId"],
+    ["campaign-id", "campaignId"],
     ["assigned-to-user-id", "assignedToUserId"],
     ["search", "search"],
     ["cursor", "cursor"],

package/cli/audience-operations.mjs

@@ -13,4 +13,9 @@ 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_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.'},
+ audience_prospect_test:{schema:z.object({...locator,url:z.string(),requestId:uuid,revision:z.number().int().positive().optional()}).strict(),method:'POST',path:a=>path(a)+`/${a.audienceId}/prospect-tests`,body:a=>({url:a.url,requestId:a.requestId,...(a.revision?{revision:a.revision}:{})}),scoped:true,description:'Check one LinkedIn person URL against the Audience rules and name the deciding rule. Read-only: never admits the person. Saved profiles are reused free; otherwise the person and company fetches spend hosted credits. Generate requestId once and reuse it after an interruption so a retry never pays twice.'},
 };

package/cli/audiences.mjs

@@ -3,11 +3,11 @@ import {readJsonFile} from './json-file.mjs';
 export async function audienceCli(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','kind'].includes(key)||!args[i+1]||args[i+1].startsWith('--')||Object.hasOwn(flags,key))throw new Error('Unknown or incomplete audience option.');
+  const key=args[i].slice(2);if(!['profile','workspace','file','request-id','expected-revision','revision','archived','limit','after','q','kind','url','audience','text'].includes(key)||!args[i+1]||args[i+1].startsWith('--')||Object.hasOwn(flags,key))throw new Error('Unknown or incomplete audience option.');
   flags[key]=args[++i];
  }
- const command=position[1],name={options:'audience_options',list:'audience_list',show:'audience_get',create:'audience_create',update:'audience_update',archive:'audience_archive',restore:'audience_restore'}[command];
- if(!name||position.length!==(['list','create','options'].includes(command)?2:3))throw new Error('Use audience options --kind KIND [--q TEXT]|list|show ID|create|update ID|archive ID|restore ID.');
+ const command=position[1],name={options:'audience_options',list:'audience_list',show:'audience_get',create:'audience_create',update:'audience_update',archive:'audience_archive',restore:'audience_restore',summary:'audience_summary',people:'audience_people',companies:'audience_companies',test:'audience_prospect_test',improve:'audience_fit_check_improve'}[command];
+ if(!name||position.length!==(['list','create','options','summary','improve'].includes(command)?2:3))throw new Error('Use audience options --kind KIND [--q TEXT]|list|show ID|create|update ID|archive ID|restore ID|summary|people ID|companies ID|test ID --url URL --request-id UUID [--revision N]|improve --text RULE.');
  const input={workspaceId:flags.workspace};
  if(position[2])input.audienceId=position[2];
  if(command==='options'){input.kind=flags.kind;if(flags.q!==undefined)input.q=flags.q;}
@@ -18,7 +18,10 @@ export async function audienceCli(args){
   if(flags.after)input.after=flags.after;
   if(flags.q!==undefined)input.q=flags.q;
  }
- if(command==='show'&&flags.revision!==undefined)input.revision=Number(flags.revision);
+ if(command==='summary'&&flags.audience!==undefined)input.audienceId=flags.audience;
+ if(command==='test'){if(!flags.url)throw new Error('Supply --url with a LinkedIn profile URL.');input.url=flags.url;input.requestId=flags['request-id'];}
+ if(command==='improve'){if(!flags.text)throw new Error('Supply the smart rule with --text.');input.text=flags.text;}
+ if(['show','test'].includes(command)&&flags.revision!==undefined)input.revision=Number(flags.revision);
  if(['create','update'].includes(command)){if(!flags.file)throw new Error('Supply --file PATH containing Audience fields.');input.fields=readJsonFile(flags.file,65536,'Audience file');}
  if(command==='create')input.requestId=flags['request-id'];
  if(command==='update')input.expectedRevision=Number(flags['expected-revision']);

package/cli/audienti.mjs

@@ -12,7 +12,7 @@ Usage: audienti whoami [--json]
        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,10 +23,13 @@ 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 [--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
 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
 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
@@ -35,9 +38,18 @@ 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 feedback: work changes request|list|get|respond|withdraw PLAN --workspace ID
 Work: work plan save|list|show|approve|withdraw-approval|cancel|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]
 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]
            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)
+           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)
 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]
@@ -47,13 +59,32 @@ Discovery: prospects list|get ID|observation create|citation create|evidence cre
            prospects contacts list|record PERSON --workspace ID
            prospects contacts get|retire PERSON CONTACT --workspace ID
            prospects suppression get|set ID --workspace ID
-Qualification: experiments qualification submit --file INPUT.json
+           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
+           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 [--experiment ID] [--approach-version ID]
+Analytics: analytics show --from ISO --to ISO [--campaign ID] [--approach-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]
 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)
 Save an environment token: profile save --scope account:read|workspace:access|agents:manage --profile PATH
@@ -67,16 +98,27 @@ async function main() {
   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]==='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]==='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(['approach','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]==='rooms'){const {roomsCli}=await import('./rooms.mjs');await roomsCli(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; }

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-operations.mjs

@@ -0,0 +1,26 @@
+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(),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',[
+ 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(),
+]).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, approach, 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_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/{experiments.mjs → campaigns.mjs}

@@ -1,15 +1,15 @@
 import {callWorkspace,configuration} from './workspaces.mjs';
 import {readJsonFile} from './json-file.mjs';
-export async function experimentCli(args){
+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'].includes(key)||!args[i+1]||args[i+1].startsWith('--')||Object.hasOwn(flags,key))throw new Error('Unknown or incomplete experiment option.');
+  const key=args[i].slice(2);if(!['profile','workspace','file','request-id','expected-revision','revision','archived','limit','after','q','state','operation','expected-state','reason'].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],name={list:'experiment_list',show:'experiment_get',create:'experiment_create',update:'experiment_update',transition:'experiment_transition',successor:'experiment_successor',events:'experiment_events'}[command];
- if(!name||position.length!==(['list','create'].includes(command)?2:3))throw new Error('Use experiment list|show ID|create|update ID|transition ID|successor ID|events ID.');
+ const command=position[1],name={list:'campaign_list',show:'campaign_get',create:'campaign_create',update:'campaign_update',transition:'campaign_transition',successor:'campaign_successor',events:'campaign_events'}[command];
+ if(!name||position.length!==(['list','create'].includes(command)?2:3))throw new Error('Use campaign list|show ID|create|update ID|transition ID|successor ID|events ID.');
  const input={workspaceId:flags.workspace};
- if(position[2])input.experimentId=position[2];
+ 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';
@@ -18,7 +18,7 @@ export async function experimentCli(args){
   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 Experiment fields.');input.fields=readJsonFile(flags.file,65536,'Experiment file');}
+ 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;}

package/cli/cohort-operations.mjs

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+const uuid = z.string().uuid();
+const filters = { workspaceId: uuid.optional(), campaignId: uuid.optional(), ownerUserId: uuid.optional(), offerId: uuid.optional(), audienceId: uuid.optional(), tag: z.string().min(1).max(64).optional() };
+const FILTER_TEXT = 'Filters (all optional, combined with AND): campaignId, ownerUserId (the campaign owner), offerId and audienceId (as pinned by the campaign), tag (a campaign tag). List the values with workspace_analytics_filters.';
+const path = name => a => {
+ const query = new URLSearchParams(Object.entries(a).filter(([key, value]) => key !== 'workspaceId' && value !== undefined).map(([key, value]) => [key, String(value)]));
+ return `/workspaces/${a.workspaceId}/analytics/${name}${query.size ? `?${query}` : ''}`;
+};
+export const cohortOperations = {
+ workspace_analytics_cohorts: {
+  schema: z.object({ ...filters, stage: z.string().min(1).max(100).optional(), cohorts: z.number().int().min(1).max(52).optional(), horizon: z.number().int().min(1).max(26).optional() }).strict(), method: 'GET', path: path('cohorts'), scoped: true,
+  description: `Weekly entry cohorts: people grouped by the UTC week (Monday start) they were admitted to a campaign, and for each week since admission the share that reached a stage. stage is "goal" (default, each approach's goal) or a stage key from the stages list in the response. cohorts is the number of weeks (default 12, at most 52); horizon is the number of weeks since entry shown after week 0 (default 8, at most 26). A cell is empty (null) until every member of the cohort has had that long. ${FILTER_TEXT} Same figures as Analytics > Cohorts.`,
+ },
+ workspace_stage_aging: {
+  schema: z.object({ ...filters, thresholdDays: z.number().int().min(1).max(365).optional() }).strict(), method: 'GET', path: path('stage-aging'), scoped: true,
+  description: `Stage aging: how long people still active in a campaign have been in their current stage, by stage: count, median days, 90th percentile days, oldest, and how many are over thresholdDays (default 7). ${FILTER_TEXT} Same figures as Analytics > Stage aging.`,
+ },
+ workspace_analytics_filters: {
+  schema: z.object({ workspaceId: uuid.optional() }).strict(), method: 'GET', path: path('filters'), scoped: true,
+  description: 'List the values the analytics filters can take in this workspace: campaigns, campaign owners, offers, audiences and campaign tags, with ids and names. Use the ids with workspace_analytics_get, workspace_analytics_cohorts and workspace_stage_aging.',
+ },
+};