@link-assistant/agent 0.0.8 → 0.0.11

package/EXAMPLES.md

@@ -17,6 +17,7 @@ This document provides practical examples for using each tool with both `@link-a
 ### Simplest Examples - Start Here!
 
 **Plain text (@link-assistant/agent only, easiest!):**
+
 ```bash
 echo "hi" | agent
 ```
@@ -24,11 +25,13 @@ 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
 ```
@@ -49,11 +52,13 @@ 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
 ```
@@ -65,16 +70,19 @@ echo '{"message":"hello world"}' | opencode run --format json --model opencode/g
 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
 ```
@@ -84,11 +92,13 @@ echo '{"message":"list files","tools":[{"name":"bash","params":{"command":"ls -l
 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
 ```
@@ -98,11 +108,13 @@ echo '{"message":"read file","tools":[{"name":"read","params":{"file_path":"/pat
 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
 ```
@@ -112,11 +124,13 @@ echo '{"message":"write file","tools":[{"name":"write","params":{"file_path":"/t
 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
 ```
@@ -126,11 +140,13 @@ echo '{"message":"edit file","tools":[{"name":"edit","params":{"file_path":"/tmp
 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
 ```
@@ -142,6 +158,7 @@ echo '{"message":"list directory","tools":[{"name":"list","params":{"path":"."}}
 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
@@ -151,6 +168,7 @@ echo '{"message":"find ts files","tools":[{"name":"glob","params":{"pattern":"sr
 ```
 
 **opencode:**
+
 ```bash
 echo '{"message":"find js files","tools":[{"name":"glob","params":{"pattern":"**/*.js"}}]}' | opencode run --format json --model opencode/grok-code
 ```
@@ -160,6 +178,7 @@ echo '{"message":"find js files","tools":[{"name":"glob","params":{"pattern":"**
 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
@@ -172,6 +191,7 @@ echo '{"message":"search error","tools":[{"name":"grep","params":{"pattern":"err
 ```
 
 **opencode:**
+
 ```bash
 echo '{"message":"search pattern","tools":[{"name":"grep","params":{"pattern":"TODO","output_mode":"content"}}]}' | opencode run --format json --model opencode/grok-code
 ```
@@ -181,6 +201,7 @@ echo '{"message":"search pattern","tools":[{"name":"grep","params":{"pattern":"T
 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
 
@@ -188,6 +209,7 @@ echo '{"message":"search web","tools":[{"name":"websearch","params":{"query":"Re
 ```
 
 **opencode (requires OPENCODE_EXPERIMENTAL_EXA=true):**
+
 ```bash
 echo '{"message":"search web","tools":[{"name":"websearch","params":{"query":"TypeScript latest features"}}]}' | OPENCODE_EXPERIMENTAL_EXA=true opencode run --format json --model opencode/grok-code
 ```
@@ -197,6 +219,7 @@ echo '{"message":"search web","tools":[{"name":"websearch","params":{"query":"Ty
 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
 
@@ -204,6 +227,7 @@ echo '{"message":"search code","tools":[{"name":"codesearch","params":{"query":"
 ```
 
 **opencode (requires OPENCODE_EXPERIMENTAL_EXA=true):**
+
 ```bash
 echo '{"message":"search code","tools":[{"name":"codesearch","params":{"query":"React hooks implementation"}}]}' | OPENCODE_EXPERIMENTAL_EXA=true opencode run --format json --model opencode/grok-code
 ```
@@ -215,11 +239,13 @@ echo '{"message":"search code","tools":[{"name":"codesearch","params":{"query":"
 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 .opencode
@@ -234,11 +260,13 @@ echo '{"message":"run batch","tools":[{"name":"batch","params":{"tool_calls":[{"
 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
 ```
@@ -250,6 +278,7 @@ echo '{"message":"launch task","tools":[{"name":"task","params":{"description":"
 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
@@ -259,6 +288,7 @@ echo '{"message":"read todos","tools":[{"name":"todoread","params":{}}]}' | agen
 ```
 
 **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
 ```
@@ -268,18 +298,41 @@ echo '{"message":"add todos","tools":[{"name":"todowrite","params":{"todos":[{"c
 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 Event Streaming (Pretty-Printed)
+### 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:
 
@@ -288,6 +341,7 @@ echo "hi" | agent
 ```
 
 Output (pretty-printed JSON events):
+
 ```json
 {
   "type": "step_start",
@@ -322,11 +376,36 @@ Output (pretty-printed JSON events):
 ```
 
 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`:

package/MODELS.md

@@ -1,10 +1,21 @@
 # Models
 
-This agent uses models from the [OpenCode Zen](https://opencode.ai/docs/zen/) subscription service. OpenCode Zen provides access to a wide variety of AI models through a unified API.
+This agent supports multiple model providers. By default, it uses models from the [OpenCode Zen](https://opencode.ai/docs/zen/) subscription service. Additionally, you can use models directly from providers like [Groq](https://groq.com/) by setting the appropriate API key.
+
+## Supported Providers
+
+| Provider     | Format                    | API Key Env Variable         | Documentation                                      |
+| ------------ | ------------------------- | ---------------------------- | -------------------------------------------------- |
+| OpenCode Zen | `opencode/<model-id>`     | N/A (public for free models) | [OpenCode Zen](https://opencode.ai/docs/zen/)      |
+| Anthropic    | `anthropic/<model-id>`    | `ANTHROPIC_API_KEY`          | [Anthropic Docs](https://docs.anthropic.com/)      |
+| Claude OAuth | `claude-oauth/<model-id>` | `CLAUDE_CODE_OAUTH_TOKEN`    | [Claude OAuth Documentation](docs/claude-oauth.md) |
+| Groq         | `groq/<model-id>`         | `GROQ_API_KEY`               | [Groq Documentation](docs/groq.md)                 |
+
+> **Claude OAuth:** The `claude-oauth` provider allows using your Claude Pro/Max subscription. Authenticate with `agent auth claude` or use existing Claude Code CLI credentials with `--use-existing-claude-oauth`.
 
 ## Available Models
 
-All models are accessed using the format `opencode/<model-id>`. Use the `--model` option to specify which model to use:
+All models are accessed using the format `<provider>/<model-id>`. Use the `--model` option to specify which model to use:
 
 ```bash
 echo "hi" | agent --model opencode/grok-code
@@ -14,29 +25,29 @@ echo "hi" | agent --model opencode/grok-code
 
 Below are the prices per 1M tokens for OpenCode Zen models. Models are sorted by output price (lowest first) for best pricing visibility.
 
-| Model | Model ID | Input | Output | Cached Read | Cached Write |
-|-------|----------|-------|--------|-------------|--------------|
-| **Free Models (Output: $0.00)** |
-| Grok Code Fast 1 | `opencode/grok-code` | Free | Free | Free | - |
-| GPT 5 Nano | `opencode/gpt-5-nano` | Free | Free | Free | - |
-| Big Pickle | `opencode/big-pickle` | Free | Free | Free | - |
+| Model                                    | Model ID                    | Input  | Output | Cached Read | Cached Write |
+| ---------------------------------------- | --------------------------- | ------ | ------ | ----------- | ------------ |
+| **Free Models (Output: $0.00)**          |
+| Grok Code Fast 1                         | `opencode/grok-code`        | Free   | Free   | Free        | -            |
+| GPT 5 Nano                               | `opencode/gpt-5-nano`       | Free   | Free   | Free        | -            |
+| Big Pickle                               | `opencode/big-pickle`       | Free   | Free   | Free        | -            |
 | **Paid Models (sorted by output price)** |
-| Qwen3 Coder 480B | `opencode/qwen3-coder-480b` | $0.45 | $1.50 | - | - |
-| GLM 4.6 | `opencode/glm-4-6` | $0.60 | $2.20 | $0.10 | - |
-| Kimi K2 | `opencode/kimi-k2` | $0.60 | $2.50 | $0.36 | - |
-| Claude Haiku 3.5 | `opencode/claude-haiku-3-5` | $0.80 | $4.00 | $0.08 | $1.00 |
-| Claude Haiku 4.5 | `opencode/haiku` | $1.00 | $5.00 | $0.10 | $1.25 |
-| GPT 5.1 | `opencode/gpt-5-1` | $1.25 | $10.00 | $0.125 | - |
-| GPT 5.1 Codex | `opencode/gpt-5-1-codex` | $1.25 | $10.00 | $0.125 | - |
-| GPT 5 | `opencode/gpt-5` | $1.25 | $10.00 | $0.125 | - |
-| GPT 5 Codex | `opencode/gpt-5-codex` | $1.25 | $10.00 | $0.125 | - |
-| Gemini 3 Pro (≤ 200K tokens) | `opencode/gemini-3-pro` | $2.00 | $12.00 | $0.20 | - |
-| Claude Sonnet 4.5 (≤ 200K tokens) | `opencode/sonnet` | $3.00 | $15.00 | $0.30 | $3.75 |
-| Claude Sonnet 4 (≤ 200K tokens) | `opencode/claude-sonnet-4` | $3.00 | $15.00 | $0.30 | $3.75 |
-| Gemini 3 Pro (> 200K tokens) | `opencode/gemini-3-pro` | $4.00 | $18.00 | $0.40 | - |
-| Claude Sonnet 4.5 (> 200K tokens) | `opencode/sonnet` | $6.00 | $22.50 | $0.60 | $7.50 |
-| Claude Sonnet 4 (> 200K tokens) | `opencode/claude-sonnet-4` | $6.00 | $22.50 | $0.60 | $7.50 |
-| Claude Opus 4.1 | `opencode/opus` | $15.00 | $75.00 | $1.50 | $18.75 |
+| Qwen3 Coder 480B                         | `opencode/qwen3-coder-480b` | $0.45  | $1.50  | -           | -            |
+| GLM 4.6                                  | `opencode/glm-4-6`          | $0.60  | $2.20  | $0.10       | -            |
+| Kimi K2                                  | `opencode/kimi-k2`          | $0.60  | $2.50  | $0.36       | -            |
+| Claude Haiku 3.5                         | `opencode/claude-haiku-3-5` | $0.80  | $4.00  | $0.08       | $1.00        |
+| Claude Haiku 4.5                         | `opencode/haiku`            | $1.00  | $5.00  | $0.10       | $1.25        |
+| GPT 5.1                                  | `opencode/gpt-5-1`          | $1.25  | $10.00 | $0.125      | -            |
+| GPT 5.1 Codex                            | `opencode/gpt-5-1-codex`    | $1.25  | $10.00 | $0.125      | -            |
+| GPT 5                                    | `opencode/gpt-5`            | $1.25  | $10.00 | $0.125      | -            |
+| GPT 5 Codex                              | `opencode/gpt-5-codex`      | $1.25  | $10.00 | $0.125      | -            |
+| Gemini 3 Pro (≤ 200K tokens)             | `opencode/gemini-3-pro`     | $2.00  | $12.00 | $0.20       | -            |
+| Claude Sonnet 4.5 (≤ 200K tokens)        | `opencode/sonnet`           | $3.00  | $15.00 | $0.30       | $3.75        |
+| Claude Sonnet 4 (≤ 200K tokens)          | `opencode/claude-sonnet-4`  | $3.00  | $15.00 | $0.30       | $3.75        |
+| Gemini 3 Pro (> 200K tokens)             | `opencode/gemini-3-pro`     | $4.00  | $18.00 | $0.40       | -            |
+| Claude Sonnet 4.5 (> 200K tokens)        | `opencode/sonnet`           | $6.00  | $22.50 | $0.60       | $7.50        |
+| Claude Sonnet 4 (> 200K tokens)          | `opencode/claude-sonnet-4`  | $6.00  | $22.50 | $0.60       | $7.50        |
+| Claude Opus 4.1                          | `opencode/opus`             | $15.00 | $75.00 | $1.50       | $18.75       |
 
 ## Default Model
 
@@ -93,3 +104,40 @@ For complete details about OpenCode Zen subscription and pricing, visit the [Ope
 - Cache pricing applies when using prompt caching features
 - Token context limits vary by model
 - Free models have no token costs but may have rate limits
+
+---
+
+## Groq Provider
+
+[Groq](https://groq.com/) provides ultra-fast inference for open-source large language models. To use Groq models, set your API key:
+
+```bash
+export GROQ_API_KEY=your_api_key_here
+```
+
+### Groq Models
+
+| Model                   | Model ID                       | Context Window | Tool Use |
+| ----------------------- | ------------------------------ | -------------- | -------- |
+| Llama 3.3 70B Versatile | `groq/llama-3.3-70b-versatile` | 131,072 tokens | Yes      |
+| Llama 3.1 8B Instant    | `groq/llama-3.1-8b-instant`    | 131,072 tokens | Yes      |
+| GPT-OSS 120B            | `groq/openai/gpt-oss-120b`     | 131,072 tokens | Yes      |
+| GPT-OSS 20B             | `groq/openai/gpt-oss-20b`      | 131,072 tokens | Yes      |
+| Qwen3 32B               | `groq/qwen/qwen3-32b`          | 131,072 tokens | Yes      |
+| Compound                | `groq/groq/compound`           | 131,072 tokens | Yes      |
+| Compound Mini           | `groq/groq/compound-mini`      | 131,072 tokens | Yes      |
+
+### Groq Usage Examples
+
+```bash
+# Using Llama 3.3 70B (recommended)
+echo "hello" | agent --model groq/llama-3.3-70b-versatile
+
+# Using faster Llama 3.1 8B
+echo "hello" | agent --model groq/llama-3.1-8b-instant
+
+# Using Compound (agentic with server-side tools)
+echo "hello" | agent --model groq/groq/compound
+```
+
+For more details, see the [Groq Documentation](docs/groq.md).