Document SolidAgent, and test the two repos together

[TonsOfFun]

Draft — for review alongside activeagents/solid_agent#8, which adds the examples these pages link to and CI on that side.

Why

solid_agent's gemspec has pointed homepage and documentation_uri at docs.activeagents.ai/solid_agent since it was published, and that page did not exist. The docs mentioned the gem only in passing, as something the dashboard happens to depend on.

Writing those pages meant running the two gems together, which nothing did — and that turned up two live breakages (below).

What's here

Docs — a Persistence section at /solid_agent

Page	Covers
/solid_agent	What it is, why it's a separate gem, what the installer writes, the concern map
/solid_agent/context	has_context: naming, options, multiple contexts, the tool exchange, provenance, trace correlation
/solid_agent/memory	has_memory, subject scoping, agent-to-agent hand-off
/solid_agent/tools	HasTools, StreamsToolUpdates, ToolCache
/solid_agent/reasoning	HasReasons + Reasonable
/solid_agent/runs	AgentRun, progress events, instruction cohorts, ModelPricing
/solid_agent/manifests	.agent.md, validation, conversion, building classes
/solid_agent/examples	Worked examples, mirroring examples/ in the solid_agent repo
/contributing/releasing	How the three gems are tested together and published

Linked from the sidebar, home-page features, framework overview, getting started, agents.md, actions/tools.md, and the dashboard page that already depended on the gem. npm run docs:build passes with dead-link checking on.

Cross-repo integration suite — test/integration/solid_agent/

Both gems in the dummy Rails app, against the models rails generate solid_agent:install writes, through the mock provider (deterministic, no API keys, no cassettes). Covers conversation persistence, memory hand-offs, run records, the tool cache, and the version constraints themselves.

Two configurations, both meaningful:

Configuration	Bundle	Rule
source	solid_agent main, SOLID_AGENT_STRICT=1	What the repos develop toward — must be green (29 runs, 0 skips)
released	whatever Bundler resolves from RubyGems	What users install today

A test declares what it needs (requires_solid_agent, or requires_solid_agent_capability for a method signature) and skips when the resolved gem can't do it, printing the reason; strict mode turns those skips into failures. So the released run never fails for merely being behind — its skip list is the drift report.

gemfiles/solid_agent_main.gemfile takes SOLID_AGENT_PATH (a local checkout) or SOLID_AGENT_REF (branch/tag/SHA), so either repository can drive the same suite. Runs on every PR (ci.yml), nightly, on repository_dispatch, and as a gate before publishing (release.yml).

Two bugs it found immediately

1. The dashboard was broken against solid_agent's current main. has_context's auto-context keyword was renamed contextable: → contextual: in 0.2. AgentExecutionService still passed the old one, so every run against source solid_agent died with ArgumentError: unknown keyword. Both repos' CI was green, because CI resolves the published 0.1.1 where the old keyword still works. Now resolved from the installed method (ActionAgent.solid_agent_auto_context_keyword) rather than hard-coded, since the gemspec floor admits both versions.

2. AgentToolbox's fallback cache key didn't match SolidAgent::ToolCache's. The fallback used kwargs.sort.to_h.to_json; ToolCache normalizes to sorted pairs recursively. Upgrading solid_agent silently invalidated every cached tool result. Both paths normalize identically now, with a test pinning them together.

Also fixes the docs and examples that named a context without class_name: — has_context :conversation resolves Conversation/ConversationMessage/ConversationGeneration, not the installed AgentContext family, and raises NameError on the first request.

Also

README badges: gem version (activeagent + actionagent), downloads, CI, cross-repo integration, docs, Ruby, Rails, license.

Testing

• bin/rubocop — clean (458 files)
• npm run docs:build — clean, dead-link checking verified active
• Source combination, strict: 29 runs, 98 assertions, 0 failures, 0 skips
• Released combination: 29 runs, 0 failures, 20 skips naming exactly what 0.1.1 lacks
• Full suite unchanged against both bundles (same pass/error counts as main in this sandbox, which has no API keys)

Notes for review

• Docs pages carry code inline instead of <<< imports. contributing/documentation.md requires importing from tested files, but solid_agent's sources are in another repository. The exception is documented there and points at the tested examples/ the pages mirror. The alternative — a git-source dev dependency plus test/docs/ tests — is a bigger call than a docs PR should make.
• The published gem is 0.1.1 and only has HasContext, HasTools, StreamsToolUpdates. HasMemory, AgentRun, ToolCache, ModelPricing, RunFingerprint and AgentManifest exist only on solid_agent's main, which is why 20 tests skip against the real gem and why these docs describe a gem you can't bundle add yet. Cutting solid_agent 0.2.0 closes that; afterwards actionagent.gemspec's solid_agent >= 0.1 floor should move to >= 0.2 and the keyword detection in ActionAgent.solid_agent_auto_context_keyword can go.
• Merge this before Add examples, CI, release automation, badges and a LICENSE solid_agent#8 — that repo's cross-repo CI job checks out activeagent main and runs the suite added here, so it stays red until this lands.
• test/dummy/db/schema.rb is regenerated (migration 005 adds the unprefixed host-app tables; the engine's prefixed copies in 004 are untouched).

🤖 Generated with Claude Code

https://claude.ai/code/session_01NGn2NzpzFZT4JGKBdFMpxh

[Copilot]

Pull request overview

Adds first-class documentation for the solid_agent persistence gem within the ActiveAgent docs site, and introduces a cross-repo integration test + CI workflow to continuously validate the activeagent/actionagent ↔ solid_agent compatibility seam (both against the released gem and against solid_agent main). It also updates the dashboard engine to tolerate upstream API drift (contextable: → contextual:) and to keep tool-cache keys stable across upgrades.

Changes:

• Add a new SolidAgent documentation section (/solid_agent) with pages for context, memory, tools/caching, reasoning, runs/cost, manifests, and examples; wire it into the docs nav and cross-links.
• Add a cross-repo integration suite (test/integration/solid_agent) plus dummy-app host tables/models matching solid_agent:install, and a Gemfile to run against solid_agent source.
• Update ActionAgent’s integration points (auto-context keyword detection; tool-cache fallback key normalization) and add CI/release gating via a dedicated integration workflow.

Reviewed changes

Copilot reviewed 41 out of 41 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
test/integration/solid_agent/tool_cache_test.rb	Verifies ToolCache behavior and pins ActionAgent fallback cache key to match SolidAgent::ToolCache.
test/integration/solid_agent/runs_test.rb	Exercises host-app AgentRun lifecycle/events and SolidAgent::ModelPricing/fingerprinting integration.
test/integration/solid_agent/memory_test.rb	Validates HasMemory hand-off behavior and host-app model persistence.
test/integration/solid_agent/integration_case.rb	Base test harness implementing capability/constant gating with strict-mode behavior.
test/integration/solid_agent/context_persistence_test.rb	Ensures HasContext persists/replays messages/generations and trace/provenance.
test/integration/solid_agent/compatibility_test.rb	Compatibility assertions covering dependency constraints and dashboard API expectations.
test/dummy/db/schema.rb	Regenerated dummy schema to include unprefixed host-app persistence tables.
test/dummy/db/migrate/005_create_solid_agent_tables.rb	Adds dummy-app migration mirroring solid_agent:install host tables.
test/dummy/app/models/agent_run.rb	Adds host-app AgentRun model contract used by integration tests.
test/dummy/app/models/agent_message.rb	Adds host-app AgentMessage model contract used by integration tests.
test/dummy/app/models/agent_memory.rb	Adds host-app AgentMemory model contract used by integration tests.
test/dummy/app/models/agent_memory_entry.rb	Adds host-app AgentMemoryEntry model contract used by integration tests.
test/dummy/app/models/agent_generation.rb	Adds host-app AgentGeneration model contract used by integration tests.
test/dummy/app/models/agent_context.rb	Adds host-app AgentContext model contract used by integration tests.
test/dummy/app/agents/persistence/support_agent.rb	Adds a deterministic mock-provider agent used to drive persistence integration tests.
README.md	Adds badges for gem versions, downloads, CI, integration workflow, docs, Ruby/Rails, license.
gemfiles/solid_agent_main.gemfile	Adds a bundle configuration to run integration suite against solid_agent source (path/ref).
docs/solid_agent/tools.md	Documents SolidAgent tooling schema sources, streaming tool status, and ToolCache behavior.
docs/solid_agent/runs.md	Documents run records, progress events, cohorts, and cost estimation.
docs/solid_agent/reasoning.md	Documents extended-thinking capture/persistence via HasReasons/Reasonable.
docs/solid_agent/memory.md	Documents durable subject-scoped memory and the save_memory/recall_memory tools.
docs/solid_agent/manifests.md	Documents .agent.md manifests: loading, validating, exporting, building agents.
docs/solid_agent/examples.md	Provides worked examples and links back to the solid_agent repo’s examples/.
docs/solid_agent/context.md	Documents has_context behavior, naming, tool exchange persistence, provenance/trace correlation.
docs/solid_agent.md	Adds top-level SolidAgent overview page and navigation to subtopics.
docs/index.md	Adds SolidAgent “Persistence” feature tile on the docs homepage.
docs/getting_started.md	Adds SolidAgent persistence link to framework navigation.
docs/framework/dashboard.md	Updates dashboard docs to link to local SolidAgent docs and mention added persistence coverage.
docs/framework.md	Adds SolidAgent persistence link to framework overview.
docs/contributing/releasing.md	Documents cross-repo testing strategy and release ordering/constraints.
docs/contributing/documentation.md	Records the documented exception for sibling-gem pages carrying inline code (no <<< imports).
docs/agents.md	Adds SolidAgent persistence link to related topics.
docs/actions/tools.md	Adds SolidAgent tools/streaming/caching link to related topics.
docs/.vitepress/config.mts	Adds SolidAgent section to the sidebar/nav and a link to releasing docs.
AGENTS.md	Adds cross-repo testing instructions for contributors.
actionagent/lib/action_agent.rb	Adds runtime detection for has_context auto-context keyword (contextable vs contextual).
actionagent/app/services/action_agent/agent_toolbox.rb	Replaces cache-key fallback with normalized scheme matching ToolCache.
actionagent/app/services/action_agent/agent_execution_service.rb	Uses detected auto-context keyword when calling has_context for runtime-generated agents.
.github/workflows/release.yml	Gates release build on the cross-repo integration workflow.
.github/workflows/integration.yml	Adds a dedicated workflow to run integration suite against released and source solid_agent.
.github/workflows/ci.yml	Adds integration workflow invocation to PR/CI runs.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[TonsOfFun]

Copilot's three findings, all accepted (c18e25b):

1. append_event is not concurrency-safe. Correct, and the root cause is upstream — the dummy model is a verbatim copy of solid_agent's install-generator template, comment included. Fixed at the source in activeagents/solid_agent#8 (with_lock around the re-read and the write, in both SolidAgent::Records::AgentRun and the template, with tests), and mirrored here so the copy keeps tracking it.

2. docs/solid_agent/runs.md overclaimed. Same root cause — the page repeated the template's "interleave instead of clobbering each other", which described the re-read rather than a lock. Reworded to describe what the lock actually guarantees.

3. docs/solid_agent/context.md "turned auto_save: false off". Reads as the opposite of what it means; now "when you have set auto_save: false".

Also since the first review: test/dummy/db/schema.rb was stamped ActiveRecord::Schema[8.1] by the regeneration, which the API-gem jobs (pinned to rails ~> 8.0.0) reject outright — that was the one red check, now green. All 8 checks pass, including both integration configurations.

---

Generated by Claude Code