@openduo/duoduo 0.2.12 → 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/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/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