corkcrm-mcp 0.1.3 → 0.5.0

package/dist/auth.js

@@ -17,7 +17,7 @@ export function getConvexUrl() {
     const url = process.env.CONVEX_URL;
     if (!url) {
         throw new Error("CONVEX_URL environment variable is required. " +
-            "Set it to your Convex deployment URL (e.g., https://your-deployment.convex.cloud).");
+            "Set it to your Convex deployment URL (e.g., https://your-deployment.convex.site).");
     }
     return url;
 }

package/dist/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,IAAI,SAAS,GAAG,KAAK,CAAC;AAEtB,MAAM,UAAU,SAAS;IACvB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IACrC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,iDAAiD;YAC/C,gDAAgD,CACnD,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;IACnC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,+CAA+C;YAC7C,oFAAoF,CACvF,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAA8B;IAE9B,IAAI,SAAS;QAAE,OAAO;IACtB,IAAI,CAAC;QACH,MAAM,MAAM,EAAE,CAAC;QACf,SAAS,GAAG,IAAI,CAAC;IACnB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;QACrE,MAAM,IAAI,KAAK,CAAC,8BAA8B,GAAG,EAAE,CAAC,CAAC;IACvD,CAAC;AACH,CAAC"}
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,IAAI,SAAS,GAAG,KAAK,CAAC;AAEtB,MAAM,UAAU,SAAS;IACvB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IACrC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,iDAAiD;YAC/C,gDAAgD,CACnD,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;IACnC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,+CAA+C;YAC7C,mFAAmF,CACtF,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAA8B;IAE9B,IAAI,SAAS;QAAE,OAAO;IACtB,IAAI,CAAC;QACH,MAAM,MAAM,EAAE,CAAC;QACf,SAAS,GAAG,IAAI,CAAC;IACnB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;QACrE,MAAM,IAAI,KAAK,CAAC,8BAA8B,GAAG,EAAE,CAAC,CAAC;IACvD,CAAC;AACH,CAAC"}

package/dist/client.d.ts

@@ -1,12 +1,10 @@
-/**
- * HTTP client for communicating with Convex HTTP actions.
- * All MCP server → Convex communication goes through HTTP endpoints.
- */
+import type { ErrorShape } from "./format.js";
+export type CallResult = {
+    ok: true;
+    data: unknown;
+} | {
+    ok: false;
+    error: ErrorShape;
+};
 export declare function initClient(url: string, key: string): void;
-/**
- * Make an authenticated request to a Convex HTTP action endpoint.
- */
-export declare function convexFetch<T = unknown>(path: string, options?: {
-    method?: string;
-    body?: unknown;
-}): Promise<T>;
+export declare function callTool(name: string, args: Record<string, unknown>): Promise<CallResult>;

package/dist/client.js

@@ -1,42 +1,70 @@
-/**
- * HTTP client for communicating with Convex HTTP actions.
- * All MCP server → Convex communication goes through HTTP endpoints.
- */
+import { clockOverride } from "./present.js";
+const TIMEOUT_MS = 60_000;
 let convexUrl = null;
 let apiKey = null;
+const nowOverride = clockOverride();
 export function initClient(url, key) {
-    convexUrl = url;
+    convexUrl = url.replace(/\/+$/, "");
     apiKey = key;
 }
-/**
- * Make an authenticated request to a Convex HTTP action endpoint.
- */
-export async function convexFetch(path, options = {}) {
+function hostOf(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return url;
+    }
+}
+function errorOf(body) {
+    if (body && typeof body === "object" && "error" in body) {
+        const e = body.error;
+        if (e && typeof e === "object" && "code" in e && "message" in e)
+            return e;
+    }
+    return null;
+}
+export async function callTool(name, args) {
     if (!convexUrl || !apiKey) {
-        throw new Error("Client not initialized. Call initClient() first.");
-    }
-    const url = `${convexUrl}${path}`;
-    const method = options.method || "GET";
-    const headers = {
-        Authorization: `Bearer ${apiKey}`,
-    };
-    const fetchOptions = { method, headers };
-    if (options.body !== undefined) {
-        headers["Content-Type"] = "application/json";
-        fetchOptions.body = JSON.stringify(options.body);
-    }
-    const response = await fetch(url, fetchOptions);
-    if (!response.ok) {
-        let errorMessage;
-        try {
-            const errorBody = await response.json();
-            errorMessage = errorBody.error || `HTTP ${response.status}`;
-        }
-        catch {
-            errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+        return { ok: false, error: { code: "internal", message: "Client not initialized. Call initClient() first." } };
+    }
+    const body = nowOverride === null ? args : { ...args, _now: nowOverride };
+    let response;
+    let text;
+    try {
+        response = await fetch(`${convexUrl}/mcp/${name}`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        text = await response.text();
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return { ok: false, error: { code: "internal", message: `Could not reach ${hostOf(convexUrl)}: ${message}.` } };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        if (response.status === 200) {
+            return {
+                ok: false,
+                error: { code: "internal", message: `Could not reach ${hostOf(convexUrl)}: HTTP 200 with a non-JSON body.` },
+            };
         }
-        throw new Error(errorMessage);
+        parsed = null;
+    }
+    const error = errorOf(parsed);
+    if (response.status === 200)
+        return error ? { ok: false, error } : { ok: true, data: parsed };
+    if (response.status === 401) {
+        return { ok: false, error: error ?? { code: "unauthorized", message: "This API key is not valid.", candidates: [] } };
     }
-    return response.json();
+    const message = response.status === 500
+        ? "The server could not answer this call (HTTP 500). Try again; if it repeats, report the call and the time."
+        : (error?.message ?? `HTTP ${response.status}`);
+    return { ok: false, error: { code: "internal", message } };
 }
 //# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,IAAI,SAAS,GAAkB,IAAI,CAAC;AACpC,IAAI,MAAM,GAAkB,IAAI,CAAC;AAEjC,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,GAAW;IACjD,SAAS,GAAG,GAAG,CAAC;IAChB,MAAM,GAAG,GAAG,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAY,EACZ,UAA+C,EAAE;IAEjD,IAAI,CAAC,SAAS,IAAI,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IAED,MAAM,GAAG,GAAG,GAAG,SAAS,GAAG,IAAI,EAAE,CAAC;IAClC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC;IAEvC,MAAM,OAAO,GAA2B;QACtC,aAAa,EAAE,UAAU,MAAM,EAAE;KAClC,CAAC;IAEF,MAAM,YAAY,GAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAEtD,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;QAC7C,YAAY,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IAEhD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,IAAI,YAAoB,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACxC,YAAY,GAAG,SAAS,CAAC,KAAK,IAAI,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC9D,CAAC;QAAC,MAAM,CAAC;YACP,YAAY,GAAG,QAAQ,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,UAAU,EAAE,CAAC;QACnE,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC;IAChC,CAAC;IAED,OAAO,QAAQ,CAAC,IAAI,EAAgB,CAAC;AACvC,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/descriptions.d.ts

@@ -0,0 +1,5 @@
+export type ToolName = "find_tasks" | "get_task" | "count_tasks" | "list_views" | "list_projects" | "get_workspace_info" | "resolve" | "find_timecards" | "sum_time" | "find_comments" | "create_task" | "update_task" | "place_task" | "move_task" | "delete_task" | "add_comment" | "edit_comment" | "delete_comment" | "link_pull_request";
+export declare const DESCRIPTIONS: Record<ToolName, {
+    title: string;
+    description: string;
+}>;

package/dist/descriptions.js

@@ -0,0 +1,172 @@
+// The description texts are the "### Description" (reads) and "#### Description" (writes) blocks of the project's Tool Design, verbatim.
+export const DESCRIPTIONS = {
+    find_tasks: {
+        title: "Find tasks",
+        description: `Find tasks in the workspace by filter, by text, or both. Returns a sentence with the total and what is hidden, then one line per row (name, status, priority, people, dates, comments) ending in its alpha-ID linked to corktasks.com, under "Project > Milestone" headings, or one flat list for a date or name sort; plus structured rows, an exact total, hidden_closed and hidden_archived counts, and a cursor when there are more. Every level is returned unless \`level\` narrows it: goal, project, milestone, task, subtask, or \`tasks\` (task, subtask, and rows with no level). Rows come back in view order by default, the same order a person sees in the app.
+
+Use it for any question that lists or searches tasks: "Hassan's open tasks", "what's due this month", "tasks with 'invoice' in the name", "the P2 tasks in Inbox in order", "what's in Hassan's dev view". Do not use it to fetch one task by alpha-ID (use get_task), to count (use count_tasks), to list views (list_views) or projects (list_projects), or to look up an ID for a name you are unsure of (use resolve first).
+
+Names are accepted for assignee, status, priority, view, project, and milestone and are matched in this workspace only. If a name matches several things, the call returns candidates and no rows; call again with the ID or add \`view\` or \`project\` to narrow. Two projects can share a name across views, so pass \`view\` with \`project\` whenever the person named the view. A dev view expands to the milestones assigned to its person plus every task and subtask under them, whoever they are assigned to; that is not the same as \`assignee\`.
+
+Completed and cancelled rows are hidden unless \`include_completed\` is true, or \`status_type\` names \`completed\` or \`cancelled\`, or \`completed_from\`/\`completed_to\` is given. Rows closed more than 180 days ago are hidden unless \`include_archived\` is true. A result of zero rows with hidden_closed > 0 means the match exists but is closed. Dates are YYYY-MM-DD, inclusive; rows with no date in a filtered field are dropped; read today's date from get_workspace_info. \`status_type\` values: not_started, active, completed, cancelled. \`priority\` accepts a workspace priority name, \`none\`, or \`highest\`. \`sort\` values: view_order (default), end_date_asc, end_date_desc, start_date_asc, start_date_desc, completed_at_asc, completed_at_desc, name_asc, name_desc. \`limit\` 1 to 200, default 50.
+
+Text search is a case-insensitive substring on name (\`name\`), description (\`description\`), or either (\`text\`); these OR together and AND with everything else. It does not search comments (use find_comments), tags, assignee names, project names, due dates, hours, or custom columns, and it does not match words out of order or with typos. Example: {"assignee":"Hassan","end_from":"2026-09-01","end_to":"2026-09-30","name":"estimating","description":"pizza"}
+
+To show it: group by project and milestone for app-order lists; one table sorted by date for due or overdue questions; leave IDs out unless asked.`,
+    },
+    get_task: {
+        title: "Get one task",
+        description: `Fetch one task by alpha-ID (for example "alpha-482") or Convex ID. Returns the full record including description, hours, tags, and custom columns; the ancestor chain up to its project; its view and view type; its position among siblings in view order; its direct children as references in order with hidden_closed and hidden_archived counts; its linked pull requests; its newest comments, newest first, with comment_count and, when there are more, a cursor to pass to find_comments for the older ones (comment_limit 0 to 50, default 10; a comment over 1,000 characters is cut); and, with include_siblings=true, its siblings in order with the task marked in place. The task itself is returned even if it is completed, cancelled, or archived; include_completed and include_archived (both default false) apply only to the children and siblings lists.
+
+Use it for "where does alpha-482 sit", "which view is it in", "what are its subtasks", "what else is in the same milestone", "what's been said on alpha-482". Do not use it to search by name (use find_tasks), to list a container's whole subtree (use find_tasks with project or milestone), or to search comments across tasks (use find_comments). Example: {"id":"alpha-482","include_siblings":true}
+
+To show it: a short card -- name linked, where it sits, status, people, dates, then the description, subtasks, and newest comments.`,
+    },
+    count_tasks: {
+        title: "Count tasks",
+        description: `Count tasks that match the same filters as find_tasks, optionally broken down with count_by: none (default), view, assignee, status, priority, or level. Returns exact numbers, never capped or paged, plus hidden_closed and hidden_archived so you can see what the default rules excluded. A row with two assignees counts once under each; rows with no value for the count_by field get their own "none" line. Completed and archived rules and every name-resolution rule are identical to find_tasks.
+
+Use it for "how many", "how many per person", "how many in each view". Do not use it to see the tasks themselves (use find_tasks). Example: {"count_by":"assignee","completed_from":"2026-08-01","completed_to":"2026-08-31"}
+
+To show it: a small table, then the total and what was hidden.`,
+    },
+    list_views: {
+        title: "List views",
+        description: `List every view in the workspace in the order the app shows them, with each view's ID, type (normal or dev), and, for dev views, the person it belongs to. Use it to learn view names before passing \`view\` to find_tasks, list_projects, or count_tasks, and to answer "what views are there" or "which are dev views". Do not use it to list tasks (find_tasks) or projects (list_projects). It never lists views of another workspace. Example: {}
+
+To show it: a plain list in app order.`,
+    },
+    list_projects: {
+        title: "List projects",
+        description: `List the projects (level "project") in one view, or in every view grouped by view, in the order they appear in the app, with each project's alpha-ID, ID, status, assignees, and number of open milestones. Completed and cancelled projects are hidden unless include_completed is true; projects closed more than 180 days ago are hidden unless include_archived is true. Use it for "what projects are in Inbox, in order" or to find the ID of a project whose view you know. Do not use it to see what is inside a project (find_tasks with project and view) or when several views may hold the same project name and you do not know the view (use resolve with type "project"). Example: {"view":"Inbox"}
+
+To show it: a plain list in app order.`,
+    },
+    get_workspace_info: {
+        title: "Workspace info",
+        description: `Return the facts needed to ask precise questions: the workspace and who you are acting as, every member with ID, every status with its type (not_started, active, completed, cancelled) and order, every priority in order (first is highest), today's date in America/Detroit, the 180-day archive window, the day the week starts on and any former members who still have timecards, page limits, and the list of things this server cannot filter on. Call it once at the start of a session before using status, priority, or date words, and whenever you need "today" for overdue or this-week questions. Do not use it to find a person by partial name when the list is long (use resolve). Example: {}
+
+To show it: usually don't; use it to answer the question.`,
+    },
+    resolve: {
+        title: "Resolve a name",
+        description: `Turn a name into an ID before filtering, when you are not sure the name is unique or spelled the way the workspace spells it. type is one of member, view, project, milestone, status, priority. Matching is case-insensitive on the full name first, then as a substring; members also match on email; a dev view matches its person's name. Returns exactly one ID when one thing matches; a candidate list with each item's view and parent when several match; and an empty list with a sentence when nothing matches in this workspace. An empty result means no such name in this workspace, not that it does not exist elsewhere.
+
+Use it for "which To Do project", "is there a status called Review", "Hassan's user ID". Do not call it when the name is already unique and known, because find_tasks, count_tasks, and list_projects resolve names themselves and return the same candidates when a name is ambiguous. Example: {"type":"project","name":"To Do"}
+
+To show it: when several match, ask which one by name and where it sits.`,
+    },
+    find_timecards: {
+        title: "Find timecards",
+        description: `Find timecards (time entries) in the workspace by person, task, milestone, project, date window, and payment status. Returns a sentence with the hours, the count, and whether they are paid, then the rows under a heading for each Detroit day, one line each (the person when there are several, start to end time, hours, the task with its milestone or project, and paid or unpaid when they are mixed), plus structured rows, an exact total, exact total seconds and hours over every matched row, the number of running timers, and a cursor when there are more. Rows come back oldest first (sort start_asc; start_desc is the other value). limit 1 to 200, default 50.
+
+Use it for "what did Hassan work on today", "show me every timecard on the Stripe migration milestone", "Hassan's unpaid timecards last week", "who is clocked in right now" (running_only=true). Do not use it for hours per person, per day, per week, or per task (use sum_time), or to read the task itself (use get_task).
+
+person is a user ID, a member name, or "me"; there is no "none", because every timecard has a person. A name that is no longer a member but still has timecards resolves and is marked former_member. task, milestone, and project take an alpha-ID or a name; a match means the row is on that item or on anything under it, and closed, cancelled, and archived items always count, so there is no include_completed. A row whose task was deleted shows "(no task)" and still counts. A name matching several things returns candidates and no rows; pass the alpha-ID.
+
+from and to are YYYY-MM-DD in America/Detroit, inclusive; a row belongs to the day its timer started, whole, even if it ran past midnight. Both absent means all time. The server never turns "today" or "this week" into dates: read today and week_start from get_workspace_info, then pass Monday to Sunday; for example, today 2026-09-09 makes this week from 2026-09-07 to 2026-09-13. status values: any (default), paid, unpaid; unpaid includes rows whose status was never set. A running timer has no end and no hours and adds zero to every total; running_count says how many there are.
+
+Nothing searches notes; they are returned on each row. Rates, pay periods, approvals, estimates, and other workspaces are not available. Example: {"person":"Hassan","from":"2026-09-09","to":"2026-09-09"}
+
+To show it: group by day, or a table of task and hours when one day.`,
+    },
+    sum_time: {
+        title: "Sum time",
+        description: `Sum hours over the timecards that match the same filters as find_timecards (person, task, milestone, project, from, to, status, running_only), optionally broken down with group_by: none (default), person, day, week, task, milestone, or project. Returns exact seconds and hours over every matched row, the row count, the number of running timers (they add zero), and every group with its seconds, hours, and row count, never capped or paged. Days are America/Detroit and a row belongs to the day its timer started; weeks run Monday to Sunday and are keyed by their Monday, so a month that starts on a Saturday begins with a partial week keyed by the previous Monday. Groups by person list only people who logged time, former members included and marked. Groups by task, milestone, or project put rows whose task was deleted under one "no task" line. Time on closed tasks always counts; nothing searches notes.
+
+Use it for "how many hours did Hassan work today", "hours per person this week", "hours per week in August", "which milestones in Estimating have the most time", "unpaid hours per person". Do not use it to see the timecards themselves (use find_timecards). Dates are YYYY-MM-DD; read today and week_start from get_workspace_info first. Example: {"person":"Daniyal","from":"2026-08-01","to":"2026-08-31","group_by":"week"}
+
+To show it: a small table with a total row.`,
+    },
+    find_comments: {
+        title: "Find comments",
+        description: `Find comments people wrote on tasks: by task, by author, by who is mentioned, by date, or by a word in the comment. Returns each comment's clean text (mentions shown as @Name), author, Detroit time, whether it was edited, who it mentions, and the task it is on with its alpha-ID, level, and whether the task is closed; plus an exact total and a cursor when there are more. Newest first by default (sort newest; oldest reads a thread top to bottom). limit 1 to 200, default 50.
+
+Use it for "what has Hassan commented on this week", "which comments mention me", "what's been said in the Payments project since Monday", "find comments that say iPad", "which tasks have the most comments" (count_by task), "comments per person last week" (count_by person), and for the older comments of a long thread: get_task shows a task's newest comments and gives a cursor for the rest. Do not use it to read one task's recent comments (get_task does that) or to search task names (find_tasks).
+
+task takes an alpha-ID or a name at any level and returns that item's own comments; pass include_descendants=true for everything under it too. person is the author; mentions is someone mentioned, or "any". Both take a user ID, a member name, or "me". A name matching several people returns candidates and no rows; pass the user ID.
+
+from and to are YYYY-MM-DD America/Detroit days, inclusive, by when the comment was posted; read today from get_workspace_info. text is one case-insensitive substring of the comment text only. edited_only=true keeps edited comments. count_by values: none (default), task, person; it adds exact counts for the whole match, highest first, and rows still come back.
+
+Comments on closed tasks always count. Comments on a task in the trash never appear. Deleted comments and an edited comment's earlier text are gone. Example: {"person":"Hassan","from":"2026-09-29","to":"2026-10-05"}
+
+To show it: group by task; who, when, and the text for each.`,
+    },
+    create_task: {
+        title: "Create task",
+        description: `Create a milestone, task, or subtask under a parent, optionally with its tasks and subtasks in the same call. parent is the alpha-ID of a project (makes a milestone), a milestone (makes a task), or a task (makes a subtask); level is implied. Fields: name (required), assignees (member names, user IDs, or "me"), status and priority (names from get_workspace_info; status defaults to the first not-started status), start_date and end_date (YYYY-MM-DD; "due" means end_date), description.
+
+placement says where it goes: {"position":"top"|"bottom"|"before"|"after","item":"alpha-N"} among the milestone's tasks for a task; for a milestone, its spot in a dev view section, with "view" (a dev view or its person, default the first assignee's) and "group_by" ("status", the default, or "priority"). placement is required for a task and for an assigned milestone. Never choose it yourself: unless the person said "at the bottom" or "wherever", read the neighbors first (find_tasks with view, group_by, group, level=milestone, sort=view_order for a section; get_task with include_siblings for a milestone's tasks), show them, and ask. A subtask goes to the bottom when placement is left out. A milestone always goes to the bottom of its project.
+
+children is a list of {name, assignees, status, priority, start_date, end_date, description, children}, one level below each parent, created in the order given. Children don't inherit assignees; name them. Everything is created or nothing is. One call makes at most 25 items, children included; split a bigger request. Example: {"parent":"alpha-4608","name":"Rotate the API keys","assignees":["Hassan"],"end_date":"2026-10-09","placement":{"position":"bottom"}}
+
+This app can't turn a task into a milestone or a subtask, or the other way round. Offer to create a new item and trash the old one instead.
+
+To show it: one sentence saying what was created, where, and for whom.`,
+    },
+    update_task: {
+        title: "Update task",
+        description: `Change one milestone, task, or subtask: name, status, priority, assignees, start_date, end_date, description. task is its alpha-ID. Pass only the fields to change. Statuses and priorities are names from get_workspace_info; priority "none" clears it. "Reopen" means the first not-started status unless the person names one. Dates are YYYY-MM-DD, or "none" to clear; "due" means end_date.
+
+Assignees change by add_assignees and remove_assignees, never by replacing the list, so people nobody mentioned stay. Only active members can be added; a bot or someone no longer in the workspace is refused. description replaces the whole text; to add a line, read it with get_task and send the full new text.
+
+When a milestone's new status or priority puts it in another section of a dev view, it goes to the bottom of that section; pass placement ({"position":"top"|"bottom"|"before"|"after","item":"alpha-N","view":"Hassan"}) to put it somewhere else. To reorder without changing a field, use place_task. To give it a new parent, use move_task. Example: {"task":"alpha-5201","status":"In Progress"}
+
+To show it: one sentence naming the item and what changed.`,
+    },
+    place_task: {
+        title: "Place task",
+        description: `Reorder one item without changing anything else. task is its alpha-ID. placement is {"position":"top"|"bottom"|"before"|"after","item":"alpha-N"}; before and after need an item in the same list.
+
+A task or subtask moves among its parent's children. That order is the same in every view. A task has no spot of its own in a dev view section: it sits under its milestone. If the person asks for a task at the top of someone's section, move the task to the top of its milestone, say so, and offer to move the milestone.
+
+A milestone moves inside its section of a dev view: pass "view" (the dev view or its person; default its first assignee's) and "group_by" ("status", the default, or "priority"). The two groupings keep separate orders; moving in one leaves the other alone. It stays in its section; to move it to another section, change its status or priority with update_task.
+
+"Make this the first thing Hassan works on" about a task is two calls: the task to the top of its milestone, then the milestone to the top of Hassan's section in the status grouping. Say both. Never choose a spot yourself: read the section with find_tasks (view, group_by, group, level=milestone, sort=view_order) or the milestone with get_task (include_siblings), show it, and ask. Example: {"task":"alpha-5201","placement":{"position":"bottom","view":"Hassan","group_by":"priority"}}
+
+To show it: one sentence saying where it is now.`,
+    },
+    move_task: {
+        title: "Move task",
+        description: `Give one milestone, task, or subtask a new parent at the same level: a milestone to another project, a task to another milestone, a subtask to another task. task is the item's alpha-ID; to is the new parent's alpha-ID. Its tasks and subtasks come with it. It lands at the bottom of the new parent; call place_task afterward if the person wants another spot. Its spots in dev views don't change.
+
+This app can't change an item's level: no task to subtask, task to milestone, or milestone to task. Those calls are refused; offer to create a new item and trash the old one instead. Example: {"task":"alpha-5201","to":"alpha-4356"}
+
+To show it: one sentence naming the item, where it was, and where it is now.`,
+    },
+    delete_task: {
+        title: "Delete task",
+        description: `Move a milestone, task, or subtask to the trash, in two calls. First call with task only: nothing changes, and you get a preview of everything the delete takes with it (tasks and subtasks under it, how many are still open) and what stays (timecards and their hours, comments, files, pull request links), plus a confirm_token. Show the person the whole preview in plain words and ask. Only after they say yes, call again with the same task and the confirm_token. Never confirm in the same turn as the preview, even if the person said "confirm" up front.
+
+The code works once, for that item only, for 10 minutes. If anything under the item changed since the preview, you get a new preview instead; show it and ask again. Trashed items can be restored by any member from Settings, Trash for 90 days. Restoring a milestone brings back the milestone only; its tasks are restored one by one. There is no permanent delete and no restore here. Example: {"task":"alpha-5201"} then {"task":"alpha-5201","confirm_token":"7QX2-M4KD"}
+
+To show it: the preview as a short list, then the question; after a confirm, one sentence.`,
+    },
+    add_comment: {
+        title: "Add comment",
+        description: `Post a comment on a task as the person whose key this is. task is the alpha-ID; text is the comment. To notify someone, put them in mentions (member names or user IDs) and write "@Hassan" where the mention goes; the app shows it as a tag and sends them a notification. People not in mentions are not notified beyond the task's usual comment notifications. Comments on a task in the trash are refused. Example: {"task":"alpha-5201","text":"@Hassan can you check this?","mentions":["Hassan"]}
+
+To show it: one sentence naming the task and anyone mentioned.`,
+    },
+    edit_comment: {
+        title: "Edit comment",
+        description: `Replace the text of a comment the person wrote. comment is the comment's id from get_task or find_comments; text is the full new text. Only the author can edit, and the old text is gone for good: there is no history. Edits don't notify anyone. Read the comment first and confirm the new wording if the person didn't give it exactly. Example: {"comment":"<id from get_task>","text":"keys rotate Saturday morning"}
+
+To show it: one sentence naming the task.`,
+    },
+    delete_comment: {
+        title: "Delete comment",
+        description: `Delete a comment for good. comment is the comment's id from get_task or find_comments. The author can delete their own; a workspace admin or owner can delete anyone's. It can't be restored, so quote the comment back and ask before deleting unless the person named that exact comment. Example: {"comment":"<id from get_task>"}
+
+To show it: one sentence naming the task, and that it can't be restored.`,
+    },
+    link_pull_request: {
+        title: "Link a pull request",
+        description: `Attach a GitHub pull request to one task so it shows on the task's PRs tab and badge. Pass the task's alpha-ID or Convex ID and the pull request URL (https://github.com/{owner}/{repo}/pull/{number}). The repository must be connected to this workspace under Settings > GitHub; otherwise the call fails with not_found.
+
+You usually do not need this: any pull request whose branch name, title, or body contains the task's alpha-ID (for example "alpha-482-fix-login") is linked automatically when it is opened. Use link_pull_request for a pull request that already existed before you knew the task, or whose text cannot mention the key. Linking is idempotent. Links made this way stay even if the PR title changes; they can be removed from the task's PRs tab. Example: {"task":"alpha-482","pull_request_url":"https://github.com/acme/app/pull/12"}
+
+To show it: one sentence naming the pull request and the task.`,
+    },
+};
+//# sourceMappingURL=descriptions.js.map

package/dist/descriptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptions.js","sourceRoot":"","sources":["../src/descriptions.ts"],"names":[],"mappings":"AAqBA,yIAAyI;AACzI,MAAM,CAAC,MAAM,YAAY,GAA6D;IACpF,UAAU,EAAE;QACV,KAAK,EAAE,YAAY;QACnB,WAAW,EAAE;;;;;;;;;;mJAUkI;KAChJ;IACD,QAAQ,EAAE;QACR,KAAK,EAAE,cAAc;QACrB,WAAW,EAAE;;;;oIAImH;KACjI;IACD,WAAW,EAAE;QACX,KAAK,EAAE,aAAa;QACpB,WAAW,EAAE;;;;+DAI8C;KAC5D;IACD,UAAU,EAAE;QACV,KAAK,EAAE,YAAY;QACnB,WAAW,EAAE;;uCAEsB;KACpC;IACD,aAAa,EAAE;QACb,KAAK,EAAE,eAAe;QACtB,WAAW,EAAE;;uCAEsB;KACpC;IACD,kBAAkB,EAAE;QAClB,KAAK,EAAE,gBAAgB;QACvB,WAAW,EAAE;;0DAEyC;KACvD;IACD,OAAO,EAAE;QACP,KAAK,EAAE,gBAAgB;QACvB,WAAW,EAAE;;;;yEAIwD;KACtE;IACD,cAAc,EAAE;QACd,KAAK,EAAE,gBAAgB;QACvB,WAAW,EAAE;;;;;;;;;;qEAUoD;KAClE;IACD,QAAQ,EAAE;QACR,KAAK,EAAE,UAAU;QACjB,WAAW,EAAE;;;;4CAI2B;KACzC;IACD,aAAa,EAAE;QACb,KAAK,EAAE,eAAe;QACtB,WAAW,EAAE;;;;;;;;;;6DAU4C;KAC1D;IACD,WAAW,EAAE;QACX,KAAK,EAAE,aAAa;QACpB,WAAW,EAAE;;;;;;;;uEAQsD;KACpE;IACD,WAAW,EAAE;QACX,KAAK,EAAE,aAAa;QACpB,WAAW,EAAE;;;;;;2DAM0C;KACxD;IACD,UAAU,EAAE;QACV,KAAK,EAAE,YAAY;QACnB,WAAW,EAAE;;;;;;;;iDAQgC;KAC9C;IACD,SAAS,EAAE;QACT,KAAK,EAAE,WAAW;QAClB,WAAW,EAAE;;;;6EAI4D;KAC1E;IACD,WAAW,EAAE;QACX,KAAK,EAAE,aAAa;QACpB,WAAW,EAAE;;;;2FAI0E;KACxF;IACD,WAAW,EAAE;QACX,KAAK,EAAE,aAAa;QACpB,WAAW,EAAE;;+DAE8C;KAC5D;IACD,YAAY,EAAE;QACZ,KAAK,EAAE,cAAc;QACrB,WAAW,EAAE;;0CAEyB;KACvC;IACD,cAAc,EAAE;QACd,KAAK,EAAE,gBAAgB;QACvB,WAAW,EAAE;;yEAEwD;KACtE;IACD,iBAAiB,EAAE;QACjB,KAAK,EAAE,qBAAqB;QAC5B,WAAW,EAAE;;;;+DAI8C;KAC5D;CACF,CAAC"}

package/dist/format.d.ts

@@ -0,0 +1,224 @@
+import { type TaskComments } from "./formatComments.js";
+export type TaskRef = {
+    id: string;
+    simple_id: string;
+    name: string;
+    level: string;
+};
+type Named = {
+    id: string;
+    name: string;
+};
+type RowView = {
+    id: string;
+    name: string;
+    type: string;
+};
+export type TaskRow = {
+    id: string;
+    simple_id: string;
+    name: string;
+    level: string;
+    status: {
+        value: string;
+        name: string;
+        type: string;
+    };
+    priority: {
+        value: string;
+        name: string;
+    } | null;
+    assignees: Named[];
+    start_date: string | null;
+    end_date: string | null;
+    completed_at: string | null;
+    view: RowView | null;
+    parent: TaskRef | null;
+    ancestors: TaskRef[];
+    position: {
+        index: number;
+        of: number;
+    } | null;
+    group: string | null;
+    child_count: number;
+    comment_count: number;
+};
+export type Scope = {
+    kind: "workspace";
+} | {
+    kind: "view";
+    id: string;
+    name: string;
+    type: string;
+};
+export type ListEnvelope = {
+    total: number;
+    returned: number;
+    has_more: boolean;
+    cursor: string | null;
+    hidden_closed: number;
+    hidden_archived: number;
+    truncated: boolean;
+    applied_filters: Record<string, unknown>;
+    scope: Scope;
+    sort: string;
+    rows: TaskRow[];
+    position_note?: string | null;
+};
+export type Candidate = {
+    id: string;
+    simple_id: string | null;
+    name: string;
+    type: string;
+    view_type?: string;
+    view_name: string | null;
+    parent_name: string | null;
+    detail: string | null;
+};
+export type ErrorShape = {
+    code: string;
+    message: string;
+    candidates?: Candidate[];
+    details?: unknown;
+};
+type ChildRef = TaskRef & {
+    child_count: number | null;
+    has_children: boolean | null;
+};
+type SiblingRef = TaskRef & {
+    is_self: boolean;
+};
+export type PullRequestRef = {
+    number: number;
+    title: string;
+    url: string;
+    state: string;
+    repo: string;
+    linked_via: string;
+};
+export type LinkPullRequestResult = {
+    task: TaskRef;
+    pull_request: PullRequestRef;
+};
+/** "Fix login -- open [acme/app#12](https://github.com/acme/app/pull/12)". */
+export declare function formatPullRequestLine(p: PullRequestRef): string;
+export declare function formatLinkPullRequest(r: LinkPullRequestResult): string;
+export type TaskDetail = TaskComments & {
+    task: TaskRow & {
+        description: string;
+        created_by: Named;
+        created_at: string;
+        updated_at: string;
+        estimated_hours: number | null;
+        actual_hours: number | null;
+        tags: string[];
+        custom_fields: {
+            column: string;
+            values: string[];
+        }[];
+        pull_requests: PullRequestRef[];
+    };
+    ancestors: TaskRef[];
+    view: (RowView & {
+        dev_view_assignee: Named | null;
+    }) | null;
+    position: {
+        index: number;
+        of: number;
+    } | null;
+    children: ChildRef[];
+    child_count: number;
+    hidden_closed: number;
+    hidden_archived: number;
+    siblings: SiblingRef[] | null;
+    siblings_hidden_closed: number;
+    siblings_hidden_archived: number;
+    position_note: string | null;
+};
+export type CountResult = {
+    total: number;
+    hidden_closed: number;
+    hidden_archived: number;
+    truncated: boolean;
+    applied_filters: Record<string, unknown>;
+    scope: Scope;
+    counts: {
+        key: string;
+        id: string | null;
+        name: string;
+        count: number;
+    }[];
+};
+export type ViewList = {
+    total: number;
+    rows: {
+        id: string;
+        name: string;
+        type: string;
+        dev_view_assignee: Named | null;
+        position: number;
+    }[];
+};
+export type WorkspaceInfo = {
+    workspace: Named;
+    user: Named;
+    members: {
+        id: string;
+        name: string;
+        email: string;
+        inactive?: boolean;
+    }[];
+    statuses: {
+        value: string;
+        name: string;
+        type: string;
+        order: number;
+    }[];
+    priorities: {
+        value: string;
+        name: string;
+        order: number;
+    }[];
+    archive_days: number;
+    today: string;
+    timezone: string;
+    limits: {
+        default_limit: number;
+        max_limit: number;
+    };
+    week_start: string;
+    former_members_with_time: {
+        id: string;
+        name: string;
+    }[];
+    unsupported: string[];
+};
+export type ResolveResult = {
+    type: string;
+    name: string;
+    id: string | null;
+    count: number;
+    candidates: Candidate[];
+    message: string;
+};
+type DateField = "end" | "start" | "completed";
+export type RowOptions = {
+    /** The assignee filter: a user ID, null for "nobody", undefined when the list isn't filtered by person. */
+    assigneeId?: string | null;
+    /** In a date sort, the sorted date goes first on the line. */
+    lead?: DateField;
+    /** Where the row sits, after the details: "parent" names a milestone or project parent, "full" also names the view of a top-level row. */
+    where?: "none" | "parent" | "full";
+};
+/** One task line: name -- details -- where, then the ID tail. No bullet. */
+export declare function formatRow(row: TaskRow, opts?: RowOptions): string;
+export declare function formatList(env: ListEnvelope, label: "Tasks" | "Projects", _limit?: number): string;
+export declare function formatTask(d: TaskDetail): string;
+export declare function formatCounts(r: CountResult): string;
+export declare function formatViews(r: ViewList): string;
+export declare function formatWorkspaceInfo(w: WorkspaceInfo): string;
+/** "- To Do -- in Inbox, under Roadmap, To Do [alpha-120]"; a person or view keeps its ID at the end. */
+export declare function candidateLine(c: Candidate): string;
+export declare function formatResolve(r: ResolveResult): string;
+export declare function formatError(e: ErrorShape): string;
+export {};