agent-ticketing 0.1.2 → 0.1.4

package/README.md

@@ -75,6 +75,27 @@ Runners are agent-specific — `mailbox-claude-runner` launches headless **Claud
 sessions. Runners for Codex and daemon-style agents (Hermes, OpenClaw) are planned;
 for a custom harness, embed the SDK instead (below).
 
+### Runner behavior (v0.1.3)
+
+- Runs Claude with **`--permission-mode bypassPermissions`** — an autonomous runner
+  must edit files and run commands unattended. Override with
+  `CLAUDE_PERMISSION_MODE` (`default`, `acceptEdits`, `plan`).
+- **Ask → pending → resume**: if Claude asks a question mid-task (AskUserQuestion),
+  the runner posts it to the ticket (`pending`), and after the requester replies it
+  **resumes the same Claude session** with the answer — full conversational loop.
+- Announces the Claude **session id** in the ticket thread and the ndjson log
+  (`claude_session` event) — inspect a stuck run with `claude --resume <id>`.
+- **Live progress**: tails the session's JSONL and posts throttled ⚙ steps
+  ("Bash: npm test", "Edit: app.ts") to the ticket — watch the agent work from
+  the dashboard. Sessions run in `MAILBOX_WORKDIR`
+  (default `~/.agent-ticketing/workspace`).
+- **Deliverables**: the prompt tells Claude to save output files into a per-ticket
+  deliverables directory; the runner uploads them as ticket attachments on
+  completion (≤10 files, ≤25MB each — anything skipped is named in the summary).
+  Images preview inline in the dashboard.
+- `CLAUDE_TIMEOUT_MS` (default 10 min, 0 disables) with SIGTERM→SIGKILL escalation;
+  JSON output is salvaged from timed-out processes when possible.
+
 ## Low-level client
 
 Every REST endpoint is also exposed directly if you don't want the loop:

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export type Ticket = {
     status: TicketStatus;
     requesterId: string;
     assigneeAgentId: string | null;
+    releasedFromAgentId?: string | null;
     claim: {
         agentId: string;
         agentInstanceId: string;
@@ -63,7 +64,7 @@ export type MailboxConfig = {
 };
 export type MailboxEvent = {
     ts: string;
-    event: "poll_start" | "claimed" | "completed" | "released" | "claim_lost" | "handler_error" | "poll_error";
+    event: "poll_start" | "claimed" | "completed" | "released" | "claim_lost" | "handler_error" | "poll_error" | "asked" | (string & {});
     instanceId: string;
     ticketId?: string;
     subject?: string;
@@ -111,6 +112,10 @@ export type TicketContext = {
     ask(question: string, opts?: {
         pollSeconds?: number;
     }): Promise<string>;
+    /** Ask the human and EXIT the handler (for runners that resume later). The ticket
+     * goes pending; the claim expires naturally and the assignee is kept, so this
+     * agent re-claims after the human replies. */
+    askAsync(question: string): Promise<void>;
     /** Upload a file; returns a staged attachmentId to pass to post()/complete(). */
     attach(filePath: string, contentType?: string): Promise<string>;
     /** Mark the work done (ticket → done, awaiting human review). Ends the handler's claim. */

package/dist/index.js

@@ -193,6 +193,12 @@ export class MailboxAgent {
                 assertLive(claimLost.signal);
                 await self.postMessage(ticket.id, body, { attachmentIds: opts?.attachmentIds });
             },
+            async askAsync(question) {
+                assertLive(claimLost.signal);
+                await self.postMessage(ticket.id, question, { askRequester: true });
+                finished = true;
+                o.emit({ event: "asked", ticketId: ticket.id });
+            },
             async ask(question, opts) {
                 assertLive(claimLost.signal);
                 const asked = await self.postMessage(ticket.id, question, { askRequester: true });

package/dist/runner.js

@@ -8,9 +8,10 @@
  *   npx @mailbox/agent   # or: mailbox-claude-runner [--interval 5m] [--once]
  */
 import { execSync, spawn } from "node:child_process";
-import { appendFileSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { appendFileSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
+import { open as fsOpen } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
-import { basename, join } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { MailboxAgent } from "./index.js";
 const baseUrl = process.env.MAILBOX_URL;
 const apiKey = process.env.MAILBOX_API_KEY;
@@ -158,6 +159,17 @@ const onEvent = logFile
     : undefined;
 // Non-null: every path reaching here passed the env guard (service handlers exit earlier).
 const mailbox = new MailboxAgent({ baseUrl: baseUrl, apiKey: apiKey });
+function deliverablesDir(ticketId) {
+    return join(WORK_DIR, "deliverables", ticketId);
+}
+function deliverablesInstruction(ticketId) {
+    return [
+        ``,
+        `If the requester should receive any FILES (images, documents, code artifacts…),`,
+        `save them into this directory — everything in it is attached to your reply automatically:`,
+        `DELIVERABLES: ${deliverablesDir(ticketId)}`,
+    ].join("\n");
+}
 function promptFor(ticket, messages, attachmentPaths) {
     const thread = messages
         .filter((m) => m.kind === "message")
@@ -179,6 +191,7 @@ function promptFor(ticket, messages, attachmentPaths) {
         ``,
         thread,
         ...files,
+        deliverablesInstruction(ticket.id),
     ].join("\n");
 }
 /** Download the ticket's attachments so the headless session can open them. */
@@ -203,58 +216,252 @@ async function fetchAttachments(ticket, messages) {
     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.
+ * Run headless Claude Code (ideas borrowed from claude-code-telegram's runner):
+ * - prompt via STDIN (ARG_MAX-proof, quoting-proof, not in `ps`)
+ * - `--permission-mode bypassPermissions` by default — an autonomous runner must
+ *   be able to edit files / run commands (override: CLAUDE_PERMISSION_MODE)
+ * - `--output-format json` → { result, session_id, is_error, permission_denials }
+ * - SIGTERM → SIGKILL escalation; salvage JSON from a timed-out process
  */
-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 PERMISSION_MODE = process.env.CLAUDE_PERMISSION_MODE ?? "bypassPermissions";
+const CLAUDE_TIMEOUT_MS = Number(process.env.CLAUDE_TIMEOUT_MS ?? String(10 * 60 * 1000));
+// Sessions run in a stable workspace so their JSONL lives at a predictable path
+// (~/.claude/projects/<slug>/<sessionId>.jsonl) for the live-progress watcher.
+const WORK_DIR = process.env.MAILBOX_WORKDIR ?? join(homedir(), ".agent-ticketing", "workspace");
+mkdirSync(WORK_DIR, { recursive: true });
+function runClaude(prompt, session, signal) {
+    return new Promise((resolve) => {
         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"],
-        });
+        const args = ["-p", "--output-format", "json", "--permission-mode", PERMISSION_MODE];
+        if (session.resume)
+            args.push("--resume", session.resume);
+        else if (session.newId)
+            args.push("--session-id", session.newId);
+        const child = spawn(claudeCmd, args, { env, cwd: WORK_DIR, 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}`)));
+        let timedOut = false;
+        let killTimer;
+        const kill = () => {
+            try {
+                child.kill();
+            }
+            catch { /* already gone */ }
+            killTimer = setTimeout(() => {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch { /* already gone */ }
+            }, 3_000);
+        };
+        const timeout = CLAUDE_TIMEOUT_MS > 0
+            ? setTimeout(() => { timedOut = true; kill(); }, CLAUDE_TIMEOUT_MS)
+            : undefined;
+        const onAbort = () => kill();
+        signal?.addEventListener("abort", onAbort, { once: true });
+        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) => finish({ kind: "error", message: `could not run "${claudeCmd}": ${e.message}` }));
         child.on("close", (code, sig) => {
-            if (code === 0)
-                return resolve(stdout);
+            const parsed = parseClaudeOutput(stdout, stderr);
+            if (parsed)
+                return finish(parsed);
+            if (timedOut)
+                return finish({ kind: "error", message: `claude timed out after ${Math.round(CLAUDE_TIMEOUT_MS / 60000)} min` });
             const tail = stderr.trim().slice(-600) || stdout.trim().slice(-600) || "(no output)";
-            reject(new Error(`${claudeCmd} exited with ${sig ? `signal ${sig}` : `code ${code}`}: ${tail}`));
+            finish({ kind: "error", message: `${claudeCmd} exited with ${sig ? `signal ${sig}` : `code ${code}`}: ${tail}` });
         });
-        child.stdin.on("error", () => undefined); // child died before reading stdin; close() reports it
+        function finish(o) {
+            if (timeout)
+                clearTimeout(timeout);
+            if (killTimer)
+                clearTimeout(killTimer);
+            signal?.removeEventListener("abort", onAbort);
+            resolve(o);
+        }
+        child.stdin.on("error", () => undefined);
         child.stdin.write(prompt);
         child.stdin.end();
     });
 }
+function parseClaudeOutput(stdout, stderr) {
+    if (/No conversation found with session ID/i.test(`${stdout}\n${stderr}`)) {
+        return { kind: "stale_session" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return null; // not JSON — let close-handler report exit code/stderr
+    }
+    if (parsed.is_error)
+        return { kind: "error", message: parsed.result || "claude reported an error" };
+    return { kind: "ok", result: (parsed.result ?? "").trim(), questions: extractQuestions(parsed.permission_denials) };
+}
+/** Headless mode auto-denies AskUserQuestion but preserves it in permission_denials —
+ * recover the questions so they become ask_requester on the ticket. */
+function extractQuestions(denials) {
+    const out = [];
+    for (const d of denials ?? []) {
+        if (d?.tool_name !== "AskUserQuestion")
+            continue;
+        const qs = d.tool_input?.questions;
+        if (!Array.isArray(qs))
+            continue;
+        for (const q of qs) {
+            if (typeof q?.question !== "string")
+                continue;
+            let text = q.question;
+            const opts = (q.options ?? []).filter((o) => typeof o?.label === "string");
+            if (opts.length > 0) {
+                text += "\n" + opts.map((o) => `- **${o.label}**${o.description ? ` — ${o.description}` : ""}`).join("\n");
+            }
+            out.push(text);
+        }
+    }
+    return out;
+}
+// ── live progress: tail the session JSONL and post ⚙ steps to the ticket ─────
+// (adapted from claude-code-telegram/server/claude-stream.ts)
+function sessionJsonlPath(sessionId) {
+    // Claude Code's project slug replaces EVERY non-alphanumeric char with "-"
+    // (verified: /Users/x/.agent-ticketing/workspace → -Users-x--agent-ticketing-workspace)
+    const slug = resolve(WORK_DIR).replace(/[^a-zA-Z0-9]/g, "-");
+    return join(homedir(), ".claude", "projects", slug, `${sessionId}.jsonl`);
+}
+function stepLabel(block) {
+    const name = block.name ?? "?";
+    const input = block.input ?? {};
+    const short = (v, n = 70) => {
+        const t = String(v ?? "");
+        return t.length > n ? t.slice(0, n) + "…" : t;
+    };
+    switch (name) {
+        case "Bash": return `Bash: ${short(input.command)}`;
+        case "Edit":
+        case "Write":
+        case "Read": return `${name}: ${short(basename(String(input.file_path ?? "")))}`;
+        case "Grep": return `Grep: ${short(input.pattern)}`;
+        case "Glob": return `Glob: ${short(input.pattern)}`;
+        case "WebFetch": return `WebFetch: ${short(input.url)}`;
+        case "WebSearch": return `WebSearch: ${short(input.query)}`;
+        case "Task": return `Task: ${short(input.description)}`;
+        case "TodoWrite": return "updating plan";
+        default: return name;
+    }
+}
+/**
+ * Tail the session JSONL (retrying until claude creates it) and report each
+ * tool-use step. Caller throttles/ships them to the ticket thread.
+ */
+function watchClaudeSession(sessionId, onStep) {
+    const path = sessionJsonlPath(sessionId);
+    let stopped = false;
+    let offset = 0;
+    let buf = "";
+    let fh = null;
+    let watcher = null;
+    let poll = null;
+    async function readNew() {
+        if (stopped || !fh)
+            return;
+        try {
+            const chunk = Buffer.alloc(64 * 1024);
+            for (;;) {
+                const { bytesRead } = await fh.read(chunk, 0, chunk.length, offset);
+                if (bytesRead === 0)
+                    break;
+                offset += bytesRead;
+                buf += chunk.toString("utf8", 0, bytesRead);
+                let nl;
+                while ((nl = buf.indexOf("\n")) !== -1) {
+                    const line = buf.slice(0, nl).trim();
+                    buf = buf.slice(nl + 1);
+                    if (!line)
+                        continue;
+                    try {
+                        const obj = JSON.parse(line);
+                        if (obj.type !== "assistant" || !Array.isArray(obj.message?.content))
+                            continue;
+                        for (const block of obj.message.content) {
+                            if (block?.type === "tool_use")
+                                onStep(stepLabel(block));
+                        }
+                    }
+                    catch { /* partial/bad line */ }
+                }
+            }
+        }
+        catch { /* transient read error */ }
+    }
+    async function tryOpen(attempt = 0) {
+        if (stopped)
+            return;
+        try {
+            fh = await fsOpen(path, "r");
+            // fresh sessions: read from the start; resumed: skip history
+            offset = 0;
+            watcher = watch(path, () => void readNew());
+            poll = setInterval(() => void readNew(), 2000);
+            void readNew();
+        }
+        catch {
+            if (attempt < 30)
+                setTimeout(() => void tryOpen(attempt + 1), 1000); // file appears when the session starts
+        }
+    }
+    void tryOpen();
+    return () => {
+        stopped = true;
+        if (poll)
+            clearInterval(poll);
+        watcher?.close();
+        void fh?.close().catch(() => undefined);
+    };
+}
+/** A prior run of this ticket announced its session in a progress note — find it. */
+function findPreviousSession(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m.kind !== "progress")
+            continue;
+        const match = /headless Claude Code session ([0-9a-f-]{36})/.exec(m.body);
+        if (match)
+            return match[1];
+    }
+    return null;
+}
+/** For resumed sessions: only what happened since the agent last spoke. */
+function repliesSince(messages) {
+    let lastAgent = -1;
+    messages.forEach((m, i) => {
+        if (m.author.type === "agent")
+            lastAgent = i;
+    });
+    const fresh = messages.slice(lastAgent + 1).filter((m) => m.kind === "message" && m.author.type === "human");
+    return fresh.map((m) => m.body).join("\n\n");
+}
+const MAX_DELIVERABLES = 10; // server cap: attachments per message
+const MAX_DELIVERABLE_BYTES = 25 * 1024 * 1024;
+const MIME_BY_EXT = {
+    png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp",
+    svg: "image/svg+xml", pdf: "application/pdf", txt: "text/plain", md: "text/markdown",
+    json: "application/json", csv: "text/csv", html: "text/html", zip: "application/zip",
+};
 const controller = new AbortController();
 await mailbox.poll(async (ticket, ctx) => {
-    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");
-    await ctx.complete(result.slice(0, 60_000));
-    if (once)
-        controller.abort();
+    try {
+        await workTicket(ticket, ctx);
+    }
+    finally {
+        if (once)
+            controller.abort(); // every outcome ends a --once run: complete, ask, or error
+    }
 }, {
     mode: interval ? "interval" : "continuous",
     every: interval ?? "5m",
@@ -262,3 +469,130 @@ await mailbox.poll(async (ticket, ctx) => {
     signal: controller.signal,
     onEvent,
 });
+async function workTicket(ticket, ctx) {
+    mkdirSync(deliverablesDir(ticket.id), { recursive: true });
+    const attachmentPaths = await fetchAttachments(ticket, ctx.messages);
+    const previous = findPreviousSession(ctx.messages);
+    const sessionId = previous ?? crypto.randomUUID();
+    onEvent?.({
+        ts: new Date().toISOString(),
+        event: "claude_session",
+        instanceId: mailbox.instanceId,
+        ticketId: ticket.id,
+        detail: { message: sessionId + (previous ? " (resumed)" : "") },
+    });
+    await ctx.progress(`headless Claude Code session ${sessionId}` +
+        (previous ? " (resumed)" : "") +
+        (attachmentPaths.length > 0 ? ` (${attachmentPaths.length} attachment(s) downloaded)` : ""));
+    // Live peek: steps from the session JSONL → throttled ⚙ entries on the ticket.
+    let lastShipped = 0;
+    let lastLabel = "";
+    const stopWatch = watchClaudeSession(sessionId, (label) => {
+        const now = Date.now();
+        if (label === lastLabel || now - lastShipped < 7_000)
+            return;
+        lastShipped = now;
+        lastLabel = label;
+        ctx.progress(label).catch(() => undefined); // heartbeat + visible step; best-effort
+    });
+    const freshPrompt = promptFor(ticket, ctx.messages, attachmentPaths);
+    const resumePrompt = `The requester replied on the ticket you were working:\n\n${repliesSince(ctx.messages)}\n\n` +
+        `Continue the task. Reply with your final result (it is posted back as the ticket resolution), ` +
+        `or use the AskUserQuestion tool if you are blocked on the requester again.` +
+        deliverablesInstruction(ticket.id);
+    let outcome = previous
+        ? await runClaude(resumePrompt, { resume: previous }, ctx.signal)
+        : await runClaude(freshPrompt, { newId: sessionId }, ctx.signal);
+    if (outcome.kind === "stale_session" && previous) {
+        // Session file vanished (cache cleaned / machine changed) — start over.
+        stopWatch();
+        const freshId = crypto.randomUUID();
+        await ctx.progress(`previous session gone — fresh headless Claude Code session ${freshId}`);
+        const stopWatch2 = watchClaudeSession(freshId, (label) => {
+            const now = Date.now();
+            if (label === lastLabel || now - lastShipped < 7_000)
+                return;
+            lastShipped = now;
+            lastLabel = label;
+            ctx.progress(label).catch(() => undefined);
+        });
+        try {
+            outcome = await runClaude(freshPrompt, { newId: freshId }, ctx.signal);
+        }
+        finally {
+            stopWatch2();
+        }
+    }
+    stopWatch();
+    if (outcome.kind === "error" || outcome.kind === "stale_session") {
+        const message = outcome.kind === "error" ? outcome.message : "session lost and restart failed";
+        throw new Error(`${message} [claude session ${sessionId}]`);
+    }
+    if (outcome.questions.length > 0) {
+        // Claude asked the human — ticket goes pending; we resume this session
+        // after the reply (assignee survives claim expiry by design).
+        await ctx.askAsync(outcome.questions.join("\n\n"));
+        return;
+    }
+    if (!outcome.result)
+        throw new Error(`claude produced no output [claude session ${sessionId}]`);
+    const { attachmentIds, note } = await uploadDeliverables(ticket.id, ctx);
+    const summary = outcome.result.slice(0, 60_000) + note;
+    if (attachmentIds.length > 0)
+        await ctx.complete(summary, { attachmentIds });
+    else
+        await ctx.complete(summary);
+    rmSync(deliverablesDir(ticket.id), { recursive: true, force: true });
+}
+function listFilesRecursive(dir) {
+    const out = [];
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        const full = join(dir, e.name);
+        if (e.isDirectory())
+            out.push(...listFilesRecursive(full));
+        else if (e.isFile())
+            out.push(full);
+    }
+    return out.sort();
+}
+/** Upload everything Claude saved to the deliverables dir; report what was skipped. */
+async function uploadDeliverables(ticketId, ctx) {
+    void ctx; // (claim is held by caller; uploads use the client directly)
+    const files = listFilesRecursive(deliverablesDir(ticketId));
+    if (files.length === 0)
+        return { attachmentIds: [], note: "" };
+    const attachmentIds = [];
+    const skipped = [];
+    for (const path of files) {
+        const name = basename(path);
+        if (attachmentIds.length >= MAX_DELIVERABLES) {
+            skipped.push(`${name} (over ${MAX_DELIVERABLES}-file limit)`);
+            continue;
+        }
+        try {
+            if (statSync(path).size > MAX_DELIVERABLE_BYTES) {
+                skipped.push(`${name} (larger than 25MB)`);
+                continue;
+            }
+            const ext = name.split(".").pop()?.toLowerCase() ?? "";
+            const id = await mailbox.uploadAttachment(ticketId, {
+                filename: name,
+                contentType: MIME_BY_EXT[ext] ?? "application/octet-stream",
+                data: new Uint8Array(readFileSync(path)),
+            });
+            attachmentIds.push(id);
+        }
+        catch (e) {
+            skipped.push(`${name} (upload failed: ${e instanceof Error ? e.message : String(e)})`);
+        }
+    }
+    const note = skipped.length > 0 ? `\n\n---\n⚠️ Deliverables not attached: ${skipped.join(", ")}` : "";
+    return { attachmentIds, note };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-ticketing",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Agent SDK for Agent Mailbox — poll tickets, heartbeat, ask the requester, complete. Zero dependencies.",
   "type": "module",
   "main": "./dist/index.js",