@openduo/duoduo 0.2.11 → 0.3.0

package/bootstrap/config/stdio.md

@@ -17,7 +17,16 @@
 #    Example:
 #    prompt_mode: append
 #
-# 3) Claude Agent SDK-aligned options (optional)
+# 3) time_gap_minutes (optional, number)
+#    Minutes of inactivity before injecting a time-context hint into the
+#    next user turn. Helps the agent sense elapsed time after idle gaps.
+#    Set to 0 to disable. Instance Descriptors override Kind Descriptors.
+#    Default: 60 (1 hour).
+#
+#    Example:
+#    time_gap_minutes: 30
+#
+# 4) Claude Agent SDK-aligned options (optional)
 #    These keys map directly to SDK query() options and may also be set on
 #    Instance Descriptors. Instance values override Kind values.
 #    Runtime defaults still apply underneath: ALADUO disables

package/bootstrap/subconscious/cadence-executor/CLAUDE.md

@@ -37,7 +37,7 @@ When a queue item contains `trigger job:<id>`:
 
 1. Use `ManageJob` (action: read) to verify the job exists.
 2. Read the job's `.state.json` sidecar file (path shown in job info).
-3. Set `last_run_at` to `null` in that file and write it back.
+3. Set `last_scheduled_at` to `null` in that file and write it back.
 4. The job scheduler (60-second cycle) will see it as due and spawn it.
 
 If the job doesn't exist or is already running, note the error and

package/bootstrap/var/DUODUO.md

@@ -15,4 +15,5 @@ Look for `DUODUO.md` in subdirectories to learn how each part works.
 - `registry/` — runtime status snapshots
 - `outbox/` — pending egress messages
 - `ingress/` — raw channel inputs before normalization
+- `telemetry/` — structured runtime latency samples for offline aggregation
 - `usage/` — per-session drain usage records (token counts, cost, tool calls)

package/bootstrap/var/cadence/DUODUO.md

@@ -34,11 +34,11 @@ 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
+- [ ] (cadence:fast) trigger job:<job-id> — reset last_scheduled_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`
+(in `~/.aladuo/var/jobs/active/<job-id>.state.json`), set `last_scheduled_at`
 to null, and the job scheduler spawns it within 60 seconds.
 
 ### Example: Memory Compression

package/bootstrap/var/jobs/DUODUO.md

@@ -32,7 +32,8 @@ created_at: 2026-02-17T10:00:00Z
 
 ```json
 {
-  "last_run_at": "2026-02-17T12:00:00Z",
+  "last_scheduled_at": "2026-02-17T12:00:00Z",
+  "last_run_at": "2026-02-17T12:01:30Z",
   "last_result": "success",
   "run_count": 42
 }
@@ -42,27 +43,27 @@ created_at: 2026-02-17T10:00:00Z
 
 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
+3. **Spawned** as a session when `isJobDue(cron, last_scheduled_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:
+`last_scheduled_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
+- [ ] (cadence:fast) trigger job:<job-id> — reset last_scheduled_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.
+Set `last_scheduled_at` to `null` in `<job-id>.state.json`. The scheduler
+will see it as never-scheduled 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).

package/bootstrap/var/telemetry/DUODUO.md

@@ -0,0 +1,61 @@
+# Telemetry — Structured Runtime Samples
+
+This directory contains append-only JSONL telemetry files for low-level runtime timings.
+
+These records are separate from `usage/`:
+
+- `usage/` is scoped to one `drainMailboxOnce()` execution and focuses on per-session work.
+- `telemetry/` is for cross-cutting transport and gateway timings that do not fit cleanly into a single drain record.
+
+## Layout
+
+Files are partitioned by UTC day:
+
+```text
+telemetry/
+  2026-03-14.jsonl
+  2026-03-15.jsonl
+```
+
+## Record Format
+
+Each line is one JSON object. The current metric records look like:
+
+```jsonc
+{
+  "kind": "metric",
+  "metric": "ingress_snapshot_ms",
+  "value": 4.2,
+  "ts": 1773475200000,
+  "eventId": "evt_123",
+  "sessionKey": "stdio:alice",
+  "sourceKind": "stdio"
+}
+```
+
+Current metric names:
+
+- `ingress_snapshot_ms` — gateway snapshot persistence latency
+- `replay_scan_ms` — unread outbox scan latency during pull/replay
+- `cursor_load_ms` — delivery cursor read latency
+- `cursor_store_ms` — delivery cursor write latency
+
+Extra fields may vary by metric. They are for debugging context and may grow over time.
+
+## Reporting
+
+Use the report helper to aggregate recent samples:
+
+```bash
+pnpm run telemetry:report -- --since 30m
+```
+
+Bare numeric values are treated as minutes, so `--since 90` means the last 90 minutes.
+
+The report prints `count`, `avg`, `p50`, `p95`, and `max` for each known metric.
+
+## Guarantees
+
+- **Append-only**: telemetry files are never rewritten in place.
+- **Best-effort**: failed telemetry writes never block the main runtime path.
+- **Low ceremony**: records are plain JSONL so they are easy to inspect with shell tools.

package/bootstrap/var/usage/DUODUO.md

@@ -1,7 +1,7 @@
 # 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.
+Each file tracks token counts, cost, tool call metrics, and runner-side local performance snapshots across every `drainMailboxOnce()` invocation.
 
 ## Layout
 
@@ -37,11 +37,36 @@ Each line is a JSON `DrainRecord`:
     "output_tokens": 410,
     "cache_read_input_tokens": 1200,
     "cache_creation_input_tokens": 0
+  },
+  "perf": {
+    "mailbox_merge_ms": 6.1,
+    "mailbox_parse_ms": 1.8,
+    "session_snapshot_ms": 2.2,
+    "session_state_ms": 0.9,
+    "outbox_lookup_ms": 0.4,
+    "event_read_ms": 1.6,
+    "effective_config_ms": 0.7,
+    "outbox_emit_ms": 4.3,
+    "session_upsert_ms": 1.5,
+    "mailbox_finalize_ms": 1.1,
+    "sdk_ttft_ms_total": 842,
+    "sdk_ttft_samples": 1
   }
 }
 ```
 
 `usage` is absent when the drain was cancelled before the SDK returned a result.
+`perf` is optional and records best-effort local timings for the runner-side stages observed during that drain.
+
+## Summary Semantics
+
+`usage.get` returns both per-record detail and an aggregated summary.
+
+- `usage` fields are summed across records in the summary.
+- `perf` fields are also summed across records in the summary.
+- `sdk_ttft_ms_total / sdk_ttft_samples` are emitted separately so callers can compute average TTFT without losing sample count.
+
+These timings are scoped to one `drainMailboxOnce()` execution. Transport-side or consumer-side costs such as ingress snapshots, replay scans, websocket delivery, and CLI rendering are not part of this ledger yet.
 
 ## Querying via RPC