carthagent 1.0.7 → 1.1.0-beta.1

package/plugins/carthagent/src/tui.tsx

@@ -0,0 +1,496 @@
+/** @jsxImportSource @opentui/solid */
+import { Plugin } from "@opencode/plugin/tui";
+import { Show } from "solid-js";
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { nativeProviderName } from "../../../lib/opencode/provider-policy.mjs";
+import { framePrompt } from "../../../lib/tui/framing.mjs";
+import { carthagentConfigPath, loadCarthagentConfig, resolveReviewMode, reviewKickoff, saveCarthagentConfig } from "../../../lib/review.mjs";
+import { COMMANDS, NATIVE_COMMAND_COLLISIONS } from "./ui/commands.js";
+import { Workspace, rpcEventOptions, sessionControls, workspaceClient, shipClient, archiveClient, cloudAccountText, cloudUsageText, archiveItemText } from "./ui/client.js";
+import { findNativeResumeSession } from "./ui/resume-session.mjs";
+import { cliConfigDirectory, cliConfigPath, readCliConfig, writeNativeTheme } from "./ui/host-state.js";
+import { WorkspacePage } from "./ui/workspace.js";
+import { VoyagesPage } from "./ui/voyages.js";
+import { DailyQuestsPage } from "./ui/daily-quests.js";
+import { VoyagesNavigation } from "./ui/voyages-navigation.js";
+import { nativeNavigation } from "./ui/native-navigation.js";
+import { provisionNativeThemes } from "./ui/theme-provision.mjs";
+import { setSessionAutoCompaction } from "./ui/session-preferences.mjs";
+import { runModelCommand } from "./ui/model-command.js";
+import { createNativeReviewConsumer, nativeReviewMode, sendNativeReviewKickoff, subscribeNativeReviewEvents } from "./ui/native-review.mjs";
+
+const THEMES = ["carthage", "tokyonight", "nebula", "ember", "forest", "mono", "obsidian", "midnight", "solarized-dark", "nord", "contrast-dark", "okabe-dark", "paper", "daylight", "solarized-light", "contrast-light", "okabe-light", "solarized", "okabe", "contrast", "system"];
+const OPENCODE_BUILTIN_THEMES = new Set(["opencode", "tokyonight"]);
+
+export default Plugin.define({
+  id: "carthagent.tui",
+  setup(context) {
+    const unregister = context.ui.router.register({ name: "carthagent", render: ({ data }) => <WorkspacePage view={String(data?.view ?? "workspace")} refreshKey={String(data?.refresh ?? "")} sessionID={typeof data?.sessionID === "string" ? data.sessionID : undefined} /> });
+    const cleanups = [unregister];
+    cleanups.push(context.ui.router.register({ name: "voyages", render: ({ data }) => <VoyagesPage sessionID={typeof data?.sessionID === "string" ? data.sessionID : undefined} section={data?.section === "profile" || data?.section === "equipment" ? data.section : undefined} /> }));
+    cleanups.push(context.ui.router.register({ name: "daily-quests", render: ({ data }) => <DailyQuestsPage sessionID={typeof data?.sessionID === "string" ? data.sessionID : undefined} questID={typeof data?.questID === "string" ? data.questID : undefined} /> }));
+    const navigation = nativeNavigation(context);
+    if (navigation) cleanups.push(navigation.register({ name: "voyages", title: "Voyages", render: (input) => <VoyagesNavigation {...input} /> }));
+    const lifecycle = new AbortController();
+    cleanups.push(() => lifecycle.abort());
+    const [reviewLoopState, updateReviewLoopState] = context.storage.store("carthagent.native-review-loops", { initial: { sessions: [] as string[] } });
+    const reviewLoops = new Set<string>(reviewLoopState.sessions);
+    const reviewConsumer = createNativeReviewConsumer({
+      mode: (sessionID: string) => nativeReviewMode(context.data.session.get(sessionID), loadCarthagentConfig()),
+      diff: async (sessionID: string, signal?: AbortSignal) => await context.client.session.diff({ sessionID }, { signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(15_000)]) : AbortSignal.timeout(15_000) }),
+      signal: lifecycle.signal,
+      isLoopActive: (sessionID: string) => reviewLoops.has(sessionID),
+      setLoopActive: (sessionID: string, active: boolean) => {
+        if (active) reviewLoops.add(sessionID);
+        else reviewLoops.delete(sessionID);
+        void updateReviewLoopState((state) => { state.sessions = [...reviewLoops]; });
+      },
+      // No formal delivery (unavailable) or a verified one; blocked/unfinished runs are not offered.
+      eligible: async (sessionID: string, signal?: AbortSignal) => {
+        const delivery = await workspaceClient(context, context.data.session.get(sessionID)?.location).delivery({ sessionID }, signal ? AbortSignal.any([signal, AbortSignal.timeout(15_000)]) : AbortSignal.timeout(15_000));
+        return delivery.status === "unavailable" || delivery.status === "verified";
+      },
+      offer: async ({ sessionID, writes, start }: { sessionID: string; writes: number; start: () => Promise<boolean> }) => {
+        const accepted = await context.ui.dialog.confirm({ title: `Review ${context.data.session.get(sessionID)?.title ?? sessionID}?`, message: `This run changed ${writes} file${writes === 1 ? "" : "s"}. Start the PR → fresh-context review → fixes workflow?`, label: { confirm: "Start review", cancel: "Not now" } });
+        if (accepted) await start();
+      },
+      kickoff: async (reviewSessionID: string, signal?: AbortSignal) => sendNativeReviewKickoff({ client: context.client, sessionID: reviewSessionID, signal }),
+    });
+    cleanups.push(() => reviewConsumer.dispose());
+    cleanups.push(...subscribeNativeReviewEvents(
+      context.data,
+      reviewConsumer,
+      (error: unknown) => context.ui.toast.show({ message: error instanceof Error ? error.message : String(error), variant: "error" }),
+      async (sessionID: string, messageID: string, signal?: AbortSignal) => await context.client.session.message.get({ sessionID, messageID }, { signal }),
+    ));
+    const workspaceEvents = context.client.rpc(Workspace);
+    cleanups.push(workspaceEvents.events.on("updated", (event) => {
+      // Promise RPC exposes the server event envelope (including location)
+      // separately from the declared event data ({ revision }).
+      const route = context.ui.router.current();
+      const sessionID = route.type === "session" ? route.sessionID : route.type === "plugin" && ["carthagent", "voyages", "daily-quests"].includes(route.name) && typeof route.data?.sessionID === "string" ? route.data.sessionID : undefined;
+      const expected = (sessionID ? context.data.session.get(sessionID)?.location : undefined) ?? context.location ?? context.data.location.default();
+      if (event.location?.directory === expected.directory) context.data.project.invalidate();
+    }, rpcEventOptions(context, lifecycle.signal)));
+    context.keymap.layer(() => ({
+      mode: "global",
+      priority: 20,
+      commands: [
+        ...COMMANDS.filter((item) => !NATIVE_COMMAND_COLLISIONS.includes(item.name as typeof NATIVE_COMMAND_COLLISIONS[number]))
+        .map((item) => ({
+          id: `carthagent.${item.id}`,
+          title: `/${item.name}${item.args ? ` ${item.args}` : ""}`,
+          description: item.description,
+          group: "Carthagent",
+          palette: true as const,
+          slash: { name: item.name, ...(item.aliases ? { aliases: item.aliases } : {}), ...(item.args || item.submitSlash ? { arguments: true as const } : {}) },
+          run: (input?: string) => {
+            const report = (error: unknown) => context.ui.toast.show({ message: error instanceof Error ? error.message : String(error), variant: "error" });
+            if (item.id === "restart" || item.id === "abort") {
+              void dispatch(item.id, input ?? "").catch(report);
+              return false;
+            }
+            return dispatch(item.id, input ?? "").then(() => undefined).catch(report);
+          },
+        })),
+      ],
+    }));
+
+    async function dispatch(id: string, input: string) {
+      const route = context.ui.router.current();
+      const sessionID = route.type === "session" ? route.sessionID : route.type === "plugin" && ["carthagent", "voyages", "daily-quests"].includes(route.name) && typeof route.data?.sessionID === "string" ? route.data.sessionID : undefined;
+      const activeSession = sessionID ? context.data.session.get(sessionID) : undefined;
+      const location = activeSession?.location ?? context.location ?? context.data.location.default();
+      const arg = input.trim();
+      const toast = (message: string, variant: "info" | "success" | "warning" | "error" = "info") => context.ui.toast.show({ message, variant });
+      const selectedModel = context.ui.model.current();
+      const sessionApi = sessionControls(context, location);
+      switch (id) {
+        case "voyages":
+          context.ui.router.navigate({ type: "plugin", name: "voyages", data: { ...(sessionID ? { sessionID } : {}) } });
+          return;
+        case "quests":
+          context.ui.router.navigate({ type: "plugin", name: "daily-quests", data: { ...(sessionID ? { sessionID } : {}) } });
+          return;
+        case "login":
+          context.keymap.dispatch("provider.connect");
+          return;
+        case "help": case "ctg-help":
+          await context.ui.dialog.alert({ title: "Carthagent commands", message: COMMANDS.map((command) => `/${command.name}${command.args ? ` ${command.args}` : ""}${command.aliases?.length ? ` (${command.aliases.map((alias) => `/${alias}`).join(", ")})` : ""} — ${command.description}`).join("\n") + "\n\nCtrl+R sessions · Ctrl+T settings · Ctrl+N new session are native Carthagent actions." });
+          return;
+        case "resume": {
+          const query = arg.toLowerCase();
+          const pageSize = 100;
+          const match = query ? await findNativeResumeSession({ query: arg, directory: location.directory, client: context.client }) : undefined;
+          if (match) { context.ui.router.navigate({ type: "session", sessionID: match.id }); return; }
+          if (query) {
+            const archived = await archiveClient(context, location).search({ query: arg, limit: 1 }) as { total: number };
+            if (archived.total > 0) { toast(`“${arg}” matched ${archived.total} legacy archive result(s); archives are read-only and cannot be resumed. Use /archive search ${arg}.`, "warning"); return; }
+            toast(`No native session matches “${arg}” in ${context.ui.format.path(location.directory)}.`, "warning");
+            return;
+          }
+          let cursor: string | undefined;
+          const sessions: Array<{ id: string; title?: string; parentID?: string; time: { updated: number } }> = [];
+          do {
+            const page = await context.client.session.list({ limit: pageSize, order: "desc", directory: location.directory, ...(cursor ? { cursor } : {}) });
+            sessions.push(...page.data.filter((session) => !session.parentID));
+            cursor = page.cursor.next ?? undefined;
+          } while (cursor);
+          const selected = await context.ui.dialog.select({ title: `Resume native session · ${sessions.length} loaded`, options: sessions.map((session) => ({ title: session.title ?? session.id, value: session.id, description: `${new Date(session.time.updated).toLocaleString()} · ${session.id}` })) });
+          if (selected) context.ui.router.navigate({ type: "session", sessionID: selected });
+          return;
+        }
+        case "ctg-task": {
+          if (!arg) { toast("Usage: /ctg-task <task description>.", "warning"); return; }
+          const result = await workspaceClient(context, location).createTask({ task: arg }, AbortSignal.timeout(60_000));
+          context.ui.router.navigate({ type: "session", sessionID: result.sessionID });
+          toast(`Task created in ${context.ui.format.path(result.directory)}.`, "success");
+          return;
+        }
+        case "restart":
+          if (!sessionID) { toast("/restart requires an open session; it interrupts only the selected session and never restarts the shared service.", "warning"); return; }
+          await context.client.session.interrupt({ sessionID, resume: false });
+          toast("Selected session interrupted; its transcript is preserved.", "success");
+          return;
+        case "theme": {
+          const theme = arg.toLowerCase();
+          const cliPath = cliConfigPath();
+          const currentConfig = await readCliConfig(cliPath);
+          const currentTheme = typeof currentConfig.theme === "string" ? currentConfig.theme : currentConfig.theme?.name;
+          if (theme) {
+            if (!THEMES.includes(theme)) { toast(`Unknown theme “${theme}”. Available compatibility names: ${THEMES.join(", ")}.`, "warning"); return; }
+            const provisioned: { directory?: string; installed: string[] } = OPENCODE_BUILTIN_THEMES.has(theme) ? { installed: [] } : await provisionNativeThemes(cliConfigDirectory(), [theme]);
+            if (provisioned.installed.length) {
+              toast(`Installed native theme “${theme}” in ${provisioned.directory ?? cliConfigDirectory()}. Carthagent discovers new theme files at startup; restart the TUI, then run /theme ${theme} again to select it.`, "warning");
+              return;
+            }
+            await writeNativeTheme(cliConfigPath(), theme);
+            toast(`Theme “${theme}” saved to native Carthagent cli.json. Carthagent reloads valid theme selections while the TUI is running.`, "success");
+            return;
+          }
+          const selected = await context.ui.dialog.select({ title: "Carthagent themes", current: currentTheme, options: THEMES.map((name) => ({ title: name, value: name, description: name === "carthage" ? "Carthagent purple field, gold accent" : "Carthagent theme" })) });
+          if (selected) {
+            const provisioned: { directory?: string; installed: string[] } = OPENCODE_BUILTIN_THEMES.has(selected) ? { installed: [] } : await provisionNativeThemes(cliConfigDirectory(), [selected]);
+            if (provisioned.installed.length) {
+              toast(`Installed native theme “${selected}” in ${provisioned.directory ?? cliConfigDirectory()}. Carthagent discovers new theme files at startup; restart the TUI, then select it again.`, "warning");
+              return;
+            }
+            await writeNativeTheme(cliPath, selected);
+            toast(`Theme “${selected}” saved to native Carthagent cli.json. Carthagent reloads valid theme selections while the TUI is running.`, "success");
+          }
+          return;
+        }
+        case "model":
+          await runModelCommand({
+            sync: () => context.data.location.model.sync(location),
+            list: () => context.data.location.model.list(location) ?? [],
+            select: (options) => context.ui.dialog.select({ title: "Select provider model", placeholder: "Search provider/model…", options }),
+            switchModel: (target, model) => context.client.session.switchModel({ sessionID: target, model }),
+            openNativePicker: (query) => context.keymap.dispatch("model.list", query),
+            providerName: nativeProviderName,
+            toast,
+          }, { sessionID, arg });
+          return;
+        case "thinking": {
+          if (!selectedModel) { toast("Choose a model first.", "warning"); return; }
+          const variants = context.ui.model.variant.list();
+          const selected = await context.ui.dialog.select({ title: "Model variant", current: selectedModel.variant, options: [{ title: "Default", value: "" }, ...variants.map((variant) => ({ title: variant, value: variant }))] });
+          if (selected !== undefined) context.ui.model.variant.set(selected || undefined);
+          return;
+        }
+        case "compact":
+          if (!sessionID) { toast("/compact requires an open session.", "warning"); return; }
+          {
+            const result = await sessionApi.compact({ sessionID, ...(arg ? { notes: arg } : {}) });
+            toast(result.admitted ? "Compaction with notes admitted to the selected session." : "Compaction was not admitted.", result.admitted ? "success" : "warning");
+          }
+          return;
+        case "autocompact":
+          if (!sessionID) { toast("/autocompact requires an open session.", "warning"); return; }
+          if (arg && !["on", "off"].includes(arg.toLowerCase())) { toast("Usage: /autocompact [on|off]. Bare /autocompact toggles the selected session.", "warning"); return; }
+          {
+            const action = arg.toLowerCase() || "toggle";
+            const enabled = await setSessionAutoCompaction(context.client.session, sessionID, location, action as "on" | "off" | "toggle");
+            toast(`Automatic compaction ${enabled ? "enabled" : "disabled"} for this session.`, "success");
+          }
+          return;
+        case "review": {
+          if (!sessionID) { toast("/review requires an open session.", "warning"); return; }
+          if (arg && !["ask", "yes", "no", "status"].includes(arg.toLowerCase())) { toast("Usage: /review [ask|yes|no|status]. ask/yes/no sets the Carthagent automatic-review default; bare /review always starts an independent reviewer.", "warning"); return; }
+          if (arg && ["ask", "yes", "no"].includes(arg.toLowerCase())) {
+            const mode = arg.toLowerCase() as "ask" | "yes" | "no";
+            const config = saveCarthagentConfig({ review: mode });
+            toast(`Automatic fresh-review default saved to ${carthagentConfigPath()}: ${resolveReviewMode(undefined, config)}.`, "success");
+            return;
+          }
+          if (arg.toLowerCase() === "status") { toast(`Automatic fresh-review default: ${nativeReviewMode(activeSession, loadCarthagentConfig())} (Carthagent profile: ${carthagentConfigPath()}).`, "info"); return; }
+          {
+            reviewConsumer.setLoopActive(sessionID, true);
+            try {
+              await sendNativeReviewKickoff({ client: context.client, sessionID, signal: lifecycle.signal, prompt: reviewKickoff() });
+              toast("Started the PR → fresh-context review → fixes workflow in this session.", "success");
+            } catch (error) {
+              reviewConsumer.setLoopActive(sessionID, false);
+              throw error;
+            }
+          }
+          return;
+        }
+        case "export":
+          if (!sessionID) { toast("/export requires an open session.", "warning"); return; }
+          {
+            const transfer = await context.client.session.export({ sessionID }, { signal: AbortSignal.timeout(60_000) });
+            const messages = transfer.messages;
+            const session = context.data.session.get(sessionID);
+            const title = session?.title ?? "Carthagent session";
+            const content = messages.map((message) => {
+              const who = message.type === "assistant" ? "Assistant" : message.type === "user" ? "You" : message.type;
+              const body = message.type === "assistant" ? message.content.map((part) => {
+                if (part.type === "text" || part.type === "reasoning") return part.text;
+                if (part.type === "tool") {
+                  const state = part.state;
+                  const input = typeof state.input === "string" ? state.input : JSON.stringify(state.input, null, 2);
+                  const result = "content" in state && state.content ? `\nOutput: ${state.content.map((item) => item.type === "text" ? item.text : JSON.stringify(item)).join("\n")}` : "";
+                  const failure = state.status === "error" ? `\nError: ${state.error.message}` : "";
+                  return `[Tool ${part.name} · ${state.status}]\nInput: ${input}${result}${failure}`;
+                }
+                return "[Unsupported assistant content]";
+              }).join("\n")
+                : message.type === "user" || message.type === "synthetic" || message.type === "system" || message.type === "skill" ? message.text
+                  : message.type === "shell" ? `$ ${message.command}\n${message.output?.output ?? ""}` : message.type === "compaction" ? `[Compaction ${message.status}${message.status === "completed" || message.status === "running" ? `: ${message.summary}` : `: ${message.error.message}`}]` : "";
+              return body ? `<article><h2>${escapeHtml(who)}</h2><pre>${escapeHtml(body)}</pre></article>` : "";
+            }).join("\n");
+            const html = `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>${escapeHtml(title)}</title><style>body{margin:3rem auto;max-width:52rem;padding:0 1rem;background:#160e20;color:#f6f0e7;font:16px/1.6 system-ui}h1{color:#e6c480}article{border-top:1px solid #49364f;padding:1rem 0}h2{color:#c0b3ca;font-size:.9rem}pre{white-space:pre-wrap;font:inherit}</style><h1>${escapeHtml(title)}</h1>${content}</html>`;
+            const base = location.directory;
+            const safeTitle = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "session";
+            const outputPath = resolve(base, arg || `${safeTitle}.html`);
+            await writeFile(outputPath, html, { encoding: "utf8", flag: "wx" });
+            toast(`Session exported to ${context.ui.format.path(outputPath)}`, "success");
+          }
+          return;
+        case "copy": {
+          if (!sessionID) { toast("/copy requires an open session.", "warning"); return; }
+          const { messages } = await context.client.session.export({ sessionID }, { signal: AbortSignal.timeout(60_000) });
+          const latest = messages.filter((message) => message.type === "assistant")
+            .sort((left, right) => (right.time.completed ?? right.time.created) - (left.time.completed ?? left.time.created))[0];
+          const text = latest?.content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
+          if (!text) { toast("No assistant response to copy yet.", "warning"); return; }
+          await copyWithHost(text);
+          toast("Full assistant response copied.", "success");
+          return;
+        }
+        case "stats": {
+          if (!sessionID) { toast("/stats requires an open session.", "warning"); return; }
+          const session = context.data.session.get(sessionID);
+          const cachedCost = context.data.session.cost(sessionID);
+          await context.data.session.message.sync(sessionID);
+          const messages = context.data.session.message.list(sessionID);
+          const assistants = messages.filter((message) => message.type === "assistant");
+          const totals = assistants.reduce((sum, message) => {
+            const tokens = message.tokens;
+            if (tokens) {
+              sum.input += tokens.input;
+              sum.output += tokens.output;
+              sum.reasoning += tokens.reasoning;
+              sum.cacheRead += tokens.cache.read;
+              sum.cacheWrite += tokens.cache.write;
+            }
+            if (message.cost !== undefined) sum.cost += message.cost;
+            return sum;
+          }, { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0, cost: 0 });
+          const hasMessageCost = assistants.some((message) => message.cost !== undefined);
+          if (!hasMessageCost && Number.isFinite(cachedCost) && cachedCost > 0) totals.cost = cachedCost;
+          const hasCost = hasMessageCost || Number.isFinite(cachedCost) && cachedCost > 0;
+          const hasTokens = assistants.some((message) => message.tokens !== undefined);
+          await context.ui.dialog.alert({ title: "Session stats", message: `${session?.title ?? sessionID}\nMessages: ${messages.length} (${assistants.length} assistant)\nInput tokens: ${hasTokens ? totals.input : "not reported"}\nOutput tokens: ${hasTokens ? totals.output : "not reported"}\nReasoning tokens: ${hasTokens ? totals.reasoning : "not reported"}\nCache read/write: ${hasTokens ? `${totals.cacheRead} / ${totals.cacheWrite}` : "not reported"}\nCost: ${hasCost ? `$${totals.cost.toFixed(4)}` : "not reported"}` });
+          return;
+        }
+        case "account": {
+          const result = await shipClient(context, location).account() as { account: Record<string, unknown> };
+          await context.ui.dialog.alert({ title: "Carthagent Ship account", message: cloudAccountText(result.account) });
+          return;
+        }
+        case "usage": {
+          const [accountResult, usageResult] = await Promise.all([
+            shipClient(context, location).account() as Promise<{ account: Record<string, unknown> }>,
+            shipClient(context, location).usage({ limit: 50 }) as Promise<{ usage: Record<string, unknown> }>,
+          ]);
+          await context.ui.dialog.alert({ title: "Carthagent Ship usage", message: cloudUsageText(usageResult.usage, accountResult.account) });
+          return;
+        }
+        case "billing": {
+          const action = arg.toLowerCase() || "checkout";
+          if (!["checkout", "portal"].includes(action)) { toast("Usage: /billing [checkout|portal].", "warning"); return; }
+          const { url } = await shipClient(context, location).billing({ action: action as "checkout" | "portal" }) as { url: string };
+          const { openBrowser } = await import("../../../lib/cloud/client.mjs");
+          const opened = await openBrowser(url).catch(() => false);
+          await context.ui.dialog.alert({ title: action === "portal" ? "Ship billing portal" : "Ship checkout", message: `${opened ? "Opened in your browser." : "Open this URL in your browser:"}\n${url}` });
+          return;
+        }
+        case "logout-cloud": {
+          const session = arg || undefined;
+          const confirmed = await context.ui.dialog.confirm({ title: session ? "Revoke Ship session" : "Sign out of Carthagent Ship", message: session ? `Revoke Ship session ${session}?` : "Revoke the active Ship session and remove its Carthagent connection?" });
+          if (confirmed !== true) return;
+          await shipClient(context, location).logout(session ? { session } : {});
+          toast(session ? `Revoked Ship session ${session}.` : "Revoked and removed the active Carthagent Ship connection.", "success");
+          return;
+        }
+        case "archive": {
+          const [operation, ...rest] = arg.split(/\s+/).filter(Boolean);
+          const archive = archiveClient(context, location);
+          if (operation && !["list", "search", "read", "export"].includes(operation)) { toast("Usage: /archive [list|search <query>|read <id>|export <id>].", "warning"); return; }
+          if (operation === "search" && !rest.length) { toast("Usage: /archive search <query>.", "warning"); return; }
+          if (operation === "read" || operation === "export") {
+            const id = rest[0];
+            if (!id) { toast(`Usage: /archive ${operation} <id>.`, "warning"); return; }
+            if (operation === "read") {
+              const result = await archive.read({ id }) as { records: unknown[] };
+              const content = result.records.map((record: unknown) => JSON.stringify(record)).join("\n") || "Archive is empty.";
+              const pageSize = 24000;
+              for (let offset = 0; offset < content.length; offset += pageSize) {
+                const end = Math.min(offset + pageSize, content.length);
+                await context.ui.dialog.alert({ title: `Archived session ${id} · characters ${offset + 1}–${end} of ${content.length}`, message: content.slice(offset, end) });
+                if (end < content.length && await context.ui.dialog.confirm({ title: "Continue archived session?", message: `Show characters ${end + 1}–${Math.min(end + pageSize, content.length)} of ${content.length}?`, label: { confirm: "Continue", cancel: "Stop reading" } }) !== true) break;
+              }
+            } else {
+              const result = await archive.export({ id, format: "jsonl" }) as { content: string };
+              const path = resolve(location.directory, `${id.replace(/[^a-zA-Z0-9._-]/g, "_")}.jsonl`);
+              await writeFile(path, result.content, { encoding: "utf8", flag: "wx" });
+              toast(`Complete archive export (${Buffer.byteLength(result.content, "utf8")} bytes) saved to ${context.ui.format.path(path)}.`, "success");
+            }
+            return;
+          }
+          const query = operation === "search" ? rest.join(" ") : undefined;
+          let offset = 0;
+          const pageSize = 50;
+          while (true) {
+            const result = (query
+              ? await archive.search({ query, offset, limit: pageSize })
+              : await archive.list({ offset, limit: pageSize })) as { total: number; offset: number; limit: number; items: Array<Record<string, unknown>> };
+            const returned = result.items.length;
+            const first = returned ? result.offset + 1 : 0;
+            const last = result.offset + returned;
+            await context.ui.dialog.alert({
+              title: `${query ? "Archive search" : "Archived sessions"} · ${first}–${last} of ${result.total}`,
+              message: `${returned} item(s) returned on this page${result.total > returned ? `; ${result.total} total matches` : ""}.\n\n${result.items.map(archiveItemText).join("\n\n") || (query ? "No archived sessions matched." : "No archived sessions found.")}`,
+            });
+            if (!returned || last >= result.total) break;
+            const next = await context.ui.dialog.confirm({ title: "More archived sessions?", message: `Showing ${last} of ${result.total}. Load the next page?`, label: { confirm: "Next page", cancel: "Done" } });
+            if (next !== true) break;
+            offset += returned;
+          }
+          return;
+        }
+        case "demo": {
+          const { runOfflineDemo } = await import("../../../lib/opencode/demo.mjs");
+          const lines: string[] = [];
+          const demoIo = Object.assign(Object.create(console), {
+            log: (...values: unknown[]) => { lines.push(values.map(String).join(" ")); },
+            error: (...values: unknown[]) => { lines.push(values.map(String).join(" ")); },
+          }) as Console;
+          let exitCode: number;
+          try { exitCode = await runOfflineDemo({ io: demoIo, signal: lifecycle.signal }); }
+          catch (error) {
+            if (lifecycle.signal.aborted) return;
+            throw error;
+          }
+          await context.ui.dialog.alert({ title: exitCode === 130 ? "Carthagent offline demo · cancelled" : exitCode === 0 ? "Carthagent offline demo · fixture passed" : "Carthagent offline demo · fixture failed", message: `${lines.join("\n")}\n\nActual fixture exit status: ${exitCode}\nThis disposable fixture is not evidence about the current workspace.` });
+          return;
+        }
+        case "clear":
+          if (!sessionID) { toast("/clear requires an open session.", "warning"); return; }
+          // Hand off to the registered host action; it owns presentation
+          // state and guarantees the durable conversation is untouched.
+          context.keymap.dispatch("session.transcript.clear");
+          return;
+        case "abort":
+          if (!sessionID) { toast("/abort requires an open session.", "warning"); return; }
+          await context.client.session.interrupt({ sessionID, resume: false });
+          return;
+        case "raw":
+          if (!sessionID || !arg) { toast("Usage: /raw <prompt> (inside a session).", "warning"); return; }
+          await context.client.session.prompt({ sessionID, text: arg, metadata: { "ctg.raw": true } });
+          return;
+        case "guide":
+          if (!sessionID) { toast("/guide requires an open session.", "warning"); return; }
+          if (!arg) {
+            const result = await sessionApi.framing({ sessionID });
+            toast(`Carthagent framing ${result.enabled ? "enabled" : "disabled"} for this session.`, "success");
+            return;
+          }
+          await context.client.session.prompt({ sessionID, text: framePrompt(arg) });
+          return;
+        case "workflow": case "architecture": case "evidence":
+          context.ui.router.navigate({ type: "plugin", name: "carthagent", data: { view: id, ...(sessionID ? { sessionID } : {}) } });
+          return;
+        case "ctg-workspace":
+          context.ui.router.navigate({ type: "plugin", name: "carthagent", data: { view: "workspace" } });
+          return;
+        case "ctg-open": {
+          const api = workspaceClient(context, location);
+          if (!api) { toast("CTG workspace service is unavailable.", "warning"); return; }
+          try {
+            const snapshot = await api.snapshot();
+            const sessions = snapshot.sessions.filter((session) => !arg || `${session.title} ${session.id}`.toLowerCase().includes(arg.toLowerCase()));
+            const selected = await context.ui.dialog.select({ title: "Open CTG session", options: sessions.map((session) => ({ title: session.title, value: session.id, description: `${session.status} · ${session.id}` })) });
+            if (selected) {
+              await api.open({ sessionID: selected });
+              context.ui.router.navigate({ type: "session", sessionID: selected });
+            }
+          } catch (error) { toast(error instanceof Error ? error.message : String(error), "error"); }
+          return;
+        }
+        case "ctg-worktree":
+          await createWorktree(arg);
+          return;
+        case "ctg-preview": case "ctg-review": {
+          if (!sessionID) { toast(`/${id} requires an open session.`, "warning"); return; }
+          const api = workspaceClient(context, location);
+          if (!api) { toast("CTG workspace service is unavailable.", "warning"); return; }
+          try {
+            const result = id === "ctg-review" ? await api.review({ sessionID }) : await api.delivery({ sessionID });
+            toast(result ? JSON.stringify(result) : "No CTG status is recorded for this session.", "info");
+          } catch (error) { toast(error instanceof Error ? error.message : String(error), "error"); }
+          return;
+        }
+      }
+    }
+
+    async function createWorktree(input: string) {
+      const route = context.ui.router.current();
+      const sessionID = route.type === "session" ? route.sessionID : route.type === "plugin" && route.name === "carthagent" && typeof route.data?.sessionID === "string" ? route.data.sessionID : undefined;
+      const selectedLocation = sessionID ? context.data.session.get(sessionID)?.location : undefined;
+      const api = workspaceClient(context, selectedLocation);
+      if (!api) { context.ui.toast.show({ message: "CTG workspace RPC is unavailable; no worktree was created.", variant: "warning" }); return; }
+      const [projectID, ...nameParts] = input.trim().split(/\s+/);
+      const name = nameParts.join(" ");
+      if (!projectID || !name) { context.ui.toast.show({ message: "Usage: /ctg-worktree <local-project-id> <name>.", variant: "warning" }); return; }
+      try {
+        const result = await api.createWorktree({ projectID, name });
+        context.ui.toast.show({ message: `CTG worktree created at ${context.ui.format.path(result.directory)}`, variant: "success" });
+      } catch (error) { context.ui.toast.show({ message: error instanceof Error ? error.message : String(error), variant: "error" }); }
+    }
+
+    async function copyWithHost(text: string) {
+      if (!context.renderer.isOsc52Supported()) throw new Error("This terminal does not support OSC 52 clipboard copy; select and copy the response manually.");
+      if (!context.renderer.copyToClipboardOSC52(text)) throw new Error("Terminal rejected clipboard copy; select and copy the response manually.");
+    }
+
+    function escapeHtml(value: string) {
+      return value.replace(/[&<>"']/g, (character) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[character]!);
+    }
+
+    cleanups.push(context.ui.slot({ append: "session.panel", render: (panel) => <Show when={panel.name === "carthagent.delivery"}><text fg={context.theme.text.base}>Carthagent delivery · session {panel.sessionID} · use /workflow or /evidence for the CTG workspace report</text></Show> }));
+    cleanups.push(context.ui.slot({ append: "home.footer.status", render: () => <text fg={context.theme.hue.accent[400]}>◆ CTG</text> }));
+    const stopEvents = context.data.listen(({ details }) => {
+      if (details.type.startsWith("session.")) {
+        const data = (details as unknown as { data?: { sessionID?: string } }).data;
+        if (data?.sessionID) context.data.session.invalidate(data.sessionID);
+      }
+      if (details.type.startsWith("rpc.carthagent.workspace.")) context.data.project.invalidate();
+    });
+    cleanups.push(stopEvents);
+    return () => cleanups.reverse().forEach((cleanup) => cleanup());
+  },
+});

package/plugins/carthagent/src/ui/client.ts

@@ -0,0 +1,127 @@
+import type { Context } from "@opencode/plugin/tui/context";
+import type { LocationRef } from "@opencode/client";
+import { Workspace, type WorkspaceDelivery, type WorkspaceSnapshot } from "../workspace-rpc.js";
+import { SessionControls } from "../session-rpc.js";
+import { PullRequests, type PullRequestRecord } from "../pull-request-rpc.js";
+import { Archive } from "../archive-rpc.js";
+import { Carthagent } from "../rpc.js";
+import { Voyages, type VoyagesSnapshot, type VoyagesProfile, type VoyagesItem, type VoyagesQuote } from "../voyages-rpc.js";
+import { DailyQuests, type DailyEvidence, type DailySnapshot, type DailyQuestDetail } from "../daily-quests-rpc.js";
+import { DailySource, type DailySourceReport } from "../daily-source-rpc.js";
+import { formatCloudAccount, formatCloudUsage } from "../../../../lib/cloud/client.mjs";
+
+export { Workspace, SessionControls, PullRequests, Archive };
+export type { WorkspaceDelivery, WorkspaceSnapshot, PullRequestRecord };
+export type { VoyagesSnapshot, VoyagesProfile, VoyagesItem, VoyagesQuote };
+
+const REQUEST_TIMEOUT_MS = 15_000;
+
+type RpcContext = Pick<Context, "client" | "location" | "data">;
+
+type SelectedLocation = LocationRef | (() => LocationRef | undefined);
+
+function requestOptions(context: RpcContext, selectedLocation?: SelectedLocation, signal?: AbortSignal) {
+  const location = typeof selectedLocation === "function" ? selectedLocation() : selectedLocation;
+  return {
+    location: location ?? context.location ?? context.data.location.default(),
+    signal: signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  };
+}
+
+export function voyagesClient(context: RpcContext, selectedLocation?: SelectedLocation) {
+  const rpc = context.client.rpc(Voyages);
+  return {
+    previewReward: (input: { sessionID: string }, signal?: AbortSignal) => rpc.previewReward(input, requestOptions(context, selectedLocation, signal)),
+    claimReward: (input: { sessionID: string; runId: string; snapshot: string }, signal?: AbortSignal) => rpc.claimReward(input, requestOptions(context, selectedLocation, signal)),
+    snapshot: (signal?: AbortSignal) => rpc.snapshot({}, requestOptions(context, selectedLocation, signal)) as Promise<VoyagesSnapshot>,
+    customize: (input: { version: number; name?: string; shipName?: string; skin?: string; hair?: string; pattern?: string }, signal?: AbortSignal) => rpc.customize(input, requestOptions(context, selectedLocation, signal)),
+    equip: (input: { version: number; slot: string; item: string }, signal?: AbortSignal) => rpc.equip(input, requestOptions(context, selectedLocation, signal)),
+    quote: (input: { slot: string; item: string }, signal?: AbortSignal) => rpc.quote(input, requestOptions(context, selectedLocation, signal)),
+    purchase: (input: { quoteId: string }, signal?: AbortSignal) => rpc.purchase(input, requestOptions(context, selectedLocation, signal)),
+    retryPurchase: (input: { quoteId: string }, signal?: AbortSignal) => rpc.retryPurchase(input, requestOptions(context, selectedLocation, signal)),
+  };
+}
+
+export function dailyQuestsClient(context: RpcContext, selectedLocation?: SelectedLocation) {
+  const rpc = context.client.rpc(DailyQuests);
+  return {
+    snapshot: (signal?: AbortSignal) => rpc.snapshot({}, requestOptions(context, selectedLocation, signal)) as Promise<DailySnapshot>,
+    detail: (input: { id: string }, signal?: AbortSignal) => rpc.detail(input, requestOptions(context, selectedLocation, signal)) as Promise<DailyQuestDetail>,
+    submit: (input: { accountKey: string; questId: string; id: string; consent: true; evidence: DailyEvidence }, signal?: AbortSignal) => rpc.submit(input, requestOptions(context, selectedLocation, signal)),
+    retry: (input: { accountKey: string; id: string }, signal?: AbortSignal) => rpc.retry(input, requestOptions(context, selectedLocation, signal)),
+    poll: (input: { id: string }, signal?: AbortSignal) => rpc.poll(input, requestOptions(context, selectedLocation, signal)),
+    forgetPayload: (input: { accountKey: string; id: string }, signal?: AbortSignal) => rpc.forgetPayload(input, requestOptions(context, selectedLocation, signal)),
+  };
+}
+
+export function dailySourceClient(context: RpcContext, selectedLocation?: SelectedLocation) {
+  const rpc = context.client.rpc(DailySource);
+  return { report: (input: { sessionID: string }, signal?: AbortSignal) => rpc.report(input, requestOptions(context, selectedLocation, signal)) as Promise<{ source: DailySourceReport | null }> };
+}
+
+export function workspaceClient(context: RpcContext, selectedLocation?: SelectedLocation) {
+  const rpc = context.client.rpc(Workspace);
+  return {
+    snapshot: (input?: { projectID?: string }, signal?: AbortSignal) => rpc.snapshot(input ?? {}, requestOptions(context, selectedLocation, signal)) as Promise<WorkspaceSnapshot>,
+    open: (input: { sessionID: string }, signal?: AbortSignal) => rpc.open(input, requestOptions(context, selectedLocation, signal)) as Promise<{ opened: boolean; directory: string }>,
+    createWorktree: (input: { projectID: string; name: string }, signal?: AbortSignal) => rpc.createWorktree(input, requestOptions(context, selectedLocation, signal)) as Promise<{ directory: string }>,
+    createTask: (input: { task: string; branch?: string }, signal?: AbortSignal) => rpc.createTask(input, requestOptions(context, selectedLocation, signal)) as Promise<{ taskID: string; sessionID: string; directory: string }>,
+    delivery: (input: { sessionID: string }, signal?: AbortSignal) => rpc.delivery(input, requestOptions(context, selectedLocation, signal)) as Promise<WorkspaceDelivery>,
+    review: (input: { sessionID: string }, signal?: AbortSignal) => rpc.review(input, requestOptions(context, selectedLocation, signal)) as Promise<{ status: string; summary?: string }>,
+    startReview: (input: { sessionID: string }, signal?: AbortSignal) => rpc.startReview(input, requestOptions(context, selectedLocation, signal)) as Promise<{ status: string; summary: string; sessionID?: string }>,
+    events: rpc.events,
+  };
+}
+
+export function sessionControls(context: RpcContext, selectedLocation?: SelectedLocation) {
+  const rpc = context.client.rpc(SessionControls);
+  return {
+    framing: (input: { sessionID: string; enabled?: boolean }, signal?: AbortSignal) => rpc.framing(input, requestOptions(context, selectedLocation, signal)) as Promise<{ enabled: boolean }>,
+    compact: (input: { sessionID: string; notes?: string }, signal?: AbortSignal) => rpc.compact(input, requestOptions(context, selectedLocation, signal)) as Promise<{ admitted: boolean }>,
+  };
+}
+
+export function pullRequestClient(context: RpcContext, selectedLocation?: SelectedLocation) {
+  const rpc = context.client.rpc(PullRequests);
+  return {
+    list: (input: { sessionID: string; taskID: string }, signal?: AbortSignal) => rpc.list(input, requestOptions(context, selectedLocation, signal)) as Promise<{ pullRequests: PullRequestRecord[] }>,
+    associate: (input: { sessionID: string; taskID: string; number: number }, signal?: AbortSignal) => rpc.associate(input, requestOptions(context, selectedLocation, signal)) as Promise<{ pullRequest: PullRequestRecord }>,
+    refresh: (input: { sessionID: string; taskID: string; number?: number }, signal?: AbortSignal) => rpc.refresh(input, requestOptions(context, selectedLocation, signal)) as Promise<{ pullRequest: PullRequestRecord }>,
+  };
+}
+
+export function shipClient(context: RpcContext, selectedLocation?: SelectedLocation) {
+  const rpc = context.client.rpc(Carthagent);
+  return {
+    account: (signal?: AbortSignal) => rpc.shipAccount({}, requestOptions(context, selectedLocation, signal)),
+    usage: (input: { limit?: number } = {}, signal?: AbortSignal) => rpc.shipUsage(input, requestOptions(context, selectedLocation, signal)),
+    billing: (input: { action: "checkout" | "portal" }, signal?: AbortSignal) => rpc.shipBilling(input, requestOptions(context, selectedLocation, signal)),
+    logout: (input: { session?: string } = {}, signal?: AbortSignal) => rpc.shipLogout(input, requestOptions(context, selectedLocation, signal)),
+  };
+}
+
+export function archiveClient(context: RpcContext, selectedLocation?: SelectedLocation) {
+  const rpc = context.client.rpc(Archive);
+  return {
+    list: (input: { offset?: number; limit?: number } = {}, signal?: AbortSignal) => rpc.list(input, requestOptions(context, selectedLocation, signal)),
+    search: (input: { query: string; offset?: number; limit?: number }, signal?: AbortSignal) => rpc.search(input, requestOptions(context, selectedLocation, signal)),
+    read: (input: { id: string }, signal?: AbortSignal) => rpc.read(input, requestOptions(context, selectedLocation, signal)),
+    export: (input: { id: string; format?: "json" | "jsonl" }, signal?: AbortSignal) => rpc.export(input, requestOptions(context, selectedLocation, signal)),
+  };
+}
+
+export function cloudAccountText(account: Record<string, unknown>) {
+  return formatCloudAccount(account);
+}
+
+export function cloudUsageText(usage: Record<string, unknown>, account?: Record<string, unknown>) {
+  return formatCloudUsage(usage, { account } as Parameters<typeof formatCloudUsage>[1]);
+}
+
+export function archiveItemText(item: Record<string, unknown>) {
+  return `${String(item.id)} · ${String(item.messageCount)} messages${item.createdAt ? ` · ${String(item.createdAt)}` : ""}${item.excerpt ? `\n${String(item.excerpt)}` : ""}`;
+}
+
+export function rpcEventOptions(_context: RpcContext, signal?: AbortSignal): { signal?: AbortSignal } {
+  return signal ? { signal } : {};
+}