perf(agent-runtime): avoid full thread reads for resume checks

[jerryliang64]

What changed

• Add an optional AgentStore.hasMessages(threadId) capability for checking whether a thread contains user or assistant messages.
• Make AgentRuntime.ensureThread() prefer the lightweight capability while retaining the existing getThread() fallback for custom stores.
• Add optional byte-range reads to ObjectStorageClient and implement them in OSSObjectStorageClient.
• Implement OSSAgentStore.hasMessages() with a 64 KiB prefix read; fall back to a full object read only when the prefix is inconclusive.
• Add regression coverage for runtime fallback compatibility, missing threads, range reads, decisive prefixes, and truncated leading records.

Why

AgentRuntime.ensureThread() previously loaded and parsed the entire thread only to evaluate thread.messages.length > 0. For long JSONL histories this adds avoidable object-store transfer, parsing cost, memory pressure, and run-start latency.

The new capability lets each store provide its cheapest correct existence check. Existing stores remain source-compatible because the method is optional.

Behavior and compatibility

• hasMessages() follows the default getThread() filtering semantics: only user and assistant messages count.
• Missing threads still raise AgentNotFoundError.
• Stores that do not implement the capability continue using the existing full getThread() path.
• OSS range reads only return early after parsing complete JSONL records. Partial prefixes and oversized leading system records fall back to the full object, avoiding false negatives.

Validation

• ut run test --workspace=@eggjs/agent-runtime — 209 passing
• ut run tsc --workspace=@eggjs/agent-runtime
• ut run tsc:pub --workspace=@eggjs/agent-runtime
• ut run tsc:pub --workspace=@eggjs/tegg-types
• ut run lint — 0 errors; 10 pre-existing warnings in unrelated files
• Independent correctness/security review — LGTM

CI compatibility

• Provide the Web Crypto global required by the latest MCP SDK when running Streamable HTTP paths on Node.js 18.
• Keep the compatibility initialization guarded so Node.js 20+ retains its native global.
• GitHub Actions Node.js 16/18/20 matrix passes on both Ubuntu and macOS.

Summary by CodeRabbit

• Improvements

  • Thread resumption now detects existing conversation history more efficiently.
  • Large message histories can be checked without downloading the entire message file when supported by storage.
  • Added support for reading specific byte ranges from stored objects.

• Bug Fixes

  • Improved compatibility for MCP features in Node.js environments without a global Web Crypto API.

• Documentation

  • Clarified how resumed runs are determined based on persisted conversation messages.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0184b0e3-0908-4088-bfe2-b168a21c4cff

📥 Commits

Reviewing files that changed from the base of the PR and between b77c789 and 462ea75.

📒 Files selected for processing (13)

• core/agent-runtime/src/AgentRuntime.ts
• core/agent-runtime/src/OSSAgentStore.ts
• core/agent-runtime/src/OSSObjectStorageClient.ts
• core/agent-runtime/test/AgentRuntime.test.ts
• core/agent-runtime/test/OSSAgentStore.test.ts
• core/agent-runtime/test/OSSObjectStorageClient.test.ts
• core/agent-runtime/test/helpers.ts
• core/mcp-client/test/fixtures/streamable-mcp-server/http.ts
• core/types/agent-runtime/AgentRuntime.ts
• core/types/agent-runtime/AgentStore.ts
• core/types/agent-runtime/ObjectStorageClient.ts
• plugin/controller/lib/impl/mcp/MCPControllerRegister.ts
• plugin/mcp-client/test/fixtures/streamable-mcp-server/http.ts

---

📝 Walkthrough

Walkthrough

Changes

Thread resume detection now checks for persisted user or assistant messages through an optional AgentStore.hasMessages capability. OSS storage uses bounded ranged reads with full-read fallback, while MCP modules initialize Node Web Crypto when needed.

Thread resume detection

Layer / File(s)	Summary
Storage range contracts and implementation core/types/agent-runtime/ObjectStorageClient.ts, core/agent-runtime/src/OSSObjectStorageClient.ts, core/agent-runtime/test/helpers.ts, core/agent-runtime/test/OSSObjectStorageClient.test.ts	Adds inclusive byte-range storage reads with validation, error mapping, and test coverage.
OSS conversation-message detection core/agent-runtime/src/OSSAgentStore.ts, core/agent-runtime/test/OSSAgentStore.test.ts	Adds hasMessages, scans bounded JSONL prefixes for conversation messages, and falls back to full reads when required.
Runtime resume wiring and compatibility core/types/agent-runtime/AgentStore.ts, core/types/agent-runtime/AgentRuntime.ts, core/agent-runtime/src/AgentRuntime.ts, core/agent-runtime/test/AgentRuntime.test.ts	Uses hasMessages for isResume, preserves the getThread fallback, and updates the related contract documentation and tests.

Node Web Crypto initialization

Layer / File(s)	Summary
MCP Web Crypto initialization plugin/controller/lib/impl/mcp/MCPControllerRegister.ts, core/mcp-client/test/fixtures/streamable-mcp-server/http.ts, plugin/mcp-client/test/fixtures/streamable-mcp-server/http.ts	Conditionally defines globalThis.crypto from Node’s webcrypto implementation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant AgentRuntime
  participant AgentStore
  participant ObjectStorage
  AgentRuntime->>AgentStore: ensureThread(threadId)
  AgentStore->>ObjectStorage: inspect metadata and message prefix
  ObjectStorage-->>AgentStore: range result or full messages
  AgentStore-->>AgentRuntime: isResume boolean

Loading

Possibly related PRs

• eggjs/tegg#414: Introduces the isResume population that this PR refines with message-presence detection.
• eggjs/tegg#439: Persists user and partial assistant messages used by hasMessages on subsequent runs.

Suggested reviewers: akitasummer, killagu

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/agent-store-has-messages

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

core/agent-runtime/src/AgentRuntime.ts

ESLint skipped: missing config or dependency (missing-dependency). The ESLint configuration references a package that is not available in the sandbox.

core/agent-runtime/src/OSSAgentStore.ts

ESLint skipped: the ESLint configuration for this file references a package that is not available in the sandbox.

core/agent-runtime/src/OSSObjectStorageClient.ts

ESLint skipped: the ESLint configuration for this file references a package that is not available in the sandbox.

• 10 others

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[akitaSummer]

1

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.