@link-assistant/agent 0.7.0 → 0.8.2

package/README.md

@@ -18,11 +18,13 @@
 
 > ⚠️ **Bun-only runtime** - This package requires [Bun](https://bun.sh) and does NOT support Node.js or Deno.
 
+> This is the JavaScript/Bun implementation. See also the [Rust implementation](../rust/README.md).
+
 This is an MVP implementation of an OpenCode-compatible CLI agent, focused on maximum efficiency and unrestricted execution. We reproduce OpenCode's `run --format json --model opencode/grok-code` mode with:
 
 - ✅ **JSON Input/Output**: Compatible with `opencode run --format json --model opencode/grok-code`
 - ✅ **Plain Text Input**: Also accepts plain text messages (auto-converted to JSON format)
-- ✅ **Flexible Model Selection**: Defaults to free OpenCode Zen Grok Code Fast 1, supports [OpenCode Zen](https://opencode.ai/docs/zen/), [Claude OAuth](docs/claude-oauth.md), and [Groq](docs/groq.md) providers
+- ✅ **Flexible Model Selection**: Defaults to free OpenCode Zen Grok Code Fast 1, supports [OpenCode Zen](https://opencode.ai/docs/zen/), [Claude OAuth](../docs/claude-oauth.md), and [Groq](../docs/groq.md) providers
 - ✅ **No Restrictions**: Fully unrestricted file system and command execution access (no sandbox)
 - ✅ **Minimal Footprint**: Built with Bun.sh for maximum efficiency
 - ✅ **Full Tool Support**: 13 tools including websearch, codesearch, batch - all enabled by default
@@ -38,55 +40,12 @@ This is an MVP implementation of an OpenCode-compatible CLI agent, focused on ma
 - ❌ **No External API**: Server runs only internally, not exposed to network
 - ❌ **No ACP**: No Agent Client Protocol support
 
-## Project Vision
-
-We're creating a slimmed-down, public domain version of OpenCode CLI focused on the "agentic run mode" for use in virtual machines, Docker containers, and other environments where unrestricted AI agent access is acceptable. This is **not** for general desktop use - it's for isolated environments where you want maximum AI agent freedom.
-
-**OpenCode Compatibility**: We maintain 100% compatibility with OpenCode's JSON event streaming format, so tools expecting `opencode run --format json --model opencode/grok-code` output will work with our agent-cli.
-
-## Design Choices
-
-### Why Bun-only? No Node.js or Deno support?
-
-This agent is **exclusively built for Bun** for the following reasons:
-
-1. **Faster Development**: No compilation step - direct execution with `bun run`
-2. **Simpler Dependencies**: Fewer dev dependencies, no TypeScript compiler overhead
-3. **Performance**: Bun's fast runtime and native ESM support
-4. **Minimalism**: Single runtime target keeps the codebase simple
-5. **Bun Ecosystem**: Leverages Bun-specific features and optimizations
-
-**Not supporting Node.js or Deno is intentional** to keep the project focused and minimal. If you need Node.js/Deno compatibility, consider using [OpenCode](https://github.com/sst/opencode) instead.
-
-### Architecture: Reproducing OpenCode's JSON Event Streaming
-
-This agent-cli reproduces the core architecture of [OpenCode](https://github.com/sst/opencode)'s `run --format json` command:
-
-- **Streaming JSON Events**: Instead of single responses, outputs real-time event stream
-- **Event Types**: `tool_use`, `text`, `step_start`, `step_finish`, `error`
-- **Session Management**: Each request gets a unique session ID
-- **Tool Execution**: 13 tools with unrestricted access (bash, read, write, edit, list, glob, grep, websearch, codesearch, batch, task, todo, webfetch)
-- **Compatible Format**: Events match OpenCode's JSON schema for interoperability
-
-The agent streams events as they occur, providing the same real-time experience as OpenCode's JSON mode.
-
-## Features
+## Requirements
 
-- **JSON Input/Output**: Accepts JSON via stdin, outputs JSON event streams (OpenCode-compatible)
-- **Plain Text Input**: Also accepts plain text messages (auto-converted to JSON format)
-- **Unrestricted Access**: Full file system and command execution access (no sandbox, no restrictions)
-- **Tool Support**: 13 tools including websearch, codesearch, batch - all enabled by default
-- **Flexible Model Selection**: Defaults to free Grok Code Fast 1, supports [OpenCode Zen](https://opencode.ai/docs/zen/), [Claude OAuth](docs/claude-oauth.md), and [Groq](docs/groq.md) - see [MODELS.md](MODELS.md)
-- **Bun.sh First**: Built with Bun for maximum efficiency and minimal resource usage
-- **No TUI**: Pure JSON CLI interface for automation and integration
-- **Public Domain**: Unlicense - use it however you want
+- [Bun](https://bun.sh) >= 1.0.0 (Node.js and Deno are NOT supported)
 
 ## Installation
 
-**Requirements:**
-
-- [Bun](https://bun.sh) >= 1.0.0 (Node.js and Deno are NOT supported)
-
 ```bash
 # Install Bun first if you haven't already
 curl -fsSL https://bun.sh/install | bash
@@ -177,9 +136,9 @@ agent auth login                                       # Select GitHub Copilot
 echo "hi" | agent --model github-copilot/gpt-4o        # Uses Copilot
 ```
 
-See [MODELS.md](MODELS.md) for complete list of available models and pricing.
-See [docs/groq.md](docs/groq.md) for Groq provider documentation.
-See [docs/claude-oauth.md](docs/claude-oauth.md) for Claude OAuth provider documentation.
+See [MODELS.md](../MODELS.md) for complete list of available models and pricing.
+See [docs/groq.md](../docs/groq.md) for Groq provider documentation.
+See [docs/claude-oauth.md](../docs/claude-oauth.md) for Claude OAuth provider documentation.
 
 ### Direct Prompt Mode
 
@@ -193,7 +152,30 @@ agent -p "What is 2+2?"
 result=$(agent -p "Summarize: $(cat file.txt)")
 ```
 
-### CLI Options
+### Session Resume
+
+Resume or continue previous sessions:
+
+```bash
+# Continue the most recent session (creates a fork with new UUID by default)
+echo "Continue where we left off" | agent --continue
+
+# Short form
+echo "Continue where we left off" | agent -c
+
+# Resume a specific session by ID (creates a fork with new UUID by default)
+echo "Let's continue" | agent --resume ses_abc123xyz
+
+# Continue in the same session without forking
+echo "Keep going" | agent --continue --no-fork
+
+# Resume specific session without forking
+echo "Keep going" | agent --resume ses_abc123xyz --no-fork
+```
+
+**Note**: By default, `--resume` and `--continue` create a new session ID (fork) to preserve the original conversation history. Use `--no-fork` to continue in the same session.
+
+## CLI Options
 
 ```bash
 agent [options]
@@ -222,6 +204,14 @@ Stdin Mode Options:
   --no-always-accept-stdin       Single-message mode - exit after first response
   --compact-json                 Output compact JSON for program-to-program use
 
+Session Resume Options:
+  -r, --resume <sessionID>       Resume a specific session by ID
+                                 By default, forks with a new UUID
+  -c, --continue                 Continue the most recent session
+                                 By default, forks with a new UUID
+  --no-fork                      When used with --resume or --continue,
+                                 continue in the same session without forking
+
   --help                         Show help
   --version                      Show version number
 
@@ -233,7 +223,7 @@ Commands:
   mcp                  MCP server commands
 ```
 
-See [docs/stdin-mode.md](docs/stdin-mode.md) for comprehensive stdin mode documentation.
+See [docs/stdin-mode.md](../docs/stdin-mode.md) for comprehensive stdin mode documentation.
 
 ### JSON Output Standards
 
@@ -289,7 +279,7 @@ echo "your message here" | agent
 
 ## Supported Tools
 
-All 13 tools are **enabled by default** with **no configuration required**. See [TOOLS.md](TOOLS.md) for complete documentation.
+All 13 tools are **enabled by default** with **no configuration required**. See [TOOLS.md](../TOOLS.md) for complete documentation.
 
 ### File Operations
 
@@ -396,7 +386,7 @@ The agent will automatically use the Playwright MCP tools when browser automatio
 
 - [Playwright MCP GitHub Repository](https://github.com/microsoft/playwright-mcp)
 - [Using Playwright MCP with Claude Code](https://til.simonwillison.net/claude-code/playwright-mcp-claude-code)
-- [Playwright MCP Case Study](docs/case-studies/playwright-mcp-support/case-study.md)
+- [Playwright MCP Case Study](../docs/case-studies/playwright-mcp-support/case-study.md)
 
 ### Managing MCP Servers
 
@@ -422,84 +412,6 @@ agent mcp add
 
 The interactive prompt will guide you through configuring local or remote MCP servers.
 
-## Examples
-
-See [EXAMPLES.md](EXAMPLES.md) for detailed usage examples of each tool with both agent-cli and opencode commands.
-
-## Testing
-
-```bash
-# Run all tests
-bun test
-
-# Run specific test file
-bun test tests/mcp.test.js
-bun test tests/websearch.tools.test.js
-bun test tests/batch.tools.test.js
-bun test tests/plaintext.input.test.js
-```
-
-For detailed testing information including how to run tests manually and trigger CI tests, see [TESTING.md](TESTING.md).
-
-## Maintenance
-
-### Development
-
-Run the agent in development mode:
-
-```bash
-bun run dev
-```
-
-Or run directly:
-
-```bash
-bun run src/index.js
-```
-
-### Testing
-
-Simply run:
-
-```bash
-bun test
-```
-
-Bun automatically discovers and runs all `*.test.js` files in the project.
-
-### Test Coverage
-
-- ✅ 13 tool implementation tests
-- ✅ Plain text input support test
-- ✅ OpenCode compatibility tests for websearch/codesearch
-- ✅ JSON standard unit tests (opencode and claude formats)
-- ✅ All tests pass with 100% OpenCode JSON format compatibility
-
-### Publishing
-
-To publish a new version to npm:
-
-1. **Update version** in `package.json`:
-
-   ```bash
-   # Update version field manually (e.g., 0.0.3 -> 0.0.4)
-   ```
-
-2. **Commit changes**:
-
-   ```bash
-   git add .
-   git commit -m "Release v0.0.4"
-   git push
-   ```
-
-3. **Publish to npm**:
-   ```bash
-   npm publish
-   ```
-
-The package publishes source files directly (no build step required). Bun handles TypeScript execution natively.
-
 ## Key Features
 
 ### No Configuration Required
@@ -574,42 +486,132 @@ Output (pretty-printed JSON events):
 }
 ```
 
-## Architecture
+## Development
 
-This agent-cli reproduces OpenCode's `run --format json` command architecture:
+### Running in Development Mode
 
-- **Streaming JSON Events**: Real-time event stream output
-- **Event Types**: `tool_use`, `text`, `step_start`, `step_finish`, `error`
-- **Session Management**: Unique session IDs for each request
-- **Tool Execution**: 13 tools with unrestricted access
-- **Compatible Format**: Events match OpenCode's JSON schema exactly
+```bash
+bun run dev
+```
+
+Or run directly:
+
+```bash
+bun run src/index.js
+```
 
-## Files
+### Testing
 
-- `src/index.js` - Main entry point with JSON/plain text input support
-- `src/session/agent.js` - Agent implementation
-- `src/tool/` - Tool implementations
-- `tests/` - Comprehensive test suite
-- [MODELS.md](MODELS.md) - Available models and pricing
-- [TOOLS.md](TOOLS.md) - Complete tool documentation
-- [EXAMPLES.md](EXAMPLES.md) - Usage examples for each tool
+```bash
+# Run all tests
+bun test
 
-## Reference Implementations
+# Run specific test file
+bun test tests/mcp.test.js
+bun test tests/websearch.tools.test.js
+bun test tests/batch.tools.test.js
+bun test tests/plaintext.input.test.js
+```
 
-This repository includes official reference implementations as git submodules to provide best-in-class examples:
+For detailed testing information including how to run tests manually and trigger CI tests, see [TESTING.md](../TESTING.md).
 
-- **original-opencode** - [OpenCode](https://github.com/sst/opencode) - The original OpenCode implementation we maintain compatibility with
-- **reference-gemini-cookbook** - [Google Gemini Cookbook](https://github.com/google-gemini/cookbook) - Official examples and guides for using the Gemini API
-- **reference-gemini-cli** - [Google Gemini CLI](https://github.com/google-gemini/gemini-cli) - Official AI agent bringing Gemini directly to the terminal
-- **reference-qwen3-coder** - [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder) - Official Qwen3 code model from Alibaba Cloud
+### Test Coverage
 
-To initialize all submodules:
+- ✅ 13 tool implementation tests
+- ✅ Plain text input support test
+- ✅ OpenCode compatibility tests for websearch/codesearch
+- ✅ JSON standard unit tests (opencode and claude formats)
+- ✅ All tests pass with 100% OpenCode JSON format compatibility
+
+### Linting and Formatting
 
 ```bash
-git submodule update --init --recursive
+# Run linting
+bun run lint
+
+# Fix linting issues
+bun run lint:fix
+
+# Format code
+bun run format
+
+# Check formatting
+bun run format:check
 ```
 
-These reference implementations provide valuable insights into different approaches for building AI agents and can serve as learning resources for developers working with this codebase.
+### Publishing
+
+The package uses [Changesets](https://github.com/changesets/changesets) for version management:
+
+1. Create a changeset:
+
+   ```bash
+   bun run changeset
+   ```
+
+2. Version the package:
+
+   ```bash
+   bun run changeset:version
+   ```
+
+3. Publish to npm:
+   ```bash
+   bun run changeset:publish
+   ```
+
+The package publishes source files directly (no build step required). Bun handles TypeScript execution natively.
+
+## Why Bun-only? No Node.js or Deno support?
+
+This agent is **exclusively built for Bun** for the following reasons:
+
+1. **Faster Development**: No compilation step - direct execution with `bun run`
+2. **Simpler Dependencies**: Fewer dev dependencies, no TypeScript compiler overhead
+3. **Performance**: Bun's fast runtime and native ESM support
+4. **Minimalism**: Single runtime target keeps the codebase simple
+5. **Bun Ecosystem**: Leverages Bun-specific features and optimizations
+
+**Not supporting Node.js or Deno is intentional** to keep the project focused and minimal. If you need Node.js/Deno compatibility, consider using [OpenCode](https://github.com/sst/opencode) instead.
+
+## Project Structure
+
+```
+js/
+├── src/           # Source code
+│   ├── index.js   # Main entry point with JSON/plain text input support
+│   ├── session/   # Session management and agent implementation
+│   └── tool/      # Tool implementations
+├── tests/         # Comprehensive test suite
+├── experiments/   # Experimental code
+├── package.json   # npm package configuration
+└── tsconfig.json  # TypeScript configuration
+```
+
+## Architecture
+
+This agent-cli reproduces the core architecture of [OpenCode](https://github.com/sst/opencode)'s `run --format json` command:
+
+- **Streaming JSON Events**: Instead of single responses, outputs real-time event stream
+- **Event Types**: `tool_use`, `text`, `step_start`, `step_finish`, `error`
+- **Session Management**: Each request gets a unique session ID
+- **Tool Execution**: 13 tools with unrestricted access (bash, read, write, edit, list, glob, grep, websearch, codesearch, batch, task, todo, webfetch)
+- **Compatible Format**: Events match OpenCode's JSON schema for interoperability
+
+The agent streams events as they occur, providing the same real-time experience as OpenCode's JSON mode.
+
+## Examples
+
+See [EXAMPLES.md](../EXAMPLES.md) for detailed usage examples of each tool with both agent-cli and opencode commands.
+
+## Documentation
+
+For full documentation, see the [main README](../README.md) in the repository root.
+
+- [Models and Pricing](../MODELS.md)
+- [Tools Reference](../TOOLS.md)
+- [Usage Examples](../EXAMPLES.md)
+- [Testing Guide](../TESTING.md)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/agent",
-  "version": "0.7.0",
+  "version": "0.8.2",
   "description": "A minimal, public domain AI CLI agent compatible with OpenCode's JSON interface. Bun-only runtime.",
   "main": "src/index.js",
   "type": "module",
@@ -14,11 +14,11 @@
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "check:file-size": "node scripts/check-file-size.mjs",
+    "check:file-size": "node ../scripts/check-file-size.mjs",
     "check": "npm run lint && npm run format:check && npm run check:file-size",
-    "prepare": "husky || true",
+    "prepare": "cd .. && husky || true",
     "changeset": "changeset",
-    "changeset:version": "node scripts/changeset-version.mjs",
+    "changeset:version": "node ../scripts/changeset-version.mjs",
     "changeset:publish": "changeset publish",
     "changeset:status": "changeset status --since=origin/main"
   },
@@ -45,10 +45,10 @@
     "src/",
     "package.json",
     "README.md",
-    "MODELS.md",
-    "TOOLS.md",
-    "EXAMPLES.md",
-    "LICENSE"
+    "../MODELS.md",
+    "../TOOLS.md",
+    "../EXAMPLES.md",
+    "../LICENSE"
   ],
   "dependencies": {
     "@actions/core": "^1.11.1",

package/src/cli/continuous-mode.js

@@ -10,6 +10,7 @@ import { Session } from '../session/index.ts';
 import { SessionPrompt } from '../session/prompt.ts';
 import { createEventHandler } from '../json-standard/index.ts';
 import { createContinuousStdinReader } from './input-queue.js';
+import { Log } from '../util/log.ts';
 
 // Shared error tracking
 let hasError = false;
@@ -42,6 +43,155 @@ function outputStatus(status, compact = false) {
   console.error(json);
 }
 
+// Logger for resume operations
+const log = Log.create({ service: 'resume' });
+
+/**
+ * Resolve the session to use based on --resume, --continue, and --no-fork options.
+ * Returns the session ID to use, handling forking as needed.
+ * @param {object} argv - Command line arguments
+ * @param {boolean} compactJson - Whether to use compact JSON output
+ * @returns {Promise<{sessionID: string, wasResumed: boolean, wasForked: boolean} | null>} - Session info or null if new session should be created
+ * @export
+ */
+export async function resolveResumeSession(argv, compactJson) {
+  const resumeSessionID = argv.resume;
+  const shouldContinue = argv.continue === true;
+  const noFork = argv['no-fork'] === true;
+
+  // If neither --resume nor --continue is specified, return null to create new session
+  if (!resumeSessionID && !shouldContinue) {
+    return null;
+  }
+
+  let targetSessionID = resumeSessionID;
+
+  // If --continue is specified, find the most recent session
+  if (shouldContinue && !targetSessionID) {
+    let mostRecentSession = null;
+    let mostRecentTime = 0;
+
+    for await (const session of Session.list()) {
+      // Skip child sessions (those with parentID) - find top-level sessions only
+      if (session.parentID) {
+        continue;
+      }
+
+      if (session.time.updated > mostRecentTime) {
+        mostRecentTime = session.time.updated;
+        mostRecentSession = session;
+      }
+    }
+
+    if (!mostRecentSession) {
+      outputStatus(
+        {
+          type: 'error',
+          errorType: 'SessionNotFound',
+          message:
+            'No existing sessions found to continue. Start a new session first.',
+        },
+        compactJson
+      );
+      process.exit(1);
+    }
+
+    targetSessionID = mostRecentSession.id;
+    log.info(() => ({
+      message: 'Found most recent session to continue',
+      sessionID: targetSessionID,
+      title: mostRecentSession.title,
+    }));
+  }
+
+  // Verify the session exists
+  let existingSession;
+  try {
+    existingSession = await Session.get(targetSessionID);
+  } catch (_error) {
+    // Session.get throws an error when the session doesn't exist
+    outputStatus(
+      {
+        type: 'error',
+        errorType: 'SessionNotFound',
+        message: `Session not found: ${targetSessionID}`,
+      },
+      compactJson
+    );
+    process.exit(1);
+  }
+
+  if (!existingSession) {
+    outputStatus(
+      {
+        type: 'error',
+        errorType: 'SessionNotFound',
+        message: `Session not found: ${targetSessionID}`,
+      },
+      compactJson
+    );
+    process.exit(1);
+  }
+
+  log.info(() => ({
+    message: 'Resuming session',
+    sessionID: targetSessionID,
+    title: existingSession.title,
+    noFork,
+  }));
+
+  // If --no-fork is specified, continue in the same session
+  if (noFork) {
+    outputStatus(
+      {
+        type: 'status',
+        mode: 'resume',
+        message: `Continuing session without forking: ${targetSessionID}`,
+        sessionID: targetSessionID,
+        title: existingSession.title,
+        forked: false,
+      },
+      compactJson
+    );
+
+    return {
+      sessionID: targetSessionID,
+      wasResumed: true,
+      wasForked: false,
+    };
+  }
+
+  // Fork the session to a new UUID (default behavior)
+  const forkedSession = await Session.fork({
+    sessionID: targetSessionID,
+  });
+
+  outputStatus(
+    {
+      type: 'status',
+      mode: 'resume',
+      message: `Forked session ${targetSessionID} to new session: ${forkedSession.id}`,
+      originalSessionID: targetSessionID,
+      sessionID: forkedSession.id,
+      title: forkedSession.title,
+      forked: true,
+    },
+    compactJson
+  );
+
+  log.info(() => ({
+    message: 'Forked session',
+    originalSessionID: targetSessionID,
+    newSessionID: forkedSession.id,
+  }));
+
+  return {
+    sessionID: forkedSession.id,
+    wasResumed: true,
+    wasForked: true,
+  };
+}
+
 /**
  * Run server mode with continuous stdin input
  * Keeps the session alive and processes messages as they arrive
@@ -64,20 +214,30 @@ export async function runContinuousServerMode(
   let stdinReader = null;
 
   try {
-    // Create a session
-    const createRes = await fetch(
-      `http://${server.hostname}:${server.port}/session`,
-      {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      }
-    );
-    const session = await createRes.json();
-    const sessionID = session.id;
+    // Check if we should resume an existing session
+    const resumeInfo = await resolveResumeSession(argv, compactJson);
+
+    let sessionID;
+
+    if (resumeInfo) {
+      // Use the resumed/forked session
+      sessionID = resumeInfo.sessionID;
+    } else {
+      // Create a new session
+      const createRes = await fetch(
+        `http://${server.hostname}:${server.port}/session`,
+        {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({}),
+        }
+      );
+      const session = await createRes.json();
+      sessionID = session.id;
 
-    if (!sessionID) {
-      throw new Error('Failed to create session');
+      if (!sessionID) {
+        throw new Error('Failed to create session');
+      }
     }
 
     // Create event handler for the selected JSON standard
@@ -275,11 +435,21 @@ export async function runContinuousDirectMode(
   let stdinReader = null;
 
   try {
-    // Create a session directly
-    const session = await Session.createNext({
-      directory: process.cwd(),
-    });
-    const sessionID = session.id;
+    // Check if we should resume an existing session
+    const resumeInfo = await resolveResumeSession(argv, compactJson);
+
+    let sessionID;
+
+    if (resumeInfo) {
+      // Use the resumed/forked session
+      sessionID = resumeInfo.sessionID;
+    } else {
+      // Create a new session directly
+      const session = await Session.createNext({
+        directory: process.cwd(),
+      });
+      sessionID = session.id;
+    }
 
     // Create event handler for the selected JSON standard
     const eventHandler = createEventHandler(jsonStandard, sessionID);