Atmosphere — AI Agent Foundation Strategy v0.5 (foundation-frame rewrite, 8 primitives, 2 proof samples, supersedes v0.4)

atmosphere-personal-agent-strategy-v0.5.md

Atmosphere — AI Agent Foundation Strategy (v0.5)

Working draft. Secret gist. Iterated with ChefFamille.

Date: 2026-04-15 Status: v0.5 — full rewrite under the foundation frame. Supersedes v0.4. Predecessors: v0.1 · v0.2 · v0.3 · v0.4

---

The reframe

v0.1 through v0.4 were product-framed — "platform for personal agents". That was wrong. ChefFamille's correction: we are building a foundation, the way Atmosphere 1.0 (2008–2013) was the foundation for Java real-time web apps.

Atmosphere 1.0 didn't build a chat app or a push-notification product. It built primitives — AtmosphereResource, Broadcaster, CometSupport, AtmosphereInterceptor, AsyncSupport — nouns that every real-time Java app needed regardless of what it did. The samples (chat, pubsub) proved the platform worked; they were not the platform.

Atmosphere 2.x does the same for AI agents. The primitives every Java AI agent needs, regardless of whether it's a personal assistant, a coding agent, a customer-service bot, a research agent, or anything else. The samples prove the primitives work. They are not the product.

---

Thesis

Atmosphere is the foundation for Java AI agents — the primitives every agent needs, regardless of what the agent does, runtime-agnostic by construction.

If a feature only helps one specific agent use case, it's a sample. If a feature only helps one runtime, runtime code owns it. If a feature is a named noun that any agent might need and works across all seven runtimes, Atmosphere owns it as a foundation primitive.

---

What Atmosphere 2.x already ships as foundation primitives

Reading the current tree, the foundation is further along than the v0.x product-framed plans gave it credit for. Named primitives that already exist and work across the seven runtimes:

Execution: AgentRuntime SPI · AgentExecutionContext · AbstractAgentRuntime<C> · ExecutionHandle · RetryPolicy · AgentLifecycleListener · AiInterceptor · StreamingSession · AiEndpointHandler

Tools & HITL: @AiTool · ToolDefinition · ToolExecutionHelper.executeWithApproval() · ApprovalStrategy (virtual-thread-parked) · ApprovalRegistry · ToolApprovalPolicy · @RequiresApproval

Orchestration: @Coordinator · AgentFleet (parallel / pipeline / route) · FanOutStrategy (AllResponses / FirstComplete / FastestStreamingTexts) · DefaultModelRouter (FAILOVER / ROUND_ROBIN / CONTENT_BASED with circuit breaker)

State surfaces: AiConversationMemory (6 of 7 runtimes already consume context.history()) · PersistentConversationMemory + SQLite / Redis · DurableSession + SessionStore · CheckpointStore with fork semantics

Content: Content.Text / Image / Audio / File · CacheHint · pipeline-level structured output + native jsonMode for Built-in

Protocols & transport: MCP server · A2A JSON-RPC · AG-UI · gRPC · WebSocket · SSE · HTTP/3 (WebTransport) · long-poll · five messaging channels (Slack / Telegram / Discord / WhatsApp / Messenger)

Safety: ContentSafetyFilter · SafetyChecker · StreamingTextBudgetManager · AiGuardrail

Observability: MicrometerAiMetrics · TracingCapturingSession · CoordinationJournal · admin control plane (25+ REST endpoints)

DX: @Agent · @Prompt · @Skill · skill files with three-tier resolution + SHA-256 integrity · CLI (atmosphere install / run / list) · capability matrix pinned via AbstractAgentRuntimeContractTest

That is already a substantial foundation. The v0.5 work is naming the eight primitives that are missing or fragmented, shipping them, and contract-testing the whole set across the seven runtimes.

---

The eight foundation primitives

Each one is a noun any Java AI agent might need, regardless of use case. The Atmosphere 1.0 discipline holds: if it's not used by every agent, it's not a primitive.

1. AgentState

Unified state SPI covering conversation history, durable facts, ephemeral working memory, and hierarchical rules. Today those are fragmented: AiConversationMemory owns conversation, LongTermMemory owns facts (flat, in-memory only), working memory doesn't exist, hierarchical rules don't exist. One SPI collapses them.

• File-backed default (Markdown + JSONL, OpenClaw-compatible as a free benefit)
• SQLite / Redis backends optional for enterprise audit / multi-tenant
• AutoMemoryStrategy pluggable sub-SPI: LlmDecided · EveryNTurns · SessionEnd · Hybrid
• AiConversationMemory kept as thin compatibility shim over AgentState.getConversation()
• Admin inspection endpoints on the existing admin control plane

2. AgentWorkspace

Agent-as-artifact SPI. "Here is a directory, parse it as a runnable agent definition." Users bring whatever workspace convention they want; Atmosphere reads it through the SPI.

• OpenClawWorkspaceAdapter — reads AGENTS.md / SOUL.md / USER.md / IDENTITY.md / MEMORY.md / memory/YYYY-MM-DD.md / skills/ / JSONL sessions
• ClaudeCodeWorkspaceAdapter — reads CLAUDE.md hierarchical memory
• AtmosphereNativeWorkspaceAdapter — simple default for users without existing conventions
• Atmosphere-specific extensions live as additional Markdown files in the workspace (CHANNELS.md, MCP.md, RUNTIME.md, PERMISSIONS.md, SKILLS.md) — other adapters ignore them
• CLI: atmosphere agent --workspace <path>, user-configurable default, no required conversion step

3. AgentIdentity

Per-user identity, credentials, permissions, rate limits, and audit trail. Today these are fragmented across AiConfig.LlmSettings (global credentials), StreamingTextBudgetManager (global token budget), CoordinationJournal (audit data but no per-user endpoint). Session-level permission modes don't exist. One primitive unifies them.

• Per-user credential store (encrypted default, OS keychain, OAuth delegation — same pluggability as primitive #4)
• Per-user rate limiting (RPS / RPM, separate from token budgets)
• PermissionMode on DurableSession: DEFAULT / PLAN / ACCEPT_EDITS / BYPASS / DENY_ALL, layered over per-tool @RequiresApproval
• Per-user audit endpoint derived from CoordinationJournal + tool execution history
• Read-only session sharing as a user-facing feature

4. ToolExtensibilityPoint

The "how agents acquire new capabilities at runtime" primitive. Includes per-user MCP client configuration, pluggable trust, and dynamic tool discovery.

• Per-user MCP client config (Atmosphere hosts an MCP server today; this is the missing MCP client per-user config)
• McpTrustProvider SPI: AtmosphereEncrypted (default) · OsKeychain · OAuthDelegated
• Dynamic tool discovery / advanced tool selection: a ToolIndex with semantic search over tool descriptions, @AiEndpoint(maxToolsPerRequest = N) with automatic selection. Validated by the Spring IO capability matrix as a common evaluation criterion; today Atmosphere injects every agent's tools into every request, which is bounded but not discoverable.
• Admin endpoints for install / uninstall / authorize

5. Sandbox

Isolated execution primitive for untrusted code, commands, and data transforms. Pluggable backends, Atmosphere-house style.

• Sandbox SPI: shell() · filesystem() · expose(port) · snapshot() · hibernate()
• Pluggable backends: Docker (local-dev default) · Firecracker · Kata · hosted (Vercel Sandbox, E2B, Modal, Blaxel) all as optional modules
• @SandboxTool annotation binds a tool to a sandbox instead of the JVM
• Resource limits per run: CPU, memory, wall-time, network
• Snapshot / hibernate support so long-running sandbox sessions can be suspended

6. AiGateway

Outbound facade consolidating DefaultModelRouter + StreamingTextBudgetManager + per-user credentials + per-user rate limits + MicrometerAiMetrics tracing under one named primitive. Mostly existing machinery wired under one facade, plus small additions.

• Cross-provider fallback (already there via DefaultModelRouter)
• Per-user rate limiting (new, small)
• Per-user credential resolution (shared with AgentIdentity)
• Unified trace export format
• Narrative win: every agent's LLM call enters through AiGateway, devs know where to look

7. ProtocolBridge

Inbound facade. Every @Agent is exposed via every enabled bridge. In-JVM dispatch becomes a first-class bridge implementation, not a special case hidden in AgentProcessor.

• ProtocolBridge SPI with explicit implementations:
  • InMemoryProtocolBridge — in-JVM dispatch, promoted from LocalAgentTransport to first-class status
  • McpProtocolBridge — MCP server host
  • A2aProtocolBridge — A2A JSON-RPC
  • AgUiProtocolBridge — AG-UI
  • GrpcProtocolBridge — gRPC
• Local and remote agent calls are architecturally symmetric: same interceptors, same tracing, same contract tests, same observability
• An agent can move from in-JVM to remote without changing code — swap the bridge, everything else stays
• This is the Broadcaster pattern from Atmosphere 1.0 applied to agent dispatch

8. AgentResumeHandle

Run ID, run registry, and event replay for mid-stream reconnect. Verified as a real gap at the agent-run level — DurableSessionInterceptor.restoreSession() at modules/durable-sessions/src/main/java/org/atmosphere/session/DurableSessionInterceptor.java:151-175 restores rooms and broadcasters on reconnect but does not reattach to in-flight ExecutionHandles. DurableSession's schema has no field for active runs.

• Explicit runId threaded through StreamingSession
• RunRegistry mapping runId → ExecutionHandle
• Per-run event replay buffer (reuse BroadcasterCache if the shape fits)
• DurableSessionInterceptor learns to reattach when the reconnecting client sends a runId header
• New field on DurableSession for active run IDs
• TTL on abandoned runs

---

The two proof samples

The samples prove the primitives work. They are not the product. Together they cover all eight primitives.

Proof sample #1 — personal assistant

Exercises: AgentState, AgentWorkspace, AgentIdentity, ToolExtensibilityPoint, orchestration, multi-channel continuity.

A long-lived, one-user, remembers-you assistant. Primary conversation agent plus a small fleet (scheduler, research, drafter) via @Coordinator / AgentFleet over InMemoryProtocolBridge. Ships as an OpenClaw-compatible workspace under samples/personal-assistant/.agent-workspace/. Default runtime Spring AI, --runtime=<name> flag switches any of the other six.

Demonstrates memory across restarts, identity across channels (Slack → web → mobile, one thread), per-user permissions, per-user MCP tools (user brings their own GitHub / Gmail / filesystem), audit per user.

Proof sample #2 — coding agent

Exercises: Sandbox, AgentResumeHandle, plus inherits everything from sample #1 through the shared foundation.

Small scope. Clones a repo into a Docker sandbox, reads files, proposes a patch, commits. Not a Cursor competitor. Not a product. The proof that Sandbox works end-to-end across all seven runtimes and that AgentResumeHandle correctly reattaches when a client disconnects mid-patch.

---

Non-goals

• Graph workflow DSL. LangGraph owns the category. @Coordinator / AgentFleet + CheckpointStore.fork() already covers imperative orchestration, and Spring IO's "Deterministic Workflow" row is green on us through the existing primitives.
• Voice / realtime pipeline (STT → agent → TTS with VAD, sub-100ms latency). A specific modality, substantial engineering, not core to the foundation. Revisit after the foundation is proven.
• New LLM client abstraction. Our clients are the seven runtimes.
• Backward-compatibility shims for deprecated SPIs, except the thin AiConversationMemory shim over AgentState.
• Custom Atmosphere YAML manifest format. AgentWorkspace reads whatever convention the user brings (OpenClaw, Claude Code, native).
• Feature-parity chasing with Python / TypeScript frameworks on anything that doesn't pass the "named noun every Java AI agent needs" test.
• Product-level positioning (personal agent product, coding agent product, customer service agent product). The samples prove the foundation; the foundation is the product.

---

Sequencing

Not months, not weeks. Hours. Actions done so far: platform audit (existing primitives catalogued), OpenClaw spec fetched, reflection-federation bet resolved as unnecessary, AgentResumeHandle verified as a real gap. Remaining:

• Primitive 1 — AgentState: ~2h (file-backed default, admin inspection, auto-memory strategies, ADK fix, contract test)
• Primitive 2 — AgentWorkspace: ~1h (SPI, OpenClaw adapter, native adapter, CLI --workspace flag)
• Primitive 3 — AgentIdentity: ~1h (permission modes, per-user audit, read-only sharing, per-user credential / rate limit)
• Primitive 4 — ToolExtensibilityPoint: ~1.5h (per-user MCP client, McpTrustProvider with three built-ins, ToolIndex with semantic search)
• Primitive 5 — Sandbox: ~1.5h (SPI + Docker default; Firecracker / Kata / hosted as separate follow-up modules in the backlog)
• Primitive 6 — AiGateway: ~1h (facade consolidation + per-user rate limit + unified trace export)
• Primitive 7 — ProtocolBridge: ~1h (SPI, elevate InMemoryProtocolBridge, relocate existing McpProtocolBridge / A2aProtocolBridge / AgUiProtocolBridge / GrpcProtocolBridge behind the SPI)
• Primitive 8 — AgentResumeHandle: ~2h (runId, RunRegistry, event replay buffer, DurableSessionInterceptor reattach logic, DurableSession schema field)
• Proof sample #1 — personal assistant: ~2h (fleet composition, example workspace, integrates primitives 1-4, 6, 7)
• Proof sample #2 — coding agent: ~2h (Docker sandbox, repo clone, patch proposal, integrates primitives 5, 8 plus inherits the rest)

Total: ~16 hours across eight primitives and two samples. Two to three focused sessions.

Quiet tease at the end, not before. Per ChefFamille's cadence — 3,750 stars with organic +1/day growth. Build the foundation, prove it with two samples, then tease.

---

Success measure

Eight yes/no questions, one per primitive. All must be yes for the foundation to be shipped.

1. AgentState — can I write a fact to memory on runtime X, restart the agent on runtime Y (any of the other six), and the fact is still there?
2. AgentWorkspace — can I point Atmosphere at an OpenClaw workspace, a Claude Code CLAUDE.md directory, and a native Atmosphere workspace, and all three run identically?
3. AgentIdentity — can a user see what the agent remembers about them, edit or delete entries, and see everything the agent has done on their behalf?
4. ToolExtensibilityPoint — can a user bring their own MCP tools via MCP.md without touching agent code, with credentials handled by any of three trust providers, and does an agent with 100 tools dynamically select the right ones per request instead of injecting all?
5. Sandbox — can I execute untrusted code inside a Docker sandbox from any of the seven runtimes, with resource limits, snapshot, and hibernate working correctly?
6. AiGateway — does every LLM call traverse the gateway, respect per-user rate limits, emit unified traces, and resolve per-user credentials?
7. ProtocolBridge — does the same @Agent behave identically when invoked via InMemoryProtocolBridge, McpProtocolBridge, A2aProtocolBridge, AgUiProtocolBridge, and GrpcProtocolBridge?
8. AgentResumeHandle — can a client disconnect mid-stream, reconnect ten seconds later with runId, and resume the in-flight run with missed events replayed?

Contract tests enforce each answer in CI across all seven runtimes. Same discipline as AbstractAgentRuntimeContractTest.expectedCapabilities(). No drift between claim and reality.

---

Validation from the Spring IO capability matrix

A Spring IO 2026 talk presented a three-column comparison of Spring AI · LangChain4j · Embabel across eleven capability rows (Documentation · Deterministic Workflow · Pure Agents · Subagents · Advanced tool selection · Human-in-the-loop · AI skills · Observability · Testing · MCP · A2A). Different frameworks were green on different rows. LangChain4j was flagged red on MCP with "No HTTP Server".

Mapped to Atmosphere's primitive set: ten of eleven rows are green on Atmosphere alone, regardless of which framework is underneath. The eleventh (Advanced tool selection) is the dynamic tool discovery gap — now folded into ToolExtensibilityPoint (primitive #4) as a sub-capability.

The slide is also narrower than Atmosphere's surface area. Nothing on it about multi-channel delivery, multi-transport streaming with fallback, durable sessions, fan-out strategies, circuit-breaker model routing, content safety, per-user budgets, per-run event replay, sandbox primitives, or agent-workspace portability. The slide is a framework comparison; Atmosphere operates at a different layer — the platform layer above those frameworks. That gap on the slide is the wedge.

---

Status log

• 2026-04-14 — v0.1 (gist) — thesis locked, six themes sketched.
• 2026-04-14 — v0.2 (gist) — schema / manifest / pace / flagship / UI / contract scope resolved. Raised architectural bet about memory above the runtime.
• 2026-04-14 — v0.3 (gist) — pluggable memory strategy, pluggable trust, OpenClaw adopted as YAML (wrongly), reflection-federation bet accepted as mitigation.
• 2026-04-14 — v0.4 (gist) — Actions 1 and 2 complete. Reflection-federation bet proven unnecessary. OpenClaw proven to use file-first Markdown workspace. Theme 1 pivoted from SQLite-first to file-first.
• 2026-04-15 — v0.5 (this gist) — full rewrite under the foundation frame. Product framing ("personal agent platform") replaced by foundation framing ("Java AI agent foundation, Atmosphere 1.0 style"). Six product themes replaced by eight primitives (AgentState, AgentWorkspace, AgentIdentity, ToolExtensibilityPoint, Sandbox, AiGateway, ProtocolBridge, AgentResumeHandle). Skill polish demoted from theme to backlog. Sandbox elevated from non-goal to required primitive. InMemoryProtocolBridge promoted to first-class bridge implementation. AgentResumeHandle scoped against the verified gap at the agent-run level. Dynamic tool discovery folded into ToolExtensibilityPoint. Two proof samples (personal assistant + coding agent) cover all eight primitives. Validated against Spring IO 2026 three-framework capability matrix — ten of eleven rows green on Atmosphere alone, eleventh addressed by primitive #4. Next: begin primitive implementation.