@threahq/cli 0.1.0

package/cli.js

@@ -0,0 +1,3884 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/cli.ts
+import { text } from "node:stream/consumers";
+import { parseArgs } from "node:util";
+
+// src/commands/skill.ts
+import { copyFileSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync3 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { dirname as dirname2, join as join3, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// src/config.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import { homedir } from "node:os";
+import { join as join2 } from "node:path";
+
+// ../../extensions/bot-runtime-client/src/keyring.ts
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+var E2E_KEY_SCOPES = ["host", "identity", "instance", "stream"];
+var E2E_KEY_STORE_KINDS = ["keychain", "file"];
+function hash16(value) {
+  return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+function e2eKeyAccount(params) {
+  switch (params.scope) {
+    case "identity":
+      return `identity-${hash16(params.identitySeed)}`;
+    case "instance":
+      return `instance-${params.instanceId.replace(/[^A-Za-z0-9_-]+/g, "-")}`.slice(0, 96);
+    case "host":
+      return `host-${hash16(params.hostname)}`;
+    case "stream":
+      return null;
+  }
+}
+function e2eStreamKeyAccount(streamId) {
+  return `stream-${hash16(streamId)}`;
+}
+function e2eUserKeyAccount(workspaceId, userId) {
+  return `user-${hash16(`${workspaceId}:${userId}`)}`;
+}
+function decodeRecord(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.keyId === "string" && typeof parsed.publicKey === "string" && typeof parsed.privateKey === "string") {
+      return { keyId: parsed.keyId, publicKey: parsed.publicKey, privateKey: parsed.privateKey };
+    }
+  } catch {}
+  return;
+}
+
+class FileKeyStore {
+  kind = "file";
+  describe;
+  dir;
+  constructor(opts) {
+    this.dir = opts.dir;
+    this.describe = opts.dir;
+  }
+  path(account) {
+    return join(this.dir, `${account}.json`);
+  }
+  read(account) {
+    const path = this.path(account);
+    if (!existsSync(path))
+      return;
+    return decodeRecord(readFileSync(path, "utf8"));
+  }
+  hasAny() {
+    if (!existsSync(this.dir))
+      return false;
+    return readdirSync(this.dir).some((entry) => entry.endsWith(".json"));
+  }
+  createExclusive(account, record) {
+    const path = this.path(account);
+    mkdirSync(dirname(path), { recursive: true });
+    try {
+      writeFileSync(path, `${JSON.stringify(record, null, 2)}
+`, { mode: 384, flag: "wx" });
+      return record;
+    } catch (error) {
+      if (error.code !== "EEXIST")
+        throw error;
+      const winner = this.read(account);
+      if (!winner)
+        throw new Error(`${path} exists but could not be read`);
+      return winner;
+    }
+  }
+  write(account, record) {
+    const path = this.path(account);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(record, null, 2)}
+`, { mode: 384 });
+  }
+  remove(account) {
+    rmSync(this.path(account), { force: true });
+  }
+}
+var KEYCHAIN_COMMAND_TIMEOUT_MS = 5000;
+function runKeychainCommand(command, args, input, timeoutMs = KEYCHAIN_COMMAND_TIMEOUT_MS) {
+  const result = spawnSync(command, args, { encoding: "utf8", input, timeout: timeoutMs });
+  if (result.error?.code === "ETIMEDOUT") {
+    return {
+      status: -1,
+      stdout: "",
+      stderr: `${command} gave no answer within ${timeoutMs}ms; the keyring is probably locked and waiting on a password prompt`,
+      unavailable: true
+    };
+  }
+  if (result.error) {
+    return { status: -1, stdout: "", stderr: String(result.error), unavailable: true };
+  }
+  return { status: result.status ?? -1, stdout: result.stdout ?? "", stderr: result.stderr ?? "", unavailable: false };
+}
+function encodeSecret(record) {
+  return Buffer.from(JSON.stringify(record), "utf8").toString("base64");
+}
+function decodeSecret(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed)
+    return;
+  return decodeRecord(Buffer.from(trimmed, "base64").toString("utf8"));
+}
+var KEYCHAIN_SERVICE = "threa-e2e";
+var sameRecord = (a, b) => a.keyId === b.keyId && a.publicKey === b.publicKey && a.privateKey === b.privateKey;
+
+class MacKeychainStore {
+  kind = "keychain";
+  describe = `macOS keychain (service ${KEYCHAIN_SERVICE})`;
+  exec;
+  constructor(opts = {}) {
+    this.exec = opts.exec ?? runKeychainCommand;
+  }
+  read(account) {
+    const result = this.exec("/usr/bin/security", [
+      "find-generic-password",
+      "-s",
+      KEYCHAIN_SERVICE,
+      "-a",
+      account,
+      "-w"
+    ]);
+    if (result.unavailable)
+      throw new Error(`macOS keychain unavailable: ${result.stderr}`);
+    if (result.status !== 0)
+      return;
+    return decodeSecret(result.stdout);
+  }
+  createExclusive(account, record) {
+    const result = this.exec("/usr/bin/security", ["-i"], `add-generic-password -s ${KEYCHAIN_SERVICE} -a ${account} -w ${encodeSecret(record)}
+`);
+    if (result.unavailable)
+      throw new Error(`macOS keychain unavailable: ${result.stderr}`);
+    const stored = this.read(account);
+    if (!stored)
+      throw new Error(`macOS keychain accepted no key for ${account}: ${result.stderr || result.stdout}`);
+    return stored;
+  }
+  write(account, record) {
+    const result = this.exec("/usr/bin/security", ["-i"], `add-generic-password -U -s ${KEYCHAIN_SERVICE} -a ${account} -w ${encodeSecret(record)}
+`);
+    if (result.unavailable)
+      throw new Error(`macOS keychain unavailable: ${result.stderr}`);
+    if (result.status !== 0) {
+      throw new Error(`macOS keychain rejected the key for ${account}: ${result.stderr || result.stdout}`);
+    }
+    const stored = this.read(account);
+    if (!stored || !sameRecord(stored, record)) {
+      throw new Error(`macOS keychain did not store the key for ${account}: ${result.stderr || result.stdout}`);
+    }
+  }
+  remove(account) {
+    const result = this.exec("/usr/bin/security", ["delete-generic-password", "-s", KEYCHAIN_SERVICE, "-a", account]);
+    if (result.unavailable)
+      throw new Error(`macOS keychain unavailable: ${result.stderr}`);
+    if (this.read(account))
+      throw new Error(`macOS keychain kept the key for ${account}: ${result.stderr}`);
+  }
+}
+
+class SecretServiceStore {
+  kind = "keychain";
+  describe = `Secret Service keyring (service ${KEYCHAIN_SERVICE})`;
+  exec;
+  constructor(opts = {}) {
+    this.exec = opts.exec ?? runKeychainCommand;
+  }
+  read(account) {
+    const result = this.exec("secret-tool", ["lookup", "service", KEYCHAIN_SERVICE, "account", account]);
+    if (result.unavailable)
+      throw new Error(`Secret Service unavailable: ${result.stderr}`);
+    if (result.status !== 0)
+      return;
+    return decodeSecret(result.stdout);
+  }
+  createExclusive(account, record) {
+    const existing = this.read(account);
+    if (existing)
+      return existing;
+    const result = this.exec("secret-tool", ["store", "--label", `Threa E2E key ${account}`, "service", KEYCHAIN_SERVICE, "account", account], encodeSecret(record));
+    if (result.unavailable)
+      throw new Error(`Secret Service unavailable: ${result.stderr}`);
+    const stored = this.read(account);
+    if (!stored)
+      throw new Error(`Secret Service stored no key for ${account}: ${result.stderr || result.stdout}`);
+    return stored;
+  }
+  write(account, record) {
+    const result = this.exec("secret-tool", ["store", "--label", `Threa E2E key ${account}`, "service", KEYCHAIN_SERVICE, "account", account], encodeSecret(record));
+    if (result.unavailable)
+      throw new Error(`Secret Service unavailable: ${result.stderr}`);
+    if (result.status !== 0) {
+      throw new Error(`Secret Service rejected the key for ${account}: ${result.stderr || result.stdout}`);
+    }
+    const stored = this.read(account);
+    if (!stored || !sameRecord(stored, record)) {
+      throw new Error(`Secret Service did not store the key for ${account}: ${result.stderr || result.stdout}`);
+    }
+  }
+  remove(account) {
+    const result = this.exec("secret-tool", ["clear", "service", KEYCHAIN_SERVICE, "account", account]);
+    if (result.unavailable)
+      throw new Error(`Secret Service unavailable: ${result.stderr}`);
+    if (this.read(account))
+      throw new Error(`Secret Service kept the key for ${account}: ${result.stderr}`);
+  }
+}
+function resolveKeyStore(input) {
+  const keychain = () => input.platform === "darwin" ? new MacKeychainStore({ exec: input.exec }) : new SecretServiceStore({ exec: input.exec });
+  if (input.requested === "file")
+    return new FileKeyStore({ dir: input.dir });
+  if (input.requested === "keychain") {
+    const store2 = keychain();
+    store2.read("threa-probe");
+    return store2;
+  }
+  if (input.hasExistingFileKey)
+    return new FileKeyStore({ dir: input.dir });
+  const store = keychain();
+  try {
+    store.read("threa-probe");
+    return store;
+  } catch (error) {
+    throw new Error(`No OS keychain available for Threa's end-to-end keys (${String(error)}). ` + `Set keyStore to "keychain" once one is installed and unlocked, or "file" to keep them in ${input.dir} at mode 0600.`);
+  }
+}
+
+class E2eKeyring {
+  opts;
+  log;
+  held = [];
+  inFlight = new Map;
+  loaded = false;
+  constructor(opts) {
+    this.opts = opts;
+    this.log = opts.log ?? ((message) => console.error(message));
+  }
+  get current() {
+    return this.held;
+  }
+  async ensure() {
+    if (this.loaded)
+      return this.held;
+    const account = this.opts.account;
+    if (account === null) {
+      this.loaded = true;
+      return this.held;
+    }
+    await this.loadAccount(account, undefined);
+    this.loaded = this.held.length > 0;
+    return this.held;
+  }
+  async ensureForStream(streamId) {
+    if (this.opts.account !== null)
+      return this.ensure();
+    return this.loadAccount(e2eStreamKeyAccount(streamId), streamId);
+  }
+  dropStream(streamId) {
+    const held = this.held.find((key) => key.streamId === streamId);
+    if (!held)
+      return this.held;
+    this.held = this.held.filter((key) => key !== held);
+    this.opts.store.remove(held.account);
+    this.log(`Threa sealed: dropped ${held.keyId}, the key for revoked stream ${streamId}`);
+    return this.held;
+  }
+  forStream(streamId) {
+    if (this.opts.account !== null)
+      return this.held.find((key) => !key.streamId);
+    return this.held.find((key) => key.streamId === streamId);
+  }
+  presenceFields() {
+    if (this.held.length === 0)
+      return {};
+    const e2eKeys = this.held.map((key) => ({
+      keyId: key.keyId,
+      publicKey: key.publicKey,
+      ...key.streamId ? { streamId: key.streamId } : {}
+    }));
+    const unscoped = this.held.find((key) => !key.streamId);
+    return unscoped ? { e2eKeys, publicKey: unscoped.publicKey, publicKeyId: unscoped.keyId } : { e2eKeys };
+  }
+  async loadAccount(account, streamId) {
+    const existing = this.held.find((key) => key.account === account);
+    if (existing)
+      return this.held;
+    let attempt = this.inFlight.get(account);
+    if (!attempt) {
+      attempt = this.mintAccount(account, streamId).finally(() => this.inFlight.delete(account));
+      this.inFlight.set(account, attempt);
+    }
+    return attempt;
+  }
+  async mintAccount(account, streamId) {
+    const record = this.opts.store.read(account) ?? await this.createRecord(account);
+    if (!this.held.some((key) => key.account === account)) {
+      this.held = [...this.held, { ...record, account, ...streamId ? { streamId } : {} }];
+    }
+    return this.held;
+  }
+  async createRecord(account) {
+    const legacy = account === this.opts.account ? this.opts.legacy?.() : undefined;
+    if (legacy) {
+      const adopted = this.opts.store.createExclusive(account, legacy);
+      this.log(`Threa sealed: adopted this install's existing key ${adopted.keyId} into ${this.opts.store.describe} as ${account}`);
+      return adopted;
+    }
+    const minted = this.opts.store.createExclusive(account, await this.opts.mint());
+    this.log(`Threa sealed: end-to-end key ${minted.keyId} is in ${this.opts.store.describe} as ${account}`);
+    return minted;
+  }
+}
+
+// src/config.ts
+var OUTPUT_MODES = ["text", "json"];
+var PRINCIPAL_KINDS = ["bot", "user"];
+var DEFAULT_BASE_URL = "https://app.threa.io";
+function readFileConfig() {
+  const explicit = process.env.THREA_CONFIG;
+  const home = process.env.HOME ?? homedir();
+  const candidates = explicit ? [explicit] : [join2(home, ".threa", "config.json"), join2(home, ".threa", "mcp.json")];
+  let raw;
+  let path;
+  for (const candidate of candidates) {
+    try {
+      raw = readFileSync2(candidate, "utf8");
+      path = candidate;
+      break;
+    } catch {}
+  }
+  if (raw === undefined || path === undefined) {
+    if (explicit) {
+      throw new Error(`[threa] THREA_CONFIG points to ${explicit}, but it could not be read.`);
+    }
+    return {};
+  }
+  if (path.endsWith("mcp.json")) {
+    process.stderr.write(`[threa] Using legacy ${path} — rename it to ~/.threa/config.json.
+`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`[threa] Config file ${path} is not valid JSON.`);
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new Error(`[threa] Config file ${path} must contain a JSON object with { apiKey, workspaceId, baseUrl }.`);
+  }
+  return parsed;
+}
+function loadConfig() {
+  const file = readFileConfig();
+  const explicit = Boolean(process.env.THREA_CONFIG);
+  const apiKey = explicit ? file.apiKey || process.env.THREA_API_KEY : process.env.THREA_API_KEY || file.apiKey;
+  const workspaceId = explicit ? file.workspaceId || process.env.THREA_WORKSPACE_ID : process.env.THREA_WORKSPACE_ID || file.workspaceId;
+  const baseUrl = (explicit ? file.baseUrl ?? process.env.THREA_BASE_URL : process.env.THREA_BASE_URL ?? file.baseUrl) ?? DEFAULT_BASE_URL;
+  const output = file.output ?? "text";
+  const principal = explicit ? file.principal ?? process.env.THREA_PRINCIPAL : process.env.THREA_PRINCIPAL ?? file.principal;
+  const keyScope = pick(explicit, file.keyScope, process.env.THREA_E2E_KEY_SCOPE);
+  const keyStore = pick(explicit, file.keyStore, process.env.THREA_E2E_KEY_STORE);
+  const keyDir = pick(explicit, file.keyDir, process.env.THREA_E2E_KEY_DIR);
+  const instanceId = pick(explicit, file.instanceId, process.env.THREA_INSTANCE_ID);
+  const missing = [];
+  if (!apiKey)
+    missing.push("THREA_API_KEY");
+  if (!workspaceId)
+    missing.push("THREA_WORKSPACE_ID");
+  if (missing.length > 0) {
+    throw new Error(`[threa] Missing required config: ${missing.join(", ")}. ` + `Set them as environment variables, or provide a JSON file at ~/.threa/config.json ` + `(or the path in THREA_CONFIG) with { apiKey, workspaceId, baseUrl } and optionally { principal }. ` + `Environment variables win over ~/.threa/config.json; a THREA_CONFIG file wins over them.`);
+  }
+  if (!OUTPUT_MODES.includes(output)) {
+    throw new Error(`[threa] Config "output" must be one of ${OUTPUT_MODES.join(", ")} — got "${output}".`);
+  }
+  if (principal !== undefined && !PRINCIPAL_KINDS.includes(principal)) {
+    throw new Error(`[threa] Config "principal" must be one of ${PRINCIPAL_KINDS.join(", ")} — got "${principal}".`);
+  }
+  if (keyScope !== undefined && !E2E_KEY_SCOPES.includes(keyScope)) {
+    throw new Error(`[threa] Config "keyScope" must be one of ${E2E_KEY_SCOPES.join(", ")} — got "${keyScope}".`);
+  }
+  if (keyStore !== undefined && !E2E_KEY_STORE_KINDS.includes(keyStore)) {
+    throw new Error(`[threa] Config "keyStore" must be one of ${E2E_KEY_STORE_KINDS.join(", ")} — got "${keyStore}".`);
+  }
+  assertSafeBaseUrl(baseUrl);
+  return {
+    apiKey,
+    workspaceId,
+    baseUrl,
+    output,
+    ...principal === undefined ? {} : { principal },
+    ...keyScope === undefined ? {} : { keyScope },
+    ...keyStore === undefined ? {} : { keyStore },
+    ...keyDir === undefined ? {} : { keyDir },
+    ...instanceId === undefined ? {} : { instanceId }
+  };
+}
+function pick(explicit, fromFile, fromEnv) {
+  return explicit ? fromFile ?? fromEnv : fromEnv ?? fromFile;
+}
+var LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+function assertSafeBaseUrl(baseUrl) {
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    throw new Error(`[threa] THREA_BASE_URL is not a valid URL: ${baseUrl}`);
+  }
+  if (url.protocol === "https:")
+    return;
+  if (url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname))
+    return;
+  throw new Error(`[threa] THREA_BASE_URL must be https:// (http:// is allowed only for localhost) — got ${baseUrl}. ` + `The API key is sent as a bearer token to this host on every request.`);
+}
+
+// src/api-client.ts
+var FETCH_TIMEOUT_MS = 30000;
+var RETRY_DELAYS_MS = [2000, 4000, 8000];
+function deriveHint(status) {
+  if (status === 404) {
+    return "A 404 can mean the resource does not exist OR that this API key lacks the scope required to see it.";
+  }
+  if (status === 429) {
+    return "Rate limited after retrying with backoff; retry later.";
+  }
+  return;
+}
+
+class ThreaApiError extends Error {
+  status;
+  code;
+  hint;
+  constructor(args) {
+    super(args.message);
+    this.name = "ThreaApiError";
+    this.status = args.status;
+    this.code = args.code;
+    this.hint = deriveHint(args.status);
+  }
+}
+
+class ThreaApiClient {
+  baseUrl;
+  workspaceId;
+  apiKey;
+  sleep;
+  timeoutMs;
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl.replace(/\/$/, "");
+    this.workspaceId = opts.workspaceId;
+    this.apiKey = opts.apiKey;
+    this.sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    this.timeoutMs = opts.timeoutMs ?? FETCH_TIMEOUT_MS;
+  }
+  get(path) {
+    return this.request("GET", path);
+  }
+  post(path, body, headers) {
+    return this.request("POST", path, body, headers);
+  }
+  patch(path, body) {
+    return this.request("PATCH", path, body);
+  }
+  delete(path) {
+    return this.request("DELETE", path);
+  }
+  workspacePath(path) {
+    return `${this.baseUrl}/api/v1/workspaces/${this.workspaceId}${path}`;
+  }
+  async request(method, path, body, extraHeaders) {
+    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);
+      let retryAfter429 = false;
+      try {
+        const response = await fetch(url, {
+          method,
+          signal: controller.signal,
+          headers: {
+            Authorization: `Bearer ${this.apiKey}`,
+            ...hasBody ? { "Content-Type": "application/json" } : {},
+            ...extraHeaders ?? {}
+          },
+          ...hasBody ? { body: JSON.stringify(body) } : {}
+        });
+        if (response.status === 429 && attempt < RETRY_DELAYS_MS.length) {
+          retryAfter429 = true;
+        } else {
+          if (!response.ok) {
+            throw await this.toError(response);
+          }
+          if (response.status === 204)
+            return;
+          return await response.json();
+        }
+      } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+          throw new ThreaApiError({
+            status: 0,
+            code: "TIMEOUT",
+            message: `Threa API ${method} ${path} timed out after ${this.timeoutMs}ms`
+          });
+        }
+        throw error;
+      } finally {
+        clearTimeout(timeout);
+      }
+      if (retryAfter429)
+        await this.sleep(RETRY_DELAYS_MS[attempt]);
+    }
+  }
+  async toError(response) {
+    let code;
+    let message;
+    if (response.headers.get("content-type")?.includes("application/json")) {
+      try {
+        const parsed = JSON.parse((await response.text()).slice(0, 4000));
+        if (typeof parsed.error === "string")
+          message = parsed.error;
+        if (typeof parsed.code === "string")
+          code = parsed.code;
+      } catch {}
+    }
+    return new ThreaApiError({
+      status: response.status,
+      code,
+      message: message ?? `Threa API ${response.status} ${response.statusText}`
+    });
+  }
+}
+
+// src/tools/result.ts
+class UnresolvedRefError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnresolvedRefError";
+  }
+}
+
+class ToolInputError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "ToolInputError";
+    this.code = code;
+  }
+}
+function jsonResult(payload) {
+  return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+}
+function buildQuery(params) {
+  const search = new URLSearchParams;
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null)
+      continue;
+    if (Array.isArray(value)) {
+      for (const item of value)
+        search.append(key, item);
+    } else {
+      search.append(key, String(value));
+    }
+  }
+  const qs = search.toString();
+  return qs ? `?${qs}` : "";
+}
+async function runTool(fn) {
+  try {
+    return jsonResult(await fn());
+  } catch (error) {
+    return errorResult(error);
+  }
+}
+function toErrorShape(error) {
+  if (error instanceof UnresolvedRefError)
+    return { code: "UNRESOLVED_REF", message: error.message };
+  if (error instanceof ToolInputError)
+    return { code: error.code, message: error.message };
+  if (error instanceof ThreaApiError) {
+    const shape = { code: error.code ?? `HTTP_${error.status}`, message: error.message };
+    if (error.hint)
+      shape.hint = error.hint;
+    return shape;
+  }
+  return { code: "ERROR", message: error instanceof Error ? error.message : String(error) };
+}
+function errorResult(error) {
+  return { isError: true, content: [{ type: "text", text: JSON.stringify(toErrorShape(error), null, 2) }] };
+}
+
+// src/output.ts
+class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+  }
+}
+var errorObject = toErrorShape;
+function formatSuccess(spec, payload, opts) {
+  if (opts.mode === "json" || !spec.render)
+    return JSON.stringify(payload, null, 2);
+  try {
+    return spec.render(payload);
+  } catch {
+    return JSON.stringify(payload, null, 2);
+  }
+}
+var GLOBAL_OPTIONS = {
+  help: { type: "boolean", short: "h" }
+};
+function extractOutputMode(argv) {
+  const rest = [];
+  let mode;
+  for (let i = 0;i < argv.length; i++) {
+    const token = argv[i];
+    if (token === "--") {
+      rest.push(...argv.slice(i));
+      break;
+    }
+    if (token === "--json") {
+      mode = "json";
+      continue;
+    }
+    let value;
+    if (token === "-o" || token === "--output") {
+      value = argv[++i];
+      if (value === undefined)
+        throw new UsageError(`${token} requires a value: ${OUTPUT_MODES.join("|")}`);
+    } else if (token.startsWith("-o=") || token.startsWith("--output=")) {
+      value = token.slice(token.indexOf("=") + 1);
+    } else {
+      rest.push(token);
+      continue;
+    }
+    if (!OUTPUT_MODES.includes(value)) {
+      throw new UsageError(`-o/--output must be one of ${OUTPUT_MODES.join("|")}, got "${value}"`);
+    }
+    mode = value;
+  }
+  return { argv: rest, mode };
+}
+function withGlobalOptions(options) {
+  return { ...options, ...GLOBAL_OPTIONS };
+}
+function intFlag(values, name) {
+  const v = values[name];
+  if (v === undefined)
+    return;
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < 1) {
+    throw new UsageError(`--${name} must be a positive integer, got "${String(v)}"`);
+  }
+  return n;
+}
+function stringFlag(values, name) {
+  const v = values[name];
+  return typeof v === "string" ? v : undefined;
+}
+function boolFlag(values, name) {
+  return values[name] === true;
+}
+function arrayFlag(values, name) {
+  const v = values[name];
+  if (Array.isArray(v) && v.length > 0)
+    return v;
+  return;
+}
+function kvPairs(pairs, label = "metadata") {
+  const out = {};
+  for (const pair of pairs) {
+    const eq = pair.indexOf("=");
+    if (eq <= 0)
+      throw new UsageError(`${label} must be key=value, got "${pair}"`);
+    out[pair.slice(0, eq)] = pair.slice(eq + 1);
+  }
+  return out;
+}
+function stderrJson(obj) {
+  return `${JSON.stringify(obj, null, 2)}
+`;
+}
+function enumFlag(values, name, allowed) {
+  const v = stringFlag(values, name);
+  if (v === undefined)
+    return;
+  if (!allowed.includes(v)) {
+    throw new UsageError(`--${name} must be one of ${allowed.join("|")}, got "${v}"`);
+  }
+  return v;
+}
+function enumArrayFlag(values, name, allowed) {
+  const arr = arrayFlag(values, name);
+  if (arr === undefined)
+    return;
+  for (const v of arr) {
+    if (!allowed.includes(v)) {
+      throw new UsageError(`--${name} must be one of ${allowed.join("|")}, got "${v}"`);
+    }
+  }
+  return arr;
+}
+function fmtTimestamp(iso) {
+  if (typeof iso !== "string")
+    return "";
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime()))
+    return "";
+  const p = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+function streamLabel(row) {
+  const name = row.stream?.name ?? row.stream?.id ?? (typeof row.streamId === "string" ? row.streamId : undefined);
+  if (!name)
+    return "";
+  const root = row.rootStream?.name ?? row.rootStream?.id;
+  return root && root !== name ? `${root} › ${name}` : name;
+}
+function snippet(text, max = 160) {
+  if (typeof text !== "string")
+    return "";
+  const collapsed = text.replace(/\s+/g, " ").trim();
+  return collapsed.length > max ? `${collapsed.slice(0, max - 1)}…` : collapsed;
+}
+function cursorFooter(p, flag) {
+  return p.hasMore && p.cursor ? [`… more (--${flag} ${p.cursor})`] : [];
+}
+function renderList(payload, formatRow, opts) {
+  const p = payload;
+  const lines = (p.data ?? []).map(formatRow);
+  if (opts.cursorFlag)
+    lines.push(...cursorFooter(p, opts.cursorFlag));
+  return lines.join(`
+`) || opts.empty;
+}
+
+// src/commands/skill.ts
+var SKILL_NAME = "threa-cli";
+var here = dirname2(fileURLToPath(import.meta.url));
+var SKILL_SOURCE = import.meta.url.endsWith(".ts") ? resolve(here, "../../../..", ".agents/skills", SKILL_NAME, "SKILL.md") : join3(here, "skills", SKILL_NAME, "SKILL.md");
+var skillCommand = {
+  name: "skill",
+  usage: "threa skill install [--target dir] | threa skill print",
+  summary: "Install the threa-cli agent skill into ~/.claude/skills, or print it",
+  help: `threa skill install [flags]
+` + `threa skill print
+
+` + `install copies the threa-cli skill (how an agent uses this CLI well) into the global Claude Code
+` + `skills directory so every session on this machine can load it, in any project.
+` + `print writes the skill markdown to stdout — pipe it wherever a skills directory is not the target.
+
+` + `Flags:
+` + `  --target dir   install: destination skills directory (default ~/.claude/skills)
+` + "  --help         show this help",
+  options: {
+    target: { type: "string" }
+  },
+  run: async (_ctx, positionals, values) => {
+    const sub = positionals[0];
+    if (sub !== "install" && sub !== "print") {
+      throw new UsageError(`skill supports two subcommands: install, print (got "${sub ?? ""}")`);
+    }
+    if (!existsSync2(SKILL_SOURCE)) {
+      throw new UsageError(`Skill source not found at ${SKILL_SOURCE}. Reinstall @threahq/cli.`);
+    }
+    if (sub === "print") {
+      return { skill: SKILL_NAME, source: SKILL_SOURCE, content: readFileSync3(SKILL_SOURCE, "utf8") };
+    }
+    const targetRoot = stringFlag(values, "target") ?? join3(homedir2(), ".claude", "skills");
+    const destination = join3(targetRoot, SKILL_NAME, "SKILL.md");
+    mkdirSync2(dirname2(destination), { recursive: true });
+    copyFileSync(SKILL_SOURCE, destination);
+    return { installed: true, skill: SKILL_NAME, source: SKILL_SOURCE, destination };
+  },
+  render: (payload) => {
+    const p = payload;
+    if (typeof p.content === "string")
+      return p.content;
+    return `installed ${SKILL_NAME} → ${p.destination ?? "?"}
+Re-run after updating the CLI to refresh it.`;
+  },
+  noConfig: true
+};
+
+// src/token-store.ts
+import { chmodSync, mkdirSync as mkdirSync3, readFileSync as readFileSync4, renameSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { createRequire as createRequire2 } from "node:module";
+import { homedir as homedir3 } from "node:os";
+import { dirname as dirname3, join as join4 } from "node:path";
+var LOCK_WAIT_MS = 5000;
+function openLockDatabase(path) {
+  const require2 = createRequire2(import.meta.url);
+  if (process.versions.bun) {
+    const { Database } = require2("bun:sqlite");
+    return new Database(path, { create: true });
+  }
+  const { DatabaseSync } = require2("node:sqlite");
+  return new DatabaseSync(path);
+}
+function defaultPath() {
+  return process.env.THREA_STATE_FILE ?? join4(homedir3(), ".threa", "state.json");
+}
+function emptyState() {
+  return { claimTokens: {} };
+}
+
+class TokenStore {
+  path;
+  state = emptyState();
+  warned = false;
+  constructor(pathOverride) {
+    this.path = pathOverride ?? defaultPath();
+  }
+  readState() {
+    let raw;
+    try {
+      raw = readFileSync4(this.path, "utf8");
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        this.warnOnce(`[threa] state file ${this.path} could not be read; starting with an empty claim-token store
+`);
+      }
+      return emptyState();
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed.claimTokens === "object" && parsed.claimTokens !== null) {
+        return { claimTokens: parsed.claimTokens };
+      }
+    } catch {
+      this.warnOnce(`[threa] state file ${this.path} is corrupt; starting with an empty claim-token store
+`);
+    }
+    return emptyState();
+  }
+  warnOnce(message) {
+    if (this.warned)
+      return;
+    this.warned = true;
+    process.stderr.write(message);
+  }
+  get(workspaceId, delegationId) {
+    this.state = this.readState();
+    return this.state.claimTokens[workspaceId]?.[delegationId];
+  }
+  set(workspaceId, delegationId, token) {
+    this.mutate((state) => {
+      (state.claimTokens[workspaceId] ??= {})[delegationId] = token;
+      return true;
+    });
+  }
+  delete(workspaceId, delegationId) {
+    this.mutate((state) => this.remove(state, workspaceId, delegationId));
+  }
+  deleteIfMatches(workspaceId, delegationId, observedToken) {
+    return this.mutate((state) => {
+      if (state.claimTokens[workspaceId]?.[delegationId] !== observedToken)
+        return false;
+      this.remove(state, workspaceId, delegationId);
+      return true;
+    });
+  }
+  remove(state, workspaceId, delegationId) {
+    const ws = state.claimTokens[workspaceId];
+    if (ws?.[delegationId] === undefined)
+      return false;
+    delete ws[delegationId];
+    if (Object.keys(ws).length === 0)
+      delete state.claimTokens[workspaceId];
+    return true;
+  }
+  mutate(change) {
+    const unlock = this.lock();
+    try {
+      const state = this.readState();
+      const result = change(state);
+      this.state = state;
+      if (result !== false)
+        this.persist(state);
+      return result;
+    } finally {
+      unlock();
+    }
+  }
+  lock() {
+    mkdirSync3(dirname3(this.path), { recursive: true });
+    const lockPath = `${this.path}.lock.sqlite`;
+    const db = openLockDatabase(lockPath);
+    try {
+      chmodSync(lockPath, 384);
+      db.exec(`PRAGMA busy_timeout = ${LOCK_WAIT_MS}`);
+      db.exec("BEGIN IMMEDIATE");
+    } catch (error) {
+      db.close();
+      throw error;
+    }
+    return () => {
+      try {
+        db.exec("COMMIT");
+      } finally {
+        db.close();
+      }
+    };
+  }
+  persist(state) {
+    const tmp = `${this.path}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync2(tmp, JSON.stringify(state), { mode: 384 });
+    renameSync(tmp, this.path);
+  }
+}
+
+// src/commands/attachments.ts
+import { existsSync as existsSync3, statSync, writeFileSync as writeFileSync3 } from "node:fs";
+import { basename, extname, join as join5 } from "node:path";
+
+// src/enrich.ts
+async function loadUsersById(resolver) {
+  try {
+    const users = await resolver.allUsers();
+    return new Map(users.map((u) => [u.id, { name: u.name, slug: u.slug }]));
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`[threa] enrichment skipped: users fetch failed: ${detail}
+`);
+    return null;
+  }
+}
+function enrichOne(row, usersById) {
+  if (!row || typeof row !== "object")
+    return row;
+  const m = row;
+  if (typeof m.authorId !== "string")
+    return row;
+  const user = usersById.get(m.authorId);
+  const name = user?.name ?? (typeof m.authorDisplayName === "string" ? m.authorDisplayName : undefined);
+  const author = { id: m.authorId };
+  if (typeof m.authorType === "string")
+    author.type = m.authorType;
+  if (name != null)
+    author.name = name;
+  if (user?.slug)
+    author.slug = user.slug;
+  return { ...m, author };
+}
+async function enrichMessages(rows, resolver) {
+  if (!Array.isArray(rows))
+    return rows;
+  if (!rows.some((row) => row && typeof row === "object" && typeof row.authorId === "string")) {
+    return rows;
+  }
+  const usersById = await loadUsersById(resolver);
+  if (!usersById)
+    return rows;
+  return rows.map((row) => enrichOne(row, usersById));
+}
+function toStreamRef(info, id) {
+  const ref = { id };
+  if (info?.displayName ?? info?.slug)
+    ref.name = info.displayName ?? info.slug;
+  if (info?.type)
+    ref.type = info.type;
+  return ref;
+}
+async function enrichStreamContext(rows, resolver) {
+  if (!Array.isArray(rows))
+    return rows;
+  const streamIds = new Set;
+  for (const row of rows) {
+    if (!row || typeof row !== "object")
+      continue;
+    const { streamId, rootStreamId } = row;
+    if (typeof streamId === "string")
+      streamIds.add(streamId);
+    if (typeof rootStreamId === "string")
+      streamIds.add(rootStreamId);
+  }
+  if (streamIds.size === 0)
+    return rows;
+  const infos = new Map;
+  await Promise.all([...streamIds].map(async (id) => infos.set(id, await resolver.streamInfo(id))));
+  const rootIds = new Set;
+  for (const [id, info] of infos) {
+    if (info?.rootStreamId && info.rootStreamId !== id && !infos.has(info.rootStreamId)) {
+      rootIds.add(info.rootStreamId);
+    }
+  }
+  await Promise.all([...rootIds].map(async (id) => infos.set(id, await resolver.streamInfo(id))));
+  return rows.map((row) => {
+    if (!row || typeof row !== "object")
+      return row;
+    const r = row;
+    if (typeof r.streamId !== "string")
+      return row;
+    const info = infos.get(r.streamId) ?? null;
+    const out = { ...r, stream: toStreamRef(info, r.streamId) };
+    const rootId = typeof r.rootStreamId === "string" ? r.rootStreamId : info?.rootStreamId;
+    if (rootId && rootId !== r.streamId) {
+      out.rootStream = toStreamRef(infos.get(rootId) ?? null, rootId);
+    }
+    return out;
+  });
+}
+async function enrichConversation(conversation, resolver) {
+  if (!conversation || typeof conversation !== "object")
+    return conversation;
+  const c = conversation;
+  if (!Array.isArray(c.participantIds) || c.participantIds.length === 0)
+    return conversation;
+  const usersById = await loadUsersById(resolver);
+  if (!usersById)
+    return conversation;
+  const participants = c.participantIds.map((id) => {
+    if (typeof id !== "string")
+      return { id };
+    const user = usersById.get(id);
+    const entry = { id };
+    if (user?.name)
+      entry.name = user.name;
+    if (user?.slug)
+      entry.slug = user.slug;
+    return entry;
+  });
+  return { ...c, participants };
+}
+
+// src/tools/constants.ts
+var CALLBACK_TOKEN_HEADER = "X-Threa-Callback-Token";
+var STREAM_TYPES = ["scratchpad", "channel", "dm", "thread", "system", "aside"];
+var CONVERSATION_STATUSES = ["active", "stalled", "resolved"];
+var MEMO_TYPES = ["message", "conversation"];
+var KNOWLEDGE_TYPES = ["decision", "learning", "procedure", "context", "reference"];
+var MEMO_SCOPES = ["user", "stream", "workspace"];
+var EXTRACTION_CONTENT_TYPES = [
+  "chart",
+  "table",
+  "diagram",
+  "screenshot",
+  "photo",
+  "document",
+  "other"
+];
+
+// src/ops.ts
+async function whoami(client, config) {
+  const { data } = await client.get("/me");
+  return {
+    principal: data,
+    declaredPrincipal: config.principal ?? null,
+    baseUrl: config.baseUrl,
+    workspaceId: config.workspaceId
+  };
+}
+function listStreams(client, p) {
+  return client.get(`/streams${buildQuery({
+    type: p.type,
+    query: p.query,
+    after: p.after,
+    limit: p.limit,
+    includeArchived: p.includeArchived ? "true" : undefined
+  })}`);
+}
+async function openSealedRows(sealed, streamId, rows) {
+  if (!Array.isArray(rows))
+    return rows;
+  const opened = [];
+  for (const row of rows) {
+    const candidate = row;
+    if (!row || typeof row !== "object" || !candidate.sealed) {
+      opened.push(row);
+      continue;
+    }
+    const { sealed: envelope, ...rest } = candidate;
+    const body = await sealed.open(streamId, envelope);
+    opened.push({
+      ...rest,
+      content: body.contentMarkdown,
+      ...body.attachmentRefs.length > 0 ? { sealedAttachmentRefs: body.attachmentRefs } : {},
+      ...body.unreadableReason === undefined ? {} : { unreadableReason: body.unreadableReason }
+    });
+  }
+  return opened;
+}
+async function readStream(client, resolver, p) {
+  const streamId = await resolver.resolveStream(p.streamId);
+  const id = encodeURIComponent(streamId);
+  const streamReq = client.get(`/streams/${id}`);
+  const messagesReq = client.get(`/streams/${id}/messages${buildQuery({ before: p.before, after: p.after, limit: p.limit })}`);
+  const membersReq = p.includeMembers ? client.get(`/streams/${id}/members`) : undefined;
+  const [streamResp, messagesResp, membersResp] = await Promise.all([
+    streamReq,
+    messagesReq,
+    membersReq ?? Promise.resolve(undefined)
+  ]);
+  const enriched = await enrichMessages(messagesResp.data, resolver);
+  const messages = p.sealed ? await openSealedRows(p.sealed, streamId, enriched) : enriched;
+  const result = {
+    stream: streamResp.data,
+    messages: { data: messages, hasMore: messagesResp.hasMore ?? false }
+  };
+  if (membersResp) {
+    result.members = {
+      data: membersResp.data,
+      hasMore: membersResp.hasMore ?? false,
+      cursor: membersResp.cursor ?? null
+    };
+  }
+  return result;
+}
+async function setStreamArchived(client, resolver, p) {
+  const id = encodeURIComponent(await resolver.resolveStream(p.streamRef));
+  return client.post(`/streams/${id}/${p.archived ? "archive" : "unarchive"}`);
+}
+function listUsers(client, p) {
+  return client.get(`/users${buildQuery({ query: p.query, after: p.after, limit: p.limit })}`);
+}
+async function findMessagesByMetadata(client, resolver, p) {
+  const streamId = p.streamRef ? await resolver.resolveStream(p.streamRef) : undefined;
+  const response = await client.post("/messages/find-by-metadata", {
+    metadata: p.metadata,
+    streamId,
+    limit: p.limit
+  });
+  return { ...response, data: await enrichMessages(response.data, resolver) };
+}
+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 withParticipants = await Promise.all(response.data.map((c) => enrichConversation(c, resolver)));
+  return { ...response, data: await enrichStreamContext(withParticipants, resolver) };
+}
+async function readConversation(client, resolver, p) {
+  const id = encodeURIComponent(p.conversationId);
+  const [conversationResp, messagesResp] = await Promise.all([
+    client.get(`/conversations/${id}`),
+    client.get(`/conversations/${id}/messages${buildQuery({ after: p.cursor, limit: p.limit })}`)
+  ]);
+  const [conversation] = await enrichStreamContext([await enrichConversation(conversationResp.data, resolver)], resolver);
+  return {
+    conversation,
+    messages: {
+      data: await enrichMessages(messagesResp.data, resolver),
+      hasMore: messagesResp.hasMore ?? false,
+      cursor: messagesResp.cursor ?? null
+    }
+  };
+}
+function getMemo(client, memoId) {
+  return client.get(`/memos/${encodeURIComponent(memoId)}`);
+}
+function getAttachment(client, attachmentId) {
+  return client.get(`/attachments/${encodeURIComponent(attachmentId)}`);
+}
+function getAttachmentDownloadUrl(client, attachmentId) {
+  return client.get(`/attachments/${encodeURIComponent(attachmentId)}/url`);
+}
+var SEARCH_WHATS = ["messages", "memos", "attachments"];
+var ALLOWED_FILTERS = {
+  messages: ["query", "semantic", "exact", "stream_ids", "type", "before", "after", "limit"],
+  memos: ["query", "exact", "stream_ids", "memo_type", "knowledge_type", "tags", "scope", "before", "after", "limit"],
+  attachments: ["query", "stream_ids", "content_types", "limit"]
+};
+var FILTER_KEYS = [
+  "query",
+  "semantic",
+  "exact",
+  "stream_ids",
+  "type",
+  "memo_type",
+  "knowledge_type",
+  "tags",
+  "scope",
+  "content_types",
+  "before",
+  "after",
+  "limit"
+];
+async function search(client, resolver, args) {
+  const { what } = args;
+  const allowed = ALLOWED_FILTERS[what];
+  const raw = args;
+  const offending = FILTER_KEYS.filter((key) => raw[key] !== undefined && !allowed.includes(key));
+  if (offending.length > 0) {
+    const validList = allowed.filter((f) => f !== "query" && f !== "limit").join(", ");
+    throw new ToolInputError("UNSUPPORTED_FILTER", `search what="${what}" does not support: ${offending.join(", ")}. ` + `Valid filters for "${what}": ${validList || "none"} (plus query, limit).`);
+  }
+  const query = args.query;
+  if (what === "messages" && (query === undefined || query.trim() === "")) {
+    throw new ToolInputError("INVALID_ARGUMENT", `search what="messages" requires a non-empty query. Omitting the query (recent-first browse) is only ` + `supported for what="memos" and what="attachments".`);
+  }
+  if (what === "attachments" && query !== undefined && query.trim() === "") {
+    throw new ToolInputError("INVALID_ARGUMENT", `search what="attachments" got a blank query. Pass a non-empty query, or omit it entirely to browse the most recent attachments.`);
+  }
+  if (what !== "memos" && args.limit !== undefined && args.limit > 50) {
+    throw new ToolInputError("INVALID_ARGUMENT", `search what="${what}" caps limit at 50 (only what="memos" allows up to 100).`);
+  }
+  if (what === "messages") {
+    const streams2 = args.stream_ids ? await resolver.resolveStreams(args.stream_ids) : undefined;
+    const response2 = await client.post("/messages/search", {
+      query,
+      semantic: args.semantic,
+      exact: args.exact,
+      streams: streams2,
+      type: args.type,
+      before: args.before,
+      after: args.after,
+      limit: args.limit
+    });
+    const data = await enrichStreamContext(await enrichMessages(response2.data, resolver), resolver);
+    return { ...response2, data };
+  }
+  if (what === "memos") {
+    const streams2 = args.stream_ids ? await resolver.resolveStreams(args.stream_ids) : undefined;
+    return client.post("/memos/search", {
+      query,
+      exact: args.exact,
+      streams: streams2,
+      memoType: args.memo_type,
+      knowledgeType: args.knowledge_type,
+      tags: args.tags,
+      scope: args.scope,
+      before: args.before,
+      after: args.after,
+      limit: args.limit
+    });
+  }
+  const streams = args.stream_ids ? await resolver.resolveStreams(args.stream_ids) : undefined;
+  const response = await client.post("/attachments/search", {
+    query,
+    streams,
+    contentTypes: args.content_types,
+    limit: args.limit
+  });
+  return { ...response, data: await enrichStreamContext(response.data, resolver) };
+}
+function sealedSendArgError(p) {
+  if (p.metadata)
+    return "An end-to-end-encrypted stream takes no metadata: it would travel in the clear.";
+  if (p.conversationId || p.startConversation) {
+    return "Conversations are not available in an end-to-end-encrypted stream.";
+  }
+  return;
+}
+function sendConversationArgError(p) {
+  if (p.conversationId && p.startConversation) {
+    return "Pass either conversation_id (resume an existing conversation) or start_conversation (open a new one), not both.";
+  }
+  return;
+}
+async function sendMessage(client, resolver, p) {
+  const argError = sendConversationArgError(p);
+  if (argError) {
+    throw new ToolInputError("INVALID_ARGUMENT", argError);
+  }
+  const streamId = await resolver.resolveStream(p.streamRef);
+  if (p.sealed) {
+    const stream = await client.get(`/streams/${encodeURIComponent(streamId)}`);
+    if (stream.data.e2eEnabled === true) {
+      const sealedArgError = sealedSendArgError(p);
+      if (sealedArgError)
+        throw new ToolInputError("INVALID_ARGUMENT", sealedArgError);
+      const sent = await p.sealed.send(streamId, p.content, {
+        ...p.clientMessageId === undefined ? {} : { clientMessageId: p.clientMessageId }
+      });
+      return { data: { id: sent.messageId }, clientMessageId: sent.clientMessageId, sealed: true };
+    }
+  }
+  const clientMessageId = p.clientMessageId ?? `mcp-${crypto.randomUUID()}`;
+  const body = { content: p.content, clientMessageId };
+  if (p.metadata)
+    body.metadata = p.metadata;
+  if (p.conversationId)
+    body.conversation = { intent: "existing", conversationId: p.conversationId };
+  else if (p.startConversation)
+    body.conversation = { intent: "new" };
+  const response = await client.post(`/streams/${encodeURIComponent(streamId)}/messages`, body);
+  return { ...response, clientMessageId, ...p.sealed ? { sealed: false } : {} };
+}
+function updateMessage(client, messageId, content) {
+  return client.patch(`/messages/${encodeURIComponent(messageId)}`, { content });
+}
+async function deleteMessage(client, messageId) {
+  await client.delete(`/messages/${encodeURIComponent(messageId)}`);
+  return { deleted: true, message_id: messageId };
+}
+function listLabels(client) {
+  return client.get("/labels");
+}
+async function applyLabel(client, resolver, p) {
+  return client.post("/labels/assignments", {
+    name: p.name,
+    color: p.color,
+    emoji: p.emoji,
+    description: p.description,
+    resourceType: "stream",
+    resourceId: await resolver.resolveStream(p.streamRef)
+  });
+}
+async function removeLabel(client, resolver, p) {
+  const resourceId = await resolver.resolveStream(p.streamRef);
+  await client.delete(`/labels/assignments${buildQuery({ name: p.name, resourceType: "stream", resourceId })}`);
+  return { removed: true, name: p.name, stream_id: resourceId };
+}
+function listDelegations(client, p) {
+  return client.get(`/delegations${buildQuery({ status: p.status, since: p.since })}`);
+}
+function getDelegation(client, delegationId) {
+  return client.get(`/delegations/${encodeURIComponent(delegationId)}`);
+}
+async function claimDelegation(client, store, workspaceId, p) {
+  const response = await client.post(`/delegations/${encodeURIComponent(p.delegationId)}/claim`, { claimedByLabel: p.claimedByLabel, idempotencyKey: p.idempotencyKey });
+  const token = response.data?.claimToken;
+  if (token)
+    store.set(workspaceId, p.delegationId, token);
+  return response;
+}
+function resolveDelegationToken(store, workspaceId, delegationId, explicit) {
+  const token = explicit ?? store.get(workspaceId, delegationId);
+  if (!token) {
+    throw new ToolInputError("MISSING_CLAIM_TOKEN", "No claim token for this delegation. Pass claim_token — the value the claim returned once. The persistent " + "store has no token for this id (you never claimed it, or the claim was already finished and cleared).");
+  }
+  return token;
+}
+async function releaseDelegation(client, store, workspaceId, p) {
+  const token = resolveDelegationToken(store, workspaceId, p.delegationId, p.claimToken);
+  const headers = { [CALLBACK_TOKEN_HEADER]: token };
+  const response = await client.post(`/delegations/${encodeURIComponent(p.delegationId)}/release`, undefined, headers);
+  store.deleteIfMatches(workspaceId, p.delegationId, token);
+  return response;
+}
+function updateDelegation(client, store, workspaceId, p) {
+  const headers = { [CALLBACK_TOKEN_HEADER]: resolveDelegationToken(store, workspaceId, p.delegationId, p.claimToken) };
+  const id = encodeURIComponent(p.delegationId);
+  return p.statusNote ? client.post(`/delegations/${id}/status`, { statusNote: p.statusNote }, headers) : client.post(`/delegations/${id}/heartbeat`, undefined, headers);
+}
+function finishDelegationArgError(p) {
+  if (p.outcome === "fail") {
+    if (!p.errorMessage)
+      return "outcome=fail requires error_message.";
+    const misplaced = [];
+    if (p.resultMarkdown !== undefined)
+      misplaced.push("result_markdown");
+    if (p.metadata !== undefined)
+      misplaced.push("metadata");
+    if (misplaced.length > 0) {
+      return `outcome=fail does not accept ${misplaced.join(", ")} — those belong to outcome=complete.`;
+    }
+    return;
+  }
+  if (p.errorMessage !== undefined) {
+    return "outcome=complete does not accept error_message — that belongs to outcome=fail.";
+  }
+  return;
+}
+async function finishDelegation(client, store, workspaceId, p) {
+  const argError = finishDelegationArgError(p);
+  if (argError)
+    throw new ToolInputError("INVALID_ARGUMENT", argError);
+  const headers = { [CALLBACK_TOKEN_HEADER]: resolveDelegationToken(store, workspaceId, p.delegationId, p.claimToken) };
+  const id = encodeURIComponent(p.delegationId);
+  const body = {};
+  let path;
+  if (p.outcome === "fail") {
+    path = `/delegations/${id}/fail`;
+    body.errorMessage = p.errorMessage;
+  } else {
+    path = `/delegations/${id}/complete`;
+    if (p.resultMarkdown)
+      body.resultMarkdown = p.resultMarkdown;
+    if (p.metadata)
+      body.metadata = p.metadata;
+  }
+  const response = await client.post(path, body, headers);
+  store.delete(workspaceId, p.delegationId);
+  return response;
+}
+function requestDelegationAccess(client, delegationId) {
+  return client.post(`/delegations/${encodeURIComponent(delegationId)}/request-access`, {});
+}
+
+// src/commands/search.ts
+var searchCommand = {
+  name: "search",
+  summary: "Search the workspace across messages, memos, or attachments",
+  usage: "threa search [query] --what messages|memos|attachments [per-what filters]",
+  help: `threa search [query] --what messages|memos|attachments [flags]
+
+` + "One search routed by --what. Only the filters valid for the chosen --what are accepted; passing another " + "is an error naming the offending flag. query is required for messages; for memos and attachments it is " + `optional (omit it to browse the most recent, newest first).
+
+` + `Common flags:
+` + `  --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)
+` + "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)
+` + `  --json           force JSON output
+` + "  --help           show this help",
+  options: {
+    what: { type: "string" },
+    semantic: { type: "boolean" },
+    exact: { type: "boolean" },
+    stream: { type: "string", multiple: true },
+    type: { type: "string", multiple: true },
+    "memo-type": { type: "string", multiple: true },
+    "knowledge-type": { type: "string", multiple: true },
+    tag: { type: "string", multiple: true },
+    scope: { type: "string" },
+    "content-type": { type: "string", multiple: true },
+    before: { type: "string" },
+    after: { type: "string" },
+    limit: { type: "string" }
+  },
+  run: (ctx, positionals, values) => {
+    const what = stringFlag(values, "what");
+    if (!what)
+      throw new UsageError("search requires --what (messages, memos, or attachments)");
+    if (!SEARCH_WHATS.includes(what)) {
+      throw new UsageError(`--what must be one of ${SEARCH_WHATS.join(", ")}, got "${what}"`);
+    }
+    const args = { what };
+    const query = positionals[0];
+    if (query !== undefined)
+      args.query = query;
+    if (values.semantic === true)
+      args.semantic = true;
+    if (values.exact === true)
+      args.exact = true;
+    const streams = arrayFlag(values, "stream");
+    if (streams)
+      args.stream_ids = streams;
+    const type = arrayFlag(values, "type");
+    if (type)
+      args.type = type;
+    const memoType = arrayFlag(values, "memo-type");
+    if (memoType)
+      args.memo_type = memoType;
+    const knowledgeType = arrayFlag(values, "knowledge-type");
+    if (knowledgeType)
+      args.knowledge_type = knowledgeType;
+    const tags = arrayFlag(values, "tag");
+    if (tags)
+      args.tags = tags;
+    const scope = stringFlag(values, "scope");
+    if (scope)
+      args.scope = scope;
+    const contentTypes = arrayFlag(values, "content-type");
+    if (contentTypes)
+      args.content_types = contentTypes;
+    const before = stringFlag(values, "before");
+    if (before)
+      args.before = before;
+    const after = stringFlag(values, "after");
+    if (after)
+      args.after = after;
+    const limit = intFlag(values, "limit");
+    if (limit !== undefined)
+      args.limit = limit;
+    return search(ctx.client, ctx.resolver, args);
+  },
+  render: (payload) => {
+    const p = payload;
+    const rows = p.data ?? [];
+    if (rows.length === 0)
+      return "(no results)";
+    return rows.map(renderSearchResult).join(`
+`);
+  }
+};
+function joinFields(fields) {
+  return fields.filter(Boolean).join("  ");
+}
+function renderSearchResult(r) {
+  if (r.memo && typeof r.memo === "object")
+    return renderMemoResult(r);
+  if (typeof r.filename === "string")
+    return renderAttachmentResult(r);
+  return renderMessageResult(r);
+}
+function renderMessageResult(r) {
+  const author = r.author;
+  const who = author?.name ?? (typeof r.authorDisplayName === "string" ? r.authorDisplayName : undefined);
+  const header = joinFields([
+    String(r.id ?? "?"),
+    fmtTimestamp(r.createdAt),
+    streamLabel(r),
+    who
+  ]);
+  return `${header}
+  ${snippet(r.content)}`;
+}
+function renderMemoResult(r) {
+  const memo = r.memo;
+  const source = r.sourceStream ?? null;
+  const root = r.rootStream ?? null;
+  const scope = [root?.name, source?.name].filter((n) => Boolean(n));
+  const scopeLabel = scope[0] === scope[1] ? scope[0] : scope.join(" › ");
+  const header = joinFields([
+    String(memo.id ?? "?"),
+    typeof memo.knowledgeType === "string" ? memo.knowledgeType : undefined,
+    fmtTimestamp(memo.createdAt),
+    scopeLabel || undefined
+  ]);
+  const title = typeof memo.title === "string" ? memo.title : "";
+  return `${header}
+  ${snippet(`${title}${title && memo.abstract ? " — " : ""}${String(memo.abstract ?? "")}`)}`;
+}
+function renderAttachmentResult(r) {
+  const header = joinFields([
+    String(r.id ?? "?"),
+    String(r.filename ?? "?"),
+    typeof r.mimeType === "string" ? r.mimeType : undefined,
+    fmtTimestamp(r.createdAt),
+    streamLabel(r)
+  ]);
+  const summary = snippet(r.summary);
+  return summary ? `${header}
+  ${summary}` : header;
+}
+
+// src/commands/attachments.ts
+var listVerb = {
+  name: "list",
+  summary: "List the most recent attachments, optionally scoped to streams",
+  usage: "threa attachments list [--stream ref]... [--limit n]",
+  help: `threa attachments list [flags]
+
+` + "Browse accessible attachments, newest first (a query-less attachment search). Filter by content with " + "`threa search --what attachments`.\n\n" + `Flags:
+` + `  --stream ref   limit to a source stream (stream_ id or #slug); repeatable
+` + `  --limit n      max results, <= 50 (default 20)
+` + `  --json         force JSON output
+` + "  --help         show this help",
+  options: {
+    stream: { type: "string", multiple: true },
+    limit: { type: "string" }
+  },
+  run: (ctx, _positionals, values) => search(ctx.client, ctx.resolver, {
+    what: "attachments",
+    stream_ids: arrayFlag(values, "stream"),
+    limit: intFlag(values, "limit")
+  }),
+  render: (payload) => {
+    const rows = payload.data ?? [];
+    return rows.map(renderSearchResult).join(`
+`) || "(no attachments)";
+  }
+};
+var getVerb = {
+  name: "get",
+  summary: "Get an attachment's metadata and extracted text, or a signed download URL",
+  usage: "threa attachments get <id> [--url]",
+  help: `threa attachments get <id> [flags]
+
+` + "Retrieve an attachment's metadata and extracted text. With --url, instead return a short-lived signed URL " + `to download the raw bytes.
+
+` + `Flags:
+` + `  --url     return a short-lived signed download URL instead of the metadata/text
+` + `  --json    force JSON output
+` + "  --help    show this help",
+  options: {
+    url: { type: "boolean" }
+  },
+  run: (ctx, positionals, values) => {
+    const id = positionals[0];
+    if (!id)
+      throw new UsageError("attachments get requires a <id> (an att_ id)");
+    return boolFlag(values, "url") ? getAttachmentDownloadUrl(ctx.client, id) : getAttachment(ctx.client, id);
+  }
+};
+function resolveDownloadTarget(destination, filename) {
+  const isDir = destination.endsWith("/") || existsSync3(destination) && statSync(destination).isDirectory();
+  if (!isDir)
+    return destination;
+  const ext = extname(filename);
+  const stem = basename(filename, ext);
+  let candidate = join5(destination, filename);
+  for (let n = 1;existsSync3(candidate); n++) {
+    candidate = join5(destination, `${stem} (${n})${ext}`);
+  }
+  return candidate;
+}
+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).
+
+` + `Flags:
+` + `  --json    force JSON output
+` + "  --help    show this help",
+  options: {},
+  run: async (ctx, positionals) => {
+    const id = positionals[0];
+    if (!id)
+      throw new UsageError("attachments download requires a <id> (an att_ id)");
+    const [meta, urlResp] = await Promise.all([
+      getAttachment(ctx.client, id),
+      getAttachmentDownloadUrl(ctx.client, id)
+    ]);
+    const url = urlResp.data?.url;
+    if (!url)
+      throw new Error(`no download URL returned 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 };
+  },
+  render: (payload) => {
+    const p = payload;
+    return `downloaded ${p.id ?? "?"} → ${p.path ?? "?"} (${p.sizeBytes ?? 0} bytes)`;
+  }
+};
+var attachmentsNoun = {
+  name: "attachments",
+  summary: "List attachments, get one's text or URL, or download its bytes",
+  verbs: [listVerb, getVerb, downloadVerb]
+};
+
+// 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]",
+  help: `threa conversations list [flags]
+
+` + `List conversations (grouped runs of messages under a stream's effective root), newest activity first.
+
+` + `Flags:
+` + `  --stream ref   scope to a stream (stream_ id or #slug) and its threads
+` + "  --status s     " + CONVERSATION_STATUSES.join(" | ") + `
+` + `  --cursor c     pagination cursor from a previous response
+` + `  --limit n      max results, <= 100 (default 50)
+` + `  --json         force JSON output
+` + "  --help         show this help",
+  options: {
+    stream: { type: "string" },
+    status: { type: "string" },
+    cursor: { type: "string" },
+    limit: { type: "string" }
+  },
+  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")
+  }),
+  render: (payload) => renderList(payload, renderConversationRow, {
+    empty: "(no conversations)",
+    cursorFlag: "cursor"
+  })
+};
+function renderConversationRow(c) {
+  const header = [
+    c.id ?? "?",
+    c.status ?? "?",
+    c.messageCount !== undefined ? `${c.messageCount} msgs` : undefined,
+    fmtTimestamp(c.lastActivityAt) || undefined,
+    streamLabel(c) || undefined
+  ].filter(Boolean).join("  ");
+  const topic = snippet(c.topicSummary ?? c.summary ?? "");
+  return topic ? `${header}
+  ${topic}` : header;
+}
+var readVerb = {
+  name: "read",
+  summary: "Read a conversation with a page of its messages",
+  usage: "threa conversations read <id> [--cursor c] [--limit n]",
+  help: `threa conversations read <id> [flags]
+
+` + `Fetch a conversation and a page of its member messages. Page with --cursor from the previous response.
+
+` + `Flags:
+` + `  --cursor c   pagination cursor from a previous response
+` + `  --limit n    max messages, <= 100 (default 50)
+` + `  --json       force JSON output
+` + "  --help       show this help",
+  options: {
+    cursor: { type: "string" },
+    limit: { type: "string" }
+  },
+  run: (ctx, positionals, values) => {
+    const id = positionals[0];
+    if (!id)
+      throw new UsageError("conversations read requires a <id> (a conv_ id)");
+    return readConversation(ctx.client, ctx.resolver, {
+      conversationId: id,
+      cursor: stringFlag(values, "cursor"),
+      limit: intFlag(values, "limit")
+    });
+  },
+  render: (payload) => {
+    const p = payload;
+    const lines = [];
+    const c = p.conversation;
+    if (c) {
+      lines.push([c.id ?? "?", c.status ?? "?", streamLabel(c) || 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`
+      ].filter(Boolean).join(" · "));
+      const topic = snippet(c.topicSummary ?? c.summary ?? "");
+      if (topic)
+        lines.push(`topic: ${topic}`);
+    }
+    const msgs = p.messages?.data ?? [];
+    lines.push(`messages: ${msgs.length}${p.messages?.hasMore ? " (more)" : ""}`);
+    for (const m of msgs) {
+      const who = m.author?.name ?? m.authorDisplayName ?? "?";
+      const ts = fmtTimestamp(m.createdAt);
+      lines.push(`  ${ts ? `[${ts}] ` : ""}${who}: ${snippet(m.contentMarkdown ?? m.content ?? "", 120)}`);
+    }
+    return lines.join(`
+`);
+  }
+};
+var conversationsNoun = {
+  name: "conversations",
+  summary: "List conversations and read one with its messages",
+  verbs: [listVerb2, readVerb]
+};
+
+// src/commands/delegations.ts
+var OUTCOMES = ["complete", "fail"];
+function renderLifecycle(payload) {
+  const data = payload.data;
+  const lines = [];
+  if (data?.id)
+    lines.push(`delegation: ${data.id}`);
+  if (data?.status)
+    lines.push(`status: ${data.status}`);
+  if (data?.claimToken)
+    lines.push(`claimToken (shown once): ${data.claimToken}`);
+  return lines.join(`
+`) || JSON.stringify(payload);
+}
+var listVerb3 = {
+  name: "list",
+  summary: "List open delegations. --since <iso> returns availability changes after that instant",
+  usage: "threa delegations list [--since iso]",
+  help: `threa delegations list [flags]
+
+` + `List open delegations. Pass --since to poll for a cheap delta.
+
+` + `Flags:
+` + `  --since iso   tasks whose availability changed after this ISO-8601 instant
+` + `  --json        force JSON output
+` + "  --help        show this help",
+  options: {
+    since: { type: "string" }
+  },
+  run: (ctx, _positionals, values) => listDelegations(ctx.client, { since: stringFlag(values, "since") }),
+  render: (payload) => {
+    return renderList(payload, (d) => `${d.id ?? "?"}  ${d.title ?? d.brief ?? ""}`.trimEnd(), { empty: "(no open delegations)" });
+  }
+};
+var getVerb2 = {
+  name: "get",
+  summary: "Inspect a delegation's brief and context before claiming it",
+  usage: "threa delegations get <id>",
+  help: `threa delegations get <id> [--json]
+
+Inspect a delegation without claiming it.
+`,
+  options: {},
+  run: (ctx, positionals) => {
+    const id = positionals[0];
+    if (!id)
+      throw new UsageError("delegations get requires a <delegation-id>");
+    return getDelegation(ctx.client, id);
+  },
+  render: (payload) => JSON.stringify(payload, null, 2)
+};
+var claimVerb = {
+  name: "claim",
+  summary: "Claim an open or historical expired task after inspection; requires --label",
+  usage: "threa delegations claim <id> --label who [--idempotency-key k]",
+  help: `threa delegations claim <id> --label who [flags]
+
+` + "Claim an open or historical expired task after inspecting it with `delegations get`. The claim token is persisted to ~/.threa/state.json (mode 0600, keyed by workspace and " + "delegation), so update and finish reuse it across separate `threa` invocations. The token is shown once.\n\n" + `Flags:
+` + `  --label who           human-readable identity shown on the card (required)
+` + `  --idempotency-key k   persist before claiming to re-key a crashed claim (8-128 chars)
+` + `  --json                force JSON output
+` + "  --help                show this help",
+  options: {
+    label: { type: "string" },
+    "idempotency-key": { type: "string" }
+  },
+  run: (ctx, positionals, values) => {
+    const id = positionals[0];
+    if (!id)
+      throw new UsageError("delegations claim requires a <delegation-id>");
+    const label = stringFlag(values, "label");
+    if (!label)
+      throw new UsageError('delegations claim requires --label "who is claiming"');
+    return claimDelegation(ctx.client, ctx.tokenStore, ctx.config.workspaceId, {
+      delegationId: id,
+      claimedByLabel: label,
+      idempotencyKey: stringFlag(values, "idempotency-key")
+    });
+  },
+  render: renderLifecycle
+};
+var releaseVerb = {
+  name: "release",
+  summary: "Release a live claim back to the open queue",
+  usage: "threa delegations release <id> [--claim-token t]",
+  help: `threa delegations release <id> [flags]
+
+Release a live claim. On success, only a matching stored token is cleared; a replacement token is preserved.
+
+` + `Flags:
+  --claim-token <t>  override the stored token
+  --json             force JSON output
+  --help             show this help`,
+  options: { "claim-token": { type: "string" } },
+  run: (ctx, positionals, values) => {
+    const id = positionals[0];
+    if (!id)
+      throw new UsageError("delegations release requires a <delegation-id>");
+    return releaseDelegation(ctx.client, ctx.tokenStore, ctx.config.workspaceId, {
+      delegationId: id,
+      claimToken: stringFlag(values, "claim-token")
+    });
+  },
+  render: renderLifecycle
+};
+var updateVerb = {
+  name: "update",
+  summary: "Renew the claim; --note posts progress, no note is a pure heartbeat",
+  usage: "threa delegations update <id> [--note ...] [--claim-token t]",
+  help: `threa delegations update <id> [flags]
+
+` + `Renew the claim (15-min TTL). Reuses the stored claim token; pass --claim-token to override or recover it.
+
+` + `Flags:
+` + `  --note text        progress note (renews the TTL); omit for a pure heartbeat
+` + `  --claim-token t    override the stored token
+` + `  --json             force JSON output
+` + "  --help             show this help",
+  options: {
+    note: { type: "string" },
+    "claim-token": { type: "string" }
+  },
+  run: (ctx, positionals, values) => {
+    const id = positionals[0];
+    if (!id)
+      throw new UsageError("delegations update requires a <delegation-id>");
+    return updateDelegation(ctx.client, ctx.tokenStore, ctx.config.workspaceId, {
+      delegationId: id,
+      statusNote: stringFlag(values, "note"),
+      claimToken: stringFlag(values, "claim-token")
+    });
+  },
+  render: renderLifecycle
+};
+var finishVerb = {
+  name: "finish",
+  summary: "Close the task; --outcome complete|fail (fail requires --error)",
+  usage: "threa delegations finish <id> --outcome complete|fail [--result md|-] [--error msg] [--metadata k=v]... " + "[--claim-token t]",
+  help: `threa delegations finish <id> --outcome complete|fail [flags]
+
+` + `Complete or fail a claimed task. Reuses the stored claim token; --claim-token overrides it. On success, clears the token.
+
+` + `Flags:
+` + `  --outcome o        complete | fail (required)
+` + "  --result md        outcome (complete): markdown posted in the thread anchored on the delegation card; `-` reads stdin\n" + `  --error msg        outcome (fail): why it failed
+` + `  --metadata k=v     outcome (complete): stamp the result message; repeatable
+` + `  --claim-token t    override the stored token
+` + `  --json             force JSON output
+` + "  --help             show this help",
+  options: {
+    outcome: { type: "string" },
+    result: { type: "string" },
+    error: { type: "string" },
+    metadata: { type: "string", multiple: true },
+    "claim-token": { type: "string" }
+  },
+  run: async (ctx, positionals, values) => {
+    const id = positionals[0];
+    if (!id)
+      throw new UsageError("delegations finish requires a <delegation-id>");
+    const outcome = enumFlag(values, "outcome", OUTCOMES);
+    if (!outcome)
+      throw new UsageError("delegations finish requires --outcome complete|fail");
+    const rawResult = stringFlag(values, "result");
+    const resultMarkdown = rawResult === "-" ? await ctx.readStdin() : rawResult;
+    const metadataPairs = arrayFlag(values, "metadata");
+    const params = {
+      delegationId: id,
+      outcome,
+      resultMarkdown,
+      metadata: metadataPairs ? kvPairs(metadataPairs) : undefined,
+      errorMessage: stringFlag(values, "error"),
+      claimToken: stringFlag(values, "claim-token")
+    };
+    const argError = finishDelegationArgError(params);
+    if (argError)
+      throw new UsageError(argError);
+    return finishDelegation(ctx.client, ctx.tokenStore, ctx.config.workspaceId, params);
+  },
+  render: renderLifecycle
+};
+var requestAccessVerb = {
+  name: "request-access",
+  summary: "Bot-key only; file an access request for a stream the bot cannot see",
+  usage: "threa delegations request-access <id>",
+  help: `threa delegations request-access <id> [flags]
+
+` + `Bot-key only. File an access request for a stream the bot cannot see, so an admin can grant it.
+
+` + `Flags:
+` + `  --json    force JSON output
+` + "  --help    show this help",
+  options: {},
+  run: (ctx, positionals) => {
+    const id = positionals[0];
+    if (!id)
+      throw new UsageError("delegations request-access requires a <delegation-id>");
+    return requestDelegationAccess(ctx.client, id);
+  },
+  render: renderLifecycle
+};
+var delegationsNoun = {
+  name: "delegations",
+  summary: "Run the delegation lifecycle end to end",
+  verbs: [listVerb3, getVerb2, claimVerb, releaseVerb, updateVerb, finishVerb, requestAccessVerb]
+};
+
+// src/e2e-keys.ts
+import { homedir as homedir4, hostname } from "node:os";
+import { join as join6 } from "node:path";
+
+// ../../extensions/bot-runtime-client/src/crypto.ts
+import { Aes256Gcm, CipherSuite, HkdfSha256 } from "@hpke/core";
+import { DhkemX25519HkdfSha256 } from "@hpke/dhkem-x25519";
+function bytesToBase64(bytes) {
+  const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  let binary = "";
+  for (let i = 0;i < view.length; i++)
+    binary += String.fromCharCode(view[i]);
+  return btoa(binary);
+}
+function base64ToBytes(b64) {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0;i < binary.length; i++)
+    bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+function utf8Encode(text) {
+  return new TextEncoder().encode(text);
+}
+function utf8Decode(bytes) {
+  return new TextDecoder().decode(bytes);
+}
+function concatBytes(...parts) {
+  let total = 0;
+  for (const p of parts)
+    total += p.length;
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const p of parts) {
+    out.set(p, offset);
+    offset += p.length;
+  }
+  return out;
+}
+var suite = null;
+function getSuite() {
+  if (!suite) {
+    suite = new CipherSuite({
+      kem: new DhkemX25519HkdfSha256,
+      kdf: new HkdfSha256,
+      aead: new Aes256Gcm
+    });
+  }
+  return suite;
+}
+async function importRecipientPrivateKey(raw) {
+  const buf = raw instanceof Uint8Array ? raw.buffer.slice(raw.byteOffset, raw.byteOffset + raw.byteLength) : raw;
+  return getSuite().kem.deserializePrivateKey(buf);
+}
+async function exportPrivateKey(key) {
+  return new Uint8Array(await getSuite().kem.serializePrivateKey(key));
+}
+async function hpkeOpen(params) {
+  const buf = await getSuite().open({ recipientKey: params.recipientPrivateKey, enc: params.enc }, params.ct, params.aad);
+  return new Uint8Array(buf);
+}
+var STREAM_ENVELOPE_VERSION = 2;
+var SSK_LENGTH = 32;
+var IV_LENGTH = 12;
+function assertBoundAad(fn, aad) {
+  if (aad.length === 0) {
+    throw new Error(`${fn}: aad must be non-empty (see buildMessageAad/buildWrapAad)`);
+  }
+}
+async function sealMessage(input) {
+  if (input.key.length !== SSK_LENGTH) {
+    throw new Error(`sealMessage: SSK must be ${SSK_LENGTH} bytes, got ${input.key.length}`);
+  }
+  assertBoundAad("sealMessage", input.aad);
+  const iv = new Uint8Array(IV_LENGTH);
+  crypto.getRandomValues(iv);
+  const plaintext = typeof input.payload === "string" ? utf8Encode(input.payload) : new Uint8Array(input.payload);
+  const aad = new Uint8Array(input.aad);
+  const sskKey = await crypto.subtle.importKey("raw", new Uint8Array(input.key), { name: "AES-GCM" }, false, [
+    "encrypt"
+  ]);
+  const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv, additionalData: aad }, sskKey, plaintext));
+  return {
+    envelope: {
+      v: STREAM_ENVELOPE_VERSION,
+      keyGeneration: input.keyGeneration,
+      iv: bytesToBase64(iv),
+      aad: bytesToBase64(aad)
+    },
+    ciphertext
+  };
+}
+async function openMessage(input) {
+  if (input.envelope.v !== STREAM_ENVELOPE_VERSION) {
+    throw new Error(`Unsupported stream envelope version: ${input.envelope.v}`);
+  }
+  if (input.key.length !== SSK_LENGTH) {
+    throw new Error(`openMessage: SSK must be ${SSK_LENGTH} bytes, got ${input.key.length}`);
+  }
+  const aad = base64ToBytes(input.envelope.aad);
+  const sskKey = await crypto.subtle.importKey("raw", new Uint8Array(input.key), { name: "AES-GCM" }, false, [
+    "decrypt"
+  ]);
+  const plaintext = new Uint8Array(await crypto.subtle.decrypt({ name: "AES-GCM", iv: base64ToBytes(input.envelope.iv), additionalData: aad }, sskKey, new Uint8Array(input.ciphertext)));
+  return plaintext;
+}
+async function openMessageAsString(input) {
+  return utf8Decode(await openMessage(input));
+}
+async function unwrapStreamKey(input) {
+  assertBoundAad("unwrapStreamKey", input.aad);
+  const key = await hpkeOpen({
+    recipientPrivateKey: input.recipientPrivateKey,
+    enc: input.enc,
+    ct: input.ct,
+    aad: input.aad
+  });
+  if (key.length !== SSK_LENGTH) {
+    throw new Error(`unwrapStreamKey: recovered key is ${key.length} bytes, expected ${SSK_LENGTH}`);
+  }
+  return key;
+}
+function buildWrapAad(parts) {
+  if (parts.streamId.length === 0 || parts.recipientKeyId.length === 0) {
+    throw new Error("buildWrapAad: streamId and recipientKeyId must be non-empty");
+  }
+  if (parts.streamId.includes("|") || parts.recipientKeyId.includes("|")) {
+    throw new Error("buildWrapAad: streamId and recipientKeyId must not contain '|'");
+  }
+  if (!Number.isInteger(parts.keyGeneration) || parts.keyGeneration < 0) {
+    throw new Error("buildWrapAad: keyGeneration must be a non-negative integer");
+  }
+  return concatBytes(utf8Encode(parts.streamId), utf8Encode("|"), utf8Encode(String(parts.keyGeneration)), utf8Encode("|"), utf8Encode(parts.recipientKeyId));
+}
+function buildMessageAad(parts) {
+  return concatBytes(utf8Encode(parts.streamId), utf8Encode("|"), utf8Encode(parts.messageId), utf8Encode("|"), utf8Encode(parts.senderId));
+}
+var ATTACHMENT_AAD = utf8Encode("threa-attachment-v1");
+var E2E_PAYLOAD_VERSION = 1;
+function serializeSealedPayload(contentMarkdown, extras) {
+  const attachmentRefs = extras?.attachmentRefs;
+  const sources = extras?.sources;
+  const draftContentJson = extras?.draftContentJson;
+  const hasRefs = attachmentRefs !== undefined && attachmentRefs.length > 0;
+  const hasSources = sources !== undefined && sources.length > 0;
+  const hasDraftBody = draftContentJson !== undefined && draftContentJson !== null;
+  if (!hasRefs && !hasSources && !hasDraftBody)
+    return contentMarkdown;
+  return JSON.stringify({
+    __e2ePayload: E2E_PAYLOAD_VERSION,
+    contentMarkdown,
+    attachmentRefs: attachmentRefs ?? [],
+    ...hasSources ? { sources } : {},
+    ...hasDraftBody ? { draftContentJson } : {}
+  });
+}
+function isAttachmentRef(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const r = value;
+  return typeof r.attachmentId === "string" && typeof r.key === "string" && typeof r.iv === "string" && typeof r.filename === "string" && typeof r.mimeType === "string" && typeof r.sizeBytes === "number";
+}
+function isSealedSourceItem(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const s = value;
+  return typeof s.title === "string" && typeof s.url === "string" && (s.type === undefined || typeof s.type === "string") && (s.snippet === undefined || typeof s.snippet === "string");
+}
+function isDocLike(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const v = value;
+  return v.type === "doc" && Array.isArray(v.content);
+}
+function parseSealedPayload(raw) {
+  if (raw.startsWith("{")) {
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed.__e2ePayload === E2E_PAYLOAD_VERSION && typeof parsed.contentMarkdown === "string") {
+        const attachmentRefs = Array.isArray(parsed.attachmentRefs) ? parsed.attachmentRefs.filter(isAttachmentRef) : [];
+        const sources = Array.isArray(parsed.sources) ? parsed.sources.filter(isSealedSourceItem) : [];
+        const draftContentJson = isDocLike(parsed.draftContentJson) ? parsed.draftContentJson : null;
+        return { contentMarkdown: parsed.contentMarkdown, attachmentRefs, sources, draftContentJson };
+      }
+    } catch {}
+  }
+  return { contentMarkdown: raw, attachmentRefs: [], sources: [], draftContentJson: null };
+}
+
+// ../../extensions/bot-runtime-client/src/user-key.ts
+import { argon2id } from "hash-wasm";
+var DEFAULT_KDF_PARAMS = {
+  algorithm: "argon2id",
+  m: 64 * 1024,
+  t: 3,
+  p: 1,
+  version: 19
+};
+var KEK_LENGTH_BYTES = 32;
+var PRIVATE_BUNDLE_VERSION = 1;
+var IV_LENGTH2 = 12;
+var ARGON2_VERSION = 19;
+async function deriveKEK(passphrase, salt, params = DEFAULT_KDF_PARAMS) {
+  if (params.algorithm !== "argon2id") {
+    throw new Error(`Unsupported KDF algorithm: ${params.algorithm}`);
+  }
+  if (params.version !== ARGON2_VERSION) {
+    throw new Error(`Unsupported Argon2 version: ${params.version}`);
+  }
+  const raw = await argon2id({
+    password: passphrase,
+    salt,
+    iterations: params.t,
+    parallelism: params.p,
+    memorySize: params.m,
+    hashLength: KEK_LENGTH_BYTES,
+    outputType: "binary"
+  });
+  return crypto.subtle.importKey("raw", new Uint8Array(raw), { name: "AES-GCM" }, false, ["decrypt"]);
+}
+
+class WrongPassphraseError extends Error {
+  constructor() {
+    super("Wrapped private bundle did not open with this passphrase");
+    this.name = "WrongPassphraseError";
+  }
+}
+async function unwrapPrivate(bundle, kek) {
+  if (bundle.length < 1 + IV_LENGTH2 + 1) {
+    throw new Error("Wrapped private bundle is too short");
+  }
+  const version = bundle[0];
+  if (version !== PRIVATE_BUNDLE_VERSION) {
+    throw new Error(`Unsupported private bundle version: ${version}`);
+  }
+  const iv = bundle.slice(1, 1 + IV_LENGTH2);
+  const ciphertext = bundle.slice(1 + IV_LENGTH2);
+  const plaintext = await crypto.subtle.decrypt({ name: "AES-GCM", iv }, kek, ciphertext).catch(() => {
+    throw new WrongPassphraseError;
+  });
+  const privBytes = new Uint8Array(plaintext);
+  return importRecipientPrivateKey(privBytes);
+}
+async function unlockUserKey(input) {
+  const kek = await deriveKEK(input.passphrase, input.kdfSalt, input.kdfParams);
+  return unwrapPrivate(input.encryptedPrivateBundle, kek);
+}
+
+// src/e2e-keys.ts
+function keyDirOf(choice) {
+  return choice.dir ?? join6(homedir4(), ".threa", "e2e-keys");
+}
+function openKeyStore(choice, account) {
+  const dir = keyDirOf(choice);
+  return resolveKeyStore({
+    ...choice.requested === undefined ? {} : { requested: choice.requested },
+    platform: process.platform,
+    dir,
+    hasExistingFileKey: new FileKeyStore({ dir }).read(account) !== undefined
+  });
+}
+function fetchPrincipal(client) {
+  return client.get("/me").then((response) => response.data);
+}
+async function principalForKey(client, workspaceId) {
+  const me = await fetchPrincipal(client);
+  const userId = me.userId;
+  if (!userId) {
+    throw new Error(`threa: end-to-end keys belong to a person, but this API key acts as ${me.kind}. ` + `Use your own key, not a bot's.`);
+  }
+  return { account: e2eUserKeyAccount(workspaceId, userId), userId };
+}
+var NO_USER_KEY_HINT = 'threa: this stream is end-to-end encrypted, and no key is unlocked on this machine — run "threa e2e unlock"';
+async function resolveSealedKeyAccounts(params) {
+  const me = await fetchPrincipal(params.client);
+  if (me.kind !== "bot") {
+    const userId = me.userId;
+    if (!userId)
+      throw new Error(`threa: GET /me named no principal id for ${me.kind}`);
+    const account2 = e2eUserKeyAccount(params.config.workspaceId, userId);
+    return { senderId: userId, accountFor: () => account2, missingKeyHint: () => NO_USER_KEY_HINT };
+  }
+  const botId = me.botId;
+  if (!botId)
+    throw new Error("threa: GET /me named no bot id");
+  const scope = params.config.keyScope ?? "host";
+  if (scope === "instance" && !params.config.instanceId) {
+    throw new Error('threa: keyScope "instance" needs an instanceId in the config (THREA_INSTANCE_ID)');
+  }
+  const account = e2eKeyAccount({
+    scope,
+    hostname: hostname(),
+    instanceId: params.config.instanceId ?? "",
+    identitySeed: params.config.apiKey
+  });
+  return {
+    senderId: botId,
+    accountFor: (streamId) => account ?? e2eStreamKeyAccount(streamId),
+    missingKeyHint: (missing, store) => `threa: this stream is end-to-end encrypted, and this bot holds no key in ${store.describe} ` + `as ${missing} — start the runtime that owns this key, or set keyScope to the one it uses ` + `(currently "${scope}")`
+  };
+}
+async function accountForKey(client, workspaceId) {
+  return (await principalForKey(client, workspaceId)).account;
+}
+async function unlockE2eKey(params) {
+  if (!params.passphrase)
+    throw new Error("threa: no passphrase given");
+  const account = await accountForKey(params.client, params.workspaceId);
+  const key = (await params.client.get("/me/e2e-key")).data;
+  const privateKey = await unlockUserKey({
+    passphrase: params.passphrase,
+    encryptedPrivateBundle: base64ToBytes(key.encryptedPrivateBundle),
+    kdfSalt: base64ToBytes(key.kdfSalt),
+    kdfParams: key.kdfParams
+  }).catch((error) => {
+    if (error instanceof WrongPassphraseError) {
+      throw new Error("threa: that passphrase does not open your encryption key");
+    }
+    throw error;
+  });
+  const record = {
+    keyId: key.keyId,
+    publicKey: key.publicKey,
+    privateKey: bytesToBase64(await exportPrivateKey(privateKey))
+  };
+  const store = openKeyStore(params.choice, account);
+  const held = store.read(account);
+  if (held?.keyId !== record.keyId || held.privateKey !== record.privateKey)
+    store.write(account, record);
+  return {
+    keyId: record.keyId,
+    account,
+    store: store.kind,
+    storeDescription: store.describe,
+    createdAt: key.createdAt,
+    unchanged: held?.keyId === record.keyId && held.privateKey === record.privateKey
+  };
+}
+async function e2eKeyStatus(params) {
+  const account = await accountForKey(params.client, params.workspaceId);
+  const store = openKeyStore(params.choice, account);
+  const held = store.read(account);
+  const serverKeyId = await params.client.get("/me/e2e-key").then((response) => response.data.keyId).catch((error) => {
+    if (error instanceof ThreaApiError && error.status === 404)
+      return;
+    throw error;
+  });
+  return {
+    held: held !== undefined,
+    ...held ? { keyId: held.keyId } : {},
+    ...serverKeyId === undefined ? {} : { serverKeyId },
+    current: held !== undefined && held.keyId === serverKeyId,
+    account,
+    store: store.kind,
+    storeDescription: store.describe
+  };
+}
+async function lockE2eKey(params) {
+  const account = await accountForKey(params.client, params.workspaceId);
+  const store = openKeyStore(params.choice, account);
+  const removed = store.read(account) !== undefined;
+  store.remove(account);
+  return { account, store: store.kind, storeDescription: store.describe, removed };
+}
+
+// src/commands/key-store.ts
+var KEY_STORE_OPTIONS = {
+  "key-store": { type: "string" },
+  "key-dir": { type: "string" }
+};
+var KEY_STORE_FLAGS = `  --key-store keychain|file   where the key is kept (default: the OS keychain)
+` + `  --key-dir <path>            directory for a file store (default: ~/.threa/e2e-keys)
+`;
+function storeChoice(values, config) {
+  const requested = stringFlag(values, "key-store");
+  if (requested !== undefined && !E2E_KEY_STORE_KINDS.includes(requested)) {
+    throw new UsageError(`--key-store must be one of ${E2E_KEY_STORE_KINDS.join(", ")} — got "${requested}"`);
+  }
+  const dir = stringFlag(values, "key-dir") ?? config.keyDir;
+  const store = requested ?? config.keyStore;
+  return {
+    ...store === undefined ? {} : { requested: store },
+    ...dir === undefined ? {} : { dir }
+  };
+}
+
+// src/commands/e2e.ts
+async function readPassphrase(readStdin) {
+  const input = process.stdin;
+  if (!input.isTTY)
+    return (await readStdin()).replace(/\r?\n$/, "");
+  process.stderr.write("Passphrase: ");
+  input.setRawMode(true);
+  input.resume();
+  input.setEncoding("utf8");
+  try {
+    let typed = "";
+    for await (const chunk of input) {
+      for (const char of chunk) {
+        if (char === "\r" || char === `
+` || char === "\x04")
+          return typed;
+        if (char === "\x03")
+          throw new UsageError("cancelled");
+        if (char === "" || char === "\b")
+          typed = typed.slice(0, -1);
+        else
+          typed += char;
+      }
+    }
+    return typed;
+  } finally {
+    input.setRawMode(false);
+    input.pause();
+    process.stderr.write(`
+`);
+  }
+}
+var unlockVerb = {
+  name: "unlock",
+  summary: "Open your encryption key with your passphrase and keep it on this machine",
+  usage: "threa e2e unlock [--key-store keychain|file] [--key-dir <path>]",
+  help: `threa e2e unlock [flags]
+
+` + "Fetch the encrypted bundle holding your identity key, open it with your passphrase, and file the key on " + "this machine so sealed streams can be read and written here. The passphrase is typed at the prompt (never " + "echoed) or piped on stdin; it is never sent anywhere, and neither is the key. Run it again after changing " + `your passphrase or rotating the key — it replaces what this machine holds.
+
+` + `Flags:
+` + KEY_STORE_FLAGS + `  --json                      force JSON output
+` + "  --help                      show this help",
+  options: KEY_STORE_OPTIONS,
+  run: async (ctx, _positionals, values) => {
+    const choice = storeChoice(values, ctx.config);
+    return unlockE2eKey({
+      client: ctx.client,
+      workspaceId: ctx.config.workspaceId,
+      passphrase: await readPassphrase(ctx.readStdin),
+      choice
+    });
+  },
+  render: (payload) => {
+    const p = payload;
+    return p.unchanged ? `${p.keyId ?? "?"} was already unlocked in ${p.storeDescription ?? "?"}` : `unlocked ${p.keyId ?? "?"} into ${p.storeDescription ?? "?"}`;
+  }
+};
+var statusVerb = {
+  name: "status",
+  summary: "Show whether this machine holds your encryption key, and whether it is current",
+  usage: "threa e2e status [--key-store keychain|file] [--key-dir <path>]",
+  help: `threa e2e status [flags]
+
+` + "Report the key this machine holds and the key the workspace has active for you. They differ after the web " + `app rotates your key, which is when sealed streams stop opening here until you unlock again.
+
+` + `Flags:
+` + KEY_STORE_FLAGS + `  --json                      force JSON output
+` + "  --help                      show this help",
+  options: KEY_STORE_OPTIONS,
+  run: (ctx, _positionals, values) => e2eKeyStatus({ client: ctx.client, workspaceId: ctx.config.workspaceId, choice: storeChoice(values, ctx.config) }),
+  render: (payload) => {
+    const p = payload;
+    if (!p.held) {
+      return p.serverKeyId ? `no key on this machine — run "threa e2e unlock" to open ${p.serverKeyId}` : "no key on this machine, and none set up in the workspace";
+    }
+    return p.current ? `holding ${p.keyId ?? "?"} (current)` : `holding ${p.keyId ?? "?"}, but the workspace has moved to ${p.serverKeyId ?? "no key"} — unlock again`;
+  }
+};
+var lockVerb = {
+  name: "lock",
+  summary: "Forget the encryption key this machine holds",
+  usage: "threa e2e lock [--key-store keychain|file] [--key-dir <path>]",
+  help: `threa e2e lock [flags]
+
+` + "Remove your identity key from this machine. Sealed streams stop opening here until you unlock again. The " + `key itself is untouched everywhere else — this forgets a copy, it does not revoke anything.
+
+` + `Flags:
+` + KEY_STORE_FLAGS + `  --json                      force JSON output
+` + "  --help                      show this help",
+  options: KEY_STORE_OPTIONS,
+  run: (ctx, _positionals, values) => lockE2eKey({ client: ctx.client, workspaceId: ctx.config.workspaceId, choice: storeChoice(values, ctx.config) }),
+  render: (payload) => {
+    const p = payload;
+    return p.removed ? `forgot the key in ${p.storeDescription ?? "?"}` : "no key was held on this machine";
+  }
+};
+var e2eNoun = {
+  name: "e2e",
+  summary: "Unlock, inspect, and forget your end-to-end encryption key on this machine",
+  verbs: [unlockVerb, statusVerb, lockVerb]
+};
+
+// src/commands/identity.ts
+var whoamiCommand = {
+  name: "whoami",
+  summary: "Show the authenticated principal, API version, and the bound workspace",
+  usage: "threa whoami",
+  help: `threa whoami
+
+` + "Return the authenticated principal for the configured API key (user or bot), the resolved API version, " + "and the base URL and workspace this CLI is bound to. Use it to confirm the key works. When the config " + 'declares a principal ("principal": "bot"|"user"), the declared kind is shown too and a mismatched key ' + `refuses to run.
+
+` + `Flags:
+` + `  --json / -o json    force JSON output
+` + "  --help    show this help",
+  options: {},
+  run: (ctx) => whoami(ctx.client, ctx.config),
+  render: (payload) => {
+    const p = payload;
+    const who = p.principal?.userId ?? p.principal?.botId ?? "?";
+    return [
+      `principal: ${p.principal?.kind ?? "?"} ${who}`,
+      ...p.declaredPrincipal ? [`declared:  ${p.declaredPrincipal}`] : [],
+      `workspace: ${p.workspaceId ?? "?"}`,
+      `baseUrl:   ${p.baseUrl ?? "?"}`
+    ].join(`
+`);
+  }
+};
+
+// src/commands/labels.ts
+var listVerb4 = {
+  name: "list",
+  summary: "List this key actor's labels and assignments",
+  usage: "threa labels list",
+  help: `threa labels list [flags]
+
+` + "List this key actor's labels and their resource assignments. Every label is private to the actor the API " + `key acts as; you never see another actor's labels.
+
+` + `Flags:
+` + `  --json    force JSON output
+` + "  --help    show this help",
+  options: {},
+  run: (ctx) => listLabels(ctx.client),
+  render: (payload) => {
+    const p = payload;
+    const rows = p.data?.labels ?? [];
+    return rows.map((l) => `${l.id ?? "?"}  ${l.emoji ? `${l.emoji} ` : ""}${l.name ?? ""}`.trimEnd()).join(`
+`) || "(no labels)";
+  }
+};
+var addVerb = {
+  name: "add",
+  summary: "Attach a label to a stream by name (found-or-created, idempotent)",
+  usage: "threa labels add <name> <stream-ref> [--color #RRGGBB] [--emoji e] [--description d]",
+  help: `threa labels add <name> <stream-ref> [flags]
+
+` + "Attach a label to a stream, identifying the label by its name. The label is found-or-created for this key " + "actor and then assigned, so re-applying the same name is idempotent. Any appearance flag you supply " + "overwrites that field on the existing label everywhere it is used, not only at creation. <stream-ref> is a " + `stream_ id or #channel-slug.
+
+` + `Flags:
+` + `  --color #RRGGBB   set the label color
+` + `  --emoji e         set the label emoji
+` + `  --description d   set the label description
+` + `  --json            force JSON output
+` + "  --help            show this help",
+  options: {
+    color: { type: "string" },
+    emoji: { type: "string" },
+    description: { type: "string" }
+  },
+  run: (ctx, positionals, values) => {
+    const name = positionals[0];
+    if (!name)
+      throw new UsageError("labels add requires a <name>");
+    const ref = positionals[1];
+    if (!ref)
+      throw new UsageError("labels add requires a <stream-ref> (a stream_ id or #channel-slug)");
+    return applyLabel(ctx.client, ctx.resolver, {
+      name,
+      streamRef: ref,
+      color: stringFlag(values, "color"),
+      emoji: stringFlag(values, "emoji"),
+      description: stringFlag(values, "description")
+    });
+  },
+  render: (payload) => {
+    const label = payload.data?.label;
+    return `labeled ${label?.name ?? "?"}`;
+  }
+};
+var removeVerb = {
+  name: "remove",
+  summary: "Remove this key actor's label assignment from a stream",
+  usage: "threa labels remove <name> <stream-ref>",
+  help: `threa labels remove <name> <stream-ref> [flags]
+
+` + "Remove this key actor's assignment of a label (identified by its name) from a stream. The label itself is " + `not deleted, only its assignment to this stream. <stream-ref> is a stream_ id or #channel-slug.
+
+` + `Flags:
+` + `  --json    force JSON output
+` + "  --help    show this help",
+  options: {},
+  run: (ctx, positionals) => {
+    const name = positionals[0];
+    if (!name)
+      throw new UsageError("labels remove requires a <name>");
+    const ref = positionals[1];
+    if (!ref)
+      throw new UsageError("labels remove requires a <stream-ref> (a stream_ id or #channel-slug)");
+    return removeLabel(ctx.client, ctx.resolver, { name, streamRef: ref });
+  },
+  render: (payload) => {
+    const p = payload;
+    return `unlabeled ${p.name ?? "?"} from ${p.stream_id ?? "?"}`;
+  }
+};
+var labelsNoun = {
+  name: "labels",
+  summary: "List, add, and remove labels on streams",
+  verbs: [listVerb4, addVerb, removeVerb]
+};
+
+// src/commands/mcp.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/principal.ts
+async function assertPrincipal(client, config, { retryDelaysMs = [], sleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms)) } = {}) {
+  if (config.principal === undefined)
+    return;
+  const data = await fetchPrincipal2(client, retryDelaysMs, sleep);
+  if (data.kind === config.principal)
+    return;
+  throw new Error(`threa: config declares principal "${config.principal}" but the key belongs to ${data.kind} ${data.userId ?? data.botId ?? "?"} (INV-11)`);
+}
+async function fetchPrincipal2(client, retryDelaysMs, sleep) {
+  for (let attempt = 0;; attempt++) {
+    try {
+      return (await client.get("/me")).data;
+    } catch (error) {
+      const delay = retryDelaysMs[attempt];
+      if (delay === undefined || !isTransient(error))
+        throw error;
+      process.stderr.write(`[threa] /me failed, retrying: ${error instanceof Error ? error.message : String(error)}
+`);
+      await sleep(delay);
+    }
+  }
+}
+function isTransient(error) {
+  if (!(error instanceof ThreaApiError))
+    return true;
+  return error.status === 0 || error.status === 429 || error.status >= 500;
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/resolver.ts
+var DEFAULT_TTL_MS = 5 * 60 * 1000;
+
+class RefResolver {
+  client;
+  ttlMs;
+  now;
+  channelCache = new Map;
+  streamInfoCache = new Map;
+  allUsersCache;
+  allUsersInFlight;
+  constructor(opts) {
+    this.client = opts.client;
+    this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+    this.now = opts.now ?? Date.now;
+  }
+  async resolveStream(ref) {
+    const trimmed = ref.trim();
+    if (trimmed.startsWith("#"))
+      return this.resolveChannel(trimmed.slice(1));
+    if (trimmed.startsWith("@"))
+      return this.resolveDmWithUser(trimmed.slice(1));
+    return trimmed;
+  }
+  async resolveStreams(refs) {
+    return Promise.all(refs.map((ref) => this.resolveStream(ref)));
+  }
+  async resolveUser(ref) {
+    const trimmed = ref.trim();
+    if (trimmed.startsWith("@"))
+      return this.resolveUserSlug(trimmed.slice(1));
+    return trimmed;
+  }
+  async allUsers() {
+    const hit = this.allUsersCache;
+    if (hit && hit.expires > this.now())
+      return hit.value;
+    if (this.allUsersInFlight)
+      return this.allUsersInFlight;
+    const inFlight = this.client.get(`/users${buildQuery({ limit: 200 })}`).then((resp) => {
+      this.allUsersCache = { value: resp.data, expires: this.now() + this.ttlMs };
+      return resp.data;
+    }).finally(() => {
+      this.allUsersInFlight = undefined;
+    });
+    this.allUsersInFlight = inFlight;
+    return inFlight;
+  }
+  async streamInfo(streamId) {
+    const hit = this.streamInfoCache.get(streamId);
+    if (hit && hit.expires > this.now())
+      return hit.value;
+    let value = null;
+    try {
+      const resp = await this.client.get(`/streams/${encodeURIComponent(streamId)}`);
+      value = resp.data ?? null;
+    } catch {
+      value = null;
+    }
+    this.streamInfoCache.set(streamId, { value, expires: this.now() + this.ttlMs });
+    return value;
+  }
+  async resolveUserSlug(slug) {
+    const target = slug.toLowerCase();
+    const users = await this.allUsers();
+    const bySlug = users.filter((u) => u.slug?.toLowerCase() === target);
+    const matches = bySlug.length > 0 ? bySlug : users.filter((u) => u.name?.toLowerCase() === target);
+    if (matches.length === 1)
+      return matches[0].id;
+    if (matches.length > 1) {
+      throw new UnresolvedRefError(`"@${slug}" is ambiguous. Candidates: ${matches.map((u) => `${u.id} (${u.name}, @${u.slug})`).join("; ")}. Pass the usr_ id.`);
+    }
+    throw new UnresolvedRefError(`No user matches "@${slug}". List the workspace users (list_users tool / \`threa users list\`) to find them, then pass the usr_ id. ` + "Bots and personas are not queryable by slug on the public API; pass their bot_/persona_ id.");
+  }
+  async resolveChannel(slug) {
+    const key = slug.toLowerCase();
+    const hit = this.channelCache.get(key);
+    if (hit && hit.expires > this.now())
+      return hit.value;
+    const resp = await this.client.get(`/streams${buildQuery({ type: "channel", query: slug, limit: 200 })}`);
+    const matches = resp.data.filter((s) => {
+      const streamSlug = s.slug?.toLowerCase();
+      const bareName = typeof s.displayName === "string" ? s.displayName.replace(/^#/, "").toLowerCase() : undefined;
+      return streamSlug === key || bareName === key;
+    });
+    if (matches.length === 1) {
+      const id = matches[0].id;
+      this.channelCache.set(key, { value: id, expires: this.now() + this.ttlMs });
+      return id;
+    }
+    if (matches.length > 1) {
+      throw new UnresolvedRefError(`"#${slug}" is ambiguous. Candidates: ${matches.map((s) => `${s.id} (${s.displayName ?? s.slug})`).join("; ")}. Pass the stream_ id.`);
+    }
+    throw new UnresolvedRefError(`No channel matches "#${slug}". List channels (list_streams tool / \`threa streams list --type channel\`) to find it, then pass the stream_ id.`);
+  }
+  async resolveDmWithUser(slug) {
+    const userId = await this.resolveUserSlug(slug);
+    throw new UnresolvedRefError(`Found user @${slug} (${userId}), but the public API does not expose which DM stream is your 1:1 with them ` + "(DM streams carry no counterpart on the wire). List your DMs (list_streams tool / `threa streams list --type dm`), " + `then read the members of each (read_stream with include_members / \`threa streams read <id> --members\`) to find the one whose members include ${userId}, and pass that stream_ id. ` + "Or target a channel with #channel-slug.");
+  }
+}
+
+// ../../extensions/bot-runtime-client/src/sealed-stream-client.ts
+import { ulid } from "ulid";
+class SealedStreamApiError extends Error {
+  status;
+  code;
+  constructor(message, status, code) {
+    super(message);
+    this.name = "SealedStreamApiError";
+    this.status = status;
+    this.code = code;
+  }
+}
+function reasonOf(error) {
+  return String(error instanceof Error ? error.message : error);
+}
+
+class SealedStreamClient {
+  opts;
+  doFetch;
+  roots = new Map;
+  ssks = new Map;
+  generations = new Map;
+  sender;
+  constructor(opts) {
+    this.opts = opts;
+    this.doFetch = opts.fetch ?? globalThis.fetch;
+  }
+  async readMessages(streamId, opts = {}) {
+    const root = await this.resolveRoot(streamId);
+    const query = new URLSearchParams;
+    if (opts.limit !== undefined)
+      query.set("limit", String(opts.limit));
+    if (opts.before)
+      query.set("before", opts.before);
+    if (opts.after)
+      query.set("after", opts.after);
+    const suffix = query.size > 0 ? `?${query.toString()}` : "";
+    const page = await this.request("GET", `/streams/${streamId}/messages${suffix}`);
+    const messages = [];
+    for (const wire of page.data) {
+      messages.push(await this.openMessage(root, wire));
+    }
+    return { messages, hasMore: page.hasMore };
+  }
+  async sendMessage(streamId, contentMarkdown, opts = {}) {
+    const root = await this.resolveRoot(streamId);
+    const keyGeneration = await this.currentGeneration(root);
+    const key = await this.streamKey(root, keyGeneration);
+    const senderId = await this.resolveSenderId();
+    const clientMessageId = opts.clientMessageId ?? `msg_${ulid()}`;
+    const sealed = await sealMessage({
+      key,
+      keyGeneration,
+      payload: serializeSealedPayload(contentMarkdown, { attachmentRefs: opts.attachmentRefs }),
+      aad: buildMessageAad({ streamId: root, messageId: clientMessageId, senderId })
+    });
+    const created = await this.request("POST", `/streams/${streamId}/messages`, {
+      sealed: { ciphertext: bytesToBase64(sealed.ciphertext), envelope: sealed.envelope },
+      clientMessageId
+    });
+    return { messageId: created.data.id, clientMessageId };
+  }
+  async openSealedBody(streamId, sealed) {
+    const root = await this.resolveRoot(streamId);
+    return this.openBody(root, sealed);
+  }
+  async openBody(root, sealed) {
+    let key;
+    try {
+      key = await this.streamKey(root, sealed.envelope.keyGeneration);
+    } catch (error) {
+      return { contentMarkdown: null, attachmentRefs: [], unreadableReason: reasonOf(error) };
+    }
+    try {
+      const raw = await openMessageAsString({
+        key,
+        ciphertext: base64ToBytes(sealed.ciphertext),
+        envelope: sealed.envelope
+      });
+      const payload = parseSealedPayload(raw);
+      return { contentMarkdown: payload.contentMarkdown, attachmentRefs: payload.attachmentRefs ?? [] };
+    } catch (error) {
+      return { contentMarkdown: null, attachmentRefs: [], unreadableReason: reasonOf(error) };
+    }
+  }
+  async openMessage(root, wire) {
+    const base = {
+      id: wire.id,
+      sequence: wire.sequence,
+      authorId: wire.authorId,
+      authorType: wire.authorType,
+      ...wire.authorDisplayName ? { authorDisplayName: wire.authorDisplayName } : {},
+      createdAt: wire.createdAt,
+      attachmentRefs: []
+    };
+    if (!wire.sealed) {
+      return { ...base, contentMarkdown: null, unreadableReason: "Message carries no stream-key envelope" };
+    }
+    return { ...base, ...await this.openBody(root, wire.sealed) };
+  }
+  async streamKey(root, keyGeneration) {
+    const cached = this.ssks.get(`${root}:${keyGeneration}`);
+    if (cached)
+      return cached;
+    await this.loadWraps(root);
+    const key = this.ssks.get(`${root}:${keyGeneration}`);
+    if (!key) {
+      throw new Error(`No key wrap for generation ${keyGeneration} of ${root} is addressed to a key this client holds`);
+    }
+    return key;
+  }
+  async currentGeneration(root) {
+    await this.loadWraps(root);
+    return this.generations.get(root) ?? 0;
+  }
+  async loadWraps(root) {
+    const identities = await this.opts.keys.keysForStream(root);
+    if (identities.length === 0) {
+      throw new Error(`No end-to-end key available for ${root}`);
+    }
+    const wraps = await this.request("GET", `/streams/${root}/e2e/key-wraps`);
+    this.generations.set(root, wraps.data.currentKeyGeneration);
+    for (const wrap of wraps.data.wraps) {
+      const identity = identities.find((candidate) => candidate.keyId === wrap.recipientKeyId);
+      if (!identity)
+        continue;
+      if (this.ssks.has(`${root}:${wrap.keyGeneration}`))
+        continue;
+      const key = await unwrapStreamKey({
+        enc: base64ToBytes(wrap.wrapEnc),
+        ct: base64ToBytes(wrap.wrapCt),
+        recipientPrivateKey: identity.privateKey,
+        aad: buildWrapAad({
+          streamId: root,
+          keyGeneration: wrap.keyGeneration,
+          recipientKeyId: wrap.recipientKeyId
+        })
+      });
+      this.ssks.set(`${root}:${wrap.keyGeneration}`, key);
+    }
+  }
+  async resolveRoot(streamId) {
+    let pending = this.roots.get(streamId);
+    if (!pending) {
+      pending = this.request("GET", `/streams/${streamId}`).then((stream) => stream.data.rootStreamId ?? stream.data.id).catch((error) => {
+        this.roots.delete(streamId);
+        throw error;
+      });
+      this.roots.set(streamId, pending);
+    }
+    return pending;
+  }
+  async resolveSenderId() {
+    if (this.opts.senderId)
+      return this.opts.senderId;
+    if (!this.sender) {
+      this.sender = this.request("GET", "/me").then((me) => {
+        const id = me.data.kind === "bot" ? me.data.botId : me.data.userId;
+        if (!id)
+          throw new Error("GET /me named no principal id");
+        return id;
+      }).catch((error) => {
+        this.sender = undefined;
+        throw error;
+      });
+    }
+    return this.sender;
+  }
+  async request(method, path, body) {
+    const url = `${this.opts.baseUrl.replace(/\/$/, "")}/api/v1/workspaces/${this.opts.workspaceId}${path}`;
+    const response = await this.doFetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.opts.apiKey}`,
+        ...body === undefined ? {} : { "Content-Type": "application/json" }
+      },
+      ...body === undefined ? {} : { body: JSON.stringify(body) }
+    });
+    const text = await response.text();
+    if (!response.ok) {
+      let parsed = {};
+      try {
+        if (text.length > 0)
+          parsed = JSON.parse(text);
+      } catch {
+        parsed = {};
+      }
+      throw new SealedStreamApiError(typeof parsed.message === "string" ? parsed.message : `${method} ${path} failed`, response.status, typeof parsed.code === "string" ? parsed.code : "UNKNOWN");
+    }
+    return text.length > 0 ? JSON.parse(text) : {};
+  }
+}
+
+// src/sealed.ts
+function sealedStreams(params) {
+  let pending;
+  async function build() {
+    const accounts = await resolveSealedKeyAccounts({ client: params.client, config: params.config });
+    const imported = new Map;
+    function identityFor(streamId) {
+      const account = accounts.accountFor(streamId);
+      let identity = imported.get(account);
+      if (!identity) {
+        const store = openKeyStore(params.choice, account);
+        const record = store.read(account);
+        if (!record)
+          return Promise.reject(new Error(accounts.missingKeyHint(account, store)));
+        identity = importRecipientPrivateKey(base64ToBytes(record.privateKey)).then((privateKey) => ({
+          keyId: record.keyId,
+          privateKey
+        }));
+        imported.set(account, identity);
+      }
+      return identity;
+    }
+    const keys = { keysForStream: async (streamId) => [await identityFor(streamId)] };
+    return {
+      identityFor,
+      client: new SealedStreamClient({
+        baseUrl: params.config.baseUrl,
+        apiKey: params.config.apiKey,
+        workspaceId: params.config.workspaceId,
+        keys,
+        senderId: accounts.senderId
+      })
+    };
+  }
+  function sealed() {
+    if (!pending) {
+      pending = build().catch((error) => {
+        pending = undefined;
+        throw error;
+      });
+    }
+    return pending;
+  }
+  return {
+    async open(streamId, body) {
+      const { client, identityFor } = await sealed();
+      await identityFor(streamId);
+      return client.openSealedBody(streamId, body);
+    },
+    async send(streamId, contentMarkdown, opts) {
+      const { client, identityFor } = await sealed();
+      await identityFor(streamId);
+      return client.sendMessage(streamId, contentMarkdown, {
+        ...opts.clientMessageId === undefined ? {} : { clientMessageId: opts.clientMessageId }
+      });
+    }
+  };
+}
+
+// src/tools/attachments.ts
+import { z } from "zod";
+function registerAttachmentTools(server, client) {
+  server.registerTool("get_attachment", {
+    title: "Get an attachment",
+    description: "Retrieve an attachment's metadata (filename, mime type, size, processing status) and its extracted " + "content when available: `data.extraction` carries a summary and `fullText` (the full extracted " + "text) once processing has finished — it is null while extraction is pending or when the file type " + "yields no text. Read the text here rather than downloading the file when you only need its content.",
+    inputSchema: {
+      attachment_id: z.string()
+    }
+  }, async ({ attachment_id }) => runTool(() => getAttachment(client, attachment_id)));
+  server.registerTool("get_attachment_download_url", {
+    title: "Get an attachment download URL",
+    description: "Create a short-lived signed URL to download the raw bytes of an attachment. The response is " + "{ data: { url, expiresIn } } where expiresIn is the lifetime in seconds — fetch the bytes yourself promptly, the " + "URL expires. Prefer get_attachment when you only need the extracted text.",
+    inputSchema: {
+      attachment_id: z.string()
+    }
+  }, async ({ attachment_id }) => runTool(() => getAttachmentDownloadUrl(client, attachment_id)));
+}
+
+// src/tools/conversations.ts
+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).",
+    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()
+    }
+  }, async ({ stream_id, status, cursor, limit }) => runTool(() => listConversations(client, resolver, { streamRef: stream_id, status, cursor, limit })));
+  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.",
+    inputSchema: {
+      conversation_id: z2.string(),
+      cursor: z2.string().optional(),
+      limit: z2.number().int().min(1).max(100).optional()
+    }
+  }, async ({ conversation_id, cursor, limit }) => runTool(() => readConversation(client, resolver, { conversationId: conversation_id, cursor, limit })));
+}
+
+// src/tools/delegations.ts
+import { z as z3 } from "zod";
+function registerDelegationTools(server, client, store, workspaceId) {
+  server.registerTool("list_delegations", {
+    title: "List open delegations",
+    description: "List open delegations (the queue for `delegate_task` hand-offs). Only " + "streams this key can access appear. The lifecycle loop is: list_delegations → get_delegation → " + "claim_delegation → optional update_delegation while you work → finish_delegation or release_delegation. 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. `status` is `open` (the only listable state). " + "`since`: ISO-8601 datetime; returns tasks whose availability changed after that instant. Useful for polling deltas.",
+    inputSchema: {
+      status: z3.literal("open").optional(),
+      since: z3.string().optional()
+    }
+  }, async ({ status, since }) => runTool(() => listDelegations(client, { status, since })));
+  server.registerTool("get_delegation", {
+    title: "Inspect a delegation",
+    description: "Inspect the full brief and context refs before deciding whether to claim. This never creates a claim or token.",
+    inputSchema: { delegation_id: z3.string() }
+  }, async ({ delegation_id }) => runTool(() => getDelegation(client, delegation_id)));
+  server.registerTool("claim_delegation", {
+    title: "Claim an open or historical expired delegation",
+    description: "After inspecting with get_delegation, atomically claim an open delegation or a historical task still stored as expired. On success, returns the brief, context refs, and `claimToken` (shown once). Every later lifecycle call for this delegation needs that " + "token; this server also stashes it in a persistent state file (`~/.threa/state.json`) so you can omit " + "`claim_token` on the follow-up calls, and it survives a server restart. The claim has a 15-minute TTL: " + "call update_delegation to renew it before it lapses, or the task returns to the queue. `claimed_by_label` " + `is your human-readable identity shown on the card (e.g. "Kris's MacBook / Claude Code"). ` + "`idempotency_key` re-keys your own live claim after a crash: persist it BEFORE claiming, and a retry " + "bearing the same key hands back a fresh token and lease instead of a 409. A 409 DELEGATION_NOT_OPEN means " + "the task is not currently claimable or re-keyable; inspect its status and claim expiry. A lapsed-but-unswept claim must wait for the sweep to reopen it. After claiming, keep the lease alive with " + "update_delegation and close out with finish_delegation.",
+    inputSchema: {
+      delegation_id: z3.string(),
+      claimed_by_label: z3.string().min(1).max(200),
+      idempotency_key: z3.string().min(8).max(128).optional()
+    }
+  }, async ({ delegation_id, claimed_by_label, idempotency_key }) => runTool(() => claimDelegation(client, store, workspaceId, {
+    delegationId: delegation_id,
+    claimedByLabel: claimed_by_label,
+    idempotencyKey: idempotency_key
+  })));
+  server.registerTool("release_delegation", {
+    title: "Release a delegation claim",
+    description: "Return a live claim to the open queue without failing it. Uses the stored token unless overridden with `claim_token`. After a successful release, only the matching stored token is cleared; a replacement token is preserved.",
+    inputSchema: { delegation_id: z3.string(), claim_token: z3.string().optional() }
+  }, async ({ delegation_id, claim_token }) => runTool(() => releaseDelegation(client, store, workspaceId, { delegationId: delegation_id, claimToken: claim_token })));
+  server.registerTool("update_delegation", {
+    title: "Update a delegation's progress",
+    description: "Keep a claimed delegation alive and, optionally, report progress. Pass `status_note` to mark the " + "delegation running and put a free-text note on its card (each note replaces the previous one) — this " + "also renews the claim's 15-minute TTL. Omit `status_note` for a pure heartbeat: liveness only, no card " + "change, TTL renewed. Uses the claim token from claim_delegation (persisted to `~/.threa/state.json`); " + "pass `claim_token` to override the stored one. A 404 means the claim lapsed or was lost — re-claim the " + "delegation.",
+    inputSchema: {
+      delegation_id: z3.string(),
+      status_note: z3.string().min(1).max(2000).optional(),
+      claim_token: z3.string().optional()
+    }
+  }, async ({ delegation_id, status_note, claim_token }) => runTool(() => updateDelegation(client, store, workspaceId, {
+    delegationId: delegation_id,
+    statusNote: status_note,
+    claimToken: claim_token
+  })));
+  server.registerTool("finish_delegation", {
+    title: "Finish a delegation",
+    description: 'Complete or fail a claimed delegation. `outcome: "complete"` marks success. Provide `result_markdown` ' + "to post to the thread anchored on the delegation card (authored as this key's identity, entering the normal " + "message pipeline so workspace memory can capture it) or omit it to close without a message, and `metadata` (a flat " + "string→string map) stamps the result message for later find_messages_by_metadata lookup. " + '`outcome: "fail"` marks failure and REQUIRES `error_message` (recorded on the card so the delegator ' + "knows why); it rejects result_markdown/metadata. `error_message` is only valid with outcome=fail. Uses " + "the stored claim token (pass `claim_token` to override). On success the stored token is cleared — the " + "claim is spent.",
+    inputSchema: {
+      delegation_id: z3.string(),
+      outcome: z3.enum(["complete", "fail"]),
+      result_markdown: z3.string().min(1).max(50000).optional(),
+      metadata: z3.record(z3.string(), z3.string()).optional(),
+      error_message: z3.string().min(1).max(2000).optional(),
+      claim_token: z3.string().optional()
+    }
+  }, async ({ delegation_id, outcome, result_markdown, metadata, error_message, claim_token }) => runTool(() => finishDelegation(client, store, workspaceId, {
+    delegationId: delegation_id,
+    outcome,
+    resultMarkdown: result_markdown,
+    metadata,
+    errorMessage: error_message,
+    claimToken: claim_token
+  })));
+  server.registerTool("request_delegation_access", {
+    title: "Request access to a delegation's stream",
+    description: "Bot-key only. When a workspace (bot) key sees a delegation it cannot claim because the bot lacks a " + "grant on the stream, file an access request that renders as a card for a member to approve. Returns " + "already_granted (no card) when the bot already has access. A user-scoped key gets 400 " + "USER_KEY_CANNOT_REQUEST_ACCESS — a user key's access follows its user, who should join the stream " + "directly.",
+    inputSchema: {
+      delegation_id: z3.string()
+    }
+  }, async ({ delegation_id }) => runTool(() => requestDelegationAccess(client, delegation_id)));
+}
+
+// src/tools/identity.ts
+function registerIdentityTools(server, client, config) {
+  server.registerTool("whoami", {
+    title: "Who am I",
+    description: "Return the authenticated principal for the configured API key (user or bot), the resolved API " + "version info, and the base URL and workspace this server is bound to. Use it to confirm the key " + "works and to discover your identity before other calls."
+  }, async () => runTool(() => whoami(client, config)));
+}
+
+// src/tools/labels.ts
+import { z as z4 } from "zod";
+function registerLabelTools(server, client, resolver) {
+  server.registerTool("list_labels", {
+    title: "List labels",
+    description: "List this key actor's labels and their resource assignments. Every label is private to the actor " + "the API key acts as; you never see another actor's labels.",
+    inputSchema: {}
+  }, async () => runTool(() => listLabels(client)));
+  server.registerTool("apply_label", {
+    title: "Apply a label to a stream",
+    description: "Attach a label to a stream, identifying the label by its `name`. The label is found-or-created for " + "this key actor (labels are private per actor and keyed by their text), then assigned — so re-applying " + "the same name is idempotent. Any appearance field you supply (`color` as #RRGGBB, `emoji`, " + "`description`) overwrites that field on the existing label every time, not only at creation — so omit " + "them unless you intend to recolor/re-emoji the label wherever it is already used. `stream_id` accepts a " + "stream_ id or `#channel-slug`.",
+    inputSchema: {
+      name: z4.string().min(1).max(100),
+      stream_id: z4.string(),
+      color: z4.string().optional(),
+      emoji: z4.string().optional(),
+      description: z4.string().optional()
+    }
+  }, async ({ name, stream_id, color, emoji, description }) => runTool(() => applyLabel(client, resolver, { name, streamRef: stream_id, color, emoji, description })));
+  server.registerTool("remove_label", {
+    title: "Remove a label from a stream",
+    description: "Remove this key actor's assignment of a label (identified by its `name`) from a stream (`stream_id` " + "accepts a stream_ id or `#channel-slug`). The label itself is not deleted, only its assignment to this stream.",
+    inputSchema: {
+      name: z4.string().min(1).max(100),
+      stream_id: z4.string()
+    }
+  }, async ({ name, stream_id }) => runTool(() => removeLabel(client, resolver, { name, streamRef: stream_id })));
+}
+
+// src/tools/memos.ts
+import { z as z5 } from "zod";
+function registerMemoTools(server, client) {
+  server.registerTool("get_memo", {
+    title: "Get a memo",
+    description: "Retrieve one memo by id, together with its source stream and the source messages it was extracted " + "from (provenance) plus any successor memo id. Use this to trace a memory back to the exact " + "conversation that produced it. Find memos in the first place with the `search` tool (what: 'memos').",
+    inputSchema: {
+      memo_id: z5.string()
+    }
+  }, async ({ memo_id }) => runTool(() => getMemo(client, memo_id)));
+}
+
+// src/tools/messages.ts
+import { z as z6 } from "zod";
+function registerMessageTools(server, client, resolver, sealed) {
+  server.registerTool("send_message", {
+    title: "Send a message to a stream",
+    description: "Post a markdown message to a stream. `stream_id` accepts a stream_ id or a `#channel-slug` (an " + "`@user-slug` DM ref is not resolvable — pass the DM's stream_ id). Content is markdown: mentions are `[@slug](user:usr_x)` / " + "`[@slug](persona:persona_x)` / `[#slug](channel:stream_x)`, and plain URLs unfurl into link previews. " + "Conversation control: pass `conversation_id` to append to an existing conversation (it must live under " + "the same root stream as the target, else the API returns 400 CONVERSATION_NOT_IN_ROOT), or set " + "`start_conversation: true` to open a fresh conversation; setting both is an error. Idempotency: a " + "`client_message_id` is auto-generated (`mcp-<uuid>`) when you omit one so a retried call never " + "double-posts — the effective id is returned as `clientMessageId`. `metadata` is a flat string→string " + "map (≤20 keys, no `threa.` key prefix) stamped on the message for later lookup via " + "find_messages_by_metadata. The result carries the created message plus `conversationId` when a " + "conversation directive was applied. Into an end-to-end-encrypted stream the content is sealed with " + "the key this machine holds before it leaves this process, and the result carries `sealed: true`; " + "`metadata` and the conversation args are rejected there because they would travel in the clear.",
+    inputSchema: {
+      stream_id: z6.string(),
+      content: z6.string().min(1),
+      client_message_id: z6.string().max(128).optional(),
+      metadata: z6.record(z6.string(), z6.string()).optional(),
+      conversation_id: z6.string().optional(),
+      start_conversation: z6.boolean().optional()
+    }
+  }, async ({ stream_id, content, client_message_id, metadata, conversation_id, start_conversation }) => runTool(() => sendMessage(client, resolver, {
+    streamRef: stream_id,
+    content,
+    clientMessageId: client_message_id,
+    metadata,
+    conversationId: conversation_id,
+    startConversation: start_conversation,
+    sealed
+  })));
+  server.registerTool("update_message", {
+    title: "Edit a message",
+    description: "Replace a message's content with new markdown. Only works on messages this API key sent — the API " + "rejects edits to any other author's message. Returns the updated message.",
+    inputSchema: {
+      message_id: z6.string(),
+      content: z6.string().min(1)
+    }
+  }, async ({ message_id, content }) => runTool(() => updateMessage(client, message_id, content)));
+  server.registerTool("delete_message", {
+    title: "Delete a message",
+    description: "Delete a message. Only works on messages this API key sent — the API rejects deletes of any other " + "author's message. Returns { deleted: true, message_id } on success.",
+    inputSchema: {
+      message_id: z6.string()
+    }
+  }, async ({ message_id }) => runTool(() => deleteMessage(client, message_id)));
+  server.registerTool("find_messages_by_metadata", {
+    title: "Find messages by metadata",
+    description: "Find non-deleted messages whose `metadata` contains every given key/value pair (exact AND-containment, " + "not text search). Use this for dedup and lookup by external reference you stamped at send time, e.g. " + '{ "github.pr": "org/repo#42" } to check whether a message was already posted for that PR. Narrow ' + "with `stream_id` (accepts a stream_ id or `#channel-slug`). limit ≤ 100 (default 20). Message rows " + "carry author { id, type, name, slug? }.",
+    inputSchema: {
+      metadata: z6.record(z6.string(), z6.string()),
+      stream_id: z6.string().optional(),
+      limit: z6.number().int().min(1).max(100).optional()
+    }
+  }, async ({ metadata, stream_id, limit }) => runTool(() => findMessagesByMetadata(client, resolver, { metadata, streamRef: stream_id, limit })));
+}
+
+// src/tools/search.ts
+import { z as z7 } from "zod";
+function registerSearchTools(server, client, resolver) {
+  server.registerTool("search", {
+    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: '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: {
+      what: z7.enum(SEARCH_WHATS),
+      query: z7.string().optional(),
+      semantic: z7.boolean().optional(),
+      exact: z7.boolean().optional(),
+      stream_ids: z7.array(z7.string()).optional(),
+      type: z7.array(z7.enum(STREAM_TYPES)).optional(),
+      memo_type: z7.array(z7.enum(MEMO_TYPES)).optional(),
+      knowledge_type: z7.array(z7.enum(KNOWLEDGE_TYPES)).optional(),
+      tags: z7.array(z7.string()).optional(),
+      scope: z7.enum(MEMO_SCOPES).optional(),
+      content_types: z7.array(z7.enum(EXTRACTION_CONTENT_TYPES)).optional(),
+      before: z7.string().optional(),
+      after: z7.string().optional(),
+      limit: z7.number().int().min(1).max(100).optional()
+    }
+  }, async (args) => runTool(() => search(client, resolver, args)));
+}
+
+// src/tools/streams.ts
+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.",
+    inputSchema: {
+      type: z8.array(z8.enum(STREAM_TYPES)).optional(),
+      query: z8.string().optional(),
+      after: z8.string().optional(),
+      limit: z8.number().int().min(1).max(200).optional(),
+      include_archived: z8.boolean().optional()
+    }
+  }, async ({ type, query, after, limit, include_archived }) => runTool(() => listStreams(client, { type, query, after, limit, includeArchived: include_archived })));
+  server.registerTool("read_stream", {
+    title: "Read a stream with its messages",
+    description: "Fetch a stream and a page of its messages in one call (concurrent requests). `stream_id` accepts a " + "stream_ id or a `#channel-slug` (an `@user-slug` DM ref is not resolvable — pass the DM's stream_ id). " + "Returns { stream, messages: { data, hasMore } } and, when `include_members` is true, " + "{ members: { data, hasMore, cursor } }. Message rows carry author { id, type, name, slug? } and members " + "carry name/slug, so author identity needs no follow-up. Message paging is by numeric message sequence, " + "NOT a cursor: " + "`before` returns messages before that sequence (older), `after` returns messages after it (newer); " + "pass at most one, and walk pages by taking the boundary message's `sequence`. limit ≤ 100 (default " + "50) applies to messages. If the stream cannot be read the whole call errors — no partial data is " + "returned. In an end-to-end-encrypted stream each body is opened with the key this machine holds, so " + "rows read as normal content; a body sealed to a key generation this key was never wrapped to keeps a " + "null `content` and says why in `unreadableReason`, and the call errors outright when no key is held " + "here at all.",
+    inputSchema: {
+      stream_id: z8.string(),
+      include_members: z8.boolean().optional(),
+      before: z8.string().optional(),
+      after: z8.string().optional(),
+      limit: z8.number().int().min(1).max(100).optional()
+    }
+  }, async ({ stream_id, include_members, before, after, limit }) => runTool(() => readStream(client, resolver, {
+    streamId: stream_id,
+    includeMembers: include_members,
+    before,
+    after,
+    limit,
+    sealed
+  })));
+}
+
+// src/tools/users.ts
+import { z as z9 } from "zod";
+function registerUserTools(server, client) {
+  server.registerTool("list_users", {
+    title: "List workspace users",
+    description: "List users in this workspace. Filter with `query` (text match on name or email — NOT slug; slugs resolve via the @slug ref form). Page by passing the " + "previous response's `cursor` value back as `after`; `hasMore` tells you when to stop. limit ≤ 200 " + "(default 50).",
+    inputSchema: {
+      query: z9.string().optional(),
+      after: z9.string().optional(),
+      limit: z9.number().int().min(1).max(200).optional()
+    }
+  }, async ({ query, after, limit }) => runTool(() => listUsers(client, { query, after, limit })));
+}
+
+// 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.";
+function createThreaMcpServer(config, deps = {}) {
+  const server = new McpServer({ name: "threa", version: "0.1.0" }, { instructions: INSTRUCTIONS });
+  const client = new ThreaApiClient({
+    baseUrl: config.baseUrl,
+    workspaceId: config.workspaceId,
+    apiKey: config.apiKey
+  });
+  const resolver = new RefResolver({ client });
+  const tokenStore = deps.tokenStore ?? new TokenStore;
+  const sealed = sealedStreams({
+    client,
+    config,
+    choice: {
+      ...config.keyStore === undefined ? {} : { requested: config.keyStore },
+      ...config.keyDir === undefined ? {} : { dir: config.keyDir }
+    }
+  });
+  registerIdentityTools(server, client, config);
+  registerStreamTools(server, client, resolver, sealed);
+  registerUserTools(server, client);
+  registerMessageTools(server, client, resolver, sealed);
+  registerSearchTools(server, client, resolver);
+  registerConversationTools(server, client, resolver);
+  registerLabelTools(server, client, resolver);
+  registerMemoTools(server, client);
+  registerAttachmentTools(server, client);
+  registerDelegationTools(server, client, tokenStore, config.workspaceId);
+  return server;
+}
+
+// src/commands/mcp.ts
+async function serveMcp(config) {
+  await assertPrincipal(new ThreaApiClient({ baseUrl: config.baseUrl, workspaceId: config.workspaceId, apiKey: config.apiKey }), config, { retryDelaysMs: [1000, 2000, 4000, 8000] });
+  const server = createThreaMcpServer(config);
+  const transport = new StdioServerTransport;
+  await server.connect(transport);
+  process.stderr.write(`[threa] mcp serve connected; workspace ${config.workspaceId} at ${config.baseUrl}
+`);
+}
+var mcpCommand = {
+  name: "mcp",
+  summary: "Serve the same tools over MCP (`threa mcp serve`) on stdio",
+  usage: "threa mcp serve",
+  help: `threa mcp serve
+
+` + "Run the Threa MCP server over stdio, exposing the same workspace tools to an MCP client (e.g. Claude " + `Code). Register it with:
+` + `  claude mcp add threa --env THREA_API_KEY=... --env THREA_WORKSPACE_ID=... -- threa mcp serve
+
+` + `Flags:
+` + "  --help    show this help",
+  options: {},
+  serve: true,
+  run: (_ctx, positionals) => {
+    const sub = positionals[0];
+    if (sub !== "serve") {
+      throw new UsageError(`unknown mcp subcommand "${sub ?? ""}" — the only subcommand is "serve"`);
+    }
+    return Promise.resolve(undefined);
+  }
+};
+
+// src/commands/messages.ts
+async function resolveContent(raw, readStdin) {
+  const content = raw === "-" ? await readStdin() : raw;
+  if (content.trim() === "")
+    throw new UsageError("content is empty");
+  return content;
+}
+var sendVerb = {
+  name: "send",
+  summary: "Post a markdown message to a stream (content `-` reads stdin)",
+  usage: "threa messages send <stream-ref> <content> [--new-conversation | --conversation conv_id] [--metadata k=v]... " + "[--client-message-id id]",
+  help: `threa messages send <stream-ref> <content> [flags]
+
+` + "Post a markdown message to a stream. <stream-ref> is a stream_ id or #channel-slug. Pass content as the " + "second positional, or `-` to read it from stdin. A client message id is auto-generated (mcp-<uuid>) when " + "you omit --client-message-id, so a retried send never double-posts; the effective id is returned as " + `clientMessageId.
+
+` + 'Into an end-to-end-encrypted stream the body is sealed here, with the key "threa e2e unlock" filed on this ' + "machine — the plaintext never leaves it, and without a key the send fails rather than falling back. Such a " + "stream takes no --metadata and no conversation: both would travel in the clear, so they are refused here " + `rather than dropped.
+
+` + `Flags:
+` + `  --new-conversation      open a fresh conversation (mutually exclusive with --conversation)
+` + `  --conversation conv_id  append to an existing conversation under the same root stream
+` + `  --metadata k=v          stamp flat string metadata; repeatable
+` + `  --client-message-id id  set the idempotency key explicitly (<= 128 chars)
+` + KEY_STORE_FLAGS + `  --json                  force JSON output
+` + "  --help                  show this help",
+  options: {
+    "new-conversation": { type: "boolean" },
+    conversation: { type: "string" },
+    metadata: { type: "string", multiple: true },
+    "client-message-id": { type: "string" },
+    ...KEY_STORE_OPTIONS
+  },
+  run: async (ctx, positionals, values) => {
+    const ref = positionals[0];
+    if (!ref)
+      throw new UsageError("messages send requires a <stream-ref> (a stream_ id or #channel-slug)");
+    const rawContent = positionals[1];
+    if (rawContent === undefined)
+      throw new UsageError("messages send requires <content> (or `-` to read stdin)");
+    const startConversation = boolFlag(values, "new-conversation");
+    const conversationId = stringFlag(values, "conversation");
+    if (sendConversationArgError({ conversationId, startConversation })) {
+      throw new UsageError("pass either --new-conversation or --conversation conv_id, not both");
+    }
+    const metadataPairs = arrayFlag(values, "metadata");
+    return sendMessage(ctx.client, ctx.resolver, {
+      streamRef: ref,
+      content: await resolveContent(rawContent, ctx.readStdin),
+      clientMessageId: stringFlag(values, "client-message-id"),
+      metadata: metadataPairs ? kvPairs(metadataPairs) : undefined,
+      conversationId,
+      startConversation,
+      sealed: ctx.sealed(storeChoice(values, ctx.config))
+    });
+  },
+  render: (payload) => {
+    const p = payload;
+    const lines = [`sent ${p.data?.id ?? "?"}${p.sealed ? " (sealed)" : ""}`];
+    if (p.conversationId)
+      lines.push(`conversation: ${p.conversationId}`);
+    if (p.clientMessageId)
+      lines.push(`clientMessageId: ${p.clientMessageId}`);
+    return lines.join(`
+`);
+  }
+};
+var editVerb = {
+  name: "edit",
+  summary: "Replace a message's content (only messages this key sent)",
+  usage: "threa messages edit <message-id> <content>",
+  help: `threa messages edit <message-id> <content> [flags]
+
+` + "Replace a message's content with new markdown. Only works on messages this API key sent — the API rejects " + `edits to any other author's message.
+
+` + `Flags:
+` + `  --json    force JSON output
+` + "  --help    show this help",
+  options: {},
+  run: (ctx, positionals) => {
+    const messageId = positionals[0];
+    if (!messageId)
+      throw new UsageError("messages edit requires a <message-id>");
+    const content = positionals[1];
+    if (content === undefined || content.trim() === "")
+      throw new UsageError("messages edit requires <content>");
+    return updateMessage(ctx.client, messageId, content);
+  },
+  render: (payload) => `edited ${payload.data?.id ?? "?"}`
+};
+var deleteVerb = {
+  name: "delete",
+  summary: "Delete a message (only messages this key sent)",
+  usage: "threa messages delete <message-id>",
+  help: `threa messages delete <message-id> [flags]
+
+` + "Delete a message. Only works on messages this API key sent — the API rejects deletes of any other " + `author's message.
+
+` + `Flags:
+` + `  --json    force JSON output
+` + "  --help    show this help",
+  options: {},
+  run: (ctx, positionals) => {
+    const messageId = positionals[0];
+    if (!messageId)
+      throw new UsageError("messages delete requires a <message-id>");
+    return deleteMessage(ctx.client, messageId);
+  },
+  render: (payload) => `deleted ${payload.message_id ?? "?"}`
+};
+var findByMetadataVerb = {
+  name: "find-by-metadata",
+  summary: "Find messages whose metadata contains every given key=value pair",
+  usage: "threa messages find-by-metadata k=v [k=v ...] [--stream ref] [--limit n]",
+  help: `threa messages find-by-metadata k=v [k=v ...] [flags]
+
+` + "Find non-deleted messages whose metadata contains every given key=value pair (exact AND-containment, not " + `text search). Use it to dedup by an external reference you stamped at send time, e.g. github.pr=org/repo#42.
+
+` + `Flags:
+` + `  --stream ref   narrow to a stream (stream_ id or #slug)
+` + `  --limit n      max results, <= 100 (default 20)
+` + `  --json         force JSON output
+` + "  --help         show this help",
+  options: {
+    stream: { type: "string" },
+    limit: { type: "string" }
+  },
+  run: (ctx, positionals, values) => {
+    if (positionals.length === 0) {
+      throw new UsageError("messages find-by-metadata requires at least one k=v pair");
+    }
+    return findMessagesByMetadata(ctx.client, ctx.resolver, {
+      metadata: kvPairs(positionals),
+      streamRef: stringFlag(values, "stream"),
+      limit: intFlag(values, "limit")
+    });
+  },
+  render: (payload) => {
+    const p = payload;
+    const rows = p.data ?? [];
+    return rows.map((m) => `${m.id ?? "?"}  ${m.streamId ?? "?"}  ${m.author?.name ?? ""}`.trimEnd()).join(`
+`) || "(no matches)";
+  }
+};
+var messagesNoun = {
+  name: "messages",
+  summary: "Send, edit, delete, and look up messages",
+  verbs: [sendVerb, editVerb, deleteVerb, findByMetadataVerb]
+};
+
+// src/commands/memos.ts
+var listVerb5 = {
+  name: "list",
+  summary: "List the most recent memos, optionally scoped to streams",
+  usage: "threa memos list [--stream ref]... [--limit n]",
+  help: `threa memos list [flags]
+
+` + "Browse preserved workspace memos, newest first (a query-less memo search). Filter further with " + "`threa search --what memos`.\n\n" + `Flags:
+` + `  --stream ref   limit to a source stream (stream_ id or #slug); repeatable
+` + `  --limit n      max results, <= 100 (default 20)
+` + `  --json         force JSON output
+` + "  --help         show this help",
+  options: {
+    stream: { type: "string", multiple: true },
+    limit: { type: "string" }
+  },
+  run: (ctx, _positionals, values) => search(ctx.client, ctx.resolver, {
+    what: "memos",
+    stream_ids: arrayFlag(values, "stream"),
+    limit: intFlag(values, "limit")
+  }),
+  render: (payload) => {
+    const rows = payload.data ?? [];
+    return rows.map(renderSearchResult).join(`
+`) || "(no memos)";
+  }
+};
+var getVerb3 = {
+  name: "get",
+  summary: "Get a memo by id, with its source-message provenance",
+  usage: "threa memos get <id>",
+  help: `threa memos get <id>
+
+` + "Retrieve one memo by id, with its source stream and the source messages it was extracted from " + "(provenance). Find memos in the first place with `threa memos list` or `threa search --what memos`.\n\n" + `Flags:
+` + `  --json    force JSON output
+` + "  --help    show this help",
+  options: {},
+  run: (ctx, positionals) => {
+    const id = positionals[0];
+    if (!id)
+      throw new UsageError("memos get requires a <id> (a memo_ id)");
+    return getMemo(ctx.client, id);
+  }
+};
+var memosNoun = {
+  name: "memos",
+  summary: "List memos and get one by id",
+  verbs: [listVerb5, getVerb3]
+};
+
+// src/commands/streams.ts
+function streamLabel2(s) {
+  return s.displayName ?? s.name ?? (s.slug ? `#${s.slug}` : s.id ?? "?");
+}
+var listVerb6 = {
+  name: "list",
+  summary: "List streams this key can access",
+  usage: "threa streams list [--type t]... [--query q] [--after cursor] [--limit n] [--archived]",
+  help: `threa streams list [flags]
+
+` + `List streams this key can access. Page by passing the previous response's cursor back as --after.
+
+` + `Flags:
+` + "  --type t     filter by stream type (" + STREAM_TYPES.join("|") + `); repeatable
+` + `  --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
+` + `  --json       force JSON output
+` + "  --help       show this help",
+  options: {
+    type: { type: "string", multiple: true },
+    query: { type: "string" },
+    after: { type: "string" },
+    limit: { type: "string" },
+    archived: { type: "boolean" }
+  },
+  run: (ctx, _positionals, values) => listStreams(ctx.client, {
+    type: enumArrayFlag(values, "type", STREAM_TYPES),
+    query: stringFlag(values, "query"),
+    after: stringFlag(values, "after"),
+    limit: intFlag(values, "limit"),
+    includeArchived: boolFlag(values, "archived")
+  }),
+  render: (payload) => renderList(payload, (s) => `${s.id ?? "?"}  ${s.type ?? "?"}  ${streamLabel2(s)}`, {
+    empty: "(no streams)",
+    cursorFlag: "after"
+  })
+};
+var readVerb2 = {
+  name: "read",
+  summary: "Read a stream with a page of its messages (accepts a stream_ id or #slug)",
+  usage: "threa streams read <ref> [--members] [--before seq] [--after seq] [--limit n]",
+  help: `threa streams read <ref> [flags]
+
+` + `Fetch a stream and a page of its messages. <ref> is a stream_ id or a #channel-slug.
+` + "Message paging is by numeric sequence, not a cursor: --before returns older messages, --after newer; " + `pass at most one and walk pages by the boundary message's sequence.
+
+` + 'An end-to-end-encrypted stream is read with the key this machine holds, so run "threa e2e unlock" ' + "first — without it the bodies cannot be opened here, and the command says so rather than printing the " + "placeholder the server stores. A message sealed to a key generation you were never wrapped to keeps a " + `null content and reports why, alone among the page.
+
+` + `Flags:
+` + `  --members    also fetch the stream's members
+` + `  --before seq messages before this sequence (older)
+` + `  --after seq  messages after this sequence (newer)
+` + `  --limit n    max messages, <= 100 (default 50)
+` + KEY_STORE_FLAGS + `  --json       force JSON output
+` + "  --help       show this help",
+  options: {
+    members: { type: "boolean" },
+    before: { type: "string" },
+    after: { type: "string" },
+    limit: { type: "string" },
+    ...KEY_STORE_OPTIONS
+  },
+  run: (ctx, positionals, values) => {
+    const ref = positionals[0];
+    if (!ref)
+      throw new UsageError("streams read requires a <ref> (a stream_ id or #channel-slug)");
+    return readStream(ctx.client, ctx.resolver, {
+      streamId: ref,
+      includeMembers: boolFlag(values, "members"),
+      before: stringFlag(values, "before"),
+      after: stringFlag(values, "after"),
+      limit: intFlag(values, "limit"),
+      sealed: ctx.sealed(storeChoice(values, ctx.config))
+    });
+  },
+  render: (payload) => {
+    const p = payload;
+    const lines = [];
+    if (p.stream)
+      lines.push(`stream: ${p.stream.id ?? "?"}  ${streamLabel2(p.stream)}`);
+    const msgs = p.messages?.data ?? [];
+    lines.push(`messages: ${msgs.length}${p.messages?.hasMore ? " (more)" : ""}`);
+    for (const m of msgs) {
+      const body = m.unreadableReason ? `<unreadable: ${m.unreadableReason}>` : (m.contentMarkdown ?? m.content ?? "").replace(/\s+/g, " ").trim();
+      lines.push(`  [${String(m.sequence ?? "?")}] ${m.author?.name ?? "?"}: ${body.slice(0, 120)}`);
+    }
+    if (p.members) {
+      lines.push(`members: ${(p.members.data ?? []).length}`);
+      for (const mem of p.members.data ?? [])
+        lines.push(`  ${mem.id ?? "?"} ${mem.name ?? ""}`.trimEnd());
+    }
+    return lines.join(`
+`);
+  }
+};
+function archiveVerb(archived) {
+  const name = archived ? "archive" : "unarchive";
+  const effect = archived ? "Archive a stream: it goes read-only and every thread beneath it is sealed with it." : "Reopen an archived stream. An archived ancestor keeps the subtree sealed until it is reopened too.";
+  return {
+    name,
+    summary: `${archived ? "Archive" : "Unarchive"} a stream (accepts a stream_ id or #slug)`,
+    usage: `threa streams ${name} <ref>`,
+    help: `threa streams ${name} <ref>
+
+` + `${effect}
+` + "<ref> is a stream_ id or a #channel-slug. Open to the stream's creator and, for a user key, the creator " + "of its root; a workspace key acts for its bot and reaches only the streams that bot opened. Repeating " + `the call is a no-op. An archived channel is not resolvable by #slug — pass its stream_ id.
+
+` + `Flags:
+` + `  --json       force JSON output
+` + "  --help       show this help",
+    options: {},
+    run: (ctx, positionals) => {
+      const ref = positionals[0];
+      if (!ref)
+        throw new UsageError(`streams ${name} requires a <ref> (a stream_ id or #channel-slug)`);
+      return setStreamArchived(ctx.client, ctx.resolver, { streamRef: ref, archived });
+    },
+    render: (payload) => {
+      const stream = payload.data;
+      return `${stream.id ?? "?"}  ${streamLabel2(stream)}  ${stream.archivedAt ? `archived ${stream.archivedAt}` : "active"}`;
+    }
+  };
+}
+var streamsNoun = {
+  name: "streams",
+  summary: "List streams, read one with its messages, archive and unarchive",
+  verbs: [listVerb6, readVerb2, archiveVerb(true), archiveVerb(false)]
+};
+
+// src/commands/users.ts
+var listVerb7 = {
+  name: "list",
+  summary: "List workspace users",
+  usage: "threa users list [--query q] [--after cursor] [--limit n]",
+  help: `threa users list [flags]
+
+` + `List users in this workspace. --query matches on name or email (not slug).
+
+` + `Flags:
+` + `  --query q    text match on name or email
+` + `  --after c    pagination cursor from a previous response
+` + `  --limit n    max results, <= 200 (default 50)
+` + `  --json       force JSON output
+` + "  --help       show this help",
+  options: {
+    query: { type: "string" },
+    after: { type: "string" },
+    limit: { type: "string" }
+  },
+  run: (ctx, _positionals, values) => listUsers(ctx.client, {
+    query: stringFlag(values, "query"),
+    after: stringFlag(values, "after"),
+    limit: intFlag(values, "limit")
+  }),
+  render: (payload) => renderList(payload, (u) => `${u.id ?? "?"}  ${u.name ?? "?"}  ${u.slug ? `@${u.slug}` : ""}  ${u.email ?? ""}`.trimEnd(), { empty: "(no users)", cursorFlag: "after" })
+};
+var usersNoun = {
+  name: "users",
+  summary: "List workspace users",
+  verbs: [listVerb7]
+};
+
+// src/cli.ts
+var FLAT_COMMANDS = [whoamiCommand, searchCommand, skillCommand, mcpCommand];
+var NOUNS = [
+  messagesNoun,
+  streamsNoun,
+  conversationsNoun,
+  usersNoun,
+  memosNoun,
+  attachmentsNoun,
+  labelsNoun,
+  delegationsNoun,
+  e2eNoun
+];
+var FLAT_REGISTRY = new Map(FLAT_COMMANDS.map((c) => [c.name, c]));
+var NOUN_REGISTRY = new Map(NOUNS.map((n) => [n.name, n]));
+var SERVE_STUB = {};
+var TOP_ENTRIES = [
+  { name: whoamiCommand.name, summary: whoamiCommand.summary },
+  ...NOUNS.map((n) => ({ name: n.name, summary: n.summary, verbs: n.verbs.map((v) => v.name).join(", ") })),
+  { name: searchCommand.name, summary: searchCommand.summary },
+  { name: skillCommand.name, summary: skillCommand.summary },
+  { name: mcpCommand.name, summary: mcpCommand.summary }
+];
+function topHelp() {
+  const width = Math.max(...TOP_ENTRIES.map((e) => e.name.length));
+  const lines = TOP_ENTRIES.map((e) => {
+    const verbs = e.verbs ? ` (${e.verbs})` : "";
+    return `  ${e.name.padEnd(width)}  ${e.summary}${verbs}`;
+  });
+  return [
+    "threa — command-line access to a Threa workspace (one API key, bound via config).",
+    "",
+    "Usage: threa <command> [subcommand] [args] [flags]",
+    "",
+    "Commands:",
+    ...lines,
+    "",
+    "Global flags: -o json|text / --json (output mode, any position), --help (per-command help).",
+    'Config: THREA_API_KEY and THREA_WORKSPACE_ID (env, or ~/.threa/config.json, or the file in THREA_CONFIG, which wins over env); optional THREA_BASE_URL, THREA_PRINCIPAL / "principal": "bot"|"user" (asserted against the key at startup), and "output": "json"|"text".',
+    "Run `threa <command> --help` for a command's subcommands or flags."
+  ].join(`
+`);
+}
+function nounHelp(noun) {
+  const width = Math.max(...noun.verbs.map((v) => v.name.length));
+  const lines = noun.verbs.map((v) => `  ${v.name.padEnd(width)}  ${v.summary}`);
+  return [
+    `threa ${noun.name} <subcommand> [args] [flags]`,
+    "",
+    noun.summary,
+    "",
+    "Subcommands:",
+    ...lines,
+    "",
+    `Run \`threa ${noun.name} <subcommand> --help\` for a subcommand's flags.`
+  ].join(`
+`);
+}
+function leafFlags(leaf) {
+  return {
+    serve: leaf.serve === true,
+    noConfig: leaf.noConfig === true
+  };
+}
+async function executeLeaf(leaf, args, deps, flagMode) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args,
+      options: withGlobalOptions(leaf.options),
+      allowPositionals: true,
+      strict: true
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { exitCode: 2, stdout: "", stderr: stderrJson({ code: "USAGE", message, hint: leaf.usage }) };
+  }
+  const values = parsed.values;
+  const positionals = parsed.positionals;
+  if (values.help === true) {
+    return { exitCode: 0, stdout: `${leaf.help}
+`, stderr: "" };
+  }
+  const { serve, noConfig } = leafFlags(leaf);
+  try {
+    if (serve) {
+      await leaf.run(SERVE_STUB, positionals, values);
+      return { exitCode: 0, stdout: "", stderr: "", serve: true };
+    }
+    if (noConfig) {
+      const payload2 = await leaf.run(SERVE_STUB, positionals, values);
+      return {
+        exitCode: 0,
+        stdout: `${formatSuccess(leaf, payload2, { mode: flagMode ?? "text" })}
+`,
+        stderr: ""
+      };
+    }
+    const config = deps.config ?? loadConfig();
+    const client = new ThreaApiClient({
+      baseUrl: config.baseUrl,
+      workspaceId: config.workspaceId,
+      apiKey: config.apiKey
+    });
+    await assertPrincipal(client, config);
+    const resolver = new RefResolver({ client });
+    const readStdin = deps.readStdin ?? (() => text(process.stdin));
+    const tokenStore = deps.tokenStore ?? new TokenStore;
+    const sealed = (choice) => sealedStreams({ client, config, choice });
+    const payload = await leaf.run({ client, resolver, config, tokenStore, readStdin, sealed }, positionals, values);
+    return {
+      exitCode: 0,
+      stdout: `${formatSuccess(leaf, payload, { mode: flagMode ?? config.output })}
+`,
+      stderr: ""
+    };
+  } catch (error) {
+    if (error instanceof UsageError) {
+      return {
+        exitCode: 2,
+        stdout: "",
+        stderr: stderrJson({ code: "USAGE", message: error.message, hint: leaf.usage })
+      };
+    }
+    return { exitCode: 1, stdout: "", stderr: stderrJson(errorObject(error)) };
+  }
+}
+async function runNoun(noun, args, deps, flagMode) {
+  const verbName = args[0];
+  if (verbName === undefined) {
+    return {
+      exitCode: 2,
+      stdout: "",
+      stderr: stderrJson({
+        code: "USAGE",
+        message: `"${noun.name}" needs a subcommand: ${noun.verbs.map((v) => v.name).join(", ")}`,
+        hint: nounHelp(noun)
+      })
+    };
+  }
+  if (verbName === "--help" || verbName === "-h") {
+    return { exitCode: 0, stdout: `${nounHelp(noun)}
+`, stderr: "" };
+  }
+  const verb = noun.verbs.find((v) => v.name === verbName);
+  if (!verb) {
+    return {
+      exitCode: 2,
+      stdout: "",
+      stderr: stderrJson({
+        code: "USAGE",
+        message: `unknown ${noun.name} subcommand "${verbName}" — expected one of: ${noun.verbs.map((v) => v.name).join(", ")}`,
+        hint: nounHelp(noun)
+      })
+    };
+  }
+  return executeLeaf(verb, args.slice(1), deps, flagMode);
+}
+async function run(rawArgv, deps = {}) {
+  let argv;
+  let flagMode;
+  try {
+    ({ argv, mode: flagMode } = extractOutputMode(rawArgv));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { exitCode: 2, stdout: "", stderr: stderrJson({ code: "USAGE", message }) };
+  }
+  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h" || argv[0] === "help") {
+    return { exitCode: 0, stdout: `${topHelp()}
+`, stderr: "" };
+  }
+  const name = argv[0];
+  const flat = FLAT_REGISTRY.get(name);
+  if (flat)
+    return executeLeaf(flat, argv.slice(1), deps, flagMode);
+  const noun = NOUN_REGISTRY.get(name);
+  if (noun)
+    return runNoun(noun, argv.slice(1), deps, flagMode);
+  return {
+    exitCode: 2,
+    stdout: "",
+    stderr: stderrJson({ code: "UNKNOWN_COMMAND", message: `unknown command "${name}"`, hint: topHelp() })
+  };
+}
+async function main() {
+  const result = await run(process.argv.slice(2));
+  if (result.stdout)
+    process.stdout.write(result.stdout);
+  if (result.stderr)
+    process.stderr.write(result.stderr);
+  if (result.serve) {
+    try {
+      await serveMcp(loadConfig());
+    } catch (error) {
+      process.stderr.write(stderrJson(errorObject(error)));
+      process.exit(1);
+    }
+    return;
+  }
+  process.exit(result.exitCode);
+}
+if (__require.main == __require.module) {
+  main().catch((error) => {
+    process.stderr.write(stderrJson(errorObject(error)));
+    process.exit(1);
+  });
+}
+export {
+  run
+};