@agentled/cli 0.7.16 → 0.7.17

package/dist/commands/builder-work-items.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerBuilderWorkItemCommands(program: Command): void;

package/dist/commands/builder-work-items.js

@@ -0,0 +1,251 @@
+import { readFileSync } from 'node:fs';
+import { AgentledClient } from '../client.js';
+import { printError, printOutput } from '../utils/output.js';
+function readJsonOption(value, fallback) {
+    if (!value)
+        return fallback;
+    return JSON.parse(value);
+}
+function readJsonFileOption(path, fallback) {
+    if (!path)
+        return fallback;
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+function parseCsv(value) {
+    if (!value)
+        return undefined;
+    return value.split(',').map((item) => item.trim()).filter(Boolean);
+}
+function printCliError(error) {
+    printError(error instanceof Error ? error.message : String(error));
+}
+export function registerBuilderWorkItemCommands(program) {
+    const builders = program
+        .command('builders')
+        .description('Manage external AI builder profiles and work item handoffs');
+    const profile = builders.command('profile').description('Manage this API key\'s AI builder profile');
+    profile
+        .command('upsert')
+        .description('Create or update this API key\'s AI builder profile')
+        .requiredOption('--provider <provider>', 'Builder provider: codex, claude, openclaw, herms, or custom')
+        .requiredOption('--name <name>', 'Builder display name')
+        .option('--metadata <json>', 'JSON metadata object')
+        .option('--metadata-file <path>', 'Path to JSON metadata object')
+        .option('--format <fmt>', 'Output format', 'json')
+        .action(async (opts) => {
+        try {
+            const metadata = opts.metadataFile
+                ? readJsonFileOption(opts.metadataFile, {})
+                : readJsonOption(opts.metadata, {});
+            const result = await new AgentledClient().upsertAiBuilderProfile({
+                provider: opts.provider,
+                name: opts.name,
+                metadata,
+            });
+            printOutput(result, opts.format);
+        }
+        catch (error) {
+            printCliError(error);
+        }
+    });
+    const workItems = builders.command('work-items').description('Manage builder work item handoffs');
+    workItems
+        .command('list')
+        .description('List work items eligible for this authenticated builder')
+        .option('--status <csv>', 'Comma-separated statuses')
+        .option('--source-agent-entity-id <id>', 'Optional source business-agent ID filter')
+        .option('--type <type>', 'Optional work item type filter')
+        .option('--limit <n>', 'Maximum items to return')
+        .option('--format <fmt>', 'Output format', 'json')
+        .action(async (opts) => {
+        try {
+            const result = await new AgentledClient().listBuilderWorkItems({
+                status: parseCsv(opts.status),
+                sourceAgentEntityId: opts.sourceAgentEntityId,
+                type: opts.type,
+                limit: opts.limit ? Number(opts.limit) : undefined,
+            });
+            printOutput(result, opts.format);
+        }
+        catch (error) {
+            printCliError(error);
+        }
+    });
+    workItems
+        .command('list-for-agent <sourceAgentEntityId>')
+        .description('List builder work items for a business agent')
+        .option('--status <csv>', 'Comma-separated statuses')
+        .option('--type <type>', 'Optional work item type filter')
+        .option('--limit <n>', 'Maximum items to return')
+        .option('--format <fmt>', 'Output format', 'json')
+        .action(async (sourceAgentEntityId, opts) => {
+        try {
+            const result = await new AgentledClient().listBuilderWorkItemsForAgent({
+                sourceAgentEntityId,
+                status: parseCsv(opts.status),
+                type: opts.type,
+                limit: opts.limit ? Number(opts.limit) : undefined,
+            });
+            printOutput(result, opts.format);
+        }
+        catch (error) {
+            printCliError(error);
+        }
+    });
+    workItems
+        .command('create')
+        .description('Create a business-agent handoff for an external AI builder')
+        .requiredOption('--source-agent-entity-id <id>', 'Source business-agent ID')
+        .requiredOption('--title <title>', 'Work item title')
+        .requiredOption('--brief <brief>', 'Work item brief')
+        .option('--type <type>', 'Work item type')
+        .option('--builder-id <id>', 'Optional target builder ID')
+        .option('--context-refs <json>', 'JSON array of context refs')
+        .option('--context-refs-file <path>', 'Path to JSON array of context refs')
+        .option('--metadata <json>', 'JSON metadata object')
+        .option('--metadata-file <path>', 'Path to JSON metadata object')
+        .option('--format <fmt>', 'Output format', 'json')
+        .action(async (opts) => {
+        try {
+            const contextRefs = opts.contextRefsFile
+                ? readJsonFileOption(opts.contextRefsFile, [])
+                : readJsonOption(opts.contextRefs, []);
+            const metadata = opts.metadataFile
+                ? readJsonFileOption(opts.metadataFile, {})
+                : readJsonOption(opts.metadata, {});
+            const result = await new AgentledClient().createBuilderWorkItem({
+                sourceAgentEntityId: opts.sourceAgentEntityId,
+                title: opts.title,
+                brief: opts.brief,
+                type: opts.type,
+                builderId: opts.builderId,
+                contextRefs,
+                metadata,
+            });
+            printOutput(result, opts.format);
+        }
+        catch (error) {
+            printCliError(error);
+        }
+    });
+    workItems
+        .command('get <id>')
+        .description('Get a builder work item')
+        .option('--format <fmt>', 'Output format', 'json')
+        .action(async (id, opts) => {
+        try {
+            const result = await new AgentledClient().getBuilderWorkItem(id);
+            printOutput(result, opts.format);
+        }
+        catch (error) {
+            printCliError(error);
+        }
+    });
+    workItems
+        .command('claim <id>')
+        .description('Claim a builder work item as this registered builder')
+        .option('--status <status>', 'claimed or in_progress')
+        .option('--note <note>', 'Optional claim note')
+        .option('--format <fmt>', 'Output format', 'json')
+        .action(async (id, opts) => {
+        try {
+            const result = await new AgentledClient().claimBuilderWorkItem(id, {
+                status: opts.status,
+                note: opts.note,
+            });
+            printOutput(result, opts.format);
+        }
+        catch (error) {
+            printCliError(error);
+        }
+    });
+    workItems
+        .command('activity <id>')
+        .description('Append builder progress activity')
+        .requiredOption('--note <note>', 'Progress note')
+        .option('--activity-action <action>', 'Activity action label')
+        .option('--refs <json>', 'JSON array of refs')
+        .option('--format <fmt>', 'Output format', 'json')
+        .action(async (id, opts) => {
+        try {
+            const result = await new AgentledClient().appendBuilderWorkActivity(id, {
+                note: opts.note,
+                activityAction: opts.activityAction,
+                refs: readJsonOption(opts.refs, []),
+            });
+            printOutput(result, opts.format);
+        }
+        catch (error) {
+            printCliError(error);
+        }
+    });
+    workItems
+        .command('submit <id>')
+        .description('Submit completed builder work')
+        .requiredOption('--summary <summary>', 'Completion summary')
+        .option('--output-refs <json>', 'JSON array of output refs')
+        .option('--metadata <json>', 'JSON metadata object')
+        .option('--note <note>', 'Optional submit note')
+        .option('--format <fmt>', 'Output format', 'json')
+        .action(async (id, opts) => {
+        try {
+            const result = await new AgentledClient().submitBuilderWorkItem(id, {
+                summary: opts.summary,
+                outputRefs: readJsonOption(opts.outputRefs, []),
+                metadata: readJsonOption(opts.metadata, {}),
+                note: opts.note,
+            });
+            printOutput(result, opts.format);
+        }
+        catch (error) {
+            printCliError(error);
+        }
+    });
+    workItems
+        .command('review <id>')
+        .description('Review a submitted builder work item as a business agent')
+        .requiredOption('--verdict <verdict>', 'accepted, needs_changes, or closed')
+        .requiredOption('--note <note>', 'Review note')
+        .option('--source-agent-entity-id <id>', 'Source business-agent ID')
+        .option('--business-agent-rating <rating>', 'thumbs_up, thumbs_down, or neutral')
+        .option('--metadata <json>', 'JSON metadata object')
+        .option('--format <fmt>', 'Output format', 'json')
+        .action(async (id, opts) => {
+        try {
+            const result = await new AgentledClient().reviewBuilderWorkItem(id, {
+                verdict: opts.verdict,
+                note: opts.note,
+                sourceAgentEntityId: opts.sourceAgentEntityId,
+                businessAgentRating: opts.businessAgentRating,
+                metadata: readJsonOption(opts.metadata, {}),
+            });
+            printOutput(result, opts.format);
+        }
+        catch (error) {
+            printCliError(error);
+        }
+    });
+    workItems
+        .command('agent-activity <id>')
+        .description('Append business-agent activity to a builder work item')
+        .requiredOption('--note <note>', 'Activity note')
+        .option('--actor-id <id>', 'Business-agent actor ID')
+        .option('--activity-action <action>', 'Activity action label')
+        .option('--refs <json>', 'JSON array of refs')
+        .option('--format <fmt>', 'Output format', 'json')
+        .action(async (id, opts) => {
+        try {
+            const result = await new AgentledClient().appendBuilderWorkItemActivity(id, {
+                note: opts.note,
+                actorId: opts.actorId,
+                activityAction: opts.activityAction,
+                refs: readJsonOption(opts.refs, []),
+            });
+            printOutput(result, opts.format);
+        }
+        catch (error) {
+            printCliError(error);
+        }
+    });
+}
+//# sourceMappingURL=builder-work-items.js.map

package/dist/commands/builder-work-items.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder-work-items.js","sourceRoot":"","sources":["../../src/commands/builder-work-items.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,WAAW,EAAgB,MAAM,oBAAoB,CAAC;AAE3E,SAAS,cAAc,CAAC,KAAyB,EAAE,QAAiB;IAChE,IAAI,CAAC,KAAK;QAAE,OAAO,QAAQ,CAAC;IAC5B,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,kBAAkB,CAAC,IAAwB,EAAE,QAAiB;IACnE,IAAI,CAAC,IAAI;QAAE,OAAO,QAAQ,CAAC;IAC3B,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,QAAQ,CAAC,KAAyB;IACvC,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,OAAO,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACjC,UAAU,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,+BAA+B,CAAC,OAAgB;IAC5D,MAAM,QAAQ,GAAG,OAAO;SACnB,OAAO,CAAC,UAAU,CAAC;SACnB,WAAW,CAAC,4DAA4D,CAAC,CAAC;IAE/E,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,WAAW,CAAC,2CAA2C,CAAC,CAAC;IAErG,OAAO;SACF,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,qDAAqD,CAAC;SAClE,cAAc,CAAC,uBAAuB,EAAE,6DAA6D,CAAC;SACtG,cAAc,CAAC,eAAe,EAAE,sBAAsB,CAAC;SACvD,MAAM,CAAC,mBAAmB,EAAE,sBAAsB,CAAC;SACnD,MAAM,CAAC,wBAAwB,EAAE,8BAA8B,CAAC;SAChE,MAAM,CAAC,gBAAgB,EAAE,eAAe,EAAE,MAAM,CAAC;SACjD,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACnB,IAAI,CAAC;YACD,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY;gBAC9B,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;gBAC3C,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;YACxC,MAAM,MAAM,GAAG,MAAM,IAAI,cAAc,EAAE,CAAC,sBAAsB,CAAC;gBAC7D,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,QAAQ;aACX,CAAC,CAAC;YACH,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,MAAsB,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACtB,aAAa,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;IACL,CAAC,CAAC,CAAC;IAEP,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,WAAW,CAAC,mCAAmC,CAAC,CAAC;IAElG,SAAS;SACJ,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,yDAAyD,CAAC;SACtE,MAAM,CAAC,gBAAgB,EAAE,0BAA0B,CAAC;SACpD,MAAM,CAAC,+BAA+B,EAAE,0CAA0C,CAAC;SACnF,MAAM,CAAC,eAAe,EAAE,gCAAgC,CAAC;SACzD,MAAM,CAAC,aAAa,EAAE,yBAAyB,CAAC;SAChD,MAAM,CAAC,gBAAgB,EAAE,eAAe,EAAE,MAAM,CAAC;SACjD,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACnB,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,IAAI,cAAc,EAAE,CAAC,oBAAoB,CAAC;gBAC3D,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC;gBAC7B,mBAAmB,EAAE,IAAI,CAAC,mBAAmB;gBAC7C,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;aACrD,CAAC,CAAC;YACH,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,MAAsB,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACtB,aAAa,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;IACL,CAAC,CAAC,CAAC;IAEP,SAAS;SACJ,OAAO,CAAC,sCAAsC,CAAC;SAC/C,WAAW,CAAC,8CAA8C,CAAC;SAC3D,MAAM,CAAC,gBAAgB,EAAE,0BAA0B,CAAC;SACpD,MAAM,CAAC,eAAe,EAAE,gCAAgC,CAAC;SACzD,MAAM,CAAC,aAAa,EAAE,yBAAyB,CAAC;SAChD,MAAM,CAAC,gBAAgB,EAAE,eAAe,EAAE,MAAM,CAAC;SACjD,MAAM,CAAC,KAAK,EAAE,mBAAmB,EAAE,IAAI,EAAE,EAAE;QACxC,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,IAAI,cAAc,EAAE,CAAC,4BAA4B,CAAC;gBACnE,mBAAmB;gBACnB,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC;gBAC7B,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;aACrD,CAAC,CAAC;YACH,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,MAAsB,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACtB,aAAa,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;IACL,CAAC,CAAC,CAAC;IAEP,SAAS;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,4DAA4D,CAAC;SACzE,cAAc,CAAC,+BAA+B,EAAE,0BAA0B,CAAC;SAC3E,cAAc,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;SACpD,cAAc,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;SACpD,MAAM,CAAC,eAAe,EAAE,gBAAgB,CAAC;SACzC,MAAM,CAAC,mBAAmB,EAAE,4BAA4B,CAAC;SACzD,MAAM,CAAC,uBAAuB,EAAE,4BAA4B,CAAC;SAC7D,MAAM,CAAC,4BAA4B,EAAE,oCAAoC,CAAC;SAC1E,MAAM,CAAC,mBAAmB,EAAE,sBAAsB,CAAC;SACnD,MAAM,CAAC,wBAAwB,EAAE,8BAA8B,CAAC;SAChE,MAAM,CAAC,gBAAgB,EAAE,eAAe,EAAE,MAAM,CAAC;SACjD,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACnB,IAAI,CAAC;YACD,MAAM,WAAW,GAAG,IAAI,CAAC,eAAe;gBACpC,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,CAAC;gBAC9C,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;YAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY;gBAC9B,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;gBAC3C,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;YACxC,MAAM,MAAM,GAAG,MAAM,IAAI,cAAc,EAAE,CAAC,qBAAqB,CAAC;gBAC5D,mBAAmB,EAAE,IAAI,CAAC,mBAAmB;gBAC7C,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,WAAW;gBACX,QAAQ;aACX,CAAC,CAAC;YACH,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,MAAsB,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACtB,aAAa,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;IACL,CAAC,CAAC,CAAC;IAEP,SAAS;SACJ,OAAO,CAAC,UAAU,CAAC;SACnB,WAAW,CAAC,yBAAyB,CAAC;SACtC,MAAM,CAAC,gBAAgB,EAAE,eAAe,EAAE,MAAM,CAAC;SACjD,MAAM,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE;QACvB,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,IAAI,cAAc,EAAE,CAAC,kBAAkB,CAAC,EAAE,CAAC,CAAC;YACjE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,MAAsB,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACtB,aAAa,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;IACL,CAAC,CAAC,CAAC;IAEP,SAAS;SACJ,OAAO,CAAC,YAAY,CAAC;SACrB,WAAW,CAAC,sDAAsD,CAAC;SACnE,MAAM,CAAC,mBAAmB,EAAE,wBAAwB,CAAC;SACrD,MAAM,CAAC,eAAe,EAAE,qBAAqB,CAAC;SAC9C,MAAM,CAAC,gBAAgB,EAAE,eAAe,EAAE,MAAM,CAAC;SACjD,MAAM,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE;QACvB,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,IAAI,cAAc,EAAE,CAAC,oBAAoB,CAAC,EAAE,EAAE;gBAC/D,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,IAAI,EAAE,IAAI,CAAC,IAAI;aAClB,CAAC,CAAC;YACH,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,MAAsB,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACtB,aAAa,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;IACL,CAAC,CAAC,CAAC;IAEP,SAAS;SACJ,OAAO,CAAC,eAAe,CAAC;SACxB,WAAW,CAAC,kCAAkC,CAAC;SAC/C,cAAc,CAAC,eAAe,EAAE,eAAe,CAAC;SAChD,MAAM,CAAC,4BAA4B,EAAE,uBAAuB,CAAC;SAC7D,MAAM,CAAC,eAAe,EAAE,oBAAoB,CAAC;SAC7C,MAAM,CAAC,gBAAgB,EAAE,eAAe,EAAE,MAAM,CAAC;SACjD,MAAM,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE;QACvB,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,IAAI,cAAc,EAAE,CAAC,yBAAyB,CAAC,EAAE,EAAE;gBACpE,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,cAAc,EAAE,IAAI,CAAC,cAAc;gBACnC,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;aACtC,CAAC,CAAC;YACH,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,MAAsB,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACtB,aAAa,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;IACL,CAAC,CAAC,CAAC;IAEP,SAAS;SACJ,OAAO,CAAC,aAAa,CAAC;SACtB,WAAW,CAAC,+BAA+B,CAAC;SAC5C,cAAc,CAAC,qBAAqB,EAAE,oBAAoB,CAAC;SAC3D,MAAM,CAAC,sBAAsB,EAAE,2BAA2B,CAAC;SAC3D,MAAM,CAAC,mBAAmB,EAAE,sBAAsB,CAAC;SACnD,MAAM,CAAC,eAAe,EAAE,sBAAsB,CAAC;SAC/C,MAAM,CAAC,gBAAgB,EAAE,eAAe,EAAE,MAAM,CAAC;SACjD,MAAM,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE;QACvB,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,IAAI,cAAc,EAAE,CAAC,qBAAqB,CAAC,EAAE,EAAE;gBAChE,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,UAAU,EAAE,cAAc,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;gBAC/C,QAAQ,EAAE,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;gBAC3C,IAAI,EAAE,IAAI,CAAC,IAAI;aAClB,CAAC,CAAC;YACH,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,MAAsB,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACtB,aAAa,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;IACL,CAAC,CAAC,CAAC;IAEP,SAAS;SACJ,OAAO,CAAC,aAAa,CAAC;SACtB,WAAW,CAAC,0DAA0D,CAAC;SACvE,cAAc,CAAC,qBAAqB,EAAE,oCAAoC,CAAC;SAC3E,cAAc,CAAC,eAAe,EAAE,aAAa,CAAC;SAC9C,MAAM,CAAC,+BAA+B,EAAE,0BAA0B,CAAC;SACnE,MAAM,CAAC,kCAAkC,EAAE,oCAAoC,CAAC;SAChF,MAAM,CAAC,mBAAmB,EAAE,sBAAsB,CAAC;SACnD,MAAM,CAAC,gBAAgB,EAAE,eAAe,EAAE,MAAM,CAAC;SACjD,MAAM,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE;QACvB,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,IAAI,cAAc,EAAE,CAAC,qBAAqB,CAAC,EAAE,EAAE;gBAChE,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,mBAAmB,EAAE,IAAI,CAAC,mBAAmB;gBAC7C,mBAAmB,EAAE,IAAI,CAAC,mBAAmB;gBAC7C,QAAQ,EAAE,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;aAC9C,CAAC,CAAC;YACH,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,MAAsB,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACtB,aAAa,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;IACL,CAAC,CAAC,CAAC;IAEP,SAAS;SACJ,OAAO,CAAC,qBAAqB,CAAC;SAC9B,WAAW,CAAC,uDAAuD,CAAC;SACpE,cAAc,CAAC,eAAe,EAAE,eAAe,CAAC;SAChD,MAAM,CAAC,iBAAiB,EAAE,yBAAyB,CAAC;SACpD,MAAM,CAAC,4BAA4B,EAAE,uBAAuB,CAAC;SAC7D,MAAM,CAAC,eAAe,EAAE,oBAAoB,CAAC;SAC7C,MAAM,CAAC,gBAAgB,EAAE,eAAe,EAAE,MAAM,CAAC;SACjD,MAAM,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE;QACvB,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,IAAI,cAAc,EAAE,CAAC,6BAA6B,CAAC,EAAE,EAAE;gBACxE,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,cAAc,EAAE,IAAI,CAAC,cAAc;gBACnC,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;aACtC,CAAC,CAAC;YACH,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,MAAsB,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACtB,aAAa,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;IACL,CAAC,CAAC,CAAC;AACX,CAAC"}

package/dist/index.js

@@ -42,6 +42,7 @@ import { registerInitCommand } from './commands/init.js';
 import { registerFixtureCommands } from './commands/fixture.js';
 import { registerTestCommand } from './commands/test.js';
 import { registerDryRunCommand } from './commands/dryrun.js';
+import { registerBuilderWorkItemCommands } from './commands/builder-work-items.js';
 import { checkForUpdate, printUpdateNotice } from './update-check.js';
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
@@ -98,6 +99,7 @@ registerInitCommand(program);
 registerFixtureCommands(program);
 registerTestCommand(program);
 registerDryRunCommand(program);
+registerBuilderWorkItemCommands(program);
 await program.parseAsync();
 await updatePromise;
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentled/cli",
-  "version": "0.7.16",
+  "version": "0.7.17",
   "description": "CLI for Agentled — manage workflows, apps, and knowledge from the command line. Zero context-window cost for AI agents.",
   "type": "module",
   "main": "dist/index.js",

package/skills/agentled/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agentled
-version: 0.7.0
+version: 0.7.1
 description: Build, manage, and execute Agentled AI workflows via MCP tools. Use when the user asks to create workflows, automate tasks, enrich leads, scrape websites, find emails, manage executions, or interact with any Agentled workspace capability.
 user-invocable: false
 ---
@@ -77,6 +77,38 @@ If MCP tools are already connected and working, **do not block** on missing loca
 
 `agentled setup` is the full first-run path (auth, workspace folder scaffold, MCP config, skill install, knowledge probe). `agentled init` is the targeted local scaffold when they only want the local workspace folder and cache.
 
+### CLI freshness
+
+Use the latest `@agentled/cli` for setup, local scaffolds, fixtures, tests, and
+builder-work CLI commands. Prefer `npx -y @agentled/cli@latest ...` for one-off
+setup commands. If using a global `agentled` install, run `agentled --version`
+or any CLI command and follow the update notice when it reports a newer version.
+
+Do not block a working MCP-only task just because the local CLI is absent or old.
+Only update/install the CLI when the task needs CLI-backed setup, local files,
+fixtures, tests, or builder-work commands.
+
+### External builder setup
+
+When this session is acting as an external AI builder for Agentled work items,
+register or refresh the builder identity before listing, claiming, or submitting
+builder work. This links the current API key to a visible builder profile in
+Developer settings and lets business agents attribute work correctly.
+
+- If MCP is available, call `upsert_ai_builder_profile` once per API key with
+  the provider (`codex`, `claude`, `openclaw`, `herms`, or `custom`), a clear
+  display name, and optional metadata such as capabilities or setup state.
+- If only shell/CLI access is available, run:
+
+```bash
+agentled builders profile upsert --provider codex --name "Codex"
+```
+
+After the profile exists, use `list_builder_work_items` / `agentled builders
+work-items list` according to the polling cadence in the MCP tool description.
+If a builder-work command returns `Call upsert_ai_builder_profile...`, do that
+setup step and retry; do not ask the user to create the profile manually.
+
 ### First-run setup: choose the target AI client
 
 When helping a user connect Agentled to a specific AI client, tell the CLI which
@@ -172,6 +204,26 @@ agentled best-practices                             # summary + link to agentic-
 
 > **Silent-strip failures caught by preflight:** invalid `type` on a context / input-page field (e.g. `"multi-select"`, `"checkbox"`, `"number"`) and invalid `builtinType` on an `aiActionWithTools` tool (e.g. `"web-search"`, `"memory"`) both get silently stripped by the runtime — `workflows validate` now flags them with a "did you mean" fix.
 
+### Prompt caching for repeated AI steps
+
+Provider prompt caching reduces cost/latency by reusing the identical prompt prefix; it does not cache or replay the AI answer. For high-volume `aiAction`, `aiActionWithTools`, and looped AI steps, put stable role, task, rubric, examples, output schema, and formatting rules before the first `{{...}}` variable.
+
+Use this layout:
+
+```text
+[stable role and task]
+[stable rubric / scoring dimensions]
+[stable output JSON schema]
+[stable examples or decision rules]
+
+Runtime inputs:
+{{currentItem}}
+{{steps.previous.output}}
+{{input.field}}
+```
+
+Avoid starting prompts with `INPUTS`, `{{currentItem}}`, `{{steps.*}}`, `{{input.*}}`, `{{execution.id}}`, `{{now}}`, or `{{today}}`. In batch workflows like investor matching, keep the long scoring rubric first and put the startup/investor payload at the end so OpenAI/Anthropic can cache the shared prefix.
+
 **Which pattern to read, by task:**
 
 | You're building… | Read pattern | Scaffold |