@aitne/daemon 0.1.7 → 0.1.9

package/dist/core/morning/orchestrator.d.ts

@@ -0,0 +1,424 @@
+/**
+ * `MorningRoutinePipelineOrchestrator` — Phase 5 of
+ * `docs/design/appendices/morning-routine-optimization.md`. Replaces the
+ * single monolithic medium-tier session that today's
+ * `MorningRoutineRunner.executeMorningRoutine` runs with a daemon-
+ * orchestrated pipeline:
+ *
+ *     ① rotateDayFiles                          (owned by MorningRoutineRunner)
+ *     ② HandoffParser                           (this module)
+ *     ③ JournalSkeletonBuilder                  (this module)
+ *     ④ Pre-pass fan-out                        (owned by MorningRoutineRunner)
+ *     ⑤A Stage A: today.md synthesis  [medium]  (this module)  ─┐ Promise.all
+ *     ⑤B Stage B: daily journal author [lite]   (this module)  ─┘
+ *     ⑥  AgentJournalAppender                   (Phase 6 — left to MorningRoutineRunner)
+ *     ⑥b parent audit row emit                  (this module)
+ *     ⑦  diagnoseTodayMdState                   (owned by MorningRoutineRunner)
+ *     ⑧  Post-morning catchups + roadmap_refresh (owned by MorningRoutineRunner)
+ *
+ * The orchestrator owns only ②③⑤A∥⑤B⑥b. ① and ④ are upstream of `run()`;
+ * ⑥, ⑦, ⑧ stay with the runner so the existing today.md health check /
+ * retry chain / catchups continue to work unchanged on both legacy and
+ * V2 paths.
+ *
+ * Stage event design:
+ *   - Stage A event.type = `routine.morning_routine_today` so its
+ *     `agent_actions` row lands with `action_type='routine.morning_routine_today'`
+ *     (the audit logger derives action_type from `event.type`). Stage A's
+ *     `routine` field stays `"morning_routine"` so ContextBuilder's
+ *     existing heavy-context branch fires (yesterday.md / roadmap.md /
+ *     active_projects / calendar_events_7d).
+ *   - Stage B event.type = `routine.morning_routine_journal`. Stage B's
+ *     `routine` field is `"morning_routine_journal"` so ContextBuilder
+ *     fires the minimal Stage-B branch added in Phase 5 (calendar_events_7d
+ *     for wikilink resolution; no yesterday / roadmap / projects).
+ *   - Both stage events share `correlationId` with the parent
+ *     `routine.morning_routine` envelope — `loadMorningRoutineActionRows`
+ *     and `emitMorningRoutineParentAuditRow` use that as `event_id` to
+ *     correlate.
+ *
+ * Today.md write-lock: Stage A inherits the lockId set on the parent
+ * event by `MorningRoutineRunner` (the lock is acquired before this
+ * runs and released after); Stage B does not write to today.md and
+ * does not receive the lockId.
+ *
+ * Retry semantics (rev2 — `morning-routine-optimization.md`
+ * §"Pipeline-level invariants"):
+ *   - The retry chain is gated on today.md health; only Stage A regen
+ *     is what fixes a missing / wrong-date today.md. On retry,
+ *     `inputs.isRetry` is true and Stage B is NOT re-fired. Phase 5
+ *     simplification: if Stage B succeeded on attempt 1, its
+ *     `daily/<yesterday>.md` is already on disk and re-firing would
+ *     hit the 200/PATCH-Agent-revision path, producing a second
+ *     journal entry on every retry; if Stage B failed on attempt 1,
+ *     re-firing would still risk that duplication once the next
+ *     scheduled write succeeds. The trade-off is documented in design
+ *     §"Retry semantics" — Phase 6 may revisit if structured Stage B
+ *     result tracking justifies the work.
+ *
+ * Pre-pass skip on retry: not enforced here because `MorningRoutineRunner`
+ * already short-circuits the pre-pass when `isRetry === true`. The
+ * pre-pass result lives on the parent event's `event.data.fetchReportBlock`
+ * and is forwarded into the Stage A event unchanged (Stage B does not
+ * consume it).
+ */
+import type Database from "better-sqlite3";
+import { type AgentResult, type BackendId, type Event, type ProcessKey } from "@aitne/shared";
+import type { AgentConfig } from "../../config.js";
+import type { IAuditLogger, IContextBuilder } from "../dispatcher-types.js";
+import type { PromptAssembler } from "../dispatcher-prompt.js";
+import { type IAgentRouter } from "../backends/backend-router.js";
+import type { DispatcherErrorRouter } from "../dispatcher-error-handling.js";
+import type { ResultProcessor } from "../dispatcher-result-processor.js";
+import type { AgentWriteTracker } from "../../safety/agent-write-tracker.js";
+import { type ParentAuditEmitResult, type TodayMdHealth } from "./parent-audit-emitter.js";
+import { type AgentJournalAppenderResult } from "./agent-journal-appender.js";
+import type { DailyJournalComposer } from "./daily-journal-composer.js";
+import { type PartialExtractStreakNotifier } from "./partial-extract-streak.js";
+declare const STAGE_A_PROCESS_KEY: ProcessKey;
+declare const STAGE_B_PROCESS_KEY: ProcessKey;
+/**
+ * The `routine` slug carried on each stage's RoutineEvent. Stage A reuses
+ * the legacy `"morning_routine"` value so the heavy ContextBuilder branch
+ * (yesterday.md / roadmap.md / active_projects / calendar_events_7d)
+ * continues to fire unchanged — the Phase 5 split is about dispatch
+ * shape, not Stage A's context inputs. Stage B's
+ * `"morning_routine_journal"` slug routes into the minimal branch added
+ * to ContextBuilder for Phase 5.
+ */
+declare const STAGE_A_ROUTINE_SLUG = "morning_routine";
+declare const STAGE_B_ROUTINE_SLUG = "morning_routine_journal";
+export interface MorningPipelineOrchestratorDeps {
+    db: Database.Database;
+    config: AgentConfig;
+    contextBuilder: IContextBuilder;
+    agentRouter: IAgentRouter;
+    prompt: PromptAssembler;
+    errorRouter: DispatcherErrorRouter;
+    resultProcessor: ResultProcessor;
+    /**
+     * morning-routine-optimization.md Phase 6 — pre-insert an
+     * `agent_actions(result='in_progress', action_type='routine.morning_routine_today')`
+     * row before Stage A spawns so the agent's
+     * `PATCH /api/agent-actions/self` can resolve and write its structured
+     * metadata side-channel. Optional so Phase 5 tests that don't exercise
+     * the metadata pathway can construct the orchestrator without an
+     * `IAuditLogger` mock. Production wiring always supplies it.
+     */
+    audit?: IAuditLogger;
+    /**
+     * morning-routine-optimization.md Phase 6 — ⑥ AgentJournalAppender
+     * needs the safety write-tracker so the journal's atomic write does
+     * not get tagged as a user-actor change by the obsidian / git
+     * observers (which would re-trigger the hourly check on the agent's
+     * own output). The context-index reconciler is intentionally NOT
+     * threaded here: `journal/agent.md` is not in the indexable set, so
+     * the chokidar fallback path covers it without an explicit hint.
+     */
+    writeTracker?: AgentWriteTracker;
+    /**
+     * daily-journal-daemon-write.md §4.11 — Stage B's daily journal
+     * compose step. The orchestrator invokes the composer AFTER
+     * `Promise.allSettled` settles both stages and BEFORE
+     * `persistStageAuditRows` so the compose outcome lands on the same
+     * INSERT/UPSERT as the Stage B audit row (`detail.dailyWrite`).
+     *
+     * Optional so the Phase 5 test fixtures that don't exercise the
+     * daily-write path can construct the orchestrator without a real
+     * composer. Production wiring always supplies it; when omitted the
+     * orchestrator skips the compose call entirely (Stage B's audit row
+     * lands without `detail.dailyWrite` and `agent-journal-appender`
+     * falls back to the file-presence heuristic).
+     */
+    dailyJournalComposer?: DailyJournalComposer;
+    /**
+     * daily-journal-daemon-write.md §4.7b — owner-DM emitter the
+     * partial-extract streak detector uses. The orchestrator passes the
+     * existing `sendNotification` chain via a thin adapter so the
+     * detector doesn't depend on Hono / messaging adapters directly.
+     * Optional: when omitted the streak detector still runs (SQL is
+     * cheap, the result is logged), but no DM is emitted.
+     */
+    partialExtractStreakNotifier?: PartialExtractStreakNotifier;
+}
+export interface MorningPipelineRunInputs {
+    /**
+     * The parent `routine.morning_routine` event. Its `correlationId` is
+     * the link parent-audit-emitter uses to find both stages' agent_actions
+     * rows; `data.fetchReportBlock` (pre-pass output) and
+     * `data.todayWriteLockId` (today.md lock from the runner) are
+     * forwarded to Stage A verbatim.
+     */
+    parentEvent: Event;
+    /**
+     * Mirrors `MorningRoutineRunner`'s `isRetry` derivation. When true,
+     * Stage B is skipped (see §"Retry semantics" in the module JSDoc).
+     */
+    isRetry: boolean;
+    /**
+     * When set, both stages' `resolveBinding` calls receive this as
+     * `requestedTier`. `MorningRoutineRunner` forces `"medium"` on retry;
+     * the orchestrator forwards verbatim so Stage A's cost-cap-fix
+     * downgrade behaviour is preserved. Stage B ignores the override —
+     * it always runs on lite per `routine.morning_routine_journal`'s
+     * process-key default. (Forcing Stage B to medium on retry would
+     * defeat the whole point of the split, and the journal author has
+     * no failure mode that medium would fix.)
+     */
+    requestedTier?: "lite" | "medium" | "high";
+}
+export interface MorningPipelineRunResult {
+    /**
+     * Stage A's `AgentResult`. `MorningRoutineRunner.processResult` is
+     * invoked on this so today.md health checks / drift / cost telemetry
+     * follow the same path as the legacy monolithic session.
+     */
+    stageAResult: AgentResult;
+    /**
+     * Stage B's `AgentResult`, or `null` when Stage B was skipped (retry
+     * path) or its session threw before producing a result. Stage B
+     * failure does not block the pipeline — the journal author is
+     * independent of today.md health, so its absence surfaces only in
+     * the parent audit row's `detail.stageB` field.
+     */
+    stageBResult: AgentResult | null;
+    /**
+     * Snapshot of `Date.now()` taken when `run()` is first invoked. Used
+     * by `MorningRoutineRunner` as the parent audit row's `started_at`
+     * when it later calls `emitParentAuditRow`.
+     */
+    startedAt: Date;
+}
+export declare class MorningRoutinePipelineOrchestrator {
+    private readonly deps;
+    constructor(deps: MorningPipelineOrchestratorDeps);
+    /**
+     * Drive ②③⑤A∥⑤B. The caller (`MorningRoutineRunner`) is responsible
+     * for invoking ⑦ (today.md health diagnose) and ⑥b (parent audit
+     * emit, via `emitParentAuditRow`) afterwards.
+     *
+     * Errors:
+     *   - Stage A throw → re-thrown so the runner's outer try/finally
+     *     (lock release + flag reset) still fires, and the runner's
+     *     `diagnoseTodayMdState` post-check catches the missing today.md
+     *     and schedules a retry the same way legacy failures do.
+     *   - Stage B throw → logged + folded into `stageBResult=null`. Does
+     *     NOT propagate; Stage B failure is independent of today.md
+     *     health (the day still opens, the journal is best-effort).
+     */
+    run(inputs: MorningPipelineRunInputs): Promise<MorningPipelineRunResult>;
+    /**
+     * Wrap `agentRouter.resolveBinding` so a resolver-side throw (e.g. a
+     * malformed `process_backend_config` row) doesn't abort the whole
+     * `run()` before either stage gets a chance to dispatch. A null
+     * binding signals "binding unknown" to the failure-path writer; the
+     * resulting `agent_actions(result='failed')` row will lack the
+     * backend / model columns but still pin the failure to a known
+     * stage event. The stage's own `runStage*` will re-throw the same
+     * resolution error on dispatch and that's what
+     * `persistStageAuditRows` records.
+     */
+    private safeResolveBinding;
+    /**
+     * Write per-stage `agent_actions` rows for both success and failure
+     * outcomes. Each stage's row lands keyed on its OWN `RoutineEvent`
+     * (carrying the stage's process-key event type), so the row's
+     * `action_type` is `routine.morning_routine_today` /
+     * `routine.morning_routine_journal` — exactly what
+     * `parent-audit-emitter.readStageSummaries` and the Phase 6
+     * `agent-journal-appender` will read.
+     *
+     * Success path → `processResult` (which calls `audit.logAction`,
+     * settling the in_progress sentinel row to `result='success'`).
+     *
+     * Failure path → `audit.logError` (which UPSERTs the same in_progress
+     * sentinel to `result='failed'`, preserving the agent-side metadata
+     * column intact). Without the failure-path write, Stage B rejections
+     * (most commonly `BackendQuotaError(max_budget_usd)` from a tight
+     * lite-tier envelope) leave the audit trail with NO Stage B row at
+     * all — `agent-journal-appender.formatJournalLine` then falls into
+     * the `stageB === null` branch and renders `Journal synthesis:
+     * skipped (no prior-day data)`, indistinguishable from a legitimate
+     * first-run skip. This is the structural bug the failure-path write
+     * closes.
+     *
+     * Failures inside `processResult` or `audit.logError` do NOT
+     * propagate — losing audit rows is bad, but blocking the entire
+     * morning routine on a downstream telemetry hiccup is worse. In
+     * practice `audit.logAction` / `audit.logError` already swallow their
+     * own DB errors with an internal logger.error, so the catches here
+     * are defence-in-depth guards against non-audit hooks (notify side
+     * effects we don't expect for routine events but might land later).
+     *
+     * Tail-risk acknowledgement: if a stage row truly fails to land
+     * (audit's internal try/catch swallowed a real SQLite error AND
+     * `processResult`'s notification path threw too), the parent-audit
+     * emitter will return `stage_a_row_missing` and the pre-routine gate
+     * stays unfired for the day — that day's hourly_check / evening_review
+     * are skipped with `morning_routine_pending_for_today`, but
+     * `MAX_RETRIES`-bounded `scheduleMorningRetry` does NOT loop on this
+     * shape because today.md health is independent. The day's automation
+     * degrades silently for that day; it does not infinite-loop.
+     */
+    private persistStageAuditRows;
+    /**
+     * Write a `result='failed'` agent_actions row for a rejected stage.
+     * Uses `audit.logError`, which UPSERTs the matching in_progress
+     * sentinel row when one exists (Stage A's pre-insert) and INSERTs a
+     * fresh row otherwise (Stage B). Both paths land a terminal-state
+     * row keyed on `(event_id=correlationId, action_type=event.type)` so
+     * the downstream readers — `loadMorningRoutineActionRows`,
+     * `parent-audit-emitter.readStageSummaries`,
+     * `agent-journal-appender.formatJournalLine` — see one consistent
+     * shape per stage regardless of which terminal state the stage
+     * reached.
+     *
+     * Backend / model attribution: pulled from the pre-resolved binding
+     * when available, with a fallback to `BackendQuotaError.backendId`
+     * if the binding was unresolvable but the error happens to carry
+     * that field. Other failure shapes leave backend/model unset; the
+     * audit logger's `context` schema tolerates absent values.
+     */
+    private recordStageFailure;
+    /**
+     * daily-journal-daemon-write.md §4.11 — invoke the daily-journal
+     * composer when (a) the orchestrator has a composer dep, (b) Stage B
+     * was actually dispatched (event built), and (c) `buildStageBInputs`
+     * produced the skeleton facts the composer needs. Otherwise return
+     * `null` and let the appender fall back to file-presence detection.
+     *
+     * Reuses the SAME skeleton + counts cached on `stageBInputs` (the
+     * exact byte stream Stage B's prompt saw) rather than re-deriving
+     * against the live DB. Re-deriving was the previous behaviour and
+     * introduced a drift class: if a new DM or calendar observation
+     * landed during Stage A's wall-clock window, the LLM authored against
+     * Skeleton-V1 while the daemon wrote Skeleton-V2 frontmatter; ditto
+     * `updated:` if the agent day rolled over between the two reads.
+     *
+     * Stage B's `AgentResult` may be `null` even when the event was
+     * dispatched (the SDK threw mid-stream); the composer handles that
+     * explicitly via its `stage_b_null` reason.
+     */
+    private composeDailyJournalIfPossible;
+    /**
+     * ⑥b parent audit emit — the row keyed `action_type='routine.morning_routine'`
+     * that `morningRoutineRanToday` in `schedule-helpers.ts` SELECTs on.
+     * Called by `MorningRoutineRunner` AFTER its `diagnoseTodayMdState`
+     * verdict so the today.md health gate is enforced; gated also on
+     * Stage A success (Stage B success is recorded in `detail` but does
+     * NOT block — the day still "opened" if today.md is good).
+     *
+     * Reads agent_actions rows by correlationId to get authoritative
+     * `cost_usd` / `num_turns` / `result` for each stage — handles the
+     * case where one stage's `AgentResult` is in memory and the other
+     * is null (Stage B was skipped on retry) without an
+     * impedance-mismatch shim.
+     */
+    emitParentAuditRow(args: {
+        correlationId: string;
+        startedAt: Date;
+        todayMdHealth: TodayMdHealth;
+        backend?: BackendId;
+    }): ParentAuditEmitResult;
+    /**
+     * morning-routine-optimization.md Phase 6 — ⑥ AgentJournalAppender.
+     * Assembles the one-paragraph English audit-trail entry for
+     * `journal/agent.md` from `agent_actions` rows (stage results +
+     * the metadata column Stage A wrote via `PATCH /api/agent-actions/self`)
+     * plus `daily/<yesterday>.md` frontmatter. No LLM final-text parsing.
+     *
+     * Called by `MorningRoutineRunner` AFTER both stage rows have settled
+     * (so `loadMorningRoutineActionRows` sees terminal `result` + the
+     * agent-supplied metadata) and BEFORE `emitParentAuditRow` so the
+     * journal block is on disk by the time the pre-routine gate fires.
+     *
+     * Returns the appender's structured outcome so the runner can log the
+     * skip reason (e.g. `stage_a_row_missing` when the Stage A audit row
+     * never landed) without grepping the file. Returns `null` when the
+     * orchestrator was constructed without the deps the appender needs
+     * (Phase 5-only test fixtures) — caller treats `null` as a no-op.
+     */
+    appendAgentJournalEntry(args: {
+        correlationId: string;
+    }): Promise<AgentJournalAppenderResult | null>;
+    private preInsertStageAInProgressRow;
+    private buildHandoffParsedBlock;
+    private buildStageBInputs;
+    private readYesterdayCalendarEvents;
+    private composeStageAEvent;
+    /**
+     * Compose the `<roadmap_skeleton>` block injected into Stage A's
+     * prompt on the **first-run** (no-yesterday) branch. Returns `null`
+     * on the recurring branch (yesterday.md present); the recurring
+     * branch reads the live truncated `<roadmap>` ContextBuilder
+     * already injects.
+     *
+     * Why gate on `yesterday.md`: the first-run signal lines up with
+     * the variant collapse documented in §5 ("variant collapse") — the
+     * setup wizard produces a placeholder roadmap.md and rotateDayFiles
+     * has not yet emitted yesterday.md. Both gates fire from the same
+     * fs predicate so Stage A's first-run branch never sees a mismatch.
+     *
+     * Errors are swallowed: a malformed projects file or a missing
+     * travel_bookings table degrades to "Stage A sees an empty
+     * section" rather than failing the whole stage. The variant
+     * collapse depends on Stage A still landing roadmap.md in this
+     * case (it can fall back to reading `<management_rules>` and
+     * `<active_projects>` inline); shipping a broken skeleton block
+     * would be worse than no skeleton block at all.
+     */
+    private buildRoadmapSkeletonBlock;
+    /**
+     * Read forward-looking calendar events from the observations table
+     * for the next 7 days (matching the design's "Annual Goals from
+     * management rules, Quarterly Focus from active projects +
+     * calendar, Preparation Timeline from travel_bookings + calendar"
+     * window).
+     *
+     * Filtering note (pre-Phase-7-rev2 bug fix): the SQL filter does
+     * NOT use `observed_at` as a window bound. `observed_at` is the
+     * recording timestamp (CURRENT_TIMESTAMP at INSERT) — for a
+     * forward-looking window every relevant row was inserted BEFORE
+     * `now` (the just-completed pre-pass, an observer poll yesterday,
+     * etc.), so an `observed_at >= now` predicate would exclude every
+     * row. Instead we pull pending calendar observations and let JS
+     * filter on the parsed event start time extracted from
+     * `payload.raw.start`. The `consumed_at IS NULL` predicate scopes
+     * the read to rows the next Stage A turn has not yet consumed —
+     * exactly the set the pre-pass just landed for this morning's run.
+     * The `LIMIT 500` clamp guards against an unexpectedly large
+     * pending backlog blowing up Stage A's prompt budget; 500 is well
+     * above any realistic seven-day window the routine
+     * `cal_morning_7d` pre-pass would emit.
+     *
+     * Returns `[]` when no provider has pushed observations yet — the
+     * skeleton renders an explicit placeholder line.
+     */
+    private readForwardCalendarEvents;
+    private runStageA;
+    private composeStageBEvent;
+    /**
+     * Resolve the `<browser_digest>` block Stage B used to fetch via
+     * `GET /api/context/browser/yesterday-<date>.md`. Now daemon-driven
+     * since Stage B has no tools:
+     *
+     *  1. Gate on integration mode — `browser_history` `disabled` →
+     *     return `null` (no block injection).
+     *  2. File-first — `<contextDir>/browser/yesterday-<date>.md` written
+     *     by the 03:00 cron is the primary surface.
+     *  3. In-process JSON fallback — if the file is absent (daemon was
+     *     down at 03:00 or the file was purged), call
+     *     `runPreMorningDigestJob` in-process to rebuild from SQLite +
+     *     render the markdown shape (no HTTP loopback).
+     *  4. Both unavailable → return `null` (silent skip; the task-flow
+     *     omits the block).
+     *
+     * The block is wrapped in `<browser_digest>...</browser_digest>` to
+     * match the inbound-XML idiom every other ContextBuilder injection
+     * uses (`<fetch_report>`, `<journal_skeleton>`, etc.).
+     */
+    private buildBrowserDigestBlock;
+    private runStageB;
+    private readStageSummaries;
+}
+export { STAGE_A_PROCESS_KEY, STAGE_B_PROCESS_KEY, STAGE_A_ROUTINE_SLUG, STAGE_B_ROUTINE_SLUG, };