# kcode-kennedy-session-services 0.1.2
`kcode-kennedy-session-services` provides the shared in-process capabilities used by a Kennedy logical session.
## Construction
`LocalServices` is the editable construction bundle:
- `kmap: kcode_kweb_manager::KwebManager`
- `intelligence: kcode_intelligence_router::Intelligence`
- `history: kcode_session_history::SessionHistory`
- `speech_classifier: Arc<kcode_speech_classification::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 complete bundle behind an `Arc`. Cloning `Api` retains the same capability handles.
## Operations
Synchronous access and persistence:
- `kmap(&self) -> &kcode_kweb_manager::KwebManager`
- `telegram(&self) -> &kcode_telegram_session_coordinator::Service`
- `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>`
- `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>`
`kmap_file` requires a canonical object ID and decodes the stored file envelope. `save_generated_image` encodes and stores a generated-image object and returns its canonical ID. `commit_kweb_session` delegates the request's idempotency and atomicity semantics to Kweb Manager.
Asynchronous capabilities:
- `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>`
Audio transcription and annotation prompts are forwarded unchanged to the
intelligence router. This facade does not impose a character or byte ceiling.
- `extract_document(&self, bytes: Vec<u8>, filename: String, mime: &str) -> Result<DocumentExtraction, ApiError>`
- `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)`
Transcription, annotation, and image generation create a descendant operation under `parent_operation_id`. Annotation accepts image, audio, or video media; image references must have image content types. `managed_source_execute` stores every returned binary payload in Kmap and appends the resulting canonical object IDs to the returned text; storage can therefore have effects before a later error. `release_managed_sources` is best-effort and logs rather than returns a release failure.
## Errors and receipts
`ApiError` implements `Display` and `std::error::Error`. Its public `receipt: Option<Box<kcode_intelligence_router::UsageReceipt>>` preserves an intelligence usage receipt even when an accounted operation fails; callers responsible for accounting must record that receipt before propagating the error.
Expected Kmap invalid-input, not-found, and conflict messages remain caller-visible; unexpected Kmap failures are redacted. Intelligence and managed-development errors retain their public messages. Speech validation errors remain caller-visible, while task, storage, schema, and corrupt-storage failures are logged and redacted. Only intelligence errors carry usage receipts.