agent-ticketing 0.1.3 → 0.1.5

package/README.md

@@ -85,6 +85,14 @@ for a custom harness, embed the SDK instead (below).
   **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.
 

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. */
@@ -212,6 +225,10 @@ async function fetchAttachments(ticket, messages) {
  */
 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 };
@@ -222,7 +239,7 @@ function runClaude(prompt, session, signal) {
             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"] });
+        const child = spawn(claudeCmd, args, { env, cwd: WORK_DIR, stdio: ["pipe", "pipe", "pipe"] });
         let stdout = "";
         let stderr = "";
         let timedOut = false;
@@ -309,6 +326,104 @@ function extractQuestions(denials) {
     }
     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--) {
@@ -331,6 +446,17 @@ function repliesSince(messages) {
     const fresh = messages.slice(lastAgent + 1).filter((m) => m.kind === "message" && m.author.type === "human");
     return fresh.map((m) => m.body).join("\n\n");
 }
+// Live-step shipping cadence: min ms between ⚙ progress posts (each is a
+// permanent thread row + an HTTP call, and Claude bursts tool calls) — but
+// trailing-edge: the LATEST step always ships once the window opens.
+const STEP_INTERVAL_MS = Math.max(2_000, Number(process.env.MAILBOX_STEP_INTERVAL_MS ?? "7000"));
+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) => {
     try {
@@ -348,6 +474,7 @@ await mailbox.poll(async (ticket, ctx) => {
     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();
@@ -361,19 +488,63 @@ async function workTicket(ticket, ctx) {
     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.
+    // Trailing-edge throttle: never more often than STEP_INTERVAL_MS, but the
+    // latest step is never lost — it ships when the window reopens.
+    let lastShipped = 0;
+    let lastLabel = "";
+    let pending = null;
+    let pendingTimer = null;
+    const ship = (label) => {
+        lastShipped = Date.now();
+        lastLabel = label;
+        ctx.progress(label).catch(() => undefined); // heartbeat + visible step; best-effort
+    };
+    const onStep = (label) => {
+        if (label === lastLabel || label === pending)
+            return;
+        const wait = lastShipped + STEP_INTERVAL_MS - Date.now();
+        if (wait <= 0)
+            return ship(label);
+        pending = label;
+        if (!pendingTimer) {
+            pendingTimer = setTimeout(() => {
+                pendingTimer = null;
+                const p = pending;
+                pending = null;
+                if (p && p !== lastLabel)
+                    ship(p);
+            }, wait);
+        }
+    };
+    const stopWatch0 = watchClaudeSession(sessionId, onStep);
+    const stopWatch = () => {
+        stopWatch0();
+        if (pendingTimer)
+            clearTimeout(pendingTimer);
+    };
     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.`;
+        `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}`);
-        outcome = await runClaude(freshPrompt, { newId: freshId }, ctx.signal);
+        const stopWatch2 = watchClaudeSession(freshId, onStep);
+        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}]`);
@@ -386,5 +557,63 @@ async function workTicket(ticket, ctx) {
     }
     if (!outcome.result)
         throw new Error(`claude produced no output [claude session ${sessionId}]`);
-    await ctx.complete(outcome.result.slice(0, 60_000));
+    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.3",
+  "version": "0.1.5",
   "description": "Agent SDK for Agent Mailbox — poll tickets, heartbeat, ask the requester, complete. Zero dependencies.",
   "type": "module",
   "main": "./dist/index.js",