agent-ticketing 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # agent-ticketing
 
-Agent SDK for **Agent Mailbox** — claim tickets, heartbeat, ask the requester, complete. Zero dependencies, Node 18+.
+Agent SDK for **Agent Ticketing** — claim tickets, heartbeat, ask the requester, complete. Zero dependencies, Node 18+.
 
 ```bash
 npm install agent-ticketing   # (or use it from this repo via workspaces)
@@ -12,7 +12,7 @@ npm install agent-ticketing   # (or use it from this repo via workspaces)
 import { MailboxAgent } from "agent-ticketing";
 
 const mailbox = new MailboxAgent({
-  baseUrl: "https://agent-mailbox.<you>.workers.dev",
+  baseUrl: "https://agent-ticketing.<you>.workers.dev",
   apiKey: process.env.MAILBOX_API_KEY, // mbx_live_… from Settings → Agents
 });
 
@@ -59,9 +59,22 @@ NOT keep the Durable Object hot, so pick the mode by latency preference, not cos
   the thinking, the ticket is completed with its output.
 
 ```bash
-MAILBOX_URL=https://… MAILBOX_API_KEY=mbx_live_… node examples/runner-claude.mjs --interval 5m
+# persistent service (recommended): starts now, restarts on crash, survives reboots
+MAILBOX_URL=https://… MAILBOX_API_KEY=mbx_live_… \
+npx -y -p agent-ticketing mailbox-claude-runner --install-service
+
+# one-off foreground run: drop --install-service (add --interval 5m for lazy polling)
+# remove the service later: mailbox-claude-runner --uninstall-service
 ```
 
+`--install-service` writes a launchd LaunchAgent (macOS) or a systemd user unit
+(Linux) with your env baked in. Linux + reboot-without-login also needs
+`loginctl enable-linger $USER` once.
+
+Runners are agent-specific — `mailbox-claude-runner` launches headless **Claude Code**
+sessions. Runners for Codex and daemon-style agents (Hermes, OpenClaw) are planned;
+for a custom harness, embed the SDK instead (below).
+
 ## Low-level client
 
 Every REST endpoint is also exposed directly if you don't want the loop:

package/dist/index.d.ts

@@ -143,6 +143,12 @@ export declare class MailboxAgent {
     }): Promise<Message>;
     complete(ticketId: string, summary?: string): Promise<Ticket>;
     release(ticketId: string, reason?: string): Promise<Ticket>;
+    /** Download an attachment's bytes (any attachment in your mailbox's tickets). */
+    downloadAttachment(attachmentId: string): Promise<{
+        filename: string;
+        contentType: string;
+        data: Uint8Array;
+    }>;
     uploadAttachment(ticketId: string, file: {
         filename: string;
         contentType?: string;

package/dist/index.js

@@ -87,6 +87,21 @@ export class MailboxAgent {
         });
         return (await res.json()).ticket;
     }
+    /** Download an attachment's bytes (any attachment in your mailbox's tickets). */
+    async downloadAttachment(attachmentId) {
+        const res = await fetch(`${this.baseUrl}/v1/attachments/${attachmentId}`, {
+            headers: { Authorization: `Bearer ${this.#apiKey}` },
+        });
+        if (!res.ok)
+            throw await toApiError(res);
+        const cd = res.headers.get("Content-Disposition") ?? "";
+        const filename = /filename="([^"]+)"/.exec(cd)?.[1] ?? attachmentId;
+        return {
+            filename,
+            contentType: res.headers.get("Content-Type") ?? "application/octet-stream",
+            data: new Uint8Array(await res.arrayBuffer()),
+        };
+    }
     async uploadAttachment(ticketId, file) {
         const params = new URLSearchParams({
             filename: file.filename,

package/dist/runner.js

@@ -7,20 +7,141 @@
  *   MAILBOX_URL=https://…workers.dev MAILBOX_API_KEY=mbx_live_… \
  *   npx @mailbox/agent   # or: mailbox-claude-runner [--interval 5m] [--once]
  */
-import { execFile } from "node:child_process";
-import { appendFileSync } from "node:fs";
-import { promisify } from "node:util";
+import { execSync, spawn } from "node:child_process";
+import { appendFileSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, join } from "node:path";
 import { MailboxAgent } from "./index.js";
-const exec = promisify(execFile);
 const baseUrl = process.env.MAILBOX_URL;
 const apiKey = process.env.MAILBOX_API_KEY;
-if (!baseUrl || !apiKey) {
+if ((!baseUrl || !apiKey) && !process.argv.includes("--uninstall-service")) {
     console.error("Set MAILBOX_URL and MAILBOX_API_KEY (Settings → Agents in the mailbox UI)");
     process.exit(1);
 }
 const args = process.argv.slice(2);
 const interval = args.includes("--interval") ? args[args.indexOf("--interval") + 1] : null;
 const once = args.includes("--once");
+// ── --install-service / --uninstall-service: survive host reboots ────────────
+// macOS → launchd LaunchAgent; Linux → systemd user unit. Env is baked in.
+const SERVICE_LABEL = "com.agent-ticketing.runner";
+const UNIT_NAME = "agent-ticketing-runner";
+function serviceCommand() {
+    let npx = "npx";
+    try {
+        npx = execSync("command -v npx", { shell: "/bin/sh", encoding: "utf8" }).trim() || "npx";
+    }
+    catch {
+        // fall back to PATH lookup (we bake PATH into the service env anyway)
+    }
+    return `exec "${npx}" -y -p agent-ticketing mailbox-claude-runner${interval ? ` --interval ${interval}` : ""}`;
+}
+function xmlEscape(v) {
+    return v.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function installService() {
+    const home = homedir();
+    const logDir = join(home, ".agent-ticketing");
+    mkdirSync(logDir, { recursive: true });
+    const envs = {
+        MAILBOX_URL: baseUrl ?? "",
+        MAILBOX_API_KEY: apiKey ?? "",
+        MAILBOX_LOG_FILE: process.env.MAILBOX_LOG_FILE ?? join(logDir, "events.ndjson"),
+        // Service shells get a bare PATH (no profile) — bake the installing shell's
+        // PATH so node/npx/claude resolve exactly as they did for the human.
+        PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
+    };
+    if (process.env.CLAUDE_CMD)
+        envs.CLAUDE_CMD = process.env.CLAUDE_CMD;
+    if (process.platform === "darwin") {
+        const plist = join(home, "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`);
+        mkdirSync(join(home, "Library", "LaunchAgents"), { recursive: true });
+        const envXml = Object.entries(envs)
+            .map(([k, v]) => `    <key>${k}</key><string>${xmlEscape(v)}</string>`)
+            .join("\n");
+        writeFileSync(plist, `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array><string>/bin/sh</string><string>-lc</string><string>${xmlEscape(serviceCommand())}</string></array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${envXml}
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${join(logDir, "runner.log")}</string>
+  <key>StandardErrorPath</key><string>${join(logDir, "runner.log")}</string>
+</dict>
+</plist>
+`);
+        execSync(`launchctl unload "${plist}" 2>/dev/null || true`, { shell: "/bin/sh" });
+        execSync(`launchctl load -w "${plist}"`, { shell: "/bin/sh" });
+        console.log(`installed launchd service ${SERVICE_LABEL}`);
+        console.log(`  plist: ${plist}`);
+        console.log(`  logs:  ${join(logDir, "runner.log")}`);
+        console.log(`It starts now, restarts on crash, and survives reboots (starts at login).`);
+    }
+    else if (process.platform === "linux") {
+        const unitDir = join(home, ".config", "systemd", "user");
+        mkdirSync(unitDir, { recursive: true });
+        const unit = join(unitDir, `${UNIT_NAME}.service`);
+        const envLines = Object.entries(envs)
+            .map(([k, v]) => `Environment="${k}=${v}"`)
+            .join("\n");
+        writeFileSync(unit, `[Unit]
+Description=Agent Ticketing runner (mailbox-claude-runner)
+After=network-online.target
+
+[Service]
+${envLines}
+ExecStart=/bin/sh -lc '${serviceCommand()}'
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+`);
+        execSync(`systemctl --user daemon-reload && systemctl --user enable --now ${UNIT_NAME}`, { shell: "/bin/sh" });
+        console.log(`installed systemd user service ${UNIT_NAME}`);
+        console.log(`  unit: ${unit}`);
+        console.log(`  logs: journalctl --user -u ${UNIT_NAME} -f   (plus ${envs.MAILBOX_LOG_FILE})`);
+        console.log(`To also start WITHOUT anyone logging in after reboot, run once:`);
+        console.log(`  loginctl enable-linger $USER`);
+    }
+    else {
+        console.error(`--install-service supports macOS (launchd) and Linux (systemd) — on ${process.platform}, run the runner under your own supervisor.`);
+        process.exit(1);
+    }
+}
+function uninstallService() {
+    const home = homedir();
+    if (process.platform === "darwin") {
+        const plist = join(home, "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`);
+        execSync(`launchctl unload -w "${plist}" 2>/dev/null || true`, { shell: "/bin/sh" });
+        rmSync(plist, { force: true });
+        console.log(`removed launchd service ${SERVICE_LABEL}`);
+    }
+    else if (process.platform === "linux") {
+        execSync(`systemctl --user disable --now ${UNIT_NAME} 2>/dev/null || true`, { shell: "/bin/sh" });
+        rmSync(join(home, ".config", "systemd", "user", `${UNIT_NAME}.service`), { force: true });
+        execSync(`systemctl --user daemon-reload 2>/dev/null || true`, { shell: "/bin/sh" });
+        console.log(`removed systemd user service ${UNIT_NAME}`);
+    }
+    else {
+        console.error(`--uninstall-service supports macOS and Linux only.`);
+        process.exit(1);
+    }
+}
+if (args.includes("--uninstall-service")) {
+    uninstallService();
+    process.exit(0);
+}
+if (args.includes("--install-service")) {
+    installService();
+    process.exit(0);
+}
 const claudeCmd = process.env.CLAUDE_CMD ?? "claude";
 // MAILBOX_LOG_FILE=agent.ndjson → one JSON event per line (ts, event, ticketId…)
 // for grep-able history that cross-references the server-side ticket threads.
@@ -35,12 +156,21 @@ const onEvent = logFile
         }
     }
     : undefined;
-const mailbox = new MailboxAgent({ baseUrl, apiKey });
-function promptFor(ticket, messages) {
+// Non-null: every path reaching here passed the env guard (service handlers exit earlier).
+const mailbox = new MailboxAgent({ baseUrl: baseUrl, apiKey: apiKey });
+function promptFor(ticket, messages, attachmentPaths) {
     const thread = messages
         .filter((m) => m.kind === "message")
         .map((m) => `${m.author.type === "human" ? "REQUESTER" : m.author.type.toUpperCase()}: ${m.body}`)
         .join("\n\n");
+    const files = attachmentPaths.length > 0
+        ? [
+            ``,
+            `ATTACHMENTS — the requester attached these files; they are downloaded locally.`,
+            `Read them with your file tools (images can be viewed directly):`,
+            ...attachmentPaths.map((p) => `- ${p}`),
+        ]
+        : [];
     return [
         `You are working a ticket from a ticketing system. Do the task and reply with your final result.`,
         `Your reply is posted back to the requester as the ticket resolution — be complete but concise.`,
@@ -48,16 +178,77 @@ function promptFor(ticket, messages) {
         `TICKET: ${ticket.subject}`,
         ``,
         thread,
+        ...files,
     ].join("\n");
 }
+/** Download the ticket's attachments so the headless session can open them. */
+async function fetchAttachments(ticket, messages) {
+    const attachments = messages.flatMap((m) => m.attachments);
+    if (attachments.length === 0)
+        return [];
+    const dir = join(tmpdir(), "agent-ticketing", ticket.id);
+    mkdirSync(dir, { recursive: true });
+    const paths = [];
+    for (const a of attachments) {
+        try {
+            const file = await mailbox.downloadAttachment(a.id);
+            const path = join(dir, basename(a.filename) || a.id);
+            writeFileSync(path, file.data);
+            paths.push(path);
+        }
+        catch (e) {
+            console.error(`[mailbox] could not download attachment ${a.id} (${a.filename}): ${String(e)}`);
+        }
+    }
+    return paths;
+}
+/**
+ * Run `claude -p` with the prompt on STDIN (immune to ARG_MAX for long threads,
+ * keeps ticket text out of `ps`). On failure, the error carries the exit code
+ * AND the stderr tail — so the release reason / ndjson log show the real cause.
+ */
+function runClaude(prompt, signal) {
+    return new Promise((resolve, reject) => {
+        // The runner is often launched from INSIDE a Claude session (setup prompt);
+        // strip nested-session markers so the child behaves like a fresh CLI run.
+        const env = { ...process.env };
+        delete env.CLAUDECODE;
+        delete env.CLAUDE_CODE_ENTRYPOINT;
+        const child = spawn(claudeCmd, ["-p", "--output-format", "text"], {
+            env,
+            signal,
+            timeout: 10 * 60 * 1000,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => {
+            if (stdout.length < 10 * 1024 * 1024)
+                stdout += d.toString();
+        });
+        child.stderr.on("data", (d) => {
+            if (stderr.length < 1024 * 1024)
+                stderr += d.toString();
+        });
+        child.on("error", (e) => reject(new Error(`could not run "${claudeCmd}": ${e.message}`)));
+        child.on("close", (code, sig) => {
+            if (code === 0)
+                return resolve(stdout);
+            const tail = stderr.trim().slice(-600) || stdout.trim().slice(-600) || "(no output)";
+            reject(new Error(`${claudeCmd} exited with ${sig ? `signal ${sig}` : `code ${code}`}: ${tail}`));
+        });
+        child.stdin.on("error", () => undefined); // child died before reading stdin; close() reports it
+        child.stdin.write(prompt);
+        child.stdin.end();
+    });
+}
 const controller = new AbortController();
 await mailbox.poll(async (ticket, ctx) => {
-    await ctx.progress("launching headless Claude Code session");
-    const { stdout } = await exec(claudeCmd, ["-p", promptFor(ticket, ctx.messages), "--output-format", "text"], {
-        timeout: 10 * 60 * 1000,
-        maxBuffer: 10 * 1024 * 1024,
-        signal: ctx.signal,
-    });
+    const attachmentPaths = await fetchAttachments(ticket, ctx.messages);
+    await ctx.progress(attachmentPaths.length > 0
+        ? `launching headless Claude Code session (${attachmentPaths.length} attachment(s) downloaded)`
+        : "launching headless Claude Code session");
+    const stdout = await runClaude(promptFor(ticket, ctx.messages, attachmentPaths), ctx.signal);
     const result = stdout.trim();
     if (!result)
         throw new Error("claude produced no output");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-ticketing",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Agent SDK for Agent Mailbox — poll tickets, heartbeat, ask the requester, complete. Zero dependencies.",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,7 +31,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/terryds/agent-mailbox"
+    "url": "https://github.com/terryds/agent-ticketing"
   },
   "license": "MIT",
   "keywords": [