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

package/cli/tools.mjs

@@ -1,15 +1,25 @@
-import { z } from 'zod';
+import { randomUUID } from 'node:crypto';
 import { hostedToolOperations, paidToolByName, isPaidToolOperation, paidToolResult } from './tools-operations.mjs';
 import { parseArgs } from 'node:util';
 import { readJsonFile } from './json-file.mjs';
 import { callWorkspace, configuration } from './workspaces.mjs';
 const help = `Usage:
-  audienti tools list [--workspace UUID] [--json]
-  audienti tools proxy.sessions.close UUID [--workspace UUID]
-  audienti tools describe decide|email.verify|email.find|mobile.find|profiles.fetch|posts.fetch|posts.search|posts.comments|posts.reactions|profiles.posts|profiles.search|proxy.sessions.create|web.search|web.fetch
-  audienti tools decide|email.verify|email.find|mobile.find|profiles.fetch|posts.fetch|posts.search|posts.comments|posts.reactions|profiles.posts|profiles.search|proxy.sessions.create|web.search|web.fetch --input FILE|- --request-id UUID [--workspace UUID] [--json]
+  audienti call TOOL ['JSON_INPUT'] [--input FILE|-] [--request-id UUID] [--workspace UUID] [--json]
+  audienti tools search "WORDS" [--limit N] [--workspace UUID]   one server search over tools, audienti commands and skills; rows: id, kind, description, price
+  audienti tools get TOOL [--workspace UUID]         one tool: inputs, price, availability, your 30-day success rate and speed
+  audienti tools list [--workspace UUID] [--json]    the whole catalog
   audienti tools runs get UUID [--attempt-after ORDINAL] [--entry-after UUID] | list [--cursor UUID]
   audienti tools balance
+  audienti tools NAME --input FILE|- --request-id UUID [--workspace UUID] [--json]   same as call NAME; kept for existing scripts
+  audienti tools proxy.sessions.close UUID [--workspace UUID]
+
+The server catalog is the only source of tool names, inputs and prices: run tools search or tools get, then call.
+call sends {tool,requestId,input} to one route for every tool. Published ids look like audienti.email.verify;
+an old name (for example profiles.enrich) resolves on the server. A tool with no configured provider is not listed or callable.
+Record tools (profile read and enrich, email and mobile find, email.verify, web.search) reuse a saved record when one is
+current; put "cached":false in the input to skip it, make a fresh paid call and save the result.
+Without --request-id, call generates one and prints it to stderr. Save it: replaying the same ID is free and
+returns the saved result; a new ID is a new purchase.
 
 email.find and mobile.find may return running: poll tools runs get OPERATION_ID.
 Keep the same request ID after interruptions; never submit a new one to retry a purchase.
@@ -23,12 +33,12 @@ profiles.fetch accepts a person /in/ or company /company/ URL as {url,fields?,re
 Explicit refresh requires paid admission; the result includes saved profile/prospect IDs.
 Fields: name, headline, about, location, experience, currentPositions, education, skills,
 websites, photo, connections, followers, certifications, languages. Company-specific fields:
-industries, employeeCount, employeeCountRange, founded, specialities, locations.
+industries, employeeCount, employeeCountRange, founded, specialities, locations, companyType.
 profiles.enrich accepts the same fields as profiles.fetch, using url or saved profileId.
 Its operation has the same admission identity as profiles.fetch; the Prospect projection is a current free read.
 profiles.discover is the clear external-search alias of profiles.search; profiles list searches saved workspace records.
 profiles.search accepts person filters or {kind:"company",query,companySizes?}; results are partial profiles.
-Use describe for exact fields. No implicit email lookup.
+Use tools get TOOL for exact fields. No implicit email lookup.
 decide accepts {state,questions}; question types: boolean, choice, score.
 Questions have instructions; choice requires named criteria; score criteria are ordered
 from level zero. State is text, an object or an array. At most 32 KiB, 16 questions,
@@ -43,13 +53,41 @@ async function readStdin() {
  for await(const chunk of process.stdin){size+=chunk.length;if(size>32768)throw new Error('Tool input exceeds 32 KiB.');chunks.push(chunk);}
  try{return JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(Buffer.concat(chunks)));}catch{throw new Error('Tool input must be valid UTF-8 JSON.');}
 }
+const asJson=value=>{try{return JSON.parse(value);}catch{throw new Error('Tool input must be valid JSON.');}};
+async function printPaid(name,args,values){
+ try{
+  const result=await callWorkspace(name,args,configuration(values.profile));
+  const paidResult=paidToolResult(name,result?.data,args);
+  if(['failed','uncertain','rejected'].includes(paidResult?.status)){
+   process.stderr.write(JSON.stringify({error:{code:paidResult.error?.code??'tool_incomplete'},operationId:paidResult.operationId,requestId:args.requestId,billing:paidResult.billing,...(paidResult.result?.persistence?{result:paidResult.result}:{}),requestTraceId:result.requestTraceId,recovery:paidResult.status==='rejected'?'resolve_rejection_then_new_request_id':paidResult.result?.persistence?.recovery??'retry_same_request_id'})+'\n');process.exitCode=1;return;
+  }
+  console.log(JSON.stringify(result));
+ }catch(error){
+  if(isPaidToolOperation(name,args))process.stderr.write(`Retain request ID ${args.requestId}; retry with the same ID to inspect/recover this operation.\n`);
+  throw error;
+ }
+}
+const parseOptions={help:{type:'boolean',short:'h'},json:{type:'boolean'},input:{type:'string'},'request-id':{type:'string'},workspace:{type:'string'},profile:{type:'string'},cursor:{type:'string'},limit:{type:'string'},'attempt-after':{type:'string'},'entry-after':{type:'string'}};
+/** audienti call TOOL ['JSON'] : one generic route for every catalog tool. */
+export async function callCli(argv) {
+ const {positionals,values}=parseArgs({args:argv.slice(1),allowPositionals:true,strict:true,options:parseOptions});
+ if(values.help||positionals.length===0){console.log(help);return;}
+ const [tool,inline]=positionals;
+ if(positionals.length>2||(inline!==undefined&&values.input))throw new Error('Give the input once: a JSON argument or --input FILE|-.');
+ const input=inline!==undefined?asJson(inline):values.input?(values.input==='-'?await readStdin():readJsonFile(values.input,32768,'Tool input')):{};
+ if(!input||typeof input!=='object'||Array.isArray(input))throw new Error('Tool input must be a JSON object.');
+ const requestId=values['request-id']??randomUUID();
+ if(!values['request-id'])process.stderr.write(`request-id: ${requestId}\n`);
+ await printPaid('tools_call',{workspaceId:values.workspace,tool,requestId,input},values);
+}
 export async function toolsCli(argv) {
- const {positionals,values}=parseArgs({args:argv.slice(1),allowPositionals:true,strict:true,options:{help:{type:'boolean',short:'h'},json:{type:'boolean'},input:{type:'string'},'request-id':{type:'string'},workspace:{type:'string'},profile:{type:'string'},cursor:{type:'string'},'attempt-after':{type:'string'},'entry-after':{type:'string'}}});
+ const {positionals,values}=parseArgs({args:argv.slice(1),allowPositionals:true,strict:true,options:parseOptions});
  if(values.help||positionals.length===0){console.log(help);return;}
  const [verb,sub,id]=positionals;
- if(verb==='describe'&&Object.hasOwn(paidToolByName,sub)&&positionals.length===2){console.log(JSON.stringify({name:sub,version:'1',canonicalTool:paidToolByName[sub].canonicalTool??sub,responseOperationPath:paidToolByName[sub].resultKey??null,inputSchema:z.toJSONSchema(paidToolByName[sub].schema.shape.input),limits:paidToolByName[sub].limits??(sub==='decide'?{bytes:32768,depth:32,questions:16,choices:32,scoreLevels:10}:sub==='profiles.fetch'?{providerCalls:1,normalizedBytes:65536,cacheDays:30}:{providerCalls:1,resultCache:false}),retry:'Reuse the same requestId and authenticated principal after interruptions.'},null,values.json?undefined:2));return;}
  let name,args={workspaceId:values.workspace};
  if(verb==='list'&&positionals.length===1)name='tools_list';
+ else if(verb==='search'&&positionals.length>=2){name='tools_search';args.query=positionals.slice(1).join(' ');if(values.limit!==undefined)args.limit=Number(values.limit);}
+ else if((verb==='get'||verb==='describe')&&positionals.length===2){name='tools_get';args.tool=sub;}
  else if(verb==='balance'&&positionals.length===1)name='tools_balance';
  else if(verb==='runs'&&sub==='get'&&positionals.length===3){name='tools_runs_get';args.operationId=id;args.entryAfter=values['entry-after'];if(values['attempt-after']!==undefined)args.attemptAfter=Number(values['attempt-after']);}
  else if(verb==='runs'&&sub==='list'&&positionals.length===2){name='tools_runs_list';args.cursor=values.cursor;}
@@ -58,15 +96,5 @@ export async function toolsCli(argv) {
   if(!values.input||!values['request-id'])throw new Error(`${verb} requires --input FILE|- and --request-id UUID. Keep the request ID for retries.`);
   name=paidToolByName[verb].name;args.requestId=values['request-id'];args.input=values.input==='-'?await readStdin():readJsonFile(values.input,32768,'Tool input');
  }else throw new Error('Unknown tools command. Use audienti tools --help.');
- try{
-  const result=await callWorkspace(name,args,configuration(values.profile));
-  const paidResult = paidToolResult(name,result?.data);
-  if(['failed','uncertain','rejected'].includes(paidResult?.status)){
-   process.stderr.write(JSON.stringify({error:{code:paidResult.error?.code??'tool_incomplete'},operationId:paidResult.operationId,requestId:args.requestId,billing:paidResult.billing,...(paidResult.result?.persistence?{result:paidResult.result}:{}),requestTraceId:result.requestTraceId,recovery:paidResult.status==='rejected'?'resolve_rejection_then_new_request_id':paidResult.result?.persistence?.recovery??'retry_same_request_id'})+'\n');process.exitCode=1;return;
-  }
-  console.log(JSON.stringify(result));
- }catch(error){
-  if(isPaidToolOperation(name))process.stderr.write(`Retain request ID ${args.requestId}; retry with the same ID to inspect/recover this operation.\n`);
-  throw error;
- }
+ await printPaid(name,args,values);
 }

package/cli/usage-operations.mjs

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+export const usageOperations = {
+ workspace_usage_breakdown: {
+  schema: z.object({ workspaceId: z.string().uuid().optional(), period: z.enum(['month', '7d', '30d', '90d']).optional() }).strict(),
+  method: 'GET', path: a => `/workspaces/${a.workspaceId}/usage/breakdown${a.period ? `?period=${a.period}` : ''}`, scoped: true,
+  description: 'Credit cost for a period (default this month) by tool, provider, model and caller, with a zero-filled daily series and share of total. Amounts are pico USD (1 credit = 10,000,000,000). Model is recorded only for AI decision calls. Same figures as Settings > Usage.',
+ },
+};

package/cli/usage.mjs

@@ -0,0 +1,41 @@
+import { callWorkspace, configuration } from './workspaces.mjs';
+
+const PERIODS = { month: 'month', '7d': '7d', '30d': '30d', '90d': '90d' };
+const DIMENSIONS = ['tool', 'provider', 'model', 'caller', 'day'];
+const PICO_PER_CREDIT = 10_000_000_000n;
+const cell = value => { const text = String(value); return /[",\n\r]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text; };
+export function credits(amount) {
+ const value = BigInt(amount), whole = value / PICO_PER_CREDIT, fraction = (value % PICO_PER_CREDIT).toString().padStart(10, '0').replace(/0+$/, '');
+ return fraction ? `${whole}.${fraction}` : String(whole);
+}
+const percent = share => `${(share * 100).toFixed(1)}%`;
+/** Rows for one dimension: a label, calls, credits and share of the period total. */
+export function breakdownRows(data, by) {
+ if (by === 'day') return (data.daily ?? []).map(row => [row.day, row.calls, credits(row.charged), '']);
+ const items = { tool: data.byTool, provider: data.byProvider, model: data.byModel, caller: data.byCaller }[by] ?? [];
+ const name = row => by === 'tool' ? row.tool : by === 'provider' ? row.provider : by === 'model' ? row.model ?? 'Not recorded' : [row.owner, row.keyName, row.agentName].filter(Boolean).join(' / ');
+ return items.map(row => [name(row), row.calls, credits(row.charged), percent(row.share)]);
+}
+export function breakdownCsv(data, by) {
+ return [[by, 'calls', 'credits', 'share'], ...breakdownRows(data, by)].map(row => row.map(cell).join(',')).join('\n') + '\n';
+}
+export async function usageCli(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', 'by', '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] !== 'breakdown') throw Error('Use usage breakdown [--workspace ID] [--since month|7d|30d|90d] [--by tool|provider|model|caller|day] [--format json|csv].');
+ if (flags.since && !PERIODS[flags.since]) throw Error('--since must be month, 7d, 30d or 90d.');
+ if (flags.by && !DIMENSIONS.includes(flags.by)) throw Error('--by must be tool, provider, model, caller or day.');
+ if (flags.format && !['json', 'csv'].includes(flags.format)) throw Error('--format must be json or csv.');
+ const input = { workspaceId: flags.workspace };
+ if (flags.since) input.period = PERIODS[flags.since];
+ const result = await callWorkspace('workspace_usage_breakdown', input, configuration(flags.profile));
+ if (flags.format === 'csv') { process.stdout.write(breakdownCsv(result?.data ?? result, flags.by ?? 'tool')); return; }
+ console.log(JSON.stringify(result));
+}

package/cli/work-execution-operations.mjs

@@ -25,8 +25,15 @@ const body=({workspaceId,planId,clientActionId,attemptId,...rest})=>rest;
 export const workspaceExecutionOperations={
  workspace_work_claim:{schema:z.object({...location,expectedRevision:z.number().int().positive(),requestId:uuid}).strict(),scoped:true,method:'POST',path:a=>`${path(a)}/claims`,body},
  workspace_work_start:{schema:z.object({...location,claimId:uuid,requestId:uuid}).strict(),scoped:true,method:'POST',path:a=>`${path(a)}/start`,body},
+ workspace_work_send:{schema:z.object({...location,claimId:uuid,requestId:uuid}).strict(),scoped:true,method:'POST',path:a=>`${path(a)}/send`,body,description:'LinkedIn accounts connected through Audienti only. Starts the claimed, approved action and sends it once through the managed account, then records the result. Replaying the same claim returns the recorded send; it never sends again.'},
  workspace_work_attempt_get:{schema:z.object({...location,historyCursor:uuid.optional(),historyLimit:z.number().int().min(1).max(100).optional()}).strict(),scoped:true,method:'GET',path:a=>{const q=new URLSearchParams();for(const key of ['historyCursor','historyLimit'])if(a[key]!==undefined)q.set(key,String(a[key]));return `${path(a)}/attempt?${q}`;}},
 };
+// LinkedIn accounts connected through Audienti. Only the user connects one; agents list them and send through work send.
+export const managedAccountOperations={
+ workspace_managed_accounts_list:{schema:z.object({workspaceId:uuid.optional()}).strict(),scoped:true,method:'GET',path:a=>`/workspaces/${a.workspaceId}/managed-accounts`,description:'List the LinkedIn accounts connected through Audienti in this workspace, with their sending account IDs and status.'},
+ workspace_managed_account_plan_set:{schema:z.object({workspaceId:uuid.optional(),managedAccountId:uuid,plan:z.enum(['free','premium_career','premium_business','premium_all_in_one','sales_navigator_core','sales_navigator_advanced','recruiter_lite']).nullable()}).strict(),scoped:true,method:'PUT',path:a=>`/workspaces/${a.workspaceId}/managed-accounts/${a.managedAccountId}/plan`,body:a=>({plan:a.plan}),description:'The user only, not agents. States the LinkedIn plan of a managed account, which sets how long a connection note may be. Pass plan null to clear it; the safer figures then apply. Returns the account.'},
+ workspace_managed_account_connect:{schema:z.object({workspaceId:uuid.optional()}).strict(),scoped:true,method:'POST',path:a=>`/workspaces/${a.workspaceId}/managed-accounts/connect`,body:()=>({}),description:'The user only, not agents. Returns a sign-in link, valid 15 minutes, where the user connects a LinkedIn account through Audienti.'},
+};
 export const narrowExecutionOperations={
  work_claim_release:{schema:z.object({claimId:uuid,requestId:uuid,reason}).strict(),method:'POST',path:a=>`/work-execution/claims/${a.claimId}/release`,body:({claimId,...rest})=>rest},
  work_attempt_lookup:{schema:z.object({claimId:uuid}).strict(),method:'GET',path:a=>`/work-execution/claims/${a.claimId}/attempt`},

package/cli/work-execution.mjs

@@ -12,9 +12,9 @@ export async function workExecutionCli(args) {
   const arg=args[i];if(arg==='--json')continue;if(!arg.startsWith('--')){positions.push(arg);continue;}
   const key=arg.slice(2);if(!['profile','workspace','action','claim','attempt','file','cursor','limit'].includes(key)||Object.hasOwn(flags,key)||!args[i+1]||args[i+1].startsWith('--'))throw Error('Unknown, repeated or incomplete execution option.');flags[key]=args[++i];
  }
- const command=positions[2],workspace=['claim','start','get'].includes(command),read=['get','lookup'].includes(command);
- const names={claim:'workspace_work_claim',start:'workspace_work_start',get:'workspace_work_attempt_get',release:'work_claim_release',lookup:'work_attempt_lookup',report:'work_result_report'};
- if(!names[command]||positions.length!==(workspace?4:3))throw Error('Use work execution claim|start|get PLAN, release|lookup --claim ID, or report --attempt ID.');
+ const command=positions[2],workspace=['claim','start','send','get'].includes(command),read=['get','lookup'].includes(command);
+ const names={claim:'workspace_work_claim',start:'workspace_work_start',send:'workspace_work_send',get:'workspace_work_attempt_get',release:'work_claim_release',lookup:'work_attempt_lookup',report:'work_result_report'};
+ if(!names[command]||positions.length!==(workspace?4:3))throw Error('Use work execution claim|start|send|get PLAN, release|lookup --claim ID, or report --attempt ID.');
  const allowed=['profile',...(workspace?['workspace','action']:command==='report'?['attempt']:['claim']),...(read?command==='get'?['cursor','limit']:[]:['file'])];
  if(Object.keys(flags).some(key=>!allowed.includes(key)))throw Error('Option does not apply to this execution command.');
  if(workspace&&!flags.action)throw Error('This command requires --action.');

package/cli/work-operations.mjs

@@ -5,10 +5,10 @@ const page = z.object({cursor: uuid.optional(), limit: z.number().int().min(1).m
 const clientId = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/);
 const accountRef = z.string().min(1).max(200).regex(/^[A-Za-z0-9@._:+\/-]+$/);
 const evidence = z.array(uuid).max(100);
-const commonAction = {clientActionId: clientId, reason: z.string().min(1), evidenceIds: evidence, replyToEvidenceId: uuid.optional()};
+const commonAction = {clientActionId: clientId, capability: z.enum(['profile.connection.request','profile.message.send']).optional().describe('The owner action: profile.connection.request or profile.message.send on linkedin.send, profile.message.send on email.send. The sending account\'s mode for it decides whether approval is needed or the action is not allowed. Without it the old per-channel automation switch applies, unless a mode restricts it.'), reason: z.string().min(1), evidenceIds: evidence, replyToEvidenceId: uuid.optional(), playbookStepKey: uuid.optional().describe("The playbook step this action runs; a succeeded result starts that step's wait. Saving the plan checks it: the key must name a step of the playbook pinned to the person's active participation in the plan's Campaign, and the step's channel must match the action type (email.send only with an Email step, linkedin.send only with a LinkedIn step); otherwise the save is refused with invalid_fields.")};
 const email = z.object({...commonAction, type:z.literal('email.send'), content:z.object({subject:z.string(),body:z.string()}).strict(),recipient:z.object({prospectId:uuid,email:z.string(),contactId:uuid.optional()}).strict(),sender:z.object({provider:z.literal('email'),accountRef,senderAccountId:uuid.optional()}).strict()}).strict();
-const linkedin = z.object({...commonAction,type:z.literal('linkedin.send'),content:z.object({body:z.string()}).strict(),recipient:z.object({prospectId:uuid,profileUrl:z.string(),contactId:uuid.optional()}).strict(),sender:z.object({provider:z.literal('linkedin'),accountRef,senderAccountId:uuid.optional()}).strict()}).strict();
-const cadence = z.object({clientActionId:clientId,afterClientActionId:clientId.nullable(),trigger:z.literal('reported_success').nullable(),at:z.string().nullable(),waitSeconds:z.number().int().min(0).max(7776000).nullable(),condition:z.literal('no_pending_reply').nullable()}).strict();
+const linkedin = z.object({...commonAction,type:z.literal('linkedin.send'),content:z.object({body:z.string(),attachments:z.array(z.object({id:uuid}).strict()).min(1).max(1).optional()}).strict(),recipient:z.object({prospectId:uuid,profileUrl:z.string(),contactId:uuid.optional()}).strict(),sender:z.object({provider:z.literal('linkedin'),accountRef,senderAccountId:uuid.optional()}).strict()}).strict();
+const cadence = z.object({notBefore:z.string().datetime().optional(),clientActionId:clientId,afterClientActionId:clientId.nullable(),trigger:z.literal('reported_success').nullable(),at:z.string().nullable(),waitSeconds:z.number().int().min(0).max(7776000).nullable(),condition:z.literal('no_pending_reply').nullable()}).strict();
 const located = {...workspace,planId:uuid,clientActionId:clientId};
 const mutation = {...located,expectedRevision:z.number().int().positive(),requestId:uuid};
 const root = a => `/workspaces/${a.workspaceId}`;
@@ -18,11 +18,13 @@ const omit = (a, keys) => Object.fromEntries(Object.entries(a).filter(([k])=>!ke
 const body = a => omit(a,['workspaceId','planId','clientActionId']);
 const qs = values => { const p=new URLSearchParams(); for(const [k,v] of Object.entries(values)) if(v!==undefined)p.set(k,String(v));return p.toString(); };
 export const workOperations = {
- workspace_work_action_plan_save: {schema:z.object({...workspace,planId:uuid.nullable(),prospectId:uuid,experimentId:uuid.nullable(),experimentRevision:z.number().int().positive().nullable(),expectedRevision:version,requestId:uuid,origin:z.discriminatedUnion('kind',[z.object({kind:z.literal('agent'),skill:z.object({id:z.string(),version:z.string()}).strict()}).strict(),z.object({kind:z.literal('human'),editReason:z.string()}).strict()]),rationale:z.string(),evidenceIds:evidence,actions:z.array(z.discriminatedUnion('type',[email,linkedin])).min(1).max(50),cadence:z.array(cadence).max(50)}).strict(), method:'POST',path:a=>`${root(a)}/action-plans`,body:a=>omit(a,['workspaceId']),scoped:true},
- workspace_work_operator_list: {schema:z.object({...workspace,page:page.optional(),filter:z.object({state:z.enum(['open','cancelled','terminal','invalidated']).optional(),reviewStatus:z.enum(['awaiting_revision','invalidated','pending_review','approved','in_progress','reconciliation_required','completed','cancelled']).optional(),search:z.string().optional(),queue:z.enum(['review','blocked','activity']).optional()}).strict().optional()}).strict(),method:'GET',path:a=>`${root(a)}/operator/work?${qs({...a.page,...a.filter})}`,scoped:true},
+ workspace_work_activity_list: {description:'Read recorded workspace Activity, newest first: actor, fact, person, time and recorded status. Human tokens require workspace:access; connected agents require workspace:read and workspace policy access, acting as their user. Stage decisions follow Admin/current-assignee visibility. Fixed pages of 50; reuse search and both cursor fields. Read only, no decision or inferred send success.',schema:z.object({...workspace,search:z.string().trim().max(120).optional(),cursor:z.object({at:z.string().datetime(),id:z.string().max(160)}).strict().optional()}).strict(),method:'GET',path:a=>`${root(a)}/operator/activity?${qs({search:a.search,cursorAt:a.cursor?.at,cursorId:a.cursor?.id})}`,scoped:true},
+ workspace_work_action_plan_save: {schema:z.object({...workspace,planId:uuid.nullable(),prospectId:uuid,campaignId:uuid.nullable(),campaignRevision:z.number().int().positive().nullable(),expectedRevision:version,requestId:uuid,origin:z.discriminatedUnion('kind',[z.object({kind:z.literal('agent'),skill:z.object({id:z.string(),version:z.string()}).strict()}).strict(),z.object({kind:z.literal('human'),editReason:z.string()}).strict()]),rationale:z.string(),evidenceIds:evidence,actions:z.array(z.discriminatedUnion('type',[email,linkedin])).min(1).max(50),cadence:z.array(cadence).max(50)}).strict(), method:'POST',path:a=>`${root(a)}/action-plans`,body:a=>omit(a,['workspaceId']),scoped:true},
+ workspace_work_operator_list: {description:'Read workspace proposals. order=priority matches the Operator queue: open replies first, then oldest proposals, with head-page totals. Omit order for legacy oldest-first order. Keep order and filters unchanged while paging. Read only; grants no execution authority.',schema:z.object({...workspace,order:z.enum(['oldest','priority']).optional(),page:page.optional(),filter:z.object({state:z.enum(['open','cancelled','terminal','invalidated']).optional(),reviewStatus:z.enum(['awaiting_revision','invalidated','pending_review','approved','in_progress','reconciliation_required','completed','skipped','cancelled']).optional(),search:z.string().optional(),queue:z.enum(['review','blocked','activity']).optional()}).strict().optional()}).strict(),method:'GET',path:a=>`${root(a)}/operator/work?${qs({...a.page,...a.filter,order:a.order})}`,scoped:true},
  workspace_work_operator_get: {schema:z.object({...workspace,planId:uuid,revision:z.number().int().positive().optional(),history:page.optional()}).strict(),method:'GET',path:a=>`${plan(a)}?${qs({revision:a.revision,historyCursor:a.history?.cursor,historyLimit:a.history?.limit})}`,scoped:true},
  workspace_work_action_approve: {schema:z.object({...mutation,expectedApprovalVersion:version}).strict(),method:'POST',path:a=>`${action(a)}/approve`,body,scoped:true},
  workspace_work_action_withdraw: {schema:z.object({...mutation,expectedApprovalVersion:z.number().int().positive(),reason:z.string().min(1)}).strict(),method:'POST',path:a=>`${action(a)}/withdraw`,body,scoped:true},
  workspace_work_action_cancel: {schema:z.object({...mutation,reason:z.string().min(1)}).strict(),method:'POST',path:a=>`${action(a)}/cancel`,body,scoped:true},
+ workspace_work_action_skip: {description:'Human only. Skip one pending touch without sending it; the plan continues with its next step. When no touch is left the plan closes and the person stays in the campaign for the next playbook step. Only skipping the playbook\'s last step for the person ends their campaign, with the note skipped by owner; a skipped reply proposal never does, and the reply stays unanswered.',schema:z.object(mutation).strict(),method:'POST',path:a=>`${action(a)}/skip`,body,scoped:true},
  workspace_work_eligibility_get: {schema:z.object(located).strict(),method:'GET',path:a=>`${action(a)}/eligibility`,scoped:true},
 };

package/cli/work.mjs

@@ -2,25 +2,30 @@ import { callWorkspace, configuration } from './workspaces.mjs';
 import { readJsonFile } from './json-file.mjs';
 export async function workCli(args) {
  const flags={}, position=[];
- const allowed=['profile','workspace','file','request-id','plan-id','client-action-id','cursor','limit','history-cursor','history-limit','revision','state','review-status','queue','search'];
+ const allowed=['profile','workspace','file','request-id','plan-id','client-action-id','cursor','limit','history-cursor','history-limit','revision','state','review-status','queue','search','order','cursor-at','cursor-id'];
  for(let i=0;i<args.length;i++) {
   if(args[i]==='--json')continue;
   if(!args[i].startsWith('--')){position.push(args[i]);continue;}
   const key=args[i].slice(2);if(!allowed.includes(key)||Object.hasOwn(flags,key)||args[i+1]===undefined||args[i+1].startsWith('--'))throw new Error('Unknown, repeated, or incomplete work option.');flags[key]=args[++i];
  }
- const names={'work plan save':'workspace_work_action_plan_save','work list':'workspace_work_operator_list','work show':'workspace_work_operator_get','work approve':'workspace_work_action_approve','work withdraw-approval':'workspace_work_action_withdraw','work cancel':'workspace_work_action_cancel','work eligibility':'workspace_work_eligibility_get'};
- const name=names[position.join(' ')];if(!name)throw new Error('Use work plan save, list, show, approve, withdraw-approval, cancel, or eligibility. Writes require --file INPUT.json.');
- const read=['workspace_work_operator_list','workspace_work_operator_get','workspace_work_eligibility_get'].includes(name);
+ const names={'work activity':'workspace_work_activity_list','work plan save':'workspace_work_action_plan_save','work list':'workspace_work_operator_list','work show':'workspace_work_operator_get','work approve':'workspace_work_action_approve','work withdraw-approval':'workspace_work_action_withdraw','work cancel':'workspace_work_action_cancel','work skip':'workspace_work_action_skip','work eligibility':'workspace_work_eligibility_get'};
+ const name=names[position.join(' ')];if(!name)throw new Error('Use work plan save, list, activity, show, approve, withdraw-approval, cancel, skip, or eligibility. Writes require --file INPUT.json.');
+ const read=['workspace_work_activity_list','workspace_work_operator_list','workspace_work_operator_get','workspace_work_eligibility_get'].includes(name);
  const input=read?{}:readJsonFile(flags.file,65536,'Work input');
  for(const [flag,key] of [['workspace','workspaceId'],['request-id','requestId'],['plan-id','planId'],['client-action-id','clientActionId']])if(flags[flag]!==undefined)input[key]=flags[flag];
- if(name==='workspace_work_operator_list'){
+ if(name==='workspace_work_activity_list'){
+  if(flags.search!==undefined)input.search=flags.search;
+  if((flags['cursor-at']===undefined)!==(flags['cursor-id']===undefined))throw new Error('Activity requires both --cursor-at and --cursor-id.');
+  if(flags['cursor-at']!==undefined)input.cursor={at:flags['cursor-at'],id:flags['cursor-id']};
+ } else if(name==='workspace_work_operator_list'){
+  if(flags.order!==undefined)input.order=flags.order;
   input.page={...(flags.cursor===undefined?{}:{cursor:flags.cursor}),...(flags.limit===undefined?{}:{limit:Number(flags.limit)})};
   input.filter={};for(const [flag,key] of [['state','state'],['review-status','reviewStatus'],['search','search'],['queue','queue']])if(flags[flag]!==undefined)input.filter[key]=flags[flag];
  } else if(name==='workspace_work_operator_get'){
   if(flags.revision!==undefined)input.revision=Number(flags.revision);
   input.history={...(flags['history-cursor']===undefined?{}:{cursor:flags['history-cursor']}),...(flags['history-limit']===undefined?{}:{limit:Number(flags['history-limit'])})};
  }
- const applicable=new Set(['profile','workspace','file','request-id','plan-id','client-action-id',...(name==='workspace_work_operator_list'?['cursor','limit','state','review-status','search','queue']:[]),...(name==='workspace_work_operator_get'?['revision','history-cursor','history-limit']:[])]);
+ const applicable=new Set(['profile','workspace','file','request-id','plan-id','client-action-id',...(name==='workspace_work_operator_list'?['cursor','limit','state','review-status','search','queue','order']:[]),...(name==='workspace_work_activity_list'?['search','cursor-at','cursor-id']:[]),...(name==='workspace_work_operator_get'?['revision','history-cursor','history-limit']:[])]);
  if(Object.keys(flags).some(k=>!applicable.has(k)))throw new Error('Option does not apply to this work command.');
  if(read&&flags.file!==undefined)throw new Error('Read commands do not accept --file.');
  console.log(JSON.stringify(await callWorkspace(name,input,configuration(flags.profile))));

package/cli/workspaces.mjs

@@ -1,32 +1,69 @@
-import {approachOperations} from './approach-operations.mjs';
+import {randomUUID} from 'node:crypto';
+import {notificationOperations} from './notification-operations.mjs';
+import {roomsOperations} from './rooms-operations.mjs';
+import {queueOperations} from './queue-operations.mjs';
+import {handTaskOperations} from './hand-task-operations.mjs';
+import {kvOperations} from './kv-operations.mjs';
+import {outcomeOperations} from './outcome-operations.mjs';
+import {attachmentOperations} from './attachment-operations.mjs';
+import {questionOperations} from './question-operations.mjs';
+import {searchOperations} from './search-operations.mjs';
+import {fileOperations,uploadFileContent} from './file-operations.mjs';
+import {playbookOperations} from './playbook-operations.mjs';
 import {connectionRegistryOperations} from './connection-registry-operations.mjs';
+import { budgetOperations } from './budget-operations.mjs';
+import { secretOperations } from './secret-operations.mjs';
 import { hostedToolOperations, paidToolByName, isPaidToolOperation, paidToolResult } from './tools-operations.mjs';
-import { workspaceExecutionOperations } from './work-execution-operations.mjs';
+import { workspaceExecutionOperations, managedAccountOperations } from './work-execution-operations.mjs';
 import { workFeedbackOperations } from './work-feedback-operations.mjs';
 import { accountReplyOperations } from './account-reply-operations.mjs';
 import { accountIntakeOperations } from './account-intake-operations.mjs';
 import { recipientOperations } from './recipient-operations.mjs';
 import { suppressionOperations } from './suppression-operations.mjs';
+import { guardrailsOperations } from './guardrails-operations.mjs';
+import { auditOperations } from './audit-operations.mjs';
+import { usageOperations } from './usage-operations.mjs';
+import { outboundOperations } from './outbound-operations.mjs';
+import { cohortOperations } from './cohort-operations.mjs';
 import { workOperations } from './work-operations.mjs';
 import { assignmentOperations } from './assignment-operations.mjs';
 import {discoveryOperations} from './discovery-operations.mjs';
-import {experimentOperations} from './experiment-operations.mjs';
+import {campaignOperations} from './campaign-operations.mjs';
 import {audienceOperations} from './audience-operations.mjs';
 import { readFileSync, writeFileSync, renameSync, mkdirSync, statSync, lstatSync, realpathSync } from 'node:fs';
 import { dirname, resolve, relative, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import {offerOperations} from './offer-operations.mjs';
+import {readJsonFile} from './json-file.mjs';
 const uuid = z.string().uuid();
 const workspace = { workspaceId: uuid.optional() };
 export const operations = {
- ...approachOperations,
+ ...searchOperations,
+ ...notificationOperations,
+ ...roomsOperations,
+ ...queueOperations,
+ ...handTaskOperations,
+ ...kvOperations,
+ ...outcomeOperations,
+ ...attachmentOperations,
+ ...questionOperations,
+ ...fileOperations,
+ ...playbookOperations,
  ...connectionRegistryOperations,
+ ...budgetOperations,
+ ...secretOperations,
  ...hostedToolOperations,
  ...workOperations,
  ...workspaceExecutionOperations,
+ ...managedAccountOperations,
  ...workFeedbackOperations,
  ...suppressionOperations,
+ ...guardrailsOperations,
+ ...auditOperations,
+ ...usageOperations,
+ ...outboundOperations,
+ ...cohortOperations,
  ...recipientOperations,
  ...accountIntakeOperations,
  ...accountReplyOperations,
@@ -34,8 +71,13 @@ export const operations = {
  ...discoveryOperations,
  ...offerOperations,
  ...audienceOperations,
- ...experimentOperations,
+ ...campaignOperations,
  workspace_sending_settings_get: {schema:z.object({...workspace,userId:uuid.optional()}).strict(),method:'GET',path:a=>`/workspaces/${a.workspaceId}/sending-settings${a.userId?'?userId='+encodeURIComponent(a.userId):''}`,scoped:true,description:'Read workspace sending defaults, or own member effective hours, ramp and activity limits with userId. A workspace Admin may read another member. External activities remain agent-managed; these values do not authorize sending.'},
+ workspace_sending_settings_save: {schema:z.object({...workspace,userId:uuid.optional(),expectedVersion:z.number().int().nonnegative(),expectedDefaultsVersion:z.number().int().nonnegative().optional(),requestId:uuid,reason:z.string().trim().min(1).max(2000),schedule:z.unknown(),limits:z.unknown(),rampPercent:z.union([z.literal(25),z.literal(50),z.literal(75),z.literal(100)]).optional(),raiseEachMonday:z.boolean().optional()}).strict(),method:'POST',path:a=>`/workspaces/${a.workspaceId}/sending-settings`,body:({workspaceId,...a})=>a,scoped:true,description:'Save workspace sending defaults, or one member\'s hours, limits and ramp with userId. People only: agent credentials are refused. Send expectedVersion from the last read; a stale version is rejected. A reason is recorded with the change.'},
+ workspace_usage_summary: {schema:z.object(workspace).strict(),method:'GET',path:a=>`/workspaces/${a.workspaceId}/usage/summary`,scoped:true,description:'Paid tool use for the last 30 days, per tool: operations, cache hits, charged amount (pico USD), pending and expired. Same figures as Settings > Usage.'},
+ workspace_usage_callers: {schema:z.object(workspace).strict(),method:'GET',path:a=>`/workspaces/${a.workspaceId}/usage/callers`,scoped:true,description:'People, agents and API keys that have called paid tools in this workspace, for filtering usage calls.'},
+ workspace_usage_calls: {schema:z.object({...workspace,after:uuid.optional(),caller:z.string().regex(/^(key|agent|user):[0-9a-f-]{36}$/i).optional(),status:z.enum(['all','succeeded','failed','pending']).optional()}).strict(),method:'GET',path:a=>`/workspaces/${a.workspaceId}/usage/calls?${new URLSearchParams(Object.entries(a).filter(([k,v])=>k!=='workspaceId'&&v!==undefined).map(([k,v])=>[k,String(v)]))}`,scoped:true,description:'Paid tool calls, newest first, 50 per page, with counts by status. Filter by caller (user:ID, agent:ID or key:ID) and status.'},
+ workspace_usage_call: {schema:z.object({...workspace,callId:uuid}).strict(),method:'GET',path:a=>`/workspaces/${a.workspaceId}/usage/calls/${a.callId}`,scoped:true,description:'One paid tool call with its request, response and saved result while the payload is kept.'},
  workspace_member: {schema:z.object({...workspace,userId:uuid}).strict(),method:'GET',path:a=>`/workspaces/${a.workspaceId}/members/${a.userId}`,scoped:true},
  workspace_agent_access: { schema:z.object(workspace).strict(), method:'GET', path:a=>`/workspaces/${a.workspaceId}/agent-access`, scoped:true },
  workspace_agent_access_set: { schema:z.object({...workspace,userId:uuid,blocked:z.boolean()}).strict(), method:'POST', path:a=>`/workspaces/${a.workspaceId}/members/${a.userId}/agent-access`, body:a=>({blocked:a.blocked}), scoped:true },
@@ -49,6 +91,7 @@ export const operations = {
  workspace_invitations: { schema: z.object({}).strict(), method: 'GET', path: () => '/me/invitations' },
  workspace_invitation_get: { schema: z.object({ id: uuid, generation: z.number().int().positive() }).strict(), method: 'GET', path: a => `/invitations/${a.id}?generation=${a.generation}` },
  workspace_invitation_accept: { schema: z.object({ id: uuid, generation: z.number().int().positive() }).strict(), method: 'POST', path: a => `/invitations/${a.id}/accept`, body: a => ({ generation: a.generation }) },
+ workspace_invitation_decline: { schema: z.object({ id: uuid, generation: z.number().int().positive() }).strict(), method: 'POST', path: a => `/invitations/${a.id}/decline`, body: a => ({ generation: a.generation }) },
  workspace_select: { schema: z.object({ workspaceId: uuid }).strict(), method: 'GET', path: a => `/workspaces/${a.workspaceId}` },
 };
 function profilePath(path) {
@@ -77,7 +120,11 @@ export function writeProfile(path, profile) {
  const target=profilePath(path); const temporary=`${target}.${process.pid}.tmp`;
  writeFileSync(temporary,JSON.stringify(profile)+'\n',{mode:0o600,flag:'wx'}); renameSync(temporary,target);
 }
+/** The profile path: --profile wins, then AUDIENTI_PROFILE (the variable the MCP server reads), else none (#448). */
+export const profileFrom = flag => flag ?? (process.env.AUDIENTI_PROFILE || undefined);
+export const profileHint = 'Pass --profile PATH, or set AUDIENTI_PROFILE to the profile file.';
 export function configuration(path, scope='workspace:access') {
+ path=profileFrom(path);
  const profile=readProfile(path);
  const agentProfile = Boolean(profile.agent || profile.pendingAgent || profile.connectionSecret);
  return { url:agentProfile ? profile.url : process.env.AUDIENTI_API_URL ?? profile.url, token:agentProfile ? (scope === 'workspace:access' ? profile.tokens?.['workspace:read'] : undefined) : process.env.AUDIENTI_API_TOKEN ?? (scope === 'workspace:access' ? profile.tokens?.['workspace:read'] ?? profile.tokens?.[scope] : profile.tokens?.[scope]), workspaceId:profile.workspaceId, profile };
@@ -88,9 +135,44 @@ export function validateUrl(value) {
  if(url.protocol!=='https:' && !(url.protocol==='http:' && ['localhost','127.0.0.1','[::1]'].includes(url.hostname))) throw new Error('Use HTTPS for remote API hosts.');
  return url;
 }
+// A refused request that never left this machine. It prints like an API error, so a caller reads one format (#451).
+export class InvalidArguments extends Error {
+ constructor(message, guidance = {}) { super(message); this.field = guidance.field; this.allowed = guidance.allowed; this.next = guidance.next; }
+ toJSON() { return {code:'invalid_arguments',message:this.message,...(this.field ? {field:this.field} : {}),...(this.allowed ? {allowed:this.allowed} : {}),...(this.next ? {next:this.next} : {})}; }
+}
+// The same field, allowed values and next step the server gives (#483), for a mistake the CLI refuses before sending.
+const pathText = path => path.reduce((text, part) => typeof part === 'number' ? `${text}[${part}]` : text ? `${text}.${part}` : String(part), '');
+const FIELD_RULES = 'audienti skills read playbook-design references/fields.md';
+export function localGuidance(name, issues, args) {
+ const issue = issues[0]; if(!issue) return {};
+ const playbook = name.startsWith('playbook_');
+ const path = issue.code === 'unrecognized_keys' ? [...issue.path, issue.keys?.[0] ?? ''] : issue.path;
+ const fieldText = pathText(path).slice(0, 200), field = /^[A-Za-z0-9_.[\]-]+$/.test(fieldText) ? fieldText : undefined, last = String(path[path.length - 1] ?? '');
+ const given = path.reduce((value, part) => value?.[part], args);
+ const shown = typeof given === 'string' ? `"${given.slice(0, 60)}"` : 'that value';
+ if(issue.code === 'invalid_value') {
+  const allowed = issue.values.filter(value => typeof value === 'string' && value.length <= 80).slice(0, 60);
+  const phone = playbook && last === 'channel' ? ' A phone call, voicemail or gift is a Custom step: use channel Custom and write in its instructions what the person does by hand. Your agent prepares the script or text and the person records the outcome.' : '';
+  const more = playbook && last === 'actionId' ? ' List every action id with its channel: audienti playbook actions.' : playbook && last === 'when' ? ' List the event names: audienti playbook actions.' : '';
+  return {field, ...(allowed.length ? {allowed} : {}), next: `Use one of the allowed values in place of ${shown}.${phone}${more}`};
+ }
+ if(issue.code === 'unrecognized_keys') return {field, next: `Remove ${issue.keys.map(key => `"${key}"`).join(', ')} or fix the spelling. ${playbook ? `The fields a playbook has are in the example of: audienti playbook save --help. Field rules: ${FIELD_RULES}` : 'Run audienti --help for the options of this command.'}`};
+ if(issue.code === 'invalid_type') return {field, next: given === undefined ? `Add ${last || 'the value'}.${playbook ? ` Field rules: ${FIELD_RULES}` : ''}` : `Send a ${issue.expected} for ${last || field}.${playbook ? ` Field rules: ${FIELD_RULES}` : ''}`};
+ return field ? {field, next: `Fix this value and send the command again.${playbook ? ` Field rules: ${FIELD_RULES}` : ''}`} : {};
+}
+// The next step an error gives an agent (#483): one sentence, the path of the wrong value and the values that would have worked.
+// Checked here too, so a response never puts the token or control text into the agent's context.
+export function errorGuidance(error, token) {
+ const clean = text => typeof text === 'string' && !/[\u0000-\u001f\u007f]/.test(text) && !(token && text.includes(token));
+ return {
+  next: clean(error?.next) && error.next.length <= 600 ? error.next : undefined,
+  field: clean(error?.field) && /^[A-Za-z0-9_.[\]-]{1,200}$/.test(error.field) ? error.field : undefined,
+  allowed: Array.isArray(error?.allowed) && error.allowed.length > 0 && error.allowed.length <= 60 && error.allowed.every(value => clean(value) && value.length <= 80) ? error.allowed : undefined
+ };
+}
 export class WorkspaceRequestError extends Error {
- constructor(status, code, message, retryAt, blockers, requestTraceId) { super(message); this.status = status; this.code = code; this.retryAt = retryAt; this.blockers = blockers; this.requestTraceId = requestTraceId; }
- toJSON() { return { ...(this.requestId ? {requestId:this.requestId,recovery:this.recovery} : {}), ...(this.requestTraceId ? {requestTraceId:this.requestTraceId} : {}), code:this.code, status:this.status, message:this.message, ...(this.retryAt ? {retryAt:this.retryAt} : {}), ...(this.blockers ? {blockers:this.blockers} : {}) }; }
+ constructor(status, code, message, retryAt, blockers, requestTraceId, guidance = {}) { super(message); this.status = status; this.code = code; this.retryAt = retryAt; this.blockers = blockers; this.requestTraceId = requestTraceId; this.next = guidance.next; this.field = guidance.field; this.allowed = guidance.allowed; }
+ toJSON() { return { ...(this.requestId ? {requestId:this.requestId,recovery:this.recovery} : {}), ...(this.requestTraceId ? {requestTraceId:this.requestTraceId} : {}), code:this.code, status:this.status, message:this.message, ...(this.field ? {field:this.field} : {}), ...(this.allowed ? {allowed:this.allowed} : {}), ...(this.next ? {next:this.next} : {}), ...(this.currentRevision!==undefined ? {currentRevision:this.currentRevision} : {}), ...(this.campaigns ? {campaigns:this.campaigns,campaignCount:this.campaignCount} : {}), ...(this.retryAt ? {retryAt:this.retryAt} : {}), ...(this.blockers ? {blockers:this.blockers} : {}), ...(this.errors ? {errors:this.errors} : {}), ...(this.charged ? {charged:this.charged} : {}) }; }
 }
 export class HostedResponseUnknown extends Error {
  constructor(requestId, reason, requestTraceId) { super('The server response is unknown. Paid work may have started. Retry using the same requestId and principal; never generate a new ID to recover this call.'); this.requestId=requestId; this.reason=reason; this.requestTraceId=requestTraceId; }
@@ -98,61 +180,78 @@ export class HostedResponseUnknown extends Error {
 }
 export async function callWorkspace(name, args, config) {
  const operation=operations[name]; if(!operation) throw new Error('Unknown workspace operation.');
- const parsed=operation.schema.safeParse(args);if(!parsed.success) throw new Error('Invalid workspace arguments. Check IDs and required fields.');
+ const parsed=operation.schema.safeParse(args);if(!parsed.success) throw new InvalidArguments(`Invalid workspace arguments. Check IDs and required fields: ${parsed.error.issues.slice(0,5).map(i=>`${i.path.join('.')||'input'}: ${i.message}`).join('; ')}.`,localGuidance(name,parsed.error.issues,args));
  const input={...parsed.data};
- if(operation.scoped) { input.workspaceId ??= config.workspaceId;if(!uuid.safeParse(input.workspaceId).success) throw new Error('Select a workspace or supply --workspace ID.'); }
- const url=validateUrl(config.url); if(!config.token) throw new Error('A workspace:access token is required. Configure the environment or a private profile.');
+ if(operation.localUpload)return uploadFileContent(input,(operationName,fields)=>callWorkspace(operationName,fields,config));
+ // #333: an agent's own queue covers all its workspaces; a user's reads the selected workspace, as before.
+ if(operation.scoped || (operation.agentWide && !/^agt_/.test(config.token ?? ''))) { input.workspaceId ??= config.workspaceId;if(!uuid.safeParse(input.workspaceId).success) throw new Error(`Select a workspace or supply --workspace ID. ${config.profile&&Object.keys(config.profile).length?'Run workspace use WORKSPACE_ID once for this profile.':profileHint}`); }
+ const url=validateUrl(config.url); if(!config.token) throw new Error(`A workspace:access token is required. ${profileHint} Or set AUDIENTI_API_URL and AUDIENTI_API_TOKEN.`);
  const target=new URL(`/api/v1${operation.path(input)}`,url);
- let response;try {response=await fetch(target,{method:operation.method,headers:{Authorization:`Bearer ${config.token}`,Accept:'application/json','Content-Type':'application/json',...((operation.traced||name.startsWith('tools_'))?{'X-Audienti-Interface':config.interface==='mcp'?'mcp':'cli'}:{})},...(['POST','PUT','PATCH'].includes(operation.method)?{body:JSON.stringify(operation.body?.(input)??{})}:{}),redirect:'error',signal:AbortSignal.timeout(operation.timeoutMs ?? 10000)});}catch(error){if(isPaidToolOperation(name))throw new HostedResponseUnknown(input.requestId,['TimeoutError','AbortError'].includes(error?.name)?'timeout':'transport_failure');throw new Error('Could not reach the API. Redirects are not followed.');}
+ let response;try {response=await fetch(target,{method:operation.method,headers:{Authorization:`Bearer ${config.token}`,Accept:'application/json','Content-Type':'application/json',...((operation.traced||name.startsWith('tools_'))?{'X-Audienti-Interface':config.interface==='mcp'?'mcp':'cli'}:{})},...(['POST','PUT','PATCH'].includes(operation.method)?{body:JSON.stringify(operation.body?.(input)??{})}:{}),redirect:'error',signal:AbortSignal.timeout(operation.timeoutMs ?? 10000)});}catch(error){if(isPaidToolOperation(name,input)||operation.recoverable)throw new HostedResponseUnknown(input.requestId,['TimeoutError','AbortError'].includes(error?.name)?'timeout':'transport_failure');throw new Error('Could not reach the API. Redirects are not followed.');}
  const headerTrace=(operation.traced||name.startsWith('tools_'))&&uuid.safeParse(response.headers.get('x-request-trace-id')).success?response.headers.get('x-request-trace-id'):undefined;
- let result;try{result=await response.json();}catch{if(isPaidToolOperation(name))throw new HostedResponseUnknown(input.requestId,'invalid_response',headerTrace);throw new Error('The API returned an invalid response.');}
+ let result;try{result=await response.json();}catch{if(isPaidToolOperation(name,input)||operation.recoverable)throw new HostedResponseUnknown(input.requestId,'invalid_response',headerTrace);throw new Error('The API returned an invalid response.');}
  const requestTraceId=uuid.safeParse(result?.requestTraceId).success?result.requestTraceId:headerTrace;
  if(!response.ok) {
   const code = typeof result?.error?.code==='string' && /^[a-z_]+$/.test(result.error.code) ? result.error.code : 'request_failed';
   const retryAt = typeof result?.error?.retryAt === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(result.error.retryAt) ? result.error.retryAt : undefined;
-  const blockers = code==='execution_blocked' && Array.isArray(result?.error?.blockers) && result.error.blockers.length<=28 && result.error.blockers.every(v=>typeof v==='string' && /^[a-z_]+$/.test(v)) ? result.error.blockers : undefined;
-  const error = new WorkspaceRequestError(response.status, code, `Workspace request failed: ${code} (HTTP ${response.status}).${retryAt ? ` Retry after ${retryAt}.` : ''}`, retryAt, blockers, requestTraceId);
-  if(isPaidToolOperation(name)){error.requestId=input.requestId;error.recovery=response.status>=500?'retry_same_request_id':'inspect_rejection';}
+  const detail = ((response.status===400 && (code==='invalid_fields' || code==='validation_error' || code==='secret_rejected')) || (response.status===404 && code==='not_found') || (response.status===422 && code==='playbook_cannot_work') || (response.status===409 && (code==='revision_conflict' || code==='playbook_in_use' || code==='definition_archived' || code==='playbook_archived' || code==='starter_playbook' || code==='identity_conflict' || code==='task_not_for_you' || code==='version_conflict' || code==='request_conflict' || code==='campaign_not_ready' || code==='campaign_not_paced' || code==='wrong_event_name' || code==='mark_task_done_first' || code==='no_event' || code==='prepare_first' || code==='task_closed' || code==='not_claimed'))) && typeof result?.error?.message==='string' && result.error.message.length<=(code==='playbook_cannot_work'?2000:1000) && !/[\u0000-\u001f\u007f]/.test(result.error.message) && !/^Workspace request failed/.test(result.error.message) && !(config.token && result.error.message.includes(config.token)) ? result.error.message.trim() : '';
+  const blockers = (code==='execution_blocked' || code==='campaign_not_ready') && Array.isArray(result?.error?.blockers) && result.error.blockers.length<=28 && result.error.blockers.every(v=>typeof v==='string' && /^[a-z_]+$/.test(v)) ? result.error.blockers : undefined;
+  const error = new WorkspaceRequestError(response.status, code, `Workspace request failed: ${code} (HTTP ${response.status}).${detail ? ` ${detail}` : ''}${retryAt ? ` Retry after ${retryAt}.` : ''}`, retryAt, blockers, requestTraceId, errorGuidance(result?.error, config.token));
+  if(code==='playbook_cannot_work'&&Array.isArray(result?.error?.errors)&&result.error.errors.length<=30)error.errors=result.error.errors.filter(item=>item&&typeof item.id==='string'&&typeof item.message==='string').map(item=>({id:item.id,level:item.level,message:item.message,...(typeof item.stageKey==='string'?{stageKey:item.stageKey}:{}),...(item.fix&&typeof item.fix.label==='string'?{fix:{id:item.fix.id,label:item.fix.label}}:{})}));
+  if(code==='revision_conflict'&&Number.isInteger(result?.error?.currentRevision)&&result.error.currentRevision>=0)error.currentRevision=result.error.currentRevision;
+  // A playbook that is in use names the campaigns that use it (#459).
+  if(code==='playbook_in_use'&&Array.isArray(result?.error?.campaigns)&&Number.isInteger(result.error.campaignCount)){error.campaigns=result.error.campaigns.slice(0,20).filter(c=>uuid.safeParse(c?.id).success&&typeof c.name==='string'&&c.name.length<=200&&!/[\u0000-\u001f\u007f]/.test(c.name)).map(c=>({id:c.id,name:c.name}));error.campaignCount=result.error.campaignCount;}
+  // What a failed paid check already spent (pico USD), so a caller counting its spend never loses it.
+  if(typeof result?.error?.charged==='string'&&/^\d{1,20}$/.test(result.error.charged))error.charged=result.error.charged;
+  if(isPaidToolOperation(name,input)){error.requestId=input.requestId;error.recovery=response.status>=500?'retry_same_request_id':'inspect_rejection';}
   throw error;
  }
- if(!result || !Object.hasOwn(result,'data')) {if(isPaidToolOperation(name))throw new HostedResponseUnknown(input.requestId,'invalid_response',requestTraceId);throw new Error('The API returned an invalid response.');}
- const paidResult = paidToolResult(name, result?.data);
- if(isPaidToolOperation(name)&&(!uuid.safeParse(paidResult?.operationId).success||paidResult.requestId!==input.requestId||!['running','succeeded','failed','uncertain','rejected'].includes(paidResult.status)))throw new HostedResponseUnknown(input.requestId,'invalid_response',requestTraceId);
+ if(!result || !Object.hasOwn(result,'data')) {if(isPaidToolOperation(name,input)||operation.recoverable)throw new HostedResponseUnknown(input.requestId,'invalid_response',requestTraceId);throw new Error('The API returned an invalid response.');}
+ const paidResult = paidToolResult(name, result?.data, input);
+ if(isPaidToolOperation(name,input)&&(!uuid.safeParse(paidResult?.operationId).success||paidResult.requestId!==input.requestId||!['running','succeeded','failed','uncertain','rejected'].includes(paidResult.status)))throw new HostedResponseUnknown(input.requestId,'invalid_response',requestTraceId);
  if(name==='workspace_select') config.workspaceId=input.workspaceId;
- return {data:result.data,...(requestTraceId?{requestTraceId}:{})};
+ return {data:operation.transform?operation.transform(result.data,input):result.data,...(requestTraceId?{requestTraceId}:{})};
 }
 export async function workspaceCli(args) {
  const flags={}; const position=[];
  for(let i=0;i<args.length;i++) {
   if(args[i]==='--json') continue;
-  if(args[i].startsWith('--')) {const key=args[i].slice(2);if(!['profile','workspace','name','request-id','email','generation','scope','user'].includes(key)||!args[i+1]||args[i+1].startsWith('--')) throw new Error('Unknown or incomplete option.');flags[key]=args[++i];}
+  if(args[i].startsWith('--')) {const key=args[i].slice(2);if(!['profile','workspace','name','request-id','email','generation','scope','user','file','caller','status','after','query','people-only','recent','unread-only','cursor','key','read','through'].includes(key)||!args[i+1]||args[i+1].startsWith('--')) throw new Error('Unknown or incomplete option.');flags[key]=args[++i];}
   else position.push(args[i]);
  }
  if(position[0]==='profile' && position[1]==='save') {
   if(!['account:read','workspace:access','agents:manage'].includes(flags.scope)) throw new Error('Specify --scope account:read, workspace:access or agents:manage.');
   const url=validateUrl(process.env.AUDIENTI_API_URL).toString().replace(/\/$/,'');const token=process.env.AUDIENTI_API_TOKEN;if(!token) throw new Error('Set AUDIENTI_API_TOKEN.');
-  const profile=readProfile(flags.profile);if(profile.agent || profile.pendingAgent || profile.connectionSecret) throw new Error('Use a separate user profile; agent profiles cannot store user API tokens.');writeProfile(flags.profile,{...profile,url,tokens:{...profile.tokens,[flags.scope]:token}});console.log('Profile saved.');return;
+  const profile=readProfile(profileFrom(flags.profile));if(profile.agent || profile.pendingAgent || profile.connectionSecret) throw new Error('Use a separate user profile; agent profiles cannot store user API tokens.');writeProfile(profileFrom(flags.profile),{...profile,url,tokens:{...profile.tokens,[flags.scope]:token}});console.log('Profile saved.');return;
  }
  const config=configuration(flags.profile);const command=position.slice(1).join(' ');
  let name, input={};
  if(command==='sending-settings') {name='workspace_sending_settings_get';input={workspaceId:flags.workspace,...(flags.user?{userId:flags.user}:{})};}
+ else if(command==='sending-settings save') {if(!flags.file) throw new Error('Supply the settings with --file PATH.');const body=readJsonFile(flags.file,65536,'Settings file');if(!body||typeof body!=='object'||Array.isArray(body)) throw new Error('Settings must be an object.');name='workspace_sending_settings_save';input={...body,workspaceId:flags.workspace??body.workspaceId,...(flags.user?{userId:flags.user}:{})};}
+ else if(command==='usage summary') {name='workspace_usage_summary';input={workspaceId:flags.workspace};}
+ else if(command==='usage callers') {name='workspace_usage_callers';input={workspaceId:flags.workspace};}
+ else if(command==='usage calls') {name='workspace_usage_calls';input={workspaceId:flags.workspace,...(flags.after?{after:flags.after}:{}),...(flags.caller?{caller:flags.caller}:{}),...(flags.status?{status:flags.status}:{})};}
+ else if(position[1]==='usage'&&position[2]==='call'&&position.length===4) {name='workspace_usage_call';input={workspaceId:flags.workspace,callId:position[3]};}
  else if(command==='agent-access') {name='workspace_agent_access';input={workspaceId:flags.workspace};}
  else if(['agent-access block','agent-access restore'].includes(command)) {name='workspace_agent_access_set';input={workspaceId:flags.workspace,userId:flags.user,blocked:command.endsWith('block')};}
  else if(command==='init') name='workspace_initialize';
  else if(command==='list') name='workspace_list';
- else if(command==='create') {name='workspace_create';input={name:flags.name,requestId:flags['request-id']};}
+ else if(command==='notifications') {if(flags['unread-only']&&!['true','false'].includes(flags['unread-only']))throw new Error('--unread-only must be true or false.');name='workspace_notifications_list';input={workspaceId:flags.workspace,unreadOnly:flags['unread-only']==='true',...(flags.cursor?{cursor:readJsonFile(flags.cursor,4096,'Notification cursor')}:{})};}
+ else if(command==='notification-read') {if(!['true','false'].includes(flags.read))throw new Error('--read must be true or false.');name='workspace_notifications_mark';input={workspaceId:flags.workspace,sourceKey:flags.key,isRead:flags.read==='true',...(flags.through?{through:flags.through}:{})};}
+ else if(command==='search') {if(flags['people-only']&&!['true','false'].includes(flags['people-only']))throw new Error('--people-only must be true or false.');name='workspace_search';input={workspaceId:flags.workspace,query:flags.query??'',peopleOnly:flags['people-only']==='true',recent:flags.recent?readJsonFile(flags.recent,4096,'Recent references'):[]};}
+ else if(command==='create') {name='workspace_create';input={name:flags.name,requestId:flags['request-id']??randomUUID()};}
  else if(command==='show') {name='workspace_get';input={workspaceId:flags.workspace};}
  else if(command==='invite') {name='workspace_invite';input={workspaceId:flags.workspace,email:flags.email};}
  else if(command==='invitations') name='workspace_invitations';
  else if(position[1]==='member' && position.length===3) {name='workspace_member';input={workspaceId:flags.workspace,userId:position[2]};}
  else if(position[1]==='use' && position.length===3) {name='workspace_select';input={workspaceId:position[2]};}
  else if(position[1]==='invitation' && position.length===4) {
-  const action=position[2];name={show:'workspace_invitation_get',accept:'workspace_invitation_accept',retry:'workspace_invitation_retry',cancel:'workspace_invitation_cancel'}[action];
+  const action=position[2];name={show:'workspace_invitation_get',accept:'workspace_invitation_accept',decline:'workspace_invitation_decline',retry:'workspace_invitation_retry',cancel:'workspace_invitation_cancel'}[action];
   input={id:position[3],...(['retry','cancel'].includes(action)?{workspaceId:flags.workspace}:{generation:Number(flags.generation)})};
  }
  if(!name) throw new Error('Unknown workspace command. Use audienti --help.');
  const result=await callWorkspace(name,input,config);
 
- if(name==='workspace_select') writeProfile(flags.profile,{...config.profile,workspaceId:config.workspaceId});
+ if(name==='workspace_select') writeProfile(profileFrom(flags.profile),{...config.profile,workspaceId:config.workspaceId});
  console.log(JSON.stringify(result));
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@audienti/cli",
-  "version": "0.2.0-exora.1",
-  "description": "Audienti CLI and MCP client for exo.audienti.com",
+  "version": "0.2.0-exora.11",
+  "description": "Audienti CLI and MCP client for app.audienti.com",
   "type": "module",
   "bin": {
     "audienti": "cli/audienti.mjs",