@link-assistant/agent 0.7.0 → 0.8.2

package/src/session/message-v2.ts

@@ -42,6 +42,22 @@ export namespace MessageV2 {
   );
   export type APIError = z.infer<typeof APIError.Schema>;
 
+  /**
+   * Socket connection error - typically caused by Bun's 10-second idle timeout
+   * in Bun.serve() context. These errors are transient and should be retried.
+   * See: https://github.com/oven-sh/bun/issues/14439
+   */
+  export const SocketConnectionError = NamedError.create(
+    'SocketConnectionError',
+    z.object({
+      message: z.string(),
+      isRetryable: z.literal(true),
+    })
+  );
+  export type SocketConnectionError = z.infer<
+    typeof SocketConnectionError.Schema
+  >;
+
   const PartBase = z.object({
     id: z.string(),
     sessionID: z.string(),
@@ -787,11 +803,24 @@ export namespace MessageV2 {
           },
           { cause: e }
         ).toObject();
-      case e instanceof Error:
+      case e instanceof Error: {
+        const message = e.message || e.toString();
+        // Detect Bun socket connection errors (known Bun issue with 10s idle timeout)
+        // See: https://github.com/oven-sh/bun/issues/14439
+        const isSocketError =
+          message.includes('socket connection was closed') ||
+          message.includes('closed unexpectedly');
+        if (isSocketError) {
+          return new MessageV2.SocketConnectionError(
+            { message, isRetryable: true },
+            { cause: e }
+          ).toObject();
+        }
         return new NamedError.Unknown(
           { message: e.toString() },
           { cause: e }
         ).toObject();
+      }
       default:
         return new NamedError.Unknown(
           { message: JSON.stringify(e) },

package/src/session/processor.ts

@@ -314,9 +314,28 @@ export namespace SessionProcessor {
             const error = MessageV2.fromError(e, {
               providerID: input.providerID,
             });
-            if (error?.name === 'APIError' && error.data.isRetryable) {
+
+            // Check if error is retryable (APIError or SocketConnectionError)
+            const isRetryableAPIError =
+              error?.name === 'APIError' && error.data.isRetryable;
+            const isRetryableSocketError =
+              error?.name === 'SocketConnectionError' &&
+              error.data.isRetryable &&
+              attempt < SessionRetry.SOCKET_ERROR_MAX_RETRIES;
+
+            if (isRetryableAPIError || isRetryableSocketError) {
               attempt++;
-              const delay = SessionRetry.delay(error, attempt);
+              // Use socket-specific delay for socket errors
+              const delay =
+                error?.name === 'SocketConnectionError'
+                  ? SessionRetry.socketErrorDelay(attempt)
+                  : SessionRetry.delay(error, attempt);
+              log.info(() => ({
+                message: 'retrying',
+                errorType: error?.name,
+                attempt,
+                delay,
+              }));
               SessionStatus.set(input.sessionID, {
                 type: 'retry',
                 attempt,

package/src/session/prompt.ts

@@ -34,6 +34,7 @@ import { mergeDeep, pipe } from 'remeda';
 import { ToolRegistry } from '../tool/registry';
 import { Wildcard } from '../util/wildcard';
 import { MCP } from '../mcp';
+import { withTimeout } from '../util/timeout';
 import { ReadTool } from '../tool/read';
 import { ListTool } from '../tool/ls';
 import { FileTime } from '../file/time';
@@ -877,7 +878,28 @@ export namespace SessionPrompt {
       const execute = item.execute;
       if (!execute) continue;
       item.execute = async (args, opts) => {
-        const result = await execute(args, opts);
+        // Get timeout for this specific tool
+        const timeout = await MCP.getToolTimeout(key);
+
+        // Wrap the execute call with timeout to prevent indefinite hangs
+        let result;
+        try {
+          result = await withTimeout(execute(args, opts), timeout);
+        } catch (error) {
+          // Check if it's a timeout error
+          if (
+            error instanceof Error &&
+            error.message.includes('timed out after')
+          ) {
+            const timeoutSec = Math.round(timeout / 1000);
+            throw new Error(
+              `MCP tool "${key}" timed out after ${timeoutSec} seconds. ` +
+                `The operation did not complete within the configured timeout. ` +
+                `You can increase the timeout in the MCP server configuration using tool_call_timeout or tool_timeouts.`
+            );
+          }
+          throw error;
+        }
 
         const textParts: string[] = [];
         const attachments: MessageV2.FilePart[] = [];

package/src/session/retry.ts

@@ -6,6 +6,13 @@ export namespace SessionRetry {
   export const RETRY_BACKOFF_FACTOR = 2;
   export const RETRY_MAX_DELAY_NO_HEADERS = 30_000; // 30 seconds
 
+  // Socket connection error retry configuration
+  // Bun's fetch() has a known 10-second idle timeout issue
+  // See: https://github.com/oven-sh/bun/issues/14439
+  export const SOCKET_ERROR_MAX_RETRIES = 3;
+  export const SOCKET_ERROR_INITIAL_DELAY = 1000; // 1 second
+  export const SOCKET_ERROR_BACKOFF_FACTOR = 2;
+
   export async function sleep(ms: number, signal: AbortSignal): Promise<void> {
     return new Promise((resolve, reject) => {
       const timeout = setTimeout(resolve, ms);
@@ -53,4 +60,15 @@ export namespace SessionRetry {
       RETRY_MAX_DELAY_NO_HEADERS
     );
   }
+
+  /**
+   * Calculate delay for socket connection error retries.
+   * Uses exponential backoff: 1s, 2s, 4s, etc.
+   */
+  export function socketErrorDelay(attempt: number): number {
+    return (
+      SOCKET_ERROR_INITIAL_DELAY *
+      Math.pow(SOCKET_ERROR_BACKOFF_FACTOR, attempt - 1)
+    );
+  }
 }

package/EXAMPLES.md

@@ -1,462 +0,0 @@
-# Usage Examples
-
-This document provides practical examples for using each tool with both `@link-assistant/agent` and `opencode` commands.
-
-> ⚠️ **Bun-only** - `@link-assistant/agent` requires [Bun](https://bun.sh) and does NOT support Node.js or Deno.
-
-## Table of Contents
-
-- [Basic Usage](#basic-usage)
-- [File Operations](#file-operations)
-- [Search Tools](#search-tools)
-- [Execution Tools](#execution-tools)
-- [Utility Tools](#utility-tools)
-
-## Basic Usage
-
-### Simplest Examples - Start Here!
-
-**Plain text (@link-assistant/agent only, easiest!):**
-
-```bash
-echo "hi" | agent
-```
-
-**Simple JSON message (both @link-assistant/agent and opencode):**
-
-@link-assistant/agent:
-
-```bash
-echo '{"message":"hi"}' | agent
-```
-
-opencode:
-
-```bash
-echo '{"message":"hi"}' | opencode run --format json --model opencode/grok-code
-```
-
-### Plain Text Input (@link-assistant/agent only)
-
-```bash
-# Simple message
-echo "hello world" | agent
-
-# Ask a question
-echo "what is TypeScript?" | agent
-
-# Request web search
-echo "search the web for latest React news" | agent
-```
-
-### JSON Input Examples
-
-**@link-assistant/agent:**
-
-```bash
-echo '{"message":"hello world"}' | agent
-```
-
-**opencode:**
-
-```bash
-echo '{"message":"hello world"}' | opencode run --format json --model opencode/grok-code
-```
-
-## File Operations
-
-### bash Tool
-
-Execute shell commands.
-
-**@link-assistant/agent:**
-
-```bash
-echo '{"message":"run command","tools":[{"name":"bash","params":{"command":"echo hello world"}}]}' | agent
-```
-
-**opencode:**
-
-```bash
-echo '{"message":"run command","tools":[{"name":"bash","params":{"command":"echo hello world"}}]}' | opencode run --format json --model opencode/grok-code
-```
-
-**Example with description:**
-
-```bash
-echo '{"message":"list files","tools":[{"name":"bash","params":{"command":"ls -la","description":"List all files in current directory"}}]}' | agent
-```
-
-### read Tool
-
-Read file contents.
-
-**@link-assistant/agent:**
-
-```bash
-echo '{"message":"read file","tools":[{"name":"read","params":{"file_path":"/path/to/file.txt"}}]}' | agent
-```
-
-**opencode:**
-
-```bash
-echo '{"message":"read file","tools":[{"name":"read","params":{"file_path":"/path/to/file.txt"}}]}' | opencode run --format json --model opencode/grok-code
-```
-
-### write Tool
-
-Write content to a file.
-
-**@link-assistant/agent:**
-
-```bash
-echo '{"message":"write file","tools":[{"name":"write","params":{"file_path":"/tmp/test.txt","content":"Hello World"}}]}' | agent
-```
-
-**opencode:**
-
-```bash
-echo '{"message":"write file","tools":[{"name":"write","params":{"file_path":"/tmp/test.txt","content":"Hello World"}}]}' | opencode run --format json --model opencode/grok-code
-```
-
-### edit Tool
-
-Edit file with string replacement.
-
-**@link-assistant/agent:**
-
-```bash
-echo '{"message":"edit file","tools":[{"name":"edit","params":{"file_path":"/tmp/test.txt","old_string":"Hello","new_string":"Hi"}}]}' | agent
-```
-
-**opencode:**
-
-```bash
-echo '{"message":"edit file","tools":[{"name":"edit","params":{"file_path":"/tmp/test.txt","old_string":"Hello","new_string":"Hi"}}]}' | opencode run --format json --model opencode/grok-code
-```
-
-### list Tool
-
-List directory contents.
-
-**@link-assistant/agent:**
-
-```bash
-echo '{"message":"list directory","tools":[{"name":"list","params":{"path":"."}}]}' | agent
-```
-
-**opencode:**
-
-```bash
-echo '{"message":"list directory","tools":[{"name":"list","params":{"path":"."}}]}' | opencode run --format json --model opencode/grok-code
-```
-
-## Search Tools
-
-### glob Tool
-
-Find files using glob patterns.
-
-**@link-assistant/agent:**
-
-```bash
-# Find all JavaScript files
-echo '{"message":"find js files","tools":[{"name":"glob","params":{"pattern":"**/*.js"}}]}' | agent
-
-# Find TypeScript files in src directory
-echo '{"message":"find ts files","tools":[{"name":"glob","params":{"pattern":"src/**/*.ts"}}]}' | agent
-```
-
-**opencode:**
-
-```bash
-echo '{"message":"find js files","tools":[{"name":"glob","params":{"pattern":"**/*.js"}}]}' | opencode run --format json --model opencode/grok-code
-```
-
-### grep Tool
-
-Search text in files with regex.
-
-**@link-assistant/agent:**
-
-```bash
-# Search for pattern in files
-echo '{"message":"search pattern","tools":[{"name":"grep","params":{"pattern":"function","output_mode":"files_with_matches"}}]}' | agent
-
-# Search with content display
-echo '{"message":"search TODO","tools":[{"name":"grep","params":{"pattern":"TODO","output_mode":"content"}}]}' | agent
-
-# Case-insensitive search in JavaScript files
-echo '{"message":"search error","tools":[{"name":"grep","params":{"pattern":"error","-i":true,"type":"js","output_mode":"content"}}]}' | agent
-```
-
-**opencode:**
-
-```bash
-echo '{"message":"search pattern","tools":[{"name":"grep","params":{"pattern":"TODO","output_mode":"content"}}]}' | opencode run --format json --model opencode/grok-code
-```
-
-### websearch Tool
-
-Search the web using Exa API.
-
-**@link-assistant/agent (no environment variable needed!):**
-
-```bash
-echo '{"message":"search web","tools":[{"name":"websearch","params":{"query":"TypeScript latest features"}}]}' | agent
-
-echo '{"message":"search web","tools":[{"name":"websearch","params":{"query":"React hooks best practices"}}]}' | agent
-```
-
-**opencode (requires OPENCODE_EXPERIMENTAL_EXA=true):**
-
-```bash
-echo '{"message":"search web","tools":[{"name":"websearch","params":{"query":"TypeScript latest features"}}]}' | opencode run --format json --model opencode/grok-code
-```
-
-### codesearch Tool
-
-Search code repositories and documentation.
-
-**@link-assistant/agent (no environment variable needed!):**
-
-```bash
-echo '{"message":"search code","tools":[{"name":"codesearch","params":{"query":"React hooks implementation"}}]}' | agent
-
-echo '{"message":"search code","tools":[{"name":"codesearch","params":{"query":"async/await patterns"}}]}' | agent
-```
-
-**opencode (requires OPENCODE_EXPERIMENTAL_EXA=true):**
-
-```bash
-echo '{"message":"search code","tools":[{"name":"codesearch","params":{"query":"React hooks implementation"}}]}' | opencode run --format json --model opencode/grok-code
-```
-
-## Execution Tools
-
-### batch Tool
-
-Batch multiple tool calls together for optimal performance.
-
-**@link-assistant/agent (no configuration needed!):**
-
-```bash
-echo '{"message":"run batch","tools":[{"name":"batch","params":{"tool_calls":[{"tool":"bash","parameters":{"command":"echo hello"}},{"tool":"bash","parameters":{"command":"echo world"}}]}}]}' | agent
-```
-
-**opencode (requires experimental config):**
-
-```bash
-# Create config file first
-mkdir -p .link-assistant-agent
-echo '{"experimental":{"batch_tool":true}}' > .link-assistant-agent/opencode.json
-
-# Then run
-echo '{"message":"run batch","tools":[{"name":"batch","params":{"tool_calls":[{"tool":"bash","parameters":{"command":"echo hello"}},{"tool":"bash","parameters":{"command":"echo world"}}]}}]}' | opencode run --format json --model opencode/grok-code
-```
-
-### task Tool
-
-Launch specialized agents for complex tasks.
-
-**@link-assistant/agent:**
-
-```bash
-echo '{"message":"launch task","tools":[{"name":"task","params":{"description":"Analyze codebase","prompt":"Find all TODO comments in JavaScript files","subagent_type":"general-purpose"}}]}' | agent
-```
-
-**opencode:**
-
-```bash
-echo '{"message":"launch task","tools":[{"name":"task","params":{"description":"Analyze codebase","prompt":"Find all TODO comments in JavaScript files","subagent_type":"general-purpose"}}]}' | opencode run --format json --model opencode/grok-code
-```
-
-## Utility Tools
-
-### todo Tool
-
-Read and write TODO items for task tracking.
-
-**@link-assistant/agent:**
-
-```bash
-# Write todos
-echo '{"message":"add todos","tools":[{"name":"todowrite","params":{"todos":[{"content":"Implement feature X","status":"pending","activeForm":"Implementing feature X"},{"content":"Write tests","status":"pending","activeForm":"Writing tests"}]}}]}' | agent
-
-# Read todos
-echo '{"message":"read todos","tools":[{"name":"todoread","params":{}}]}' | agent
-```
-
-**opencode:**
-
-```bash
-echo '{"message":"add todos","tools":[{"name":"todowrite","params":{"todos":[{"content":"Implement feature X","status":"pending","activeForm":"Implementing feature X"}]}}]}' | opencode run --format json --model opencode/grok-code
-```
-
-### webfetch Tool
-
-Fetch and process web content.
-
-**@link-assistant/agent:**
-
-```bash
-echo '{"message":"fetch url","tools":[{"name":"webfetch","params":{"url":"https://example.com","prompt":"Summarize the content"}}]}' | agent
-```
-
-**opencode:**
-
-```bash
-echo '{"message":"fetch url","tools":[{"name":"webfetch","params":{"url":"https://example.com","prompt":"Summarize the content"}}]}' | opencode run --format json --model opencode/grok-code
-```
-
-## Output Format
-
-### JSON Standards
-
-@link-assistant/agent supports two JSON output format standards via the `--json-standard` option:
-
-#### OpenCode Standard (default)
-
-```bash
-# Default - same as --json-standard opencode
-echo "hi" | agent
-
-# Explicit opencode standard
-echo "hi" | agent --json-standard opencode
-```
-
-#### Claude Standard (experimental)
-
-```bash
-# Claude CLI compatible format (NDJSON)
-echo "hi" | agent --json-standard claude
-```
-
-### JSON Event Streaming (Pretty-Printed) - OpenCode Standard
-
-@link-assistant/agent outputs JSON events in pretty-printed streaming format for easy readability, 100% compatible with OpenCode's event structure:
-
-```bash
-echo "hi" | agent
-```
-
-Output (pretty-printed JSON events):
-
-```json
-{
-  "type": "step_start",
-  "timestamp": 1763618628840,
-  "sessionID": "ses_560236487ffe3ROK1ThWvPwTEF",
-  "part": {
-    "id": "prt_a9fdca4e8001APEs6AriJx67me",
-    "type": "step-start",
-    ...
-  }
-}
-{
-  "type": "text",
-  "timestamp": 1763618629886,
-  "sessionID": "ses_560236487ffe3ROK1ThWvPwTEF",
-  "part": {
-    "type": "text",
-    "text": "Hi! How can I help with your coding tasks today?",
-    ...
-  }
-}
-{
-  "type": "step_finish",
-  "timestamp": 1763618629916,
-  "sessionID": "ses_560236487ffe3ROK1ThWvPwTEF",
-  "part": {
-    "type": "step-finish",
-    "reason": "stop",
-    ...
-  }
-}
-```
-
-This format is designed for:
-
-- **Readability**: Pretty-printed JSON is easy to read and debug
-- **Streaming**: Events output in real-time as they occur
-- **Compatibility**: 100% compatible with OpenCode's event structure
-- **Automation**: Can be parsed using standard JSON tools (see filtering examples below)
-
-### Claude Stream-JSON Output (NDJSON)
-
-When using `--json-standard claude`, output is in NDJSON (Newline-Delimited JSON) format, compatible with Claude CLI:
-
-```bash
-echo "hi" | agent --json-standard claude
-```
-
-Output (compact NDJSON):
-
-```json
-{"type":"init","timestamp":"2025-01-01T00:00:00.000Z","session_id":"ses_560236487ffe3ROK1ThWvPwTEF"}
-{"type":"message","timestamp":"2025-01-01T00:00:01.000Z","session_id":"ses_560236487ffe3ROK1ThWvPwTEF","role":"assistant","content":[{"type":"text","text":"Hi! How can I help with your coding tasks today?"}]}
-{"type":"result","timestamp":"2025-01-01T00:00:01.100Z","session_id":"ses_560236487ffe3ROK1ThWvPwTEF","status":"success","duration_ms":1100}
-```
-
-Key differences from OpenCode format:
-
-- **Compact**: One JSON per line (no pretty-printing)
-- **Event Types**: `init`, `message`, `tool_use`, `tool_result`, `result`
-- **Timestamps**: ISO 8601 strings instead of Unix milliseconds
-- **Session ID**: `session_id` (snake_case) instead of `sessionID` (camelCase)
-- **Content**: Message content in array format with `{type, text}` objects
-
-### Filtering Output
-
-Extract specific event types using `jq`:
-
-```bash
-# Get only text responses
-echo '{"message":"hello"}' | agent | jq -r 'select(.type=="text") | .part.text'
-
-# Get tool use events
-echo '{"message":"run","tools":[{"name":"bash","params":{"command":"ls"}}]}' | agent | jq 'select(.type=="tool_use")'
-
-# Get bash tool output
-echo '{"message":"run","tools":[{"name":"bash","params":{"command":"echo test"}}]}' | agent | jq -r 'select(.type=="tool_use" and .part.tool=="bash") | .part.state.output'
-
-# Pretty print all events
-echo "hello" | agent | jq
-```
-
-## Tips
-
-### @link-assistant/agent Advantages
-
-1. **No Configuration**: WebSearch, CodeSearch, and Batch tools work without any setup
-2. **Plain Text Input**: Can use simple text instead of JSON
-3. **Always Enabled**: All tools available by default
-4. **Bun-only**: Optimized for Bun runtime (no Node.js/Deno overhead)
-
-### Working with JSON
-
-Use single quotes for the outer shell command and double quotes inside JSON:
-
-```bash
-echo '{"message":"test","tools":[{"name":"bash","params":{"command":"echo hello"}}]}' | agent
-```
-
-### Debugging
-
-Add `| jq` to prettify JSON output:
-
-```bash
-echo "hello" | agent | jq
-```
-
-### Chaining Commands
-
-Process output with standard Unix tools:
-
-```bash
-# Count events
-echo "hello" | agent | wc -l
-
-# Filter and format
-echo "hello" | agent | jq -r 'select(.type=="text") | .part.text'
-```

package/LICENSE

@@ -1,24 +0,0 @@
-This is free and unencumbered software released into the public domain.
-
-Anyone is free to copy, modify, publish, use, compile, sell, or
-distribute this software, either in source code form or as a compiled
-binary, for any purpose, commercial or non-commercial, and by any
-means.
-
-In jurisdictions that recognize copyright laws, the author or authors
-of this software dedicate any and all copyright interest in the
-software to the public domain. We make this dedication for the benefit
-of the public at large and to the detriment of our heirs and
-successors. We intend this dedication to be an overt act of
-relinquishment in perpetuity of all present and future rights to this
-software under copyright law.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
-OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
-
-For more information, please refer to <https://unlicense.org>