@skyelight/mcp 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog
+
+Notable changes to `@skyelight/mcp`. Dates are npm publish dates.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this package follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+What a version number means here: the tools are the interface. A **minor** is a
+new tool, a new argument, or a new field in a result — an agent that ignores it
+keeps working. A **patch** is a fix or a wording change. A **major** would be
+removing a tool or an argument, or changing what an existing field means, and
+there has not been one.
+
+## 0.4.1 — 2026-09-19
+
+### Fixed
+
+- **Two wrong permission claims in the README**, which is what npm serves on
+  the package page. It said a reviewer "reads and cannot write" — a reviewer
+  replies and raises items like every other role. It also said resolving stays
+  a person's call "for a thread you do not own", which read as a rule for
+  everyone; the actual rule touches only reviewers, who may move threads they
+  opened and nobody else's. Both are now taken from `convex/mcp/writes.ts`.
+- Documented the 0.4.0 tool surface, which the README had not caught up with:
+  the image blocks, merged duplicates, `assignee: "me"`, and the read ceiling.
+
+### Added
+
+- This changelog, and it ships in the package.
+
+## 0.4.0 — 2026-09-19
+
+Nine things the Skyelight web app had shown a person for months that the tool
+results did not carry.
+
+### Added
+
+- **`get_item` returns the pictures as pictures.** The screenshot taken when
+  the pin was left, and any images people attached to the thread, come back as
+  MCP `image` content blocks instead of links no agent tool can open. Capped at
+  four per call and 4MB each; anything skipped is named with its link and the
+  reason. The stdio transport fetches the storage URL, and the remote endpoint
+  reads its own storage directly.
+- **Merged duplicates leave the list**, and the item they were merged into
+  carries `reportCount`. Five reports of one problem used to read as five bugs.
+- **`list_workspaces` returns `you`** — the caller's own user id and name — and
+  `list_items` accepts `assignee: "me"`. "What is assigned to me" had no way to
+  be asked before.
+- **`get_item` carries `linear`**, naming the issue a thread was handed to and
+  who it was delegated to, so an agent stops starting work a Linear-hosted
+  agent is already finishing.
+- **`get_item` carries `attachments` and `reactions`.** Attachments cover the
+  thread and its replies, in reading order; reactions are counted by emoji
+  rather than listed one row per person.
+- **List rows use the classifier's one-line summary** where there is one, with
+  `excerptSource` saying whether the line is a machine summary or the
+  reporter's own words. Rows used to be the first 140 characters of whatever
+  somebody typed.
+- **The 2,000-item read ceiling states itself.** `capped` is set when it binds
+  and the narration calls the counts a floor rather than a total. The scan also
+  reads newest-first, so the items it keeps when it binds are the live ones.
+
+### Fixed
+
+- `set_status` returned a bare string where the server expected `{ text, data }`,
+  so a successful move answered with an empty content block and the model had
+  no way to tell it had worked.
+- `initialize` reported `0.1.0`. Both transports carried their own stale copy
+  of that literal while the package shipped 0.3.0. There is one `VERSION`
+  constant now, and a test asserts it matches `package.json`.
+- `status=deferred` was refused with a 400 by the API the stdio transport calls,
+  although every tool schema has offered `deferred` since it existed.
+
+## 0.3.0 — 2026-09-17
+
+### Added
+
+- Grok in the installer's client list, and a README that lists it.
+
+## 0.2.0 — 2026-09-09
+
+### Added
+
+- `npx @skyelight/mcp init` — finds the coding agent, registers the remote
+  server with it, and leaves sign-in to OAuth, so nothing is pasted and no key
+  is stored on disk.
+- The `ui://` item card, for clients that can render an MCP Apps resource. The
+  text result is complete on its own, so the card is strictly additive.
+
+## 0.1.4 — 2026-09-09
+
+### Added
+
+- The component that rendered the pinned element, where `@skyelight/build`
+  stamped it.
+
+## 0.1.3 — 2026-09-09
+
+### Added
+
+- Projects sort by real activity rather than by when the project record last
+  changed, so "anything new here?" gets a true answer.
+
+## 0.1.2 — 2026-09-08
+
+### Added
+
+- The source file and line behind a pin, and a repo permalink pinned to the
+  commit the page was built from.
+
+## 0.1.1 — 2026-09-08
+
+### Fixed
+
+- The README npm was serving.
+
+## 0.1.0 — 2026-09-08
+
+First release. An MCP server over stdio that reads the feedback people left on
+a running app — the thread, the page, the element they pointed at — and reports
+back on it (SKY-273).

package/README.md

@@ -83,21 +83,29 @@ Tools then default to that project and nobody has to pass an id. Without it,
 
 ## Tools
 
-| Tool              | What it is for                                                  |
-| ----------------- | --------------------------------------------------------------- |
-| `list_workspaces` | Which workspaces this credential can reach.                     |
-| `list_projects`   | The projects inside them, with the ids the other tools take.    |
-| `list_items`      | What is outstanding. Filter by page, type, status, assignee.    |
-| `search_items`    | Find items whose thread mentions some text, replies included.   |
-| `get_item`        | Everything needed to work one item: thread, page, anchor, code. |
-| `post_update`     | Report back on the thread the feedback came from.               |
-| `create_item`     | Raise a new item — an audit finding, something you noticed.     |
-| `set_status`      | Move an item to open, deferred or resolved.                     |
+| Tool              | What it is for                                                          |
+| ----------------- | ----------------------------------------------------------------------- |
+| `list_workspaces` | Which workspaces this credential can reach, and who you are.            |
+| `list_projects`   | The projects inside them, with the ids the other tools take.            |
+| `list_items`      | What is outstanding. Filter by page, type, status, assignee.            |
+| `search_items`    | Find items whose thread mentions some text, replies included.           |
+| `get_item`        | Everything needed to work one item: thread, page, anchor, code, images. |
+| `post_update`     | Report back on the thread the feedback came from.                       |
+| `create_item`     | Raise a new item — an audit finding, something you noticed.             |
+| `set_status`      | Move an item to open, deferred or resolved.                             |
 
 `list_items` leads with a summary — totals, breakdown by type and by page — so
 an agent can tell you the shape of the work before pulling any of it. Rows are
 stubs; `get_item` is where the thread and the anchor live.
 
+**"What is assigned to me."** `list_workspaces` returns your own user id, and
+`list_items` takes `assignee: "me"`, so the most ordinary question anyone asks
+an agent needs no id looked up by hand.
+
+**Merged duplicates do not appear twice.** When somebody merges five reports of
+one problem in the web app, the duplicates leave the list and the item they were
+merged into says `5 reports`. A list that shows all five reads as five bugs.
+
 ## What the agent sees
 
 ```
@@ -107,12 +115,40 @@ Busiest pages: /checkout (8), /settings (4).
 
 2 matches:
 - The pay button does nothing on the second click
-  bug · open · /checkout · unassigned · 2 replies — id i1
+  bug · open · /checkout · unassigned · 2 replies · 5 reports — id i1
 ```
 
 Deliberately prose rather than JSON. A tool that returns a bare array invites a
 model to read the array out; this one invites it to summarise.
 
+A row's line is the one-sentence summary Skyelight's classifier wrote, where
+there is one, rather than the first 140 characters of whatever somebody typed —
+four truncated paragraphs are not something you can choose between.
+
+One call reads the 2,000 most recent items in a project. Past that the result
+says so, in words, rather than presenting a slice as the total.
+
+### The pictures
+
+`get_item` returns the screenshot taken when the pin was left, and any images
+people attached to the thread, as **image content blocks** — things a model can
+actually look at, not links it cannot open.
+
+```
+Screenshot of the page when this was pinned: attached below.
+2 images attached to this thread: also below.
+```
+
+Capped at four per call. Anything too large to inline comes back as its link
+with the reason, so a picture never disappears silently.
+
+### What somebody else already did
+
+`get_item` also names the Linear issue a thread was handed to, and who it was
+delegated to, so an agent does not start work a Linear-hosted agent is
+finishing. Reactions come back counted by emoji — a thread with one comment and
+nine thumbs up is not a thread with one comment.
+
 ### Where the code is
 
 If the app was built with [`@skyelight/build`](https://www.npmjs.com/package/@skyelight/build),
@@ -146,8 +182,13 @@ reason. A personal token is the only credential the API accepts.
 The server enforces nothing; the API does. Whatever your account can do in the
 web app, the agent can do through your token, and nothing more:
 
-- A **reviewer** reads and cannot write.
+- **Owner, admin, collaborator and reviewer** all read and write — a reviewer
+  can reply on a thread and raise one, which is what a client seat is for.
+- A **reviewer** can only `set_status` on threads they opened themselves. Every
+  other role can move anyone's. It is the rule the web app already applies:
+  closing someone else's report is a decision about their report.
 - A **project-bound** credential answers 404 outside its project rather than
   reporting that something exists but is forbidden.
-- Resolving stays a person's call in the web app for a thread you do not own;
-  `set_status` obeys the same rule.
+- Workspaces your plan or seat does not cover are **listed and marked** rather
+  than hidden, with the reason, so a client can see the workspace they know
+  exists and be told which gate closed instead of being told it is missing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyelight/mcp",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "MCP server for Skyelight \u2014 read feedback items from your project as an agent",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
   "files": [
     "LICENSE",
     "README.md",
+    "CHANGELOG.md",
     "src"
   ],
   "engines": {

package/src/client.js

@@ -85,6 +85,15 @@ export function createClient({ apiUrl, token, fetchImpl = fetch }) {
   }
 
   return {
+    /**
+     * The fetch this client was built with, for the one thing that is not an
+     * API call: pulling a storage URL the API just handed us so its bytes can
+     * be returned as an image. Exposed rather than wrapped because it carries
+     * no bearer token — those links are their own credential, and attaching
+     * ours to an off-API request is how a token ends up somewhere it was
+     * never meant to go.
+     */
+    fetchImpl,
     listWorkspaces: () => request("/api/v1/workspaces"),
     listProjects: (params) => request("/api/v1/projects", params),
     listItems: (params) => request("/api/v1/items", params),

package/src/images.d.ts

@@ -0,0 +1,42 @@
+/** Types for images.js — see tools.d.ts for why declarations are shipped. */
+
+export interface TextBlock {
+  type: "text";
+  text: string;
+}
+
+export interface ImageBlock {
+  type: "image";
+  /** Base64, no data: prefix — what the MCP content block wants. */
+  data: string;
+  mimeType: string;
+}
+
+export type ContentBlock = TextBlock | ImageBlock;
+
+export declare const MAX_IMAGES: number;
+export declare const MAX_IMAGE_BYTES: number;
+
+export interface ImageSource {
+  url: string;
+  storageId: string | null;
+  label: string;
+}
+
+/** What a loader hands back: the bytes, or why there are none. */
+export type LoadedImage =
+  | { bytes: Uint8Array; mimeType?: string; skipped?: undefined }
+  | { skipped: string };
+
+export declare function imageSources(item: unknown): ImageSource[];
+
+export declare function imageBlocksFor(
+  item: unknown,
+  options?: {
+    /** Where the bytes come from. Defaults to fetching `source.url`. */
+    load?: (source: ImageSource) => Promise<LoadedImage>;
+    fetchImpl?: typeof fetch;
+    maxImages?: number;
+    maxBytes?: number;
+  },
+): Promise<ContentBlock[]>;

package/src/images.js

@@ -0,0 +1,193 @@
+/**
+ * Evidence, as something a model can actually look at.
+ *
+ * `get_item` used to print `Screenshot: https://…` and stop there. No agent
+ * tool turns a link into a picture, so the most expensive thing Skyelight
+ * captures — the state of the page at the moment somebody pinned it — reached
+ * nobody. The same was true of the images people attach themselves, which are
+ * frequently the whole diagnosis: the reply that says "here, look".
+ *
+ * MCP tool results are a LIST of content blocks and an image is one of them,
+ * so the fix is to fetch the bytes and hand them over as
+ * `{ type: "image", data, mimeType }`.
+ *
+ * Shared by both transports on purpose. The stdio package and the remote
+ * endpoint are two doors onto the same server, and an agent that can see a
+ * screenshot through one and not the other is the kind of difference nobody
+ * can debug from the outside.
+ */
+
+/**
+ * How many pictures one call may carry.
+ *
+ * A thread with a screenshot on every reply would otherwise put a dozen
+ * images into a single result. Four is the evidence capture plus the first
+ * few things people attached, which is where the information is — an
+ * eleventh screenshot of the same page has never changed a diagnosis.
+ */
+export const MAX_IMAGES = 4;
+
+/**
+ * The most one picture may weigh.
+ *
+ * Captures are JPEG at quality 0.85 and at most 2x device density, so a large
+ * viewport lands around a megabyte and nothing legitimate comes close to this.
+ * The cap is here for what people attach, which is arbitrary: somebody drags
+ * in a full-resolution phone screenshot and every subsequent call carries it.
+ *
+ * Over the line, the link is reported instead, with the size, so the reader
+ * knows a picture exists and why it is not here. Downscaling would be better
+ * and is not available: neither the dependency-free stdio package nor the
+ * Convex runtime has an image codec to re-encode with.
+ */
+export const MAX_IMAGE_BYTES = 4 * 1024 * 1024;
+
+/** Bytes to base64, in both runtimes this module is loaded into. */
+function toBase64(bytes) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(bytes).toString("base64");
+  }
+  // Convex runs a V8 isolate with no Buffer. `btoa` takes a binary string,
+  // and building one in chunks keeps the argument list to `fromCharCode`
+  // inside what a call stack will take.
+  let binary = "";
+  const CHUNK = 0x8000;
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    binary += String.fromCharCode.apply(
+      null,
+      Array.from(bytes.subarray(i, i + CHUNK)),
+    );
+  }
+  return btoa(binary);
+}
+
+/**
+ * The pictures on one item, in the order a reader wants them.
+ *
+ * Evidence first: it answers "what did this look like" without opening
+ * anything. Then what people attached, thread before replies, which is the
+ * order `attachments` already arrives in.
+ */
+export function imageSources(item) {
+  const sources = [];
+  if (item?.evidence?.screenshotUrl) {
+    sources.push({
+      url: item.evidence.screenshotUrl,
+      storageId: item.evidence.screenshotStorageId ?? null,
+      label: "The page when this was pinned:",
+    });
+  }
+  for (const a of item?.attachments ?? []) {
+    if (!a?.url) continue;
+    sources.push({
+      url: a.url,
+      storageId: a.storageId ?? null,
+      label: `Attached by ${a.author ?? "someone"}${
+        a.where === "reply" ? ", on a reply" : ""
+      }:`,
+    });
+  }
+  return sources;
+}
+
+/**
+ * The default loader: pull the storage URL over HTTP.
+ *
+ * What the stdio package has to do, because the bytes are on the other side
+ * of the network from it. The remote endpoint runs inside the deployment that
+ * holds them and passes its own loader instead — see `load` below.
+ */
+function httpLoader(fetchImpl) {
+  return async (source) => {
+    let res;
+    try {
+      res = await fetchImpl(source.url);
+    } catch (err) {
+      return { skipped: `could not be fetched (${err.message})` };
+    }
+    if (!res.ok) return { skipped: `could not be fetched (${res.status})` };
+    const mimeType = (res.headers?.get?.("content-type") ?? "")
+      .split(";")[0]
+      .trim();
+    return { bytes: new Uint8Array(await res.arrayBuffer()), mimeType };
+  };
+}
+
+/**
+ * Content blocks to append after `get_item`'s text.
+ *
+ * Each picture is introduced by a line saying what it is, because four
+ * unlabelled images of the same application are four things a reader has to
+ * work out. Anything that could not be inlined comes back as a closing note
+ * with its link, so a picture never disappears silently.
+ *
+ * Never throws. A screenshot that will not load is a worse work order, not a
+ * failed tool call — the thread, the anchor and the source line are all still
+ * in the text block above it.
+ *
+ * `load` is how the bytes arrive. It is injected because the two transports
+ * are in different places relative to the file: the stdio package is across a
+ * network and fetches the URL, and the remote endpoint is inside the
+ * deployment that stores it and reads it straight out of storage. Everything
+ * after that — the labels, the size ceiling, the cap, the notes — is one code
+ * path, which is the only way the two doors keep answering the same.
+ */
+export async function imageBlocksFor(item, options = {}) {
+  const {
+    fetchImpl = fetch,
+    load,
+    maxImages = MAX_IMAGES,
+    maxBytes = MAX_IMAGE_BYTES,
+  } = options;
+  const loader = load ?? httpLoader(fetchImpl);
+
+  const sources = imageSources(item);
+  if (sources.length === 0) return [];
+
+  const blocks = [];
+  const notes = [];
+  for (const source of sources.slice(0, maxImages)) {
+    let got;
+    try {
+      got = await loader(source);
+    } catch (err) {
+      got = { skipped: `could not be read (${err.message})` };
+    }
+
+    // Storage serves what was uploaded. Anything that is not an image is a
+    // misfiled attachment, and a non-image in an image block fails at the
+    // client rather than here, which is a worse place to find out.
+    if (!got.skipped && got.mimeType && !got.mimeType.startsWith("image/")) {
+      got = { skipped: `is not an image (${got.mimeType})` };
+    }
+    if (!got.skipped && got.bytes.byteLength > maxBytes) {
+      got = {
+        skipped:
+          `is ${Math.round(got.bytes.byteLength / 1024)}KB, over the ` +
+          `${Math.round(maxBytes / 1024)}KB limit for an inline image`,
+      };
+    }
+
+    if (got.skipped) {
+      notes.push(`${source.label} ${source.url} — ${got.skipped}.`);
+      continue;
+    }
+    blocks.push({ type: "text", text: source.label });
+    blocks.push({
+      type: "image",
+      data: toBase64(got.bytes),
+      mimeType: got.mimeType || "image/jpeg",
+    });
+  }
+
+  const overflow = sources.length - maxImages;
+  if (overflow > 0) {
+    notes.push(
+      `${overflow} more image${overflow === 1 ? "" : "s"} on this thread, not shown.`,
+    );
+  }
+  if (notes.length > 0) {
+    blocks.push({ type: "text", text: notes.join("\n") });
+  }
+  return blocks;
+}

package/src/server.js

@@ -13,6 +13,7 @@
 
 import { toolDefinitions, callTool } from "./tools.js";
 import { ApiError } from "./client.js";
+import { VERSION } from "./version.js";
 import {
   ITEM_CARD_URI,
   clientSupportsUi,
@@ -80,7 +81,7 @@ export function createServer({ client, config, name = "skyelight" }) {
           result = {
             protocolVersion: negotiateProtocolVersion(params?.protocolVersion),
             capabilities: { tools: {}, resources: {} },
-            serverInfo: { name, version: "0.1.0" },
+            serverInfo: { name, version: VERSION },
             instructions:
               "Skyelight holds feedback people left directly on pages of a running app. " +
               "list_items to see what is outstanding, get_item for the full thread and the " +
@@ -106,7 +107,10 @@ export function createServer({ client, config, name = "skyelight" }) {
             return {
               jsonrpc: "2.0",
               id,
-              error: { code: -32602, message: `Unknown resource: ${params?.uri}` },
+              error: {
+                code: -32602,
+                message: `Unknown resource: ${params?.uri}`,
+              },
             };
           }
           result = { contents: [itemCardContents()] };
@@ -115,12 +119,19 @@ export function createServer({ client, config, name = "skyelight" }) {
         case "tools/call": {
           const { name: toolName, arguments: args = {} } = params ?? {};
           try {
-            const { text, data } = await callTool(toolName, args, {
+            const {
+              text,
+              data,
+              content: extra,
+            } = await callTool(toolName, args, {
               client,
               config,
             });
             result = {
-              content: [{ type: "text", text }],
+              // A tool result is a LIST of blocks. `get_item` uses the rest
+              // of it for images; everything else returns the one block it
+              // always did.
+              content: [{ type: "text", text }, ...(extra ?? [])],
               structuredContent: data,
             };
           } catch (err) {
@@ -144,7 +155,10 @@ export function createServer({ client, config, name = "skyelight" }) {
           return {
             jsonrpc: "2.0",
             id,
-            error: { code: METHOD_NOT_FOUND, message: `Unknown method: ${method}` },
+            error: {
+              code: METHOD_NOT_FOUND,
+              message: `Unknown method: ${method}`,
+            },
           };
       }
 
@@ -185,7 +199,10 @@ function toolErrorText(err) {
  * Wire a server to a byte stream. Split on newlines and ignore blank lines;
  * a partial line is held until the rest arrives.
  */
-export function serveStdio(server, { input = process.stdin, output = process.stdout } = {}) {
+export function serveStdio(
+  server,
+  { input = process.stdin, output = process.stdout } = {},
+) {
   let buffer = "";
 
   input.setEncoding?.("utf8");

package/src/tools.d.ts

@@ -40,6 +40,11 @@ export declare function callTool(
   name: string,
   args: Record<string, unknown>,
   deps: { client: unknown; config: { projectId?: string | null } },
-): Promise<{ text: string; data: unknown }>;
+): Promise<{
+  text: string;
+  data: unknown;
+  /** Blocks to append after the text. `get_item` returns images here. */
+  content?: import("./images.js").ContentBlock[];
+}>;
 
 export declare const PROJECT_HINT: string;

package/src/tools.js

@@ -7,6 +7,8 @@
  * still attached for anything that wants to compute on it.
  */
 
+import { imageBlocksFor } from "./images.js";
+
 const PROJECT_HINT =
   'No project. Pass projectId, or add .skyelight.json with {"projectId": "..."}.';
 
@@ -35,9 +37,9 @@ export function toolDefinitions(opts = {}) {
     {
       name: "list_workspaces",
       description:
-        "Workspaces you can reach, with the role you hold in each. Use when " +
-        "you do not know what exists yet, or to find which workspace a " +
-        "project belongs to.",
+        "Workspaces you can reach, with the role you hold in each, and who " +
+        "you are. Use when you do not know what exists yet, to find which " +
+        "workspace a project belongs to, or to learn your own user id.",
       inputSchema: { type: "object", properties: {} },
     },
     {
@@ -85,7 +87,9 @@ export function toolDefinitions(opts = {}) {
           },
           assignee: {
             type: "string",
-            description: 'A user id, or "none" for unassigned items.',
+            description:
+              'A user id, "me" for whoever this connection belongs to, or ' +
+              '"none" for unassigned items.',
           },
           limit: { type: "number", description: "Max items (default 50)." },
         },
@@ -185,7 +189,9 @@ export function toolDefinitions(opts = {}) {
       name: "get_item",
       description:
         "Everything needed to work one item: the whole thread in order, the page and URL it is " +
-        "on, and the anchor identifying the element the person pointed at.",
+        "on, the anchor identifying the element the person pointed at, and the pictures \u2014 " +
+        "what the page looked like when it was pinned, plus anything people attached \u2014 " +
+        "returned as images you can look at rather than links you cannot.",
       inputSchema: {
         type: "object",
         properties: {
@@ -216,12 +222,25 @@ function topBreakdown(counts, limit = 3) {
  * array out, and a model handed a sentence summarises.
  */
 export function renderWorkspaces(result) {
-  const { workspaces, total } = result;
+  const { workspaces, total, you } = result;
+  const lines = [];
+
+  // First, because it is the answer to a question nothing else here can
+  // answer, and the id below is what `list_items` wants as `assignee`.
+  if (you) {
+    lines.push(
+      you.name ? `You are ${you.name} — ${you.id}.` : `You are ${you.id}.`,
+    );
+    lines.push('Pass "me" as assignee to list_items to see your own work.');
+    lines.push("");
+  }
+
   if (total === 0) {
-    return "You are not a member of any workspace yet.";
+    lines.push("You are not a member of any workspace yet.");
+    return lines.join("\n");
   }
 
-  const lines = [`${plural(total, "workspace", "workspaces")} you can reach:`];
+  lines.push(`${plural(total, "workspace", "workspaces")} you can reach:`);
   lines.push("");
   for (const w of workspaces) {
     const projects = plural(w.projectCount, "project", "projects");
@@ -279,7 +298,8 @@ export function renderProjects(result) {
 }
 
 export function renderList(result, { searched } = {}) {
-  const { project, summary, items, matched, truncated } = result;
+  const { project, summary, items, matched, truncated, capped, scanLimit } =
+    result;
   const lines = [];
 
   lines.push(
@@ -288,6 +308,17 @@ export function renderList(result, { searched } = {}) {
       `${summary.resolved} resolved, ${summary.unassigned} unassigned.`,
   );
 
+  // Said immediately after the counts, because it is what those counts mean.
+  // A floor stated as a total is the kind of wrong nobody catches: the number
+  // looks like every other number this tool has ever returned.
+  if (capped) {
+    lines.push(
+      `Those counts are a floor, not a total: this project is larger than ` +
+        `the ${(scanLimit ?? 2000).toLocaleString("en-US")} most recent items ` +
+        `one call reads. Filter by page, type or status for an exact count.`,
+    );
+  }
+
   const byType = topBreakdown(summary.byType);
   if (byType) lines.push(`By type: ${byType}.`);
   const byPage = topBreakdown(summary.byPage);
@@ -315,6 +346,10 @@ export function renderList(result, { searched } = {}) {
     if (i.assignee) bits.push(`assigned to ${i.assignee}`);
     else bits.push("unassigned");
     if (i.replyCount > 0) bits.push(plural(i.replyCount, "reply", "replies"));
+    // How many people hit this, once merging has told us they are the same
+    // thing. Silent at 1, which is almost every row — a list where every line
+    // ends in "1 report" has spent its width saying nothing.
+    if (i.reportCount > 1) bits.push(`${i.reportCount} reports`);
     lines.push(`- ${i.excerpt}`);
     lines.push(`  ${bits.join(" · ")} — id ${i.id}`);
   }
@@ -341,6 +376,32 @@ export function renderItem(item) {
   // line below, and that is the half an agent cannot work out for itself.
   const repo = item.project && item.project.repo;
   if (repo) lines.push(`Code: ${repo.url}`);
+
+  // Before anything else worth reading: this thread is not the one to work.
+  // Everything below still describes it faithfully, and acting on it would
+  // put the answer where nobody is looking.
+  if (item.duplicateOf) {
+    lines.push(
+      `Merged as a duplicate of item ${item.duplicateOf}. Work that one — ` +
+        `a reply here will not reach the thread people are following.`,
+    );
+  } else if (item.reportCount > 1) {
+    lines.push(
+      `${item.reportCount} people reported this ` +
+        `(${item.reportCount - 1} merged into it).`,
+    );
+  }
+
+  // Who else is already on it. An agent that starts work a Linear-hosted
+  // agent is finishing produces a second answer nobody asked for, and the
+  // first anyone hears of it is a duplicate branch.
+  for (const l of item.linear ?? []) {
+    const handed = l.delegateName
+      ? ` — handed to ${l.delegateName}${l.delegatedMode ? `, asked to ${l.delegatedMode}` : ""}`
+      : "";
+    lines.push(`Linear: ${l.identifier}${handed}. ${l.url}`);
+  }
+
   if (item.assignee?.name) {
     // The mode is the ask. An agent that reads "investigate" and opens a
     // pull request has done the wrong job well.
@@ -369,12 +430,31 @@ export function renderItem(item) {
     }
   }
 
-  // Stated before the anchor: a screenshot answers "what did this look like"
-  // in one step, where a selector needs the page opened first.
+  // How many people felt strongly enough to say so without writing a reply.
+  // A thread with one comment and nine thumbs up is not a thread with one
+  // comment, and nothing here said so.
+  if (item.reactions?.length) {
+    lines.push("");
+    lines.push(
+      `Reactions: ${item.reactions
+        .map((r) => `${r.emoji} ${r.count}`)
+        .join(", ")}.`,
+    );
+  }
+
+  // Stated before the anchor: a picture answers "what did this look like" in
+  // one step, where a selector needs the page opened first.
+  //
+  // The URL is deliberately not here. These arrive as image blocks after this
+  // text, which is the point of the change — and a link that has already been
+  // honoured is a line a reader has to decide about for nothing. When one
+  // cannot be fetched, the block builder says so and prints the link then.
   if (item.evidence) {
     if (item.evidence.screenshotUrl) {
       lines.push("");
-      lines.push(`Screenshot: ${item.evidence.screenshotUrl}`);
+      lines.push(
+        "Screenshot of the page when this was pinned: attached below.",
+      );
     } else if (item.evidence.expired) {
       lines.push("");
       lines.push(
@@ -383,6 +463,13 @@ export function renderItem(item) {
     }
   }
 
+  if (item.attachments?.length) {
+    const n = item.attachments.length;
+    lines.push(
+      `${plural(n, "image", "images")} attached to this thread: also below.`,
+    );
+  }
+
   lines.push("");
   lines.push("They were pointing at:");
   // elementText first: it is what a person would have named, and the one
@@ -560,15 +647,28 @@ export async function callTool(name, args, { client, config }) {
       status: args.status,
     });
     if (res?.error) throw new Error(res.error);
-    return res.changed
-      ? `Moved to ${res.status}.`
-      : `Already ${res.status} — nothing to do.`;
+    // `{ text, data }` like every other tool. It used to return a bare
+    // string, which the stdio server destructured into `text: undefined` —
+    // so a successful set_status answered with an empty content block and
+    // the model had no way to tell it had worked.
+    return {
+      text: res.changed
+        ? `Moved to ${res.status}.`
+        : `Already ${res.status} — nothing to do.`,
+      data: res,
+    };
   }
 
   if (name === "get_item") {
     if (!args.itemId) throw new Error("get_item needs an itemId");
     const item = await client.getItem(args.itemId);
-    return { text: renderItem(item), data: item };
+    return {
+      text: renderItem(item),
+      data: item,
+      // The pictures, as pictures. Appended after the text so the work order
+      // still reads top-down, and empty whenever there is nothing to show.
+      content: await imageBlocksFor(item, { fetchImpl: client.fetchImpl }),
+    };
   }
 
   throw new Error(`Unknown tool: ${name}`);

package/src/version.d.ts

@@ -0,0 +1,3 @@
+/** Types for version.js — see tools.d.ts for why declarations are shipped. */
+
+export declare const VERSION: string;

package/src/version.js

@@ -0,0 +1,15 @@
+/**
+ * One version number, read by everything that reports one.
+ *
+ * `initialize` used to answer `0.1.0` from a literal in `server.js` while the
+ * package on npm was 0.3.0, and the remote endpoint had its own copy of the
+ * same stale literal. A client that logs the server version — or a person
+ * reading it to work out which build they are talking to — was told something
+ * that had not been true for two releases.
+ *
+ * A constant rather than a read of `package.json`, because this module is
+ * bundled into the Convex deployment for the remote endpoint and there is no
+ * filesystem there. `test/server.test.js` asserts the two agree, so the pair
+ * cannot drift again without a test going red.
+ */
+export const VERSION = "0.4.1";