@dalmasonto/taskflow-mcp 1.0.33 → 2.0.0

package/README.md

@@ -1,221 +1,166 @@
-# TaskFlow MCP Server
+# @dalmasonto/taskflow-mcp — TaskFlow MCP server + Claude Code hooks
 
-A local-first task and time tracking system exposed as [MCP](https://modelcontextprotocol.io) tools. Any MCP-compatible AI agent can manage projects, tasks, timers, analytics, and notifications through this server.
+An **agent client** for the TaskFlow backend. It lets a coding agent (e.g. Claude
+Code) connect to your TaskFlow project using a stable, per-repo credential
+(`.taskflow.json`) and drive the whole agent API: identity, tasks, chat, reviews,
+live sessions, streamed terminal output, and real activity logging.
 
-## Quickstart
-
-### 1. Install and build
+> **2.0.0** is a ground-up rewrite. Where the 1.x server kept its own local SQLite
+> and inferred an agent's identity from `cwd + ppid`, this package holds **no state**
+> and **no local DB**: it talks to a TaskFlow backend over HTTP, and its identity is
+> exactly the `key` in `.taskflow.json`, so an agent linked yesterday keeps the same
+> identity today. Multi-agent collaboration — channels, reviews, terminal streaming,
+> `.taskflow.json` profiles — is new in 2.x.
 
 ```bash
-cd mcp-server
-npm install
-npm run build
+npm install -g @dalmasonto/taskflow-mcp
 ```
 
-### 2. Configure your MCP client
+This puts two commands on your PATH:
+
+- **`taskflow-mcp`** — the MCP server an MCP client (Claude Code, Cursor, …) runs.
+- **`taskflow-hook`** — the Claude Code lifecycle hook (see [Hooks](#hooks)).
+
+## How it works
+
+- **`.taskflow.json`** (per repo, gitignored) holds the server URL, project id, a
+  `default_profile`, and one or more named `profiles`. Each profile has an
+  `agent_id`, a `key` (the `tfk_…` credential), and a `display_name`.
+- Every backend call sends `Authorization: Agent <key>`. The chosen profile's key
+  is the whole identity — the server derives the agent, project, and display name
+  from it.
+- **Profile selection** (highest priority first): a tool's `profile` argument →
+  `TASKFLOW_PROFILE` env → the file's `default_profile` → `"main"`.
 
-Add a `.mcp.json` file to your project root (or wherever your MCP client reads config):
+## `.taskflow.json` format
 
 ```json
 {
-  "mcpServers": {
-    "taskflow": {
-      "command": "node",
-      "args": ["/absolute/path/to/mcp-server/dist/index.js"]
-    }
+  "server": "http://localhost:8000",
+  "project": 1,
+  "default_profile": "main",
+  "profiles": {
+    "main":     { "agent_id": 12, "key": "tfk_…", "display_name": "Builder" },
+    "reviewer": { "agent_id": 13, "key": "tfk_…", "display_name": "Reviewer" }
   }
 }
 ```
 
-Replace the path with the absolute path to your built `dist/index.js`.
-
-### 3. Auto-allow permissions (Claude Code)
-
-By default, Claude Code will prompt you to approve each MCP tool call. To allow all TaskFlow tools without prompts, add this to `.claude/settings.local.json`:
+Resolution: the file is read from `TASKFLOW_CONFIG` if set, otherwise found by
+walking up from the working directory. See `.taskflow.json.example`.
+
+## Setup
+
+1. **Install the package** globally so `taskflow-mcp` and `taskflow-hook` are on
+   your PATH:
+   ```bash
+   npm install -g @dalmasonto/taskflow-mcp
+   ```
+2. **Link an agent.** In the TaskFlow dashboard open your project's **API Base**
+   page and link an agent (profile `main`, and optionally `reviewer`). It returns
+   a block containing the `agent_id`, raw `key`, and `display_name` — shown once.
+3. **Create `.taskflow.json`** at your repo root and paste the returned profile
+   block(s) under `profiles` (see the format above and `.taskflow.json.example`).
+   **Do not commit it** — add `.taskflow.json` to your `.gitignore`.
+4. **Register the MCP server** with Claude Code — copy `.mcp.json.example` to
+   `.mcp.json` at your repo root:
+   ```json
+   {
+     "mcpServers": {
+       "taskflow": { "command": "taskflow-mcp", "args": [] }
+     }
+   }
+   ```
+5. **Add the hooks** (optional but recommended) — see [Hooks](#hooks) below.
+
+**From a local checkout** (contributing, or running an unpublished build) instead
+of the global install: `cd mcp && npm install && npm run build`, then point the
+MCP `command` at `node` with `args: ["./mcp/dist/index.js"]`, and the hook at
+`node ABS_PATH/mcp/hooks/taskflow-hook.mjs`.
+
+## Hooks
+
+The Claude Code hook (`taskflow-hook`) turns the agent's own lifecycle into real,
+attributable activity on the TaskFlow board — no prompting required. On each event
+it resolves your `.taskflow.json` + profile and POSTs to the backend:
+
+- **SessionStart** → registers/reconnects your live session (you show "online").
+- **PreToolUse / PostToolUse** → logs meaningful tool calls as activity. Read-only
+  noise (Read, Grep, and TaskFlow's own tools, which already write richer rows) is
+  filtered out, so the feed stays signal.
+- **Stop** → closes the session cleanly.
+- **Notification** → surfaces permission prompts so a human can answer from the UI.
+
+It is **best-effort and never blocks or crashes the agent**: with no `.taskflow.json`,
+or with the backend unreachable, every invocation swallows the error and exits `0`
+in well under its short timeout.
+
+**Wire it up** — copy the `hooks` block from `.claude/settings.example.json` into
+your project's `.claude/settings.json`. With the global install the command is just
+`taskflow-hook`:
 
 ```json
 {
-  "permissions": {
-    "allow": [
-      "mcp__taskflow__*"
-    ]
-  },
-  "enableAllProjectMcpServers": true,
-  "enabledMcpjsonServers": [
-    "taskflow"
-  ]
+  "hooks": {
+    "SessionStart":  [{ "hooks": [{ "type": "command", "command": "taskflow-hook" }] }],
+    "PreToolUse":    [{ "matcher": "*", "hooks": [{ "type": "command", "command": "taskflow-hook" }] }],
+    "PostToolUse":   [{ "matcher": "*", "hooks": [{ "type": "command", "command": "taskflow-hook" }] }],
+    "Stop":          [{ "hooks": [{ "type": "command", "command": "taskflow-hook" }] }],
+    "Notification":  [{ "hooks": [{ "type": "command", "command": "taskflow-hook" }] }]
+  }
 }
 ```
 
-The `mcp__taskflow__*` wildcard matches every tool exposed by this server.
-
-For other MCP clients (Cursor, Windsurf, etc.), check their docs for permission/auto-approve configuration.
-
-## Agent Integration Guide
-
-### How agents discover TaskFlow
-
-TaskFlow uses two layers to guide agent behavior:
-
-**Layer 1: Tool descriptions (passive discovery)**
-Every tool has a description that hints at when and why to use it. MCP clients surface these descriptions when the agent connects, so the agent learns the workflow organically. For example, `start_timer` says "Call this before beginning work on any task to track focused time."
-
-**Layer 2: `get_agent_instructions` tool (active onboarding)**
-This is the key tool. Its description says **"Call this at the start of every conversation."** When called, it returns:
-
-- A role description for the agent
-- A startup checklist (list projects, check in-progress tasks, check notifications)
-- Behavioral rules (when to start/stop timers, how to handle blockers, etc.)
-- Live context (current project count, in-progress tasks, blocked tasks, unread notifications)
-- The full task status workflow with valid transitions
-
-Any well-behaved agent will call this tool when it sees the description, without needing explicit user instructions.
-
-### Making it automatic (recommended)
-
-For the most reliable experience, add one line to your project's `CLAUDE.md` (or equivalent agent config):
-
-```markdown
-## MCP Integration
-At the start of each conversation, call the `get_agent_instructions` tool from the taskflow MCP server to understand your task management workflow.
-```
-
-This guarantees the agent calls the instruction tool on every conversation start. Without this, the agent will still likely discover the tool via its description, but the CLAUDE.md line makes it deterministic.
-
-### Example conversation flow
+The hook reads `TASKFLOW_PROFILE` (else `default_profile`, else `main`) and finds
+`.taskflow.json` by walking up from the working directory (or `TASKFLOW_CONFIG`).
+Set `TASKFLOW_HOOK_DEBUG=1` to see why a hook no-oped on stderr.
+
+## MCP tools
+
+| Tool | What it does |
+| --- | --- |
+| `whoami` | Confirm the agent identity + project behind the credential. |
+| `list_tasks(status?, assigned?)` | List project tasks; `assigned='me'` for claimed. |
+| `create_task(title, description?, priority?, claim?)` | Create (optionally claim) a task. |
+| `update_task_status(task, status)` | Advance a task's status. |
+| `claim_task(task)` | Self-assign a task. |
+| `report_review(task, decision, body?)` | Record a review (`approved`/`changes_requested`). |
+| `list_channels` | Channels this agent can see. |
+| `list_agents` | Other agents in the project. |
+| `send_message(channel, body, priority?)` | Post a chat message as this agent. |
+| `check_messages(channel, since?)` | Read a channel's messages + read cursor. |
+| `mark_read(channel, last_read_message)` | Advance this agent's read cursor. |
+| `register_session(session_identifier?, cwd?)` | Register/reconnect a live session. |
+| `heartbeat(status?)` | Bump session liveness (`idle`/`busy`). |
+| `capture_terminal(content, stream?)` | Stream terminal output into the session. |
+| `log_activity(action, body?, task?)` | Log a real activity event. |
+| `get_activity(task?, limit?)` | Read recent project activity. |
+
+Every tool also accepts an optional `profile` argument to act as a different
+profile for that one call (e.g. use `reviewer` for `report_review`).
+
+## Development
 
-Here's what a conversation looks like when the agent is properly connected:
-
-```
-Agent connects → sees get_agent_instructions in tool list → calls it
-  ↓
-Gets instructions + live context (3 projects, 2 tasks in progress, 1 blocked)
-  ↓
-Calls list_tasks(status="in_progress") → sees "Build dashboard page" is active
-  ↓
-User: "Let's work on the dashboard"
-  ↓
-Agent: calls get_task(id=5) → reads description for implementation details
-Agent: calls start_timer(task_id=5) → time tracking begins
-  ↓
-Agent implements the feature, referencing task description for acceptance criteria
-  ↓
-Agent: calls stop_timer(task_id=5, final_status="done")
-Agent: checks if any blocked tasks depended on task 5
+```bash
+npm run typecheck   # tsc --noEmit
+npm run build       # compile to dist/
+npm test            # vitest (config resolution unit tests)
 ```
 
-### Strategies for proactive agent behavior
-
-The `get_agent_instructions` tool tells agents to:
+## Smoke test (against a real backend)
 
-1. **Check tasks before coding** — before starting work, search for a matching task and start its timer
-2. **Track time automatically** — start_timer when beginning work, pause_timer on context switches, stop_timer when done
-3. **Surface blockers** — if stuck, update the task to "blocked" with context in the description
-4. **Suggest next work** — when the user asks "what should I work on?", surface high-priority unblocked tasks
-5. **Stay in sync** — create tasks for new work items to keep the tracker up to date
-6. **Read descriptions** — task descriptions contain implementation details and acceptance criteria
-
-## Agent Inbox — Remote Communication
-
-The Agent Inbox lets agents ask questions that appear in the TaskFlow UI. Users can respond from any device (phone, browser, another machine), and the response is delivered back to the agent's terminal automatically.
-
-### How it works
-
-1. Agent calls `ask_user` with a question, context, and optional quick-tap choices
-2. Question appears instantly in the TaskFlow UI at `/inbox`
-3. User responds from the UI — response is injected into the agent's terminal via tmux
-4. Agent also asks in the terminal normally, so the user can answer from either place
-
-### Setup for auto-injection
-
-For responses to be injected directly into the terminal, run Claude Code inside tmux:
+`scripts/smoke.mjs` drives the compiled client against a running backend. It is
+env-driven and safe to run anywhere: with no key or no reachable backend it prints
+`SKIPPED` and exits 0.
 
 ```bash
-# Install tmux (one-time)
-sudo apt-get install -y tmux
-
-# Start a tmux session and run claude inside it
-tmux new -s agent
-claude
+npm run build
+SMOKE_SERVER=http://localhost:8010 SMOKE_KEY=tfk_your_agent_key node scripts/smoke.mjs
+# optional: SMOKE_CHANNEL=<id> to force which channel send/check use
 ```
 
-Without tmux, the inbox still works — agents can use `check_response` to poll for answers, or the user can dismiss questions answered in the terminal.
-
-See [Terminal Injection Setup](../docs/agent-inbox-terminal-injection.md) for full details, multiple agent setup, and cleanup instructions.
-
-## Available Tools
-
-### Agent
-| Tool | Description |
-|------|-------------|
-| `get_agent_instructions` | Returns onboarding instructions and live context for AI agents. **Call first.** |
-
-### Tasks
-| Tool | Description |
-|------|-------------|
-| `create_task` | Create a task with dependencies, tags, links, and time estimates |
-| `list_tasks` | List tasks with filters (status, project, priority, tag) |
-| `get_task` | Get a task by ID with time tracking info |
-| `update_task` | Update task fields |
-| `update_task_status` | Change status with transition validation |
-| `delete_task` | Delete a task by ID |
-| `bulk_create_tasks` | Create multiple tasks in a single transaction |
-| `search_tasks` | Full-text search by title or description |
-
-### Projects
-| Tool | Description |
-|------|-------------|
-| `create_project` | Create a project (active_project or project_idea) |
-| `list_projects` | List all projects with task counts |
-| `get_project` | Get a project with all its tasks |
-| `update_project` | Update project fields |
-| `delete_project` | Delete a project (tasks are unlinked, not deleted) |
-
-### Timer
-| Tool | Description |
-|------|-------------|
-| `start_timer` | Start a timer session (task transitions to in_progress) |
-| `pause_timer` | Pause the active session (task transitions to paused) |
-| `stop_timer` | Stop timer with final status (done/partial_done/blocked) |
-| `list_sessions` | List sessions with optional date range filter |
-
-### Analytics
-| Tool | Description |
-|------|-------------|
-| `get_analytics` | Summary: focused time, completion rates, status distribution, time per project |
-| `get_timeline` | Focused time grouped by day or week |
-
-### Activity
-| Tool | Description |
-|------|-------------|
-| `get_activity_log` | Recent activity: completions, timer events, status changes |
-| `clear_activity_log` | Delete all activity log entries |
-
-### Notifications
-| Tool | Description |
-|------|-------------|
-| `list_notifications` | List notifications (filter by unread) |
-| `mark_notification_read` | Mark a single notification as read |
-| `mark_all_notifications_read` | Mark all as read |
-| `clear_notifications` | Delete all notifications |
-
-### Agent Inbox
-| Tool | Description |
-|------|-------------|
-| `ask_user` | Post a question to the Agent Inbox for remote response. Returns immediately with message ID |
-| `check_response` | Check if the user has responded to a previously posted question |
-
-### Settings
-| Tool | Description |
-|------|-------------|
-| `get_setting` | Get a setting by key (returns default if not set) |
-| `update_setting` | Update or create a setting |
-
-## Configuration
-
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `TASKFLOW_SSE_PORT` | `3456` | Port for the SSE broadcast server |
-| Database location | `~/.taskflow/taskflow.db` | SQLite database with WAL mode |
-
-The SSE server at `http://localhost:3456/events` broadcasts real-time changes to connected UI clients. The `/sync` endpoint returns a full data dump for initial sync.
+It exercises: `whoami`, `create_task`, `list_tasks`, `list_channels`,
+`send_message`, `check_messages`, `register_session`, `heartbeat`,
+`capture_terminal`, `close_session`, `log_activity`, `get_activity` — printing
+`PASS`/`FAIL` per call, and exits non-zero only if a call actually failed against a
+reachable backend.

package/dist/attachment-download.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Download a message attachment to disk.
+ *
+ * The tool exists as insulation, not as an authorization point. `/media` is
+ * currently served without auth; when storage is gated at the framework level,
+ * only this module changes — it starts sending the agent key as a header — and
+ * the agent-facing contract (url in, path out) stays put.
+ *
+ * Two untrusted inputs: the `url` (must resolve under `/media/`, or this
+ * becomes an arbitrary-URL fetcher with a disk write attached) and the
+ * filename (must not escape the download directory).
+ */
+export declare class AttachmentDownloadError extends Error {
+    constructor(message: string);
+}
+export interface DownloadResult {
+    path: string;
+    name: string;
+    size_bytes: number;
+    content_type: string;
+}
+export type BinaryFetch = (url: string, init?: {
+    headers?: Record<string, string>;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    statusText: string;
+    headers: {
+        get(name: string): string | null;
+    };
+    arrayBuffer(): Promise<ArrayBuffer>;
+}>;
+/**
+ * Validate an attachment url and reduce it to its `/media/...` path.
+ *
+ * Absolute urls are accepted only for their path — the host is discarded
+ * before the fetch (it always targets the configured server, never the url's
+ * own host), so a url pointing at another origin can never redirect the
+ * fetch there. `server` is free-form user config (any origin, not just
+ * loopback), so instead of a hardcoded allowlist, an absolute url's origin is
+ * compared against the *configured* server's origin: a match is accepted,
+ * anything else is a sign of a confused or hostile caller and is refused
+ * outright. When no `server` is given (e.g. validating a url in isolation),
+ * there is nothing to compare against, so the host is simply discarded and
+ * only the path is used — safe, since it is never fetched.
+ *
+ * The path is percent-decoded before normalisation so a bare `/media/...`
+ * input and an absolute-url input agree on what `%2e%2e`-style traversal
+ * resolves to. Anything that does not land under `/media/` after
+ * normalisation is rejected.
+ *
+ * The returned path is DECODED — it is the real storage key, and it is what
+ * the on-disk filename is taken from. It must be re-encoded before it goes
+ * into a request line; `downloadAttachment` does that per segment.
+ */
+export declare function mediaPathFrom(url: string, server?: string): string;
+/**
+ * The filename to write, always a bare basename.
+ *
+ * Storage keys are already UUID-prefixed, so the url basename is unique by
+ * construction and needs no extra prefix. An override is accepted for a
+ * friendlier name, but is reduced to its basename first.
+ */
+export declare function downloadFilenameFrom(mediaPath: string, override?: string): string;
+/** Absolute path of the download directory for a project root. */
+export declare function downloadDirFor(root: string): string;
+export declare function downloadAttachment(opts: {
+    url: string;
+    server: string;
+    root: string;
+    name?: string;
+    key?: string;
+    fetchImpl?: BinaryFetch;
+}): Promise<DownloadResult>;

package/dist/attachment-download.js

@@ -0,0 +1,193 @@
+/**
+ * Download a message attachment to disk.
+ *
+ * The tool exists as insulation, not as an authorization point. `/media` is
+ * currently served without auth; when storage is gated at the framework level,
+ * only this module changes — it starts sending the agent key as a header — and
+ * the agent-facing contract (url in, path out) stays put.
+ *
+ * Two untrusted inputs: the `url` (must resolve under `/media/`, or this
+ * becomes an arbitrary-URL fetcher with a disk write attached) and the
+ * filename (must not escape the download directory).
+ */
+import { access, mkdir, writeFile } from "node:fs/promises";
+import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+export class AttachmentDownloadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AttachmentDownloadError";
+    }
+}
+const MEDIA_PREFIX = "/media/";
+/** Cap on decode passes — enough for any real url, bounded for a hostile one. */
+const MAX_DECODE_PASSES = 5;
+/**
+ * Percent-decode until the string stops changing (bounded).
+ *
+ * One pass is not enough: `%252e%252e` decodes to the literal `%2e%2e`, which
+ * would sail past the traversal check and rely on the upstream decoder to
+ * catch it. Looping removes that reliance.
+ *
+ * A decode failure is NOT fatal. The backend emits urls unencoded, so a lone
+ * `%` is a legal character in a real storage key (`50%.png`) and
+ * `decodeURIComponent` throws on it. Falling back to the undecoded string
+ * treats it as the literal it is.
+ */
+function fullyDecode(path) {
+    let current = path;
+    for (let i = 0; i < MAX_DECODE_PASSES; i++) {
+        let next;
+        try {
+            next = decodeURIComponent(current);
+        }
+        catch {
+            return current;
+        }
+        if (next === current)
+            return current;
+        current = next;
+    }
+    return current;
+}
+/**
+ * Encode a decoded media path for use in a request line, segment by segment.
+ *
+ * The `/` separators stay literal; everything else is percent-encoded. Without
+ * this, a key containing `#` or `?` truncates the request at the fragment or
+ * query and 404s on a file that exists.
+ */
+function encodeMediaPath(mediaPath) {
+    return mediaPath.split("/").map(encodeURIComponent).join("/");
+}
+/**
+ * Validate an attachment url and reduce it to its `/media/...` path.
+ *
+ * Absolute urls are accepted only for their path — the host is discarded
+ * before the fetch (it always targets the configured server, never the url's
+ * own host), so a url pointing at another origin can never redirect the
+ * fetch there. `server` is free-form user config (any origin, not just
+ * loopback), so instead of a hardcoded allowlist, an absolute url's origin is
+ * compared against the *configured* server's origin: a match is accepted,
+ * anything else is a sign of a confused or hostile caller and is refused
+ * outright. When no `server` is given (e.g. validating a url in isolation),
+ * there is nothing to compare against, so the host is simply discarded and
+ * only the path is used — safe, since it is never fetched.
+ *
+ * The path is percent-decoded before normalisation so a bare `/media/...`
+ * input and an absolute-url input agree on what `%2e%2e`-style traversal
+ * resolves to. Anything that does not land under `/media/` after
+ * normalisation is rejected.
+ *
+ * The returned path is DECODED — it is the real storage key, and it is what
+ * the on-disk filename is taken from. It must be re-encoded before it goes
+ * into a request line; `downloadAttachment` does that per segment.
+ */
+export function mediaPathFrom(url, server) {
+    let path;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(url)) {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw new AttachmentDownloadError(`Not a valid attachment url: ${url}`);
+        }
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            throw new AttachmentDownloadError(`Attachment url must be http(s) or a /media path, got: ${url}`);
+        }
+        // The host is discarded below regardless -- the actual fetch always goes
+        // to the configured server, never to whatever host this url names. But an
+        // absolute url naming some OTHER host than the configured server is still
+        // a sign of a confused or hostile caller, so it is rejected outright
+        // rather than silently tolerated.
+        if (server) {
+            let serverOrigin;
+            try {
+                serverOrigin = new URL(server).origin;
+            }
+            catch {
+                throw new AttachmentDownloadError(`Not a valid server origin: ${server}`);
+            }
+            if (parsed.origin !== serverOrigin) {
+                throw new AttachmentDownloadError(`Attachment url points at another host, got: ${url}`);
+            }
+        }
+        path = parsed.pathname;
+    }
+    else {
+        path = url;
+    }
+    // Percent-decode before normalising, so `/media/%2e%2e/etc/passwd` collapses
+    // the same way whether it arrived as a bare path or inside an absolute url.
+    const decodedPath = fullyDecode(path);
+    // Normalise so `/media/../etc/passwd` cannot masquerade as a media path.
+    const normalised = resolve("/", decodedPath);
+    if (!normalised.startsWith(MEDIA_PREFIX)) {
+        throw new AttachmentDownloadError(`Attachment url must be under ${MEDIA_PREFIX} — got: ${url}`);
+    }
+    return normalised;
+}
+/**
+ * The filename to write, always a bare basename.
+ *
+ * Storage keys are already UUID-prefixed, so the url basename is unique by
+ * construction and needs no extra prefix. An override is accepted for a
+ * friendlier name, but is reduced to its basename first.
+ */
+export function downloadFilenameFrom(mediaPath, override) {
+    const raw = override && override.trim() ? override : mediaPath;
+    const name = basename(raw.replace(/[/\\]+$/, ""));
+    if (!name || name === "." || name === "..")
+        return "attachment";
+    return name;
+}
+/** Absolute path of the download directory for a project root. */
+export function downloadDirFor(root) {
+    return join(root, ".taskflow", "attachments");
+}
+export async function downloadAttachment(opts) {
+    const mediaPath = mediaPathFrom(opts.url, opts.server);
+    const filename = downloadFilenameFrom(mediaPath, opts.name);
+    const dir = downloadDirFor(opts.root);
+    const target = resolve(dir, filename);
+    // Belt and braces: the basename reduction above should make escape
+    // impossible, so this asserts the invariant rather than trusting it.
+    const rel = relative(dir, target);
+    if (rel === "" || rel.startsWith(`..${sep}`) || rel === ".." || isAbsolute(rel)) {
+        throw new AttachmentDownloadError(`Refusing to write outside the download directory: ${filename}`);
+    }
+    const doFetch = opts.fetchImpl ?? globalThis.fetch;
+    // `mediaPath` is decoded (see `mediaPathFrom`); the backend emits urls
+    // unencoded, so it can legitimately contain `#`, `?`, `%`, spaces and
+    // unicode. Re-encode per segment before it becomes a request line.
+    const absolute = `${opts.server.replace(/\/$/, "")}${encodeMediaPath(mediaPath)}`;
+    // When storage is gated at the framework level, the auth header goes HERE and
+    // nothing else in the system needs to change.
+    const headers = {};
+    if (opts.key)
+        headers.Authorization = `Agent ${opts.key}`;
+    const res = await doFetch(absolute, { headers });
+    if (!res.ok) {
+        throw new AttachmentDownloadError(`Download failed: ${res.status} ${res.statusText} for ${mediaPath}`);
+    }
+    const bytes = Buffer.from(await res.arrayBuffer());
+    await mkdir(dir, { recursive: true });
+    // Downloads are scratch, never committed. Written only when absent — if
+    // anything else ever keeps committed state under `.taskflow/`, an
+    // unconditional write here would silently ignore it.
+    const gitignore = join(opts.root, ".taskflow", ".gitignore");
+    try {
+        await access(gitignore);
+    }
+    catch {
+        await writeFile(gitignore, "*\n");
+    }
+    await writeFile(target, bytes);
+    return {
+        path: target,
+        name: filename,
+        size_bytes: bytes.length,
+        content_type: res.headers.get("content-type") || "application/octet-stream",
+    };
+}
+//# sourceMappingURL=attachment-download.js.map

package/dist/attachment-download.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-download.js","sourceRoot":"","sources":["../src/attachment-download.ts"],"names":[],"mappings":"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"}