@aitne/daemon 0.1.9 → 0.1.11

package/dist/core/dispatcher-activity-scan.d.ts

@@ -0,0 +1,221 @@
+/**
+ * `ActivityScanCoordinator` — owns the dispatcher's
+ * `triggerActivityScan` entry point and the cost-reduction-structural §B
+ * three-stage gate that fronts it. The coordinator decides whether a
+ * given hourly tick:
+ *   - skips (autonomous gate / morning routine active / already running
+ *     / below threshold);
+ *   - silently consumes observations + records an Agent Log line
+ *     (Stage 0 deterministic gate or Stage 2 lite-tier `log_only`);
+ *   - escalates to the existing Stage 3 enqueue (Stage 2 `escalate`
+ *     verdict or `failed` cautious-escalate path).
+ *
+ * Extracted from `core/dispatcher.ts` as part of phase D-2 of
+ * `docs/design/appendices/file-split-plan.md`. Pattern B (stateful
+ * coordinator): the coordinator owns the gate logic but borrows live
+ * accessors for state the dispatcher continues to own — the
+ * `activityScanInProgress` flag (atomic check-and-set inside the
+ * trigger), the `morningRoutineInProgress` flag (read-only), and the
+ * lazily-injected delegated-sync refresh callback.
+ *
+ * Dispatcher entry points served:
+ *   - `EventDispatcher.triggerActivityScan(source, options)` is now a
+ *     thin one-liner that delegates to `trigger(source, options)`.
+ *
+ * Invariants preserved bit-for-bit from
+ * `docs/design/02-event-pipeline.md` §2:
+ *   - skip-if-morning-routine-in-progress;
+ *   - skip-if-hourly-already-running (atomic flag flip BEFORE any
+ *     await boundary — the C1 race fix from before the split);
+ *   - skip-if-pending-observations-below-threshold (legacy
+ *     min-observations floor honoured only when the gate would have
+ *     proceeded to Stage 3 anyway);
+ *   - skip-if-setup-incomplete / vault-degraded / user-paused via
+ *     `isAutonomousAllowed`.
+ *
+ * Shared-state references held:
+ *   - `setActivityScanInProgress` / `isActivityScanInProgress` —
+ *     getter/setter pair around the dispatcher's flag. The flag is
+ *     left `true` when an enqueue actually happens (the EventBus
+ *     consumer's `dispatchSafe` finally clears it on routine
+ *     completion); it is reset inline when the coordinator owns the
+ *     turn (silent gate paths) or when the trigger is skipping.
+ *   - `isMorningRoutineActive` — read-only mirror of the dispatcher
+ *     method so the gate stays single-sourced.
+ *   - `isAutonomousAllowed` — same; returns the
+ *     `TriggerActivityScanSkipReason` the gate should surface.
+ *   - `getDelegatedSyncRefresh` — accessor; null when no delegated
+ *     integration is wired, in which case the gate proceeds without
+ *     a refresh, matching pre-injection behaviour.
+ */
+import type Database from "better-sqlite3";
+import type { IntegrationKey } from "@aitne/shared";
+import type { AgentConfig } from "../config.js";
+import type { EventBus } from "./event-bus.js";
+import type { TodayWriteLockManager } from "./today-write-lock.js";
+import type { IAgentRouter } from "./backends/backend-router.js";
+import type { IAuditLogger, IContextBuilder, TriggerActivityScanOptions, TriggerActivityScanResult, TriggerActivityScanSkipReason } from "./dispatcher-types.js";
+import type { PromptAssembler } from "./dispatcher-prompt.js";
+import type { RoutineFetchWindowRunner } from "./routine-fetch-window-runner.js";
+export interface ActivityScanCoordinatorDeps {
+    db: Database.Database;
+    config: AgentConfig;
+    eventBus: EventBus;
+    contextBuilder: IContextBuilder;
+    agentRouter: IAgentRouter;
+    audit: IAuditLogger;
+    todayWriteLock: TodayWriteLockManager | undefined;
+    prompt: PromptAssembler;
+    /**
+     * docs/design/appendices/routine-data-acquisition.md Phase 4 / D3 — pre-pass runner
+     * spawned between Stage 2 (lite-tier triage) and Stage 3 (medium-tier
+     * main session) on `escalate` / `failed` verdicts. The rendered
+     * `<fetch_report>` block rides on the Stage 3 RoutineEvent's
+     * `event.data.fetchReportBlock` so ContextBuilder folds it into the
+     * Stage 3 prompt.
+     */
+    fetchWindowRunner: RoutineFetchWindowRunner;
+    /** Accessor for the lazily-injected delegated-sync refresh callback. */
+    getDelegatedSyncRefresh: () => (() => Promise<void>) | null;
+    /** Setter for the dispatcher's `activityScanInProgress` flag. */
+    setActivityScanInProgress: (value: boolean) => void;
+    /** Getter for the dispatcher's `activityScanInProgress` flag. */
+    isActivityScanInProgress: () => boolean;
+    /** Mirrors `EventDispatcher.isMorningRoutineActive`. */
+    isMorningRoutineActive: () => boolean;
+    /**
+     * Mirrors `EventDispatcher.isAutonomousAllowed`. Returns the
+     * skip-reason when the gate must abort early (setup incomplete,
+     * vault degraded, user paused) or `null` when autonomous work is
+     * permitted to proceed.
+     */
+    isAutonomousAllowed: () => TriggerActivityScanSkipReason | null;
+    /**
+     * Accessor for the scheduler's `queueMorningRoutineWake`. Returns the
+     * bound function once wiring has completed, or `null` early in startup
+     * before the scheduler is constructed. The pre-routine gate calls this
+     * when it detects the current agent-day's morning_routine has not run
+     * yet (typical cause: Mac slept through the 04:00 cron tick). The
+     * wake row carries the dedup guarantee — multiple back-to-back hourly
+     * ticks all see the same in-flight row instead of stacking up.
+     */
+    getQueueMorningRoutineWake: () => QueueMorningRoutineWake | null;
+}
+/** Signature of `AgentScheduler.queueMorningRoutineWake`, narrowed to the
+ *  surface the dispatcher gate consumes. Kept structural so we don't pull
+ *  the scheduler class into this module just for a type reference. */
+export type QueueMorningRoutineWake = (source: string, options?: {
+    postCatchupRoutines?: string[];
+    postCatchupActivityScan?: boolean;
+}) => {
+    inserted: boolean;
+    existingId?: number;
+};
+/**
+ * HOURLY_CHECK_GATE_REDESIGN_PLAN.md §3.3 + §7.2 — outcome of the
+ * Layer-1 pre-pass harvest that runs at the top of `trigger()` for
+ * delegated/native integrations. Surfaced both in the audit row (per-
+ * tick observability) and on the Stage 3 event (the rendered
+ * `<fetch_report>` block).
+ */
+export interface HarvestResult {
+    /** True when at least one integration was eligible and the runner ran. */
+    ran: boolean;
+    /** Integrations whose sub-session completed successfully or partially. */
+    integrations: IntegrationKey[];
+    /** Eligible integrations suppressed by the freshness window. */
+    skippedIntegrations: IntegrationKey[];
+    /** Eligible integrations whose sub-session ended in `failed`. */
+    failedIntegrations: IntegrationKey[];
+    /** Wall-clock time spent on the harvest (ms). */
+    durationMs: number;
+    /**
+     * True when any eligible integration failed. Triggers §3.5 cautious-
+     * escalate: gate decision is forced to `stage3` regardless of the
+     * signal verdict so a fetch outage doesn't manifest as silent
+     * stage0.
+     */
+    failed: boolean;
+    /**
+     * Rendered `<fetch_report>` block from the runner, ready to plumb
+     * onto `stage3Event.data.fetchReportBlock`. `null` when the runner
+     * was not spawned (no eligible integrations) — in that case the
+     * Stage 3 prompt simply omits the block.
+     */
+    fetchReportBlock: string | null;
+}
+export declare class ActivityScanCoordinator {
+    private readonly db;
+    private readonly config;
+    private readonly eventBus;
+    private readonly contextBuilder;
+    private readonly agentRouter;
+    private readonly audit;
+    private readonly todayWriteLock;
+    private readonly prompt;
+    private readonly fetchWindowRunner;
+    private readonly getDelegatedSyncRefresh;
+    private readonly setActivityScanInProgress;
+    private readonly isActivityScanInProgress;
+    private readonly isMorningRoutineActive;
+    private readonly isAutonomousAllowed;
+    private readonly getQueueMorningRoutineWake;
+    constructor(deps: ActivityScanCoordinatorDeps);
+    trigger(source: string, options?: TriggerActivityScanOptions): Promise<TriggerActivityScanResult>;
+    /**
+     * HOURLY_CHECK_GATE_REDESIGN_PLAN.md §3.3 Layer 1 — pre-pass harvest
+     * for active non-direct integrations. Reads the per-integration
+     * `pre_pass_last_run:<key>` freshness key; integrations whose last
+     * successful run is within `activityScanPrePassFreshnessMinutes` are
+     * skipped this tick. Forced runs (`/api/agent/run-now`) bypass the
+     * freshness gate.
+     *
+     * Returns a `HarvestResult` so the caller can:
+     *   - emit telemetry (which integrations fetched, which skipped on
+     *     freshness, which failed),
+     *   - cautious-escalate when any non-direct integration failed
+     *     (§3.5 — prevents silent stage0 from masking a fetch outage),
+     *   - plumb the rendered `<fetch_report>` block onto the Stage 3
+     *     event so ContextBuilder folds it into the prompt.
+     */
+    private harvestForGate;
+    /**
+     * cost-reduction-structural §B — pull a fresh signal snapshot and run
+     * the deterministic gate. Helper so the dispatcher's call site stays
+     * compact and tests can spy on the boundary.
+     */
+    private computeActivityScanGateDecision;
+    private readTodayMdSafe;
+    /**
+     * cost-reduction-structural §B — daemon-direct silent path. Used by
+     * Stage 0 and Stage 2 log-only verdicts. Consumes pending user
+     * observations + appends a single Agent Log line + records the gate
+     * verdict to `agent_actions`. The flag is reset before return.
+     */
+    private runSilentActivityScanPath;
+    private enqueueStage3ActivityScan;
+    private logGateAuditRow;
+    /**
+     * cost-reduction-structural §B Stage 2 — synchronous lite-tier triage.
+     * Builds a `routine.activity_scan.triage` RoutineEvent and runs it
+     * inline through the agent router (NOT the EventBus, so the result
+     * is available before we decide whether to silence or escalate).
+     *
+     * The agent contract is JSON-only output (`{ "action": "log_only" |
+     * "escalate", "reason": "..." }`); on parse failure we return
+     * `'failed'` and the caller treats that as cautious escalate.
+     *
+     * Tool/turn clamp (defense-in-depth):
+     *   - `allowedToolsOverride: []` removes every tool from the SDK's
+     *     allowlist for the spawn. Stage 2 has nothing to do but emit a
+     *     JSON line; the design's "no write tools" rule is enforced here
+     *     instead of relying on the prompt alone.
+     *   - `maxTurns: 1` caps the spawn at a single assistant turn. Even
+     *     if a future prompt change accidentally invites tool use, the
+     *     spawn cannot loop. Codex/Gemini have no per-spawn `allowedTools`
+     *     surface today (acknowledged gap in `agent-core.ts`); the
+     *     `maxTurns` cap and process_backend_config envelope are the
+     *     remaining safety floor on those backends.
+     */
+    private runStage2Triage;
+}