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

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)

#[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