acp spec

research/acp/missing-features-spec/15-session-creation-richness.md

@@ -0,0 +1,107 @@
+# Feature 15: Session Creation Richness
+
+**Implementation approach:** Check existing extensions — most already implemented
+
+## Summary
+
+v1 `CreateSessionRequest` had `mcp` (full MCP server config with OAuth, env headers, bearer tokens), `skills` (sources with git refs), `agent_version`, `directory`. v2 needs to support these at session creation time.
+
+## Current v2 State — MOSTLY IMPLEMENTED
+
+Investigation shows that **most of these are already supported** via `_meta.sandboxagent.dev` passthrough in `session/new`:
+
+| Field | v1 | v2 Status | v2 Mechanism |
+|-------|-----|-----------|-------------|
+| `directory` | `CreateSessionRequest.directory` | **Implemented** | `cwd` parameter extracted from payload |
+| `agent_version` | `CreateSessionRequest.agent_version` | **Implemented** | `_meta.sandboxagent.dev.agentVersionRequested` (stored, forwarded) |
+| `skills` | `CreateSessionRequest.skills` | **Implemented** | `_meta.sandboxagent.dev.skills` (stored, forwarded) |
+| `mcp` | `CreateSessionRequest.mcp` | **Stored but not processed** | `_meta.sandboxagent.dev.mcp` passthrough — stored in `sandbox_meta` but no active MCP server config processing |
+| `title` | (session metadata) | **Implemented** | `_meta.sandboxagent.dev.title` extracted to `MetaSession.title` |
+| `requestedSessionId` | (session alias) | **Implemented** | `_meta.sandboxagent.dev.requestedSessionId` |
+| `model` | `CreateSessionRequest.model` | **Implemented** | `_meta.sandboxagent.dev.model` via `session_model_hint()` |
+| `variant` | `CreateSessionRequest.variant` | **Deferred** | Out of scope in current implementation pass |
+
+### Confirmation from `rfds-vs-extensions.md`
+
+- Skills: "Already extension via `_meta[\"sandboxagent.dev\"].skills` and optional `_sandboxagent/session/set_metadata`"
+- Agent version: "Already extension via `_meta[\"sandboxagent.dev\"].agentVersionRequested`"
+- Requested session ID: "Already extension via `_meta[\"sandboxagent.dev\"].requestedSessionId`"
+
+## v1 Types (for reference)
+
+```rust
+#[derive(Debug, Deserialize, JsonSchema, ToSchema)]
+pub struct CreateSessionRequest {
+    pub agent: String,
+    pub message: String,
+    pub directory: Option<String>,
+    pub variant: Option<String>,
+    pub agent_version: Option<String>,
+    pub mcp: Option<Vec<McpServerConfig>>,
+    pub skills: Option<Vec<SkillSource>>,
+    pub attachments: Option<Vec<MessageAttachment>>,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, ToSchema)]
+pub struct McpServerConfig {
+    pub name: String,
+    pub command: String,
+    pub args: Option<Vec<String>>,
+    pub env: Option<HashMap<String, String>>,
+    pub oauth: Option<McpOAuthConfig>,
+    pub headers: Option<HashMap<String, String>>,
+    pub bearer_token: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, ToSchema)]
+pub struct McpOAuthConfig {
+    pub client_id: String,
+    pub client_secret: Option<String>,
+    pub auth_url: String,
+    pub token_url: String,
+    pub scopes: Option<Vec<String>>,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, ToSchema)]
+pub struct SkillSource {
+    pub name: String,
+    pub source: SkillSourceType,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, ToSchema)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum SkillSourceType {
+    Git { url: String, ref_spec: Option<String> },
+    Local { path: String },
+}
+```
+
+## What Remains
+
+### MCP Server Config Processing
+
+The `mcp` field is stored in `sandbox_meta` but **not actively processed**. To fully support MCP server configuration at session creation:
+
+1. Extract `_meta.sandboxagent.dev.mcp` array from `session/new` params
+2. Forward MCP server configs to the agent process (agent-specific: Claude uses `--mcp-config`, Codex/OpenCode have different mechanisms)
+3. This is complex and agent-specific — may be deferred
+
+### Recommendation
+
+Since most fields are already implemented via `_meta` passthrough:
+- **No new work needed** for `directory`, `agent_version`, `skills`, `title`, `requestedSessionId`, `model`
+- **MCP config processing** is the only gap — evaluate whether the agent processes already handle MCP config from `_meta` or if explicit processing is needed
+- Mark this feature as **largely complete** with MCP as a follow-up
+
+## Files to Modify (if MCP processing is needed)
+
+| File | Change |
+|------|--------|
+| `server/packages/sandbox-agent/src/acp_runtime/mod.rs` | Extract and process `mcp` config from `_meta.sandboxagent.dev.mcp` during session creation |
+| `server/packages/agent-management/src/agents.rs` | Accept MCP config in agent spawn parameters |
+
+## Docs to Update
+
+| Doc | Change |
+|-----|--------|
+| `docs/sdks/typescript.mdx` | Document all supported `_meta.sandboxagent.dev` fields for session creation |