@mtayfur/opencode-chat-tree 1.0.1

package/README.md

@@ -0,0 +1,123 @@
+# OpenCode Chat Tree
+
+`@mtayfur/opencode-chat-tree` adds persistent conversation branching to the OpenCode TUI. It presents related sessions as a navigable tree, creates branches from any visible message, and can carry a generated handoff into the new branch.
+
+## Capabilities
+
+- Open the current conversation tree with `/tree`.
+- Navigate parent and child sessions from a single view.
+- Collapse sessions or calendar-day groups.
+- Branch from user and assistant messages without changing OpenCode's fork semantics.
+- Replay a selected user prompt in the new branch.
+- Generate an optional branch handoff.
+- Store tree metadata globally or inside the project.
+- Detect deleted sessions while preserving their descendants in the tree.
+
+## Requirements
+
+- OpenCode `1.18.16` or newer compatible 1.x release
+- Bun `1.3.14` or newer for local development
+
+## Installation
+
+Add the package to `~/.config/opencode/tui.json`:
+
+```json
+{
+  "plugin": ["@mtayfur/opencode-chat-tree"]
+}
+```
+
+OpenCode installs package plugins automatically. Restart the TUI after changing the configuration.
+
+### Local checkout
+
+```sh
+bash ./install.sh
+```
+
+The installer resolves dependencies, builds `dist/index.js`, and replaces the package entry with a local file URL. Restore the published package entry with:
+
+```sh
+bash ./install.sh --uninstall
+```
+
+## Configuration
+
+The plugin intentionally keeps its configuration small:
+
+```json
+{
+  "plugin": [
+    [
+      "@mtayfur/opencode-chat-tree",
+      {
+        "storageScope": "global",
+        "model": "openai/gpt-5.6-luna-fast",
+        "variant": "high"
+      }
+    ]
+  ]
+}
+```
+
+| Option         | Default                | Description                             |
+| -------------- | ---------------------- | --------------------------------------- |
+| `storageScope` | `global`               | Use `global` or `local` tree metadata.  |
+| `model`        | Current OpenCode model | Model used to generate branch handoffs. |
+| `variant`      | Model default          | Model variant used for branch handoffs. |
+
+Unknown options are ignored so removing an obsolete option does not prevent the plugin from loading.
+
+## Controls
+
+| Keys             | Action                                           |
+| ---------------- | ------------------------------------------------ |
+| `↑` / `k`        | Move up                                          |
+| `↓` / `j`        | Move down                                        |
+| `←` / `h`        | Collapse the selected group                      |
+| `→` / `l`        | Expand the selected group                        |
+| `Enter`          | Open a session, toggle a day, or create a branch |
+| `Esc` / `Ctrl+C` | Return to the originating session                |
+
+Controls are fixed by design. OpenCode activates them only while the tree has focus.
+
+## Branch behavior
+
+- Selecting a session opens it.
+- Selecting a user message forks at that message and restores its prompt in the input area.
+- Selecting an assistant message forks at the following message boundary.
+- Selecting the last assistant message returns to its session because no later fork boundary exists.
+- A generated handoff is written into the new session as context without requesting a reply.
+
+## Storage
+
+- Global: `<OpenCode state>/plugins/opencode-chat-tree/projects/<project-slug-hash>/`
+- Local: `<project>/.opencode/opencode-chat-tree/`
+
+Each project has a `registry.json` and immutable-style tree snapshots under `trees/<tree-id>/snapshot.json`. Writes use temporary files and atomic renames. The plugin validates ownership, parent-child symmetry, graph reachability, and path-safe tree IDs before using persisted data.
+
+## Architecture
+
+```text
+src/
+├── adapters/       OpenCode and filesystem boundaries
+├── core/           Tree, transcript, projection, and branch rules
+├── ui/             TUI controls, workflow, route, and rendering
+├── configuration.ts
+└── index.ts        Plugin entrypoint
+```
+
+Core modules are side-effect free. `TreeRepository` owns persistence, while `OpenCodeTreeGateway` owns SDK calls and fork cleanup. The UI only coordinates reactive state and user interaction.
+
+## Development
+
+From the repository root:
+
+```sh
+bun install --frozen-lockfile
+bun run --filter @mtayfur/opencode-chat-tree fmt:check
+bun run --filter @mtayfur/opencode-chat-tree typecheck
+bun run --filter @mtayfur/opencode-chat-tree build
+npm pack ./packages/chat-tree --dry-run
+```

package/dist/adapters/opencode-gateway.d.ts

@@ -0,0 +1,50 @@
+import type { OpencodeClient } from "@opencode-ai/sdk/v2";
+import type { BranchPlan } from "../core/branching";
+import type { TreeSnapshot } from "../core/tree";
+import { type TranscriptMap, type ConversationEntry } from "../core/transcript";
+import type { TreeRepository } from "./tree-repository";
+export type SummaryModel = {
+    readonly providerID: string;
+    readonly modelID: string;
+};
+export type SummaryRequest = {
+    readonly messages: readonly ConversationEntry[];
+    readonly customInstructions?: string;
+    readonly signal?: AbortSignal;
+    readonly model?: SummaryModel;
+    readonly variant?: string;
+};
+export type CreatedBranch = {
+    readonly sessionId: string;
+    readonly replayPrompt?: string;
+};
+export declare class OpenCodeTreeGateway {
+    private readonly client;
+    private readonly projectRoot;
+    private readonly repository;
+    constructor(input: {
+        readonly client: OpencodeClient;
+        readonly projectRoot: string;
+        readonly repository: TreeRepository;
+    });
+    loadTranscripts(snapshot: TreeSnapshot): Promise<TranscriptMap>;
+    createBranch(snapshot: TreeSnapshot, plan: BranchPlan, summary?: SummaryRequest): Promise<CreatedBranch>;
+    enterBranch(branch: CreatedBranch, navigate: (sessionId: string) => void | Promise<void>): Promise<void>;
+    private loadTranscript;
+    private normalizeEntry;
+    private generateSummary;
+    private promptSummary;
+    private buildSummaryPrompt;
+    private injectSummary;
+    private abortSession;
+    private deleteSession;
+    private cleanupForkedSession;
+    private isNotFoundResult;
+    private isNotFoundError;
+    private createSdkError;
+    private getErrorMessage;
+    private toError;
+    private toSummaryGenerationError;
+    private isAbortError;
+    private createSummaryCancellationError;
+}

package/dist/adapters/tree-repository.d.ts

@@ -0,0 +1,25 @@
+import { type TreeSnapshot } from "../core/tree";
+export type StorageScope = "global" | "local";
+export type TreeContext = {
+    readonly kind: "missing-session";
+    readonly projectRoot: string;
+} | {
+    readonly kind: "ready";
+    readonly projectRoot: string;
+    readonly snapshot: TreeSnapshot;
+};
+export declare function resolveTreeStorageRoot(input: {
+    readonly projectRoot: string;
+    readonly stateRoot: string;
+    readonly scope: StorageScope;
+}): string;
+export declare class TreeRepository {
+    private readonly storageRoot;
+    constructor(storageRoot: string);
+    open(projectRoot: string, sessionId?: string): Promise<TreeContext>;
+    saveBranch(snapshot: TreeSnapshot, input: {
+        readonly sessionId: string;
+        readonly parentSessionId: string;
+        readonly anchorMessageId: string;
+    }): Promise<void>;
+}

package/dist/configuration.d.ts

@@ -0,0 +1,9 @@
+import type { SummaryModel } from "./adapters/opencode-gateway";
+import type { StorageScope } from "./adapters/tree-repository";
+export type PluginConfiguration = {
+    readonly storageScope: StorageScope;
+    readonly model?: SummaryModel;
+    readonly variant?: string;
+};
+export declare function readPluginConfiguration(value: unknown): PluginConfiguration;
+export declare function readSummaryModel(value: string | undefined): SummaryModel | undefined;

package/dist/core/branching.d.ts

@@ -0,0 +1,23 @@
+import { type TranscriptMap, type ConversationEntry } from "./transcript";
+import type { TreeRow } from "./projection";
+export type BranchPlan = {
+    readonly sessionId: string;
+    readonly anchorMessageId: string;
+    readonly forkMessageId: string;
+    readonly appendPromptText?: string;
+};
+export type BranchIntent = {
+    readonly kind: "none";
+} | {
+    readonly kind: "notice";
+    readonly message: string;
+    readonly variant: "info" | "error";
+} | {
+    readonly kind: "navigate";
+    readonly sessionId: string;
+} | {
+    readonly kind: "fork";
+    readonly plan: BranchPlan;
+};
+export declare function planBranchIntent(row: TreeRow | undefined, transcripts: TranscriptMap): BranchIntent;
+export declare function collectSummaryMessages(row: TreeRow | undefined, transcripts: TranscriptMap): readonly ConversationEntry[];

package/dist/core/projection.d.ts

@@ -0,0 +1,74 @@
+import type { TreeSnapshot } from "./tree";
+import { type SessionTranscript, type TranscriptMap, type ConversationEntry } from "./transcript";
+export type ProjectedMessage = {
+    readonly kind: "message";
+    readonly sessionId: string;
+    readonly messageId: string;
+    readonly entry: ConversationEntry;
+    readonly childSessions: readonly ProjectedSession[];
+};
+export type ProjectedSession = {
+    readonly kind: "session";
+    readonly sessionId: string;
+    readonly status: SessionTranscript["status"];
+    readonly childSessions: readonly ProjectedSession[];
+    readonly messages: readonly ProjectedMessage[];
+};
+export declare function projectConversationTree(snapshot: TreeSnapshot, transcripts: TranscriptMap): ProjectedSession;
+export type SessionRowId = `session:${string}`;
+export type MessageRowId = `message:${string}:${string}`;
+export type DayRowId = `day:${string}:${string}:${string}`;
+export type TreeRowId = SessionRowId | MessageRowId | DayRowId;
+export declare function getSessionRowId(sessionId: string): SessionRowId;
+export declare function getMessageRowId(sessionId: string, messageId: string): MessageRowId;
+export declare function getDayRowId(day: string, sessionId: string, messageId: string): DayRowId;
+type SessionRow = {
+    readonly kind: "session";
+    readonly id: SessionRowId;
+    readonly depth: number;
+    readonly sessionId: string;
+    readonly title: string;
+    readonly isDeleted: boolean;
+    readonly isCollapsible: boolean;
+    readonly isCollapsed: boolean;
+};
+type DayRow = {
+    readonly kind: "day";
+    readonly id: DayRowId;
+    readonly depth: number;
+    readonly sessionId: string;
+    readonly day: string;
+    readonly isCollapsible: true;
+    readonly isCollapsed: boolean;
+};
+type MessageRow = {
+    readonly kind: "message";
+    readonly id: MessageRowId;
+    readonly depth: number;
+    readonly sessionId: string;
+    readonly messageId: string;
+    readonly role: ConversationEntry["metadata"]["role"];
+    readonly createdAt?: number;
+    readonly preview: string;
+};
+export type TreeRow = SessionRow | DayRow | MessageRow;
+export type TreePresentation = {
+    readonly rows: readonly TreeRow[];
+    readonly rowIndexById: Readonly<Record<TreeRowId, number>>;
+    readonly lastRowIndexBySessionId: Readonly<Record<string, number>>;
+    readonly parentRowIdById: ReadonlyMap<TreeRowId, TreeRowId | undefined>;
+    readonly sessionById: Readonly<Record<string, ProjectedSession>>;
+};
+type PresentationOptions = {
+    readonly collapsedSessionIds?: ReadonlySet<string>;
+    readonly collapsedDays?: ReadonlySet<string>;
+};
+export declare function buildTreePresentation(root: ProjectedSession, options?: PresentationOptions): TreePresentation;
+export declare function resolveVisibleRowId(input: {
+    readonly presentation: TreePresentation;
+    readonly currentSessionId?: string;
+    readonly preferredRowId?: TreeRowId;
+}): TreeRowId | undefined;
+export declare function moveRowSelection(rows: readonly TreeRow[], currentIndex: number | undefined, direction: -1 | 1): number | undefined;
+export declare function formatLocalDay(createdAt: number): string | undefined;
+export {};

package/dist/core/transcript.d.ts

@@ -0,0 +1,23 @@
+import type { Message, Part } from "@opencode-ai/sdk/v2";
+export type ConversationEntry = {
+    readonly id: string;
+    readonly metadata: Message;
+    readonly parts: readonly Part[];
+};
+export type SessionTranscript = {
+    readonly sessionId: string;
+    readonly status: "available" | "deleted";
+    readonly messages: readonly ConversationEntry[];
+    readonly byId: ReadonlyMap<string, ConversationEntry>;
+    readonly indexById: ReadonlyMap<string, number>;
+};
+export type TranscriptMap = Readonly<Record<string, SessionTranscript>>;
+export declare function createSessionTranscript(input: {
+    readonly sessionId: string;
+    readonly status: SessionTranscript["status"];
+    readonly messages: readonly ConversationEntry[];
+}): SessionTranscript;
+export declare function getVisibleText(parts: readonly Part[]): string | undefined;
+export declare function getMessagePreview(input: Pick<ConversationEntry, "parts">): string;
+export declare function isInternalAssistantMessage(message: ConversationEntry): boolean;
+export declare function serializeTranscriptForSummary(messages: readonly ConversationEntry[]): string;

package/dist/core/tree.d.ts

@@ -0,0 +1,20 @@
+export declare const STORAGE_FORMAT_VERSION: 1;
+export type TreeNode = {
+    readonly sessionId: string;
+    readonly parentSessionId: string | null;
+    readonly anchorMessageId: string | null;
+    readonly children: readonly string[];
+};
+export type TreeSnapshot = {
+    readonly version: typeof STORAGE_FORMAT_VERSION;
+    readonly treeId: string;
+    readonly rootSessionId: string;
+    readonly sessions: Readonly<Record<string, TreeNode>>;
+};
+export declare function createTreeId(generateUuid?: () => string): string;
+export declare function createRootSnapshot(treeId: string, sessionId: string): TreeSnapshot;
+export declare function attachBranch(snapshot: TreeSnapshot, input: {
+    readonly sessionId: string;
+    readonly parentSessionId: string;
+    readonly anchorMessageId: string;
+}): TreeSnapshot;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import type { TuiPlugin } from "@opencode-ai/plugin/tui";
+declare const _default: {
+    id: string;
+    tui: TuiPlugin;
+};
+export default _default;