mia-code 0.2.0 → 0.3.0

package/references/acp/session-list.md

@@ -0,0 +1,334 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://agentclientprotocol.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Session List
+
+* Author(s): [@ahmedhesham6](https://github.com/ahmedhesham6)
+* Champion: [@benbrandt](https://github.com/benbrandt)
+
+## Elevator pitch
+
+Add a `session/list` endpoint to the ACP protocol that allows clients to query and enumerate existing sessions from an agent, enabling session management features like session history, session switching, and session cleanup.
+
+## Status quo
+
+Currently, the ACP protocol provides session management through `session/new` and `session/load` endpoints. However, there is no way for clients to:
+
+1. **Discover existing sessions** - Clients cannot query what sessions exist on an agent
+2. **Display session history** - Users cannot see a list of their past conversations
+3. **Manage multiple sessions** - Switching between sessions requires clients to track session IDs themselves
+4. **Clean up old sessions** - No way to discover stale or abandoned sessions for cleanup
+
+This creates several problems:
+
+* **Poor user experience** - Users cannot browse their conversation history or resume previous sessions easily
+* **Client-side complexity** - Each client must implement its own session tracking and persistence
+* **Inconsistent behavior** - Different clients handle session management differently, leading to fragmented experiences
+
+The current workaround is for clients to maintain their own session registry, but this:
+
+* Requires persistent storage on the client side
+* Can get out of sync if sessions are created/destroyed outside the client
+* Doesn't work across different client instances or devices
+* Cannot leverage agent-side session metadata or state
+
+## What we propose to do about it
+
+Add a new `session/list` JSON-RPC method to the protocol that returns metadata about sessions known to the agent. This endpoint would:
+
+1. **Return a list of sessions** with essential metadata:
+   * `sessionId` - Unique identifier
+   * `cwd` - Working directory for the session
+   * `title` - Optional human-readable title (could be auto-generated from first prompt)
+   * `updatedAt` - Timestamp of last update to the session
+   * `_meta` - Optional agent-specific metadata
+2. **Support filtering and pagination**:
+   * Filter by working directory
+   * Agent provides an optional cursor for retrieving the next page of results
+3. **Be an optional capability**:
+   * Agents advertise `sessionCapabilities: { list: {} }` in initialization if they support this feature
+   * Clients check for this capability before attempting to call `session/list`
+   * Agents without persistent session storage don't need to implement this
+
+### JSON-RPC Request
+
+The client calls `session/list` with optional filtering and pagination parameters:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "session/list",
+  "params": {
+    "cwd": "/home/user/project",
+    "cursor": "eyJwYWdlIjogMn0="
+  }
+}
+```
+
+#### Request Parameters
+
+All parameters are optional:
+
+* `cwd` (string) - Filter sessions by working directory
+* `cursor` (string) - Opaque cursor token from a previous response's `nextCursor` field for cursor-based pagination
+
+#### Minimal Request Example
+
+A request with no filters returns all sessions with default sorting:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "session/list",
+  "params": {}
+}
+```
+
+### JSON-RPC Response
+
+The agent responds with a list of sessions and cursor pagination metadata:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": {
+    "sessions": [
+      {
+        "sessionId": "sess_abc123def456",
+        "updatedAt": "2025-10-29T14:22:15Z",
+        "cwd": "/home/user/project",
+        "title": "Implement session list API",
+        "_meta": {
+          "messageCount": 12,
+          "hasErrors": false
+        }
+      },
+      {
+        "sessionId": "sess_xyz789ghi012",
+        "updatedAt": "2025-10-28T16:45:30Z",
+        "cwd": "/home/user/another-project",
+        "title": "Debug authentication flow"
+      },
+      {
+        "sessionId": "sess_uvw345rst678",
+        "updatedAt": "2025-10-27T15:30:00Z",
+        "cwd": "/home/user/project"
+      }
+    ],
+    "nextCursor": "eyJwYWdlIjogM30="
+  }
+}
+```
+
+#### Response Fields
+
+**Response object:**
+
+* `sessions` (array) - Array of session information objects
+* `nextCursor` (string, optional) - Opaque cursor token. If present, pass this in the next request's `cursor` parameter to fetch the next page. If absent, there are no more results.
+
+**SessionInfo object:**
+
+* `sessionId` (string, required) - Unique identifier for the session
+* `cwd` (string, required) - Working directory for the session
+* `title` (string, optional) - Human-readable title (may be auto-generated from first prompt)
+* `updatedAt` (string, optional) - ISO 8601 timestamp of last activity
+* `_meta` (object, optional) - Agent-specific metadata (e.g., message count, error status, tags)
+
+#### Empty Result Example
+
+When no sessions match the criteria:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": {
+    "sessions": []
+  }
+}
+```
+
+## Shiny future
+
+Once this feature exists:
+
+1. **Clients can build session browsers** - Users can view a list of all their conversations, sorted by recency or relevance
+2. **Session switching becomes seamless** - Users can easily switch between ongoing conversations
+3. **Better resource management** - Clients can identify and clean up old or inactive sessions
+4. **Cross-device continuity** - Users could potentially access their sessions from different devices (if agent supports it)
+5. **Improved UX patterns**:
+   * "Recent conversations" sidebar
+   * Search through past sessions
+   * Archive/delete old sessions
+   * Resume interrupted work easily
+
+Agents that implement this feature gain:
+
+* Better visibility into active sessions
+* Opportunity to implement session lifecycle policies
+* Foundation for future features like session sharing or collaboration
+
+## Implementation details and plan
+
+### Phase 1: Core Protocol Changes
+
+1. **Update schema.json** to add:
+   * `session/list` method definition
+   * `ListSessionsRequest` and `ListSessionsResponse` types
+   * `SessionInfo` type
+   * `sessionCapabilities/list` capability flag
+
+2. **Update protocol documentation** in `/docs/protocol/session-setup.mdx`:
+   * Document the new endpoint
+   * Explain when to use it vs. maintaining client-side session tracking
+   * Provide examples of common use cases
+
+### Phase 2: Reference Implementation
+
+3. **Implement in Rust SDK** (`src/agent.rs` and `src/client.rs`):
+   * Add `list_sessions` method to agent trait
+   * Provide default implementation (empty list) for agents without persistence
+   * Add client method to call `session/list`
+
+4. **Add to TypeScript SDKs** (if applicable):
+   * Update TypeScript types
+   * Add client methods
+
+### Phase 3: Example Implementation
+
+5. **Create example agent** that demonstrates:
+   * In-memory session registry
+   * Automatic title generation from first prompt
+   * Session lifecycle management (cleanup after N days)
+   * Pagination and filtering
+
+### Compatibility Considerations
+
+* **Backward compatible**: Existing agents continue working without implementing this
+* **Capability-based**: Clients check for `listSessions` capability before using
+* **No breaking changes**: No modifications to existing endpoints
+
+### Security Considerations
+
+* **Session isolation**: Agents must ensure sessions are only listed for the authenticated client
+* **Resource limits**: Agents should enforce reasonable page sizes internally to prevent abuse
+
+## Frequently asked questions
+
+### What alternative approaches did you consider, and why did you settle on this one?
+
+Several alternatives were considered:
+
+1. **Client-side session tracking only** - This is the current approach, but it has limitations:
+   * Doesn't work across devices
+   * Can get out of sync
+   * Adds complexity to every client implementation
+
+2. **Session events/notifications** - Push notifications when sessions are created/destroyed:
+   * More complex to implement
+   * Requires long-lived connections
+   * Still requires client-side state management
+   * Better suited as a future enhancement, not a replacement
+
+3. **File-based session manifest** - Agent writes session list to a file that clients read:
+   * Couples agent and client file system access
+   * Doesn't work for remote agents
+   * No standard format
+
+The proposed RPC approach is:
+
+* **Consistent with existing protocol design** - Uses same RPC patterns as other endpoints
+* **Flexible** - Supports filtering, pagination, and agent-specific metadata
+* **Optional** - Agents can opt-in based on their architecture
+* **Simple** - Single request/response pattern, easy to implement and use
+
+### Why not make this mandatory for all agents?
+
+Many agents may not have persistent storage or multi-session capabilities. Making this optional:
+
+* Allows simple, stateless agents to remain compliant
+* Reduces implementation burden
+* Lets agents evolve session management over time
+
+### How does this interact with `session/load`?
+
+`session/load` remains the mechanism to actually restore a session. `session/list` is for discovery only:
+
+1. Client calls `session/list` to get available sessions
+2. User selects a session
+3. Client calls `session/load` with the chosen `sessionId`
+
+Agents may support `session/list` without supporting `session/load` (e.g., for read-only session browsing).
+
+### Should we include session content in the list response?
+
+No, for several reasons:
+
+* **Performance** - Full conversation history could be large
+* **Privacy** - Listing sessions might be less sensitive than exposing full content
+* **Separation of concerns** - Use `session/load` to get full session content
+
+### What about session deletion?
+
+Session deletion is intentionally left out of this RFD to keep scope focused. A future `session/delete` endpoint could be proposed separately. For now, agents can implement their own lifecycle policies.
+
+### How should pagination work for large session lists?
+
+We use cursor-based pagination:
+
+* Request includes an optional `cursor`
+* Response includes `nextCursor` when more results are available
+* Clients should treat a missing `nextCursor` as the end of results
+* Clients MUST treat cursors as opaque tokens: don't parse, modify, or persist them across sessions
+* The cursor MUST be a string; never send a raw JSON object as the cursor
+* Servers SHOULD provide stable cursors and handle invalid cursors gracefully
+
+Good request example:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "session/list",
+  "params": {
+    "cwd": "/home/user/project",
+    "createdAfter": "2025-10-20T00:00:00Z",
+    "cursor": "eyJwYWdlIjogMn0=",
+    "search": "auth"
+  }
+}
+```
+
+Corresponding response example:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": {
+    "sessions": [
+      /* ... */
+    ],
+    "nextCursor": "eyJwYWdlIjogM30="
+  }
+}
+```
+
+## Revision history
+
+* **2025-10-29**: Initial draft proposal
+* **2025-10-30**: Update to use `_meta` field for agent-specific metadata
+* **2025-10-30**: Switch from offset-based to cursor-based pagination using continuation tokens
+* **2025-10-30**: Rename `lastAccessedAt` to `updatedAt` for consistency
+* **2025-10-30**: Remove `preview` field from SessionInfo (out of scope)
+* **2025-10-30**: Remove session orphaning from problem statement
+* **2025-10-30**: Replace `sortBy`/`sortOrder` with `search` parameter; remove `total` count from response
+* **2025-10-31**: Update pagination: `continuationToken` → `cursor`, `nextContinuationToken` → `nextCursor`, remove `hasMore`
+* **2025-11-11**: Remove `createdAt`, `updatedAt`, and `search` filters from the request parameters
+* **2025-11-23**: Remove `limit` parameter from request; make `createdAt` and `updatedAt` optional in SessionInfo
+* **2025-11-24**: Update capabilities schema, consolidate to single `updatedAt` timestamp

package/references/acp/session-modes.md

@@ -0,0 +1,170 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://agentclientprotocol.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Session Modes
+
+> Switch between different agent operating modes
+
+Agents can provide a set of modes they can operate in. Modes often affect the system prompts used, the availability of tools, and whether they request permission before running.
+
+## Initial state
+
+During [Session Setup](./session-setup) the Agent **MAY** return a list of modes it can operate in and the currently active mode:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "sessionId": "sess_abc123def456",
+    "modes": {
+      "currentModeId": "ask",
+      "availableModes": [
+        {
+          "id": "ask",
+          "name": "Ask",
+          "description": "Request permission before making any changes"
+        },
+        {
+          "id": "architect",
+          "name": "Architect",
+          "description": "Design and plan software systems without implementation"
+        },
+        {
+          "id": "code",
+          "name": "Code",
+          "description": "Write and modify code with full tool access"
+        }
+      ]
+    }
+  }
+}
+```
+
+<ResponseField name="modes" type="SessionModeState">
+  The current mode state for the session
+</ResponseField>
+
+### SessionModeState
+
+<ResponseField name="currentModeId" type="SessionModeId" required>
+  The ID of the mode that is currently active
+</ResponseField>
+
+<ResponseField name="availableModes" type="SessionMode[]" required>
+  The set of modes that the Agent can operate in
+</ResponseField>
+
+### SessionMode
+
+<ResponseField name="id" type="SessionModeId" required>
+  Unique identifier for this mode
+</ResponseField>
+
+<ResponseField name="name" type="string" required>
+  Human-readable name of the mode
+</ResponseField>
+
+<ResponseField name="description" type="string">
+  Optional description providing more details about what this mode does
+</ResponseField>
+
+## Setting the current mode
+
+The current mode can be changed at any point during a session, whether the Agent is idle or generating a response.
+
+### From the Client
+
+Typically, Clients display the available modes to the user and allow them to change the current one, which they can do by calling the [`session/set_mode`](./schema#session%2Fset-mode) method.
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "session/set_mode",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "modeId": "code"
+  }
+}
+```
+
+<ParamField path="sessionId" type="SessionId" required>
+  The ID of the session to set the mode for
+</ParamField>
+
+<ParamField path="modeId" type="SessionModeId" required>
+  The ID of the mode to switch to. Must be one of the modes listed in
+  `availableModes`
+</ParamField>
+
+### From the Agent
+
+The Agent can also change its own mode and let the Client know by sending the `current_mode_update` session notification:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "method": "session/update",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "update": {
+      "sessionUpdate": "current_mode_update",
+      "modeId": "code"
+    }
+  }
+}
+```
+
+#### Exiting plan modes
+
+A common case where an Agent might switch modes is from within a special "exit mode" tool that can be provided to the language model during plan/architect modes. The language model can call this tool when it determines it's ready to start implementing a solution.
+
+This "switch mode" tool will usually request permission before running, which it can do just like any other tool:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "session/request_permission",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "toolCall": {
+      "toolCallId": "call_switch_mode_001",
+      "title": "Ready for implementation",
+      "kind": "switch_mode",
+      "status": "pending",
+      "content": [
+        {
+          "type": "text",
+          "text": "## Implementation Plan..."
+        }
+      ]
+    },
+    "options": [
+      {
+        "optionId": "code",
+        "name": "Yes, and auto-accept all actions",
+        "kind": "allow_always"
+      },
+      {
+        "optionId": "ask",
+        "name": "Yes, and manually accept actions",
+        "kind": "allow_once"
+      },
+      {
+        "optionId": "reject",
+        "name": "No, stay in architect mode",
+        "kind": "reject_once"
+      }
+    ]
+  }
+}
+```
+
+When an option is chosen, the tool runs, setting the mode and sending the `current_mode_update` notification mentioned above.
+
+<Card icon="shield-check" horizontal href="./tool-calls#requesting-permission">
+  Learn more about permission requests
+</Card>

package/references/acp/slash-commands.md

@@ -0,0 +1,99 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://agentclientprotocol.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Slash Commands
+
+> Advertise available slash commands to clients
+
+Agents can advertise a set of slash commands that users can invoke. These commands provide quick access to specific agent capabilities and workflows. Commands are run as part of regular [prompt](./prompt-turn) requests where the Client includes the command text in the prompt.
+
+## Advertising commands
+
+After creating a session, the Agent **MAY** send a list of available commands via the `available_commands_update` session notification:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "method": "session/update",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "update": {
+      "sessionUpdate": "available_commands_update",
+      "availableCommands": [
+        {
+          "name": "web",
+          "description": "Search the web for information",
+          "input": {
+            "hint": "query to search for"
+          }
+        },
+        {
+          "name": "test",
+          "description": "Run tests for the current project"
+        },
+        {
+          "name": "plan",
+          "description": "Create a detailed implementation plan",
+          "input": {
+            "hint": "description of what to plan"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+<ResponseField name="availableCommands" type="AvailableCommand[]">
+  The list of commands available in this session
+</ResponseField>
+
+### AvailableCommand
+
+<ResponseField name="name" type="string" required>
+  The command name (e.g., "web", "test", "plan")
+</ResponseField>
+
+<ResponseField name="description" type="string" required>
+  Human-readable description of what the command does
+</ResponseField>
+
+<ResponseField name="input" type="AvailableCommandInput">
+  Optional input specification for the command
+</ResponseField>
+
+### AvailableCommandInput
+
+Currently supports unstructured text input:
+
+<ResponseField name="hint" type="string" required>
+  A hint to display when the input hasn't been provided yet
+</ResponseField>
+
+## Dynamic updates
+
+The Agent can update the list of available commands at any time during a session by sending another `available_commands_update` notification. This allows commands to be added based on context, removed when no longer relevant, or modified with updated descriptions.
+
+## Running commands
+
+Commands are included as regular user messages in prompt requests:
+
+```json  theme={null}
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "session/prompt",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "prompt": [
+      {
+        "type": "text",
+        "text": "/web agent client protocol"
+      }
+    ]
+  }
+}
+```
+
+The Agent recognizes the command prefix and processes it accordingly. Commands may be accompanied by any other user message content types (images, audio, etc.) in the same prompt array.