feat: RFC-003 Agent Configuration Layer (Phase 1-5) #241

2026-04-29T04:45:16Z

xiaoju commented

2026-04-29 04:45:16 +00:00

What

Full implementation of RFC-003: Agent Configuration Layer — separates agent infrastructure (type/model/timeout) from workflow business logic (prompt/schema).

Changes

Phase 1: Types + Config Schema

AgentFn, WorkflowContext (workdir + AbortSignal), ExtractFn, ExtractError
AgentConfig, ExtractConfig in NerveConfig
nerve.yaml parser extended for agents + extract sections
Kebab-case agent name validation

Phase 2: AgentRegistry + Echo Adapter

createAgentRegistry(agents) → { get(name): AgentFn }
Echo adapter (type: echo) for testing
Throws with agent name on missing lookup

Phase 3: Extract Layer

llmExtractWithRetry: retry-once with error context
mergeExtractConfig: three-level merge (global → agent → role)
createLlmExtractFn factory, ZodMetaSchema bridge

Phase 4: WorkflowSpec Compiler

WorkflowSpec + RoleSpec authoring types
compileWorkflowSpec: WorkflowSpec → WorkflowDefinition (runtime lazy compile)
Two-level timeout resolution (role override > agent default)
parseDurationStringToMs shared utility
Backward compatible — hand-written Role<Meta> unchanged

Phase 5: Integration

Kernel rebuilds AgentRegistry on config hot-reload + logs event
Running threads unaffected, new threads use rebuilt registry
nerve validate checks: agent name refs, adapter type, extract config

Testing

539 tests, 61 test files, all pass ✅
pnpm run check clean
Phase testing issues: #235 #236 #237 #238 Phase 5 Testing: Integration (Hot-Reload + Validate) (#239)

Not included

Phase 6 (Knowledge Layer) — separate PR
Real agent adapters (cursor/hermes/codex) — future work

Ref: #234
Closes #235 #236 #237 #238 #239

## What Full implementation of RFC-003: Agent Configuration Layer — separates agent infrastructure (type/model/timeout) from workflow business logic (prompt/schema). ## Changes ### Phase 1: Types + Config Schema - `AgentFn`, `WorkflowContext` (workdir + AbortSignal), `ExtractFn`, `ExtractError` - `AgentConfig`, `ExtractConfig` in `NerveConfig` - `nerve.yaml` parser extended for `agents` + `extract` sections - Kebab-case agent name validation ### Phase 2: AgentRegistry + Echo Adapter - `createAgentRegistry(agents)` → `{ get(name): AgentFn }` - Echo adapter (`type: echo`) for testing - Throws with agent name on missing lookup ### Phase 3: Extract Layer - `llmExtractWithRetry`: retry-once with error context - `mergeExtractConfig`: three-level merge (global → agent → role) - `createLlmExtractFn` factory, `ZodMetaSchema` bridge ### Phase 4: WorkflowSpec Compiler - `WorkflowSpec` + `RoleSpec` authoring types - `compileWorkflowSpec`: WorkflowSpec → WorkflowDefinition (runtime lazy compile) - Two-level timeout resolution (role override > agent default) - `parseDurationStringToMs` shared utility - Backward compatible — hand-written `Role<Meta>` unchanged ### Phase 5: Integration - Kernel rebuilds `AgentRegistry` on config hot-reload + logs event - Running threads unaffected, new threads use rebuilt registry - `nerve validate` checks: agent name refs, adapter type, extract config ## Testing - 539 tests, 61 test files, all pass ✅ - `pnpm run check` clean - Phase testing issues: #235 #236 #237 #238 #239 ## Not included - Phase 6 (Knowledge Layer) — separate PR - Real agent adapters (cursor/hermes/codex) — future work Ref: #234 Closes #235 #236 #237 #238 #239

xiaoju added 3 commits 2026-04-29 04:45:17 +00:00

docs(rfc): knowledge layer — built-in, local-first, repo-scoped aecced587c

Replaces the Alysaril delegation with a built-in knowledge feature:
- knowledge.yaml at repo root with include/exclude
- knowledge.db (SQLite) stores chunks + embeddings locally
- Remote service only for embedding computation + content-hash cache
- In-memory cosine search (sufficient for project scale)
- CLI: nerve knowledge sync/query with -r and -g flags

Refs #233

docs(rfc): address review — resolve open questions, add error handling/hot-reload/context/validation 7a4e16381c

- model: auto = delegate to adapter's default strategy
- ExtractFn: retry once + throw ExtractError, three-level merge (global → agent → role)
- Agent hot-reload: AgentRegistry rebuilds on config change, running threads unaffected
- WorkflowContext: add workdir + AbortSignal
- Configuration validation: nerve validate checks agent name refs
- WorkflowSpec compile: runtime lazy compile at daemon startup/hot-reload
- Compatibility: existing hand-written Role functions continue to work (not breaking)
- Resolved 3 of 5 open questions, 2 remaining (long-term memory, embedding service)

Refs #233

feat(core): RFC-003 Phase 1 — agent config types + nerve.yaml schema 36e5aed1b1

- Add AgentFn, WorkflowContext (workdir + AbortSignal), ExtractFn, ExtractError
- Add AgentConfig, ExtractConfig types to NerveConfig
- Extend parseNerveConfig: agents (kebab-case keys) + extract sections
- Export all new types from @nerve/core
- Add config parse tests (7 new tests)
- Update all existing test fixtures with agents/extract fields

Closes #235
Ref: #234

xiaoju added 1 commit 2026-04-29 04:51:24 +00:00

feat(daemon): RFC-003 Phase 2 — AgentRegistry + echo adapter 88bd30a1e4

- createAgentRegistry(agents) returns { get(name): AgentFn }
- get() throws with agent name in message if not found
- Echo adapter (type: 'echo') returns prompt as-is for testing
- Tests: 5 cases covering get/throw/echo/multi-agent/AbortSignal

Closes #236
Ref: #234

xiaoju added 1 commit 2026-04-29 05:01:49 +00:00

feat(workflow-utils): RFC-003 Phase 3 — Extract Layer 136aafa209

- llmExtractWithRetry: retry-once on parse failure with error context
- mergeExtractConfig: three-level merge (global → agent → role)
- extractMetaOrThrow + createLlmExtractFn: ExtractFn factory
- ZodMetaSchema bridges core Schema<T> with runtime Zod validation
- Tests: 8 new cases (success/retry/throw/merge/factory)
- core tsconfig: add DOM lib for AbortSignal declaration emit

Closes #237
Ref: #234

xiaoju added 1 commit 2026-04-29 05:13:36 +00:00

feat(core,daemon): RFC-003 Phase 4 — WorkflowSpec Compiler 1218b5ddbd

- WorkflowSpec + RoleSpec types in packages/core
- compileWorkflowSpec: WorkflowSpec → WorkflowDefinition (daemon)
- resolveRoleTimeoutMs: two-level timeout (role override > agent default)
- parseDurationStringToMs extracted to shared duration.ts
- AgentRegistry.getAgentConfig for timeout lookup
- Tests: 10 new cases (compile shape, agent→extract flow, timeout resolution)
- Backward compat: hand-written Role<Meta> unchanged

Closes #238
Ref: #234

xiaoju added 1 commit 2026-04-29 05:26:08 +00:00

feat(daemon,cli): RFC-003 Phase 5 — Integration (hot-reload + validate) a1dda1d731

- Kernel: rebuild AgentRegistry on config hot-reload, log agent_registry_reload
- Running threads unaffected, new threads use rebuilt registry
- nerve validate: check agent name refs in WorkflowSpec source files
- nerve validate: verify adapter type is known (KNOWN_AGENT_ADAPTER_IDS)
- nerve validate: require extract config when WorkflowSpec agent refs exist
- Tests: kernel reload (mock), validate (missing/valid/extract/adapter)

Closes #239
Ref: #234

xiaoju changed title from ~~feat(core): RFC-003 Phase 1 — Agent Config Types + Schema~~ to feat: RFC-003 Agent Configuration Layer (Phase 1-5)

2026-04-29 05:27:49 +00:00

xiaoju requested review from xiaomo 2026-04-29 05:27:56 +00:00

xiaomo approved these changes 2026-04-29 05:31:56 +00:00

xiaomo left a comment

✅ Hermes Agent Review — APPROVED

总评

RFC-003 Phase 1-5 实现质量很高，架构层次清晰，与 RFC 设计完全对齐。42 个文件改动量合理，每个 Phase 边界分明。

✅ 亮点

类型设计精准 — AgentFn、WorkflowContext（含 workdir + AbortSignal）、ExtractFn、ExtractError 都到位，Schema witness pattern 巧妙
AgentRegistry 简洁 — Map-based lookup，get/getAgentConfig 分离，immutable after creation
compile-workflow-spec — AbortSignal.any() 组合 user cancel + timeout；两层 timeout resolution 干净
Extract retry 策略 — retry 时把 error 注入 user message 让 LLM 自我修正，比盲目 retry 聪明
三级 merge global-agent-role，mergeExtractConfig 29 行覆盖所有 case
Kernel 集成最小化 — reloadConfig 时 rebuild registry + log，running threads 不受影响
nerve validate — regex 扫描 workflow source agent 引用，检查 adapter type + extract，fail early
测试覆盖充分 — extract retry、merge 各层组合、validate、kernel reload 都有覆盖

💡 Minor（不阻塞）

KNOWN_AGENT_ADAPTER_IDS 目前只有 echo，加 cursor/hermes/codex 时记得同步
collectWorkflowSpecAgentReferences regex 匹配可能误报注释，当前够用
ZodMetaSchema 的 zod in schema 检查建议移到 compile 入口做一次性校验

Reviewed by 小墨

## ✅ Hermes Agent Review — APPROVED ### 总评 RFC-003 Phase 1-5 实现质量很高，架构层次清晰，与 RFC 设计完全对齐。42 个文件改动量合理，每个 Phase 边界分明。 ### ✅ 亮点 - **类型设计精准** — AgentFn、WorkflowContext（含 workdir + AbortSignal）、ExtractFn、ExtractError 都到位，Schema witness pattern 巧妙 - **AgentRegistry 简洁** — Map-based lookup，get/getAgentConfig 分离，immutable after creation - **compile-workflow-spec** — AbortSignal.any() 组合 user cancel + timeout；两层 timeout resolution 干净 - **Extract retry 策略** — retry 时把 error 注入 user message 让 LLM 自我修正，比盲目 retry 聪明 - **三级 merge** global-agent-role，mergeExtractConfig 29 行覆盖所有 case - **Kernel 集成最小化** — reloadConfig 时 rebuild registry + log，running threads 不受影响 - **nerve validate** — regex 扫描 workflow source agent 引用，检查 adapter type + extract，fail early - **测试覆盖充分** — extract retry、merge 各层组合、validate、kernel reload 都有覆盖 ### 💡 Minor（不阻塞） 1. KNOWN_AGENT_ADAPTER_IDS 目前只有 echo，加 cursor/hermes/codex 时记得同步 2. collectWorkflowSpecAgentReferences regex 匹配可能误报注释，当前够用 3. ZodMetaSchema 的 zod in schema 检查建议移到 compile 入口做一次性校验 --- *Reviewed by 小墨*

xiaomo merged commit 3d89fc4a7a into main

2026-04-29 05:31:58 +00:00

xiaomo referenced this issue from a commit

2026-04-29 05:32:00 +00:00

Merge pull request 'feat: RFC-003 Agent Configuration Layer (Phase 1-5)' (#241) from feat/rfc-003-phase-1 into main

xiaoju referenced this issue from a commit

2026-04-29 05:42:15 +00:00

feat(cli,core): RFC-003 Phase 6 — Knowledge Layer + review fixes

xiaoju referenced this pull request

2026-04-29 05:42:26 +00:00

feat: RFC-003 Phase 6 — Knowledge Layer + Review Fixes #242

xiaoju referenced this pull request