mia-code 0.2.0 → 0.3.0

package/references/acp/initialization.md

@@ -0,0 +1,225 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://agentclientprotocol.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Initialization
+
+> How all Agent Client Protocol connections begin
+
+The Initialization phase allows [Clients](./overview#client) and [Agents](./overview#agent) to negotiate protocol versions, capabilities, and authentication methods.
+
+<br />
+
+```mermaid  theme={null}
+sequenceDiagram
+    participant Client
+    participant Agent
+
+    Note over Client, Agent: Connection established
+    Client->>Agent: initialize
+    Note right of Agent: Negotiate protocol<br/>version & capabilities
+    Agent-->>Client: initialize response
+    Note over Client,Agent: Ready for session setup
+```
+
+<br />
+
+Before a Session can be created, Clients **MUST** initialize the connection by calling the `initialize` method with:
+
+* The latest [protocol version](#protocol-version) supported
+* The [capabilities](#client-capabilities) supported
+
+They **SHOULD** also provide a name and version to the Agent.
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 0,
+  "method": "initialize",
+  "params": {
+    "protocolVersion": 1,
+    "clientCapabilities": {
+      "fs": {
+        "readTextFile": true,
+        "writeTextFile": true
+      },
+      "terminal": true
+    },
+    "clientInfo": {
+      "name": "my-client",
+      "title": "My Client",
+      "version": "1.0.0"
+    }
+  }
+}
+```
+
+The Agent **MUST** respond with the chosen [protocol version](#protocol-version) and the [capabilities](#agent-capabilities) it supports. It **SHOULD** also provide a name and version to the Client as well:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 0,
+  "result": {
+    "protocolVersion": 1,
+    "agentCapabilities": {
+      "loadSession": true,
+      "promptCapabilities": {
+        "image": true,
+        "audio": true,
+        "embeddedContext": true
+      },
+      "mcp": {
+        "http": true,
+        "sse": true
+      }
+    },
+    "agentInfo": {
+      "name": "my-agent",
+      "title": "My Agent",
+      "version": "1.0.0"
+    },
+    "authMethods": []
+  }
+}
+```
+
+## Protocol version
+
+The protocol versions that appear in the `initialize` requests and responses are a single integer that identifies a **MAJOR** protocol version. This version is only incremented when breaking changes are introduced.
+
+Clients and Agents **MUST** agree on a protocol version and act according to its specification.
+
+See [Capabilities](#capabilities) to learn how non-breaking features are introduced.
+
+### Version Negotiation
+
+The `initialize` request **MUST** include the latest protocol version the Client supports.
+
+If the Agent supports the requested version, it **MUST** respond with the same version. Otherwise, the Agent **MUST** respond with the latest version it supports.
+
+If the Client does not support the version specified by the Agent in the `initialize` response, the Client **SHOULD** close the connection and inform the user about it.
+
+## Capabilities
+
+Capabilities describe features supported by the Client and the Agent.
+
+All capabilities included in the `initialize` request are **OPTIONAL**. Clients and Agents **SHOULD** support all possible combinations of their peer's capabilities.
+
+The introduction of new capabilities is not considered a breaking change. Therefore, Clients and Agents **MUST** treat all capabilities omitted in the `initialize` request as **UNSUPPORTED**.
+
+Capabilities are high-level and are not attached to a specific base protocol concept.
+
+Capabilities may specify the availability of protocol methods, notifications, or a subset of their parameters. They may also signal behaviors of the Agent or Client implementation.
+
+Implementations can also [advertise custom capabilities](./extensibility#advertising-custom-capabilities) using the `_meta` field to indicate support for protocol extensions.
+
+### Client Capabilities
+
+The Client **SHOULD** specify whether it supports the following capabilities:
+
+#### File System
+
+<ParamField path="readTextFile" type="boolean">
+  The `fs/read_text_file` method is available.
+</ParamField>
+
+<ParamField path="writeTextFile" type="boolean">
+  The `fs/write_text_file` method is available.
+</ParamField>
+
+<Card icon="file" horizontal href="./file-system">
+  Learn more about File System methods
+</Card>
+
+#### Terminal
+
+<ParamField path="terminal" type="boolean">
+  All `terminal/*` methods are available, allowing the Agent to execute and
+  manage shell commands.
+</ParamField>
+
+<Card icon="terminal" horizontal href="./terminals">
+  Learn more about Terminals
+</Card>
+
+### Agent Capabilities
+
+The Agent **SHOULD** specify whether it supports the following capabilities:
+
+<ResponseField name="loadSession" type="boolean" post={["default: false"]}>
+  The [`session/load`](./session-setup#loading-sessions) method is available.
+</ResponseField>
+
+<ResponseField name="promptCapabilities" type="PromptCapabilities Object">
+  Object indicating the different types of [content](./content) that may be
+  included in `session/prompt` requests.
+</ResponseField>
+
+#### Prompt capabilities
+
+As a baseline, all Agents **MUST** support `ContentBlock::Text` and `ContentBlock::ResourceLink` in `session/prompt` requests.
+
+Optionally, they **MAY** support richer types of [content](./content) by specifying the following capabilities:
+
+<ResponseField name="image" type="boolean" post={["default: false"]}>
+  The prompt may include `ContentBlock::Image`
+</ResponseField>
+
+<ResponseField name="audio" type="boolean" post={["default: false"]}>
+  The prompt may include `ContentBlock::Audio`
+</ResponseField>
+
+<ResponseField name="embeddedContext" type="boolean" post={["default: false"]}>
+  The prompt may include `ContentBlock::Resource`
+</ResponseField>
+
+#### MCP capabilities
+
+<ResponseField name="http" type="boolean" post={["default: false"]}>
+  The Agent supports connecting to MCP servers over HTTP.
+</ResponseField>
+
+<ResponseField name="sse" type="boolean" post={["default: false"]}>
+  The Agent supports connecting to MCP servers over SSE.
+
+  Note: This transport has been deprecated by the MCP spec.
+</ResponseField>
+
+#### Session Capabilities
+
+As a baseline, all Agents **MUST** support `session/new`, `session/prompt`, `session/cancel`, and `session/update`.
+
+Optionally, they **MAY** support other session methods and notifications by specifying additional capabilities.
+
+<Note>
+  `session/load` is still handled by the top-level `load_session` capability.
+  This will be unified in future versions of the protocol.
+</Note>
+
+## Implementation Information
+
+Both Clients and Agents **SHOULD** provide information about their implementation in the `clientInfo` and `agentInfo` fields respectively. Both take the following three fields:
+
+<ParamField path="name" type="string">
+  Intended for programmatic or logical use, but can be used as a display name
+  fallback if title isn’t present.
+</ParamField>
+
+<ParamField path="title" type="string">
+  Intended for UI and end-user contexts — optimized to be human-readable and
+  easily understood. If not provided, the name should be used for display.
+</ParamField>
+
+<ParamField path="version" type="string">
+  Version of the implementation. Can be displayed to the user or used for
+  debugging or metrics purposes.
+</ParamField>
+
+<Info>
+  Note: in future versions of the protocol, this information will be required.
+</Info>
+
+***
+
+Once the connection is initialized, you're ready to [create a session](./session-setup) and begin the conversation with the Agent.

package/references/acp/prompt-turn.md

@@ -0,0 +1,321 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://agentclientprotocol.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Prompt Turn
+
+> Understanding the core conversation flow
+
+A prompt turn represents a complete interaction cycle between the [Client](./overview#client) and [Agent](./overview#agent), starting with a user message and continuing until the Agent completes its response. This may involve multiple exchanges with the language model and tool invocations.
+
+Before sending prompts, Clients **MUST** first complete the [initialization](./initialization) phase and [session setup](./session-setup).
+
+## The Prompt Turn Lifecycle
+
+A prompt turn follows a structured flow that enables rich interactions between the user, Agent, and any connected tools.
+
+<br />
+
+```mermaid  theme={null}
+sequenceDiagram
+    participant Client
+    participant Agent
+
+    Note over Agent,Client: Session ready
+
+    Note left of Client: User sends message
+    Client->>Agent: session/prompt (user message)
+    Note right of Agent: Process with LLM
+
+    loop Until completion
+        Note right of Agent: LLM responds with<br/>content/tool calls
+        Agent->>Client: session/update (plan)
+        Agent->>Client: session/update (agent_message_chunk)
+
+        opt Tool calls requested
+            Agent->>Client: session/update (tool_call)
+            opt Permission required
+                Agent->>Client: session/request_permission
+                Note left of Client: User grants/denies
+                Client-->>Agent: Permission response
+            end
+            Agent->>Client: session/update (tool_call status: in_progress)
+            Note right of Agent: Execute tool
+            Agent->>Client: session/update (tool_call status: completed)
+            Note right of Agent: Send tool results<br/>back to LLM
+        end
+
+      opt User cancelled during execution
+          Note left of Client: User cancels prompt
+          Client->>Agent: session/cancel
+          Note right of Agent: Abort operations
+          Agent-->>Client: session/prompt response (cancelled)
+      end
+    end
+
+    Agent-->>Client: session/prompt response (stopReason)
+
+```
+
+### 1. User Message
+
+The turn begins when the Client sends a `session/prompt`:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "session/prompt",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "prompt": [
+      {
+        "type": "text",
+        "text": "Can you analyze this code for potential issues?"
+      },
+      {
+        "type": "resource",
+        "resource": {
+          "uri": "file:///home/user/project/main.py",
+          "mimeType": "text/x-python",
+          "text": "def process_data(items):\n    for item in items:\n        print(item)"
+        }
+      }
+    ]
+  }
+}
+```
+
+<ParamField path="sessionId" type="SessionId">
+  The [ID](./session-setup#session-id) of the session to send this message to.
+</ParamField>
+
+<ParamField path="prompt" type="ContentBlock[]">
+  The contents of the user message, e.g. text, images, files, etc.
+
+  Clients **MUST** restrict types of content according to the [Prompt Capabilities](./initialization#prompt-capabilities) established during [initialization](./initialization).
+
+  <Card icon="comments" horizontal href="./content">
+    Learn more about Content
+  </Card>
+</ParamField>
+
+### 2. Agent Processing
+
+Upon receiving the prompt request, the Agent processes the user's message and sends it to the language model, which **MAY** respond with text content, tool calls, or both.
+
+### 3. Agent Reports Output
+
+The Agent reports the model's output to the Client via `session/update` notifications. This may include the Agent's plan for accomplishing the task:
+
+```json expandable theme={null}
+{
+  "jsonrpc": "2.0",
+  "method": "session/update",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "update": {
+      "sessionUpdate": "plan",
+      "entries": [
+        {
+          "content": "Check for syntax errors",
+          "priority": "high",
+          "status": "pending"
+        },
+        {
+          "content": "Identify potential type issues",
+          "priority": "medium",
+          "status": "pending"
+        },
+        {
+          "content": "Review error handling patterns",
+          "priority": "medium",
+          "status": "pending"
+        },
+        {
+          "content": "Suggest improvements",
+          "priority": "low",
+          "status": "pending"
+        }
+      ]
+    }
+  }
+}
+```
+
+<Card icon="lightbulb" horizontal href="./agent-plan">
+  Learn more about Agent Plans
+</Card>
+
+The Agent then reports text responses from the model:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "method": "session/update",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "update": {
+      "sessionUpdate": "agent_message_chunk",
+      "content": {
+        "type": "text",
+        "text": "I'll analyze your code for potential issues. Let me examine it..."
+      }
+    }
+  }
+}
+```
+
+If the model requested tool calls, these are also reported immediately:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "method": "session/update",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "update": {
+      "sessionUpdate": "tool_call",
+      "toolCallId": "call_001",
+      "title": "Analyzing Python code",
+      "kind": "other",
+      "status": "pending"
+    }
+  }
+}
+```
+
+### 4. Check for Completion
+
+If there are no pending tool calls, the turn ends and the Agent **MUST** respond to the original `session/prompt` request with a `StopReason`:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": {
+    "stopReason": "end_turn"
+  }
+}
+```
+
+Agents **MAY** stop the turn at any point by returning the corresponding [`StopReason`](#stop-reasons).
+
+### 5. Tool Invocation and Status Reporting
+
+Before proceeding with execution, the Agent **MAY** request permission from the Client via the `session/request_permission` method.
+
+Once permission is granted (if required), the Agent **SHOULD** invoke the tool and report a status update marking the tool as `in_progress`:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "method": "session/update",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "update": {
+      "sessionUpdate": "tool_call_update",
+      "toolCallId": "call_001",
+      "status": "in_progress"
+    }
+  }
+}
+```
+
+As the tool runs, the Agent **MAY** send additional updates, providing real-time feedback about tool execution progress.
+
+While tools execute on the Agent, they **MAY** leverage Client capabilities such as the file system (`fs`) methods to access resources within the Client's environment.
+
+When the tool completes, the Agent sends another update with the final status and any content:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "method": "session/update",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "update": {
+      "sessionUpdate": "tool_call_update",
+      "toolCallId": "call_001",
+      "status": "completed",
+      "content": [
+        {
+          "type": "content",
+          "content": {
+            "type": "text",
+            "text": "Analysis complete:\n- No syntax errors found\n- Consider adding type hints for better clarity\n- The function could benefit from error handling for empty lists"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+<Card icon="hammer" horizontal href="./tool-calls">
+  Learn more about Tool Calls
+</Card>
+
+### 6. Continue Conversation
+
+The Agent sends the tool results back to the language model as another request.
+
+The cycle returns to [step 2](#2-agent-processing), continuing until the language model completes its response without requesting additional tool calls or the turn gets stopped by the Agent or cancelled by the Client.
+
+## Stop Reasons
+
+When an Agent stops a turn, it must specify the corresponding `StopReason`:
+
+<ResponseField name="end_turn">
+  The language model finishes responding without requesting more tools
+</ResponseField>
+
+<ResponseField name="max_tokens">
+  The maximum token limit is reached
+</ResponseField>
+
+<ResponseField name="max_turn_requests">
+  The maximum number of model requests in a single turn is exceeded
+</ResponseField>
+
+<ResponseField name="refusal">The Agent refuses to continue</ResponseField>
+
+<ResponseField name="cancelled">The Client cancels the turn</ResponseField>
+
+## Cancellation
+
+Clients **MAY** cancel an ongoing prompt turn at any time by sending a `session/cancel` notification:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "method": "session/cancel",
+  "params": {
+    "sessionId": "sess_abc123def456"
+  }
+}
+```
+
+The Client **SHOULD** preemptively mark all non-finished tool calls pertaining to the current turn as `cancelled` as soon as it sends the `session/cancel` notification.
+
+The Client **MUST** respond to all pending `session/request_permission` requests with the `cancelled` outcome.
+
+When the Agent receives this notification, it **SHOULD** stop all language model requests and all tool call invocations as soon as possible.
+
+After all ongoing operations have been successfully aborted and pending updates have been sent, the Agent **MUST** respond to the original `session/prompt` request with the `cancelled` [stop reason](#stop-reasons).
+
+<Warning>
+  API client libraries and tools often throw an exception when their operation is aborted, which may propagate as an error response to `session/prompt`.
+
+  Clients often display unrecognized errors from the Agent to the user, which would be undesirable for cancellations as they aren't considered errors.
+
+  Agents **MUST** catch these errors and return the semantically meaningful `cancelled` stop reason, so that Clients can reliably confirm the cancellation.
+</Warning>
+
+The Agent **MAY** send `session/update` notifications with content or tool call updates after receiving the `session/cancel` notification, but it **MUST** ensure that it does so before responding to the `session/prompt` request.
+
+The Client **SHOULD** still accept tool call updates received after sending `session/cancel`.
+
+***
+
+Once a prompt turn completes, the Client may send another `session/prompt` to continue the conversation, building on the context established in previous turns.