tokenmaxxing 0.17.0 → 0.19.0

package/src/lib/slackstate.ts

@@ -0,0 +1,131 @@
+// `xx serve` state. slack.json holds the Slack tokens plus the channel->repo
+// links; it is credential material (xoxb-/xapp-), so it is written 0600 and its
+// tokens must never be printed. Per-thread records under slack-threads/ pin the
+// claude session id + cwd a Slack thread resumes into (resume is cwd-keyed, so
+// the cwd must stay byte-stable for the thread's whole life). A present but
+// unparseable slack.json THROWS (no silent empty config); absent = null.
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { paths } from "./paths.ts";
+import { writeFileAtomic } from "./atomic.ts";
+
+/** Claude Agent SDK permission modes an unattended bridge may run under.
+ *  acceptEdits (default) auto-approves file edits but not arbitrary Bash;
+ *  bypassPermissions is full autonomy - a per-link, user-chosen risk posture. */
+export const ServePermissionModeSchema = z.enum(["default", "acceptEdits", "bypassPermissions", "dontAsk", "plan"]);
+
+export const SlackLinkSchema = z.object({
+  /** Slack channel id (C.../G...). Names are not stored - ids are stable. */
+  channel: z.string(),
+  /** absolute path of the git repo this channel drives. */
+  repo: z.string(),
+  /** run each thread in its own git worktree (user default 2026-07-18: true). */
+  worktree: z.boolean().default(true),
+  permissionMode: ServePermissionModeSchema.default("acceptEdits"),
+  /** optional model override for this repo's sessions. */
+  model: z.string().optional(),
+});
+export type SlackLink = z.infer<typeof SlackLinkSchema>;
+
+export const SlackConfigSchema = z.object({
+  botToken: z.string().startsWith("xoxb-"),
+  appToken: z.string().startsWith("xapp-"),
+  links: z.array(SlackLinkSchema).default([]),
+});
+export type SlackConfig = z.infer<typeof SlackConfigSchema>;
+
+export function loadSlackConfig(): SlackConfig | null {
+  if (!existsSync(paths.slackJson)) return null;
+  return SlackConfigSchema.parse(JSON.parse(readFileSync(paths.slackJson, "utf8")));
+}
+
+export function saveSlackConfig(cfg: SlackConfig): void {
+  writeFileAtomic(paths.slackJson, JSON.stringify(SlackConfigSchema.parse(cfg), null, 2) + "\n", 0o600);
+}
+
+/** A Slack channel id: C (public) or G (private/legacy) followed by uppercase
+ *  alphanumerics. Structural check, no regex. */
+export function isChannelId(s: string): boolean {
+  if (s.length < 2 || (s[0] !== "C" && s[0] !== "G")) return false;
+  const rest = s.slice(1);
+  return [...rest].every((ch) => (ch >= "0" && ch <= "9") || (ch >= "A" && ch <= "Z"));
+}
+
+// ---- per-thread session records -------------------------------------------
+
+export const SlackThreadSchema = z.object({
+  /** chat-sdk thread id, e.g. "slack:C0123:1721300000.123456". */
+  threadId: z.string(),
+  repo: z.string(),
+  /** the dir every turn of this thread runs in (repo or its worktree). */
+  cwd: z.string(),
+  /** claude session id; null until the first turn's init message arrives. */
+  sessionId: z.string().nullable(),
+  createdAt: z.string(),
+});
+export type SlackThread = z.infer<typeof SlackThreadSchema>;
+
+/** Filesystem-safe key for a thread id: alnum kept, everything else "-". */
+export function threadKey(threadId: string): string {
+  return [...threadId]
+    .map((ch) => ((ch >= "a" && ch <= "z") || (ch >= "A" && ch <= "Z") || (ch >= "0" && ch <= "9") ? ch : "-"))
+    .join("");
+}
+
+function threadFile(threadId: string): string {
+  return join(paths.slackThreadsDir, `${threadKey(threadId)}.json`);
+}
+
+export function loadSlackThread(threadId: string): SlackThread | null {
+  const f = threadFile(threadId);
+  if (!existsSync(f)) return null;
+  return SlackThreadSchema.parse(JSON.parse(readFileSync(f, "utf8")));
+}
+
+export function saveSlackThread(t: SlackThread): void {
+  writeFileAtomic(threadFile(t.threadId), JSON.stringify(SlackThreadSchema.parse(t), null, 2) + "\n");
+}
+
+export function listSlackThreads(): SlackThread[] {
+  if (!existsSync(paths.slackThreadsDir)) return [];
+  const out: SlackThread[] = [];
+  for (const f of readdirSync(paths.slackThreadsDir)) {
+    if (!f.endsWith(".json")) continue;
+    out.push(SlackThreadSchema.parse(JSON.parse(readFileSync(join(paths.slackThreadsDir, f), "utf8"))));
+  }
+  return out;
+}
+
+// ---- pure link edits (unit-tested) ----------------------------------------
+
+export function upsertLink(cfg: SlackConfig, link: SlackLink): SlackConfig {
+  const links = cfg.links.filter((l) => l.channel !== link.channel);
+  links.push(link);
+  return { ...cfg, links };
+}
+
+export function removeLink(cfg: SlackConfig, channel: string): SlackConfig | null {
+  if (!cfg.links.some((l) => l.channel === channel)) return null;
+  return { ...cfg, links: cfg.links.filter((l) => l.channel !== channel) };
+}
+
+export function linkForChannel(cfg: SlackConfig, channel: string): SlackLink | null {
+  return cfg.links.find((l) => l.channel === channel) ?? null;
+}
+
+/** Chat SDK channel ids are adapter-prefixed ("slack:C0123"); links store the
+ *  bare Slack id, so lookups must strip the prefix. */
+export function bareChannelId(id: string): string {
+  return id.startsWith("slack:") ? id.slice("slack:".length) : id;
+}
+
+/** Strip a leading Slack mention token ("<@U0123> rest") from message text. */
+export function stripLeadingMention(text: string): string {
+  const trimmed = text.trimStart();
+  if (!trimmed.startsWith("<@")) return text.trim();
+  const close = trimmed.indexOf(">");
+  if (close < 0) return text.trim();
+  return trimmed.slice(close + 1).trim();
+}

package/src/lib/slackstream.ts

@@ -0,0 +1,189 @@
+// Maps Claude Agent SDK messages onto Chat SDK stream chunks so a relayed
+// Slack turn shows the agent's process natively: task cards for thinking and
+// tool calls (pending -> in_progress -> complete/error), streamed text via
+// markdown_text, and a closing turn card with model/cost/duration. Structured
+// chunks render only when the Slack app has the agent feature + assistant:write
+// (the adapter drops them gracefully otherwise); plain text streams either way.
+
+import { z } from "zod";
+import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { StreamChunk } from "chat";
+
+const DETAILS_MAX = 400;
+const OUTPUT_MAX = 600;
+
+/** Tool-input fields worth showing on a task card, most human-readable first. */
+const SUMMARY_FIELDS = ["command", "description", "file_path", "pattern", "prompt", "query", "url"] as const;
+
+const OpenBlockSchema = z.object({
+  kind: z.enum(["thinking", "tool"]),
+  id: z.string(),
+  title: z.string(),
+  /** accumulated thinking text or partial tool-input JSON. */
+  acc: z.string(),
+});
+type OpenBlock = z.infer<typeof OpenBlockSchema>;
+
+export const StreamMapStateSchema = z.object({
+  /** open content blocks by stream index. */
+  open: z.record(z.string(), OpenBlockSchema),
+  /** tool_use id -> tool name, for labeling the eventual tool_result. */
+  toolTitles: z.record(z.string(), z.string()),
+  thinkingCount: z.number(),
+  /** reply text streamed since the last segment break. */
+  textSinceBreak: z.boolean(),
+});
+export type StreamMapState = z.infer<typeof StreamMapStateSchema>;
+
+export function newStreamMapState(): StreamMapState {
+  return { open: {}, toolTitles: {}, thinkingCount: 0, textSinceBreak: false };
+}
+
+/** Emitted when a tool starts after streamed reply text: the bridge closes the
+ *  current Slack message there and posts the rest as a new one, mirroring how
+ *  an agent turn reads as separate messages around its tool runs. */
+export const SegmentBreakSchema = z.object({ type: z.literal("segment_break") });
+export type SegmentBreak = z.infer<typeof SegmentBreakSchema>;
+
+export const StreamPartSchema = z.union([z.string(), z.custom<StreamChunk>(), SegmentBreakSchema]);
+export type StreamPart = z.infer<typeof StreamPartSchema>;
+
+function truncate(input: { text: string; max: number }): string {
+  return input.text.length > input.max ? `${input.text.slice(0, input.max)}...` : input.text;
+}
+
+/** One human line out of a tool-input JSON blob; null when nothing fits. */
+export function toolInputSummary(rawJson: string): string | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawJson);
+  } catch {
+    return null; // partial or empty input JSON - show the bare tool name
+  }
+  const obj = z.record(z.string(), z.unknown()).safeParse(parsed);
+  if (!obj.success) return null;
+  for (const field of SUMMARY_FIELDS) {
+    const value = z.string().min(1).safeParse(obj.data[field]);
+    if (value.success) return truncate({ text: value.data, max: DETAILS_MAX });
+  }
+  const compact = JSON.stringify(parsed);
+  return compact === "{}" ? null : truncate({ text: compact, max: DETAILS_MAX });
+}
+
+const ToolResultBlockSchema = z.object({
+  type: z.literal("tool_result"),
+  tool_use_id: z.string(),
+  content: z.union([z.string(), z.array(z.unknown())]).optional(),
+  is_error: z.boolean().optional(),
+});
+
+const TextPartSchema = z.object({ type: z.literal("text"), text: z.string() });
+
+function resultText(content: z.infer<typeof ToolResultBlockSchema>["content"]): string | undefined {
+  if (content === undefined) return undefined;
+  const joined = Array.isArray(content)
+    ? content
+        .flatMap((part) => {
+          const p = TextPartSchema.safeParse(part);
+          return p.success ? [p.data.text] : [];
+        })
+        .join("\n")
+    : content;
+  const trimmed = joined.trim();
+  return trimmed === "" ? undefined : truncate({ text: trimmed, max: OUTPUT_MAX });
+}
+
+/**
+ * Consume one SDK message, mutating state, and return the stream chunks it
+ * produces (strings are streamed reply text; objects are native task cards).
+ * Subagent events (parent_tool_use_id set) contribute their TOOL cards to the
+ * timeline (user ask 2026-07-18: subagent activity shows as accordions like
+ * tool calls) but never reply text, thinking cards, or segment breaks: a
+ * subagent runs inside a top-level Task tool, so its churn decorates the
+ * current message rather than reshaping it. Open blocks are keyed per stream
+ * (parent + index) because concurrent subagent streams reuse index space.
+ */
+export function agentEventChunks(input: { state: StreamMapState; message: SDKMessage }): StreamPart[] {
+  const { state, message } = input;
+  if (message.type === "stream_event") {
+    const isMain = message.parent_tool_use_id === null;
+    const event = message.event;
+    if (event.type === "content_block_start") {
+      const key = `${message.parent_tool_use_id ?? "main"}:${event.index}`;
+      if (event.content_block.type === "thinking" && isMain) {
+        state.thinkingCount += 1;
+        const id = `thinking-${state.thinkingCount}`;
+        state.open[key] = { kind: "thinking", id, title: "Thinking", acc: "" };
+        return [{ type: "task_update", id, title: "Thinking", status: "in_progress" }];
+      }
+      if (event.content_block.type === "tool_use") {
+        const { id, name } = event.content_block;
+        state.open[key] = { kind: "tool", id, title: name, acc: "" };
+        state.toolTitles[id] = name;
+        const card: StreamPart = { type: "task_update", id, title: name, status: "in_progress" };
+        if (isMain && state.textSinceBreak) {
+          state.textSinceBreak = false;
+          return [{ type: "segment_break" }, card];
+        }
+        return [card];
+      }
+      return [];
+    }
+    if (event.type === "content_block_delta") {
+      const open = state.open[`${message.parent_tool_use_id ?? "main"}:${event.index}`];
+      if (event.delta.type === "text_delta") {
+        if (!isMain) return [];
+        state.textSinceBreak = true;
+        return [event.delta.text];
+      }
+      if (event.delta.type === "thinking_delta" && open) open.acc += event.delta.thinking;
+      if (event.delta.type === "input_json_delta" && open) open.acc += event.delta.partial_json;
+      return [];
+    }
+    if (event.type === "content_block_stop") {
+      const key = `${message.parent_tool_use_id ?? "main"}:${event.index}`;
+      const open = state.open[key];
+      if (!open) return [];
+      delete state.open[key];
+      if (open.kind === "thinking") {
+        return [{ type: "task_update", id: open.id, title: open.title, status: "complete", details: truncate({ text: open.acc.trim(), max: DETAILS_MAX }) }];
+      }
+      const details = toolInputSummary(open.acc);
+      return [{ type: "task_update", id: open.id, title: open.title, status: "in_progress", ...(details ? { details } : {}) }];
+    }
+    return [];
+  }
+  if (message.type === "user") {
+    const content = message.message.content;
+    if (!Array.isArray(content)) return [];
+    const chunks: StreamChunk[] = [];
+    for (const block of content) {
+      const parsed = ToolResultBlockSchema.safeParse(block);
+      if (!parsed.success) continue;
+      const title = state.toolTitles[parsed.data.tool_use_id];
+      if (title === undefined) continue;
+      const output = resultText(parsed.data.content);
+      chunks.push({
+        type: "task_update",
+        id: parsed.data.tool_use_id,
+        title,
+        status: parsed.data.is_error === true ? "error" : "complete",
+        ...(output ? { output } : {}),
+      });
+    }
+    return chunks;
+  }
+  if (message.type === "result") {
+    const models = Object.keys(message.modelUsage).join(" ");
+    const cost = `$${message.total_cost_usd.toFixed(4)}`;
+    const secs = `${Math.round(message.duration_ms / 1000)}s`;
+    return [{
+      type: "task_update",
+      id: "turn",
+      title: "Turn",
+      status: message.subtype === "success" ? "complete" : "error",
+      details: [models, cost, secs].filter((p) => p !== "").join("  "),
+    }];
+  }
+  return [];
+}

package/src/lib/types.ts

@@ -196,6 +196,28 @@ export const StatusLineStdinSchema = RateLimitsStdinSchema.extend({
   effort: z.looseObject({ level: z.string().optional() }).nullable().optional().catch(undefined),
 });
 
+/** subagentStatusLine stdin: base session fields plus one entry per active
+ *  subagent task (verified against the 2.1.214 bundle + docs 2026-07-18;
+ *  tasks[].model/contextWindowSize need claude >= 2.1.205, effort >= 2.1.214).
+ *  Same loose + catch degradation contract as StatusLineStdinSchema. */
+export const SubagentStatusLineStdinSchema = z.looseObject({
+  tasks: z
+    .array(
+      z.looseObject({
+        id: z.string().optional(),
+        name: z.string().nullable().optional().catch(undefined),
+        description: z.string().nullable().optional().catch(undefined),
+        label: z.string().nullable().optional().catch(undefined),
+        model: z.string().nullable().optional().catch(undefined),
+        effort: z.string().nullable().optional().catch(undefined),
+        contextWindowSize: z.number().nullable().optional().catch(undefined),
+        tokenCount: z.number().nullable().optional().catch(undefined),
+      }),
+    )
+    .optional()
+    .catch(undefined),
+});
+
 /** Success body of the OAuth refresh grant. */
 export const RefreshResponseSchema = z.looseObject({
   access_token: z.string(),

package/src/lib/usage.ts

@@ -76,7 +76,7 @@ export function matchedFamily(model: ModelInfo | null, families: string[]): stri
  *  unknown. The unknown case matters on headless boxes: a swap clears the
  *  snapshots and only an actively-rendering statusLine restores the model, so
  *  the periodic check ran model-blind for hours while the active account sat at
- *  its Fable cap (the 2026-07-12 stella incident). */
+ *  its Fable cap (the 2026-07-12 ARM-box incident). */
 export function gatedFamilies(model: ModelInfo | null, families: string[]): string[] {
   if (!model) return families;
   const family = matchedFamily(model, families);

package/src/main.ts

@@ -6,6 +6,7 @@
 import { basename } from "node:path";
 import { runSupervisor } from "./entries/supervisor.ts";
 import { runStatusline } from "./entries/statusline.ts";
+import { runSubagentStatusline } from "./entries/subagentstatusline.ts";
 import { runStopHook } from "./entries/stophook.ts";
 import { runSessionStart } from "./entries/sessionstart.ts";
 import { cmdInit } from "./cli/init.ts";
@@ -25,6 +26,7 @@ import { cmdRename } from "./cli/rename.ts";
 import { cmdSwitch } from "./cli/switch.ts";
 import { cmdCheck } from "./cli/check.ts";
 import { cmdConfig } from "./cli/config.ts";
+import { cmdServe } from "./cli/serve.ts";
 import { uninstallSupervisor } from "./lib/install.ts";
 import { c } from "./cli/render.ts";
 
@@ -45,6 +47,7 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing status --force")}  ping every account (one tiny haiku request each) so all 5h session timers start now, then sample fresh; ${c.cyan("xx --force")} works too
   ${c.cyan("tokenmaxxing watch")} [seconds]  live status: re-render every N seconds (default 120, never pings)
   ${c.cyan("tokenmaxxing config")} [get|set|unset|tidy]  inspect and edit config.json (bare = effective config with sources)
+  ${c.cyan("tokenmaxxing serve")} [setup|link|unlink|links]  Slack bridge daemon: mention the bot in a linked channel to open a claude session per thread (worktree by default)
   ${c.cyan("tokenmaxxing doctor")}     verify the install is intact
   ${c.cyan("tokenmaxxing rename")} [--codex] <sel> <label>
   ${c.cyan("tokenmaxxing rm")} <sel>
@@ -72,6 +75,7 @@ async function main(): Promise<number> {
 
   switch (sub) {
     case "__statusline": return runStatusline();
+    case "__subagent-statusline": return runSubagentStatusline();
     case "__stop-hook": return runStopHook();
     case "__session-start": return runSessionStart();
     case "__codex-stop-hook": return runCodexStopHook();
@@ -80,6 +84,7 @@ async function main(): Promise<number> {
     case "switch": return args[1] === "--codex" ? cmdCodexSwitch(args[2]) : cmdSwitch(args[1]);
     case "check": return cmdCheck();
     case "config": return cmdConfig(args.slice(1));
+    case "serve": return cmdServe(args.slice(1));
     case "init": return args.includes("--codex") ? cmdCodexInit() : cmdInit();
     case "add": return args.includes("--codex") ? cmdCodexAdd() : cmdAdd();
     case "auth": return cmdAuth(args.slice(1));