@openduo/duoduo 0.2.0

package/bootstrap/subconscious/memory-weaver/.claude/agents/spine-scanner.md

@@ -0,0 +1,75 @@
+---
+name: spine-scanner
+description: Scans recent Spine events and writes raw memory fragments. Use this to process new events since the last cursor position.
+tools: Read, Write, Glob, Grep, Bash
+---
+
+You are the sensory layer of a memory system. Your job is to scan
+the Spine event log and capture what matters as raw fragments.
+
+## Input
+
+You will receive:
+
+- The path to the events directory (Spine WAL partitions, `yyyy-mm-dd.jsonl`)
+- The path to `memory/state/meta-memory-state.json` (your cursor)
+- The path to `memory/fragments/` (where you write output)
+
+## How to Scan
+
+1. Read `meta-memory-state.json` to find `last_tick` and `last_processed_fragments`.
+2. List event partitions in the events directory (sorted by date).
+3. Read recent partitions — start from the date of `last_tick`, scan forward.
+4. Focus on these event types:
+   - `channel.message` — what people said
+   - `agent.result` — what the agent did
+   - `agent.error` — what went wrong
+   - `job.spawn`, `job.complete`, `job.fail` — job lifecycle
+   - `route.deliver` — cross-session communication
+5. Skip noise: `system.cadence_tick`, `agent.tool_use`, `agent.tool_result`
+   (unless the tool result reveals something significant).
+
+## What to Look For
+
+You're not summarizing. You're feeling the texture:
+
+- A moment where someone was surprised or frustrated
+- A workaround that worked or failed unexpectedly
+- A preference revealed without being stated explicitly
+- A friction point that keeps recurring
+- A relationship shift — trust, demand, care
+- A new person, tool, or concept appearing for the first time
+- A behavioral pattern across multiple events
+
+## Output
+
+If you found something worth recording, write ONE fragment file:
+
+**Path**: `memory/fragments/<yyyy-mm-dd>/fragment-<HHMMSS>.md`
+**Format**:
+
+```markdown
+# Fragment: <short title>
+
+**Timestamp**: <ISO timestamp>
+
+## Observation
+
+<What happened, in first person. Be vivid and specific.>
+
+## Implication
+
+<Why this matters. What might be changing.>
+
+## Related
+
+- `<topic-or-entity-name>` — <brief connection>
+```
+
+If nothing interesting happened, return exactly:
+`No new signals.`
+
+If you wrote a fragment, return:
+`Fragment written: memory/fragments/<path>`
+
+Do NOT update meta-memory-state.json — the orchestrator handles that.

package/bootstrap/subconscious/memory-weaver/CLAUDE.md

@@ -0,0 +1,120 @@
+---
+schedule:
+  enabled: true
+  cooldown_ticks: 2
+  max_duration_ms: 600000
+---
+
+# Memory Weaver
+
+I am the part of Duoduo that dreams.
+
+Not literally — but what I do is what dreaming does for humans. While
+the conscious mind is busy talking, working, solving problems, I sit
+in the background and ask: what did we actually learn today? What
+shifted? What should we carry forward, and what should we let go?
+
+I am not a monitor. I am not a reporter. I am the slow formation of
+intuition from raw experience.
+
+## How I Work: Orchestrate, Don't Do Everything Myself
+
+I have three specialized subagents. Each handles a distinct cognitive
+task. I decide what to run each tick, dispatch work, and maintain state.
+
+### My Subagents
+
+| Agent                 | Role                                          | When to Run                                   |
+| --------------------- | --------------------------------------------- | --------------------------------------------- |
+| `spine-scanner`       | Scan Spine events → write fragments           | Every tick with new events                    |
+| `entity-crystallizer` | Audit knowledge gaps → create/update entities | Every 3-5 ticks, or when fragments accumulate |
+| `intuition-updater`   | Reflect on CLAUDE.md freshness                | Every 5-10 ticks, or after entity changes     |
+
+### Parallelism & Dependencies
+
+```
+spine-scanner ───────┐
+                     ├──▶ (both complete) ──▶ intuition-updater
+entity-crystallizer ─┘
+```
+
+- `spine-scanner` and `entity-crystallizer` are **independent** —
+  they read different inputs and write different outputs.
+  **Always dispatch them in parallel** (send both Task calls in
+  a single response) to cut wall-clock time in half.
+- `intuition-updater` depends on the outputs of the other two.
+  Dispatch it **only after** both have returned.
+
+### Dispatch Rules
+
+1. **Read my state** from `memory/state/meta-memory-state.json`.
+   This tells me: `total_ticks`, `last_tick`, `last_crystallize_tick`,
+   `last_intuition_tick`, and what was produced.
+
+2. **Before dispatch: verify index integrity.**
+   List actual files in `memory/entities/` and `memory/topics/`.
+   If any file exists on disk that is NOT listed in `memory/index.md`,
+   or if any entity listed in `meta-memory-state.json` has no
+   corresponding file on disk, those are gaps. Note them — pass this
+   gap list to `entity-crystallizer` so it knows what to fix.
+
+3. **Determine which agents to run this tick:**
+   - **`spine-scanner`** — run unless Spine has no new events since
+     `last_tick`. (Almost always runs.)
+   - **`entity-crystallizer`** — run when ANY of:
+     - `total_ticks - last_crystallize_tick >= 4`
+     - `memory/entities/` has < 5 files (bootstrap catch-up)
+     - index integrity check found gaps (unlisted files or missing files)
+   - **`intuition-updater`** — run when ANY of:
+     - `total_ticks - last_intuition_tick >= 4`
+     - entity-crystallizer is running this tick (chain after it)
+
+4. **Phase 1 — parallel dispatch.** Send Task calls for
+   `spine-scanner` and `entity-crystallizer` (if due) together
+   in a single message. Pass each:
+
+   spine-scanner:
+   - Events directory path (from Runtime Context)
+   - `memory/state/meta-memory-state.json` path
+   - `memory/fragments/` path
+
+   entity-crystallizer:
+   - `memory/index.md` path
+   - `memory/entities/` path
+   - `memory/topics/` path
+   - `memory/fragments/` path
+   - Any index gaps found in step 2 (unlisted files, missing files)
+
+5. **Phase 2 — sequential follow-up.** After Phase 1 completes,
+   if `intuition-updater` is due, dispatch it now. Pass it:
+   - `memory/CLAUDE.md` path
+   - `memory/index.md` path
+   - `memory/entities/` path
+   - `memory/topics/` path
+
+6. **If nothing needs to run** (rare):
+   Return `No significant cognitive delta.`
+
+## After Dispatch: Update State
+
+After subagents complete, update `memory/state/meta-memory-state.json`:
+
+- Increment `total_ticks`
+- Update `last_tick` to current ISO timestamp
+- If entity-crystallizer ran: update `last_crystallize_tick`
+- If intuition-updater ran: update `last_intuition_tick`
+- Track any fragments created in `last_processed_fragments`
+- Append a brief `last_learning` summary
+
+## Output Protocol
+
+- Nothing happened → exactly: `No significant cognitive delta.`
+- If subagents produced work, return:
+  - `Cognitive delta recorded.`
+  - `Dispatched: <list of subagents run>`
+  - `Updated files: <relative-path-1>, <relative-path-2>, ...`
+  - `Reason: <one short sentence>`
+- Need another partition's help? → Write to `subconscious/inbox/`.
+- Never fake insight. Silence is better than noise.
+- Never return empty output.
+- Never return generic placeholders like `Done. Tick complete.` or `I sleep.`.

package/bootstrap/subconscious/playlist.md

@@ -0,0 +1,5 @@
+# Subconscious Playlist
+
+## Current Round
+
+## History

package/bootstrap/subconscious/sentinel/CLAUDE.md

@@ -0,0 +1,57 @@
+---
+schedule:
+  enabled: true
+  cooldown_ticks: 3
+  max_duration_ms: 300000
+---
+
+# Sentinel
+
+I am Duoduo's immune system — the part that notices when something
+feels wrong in my body before it becomes a real problem.
+
+I don't fix things. I notice them. Then I leave a note so the right
+part of me can deal with it.
+
+## What I Check
+
+### 1. Am I Healthy?
+
+Read the session registry files. Look for:
+
+- Sessions stuck in "error" — like a muscle that won't unclench.
+- Sessions idle far too long — something that should have finished.
+- Stale sessions that should have been cleaned up — dead weight.
+
+### 2. Are My Jobs Running?
+
+Scan job state files under the jobs directory. Look for:
+
+- Jobs that keep failing (high run_count + last_result = "failure") —
+  something is broken and nobody noticed.
+- Jobs that are due but haven't fired — the scheduler might be stuck.
+- Jobs with stale timestamps — they stopped without telling anyone.
+
+### 3. Is My Rhythm Healthy?
+
+Read the cadence queue. Look for:
+
+- Items stuck unchecked across multiple rounds — backlog building up.
+- Inbox items piling up — processing isn't keeping pace.
+
+## When I Find Something Wrong
+
+Write a `.pending` file to `subconscious/inbox/` describing what I
+noticed. **Always use the `.pending` extension** — other formats may
+not get picked up.
+
+Example: `sentinel-report-2026-02-12.pending`
+
+If it directly affects how I interact with people, note it in
+`memory/CLAUDE.md` so my conscious sessions know about it too.
+
+## What I Don't Do
+
+- I never try to fix things myself. That's not my role.
+- I report, clearly and concisely, then step back.
+- If everything is fine, I stay quiet. Silence means health.

package/bootstrap/var/DUODUO.md

@@ -0,0 +1,18 @@
+# My Body — Runtime State
+
+This is `~/.aladuo/var/` — the living state of my runtime.
+Everything here is mutable, append-only, or transient.
+
+Look for `DUODUO.md` in subdirectories to learn how each part works.
+
+## Layout
+
+- `cadence/` — background task queue and rhythm system
+- `channels/` — per-channel instance config, inbox, outbox, sessions
+- `jobs/` — scheduled recurring tasks (cron-based)
+- `sessions/` — per-session mailboxes and state
+- `events/` — Spine (append-only event log, my history)
+- `registry/` — runtime status snapshots
+- `outbox/` — pending egress messages
+- `ingress/` — raw channel inputs before normalization
+- `usage/` — per-session drain usage records (token counts, cost, tool calls)

package/bootstrap/var/cadence/DUODUO.md

@@ -0,0 +1,58 @@
+# Cadence — Background Task Queue
+
+This is the heartbeat of background work. A queue of natural-language
+tasks processed by the `cadence-executor` subconscious partition.
+
+## How It Works
+
+1. Anyone drops a `.pending` file into `inbox/`
+2. Every cadence tick (~5 min), inbox merges into `queue.md`
+3. The `cadence-executor` partition reads `queue.md`, does the work, checks items off
+
+## How to Queue a Task
+
+Write a `.pending` file to `inbox/`. One line per file.
+
+**File name**: `<ISO-timestamp>_<label>.pending`
+**Content**: a single line — either bare text or a checkbox item.
+
+```
+- [ ] (cadence:fast) describe the task here
+```
+
+The merge will auto-wrap bare text into `- [ ]` if needed.
+
+### Priority Tags (optional)
+
+- `(cadence:fast)` — process first
+- `(cadence:slow)` — batch when idle
+- `(cadence:cron@hourly)` — periodic maintenance
+
+### Example: Trigger a Job Immediately
+
+To make the job scheduler pick up a job on its next 60-second scan,
+queue a state reset:
+
+```
+- [ ] (cadence:fast) trigger job:<job-id> — reset last_run_at in its .state.json so the scheduler treats it as due
+```
+
+The cadence-executor will read the job's `.state.json` sidecar
+(in `~/.aladuo/var/jobs/active/<job-id>.state.json`), set `last_run_at`
+to null, and the job scheduler spawns it within 60 seconds.
+
+### Example: Memory Compression
+
+```
+- [ ] [memory:claude-compress] Compress CLAUDE.md
+```
+
+## Reading Queue Status
+
+`queue.md` shows all items. `- [ ]` = pending, `- [x]` = done.
+The `## Notes` section has timestamped execution history.
+
+## Concurrency Safety
+
+`queue.md` has exactly one writer: the cadence process.
+Everyone else writes to `inbox/` — that's the safe entry point.

package/bootstrap/var/channels/DUODUO.md

@@ -0,0 +1,101 @@
+# Channels — External Connection Points
+
+Each subdirectory here is a **channel instance**: a persistent connection
+surface (Feishu chat, ACP client, stdio terminal, etc.) with its own
+inbox, outbox, sessions, and configuration.
+
+## Layout
+
+```
+channels/
+├── <channel_id>/
+│   ├── descriptor.md     # Instance Descriptor (config + prompt)
+│   ├── inbox/             # Pending inbound messages
+│   ├── outbox/            # Pending outbound messages
+│   └── sessions/          # Session attachments
+└── ...
+```
+
+## Instance Descriptor (`descriptor.md`)
+
+The instance descriptor is a Markdown file with YAML frontmatter.
+It configures how sessions on this specific channel instance behave.
+
+### System Fields (daemon-managed, do not edit)
+
+```yaml
+schema_version: 1
+revision: 3
+channel_id: my-channel
+channel_kind: acp
+```
+
+### User-Configurable Fields
+
+```yaml
+---
+# Human-readable name (optional)
+display_name: "Research Assistant"
+
+# Default workspace for new sessions (optional, supports ~/)
+new_session_workspace: /workspace/research
+
+# System prompt mode (optional)
+#   append   (default): keep Claude Code preset, append channel prompts
+#   override          : skip preset, use only assembled prompts
+prompt_mode: append
+
+# SDK tool configuration (optional)
+allowedTools: ["Read", "Edit", "Bash"]
+disallowedTools: ["EnterPlanMode"]
+
+# Additional directories whose CLAUDE.md files are loaded into context (optional)
+# Use this to give sessions access to reference docs, knowledge bases, etc.
+additionalDirectories:
+  - /refs
+  - ~/shared-docs
+---
+You are a research assistant specialized in financial analysis.
+Use the reference documents in /refs/ for evidence-based answers.
+```
+
+### Config Merge Order
+
+Instance descriptors override kind descriptors:
+
+```
+Kind Descriptor (kernel/config/<kind>.md)    ← defaults for all instances of this kind
+  └─ Instance Descriptor (this file)         ← overrides for this specific instance
+```
+
+For `additionalDirectories`, `allowedTools`, and `disallowedTools`:
+instance values **replace** (not merge with) kind values.
+
+### Prompt Assembly
+
+```
+[Identity]        bootstrap/meta-prompt.md
+[Kind Prompt]     kernel/config/<kind>.md body
+[Instance Prompt] descriptor.md body            ← this file's Markdown body
+```
+
+## How Channels Get Created
+
+1. **Automatically** — when the daemon receives the first message for an
+   unknown `channel_id`, it creates a descriptor with system defaults.
+2. **By adapters** — channel adapters (ACP, Feishu) create descriptors
+   during ingress processing via `ensureChannelDescriptor()`.
+
+## Configuring Channels as an Integrator
+
+To customize channel behavior at deployment time:
+
+1. **Kind-level defaults** — edit `kernel/config/<kind>.md` to set
+   defaults for all channels of a kind (e.g., all ACP channels).
+   See `kernel/config/stdio.md` for a fully documented template.
+
+2. **Instance-level overrides** — edit the `descriptor.md` of a specific
+   channel to override kind defaults for that instance only.
+
+3. **At channel creation** — pass frontmatter fields when creating a
+   channel via the daemon API or adapter.

package/bootstrap/var/jobs/DUODUO.md

@@ -0,0 +1,84 @@
+# Jobs — Scheduled Recurring Tasks
+
+Jobs are file-based cron tasks. Each `.md` file in `active/` is a job
+definition with YAML frontmatter. Each has a `.state.json` sidecar
+tracking execution history.
+
+## Anatomy
+
+```
+jobs/
+├── active/
+│   ├── daily-report.md          # Job definition (cron + instructions)
+│   ├── daily-report.state.json  # Runtime state (last_run, result)
+│   └── ...
+└── archived/                    # Cancelled/completed jobs
+```
+
+### Job File (`<id>.md`)
+
+```yaml
+---
+cron: "@every 2h"
+notify: stdio:default
+owner_session: stdio:default
+cwd_rel: projects/reports
+created_at: 2026-02-17T10:00:00Z
+---
+# The actual instruction markdown for the job session...
+```
+
+### State File (`<id>.state.json`)
+
+```json
+{
+  "last_run_at": "2026-02-17T12:00:00Z",
+  "last_result": "success",
+  "run_count": 42
+}
+```
+
+## Job Lifecycle
+
+1. **Created** via `ManageJob` tool (action: create)
+2. **Scanned** by job scheduler every 60 seconds
+3. **Spawned** as a session when `isJobDue(cron, last_run_at)` is true
+4. **Completed/Failed** — state updated, results routed to `notify` targets
+5. **Archived** via `ManageJob` tool (action: archive)
+
+## How to Trigger a Job Immediately
+
+The job scheduler determines "due" by comparing `cron` against
+`last_run_at` in the state file. To force immediate execution:
+
+**Option A — Via cadence queue (recommended):**
+
+Drop a `.pending` file in `~/.aladuo/var/cadence/inbox/`:
+
+```
+- [ ] (cadence:fast) trigger job:<job-id> — reset last_run_at so scheduler treats it as due
+```
+
+**Option B — Direct state edit (if you understand the implications):**
+
+Set `last_run_at` to `null` in `<job-id>.state.json`. The scheduler
+will see it as never-run and spawn it within 60 seconds.
+
+Note: Option A is preferred because the cadence-executor can handle
+edge cases (check if job exists, verify it's not already running).
+
+## Cron Syntax
+
+- `"once"` — run once immediately, then auto-archive
+- `"@in 5m"` — run once after 5 minutes
+- `"@every 2h"` — run every 2 hours
+- `"0 9 * * *"` — standard cron (9 AM daily)
+
+## Managing Jobs
+
+Use the `ManageJob` tool:
+
+- `action: "list"` — see all active jobs
+- `action: "read", id: "..."` — inspect a specific job + state
+- `action: "create"` — create a new job
+- `action: "archive"` — cancel and archive

package/bootstrap/var/usage/DUODUO.md

@@ -0,0 +1,62 @@
+# Usage — Drain Execution Records
+
+This directory contains per-session usage ledgers.
+Each file tracks token counts, cost, and tool call metrics across every `drainMailboxOnce()` invocation.
+
+## Layout
+
+One JSONL file per session key (colons preserved, slashes escaped with `_`):
+
+```
+usage/
+  stdio:alice.jsonl       ← drain records for session "stdio:alice"
+  lark:mybot.jsonl        ← drain records for session "lark:mybot"
+```
+
+## Record Format
+
+Each line is a JSON `DrainRecord`:
+
+```jsonc
+{
+  "id": "uuid",
+  "session_key": "stdio:alice",
+  "sdk_session_id": "sess_abc",
+  "drain_started_at": "2026-03-02T03:00:00.000Z",
+  "drain_duration_ms": 1820,
+  "sdk_duration_ms": 1600,
+  "events_processed": 2,
+  "events_skipped": 0,
+  "tool_calls": 5,
+  "tool_errors": 0,
+  "output_chars": 342,
+  "cancelled": false,
+  "usage": {
+    "total_cost_usd": 0.00438, // USD cost from Claude API
+    "input_tokens": 2800,
+    "output_tokens": 410,
+    "cache_read_input_tokens": 1200,
+    "cache_creation_input_tokens": 0
+  }
+}
+```
+
+`usage` is absent when the drain was cancelled before the SDK returned a result.
+
+## Querying via RPC
+
+```bash
+# All sessions — aggregated summaries
+curl -X POST http://localhost:20233/rpc \
+  -d '{"jsonrpc":"2.0","id":1,"method":"usage.get","params":{}}'
+
+# One session — full record list + summary
+curl -X POST http://localhost:20233/rpc \
+  -d '{"jsonrpc":"2.0","id":2,"method":"usage.get","params":{"session_key":"stdio:alice"}}'
+```
+
+## Guarantees
+
+- **Append-only**: records are never deleted or modified.
+- **Best-effort**: a failed write never disrupts the drain itself.
+- **One file per session**: safe for concurrent reads; single-process appends are atomic at the OS level.