Runtime 9: add read-only heartbeat memory contract

[roackb2]

Summary

• add public MemoryToolMode with an exact read-only capability and export memoryToolkit for explicit host composition
• thread memoryMode and toolkits through direct agent-loop and heartbeat execution-context paths
• add required AgentHeartbeatResult.memory.changed, shared with conversation results through one trace projector
• decode historical persisted heartbeat results without the receipt as { changed: false }
• stage the breaking public API as the @heddleagent/runtime 9.0.0 release candidate and document host lifecycle boundaries

Contract boundary

Heddle reports settled mutations made by Heddle memory tools. A hosted adapter still owns authenticated scope selection, restore-before-run ordering, signed capability allowlisting, checkpoint persistence/retry, and retention. Tool functions and filesystem paths remain outside the serialized heartbeat transport.

read-only exposes exactly:

• list_memory_notes
• read_memory_note
• search_memory_notes

It excludes record_knowledge, memory_checkpoint, and edit_memory_note.

Verification

• focused heartbeat/conversation/schema tests: 5 files, 69 tests passed
• full unit suite: 148 files, 972 tests passed
• integration suite excluding the environment-contaminated Agent Skills file: 48 files, 441 tests passed
• complete integration attempt: 48 of 49 files and 464 of 465 tests passed; the only failure is unrelated global skill discovery of /Users/roackb2/.agents/skills/orchestration/SKILL.md, whose description exceeds the catalog limit
• yarn typecheck
• yarn lint
• yarn runtime:build
• packed @heddleagent/runtime@9.0.0 and installed it in a fresh consumer
• fresh consumer runtime import and TypeScript compile passed for memoryToolkit, MemoryToolMode, RunAgentHeartbeatOptions.memoryMode, and AgentHeartbeatResult.memory

Release state

This PR is a reviewable Runtime 9 candidate only. It does not merge, tag, create a GitHub release, publish npm, deploy, or prove adopter behavior.

Closes #396

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-12T13:37:00.402019Z	6aa093d	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6aa093d14e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Reject missing receipts from live heartbeat transports

When HeartbeatAgentExecutionTransport returns a legacy or malformed current result without memory, executeThroughTransport() validates it with this schema, so the default silently converts it to { changed: false }. If that remote run mutated Heddle memory, the caller can then skip the required durable checkpoint and lose the update; reserve this compatibility default for persisted historical-record decoding and require memory when validating live transport results.

Useful? React with 👍 / 👎.