mia-code 0.2.0 → 0.3.0

package/references/acp/terminals.md

@@ -0,0 +1,281 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://agentclientprotocol.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Terminals
+
+> Executing and managing terminal commands
+
+The terminal methods allow Agents to execute shell commands within the Client's environment. These methods enable Agents to run build processes, execute scripts, and interact with command-line tools while providing real-time output streaming and process control.
+
+## Checking Support
+
+Before attempting to use terminal methods, Agents **MUST** verify that the Client supports this capability by checking the [Client Capabilities](./initialization#client-capabilities) field in the `initialize` response:
+
+```json highlight={7} theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 0,
+  "result": {
+    "protocolVersion": 1,
+    "clientCapabilities": {
+      "terminal": true
+    }
+  }
+}
+```
+
+If `terminal` is `false` or not present, the Agent **MUST NOT** attempt to call any terminal methods.
+
+## Executing Commands
+
+The `terminal/create` method starts a command in a new terminal:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 5,
+  "method": "terminal/create",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "command": "npm",
+    "args": ["test", "--coverage"],
+    "env": [
+      {
+        "name": "NODE_ENV",
+        "value": "test"
+      }
+    ],
+    "cwd": "/home/user/project",
+    "outputByteLimit": 1048576
+  }
+}
+```
+
+<ParamField path="sessionId" type="SessionId" required>
+  The [Session ID](./session-setup#session-id) for this request
+</ParamField>
+
+<ParamField path="command" type="string" required>
+  The command to execute
+</ParamField>
+
+<ParamField path="args" type="string[]">
+  Array of command arguments
+</ParamField>
+
+<ParamField path="env" type="EnvVariable[]">
+  Environment variables for the command.
+
+  Each variable has:
+
+  * `name`: The environment variable name
+  * `value`: The environment variable value
+</ParamField>
+
+<ParamField path="cwd" type="string">
+  Working directory for the command (absolute path)
+</ParamField>
+
+<ParamField path="outputByteLimit" type="number">
+  Maximum number of output bytes to retain. Once exceeded, earlier output is
+  truncated to stay within this limit.
+
+  When the limit is exceeded, the Client truncates from the beginning of the output
+  to stay within the limit.
+
+  The Client **MUST** ensure truncation happens at a character boundary to maintain valid
+  string output, even if this means the retained output is slightly less than the
+  specified limit.
+</ParamField>
+
+The Client returns a Terminal ID immediately without waiting for completion:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 5,
+  "result": {
+    "terminalId": "term_xyz789"
+  }
+}
+```
+
+This allows the command to run in the background while the Agent performs other operations.
+
+After creating the terminal, the Agent can use the `terminal/wait_for_exit` method to wait for the command to complete.
+
+<Note>
+  The Agent **MUST** release the terminal using `terminal/release` when it's no
+  longer needed.
+</Note>
+
+## Embedding in Tool Calls
+
+Terminals can be embedded directly in [tool calls](./tool-calls) to provide real-time output to users:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "method": "session/update",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "update": {
+      "sessionUpdate": "tool_call",
+      "toolCallId": "call_002",
+      "title": "Running tests",
+      "kind": "execute",
+      "status": "in_progress",
+      "content": [
+        {
+          "type": "terminal",
+          "terminalId": "term_xyz789"
+        }
+      ]
+    }
+  }
+}
+```
+
+When a terminal is embedded in a tool call, the Client displays live output as it's generated and continues to display it even after the terminal is released.
+
+## Getting Output
+
+The `terminal/output` method retrieves the current terminal output without waiting for the command to complete:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 6,
+  "method": "terminal/output",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "terminalId": "term_xyz789"
+  }
+}
+```
+
+The Client responds with the current output and exit status (if the command has finished):
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 6,
+  "result": {
+    "output": "Running tests...\n✓ All tests passed (42 total)\n",
+    "truncated": false,
+    "exitStatus": {
+      "exitCode": 0,
+      "signal": null
+    }
+  }
+}
+```
+
+<ResponseField name="output" type="string" required>
+  The terminal output captured so far
+</ResponseField>
+
+<ResponseField name="truncated" type="boolean" required>
+  Whether the output was truncated due to byte limits
+</ResponseField>
+
+<ResponseField name="exitStatus" type="TerminalExitStatus">
+  Present only if the command has exited. Contains:
+
+  * `exitCode`: The process exit code (may be null)
+  * `signal`: The signal that terminated the process (may be null)
+</ResponseField>
+
+## Waiting for Exit
+
+The `terminal/wait_for_exit` method returns once the command completes:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 7,
+  "method": "terminal/wait_for_exit",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "terminalId": "term_xyz789"
+  }
+}
+```
+
+The Client responds once the command exits:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 7,
+  "result": {
+    "exitCode": 0,
+    "signal": null
+  }
+}
+```
+
+<ResponseField name="exitCode" type="number">
+  The process exit code (may be null if terminated by signal)
+</ResponseField>
+
+<ResponseField name="signal" type="string">
+  The signal that terminated the process (may be null if exited normally)
+</ResponseField>
+
+## Killing Commands
+
+The `terminal/kill` method terminates a command without releasing the terminal:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 8,
+  "method": "terminal/kill",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "terminalId": "term_xyz789"
+  }
+}
+```
+
+After killing a command, the terminal remains valid and can be used with:
+
+* `terminal/output` to get the final output
+* `terminal/wait_for_exit` to get the exit status
+
+The Agent **MUST** still call `terminal/release` when it's done using it.
+
+### Building a Timeout
+
+Agents can implement command timeouts by combining terminal methods:
+
+1. Create a terminal with `terminal/create`
+2. Start a timer for the desired timeout duration
+3. Concurrently wait for either the timer to expire or `terminal/wait_for_exit` to return
+4. If the timer expires first:
+   * Call `terminal/kill` to terminate the command
+   * Call `terminal/output` to retrieve any final output
+   * Include the output in the response to the model
+5. Call `terminal/release` when done
+
+## Releasing Terminals
+
+The `terminal/release` kills the command if still running and releases all resources:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 9,
+  "method": "terminal/release",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "terminalId": "term_xyz789"
+  }
+}
+```
+
+After release the terminal ID becomes invalid for all other `terminal/*` methods.
+
+If the terminal was added to a tool call, the client **SHOULD** continue to display its output after release.

package/references/acp/tool-calls.md

@@ -0,0 +1,311 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://agentclientprotocol.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Tool Calls
+
+> How Agents report tool call execution
+
+Tool calls represent actions that language models request Agents to perform during a [prompt turn](./prompt-turn). When an LLM determines it needs to interact with external systems—like reading files, running code, or fetching data—it generates tool calls that the Agent executes on its behalf.
+
+Agents report tool calls through [`session/update`](./prompt-turn#3-agent-reports-output) notifications, allowing Clients to display real-time progress and results to users.
+
+While Agents handle the actual execution, they may leverage Client capabilities like [permission requests](#requesting-permission) or [file system access](./file-system) to provide a richer, more integrated experience.
+
+## Creating
+
+When the language model requests a tool invocation, the Agent **SHOULD** report it to the Client:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "method": "session/update",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "update": {
+      "sessionUpdate": "tool_call",
+      "toolCallId": "call_001",
+      "title": "Reading configuration file",
+      "kind": "read",
+      "status": "pending"
+    }
+  }
+}
+```
+
+<ParamField path="toolCallId" type="ToolCallId" required>
+  A unique identifier for this tool call within the session
+</ParamField>
+
+<ParamField path="title" type="string" required>
+  A human-readable title describing what the tool is doing
+</ParamField>
+
+<ParamField path="kind" type="ToolKind">
+  The category of tool being invoked.
+
+  <Expandable title="kinds">
+    * `read` - Reading files or data - `edit` - Modifying files or content -
+      `delete` - Removing files or data - `move` - Moving or renaming files -
+      `search` - Searching for information - `execute` - Running commands or code -
+      `think` - Internal reasoning or planning - `fetch` - Retrieving external data
+    * `other` - Other tool types (default)
+  </Expandable>
+
+  Tool kinds help Clients choose appropriate icons and optimize how they display tool execution progress.
+</ParamField>
+
+<ParamField path="status" type="ToolCallStatus">
+  The current [execution status](#status) (defaults to `pending`)
+</ParamField>
+
+<ParamField path="content" type="ToolCallContent[]">
+  [Content produced](#content) by the tool call
+</ParamField>
+
+<ParamField path="locations" type="ToolCallLocation[]">
+  [File locations](#following-the-agent) affected by this tool call
+</ParamField>
+
+<ParamField path="rawInput" type="object">
+  The raw input parameters sent to the tool
+</ParamField>
+
+<ParamField path="rawOutput" type="object">
+  The raw output returned by the tool
+</ParamField>
+
+## Updating
+
+As tools execute, Agents send updates to report progress and results.
+
+Updates use the `session/update` notification with `tool_call_update`:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "method": "session/update",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "update": {
+      "sessionUpdate": "tool_call_update",
+      "toolCallId": "call_001",
+      "status": "in_progress",
+      "content": [
+        {
+          "type": "content",
+          "content": {
+            "type": "text",
+            "text": "Found 3 configuration files..."
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+All fields except `toolCallId` are optional in updates. Only the fields being changed need to be included.
+
+## Requesting Permission
+
+The Agent **MAY** request permission from the user before executing a tool call by calling the `session/request_permission` method:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 5,
+  "method": "session/request_permission",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "toolCall": {
+      "toolCallId": "call_001"
+    },
+    "options": [
+      {
+        "optionId": "allow-once",
+        "name": "Allow once",
+        "kind": "allow_once"
+      },
+      {
+        "optionId": "reject-once",
+        "name": "Reject",
+        "kind": "reject_once"
+      }
+    ]
+  }
+}
+```
+
+<ParamField path="sessionId" type="SessionId" required>
+  The session ID for this request
+</ParamField>
+
+<ParamField path="toolCall" type="ToolCallUpdate" required>
+  The tool call update containing details about the operation
+</ParamField>
+
+<ParamField path="options" type="PermissionOption[]" required>
+  Available [permission options](#permission-options) for the user to choose
+  from
+</ParamField>
+
+The Client responds with the user's decision:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 5,
+  "result": {
+    "outcome": {
+      "outcome": "selected",
+      "optionId": "allow-once"
+    }
+  }
+}
+```
+
+Clients **MAY** automatically allow or reject permission requests according to the user settings.
+
+If the current prompt turn gets [cancelled](./prompt-turn#cancellation), the Client **MUST** respond with the `"cancelled"` outcome:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 5,
+  "result": {
+    "outcome": {
+      "outcome": "cancelled"
+    }
+  }
+}
+```
+
+<ResponseField name="outcome" type="RequestPermissionOutcome" required>
+  The user's decision, either: - `cancelled` - The [prompt turn was
+  cancelled](./prompt-turn#cancellation) - `selected` with an `optionId` - The
+  ID of the selected permission option
+</ResponseField>
+
+### Permission Options
+
+Each permission option provided to the Client contains:
+
+<ParamField path="optionId" type="string" required>
+  Unique identifier for this option
+</ParamField>
+
+<ParamField path="name" type="string" required>
+  Human-readable label to display to the user
+</ParamField>
+
+<ParamField path="kind" type="PermissionOptionKind" required>
+  A hint to help Clients choose appropriate icons and UI treatment for each option.
+
+  * `allow_once` - Allow this operation only this time
+  * `allow_always` - Allow this operation and remember the choice
+  * `reject_once` - Reject this operation only this time
+  * `reject_always` - Reject this operation and remember the choice
+</ParamField>
+
+## Status
+
+Tool calls progress through different statuses during their lifecycle:
+
+<ResponseField name="pending">
+  The tool call hasn't started running yet because the input is either streaming
+  or awaiting approval
+</ResponseField>
+
+<ResponseField name="in_progress">
+  The tool call is currently running
+</ResponseField>
+
+<ResponseField name="completed">
+  The tool call completed successfully
+</ResponseField>
+
+<ResponseField name="failed">The tool call failed with an error</ResponseField>
+
+## Content
+
+Tool calls can produce different types of content:
+
+### Regular Content
+
+Standard [content blocks](./content) like text, images, or resources:
+
+```json  theme={null}
+{
+  "type": "content",
+  "content": {
+    "type": "text",
+    "text": "Analysis complete. Found 3 issues."
+  }
+}
+```
+
+### Diffs
+
+File modifications shown as diffs:
+
+```json  theme={null}
+{
+  "type": "diff",
+  "path": "/home/user/project/src/config.json",
+  "oldText": "{\n  \"debug\": false\n}",
+  "newText": "{\n  \"debug\": true\n}"
+}
+```
+
+<ParamField path="path" type="string" required>
+  The absolute file path being modified
+</ParamField>
+
+<ParamField path="oldText" type="string">
+  The original content (null for new files)
+</ParamField>
+
+<ParamField path="newText" type="string" required>
+  The new content after modification
+</ParamField>
+
+### Terminals
+
+Live terminal output from command execution:
+
+```json  theme={null}
+{
+  "type": "terminal",
+  "terminalId": "term_xyz789"
+}
+```
+
+<ParamField path="terminalId" type="string" required>
+  The ID of a terminal created with `terminal/create`
+</ParamField>
+
+When a terminal is embedded in a tool call, the Client displays live output as it's generated and continues to display it even after the terminal is released.
+
+<Card icon="terminal" horizontal href="./terminals">
+  Learn more about Terminals
+</Card>
+
+## Following the Agent
+
+Tool calls can report file locations they're working with, enabling Clients to implement "follow-along" features that track which files the Agent is accessing or modifying in real-time.
+
+```json  theme={null}
+{
+  "path": "/home/user/project/src/main.py",
+  "line": 42
+}
+```
+
+<ParamField path="path" type="string" required>
+  The absolute file path being accessed or modified
+</ParamField>
+
+<ParamField path="line" type="number">
+  Optional line number within the file
+</ParamField>

package/references/acp/typescript.md

@@ -0,0 +1,29 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://agentclientprotocol.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# TypeScript
+
+> TypeScript library for the Agent Client Protocol
+
+The [@agentclientprotocol/sdk](https://www.npmjs.com/package/@agentclientprotocol/sdk) npm
+package provides implementations of both sides of the Agent Client Protocol that
+you can use to build your own agent server or client.
+
+To get started, add the package as a dependency to your project:
+
+```bash  theme={null}
+npm install @agentclientprotocol/sdk
+```
+
+Depending on what kind of tool you're building, you'll need to use either the
+[AgentSideConnection](https://agentclientprotocol.github.io/typescript-sdk/classes/AgentSideConnection.html)
+class or the
+[ClientSideConnection](https://agentclientprotocol.github.io/typescript-sdk/classes/ClientSideConnection.html)
+class to establish communication with the ACP counterpart.
+
+You can find example implementations of both sides in the [main repository](https://github.com/agentclientprotocol/typescript-sdk/tree/main/src/examples). These can be run from your terminal or from an ACP Client like [Zed](https://zed.dev), making them great starting points for your own integration!
+
+Browse the [TypeScript library reference](https://agentclientprotocol.github.io/typescript-sdk) for detailed API documentation.
+
+For a complete, production-ready implementation of an ACP agent, check out [Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/zed-integration/zedIntegration.ts).