@audienti/cli 0.1.145 → 0.2.0-exora.10

package/cli/skills.mjs

@@ -0,0 +1,113 @@
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { SKILL_VERSION, helperContracts } from '../skills/audienti/scripts/contracts.mjs';
+import { executeHelperFile } from '../skills/audienti/scripts/run.mjs';
+
+const bundles = {
+  audienti: {
+    version: SKILL_VERSION,
+    files: ['SKILL.md', 'references/profile-workflows.md', 'references/helpers.md', 'references/workflow-receipt.md', 'scripts/contracts.mjs', 'scripts/profile-helpers.mjs', 'scripts/run.mjs'],
+    helpers: true,
+  },
+  'getting-started': {
+    version: '1.5.1',
+    files: ['SKILL.md', 'references/capabilities.md', 'references/campaign-draft.md', 'references/audience.md', 'references/outcome-checks.md', 'references/replies.md', 'references/reply-checks.md', 'references/mailbox-check.md'],
+    helpers: false,
+  },
+  'playbook-design': {
+    version: '1.1.0',
+    files: ['SKILL.md', 'references/fields.md'],
+    helpers: false,
+  },
+  'agent-rooms': {
+    version: '1.0.0',
+    description: "Talk with your user's other registered agents in rooms: check your inbox each run, ask and answer, reply unable, and leave a turnover note.",
+    files: ['SKILL.md', 'references/commands.md'],
+    helpers: false,
+  },
+};
+export const SKILL_IDS = Object.keys(bundles);
+
+function readSkill(id = 'audienti') {
+  const bundle = Object.hasOwn(bundles, id) ? bundles[id] : null;
+  if (!bundle) throw new Error('Unknown bundled skill. Use skills list.');
+  const root = new URL(`../skills/${id}/`, import.meta.url);
+  const contents = bundle.files.map(path => ({ path, text: readFileSync(new URL(path, root), 'utf8') }));
+  const front = contents[0].text.match(/^---\n([\s\S]*?)\n---/)?.[1] ?? '';
+  const name = front.match(/^name: (.+)$/m)?.[1].trim(), description = front.match(/^description: (.+)$/m)?.[1].trim();
+  if (name !== id || !description) throw new Error('Bundled skill requires a matching name and description in SKILL.md frontmatter.');
+  const hash = createHash('sha256');
+  for (const file of contents) hash.update(`${file.path}\0${Buffer.byteLength(file.text)}\0`).update(file.text);
+  return { contents, details: {
+    id, version: bundle.version, digest: hash.digest('hex'),
+    description,
+    instructions: contents[0].text,
+    references: contents.filter(file => file.path.startsWith('references/')),
+    helpers: bundle.helpers ? Object.entries(helperContracts).map(([name, contract]) => ({ name, ...contract })) : [],
+  } };
+}
+
+export function skillDetails(id = 'audienti') { return readSkill(id).details; }
+
+const helperPath = name => `helpers/${name}.json`;
+
+// Compact discovery omits instructions and schemas so an agent can pick a skill,
+// then read only the files it needs with skillResource.
+export function skillCatalog({ compact = false } = {}) {
+  if (!compact) return { skills: SKILL_IDS.map(id => { const { instructions, references, ...entry } = skillDetails(id); return entry; }) };
+  return { skills: SKILL_IDS.map(id => {
+    const { version, digest, description, helpers } = skillDetails(id);
+    return {
+      id, version, digest, description,
+      resources: [...bundles[id].files, ...helpers.map(({ name }) => helperPath(name))],
+      helpers: helpers.map(({ name, description: about }) => ({ name, description: about, resource: helperPath(name) })),
+    };
+  }) };
+}
+
+export function skillResource(id, path) {
+  const artifact = skillArtifact(id);
+  // Match shipped resource names exactly; never turn input into a disk path.
+  const file = artifact.files.find(entry => entry.path === path);
+  const helper = artifact.helpers.find(entry => helperPath(entry.name) === path);
+  if (!file && !helper) throw new Error('Unknown bundled skill resource. Use skills list --compact.');
+  return { id: artifact.id, version: artifact.version, digest: artifact.digest, path, content: file ? file.content : JSON.stringify(helper) };
+}
+
+const usage = `Usage: audienti skills list [--compact] | show ${SKILL_IDS.join('|')} | read SKILL RESOURCE | helper NAME --file INPUT.json|- [--json]`;
+
+export function skillArtifact(id = 'audienti') {
+  const { details, contents } = readSkill(id);
+  return { ...details, files: contents.map(({ path, text }) => ({ path, content: text })) };
+}
+
+export async function skillsCli(argv) {
+  // Skills are public; ignore --profile and --workspace so agents can pass them everywhere.
+  const raw = argv.slice(1), drop = new Set();
+  raw.forEach((value, i) => { if (value === '--profile' || value === '--workspace') { drop.add(i); drop.add(i + 1); } });
+  const args = raw.filter((_, i) => !drop.has(i)), json = args.includes('--json');
+  const filtered = args.filter(value => value !== '--json');
+  if (args.filter(value => value === '--json').length > 1) throw new Error('Invalid skills options.');
+  if (filtered.length === 1 && ['--help', 'help'].includes(filtered[0])) {
+    process.stdout.write(`${usage}\nLocal skill instructions/helpers; no login, installation or provider calls.\n`); return;
+  }
+  if (filtered[0] === 'list' && (filtered.length === 1 || (filtered.length === 2 && filtered[1] === '--compact'))) {
+    const compact = filtered.length === 2, catalog = skillCatalog({ compact });
+    if (compact && !json) { process.stdout.write(catalog.skills.map(skill => `${skill.id}@${skill.version} — ${skill.description}\n${skill.resources.map(path => `  ${path}\n`).join('')}`).join('')); return; }
+    process.stdout.write(json ? `${JSON.stringify(catalog)}\n` : catalog.skills.map(skill => `${skill.id}@${skill.version} — ${skill.description}\n`).join('')); return;
+  }
+  if (filtered[0] === 'show' && filtered.length === 2) {
+    const details = skillDetails(filtered[1]);
+    process.stdout.write(json ? `${JSON.stringify(details)}\n` : `${details.instructions}\n${details.references.map(file => `\n--- ${file.path} ---\n${file.text}\n`).join('')}`); return;
+  }
+  if (filtered[0] === 'read' && filtered.length === 3) {
+    const resource = skillResource(filtered[1], filtered[2]);
+    process.stdout.write(json ? `${JSON.stringify(resource)}\n` : `${resource.content}\n`); return;
+  }
+  if (filtered[0] === 'helper' && filtered.length === 4 && filtered[2] === '--file') {
+    try { process.stdout.write(`${JSON.stringify(executeHelperFile(filtered[1], filtered[3]))}\n`); }
+    catch { throw new Error('Skill helper failed. Inspect its schema and provide valid JSON of at most 1 MiB.'); }
+    return;
+  }
+  throw new Error(usage);
+}

package/cli/suppression-operations.mjs

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+const uuid=z.string().uuid();
+const located={workspaceId:uuid.optional(),prospectId:uuid};
+const path=a=>`/workspaces/${a.workspaceId}/prospects/${a.prospectId}/suppression`;
+export const suppressionOperations={
+ workspace_prospect_suppression:{schema:z.object({...located,history:z.object({cursor:uuid.optional(),limit:z.number().int().min(1).max(100).optional()}).strict().optional()}).strict(),method:'GET',path:a=>{const q=new URLSearchParams();if(a.history?.cursor)q.set('historyCursor',a.history.cursor);if(a.history?.limit!==undefined)q.set('historyLimit',String(a.history.limit));return path(a)+(q.size?'?'+q:'');},scoped:true},
+ workspace_prospect_suppression_set:{schema:z.object({...located,kind:z.enum(['dnc','reject']),action:z.enum(['set','clear']),expectedVersion:z.number().int().nonnegative(),requestId:uuid,reason:z.string().optional()}).strict(),method:'POST',path,body:({workspaceId,prospectId,...body})=>body,scoped:true},
+};

package/cli/suppression.mjs

@@ -0,0 +1,12 @@
+import { callWorkspace, configuration } from './workspaces.mjs';
+export async function suppressionCli(args){
+ const flags={},positions=[];
+ const allowed=['workspace','profile','history-cursor','history-limit','kind','action','expected-version','request-id','reason'];
+ 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(!allowed.includes(key)||Object.hasOwn(flags,key)||args[i+1]===undefined||args[i+1].startsWith('--'))throw Error('Unknown, repeated or incomplete suppression option.');flags[key]=args[++i];}
+ if(positions.length!==4||positions[0]!=='prospects'||positions[1]!=='suppression'||!['get','set'].includes(positions[2]))throw Error('Use prospects suppression get|set ID --workspace ID.');
+ const read=positions[2]==='get';const valid=['workspace','profile',...(read?['history-cursor','history-limit']:['kind','action','expected-version','request-id','reason'])];if(Object.keys(flags).some(k=>!valid.includes(k)))throw Error('Option does not apply to this command.');
+ const input={workspaceId:flags.workspace,prospectId:positions[3]};
+ if(read)input.history={...(flags['history-cursor']===undefined?{}:{cursor:flags['history-cursor']}),...(flags['history-limit']===undefined?{}:{limit:Number(flags['history-limit'])})};
+ else Object.assign(input,{kind:flags.kind,action:flags.action,expectedVersion:flags['expected-version']===undefined?undefined:Number(flags['expected-version']),requestId:flags['request-id'],...(flags.reason===undefined?{}:{reason:flags.reason})});
+ console.log(JSON.stringify(await callWorkspace(read?'workspace_prospect_suppression':'workspace_prospect_suppression_set',input,configuration(flags.profile))));
+}

package/cli/tools-operations.mjs

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+const uuid = z.string().uuid(), workspace = { workspaceId: uuid.optional() };
+const root = a => `/workspaces/${a.workspaceId}/tools`;
+const toolId = z.string().regex(/^[a-z][a-z0-9._]{0,63}$/);
+const key = z.string().regex(/^[a-z][a-z0-9_]{0,47}$/).refine(v => !['constructor','prototype'].includes(v));
+const instruction = z.string().trim().min(1).max(4000);
+const question = z.discriminatedUnion('type', [
+ z.object({type:z.literal('boolean'),instructions:instruction,criteria:z.object({true:instruction.optional(),false:instruction.optional()}).strict().optional()}).strict(),
+ z.object({type:z.literal('choice'),instructions:instruction,criteria:z.record(key,z.string().max(2000)).refine(v=>Object.keys(v).length>=1&&Object.keys(v).length<=32)}).strict(),
+ z.object({type:z.literal('score'),instructions:instruction,criteria:z.array(instruction).min(1).max(10)}).strict(),
+]);
+const page = { page:z.number().int().min(1).max(10000).optional(), paginationToken:z.string().min(1).max(4096).optional() };
+const postedLimit = z.enum(['24h','week','month']).optional();
+const contentInputs = {
+ 'posts.fetch':z.object({url:z.string().min(1).max(2048),topicId:uuid}).strict(),
+ 'posts.search':z.object({query:z.string().trim().min(1).max(500),topicId:uuid,postedLimit,...page,sortBy:z.enum(['relevance','date']).optional()}).strict(),
+ 'posts.comments':z.object({postId:uuid,...page}).strict(),
+ 'posts.reactions':z.object({postId:uuid,page:page.page}).strict(),
+ 'profiles.search':z.object({kind:z.enum(['person','company']).optional(),query:z.string().trim().min(1).max(500).optional(),title:z.string().trim().min(1).max(200).optional(),location:z.string().trim().min(1).max(200).optional(),geoId:z.string().regex(/^\d{1,20}$/).optional(),industryIds:z.array(z.string().regex(/^\d{1,20}$/)).max(20).optional(),keywordsCompany:z.string().trim().min(1).max(200).optional(),currentCompany:z.string().trim().min(1).max(1024).optional(),companySizes:z.array(z.enum(['1-10','11-50','51-200','201-500','501-1000','1001-5000','5001-10000','10001+'])).max(8).optional(),page:page.page,saveProfiles:z.boolean().optional()}).strict(),
+ 'profiles.posts':z.object({profileId:uuid,topicId:uuid,postedLimit,...page}).strict(),
+};
+const contentOperations = Object.fromEntries(Object.entries(contentInputs).map(([tool,input])=>[`tools_${tool.replaceAll('.','_')}`,{tool,paid:true,schema:z.object({...workspace,requestId:uuid,input}).strict(),method:'POST',path:a=>root(a)+'/'+tool,body:a=>({requestId:a.requestId,input:a.input}),scoped:true,timeoutMs:30000}]));
+const recordsRoot = (a,kind) => `/workspaces/${a.workspaceId}/${kind}`;
+const contactInputs = {
+ 'email.find':z.object({profileId:uuid,domain:z.string().trim().min(1).max(253),refresh:z.boolean().optional(),cached:z.boolean().optional()}).strict(),
+ 'mobile.find':z.object({profileId:uuid,email:z.string().min(1).max(320).optional(),refresh:z.boolean().optional(),cached:z.boolean().optional()}).strict(),
+};
+export const hostedToolOperations = {
+ ...Object.fromEntries(Object.entries(contactInputs).map(([tool,input])=>[`tools_${tool.replaceAll('.','_')}`,{tool,paid:true,limits:{cacheDays:7,maximumAttempts:tool==='email.find'?130:3},schema:z.object({...workspace,requestId:uuid,input}).strict(),method:'POST',path:a=>root(a)+'/'+tool,body:a=>({requestId:a.requestId,input:a.input}),scoped:true,timeoutMs:60000}])),
+ tools_email_verify:{tool:'email.verify',paid:true,limits:{providerCalls:1,cacheDays:7},schema:z.object({...workspace,requestId:uuid,input:z.object({email:z.string().max(320),refresh:z.boolean().optional(),cached:z.boolean().optional()}).strict()}).strict(),method:'POST',path:a=>root(a)+'/email.verify',body:a=>({requestId:a.requestId,input:a.input}),scoped:true,timeoutMs:30000},
+ ...contentOperations,
+ topics_create:{traced:true,schema:z.object({...workspace,requestId:uuid,name:z.string().trim().min(1).max(200),slug:z.string().max(200).optional(),description:z.string().max(4000).optional()}).strict(),method:'POST',path:a=>recordsRoot(a,'topics'),body:({workspaceId,...a})=>a,scoped:true},
+ ...Object.fromEntries(['topics','posts'].flatMap(kind=>[
+  [`${kind}_list`,{traced:true,schema:z.object({...workspace,cursor:uuid.optional(),...(kind==='posts'?{topicId:uuid.optional()}:{})}).strict(),method:'GET',path:a=>recordsRoot(a,kind)+'?'+new URLSearchParams(Object.fromEntries(Object.entries({cursor:a.cursor,topicId:a.topicId}).filter(([,v])=>v))),scoped:true}],
+  [`${kind}_get`,{traced:true,schema:z.object({...workspace,id:uuid}).strict(),method:'GET',path:a=>recordsRoot(a,kind)+'/'+a.id,scoped:true}],
+ ])),
+ tools_list:{schema:z.object(workspace).strict(),method:'GET',path:root,scoped:true},
+ tools_search:{schema:z.object({...workspace,query:z.string().trim().min(1).max(200),limit:z.number().int().min(1).max(50).optional()}).strict(),method:'GET',path:a=>root(a)+'/search?'+new URLSearchParams({q:a.query,...a.limit!==undefined?{limit:String(a.limit)}:{}}),scoped:true,description:'One search across hosted tools, Audienti CLI commands and skills. Product words work (ICP finds audience tools, commands and skills; enrich finds profile tools) and so do provider names. Returns compact rows only: id, kind (tool, command or skill), one-line description and, for paid tools, the price per call or the metered unit. Then tools_get for a tool\'s inputs and tools_call to run it.'},
+ tools_get:{schema:z.object({...workspace,tool:toolId}).strict(),method:'GET',path:a=>root(a)+'/'+encodeURIComponent(a.tool),scoped:true,description:'One catalog tool: input JSON schema, limits, price per call, whether it is configured and available now, and this workspace\'s own 30-day call count, success rate and median speed.'},
+ tools_call:{paid:true,generic:true,schema:z.object({...workspace,tool:toolId,requestId:uuid,input:z.record(z.string(),z.unknown())}).strict(),method:'POST',path:a=>root(a)+'/call',body:a=>({tool:a.tool,requestId:a.requestId,input:a.input}),scoped:true,timeoutMs:90000,description:'Run any catalog tool by id (audienti.<object>.<verb>) or old name (find ids with tools_search, inputs with tools_get). Record tools accept input cached:false to skip the saved record and make a fresh paid call. Charged through workspace credits like the per-tool operations. Generate requestId once and reuse it with the same input after any interruption or error: a replay is free and returns the saved result, a new ID is a new purchase. A timeout may have consumed paid work; inspect tools_runs_get rather than redispatching with a new ID. Positive credit balance is required for paid dispatch; completion may overdraw. Rejected means no provider dispatch.'},
+ tools_web_search:{tool:'web.search',paid:true,limits:{providerCalls:1,cacheHours:24},schema:z.object({...workspace,requestId:uuid,input:z.object({query:z.string().trim().min(1).max(1000),country:z.string().regex(/^[A-Za-z]{2}$/).optional(),language:z.string().regex(/^[a-z]{2}(?:-[A-Z]{2})?$/).optional(),page:z.number().int().min(1).max(100).optional(),limit:z.number().int().min(1).max(10).optional(),timeRange:z.enum(['day','week','month','year']).optional(),refresh:z.boolean().optional(),cached:z.boolean().optional()}).strict()}).strict(),method:'POST',path:a=>root(a)+'/web.search',body:a=>({requestId:a.requestId,input:a.input}),scoped:true,timeoutMs:30000},
+ tools_web_fetch:{tool:'web.fetch',paid:true,limits:{providerCalls:3,resultCache:false},schema:z.object({...workspace,requestId:uuid,input:z.object({url:z.string().min(1).max(2048)}).strict()}).strict(),method:'POST',path:a=>root(a)+'/web.fetch',body:a=>({requestId:a.requestId,input:a.input}),scoped:true,timeoutMs:90000},
+ tools_proxy_sessions_create:{tool:'proxy.sessions.create',paid:true,limits:{maxSeconds:3600,concurrentWorkspaceConnections:32,meter:'upstream_tcp_payload_bytes'},schema:z.object({...workspace,requestId:uuid,input:z.object({ttlSeconds:z.number().int().min(60).max(3600).optional(),parentOperationId:uuid.optional()}).strict()}).strict(),method:'POST',path:a=>root(a)+'/proxy.sessions.create',body:a=>({requestId:a.requestId,input:a.input}),scoped:true,timeoutMs:30000},
+ tools_proxy_sessions_close:{tool:'proxy.sessions.close',schema:z.object({...workspace,operationId:uuid}).strict(),method:'POST',path:a=>root(a)+'/proxy.sessions.close',body:a=>({operationId:a.operationId}),scoped:true},
+ tools_decide:{tool:'decide',paid:true,schema:z.object({...workspace,requestId:uuid,input:z.object({state:z.union([z.string(),z.record(z.string(),z.unknown()),z.array(z.unknown())]),questions:z.record(key,question).refine(v=>Object.keys(v).length>=1&&Object.keys(v).length<=16)}).strict()}).strict(),method:'POST',path:a=>root(a)+'/decide',body:a=>({requestId:a.requestId,input:a.input}),scoped:true,timeoutMs:30000},
+ tools_profiles_fetch:{tool:'profiles.fetch',paid:true,schema:z.object({...workspace,requestId:uuid,input:z.object({url:z.string().min(1).max(1024),refresh:z.boolean().optional(),cached:z.boolean().optional(),fields:z.array(z.enum(['name','headline','about','location','experience','currentPositions','education','skills','websites','photo','connections','followers','certifications','languages','industries','employeeCount','employeeCountRange','founded','specialities','locations','companyType'])).min(1).max(20).optional()}).strict()}).strict(),method:'POST',path:a=>root(a)+'/profiles.fetch',body:a=>({requestId:a.requestId,input:a.input}),scoped:true,timeoutMs:30000},
+ tools_runs_get:{schema:z.object({...workspace,operationId:uuid,attemptAfter:z.number().int().min(0).max(2147483647).optional(),entryAfter:uuid.optional()}).strict(),method:'GET',path:a=>root(a)+`/runs/${a.operationId}`+((a.attemptAfter!==undefined||a.entryAfter)?`?${new URLSearchParams({...a.attemptAfter!==undefined?{attemptAfter:String(a.attemptAfter)}:{},...a.entryAfter?{entryAfter:a.entryAfter}:{}})}`:''),scoped:true},
+ tools_runs_list:{schema:z.object({...workspace,cursor:uuid.optional()}).strict(),method:'GET',path:a=>root(a)+'/runs'+(a.cursor?`?cursor=${encodeURIComponent(a.cursor)}`:''),scoped:true},
+ tools_balance:{schema:z.object(workspace).strict(),method:'GET',path:a=>root(a)+'/balance',scoped:true},
+};
+
+hostedToolOperations.tools_profiles_search.description = 'Legacy external paid Profile search, not saved database search. Retrieves one fresh provider page. Reuse requestId after interruptions; a timeout may have consumed paid work. Inspect tools_runs_get rather than redispatching with a new ID.';
+// Compatibility aliases share server admission identity; response shape is explicit.
+const fetchDescriptor = hostedToolOperations.tools_profiles_fetch;
+const fetchInput = fetchDescriptor.schema.shape.input;
+hostedToolOperations.tools_profiles_enrich = {
+ ...fetchDescriptor, tool: 'profiles.enrich', description: 'Explicit paid Profile enrichment by URL or authorized saved Profile ID; eligible 30-day cache reuse is free and refresh forces paid admission. Returns operation plus current workspace Prospect/profile projection. Shares admission identity with profiles.fetch. Reuse requestId after interruptions; a timeout may have consumed paid work. Inspect tools_runs_get rather than redispatching with a new ID.', limits: { providerCalls: 1, normalizedBytes: 65536, cacheDays: 30 }, resultKey: 'operation', canonicalTool: 'profiles.fetch',
+ schema: fetchDescriptor.schema.extend({ input: z.union([fetchInput, fetchInput.omit({url:true}).extend({profileId:uuid}).strict()]) }),
+ path: a => root(a) + '/profiles.enrich',
+};
+hostedToolOperations.tools_profiles_discover = {
+ ...hostedToolOperations.tools_profiles_search, tool: 'profiles.discover', description: 'Explicit paid external Profile discovery. Same admission identity and result as legacy profiles.search. For saved workspace profiles use profile_list. Reuse requestId after interruptions; a timeout may have consumed paid work. Inspect tools_runs_get rather than redispatching with a new ID.', canonicalTool: 'profiles.search',
+ path: a => root(a) + '/profiles.discover',
+};
+export const paidToolOperations = Object.fromEntries(Object.entries(hostedToolOperations).filter(([,operation])=>operation.paid));
+export const paidToolByName = Object.fromEntries(Object.entries(paidToolOperations).filter(([,operation])=>operation.tool).map(([name,operation])=>[operation.tool,{name,...operation}]));
+// tools_call is paid except for the free proxy.sessions.close control call, which has no requestId or fee.
+export const isPaidToolOperation = (name, args) => name === 'tools_call' ? !['proxy.sessions.close', 'audienti.proxy.session.close'].includes(args?.tool) : Object.hasOwn(paidToolOperations, name);
+
+// Only known descriptor shape decides where a paid operation lives. Never infer
+// a nested operation for unrelated responses or let projection state mask billing.
+// Through tools_call the shape follows the resolved tool: profiles.enrich nests its operation.
+export const paidToolResult = (name, data, args) => {
+ if (name === 'tools_call') return ['profiles.enrich', 'audienti.people.profile.enrich'].includes(args?.tool) ? data?.operation : data;
+ const descriptor = paidToolOperations[name];
+ return descriptor?.resultKey ? data?.[descriptor.resultKey] : data;
+};
+

package/cli/tools.mjs

@@ -0,0 +1,100 @@
+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 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.
+
+web.search returns one selected result page; workspace cache lasts 24 hours (refresh=true bypasses it).
+web.fetch returns inert text/links through a bounded HTML waterfall. Each completed logical
+web result costs 0.1 credit ($1 per 1000); failed requests, cache hits and request replays are free.
+Uses the selected private profile/workspace. Supply --profile PATH when needed.
+email.verify accepts {email,refresh?}; it records provider deliverability evidence without establishing ownership or authorizing sending. It reuses workspace validation for seven days; refresh makes a configured paid validation. Cache and same-request replay are free.
+profiles.fetch accepts a person /in/ or company /company/ URL as {url,fields?,refresh?}; a complete saved profile is free for 30 days.
+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, 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 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,
+32 choices per question and 10 score levels. No provider credentials belong in input.
+The request ID must be saved and reused after a timeout or interruption; never create a
+new ID just to retry an uncertain operation. A rejected operation made no provider call;
+after fixing its cause (for example adding credits), use a new ID for new work. Results and diagnostics contain trace IDs.
+Example input: {"state":"Can we talk?","questions":{"interest":{"type":"boolean","instructions":"Does this express interest?"}}}
+JSON results go to stdout; failures go to stderr and exit nonzero.`;
+async function readStdin() {
+ const chunks=[];let size=0;
+ 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:parseOptions});
+ if(values.help||positionals.length===0){console.log(help);return;}
+ const [verb,sub,id]=positionals;
+ 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;}
+ else if(verb==='proxy.sessions.close'&&positionals.length===2){name='tools_proxy_sessions_close';args.operationId=sub;}
+ else if(Object.hasOwn(paidToolByName,verb)&&positionals.length===1){
+  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.');
+ 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

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+const uuid=z.string().uuid(), time=z.iso.datetime({offset:true}), version=z.number().int().min(0).max(2147483646);
+const reason=z.string().meta({minLength:1,maxLength:2000,description:'Trimmed NFC reason, 1–2000 Unicode code points, no controls or unpaired surrogates.'});
+const opaque=z.string().trim().min(1).max(256).regex(/^[ -~]+$/);
+const unavailable=z.object({availability:z.literal('unavailable'),reason}).strict();
+const evidence=z.discriminatedUnion('kind',[
+ z.object({kind:z.literal('provider_report'),reference:opaque,observedAt:time}).strict(),
+ z.object({kind:z.literal('account_evidence'),evidenceId:uuid,observedAt:time}).strict(),
+ z.object({kind:z.literal('owner_confirmation'),observedAt:time}).strict(),
+ z.object({kind:z.literal('no_dispatch'),journalRef:opaque,sealed:z.literal(true)}).strict(),
+ z.object({kind:z.literal('transport_uncertain'),reference:opaque,observedAt:time}).strict(),
+]);
+const content=z.union([
+ z.object({subject:z.string().meta({minLength:1,maxLength:256}),body:z.string().meta({minLength:1,maxLength:20000})}).strict(),
+ z.object({body:z.string().meta({minLength:1,maxLength:8000})}).strict(),
+]);
+export const workExecutionResultSchema=z.discriminatedUnion('outcome',[
+ z.object({outcome:z.literal('succeeded'),actualContent:z.union([unavailable,z.object({availability:z.literal('available'),content}).strict()]),providerMessageId:z.union([unavailable,z.object({availability:z.literal('available'),value:opaque}).strict()]),effectAt:time.nullable(),evidence}).strict(),
+ z.object({outcome:z.literal('failed'),effect:z.literal('none'),evidence}).strict(),
+ z.object({outcome:z.literal('unknown'),effect:z.literal('possible'),evidence}).strict(),
+]);
+const location={workspaceId:uuid.optional(),planId:uuid,clientActionId:z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/)};
+const path=a=>`/workspaces/${a.workspaceId}/work/${a.planId}/actions/${encodeURIComponent(a.clientActionId)}`;
+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`},
+ work_result_report:{schema:z.object({attemptId:uuid,requestId:uuid,mode:z.enum(['report','correct']),expectedResultVersion:version,reason,result:workExecutionResultSchema}).strict(),method:'POST',path:a=>`/work-execution/attempts/${a.attemptId}/results`,body},
+};
+export const workExecutionOperations={...workspaceExecutionOperations,...narrowExecutionOperations};

package/cli/work-execution.mjs

@@ -0,0 +1,29 @@
+import { workExecutionOperations } from './work-execution-operations.mjs';
+import { callWorkspace, configuration } from './workspaces.mjs';
+import { callOwnerAccountOperation } from './owner-account-client.mjs';
+import { readJsonFile } from './json-file.mjs';
+export function callWorkExecution(name,args,profile=process.env.AUDIENTI_PROFILE) {
+ const operation=workExecutionOperations[name];if(!operation)throw Error('Unknown work execution operation.');
+ return operation.scoped?callWorkspace(name,args,configuration(profile)):callOwnerAccountOperation(operation,args,profile,'work execution');
+}
+export async function workExecutionCli(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(!['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','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.');
+ if(!workspace&&!(command==='report'?flags.attempt:flags.claim))throw Error('Supply the claim or attempt ID.');
+ const input=read?{}:readJsonFile(flags.file,65536,'Work execution input');
+ if(!input||typeof input!=='object'||Array.isArray(input))throw Error('invalid_fields: input must be a JSON object.');
+ const paths=workspace?['workspaceId','planId','clientActionId']:command==='report'?['attemptId']:['claimId'];
+ if(paths.some(key=>Object.hasOwn(input,key)))throw Error('invalid_fields: path IDs come from positions and flags only.');
+ Object.assign(input,workspace?{planId:positions[3],clientActionId:flags.action,...(flags.workspace?{workspaceId:flags.workspace}:{})}:command==='report'?{attemptId:flags.attempt}:{claimId:flags.claim});
+ if(command==='get'){if(flags.cursor)input.historyCursor=flags.cursor;if(flags.limit)input.historyLimit=Number(flags.limit);}
+ console.log(JSON.stringify(await callWorkExecution(names[command],input,flags.profile)));
+}

package/cli/work-feedback-operations.mjs

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+const uuid = z.string().uuid(), version = z.number().int().positive();
+const actionId = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/);
+const reason = z.string().meta({ minLength: 1, maxLength: 2000, description: 'Trimmed NFC reason, 1–2000 Unicode code points; interior controls (including tabs/newlines) and unpaired surrogates are rejected. Visible to workspace members.' });
+const location = { workspaceId: uuid.optional(), planId: uuid };
+const item = { ...location, reviewRequestId: uuid };
+const mutation = { ...item, expectedVersion: version, requestId: uuid, reason };
+const root = a => `/workspaces/${a.workspaceId}/work/${a.planId}/change-requests`;
+const detail = a => `${root(a)}/${a.reviewRequestId}`;
+const body = ({ workspaceId, planId, clientActionId, reviewRequestId, ...input }) => input;
+export const workFeedbackOperations = {
+ workspace_work_change_request: { schema: z.object({ ...location, clientActionId: actionId, expectedRevision: version, expectedApprovalVersion: z.number().int().nonnegative(), kind: z.enum(['revise','alternative']), reason, requestId: uuid }).strict(), method: 'POST', scoped: true, path: a => `/workspaces/${a.workspaceId}/work/${a.planId}/actions/${a.clientActionId}/change-requests`, body },
+ workspace_work_change_respond: { schema: z.object({ ...mutation, responseRevision: version, responseClientActionId: actionId }).strict().describe('Respond with the changed original for Revise, or a new replacement after removing the original. Skip always requires a new action ID. A response never approves the proposal.'), method: 'POST', scoped: true, path: a => `${detail(a)}/respond`, body },
+ workspace_work_change_withdraw: { schema: z.object(mutation).strict(), method: 'POST', scoped: true, path: a => `${detail(a)}/withdraw`, body },
+ workspace_work_change_get: { schema: z.object(item).strict(), method: 'GET', scoped: true, path: detail },
+ workspace_work_change_list: { schema: z.object({ ...location, page: z.object({ cursor: uuid.optional(), limit: z.number().int().min(1).max(100).optional() }).strict().optional(), status: z.enum(['open','responded','withdrawn','cancelled']).optional() }).strict(), method: 'GET', scoped: true, path: a => { const q = new URLSearchParams(); for (const [key,value] of Object.entries({ ...a.page, status:a.status })) if(value!==undefined)q.set(key,String(value)); return `${root(a)}?${q}`; } },
+};

package/cli/work-feedback.mjs

@@ -0,0 +1,18 @@
+import { callWorkspace, configuration } from './workspaces.mjs';
+import { readJsonFile } from './json-file.mjs';
+export async function workFeedbackCli(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(!['profile','workspace','file','action','change','cursor','limit','status'].includes(key)||Object.hasOwn(flags,key)||!args[i+1]||args[i+1].startsWith('--'))throw new Error('Unknown, repeated, or incomplete work changes option.');flags[key]=args[++i]; }
+ const [, , command, planId]=positions;
+ if(positions.length!==4||!['request','respond','withdraw','get','list'].includes(command))throw new Error('Use work changes request|respond|withdraw|get|list PLAN.');
+ const read=['get','list'].includes(command),specific=command==='request'?['action']:command==='list'?['cursor','limit','status']:['change'];
+ const allowed=['profile','workspace',...specific,...(read?[]:['file'])];
+ if(Object.keys(flags).some(key=>!allowed.includes(key)))throw new Error('Option does not apply to this work changes command.');
+ if(command==='request'&&!flags.action)throw new Error('Request requires --action.');
+ if(!['request','list'].includes(command)&&!flags.change)throw new Error('This command requires --change.');
+ const input=read?{}:readJsonFile(flags.file,65536,'Work change input');
+ if(['workspaceId','planId','clientActionId','reviewRequestId'].some(key=>Object.hasOwn(input,key)))throw new Error('invalid_fields: location IDs come from flags and position only.');
+ Object.assign(input,{planId,...(flags.workspace?{workspaceId:flags.workspace}:{}),...(flags.action?{clientActionId:flags.action}:{}),...(flags.change?{reviewRequestId:flags.change}:{})});
+ if(command==='list'){input.page={...(flags.cursor?{cursor:flags.cursor}:{}),...(flags.limit?{limit:Number(flags.limit)}:{})};if(flags.status!==undefined)input.status=flags.status;}
+ console.log(JSON.stringify(await callWorkspace(`workspace_work_change_${command}`,input,configuration(flags.profile))));
+}

package/cli/work-operations.mjs

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+const uuid = z.string().uuid(), version = z.number().int().nonnegative();
+const workspace = { workspaceId: uuid.optional() };
+const page = z.object({cursor: uuid.optional(), limit: z.number().int().min(1).max(100).optional()}).strict();
+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, 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(),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}`;
+const plan = a => `${root(a)}/work/${a.planId}`;
+const action = a => `${plan(a)}/actions/${encodeURIComponent(a.clientActionId)}`;
+const omit = (a, keys) => Object.fromEntries(Object.entries(a).filter(([k])=>!keys.includes(k)));
+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_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

@@ -0,0 +1,32 @@
+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','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 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_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','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))));
+}