v5.29.0 — AgentOS: Shared State Kernel & Schema-Validated Handoffs

SkillFoundry v5.29.0 — AgentOS: Shared State Kernel & Schema-Validated Handoffs

Released: 2026-07-17

---

What's in This Release

An AgentOS substrate under the CLI. Two coordinated primitives — a durable run-state
kernel and schema-validated agent handoffs — built on top of the existing message bus and
gate engine, not a rewrite. The guiding idea: the intermediate representation agents pass
around should be terse, semantic, schema-validated JSON — native to both a developer's
eyes and the model's reasoning — not opaque vectors, bitstrings, or hidden-state embeddings
(provider-fragile and API-blocked). Implements PRD genesis/2026-07-17-agentos-state-kernel.md
across 5 stories.

The run finally has a single source of truth

Every forge run now writes one authoritative, human-inspectable document at
.skillfoundry/runs/<id>/state/state.json, partitioned into owner-scoped slices
(coder_state, tester_state, security_state, …). At 2 AM, when an autonomous run has gone
sideways, you read one file to see exactly what the run believes — not a reconstruction from
scattered logs.

• Versioned + race-safe. Each slice has a single owning agent and a monotonic version.
  A stale write is rejected; the loser re-reads, rebases, and retries (compare-and-swap) — it
  never silently drops an update. Disjoint slices commit in parallel.
• Crash-safe. Writes are atomic (temp + rename); a crash leaves the last valid document intact.
• References, not blobs. Oversized fields spill to state/artifacts/<sha256> and are
  replaced with a {ref,hash,bytes} pointer, so state stays small and inspectable.

Agents can't self-certify a passing build

State writes for gated slices go through a barrier — the "MMU." An agent proposes an update;
only a deterministic gate pass commits it. If the agent claims success but the build fails, the
proposal is not merged — the slice is marked FAILED with structured error_logs and the
run's build_status flips to FAILING, forcing a retry. The gate result, not the agent's
prose, is what counts. Because only the failing slice is touched, sibling slices keep going.

Handoffs carry validated data, not narrative

Agent-to-agent messages are validated against JSON Schema before delivery (backed by ajv). A
payload that doesn't match its contract is dropped and logged — a downstream agent never parses
an upstream agent's story. Adoption is incremental: message types with no registered contract
pass through untouched, so all existing agents keep working while contracts are added one
handoff at a time. Shared types (Severity, Finding, FileRef) live in one place.

Quiet on success, clear on failure

Natural language is now a projection generated only at the human boundary. A successful run
shows a compact one-block summary (per-slice metrics; spilled fields shown as <spilled NB>);
a failure renders a readable post-mortem from the structured error_logs — not a wall of
agent-to-agent chatter.

Compatibility

• Backward-compatible. Runs are now per-run directories alongside the existing flat
  <id>.json bundle. The pipeline integration is advisory — a state-write failure logs a
  warning and never breaks a run.
• New dependency: ajv ^8.17.1.
• 47 new unit tests; 111 existing bus/gate/pipeline tests unchanged and green; tsc clean.

Not yet done (deliberate follow-ups)

These are intentional next steps, flagged rather than silently skipped:

• Per-story slice streaming — the barrier currently records the run-level outcome; threading
  it through each story in the pipeline loop is next.
• Strict bus rollout — the contract middleware is opt-in and permissive by default; it is not
  auto-installed on the global bus. A strict, flag-gated, telemetry-driven rollout follows.
• Agent conversion — the 102 markdown agents are not yet converted to strict per-agent contracts.