# Session capability facade
This library provides the shared in-process capabilities used by one Kennedy logical session. It composes already-authorized services; it does not authenticate callers, grant launch authority, open provider accounts, or choose application storage roots.
## Construction and access
`LocalServices` is the editable construction bundle:
- `load_fixed_connections: bool`
- `kmap: kcode_kweb_manager::KwebManager`
- `intelligence: kcode_intelligence_router::Intelligence`
- `history: kcode_session_history::SessionHistory`
- `speech_classifier: Arc<kcode_speaker_system::SpeechClassifier>`
- `dev_tools: kcode_dev_tools::Service`
- `agents: kcode_agent_runtime::AgentRuntime`
- `telegram: kcode_telegram_session_coordinator::Service`
`Api::new(services: LocalServices) -> Api` shares the bundle and composes its Kmap capability. Cloning `Api` retains the same underlying capability handles.
Synchronous access operations are:
- `kmap(&self) -> &kcode_kweb_manager::KwebManager`
- `loads_fixed_connections(&self) -> bool`
- `telegram(&self) -> &kcode_telegram_session_coordinator::Service`
- `with_task_board(self, task_board: kcode_task_board::TaskBoard) -> Self`
- `task_board(&self) -> Option<&kcode_task_board::TaskBoard>`
- `agent_runtime(&self) -> kcode_agent_runtime::AgentRuntime`
- `create_history_session(&self, input: kcode_session_history::NewSession) -> anyhow::Result<kcode_session_history::Session>`
- `history_session(&self, metadata: kcode_session_history::chatend::SessionMetadata, provider_model: &str) -> anyhow::Result<kcode_session_history::Session>`
The optional task board is application-selected. `loads_fixed_connections` reports the application-selected context compatibility mode and does not alter graph reads or storage. Accessors perform fixed local work and no I/O; history creation and opening perform the complete filesystem work owned by Session History.
## Kmap operations
- `kmap_node(&self, node_id: &str) -> Result<kcode_kweb_db::Node, ApiError>`
- `kmap_file(&self, object_id: &str) -> Result<kcode_server_object_envelopes::StoredFile, ApiError>`
- `commit_kweb_session(&self, input: kcode_commit_session::CommitRequest) -> Result<kcode_commit_session::CommitReceipt, ApiError>`
- `save_generated_image(&self, bytes: Vec<u8>, file_name: &str, media_type: &str, model: &str) -> Result<String, ApiError>`
These methods delegate once to the composed Session Kmap service. IDs must use canonical syntax. File reads decode and return the complete stored-file envelope. Generated-image storage preserves the existing provenance and returns the canonical object ID. Commit idempotency, atomicity, and receipts remain Kweb-owned. Work is one addressed local operation, linear in complete object, envelope, or request size where applicable. Generated-image encoding may hold the input and encoded envelope together. There are no provider calls, added limits, retries, timeouts, tasks, or truncation.
## Session launch
`launch_session(&self, input: kcode_session_history::LaunchSession) -> Result<kcode_session_history::SessionLaunch, kcode_session_history::Error>` asynchronously forwards the complete typed input to `SessionHistory::launch_session` exactly once.
The caller supplies a stable child-session UUID, RFC 3339 creation time, effective context-token value, JSON channel metadata, ordinary-conversation state, and one complete initial-message payload. Session History owns validation, deterministic command identity, same-process serialization, durable reconciliation, idempotent replay, conflict detection, synchronization, and recovery. The facade does not authorize the launch, start or wait for inference, poll, retry, add a sidecar or callback, truncate data, or impose a cap. Work, memory, and filesystem I/O equal one Session History launch call; no network or provider work is added. The typed Session History error is returned unchanged, so its `ErrorKind` preserves invalid-input, not-found, conflict, and unresolved storage classification without message parsing or an intelligence receipt.
## Intelligence and managed operations
Asynchronous intelligence operations are:
- `search(&self, user_id: &str, request: kcode_intelligence_router::SearchRequest) -> Result<Accounted<SearchResponse>, ApiError>`
- `fetch(&self, user_id: &str, request: kcode_intelligence_router::FetchRequest) -> Result<FetchResponse, ApiError>`
- `transcribe_audio(&self, user_id: &str, model: &str, prompt: &str, bytes: Vec<u8>, filename: String, mime: &str, temperature: Option<f32>, parent_operation_id: uuid::Uuid) -> Result<Accounted<TranscriptionResponse>, ApiError>`
- `annotate_media(&self, user_id: &str, model: &str, prompt: &str, bytes: Vec<u8>, filename: String, mime: &str, parent_operation_id: uuid::Uuid) -> Result<Accounted<AnnotationResponse>, ApiError>`
- `generate_image(&self, user_id: &str, model: &str, prompt: &str, references: Vec<(Vec<u8>, String, String)>, parent_operation_id: uuid::Uuid) -> Result<Accounted<ImageResponse>, ApiError>`
- `extract_document(&self, bytes: Vec<u8>, filename: String, mime: &str) -> Result<DocumentExtraction, ApiError>`
Transcription, annotation, and generation create one descendant operation under `parent_operation_id`. Prompts and complete payloads are forwarded without a facade cap or truncation. Annotation accepts image, audio, or video media; generation references must have image content types. The facade adds fixed request construction and one router call, no retry or timeout, and no provider-completion guarantee. Payload allocation is linear in complete media bytes; provider attempts, network I/O, concurrency, cancellation, and accounting remain router-owned.
Managed operations are:
- `managed_source_execute(&self, session_id: &str, name: &str, arguments: serde_json::Value, objects: Vec<Vec<u8>>) -> Result<kcode_dev_tools::ToolExecution, ApiError>`
- `execute_speech_classification_tool(&self, name: &str, arguments: serde_json::Value) -> Result<String, ApiError>`
- `release_managed_sources(&self, session_id: &str)`
Managed-source execution performs one tool call, then stores each complete returned binary payload once in Kmap and appends every canonical object ID to the returned text; effects can therefore precede a later error. Work, memory, and I/O scale with complete arguments, objects, tool output, and stored payloads. Speech classification performs one blocking classifier task. Release is one best-effort call and logs rather than returns failure. The facade adds no retries, timeout, output cap, or truncation.
## Errors and receipts
`ApiError` implements `Display` and `std::error::Error`. Its public `receipt: Option<Box<kcode_intelligence_router::UsageReceipt>>` preserves a usage receipt when an accounted intelligence operation fails; accounting callers must record it before propagating the error.
Expected Kmap parse, envelope, invalid-input, not-found, and conflict messages remain caller-visible through the leaf service; unexpected Kmap failures remain redacted. Session launch returns the typed Session History error directly, preserving its caller-visible message and `ErrorKind`; storage errors remain redacted by Session History. Intelligence and managed-development errors retain their public messages. Speech validation errors remain caller-visible; task, storage, schema, and corrupt-storage failures are logged and redacted. Only intelligence errors carry usage receipts.