sfora-cli 0.16.0 → 0.17.0

package/README.md

@@ -400,6 +400,24 @@ Reads outside `projects/<slug>/(posts|drafts)`, `inbox/mentions.md`, and
 `me/api-key` return `ENOENT`; writes outside the post/draft dirs return `EACCES`.
 ```
 
+## Attachments — `sfora attachments`
+
+A post's screenshots and files are listed in its frontmatter by `cat`, as one JSON
+line: `attachments: [{"id","name","type","size"}]`. To get the files:
+
+```bash
+sfora attachments /projects/acme/posts/2026-10-06-errors.md               # list them
+sfora attachments /projects/acme/posts/2026-10-06-errors.md --out ./shots # write them
+```
+
+`--out` writes each file under its own name (only the last path segment is
+kept, and clashes become `shot-2.png`). It checks each file's type and size
+against the list and prints one local path per line, so an agent can open the
+images. A file over 20 MB, or one that doesn't match the list, is skipped with a
+line on stderr, and the command exits 1. Inside the shell, `attachments <post>`
+lists only. Over MCP, the `attachments` and `attachment` tools return images as
+image content.
+
 ## macOS and shared local operations
 
 The desktop app and npm CLI use the same Node-only `sfora-cli/local-core`

package/dist/agent-webhook.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `sfora agent webhook <name> --url <address> --events <a,b> | --clear`
+ * (card #811, the CLI follow-up). Sets an agent's webhook with YOUR key, under
+ * the same rule as Settings → Agents: the agent's owner or a workspace
+ * owner/admin. An agent's key is refused by the server (an agent never sets a
+ * webhook). Pure: a client in, the text and the exit code out.
+ */
+import type { SforaApiClient } from "./api-client.js";
+import type { CommandOutput } from "./block-commands.js";
+/** Every event the webhook fan-out emits; the server's list (convex/lib/webhookEvents.ts). */
+export declare const WEBHOOK_EVENTS: readonly ["message.created", "mention", "post.created", "post.commented"];
+export declare const AGENT_WEBHOOK_USAGE = "usage: sfora agent webhook <name> [--url <https://\u2026>] [--events <a,b>] | --clear [--json]";
+type WebhookClient = Pick<SforaApiClient, "setAgentWebhook">;
+export declare function agentWebhookCommand(client: WebhookClient, rest: string[], opts: {
+    webhookUrl?: string;
+    events?: string;
+    clear?: boolean;
+    json?: boolean;
+}): Promise<CommandOutput>;
+export {};

package/dist/agent-webhook.js

@@ -0,0 +1,42 @@
+/** Every event the webhook fan-out emits; the server's list (convex/lib/webhookEvents.ts). */
+export const WEBHOOK_EVENTS = ["message.created", "mention", "post.created", "post.commented"];
+export const AGENT_WEBHOOK_USAGE = "usage: sfora agent webhook <name> [--url <https://…>] [--events <a,b>] | --clear [--json]";
+export async function agentWebhookCommand(client, rest, opts) {
+    const fail = (message, exitCode = 1) => ({ stdout: "", stderr: `${message}\n`, exitCode });
+    const [sub, name] = rest;
+    if (sub !== "webhook" || !name)
+        return fail(AGENT_WEBHOOK_USAGE, 2);
+    if (opts.clear && (opts.webhookUrl !== undefined || opts.events !== undefined)) {
+        return fail("--clear removes the webhook; give it alone", 2);
+    }
+    if (!opts.clear && opts.webhookUrl === undefined && opts.events === undefined) {
+        return fail(`nothing to change — give --url, --events or --clear\n${AGENT_WEBHOOK_USAGE}`, 2);
+    }
+    let events;
+    if (opts.events !== undefined) {
+        events = opts.events.split(",").map((e) => e.trim()).filter(Boolean);
+        const unknown = events.filter((e) => !WEBHOOK_EVENTS.includes(e));
+        if (unknown.length)
+            return fail(`unknown event ${unknown.join(", ")} — use one of: ${WEBHOOK_EVENTS.join(", ")}`, 2);
+    }
+    let result;
+    try {
+        result = await client.setAgentWebhook(name, opts.clear ? { clear: true } : { ...(opts.webhookUrl !== undefined ? { url: opts.webhookUrl } : {}), ...(events ? { events } : {}) });
+    }
+    catch (e) {
+        // The server's refusal as it said it: not a person, not yours, no such agent.
+        return fail(e instanceof Error ? e.message : String(e));
+    }
+    if (opts.json)
+        return { stdout: `${JSON.stringify(result, null, 2)}\n`, stderr: "", exitCode: 0 };
+    const evts = result.events.length ? result.events.join(", ") : "none";
+    return {
+        stdout: result.webhookUrl
+            ? `✓ ${result.agent}'s webhook: ${result.webhookUrl} · events: ${evts}\n`
+            : opts.clear
+                ? `✓ ${result.agent}'s webhook removed\n`
+                : `✓ ${result.agent} has no webhook URL yet · events: ${evts} — add one with --url\n`,
+        stderr: "",
+        exitCode: 0,
+    };
+}

package/dist/api-client.d.ts

@@ -311,6 +311,13 @@ export interface SforaApiConfig {
      * The server sanitizes it and ignores it where it means nothing.
      */
     clientLabel?: string;
+    /**
+     * How the client is on the line (card #815, D11). The CLI's MCP server and
+     * the hosted /mcp route pass "mcp", sent as `X-Sfora-Transport: mcp` beside
+     * the client label, so usage can tell an MCP tool call from a terminal
+     * command. Omitted, no header is sent — the CLI's own requests.
+     */
+    transport?: "mcp";
 }
 /** Non-2xx response from the fs API. Carries the HTTP status + machine code so SforaFs can map it to an errno. */
 export declare class SforaApiError extends Error {
@@ -341,6 +348,32 @@ export interface BlockView {
     lang?: string;
 }
 /** `GET …?view=blocks` — the addressable view of a document. */
+/** The `_backlinks` door's answer — see `readBacklinks`. */
+export interface BacklinksView {
+    target: {
+        kind: string;
+        id: string;
+        title: string;
+    };
+    truncated: boolean;
+    backlinks: Array<{
+        kind: string;
+        title: string;
+        token: string | null;
+        url: string | null;
+        anchors: string[];
+    }>;
+}
+/** One file attached to a post — `GET <post>/attachments` (card #822). */
+export interface AttachmentRow {
+    id: string;
+    name: string;
+    /** The media type the uploader's browser reported. */
+    type: string;
+    size: number;
+    width?: number;
+    height?: number;
+}
 export interface BlocksView {
     /** The fs path these blocks are OF — what to GET for the document itself. */
     canonical: string;
@@ -451,6 +484,26 @@ export declare class SforaApiClient {
      * `/v1/fs` URL: the CLI does not build routes.
      */
     readBlocks(fsPath: string): Promise<BlocksView>;
+    /**
+     * `GET <fs path>/_backlinks` — what links to a doc, post or task, as the
+     * agent may see it (card #682): each source with the `[[…]]` token to paste
+     * and the anchors it links to.
+     */
+    readBacklinks(fsPath: string): Promise<BacklinksView>;
+    /**
+     * `GET <post path>/attachments` — the files attached to a post (card #822).
+     * The path is the post's fs path, as for every other door here.
+     */
+    listAttachments(fsPath: string): Promise<AttachmentRow[]>;
+    /**
+     * `GET <post path>/attachments/<id>` — one file's bytes, streamed through the
+     * API with this key (no storage URL is ever handed out). `type` is the
+     * served Content-Type, so a caller can hold it against the listing.
+     */
+    downloadAttachment(fsPath: string, id: string): Promise<{
+        bytes: Uint8Array;
+        type: string;
+    }>;
     /**
      * `PUT <fs path>` — the generic write door, so the CLI can put to any path
      * (and to a single block of it) without a per-entity method.
@@ -613,6 +666,19 @@ export declare class SforaApiClient {
         joined: boolean;
         already: boolean;
     }>;
+    /**
+     * `PUT /v1/agents/:name/webhook` (card #811) — set or clear an agent's
+     * webhook with a PERSON's key, under the same rule as Settings.
+     */
+    setAgentWebhook(name: string, body: {
+        url?: string;
+        events?: string[];
+        clear?: boolean;
+    }): Promise<{
+        agent: string;
+        webhookUrl: string | null;
+        events: string[];
+    }>;
     /** `GET /api/rooms/:id/messages` — history, newest first (server cap: 100). */
     listRoomMessages(roomId: string, limit?: number): Promise<MessagesPage>;
     /** `POST /api/rooms/:id/messages` with `{ body }` — send markdown. */
@@ -621,6 +687,21 @@ export declare class SforaApiClient {
     client?: string): Promise<{
         messageId: string;
     }>;
+    /**
+     * `POST /api/rooms/:id/typing` with `{ ttlSeconds? }` — say this agent is
+     * working on a reply in the room (card #668). The server clamps the expiry
+     * to 5–120 s (default 30); send again to extend. `{ stop: true }` is the
+     * `DELETE` that ends it; sending a message in the room also ends it.
+     * Agents only, in a room they are a member of.
+     */
+    typing(roomId: string, opts?: {
+        ttlSeconds?: number;
+    } | {
+        stop: true;
+    }): Promise<{
+        typing: boolean;
+        until?: number;
+    }>;
     /**
      * `POST /api/presence` with `{ roomId?, client? }` — one presence beat.
      *
@@ -652,6 +733,22 @@ export declare class SforaApiClient {
     }): Promise<{
         askId: string;
     }>;
+    /**
+     * `POST /api/asks/:askId/claim` — take an open ask atomically. A 409 means
+     * someone else holds it (their name is in the message) or it is no longer
+     * open; the server owns that race, this only carries the answer.
+     */
+    claimAsk(askId: string): Promise<{
+        ok: boolean;
+        askId: string;
+        state: string;
+    }>;
+    /** `POST /api/asks/:askId/resolve` with `{ resolution? }` — report it done. */
+    resolveAsk(askId: string, resolution?: string): Promise<{
+        ok: boolean;
+        askId: string;
+        state: string;
+    }>;
     /** `GET /v1/fs/inbox/mentions.md` — markdown summary of unread mentions. */
     readInbox(): Promise<string>;
     /** `GET /v1/fs/me/api-key` — text identity (no key material). */

package/dist/api-client.js

@@ -96,6 +96,7 @@ export class SforaApiClient {
     #apiKey;
     #actAs;
     #clientLabel;
+    #transport;
     /**
      * What the LAST response said about itself, beyond the data it carried.
      *
@@ -116,6 +117,7 @@ export class SforaApiClient {
         this.#apiKey = config.apiKey;
         this.#actAs = config.actAs;
         this.#clientLabel = config.clientLabel;
+        this.#transport = config.transport;
     }
     /** What the last response said about itself, consumed. */
     takeResponseInfo() {
@@ -158,6 +160,8 @@ export class SforaApiClient {
             headers["X-Sfora-Act-As"] = this.#actAs;
         if (this.#clientLabel)
             headers["X-Sfora-Client"] = this.#clientLabel;
+        if (this.#transport)
+            headers["X-Sfora-Transport"] = this.#transport;
         if (body !== undefined)
             headers["Content-Type"] = contentType;
         let res;
@@ -310,6 +314,34 @@ export class SforaApiClient {
     async readBlocks(fsPath) {
         return this.#json(`${fsRequestPath(fsPath)}?view=blocks`);
     }
+    /**
+     * `GET <fs path>/_backlinks` — what links to a doc, post or task, as the
+     * agent may see it (card #682): each source with the `[[…]]` token to paste
+     * and the anchors it links to.
+     */
+    async readBacklinks(fsPath) {
+        return this.#json(`${fsRequestPath(fsPath.replace(/\/+$/, ""))}/_backlinks`);
+    }
+    /**
+     * `GET <post path>/attachments` — the files attached to a post (card #822).
+     * The path is the post's fs path, as for every other door here.
+     */
+    async listAttachments(fsPath) {
+        const data = await this.#json(`${fsRequestPath(fsPath.replace(/\/+$/, ""))}/attachments`);
+        return data.attachments;
+    }
+    /**
+     * `GET <post path>/attachments/<id>` — one file's bytes, streamed through the
+     * API with this key (no storage URL is ever handed out). `type` is the
+     * served Content-Type, so a caller can hold it against the listing.
+     */
+    async downloadAttachment(fsPath, id) {
+        const res = await this.#request("GET", `${fsRequestPath(fsPath.replace(/\/+$/, ""))}/attachments/${encodeURIComponent(id)}`);
+        return {
+            bytes: new Uint8Array(await res.arrayBuffer()),
+            type: res.headers.get("content-type") ?? "",
+        };
+    }
     /**
      * `PUT <fs path>` — the generic write door, so the CLI can put to any path
      * (and to a single block of it) without a per-entity method.
@@ -614,6 +646,14 @@ export class SforaApiClient {
         const res = await this.#request("POST", `/api/rooms/${encodeURIComponent(roomId)}/join`);
         return this.#jsonFrom(res);
     }
+    /**
+     * `PUT /v1/agents/:name/webhook` (card #811) — set or clear an agent's
+     * webhook with a PERSON's key, under the same rule as Settings.
+     */
+    async setAgentWebhook(name, body) {
+        const res = await this.#request("PUT", `/v1/agents/${encodeURIComponent(name)}/webhook`, JSON.stringify(body), undefined, "application/json");
+        return this.#jsonFrom(res);
+    }
     /** `GET /api/rooms/:id/messages` — history, newest first (server cap: 100). */
     async listRoomMessages(roomId, limit = 30) {
         return this.#json(`/api/rooms/${encodeURIComponent(roomId)}/messages?limit=${limit}`);
@@ -627,6 +667,20 @@ export class SforaApiClient {
         const res = await this.#request("POST", `/api/rooms/${encodeURIComponent(roomId)}/messages`, JSON.stringify({ body, client }), undefined, "application/json");
         return this.#jsonFrom(res);
     }
+    /**
+     * `POST /api/rooms/:id/typing` with `{ ttlSeconds? }` — say this agent is
+     * working on a reply in the room (card #668). The server clamps the expiry
+     * to 5–120 s (default 30); send again to extend. `{ stop: true }` is the
+     * `DELETE` that ends it; sending a message in the room also ends it.
+     * Agents only, in a room they are a member of.
+     */
+    async typing(roomId, opts = {}) {
+        const path = `/api/rooms/${encodeURIComponent(roomId)}/typing`;
+        const res = "stop" in opts
+            ? await this.#request("DELETE", path)
+            : await this.#request("POST", path, JSON.stringify(opts.ttlSeconds !== undefined ? { ttlSeconds: opts.ttlSeconds } : {}), undefined, "application/json");
+        return this.#jsonFrom(res);
+    }
     /**
      * `POST /api/presence` with `{ roomId?, client? }` — one presence beat.
      *
@@ -658,6 +712,20 @@ export class SforaApiClient {
         const res = await this.#request("POST", "/api/asks", JSON.stringify(body), undefined, "application/json");
         return this.#jsonFrom(res);
     }
+    /**
+     * `POST /api/asks/:askId/claim` — take an open ask atomically. A 409 means
+     * someone else holds it (their name is in the message) or it is no longer
+     * open; the server owns that race, this only carries the answer.
+     */
+    async claimAsk(askId) {
+        const res = await this.#request("POST", `/api/asks/${encodeURIComponent(askId)}/claim`, "{}", undefined, "application/json");
+        return this.#jsonFrom(res);
+    }
+    /** `POST /api/asks/:askId/resolve` with `{ resolution? }` — report it done. */
+    async resolveAsk(askId, resolution) {
+        const res = await this.#request("POST", `/api/asks/${encodeURIComponent(askId)}/resolve`, JSON.stringify(resolution !== undefined ? { resolution } : {}), undefined, "application/json");
+        return this.#jsonFrom(res);
+    }
     /** `GET /v1/fs/inbox/mentions.md` — markdown summary of unread mentions. */
     async readInbox() {
         return this.#text("/v1/fs/inbox/mentions.md");

package/dist/ask.d.ts

@@ -73,3 +73,54 @@ export type AskWaitResult = {
  * and other asks' traffic pass through silently.
  */
 export declare function askWaitLoop(deps: AskWaitDeps, options: AskWaitOptions): Promise<AskWaitResult>;
+export declare const ASK_ACTIONS: readonly ["claim", "resolve"];
+export type AskAction = (typeof ASK_ACTIONS)[number];
+export declare const ASK_ACTION_USAGE = "usage: sfora ask claim <ask-id> | sfora ask resolve <ask-id> [-m \"<resolution>\"] [--json]";
+/**
+ * `sfora ask claim <id>` / `sfora ask resolve <id>`, or `null` for a question.
+ *
+ * The same verb creates asks, so the subcommand is taken only when it cannot
+ * be a question: the first word is exactly `claim` or `resolve`, exactly one
+ * more word follows (the id), and no `--option` was given (a claim never has
+ * options, a question to pick from always does). `sfora ask "claim the
+ * domain?"` arrives as ONE word and stays a question; so does
+ * `sfora ask claim the domain`.
+ */
+export declare function parseAskAction(rest: string[], options?: string[]): {
+    action: AskAction;
+    askId: string;
+} | null;
+/**
+ * The words of a refusal. The `/api/asks` doors answer `{ "error": "<words>" }`
+ * (convex/http.ts errorResponse), which the client keeps as the raw body; this
+ * reads the words back out so the terminal says "Already claimed by Ada", not
+ * a JSON blob.
+ */
+export declare function refusalText(e: unknown): string;
+type AskActionClient = {
+    claimAsk(askId: string): Promise<{
+        askId?: string;
+        state?: string;
+    }>;
+    resolveAsk(askId: string, resolution?: string): Promise<{
+        askId?: string;
+        state?: string;
+    }>;
+};
+/**
+ * Claim or resolve one ask and say what happened in one line (or JSON).
+ *
+ * The server owns every rule: a 409 says someone else holds the ask (with
+ * their name), or that it is a question only a human answers, or that it is
+ * no longer open; a 403 says only the claimant may resolve it. Those come back
+ * as they were said, on stderr, exit 1.
+ */
+export declare function askActionCommand(client: AskActionClient, action: AskAction, askId: string, opts?: {
+    resolution?: string;
+    json?: boolean;
+}): Promise<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}>;
+export {};

package/dist/ask.js

@@ -117,3 +117,73 @@ export async function askWaitLoop(deps, options) {
     }
     return { outcome: "stopped" };
 }
+// ─── Claim and resolve (the coordination half) ───────────────────────
+export const ASK_ACTIONS = ["claim", "resolve"];
+export const ASK_ACTION_USAGE = 'usage: sfora ask claim <ask-id> | sfora ask resolve <ask-id> [-m "<resolution>"] [--json]';
+/**
+ * `sfora ask claim <id>` / `sfora ask resolve <id>`, or `null` for a question.
+ *
+ * The same verb creates asks, so the subcommand is taken only when it cannot
+ * be a question: the first word is exactly `claim` or `resolve`, exactly one
+ * more word follows (the id), and no `--option` was given (a claim never has
+ * options, a question to pick from always does). `sfora ask "claim the
+ * domain?"` arrives as ONE word and stays a question; so does
+ * `sfora ask claim the domain`.
+ */
+export function parseAskAction(rest, options = []) {
+    if (rest.length !== 2 || options.length > 0)
+        return null;
+    const [word, askId] = rest;
+    if (!ASK_ACTIONS.includes(word))
+        return null;
+    if (!askId.trim())
+        return null;
+    return { action: word, askId: askId.trim() };
+}
+/**
+ * The words of a refusal. The `/api/asks` doors answer `{ "error": "<words>" }`
+ * (convex/http.ts errorResponse), which the client keeps as the raw body; this
+ * reads the words back out so the terminal says "Already claimed by Ada", not
+ * a JSON blob.
+ */
+export function refusalText(e) {
+    const data = e?.data;
+    if (data && typeof data.message !== "string" && typeof data.error === "string")
+        return data.error;
+    return e instanceof Error ? e.message : String(e);
+}
+/**
+ * Claim or resolve one ask and say what happened in one line (or JSON).
+ *
+ * The server owns every rule: a 409 says someone else holds the ask (with
+ * their name), or that it is a question only a human answers, or that it is
+ * no longer open; a 403 says only the claimant may resolve it. Those come back
+ * as they were said, on stderr, exit 1.
+ */
+export async function askActionCommand(client, action, askId, opts = {}) {
+    if (action === "claim" && opts.resolution !== undefined) {
+        return { stdout: "", stderr: `-m is for resolve; claim takes only the id\n${ASK_ACTION_USAGE}\n`, exitCode: 2 };
+    }
+    let result;
+    try {
+        result =
+            action === "claim"
+                ? await client.claimAsk(askId)
+                : await client.resolveAsk(askId, opts.resolution);
+    }
+    catch (e) {
+        return { stdout: "", stderr: `could not ${action} ask ${askId}: ${refusalText(e)}\n`, exitCode: 1 };
+    }
+    const state = result.state ?? (action === "claim" ? "claimed" : "resolved");
+    if (opts.json) {
+        return {
+            stdout: `${JSON.stringify({ askId, state, ...(action === "resolve" && opts.resolution !== undefined ? { resolution: opts.resolution } : {}) })}\n`,
+            stderr: "",
+            exitCode: 0,
+        };
+    }
+    const line = action === "claim"
+        ? `✓ Claimed ask ${askId} — it's yours; run \`sfora ask resolve ${askId} -m "…"\` when done`
+        : `✓ Resolved ask ${askId}${opts.resolution ? ` · ${opts.resolution}` : ""}`;
+    return { stdout: `${line}\n`, stderr: "", exitCode: 0 };
+}

package/dist/attachments-node.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The disk `sfora attachments --out` writes to — the Node half of
+ * attachments.ts, kept apart so that module stays importable where there is
+ * no local filesystem (the hosted MCP route).
+ */
+import type { AttachmentIo } from "./attachments.js";
+export declare const nodeAttachmentIo: AttachmentIo;

package/dist/attachments-node.js

@@ -0,0 +1,15 @@
+/**
+ * The disk `sfora attachments --out` writes to — the Node half of
+ * attachments.ts, kept apart so that module stays importable where there is
+ * no local filesystem (the hosted MCP route).
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+export const nodeAttachmentIo = {
+    mkdir: async (dir) => {
+        await mkdir(dir, { recursive: true });
+    },
+    writeFile: (path, bytes) => writeFile(path, bytes),
+    // Absolute, so the printed path opens from anywhere.
+    join: (dir, name) => join(resolve(dir), name),
+};

package/dist/attachments.d.ts

@@ -0,0 +1,112 @@
+/**
+ * `attachments <post>` — the files a person attached to a post (card #822).
+ *
+ * Three doors, one module: the `sfora attachments` verb (list, or write the
+ * files with `--out`), the shell's `attachments` command (list only — the
+ * shell's fs is the workspace, not the disk), and the MCP tools' list and
+ * fetch, where an image comes back as image content a vision client can see.
+ *
+ * Every byte is fetched through the API with the caller's key; the server
+ * applies the post's own read rule, so nothing here decides access. What this
+ * module does decide is what lands on disk: a name that cannot leave the
+ * `--out` directory, and a file whose type and size match what was listed.
+ *
+ * No `node:` imports, so the hosted MCP route can import it; the CLI hands in
+ * the disk through {@link AttachmentIo} (see attachments-node.ts).
+ */
+import { type SforaApiClient } from "./api-client.js";
+import type { CommandOutput } from "./block-commands.js";
+/**
+ * The server's limit (Convex's HTTP response cap, checked against the stored
+ * size). Mirrored here so a listed file over it is skipped without a request.
+ */
+export declare const ATTACHMENT_MAX_BYTES: number;
+/** The two disk operations `--out` needs, injected so this module stays portable. */
+export interface AttachmentIo {
+    mkdir(dir: string): Promise<void>;
+    writeFile(path: string, bytes: Uint8Array): Promise<void>;
+    join(dir: string, name: string): string;
+}
+/**
+ * A file name that is safe to write inside one directory: the last path
+ * segment only (either separator), no control characters, no leading dots,
+ * and unique among the names already `taken` (`shot.png`, `shot-2.png`, …).
+ * An empty result falls back to `attachment-<id>`.
+ */
+export declare function safeAttachmentName(name: string, id: string, taken: Set<string>): string;
+/**
+ * `sfora attachments <post> [--out <dir>] [--json]`.
+ *
+ * Without `--out` it lists. With it, it writes each file into the directory
+ * and prints one local path per line (so an agent can open the images); a
+ * file that is too large, or does not match its listing, is skipped with a
+ * line on stderr and the command exits 1 after writing the rest.
+ */
+export declare function attachmentsCommand(client: SforaApiClient, fsPath: string, options?: {
+    out?: string;
+    json?: boolean;
+    io?: AttachmentIo;
+}): Promise<CommandOutput>;
+export type McpContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+export type McpToolResult = {
+    content: McpContent[];
+    isError: boolean;
+};
+/** The two tools both MCP servers list, so their schemas cannot drift. */
+export declare const ATTACHMENT_TOOLS: readonly [{
+    readonly name: "attachments";
+    readonly description: "List the files attached to a post (screenshots, documents). Pass the post's path, e.g. /projects/web/posts/2026-10-06-errors.md. Returns JSON rows { id, name, type, size }; fetch one with the `attachment` tool.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly path: {
+                readonly type: "string";
+                readonly description: "The post's absolute path under /projects/<slug>/posts/ (or drafts/).";
+            };
+        };
+        readonly required: readonly ["path"];
+    };
+}, {
+    readonly name: "attachment";
+    readonly description: "Fetch one attachment of a post by id (from the `attachments` tool). Images come back as image content you can look at; text files as text; other files as a description only.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly path: {
+                readonly type: "string";
+                readonly description: "The post's absolute path.";
+            };
+            readonly id: {
+                readonly type: "string";
+                readonly description: "The attachment id from the `attachments` list.";
+            };
+        };
+        readonly required: readonly ["path", "id"];
+    };
+}];
+export declare const isAttachmentTool: (name: unknown) => name is "attachments" | "attachment";
+/**
+ * The largest image the MCP fetch returns as image content: 3 MB. Base64
+ * makes it ~4 MB of JSON, which fits the hosted route's 4.5 MB response
+ * limit (a Vercel function), and it is under the 5 MB a Claude image may
+ * be. Larger images are metadata plus a pointer to `attachments --out`.
+ */
+export declare const MCP_IMAGE_MAX_BYTES: number;
+/** How much of a text file the MCP fetch inlines: 256 KB, decoded as UTF-8; the rest is cut with a note. */
+export declare const MCP_TEXT_MAX_BYTES: number;
+/**
+ * Answer an MCP call to `attachments` (no id) or `attachment` (with one).
+ * Errors are results with `isError`, never throws: the servers return them
+ * as tool output the agent can read and act on.
+ */
+export declare function attachmentToolResult(client: SforaApiClient, args: {
+    path?: unknown;
+    id?: unknown;
+}): Promise<McpToolResult>;