Antikythera MCP Framework v1.0.0

Antikythera MCP Framework is a Rust workspace for building MCP-capable agent runtimes, host-integrated orchestration flows, and portable WASM agent components.

System Overview

flowchart TD
    Host[Host Application] --> CLI[antikythera-cli]
    Host --> SDK[antikythera-sdk]
    CLI --> Core[antikythera-core]
    SDK --> Core
    Core --> Session[antikythera-session]
    Core --> Log[antikythera-log]
    Core --> MCP[MCP Servers]
    Core --> LLM[LLM Providers via Host]

What Is Included in 1.0.0

• Stable workspace crates for CLI, SDK, core runtime, session, and logging.
• Multi-agent orchestration with guardrails, resilience, and observability hooks.
• Streaming support for token/event output and buffered delivery policies.
• WASM component integration path for host-controlled execution.
• Consolidated documentation under documentation/.

Workspace Layout

• antikythera-core: protocol/runtime, orchestration, transport, resilience, streaming.
• antikythera-sdk: high-level API, component-facing integration layer.
• antikythera-cli: interactive and scripted entry binaries.
• antikythera-session: structured session state and export helpers.
• antikythera-log: structured logging and subscriber support.
• tests: integration and module-level validation suites.

Build and Validate

cargo build --workspace
cargo test --workspace
cargo fmt --all -- --check
cargo clippy --workspace --lib --bins -- -D warnings -D deprecated

Documentation Index

• Architecture
• Build
• Config
• Context Management
• Guardrails
• Hooks
• Observability
• Resilience
• Streaming
• Testing
• WASM Agent

Version

• Workspace release: 1.0.0
• Documentation baseline: 1.0.0

Product Scope

This document defines what the Antikythera MCP Framework is, what deployment targets it supports, and what surfaces its public API exposes.

What it is

Antikythera is a Rust-based MCP client framework designed to:

• prepare and process LLM message flows while leaving the actual model API call to the embedding host
• connect to MCP tool servers over STDIO and HTTP transports
• run agent and tool-calling flows with structured step management
• expose agent logic as a portable server-side WASM component (wasm32-wasip1)
• provide a native CLI for interactive and automated use

Deployment targets

No browser WASM, no C FFI, and no embedded HTTP server are provided by the framework. A host that embeds the WASM component is responsible for its own transport layer (REST, gRPC, WebSocket, or custom).

Public SDK surface

The antikythera-sdk crate provides the stable integration surface:

CLI modes

The antikythera binary accepts a --mode flag:

Architecture philosophy

The framework is designed around one principle: the host owns the interface layer.

flowchart LR
    HOST[Host application] --> WASM[WASM component]
    HOST --> LLM[LLM provider]
    HOST --> TOOLS[MCP tool servers]
    HOST --> TRANSPORT[Transport: REST / gRPC / custom]
    WASM --> LOGIC[Agent logic and reasoning loop]

The WASM component handles agent reasoning, session continuity, history shaping, and response parsing. The host handles every external integration: LLM calls, tool execution, persistence, and protocol exposure. This keeps the component portable across runtimes and avoids embedding infrastructure concerns inside the framework.

Feature flags

Related documents

• ARCHITECTURE.md — crate relationships and request flow
• BUILD.md — build commands for each target
• CLI.md — CLI usage reference
• COMPONENT.md — WASM component model details
• WASM_AGENT.md — agent logic inside the component

Workspace

This document explains how the repository is organized and how each crate relates to the others.

Repository map

flowchart TD
    ROOT[antikythera-mcp-framework]
    ROOT --> CORE[antikythera-core]
    ROOT --> SDK[antikythera-sdk]
    ROOT --> CLI[antikythera-cli]
    ROOT --> SESSION[antikythera-session]
    ROOT --> LOG[antikythera-log]
    ROOT --> TESTS[tests]
    ROOT --> SCRIPTS[scripts]
    ROOT --> WIT[wit]
    ROOT --> DOCS[documentation]

Crate responsibilities

Workspace dependency shape

flowchart LR
    CLI[antikythera-cli] --> CORE[antikythera-core]
    CLI --> SDK[antikythera-sdk]
    SDK --> CORE
    SDK --> SESSION[antikythera-session]
    SDK --> LOG[antikythera-log]
    CORE --> LOG
    TESTS[tests] --> CORE
    TESTS --> SDK
    TESTS --> SESSION
    TESTS --> LOG
    SCRIPTS[scripts] --> SDK
    SCRIPTS --> WIT[wit output]

Practical reading order

1. Start with antikythera-core to understand the runtime behavior.
2. Move to antikythera-sdk to see the public API and bindings layer.
3. Check antikythera-cli for the current command-line surface.
4. Use tests/ to see how the repository is exercised end-to-end.

Architecture

This document gives a current high-level view of how the main crates interact.

System view

flowchart TD
    USER[User or host application]
    CLI[antikythera-cli]
    SDK[antikythera-sdk]
    CORE[antikythera-core]
    SESSION[antikythera-session]
    LOG[antikythera-log]
    MCP[MCP servers]
    LLM[LLM providers]

    USER --> CLI
    USER --> SDK
    CLI --> CORE
    CLI --> SDK
    SDK --> CORE
    SDK --> SESSION
    SDK --> LOG
    CORE --> LOG
    CORE --> MCP
    CORE --> LLM

Request flow

sequenceDiagram
    participant User
    participant Surface as CLI or SDK
    participant Core as antikythera-core
    participant Provider as LLM provider
    participant Server as MCP server

    User->>Surface: Send prompt or task
    Surface->>Core: Build request
    Core->>Provider: Generate response
    Provider-->>Core: Model output
    Core->>Server: Tool call if needed
    Server-->>Core: Tool result
    Core-->>Surface: Final response
    Surface-->>User: Output

Crate reading order

• antikythera-core is the main place to understand runtime behavior.
• antikythera-sdk is the best view of the exported integration surface.
• antikythera-cli is the user-facing binary layer over core.

CLI

This guide documents the CLI binaries exposed by antikythera-cli.

Binary map

flowchart LR
    CLI_CRATE[antikythera-cli]
    CLI_CRATE --> MAIN[antikythera]
    CLI_CRATE --> CONFIG[antikythera-config]
    MAIN --> STDIO[mode: stdio]
    MAIN --> SETUP[mode: setup]
    MAIN --> MULTI[mode: multi-agent]
    MAIN --> HARNESS[mode: wasm-harness]
    CONFIG --> PC[app.pc]

Overview

The CLI crate exposes two binaries:

Runtime provider and model selection are owned by the CLI layer. antikythera-core stays model-agnostic and only executes against the runtime client configuration that the CLI has already materialized.

antikythera

Runtime modes

The main binary accepts a --mode flag:

Execution flow

flowchart TD
    START[Run antikythera] --> LOAD[Load app.pc config]
    LOAD --> BUILD[Build McpClient]
    BUILD --> PARSE[Parse --mode]
    PARSE --> STDIO[mode = stdio]
    PARSE --> SETUP[mode = setup]
    PARSE --> MULTI[mode = multi-agent]
    PARSE --> HARNESS[mode = wasm-harness]
    STDIO --> CHAT[Interactive ratatui chat workspace]
    SETUP --> WIZARD[Config wizard menu]
    MULTI --> ORCH[MultiAgentOrchestrator dispatch]
    HARNESS --> WASM[Host-FFI probe over WASM runtime exports]

Interactive TUI UX

The stdio mode now launches a ratatui-based workspace with:

1. A conversation panel that keeps the latest chat and tool trace visible. While a response is in flight it shows a live streaming preview of the incoming tokens (if the provider supports streaming).
2. A context sidebar showing provider, model, session, and configured backends.
3. A prompt box with slash-command recommendations as soon as the input starts with /.
4. Inline commands such as /help, /providers, /use <provider> [model], /model <name>, /config, /tools, /agent, /reset, and /exit.
5. A Settings overlay (press F2) showing the full active config as TOML.
6. A History browser overlay (press F3) listing saved conversations with open / rename / delete actions.
7. A health status dot in the footer that reflects live provider health (green = healthy, yellow = degraded, red = failing).

Use Tab to autocomplete the first command suggestion, Enter to submit, and Esc to quit.

Run it

# Default mode: stdio (interactive chat)
cargo run -p antikythera-cli --bin antikythera

# Explicit mode selection
cargo run -p antikythera-cli --bin antikythera -- --mode stdio
cargo run -p antikythera-cli --bin antikythera -- --mode stdio --provider gemini --model gemini-2.0-flash
cargo run -p antikythera-cli --bin antikythera -- --mode stdio --provider openai --model gpt-4o-mini
cargo run -p antikythera-cli --bin antikythera -- --mode stdio --provider ollama --model llama3.2 --provider-endpoint http://127.0.0.1:11434
cargo run -p antikythera-cli --bin antikythera -- --mode setup
cargo run -p antikythera-cli --bin antikythera -- --mode multi-agent --agents agents.json --task "Write a summary"
cargo run -p antikythera-cli --bin antikythera -- --mode wasm-harness --wasm target/wasm32-wasip1/release/antikythera_sdk.wasm --task "Smoke test"

# Task shortcuts
task run-tui
task run
task run-wasm
task setup-config PROVIDER_ID=openai PROVIDER_TYPE=openai PROVIDER_ENDPOINT=https://api.openai.com PROVIDER_API_KEY=OPENAI_API_KEY MODEL_NAME=gpt-4o-mini

task run now bootstraps app.pc automatically when needed and opens the interactive TUI directly. Change provider/model from inside the TUI with commands such as /use gemini gemini-2.0-flash or /model gpt-4o-mini instead of passing runtime shell arguments.

Common flags

Multi-agent flags

Agent profile JSON format:

[
  {
    "id": "writer",
    "name": "Writer Agent",
    "role": "writer",
    "system_prompt": "You write clear and concise content.",
    "max_steps": 8
  }
]

antikythera-config

What it does

antikythera-config manages the Postcard-based config file shared across all framework surfaces.

Config workflow

flowchart LR
    INIT[init] --> FILE[app.pc]
    FILE --> SHOW[show]
    FILE --> GET[get]
    FILE --> SET[set]
    FILE --> ADD[add-provider]
    FILE --> MODEL[set-model]
    FILE --> EXPORT[export JSON]
    EXPORT --> IMPORT[import JSON]
    FILE --> STATUS[status]

Run it

cargo run -p antikythera-cli --bin antikythera-config -- --help

Available subcommands

Supported fields for get and set

get providers is also supported and returns the provider list as JSON.

Example workflow

# Create default file
cargo run -p antikythera-cli --bin antikythera-config -- init

# Add an OpenAI provider
cargo run -p antikythera-cli --bin antikythera-config -- add-provider openai openai https://api.openai.com OPENAI_API_KEY

# Set the default model
cargo run -p antikythera-cli --bin antikythera-config -- set-model openai gpt-4o-mini

# Check current status
cargo run -p antikythera-cli --bin antikythera-config -- status

Provider limitations

antikythera-config init now seeds provider templates for gemini, openai, and ollama, including their common default endpoints and model presets. add-provider also normalizes aliases such as google-ai -> gemini and localai -> ollama.

API consistency rules

To keep CLI discoverability and public contracts stable:

Deprecated alias map

Current aliases are maintained only for compatibility and are documented in the deprecation policy.

Related documents

• CONFIG.md for the config format and serialization model
• BUILD.md for build commands and component workflows
• PRODUCT_SCOPE.md for deployment targets and feature flags
• DEPRECATION_POLICY.md for deprecation lifecycle and CI enforcement

BUILD

This guide covers the commands that match the current workspace layout and tooling.

Build map

flowchart TD
    SRC[Workspace source] --> CARGO[cargo build --workspace]
    SRC --> CLI[cargo build -p antikythera-cli --release]
    SRC --> WIT[cargo run -p build-scripts --release -- wit]
    WIT --> COMPONENT[cargo component build -p antikythera-sdk --release --target wasm32-wasip1]

What you can build

Prerequisites

• Rust 1.75+
• cargo-component for component builds
• Optional: wasm-tools for inspecting the generated component
• Optional: task for the helpers in Taskfile.yml

Native builds

Build everything

cargo build --workspace

Build release artifacts

cargo build --workspace --release

Build only the CLI crate

cargo build -p antikythera-cli --release

Native binaries

WASM component build

Generate WIT

cargo run -p build-scripts --release -- wit

This generates:

wit/antikythera.wit

Build the WASM component

cargo component build -p antikythera-sdk --release --target wasm32-wasip1 \
  --no-default-features --features component

The helper binary in scripts/build-component.rs also supports:

cargo run -p build-scripts --release -- component
cargo run -p build-scripts --release -- all

Expected component output is produced under:

target/wasm32-wasip1/release/

Canonical artifact name for CI/release packaging:

dist/antikythera-sdk.wasm

CLI harness against WASM

Use the CLI to execute the generated WASM via host runtime bridge (WasmAgentRunner):

cargo run -p antikythera-cli --bin antikythera -- \
    --mode wasm-harness \
    --wasm target/wasm32-wasip1/release/antikythera_sdk.wasm \
    --task "Smoke test"

Optional deterministic host callback payload:

cargo run -p antikythera-cli --bin antikythera -- \
    --mode wasm-harness \
    --wasm target/wasm32-wasip1/release/antikythera_sdk.wasm \
    --wasm-llm-response '{"content":"ok","model":"stub"}'

Docs site build

The repository also includes an mdBook configuration that turns README.md plus the documentation/ folder into a static documentation site.

flowchart LR
    README[README.md] --> SUMMARY[SUMMARY.md]
    DOCS[documentation/*.md] --> SUMMARY
    SUMMARY --> MDBOOK[mdbook build]
    MDBOOK --> SITE[book/]
    SITE --> PAGES[GitHub Pages deployment]

Local commands

# Build static site
mdbook build

# Preview locally
mdbook serve --open

Tests and quality checks

Verification flow

flowchart LR
    CHECK[cargo check --workspace] --> TEST[cargo test --workspace]
    TEST --> FMT[cargo fmt --all]
    FMT --> CLIPPY[cargo clippy --workspace -- -D warnings]

Workspace-wide

cargo test --workspace
cargo fmt --all
cargo clippy --workspace -- -D warnings

Common targeted checks

# SDK library tests
cargo test -p antikythera-sdk --lib

# Check all crates without producing binaries
cargo check --workspace

Taskfile helpers

The repository includes Taskfile.yml for common flows.

GitHub workflows

Feature flags overview

antikythera-core

antikythera-sdk

Notes

• The component build (wasm32-wasip1) is the WASM deployment target. Use it when embedding agent logic in a host application via wasmtime.
• For browser or C FFI targets, implement those in the host application itself — the framework does not provide those bindings.

Component

This document explains the WASM component model used by the project documentation.

Overview

The component model keeps agent logic inside the component and pushes environment-specific I/O into the host.

Component view

flowchart LR
    HOST[Host application] --> IMPORTS[Host imports]
    IMPORTS --> COMPONENT[WASM component]
    COMPONENT --> EXPORTS[Component exports]
    EXPORTS --> HOST

Responsibility model

flowchart TD
    subgraph Host
        CALL_LLM[Call LLM]
        RUN_TOOLS[Run tools]
        STORE_STATE[Persist state]
        LOG[Handle logging]
    end

    subgraph Component
        PLAN[Agent logic]
        PARSE[Parse responses]
        STEP[Track steps]
    end

    CALL_LLM --> PLAN
    RUN_TOOLS --> PLAN
    STORE_STATE --> STEP
    PLAN --> LOG

Host-driven message flow

The component does not call model APIs directly. The intended flow is:

1. Host sends the initial user prompt into the framework or component.
2. Framework/WASM assigns session_id, builds the full message list, and preserves history/context.
3. Host receives the prepared message payload and performs the actual LLM API call.
4. Host may return either plain text or a fully shaped assistant message.
5. Framework/WASM commits that response back into session history so later turns stay connected to the same context.

This means the first incoming turn may be plain text only. Once a session exists, later turns should be sent with the matching session_id and any host-level metadata needed to keep the conversation aligned with the WASM state.

Why this design is useful

Related documents

• WASM_AGENT.md
• BUILD.md

Config

This document describes the Postcard-based configuration flow used by the current documentation set and related SDK surfaces.

Overview

The repository documents two configuration stories:

1. The lightweight CLI config flow built around cli-config.pc
2. Broader SDK and core configuration helpers that use serialized configuration data

Configuration model

flowchart TD
    INPUT[Config source] --> SERIALIZE[Postcard serialization]
    SERIALIZE --> FILE[Binary file on disk]
    FILE --> LOAD[Load config]
    LOAD --> USE[CLI, SDK, or runtime usage]

Why Postcard

Main points

• Configuration is treated as structured data first, not hand-edited prose.
• Export and inspection can still be done through JSON-based helper commands or APIs.
• Secrets should remain outside the binary file when a dedicated secret mechanism is available.

Related documents

• CLI.md for the current CLI config workflow
• IMPORT_EXPORT.md for backup and restore flows
• CACHE.md for cache-specific notes

Cache (v1.0.0)

This document describes the active binary cache model for configuration data.

Cache Lifecycle

flowchart TD
    Source[Configuration source] --> Encode[Postcard encode]
    Encode --> File[Binary cache artifact]
    File --> Decode[Postcard decode]
    Decode --> Runtime[Runtime configuration use]

Current Behavior

• Binary configuration artifacts reduce parse overhead on repeated loads.
• Cache decoding is tied to active schema compatibility checks.
• Runtime uses cache artifacts only when integrity checks pass.

Operational Guidance

• Rebuild cache after schema-affecting updates.
• Keep import/export procedures aligned with cache format expectations.

Import Export

This document covers the backup and restore workflow for serialized configuration files.

Purpose

Import and export support makes it easier to:

• back up a working configuration
• move configuration between environments
• restore a known-good configuration after rebuilds or failures

Workflow

flowchart LR
    ACTIVE[Active config] --> EXPORT[Export or backup]
    EXPORT --> FILE[Saved .pc or JSON artifact]
    FILE --> IMPORT[Import or restore]
    IMPORT --> TARGET[Recovered or reused config]

Typical use cases

Guidance

• Keep backups versioned and named clearly.
• Treat exported artifacts as sensitive if they contain provider or environment details.
• Validate imported configuration before using it in production automation.

Related documents

• CONFIG.md
• CLI.md

JSON Schema

This document explains the JSON schema validation layer exposed by the SDK documentation set.

Goal

The JSON schema flow helps enforce structured model responses when plain free-form text is not enough.

Validation loop

flowchart TD
    PROMPT[Prompt with schema guidance] --> MODEL[LLM response]
    MODEL --> VALIDATE[Schema validation]
    VALIDATE -->|valid| OUTPUT[Accepted output]
    VALIDATE -->|invalid| RETRY[Retry with validation feedback]
    RETRY --> MODEL

What it is useful for

Core ideas

• A schema defines the required shape of the response.
• Validation checks the model output against that shape.
• Retry guidance can feed validation errors back into the next model attempt.

Related documents

• WASM_AGENT.md
• COMPONENT.md

Logging

This document describes the logging model used across the framework crates.

Overview

Logging is designed around structured events, session awareness, and optional subscription-style consumption.

Flow

flowchart LR
    EVENT[Runtime event] --> LOGGER[Logger]
    LOGGER --> STORE[Session log storage]
    LOGGER --> STREAM[Optional subscriber stream]
    STORE --> QUERY[Query or export logs]

Characteristics

Guidance

• Use structured metadata whenever possible.
• Keep session identifiers stable enough to trace one workflow end to end.
• Export logs when debugging long-running or multi-step flows.

Related documents

• WORKSPACE.md
• SERVERS_AND_AGENTS.md

Servers and Agents

This document summarizes the server and agent management surface exposed by the project documentation.

Overview

The framework separates:

• server definitions and tool connectivity
• agent definitions and execution behavior

High-level model

flowchart TD
    HOST[Host or operator] --> SERVERS[MCP servers]
    HOST --> AGENTS[Agent configs]
    AGENTS --> TOOLS[Tool calls]
    TOOLS --> SERVERS
    AGENTS --> OUTPUT[Responses or outcomes]

What this area covers

Runtime hardening controls (host-facing)

For multi-agent orchestration, host code can now manipulate and monitor hardening state at runtime via SDK helpers in antikythera-sdk::agents.

options_json now also accepts an optional guardrails object. Example:

{
    "max_concurrent_tasks": 4,
    "default_retry_condition": "on_transient",
    "guardrails": {
        "timeout": {
            "max_timeout_ms": 2000,
            "require_explicit_timeout": true
        },
        "budget": {
            "max_task_steps": 8,
            "require_explicit_budget": true
        },
        "rate_limit": {
            "max_tasks": 10,
            "window_ms": 60000
        },
        "cancellation": true
    }
}

The decoded task_result_detail(...) payload now includes optional guardrail_name and guardrail_stage fields when a guardrail rejected a task.

Host integration hooks

Core now also exposes host hook middleware in antikythera_core::application::hooks for auth, correlation, policy, and telemetry integration. See HOOKS.md.

The WIT multi-agent-runner contract mirrors these operations through configure-hardening, cancel-orchestrator, get-monitor-snapshot, and task-result-detail.

Native streaming pipeline

Native CLI provider clients now emit streaming events while parsing provider chunked responses:

1. provider stream payload is parsed chunk-by-chunk,
2. each chunk emits a stream event in the LLM pipeline,
3. terminal sink prints chunks live to stderr so stdout remains protocol-safe.

This keeps interactive visibility in CLI mode while preserving structured stdout output (for JSON or automation consumers). The terminal stream sink is enabled with the CLI --stream flag.

Related documents

• CLI.md
• STREAMING.md
• WASM_AGENT.md
• COMPONENT.md

Runtime Resilience (v1.0.0)

This document describes active resilience controls in runtime execution.

Resilience Control Loop

flowchart TD
    Task[Task execution] --> Retry[Retry policy]
    Task --> Timeout[Timeout policy]
    Task --> Context[Context-window controls]
    Task --> Health[Health tracking]
    Retry --> Outcome[Execution outcome]
    Timeout --> Outcome
    Context --> Outcome
    Health --> Outcome

Current Modules

• Retry/backoff behavior with explicit conditions.
• Timeout enforcement for bounded execution.
• Context-window handling to control prompt growth.
• Health-tracker surfaces for runtime state reporting.

Validation

• Covered by resilience tests under tests/resilience/.
• Integrates with guardrails and observability for production flows.

Observability (v1.0.0)

This document describes the active observability model used by runtime and host integrations.

Signal Pipeline

flowchart TD
    Runtime[Runtime event] --> Metrics[Metrics aggregation]
    Runtime --> Audit[Audit records]
    Runtime --> Trace[Tracing hooks]
    Metrics --> Export[Host export adapters]
    Audit --> Export
    Trace --> Export

Current Signals

• Latency summaries and operational counters.
• Structured audit trail records for policy and tool decisions.
• Correlation-ID aware event propagation.
• Host-facing export points for external telemetry systems.

Validation

• Use tests/observability/observability_tests.rs for behavior checks.
• Keep metric naming stable across minor updates.

Context Management (v1.0.0)

This document describes the active context management behavior in the runtime.

Runtime Flow

flowchart TD
    In[Incoming messages] --> Policy[ContextPolicy]
    Policy --> Trim[Truncation strategy]
    Trim --> Preserve[System message preservation]
    Preserve --> Out[Context for model call]

Current Capabilities

• Runtime policy configuration through context management APIs.
• Message-count and token-budget aware pruning.
• Strategy support for retaining recent context while preserving critical system prompts.
• Deterministic output for repeatable host integration tests.

Operational Notes

• Configure policy before high-volume conversational loops.
• Validate behavior with context management and session tests in tests/.
• Keep host-side persistence and restoration aligned with session snapshots.

Streaming (v1.0.0)

This document covers the currently implemented streaming behavior.

Streaming Architecture

Token streaming is built around a process-global event sink in antikythera-cli::infrastructure::llm::streaming.

flowchart LR
    Provider[LLM provider parser] --> Emit[emit_stream_event]
    Emit --> Sink[STREAM_SINK global]
    Sink --> TUI[TUI mpsc channel → Conversation panel]
    Sink --> Terminal[Terminal sink → stderr]

StreamEvent

Provider parsers emit one of three variants:

Sink modes

Runtime Guarantees

• Only one sink is active at a time; set_stream_event_sink replaces any previous sink.
• clear_stream_event_sink drops the sender, cleanly ending the mpsc channel after each response.
• Started and Completed events are forwarded to tracing::info! for the log panel under the cli:streaming source label.
• Chunk events are not traced — they are too frequent and their content is visible in the chat panel.

Related documents

• CLI.md
• SERVERS_AND_AGENTS.md

WASM Agent

This document describes the WASM-side agent model at a high level.

Overview

The WASM agent focuses on agent logic and response processing, while the host side handles external I/O.

Responsibility split

flowchart LR
    HOST[Host] --> LLM[LLM calls]
    HOST --> TOOLS[Tool execution]
    HOST --> STATE[Persistence]
    WASM[WASM agent] --> PARSE[Parse model output]
    WASM --> PLAN[Track state and next step]
    LLM --> WASM
    TOOLS --> WASM
    STATE --> WASM

Why this split matters

Benefits

• Keeps the WASM side smaller and more portable
• Lets the host choose provider and infrastructure strategy
• Avoids embedding every I/O concern into the component itself

Message and session flow

The intended host/WASM exchange is:

1. The first host request may contain only plain user text.
2. The framework creates or continues a session_id and assembles the internal message history.
3. The framework emits a prepared message list for the host to send to the LLM.
4. The host calls the provider API and may return either:
   • plain text, or
   • a structured assistant message already shaped to match framework expectations.
5. The framework records that assistant turn into history so the next prepared request remains tied to the same WASM-side context.

This allows the host to own provider-specific payload shaping while the framework owns conversation continuity, step tracking, and response interpretation.

Session archive and restore flow

The runner now supports automatic in-memory pressure handling and idle timeout archival.

Triggers

• Capacity pressure: session count exceeds max_in_memory_sessions
• Inactive timeout: sweep_idle_sessions(...) finds sessions older than session_timeout_secs

What the runner emits

When a session leaves RAM, the event stream includes:

• session_archived
  • includes reason (capacity_pressure or idle_timeout)
  • includes state_json snapshot to persist in host storage

If a request arrives for an archived session, the runner emits:

• session_restore_requested
• session_restore_progress (initial stage)

Host can push progress updates at any time using:

• report_session_restore_progress(session_id, progress_json)

After host loads state from durable storage, it restores RAM state via:

• hydrate_session(session_id, state_json)

Which emits:

• session_restored

This flow allows hosts to stream loading feedback to user interfaces when restore latency is non-trivial.

Related documents

• COMPONENT.md
• JSON_SCHEMA.md

Testing (v1.0.0)

This document describes the active test strategy for the workspace.

Test Topology

flowchart TD
    Unit[Unit and module tests] --> Crate[crate-level validation]
    Crate --> Integration[integration test binaries]
    Integration --> Contracts[contract compatibility checks]
    Integration --> Runtime[runtime behavior checks]

Current Structure

• Workspace-wide checks: build, test, fmt, and clippy gates.
• tests/ contains integration suites and module-specific binaries.
• Large suites use part-based organization for readability and maintenance.
• Contract fixtures are used for compatibility detection.

Standard Commands

cargo test --workspace
cargo test -p antikythera-tests --no-run
cargo fmt --all -- --check
cargo clippy --workspace --lib --bins -- -D warnings -D deprecated

Migration

This file records that the documentation structure has changed over time.

Current structure

The repository now keeps one README only at the repository root:

• README.md

All focused guides live under documentation/ and use uppercase direct filenames such as:

• ARCHITECTURE.md
• BUILD.md
• CLI.md
• COMPONENT.md
• WORKSPACE.md

What changed

flowchart LR
    OLD[Mixed naming and nested README] --> NEW[Single root README plus uppercase direct docs]

Before

• documentation/README.md existed as a second documentation index.
• Several files used long or mixed-style names such as CLI_DOCUMENTATION.md, json-schema-validation.md, and wasm-component-host-imports.md.

After

• documentation/README.md was removed.
• Root README.md became the single entry point for the repository.
• Documentation filenames under documentation/ were normalized to direct uppercase names.

Why this changed

• To make the repository easier to scan from the root.
• To keep documentation links predictable.
• To reduce duplicate entry points and filename noise.

Reading advice

If you are looking for current usage or structure, prefer:

1. README.md
2. documentation/WORKSPACE.md
3. documentation/ARCHITECTURE.md
4. documentation/CLI.md
5. documentation/BUILD.md

Use this file only as historical context.

Deprecation Policy (v1.0.0)

This policy defines current deprecation handling for public APIs.

Lifecycle Flow

flowchart LR
    Introduce[Introduce replacement] --> Mark[Mark deprecated API]
    Mark --> Warn[Emit compile-time warning]
    Warn --> Migrate[Consumer migration]
    Migrate --> Remove[Major-version removal]

Policy Rules

• A replacement API must exist before deprecation is introduced.
• Deprecated APIs must include since metadata and migration notes.
• Deprecated APIs remain thin delegates only.
• Removal occurs only on a major version boundary.

Enforcement

• CI/lint gate for production targets:
  • cargo clippy --workspace --lib --bins -- -D warnings -D deprecated
• Backward-compatibility tests can explicitly allow deprecated paths when required.