Noodle Agent Orchestration Framework

Events are the mechanism Noodle uses to track history and ingest information from external systems. The scheduler uses these events as context (not as direct commands) to decide how to react to the state of the world.

Noodle emits internal events automatically (e.g., stage completion, merge conflicts) and allows you to inject custom events from external tools like CI pipelines, deployment scripts, or monitoring systems.

When you emit an event, it is appended to .noodle/loop-events.ndjson. During the next build, these events appear in the recent_events array of the mise, which the scheduler reads to inform its decision-making process.

The ingestion system uses two primary data structures to manage concurrency and state:

• IngestionHandle: Used to control a specific ingestion session. It contains:

  • SessionID: Unique identifier for the session.
  • Cancel: A function to trigger session cancellation.
  • Done: A signal indicating the session has completed.
  • Sources: The list of active sources in the session.

• IngestionRegistry: A central registry keyed by the parent session ID. It tracks active workers, checkpoints, and poller metrics to ensure reliability across restarts.

Skills can be registered as part of a pipeline by including a schedule field in their YAML metadata. This tells the scheduler when the skill is eligible to run within an order's lifecycle.

Common scheduling patterns:

• schedule: "After execute stages complete, to verify changes": Used for testing skills to run after implementation.
• schedule: "After test stages pass, to ship verified changes": Used for deployment skills to run after verification.

Example test skill metadata (.agents/skills/test/SKILL.md):

---
name: test
description: Runs the project test suite and reports results.
schedule: "After execute stages complete, to verify changes"
---

To build a self-improving system, you can implement specialized skills that interact with the 'brain' (the markdown-based knowledge base):

• reflect: An agent writes what it learned during a session to the brain. This allows subsequent agents to read these notes and avoid repeating mistakes.
• meditate: An agent analyzes the accumulated learnings in the brain to extract high-level principles. These principles can then be encoded back into your skills to ground future agent decisions.

The active_order_ids field in snapshots no longer relies on inference from live cooks. Instead, it follows the state defined by the projection:

1. Inclusion: Review-blocked or non-running orders will remain in active_order_ids if the projection marks them as active.
2. Runtime Enrichment: Snapshot enrichment is restricted to session-level fields (e.g., active/recent sessions, current action, cost, and context usage).

The brainmaxxing skill pack introduces three core skills that create a continuous learning loop for agents:

1. Reflect: Runs after every session. It reviews the session and encodes learnings into the brain.
2. Meditate: Runs periodically. It distills accumulated reflections into high-level project principles.
3. Ruminate: Run ad-hoc. It mines past conversations to extract and capture knowledge that was never explicitly written down.

Agents use these to treat the brain as shared memory: reading context before work, writing notes during work, and using reflect to encode learnings after work.

When ingesting Codex child sessions, the system resolves file paths using the following rules:

1. Primary Lookup: Files are searched by thread ID filename under a date-partitioned tree: ~/.codex/sessions/YYYY/MM/DD/{thread_id}.jsonl.
2. Search Window: The system checks today, yesterday, and tomorrow partitions to handle midnight rollovers.
3. Retry Logic: If a file is unresolved, the system retries with exponential backoff (from 250ms to 5s) for a maximum of 90s before emitting a timeout warning.
4. Discovery Order: Exact partition match $\rightarrow$ adjacent partitions $\rightarrow$ bounded glob fallback within the 3-day window.

In the canonical state convergence model, the system moves away from rebuilding topology from LoopState. Instead, internal/projection/projection.go becomes the sole owner of structural snapshot topology (including projected review state and projected order/state output).

Key architectural shifts:

• projection.SnapshotView: This is the sole structural snapshot model consumed by the server. It is enriched at runtime.
• internal/snapshot/snapshot_builder.go: This component is reduced to performing runtime enrichment over the projection.SnapshotView rather than rebuilding the topology from scratch.
• Data Authority: Files like orders.json and state.json transition from being mutated by legacy workflows to being pure projection outputs.