@myapihq/cli 1.2.8 → 1.3.0

package/dist/commands/queue-validation.test.js

@@ -0,0 +1,38 @@
+// Unit tests for the queue CLI's pure validators.
+import { describe, it, expect } from 'vitest';
+import { _validateConsumerUrl, _parseDependsOn } from './queue.js';
+describe('_validateConsumerUrl', () => {
+    it.each([
+        'https://example.com/consume',
+        'http://example.com/consume',
+        'https://fn.myapi.com/org/fn_123',
+        'https://example.com:8443/path?q=v',
+    ])('accepts %s', (url) => {
+        expect(_validateConsumerUrl(url)).toBeNull();
+    });
+    it.each([
+        ['ftp://example.com', /http:\/\/ or https:\/\//],
+        ['javascript:alert(1)', /http:\/\/ or https:\/\//],
+        ['file:///etc/passwd', /http:\/\/ or https:\/\//],
+    ])('rejects non-http(s) %s', (url, re) => {
+        expect(_validateConsumerUrl(url)).toMatch(re);
+    });
+    it.each(['not a url', 'just-text', 'http//missing-colon'])('rejects malformed %s', (url) => {
+        expect(_validateConsumerUrl(url)).toMatch(/not a valid URL/);
+    });
+});
+describe('_parseDependsOn', () => {
+    it('returns undefined for empty / non-string input', () => {
+        expect(_parseDependsOn(undefined)).toBeUndefined();
+        expect(_parseDependsOn('')).toBeUndefined();
+        expect(_parseDependsOn('   ')).toBeUndefined();
+        expect(_parseDependsOn(true)).toBeUndefined();
+    });
+    it('splits a comma-separated list and trims', () => {
+        expect(_parseDependsOn('j1,j2,j3')).toEqual(['j1', 'j2', 'j3']);
+        expect(_parseDependsOn(' j1 , j2 ')).toEqual(['j1', 'j2']);
+    });
+    it('drops empty segments', () => {
+        expect(_parseDependsOn('j1,,j2,')).toEqual(['j1', 'j2']);
+    });
+});

package/dist/commands/queue.d.ts

@@ -0,0 +1,14 @@
+import type { FlagSchema } from '../flags.js';
+import { type Flags } from '../helpers.js';
+import type { Exposes } from '../exposes.js';
+export declare const EXPOSES: Exposes;
+export declare const SCHEMA: FlagSchema;
+export declare function _validateConsumerUrl(url: string): string | null;
+export declare function _parseDependsOn(raw: unknown): string[] | undefined;
+export declare function create(name: string, flags: Flags): Promise<void>;
+export declare function list(flags: Flags): Promise<void>;
+export declare function get(name: string, flags: Flags): Promise<void>;
+export declare function enqueue(name: string, flags: Flags): Promise<void>;
+export declare function jobs(name: string, flags: Flags): Promise<void>;
+export declare function job(jobId: string, flags: Flags): Promise<void>;
+export declare function run(subcommand: string | undefined, args: string[], flags: Flags): Promise<void>;

package/dist/commands/queue.js

@@ -0,0 +1,215 @@
+import { queue as sdkQueue } from '@myapihq/sdk';
+import { requireConfig } from '../config.js';
+import { success, error, printTable, info, printJson } from '../output.js';
+import { formatDate } from '../utils.js';
+import { requireOrg, requireArg } from '../helpers.js';
+export const EXPOSES = [
+    'POST /queue/orgs/{org_id}/queues',
+    'GET /queue/orgs/{org_id}/queues',
+    'GET /queue/orgs/{org_id}/queues/{name}',
+    'POST /queue/orgs/{org_id}/queues/{name}/jobs',
+    'GET /queue/orgs/{org_id}/queues/{name}/jobs',
+    'GET /queue/orgs/{org_id}/jobs/{id}',
+];
+export const SCHEMA = {
+    name: 'string',
+    'consumer-url': 'string',
+    'max-attempts': 'number',
+    'max-concurrency': 'number',
+    payload: 'string',
+    'dedup-key': 'string',
+    delay: 'number',
+    'depends-on': 'string',
+    status: 'string',
+    limit: 'number',
+};
+// Pure validator — returns an error message or null. Mirrors
+// webhook.ts's _validateForwardUrl so it's unit-testable.
+export function _validateConsumerUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return `consumer URL "${url}" is not a valid URL.`;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return `consumer URL must use http:// or https:// — got "${url}".`;
+    }
+    return null;
+}
+// Parses a comma-separated --depends-on flag into a clean id array.
+export function _parseDependsOn(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return undefined;
+    return raw.split(',').map(s => s.trim()).filter(Boolean);
+}
+// ── Queues ───────────────────────────────────────────────────────────────────
+export async function create(name, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi queue create <name> --consumer-url <url> [--org <id>]');
+    const queueName = name || flags.name;
+    requireArg(queueName, 'name', 'myapi queue create <name> --consumer-url <url>');
+    const consumerUrl = flags['consumer-url'];
+    if (typeof consumerUrl !== 'string' || consumerUrl === '') {
+        error('Missing --consumer-url.\nUsage: myapi queue create <name> --consumer-url <url> [--max-attempts <n>] [--max-concurrency <n>]');
+    }
+    const urlErr = _validateConsumerUrl(consumerUrl);
+    if (urlErr)
+        error(urlErr);
+    const q = await sdkQueue.createQueue(config.api_key, orgId, {
+        name: queueName,
+        consumerUrl,
+        maxAttempts: typeof flags['max-attempts'] === 'number' ? flags['max-attempts'] : undefined,
+        maxConcurrency: typeof flags['max-concurrency'] === 'number' ? flags['max-concurrency'] : undefined,
+    });
+    if (flags.json) {
+        printJson(q);
+        return;
+    }
+    success(`Queue created: ${q.name}`);
+    info(`Consumer:        ${q.consumer_url}`);
+    info(`Max attempts:    ${q.max_attempts}`);
+    info(`Max concurrency: ${q.max_concurrency}`);
+}
+export async function list(flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi queue list [--org <id>]');
+    const queues = await sdkQueue.listQueues(config.api_key, orgId);
+    if (flags.json) {
+        printJson(queues);
+        return;
+    }
+    printTable(queues.map(q => ({ name: q.name })), {
+        flags,
+        empty: 'No queues yet. Create one with: myapi queue create <name> --consumer-url <url>',
+    });
+}
+export async function get(name, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi queue get <name> [--org <id>]');
+    requireArg(name, 'name', 'myapi queue get <name>');
+    const q = await sdkQueue.getQueue(config.api_key, orgId, name);
+    if (flags.json) {
+        printJson(q);
+        return;
+    }
+    info(`Name:            ${q.name}`);
+    info(`Consumer:        ${q.consumer_url}`);
+    info(`Max attempts:    ${q.max_attempts}`);
+    info(`Max concurrency: ${q.max_concurrency}`);
+}
+// ── Jobs ─────────────────────────────────────────────────────────────────────
+export async function enqueue(name, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi queue enqueue <name> --payload <json> [--org <id>]');
+    requireArg(name, 'name', 'myapi queue enqueue <name> --payload <json>');
+    let payload;
+    if (typeof flags.payload === 'string') {
+        try {
+            payload = JSON.parse(flags.payload);
+        }
+        catch (e) {
+            error(`--payload is not valid JSON: ${e?.message ?? e}`);
+        }
+    }
+    else if (flags.payload === true) {
+        error('--payload needs a JSON value, e.g. --payload \'{"order_id":42}\'');
+    }
+    const job = await sdkQueue.enqueueJob(config.api_key, orgId, name, {
+        payload,
+        dedupKey: typeof flags['dedup-key'] === 'string' ? flags['dedup-key'] : undefined,
+        delaySeconds: typeof flags.delay === 'number' ? flags.delay : undefined,
+        dependsOn: _parseDependsOn(flags['depends-on']),
+    });
+    if (flags.json) {
+        printJson(job);
+        return;
+    }
+    success(`Job enqueued: ${job.id}`);
+    info(`Status: ${job.status}`);
+}
+export async function jobs(name, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi queue jobs <name> [--status <s>] [--limit <n>] [--org <id>]');
+    requireArg(name, 'name', 'myapi queue jobs <name>');
+    const list = await sdkQueue.listJobs(config.api_key, orgId, name, {
+        status: typeof flags.status === 'string' ? flags.status : undefined,
+        limit: typeof flags.limit === 'number' ? flags.limit : undefined,
+    });
+    if (flags.json) {
+        printJson(list);
+        return;
+    }
+    printTable(list.map(j => ({
+        id: j.id,
+        status: j.status,
+        attempt: j.attempt,
+        created: j.created_at ? formatDate(j.created_at) : '',
+    })), { flags, empty: 'No jobs in this queue.' });
+}
+export async function job(jobId, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi queue job <job_id> [--org <id>]');
+    requireArg(jobId, 'job_id', 'myapi queue job <job_id>');
+    const j = await sdkQueue.getJob(config.api_key, orgId, jobId);
+    if (flags.json) {
+        printJson(j);
+        return;
+    }
+    info(`Job:      ${j.id}`);
+    info(`Queue:    ${j.queue_id}`);
+    info(`Status:   ${j.status}`);
+    info(`Attempt:  ${j.attempt} / ${j.max_attempts}`);
+    if (j.last_error)
+        info(`Error:    ${j.last_error}`);
+}
+// ── Dispatcher ───────────────────────────────────────────────────────────────
+const SUBCOMMAND_USAGE = {
+    'create': 'myapi queue create <name> --consumer-url <url> [--max-attempts <n>] [--max-concurrency <n>] [--org <id>]',
+    'list': 'myapi queue list [--org <id>] [--json]',
+    'get': 'myapi queue get <name> [--org <id>] [--json]',
+    'enqueue': 'myapi queue enqueue <name> --payload <json> [--dedup-key <k>] [--delay <seconds>] [--depends-on <id,id>] [--org <id>]',
+    'jobs': 'myapi queue jobs <name> [--status <s>] [--limit <n>] [--org <id>] [--json]',
+    'job': 'myapi queue job <job_id> [--org <id>] [--json]',
+};
+export async function run(subcommand, args, flags) {
+    if (!subcommand || (flags.help && !subcommand)) {
+        info(`Usage: myapi queue <subcommand>
+
+A durable HTTP-consumer job queue — jobs are POSTed to the queue's
+consumer_url with retry/backoff, a concurrency cap, and a dependency DAG.
+
+Queues:
+  create <name>     Create a queue (--consumer-url, --max-attempts, --max-concurrency)
+  list              List queues
+  get <name>        Show a queue's policy
+
+Jobs:
+  enqueue <name>    Enqueue a job (--payload, --dedup-key, --delay, --depends-on)
+  jobs <name>       List a queue's jobs (--status, --limit)
+  job <job_id>      Show a single job's status
+
+For "needs a decision" work (agent/human), see: myapi task --help
+
+All commands accept --org <id> (or set default: myapi config set-org <id>).`);
+        return;
+    }
+    if (flags.help) {
+        const usage = SUBCOMMAND_USAGE[subcommand];
+        if (usage)
+            info(`Usage: ${usage}`);
+        else
+            info(`Unknown subcommand: ${subcommand}. Run "myapi queue --help" for the list.`);
+        return;
+    }
+    switch (subcommand) {
+        case 'create': return create(args[0], flags);
+        case 'list': return list(flags);
+        case 'get': return get(args[0], flags);
+        case 'enqueue': return enqueue(args[0], flags);
+        case 'jobs': return jobs(args[0], flags);
+        case 'job': return job(args[0], flags);
+        default: error(`Unknown subcommand: ${subcommand}. Run "myapi queue --help" for a list of valid subcommands.`);
+    }
+}

package/dist/commands/task-validation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/task-validation.test.js

@@ -0,0 +1,37 @@
+// Unit tests for the task CLI's pure parsers.
+import { describe, it, expect } from 'vitest';
+import { _parseResolveOn, _splitList } from './task.js';
+describe('_parseResolveOn', () => {
+    it('parses a bare event type', () => {
+        expect(_parseResolveOn('payment.succeeded')).toEqual({ event_type: 'payment.succeeded' });
+    });
+    it('parses event_type:field=value', () => {
+        expect(_parseResolveOn('payment.succeeded:order_id=o_42')).toEqual({
+            event_type: 'payment.succeeded', field: 'order_id', value: 'o_42',
+        });
+    });
+    it('keeps = signs inside the value', () => {
+        expect(_parseResolveOn('evt:token=a=b=c')).toEqual({
+            event_type: 'evt', field: 'token', value: 'a=b=c',
+        });
+    });
+    it('rejects an empty string', () => {
+        expect(_parseResolveOn('   ')).toMatch(/cannot be empty/);
+    });
+    it('rejects a leading colon (no event type)', () => {
+        expect(_parseResolveOn(':field=value')).toMatch(/must start with an event type/);
+    });
+    it('rejects a field match without =', () => {
+        expect(_parseResolveOn('evt:justfield')).toMatch(/field=value/);
+    });
+});
+describe('_splitList', () => {
+    it('returns undefined for empty / non-string input', () => {
+        expect(_splitList(undefined)).toBeUndefined();
+        expect(_splitList('')).toBeUndefined();
+        expect(_splitList(true)).toBeUndefined();
+    });
+    it('splits and trims, dropping empties', () => {
+        expect(_splitList('support, sales ,, billing')).toEqual(['support', 'sales', 'billing']);
+    });
+});

package/dist/commands/task.d.ts

@@ -0,0 +1,18 @@
+import { task as sdkTask } from '@myapihq/sdk';
+import type { FlagSchema } from '../flags.js';
+import { type Flags } from '../helpers.js';
+import type { Exposes } from '../exposes.js';
+export declare const EXPOSES: Exposes;
+export declare const SCHEMA: FlagSchema;
+export declare const TASK_IMPORTANCE: readonly ["low", "normal", "high", "critical"];
+export declare function _parseResolveOn(raw: string): sdkTask.ResolveOn | string;
+export declare function _splitList(raw: unknown): string[] | undefined;
+export declare function create(description: string, flags: Flags): Promise<void>;
+export declare function list(flags: Flags): Promise<void>;
+export declare function get(id: string, flags: Flags): Promise<void>;
+export declare function claim(id: string, flags: Flags): Promise<void>;
+export declare function extend(id: string, flags: Flags): Promise<void>;
+export declare function resolve(id: string, flags: Flags): Promise<void>;
+export declare function fail(id: string, flags: Flags): Promise<void>;
+export declare function cancel(id: string, flags: Flags): Promise<void>;
+export declare function run(subcommand: string | undefined, args: string[], flags: Flags): Promise<void>;

package/dist/commands/task.js

@@ -0,0 +1,288 @@
+import { task as sdkTask } from '@myapihq/sdk';
+import { requireConfig } from '../config.js';
+import { success, error, printTable, info, printJson } from '../output.js';
+import { formatDate } from '../utils.js';
+import { requireOrg, requireArg } from '../helpers.js';
+import * as fs from 'fs';
+export const EXPOSES = [
+    'POST /task/orgs/{org_id}/tasks',
+    'GET /task/orgs/{org_id}/tasks',
+    'GET /task/orgs/{org_id}/tasks/{id}',
+    'DELETE /task/orgs/{org_id}/tasks/{id}',
+    'GET /task/orgs/{org_id}/tasks/{id}/body',
+    'POST /task/orgs/{org_id}/tasks/{id}/claim',
+    'POST /task/orgs/{org_id}/tasks/{id}/extend',
+    'POST /task/orgs/{org_id}/tasks/{id}/fail',
+    'POST /task/orgs/{org_id}/tasks/{id}/resolve',
+];
+export const SCHEMA = {
+    body: 'string',
+    importance: 'string',
+    due: 'string',
+    assignee: 'string',
+    tag: 'string',
+    'depends-on': 'string',
+    'dedup-key': 'string',
+    'resolve-on': 'string',
+    source: 'string',
+    status: 'string',
+    limit: 'number',
+    lease: 'number',
+    worker: 'string',
+    reason: 'string',
+};
+// The backend's fixed importance enum — validated client-side so a typo
+// fails before the network call.
+export const TASK_IMPORTANCE = ['low', 'normal', 'high', 'critical'];
+// Parses --resolve-on "<event_type>[:<field>=<value>]" into a matcher.
+// Returns the parsed object, or a string error message.
+export function _parseResolveOn(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === '')
+        return '--resolve-on cannot be empty.';
+    const colon = trimmed.indexOf(':');
+    if (colon === -1)
+        return { event_type: trimmed };
+    const eventType = trimmed.slice(0, colon);
+    const rest = trimmed.slice(colon + 1);
+    if (eventType === '')
+        return '--resolve-on must start with an event type, e.g. payment.succeeded:amount=100';
+    const eq = rest.indexOf('=');
+    if (eq === -1) {
+        return `--resolve-on field match must look like field=value — got "${rest}".`;
+    }
+    return { event_type: eventType, field: rest.slice(0, eq), value: rest.slice(eq + 1) };
+}
+// Parses a comma-separated --tag / --depends-on flag into a clean array.
+export function _splitList(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return undefined;
+    return raw.split(',').map(s => s.trim()).filter(Boolean);
+}
+// --body accepts inline text or @path to read a Markdown file.
+function resolveBody(raw) {
+    if (raw.startsWith('@')) {
+        const path = raw.slice(1);
+        try {
+            return fs.readFileSync(path, 'utf-8');
+        }
+        catch (e) {
+            error(`Could not read --body file "${path}": ${e?.message ?? e}`);
+        }
+    }
+    return raw;
+}
+// ── Create / list ────────────────────────────────────────────────────────────
+export async function create(description, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi task create "<description>" [--org <id>]');
+    requireArg(description, 'description', 'myapi task create "<description>"');
+    let resolveOn;
+    if (typeof flags['resolve-on'] === 'string') {
+        const parsed = _parseResolveOn(flags['resolve-on']);
+        if (typeof parsed === 'string')
+            error(parsed);
+        resolveOn = parsed;
+    }
+    let body;
+    if (typeof flags.body === 'string')
+        body = resolveBody(flags.body);
+    else if (flags.body === true)
+        error('--body needs a value: inline Markdown or @path-to-file.');
+    let importance;
+    if (typeof flags.importance === 'string') {
+        if (!TASK_IMPORTANCE.includes(flags.importance)) {
+            error(`Invalid --importance "${flags.importance}". Must be one of: ${TASK_IMPORTANCE.join(', ')}.`);
+        }
+        importance = flags.importance;
+    }
+    const t = await sdkTask.createTask(config.api_key, orgId, {
+        description,
+        body,
+        importance,
+        dueAt: typeof flags.due === 'string' ? flags.due : undefined,
+        assignee: typeof flags.assignee === 'string' ? flags.assignee : undefined,
+        tags: _splitList(flags.tag),
+        dependsOn: _splitList(flags['depends-on']),
+        dedupKey: typeof flags['dedup-key'] === 'string' ? flags['dedup-key'] : undefined,
+        resolveOn,
+        source: typeof flags.source === 'string' ? flags.source : undefined,
+    });
+    if (flags.json) {
+        printJson(t);
+        return;
+    }
+    success(`Task created: ${t.id}`);
+    info(`Status: ${t.status}`);
+    if (t.assignee)
+        info(`Assignee: ${t.assignee} (magic link emailed)`);
+}
+export async function list(flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi task list [--org <id>]');
+    const res = await sdkTask.listTasks(config.api_key, orgId, {
+        status: typeof flags.status === 'string' ? flags.status : undefined,
+        tag: typeof flags.tag === 'string' ? flags.tag : undefined,
+        importance: typeof flags.importance === 'string' ? flags.importance : undefined,
+        assignee: typeof flags.assignee === 'string' ? flags.assignee : undefined,
+        source: typeof flags.source === 'string' ? flags.source : undefined,
+        limit: typeof flags.limit === 'number' ? flags.limit : undefined,
+    });
+    if (flags.json) {
+        printJson(res);
+        return;
+    }
+    printTable(res.tasks.map(t => ({
+        id: t.id,
+        score: t.score,
+        description: t.description,
+    })), { flags, empty: 'No open tasks.' });
+    info('');
+    info(`Showing ${res.meta.shown} of ${res.meta.total_open} open task(s).`);
+}
+// ── Read ─────────────────────────────────────────────────────────────────────
+export async function get(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi task get <id> [--body] [--org <id>]');
+    requireArg(id, 'id', 'myapi task get <id>');
+    const t = await sdkTask.getTask(config.api_key, orgId, id);
+    // --body opts in to the separate body tier — never fetched implicitly.
+    const wantBody = flags.body === true || typeof flags.body === 'string';
+    const body = wantBody ? await sdkTask.getTaskBody(config.api_key, orgId, id) : undefined;
+    if (flags.json) {
+        printJson(wantBody ? { ...t, body } : t);
+        return;
+    }
+    info(`Task:        ${t.id}`);
+    info(`Status:      ${t.status}`);
+    info(`Description: ${t.description}`);
+    if (t.importance)
+        info(`Importance:  ${t.importance}`);
+    if (t.due_at)
+        info(`Due:         ${formatDate(t.due_at)}`);
+    if (t.assignee)
+        info(`Assignee:    ${t.assignee}`);
+    if (t.tags?.length)
+        info(`Tags:        ${t.tags.join(', ')}`);
+    if (t.depends_on?.length)
+        info(`Depends on:  ${t.depends_on.join(', ')}`);
+    if (t.claimed_by)
+        info(`Claimed by:  ${t.claimed_by}`);
+    if (t.lease_expires_at)
+        info(`Lease until: ${formatDate(t.lease_expires_at)}`);
+    if (wantBody) {
+        info('');
+        info('── body ──');
+        info(body ?? '');
+    }
+}
+// ── Lifecycle ────────────────────────────────────────────────────────────────
+export async function claim(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi task claim <id> [--lease <seconds>] [--worker <name>] [--org <id>]');
+    requireArg(id, 'id', 'myapi task claim <id>');
+    const t = await sdkTask.claimTask(config.api_key, orgId, id, {
+        leaseSeconds: typeof flags.lease === 'number' ? flags.lease : undefined,
+        worker: typeof flags.worker === 'string' ? flags.worker : undefined,
+    });
+    if (flags.json) {
+        printJson(t);
+        return;
+    }
+    success(`Claimed task ${t.id}`);
+    if (t.lease_expires_at)
+        info(`Lease expires: ${formatDate(t.lease_expires_at)} — heartbeat with: myapi task extend ${t.id}`);
+}
+export async function extend(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi task extend <id> [--lease <seconds>] [--org <id>]');
+    requireArg(id, 'id', 'myapi task extend <id>');
+    const t = await sdkTask.extendTask(config.api_key, orgId, id, {
+        leaseSeconds: typeof flags.lease === 'number' ? flags.lease : undefined,
+    });
+    if (flags.json) {
+        printJson(t);
+        return;
+    }
+    success(`Extended lease on task ${t.id}`);
+    if (t.lease_expires_at)
+        info(`Lease expires: ${formatDate(t.lease_expires_at)}`);
+}
+export async function resolve(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi task resolve <id> [--org <id>]');
+    requireArg(id, 'id', 'myapi task resolve <id>');
+    await sdkTask.resolveTask(config.api_key, orgId, id);
+    success(`Resolved task ${id}`);
+}
+export async function fail(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi task fail <id> --reason "<why>" [--org <id>]');
+    requireArg(id, 'id', 'myapi task fail <id> --reason "<why>"');
+    const reason = flags.reason;
+    if (typeof reason !== 'string' || reason.trim() === '') {
+        error('Missing --reason.\nUsage: myapi task fail <id> --reason "<why>"');
+    }
+    await sdkTask.failTask(config.api_key, orgId, id, reason);
+    success(`Failed task ${id}`);
+}
+export async function cancel(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi task cancel <id> [--org <id>]');
+    requireArg(id, 'id', 'myapi task cancel <id>');
+    await sdkTask.cancelTask(config.api_key, orgId, id);
+    success(`Cancelled task ${id}`);
+}
+// ── Dispatcher ───────────────────────────────────────────────────────────────
+const SUBCOMMAND_USAGE = {
+    'create': 'myapi task create "<description>" [--body <md|@file>] [--importance <i>] [--due <rfc3339>] [--assignee <email>] [--tag <t,t>] [--depends-on <id,id>] [--dedup-key <k>] [--resolve-on <event[:field=value]>] [--source <s>] [--org <id>]',
+    'list': 'myapi task list [--status <s>] [--tag <t>] [--importance <i>] [--assignee <email>] [--source <s>] [--limit <n>] [--org <id>] [--json]',
+    'get': 'myapi task get <id> [--body] [--org <id>] [--json]\n\n--body additionally fetches the Markdown body tier (a separate read).',
+    'claim': 'myapi task claim <id> [--lease <seconds>] [--worker <name>] [--org <id>]',
+    'extend': 'myapi task extend <id> [--lease <seconds>] [--org <id>]',
+    'resolve': 'myapi task resolve <id> [--org <id>]',
+    'fail': 'myapi task fail <id> --reason "<why>" [--org <id>]',
+    'cancel': 'myapi task cancel <id> [--org <id>]',
+};
+export async function run(subcommand, args, flags) {
+    if (!subcommand || (flags.help && !subcommand)) {
+        info(`Usage: myapi task <subcommand>
+
+An agent-task queue — the agent-loop hot path. Tasks are ranked by score,
+claimed under a lease, then resolved, failed, or cancelled.
+
+  create "<description>"  File a task (--body, --importance, --assignee, --resolve-on, ...)
+  list                    Top open tasks, ranked (--status, --tag, --limit)
+  get <id>                Show a task; --body also fetches the Markdown body tier
+  claim <id>              Take an atomic lease (default 10 min)
+  extend <id>             Heartbeat a live claim
+  resolve <id>            Resolve a task (terminal) — unblocks dependents
+  fail <id>               Fail a task (terminal) — requires --reason
+  cancel <id>             Cancel a task (terminal, distinct from fail)
+
+The agent loop is: list → get <id> --body → claim → resolve.
+For durable machine work (retried HTTP jobs), see: myapi queue --help
+
+All commands accept --org <id> (or set default: myapi config set-org <id>).`);
+        return;
+    }
+    if (flags.help) {
+        const usage = SUBCOMMAND_USAGE[subcommand];
+        if (usage)
+            info(`Usage: ${usage}`);
+        else
+            info(`Unknown subcommand: ${subcommand}. Run "myapi task --help" for the list.`);
+        return;
+    }
+    switch (subcommand) {
+        case 'create': return create(args[0], flags);
+        case 'list': return list(flags);
+        case 'get': return get(args[0], flags);
+        case 'claim': return claim(args[0], flags);
+        case 'extend': return extend(args[0], flags);
+        case 'resolve': return resolve(args[0], flags);
+        case 'fail': return fail(args[0], flags);
+        case 'cancel': return cancel(args[0], flags);
+        default: error(`Unknown subcommand: ${subcommand}. Run "myapi task --help" for a list of valid subcommands.`);
+    }
+}

package/dist/commands/workflow-validation.test.js

@@ -120,6 +120,33 @@ describe('_validateSteps — http_request / http (2026-05-15)', () => {
             .toMatch(/"headers" value for "X-Token" must be a string/);
     });
 });
+describe('_validateSteps — enqueue_job / enqueue (2026-05-19)', () => {
+    const VALID_ENQUEUE = { type: 'enqueue_job', queue: 'thumbnails' };
+    it('accepts the canonical type name', () => {
+        expect(_validateSteps([VALID_ENQUEUE])).toBeNull();
+    });
+    it('accepts the `enqueue` alias', () => {
+        expect(_validateSteps([{ ...VALID_ENQUEUE, type: 'enqueue' }])).toBeNull();
+    });
+    it('accepts a string payload with templating', () => {
+        expect(_validateSteps([{ ...VALID_ENQUEUE, payload: '{"email":"{{ payload.email }}"}' }])).toBeNull();
+    });
+    it('accepts dedup_key and delay_seconds', () => {
+        expect(_validateSteps([{ ...VALID_ENQUEUE, dedup_key: 'k1', delay_seconds: 30 }])).toBeNull();
+    });
+    it('rejects when queue is missing', () => {
+        expect(_validateSteps([{ type: 'enqueue_job' }]))
+            .toMatch(/missing required field "queue"/);
+    });
+    it('rejects a non-string payload', () => {
+        expect(_validateSteps([{ ...VALID_ENQUEUE, payload: { not: 'a string' } }]))
+            .toMatch(/"payload" must be a string/);
+    });
+    it('rejects a non-number delay_seconds', () => {
+        expect(_validateSteps([{ ...VALID_ENQUEUE, delay_seconds: '30' }]))
+            .toMatch(/"delay_seconds" must be a number/);
+    });
+});
 describe('_validateSteps — mixed-type pipelines', () => {
     it('accepts an http_request after a send_email (pipeline shape)', () => {
         expect(_validateSteps([