@genspark/opencode-conversation-archiver 0.1.0

package/README.md

@@ -0,0 +1,164 @@
+# OpenCode conversation archiver
+
+An OpenCode server plugin that archives every top-level conversation after each
+completed turn. It keeps one Markdown file per session in a git repository and
+records only user-visible text:
+
+- user text parts;
+- assistant text parts;
+- context-compaction boundaries.
+
+Reasoning, tool calls, tool outputs, file URLs, synthetic text, ignored text,
+and child/subagent sessions are excluded.
+
+## Install From This Repository
+
+Build the package:
+
+```bash
+cd toolkits/opencode-conversation-archiver
+npm install
+npm run build
+```
+
+Register the built server entry in `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "./toolkits/opencode-conversation-archiver/dist/server.js"
+  ]
+}
+```
+
+The path is relative to the config file. Quit and restart OpenCode after adding
+or updating a plugin because configuration is loaded only at startup.
+
+For package distribution, the package exposes OpenCode's native `./server`
+entry and declares compatibility with OpenCode `1.17.18` through `<2`.
+
+## Default Behavior
+
+- Archive repo: `~/opencode-conversations`
+- Runtime state: `~/.config/opencode/conversation-archiver/`
+- Mode: `auto`
+- Trigger: canonical `session.status` event with `status.type === "idle"`
+- Auto mode: write, commit, and launch a detached push after every changed turn
+- Manual mode: write locally without commit or push
+- No remote: commits remain local and push failure never interrupts OpenCode
+
+The event hook owns a per-session queue because OpenCode intentionally does not
+await plugin event callbacks. `dispose` drains pending snapshots during a clean
+shutdown. Git and tmux commands use asynchronous child processes so archive
+work does not block OpenCode's event loop.
+
+## Management Tools
+
+The plugin exposes these native tools:
+
+| Tool | Purpose |
+| --- | --- |
+| `conversation_archive_status` | Mode, repo, redacted remote, commits, pending changes |
+| `conversation_archive_doctor` | Read-only dependency, repo, remote-auth, and activity diagnosis |
+| `conversation_archive_current` | Archive the current live session immediately |
+| `conversation_archive_backfill` | Archive all top-level sessions visible in the current OpenCode project |
+
+Users can ask OpenCode to invoke these tools naturally, for example: "diagnose
+my conversation archive". The two write tools request explicit permission.
+Credential-bearing and repository-management operations are CLI-only so their
+arguments never enter an LLM-visible conversation or tool call.
+
+OpenCode `1.17.18` does not expose a direct, no-LLM server slash-command handler.
+Markdown commands always enter the prompt pipeline and `command.execute.before`
+cannot short-circuit it. For deterministic automation, use the bundled CLI:
+
+```bash
+opencode-conversation-archiver status
+opencode-conversation-archiver doctor
+opencode-conversation-archiver manual
+opencode-conversation-archiver auto
+opencode-conversation-archiver upload
+opencode-conversation-archiver repo ~/Documents/opencode-conversations
+opencode-conversation-archiver connect '<sb-connect-link>'
+```
+
+`backfill` and `current` remain live tools because they require the injected
+OpenCode SDK and current session identity.
+
+## Second Brain
+
+`conversation_archive_connect` and the CLI `connect` support:
+
+1. A one-time `.../sb-connect/<code>` URL.
+2. No arguments, using `GSK_API_KEY` or the credential created by `gsk login`.
+3. An explicit HTTP(S) git remote and token.
+
+The git credential is stored at
+`~/.config/opencode/conversation-archiver/git-credentials` with mode `0600`,
+outside the archive repository. The remote URL shown by status, doctor, and logs
+is credential-redacted. Connected archives are confined to the `opencode/`
+subdirectory by default with sparse checkout.
+
+## Configuration
+
+Runtime configuration:
+
+```json
+{
+  "mode": "auto",
+  "repo": "/home/you/opencode-conversations",
+  "subdir": "opencode"
+}
+```
+
+Environment overrides:
+
+- `OPENCODE_ARCHIVE_MODE`
+- `OPENCODE_ARCHIVE_REPO`
+- `OPENCODE_ARCHIVE_NO_NOTIFY`
+
+For isolated tests or embedded installations, pass `appDir` as plugin options:
+
+```json
+{
+  "plugin": [
+    [
+      "@genspark/opencode-conversation-archiver",
+      { "appDir": "/custom/runtime-state" }
+    ]
+  ]
+}
+```
+
+## Preservation Guarantees
+
+- Message and compaction part IDs make overlapping/repeated idle events idempotent.
+- Cumulative text for an existing message ID can grow without duplicating a turn.
+- Session state is append-only and outside the git repo.
+- Title changes rename the archive while preserving git history where possible.
+- A collision index prevents one session from overwriting another.
+- A never-shrink guard diverts to a suffixed file if disk content is richer than
+  local state, preserving both copies instead of dropping turns.
+- Archive and push operations use cross-process lock directories.
+- Remote pushes serialize, pull with rebase, and abort a failed in-progress rebase.
+
+## Development
+
+```bash
+npm test
+npm run typecheck
+npm run build
+npm pack --dry-run
+```
+
+### Local End-to-End Verification
+
+The release was verified against a real local OpenCode `1.17.18` process, not
+only mocked SDK tests. An isolated `opencode run` session using Claude Haiku
+completed with `ARCHIVER_E2E_OK`; the plugin then created a titled Markdown
+archive containing one user and one assistant turn and committed it to the
+isolated archive git repository. The temporary plugin config and archive paths
+were supplied through `OPENCODE_CONFIG_CONTENT`, `appDir`, and
+`OPENCODE_ARCHIVE_REPO`, so the normal OpenCode configuration and archive were
+not modified.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { connect, doctor, setMode, setRepo, status, upload } from './core.js';
+const [command, ...args] = process.argv.slice(2);
+function requireSuccess(result) {
+    if (/failed|failure|not initialized|requires/i.test(result))
+        throw new Error(result);
+    return result;
+}
+async function main() {
+    switch (command) {
+        case 'auto':
+            return setMode('auto');
+        case 'manual':
+            return setMode('manual');
+        case 'upload':
+            return requireSuccess(await upload());
+        case 'repo':
+            if (!args[0])
+                throw new Error('usage: opencode-conversation-archiver repo <absolute path or ~/path>');
+            return setRepo(args[0]);
+        case 'status':
+            return status();
+        case 'doctor':
+            return doctor();
+        case 'connect':
+            return requireSuccess(await connect(args[0] || '', args[1] || '', args[2] || 'opencode'));
+        default:
+            throw new Error([
+                'usage: opencode-conversation-archiver <command>',
+                'commands: auto, manual, upload, repo <path>, status, doctor, connect [link|remote] [token] [subdir]',
+                'backfill and current-session archive are exposed as OpenCode tools because they require the live OpenCode SDK.',
+            ].join('\n'));
+    }
+}
+try {
+    console.log(await main());
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}

package/dist/core.d.ts

@@ -0,0 +1,77 @@
+import type { Message, Part, Session } from '@opencode-ai/sdk';
+export type Mode = 'auto' | 'manual';
+export type BlockRole = 'user' | 'assistant' | 'compact';
+export type Block = {
+    key: string;
+    role: BlockRole;
+    text: string;
+};
+export type Conversation = {
+    session: Session;
+    messages: Array<{
+        info: Message;
+        parts: Part[];
+    }>;
+};
+export type Config = {
+    mode?: Mode;
+    repo?: string;
+    subdir?: string;
+};
+type State = {
+    title: string;
+    file: string | null;
+    start: number;
+    blocks: Block[];
+    machine: {
+        hostname?: string;
+        ip?: string;
+        tmux?: string;
+    };
+    diverted: boolean;
+};
+export type Paths = {
+    app: string;
+    config: string;
+    state: string;
+    index: string;
+    log: string;
+    pushLog: string;
+    credentials: string;
+};
+export declare function defaultPaths(home?: string): Paths;
+export declare function expandHome(path: string, home?: string): string;
+export declare function maskUrl(text: string): string;
+export declare function slugify(value: string): string;
+export declare function extractBlocks(messages: Conversation['messages']): Block[];
+export declare function renderMarkdown(state: State, sessionID: string): string;
+export declare function bodyCovers(oldBody: string, newBody: string): boolean;
+export declare function loadConfig(paths?: Paths): Promise<Config>;
+export declare function saveConfig(config: Config, paths?: Paths): Promise<void>;
+export declare function effectiveRepo(config: Config, home?: string): string;
+export declare function effectiveMode(config: Config): Mode;
+export type GitResult = {
+    status: number;
+    stdout: string;
+    stderr: string;
+};
+export declare function run(repo: string, command: string, args: string[], timeout?: number): Promise<GitResult>;
+export declare function git(repo: string, args: string[], timeout?: number): Promise<GitResult>;
+export declare function push(repo: string, paths?: Paths): Promise<GitResult>;
+export declare function archiveConversation(conversation: Conversation, paths?: Paths, commit?: boolean): Promise<{
+    file: string;
+    turns: number;
+}>;
+export declare function commitPending(paths?: Paths, message?: string): Promise<{
+    repo: string;
+    committed: boolean;
+    error?: string;
+}>;
+export declare function upload(paths?: Paths): Promise<string>;
+export declare function setMode(mode: Mode, paths?: Paths): Promise<string>;
+export declare function setRepo(path: string, paths?: Paths): Promise<string>;
+export declare function status(paths?: Paths): Promise<string>;
+export declare function doctor(paths?: Paths): Promise<string>;
+export declare function connect(remoteUrl: string, token: string, subdir?: string, paths?: Paths): Promise<string>;
+export declare function emitNotification(sessionID: string, title: string, turns: number): Promise<void>;
+export {};