agent-ticketing 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# agent-ticketing
+
+Agent SDK for **Agent Mailbox** — claim tickets, heartbeat, ask the requester, complete. Zero dependencies, Node 18+.
+
+```bash
+npm install agent-ticketing   # (or use it from this repo via workspaces)
+```
+
+## Quick start
+
+```ts
+import { MailboxAgent } from "agent-ticketing";
+
+const mailbox = new MailboxAgent({
+  baseUrl: "https://agent-mailbox.<you>.workers.dev",
+  apiKey: process.env.MAILBOX_API_KEY, // mbx_live_… from Settings → Agents
+});
+
+await mailbox.poll(async (ticket, ctx) => {
+  await ctx.progress("reading the request");          // heartbeat + visible note
+  const env = await ctx.ask("staging or prod?");      // → pending, waits for the human
+  // ...do the work...
+  const id = await ctx.attach("./report.pdf");        // staged upload
+  await ctx.complete(`Deployed to ${env}`, { attachmentIds: [id] }); // → done
+});
+```
+
+## Polling modes
+
+```ts
+await mailbox.poll(handler);                              // continuous: pickup ≤ ~3s
+await mailbox.poll(handler, { mode: "interval", every: "5m" }); // lazy: near-free, pickup ≤ 5m
+```
+
+The server holds each poll cheaply (facade claim gate) — continuous polling does
+NOT keep the Durable Object hot, so pick the mode by latency preference, not cost.
+
+## Semantics you get for free
+
+- **Auto-heartbeat** every 45s while your handler runs (server expiry: 3 min of silence).
+- **Crash recovery**: the instance id defaults to `host:<hostname>` (stable), so if
+  your process dies mid-ticket, the next `poll()` re-delivers the same ticket to you.
+- **Claim-loss detection**: if the human resolves/cancels the ticket while you work,
+  `ctx.signal` aborts and the next `ctx.*` call throws `ClaimLostError` — stop quietly.
+- **Handler errors → release**: the ticket goes back to human triage (unassigned) with
+  the error in the thread. Use `onError: "abandon"` to let the claim expire and retry
+  yourself later instead.
+- **Returning a string** from the handler is shorthand for `ctx.complete(thatString)`.
+- **Retries**: 429s honor `Retry-After`; 5xx/network errors back off exponentially.
+  Message posts are idempotent (client-generated ULIDs), so retries never duplicate.
+- **Graceful shutdown**: SIGINT/SIGTERM stop the loop; in-flight claims are re-delivered
+  to this instance on restart.
+
+## Examples
+
+- [`examples/simple-agent.mjs`](examples/simple-agent.mjs) — the full context API.
+- [`examples/runner-claude.mjs`](examples/runner-claude.mjs) — session-based agents
+  (Claude Code, Codex): the runner owns the loop and heartbeats, `claude -p` owns
+  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
+```
+
+## Low-level client
+
+Every REST endpoint is also exposed directly if you don't want the loop:
+`claimNext`, `getTicket`, `heartbeat`, `postMessage`, `complete`, `release`,
+`uploadAttachment`.

package/dist/index.d.ts

@@ -0,0 +1,153 @@
+/**
+ * @mailbox/agent — the ~300-line integration an agent needs (docs/06).
+ *
+ * const mailbox = new MailboxAgent({ baseUrl, apiKey });
+ * await mailbox.poll(async (ticket, ctx) => {
+ *   await ctx.progress("reading the request");
+ *   const answer = await ctx.ask("prod or staging?");
+ *   await ctx.complete(`done — deployed to ${answer}`);
+ * });
+ *
+ * Handles: long-poll loop (continuous or interval), auto-heartbeat, retry with
+ * backoff (respects Retry-After), idempotent message IDs, crash recovery
+ * (stable instance id ⇒ re-claiming your in-flight ticket), claim-loss
+ * detection (human resolved/cancelled ⇒ ctx.signal aborts), graceful SIGTERM.
+ */
+export type TicketStatus = "new" | "open" | "pending" | "done" | "resolved" | "cancelled";
+export type Ticket = {
+    id: string;
+    subject: string;
+    status: TicketStatus;
+    requesterId: string;
+    assigneeAgentId: string | null;
+    claim: {
+        agentId: string;
+        agentInstanceId: string;
+        claimedAt: number;
+        lastHeartbeatAt: number;
+    } | null;
+    createdAt: number;
+    updatedAt: number;
+    doneAt: number | null;
+    metadata: Record<string, string>;
+};
+export type Message = {
+    id: string;
+    ticketId: string;
+    author: {
+        type: "human" | "agent" | "system";
+        id: string;
+    };
+    kind: "message" | "progress" | "status_change";
+    body: string;
+    bodyFormat: "markdown" | "text";
+    replyToMessageId: string | null;
+    attachments: {
+        id: string;
+        filename: string;
+        contentType: string;
+        size: number;
+    }[];
+    createdAt: number;
+};
+export type Claimed = {
+    ticket: Ticket;
+    messages: Message[];
+};
+export type MailboxConfig = {
+    baseUrl: string;
+    apiKey: string;
+    /** Stable id per running instance. Default: "host:<hostname>" — stable across
+     * restarts so an interrupted ticket is re-delivered to you (crash recovery). */
+    agentInstanceId?: string;
+};
+export type MailboxEvent = {
+    ts: string;
+    event: "poll_start" | "claimed" | "completed" | "released" | "claim_lost" | "handler_error" | "poll_error";
+    instanceId: string;
+    ticketId?: string;
+    subject?: string;
+    /** For errors: message, and HTTP status/code when the server rejected a call. */
+    detail?: {
+        message?: string;
+        status?: number;
+        code?: string;
+    };
+};
+export type PollOptions = {
+    /** "continuous": re-poll immediately (pickup ≤ ~3s). "interval": sleep between
+     * empty polls — near-free, pickup within the interval. */
+    mode?: "continuous" | "interval";
+    /** Interval-mode sleep between empty polls: ms or "30s" | "5m" | "1h". Default "5m". */
+    every?: number | string;
+    /** Long-poll hold per request, 1–30s. Default 25. */
+    timeoutSec?: number;
+    /** Auto-heartbeat cadence while a handler runs. Default 45s (server expiry 3min). */
+    heartbeatSeconds?: number;
+    /** Handler threw: "release" hands the ticket back to human triage (default);
+     * "abandon" leaves the claim to expire so THIS agent retries it later. */
+    onError?: "release" | "abandon";
+    /** Stop polling (also wired to SIGINT/SIGTERM unless handleSignals: false). */
+    signal?: AbortSignal;
+    handleSignals?: boolean;
+    /** Called for lifecycle logs. Default: console.error. */
+    log?: (msg: string) => void;
+    /** Structured lifecycle events (NDJSON-friendly) — every event carries the
+     * ticket ULID so client logs cross-reference the server-side thread history. */
+    onEvent?: (e: MailboxEvent) => void;
+};
+export type TicketContext = {
+    ticket: Ticket;
+    messages: Message[];
+    /** Aborts when the claim is lost (expired, or human resolved/cancelled/withdrew). */
+    signal: AbortSignal;
+    /** Heartbeat with a visible progress note (collapsed in the UI timeline). */
+    progress(note: string): Promise<void>;
+    /** Post a markdown message to the thread. */
+    post(body: string, opts?: {
+        attachmentIds?: string[];
+    }): Promise<void>;
+    /** Ask the human (ticket → pending) and WAIT for their reply. Returns the reply body. */
+    ask(question: string, opts?: {
+        pollSeconds?: number;
+    }): Promise<string>;
+    /** 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. */
+    complete(summary?: string, opts?: {
+        attachmentIds?: string[];
+    }): Promise<void>;
+    /** Give the ticket back to human triage (unassigns it). Ends the handler's claim. */
+    release(reason?: string): Promise<void>;
+};
+export declare class ClaimLostError extends Error {
+    constructor(message?: string);
+}
+export declare class MailboxApiError extends Error {
+    status: number;
+    code: string;
+    constructor(status: number, code: string, message: string);
+}
+export declare class MailboxAgent {
+    #private;
+    readonly baseUrl: string;
+    readonly instanceId: string;
+    constructor(cfg: MailboxConfig);
+    claimNext(timeoutSec?: number): Promise<Claimed | null>;
+    getTicket(ticketId: string): Promise<Claimed>;
+    heartbeat(ticketId: string, note?: string): Promise<void>;
+    postMessage(ticketId: string, body: string, opts?: {
+        kind?: "message" | "progress";
+        askRequester?: boolean;
+        attachmentIds?: string[];
+    }): Promise<Message>;
+    complete(ticketId: string, summary?: string): Promise<Ticket>;
+    release(ticketId: string, reason?: string): Promise<Ticket>;
+    uploadAttachment(ticketId: string, file: {
+        filename: string;
+        contentType?: string;
+        data: Uint8Array | string;
+    }): Promise<string>;
+    poll(handler: (ticket: Ticket, ctx: TicketContext) => Promise<void | string>, opts?: PollOptions): Promise<void>;
+}
+export declare function ulid(now?: number): string;

package/dist/index.js

@@ -0,0 +1,360 @@
+/**
+ * @mailbox/agent — the ~300-line integration an agent needs (docs/06).
+ *
+ * const mailbox = new MailboxAgent({ baseUrl, apiKey });
+ * await mailbox.poll(async (ticket, ctx) => {
+ *   await ctx.progress("reading the request");
+ *   const answer = await ctx.ask("prod or staging?");
+ *   await ctx.complete(`done — deployed to ${answer}`);
+ * });
+ *
+ * Handles: long-poll loop (continuous or interval), auto-heartbeat, retry with
+ * backoff (respects Retry-After), idempotent message IDs, crash recovery
+ * (stable instance id ⇒ re-claiming your in-flight ticket), claim-loss
+ * detection (human resolved/cancelled ⇒ ctx.signal aborts), graceful SIGTERM.
+ */
+import { hostname } from "node:os";
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+export class ClaimLostError extends Error {
+    constructor(message = "claim lost (ticket resolved, cancelled, or expired)") {
+        super(message);
+        this.name = "ClaimLostError";
+    }
+}
+export class MailboxApiError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "MailboxApiError";
+    }
+}
+// ── client ────────────────────────────────────────────────────────────────────
+export class MailboxAgent {
+    baseUrl;
+    instanceId;
+    #apiKey;
+    constructor(cfg) {
+        this.baseUrl = cfg.baseUrl.replace(/\/$/, "");
+        this.#apiKey = cfg.apiKey;
+        this.instanceId = cfg.agentInstanceId ?? `host:${hostname()}`;
+    }
+    // ── low-level API (1:1 with docs/03-api.md) ────────────────────────────────
+    async claimNext(timeoutSec = 25) {
+        const res = await this.#request("POST", "/v1/tickets/claim", {
+            agentInstanceId: this.instanceId,
+            timeoutSec,
+        });
+        if (res.status === 204)
+            return null;
+        return (await res.json());
+    }
+    async getTicket(ticketId) {
+        const res = await this.#request("GET", `/v1/tickets/${ticketId}`);
+        return (await res.json());
+    }
+    async heartbeat(ticketId, note) {
+        await this.#request("POST", `/v1/tickets/${ticketId}/heartbeat`, {
+            agentInstanceId: this.instanceId,
+            note,
+        });
+    }
+    async postMessage(ticketId, body, opts = {}) {
+        const res = await this.#request("POST", `/v1/tickets/${ticketId}/messages`, {
+            id: ulid(),
+            agentInstanceId: this.instanceId,
+            body,
+            kind: opts.kind,
+            askRequester: opts.askRequester,
+            attachmentIds: opts.attachmentIds,
+        });
+        return (await res.json()).message;
+    }
+    async complete(ticketId, summary) {
+        const res = await this.#request("POST", `/v1/tickets/${ticketId}/complete`, {
+            agentInstanceId: this.instanceId,
+            summary,
+        });
+        return (await res.json()).ticket;
+    }
+    async release(ticketId, reason) {
+        const res = await this.#request("POST", `/v1/tickets/${ticketId}/release`, {
+            agentInstanceId: this.instanceId,
+            reason,
+        });
+        return (await res.json()).ticket;
+    }
+    async uploadAttachment(ticketId, file) {
+        const params = new URLSearchParams({
+            filename: file.filename,
+            contentType: file.contentType ?? "application/octet-stream",
+        });
+        const body = typeof file.data === "string" ? new TextEncoder().encode(file.data) : file.data;
+        const res = await fetch(`${this.baseUrl}/v1/tickets/${ticketId}/attachments?${params}`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.#apiKey}`,
+                "Content-Length": String(body.byteLength),
+            },
+            body,
+        });
+        if (!res.ok)
+            throw await toApiError(res);
+        return (await res.json()).attachment.id;
+    }
+    // ── the poll loop (docs/06 Layer 1) ────────────────────────────────────────
+    async poll(handler, opts = {}) {
+        const mode = opts.mode ?? "continuous";
+        const everyMs = parseDuration(opts.every ?? "5m");
+        const timeoutSec = Math.min(Math.max(opts.timeoutSec ?? 25, 1), 30);
+        const heartbeatMs = (opts.heartbeatSeconds ?? 45) * 1000;
+        const onError = opts.onError ?? "release";
+        const log = opts.log ?? ((m) => console.error(`[mailbox] ${m}`));
+        const emit = (e) => opts.onEvent?.({ ts: new Date().toISOString(), instanceId: this.instanceId, ...e });
+        const stop = new AbortController();
+        if (opts.signal)
+            opts.signal.addEventListener("abort", () => stop.abort(), { once: true });
+        if (opts.handleSignals !== false) {
+            const onSignal = () => {
+                log("shutting down (claim will be re-delivered to this instance on restart)");
+                stop.abort();
+            };
+            process.once("SIGINT", onSignal);
+            process.once("SIGTERM", onSignal);
+        }
+        log(`polling ${this.baseUrl} as instance "${this.instanceId}" (${mode})`);
+        emit({ event: "poll_start" });
+        while (!stop.signal.aborted) {
+            let claimed = null;
+            try {
+                claimed = await this.claimNext(timeoutSec);
+            }
+            catch (e) {
+                log(`claim failed: ${String(e)} — backing off 10s`);
+                emit({ event: "poll_error", detail: errDetail(e) });
+                await sleep(10_000, stop.signal);
+                continue;
+            }
+            if (!claimed) {
+                if (mode === "interval")
+                    await sleep(everyMs, stop.signal);
+                continue;
+            }
+            await this.#handleTicket(claimed, handler, { heartbeatMs, onError, log, emit, stop: stop.signal });
+            // after finishing a ticket, poll again immediately in both modes —
+            // there may be more queued work.
+        }
+    }
+    async #handleTicket(claimed, handler, o) {
+        const { ticket } = claimed;
+        const claimLost = new AbortController();
+        let finished = false;
+        o.log(`claimed ${ticket.id}: ${ticket.subject}`);
+        o.emit({ event: "claimed", ticketId: ticket.id, subject: ticket.subject });
+        const heartbeatTimer = setInterval(() => {
+            this.heartbeat(ticket.id).catch((e) => {
+                if (e instanceof MailboxApiError && (e.status === 409 || e.status === 404)) {
+                    o.log(`claim lost on ${ticket.id}: ${e.message}`);
+                    o.emit({ event: "claim_lost", ticketId: ticket.id, detail: errDetail(e) });
+                    claimLost.abort();
+                    clearInterval(heartbeatTimer);
+                }
+                // transient errors: next heartbeat retries; server allows 3min of silence
+            });
+        }, o.heartbeatMs);
+        const self = this;
+        const ctx = {
+            ticket,
+            messages: claimed.messages,
+            signal: claimLost.signal,
+            async progress(note) {
+                assertLive(claimLost.signal);
+                await self.heartbeat(ticket.id, note);
+            },
+            async post(body, opts) {
+                assertLive(claimLost.signal);
+                await self.postMessage(ticket.id, body, { attachmentIds: opts?.attachmentIds });
+            },
+            async ask(question, opts) {
+                assertLive(claimLost.signal);
+                const asked = await self.postMessage(ticket.id, question, { askRequester: true });
+                const pollMs = (opts?.pollSeconds ?? 5) * 1000;
+                for (;;) {
+                    await sleep(pollMs, claimLost.signal);
+                    assertLive(claimLost.signal);
+                    const { ticket: t, messages } = await self.getTicket(ticket.id);
+                    if (t.status === "resolved" || t.status === "cancelled")
+                        throw new ClaimLostError(`ticket ${t.status}`);
+                    const reply = messages.find((m) => m.author.type === "human" && m.id > asked.id);
+                    if (reply)
+                        return reply.body;
+                }
+            },
+            async attach(filePath, contentType) {
+                assertLive(claimLost.signal);
+                const data = new Uint8Array(await readFile(filePath));
+                return self.uploadAttachment(ticket.id, { filename: basename(filePath), contentType, data });
+            },
+            async complete(summary, opts) {
+                assertLive(claimLost.signal);
+                if (opts?.attachmentIds?.length) {
+                    await self.postMessage(ticket.id, summary ?? "attached results", { attachmentIds: opts.attachmentIds });
+                    await self.complete(ticket.id);
+                }
+                else {
+                    await self.complete(ticket.id, summary);
+                }
+                finished = true;
+                o.emit({ event: "completed", ticketId: ticket.id });
+            },
+            async release(reason) {
+                assertLive(claimLost.signal);
+                await self.release(ticket.id, reason);
+                finished = true;
+                o.emit({ event: "released", ticketId: ticket.id, detail: { message: reason } });
+            },
+        };
+        try {
+            const returned = await handler(ticket, ctx);
+            if (!finished && !claimLost.signal.aborted) {
+                if (typeof returned === "string") {
+                    await self.complete(ticket.id, returned); // returning a string = the summary
+                    o.emit({ event: "completed", ticketId: ticket.id });
+                }
+                else {
+                    o.log(`handler returned without complete/release — releasing ${ticket.id} to triage`);
+                    await self.release(ticket.id, "agent handler finished without completing");
+                    o.emit({ event: "released", ticketId: ticket.id, detail: { message: "handler finished without completing" } });
+                }
+            }
+            o.log(`finished ${ticket.id}`);
+        }
+        catch (e) {
+            if (claimLost.signal.aborted || e instanceof ClaimLostError) {
+                o.log(`stopped working ${ticket.id}: claim lost`);
+                o.emit({ event: "claim_lost", ticketId: ticket.id, detail: errDetail(e) });
+            }
+            else {
+                o.log(`handler error on ${ticket.id}: ${String(e)}`);
+                o.emit({ event: "handler_error", ticketId: ticket.id, detail: errDetail(e) });
+                if (o.onError === "release" && !finished) {
+                    await this.release(ticket.id, `agent error: ${truncate(String(e), 500)}`).catch(() => undefined);
+                    o.emit({ event: "released", ticketId: ticket.id, detail: { message: "released after handler error" } });
+                }
+                // "abandon": say nothing; the visibility timeout reverts the claim and
+                // this same instance will pick it up again later.
+            }
+        }
+        finally {
+            clearInterval(heartbeatTimer);
+        }
+    }
+    // ── internals ──────────────────────────────────────────────────────────────
+    async #request(method, path, body) {
+        let attempt = 0;
+        for (;;) {
+            attempt++;
+            let res;
+            try {
+                res = await fetch(`${this.baseUrl}${path}`, {
+                    method,
+                    headers: { Authorization: `Bearer ${this.#apiKey}`, "Content-Type": "application/json" },
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                });
+            }
+            catch (e) {
+                if (attempt >= 5)
+                    throw e;
+                await sleep(backoff(attempt)); // network blip
+                continue;
+            }
+            if (res.ok || res.status === 204)
+                return res;
+            if (res.status === 429) {
+                const retryAfter = Number(res.headers.get("Retry-After") ?? "30");
+                await sleep(retryAfter * 1000);
+                continue;
+            }
+            if (res.status >= 500 && attempt < 5) {
+                await sleep(backoff(attempt));
+                continue;
+            }
+            throw await toApiError(res); // 4xx: caller's problem (message ids make retries idempotent anyway)
+        }
+    }
+}
+function errDetail(e) {
+    if (e instanceof MailboxApiError)
+        return { message: e.message, status: e.status, code: e.code };
+    return { message: e instanceof Error ? e.message : String(e) };
+}
+function assertLive(signal) {
+    if (signal.aborted)
+        throw new ClaimLostError();
+}
+async function toApiError(res) {
+    let code = "error";
+    let message = res.statusText;
+    try {
+        const body = (await res.json());
+        if (body.error)
+            ({ code, message } = body.error);
+    }
+    catch {
+        // non-JSON body
+    }
+    return new MailboxApiError(res.status, code, message);
+}
+function backoff(attempt) {
+    return Math.min(1000 * 2 ** (attempt - 1), 30_000) * (0.5 + Math.random() * 0.5);
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        const t = setTimeout(done, ms);
+        function done() {
+            signal?.removeEventListener("abort", done);
+            clearTimeout(t);
+            resolve();
+        }
+        signal?.addEventListener("abort", done, { once: true });
+    });
+}
+function parseDuration(v) {
+    if (typeof v === "number")
+        return v;
+    const m = /^(\d+)(ms|s|m|h)$/.exec(v.trim());
+    if (!m)
+        throw new Error(`invalid duration: "${v}" (use e.g. 30000, "30s", "5m", "1h")`);
+    const n = Number(m[1]);
+    return { ms: n, s: n * 1000, m: n * 60_000, h: n * 3_600_000 }[m[2]];
+}
+function truncate(s, n) {
+    return s.length > n ? `${s.slice(0, n)}…` : s;
+}
+// ULID (Crockford base32, time-sortable) — message idempotency keys.
+const ENC = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export function ulid(now = Date.now()) {
+    let time = "";
+    let t = now;
+    for (let i = 0; i < 10; i++) {
+        time = ENC[t % 32] + time;
+        t = Math.floor(t / 32);
+    }
+    const bytes = crypto.getRandomValues(new Uint8Array(10));
+    let rand = "";
+    let bits = 0;
+    let acc = 0;
+    for (const b of bytes) {
+        acc = (acc << 8) | b;
+        bits += 8;
+        while (bits >= 5) {
+            rand += ENC[(acc >>> (bits - 5)) & 31];
+            bits -= 5;
+            acc &= (1 << bits) - 1;
+        }
+    }
+    return time + rand;
+}

package/dist/runner.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/runner.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * mailbox-claude-runner — autonomous pickup for session-based agents.
+ * Polls the mailbox; per ticket, launches a headless Claude Code session with
+ * the thread as prompt and completes the ticket with its output.
+ *
+ *   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 { MailboxAgent } from "./index.js";
+const exec = promisify(execFile);
+const baseUrl = process.env.MAILBOX_URL;
+const apiKey = process.env.MAILBOX_API_KEY;
+if (!baseUrl || !apiKey) {
+    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");
+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.
+const logFile = process.env.MAILBOX_LOG_FILE;
+const onEvent = logFile
+    ? (e) => {
+        try {
+            appendFileSync(logFile, JSON.stringify(e) + "\n");
+        }
+        catch (err) {
+            console.error(`[mailbox] could not write ${logFile}: ${String(err)}`);
+        }
+    }
+    : undefined;
+const mailbox = new MailboxAgent({ baseUrl, apiKey });
+function promptFor(ticket, messages) {
+    const thread = messages
+        .filter((m) => m.kind === "message")
+        .map((m) => `${m.author.type === "human" ? "REQUESTER" : m.author.type.toUpperCase()}: ${m.body}`)
+        .join("\n\n");
+    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.`,
+        ``,
+        `TICKET: ${ticket.subject}`,
+        ``,
+        thread,
+    ].join("\n");
+}
+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 result = stdout.trim();
+    if (!result)
+        throw new Error("claude produced no output");
+    await ctx.complete(result.slice(0, 60_000));
+    if (once)
+        controller.abort();
+}, {
+    mode: interval ? "interval" : "continuous",
+    every: interval ?? "5m",
+    onError: "release",
+    signal: controller.signal,
+    onEvent,
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "agent-ticketing",
+  "version": "0.1.0",
+  "description": "Agent SDK for Agent Mailbox — poll tickets, heartbeat, ask the requester, complete. Zero dependencies.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0"
+  },
+  "bin": {
+    "mailbox-claude-runner": "./dist/runner.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/terryds/agent-mailbox"
+  },
+  "license": "MIT",
+  "keywords": [
+    "ai-agents",
+    "ticketing",
+    "mcp",
+    "claude-code"
+  ]
+}