fix(agent-runtime): support thread metadata

[jerryliang64]

Summary

• port feat(agent-runtime): pass metadata through createThread/ensureThread/createRun egg#5949 agent-runtime metadata changes into tegg
• allow createThread to persist thread metadata
• keep run metadata on run records without copying it to auto-created or existing threads
• add metadata regression coverage for createThread, syncRun, asyncRun, and streamRun

Upstream reference: eggjs/egg#5949

Test

• ut run test --workspace @eggjs/agent-runtime
• ut run tsc --workspace @eggjs/agent-runtime
• ut run lint
• ut run --workspaces tsc

Summary by CodeRabbit

• New Features

  • Thread creation now supports optional metadata that persists on threads and is not overwritten by subsequent runs.
  • Metadata is properly preserved across different run execution modes (sync, async, stream).

• Tests

  • Added comprehensive test suite verifying metadata behavior during thread creation and run execution.

[coderabbitai]

Warning

Rate limit exceeded

@jerryliang64 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 42 minutes and 15 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0b1d8cad-1629-4fb2-bb69-8093ca588dae

📥 Commits

Reviewing files that changed from the base of the PR and between 47245bb and 4df4f83.

📒 Files selected for processing (1)

• plugin/dns-cache/test/dns_cache_resolve.test.ts

📝 Walkthrough

Walkthrough

This PR adds optional metadata support to AgentRuntime.createThread(). A new CreateThreadOptions interface accepts metadata that is forwarded to the underlying store at thread creation time. The implementation updates the public method signature and internal ensureThread behavior. Comprehensive tests validate metadata persistence across thread creation and all run execution modes (sync, async, stream).

Changes

Thread metadata support

Layer / File(s)	Summary
Type contract for thread creation options core/types/agent-runtime/AgentRuntime.ts	New exported CreateThreadOptions interface defines optional metadata: Record<string, unknown> field with JSDoc specifying that metadata is forwarded to AgentStore.createThread at creation time and preserved for the thread lifetime.
AgentRuntime thread creation with metadata core/agent-runtime/src/AgentRuntime.ts	Imports CreateThreadOptions, updates createThread() signature to accept optional options parameter, passes options?.metadata to store.createThread(), and adds JSDoc to ensureThread documenting threadId reuse vs. auto-creation and that run metadata is not copied to threads.
Metadata behavior test suite core/agent-runtime/test/AgentRuntime.metadata.test.ts	Adds MockSSEWriter helper for capturing SSE events, and comprehensive tests asserting metadata persistence in createThread, run-level metadata retention in syncRun/asyncRun/streamRun execution modes, and that auto-created threads receive empty metadata without overwriting existing thread metadata.

Sequence Diagram

sequenceDiagram
  participant Client
  participant AgentRuntime
  participant AgentStore
  participant Thread
  Client->>AgentRuntime: createThread(options: {metadata: {...}})
  AgentRuntime->>AgentStore: createThread({metadata: {...}})
  AgentStore->>Thread: create with metadata
  Thread-->>AgentStore: thread record
  AgentStore-->>AgentRuntime: thread
  AgentRuntime-->>Client: thread
  Client->>AgentRuntime: syncRun({threadId, metadata: {...}})
  AgentRuntime->>AgentStore: ensureThread(threadId)
  AgentStore-->>AgentRuntime: existing thread (metadata unchanged)
  AgentRuntime->>AgentStore: createRun({threadId, metadata: {...}})
  AgentStore-->>AgentRuntime: run
  AgentRuntime-->>Client: run result

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• eggjs/tegg#445: Implements the store-side persistence of per-thread metadata that this PR's AgentRuntime.createThread options forward into OSSAgentStore.createThread.
• eggjs/tegg#414: Modifies ensureThread and thread/resume logic in the same AgentRuntime.ts file, touching related thread creation and resumption workflows.

Suggested reviewers

• akitaSummer

Poem

A rabbit hops through metadata threads,
With options passed and stored instead,
Each run keeps track, no mixing mess,
The tests all pass—a fuzzy success! 🐰✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(agent-runtime): support thread metadata' accurately and concisely describes the main change: adding support for thread metadata in the agent-runtime module.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch sync-egg-pr-5949

---

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 and usage tips.}

[gemini-code-assist]

Code Review

This pull request introduces the ability to provide metadata when creating a thread by updating the createThread method to accept CreateThreadOptions. It also ensures that metadata associated with a run is not incorrectly copied to auto-created threads, maintaining a clear separation between run and thread records. Comprehensive tests were added to verify metadata persistence and isolation across different run types. I have no feedback to provide.