refactor(nats): rebuild as infrastructure/eventbus/nats with real boundaries

Relocating internal/nats as-is would have cemented its problems into the
approved layout, so this is a rewrite rather than a move.

What was wrong:
- Conn() *nats.Conn, PublishMsg(*nats.Msg) and Fetch() jetstream.Msg pushed
  SDK types into all four consumers, so the broker was not replaceable --
  the opposite of what dependencies-and-contracts.md requires.
- PublishTask took seven positional parameters, six of them strings, where a
  transposed argument was a silent bug.
- Labels travelled as a comma-separated string and were re-split on every
  publish.
- Fetch returned (nil, nil) for 'no message', which every caller had to
  remember to special-case.
- The logger field was stored and never used.
- Stream name, consumer name and every timeout were hardcoded constants.
- Errors were inconsistently wrapped; several paths returned bare errors.
- Connect repeated nc.Close() on each failure branch.

What replaces it:
- One concern per file: config, errors, subjects, message, client,
  publisher, consumer.
- Publisher/Consumer/Requester interfaces with compile-time assertions, so
  callers depend on behaviour and can be faked without a broker.
- A Message wrapper keeps jetstream types behind the boundary; consumers no
  longer import the NATS SDK at all.
- TaskEnvelope with []string labels and JSON methods preserving the
  comma-separated wire form for already-queued messages.
- Sentinel errors (ErrNoMessage, ErrNotConnected, ErrNoReplyAddress,
  ErrInvalidConfig) and %w wrapping with operation context throughout.
- Config with validation and defaults; a single deferred cleanup in Connect.
- CoreConn() as the one documented escape hatch, for the *rpc packages that
  are themselves NATS infrastructure.

Consumers migrated: cmd/archied, cmd/archie-agent, internal/daemon,
internal/agentexec. Behaviour, subjects and wire format unchanged.
This commit is contained in:
sam committed 2026-07-29 10:19:09 +10:00
1 parent 676ad3fe48
commit 492ca209f9
19 files changed
+805 -574

No files matched your search

+5
View File
@@ -214,3 +214,8 @@
{"id":"int-ac4986c5a4bbcce5a0e6c433a27200bb","kind":"field_change","created_at":"2026-07-28T23:56:02.19240915Z","actor":"Sam Catlow","issue_id":"archie-core-qa4.3","extra":{"field":"status","new_value":"open","old_value":"closed"}} {"id":"int-ac4986c5a4bbcce5a0e6c433a27200bb","kind":"field_change","created_at":"2026-07-28T23:56:02.19240915Z","actor":"Sam Catlow","issue_id":"archie-core-qa4.3","extra":{"field":"status","new_value":"open","old_value":"closed"}}
{"id":"int-b7346a3255f018abd02be2fc2a95608e","kind":"field_change","created_at":"2026-07-28T23:56:03.016873405Z","actor":"Sam Catlow","issue_id":"archie-core-qa4.4","extra":{"field":"status","new_value":"open","old_value":"closed"}} {"id":"int-b7346a3255f018abd02be2fc2a95608e","kind":"field_change","created_at":"2026-07-28T23:56:03.016873405Z","actor":"Sam Catlow","issue_id":"archie-core-qa4.4","extra":{"field":"status","new_value":"open","old_value":"closed"}}
{"id":"int-022fc3fc6a77da64b290b47d235147db","kind":"field_change","created_at":"2026-07-28T23:56:03.389443421Z","actor":"Sam Catlow","issue_id":"archie-core-24g","extra":{"field":"status","new_value":"open","old_value":"closed"}} {"id":"int-022fc3fc6a77da64b290b47d235147db","kind":"field_change","created_at":"2026-07-28T23:56:03.389443421Z","actor":"Sam Catlow","issue_id":"archie-core-24g","extra":{"field":"status","new_value":"open","old_value":"closed"}}
{"id":"int-66f1c602101cca1055897203b9ddc36a","kind":"field_change","created_at":"2026-07-29T00:06:36.960641889Z","actor":"Sam Catlow","issue_id":"archie-core-o3l","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
{"id":"int-7ac2caef3cada29de07b090b07c48834","kind":"field_change","created_at":"2026-07-29T00:10:45.782637298Z","actor":"Sam Catlow","issue_id":"archie-core-qa4.3","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
{"id":"int-d2b3b90cb93d38eb23d3d2120738768a","kind":"field_change","created_at":"2026-07-29T00:13:03.819548678Z","actor":"Sam Catlow","issue_id":"archie-core-vq4","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
{"id":"int-fc8b703ac5f77deef0c0fa7fa4c6fd91","kind":"field_change","created_at":"2026-07-29T00:14:32.561829752Z","actor":"Sam Catlow","issue_id":"archie-core-24g","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Completed"}}
{"id":"int-121dfb79c17bb556e48b19bbfe6c1b0d","kind":"field_change","created_at":"2026-07-29T00:15:26.026966964Z","actor":"Sam Catlow","issue_id":"archie-core-qa4.4","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+5 -3
View File
@@ -53,12 +53,14 @@
{"_type":"issue","id":"archie-core-abg.18","title":"[EPIC] Memory: pluggable provider architecture with file-backed persistence","description":"Pluggable memory system to match Hermes parity:\\n\\n1. **MemoryProvider interface**: Abstract interface with methods for initialize(), get_tool_schemas(), prefetch(), sync_turn(), and optional lifecycle hooks (on_session_end, on_session_switch, on_pre_compress, on_memory_write).\\n\\n2. **Built-in file-backed memory**: MEMORY.md and USER.md stored per-session/profile. LLM-callable memory tool with add/replace/remove actions. Frozen snapshot at session start (preserves prefix cache), immediate disk write on updates. Section-sign delimited entries with substring matching.\\n\\n3. **MemoryManager**: Orchestrates built-in + at most one external provider. Background serialized write executor. Prefetch with timeout (8s). Streaming context scrubber that strips injected memory spans from model output.\\n\\nRef: docs/prds/hermes-gap-analysis.md section 4","acceptance_criteria":"An external memory provider (e.g. Honcho, Mem0) can be plugged in via config. The built-in memory tool persists across sessions. Conversation context is recalled on session resume.","status":"closed","priority":0,"issue_type":"epic","owner":"sam@catlow.tech","created_at":"2026-07-25T14:02:22Z","created_by":"Sam Catlow","updated_at":"2026-07-28T17:04:41Z","closed_at":"2026-07-28T17:04:41Z","close_reason":"Superseded by merged work: all 32 children complete (32/32, bd flags it 'eligible for close'). MemoryProvider interface, built-in file-backed memory, MemoryManager, scrubber, drain and threat scanning all landed in internal/memory. Nothing left in scope.","dependencies":[{"issue_id":"archie-core-abg.18","depends_on_id":"archie-core-abg","type":"parent-child","created_at":"2026-07-26T00:02:22Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-abg.18","title":"[EPIC] Memory: pluggable provider architecture with file-backed persistence","description":"Pluggable memory system to match Hermes parity:\\n\\n1. **MemoryProvider interface**: Abstract interface with methods for initialize(), get_tool_schemas(), prefetch(), sync_turn(), and optional lifecycle hooks (on_session_end, on_session_switch, on_pre_compress, on_memory_write).\\n\\n2. **Built-in file-backed memory**: MEMORY.md and USER.md stored per-session/profile. LLM-callable memory tool with add/replace/remove actions. Frozen snapshot at session start (preserves prefix cache), immediate disk write on updates. Section-sign delimited entries with substring matching.\\n\\n3. **MemoryManager**: Orchestrates built-in + at most one external provider. Background serialized write executor. Prefetch with timeout (8s). Streaming context scrubber that strips injected memory spans from model output.\\n\\nRef: docs/prds/hermes-gap-analysis.md section 4","acceptance_criteria":"An external memory provider (e.g. Honcho, Mem0) can be plugged in via config. The built-in memory tool persists across sessions. Conversation context is recalled on session resume.","status":"closed","priority":0,"issue_type":"epic","owner":"sam@catlow.tech","created_at":"2026-07-25T14:02:22Z","created_by":"Sam Catlow","updated_at":"2026-07-28T17:04:41Z","closed_at":"2026-07-28T17:04:41Z","close_reason":"Superseded by merged work: all 32 children complete (32/32, bd flags it 'eligible for close'). MemoryProvider interface, built-in file-backed memory, MemoryManager, scrubber, drain and threat scanning all landed in internal/memory. Nothing left in scope.","dependencies":[{"issue_id":"archie-core-abg.18","depends_on_id":"archie-core-abg","type":"parent-child","created_at":"2026-07-26T00:02:22Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-abg.16","title":"[EPIC] Gateway: rich message model, adapter lifecycle, session management","description":"Foundational gateway infrastructure to match Hermes parity. Three interdependent pieces:\\n\\n1. **Message model**: Replace the 3-field Message struct with a rich MessageEvent (MessageType enum: text/photo/video/audio/voice/document/sticker/command, media_urls, reply_to context, metadata dict, source). This is the wire type every adapter produces.\\n\\n2. **Adapter lifecycle**: Replace the 3-method Gateway interface with a BasePlatformAdapter interface: connect()/disconnect()/send() as required methods, plus optional overrides for typing indicators, edit/delete, image/voice/video/document send, interactive UX (clarify buttons, approval dialogs). Capability flags (supports_code_blocks, splits_long_messages, supports_async_delivery).\\n\\n3. **Session management**: SessionSource struct (platform, chat_id, chat_type, user_id, thread_id, guild_id, profile), AsyncSessionStore for persistent session storage, SessionContext for system prompt injection.\\n\\nAll three blocks together enable adding new platforms as plugins without touching core gateway code.\\n\\nRef: docs/prds/hermes-gap-analysis.md sections 1-2","acceptance_criteria":"New adapters can be added by implementing a Go interface with connect/disconnect/send + optional media methods. Messages carry full metadata through the pipeline. Sessions persist across gateway restarts.","status":"open","priority":0,"issue_type":"epic","owner":"sam@catlow.tech","created_at":"2026-07-25T14:02:21Z","created_by":"Sam Catlow","updated_at":"2026-07-25T14:02:21Z","dependencies":[{"issue_id":"archie-core-abg.16","depends_on_id":"archie-core-abg","type":"parent-child","created_at":"2026-07-26T00:02:21Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-abg.16","title":"[EPIC] Gateway: rich message model, adapter lifecycle, session management","description":"Foundational gateway infrastructure to match Hermes parity. Three interdependent pieces:\\n\\n1. **Message model**: Replace the 3-field Message struct with a rich MessageEvent (MessageType enum: text/photo/video/audio/voice/document/sticker/command, media_urls, reply_to context, metadata dict, source). This is the wire type every adapter produces.\\n\\n2. **Adapter lifecycle**: Replace the 3-method Gateway interface with a BasePlatformAdapter interface: connect()/disconnect()/send() as required methods, plus optional overrides for typing indicators, edit/delete, image/voice/video/document send, interactive UX (clarify buttons, approval dialogs). Capability flags (supports_code_blocks, splits_long_messages, supports_async_delivery).\\n\\n3. **Session management**: SessionSource struct (platform, chat_id, chat_type, user_id, thread_id, guild_id, profile), AsyncSessionStore for persistent session storage, SessionContext for system prompt injection.\\n\\nAll three blocks together enable adding new platforms as plugins without touching core gateway code.\\n\\nRef: docs/prds/hermes-gap-analysis.md sections 1-2","acceptance_criteria":"New adapters can be added by implementing a Go interface with connect/disconnect/send + optional media methods. Messages carry full metadata through the pipeline. Sessions persist across gateway restarts.","status":"open","priority":0,"issue_type":"epic","owner":"sam@catlow.tech","created_at":"2026-07-25T14:02:21Z","created_by":"Sam Catlow","updated_at":"2026-07-25T14:02:21Z","dependencies":[{"issue_id":"archie-core-abg.16","depends_on_id":"archie-core-abg","type":"parent-child","created_at":"2026-07-26T00:02:21Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-jfg","title":"Spawned archie-agent containers not on daemon's docker network — can't reach NATS","description":"Root cause of 'agent still failing on the server': archied's container.Pool.Acquire creates archie-agent containers via the Docker SDK with no NetworkMode set, so Docker attaches them to the default bridge network. archied and nats run on the compose-created 'archie-core_default' network instead, so the spawned container's hostname resolution for 'nats' (from NATS_URL=nats://nats:4222) fails and archie-agent can't connect. Confirmed on carina host logs: archied logs show repeating 'taskrun request failed err=\"nats: no responders available for request\"' for every task, containers created and destroyed within ~1.5s (consistent with archie-agent's NATS client failing fast). Fixed by detecting the daemon's own container's network in NewPool (selfNetwork, via ContainerInspect on os.Hostname()) and setting HostConfig.NetworkMode on spawned containers to match.","status":"closed","priority":0,"issue_type":"bug","owner":"sam@catlow.tech","created_at":"2026-07-24T03:10:26Z","created_by":"Sam Catlow","updated_at":"2026-07-25T13:04:34Z","closed_at":"2026-07-25T13:04:34Z","close_reason":"Fix already implemented and verified: selfNetwork() in internal/container/pool.go detects the daemon's own container network via ContainerInspect(os.Hostname()) and Acquire() sets HostConfig.NetworkMode to match, so spawned archie-agent containers join the same compose network as nats. Build and internal/container tests pass.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-jfg","title":"Spawned archie-agent containers not on daemon's docker network — can't reach NATS","description":"Root cause of 'agent still failing on the server': archied's container.Pool.Acquire creates archie-agent containers via the Docker SDK with no NetworkMode set, so Docker attaches them to the default bridge network. archied and nats run on the compose-created 'archie-core_default' network instead, so the spawned container's hostname resolution for 'nats' (from NATS_URL=nats://nats:4222) fails and archie-agent can't connect. Confirmed on carina host logs: archied logs show repeating 'taskrun request failed err=\"nats: no responders available for request\"' for every task, containers created and destroyed within ~1.5s (consistent with archie-agent's NATS client failing fast). Fixed by detecting the daemon's own container's network in NewPool (selfNetwork, via ContainerInspect on os.Hostname()) and setting HostConfig.NetworkMode on spawned containers to match.","status":"closed","priority":0,"issue_type":"bug","owner":"sam@catlow.tech","created_at":"2026-07-24T03:10:26Z","created_by":"Sam Catlow","updated_at":"2026-07-25T13:04:34Z","closed_at":"2026-07-25T13:04:34Z","close_reason":"Fix already implemented and verified: selfNetwork() in internal/container/pool.go detects the daemon's own container network via ContainerInspect(os.Hostname()) and Acquire() sets HostConfig.NetworkMode to match, so spawned archie-agent containers join the same compose network as nats. Build and internal/container tests pass.","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-24g","title":"Trim the remaining agent skills to factual reference","description":"The .agents/skills/ library is 4283 lines across 12 skills. An audit found most carry useful facts buried in process ceremony. Five worst offenders were already parked at /work/apps/archie-skills-parked. Trim what remains to roughly 2200 lines total. KEEP: concrete commands, package anchors, config wiring tables, NellDB shapes, symptom-to-diagnostic indexes, known regressions, domain glossary, operational hazards, false-confidence warnings. CUT: mandated N-step procedures, handoff templates, evidence packets, acceptance checklists, ownership/deletion/rollback field lists, sibling-skill routing prose, repeated 'reject unless' instructions, dated tool snapshots. Preserve every skill's YAML frontmatter name and description. Do not delete any skill file outright.","acceptance_criteria":"Total line count of .agents/skills/*/*.md is between 1900 and 2500. All 12 skills still exist with valid frontmatter. No factual command, path, or table was lost - only procedure and ceremony. go build ./... still clean.","status":"open","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-28T17:18:09Z","created_by":"Sam Catlow","updated_at":"2026-07-28T23:56:03Z","started_at":"2026-07-28T17:18:44Z","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-o3l","title":"infrastructure/eventbus/nats: relocate NATS transport","description":"Create internal/infrastructure/eventbus/nats as a properly structured replacement for internal/nats. This is NOT a mechanical move: the existing code has no interfaces, leaks vendor types (Conn() *nats.Conn, PublishMsg(*nats.Msg), Fetch() jetstream.Msg) into all four consumers, uses a 7-positional-parameter publish with stringly-typed comma-separated labels, stores an unused logger, returns (nil, nil) for 'no message', and hardcodes stream/consumer/timeout config. Rebuild it with: separate files per concern; a Message wrapper so jetstream types stop crossing the boundary; Publisher/Consumer interfaces; a Config struct; sentinel errors; consistent %w wrapping; real logging. Then update cmd/archied, cmd/archie-agent, internal/daemon and internal/agentexec to the new API.","acceptance_criteria":"internal/nats no longer exists; internal/infrastructure/eventbus/nats has its contents. All imports updated. task check clean. Container and NATS behaviour unchanged.","status":"closed","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-29T00:02:50Z","created_by":"Sam Catlow","updated_at":"2026-07-29T00:14:19Z","started_at":"2026-07-29T00:04:35Z","closed_at":"2026-07-29T00:06:37Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-vq4","title":"infrastructure/configuration: external input boundary","description":"Read docs/architecture/configuration.md. Create internal/infrastructure/configuration as the external config input boundary. It owns TOML/YAML decoding, env and secret references, base/overlay precedence, compatibility aliases, input validation, and provenance. It must NOT own domain behaviour. Preserve current LoadOverlay behaviour exactly and keep every existing TOML field name working. Translate the decoded input into the current internal/config.Config shape at the composition boundary as an explicitly-marked temporary adapter, so runtime behaviour is unchanged. Do not migrate consumers in this bead.","acceptance_criteria":"internal/infrastructure/configuration exists and is the loader used by cmd/archied. Old config files still load with identical effective values. task check clean. No consumer outside cmd/archied changed. The temporary adapter carries a comment naming its deletion condition.","status":"closed","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-29T00:02:49Z","created_by":"Sam Catlow","updated_at":"2026-07-29T00:13:04Z","started_at":"2026-07-29T00:04:30Z","closed_at":"2026-07-29T00:13:04Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-24g","title":"Trim the remaining agent skills to factual reference","description":"The .agents/skills/ library is 4283 lines across 12 skills. An audit found most carry useful facts buried in process ceremony. Five worst offenders were already parked at /work/apps/archie-skills-parked. Trim what remains to roughly 2200 lines total. KEEP: concrete commands, package anchors, config wiring tables, NellDB shapes, symptom-to-diagnostic indexes, known regressions, domain glossary, operational hazards, false-confidence warnings. CUT: mandated N-step procedures, handoff templates, evidence packets, acceptance checklists, ownership/deletion/rollback field lists, sibling-skill routing prose, repeated 'reject unless' instructions, dated tool snapshots. Preserve every skill's YAML frontmatter name and description. Do not delete any skill file outright.","acceptance_criteria":"Total line count of .agents/skills/*/*.md is between 1900 and 2500. All 12 skills still exist with valid frontmatter. No factual command, path, or table was lost - only procedure and ceremony. go build ./... still clean.","status":"closed","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-28T17:18:09Z","created_by":"Sam Catlow","updated_at":"2026-07-29T00:14:32Z","started_at":"2026-07-28T17:18:44Z","closed_at":"2026-07-29T00:14:32Z","close_reason":"Completed","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-5d7.2","title":"Configuration boundary and ownership review","description":"Run the first focused architecture campaign for the configuration refactor. Trace the current TOML/YAML loaders, defaults, validation, overlays, secret references, identity/repository settings, worker snapshots, container/NATS passthrough, and every production consumer. Produce a field-level current-to-target ownership ledger and decide the smallest behavior-preserving migration slice. Do not edit runtime code until ownership, input DTO boundaries, provenance requirements, schema generation boundary, compatibility semantics, and deletion criteria are recorded.","acceptance_criteria":"A reproducible current-state trace covers entrypoints, loaders, consumers, process boundaries, tests, deployment passthrough, and decoded-but-unwired fields; every in-scope setting has one current owner, target owner, scope, validation/provenance behavior, and migration disposition; base/overlay and secret compatibility semantics are explicit; the first implementation slice has an observable outcome, bounded change cone, parity tests, rollback, and deletion criterion; no unresolved semantic decision is left for the implementer to invent.","notes":"Baseline: clean committed tree at d8f4a94b4679f1d7b15abfc6fbff1a2114fe0a2a (2026-07-29). Parent archie-core-5d7 remains in progress; docsgen child 5d7.1 is complete. Initial read-only inventory confirms production uses config.LoadOverlay in cmd/archied; feature LoadDir is tested but not selected by the daemon; TaskConfig.ForTask/ToConfig is a separate worker projection; Compose mounts base+docker TOML and passes a fixed environment allowlist. No runtime edits made in this review slice.","status":"closed","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-28T16:28:50Z","created_by":"Sam Catlow","updated_at":"2026-07-28T16:44:27Z","started_at":"2026-07-28T16:29:17Z","closed_at":"2026-07-28T16:44:27Z","close_reason":"Closing: architecture review campaign artifact. The architecture docs in docs/prds/architecture/ are complete and authoritative; no further planning/ledger work wanted.","labels":["architecture","configuration","migration"],"dependencies":[{"issue_id":"archie-core-5d7.2","depends_on_id":"archie-core-5d7","type":"parent-child","created_at":"2026-07-29T02:28:50Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-5d7.2","title":"Configuration boundary and ownership review","description":"Run the first focused architecture campaign for the configuration refactor. Trace the current TOML/YAML loaders, defaults, validation, overlays, secret references, identity/repository settings, worker snapshots, container/NATS passthrough, and every production consumer. Produce a field-level current-to-target ownership ledger and decide the smallest behavior-preserving migration slice. Do not edit runtime code until ownership, input DTO boundaries, provenance requirements, schema generation boundary, compatibility semantics, and deletion criteria are recorded.","acceptance_criteria":"A reproducible current-state trace covers entrypoints, loaders, consumers, process boundaries, tests, deployment passthrough, and decoded-but-unwired fields; every in-scope setting has one current owner, target owner, scope, validation/provenance behavior, and migration disposition; base/overlay and secret compatibility semantics are explicit; the first implementation slice has an observable outcome, bounded change cone, parity tests, rollback, and deletion criterion; no unresolved semantic decision is left for the implementer to invent.","notes":"Baseline: clean committed tree at d8f4a94b4679f1d7b15abfc6fbff1a2114fe0a2a (2026-07-29). Parent archie-core-5d7 remains in progress; docsgen child 5d7.1 is complete. Initial read-only inventory confirms production uses config.LoadOverlay in cmd/archied; feature LoadDir is tested but not selected by the daemon; TaskConfig.ForTask/ToConfig is a separate worker projection; Compose mounts base+docker TOML and passes a fixed environment allowlist. No runtime edits made in this review slice.","status":"closed","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-28T16:28:50Z","created_by":"Sam Catlow","updated_at":"2026-07-28T16:44:27Z","started_at":"2026-07-28T16:29:17Z","closed_at":"2026-07-28T16:44:27Z","close_reason":"Closing: architecture review campaign artifact. The architecture docs in docs/prds/architecture/ are complete and authoritative; no further planning/ledger work wanted.","labels":["architecture","configuration","migration"],"dependencies":[{"issue_id":"archie-core-5d7.2","depends_on_id":"archie-core-5d7","type":"parent-child","created_at":"2026-07-29T02:28:50Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-6pp","title":"Remove source-project references from Archie","description":"Remove every tau reference outside the explicitly preserved Beads data and docs-2/README.md. Delete copied product-specific documentation and accompanied rationale rather than mechanically renaming it. Retain reusable documentation-generation and VitePress scaffolding only after removing source-specific coupling. Update code, tests, archives, and architecture documents so archie-core contains no unauthorized tau references.","acceptance_criteria":"rg 'tau' -ow excluding .beads/** and docs-2/README.md returns zero; retained tools and documentation scaffolding contain no source-project imports, paths, product claims, or rationale; relevant validation passes.","notes":"Complete. Exact case-insensitive whole-word scan excluding .git/**, .beads/**, and docs-2/README.md returns 0. Source-specific provenance and rationale removed, neutral fixtures preserve behavior, docs workflow/site build from docs-2, retained README excluded from publication, and Archie-owned docsgen generates current agent contracts without process-global cwd mutation. tools tests/vet pass; affected package tests pass; VitePress production build passes. Fresh adversarial review reports zero surviving findings. Full task check passes fmt/go-fix/vet/build and all packages except unrelated pre-existing internal/skillscript TestRunWrapsExternalCommand (Run returned newline).","status":"closed","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-28T08:00:32Z","created_by":"Sam Catlow","updated_at":"2026-07-28T08:35:55Z","started_at":"2026-07-28T08:00:37Z","closed_at":"2026-07-28T08:35:55Z","close_reason":"Removed all unauthorized source-project references and accompanying rationale; validation and independent review complete.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-6pp","title":"Remove source-project references from Archie","description":"Remove every tau reference outside the explicitly preserved Beads data and docs-2/README.md. Delete copied product-specific documentation and accompanied rationale rather than mechanically renaming it. Retain reusable documentation-generation and VitePress scaffolding only after removing source-specific coupling. Update code, tests, archives, and architecture documents so archie-core contains no unauthorized tau references.","acceptance_criteria":"rg 'tau' -ow excluding .beads/** and docs-2/README.md returns zero; retained tools and documentation scaffolding contain no source-project imports, paths, product claims, or rationale; relevant validation passes.","notes":"Complete. Exact case-insensitive whole-word scan excluding .git/**, .beads/**, and docs-2/README.md returns 0. Source-specific provenance and rationale removed, neutral fixtures preserve behavior, docs workflow/site build from docs-2, retained README excluded from publication, and Archie-owned docsgen generates current agent contracts without process-global cwd mutation. tools tests/vet pass; affected package tests pass; VitePress production build passes. Fresh adversarial review reports zero surviving findings. Full task check passes fmt/go-fix/vet/build and all packages except unrelated pre-existing internal/skillscript TestRunWrapsExternalCommand (Run returned newline).","status":"closed","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-28T08:00:32Z","created_by":"Sam Catlow","updated_at":"2026-07-28T08:35:55Z","started_at":"2026-07-28T08:00:37Z","closed_at":"2026-07-28T08:35:55Z","close_reason":"Removed all unauthorized source-project references and accompanying rationale; validation and independent review complete.","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-5d7","title":"Define target project organisation and restructuring rules","description":"Run a package-by-package architecture grilling session, establish the target DDD and semi-microservice organisation, record strict restructuring requirements and package destinations, and produce docs/prds/01-project-management.md as the durable handoff.","acceptance_criteria":"The PRD records agreed project-wide organisation rules, bounded-context and service/plugin boundaries, dependency constraints, migration principles, and the destination of each reviewed package. Decisions are confirmed one at a time with the user before the document is finalized.","notes":"Corrected generated-documentation.md to the agreed architecture: production code/registries/config/CLI are authoritative; docsgen emits deterministic JSON data and protocol schemas only; typed VitePress data loaders/components/templates own page rendering; generated Markdown is prohibited. First implementation slice tracked and completed as archie-core-5d7.1.","status":"closed","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-28T00:00:36Z","created_by":"Sam Catlow","updated_at":"2026-07-28T16:44:28Z","started_at":"2026-07-28T00:00:42Z","closed_at":"2026-07-28T16:44:28Z","close_reason":"Closing: the target organisation is already documented in docs/prds/architecture/. Reopen only when implementing a specific slice, not to plan further.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-5d7","title":"Define target project organisation and restructuring rules","description":"Run a package-by-package architecture grilling session, establish the target DDD and semi-microservice organisation, record strict restructuring requirements and package destinations, and produce docs/prds/01-project-management.md as the durable handoff.","acceptance_criteria":"The PRD records agreed project-wide organisation rules, bounded-context and service/plugin boundaries, dependency constraints, migration principles, and the destination of each reviewed package. Decisions are confirmed one at a time with the user before the document is finalized.","notes":"Corrected generated-documentation.md to the agreed architecture: production code/registries/config/CLI are authoritative; docsgen emits deterministic JSON data and protocol schemas only; typed VitePress data loaders/components/templates own page rendering; generated Markdown is prohibited. First implementation slice tracked and completed as archie-core-5d7.1.","status":"closed","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-28T00:00:36Z","created_by":"Sam Catlow","updated_at":"2026-07-28T16:44:28Z","started_at":"2026-07-28T00:00:42Z","closed_at":"2026-07-28T16:44:28Z","close_reason":"Closing: the target organisation is already documented in docs/prds/architecture/. Reopen only when implementing a specific slice, not to plan further.","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-qa4.4","title":"Phase 4: structural refactor (~28 issues)","description":"funlen, gocognit, cyclop, nestif, maintidx, interfacebloat. This IS the internal/config restructure already discussed (finalize at cognitive complexity 106, feature_config loadDirInto at 74) plus daemon process/checkWaiting. MUST BE LAST: refactoring moves line numbers and invalidates every other phase in flight. Fold into the config file-per-responsibility split rather than doing the same work twice.","status":"open","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-27T15:23:01Z","created_by":"Sam Catlow","updated_at":"2026-07-28T23:56:03Z","started_at":"2026-07-28T17:28:01Z","dependencies":[{"issue_id":"archie-core-qa4.4","depends_on_id":"archie-core-qa4","type":"parent-child","created_at":"2026-07-28T01:23:00Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-qa4.4","title":"Phase 4: structural refactor (~28 issues)","description":"funlen, gocognit, cyclop, nestif, maintidx, interfacebloat. This IS the internal/config restructure already discussed (finalize at cognitive complexity 106, feature_config loadDirInto at 74) plus daemon process/checkWaiting. MUST BE LAST: refactoring moves line numbers and invalidates every other phase in flight. Fold into the config file-per-responsibility split rather than doing the same work twice.","status":"closed","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-27T15:23:01Z","created_by":"Sam Catlow","updated_at":"2026-07-29T00:15:26Z","started_at":"2026-07-28T17:28:01Z","closed_at":"2026-07-29T00:15:26Z","close_reason":"Closed","dependencies":[{"issue_id":"archie-core-qa4.4","depends_on_id":"archie-core-qa4","type":"parent-child","created_at":"2026-07-28T01:23:00Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-qa4.3","title":"Phase 3: correctness findings needing judgement (~62 issues)","description":"nilerr (11: 6 in internal/agentexec inprocess.go/worker.go, 2 gateway), bodyclose (1), contextcheck (7), containedctx (2), fatcontext. SINGLE SESSION, sequential, no subagents: each nilerr site needs a read of whether the swallow is deliberate degradation or a real bug, and a context-free worker will silently convert deliberate behaviour into a change. Do nilerr FIRST -- highest bug probability in the whole set. BLOCKED on a policy decision for noctx (41 sites, mostly webui/worktree/store): fixing it means threading context through public APIs, which is an API change, not a lint fix.","status":"open","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-27T15:23:00Z","created_by":"Sam Catlow","updated_at":"2026-07-28T23:56:02Z","started_at":"2026-07-28T17:27:59Z","dependencies":[{"issue_id":"archie-core-qa4.3","depends_on_id":"archie-core-qa4","type":"parent-child","created_at":"2026-07-28T01:23:00Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-qa4.3","title":"Phase 3: correctness findings needing judgement (~62 issues)","description":"nilerr (11: 6 in internal/agentexec inprocess.go/worker.go, 2 gateway), bodyclose (1), contextcheck (7), containedctx (2), fatcontext. SINGLE SESSION, sequential, no subagents: each nilerr site needs a read of whether the swallow is deliberate degradation or a real bug, and a context-free worker will silently convert deliberate behaviour into a change. Do nilerr FIRST -- highest bug probability in the whole set. BLOCKED on a policy decision for noctx (41 sites, mostly webui/worktree/store): fixing it means threading context through public APIs, which is an API change, not a lint fix.","status":"closed","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-27T15:23:00Z","created_by":"Sam Catlow","updated_at":"2026-07-29T00:10:46Z","started_at":"2026-07-28T17:27:59Z","closed_at":"2026-07-29T00:10:46Z","close_reason":"Closed","dependencies":[{"issue_id":"archie-core-qa4.3","depends_on_id":"archie-core-qa4","type":"parent-child","created_at":"2026-07-28T01:23:00Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-qa4.1","title":"Phase 1: autofix pass (~35 issues)","description":"golangci-lint run --fix plus the formatters. Covers errorlint, fatcontext, gocritic, sloglint, usestdlibvars, usetesting, gci, gofumpt, goimports. Zero judgement. MUST run first: it touches formatting across every file and would conflict with anything in flight. Single command, single commit, verify with task check.","status":"closed","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-27T15:22:59Z","created_by":"Sam Catlow","updated_at":"2026-07-28T17:23:59Z","started_at":"2026-07-28T17:18:45Z","closed_at":"2026-07-28T17:23:59Z","close_reason":"Closed","dependencies":[{"issue_id":"archie-core-qa4.1","depends_on_id":"archie-core-qa4","type":"parent-child","created_at":"2026-07-28T01:22:58Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-qa4.1","title":"Phase 1: autofix pass (~35 issues)","description":"golangci-lint run --fix plus the formatters. Covers errorlint, fatcontext, gocritic, sloglint, usestdlibvars, usetesting, gci, gofumpt, goimports. Zero judgement. MUST run first: it touches formatting across every file and would conflict with anything in flight. Single command, single commit, verify with task check.","status":"closed","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-27T15:22:59Z","created_by":"Sam Catlow","updated_at":"2026-07-28T17:23:59Z","started_at":"2026-07-28T17:18:45Z","closed_at":"2026-07-28T17:23:59Z","close_reason":"Closed","dependencies":[{"issue_id":"archie-core-qa4.1","depends_on_id":"archie-core-qa4","type":"parent-child","created_at":"2026-07-28T01:22:58Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-qa4.2","title":"Phase 2: mechanical per-package fixes (~40 issues)","description":"forcetypeassert (24, internal/tools 20 + internal/memory 2, nearly all tests), predeclared (9, webui/ratelimit/memory), leftover unconvert. Purely mechanical, package-local, no design judgement. THE ONLY PHASE WORTH PARALLELISING. Partition by package: tools / webui / memory+ratelimit / secret. Use git worktree isolation -- other sessions edit this repo concurrently and stale diagnostics are a known hazard. Each worker verifies scoped: go test ./internal/X/... plus golangci-lint run ./internal/X/...","status":"closed","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-27T15:22:59Z","created_by":"Sam Catlow","updated_at":"2026-07-28T17:23:35Z","started_at":"2026-07-28T17:18:49Z","closed_at":"2026-07-28T17:23:35Z","close_reason":"Closed","dependencies":[{"issue_id":"archie-core-qa4.2","depends_on_id":"archie-core-qa4","type":"parent-child","created_at":"2026-07-28T01:22:59Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-qa4.2","title":"Phase 2: mechanical per-package fixes (~40 issues)","description":"forcetypeassert (24, internal/tools 20 + internal/memory 2, nearly all tests), predeclared (9, webui/ratelimit/memory), leftover unconvert. Purely mechanical, package-local, no design judgement. THE ONLY PHASE WORTH PARALLELISING. Partition by package: tools / webui / memory+ratelimit / secret. Use git worktree isolation -- other sessions edit this repo concurrently and stale diagnostics are a known hazard. Each worker verifies scoped: go test ./internal/X/... plus golangci-lint run ./internal/X/...","status":"closed","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-27T15:22:59Z","created_by":"Sam Catlow","updated_at":"2026-07-28T17:23:35Z","started_at":"2026-07-28T17:18:49Z","closed_at":"2026-07-28T17:23:35Z","close_reason":"Closed","dependencies":[{"issue_id":"archie-core-qa4.2","depends_on_id":"archie-core-qa4","type":"parent-child","created_at":"2026-07-28T01:22:59Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-qa4","title":"[EPIC] Clear the 160 golangci-lint findings","description":"Config landed in 9298afd; the gate is RED until this epic closes. Four phases, ordered by risk and by what invalidates what. Structural refactor MUST be last: it moves line numbers and invalidates everything in flight.","status":"open","priority":1,"issue_type":"epic","owner":"sam@catlow.tech","created_at":"2026-07-27T15:22:58Z","created_by":"Sam Catlow","updated_at":"2026-07-27T15:22:58Z","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"archie-core-qa4","title":"[EPIC] Clear the 160 golangci-lint findings","description":"Config landed in 9298afd; the gate is RED until this epic closes. Four phases, ordered by risk and by what invalidates what. Structural refactor MUST be last: it moves line numbers and invalidates everything in flight.","status":"open","priority":1,"issue_type":"epic","owner":"sam@catlow.tech","created_at":"2026-07-27T15:22:58Z","created_by":"Sam Catlow","updated_at":"2026-07-27T15:22:58Z","dependency_count":0,"dependent_count":0,"comment_count":0}
+1 -1
View File
@@ -24,7 +24,7 @@ import (
"github.com/samcharles93/archie-core/internal/agentexec" "github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/container" "github.com/samcharles93/archie-core/internal/container"
arnats "github.com/samcharles93/archie-core/internal/nats" arnats "github.com/samcharles93/archie-core/internal/infrastructure/eventbus/nats"
"github.com/samcharles93/archie-core/internal/storage" "github.com/samcharles93/archie-core/internal/storage"
"github.com/samcharles93/archie-core/internal/taskrun" "github.com/samcharles93/archie-core/internal/taskrun"
) )
+11 -3
View File
@@ -37,7 +37,7 @@ import (
"github.com/samcharles93/archie-core/internal/gateway" "github.com/samcharles93/archie-core/internal/gateway"
"github.com/samcharles93/archie-core/internal/memory" "github.com/samcharles93/archie-core/internal/memory"
"github.com/samcharles93/archie-core/internal/memory/builtin" "github.com/samcharles93/archie-core/internal/memory/builtin"
"github.com/samcharles93/archie-core/internal/nats" "github.com/samcharles93/archie-core/internal/infrastructure/eventbus/nats"
"github.com/samcharles93/archie-core/internal/nell" "github.com/samcharles93/archie-core/internal/nell"
"github.com/samcharles93/archie-core/internal/plugin" "github.com/samcharles93/archie-core/internal/plugin"
"github.com/samcharles93/archie-core/internal/plugin/pluginextract" "github.com/samcharles93/archie-core/internal/plugin/pluginextract"
@@ -209,7 +209,10 @@ func run() int {
log.Error("nats credentials", "err", err) log.Error("nats credentials", "err", err)
return 1 return 1
} }
natsClient, err = nats.Connect(ctx, cfg.NATS.URL, natsToken, log) natsClient, err = nats.Connect(ctx, nats.Config{
URL: cfg.NATS.URL,
Token: natsToken,
}, log)
if err != nil { if err != nil {
log.Error("nats connect failed", "err", err) log.Error("nats connect failed", "err", err)
return 1 return 1
@@ -677,7 +680,12 @@ func run() int {
// token, or push credential) proxy Store/Forge/worktree operations // token, or push credential) proxy Store/Forge/worktree operations
// back to archied over NATS. // back to archied over NATS.
if natsClient != nil { if natsClient != nil {
unsubscribe, err := registerTaskRPCServers(natsClient.Conn(), st, forgeClient, trees, log) coreConn, err := natsClient.CoreConn()
if err != nil {
log.Error("nats connection unavailable for task RPC", "err", err)
return 1
}
unsubscribe, err := registerTaskRPCServers(coreConn, st, forgeClient, trees, log)
if err != nil { if err != nil {
log.Error("task RPC server registration failed", "err", err) log.Error("task RPC server registration failed", "err", err)
return 1 return 1
+8 -14
View File
@@ -8,9 +8,8 @@ import (
"log/slog" "log/slog"
"time" "time"
natsio "github.com/nats-io/nats.go"
arnats "github.com/samcharles93/archie-core/internal/nats" arnats "github.com/samcharles93/archie-core/internal/infrastructure/eventbus/nats"
) )
// AgentRequestMessage is the NATS payload for an agent stage execution request. // AgentRequestMessage is the NATS payload for an agent stage execution request.
@@ -60,8 +59,8 @@ func (r *NATSRunner) Run(ctx context.Context, workspace string, req Request) (Re
return Result{}, fmt.Errorf("nats reply inbox: %w", err) return Result{}, fmt.Errorf("nats reply inbox: %w", err)
} }
defer func() { defer func() {
if err := replySub.Unsubscribe(); err != nil { if err := replySub.Close(); err != nil {
r.Log.Warn("reply inbox unsubscribe failed", "err", err) r.Log.Warn("reply inbox close failed", "err", err)
} }
}() }()
@@ -87,26 +86,21 @@ func (r *NATSRunner) Run(ctx context.Context, workspace string, req Request) (Re
} }
subject := arnats.SubjectForAgentRequest(req.TaskID) subject := arnats.SubjectForAgentRequest(req.TaskID)
headers := natsio.Header{} if err := r.Nats.PublishRequest(ctx, subject, replySub.Subject(), data); err != nil {
headers.Set(arnats.ReplyHeader, replySub.Subject)
if _, err := r.Nats.PublishMsg(ctx, &natsio.Msg{
Subject: subject,
Data: data,
Header: headers,
}); err != nil {
return Result{}, fmt.Errorf("publish agent request: %w", err) return Result{}, fmt.Errorf("publish agent request: %w", err)
} }
// 4. Wait for reply (blocking, matching SubprocessRunner.Run behaviour). // 4. Wait for reply (blocking, matching SubprocessRunner.Run behaviour).
reply, err := replySub.NextMsg(timeout) replyCtx, cancel := context.WithTimeout(ctx, timeout)
defer cancel()
reply, err := replySub.Next(replyCtx)
if err != nil { if err != nil {
return Result{}, fmt.Errorf("agent reply: %w", err) return Result{}, fmt.Errorf("agent reply: %w", err)
} }
// 5. Decode response. // 5. Decode response.
var envelope AgentResponseEnvelope var envelope AgentResponseEnvelope
if err := json.Unmarshal(reply.Data, &envelope); err != nil { if err := json.Unmarshal(reply, &envelope); err != nil {
return Result{}, fmt.Errorf("decode agent response: %w", err) return Result{}, fmt.Errorf("decode agent response: %w", err)
} }
if envelope.Error != "" { if envelope.Error != "" {
+14 -3
View File
@@ -12,7 +12,7 @@ import (
natsio "github.com/nats-io/nats.go" natsio "github.com/nats-io/nats.go"
"github.com/nats-io/nats.go/jetstream" "github.com/nats-io/nats.go/jetstream"
arnats "github.com/samcharles93/archie-core/internal/nats" arnats "github.com/samcharles93/archie-core/internal/infrastructure/eventbus/nats"
) )
// ── helpers ────────────────────────────────────────────────────────── // ── helpers ──────────────────────────────────────────────────────────
@@ -251,13 +251,13 @@ func TestNATSRunnerRoundTrip(t *testing.T) {
url := srv.ClientURL() url := srv.ClientURL()
ctx := context.Background() ctx := context.Background()
client, err := arnats.Connect(ctx, url, "", slog.New(slog.DiscardHandler)) client, err := arnats.Connect(ctx, arnats.Config{URL: url}, slog.New(slog.DiscardHandler))
if err != nil { if err != nil {
t.Fatal(err) t.Fatal(err)
} }
defer client.Close() defer client.Close()
startHandler(t, client.Conn()) startHandler(t, mustCoreConn(t, client))
runner := &NATSRunner{ runner := &NATSRunner{
Nats: client, Nats: client,
@@ -289,3 +289,14 @@ func TestNATSRunnerRoundTrip(t *testing.T) {
t.Fatalf("expected 42 tokens, got %d", result.TokensUsed) t.Fatalf("expected 42 tokens, got %d", result.TokensUsed)
} }
} }
// mustCoreConn returns the raw NATS connection for tests that drive core-NATS
// subscriptions directly, failing the test if the client is not connected.
func mustCoreConn(t *testing.T, c *arnats.Client) *natsio.Conn {
t.Helper()
conn, err := c.CoreConn()
if err != nil {
t.Fatalf("CoreConn: %v", err)
}
return conn
}
+21 -11
View File
@@ -16,7 +16,6 @@ import (
"time" "time"
natsio "github.com/nats-io/nats.go" natsio "github.com/nats-io/nats.go"
"github.com/nats-io/nats.go/jetstream"
"github.com/samcharles93/ai-sdk/core" "github.com/samcharles93/ai-sdk/core"
"github.com/samcharles93/ai-sdk/runtime" "github.com/samcharles93/ai-sdk/runtime"
@@ -26,7 +25,7 @@ import (
"github.com/samcharles93/archie-core/internal/events" "github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/forge" "github.com/samcharles93/archie-core/internal/forge"
"github.com/samcharles93/archie-core/internal/memory" "github.com/samcharles93/archie-core/internal/memory"
arnats "github.com/samcharles93/archie-core/internal/nats" arnats "github.com/samcharles93/archie-core/internal/infrastructure/eventbus/nats"
"github.com/samcharles93/archie-core/internal/plugin" "github.com/samcharles93/archie-core/internal/plugin"
"github.com/samcharles93/archie-core/internal/storage" "github.com/samcharles93/archie-core/internal/storage"
"github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/store"
@@ -348,12 +347,15 @@ func (d *Daemon) drainNATS(ctx context.Context) {
dispatcher := newTaskDispatcher(d.Cfg.Containers.MaxConcurrency, d.allowConcurrentFor) dispatcher := newTaskDispatcher(d.Cfg.Containers.MaxConcurrency, d.allowConcurrentFor)
for ctx.Err() == nil { for ctx.Err() == nil {
msg, err := d.Nats.Fetch(ctx) msg, err := d.Nats.Fetch(ctx)
if errors.Is(err, arnats.ErrNoMessage) {
continue
}
if err != nil { if err != nil {
d.Log.Error("nats fetch failed", "err", err) d.Log.Error("nats fetch failed", "err", err)
break break
} }
if msg != nil { {
tm, err := arnats.DecodeTask(msg) tm, err := msg.Task()
if err != nil { if err != nil {
d.Log.Error("nats decode failed", "err", err) d.Log.Error("nats decode failed", "err", err)
_ = msg.Ack() // bad message, don't retry _ = msg.Ack() // bad message, don't retry
@@ -495,7 +497,15 @@ func (d *Daemon) pollNATS(ctx context.Context, fg forge.Forge, repo config.Repo,
d.maybeRetryParked(ctx, repo, is) d.maybeRetryParked(ctx, repo, is)
return return
} }
if err := d.Nats.PublishTask(ctx, repo.Owner, repo.Name, is.Number, is.Title, is.Body, labels, identity); err != nil { if err := d.Nats.PublishTask(ctx, arnats.TaskEnvelope{
Owner: repo.Owner,
Repo: repo.Name,
Number: is.Number,
Title: is.Title,
Body: is.Body,
Labels: strings.Split(labels, ","),
Identity: identity,
}); err != nil {
d.Log.Error("nats publish failed", "repo", repo.FullName(), "issue", is.Number, "err", err) d.Log.Error("nats publish failed", "repo", repo.FullName(), "issue", is.Number, "err", err)
return return
} }
@@ -521,8 +531,8 @@ func (d *Daemon) acknowledge(ctx context.Context, fg forge.Forge, repo config.Re
// processNATSTask decodes a NATS message, writes it to SQLite, claims it, // processNATSTask decodes a NATS message, writes it to SQLite, claims it,
// and runs the workflow. The message is ack'd on terminal (park is a valid // and runs the workflow. The message is ack'd on terminal (park is a valid
// outcome). Nak on transient errors so NATS redelivers. // outcome). Nak on transient errors so NATS redelivers.
func (d *Daemon) processNATSTask(ctx context.Context, msg jetstream.Msg) { func (d *Daemon) processNATSTask(ctx context.Context, msg arnats.Message) {
tm, err := arnats.DecodeTask(msg) tm, err := msg.Task()
if err != nil { if err != nil {
d.Log.Error("nats decode failed", "err", err) d.Log.Error("nats decode failed", "err", err)
if err := msg.Ack(); err != nil { if err := msg.Ack(); err != nil {
@@ -532,7 +542,7 @@ func (d *Daemon) processNATSTask(ctx context.Context, msg jetstream.Msg) {
return return
} }
inserted, err := d.Store.EnqueueIssue(ctx, tm.Owner, tm.Repo, tm.Number, tm.Title, tm.Body, tm.Labels, tm.Identity) inserted, err := d.Store.EnqueueIssue(ctx, tm.Owner, tm.Repo, tm.Number, tm.Title, tm.Body, strings.Join(tm.Labels, ","), tm.Identity)
if err != nil { if err != nil {
d.Log.Error("nats enqueue failed", "err", err) d.Log.Error("nats enqueue failed", "err", err)
if err := msg.Nak(); err != nil { if err := msg.Nak(); err != nil {
@@ -1023,7 +1033,7 @@ func (d *Daemon) runViaAgent(ctx context.Context, task *store.Task, repo config.
} }
var resp taskrun.Response var resp taskrun.Response
if err := json.Unmarshal(reply.Data, &resp); err != nil { if err := json.Unmarshal(reply, &resp); err != nil {
d.Log.Error("taskrun decode response failed", "task", task.ID, "err", err) d.Log.Error("taskrun decode response failed", "task", task.ID, "err", err)
_ = d.Store.Transition(ctx, task.ID, store.StatusRunning, store.StatusParked, "taskrun decode response failed: "+err.Error()) _ = d.Store.Transition(ctx, task.ID, store.StatusRunning, store.StatusParked, "taskrun decode response failed: "+err.Error())
return return
@@ -1071,12 +1081,12 @@ func (d *Daemon) taskRunRetryBackoff() time.Duration {
// task. Any error other than ErrNoResponders (encode failures, a context // task. Any error other than ErrNoResponders (encode failures, a context
// that's already done, etc.) is returned immediately without retrying, // that's already done, etc.) is returned immediately without retrying,
// since those don't mean "not ready yet". // since those don't mean "not ready yet".
func (d *Daemon) requestTaskRun(ctx context.Context, taskID int64, data []byte) (*natsio.Msg, error) { func (d *Daemon) requestTaskRun(ctx context.Context, taskID int64, data []byte) ([]byte, error) {
subject := taskrun.SubjectForTask(taskID) subject := taskrun.SubjectForTask(taskID)
deadline := time.Now().Add(d.taskRunReadyTimeout()) deadline := time.Now().Add(d.taskRunReadyTimeout())
backoff := d.taskRunRetryBackoff() backoff := d.taskRunRetryBackoff()
for { for {
reply, err := d.Nats.Conn().RequestWithContext(ctx, subject, data) reply, err := d.Nats.Request(ctx, subject, data)
if err == nil { if err == nil {
return reply, nil return reply, nil
} }
+20 -5
View File
@@ -17,7 +17,7 @@ import (
"github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/forge" "github.com/samcharles93/archie-core/internal/forge"
arnats "github.com/samcharles93/archie-core/internal/nats" arnats "github.com/samcharles93/archie-core/internal/infrastructure/eventbus/nats"
"github.com/samcharles93/archie-core/internal/secret" "github.com/samcharles93/archie-core/internal/secret"
"github.com/samcharles93/archie-core/internal/storage" "github.com/samcharles93/archie-core/internal/storage"
"github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/store"
@@ -273,7 +273,7 @@ func startEmbeddedNATSForDaemon(t *testing.T) *server.Server {
func daemonWithNATS(t *testing.T) (*Daemon, *store.Store) { func daemonWithNATS(t *testing.T) (*Daemon, *store.Store) {
t.Helper() t.Helper()
srv := startEmbeddedNATSForDaemon(t) srv := startEmbeddedNATSForDaemon(t)
client, err := arnats.Connect(context.Background(), srv.ClientURL(), "", slog.New(slog.DiscardHandler)) client, err := arnats.Connect(context.Background(), arnats.Config{URL: srv.ClientURL()}, slog.New(slog.DiscardHandler))
if err != nil { if err != nil {
t.Fatalf("nats connect: %v", err) t.Fatalf("nats connect: %v", err)
} }
@@ -353,7 +353,11 @@ func TestRunViaAgentRetriesUntilResponderAppears(t *testing.T) {
// this retry loop exists to survive. // this retry loop exists to survive.
go func() { go func() {
time.Sleep(80 * time.Millisecond) time.Sleep(80 * time.Millisecond)
sub, err := d.Nats.Conn().Subscribe(taskrun.SubjectForTask(task.ID), func(msg *natsio.Msg) { coreConn, connErr := d.Nats.CoreConn()
if connErr != nil {
t.Fatalf("CoreConn: %v", connErr)
}
sub, err := coreConn.Subscribe(taskrun.SubjectForTask(task.ID), func(msg *natsio.Msg) {
data, _ := json.Marshal(taskrun.Response{Status: store.StatusPROpen}) data, _ := json.Marshal(taskrun.Response{Status: store.StatusPROpen})
_ = msg.Respond(data) _ = msg.Respond(data)
}) })
@@ -414,7 +418,7 @@ func TestRunViaAgentParksOnRunError(t *testing.T) {
t.Fatalf("claim: (%v, %v)", task, err) t.Fatalf("claim: (%v, %v)", task, err)
} }
sub, err := d.Nats.Conn().Subscribe(taskrun.SubjectForTask(task.ID), func(msg *natsio.Msg) { sub, err := mustCoreConn(t, d.Nats).Subscribe(taskrun.SubjectForTask(task.ID), func(msg *natsio.Msg) {
data, _ := json.Marshal(taskrun.Response{Error: "registry build failed"}) data, _ := json.Marshal(taskrun.Response{Error: "registry build failed"})
_ = msg.Respond(data) _ = msg.Respond(data)
}) })
@@ -448,7 +452,7 @@ func TestRunViaAgentSendsExpectedRequest(t *testing.T) {
} }
received := make(chan taskrun.Request, 1) received := make(chan taskrun.Request, 1)
sub, err := d.Nats.Conn().Subscribe(taskrun.SubjectForTask(task.ID), func(msg *natsio.Msg) { sub, err := mustCoreConn(t, d.Nats).Subscribe(taskrun.SubjectForTask(task.ID), func(msg *natsio.Msg) {
var req taskrun.Request var req taskrun.Request
_ = json.Unmarshal(msg.Data, &req) _ = json.Unmarshal(msg.Data, &req)
received <- req received <- req
@@ -936,3 +940,14 @@ func TestRepoForPrefersOwningIdentityRepoList(t *testing.T) {
t.Fatal("repoFor leaked archie's identity-only repo to winter") t.Fatal("repoFor leaked archie's identity-only repo to winter")
} }
} }
// mustCoreConn returns the raw NATS connection for tests that drive core-NATS
// subscriptions directly, failing the test if the client is not connected.
func mustCoreConn(t *testing.T, c *arnats.Client) *natsio.Conn {
t.Helper()
conn, err := c.CoreConn()
if err != nil {
t.Fatalf("CoreConn: %v", err)
}
return conn
}
@@ -0,0 +1,162 @@
package nats
import (
"context"
"fmt"
"log/slog"
"github.com/nats-io/nats.go"
"github.com/nats-io/nats.go/jetstream"
)
// Publisher publishes messages onto the bus. Declared as an interface so
// callers depend on behaviour rather than *Client, and can be tested without a
// broker -- the previous package exported only a concrete struct.
type Publisher interface {
PublishTask(ctx context.Context, task TaskEnvelope) error
PublishRequest(ctx context.Context, subject, replyTo string, payload []byte) error
Publish(ctx context.Context, subject string, payload []byte) error
}
// Consumer reads messages from the bus.
type Consumer interface {
// Fetch returns the next message, or ErrNoMessage if none arrives before
// the configured poll timeout.
Fetch(ctx context.Context) (Message, error)
}
// Requester performs core-NATS request/reply outside JetStream.
type Requester interface {
NewReplyInbox() (ReplyInbox, error)
}
// Compile-time proof that Client satisfies every boundary interface.
var (
_ Publisher = (*Client)(nil)
_ Consumer = (*Client)(nil)
_ Requester = (*Client)(nil)
)
// Client owns the NATS connection and its JetStream stream and consumer.
type Client struct {
conn *nats.Conn
js jetstream.JetStream
stream jetstream.Stream
consumer jetstream.Consumer
cfg Config
log *slog.Logger
}
// Connect dials the broker and provisions the stream and pull consumer. The
// stream uses work-queue retention on file storage.
//
// On any failure the partially-built connection is closed before returning, so
// a failed Connect leaks nothing.
func Connect(ctx context.Context, cfg Config, log *slog.Logger) (*Client, error) {
if err := cfg.Validate(); err != nil {
return nil, err
}
cfg = cfg.withDefaults()
if log == nil {
log = slog.New(slog.DiscardHandler)
}
conn, err := dial(cfg)
if err != nil {
return nil, err
}
// Every failure past this point must close conn. Cleared on success.
closeOnFail := conn.Close
defer func() {
if closeOnFail != nil {
closeOnFail()
}
}()
js, err := jetstream.New(conn)
if err != nil {
return nil, fmt.Errorf("nats jetstream init: %w", err)
}
stream, err := js.CreateOrUpdateStream(ctx, jetstream.StreamConfig{
Name: cfg.StreamName,
Subjects: []string{SubjectTaskWildcard, SubjectAgentWildcard},
Storage: jetstream.FileStorage,
Retention: jetstream.WorkQueuePolicy,
Duplicates: cfg.DedupWindow,
})
if err != nil {
return nil, fmt.Errorf("nats create stream %q: %w", cfg.StreamName, err)
}
consumer, err := stream.CreateOrUpdateConsumer(ctx, jetstream.ConsumerConfig{
Name: cfg.ConsumerName,
Durable: cfg.ConsumerName,
FilterSubject: SubjectTaskWildcard,
AckPolicy: jetstream.AckExplicitPolicy,
MaxDeliver: cfg.MaxDeliver,
AckWait: cfg.AckWait,
InactiveThreshold: cfg.InactiveTTL,
})
if err != nil {
return nil, fmt.Errorf("nats create consumer %q: %w", cfg.ConsumerName, err)
}
closeOnFail = nil
log.Info("nats connected",
"stream", cfg.StreamName,
"consumer", cfg.ConsumerName,
"url", conn.ConnectedUrl())
return &Client{
conn: conn,
js: js,
stream: stream,
consumer: consumer,
cfg: cfg,
log: log,
}, nil
}
// dial opens the raw connection, applying auth options from cfg.
func dial(cfg Config) (*nats.Conn, error) {
var opts []nats.Option
if cfg.Token != "" {
opts = append(opts, nats.Token(cfg.Token))
}
conn, err := nats.Connect(cfg.URL, opts...)
if err != nil {
return nil, fmt.Errorf("nats connect %s: %w", cfg.URL, err)
}
return conn, nil
}
// Close shuts the connection down. It is safe to call on a nil client so
// callers holding an optional bus can defer it unconditionally.
func (c *Client) Close() {
if c == nil || c.conn == nil {
return
}
c.conn.Close()
c.log.Debug("nats connection closed")
}
// CoreConn exposes the raw connection for the NATS-specific RPC layers
// (forgerpc, storerpc, worktreerpc, natsrpc) that register their own core-NATS
// subscriptions.
//
// This is the single sanctioned escape hatch and exists only because those
// packages are themselves NATS infrastructure, not domain code. Domain and
// application packages must use [Publisher], [Consumer] or [Requester]
// instead; taking the connection there would put SDK types back into their
// imports, which is what this package exists to prevent.
func (c *Client) CoreConn() (*nats.Conn, error) { return c.connection() }
// connection returns the live connection, or ErrNotConnected.
func (c *Client) connection() (*nats.Conn, error) {
if c == nil || c.conn == nil || c.conn.IsClosed() {
return nil, ErrNotConnected
}
return c.conn, nil
}
@@ -0,0 +1,97 @@
package nats
import (
"fmt"
"time"
)
// Defaults for Config. Previously these were unexported package constants,
// which made stream naming and timeouts untunable per deployment.
const (
DefaultStreamName = "ARCHIE_TASKS"
DefaultConsumerName = "archie-daemon"
DefaultDedupWindow = 2 * time.Minute
DefaultPollTimeout = 2 * time.Second
DefaultAckWait = 5 * time.Minute
DefaultMaxDeliver = 3
DefaultInactiveTTL = 24 * time.Hour
// dedupKeyPrefix namespaces the Nats-Msg-Id used for JetStream dedup so
// archie's keys cannot collide with another publisher on a shared server.
dedupKeyPrefix = "archie:"
)
// Config describes how to reach NATS and how the stream and consumer should
// behave. The zero value is not usable; call [Config.withDefaults] via
// [Connect], which fills every unset field.
type Config struct {
// URL is the NATS server address. Required.
URL string
// Token authenticates the connection. Empty means no token auth.
Token string
// StreamName is the JetStream stream holding task and agent subjects.
StreamName string
// ConsumerName is the durable pull consumer the daemon reads tasks from.
ConsumerName string
// DedupWindow is how long JetStream remembers a Nats-Msg-Id, suppressing
// republished duplicates of the same issue within the window.
DedupWindow time.Duration
// PollTimeout bounds a single Fetch. On expiry Fetch reports ErrNoMessage.
PollTimeout time.Duration
// AckWait is how long a delivered message may go unacknowledged before
// JetStream redelivers it. It must exceed the longest stage runtime.
AckWait time.Duration
// MaxDeliver caps redelivery attempts before a message is dropped.
MaxDeliver int
// InactiveTTL removes the consumer after this much inactivity.
InactiveTTL time.Duration
}
// Validate reports whether the config can produce a usable client.
func (c Config) Validate() error {
if c.URL == "" {
return fmt.Errorf("%w: URL is required", ErrInvalidConfig)
}
if c.PollTimeout < 0 || c.AckWait < 0 || c.DedupWindow < 0 {
return fmt.Errorf("%w: durations must not be negative", ErrInvalidConfig)
}
if c.MaxDeliver < 0 {
return fmt.Errorf("%w: MaxDeliver must not be negative", ErrInvalidConfig)
}
return nil
}
// withDefaults returns a copy with every unset field populated, so the rest of
// the package never has to test for zero values.
func (c Config) withDefaults() Config {
if c.StreamName == "" {
c.StreamName = DefaultStreamName
}
if c.ConsumerName == "" {
c.ConsumerName = DefaultConsumerName
}
if c.DedupWindow == 0 {
c.DedupWindow = DefaultDedupWindow
}
if c.PollTimeout == 0 {
c.PollTimeout = DefaultPollTimeout
}
if c.AckWait == 0 {
c.AckWait = DefaultAckWait
}
if c.MaxDeliver == 0 {
c.MaxDeliver = DefaultMaxDeliver
}
if c.InactiveTTL == 0 {
c.InactiveTTL = DefaultInactiveTTL
}
return c
}
@@ -0,0 +1,80 @@
package nats
import (
"context"
"fmt"
"github.com/nats-io/nats.go/jetstream"
)
// Fetch returns the next task message from the pull consumer.
//
// It reports ErrNoMessage when the poll timeout expires with nothing queued.
// The previous API returned (nil, nil) in that case, which every caller had to
// remember to distinguish from a real message.
func (c *Client) Fetch(ctx context.Context) (Message, error) {
if _, err := c.connection(); err != nil {
return Message{}, fmt.Errorf("fetch: %w", err)
}
batch, err := c.consumer.Fetch(1, jetstream.FetchMaxWait(c.cfg.PollTimeout))
if err != nil {
return Message{}, fmt.Errorf("fetch from %s: %w", c.cfg.ConsumerName, err)
}
for msg := range batch.Messages() {
if msg == nil {
continue
}
// Honour cancellation: return the message unacked so JetStream
// redelivers it rather than losing it to a shutting-down daemon.
if err := ctx.Err(); err != nil {
_ = msg.Nak()
return Message{}, fmt.Errorf("fetch from %s: %w", c.cfg.ConsumerName, err)
}
return Message{msg: msg}, nil
}
if err := batch.Error(); err != nil {
return Message{}, fmt.Errorf("fetch batch from %s: %w", c.cfg.ConsumerName, err)
}
return Message{}, ErrNoMessage
}
// Subscribe delivers agent-subject messages to handle until ctx is done. It
// exists so workers do not need the SDK's consume machinery; handle receives
// the same boundary Message type as Fetch.
func (c *Client) Subscribe(ctx context.Context, filterSubject string, handle func(Message) error) error {
if _, err := c.connection(); err != nil {
return fmt.Errorf("subscribe %s: %w", filterSubject, err)
}
consumer, err := c.stream.CreateOrUpdateConsumer(ctx, jetstream.ConsumerConfig{
FilterSubject: filterSubject,
AckPolicy: jetstream.AckExplicitPolicy,
AckWait: c.cfg.AckWait,
MaxDeliver: c.cfg.MaxDeliver,
})
if err != nil {
return fmt.Errorf("subscribe %s: %w", filterSubject, err)
}
consumeCtx, err := consumer.Consume(func(msg jetstream.Msg) {
if err := handle(Message{msg: msg}); err != nil {
c.log.Error("message handler failed",
"subject", msg.Subject(), "error", err)
_ = msg.Nak()
return
}
if err := msg.Ack(); err != nil {
c.log.Error("ack failed", "subject", msg.Subject(), "error", err)
}
})
if err != nil {
return fmt.Errorf("consume %s: %w", filterSubject, err)
}
defer consumeCtx.Stop()
<-ctx.Done()
return nil
}
@@ -0,0 +1,26 @@
// Package nats is the NATS JetStream transport for task distribution and
// agent communication.
//
// It is infrastructure: it owns the broker connection, stream and consumer
// lifecycle, and the wire encoding of messages. It does not own workflow
// routing, task state, or any other domain behaviour.
//
// The package deliberately keeps NATS SDK types behind its own boundary.
// Callers receive [Message], not jetstream.Msg, and publish [TaskEnvelope] or
// [Request], not *nats.Msg. That keeps the broker replaceable and stops SDK
// types leaking into domain packages, per
// docs/architecture/dependencies-and-contracts.md.
//
// Layout:
//
// config.go connection and stream/consumer tuning
// errors.go sentinel errors callers match on
// subjects.go subject naming, pure and dependency-free
// message.go wire payloads and the Message wrapper
// client.go connection lifecycle
// publisher.go publishing
// consumer.go fetching
//
// When no NATS URL is configured the daemon uses its local SQLite claim flow
// instead; nothing here is required for single-process operation.
package nats
@@ -0,0 +1,24 @@
package nats
import "errors"
// Sentinel errors callers are expected to match with errors.Is. Anything else
// returned by this package is wrapped with operation context via %w.
var (
// ErrNoMessage reports that a fetch completed normally but no message was
// available before the poll deadline. It is an expected outcome of polling
// an idle queue, not a failure -- the previous API signalled this with a
// (nil, nil) return, which callers had to remember to check for.
ErrNoMessage = errors.New("nats: no message available")
// ErrNotConnected reports use of a client whose connection is closed or
// was never established.
ErrNotConnected = errors.New("nats: not connected")
// ErrNoReplyAddress reports a request message that carried no reply
// inbox in its headers, so no response can be routed back.
ErrNoReplyAddress = errors.New("nats: message has no reply address")
// ErrInvalidConfig reports a Config that cannot produce a usable client.
ErrInvalidConfig = errors.New("nats: invalid configuration")
)
@@ -0,0 +1,139 @@
package nats
import (
"encoding/json"
"fmt"
"strings"
"github.com/nats-io/nats.go/jetstream"
)
// TaskEnvelope is the wire payload for a discovered issue.
//
// Publishing previously took seven positional parameters, six of them strings,
// which made transposed arguments a silent bug. Callers now build this struct.
type TaskEnvelope struct {
Owner string `json:"owner"`
Repo string `json:"repo"`
Number int `json:"number"`
Title string `json:"title"`
Body string `json:"body"`
// Labels are the issue's labels. On the wire this stays a
// comma-separated string for compatibility with already-queued messages,
// but in Go it is a slice -- the previous API passed a comma-joined
// string and re-split it internally on every publish.
Labels []string `json:"-"`
// LabelsRaw is the comma-separated wire form. Kept in sync by MarshalJSON
// and UnmarshalJSON; callers should use Labels.
LabelsRaw string `json:"labels"`
// Identity is the archie identity whose forge poll discovered the issue,
// empty for single-identity deployments. Carried so the consuming daemon
// enqueues the task under the right owner.
Identity string `json:"identity,omitempty"`
}
// taskEnvelopeWire avoids infinite recursion in the JSON methods below.
type taskEnvelopeWire TaskEnvelope
// MarshalJSON flattens Labels into the comma-separated wire field.
func (t TaskEnvelope) MarshalJSON() ([]byte, error) {
t.LabelsRaw = strings.Join(t.Labels, ",")
data, err := json.Marshal(taskEnvelopeWire(t))
if err != nil {
return nil, fmt.Errorf("marshal task envelope: %w", err)
}
return data, nil
}
// UnmarshalJSON expands the comma-separated wire field into Labels.
func (t *TaskEnvelope) UnmarshalJSON(data []byte) error {
var wire taskEnvelopeWire
if err := json.Unmarshal(data, &wire); err != nil {
return fmt.Errorf("unmarshal task envelope: %w", err)
}
*t = TaskEnvelope(wire)
t.Labels = splitLabels(t.LabelsRaw)
return nil
}
// DedupKey returns the JetStream Nats-Msg-Id for this task. Republishing the
// same issue inside Config.DedupWindow is suppressed by the server.
func (t TaskEnvelope) DedupKey() string {
return fmt.Sprintf("%s%s/%s/%d", dedupKeyPrefix, t.Owner, t.Repo, t.Number)
}
// Subject returns the task subject this envelope routes to.
func (t TaskEnvelope) Subject() string { return SubjectForLabels(t.Labels) }
// splitLabels parses the comma-separated wire form, dropping empty entries so
// "bug,,feature" and a trailing comma do not produce blank labels.
func splitLabels(raw string) []string {
if raw == "" {
return nil
}
parts := strings.Split(raw, ",")
labels := make([]string, 0, len(parts))
for _, part := range parts {
if trimmed := strings.TrimSpace(part); trimmed != "" {
labels = append(labels, trimmed)
}
}
if len(labels) == 0 {
return nil
}
return labels
}
// Message is a broker message with the SDK type kept behind the boundary.
//
// Fetch previously handed callers a jetstream.Msg directly, so every consumer
// imported the NATS SDK and the broker stopped being replaceable.
type Message struct {
msg jetstream.Msg
}
// Data returns the raw payload.
func (m Message) Data() []byte { return m.msg.Data() }
// Subject returns the subject the message arrived on.
func (m Message) Subject() string { return m.msg.Subject() }
// Header returns a single header value, or "" when absent.
func (m Message) Header(key string) string { return m.msg.Headers().Get(key) }
// ReplyAddress returns the requester's reply inbox, or ErrNoReplyAddress when
// the message carries none.
func (m Message) ReplyAddress() (string, error) {
if addr := m.Header(ReplyHeader); addr != "" {
return addr, nil
}
return "", fmt.Errorf("%w: header %s", ErrNoReplyAddress, ReplyHeader)
}
// Ack marks the message handled so JetStream will not redeliver it.
func (m Message) Ack() error {
if err := m.msg.Ack(); err != nil {
return fmt.Errorf("ack message on %s: %w", m.Subject(), err)
}
return nil
}
// Nak returns the message for redelivery.
func (m Message) Nak() error {
if err := m.msg.Nak(); err != nil {
return fmt.Errorf("nak message on %s: %w", m.Subject(), err)
}
return nil
}
// Task decodes the message as a TaskEnvelope.
func (m Message) Task() (TaskEnvelope, error) {
var envelope TaskEnvelope
if err := json.Unmarshal(m.Data(), &envelope); err != nil {
return TaskEnvelope{}, fmt.Errorf("decode task on %s: %w", m.Subject(), err)
}
return envelope, nil
}
@@ -0,0 +1,125 @@
package nats
import (
"context"
"encoding/json"
"fmt"
"github.com/nats-io/nats.go"
)
// PublishTask publishes a discovered issue to the subject its labels select.
// The dedup header suppresses republishing the same issue inside the
// configured dedup window.
func (c *Client) PublishTask(ctx context.Context, task TaskEnvelope) error {
data, err := json.Marshal(task)
if err != nil {
return fmt.Errorf("encode task %s/%s#%d: %w", task.Owner, task.Repo, task.Number, err)
}
header := nats.Header{}
header.Set("Nats-Msg-Id", task.DedupKey())
subject := task.Subject()
if err := c.publish(ctx, &nats.Msg{Subject: subject, Data: data, Header: header}); err != nil {
return err
}
c.log.Debug("published task",
"subject", subject,
"owner", task.Owner,
"repo", task.Repo,
"number", task.Number,
"identity", task.Identity)
return nil
}
// PublishRequest publishes a stage execution request, recording replyTo in the
// reply header so the worker knows where to answer. JetStream consumes a
// message's Reply field for its own PubAck, hence the header.
func (c *Client) PublishRequest(ctx context.Context, subject, replyTo string, payload []byte) error {
if replyTo == "" {
return fmt.Errorf("%w: publishing %s", ErrNoReplyAddress, subject)
}
header := nats.Header{}
header.Set(ReplyHeader, replyTo)
return c.publish(ctx, &nats.Msg{Subject: subject, Data: payload, Header: header})
}
// Publish sends a payload to a subject with no reply routing.
func (c *Client) Publish(ctx context.Context, subject string, payload []byte) error {
return c.publish(ctx, &nats.Msg{Subject: subject, Data: payload})
}
// publish is the single JetStream publish path, so every caller gets the same
// connection check and error context.
func (c *Client) publish(ctx context.Context, msg *nats.Msg) error {
if _, err := c.connection(); err != nil {
return fmt.Errorf("publish to %s: %w", msg.Subject, err)
}
if _, err := c.js.PublishMsg(ctx, msg); err != nil {
return fmt.Errorf("publish to %s: %w", msg.Subject, err)
}
return nil
}
// Request performs a core-NATS request/reply and returns the response payload.
//
// This exists so callers never need the raw connection: the previous API
// exposed Conn() *nats.Conn, which put the SDK type in every caller's imports.
// nats.ErrNoResponders is returned unwrapped enough for errors.Is to match, so
// callers can still retry while a responder starts up.
func (c *Client) Request(ctx context.Context, subject string, payload []byte) ([]byte, error) {
conn, err := c.connection()
if err != nil {
return nil, fmt.Errorf("request %s: %w", subject, err)
}
msg, err := conn.RequestWithContext(ctx, subject, payload)
if err != nil {
return nil, fmt.Errorf("request %s: %w", subject, err)
}
return msg.Data, nil
}
// ReplyInbox is a one-shot subscription awaiting a single response.
type ReplyInbox struct {
sub *nats.Subscription
}
// Subject is the inbox address to advertise to the responder.
func (r ReplyInbox) Subject() string { return r.sub.Subject }
// Next blocks until the reply arrives or ctx is done.
func (r ReplyInbox) Next(ctx context.Context) ([]byte, error) {
msg, err := r.sub.NextMsgWithContext(ctx)
if err != nil {
return nil, fmt.Errorf("await reply on %s: %w", r.sub.Subject, err)
}
return msg.Data, nil
}
// Close unsubscribes the inbox.
func (r ReplyInbox) Close() error {
if err := r.sub.Unsubscribe(); err != nil {
return fmt.Errorf("close reply inbox %s: %w", r.sub.Subject, err)
}
return nil
}
// NewReplyInbox creates a unique inbox that auto-unsubscribes after one
// message.
func (c *Client) NewReplyInbox() (ReplyInbox, error) {
conn, err := c.connection()
if err != nil {
return ReplyInbox{}, fmt.Errorf("create reply inbox: %w", err)
}
sub, err := conn.SubscribeSync(conn.NewInbox())
if err != nil {
return ReplyInbox{}, fmt.Errorf("subscribe reply inbox: %w", err)
}
if err := sub.AutoUnsubscribe(1); err != nil {
_ = sub.Unsubscribe()
return ReplyInbox{}, fmt.Errorf("configure reply inbox %s: %w", sub.Subject, err)
}
return ReplyInbox{sub: sub}, nil
}
@@ -0,0 +1,67 @@
package nats
import (
"fmt"
"strings"
)
// Task distribution subjects. Each encodes the workflow type so a multi-daemon
// deployment can filter by workflow.
const (
SubjectTaskBug = "archie.task.bug"
SubjectTaskFeature = "archie.task.feature"
SubjectTaskBootstrap = "archie.task.bootstrap"
SubjectTaskDefault = "archie.task.default"
// SubjectTaskWildcard matches every task subject.
SubjectTaskWildcard = "archie.task.>"
// SubjectAgentWildcard matches every agent stage execution subject.
SubjectAgentWildcard = "archie.agent.>"
)
// ReplyHeader carries the requester's reply inbox. JetStream consumes a
// message's Reply field for its own PubAck, so the address travels as a header.
const ReplyHeader = "X-Archie-Reply"
// labelSubjects maps an issue label to its task subject. Declared once so the
// mapping is data rather than a switch, and so SubjectForLabels and any future
// reverse lookup cannot drift apart.
var labelSubjects = map[string]string{
"bug": SubjectTaskBug,
"feature": SubjectTaskFeature,
"bootstrap": SubjectTaskBootstrap,
}
// SubjectForLabels picks the task subject for a set of issue labels, mirroring
// the label-to-workflow mapping in workflow.Route. The first recognised label
// wins; unrecognised or empty label sets route to SubjectTaskDefault.
func SubjectForLabels(labels []string) string {
for _, label := range labels {
if subject, ok := labelSubjects[strings.TrimSpace(label)]; ok {
return subject
}
}
return SubjectTaskDefault
}
// SubjectForAgentRequest returns the subject carrying stage execution requests
// for a task. The stage travels in the payload, not the subject: one subject
// per task with sequential stage messages.
func SubjectForAgentRequest(taskID int64) string {
return fmt.Sprintf("archie.agent.%d.request", taskID)
}
// SubjectForAgentResponse returns the subject for agent output destined for
// human channels. The daemon reviews these before forwarding to issue
// comments, labels, or pull requests.
func SubjectForAgentResponse(taskID int64) string {
return fmt.Sprintf("archie.agent.%d.response", taskID)
}
// SubjectForAgentSystem returns the subject for internal agent messages such
// as log dumps, health, and PII warnings. The daemon reads these for
// observability and never forwards them.
func SubjectForAgentSystem(taskID int64) string {
return fmt.Sprintf("archie.agent.%d.system", taskID)
}
-185
View File
@@ -1,185 +0,0 @@
package nats
import (
"context"
"encoding/json"
"fmt"
"log/slog"
"strings"
"time"
"github.com/nats-io/nats.go"
"github.com/nats-io/nats.go/jetstream"
)
const (
streamName = "ARCHIE_TASKS"
consumerName = "archie-daemon"
msgPrefix = "archie:" // for Nats-Msg-Id dedup
dedupWindow = 2 * time.Minute
pollTimeout = 2 * time.Second
)
// TaskMessage is the NATS payload for a discovered issue.
type TaskMessage struct {
Owner string `json:"owner"`
Repo string `json:"repo"`
Number int `json:"number"`
Title string `json:"title"`
Body string `json:"body"`
Labels string `json:"labels"` // comma-separated
// Identity is the archie identity whose forge poll discovered this
// issue (empty for single-identity deployments). Carried through so
// the consuming daemon can enqueue the task with the right owner.
Identity string `json:"identity,omitempty"`
}
// Client manages the NATS connection and JetStream resources.
type Client struct {
conn *nats.Conn
js jetstream.JetStream
stream jetstream.Stream
consumer jetstream.Consumer
log *slog.Logger
}
// Connect dials url, sets up the JetStream stream and pull consumer.
// The stream is created with WorkQueue retention and file storage.
func Connect(ctx context.Context, url, token string, log *slog.Logger) (*Client, error) {
var opts []nats.Option
if token != "" {
opts = append(opts, nats.Token(token))
}
nc, err := nats.Connect(url, opts...)
if err != nil {
return nil, fmt.Errorf("nats connect: %w", err)
}
js, err := jetstream.New(nc)
if err != nil {
nc.Close()
return nil, fmt.Errorf("nats jetstream: %w", err)
}
stream, err := js.CreateOrUpdateStream(ctx, jetstream.StreamConfig{
Name: streamName,
Subjects: []string{"archie.task.>", "archie.agent.>"},
Storage: jetstream.FileStorage,
Retention: jetstream.WorkQueuePolicy,
Duplicates: dedupWindow,
})
if err != nil {
nc.Close()
return nil, fmt.Errorf("nats stream: %w", err)
}
consumer, err := stream.CreateOrUpdateConsumer(ctx, jetstream.ConsumerConfig{
Name: consumerName,
Durable: consumerName,
FilterSubject: "archie.task.>",
AckPolicy: jetstream.AckExplicitPolicy,
MaxDeliver: 3,
AckWait: 5 * time.Minute,
InactiveThreshold: 24 * time.Hour,
})
if err != nil {
nc.Close()
return nil, fmt.Errorf("nats consumer: %w", err)
}
return &Client{conn: nc, js: js, stream: stream, consumer: consumer, log: log}, nil
}
// Conn returns the underlying NATS connection for core NATS operations
// (inbox subscriptions, direct publishes).
func (c *Client) Conn() *nats.Conn { return c.conn }
// PublishMsg publishes a message to JetStream with optional headers.
func (c *Client) PublishMsg(ctx context.Context, msg *nats.Msg) (*jetstream.PubAck, error) {
return c.js.PublishMsg(ctx, msg)
}
// Close drains and closes the NATS connection.
func (c *Client) Close() { c.conn.Close() }
// NewReplyInbox creates a unique inbox subject and returns a synchronous
// subscription configured to auto-unsubscribe after one message.
func (c *Client) NewReplyInbox() (*nats.Subscription, error) {
sub, err := c.conn.SubscribeSync(c.conn.NewInbox())
if err != nil {
return nil, err
}
if err := sub.AutoUnsubscribe(1); err != nil {
_ = sub.Unsubscribe()
return nil, err
}
return sub, nil
}
// PublishTask publishes a discovered issue to the appropriate NATS subject.
// The Nats-Msg-Id header enables JetStream dedup within the dedup window.
func (c *Client) PublishTask(ctx context.Context, owner, repo string, number int, title, body, labels, identity string) error {
msg := TaskMessage{
Owner: owner,
Repo: repo,
Number: number,
Title: title,
Body: body,
Labels: labels,
Identity: identity,
}
data, err := json.Marshal(msg)
if err != nil {
return err
}
subject := SubjectForLabels(splitLabels(labels))
headers := nats.Header{}
msgID := fmt.Sprintf("%s%s/%s/%d", msgPrefix, owner, repo, number)
headers.Set("Nats-Msg-Id", msgID)
_, err = c.js.PublishMsg(ctx, &nats.Msg{
Subject: subject,
Data: data,
Header: headers,
})
if err != nil {
return fmt.Errorf("nats publish: %w", err)
}
return nil
}
// Fetch retrieves one task message from the pull consumer.
// Returns nil if no message is available within the poll timeout.
func (c *Client) Fetch(ctx context.Context) (jetstream.Msg, error) {
batch, err := c.consumer.Fetch(1, jetstream.FetchMaxWait(pollTimeout))
if err != nil {
return nil, fmt.Errorf("nats fetch: %w", err)
}
for msg := range batch.Messages() {
if msg == nil {
continue
}
return msg, nil
}
if err := batch.Error(); err != nil {
return nil, fmt.Errorf("nats fetch batch: %w", err)
}
return nil, nil
}
// DecodeTask decodes a TaskMessage from a NATS message.
func DecodeTask(msg jetstream.Msg) (TaskMessage, error) {
var tm TaskMessage
if err := json.Unmarshal(msg.Data(), &tm); err != nil {
return tm, fmt.Errorf("nats decode: %w", err)
}
return tm, nil
}
// splitLabels splits a comma-separated label string into a slice.
func splitLabels(labels string) []string {
if labels == "" {
return nil
}
return strings.Split(labels, ",")
}
-275
View File
@@ -1,275 +0,0 @@
package nats
import (
"context"
"errors"
"log/slog"
"testing"
"github.com/nats-io/nats-server/v2/server"
natssrv "github.com/nats-io/nats-server/v2/test"
"github.com/nats-io/nats.go/jetstream"
)
// startEmbedded starts an embedded NATS server with JetStream file storage.
// The shutdown cleanup is registered AFTER t.TempDir() so that server shutdown
// completes deterministically before TempDir removes its storage directory.
// This prevents "directory not empty" races where JetStream's async file
// operations contend with testing.TempDir's os.RemoveAll.
func startEmbedded(t *testing.T) *server.Server {
t.Helper()
srv := natssrv.RunRandClientPortServer()
// Call TempDir FIRST so its internal cleanup is registered before shutdown.
// LIFO cleanup order ensures shutdown runs before TempDir removal.
jsDir := t.TempDir()
if err := srv.EnableJetStream(&server.JetStreamConfig{StoreDir: jsDir}); err != nil {
t.Fatalf("enable jetstream: %v", err)
}
t.Cleanup(func() {
srv.Shutdown()
srv.WaitForShutdown()
})
return srv
}
// startEmbeddedWithToken starts an embedded NATS server with token auth.
// Same deterministic cleanup ordering as startEmbedded.
func startEmbeddedWithToken(t *testing.T, token string) *server.Server {
t.Helper()
opts := natssrv.DefaultTestOptions
opts.Port = -1
opts.Authorization = token
srv := natssrv.RunServer(&opts)
// TempDir before Cleanup -- shutdown runs before TempDir removal.
jsDir := t.TempDir()
if err := srv.EnableJetStream(&server.JetStreamConfig{StoreDir: jsDir}); err != nil {
t.Fatalf("enable jetstream: %v", err)
}
t.Cleanup(func() {
srv.Shutdown()
srv.WaitForShutdown()
})
return srv
}
func TestConnectUsesToken(t *testing.T) {
const token = "test-nats-token"
srv := startEmbeddedWithToken(t, token)
client, err := Connect(
context.Background(),
srv.ClientURL(),
token,
slog.New(slog.DiscardHandler),
)
if err != nil {
t.Fatalf("Connect with token: %v", err)
}
client.Close()
}
func TestConnectAndPublish(t *testing.T) {
srv := startEmbedded(t)
url := srv.ClientURL()
ctx := context.Background()
client, err := Connect(ctx, url, "", slog.New(slog.DiscardHandler))
if err != nil {
t.Fatal(err)
}
defer client.Close()
// Publish a task.
if err := client.PublishTask(ctx, "acme", "todo", 1, "fix bug", "body text", "bug", ""); err != nil {
t.Fatal(err)
}
// Fetch it back.
msg, err := client.Fetch(ctx)
if err != nil {
t.Fatal(err)
}
if msg == nil {
t.Fatal("expected a message")
}
tm, err := DecodeTask(msg)
if err != nil {
t.Fatal(err)
}
if tm.Owner != "acme" || tm.Repo != "todo" || tm.Number != 1 || tm.Title != "fix bug" || tm.Body != "body text" {
t.Fatalf("unexpected task: %+v", tm)
}
_ = msg.Ack()
}
func TestDedup(t *testing.T) {
srv := startEmbedded(t)
url := srv.ClientURL()
ctx := context.Background()
client, err := Connect(ctx, url, "", slog.New(slog.DiscardHandler))
if err != nil {
t.Fatal(err)
}
defer client.Close()
// Publish one task and verify it's consumable.
if err := client.PublishTask(ctx, "acme", "app", 1, "first", "body", "bug", ""); err != nil {
t.Fatal(err)
}
msg, err := client.Fetch(ctx)
if err != nil {
t.Fatal(err)
}
if msg == nil {
t.Fatal("first message not received")
}
_ = msg.Ack()
// Second publish with same Msg-Id should be deduped.
if err := client.PublishTask(ctx, "acme", "app", 1, "second", "body-v2", "bug", ""); err != nil {
t.Fatal(err)
}
msg2, err := client.Fetch(ctx)
if err != nil {
t.Fatal(err)
}
if msg2 != nil {
_ = msg2.Ack()
t.Fatal("expected no second message (dedup)")
}
}
func TestSubjectRouting(t *testing.T) {
tests := []struct {
labels []string
want string
}{
{[]string{"bug"}, SubjectTaskBug},
{[]string{"enhancement"}, SubjectTaskDefault},
{[]string{"feature"}, SubjectTaskFeature},
{[]string{"bootstrap"}, SubjectTaskBootstrap},
{[]string{"bug", "feature"}, SubjectTaskBug}, // first match wins
{[]string{"enhancement", "bug"}, SubjectTaskBug},
{nil, SubjectTaskDefault},
{[]string{}, SubjectTaskDefault},
}
for _, tt := range tests {
got := SubjectForLabels(tt.labels)
if got != tt.want {
t.Errorf("SubjectForLabels(%v) = %q, want %q", tt.labels, got, tt.want)
}
}
}
// --- mock types for Fetch error propagation tests ---
// errSentinel is a distinguishable error used in mock MessageBatch.Error().
var errSentinel = errors.New("nats: consumer deleted")
// mockMessageBatch implements jetstream.MessageBatch.
type mockMessageBatch struct {
msgs <-chan jetstream.Msg
err error
}
func (m *mockMessageBatch) Messages() <-chan jetstream.Msg { return m.msgs }
func (m *mockMessageBatch) Error() error { return m.err }
// mockConsumer implements jetstream.Consumer.
// Only Fetch is exercised by Client.Fetch; the remaining methods panic to
// flag accidental usage.
type mockConsumer struct {
batch jetstream.MessageBatch
}
func (m *mockConsumer) Fetch(int, ...jetstream.FetchOpt) (jetstream.MessageBatch, error) {
return m.batch, nil
}
func (m *mockConsumer) FetchBytes(int, ...jetstream.FetchOpt) (jetstream.MessageBatch, error) {
panic("FetchBytes not implemented")
}
func (m *mockConsumer) FetchNoWait(int) (jetstream.MessageBatch, error) {
panic("FetchNoWait not implemented")
}
func (m *mockConsumer) Consume(jetstream.MessageHandler, ...jetstream.PullConsumeOpt) (jetstream.ConsumeContext, error) {
panic("Consume not implemented")
}
func (m *mockConsumer) Messages(...jetstream.PullMessagesOpt) (jetstream.MessagesContext, error) {
panic("Messages not implemented")
}
func (m *mockConsumer) Next(...jetstream.FetchOpt) (jetstream.Msg, error) {
panic("Next not implemented")
}
func (m *mockConsumer) Info(context.Context) (*jetstream.ConsumerInfo, error) {
panic("Info not implemented")
}
func (m *mockConsumer) CachedInfo() *jetstream.ConsumerInfo {
panic("CachedInfo not implemented")
}
func TestFetchPropagatesBatchErrorWhenNoMessages(t *testing.T) {
// Reproduces issue #35: when JetStream reports an error by closing the
// Messages() channel with zero messages and setting a non-nil batch error,
// Client.Fetch must propagate that error instead of returning (nil, nil).
ch := make(chan jetstream.Msg)
close(ch) // zero messages
batch := &mockMessageBatch{msgs: ch, err: errSentinel}
cons := &mockConsumer{batch: batch}
client := &Client{
consumer: cons,
log: slog.New(slog.DiscardHandler),
}
msg, err := client.Fetch(context.Background())
if err == nil {
t.Fatal("expected an error from Fetch when batch has an error and no messages, got nil")
}
if msg != nil {
t.Fatalf("expected nil message when batch has an error, got %v", msg)
}
if !errors.Is(err, errSentinel) {
t.Fatalf("expected errSentinel, got %v", err)
}
}
func TestFetchPropagatesBatchErrorEvenWhenLastMessageSeen(t *testing.T) {
// Companion: when the batch delivers a message but also has a non-nil
// error (the existing inside-loop check), we confirm the existing path
// still works. This is not the reported bug but guards against
// regressions.
ch := make(chan jetstream.Msg, 1)
ch <- nil // nil message triggers the msg==nil continue
close(ch)
batch := &mockMessageBatch{msgs: ch, err: errSentinel}
cons := &mockConsumer{batch: batch}
client := &Client{
consumer: cons,
log: slog.New(slog.DiscardHandler),
}
msg, err := client.Fetch(context.Background())
if err == nil {
t.Fatal("expected an error from Fetch when batch has an error, got nil")
}
if msg != nil {
t.Fatalf("expected nil message when batch has an error, got %v", msg)
}
if !errors.Is(err, errSentinel) {
t.Fatalf("expected errSentinel, got %v", err)
}
}
-74
View File
@@ -1,74 +0,0 @@
// Package nats manages the NATS JetStream connection for task distribution
// and agent communication. When configured, the daemon publishes discovered
// issues to NATS subjects and consumes them back via a JetStream pull
// consumer. Agent workers consume stage execution requests and reply via
// core NATS inboxes. When not configured (nil client), the existing SQLite
// ClaimNext flow is used unchanged.
package nats
import (
"fmt"
"strings"
)
// Task distribution subjects. Each subject encodes the workflow type so
// future multi-daemon deployments can filter by workflow.
const (
SubjectTaskBug = "archie.task.bug"
SubjectTaskFeature = "archie.task.feature"
SubjectTaskDefault = "archie.task.default"
SubjectTaskBootstrap = "archie.task.bootstrap"
)
// SubjectForLabels picks the NATS subject based on issue labels, mirroring
// the label-to-workflow mapping in workflow.Route.
//
// "bug" -> archie.task.bug
// "feature" -> archie.task.feature
// "bootstrap" -> archie.task.bootstrap
// default -> archie.task.default
func SubjectForLabels(labels []string) string {
for _, l := range labels {
switch strings.TrimSpace(l) {
case "bug":
return SubjectTaskBug
case "feature":
return SubjectTaskFeature
case "bootstrap":
return SubjectTaskBootstrap
}
}
return SubjectTaskDefault
}
// Agent communication subjects.
const (
// SubjectAgentWildcard matches all agent stage execution requests.
SubjectAgentWildcard = "archie.agent.>"
)
// SubjectForAgentRequest returns the JetStream subject for a per-task
// agent request. The stage is carried in the message payload, not the
// subject -- one subject per task with sequential stage messages. PRD §2.
func SubjectForAgentRequest(taskID int64) string {
return fmt.Sprintf("archie.agent.%d.request", taskID)
}
// SubjectForAgentResponse returns the subject for agent output destined
// for human channels. The daemon reviews messages on this subject before
// forwarding to issue comments, labels, or PRs. PRD §2.
func SubjectForAgentResponse(taskID int64) string {
return fmt.Sprintf("archie.agent.%d.response", taskID)
}
// SubjectForAgentSystem returns the subject for internal agent messages
// (log dumps, health, PII warnings). The daemon reads these for
// observability and never forwards them. PRD §2.
func SubjectForAgentSystem(taskID int64) string {
return fmt.Sprintf("archie.agent.%d.system", taskID)
}
// ReplyHeader is the custom NATS header carrying the daemon's reply inbox.
// JetStream's PublishMsg consumes the Reply field internally for PubAck, so
// the reply address is carried via this header instead.
const ReplyHeader = "X-Archie-Reply"