Curator definitions: generic engine + tool-carrying passes (code/config sources) #483

Closed
opened 2026-10-27 13:36:30 +00:00 by sam · 0 comments
Owner

Close the load-bearing gap that makes every other part of this epic possible: a curator cannot declare a tool set today.

curator.Manifest.Tools exists and Registrar.Tools ToolBuilder is declared, but no ToolBuilder implementation exists anywhere in the repo, and bootstrap.go builds the Registrar without a Tools field. registry.go therefore returns "curator manifest: declares tools but the registrar has no ToolBuilder" for any curator that declares tools, so declaring one fails registration outright. The daemon's curatorLLMRunner is also text-only: curator.ChatRequest carries Tools []tools.ToolEntry and MaxSteps, but the adapter passes neither into core.GenerateOptions.

This child also ships the generic engine and the first definition source, so that a curator can be defined as data end to end:

  • ToolBuilder implementation over the shared tool registry, so the declared set is resolved by name and nothing outside it is returned. Reuse the existing agentexec.BuildToolSetFrom(entries, opts) conversion to core.ToolSet rather than writing a second converter.
  • Tool-carrying runner: curatorLLMRunner passes the declared tools and the declared step budget into core.GenerateOptions (the ai-sdk runtime already executes the tool loop); ChatResult is widened only as needed to attribute what the pass did.
  • Generic definition-driven engine: one engine that interprets a definition (declared shape + free-form instructions) and runs a pass through the bound Registrar, recording an Action per pass.
  • [[curators]] config definitions: the definition is read from config at startup and registered through the same generic engine, with no defaults injected for interval, cooldown, tools, model, or memory engine.
  • Idle visibility: when a curator's Check returns not-due, log the decision, so a healthy-but-idle curator is not invisible (the session-memory curator's hourly pass is the only curator activity ever logged today).

Non-goals

  • No persistence of definitions and no REST/API mutation -- that is the later persisted-definitions child.
  • No forge issue tools; the motivating consumer's tools belong to the existing tools work.
  • No change to the sampler family, the two shipped reference curators' pass logic, or failure isolation.

Acceptance criteria

  1. A curator that declares tools: ["read", "write"] reaches exactly those tools; a declared name with no implementation fails the pass rather than silently running with fewer tools.
  2. A tools-declaring curator still fails registration when no ToolBuilder is bound (the existing guard must keep working).
  3. curatorLLMRunner passes declared tools and step budget to the model runtime; a test proves the tools reach core.GenerateOptions and that the text-only path is unchanged when no tools are declared.
  4. A curator defined entirely in config (interval, tools, model, instructions) runs through the generic engine with no code specific to it, with no pass-time fallback to a code constant.
  5. A definition missing interval is refused with a clear error, not defaulted.
  6. A curator whose Check returns not-due logs why, so an idle-but-healthy curator is observable.

Security and failure paths

  • Tool resolution fails closed: unknown names fail the pass; the pass's tool set is built from the declared list, never from the broader registry.
  • The generic engine receives exactly the registrar view its manifest declares -- it must not gain reach the typed contract does not grant.
  • A failing or unknown-tool pass affects only that curator.

Dependencies

  • None shipping; this is the prerequisite for the rest of the epic. docs/prds/dynamic-curators.md is the settled design.

Implementation status (audit-verified 2026-09-12)

Confirms the problem statement above with independently verified evidence:

  • ToolBuilder: declared at internal/domain/curator/registrar.go:86. The only other reference repo-wide is the fail-closed guard at internal/domain/curator/registry.go:123. No implementation exists. bootstrap.go:1000-1022 constructs the Registrar with no Tools field.
  • curatorLLMRunner at internal/app/archied/main.go:551: builds core.GenerateOptions{Messages: msgs, MaxSteps: max(...)}. curator.ChatRequest.Tools is never passed. Confirms the text-only path.
  • These are two independent blockers. Binding ToolBuilder alone still produces tool-less passes.
  • The two shipped reference curators (skillcurator, sessioncurator) both declare zero tools, so neither exercises the guard — the failure mode is latent, not surfaced by current usage.

Merged from the other tracker

Phase 1. Close the load-bearing gap: ToolBuilder implementation (declared tools resolve, nothing outside the set), curatorLLMRunner passes Tools+MaxSteps into core.GenerateOptions, one generic definition-driven engine (Manifest + free-form instructions), curators config definitions, idle logging when Check returns not-due.

Acceptance: a curator declaring tools reaches exactly those; unknown declared name fails the pass; tools-declaring curator still refuses registration with no ToolBuilder bound; a fully config-defined curator runs with no pass-time fallback to a code constant; a definition missing interval is refused, not defaulted.

Security/failure: tool resolution fails closed; generic engine gets only its declared registrar view; a failing pass affects that curator only.

Deps: none shipping (this is the prerequisite). GitHub: #790. Design: docs/prds/dynamic-curators.md.

Notes

CORRECTION (2026-09-12): the 'forge issue tools are a blocker' finding was wrong. No dedicated issue tool exists and no MCP server was ever configured, BUT the chat agent's is unconfined (chat.unrestricted_filesystem=true), so already works. Dedicated tools (#161) are convenience, not a prerequisite. VERIFIED STATE: (1) ToolBuilder has NO implementation anywhere - only the interface decl at domain/curator/registrar.go:86 and the fail-closed guard at registry.go:123; bootstrap.go builds the Registrar with no Tools field. (2) curatorLLMRunner at app/archied/main.go:551 drops ChatRequest.Tools - a SECOND independent blocker; fixing ToolBuilder alone still yields tool-less passes. (3) No definition persistence, no Unregister, no Runtime.Add/Remove. (4) runtime.go:202-211 logs nothing on not-due, so the skill curator's absence from logs is indistinguishable from health. EVIDENCE: standalone prototype at ~/projects/issue-orchestrator drove a real tool loop against live GitHub issues with local model defiant-fable-q6: 3 issues, 2 model steps, ~60s. Proof the loop works on local HW.

Close reason

Shipped in 60f04a35 (ancestor of main): all five Phase-1 curator items are live - toolbuilder.New resolves exactly the declared set (internal/infrastructure/toolbuilder/toolbuilder.go:36-48), curatorLLMRunner passes Tools+MaxSteps (app/archied/main.go:533-534), generic definition-driven engine (domain/curator/definition_engine.go), curators config consumed at bootstrap.go:1357-1385, and idle logging when Check reports not-due (runtime.go:211). Tests TestBuilderResolvesExactlyDeclared, TestDefinitionEnginePassReachesExactlyDeclaredTools, TestRuntimeLogsWhenCheckReportsNotDue, TestValidateCurators. Dynamic mutation is carved out to trnd.2/trnd.3.


Imported from beads archie-core-trnd.1 · GitHub #799 · body merged from the fuller GitHub #790 · type task · priority P1 · created 2026-09-12 · closed 2026-10-02

Close the load-bearing gap that makes every other part of this epic possible: **a curator cannot declare a tool set today.** `curator.Manifest.Tools` exists and `Registrar.Tools ToolBuilder` is declared, but no `ToolBuilder` implementation exists anywhere in the repo, and `bootstrap.go` builds the `Registrar` without a `Tools` field. `registry.go` therefore returns `"curator manifest: declares tools but the registrar has no ToolBuilder"` for any curator that declares tools, so declaring one fails registration outright. The daemon's `curatorLLMRunner` is also text-only: `curator.ChatRequest` carries `Tools []tools.ToolEntry` and `MaxSteps`, but the adapter passes neither into `core.GenerateOptions`. This child also ships the generic engine and the first definition source, so that a curator can be defined as data end to end: - **ToolBuilder implementation** over the shared tool registry, so the declared set is resolved by name and nothing outside it is returned. Reuse the existing `agentexec.BuildToolSetFrom(entries, opts)` conversion to `core.ToolSet` rather than writing a second converter. - **Tool-carrying runner**: `curatorLLMRunner` passes the declared tools and the declared step budget into `core.GenerateOptions` (the ai-sdk runtime already executes the tool loop); `ChatResult` is widened only as needed to attribute what the pass did. - **Generic definition-driven engine**: one engine that interprets a definition (declared shape + free-form instructions) and runs a pass through the bound `Registrar`, recording an `Action` per pass. - **`[[curators]]` config definitions**: the definition is read from config at startup and registered through the same generic engine, with no defaults injected for interval, cooldown, tools, model, or memory engine. - **Idle visibility**: when a curator's `Check` returns not-due, log the decision, so a healthy-but-idle curator is not invisible (the session-memory curator's hourly pass is the only curator activity ever logged today). ### Non-goals - No persistence of definitions and no REST/API mutation -- that is the later persisted-definitions child. - No forge issue tools; the motivating consumer's tools belong to the existing tools work. - No change to the sampler family, the two shipped reference curators' pass logic, or failure isolation. ### Acceptance criteria 1. A curator that declares `tools: ["read", "write"]` reaches exactly those tools; a declared name with no implementation fails the pass rather than silently running with fewer tools. 2. A tools-declaring curator still fails registration when no `ToolBuilder` is bound (the existing guard must keep working). 3. `curatorLLMRunner` passes declared tools and step budget to the model runtime; a test proves the tools reach `core.GenerateOptions` and that the text-only path is unchanged when no tools are declared. 4. A curator defined entirely in config (interval, tools, model, instructions) runs through the generic engine with no code specific to it, with no pass-time fallback to a code constant. 5. A definition missing `interval` is refused with a clear error, not defaulted. 6. A curator whose `Check` returns not-due logs why, so an idle-but-healthy curator is observable. ### Security and failure paths - Tool resolution fails closed: unknown names fail the pass; the pass's tool set is built from the declared list, never from the broader registry. - The generic engine receives exactly the registrar view its manifest declares -- it must not gain reach the typed contract does not grant. - A failing or unknown-tool pass affects only that curator. ### Dependencies - None shipping; this is the prerequisite for the rest of the epic. `docs/prds/dynamic-curators.md` is the settled design. ### Implementation status (audit-verified 2026-09-12) Confirms the problem statement above with independently verified evidence: - `ToolBuilder`: declared at `internal/domain/curator/registrar.go:86`. The only other reference repo-wide is the fail-closed guard at `internal/domain/curator/registry.go:123`. No implementation exists. `bootstrap.go:1000-1022` constructs the `Registrar` with no `Tools` field. - `curatorLLMRunner` at `internal/app/archied/main.go:551`: builds `core.GenerateOptions{Messages: msgs, MaxSteps: max(...)}`. `curator.ChatRequest.Tools` is never passed. Confirms the text-only path. - These are two independent blockers. Binding `ToolBuilder` alone still produces tool-less passes. - The two shipped reference curators (`skillcurator`, `sessioncurator`) both declare zero tools, so neither exercises the guard — the failure mode is latent, not surfaced by current usage. ### Merged from the other tracker Phase 1. Close the load-bearing gap: ToolBuilder implementation (declared tools resolve, nothing outside the set), curatorLLMRunner passes Tools+MaxSteps into core.GenerateOptions, one generic definition-driven engine (Manifest + free-form instructions), [[curators]] config definitions, idle logging when Check returns not-due. Acceptance: a curator declaring tools reaches exactly those; unknown declared name fails the pass; tools-declaring curator still refuses registration with no ToolBuilder bound; a fully config-defined curator runs with no pass-time fallback to a code constant; a definition missing interval is refused, not defaulted. Security/failure: tool resolution fails closed; generic engine gets only its declared registrar view; a failing pass affects that curator only. Deps: none shipping (this is the prerequisite). GitHub: #790. Design: docs/prds/dynamic-curators.md. ### Notes CORRECTION (2026-09-12): the 'forge issue tools are a blocker' finding was wrong. No dedicated issue tool exists and no MCP server was ever configured, BUT the chat agent's is unconfined (chat.unrestricted_filesystem=true), so already works. Dedicated tools (#161) are convenience, not a prerequisite. VERIFIED STATE: (1) ToolBuilder has NO implementation anywhere - only the interface decl at domain/curator/registrar.go:86 and the fail-closed guard at registry.go:123; bootstrap.go builds the Registrar with no Tools field. (2) curatorLLMRunner at app/archied/main.go:551 drops ChatRequest.Tools - a SECOND independent blocker; fixing ToolBuilder alone still yields tool-less passes. (3) No definition persistence, no Unregister, no Runtime.Add/Remove. (4) runtime.go:202-211 logs nothing on not-due, so the skill curator's absence from logs is indistinguishable from health. EVIDENCE: standalone prototype at ~/projects/issue-orchestrator drove a real tool loop against live GitHub issues with local model defiant-fable-q6: 3 issues, 2 model steps, ~60s. Proof the loop works on local HW. ### Close reason Shipped in 60f04a35 (ancestor of main): all five Phase-1 curator items are live - toolbuilder.New resolves exactly the declared set (internal/infrastructure/toolbuilder/toolbuilder.go:36-48), curatorLLMRunner passes Tools+MaxSteps (app/archied/main.go:533-534), generic definition-driven engine (domain/curator/definition_engine.go), [[curators]] config consumed at bootstrap.go:1357-1385, and idle logging when Check reports not-due (runtime.go:211). Tests TestBuilderResolvesExactlyDeclared, TestDefinitionEnginePassReachesExactlyDeclaredTools, TestRuntimeLogsWhenCheckReportsNotDue, TestValidateCurators. Dynamic mutation is carved out to trnd.2/trnd.3. --- _Imported from beads `archie-core-trnd.1` · GitHub #799 · body merged from the fuller GitHub #790 · type task · priority P1 · created 2026-09-12 · closed 2026-10-02_
sam added the hightask labels 2026-10-27 13:36:30 +00:00
sam self-assigned this 2026-10-27 13:36:30 +00:00
sam closed this issue 2026-10-27 13:36:30 +00:00
sam added a new dependency 2026-10-27 13:41:40 +00:00
sam added a new dependency 2026-10-27 13:42:06 +00:00
sam added a new dependency 2026-11-14 14:45:08 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#483