@dalmasonto/taskflow-mcp 1.0.33 → 2.0.0

package/dist/attachments.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Resolve local file paths into message attachments.
+ *
+ * An attachment becomes a fetchable URL once uploaded, so an unrestricted path
+ * parameter would turn one bad instruction into an exfiltration channel. Every
+ * path is therefore confined to the project root — the directory holding
+ * `.taskflow.json` — and validated fully before any upload begins.
+ */
+/** Mirrors `MAX_ATTACHMENT_BYTES` in the backend (views.rs). */
+export declare const MAX_ATTACHMENT_BYTES: number;
+export declare class AttachmentError extends Error {
+    constructor(message: string);
+}
+export interface Attachment {
+    filename: string;
+    bytes: Buffer;
+}
+/**
+ * Validate and read every path, or throw. Nothing is returned unless all paths
+ * pass — a partially-attached message is worse than none, because the reader
+ * sees text citing a file that never arrived.
+ */
+export declare function resolveAttachments(paths: string[], root: string): Promise<Attachment[]>;

package/dist/attachments.js

@@ -0,0 +1,66 @@
+/**
+ * Resolve local file paths into message attachments.
+ *
+ * An attachment becomes a fetchable URL once uploaded, so an unrestricted path
+ * parameter would turn one bad instruction into an exfiltration channel. Every
+ * path is therefore confined to the project root — the directory holding
+ * `.taskflow.json` — and validated fully before any upload begins.
+ */
+import { readFile, realpath, stat } from "node:fs/promises";
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
+/** Mirrors `MAX_ATTACHMENT_BYTES` in the backend (views.rs). */
+export const MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
+export class AttachmentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AttachmentError";
+    }
+}
+/**
+ * True when `candidate` is inside `root`.
+ *
+ * Uses `path.relative` rather than a string prefix test: `startsWith` would let
+ * `<root>_evil` pass, since it shares the root's characters without being under
+ * it. Both arguments must already be real (symlink-resolved) paths.
+ */
+function isInside(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel !== "" && !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel);
+}
+/**
+ * Validate and read every path, or throw. Nothing is returned unless all paths
+ * pass — a partially-attached message is worse than none, because the reader
+ * sees text citing a file that never arrived.
+ */
+export async function resolveAttachments(paths, root) {
+    const realRoot = await realpath(root);
+    const out = [];
+    for (const input of paths) {
+        // Relative paths resolve against the project root, never process.cwd():
+        // a stdio MCP server inherits the client's cwd, which need not match.
+        const absolute = isAbsolute(input) ? input : resolve(realRoot, input);
+        // realpath BEFORE the containment check — a symlink inside the root that
+        // points outside it would pass a check made on the unresolved path.
+        let real;
+        try {
+            real = await realpath(absolute);
+        }
+        catch {
+            throw new AttachmentError(`Attachment not found: ${input}`);
+        }
+        if (!isInside(realRoot, real)) {
+            throw new AttachmentError(`Attachment is outside the project root: ${input} (resolved to ${real})`);
+        }
+        const info = await stat(real);
+        if (!info.isFile()) {
+            throw new AttachmentError(`Attachment is not a file: ${input}`);
+        }
+        if (info.size > MAX_ATTACHMENT_BYTES) {
+            const mb = (info.size / (1024 * 1024)).toFixed(1);
+            throw new AttachmentError(`Attachment "${input}" is ${mb}MB; the maximum attachment size is 25MB.`);
+        }
+        out.push({ filename: basename(real), bytes: await readFile(real) });
+    }
+    return out;
+}
+//# sourceMappingURL=attachments.js.map

package/dist/attachments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.js","sourceRoot":"","sources":["../src/attachments.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEzE,gEAAgE;AAChE,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAErD,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAOD;;;;;;GAMG;AACH,SAAS,QAAQ,CAAC,IAAY,EAAE,SAAiB;IAC/C,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACtC,OAAO,GAAG,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AACvF,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAe,EACf,IAAY;IAEZ,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,GAAG,GAAiB,EAAE,CAAC;IAE7B,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,wEAAwE;QACxE,sEAAsE;QACtE,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAEtE,yEAAyE;QACzE,oEAAoE;QACpE,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,eAAe,CAAC,yBAAyB,KAAK,EAAE,CAAC,CAAC;QAC9D,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,eAAe,CACvB,2CAA2C,KAAK,iBAAiB,IAAI,GAAG,CACzE,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YACnB,MAAM,IAAI,eAAe,CAAC,6BAA6B,KAAK,EAAE,CAAC,CAAC;QAClE,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,GAAG,oBAAoB,EAAE,CAAC;YACrC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YAClD,MAAM,IAAI,eAAe,CACvB,eAAe,KAAK,QAAQ,EAAE,0CAA0C,CACzE,CAAC;QACJ,CAAC;QAED,GAAG,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtE,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,206 @@
+/**
+ * A small typed HTTP client for the TaskFlow backend's agent-authed API.
+ *
+ * One method per endpoint in the agent surface (Stages 1–6). Every request is
+ * authenticated with the profile key via `Authorization: Agent <key>`; the base
+ * URL is the resolved profile's `server`. A non-2xx response is turned into a
+ * thrown {@link TaskflowApiError} carrying the backend's `detail`/text so the
+ * MCP tool (or hook) surfaces a real reason, never a bare status.
+ *
+ * `fetchImpl` is injectable so the client can be unit-tested against a stub
+ * without a live backend.
+ */
+export type FetchLike = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string | FormData;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    statusText: string;
+    text: () => Promise<string>;
+}>;
+export interface TaskflowClientOptions {
+    /** Base server URL, e.g. `http://localhost:8000` (trailing slash trimmed). */
+    server: string;
+    /** The profile's raw `tfk_…` key. */
+    key: string;
+    /** Injectable fetch (defaults to the global `fetch`). */
+    fetchImpl?: FetchLike;
+    /** Per-request timeout in ms (default 15000). */
+    timeoutMs?: number;
+}
+/** An error carrying the backend's status + parsed detail. */
+export declare class TaskflowApiError extends Error {
+    readonly status: number;
+    readonly detail: string;
+    readonly method: string;
+    readonly path: string;
+    constructor(method: string, path: string, status: number, detail: string);
+}
+export interface Whoami {
+    agent_id: number;
+    display_name: string;
+    identifier: string;
+    project: number;
+    status: string;
+}
+export interface ChannelSummary {
+    id: number;
+    title: string;
+    kind: string;
+    topic: string | null;
+}
+export interface AgentSummary {
+    id: number;
+    display_name: string;
+    identifier: string;
+    status: string;
+    last_seen_at: string | null;
+}
+export interface MessagesPage {
+    messages: unknown[];
+    read_cursor: number | null;
+    /** Size of this page — with `unread: true`, the number of unread messages. */
+    unread_count?: number;
+}
+export interface SessionRow {
+    id: number;
+    session_identifier: string;
+    status: string;
+    [key: string]: unknown;
+}
+export interface SendMessageInput {
+    channel: number;
+    body_markdown: string;
+    priority?: string;
+    client_nonce?: string;
+    /** Resolved by `resolveAttachments`; switches the POST to multipart. */
+    attachments?: {
+        filename: string;
+        bytes: Buffer;
+    }[];
+}
+export interface CreateTaskInput {
+    title: string;
+    description_markdown?: string;
+    priority?: string;
+    notes_markdown?: string;
+    claim?: boolean;
+}
+/**
+ * Fields of a task that an agent may edit. Every one is optional: what is
+ * absent is left alone rather than blanked.
+ *
+ * Status, assignment and project are deliberately NOT here — they move through
+ * `updateTaskStatus` and `claimTask`, and the project is derived from the
+ * credential and never accepted from a caller.
+ */
+export interface UpdateTaskInput {
+    title?: string;
+    description_markdown?: string;
+    notes_markdown?: string;
+    priority?: string;
+}
+export interface RegisterSessionInput {
+    session_identifier: string;
+    host?: string;
+    pid?: number;
+    cwd?: string;
+    transport?: string;
+}
+export interface FrameInput {
+    content: string;
+    stream?: string;
+    task?: number;
+}
+export interface ActivityEventInput {
+    action: string;
+    body_markdown?: string;
+    metadata_json?: string;
+    task?: number;
+    /** Also mirror this event to the task's linked GitHub issue (opt-in, best-effort). */
+    post_to_github?: boolean;
+}
+export declare class TaskflowClient {
+    private readonly server;
+    private readonly key;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(options: TaskflowClientOptions);
+    private request;
+    /** `GET /agents/whoami` — the identity behind the presented credential. */
+    whoami(): Promise<Whoami>;
+    /** `GET /agents/tasks?status=&assigned=` — tasks in the agent's project. */
+    listTasks(params?: {
+        status?: string;
+        assigned?: string;
+    }): Promise<unknown[]>;
+    /** `GET /agents/channels` — channels the agent may see. */
+    listChannels(): Promise<ChannelSummary[]>;
+    /** `GET /agents/agents` — the other agents in the caller's project. */
+    listAgents(): Promise<AgentSummary[]>;
+    /** `GET /agents/messages?channel=&since=&limit=` → `{ messages, read_cursor }`. */
+    listMessages(params: {
+        channel: number;
+        since?: number;
+        limit?: number;
+        /** Only messages past this agent's read cursor. */
+        unread?: boolean;
+    }): Promise<MessagesPage>;
+    /** `GET /agents/activity?task=&limit=` — recent activity, newest first. */
+    listActivity(params?: {
+        task?: number;
+        limit?: number;
+    }): Promise<unknown[]>;
+    /** `POST /agents/agent/messages` — speak as this agent in a channel. */
+    sendMessage(input: SendMessageInput): Promise<unknown>;
+    /** `POST /channels/{id}/agent/read` — advance this agent's read cursor. */
+    markRead(channel: number, lastReadMessage: number): Promise<unknown>;
+    /** `POST /agents/tasks` — author a task in the agent's project (optionally claim). */
+    createTask(input: CreateTaskInput): Promise<unknown>;
+    /**
+     * `POST /agents/tasks/{id}` — edit a task's content.
+     *
+     * Only the fields present in `input` are sent, and the server writes only what
+     * it receives: a partial edit must not blank what it does not mention, which
+     * is the difference between an edit and an overwrite.
+     */
+    updateTask(task: number, input: UpdateTaskInput): Promise<unknown>;
+    /** `POST /agents/tasks/{id}/attachments` — hang files on a task (multipart). */
+    uploadTaskAttachments(task: number, attachments: {
+        filename: string;
+        bytes: Buffer;
+    }[]): Promise<unknown>;
+    /** `POST /agents/tasks/{id}/status` — advance a task's status. */
+    updateTaskStatus(task: number, status: string): Promise<unknown>;
+    /** `POST /agents/tasks/{id}/claim` — self-assign a task. */
+    claimTask(task: number): Promise<unknown>;
+    /** `POST /tasks/{id}/agent/review` — record a review verdict as this agent. */
+    reportReview(task: number, decision: string, bodyMarkdown?: string): Promise<unknown>;
+    /** `POST /agents/sessions` — register or reconnect a live session. */
+    registerSession(input: RegisterSessionInput): Promise<SessionRow>;
+    /** `POST /agents/sessions/{id}/heartbeat` — bump liveness (status hint idle/busy). */
+    heartbeat(session: number, status?: string): Promise<SessionRow>;
+    /** `POST /agents/sessions/{id}/frames` — append one terminal frame. */
+    appendFrame(session: number, frame: FrameInput): Promise<unknown>;
+    /** `POST /agents/sessions/{id}/frames` — append a batch of terminal frames. */
+    appendFrames(session: number, frames: FrameInput[]): Promise<unknown>;
+    /** `POST /agents/sessions/{id}/close` — disconnect a session. */
+    closeSession(session: number): Promise<SessionRow>;
+    /** `POST /agents/activity` — log one real activity event. */
+    logActivity(event: ActivityEventInput): Promise<{
+        created: number;
+    }>;
+    /** `POST /agents/activity` — log a batch of activity events. */
+    logActivityBatch(events: ActivityEventInput[]): Promise<{
+        created: number;
+    }>;
+}
+/**
+ * Pull a human message out of an error response body: prefer a JSON `detail`
+ * (the backend's convention) or `error`, else the raw text, else the status
+ * line. Kept resilient — a malformed body must never mask the real failure.
+ */
+export declare function extractDetail(raw: string, statusText: string): string;

package/dist/client.js

@@ -0,0 +1,279 @@
+/**
+ * A small typed HTTP client for the TaskFlow backend's agent-authed API.
+ *
+ * One method per endpoint in the agent surface (Stages 1–6). Every request is
+ * authenticated with the profile key via `Authorization: Agent <key>`; the base
+ * URL is the resolved profile's `server`. A non-2xx response is turned into a
+ * thrown {@link TaskflowApiError} carrying the backend's `detail`/text so the
+ * MCP tool (or hook) surfaces a real reason, never a bare status.
+ *
+ * `fetchImpl` is injectable so the client can be unit-tested against a stub
+ * without a live backend.
+ */
+/** An error carrying the backend's status + parsed detail. */
+export class TaskflowApiError extends Error {
+    status;
+    detail;
+    method;
+    path;
+    constructor(method, path, status, detail) {
+        super(`${method} ${path} → ${status}: ${detail}`);
+        this.name = "TaskflowApiError";
+        this.status = status;
+        this.detail = detail;
+        this.method = method;
+        this.path = path;
+    }
+}
+const API_PREFIX = "/api/taskflow";
+export class TaskflowClient {
+    server;
+    key;
+    fetchImpl;
+    timeoutMs;
+    constructor(options) {
+        this.server = options.server.replace(/\/+$/, "");
+        this.key = options.key;
+        const globalFetch = globalThis.fetch;
+        const impl = options.fetchImpl ?? globalFetch;
+        if (!impl) {
+            throw new Error("No fetch implementation available (Node >=18 or pass fetchImpl).");
+        }
+        this.fetchImpl = impl;
+        this.timeoutMs = options.timeoutMs ?? 15000;
+    }
+    // ---- core request helper -------------------------------------------------
+    async request(method, path, options = {}) {
+        let url = `${this.server}${path}`;
+        if (options.query) {
+            const params = new URLSearchParams();
+            for (const [k, v] of Object.entries(options.query)) {
+                if (v !== undefined && v !== null && v !== "") {
+                    params.set(k, String(v));
+                }
+            }
+            const qs = params.toString();
+            if (qs)
+                url += `?${qs}`;
+        }
+        const headers = {
+            Authorization: `Agent ${this.key}`,
+            Accept: "application/json",
+        };
+        const init = { method, headers };
+        if (options.form !== undefined) {
+            // Deliberately no Content-Type: fetch must set it to supply the
+            // multipart boundary. Setting it here produces a body the server
+            // cannot parse.
+            init.body = options.form;
+        }
+        else if (options.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            init.body = JSON.stringify(options.body);
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? this.timeoutMs);
+        init.signal = controller.signal;
+        let res;
+        try {
+            res = await this.fetchImpl(url, init);
+        }
+        catch (err) {
+            throw new TaskflowApiError(method, path, 0, `network error: ${err.message}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const raw = await res.text();
+        if (!res.ok) {
+            throw new TaskflowApiError(method, path, res.status, extractDetail(raw, res.statusText));
+        }
+        if (!raw) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            // A 2xx with a non-JSON body (e.g. the health string) — hand it back raw.
+            return raw;
+        }
+    }
+    // ---- READS ---------------------------------------------------------------
+    /** `GET /agents/whoami` — the identity behind the presented credential. */
+    whoami() {
+        return this.request("GET", `${API_PREFIX}/agents/whoami`);
+    }
+    /** `GET /agents/tasks?status=&assigned=` — tasks in the agent's project. */
+    listTasks(params = {}) {
+        return this.request("GET", `${API_PREFIX}/agents/tasks`, {
+            query: { status: params.status, assigned: params.assigned },
+        });
+    }
+    /** `GET /agents/channels` — channels the agent may see. */
+    listChannels() {
+        return this.request("GET", `${API_PREFIX}/agents/channels`);
+    }
+    /** `GET /agents/agents` — the other agents in the caller's project. */
+    listAgents() {
+        return this.request("GET", `${API_PREFIX}/agents/agents`);
+    }
+    /** `GET /agents/messages?channel=&since=&limit=` → `{ messages, read_cursor }`. */
+    listMessages(params) {
+        return this.request("GET", `${API_PREFIX}/agents/messages`, {
+            query: {
+                channel: params.channel,
+                since: params.since,
+                limit: params.limit,
+                unread: params.unread,
+            },
+        });
+    }
+    /** `GET /agents/activity?task=&limit=` — recent activity, newest first. */
+    listActivity(params = {}) {
+        return this.request("GET", `${API_PREFIX}/agents/activity`, {
+            query: { task: params.task, limit: params.limit },
+        });
+    }
+    // ---- WRITES: messages / read cursor --------------------------------------
+    /** `POST /agents/agent/messages` — speak as this agent in a channel. */
+    sendMessage(input) {
+        const { attachments, ...fields } = input;
+        if (!attachments?.length) {
+            return this.request("POST", `${API_PREFIX}/agents/agent/messages`, { body: fields });
+        }
+        const form = new FormData();
+        form.set("channel", String(fields.channel));
+        form.set("body_markdown", fields.body_markdown);
+        if (fields.priority)
+            form.set("priority", fields.priority);
+        if (fields.client_nonce)
+            form.set("client_nonce", fields.client_nonce);
+        for (const file of attachments) {
+            // The server treats a part as a file only when it carries a non-empty
+            // filename (views.rs:180-186), so the basename must be preserved.
+            form.append("files", new Blob([file.bytes]), file.filename);
+        }
+        // 25MB may not finish inside the default 15s.
+        return this.request("POST", `${API_PREFIX}/agents/agent/messages`, {
+            form,
+            timeoutMs: 120_000,
+        });
+    }
+    /** `POST /channels/{id}/agent/read` — advance this agent's read cursor. */
+    markRead(channel, lastReadMessage) {
+        return this.request("POST", `${API_PREFIX}/channels/${channel}/agent/read`, {
+            body: { last_read_message: lastReadMessage },
+        });
+    }
+    // ---- WRITES: tasks -------------------------------------------------------
+    /** `POST /agents/tasks` — author a task in the agent's project (optionally claim). */
+    createTask(input) {
+        return this.request("POST", `${API_PREFIX}/agents/tasks`, { body: input });
+    }
+    /**
+     * `POST /agents/tasks/{id}` — edit a task's content.
+     *
+     * Only the fields present in `input` are sent, and the server writes only what
+     * it receives: a partial edit must not blank what it does not mention, which
+     * is the difference between an edit and an overwrite.
+     */
+    updateTask(task, input) {
+        return this.request("POST", `${API_PREFIX}/agents/tasks/${task}`, { body: input });
+    }
+    /** `POST /agents/tasks/{id}/attachments` — hang files on a task (multipart). */
+    uploadTaskAttachments(task, attachments) {
+        const form = new FormData();
+        for (const file of attachments) {
+            // The server counts a part as a file only when it carries a non-empty
+            // filename, so the basename has to survive.
+            form.append("files", new Blob([file.bytes]), file.filename);
+        }
+        // 25MB may not finish inside the default 15s.
+        return this.request("POST", `${API_PREFIX}/agents/tasks/${task}/attachments`, {
+            form,
+            timeoutMs: 120_000,
+        });
+    }
+    /** `POST /agents/tasks/{id}/status` — advance a task's status. */
+    updateTaskStatus(task, status) {
+        return this.request("POST", `${API_PREFIX}/agents/tasks/${task}/status`, {
+            body: { status },
+        });
+    }
+    /** `POST /agents/tasks/{id}/claim` — self-assign a task. */
+    claimTask(task) {
+        return this.request("POST", `${API_PREFIX}/agents/tasks/${task}/claim`, { body: {} });
+    }
+    /** `POST /tasks/{id}/agent/review` — record a review verdict as this agent. */
+    reportReview(task, decision, bodyMarkdown) {
+        const body = { decision };
+        if (bodyMarkdown !== undefined)
+            body.body_markdown = bodyMarkdown;
+        return this.request("POST", `${API_PREFIX}/tasks/${task}/agent/review`, { body });
+    }
+    // ---- WRITES: sessions / frames / activity --------------------------------
+    /** `POST /agents/sessions` — register or reconnect a live session. */
+    registerSession(input) {
+        return this.request("POST", `${API_PREFIX}/agents/sessions`, { body: input });
+    }
+    /** `POST /agents/sessions/{id}/heartbeat` — bump liveness (status hint idle/busy). */
+    heartbeat(session, status) {
+        const body = {};
+        if (status !== undefined)
+            body.status = status;
+        return this.request("POST", `${API_PREFIX}/agents/sessions/${session}/heartbeat`, { body });
+    }
+    /** `POST /agents/sessions/{id}/frames` — append one terminal frame. */
+    appendFrame(session, frame) {
+        return this.request("POST", `${API_PREFIX}/agents/sessions/${session}/frames`, {
+            body: frame,
+        });
+    }
+    /** `POST /agents/sessions/{id}/frames` — append a batch of terminal frames. */
+    appendFrames(session, frames) {
+        return this.request("POST", `${API_PREFIX}/agents/sessions/${session}/frames`, {
+            body: { frames },
+        });
+    }
+    /** `POST /agents/sessions/{id}/close` — disconnect a session. */
+    closeSession(session) {
+        return this.request("POST", `${API_PREFIX}/agents/sessions/${session}/close`, { body: {} });
+    }
+    /** `POST /agents/activity` — log one real activity event. */
+    logActivity(event) {
+        return this.request("POST", `${API_PREFIX}/agents/activity`, { body: event });
+    }
+    /** `POST /agents/activity` — log a batch of activity events. */
+    logActivityBatch(events) {
+        return this.request("POST", `${API_PREFIX}/agents/activity`, { body: { events } });
+    }
+}
+/**
+ * Pull a human message out of an error response body: prefer a JSON `detail`
+ * (the backend's convention) or `error`, else the raw text, else the status
+ * line. Kept resilient — a malformed body must never mask the real failure.
+ */
+export function extractDetail(raw, statusText) {
+    const trimmed = raw.trim();
+    if (trimmed) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed.detail === "string")
+                return parsed.detail;
+            if (typeof parsed.error === "string")
+                return parsed.error;
+            // Field-error envelope (e.g. { user: ["…"] }) — surface the first message.
+            for (const value of Object.values(parsed)) {
+                if (Array.isArray(value) && typeof value[0] === "string")
+                    return value[0];
+            }
+            return trimmed;
+        }
+        catch {
+            return trimmed;
+        }
+    }
+    return statusText || "request failed";
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA4BH,8DAA8D;AAC9D,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,MAAM,CAAS;IACf,MAAM,CAAS;IACf,MAAM,CAAS;IACf,IAAI,CAAS;IACtB,YAAY,MAAc,EAAE,IAAY,EAAE,MAAc,EAAE,MAAc;QACtE,KAAK,CAAC,GAAG,MAAM,IAAI,IAAI,MAAM,MAAM,KAAK,MAAM,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAWD,MAAM,UAAU,GAAG,eAAe,CAAC;AAgGnC,MAAM,OAAO,cAAc;IACR,MAAM,CAAS;IACf,GAAG,CAAS;IACZ,SAAS,CAAY;IACrB,SAAS,CAAS;IAEnC,YAAY,OAA8B;QACxC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACjD,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;QACvB,MAAM,WAAW,GAAI,UAAoC,CAAC,KAAK,CAAC;QAChE,MAAM,IAAI,GAAG,OAAO,CAAC,SAAS,IAAI,WAAW,CAAC;QAC9C,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAC;QACtF,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;IAC9C,CAAC;IAED,6EAA6E;IAErE,KAAK,CAAC,OAAO,CACnB,MAAc,EACd,IAAY,EACZ,UAA0B,EAAE;QAE5B,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;QAClC,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;YACrC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACnD,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC;oBAC9C,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC3B,CAAC;YACH,CAAC;YACD,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;YAC7B,IAAI,EAAE;gBAAE,GAAG,IAAI,IAAI,EAAE,EAAE,CAAC;QAC1B,CAAC;QAED,MAAM,OAAO,GAA2B;YACtC,aAAa,EAAE,SAAS,IAAI,CAAC,GAAG,EAAE;YAClC,MAAM,EAAE,kBAAkB;SAC3B,CAAC;QACF,MAAM,IAAI,GAA6B,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QAC3D,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC/B,gEAAgE;YAChE,iEAAiE;YACjE,gBAAgB;YAChB,IAAK,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QAC5B,CAAC;aAAM,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YACtC,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;YAC7C,IAAK,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC5C,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CACtB,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EACxB,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,CACpC,CAAC;QACF,IAAK,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;QAEjC,IAAI,GAAmC,CAAC;QACxC,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACxC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,gBAAgB,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,kBAAmB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAC1F,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC7B,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,gBAAgB,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;QAC3F,CAAC;QACD,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO,SAAc,CAAC;QACxB,CAAC;QACD,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAM,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,0EAA0E;YAC1E,OAAO,GAAmB,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,6EAA6E;IAE7E,2EAA2E;IAC3E,MAAM;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,UAAU,gBAAgB,CAAC,CAAC;IAC5D,CAAC;IAED,4EAA4E;IAC5E,SAAS,CAAC,SAAiD,EAAE;QAC3D,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,UAAU,eAAe,EAAE;YACvD,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE;SAC5D,CAAC,CAAC;IACL,CAAC;IAED,2DAA2D;IAC3D,YAAY;QACV,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,UAAU,kBAAkB,CAAC,CAAC;IAC9D,CAAC;IAED,uEAAuE;IACvE,UAAU;QACR,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,UAAU,gBAAgB,CAAC,CAAC;IAC5D,CAAC;IAED,mFAAmF;IACnF,YAAY,CAAC,MAMZ;QACC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,UAAU,kBAAkB,EAAE;YAC1D,KAAK,EAAE;gBACL,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,MAAM,EAAE,MAAM,CAAC,MAAM;aACtB;SACF,CAAC,CAAC;IACL,CAAC;IAED,2EAA2E;IAC3E,YAAY,CAAC,SAA4C,EAAE;QACzD,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,UAAU,kBAAkB,EAAE;YAC1D,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE;SAClD,CAAC,CAAC;IACL,CAAC;IAED,6EAA6E;IAE7E,wEAAwE;IACxE,WAAW,CAAC,KAAuB;QACjC,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,EAAE,GAAG,KAAK,CAAC;QACzC,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,UAAU,wBAAwB,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QACvF,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;QAC5C,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;QAChD,IAAI,MAAM,CAAC,QAAQ;YAAE,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC3D,IAAI,MAAM,CAAC,YAAY;YAAE,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;QACvE,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;YAC/B,sEAAsE;YACtE,kEAAkE;YAClE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9D,CAAC;QAED,8CAA8C;QAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,UAAU,wBAAwB,EAAE;YACjE,IAAI;YACJ,SAAS,EAAE,OAAO;SACnB,CAAC,CAAC;IACL,CAAC;IAED,2EAA2E;IAC3E,QAAQ,CAAC,OAAe,EAAE,eAAuB;QAC/C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,UAAU,aAAa,OAAO,aAAa,EAAE;YAC1E,IAAI,EAAE,EAAE,iBAAiB,EAAE,eAAe,EAAE;SAC7C,CAAC,CAAC;IACL,CAAC;IAED,6EAA6E;IAE7E,sFAAsF;IACtF,UAAU,CAAC,KAAsB;QAC/B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,UAAU,eAAe,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7E,CAAC;IAED;;;;;;OAMG;IACH,UAAU,CAAC,IAAY,EAAE,KAAsB;QAC7C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,UAAU,iBAAiB,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACrF,CAAC;IAED,gFAAgF;IAChF,qBAAqB,CACnB,IAAY,EACZ,WAAkD;QAElD,MAAM,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC5B,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;YAC/B,sEAAsE;YACtE,4CAA4C;YAC5C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9D,CAAC;QACD,8CAA8C;QAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,UAAU,iBAAiB,IAAI,cAAc,EAAE;YAC5E,IAAI;YACJ,SAAS,EAAE,OAAO;SACnB,CAAC,CAAC;IACL,CAAC;IAED,kEAAkE;IAClE,gBAAgB,CAAC,IAAY,EAAE,MAAc;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,UAAU,iBAAiB,IAAI,SAAS,EAAE;YACvE,IAAI,EAAE,EAAE,MAAM,EAAE;SACjB,CAAC,CAAC;IACL,CAAC;IAED,4DAA4D;IAC5D,SAAS,CAAC,IAAY;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,UAAU,iBAAiB,IAAI,QAAQ,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IACxF,CAAC;IAED,+EAA+E;IAC/E,YAAY,CAAC,IAAY,EAAE,QAAgB,EAAE,YAAqB;QAChE,MAAM,IAAI,GAAiD,EAAE,QAAQ,EAAE,CAAC;QACxE,IAAI,YAAY,KAAK,SAAS;YAAE,IAAI,CAAC,aAAa,GAAG,YAAY,CAAC;QAClE,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,UAAU,UAAU,IAAI,eAAe,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IACpF,CAAC;IAED,6EAA6E;IAE7E,sEAAsE;IACtE,eAAe,CAAC,KAA2B;QACzC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,UAAU,kBAAkB,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAChF,CAAC;IAED,sFAAsF;IACtF,SAAS,CAAC,OAAe,EAAE,MAAe;QACxC,MAAM,IAAI,GAAwB,EAAE,CAAC;QACrC,IAAI,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAC/C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,UAAU,oBAAoB,OAAO,YAAY,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9F,CAAC;IAED,uEAAuE;IACvE,WAAW,CAAC,OAAe,EAAE,KAAiB;QAC5C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,UAAU,oBAAoB,OAAO,SAAS,EAAE;YAC7E,IAAI,EAAE,KAAK;SACZ,CAAC,CAAC;IACL,CAAC;IAED,+EAA+E;IAC/E,YAAY,CAAC,OAAe,EAAE,MAAoB;QAChD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,UAAU,oBAAoB,OAAO,SAAS,EAAE;YAC7E,IAAI,EAAE,EAAE,MAAM,EAAE;SACjB,CAAC,CAAC;IACL,CAAC;IAED,iEAAiE;IACjE,YAAY,CAAC,OAAe;QAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,UAAU,oBAAoB,OAAO,QAAQ,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IAC9F,CAAC;IAED,6DAA6D;IAC7D,WAAW,CAAC,KAAyB;QACnC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,UAAU,kBAAkB,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAChF,CAAC;IAED,gEAAgE;IAChE,gBAAgB,CAAC,MAA4B;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,UAAU,kBAAkB,EAAE,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;IACrF,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,UAAkB;IAC3D,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,OAAO,EAAE,CAAC;QACZ,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAA4B,CAAC;YAC9D,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ;gBAAE,OAAO,MAAM,CAAC,MAAM,CAAC;YAC5D,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ;gBAAE,OAAO,MAAM,CAAC,KAAK,CAAC;YAC1D,2EAA2E;YAC3E,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC1C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ;oBAAE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;YAC5E,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IACD,OAAO,UAAU,IAAI,gBAAgB,CAAC;AACxC,CAAC"}