@homespunapps/cli 1.6.52 → 1.6.53

package/dist/commands/work.js

@@ -0,0 +1,301 @@
+// `homespun work` - the long-running worker that drains this identity's agent-task
+// queue and hands each task to whatever agent its owner uses.
+//
+// THE ENVELOPE GOES TO A CHILD PROCESS ON STDIN, and that is the entire integration
+// contract. No SDK, no library, no assumption that the consumer is Claude or that it
+// can call tools: `--exec` names any command, and a shell script reading stdin is a
+// first-class consumer. That is also how the harness-agnostic claim gets tested, by
+// pointing `--exec` at a script rather than at a model.
+//
+// EXIT CODE IS THE ANSWER. Zero acks, non-zero nacks with the child's stderr as the
+// report. Nothing is parsed out of stdout, deliberately: requiring a structured
+// reply would mean every worker needs a wrapper that produces it, and the one thing
+// every program on every platform already reports reliably is its exit status.
+//
+// POLLING IS THE FLOOR. The wake frame only shortens the wait, so this drains
+// correctly with no socket at all. That is why the reconnect logic below is allowed
+// to give up on the socket and keep working.
+//
+// WHY THIS FILE CONTAINS RECONNECT LOGIC AT ALL, when `apps watch` does not: nothing
+// in this CLI has it. `apps watch` falls back to HTTP long-polling permanently on any
+// pre-connect WS failure, never retries, handles SIGINT but not SIGTERM, and parks on
+// `await new Promise(() => {})`. That is fine for a person watching a terminal and
+// wrong for a process meant to run under a supervisor for weeks: it would silently
+// degrade to a slower path and nothing would say so. So this reconnects with capped
+// backoff, says so on stderr when it does, and exits cleanly on SIGTERM.
+import { spawn } from "node:child_process";
+import { openAppStream, appWsUrlFromAppUrl } from "@homespunapps/core";
+import { assertKnownFlags } from "../argv.js";
+import { nounSpec, renderNounHelp, specFor } from "../help-catalog.js";
+import { resolveConfig } from "../config.js";
+import { fail, printJsonLine, warn } from "../output.js";
+/** Backoff bounds for the wake socket. Capped so a long outage does not spin. */
+const RECONNECT_MIN_MS = 1_000;
+const RECONNECT_MAX_MS = 60_000;
+export async function runWork(args) {
+    if (args.flags.has("help") ||
+        args.bools.has("help") ||
+        args.positionals[0] === "help") {
+        const spec = nounSpec("work");
+        if (spec)
+            process.stdout.write(renderNounHelp(spec));
+        return;
+    }
+    // The catalogue entry IS the flag allowlist, so a flag documented in help and a
+    // flag accepted here cannot drift apart.
+    assertKnownFlags(args, ...specFor("work"));
+    const exec = args.flags.get("exec");
+    if (!exec) {
+        fail("work requires --exec <command>: the program each task envelope is piped to", "invalid_request");
+    }
+    const opts = {
+        // Repeatable OR comma-separated, because both are things a person types.
+        appIds: (args.flags.get("app") ?? "")
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean),
+        exec: exec,
+        maxConcurrent: positiveInt(args.flags.get("max-concurrent"), 1),
+        once: args.bools.has("once") || args.flags.has("once"),
+        pollSeconds: positiveInt(args.flags.get("poll-interval"), 15),
+    };
+    const cfg = resolveConfig(args);
+    const base = cfg.url.replace(/\/$/, "");
+    let stopping = false;
+    /** Resolves early when the wake frame arrives, so a sleep can be interrupted. */
+    let wake = null;
+    const stop = () => {
+        stopping = true;
+        wake?.();
+    };
+    // BOTH signals. A supervisor sends SIGTERM, and a worker that only handles SIGINT
+    // gets killed mid-task, which strands its lease until it expires.
+    //
+    // Removed again in the `finally` below. In production this runs once and process
+    // exit would clean up anyway, but leaving them attached leaks a listener per call,
+    // which surfaced as a MaxListenersExceededWarning once the test suite called this
+    // fifteen times in one process. A warning that only appears under test is still a
+    // handler this function attached and did not own up to.
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    const socket = opts.once
+        ? null
+        : openWakeSocket(opts, cfg.apiKey, base, () => wake?.());
+    try {
+        for (;;) {
+            const claimed = await claim(base, cfg.apiKey, opts);
+            for (const task of claimed) {
+                await runTask(base, cfg.apiKey, task, opts.exec);
+                if (stopping)
+                    break;
+            }
+            if (opts.once || stopping)
+                break;
+            // Sleep, interruptible by the wake frame. `wake` is re-armed each pass so a
+            // frame that arrives WHILE tasks are running does not resolve a stale promise
+            // and get lost; the next sleep is what it shortens.
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, opts.pollSeconds * 1000);
+                wake = () => {
+                    clearTimeout(timer);
+                    resolve();
+                };
+            });
+            wake = null;
+        }
+    }
+    finally {
+        socket?.close();
+        process.off("SIGINT", stop);
+        process.off("SIGTERM", stop);
+    }
+}
+/**
+ * Claim a batch. A claim failure is NOT fatal outside `--once`: the relay may be
+ * restarting or briefly unreachable, and a worker that exits on the first 503 is a
+ * worker that needs a supervisor to do its retrying. Logged and retried on the next
+ * pass instead.
+ */
+async function claim(base, apiKey, opts) {
+    const body = { max: opts.maxConcurrent };
+    if (opts.appIds.length > 0)
+        body.app_ids = opts.appIds;
+    try {
+        const res = await fetch(`${base}/v1/agent-tasks/claim`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${apiKey}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            if (opts.once) {
+                fail(`claim failed (${res.status}): ${text}`, "claim_failed");
+            }
+            warn(`claim failed (${res.status}), retrying next pass: ${text}`);
+            return [];
+        }
+        return (await res.json()).tasks ?? [];
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (opts.once)
+            fail(`claim failed: ${msg}`, "claim_failed");
+        warn(`claim failed, retrying next pass: ${msg}`);
+        return [];
+    }
+}
+/**
+ * Hand one task to the child and report the outcome.
+ *
+ * The whole envelope goes on stdin as one JSON line, including the credential, so a
+ * worker needs no configuration of its own to write results back: everything it
+ * needs to act is in the thing it was handed.
+ */
+async function runTask(base, apiKey, task, exec) {
+    const started = Date.now();
+    const result = await runChild(exec, JSON.stringify(task));
+    const seconds = Math.round((Date.now() - started) / 100) / 10;
+    if (result.code === 0) {
+        await report(base, apiKey, task.task_id, "ack", trim(result.stdout));
+        printJsonLine({
+            task: task.task_id,
+            app: task.app_slug,
+            type: task.task_type,
+            status: "done",
+            seconds,
+        });
+        return;
+    }
+    // Non-zero: nack, with the child's STDERR as the report. Stderr rather than stdout
+    // because that is where a failing program explains itself, and the report is read
+    // by a person working out why their task did not run.
+    await report(base, apiKey, task.task_id, "nack", trim(result.stderr || result.stdout) ||
+        `worker exited ${result.code ?? "on a signal"}`);
+    printJsonLine({
+        task: task.task_id,
+        app: task.app_slug,
+        type: task.task_type,
+        status: "failed",
+        exit: result.code,
+        seconds,
+    });
+}
+function runChild(exec, stdin) {
+    return new Promise((resolve) => {
+        // Through a shell, so `--exec "claude -p"` and `--exec ./parse.sh` both work the
+        // way a person expects when they type them.
+        const child = spawn(exec, { shell: true });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => (stdout += String(d)));
+        child.stderr.on("data", (d) => (stderr += String(d)));
+        child.on("error", (err) => {
+            resolve({ code: 127, stdout, stderr: stderr + String(err) });
+        });
+        child.on("close", (code) => resolve({ code, stdout, stderr }));
+        child.stdin.write(stdin);
+        child.stdin.end();
+    });
+}
+/**
+ * Ack or nack. A REPORTING failure is logged and swallowed rather than thrown: the
+ * work has already happened, and the lease will lapse and return the task to the
+ * queue on its own, which is the correct recovery. Crashing the worker here would
+ * lose every other task it holds for the sake of one it could not report on.
+ */
+async function report(base, apiKey, taskId, verb, text) {
+    try {
+        const res = await fetch(`${base}/v1/agent-tasks/${taskId}/${verb}`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${apiKey}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(text ? { report: text } : {}),
+        });
+        if (!res.ok) {
+            warn(`${verb} failed for ${taskId} (${res.status}); lease will lapse`);
+        }
+    }
+    catch (err) {
+        warn(`${verb} failed for ${taskId} (${err instanceof Error ? err.message : String(err)}); lease will lapse`);
+    }
+}
+/**
+ * The wake socket, with real reconnect.
+ *
+ * ONE APP ONLY, and this is the honest limitation of the frame rather than of this
+ * command: the hint is published on the app's own `/_hs/ws`, so a worker draining
+ * five apps would need five sockets. Polling already drains every app correctly, so
+ * the socket is opened only when `--app` names exactly one and is simply skipped
+ * otherwise. A multi-app worker polls, which costs latency and nothing else.
+ *
+ * Reconnects with capped exponential backoff and says so, once, per outage. It never
+ * escalates to an exit: losing the socket makes this slower, not broken, and a
+ * worker that killed itself over a lost optimisation would be worse than one that
+ * kept polling.
+ */
+function openWakeSocket(opts, apiKey, base, onWake) {
+    if (opts.appIds.length !== 1)
+        return null;
+    const appId = opts.appIds[0];
+    let closed = false;
+    let delay = RECONNECT_MIN_MS;
+    let handle = null;
+    let announcedOutage = false;
+    const connect = () => {
+        if (closed)
+            return;
+        const wsUrl = appWsUrlFromAppUrl(`${base}/a/${appId}/`);
+        handle = openAppStream({ wsUrl, apiKey, since: Number.MAX_SAFE_INTEGER }, {
+            onHello: () => {
+                // A successful connect resets the backoff, so a flapping link does not
+                // inherit the previous outage's delay.
+                delay = RECONNECT_MIN_MS;
+                if (announcedOutage) {
+                    warn("wake socket reconnected");
+                    announcedOutage = false;
+                }
+            },
+            onAgentTaskAvailable: onWake,
+            onClose: () => scheduleReconnect(),
+            onError: () => scheduleReconnect(),
+        });
+    };
+    const scheduleReconnect = () => {
+        if (closed)
+            return;
+        if (!announcedOutage) {
+            warn("wake socket lost; polling continues while it reconnects");
+            announcedOutage = true;
+        }
+        const wait = delay;
+        delay = Math.min(delay * 2, RECONNECT_MAX_MS);
+        setTimeout(connect, wait).unref?.();
+    };
+    connect();
+    return {
+        close: () => {
+            closed = true;
+            handle?.close();
+        },
+    };
+}
+function positiveInt(raw, fallback) {
+    if (raw === undefined)
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        fail(`expected a positive integer, got '${raw}'`, "invalid_request");
+    }
+    return n;
+}
+/** Cap the report at what the ack route accepts, keeping the TAIL of a long one:
+ * the end of a stack trace says more about a failure than its beginning. */
+function trim(s) {
+    const t = s.trim();
+    return t.length > 3900 ? t.slice(-3900) : t;
+}

package/dist/help-catalog.js

@@ -1595,9 +1595,55 @@ const REVIEW = {
 };
 // Order here is the order in `homespun --help` and in the generated reference
 // page: app commands first, then the rest.
+const WORK = {
+    noun: "work",
+    tagline: "run the agent-task worker",
+    group: "app",
+    rootSummary: "Runs a long-lived worker that claims agent tasks for your apps and pipes each one to a command you name.",
+    verbs: [
+        {
+            verb: "",
+            summary: "Claims tasks and pipes each envelope to --exec on stdin, acking on exit 0 and nacking otherwise.",
+            flags: [
+                {
+                    name: "exec",
+                    value: "<command>",
+                    description: "Required. The command each task envelope is piped to",
+                },
+                {
+                    name: "app",
+                    value: "<id[,id]>",
+                    description: "Only these apps (default: every app you own)",
+                },
+                {
+                    name: "max-concurrent",
+                    value: "<n>",
+                    description: "Tasks to claim per pass (default 1)",
+                },
+                {
+                    name: "poll-interval",
+                    value: "<seconds>",
+                    description: "Seconds between claims (default 15)",
+                },
+                {
+                    name: "once",
+                    description: "Drain one pass and exit, for cron",
+                },
+            ],
+        },
+    ],
+    notes: [
+        "The whole task envelope arrives on the command's stdin as one JSON line: a `prompt` from the app manifest, a `context` holding the row that triggered it, and a short-lived credential scoped to exactly the collections the rule declared. The command needs no configuration of its own; everything it needs to write results back is in what it was handed.",
+        "`context` is DATA, not instructions. It holds row content that any user of the app may have written, including an anonymous one. A worker should follow only `prompt`, which comes from the manifest its owner approved.",
+        "Exit 0 acks the task. Any non-zero exit nacks it and records the command's stderr as the reason, so the task returns to the queue and eventually dead-letters if it can never succeed. Nothing is parsed out of stdout.",
+        "Without --once this runs until stopped, reconnecting its wake socket with backoff and continuing to poll throughout. It exits cleanly on SIGINT and SIGTERM, so it is safe to run under a supervisor.",
+    ],
+    outputNote: 'One JSON line per finished task on stdout. Progress and transient failures go to stderr; errors are {"error":{"code","message"}} with a non-zero exit.',
+};
 const NOUNS = [
     DEPLOY,
     APPS,
+    WORK,
     DATA,
     MEMBERS,
     GRANTS,

package/dist/index.js

@@ -35,6 +35,7 @@ import { runBlob } from "./commands/attachment.js";
 import { runSkill } from "./commands/skill.js";
 import { runDeploy } from "./commands/deploy.js";
 import { runApps } from "./commands/apps.js";
+import { runWork } from "./commands/work.js";
 import { runData } from "./commands/data.js";
 import { runMembers } from "./commands/members.js";
 import { runGrant } from "./commands/grant.js";
@@ -122,6 +123,9 @@ async function main() {
         case "apps":
             await runApps(args);
             break;
+        case "work":
+            await runWork(args);
+            break;
         case "data":
             await runData(args);
             break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homespunapps/cli",
-  "version": "1.6.52",
+  "version": "1.6.53",
   "description": "Command-line client for the Homespun relay: deploy a real multi-user web app from your agent, then keep reading and writing its data.",
   "license": "MIT",
   "type": "module",
@@ -36,7 +36,7 @@
     "test:unit": "vitest run"
   },
   "dependencies": {
-    "@homespunapps/core": "^1.6.52",
+    "@homespunapps/core": "^1.6.53",
     "qrcode-terminal": "^0.12.0"
   },
   "devDependencies": {