agent-ticketing 0.1.2 → 0.1.3

package/README.md

@@ -75,6 +75,19 @@ 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>`.
+- `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

@@ -203,58 +203,143 @@ 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));
+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, 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;
+}
+/** 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 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 +347,44 @@ await mailbox.poll(async (ticket, ctx) => {
     signal: controller.signal,
     onEvent,
 });
+async function workTicket(ticket, ctx) {
+    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)` : ""));
+    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.`;
+    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.
+        const freshId = crypto.randomUUID();
+        await ctx.progress(`previous session gone — fresh headless Claude Code session ${freshId}`);
+        outcome = await runClaude(freshPrompt, { newId: freshId }, ctx.signal);
+    }
+    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}]`);
+    await ctx.complete(outcome.result.slice(0, 60_000));
+}

package/package.json

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