Shelvia
ConceptDeveloper preview

Agent Compatibility

Shelvia does not run your agents. Shelvia is the memory layer external agent runtimes call before they act. Agents propose. Humans approve. Shelvia keeps the trusted memory.

Per-runtime attestation is ongoing

The capabilities below are reachable today and every agent-originated write is review-gated. A manual end-to-end attestation across all four runtimes is still in progress. Until the attestation reaches PASS, Shelvia avoids "fully verified across all runtimes" language for this surface.

Principle

Agent Compatibility means external runtimes can request reviewed project context from Shelvia and send proposed updates back to the Review Queue. Shelvia does not run your agents. It gives them scoped, reviewed context and records what they propose.

It is a compatibility layer, not an Agent OS, not a runtime, not a sandbox. External agent runtimes (OpenAI Agents SDK, MCP clients, LangGraph, Google ADK, and custom backends) call Shelvia's already-shipped REST, MCP, and SDK surface to retrieve reviewed memory, propose candidates, and record what they did. The review-before-save contract applies to every agent-originated write.

What is available today

  • Four runtime recipes: OpenAI Agents SDK, MCP client, LangGraph, and Google ADK (links below).
  • A cross-cutting candidate-write safety pattern, the agent-proposes-candidate recipe.
  • Candidate-write API: POST to the project candidates endpoint with the memory.candidates scope. It always inserts status pending, never trusted memory directly.
  • MCP tools shelvia_create_memory_candidate and shelvia_log_continuation, with the same auth, scope, BOLA, and review-before-save chokepoint as REST.
  • TypeScript SDK helpers: client.memory.createCandidate(...) and client.projects.logContinuation(...).
  • Audit-only observability via projects.logContinuation, under the continuations.log scope.
  • Narrow-scope identity: one labelled shv_live_<hex> token per agent or workflow, issued under Settings > API.
  • Idempotency: an Idempotency-Key shaped agent-<runtime>-<run-id>-<candidate-hash>.

What it is not

  • Not an Agent OS.
  • Not a runtime or sandbox.
  • Not a scheduler or orchestrator.
  • Not autonomous execution.
  • Not a service-token path that bypasses review-before-save. No agent can write directly to trusted memory rows like project_decisions, source_links, or saved_prompts.
  • Not a self-approval surface. Agents cannot promote their own candidates; promotion is always a human review action in the Shelvia UI.
  • Not a chain-of-thought logger. Candidate bodies are final claims only.

Supported runtimes (recipes)

  • OpenAI Agents SDK, /docs/recipes/openai-agents-sdk
  • MCP client (Claude Desktop / Cursor / Cline / Continue / any spec-compliant client), /docs/recipes/mcp-client
  • LangGraph, /docs/recipes/langgraph
  • Google ADK, /docs/recipes/google-adk
  • Custom backends, follow /docs/recipes/agent-proposes-candidate

Each recipe is a docs-only page that uses the already-shipped REST, MCP, and SDK surface. No new Shelvia runtime is needed. Manual end-to-end attestation per runtime is the gate for full-live status. That attestation is still pending.

Safety envelope

  • Agents propose; humans approve. Every agent-originated write enters the review queue.
  • Narrow-scope identity per agent or workflow, set under Settings > API.
  • Idempotency-Key on every candidate write to prevent duplicates on retry.
  • No raw chain-of-thought in candidate bodies.
  • Forbidden body keys (cookie, authorization, session_token, api_key, ...) rejected with structured error codes.
  • Workspace anchor on the token: no body field can retarget a different workspace.
  • BOLA: cross-workspace project_ids are rejected before any read or write executes.
  • Agents cannot promote their own candidates via any documented surface.

Verification gate

Agent Compatibility's capabilities ship today. The attestation gate (planned, not yet open) requires a real human end-to-end attestation across all four runtimes. Until the attestation reads PASS with real evidence in every block, Shelvia does not use "fully verified" or "fully live" language for Agent Compatibility anywhere on the public surface.

  • Tester must produce a real memory_approval_candidates row with status: pending per runtime.
  • Tester must produce a real audit_logs row with action: api.candidate.create per runtime.
  • Tester must produce a real continue_recommendations row with suggested_tool matching the runtime tag per runtime.
  • Tester must run six safety walkthroughs per runtime (idempotency replay, forbidden-key rejection, pending exclusion from search, BOLA cross-workspace rejection, no self-approval surface, human approval still required).
  • Tester must capture redacted evidence per runtime.

Where to go next

  • Recipes, /docs/recipes/openai-agents-sdk, /docs/recipes/mcp-client, /docs/recipes/langgraph, /docs/recipes/google-adk, /docs/recipes/agent-proposes-candidate
  • REST API, /docs/developers/api
  • MCP, /docs/developers/mcp
  • TypeScript SDK, /docs/developers/sdk
  • Review-before-save concept, /docs/concepts/review-before-save
  • Roadmap (full attestation gate), /docs/roadmap/agent-compatibility

For runnable code samples and the developer reference, see /developers. For the trust model in depth, see /security.