@threahq/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @threahq/cli
 
-`threa` is a command-line client for one Threa workspace. It wraps Threa's public REST API so any local agent or script gets workspace access with one API key: read and search streams, users, messages, conversations, memos, and attachments; send, edit, and delete messages; manage labels; and run the delegation lifecycle end to end.
+`threa` is a command-line client for one Threa workspace. It wraps Threa's public REST API so any local agent or script gets workspace access with one API key: read and search streams, users, messages, conversations, memos, and attachments; send, edit, and delete messages; upload attachments; manage labels; and run the delegation lifecycle end to end.
 
 It is one package with two heads. The command-line interface is the primary head. The same core is also served over the Model Context Protocol with `threa mcp serve`, so an MCP client such as Claude Code can call the same operations as tools. Both heads bind to one workspace and one API key from config, so no command and no tool takes a workspace id. There are no WebSockets; every call goes to `<baseUrl>/api/v1/workspaces/{workspaceId}/…`.
 
@@ -64,11 +64,13 @@ threa whoami                                        # authenticated principal, a
 threa streams list --type channel --query eng       # list accessible streams (page with --after)
 threa streams read #eng --members --limit 20        # a stream plus a page of its messages
 threa streams archive stream_abc                     # archive a stream; unarchive reopens it
+threa streams list --archived                       # include archived streams, marked [archived]
 threa users list --query alice                      # workspace users
 threa search "deploy plan" --what messages          # search messages (--semantic, --exact, --type)
 threa search "" --what memos --knowledge-type decision   # browse workspace memory (empty query allowed)
 threa search invoice --what attachments             # search attachments by name or extracted text
 threa conversations list --stream #eng --status active
+threa conversations list --stream stream_abc --archived   # include conversations in archived streams
 threa conversations read conv_123 --limit 50
 threa messages find-by-metadata github.pr=org/repo#42 --stream #eng
 threa memos list --stream #eng                      # browse recent memos, newest first
@@ -76,6 +78,7 @@ threa memos get memo_123
 threa attachments list --stream #eng                # browse recent attachments, newest first
 threa attachments get att_123 --url                 # --url returns a short-lived signed download URL
 threa attachments download att_123 ./               # download bytes; dir dest names it after the file
+threa attachments upload ./report.csv               # upload a file; reference it as [report.csv](attachment:<id>)
 threa skill print                                   # print the threa-cli agent skill to stdout
 
 # writes
@@ -112,6 +115,8 @@ threa mcp serve
 
 Any stream argument (`streams read`, `messages send`, `labels add`, `labels remove`, `search --stream`, `conversations list --stream`, `messages find-by-metadata --stream`) accepts a `stream_…` id or a `#channel-slug`. An `@user-slug` is not resolvable as a stream (a DM hides its counterpart on the wire); pass the DM's `stream_…` id. A ref that matches nothing or is ambiguous fails before any API call with code `UNRESOLVED_REF`.
 
+An archived stream stays readable to any key that could read it before. `streams read`, `conversations read`, and `search` work on it and on any thread under it; a send, edit, or delete there fails with code `STREAM_READ_ONLY`. By default `streams list` leaves out archived streams and their threads, and `conversations list` leaves out the conversations in those streams. With `--archived`, both commands include those rows, which print `[archived]` and carry `archived: true` in JSON. A `#channel-slug` does not resolve an archived channel (the ref fails with `UNRESOLVED_REF`), so pass the `stream_…` id that `streams list --archived` shows.
+
 `messages send` and `messages edit` take content as an argument; `messages send` reads stdin when the content argument is `-`. `delegations finish --result -` also reads the result markdown from stdin.
 
 Once a key is unlocked, `streams read` and `messages send` work on an end-to-end-encrypted stream (a scratchpad or one of its threads) the same way they do on a plaintext one. A read opens each body locally, so what prints is the message rather than the opaque placeholder the server stores; a body sealed to a key generation you were never wrapped to keeps a null `content` and says why, costing you that row and not the page. A send checks the stream first and seals the body under the stream key before anything leaves the machine — the plaintext is never posted, not even once to be rejected. Both take `--key-store` and `--key-dir`. With no key unlocked here, each fails and names `threa e2e unlock` instead of falling back to plaintext. A sealed stream carries no `--metadata` and no conversation: both would travel in the clear, so they are refused rather than dropped.
@@ -186,6 +191,7 @@ The scopes on the key decide which areas work. A key without a scope does not ge
 | `messages:write`    | `messages send`, `messages edit`, `messages delete`                                                                  |
 | `memos:read`        | `search --what memos`, `memos list`, `memos get`                                                                     |
 | `attachments:read`  | `search --what attachments`, `attachments list`, `attachments get`, `attachments download`                           |
+| `attachments:write` | `attachments upload`                                                                                                 |
 | `labels:read`       | `labels list`                                                                                                        |
 | `labels:write`      | `labels add`, `labels remove`                                                                                        |
 | `delegations:read`  | `delegations list`, `delegations get`                                                                                |

package/cli.js

@@ -441,6 +441,7 @@ function assertSafeBaseUrl(baseUrl) {
 
 // src/api-client.ts
 var FETCH_TIMEOUT_MS = 30000;
+var UPLOAD_MIN_BYTES_PER_MS = 256;
 var RETRY_DELAYS_MS = [2000, 4000, 8000];
 function deriveHint(status) {
   if (status === 404) {
@@ -482,23 +483,30 @@ class ThreaApiClient {
     return this.request("GET", path);
   }
   post(path, body, headers) {
-    return this.request("POST", path, body, headers);
+    return this.request("POST", path, body === undefined ? undefined : { json: body }, headers);
+  }
+  postForm(path, form, bodyBytes) {
+    return this.request("POST", path, { form }, undefined, {
+      timeoutMs: this.timeoutMs + Math.ceil(bodyBytes / UPLOAD_MIN_BYTES_PER_MS)
+    });
   }
   patch(path, body) {
-    return this.request("PATCH", path, body);
+    return this.request("PATCH", path, body === undefined ? undefined : { json: body });
   }
   delete(path) {
     return this.request("DELETE", path);
   }
+  getRaw(path) {
+    return this.request("GET", path, undefined, undefined, { raw: true });
+  }
   workspacePath(path) {
     return `${this.baseUrl}/api/v1/workspaces/${this.workspaceId}${path}`;
   }
-  async request(method, path, body, extraHeaders) {
+  async request(method, path, payload, extraHeaders, { raw = false, timeoutMs = this.timeoutMs } = {}) {
     const url = this.workspacePath(path);
-    const hasBody = body !== undefined;
     for (let attempt = 0;; attempt++) {
       const controller = new AbortController;
-      const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+      const timeout = setTimeout(() => controller.abort(), timeoutMs);
       let retryAfter429 = false;
       try {
         const response = await fetch(url, {
@@ -506,10 +514,10 @@ class ThreaApiClient {
           signal: controller.signal,
           headers: {
             Authorization: `Bearer ${this.apiKey}`,
-            ...hasBody ? { "Content-Type": "application/json" } : {},
+            ...payload && "json" in payload ? { "Content-Type": "application/json" } : {},
             ...extraHeaders ?? {}
           },
-          ...hasBody ? { body: JSON.stringify(body) } : {}
+          ...payload ? { body: "json" in payload ? JSON.stringify(payload.json) : payload.form } : {}
         });
         if (response.status === 429 && attempt < RETRY_DELAYS_MS.length) {
           retryAfter429 = true;
@@ -517,6 +525,8 @@ class ThreaApiClient {
           if (!response.ok) {
             throw await this.toError(response);
           }
+          if (raw)
+            return response;
           if (response.status === 204)
             return;
           return await response.json();
@@ -526,7 +536,7 @@ class ThreaApiClient {
           throw new ThreaApiError({
             status: 0,
             code: "TIMEOUT",
-            message: `Threa API ${method} ${path} timed out after ${this.timeoutMs}ms`
+            message: `Threa API ${method} ${path} timed out after ${timeoutMs}ms`
           });
         }
         throw error;
@@ -936,7 +946,10 @@ class TokenStore {
 }
 
 // src/commands/attachments.ts
-import { existsSync as existsSync3, statSync, writeFileSync as writeFileSync3 } from "node:fs";
+import { createWriteStream, existsSync as existsSync3, rmSync as rmSync2, statSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { once } from "node:events";
+import { finished } from "node:stream/promises";
 import { basename, extname, join as join5 } from "node:path";
 
 // src/enrich.ts
@@ -1150,7 +1163,13 @@ async function findMessagesByMetadata(client, resolver, p) {
 }
 async function listConversations(client, resolver, p) {
   const streamId = p.streamRef ? await resolver.resolveStream(p.streamRef) : undefined;
-  const response = await client.get(`/conversations${buildQuery({ streamId, status: p.status, after: p.cursor, limit: p.limit })}`);
+  const response = await client.get(`/conversations${buildQuery({
+    streamId,
+    status: p.status,
+    after: p.cursor,
+    limit: p.limit,
+    includeArchived: p.includeArchived ? "true" : undefined
+  })}`);
   const withParticipants = await Promise.all(response.data.map((c) => enrichConversation(c, resolver)));
   return { ...response, data: await enrichStreamContext(withParticipants, resolver) };
 }
@@ -1173,12 +1192,23 @@ async function readConversation(client, resolver, p) {
 function getMemo(client, memoId) {
   return client.get(`/memos/${encodeURIComponent(memoId)}`);
 }
+function recallMemos(client, query) {
+  return client.post("/memos/recall", { query });
+}
 function getAttachment(client, attachmentId) {
   return client.get(`/attachments/${encodeURIComponent(attachmentId)}`);
 }
 function getAttachmentDownloadUrl(client, attachmentId) {
   return client.get(`/attachments/${encodeURIComponent(attachmentId)}/url`);
 }
+function getAttachmentContent(client, attachmentId) {
+  return client.getRaw(`/attachments/${encodeURIComponent(attachmentId)}/content`);
+}
+function uploadAttachment(client, file, filename) {
+  const form = new FormData;
+  form.append("file", file, filename);
+  return client.postForm("/attachments", form, file.size);
+}
 var SEARCH_WHATS = ["messages", "memos", "attachments"];
 var ALLOWED_FILTERS = {
   messages: ["query", "semantic", "exact", "stream_ids", "type", "before", "after", "limit"],
@@ -1416,8 +1446,10 @@ var searchCommand = {
 ` + `  --what w         messages | memos | attachments (required)
 ` + `  --stream ref     limit to a source stream (stream_ id or #slug); repeatable
 ` + `  --limit n        max results (messages/attachments <= 50, memos <= 100; default 20)
-` + `  --before iso     only results before this ISO-8601 datetime (messages and memos only)
-` + `  --after iso      only results after this ISO-8601 datetime (messages and memos only)
+` + `  --before iso     only results before this ISO-8601 datetime (messages and memos only; memos by when
+` + `                   their source messages were posted)
+` + `  --after iso      only results after this ISO-8601 datetime (messages and memos only; memos by when
+` + `                   their source messages were posted)
 ` + "messages: --semantic  --exact  --type " + STREAM_TYPES.join("|") + ` (repeatable)
 ` + "memos:    --exact  --memo-type " + MEMO_TYPES.join("|") + " (repeatable)  --knowledge-type " + KNOWLEDGE_TYPES.join("|") + " (repeatable)  --tag t (repeatable)  --scope " + MEMO_SCOPES.join("|") + `
 ` + "attachments: --content-type " + EXTRACTION_CONTENT_TYPES.join("|") + ` (repeatable)
@@ -1525,7 +1557,7 @@ function renderMemoResult(r) {
   const header = joinFields([
     String(memo.id ?? "?"),
     typeof memo.knowledgeType === "string" ? memo.knowledgeType : undefined,
-    fmtTimestamp(memo.createdAt),
+    fmtTimestamp(memo.latestSourceAt),
     scopeLabel || undefined
   ]);
   const title = typeof memo.title === "string" ? memo.title : "";
@@ -1606,13 +1638,38 @@ function resolveDownloadTarget(destination, filename) {
   }
   return candidate;
 }
+var DOWNLOAD_IDLE_MS = 30000;
+async function saveDownload(body, target, idleMs = DOWNLOAD_IDLE_MS) {
+  const reader = body.getReader();
+  const out = createWriteStream(target);
+  try {
+    for (;; ) {
+      let timer;
+      const stalled = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`download stalled: no bytes for ${idleMs}ms`)), idleMs);
+      });
+      const chunk = await Promise.race([reader.read(), stalled]).finally(() => clearTimeout(timer));
+      if (chunk.done)
+        break;
+      if (!out.write(chunk.value))
+        await once(out, "drain");
+    }
+    out.end();
+    await finished(out);
+  } catch (error) {
+    reader.cancel().catch(() => {});
+    out.destroy();
+    rmSync2(target, { force: true });
+    throw error;
+  }
+}
 var downloadVerb = {
   name: "download",
   summary: "Download an attachment's raw bytes to a local file",
   usage: "threa attachments download <id> [destination]",
   help: `threa attachments download <id> [destination] [flags]
 
-` + "Download the attachment's raw bytes via its signed URL. destination defaults to the current directory. " + "A directory destination names the file after the attachment and picks `name (1).ext` on conflict; an " + `explicit file path is written as given (overwriting).
+` + "Download the attachment's raw bytes. destination defaults to the current directory. " + "A directory destination names the file after the attachment and picks `name (1).ext` on conflict; an " + `explicit file path is written as given (overwriting).
 
 ` + `Flags:
 ` + `  --json    force JSON output
@@ -1622,37 +1679,78 @@ var downloadVerb = {
     const id = positionals[0];
     if (!id)
       throw new UsageError("attachments download requires a <id> (an att_ id)");
-    const [meta, urlResp] = await Promise.all([
+    const [meta, response] = await Promise.all([
       getAttachment(ctx.client, id),
-      getAttachmentDownloadUrl(ctx.client, id)
+      getAttachmentContent(ctx.client, id)
     ]);
-    const url = urlResp.data?.url;
-    if (!url)
-      throw new Error(`no download URL returned for ${id}`);
+    if (!response.body)
+      throw new Error(`download failed: empty body for ${id}`);
     const target = resolveDownloadTarget(positionals[1] ?? ".", meta.data?.filename ?? id);
-    const response = await fetch(url);
-    if (!response.ok)
-      throw new Error(`download failed: HTTP ${response.status}`);
-    const bytes = new Uint8Array(await response.arrayBuffer());
-    writeFileSync3(target, bytes);
-    return { downloaded: true, id, path: target, sizeBytes: bytes.byteLength };
+    await saveDownload(response.body, target);
+    return { downloaded: true, id, path: target, sizeBytes: statSync(target).size };
   },
   render: (payload) => {
     const p = payload;
     return `downloaded ${p.id ?? "?"} → ${p.path ?? "?"} (${p.sizeBytes ?? 0} bytes)`;
   }
 };
+var MIME_BY_EXTENSION = {
+  ".csv": "text/csv",
+  ".tsv": "text/tab-separated-values",
+  ".txt": "text/plain",
+  ".md": "text/markdown",
+  ".html": "text/html",
+  ".json": "application/json",
+  ".pdf": "application/pdf",
+  ".zip": "application/zip",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".svg": "image/svg+xml"
+};
+var uploadVerb = {
+  name: "upload",
+  summary: "Upload a local file as an attachment",
+  usage: "threa attachments upload <path> [--name filename] [--type mime]",
+  help: `threa attachments upload <path> [flags]
+
+` + "Upload a file and print its attachment id. Reference it in message markdown as `[name](attachment:<id>)` " + `to attach it. The content type is guessed from the extension, else application/octet-stream.
+
+` + `Flags:
+` + `  --name filename   filename to store (default: the file's basename)
+` + `  --type mime       content type to store, overriding the guess
+` + `  --json            force JSON output
+` + "  --help            show this help",
+  options: {
+    name: { type: "string" },
+    type: { type: "string" }
+  },
+  run: async (ctx, positionals, values) => {
+    const path = positionals[0];
+    if (!path)
+      throw new UsageError("attachments upload requires a <path>");
+    const filename = stringFlag(values, "name") ?? basename(path);
+    const type = stringFlag(values, "type") ?? MIME_BY_EXTENSION[extname(filename).toLowerCase()] ?? "application/octet-stream";
+    return uploadAttachment(ctx.client, new Blob([await readFile(path)], { type }), filename);
+  },
+  render: (payload) => {
+    const a = payload.data ?? {};
+    return `uploaded ${a.filename ?? "?"} → ${a.id ?? "?"} (${a.sizeBytes ?? 0} bytes)`;
+  }
+};
 var attachmentsNoun = {
   name: "attachments",
-  summary: "List attachments, get one's text or URL, or download its bytes",
-  verbs: [listVerb, getVerb, downloadVerb]
+  summary: "List attachments, get one's text or URL, download its bytes, or upload a file",
+  verbs: [listVerb, getVerb, downloadVerb, uploadVerb]
 };
 
 // src/commands/conversations.ts
 var listVerb2 = {
   name: "list",
   summary: "List conversations, optionally scoped to a stream",
-  usage: "threa conversations list [--stream ref] [--status s] [--cursor c] [--limit n]",
+  usage: "threa conversations list [--stream ref] [--status s] [--cursor c] [--limit n] [--archived]",
   help: `threa conversations list [flags]
 
 ` + `List conversations (grouped runs of messages under a stream's effective root), newest activity first.
@@ -1662,19 +1760,24 @@ var listVerb2 = {
 ` + "  --status s     " + CONVERSATION_STATUSES.join(" | ") + `
 ` + `  --cursor c     pagination cursor from a previous response
 ` + `  --limit n      max results, <= 100 (default 50)
+` + `  --archived     include conversations in archived streams and in threads under archived ancestors.
+` + `                 An archived channel is not resolvable by #slug: pass --stream its stream_ id
+` + `                 (threa streams list --archived shows it)
 ` + `  --json         force JSON output
 ` + "  --help         show this help",
   options: {
     stream: { type: "string" },
     status: { type: "string" },
     cursor: { type: "string" },
-    limit: { type: "string" }
+    limit: { type: "string" },
+    archived: { type: "boolean" }
   },
   run: (ctx, _positionals, values) => listConversations(ctx.client, ctx.resolver, {
     streamRef: stringFlag(values, "stream"),
     status: enumFlag(values, "status", CONVERSATION_STATUSES),
     cursor: stringFlag(values, "cursor"),
-    limit: intFlag(values, "limit")
+    limit: intFlag(values, "limit"),
+    includeArchived: boolFlag(values, "archived")
   }),
   render: (payload) => renderList(payload, renderConversationRow, {
     empty: "(no conversations)",
@@ -1687,7 +1790,8 @@ function renderConversationRow(c) {
     c.status ?? "?",
     c.messageCount !== undefined ? `${c.messageCount} msgs` : undefined,
     fmtTimestamp(c.lastActivityAt) || undefined,
-    streamLabel(c) || undefined
+    streamLabel(c) || undefined,
+    c.archived ? "[archived]" : undefined
   ].filter(Boolean).join("  ");
   const topic = snippet(c.topicSummary ?? c.summary ?? "");
   return topic ? `${header}
@@ -1725,7 +1829,7 @@ var readVerb = {
     const lines = [];
     const c = p.conversation;
     if (c) {
-      lines.push([c.id ?? "?", c.status ?? "?", streamLabel(c) || undefined].filter(Boolean).join("  "), [
+      lines.push([c.id ?? "?", c.status ?? "?", streamLabel(c) || undefined, c.archived ? "[archived]" : undefined].filter(Boolean).join("  "), [
         fmtTimestamp(c.createdAt) && `created ${fmtTimestamp(c.createdAt)}`,
         fmtTimestamp(c.lastActivityAt) && `last activity ${fmtTimestamp(c.lastActivityAt)}`,
         c.messageCount !== undefined && `${c.messageCount} messages`
@@ -2978,14 +3082,21 @@ import { z as z2 } from "zod";
 function registerConversationTools(server, client, resolver) {
   server.registerTool("list_conversations", {
     title: "List conversations",
-    description: "List conversations (grouped runs of messages under a stream's effective root), newest activity first. " + "Filter with `stream_id` (accepts a stream_ id or `#channel-slug`; scopes to that stream's root and its " + "threads) and `status` (active, stalled, resolved). Each conversation mirrors its participantIds with a " + "participants array carrying name/slug. Page by passing the previous response's `cursor` value back as " + "`cursor`; `hasMore` tells you when to stop. limit ≤ 100 (default 50).",
+    description: "List conversations (grouped runs of messages under a stream's effective root), newest activity first. " + "Filter with `stream_id` (accepts a stream_ id or `#channel-slug`; scopes to that stream's root and its " + "threads) and `status` (active, stalled, resolved). Conversations in an archived stream, or in a thread " + "under an archived ancestor, are omitted unless `include_archived` is true; those rows then carry " + "`archived: true`. An archived channel is not resolvable by `#channel-slug`: pass its stream_ id, which " + "`list_streams` with `include_archived` returns. Each conversation mirrors its participantIds with a " + "participants array carrying name/slug. Page by passing the previous response's `cursor` value back as " + "`cursor`; `hasMore` tells you when to stop. limit ≤ 100 (default 50).",
     inputSchema: {
       stream_id: z2.string().optional(),
       status: z2.enum(CONVERSATION_STATUSES).optional(),
       cursor: z2.string().optional(),
-      limit: z2.number().int().min(1).max(100).optional()
+      limit: z2.number().int().min(1).max(100).optional(),
+      include_archived: z2.boolean().optional()
     }
-  }, async ({ stream_id, status, cursor, limit }) => runTool(() => listConversations(client, resolver, { streamRef: stream_id, status, cursor, limit })));
+  }, async ({ stream_id, status, cursor, limit, include_archived }) => runTool(() => listConversations(client, resolver, {
+    streamRef: stream_id,
+    status,
+    cursor,
+    limit,
+    includeArchived: include_archived
+  })));
   server.registerTool("read_conversation", {
     title: "Read a conversation with its messages",
     description: "Fetch a conversation and a page of its member messages in one call (concurrent requests). Returns " + "{ conversation, messages: { data, hasMore, cursor } }. The conversation mirrors its participantIds with " + "a participants array (name/slug) and message rows carry author { id, type, name, slug? }. Messages are " + "chronological and may span the " + "conversation's root stream and its threads; each carries its own `streamId`. Page the messages by " + "passing the previous response's `cursor` value back as `cursor`; `hasMore` tells you when to stop. " + "limit ≤ 100 (default 50) applies to messages. If the conversation cannot be read the whole call " + "errors — no partial data is returned.",
@@ -3119,6 +3230,13 @@ function registerMemoTools(server, client) {
       memo_id: z5.string()
     }
   }, async ({ memo_id }) => runTool(() => getMemo(client, memo_id)));
+  server.registerTool("recall_memos", {
+    title: "Recall memos for a message",
+    description: "Pass the message you are about to answer and get back the few memos that actually help with it, " + "scored for relevance (at most 5). An empty `data` with outcome 'nothing_relevant' or 'no_candidates' " + "means memory holds nothing useful for it; 'unscored', 'timeout' or 'failed' mean recall could not " + "judge, so fall back to the `search` tool (what: 'memos'). Each call runs a model, so recall once per " + "message rather than per idea; use `search` to explore.",
+    inputSchema: {
+      message: z5.string().min(1)
+    }
+  }, async ({ message }) => runTool(() => recallMemos(client, message)));
 }
 
 // src/tools/messages.ts
@@ -3177,7 +3295,7 @@ function registerSearchTools(server, client, resolver) {
     title: "Search the workspace",
     description: "One search across the workspace, routed by `what`. Only the filters listed for the chosen `what` are " + `accepted; passing any other filter is an error that names the offending arg.
 ` + "- what: 'messages' — full-text search over messages in accessible streams. Filters: query (required), " + "`semantic: true` for meaning-based vector retrieval when you know the idea but not the words, " + "`exact: true` to match the query as a literal phrase, stream_ids, type (stream types), before/after " + `(ISO-8601 datetimes), limit (≤50, default 20).
-` + "- what: 'memos' — search GAM (the knowledge extracted from this workspace's conversations: decisions, " + "learnings, procedures, context, references). Search this BEFORE asking a human. query is meaning-based " + "and OPTIONAL — leave it empty to browse the most recent memos. Filters: query, `exact: true` (or wrap " + "the query in double quotes) to match a literal phrase, stream_ids, memo_type (message vs. conversation " + "source), knowledge_type, tags, scope (user = private to this key's user, stream, workspace), " + `before/after (ISO-8601 datetimes), limit (≤100, default 20).
+` + "- what: 'memos' — search GAM (the knowledge extracted from this workspace's conversations: decisions, " + "learnings, procedures, context, references). Search this BEFORE asking a human. query is meaning-based " + "and OPTIONAL — leave it empty to browse the most recent memos. Filters: query, `exact: true` (or wrap " + "the query in double quotes) to match a literal phrase, stream_ids, memo_type (message vs. conversation " + "source), knowledge_type, tags, scope (user = private to this key's user, stream, workspace), " + "before/after (ISO-8601 datetimes, matched against when the memo's source messages were posted, not " + `when it was captured), limit (≤100, default 20).
 ` + "- what: 'attachments' — search accessible attachments by filename or extracted content. query is " + "OPTIONAL — leave it empty to browse the most recent attachments. Filters: query, stream_ids, " + `content_types (chart, table, diagram, screenshot, photo, document, other), limit (≤50, default 20).
 ` + "stream_ids maps to the API's source-stream scope; each entry accepts a stream_ id or `#channel-slug`. " + "For what='messages', result rows carry author { id, type, name, slug? }; message, attachment, and " + "conversation rows carry stream { id, name?, type? } and, for threads, rootStream. " + "Results are the search envelope { data: [...] }. For " + "exact metadata lookup use find_messages_by_metadata; for a memo's source provenance use get_memo.",
     inputSchema: {
@@ -3204,7 +3322,7 @@ import { z as z8 } from "zod";
 function registerStreamTools(server, client, resolver, sealed) {
   server.registerTool("list_streams", {
     title: "List streams",
-    description: "List streams this key can access, newest-ish first. Filter with `type` (one or more of scratchpad, " + "channel, dm, thread, system) and `query` (text match on name). Page by passing the previous " + "response's `cursor` value back as `after`; `hasMore` tells you when to stop. limit ≤ 200 (default 50). " + "Archived streams (and live threads under an archived root) are omitted unless `include_archived` is true.",
+    description: "List streams this key can access, newest-ish first. Filter with `type` (one or more of scratchpad, " + "channel, dm, thread, system) and `query` (text match on name). Page by passing the previous " + "response's `cursor` value back as `after`; `hasMore` tells you when to stop. limit ≤ 200 (default 50). " + "Archived streams and live threads under an archived ancestor are omitted unless `include_archived` is true; " + "both then carry `archived: true`.",
     inputSchema: {
       type: z8.array(z8.enum(STREAM_TYPES)).optional(),
       query: z8.string().optional(),
@@ -3248,7 +3366,7 @@ function registerUserTools(server, client) {
 }
 
 // src/server.ts
-var INSTRUCTIONS = "Threa MCP server. Wraps the Threa public REST API for one workspace, bound once from this server's " + "config — no tool takes a workspaceId. Authentication is a single API key. Tool results are JSON text in " + "the API's envelope: single resources under `data`, lists as { data, hasMore, cursor? } (feed `cursor` back " + "as the paging arg to continue); " + "failures come back as isError results carrying { code, message, hint? }. A 404 can mean the resource " + "does not exist or that the key lacks the required scope. Identifier args accept a raw id or a " + "sigil-prefixed slug: a stream arg takes a stream_ id or `#channel-slug` (your DM with a user by `@user-slug` " + "is not resolvable — the public API hides a DM's counterpart, so pass the DM's stream_ id), and user args " + "take a usr_/bot_ id or `@user-slug` (bots and personas are not queryable by slug). An unresolved ref fails " + "before any call with code UNRESOLVED_REF. Payloads are self-descriptive: message rows carry " + "author { id, type, name, slug? }, conversation participantIds are mirrored by a participants array with " + "name/slug, and stream members carry name/slug — so you rarely need a follow-up lookup. Start with `whoami` " + "to confirm the key and " + "identity. Read tools: list_streams and read_stream (one call returns a stream plus a page of its messages " + "by numeric sequence, and its members when include_members is set), list_users, list_conversations and " + "read_conversation (a conversation plus a page of its messages), and find_messages_by_metadata (exact " + "reference lookup). Search: one `search` tool with what = messages | memos | attachments — memos is GAM " + "(the knowledge extracted from this workspace's conversations), search it before asking a human; each " + "`what` accepts only its own filters. Write tools: send_message (markdown; optional conversation resume via " + "conversation_id or a new one via start_conversation; auto client_message_id for idempotent retries), " + "update_message / delete_message (only messages this key sent), and list_labels / apply_label / remove_label " + "(labels are private to the key actor and found-or-created by name). Memory provenance: get_memo traces a " + "memo to its source messages. Attachments: get_attachment (metadata plus extracted text), " + "get_attachment_download_url (short-lived signed URL for the raw bytes). Delegations: close the loop on a " + "delegated task with list_delegations (the open queue; since filters availability changes) → get_delegation (inspect brief/context without claim secrets) → " + "claim_delegation (returns a claim token shown once and persisted to ~/.threa/state.json; 15-min TTL) → optional " + "update_delegation while working (status_note reports progress and renews the claim, no note is a pure heartbeat) → " + "finish_delegation (outcome complete or fail) or release_delegation for controlled stop. Historical expired tasks are not listed but can be inspected and claimed directly by id. " + "A completed result is posted in the thread anchored on the delegation card and enters the normal message pipeline, so workspace memory can capture it. Lifecycle tools reuse the " + "stored token; pass claim_token to override or to recover on another machine. request_delegation_access " + "is bot-key only. End-to-end-encrypted streams: read_stream and send_message open and seal bodies with the " + "key this machine holds, so they read and write like any other stream; when no key is held here they say " + "so rather than returning the placeholder the server stores.";
+var INSTRUCTIONS = "Threa MCP server. Wraps the Threa public REST API for one workspace, bound once from this server's " + "config — no tool takes a workspaceId. Authentication is a single API key. Tool results are JSON text in " + "the API's envelope: single resources under `data`, lists as { data, hasMore, cursor? } (feed `cursor` back " + "as the paging arg to continue); " + "failures come back as isError results carrying { code, message, hint? }. A 404 can mean the resource " + "does not exist or that the key lacks the required scope. Identifier args accept a raw id or a " + "sigil-prefixed slug: a stream arg takes a stream_ id or `#channel-slug` (your DM with a user by `@user-slug` " + "is not resolvable — the public API hides a DM's counterpart, so pass the DM's stream_ id), and user args " + "take a usr_/bot_ id or `@user-slug` (bots and personas are not queryable by slug). An unresolved ref fails " + "before any call with code UNRESOLVED_REF. Payloads are self-descriptive: message rows carry " + "author { id, type, name, slug? }, conversation participantIds are mirrored by a participants array with " + "name/slug, and stream members carry name/slug — so you rarely need a follow-up lookup. Start with `whoami` " + "to confirm the key and " + "identity. Read tools: list_streams and read_stream (one call returns a stream plus a page of its messages " + "by numeric sequence, and its members when include_members is set), list_users, list_conversations and " + "read_conversation (a conversation plus a page of its messages), and find_messages_by_metadata (exact " + "reference lookup). Search: one `search` tool with what = messages | memos | attachments — memos is GAM " + "(the knowledge extracted from this workspace's conversations), search it before asking a human; each " + "`what` accepts only its own filters. Write tools: send_message (markdown; optional conversation resume via " + "conversation_id or a new one via start_conversation; auto client_message_id for idempotent retries), " + "update_message / delete_message (only messages this key sent), and list_labels / apply_label / remove_label " + "(labels are private to the key actor and found-or-created by name). Memory: recall_memos returns the few " + "memos relevant to a message you are about to answer (empty when nothing is), get_memo traces a " + "memo to its source messages. Attachments: get_attachment (metadata plus extracted text), " + "get_attachment_download_url (short-lived signed URL for the raw bytes). Delegations: close the loop on a " + "delegated task with list_delegations (the open queue; since filters availability changes) → get_delegation (inspect brief/context without claim secrets) → " + "claim_delegation (returns a claim token shown once and persisted to ~/.threa/state.json; 15-min TTL) → optional " + "update_delegation while working (status_note reports progress and renews the claim, no note is a pure heartbeat) → " + "finish_delegation (outcome complete or fail) or release_delegation for controlled stop. Historical expired tasks are not listed but can be inspected and claimed directly by id. " + "A completed result is posted in the thread anchored on the delegation card and enters the normal message pipeline, so workspace memory can capture it. Lifecycle tools reuse the " + "stored token; pass claim_token to override or to recover on another machine. request_delegation_access " + "is bot-key only. End-to-end-encrypted streams: read_stream and send_message open and seal bodies with the " + "key this machine holds, so they read and write like any other stream; when no key is held here they say " + "so rather than returning the placeholder the server stores.";
 function createThreaMcpServer(config, deps = {}) {
   const server = new McpServer({ name: "threa", version: "0.1.0" }, { instructions: INSTRUCTIONS });
   const client = new ThreaApiClient({
@@ -3502,16 +3620,52 @@ var getVerb3 = {
     return getMemo(ctx.client, id);
   }
 };
+var recallVerb = {
+  name: "recall",
+  summary: "Recall the memos relevant to a message",
+  usage: "threa memos recall <message>",
+  help: `threa memos recall <message>
+
+` + "Pass the message you are about to answer; get back the few memos that help with it (at most 5), " + "scored for relevance by a model. Nothing comes back when memory holds nothing relevant. To explore " + "memory by idea or filter, use `threa search --what memos`.\n\n" + `Flags:
+` + `  --json    force JSON output
+` + "  --help    show this help",
+  options: {},
+  run: (ctx, positionals) => {
+    const message = positionals.join(" ").trim();
+    if (!message)
+      throw new UsageError("memos recall requires a <message>");
+    return recallMemos(ctx.client, message);
+  },
+  render: (payload) => {
+    const { data = [], outcome } = payload;
+    if (data.length > 0)
+      return data.map((memo) => renderSearchResult({ memo })).join(`
+`);
+    if (outcome === "nothing_relevant" || outcome === "no_candidates")
+      return "(nothing relevant)";
+    return `(recall ${outcome ?? "failed"}; try \`threa search --what memos\`)`;
+  }
+};
 var memosNoun = {
   name: "memos",
-  summary: "List memos and get one by id",
-  verbs: [listVerb5, getVerb3]
+  summary: "List, recall, and get memos",
+  verbs: [listVerb5, recallVerb, getVerb3]
 };
 
 // src/commands/streams.ts
 function streamLabel2(s) {
   return s.displayName ?? s.name ?? (s.slug ? `#${s.slug}` : s.id ?? "?");
 }
+function renderStreamRow(s) {
+  return [s.id ?? "?", s.type ?? "?", streamLabel2(s), s.archived ? "[archived]" : undefined].filter(Boolean).join("  ");
+}
+function archiveState(s) {
+  if (s.archivedAt)
+    return `archived ${s.archivedAt}`;
+  if (s.archived)
+    return "sealed by an archived ancestor";
+  return "active";
+}
 var listVerb6 = {
   name: "list",
   summary: "List streams this key can access",
@@ -3525,7 +3679,7 @@ var listVerb6 = {
 ` + `  --query q    text match on stream name
 ` + `  --after c    pagination cursor from a previous response
 ` + `  --limit n    max results, <= 200 (default 50)
-` + `  --archived   include archived streams and threads under archived roots
+` + `  --archived   include archived streams and threads under archived ancestors
 ` + `  --json       force JSON output
 ` + "  --help       show this help",
   options: {
@@ -3542,10 +3696,7 @@ var listVerb6 = {
     limit: intFlag(values, "limit"),
     includeArchived: boolFlag(values, "archived")
   }),
-  render: (payload) => renderList(payload, (s) => `${s.id ?? "?"}  ${s.type ?? "?"}  ${streamLabel2(s)}`, {
-    empty: "(no streams)",
-    cursorFlag: "after"
-  })
+  render: (payload) => renderList(payload, renderStreamRow, { empty: "(no streams)", cursorFlag: "after" })
 };
 var readVerb2 = {
   name: "read",
@@ -3588,8 +3739,9 @@ var readVerb2 = {
   render: (payload) => {
     const p = payload;
     const lines = [];
-    if (p.stream)
-      lines.push(`stream: ${p.stream.id ?? "?"}  ${streamLabel2(p.stream)}`);
+    if (p.stream) {
+      lines.push([`stream: ${p.stream.id ?? "?"}`, streamLabel2(p.stream), p.stream.archived ? "[archived]" : undefined].filter(Boolean).join("  "));
+    }
     const msgs = p.messages?.data ?? [];
     lines.push(`messages: ${msgs.length}${p.messages?.hasMore ? " (more)" : ""}`);
     for (const m of msgs) {
@@ -3629,7 +3781,7 @@ function archiveVerb(archived) {
     },
     render: (payload) => {
       const stream = payload.data;
-      return `${stream.id ?? "?"}  ${streamLabel2(stream)}  ${stream.archivedAt ? `archived ${stream.archivedAt}` : "active"}`;
+      return `${stream.id ?? "?"}  ${streamLabel2(stream)}  ${archiveState(stream)}`;
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@threahq/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Command-line client and MCP server for Threa: read and search streams, send messages, manage attachments, and serve the Threa tools to any MCP-capable agent.",
   "license": "MIT",
   "repository": {

package/skills/threa-cli/SKILL.md

@@ -41,6 +41,12 @@ You rarely need to look up an id first. Any stream argument takes a `stream_…`
 
 Two things you cannot do this way, by design of the API: an `@user-slug` will not stand in for your DM with that user (DM streams hide their counterpart on the wire), and bots and personas are not queryable by slug. For a DM, find its `stream_…` id with `threa streams list --type dm` and `threa streams read <id> --members`; for a bot or persona, pass its id.
 
+## Archived streams stay readable
+
+If your key could read a stream before it was archived, it still can. `threa streams read`, `threa conversations read`, and `threa search` (tools `read_stream`, `read_conversation`, `search`) work on an archived stream and on any thread under it. A send, edit, or delete there fails with code `STREAM_READ_ONLY`.
+
+By default `threa streams list` leaves out archived streams and their threads, and `threa conversations list` leaves out the conversations in those streams. Pass `--archived` to either command (tools `list_streams` and `list_conversations` with `include_archived: true`) to include those rows, which carry `archived: true` in JSON and print `[archived]` in text output. Refer to an archived channel by its `stream_…` id, which `threa streams list --archived` shows; its `#channel-slug` fails with `UNRESOLVED_REF`.
+
 ## Payloads name their authors
 
 Read results already carry author identity, so you seldom need a second call to name who said what. Message rows carry `author: { id, type, name, slug? }` (a bot or persona author has no slug and its name comes from `authorDisplayName`). Conversations carry a `participants` array parallel to `participantIds` with each participant's name and slug. Stream members carry name and slug. Message search results, attachment rows, and conversations also carry `stream: { id, name?, type? }` — and `rootStream` when the stream is a thread — so you can name the scope without a `streams read`. Use these fields directly instead of listing users or streams per id.
@@ -52,6 +58,7 @@ Read results already carry author identity, so you seldom need a second call to
 - The query is semantic by default and optional. Pass the idea you are after even if you do not know the exact wording; leave it empty (`--what memos` with no query) to browse the most recent memos.
 - Pass `--exact` to match a literal phrase.
 - Narrow with `--stream`, `--knowledge-type`, `--memo-type`, `--tag`, `--scope`, and `--before`/`--after`.
+- When you are answering a specific message, `threa memos recall "<message>"` (tool `recall_memos`) returns only the memos a model judged relevant to it, at most 5, or `(nothing relevant)`. It runs a model per call, so recall once per message and use search to explore.
 - Follow a hit with `threa memos get <id>` (tool `get_memo`) to see the source messages it was extracted from, so you can cite or verify the origin.
 
 ## Conversation create and resume
@@ -88,7 +95,7 @@ One `search` command covers all three kinds; pick with `--what`, and pass only t
 
 - **`--what messages`**, default full-text: you know the words that appear in the message. Add `--semantic` when you know the idea but not the wording, or `--exact` to match the query as a literal phrase. Query required.
 - **`--what memos`**: search workspace memory (see the memory section). Query optional and semantic; an empty query browses recent memos.
-- **`--what attachments`**: search files by filename or extracted content, then `threa attachments get <id>` (tool `get_attachment`) for the full extracted text, or `threa attachments get <id> --url` (tool `get_attachment_download_url`) only when you need the raw bytes' URL. Query optional; omit it to browse the most recent attachments. `threa attachments download <id> [dest]` fetches the bytes to disk — a directory dest names the file after the attachment (`name (1).ext` on conflict), a file dest is written as given.
+- **`--what attachments`**: search files by filename or extracted content, then `threa attachments get <id>` (tool `get_attachment`) for the full extracted text, or `threa attachments get <id> --url` (tool `get_attachment_download_url`) only when you need the raw bytes' URL. Query optional; omit it to browse the most recent attachments. `threa attachments download <id> [dest]` fetches the bytes to disk — a directory dest names the file after the attachment (`name (1).ext` on conflict), a file dest is written as given. `threa attachments upload <path> [--name f] [--type mime]` uploads a file and returns its id; link it in a message as `[name](attachment:<id>)`.
 - **Recent-first browsing**: `threa memos list` and `threa attachments list` (both take repeatable `--stream` and `--limit`) are shorthand for a query-less search — use them for "what's new here" instead of inventing a query.
 - **`messages find-by-metadata`**: you want messages by a reference you stamped at send time, not by text. It is exact key/value AND-containment, the right tool for dedup and external-id lookup.