@aitne/daemon 0.1.8 → 0.1.9

package/dist/core/agents/agent-execution-tracker.js

@@ -0,0 +1,226 @@
+import { getAgent } from "../../db/agents-store.js";
+import { createLogger } from "../../logging.js";
+import { evaluateSuccessCriteria } from "./success-criteria.js";
+import { resolveAgentId, } from "./agent-id-resolver.js";
+/**
+ * Per-firing execution lifecycle (AGENT_DEFINITIONS_DESIGN.md §8.1–§8.3).
+ *
+ * The single owner of the {@link AgentExecutionRecorder} hookup so the
+ * dispatcher + result-processor (both coverage-excluded orchestrators) carry
+ * only three thin calls — `begin` / `recordOutcome` / `completeFromDispatch` —
+ * keyed by the event `correlationId`. Every firing that resolves to a known
+ * Agent opens exactly one `agent_executions` row at start and settles it once
+ * at the dispatch boundary, where success AND both failure modes converge:
+ *
+ *   - a **thrown** dispatch → `result='error'`, `error_kind='exception'`;
+ *   - a **soft** failure (`AgentResult.isError`, recorded via
+ *     {@link recordOutcome}) → `result='error'`, `error_kind='agent_error'`;
+ *   - otherwise → `result='success'`.
+ *
+ * Anchoring completion at the dispatch boundary (not solely at the
+ * result-processor) means a routine that never reaches `processResult` still
+ * settles — the boot janitor only ever sweeps a genuinely abandoned (crashed)
+ * row. Completion is idempotent: the map entry is consumed on the first call.
+ *
+ * Success criteria are evaluated best-effort at completion (§8.3); a throwing
+ * criterion records `false` + a warning and never flips the LLM-level result.
+ */
+const baseLogger = createLogger("agent-execution-tracker");
+/** Sum two nullable numeric fields, preserving `null` only when both are absent. */
+function addNullable(a, b) {
+    if (a == null)
+        return b ?? null;
+    if (b == null)
+        return a;
+    return a + b;
+}
+/**
+ * Fold a stage's outcome into the execution's running rollup. The first call
+ * (`prev === undefined`) adopts the outcome verbatim; a later call (a second
+ * stage of the same firing) sums the spend and keeps `isError` sticky so any
+ * stage's error marks the run, deterministically and independent of the
+ * `Promise.allSettled` completion order. `outputSummary` keeps the latest
+ * non-empty value.
+ */
+function mergeOutcome(prev, next) {
+    if (prev === undefined)
+        return next;
+    return {
+        isError: prev.isError || next.isError,
+        costUsd: addNullable(prev.costUsd, next.costUsd),
+        tokensIn: addNullable(prev.tokensIn, next.tokensIn),
+        tokensOut: addNullable(prev.tokensOut, next.tokensOut),
+        turns: addNullable(prev.turns, next.turns),
+        outputSummary: next.outputSummary ?? prev.outputSummary,
+    };
+}
+export class AgentExecutionTracker {
+    db;
+    recorder;
+    contextDir;
+    emitSse;
+    loadCriteria;
+    logger;
+    active = new Map();
+    constructor(deps) {
+        this.db = deps.db;
+        this.recorder = deps.recorder;
+        this.contextDir = deps.contextDir;
+        this.emitSse = deps.emitSse;
+        this.loadCriteria = deps.loadCriteria;
+        this.logger = deps.logger ?? baseLogger;
+    }
+    /**
+     * Open an execution for a firing. Resolves the owning Agent (§8.1); when none
+     * resolves, returns `null` and records nothing (legacy task, no-LLM pass).
+     * Otherwise starts the `agent_executions` row, caches the loaded criteria,
+     * and emits `agent.execution.started`. Returns the resolved Agent slug so the
+     * dispatcher can short-circuit stamping when there is no Agent.
+     */
+    begin(correlationId, resolution, opts) {
+        const agentId = resolveAgentId(this.db, resolution);
+        if (agentId === null)
+            return null;
+        // resolveAgentId verified the row exists synchronously, so getAgent is
+        // non-null here (better-sqlite3 is single-threaded; no row can vanish
+        // between the two reads).
+        const definitionPath = getAgent(this.db, agentId).definitionPath;
+        const criteria = this.loadCriteria(definitionPath);
+        const handle = this.recorder.start({
+            agentId,
+            scheduleRowId: opts.scheduleRowId ?? null,
+            trigger: opts.trigger,
+        });
+        this.active.set(correlationId, {
+            executionId: handle.executionId,
+            startedAt: handle.startedAt,
+            dateStr: handle.dateStr,
+            agentId,
+            criteria,
+        });
+        this.emitSse("agent.execution.started", {
+            slug: agentId,
+            executionId: handle.executionId,
+            trigger: opts.trigger,
+            startedAt: handle.startedAt,
+        });
+        return agentId;
+    }
+    /**
+     * Record the terminal LLM-level outcome (cost / soft-error) before the
+     * dispatch boundary settles the row. No-op when no execution is active.
+     *
+     * A single-session firing calls this exactly once (merge == replace). A
+     * **multi-stage** firing — today only the morning routine, whose Stage A
+     * (today.md) and Stage B (daily journal) are two separate LLM sessions that
+     * both funnel through the shared `ResultProcessor` carrying the
+     * parent's `correlationId` — calls it once per stage. The outcomes are
+     * therefore *folded* (see {@link mergeOutcome}): cost / tokens / turns are
+     * SUMMED so the rollup reflects the firing's total spend rather than the
+     * last (race-ordered) stage's, and `isError` is sticky-OR.
+     */
+    recordOutcome(correlationId, outcome) {
+        const entry = this.active.get(correlationId);
+        if (entry === undefined)
+            return;
+        entry.outcome = mergeOutcome(entry.outcome, outcome);
+    }
+    /** The Agent slug currently executing for this correlation id, for
+     *  `agent_actions.agent_id` stamping. `null` when no execution is active. */
+    currentAgentId(correlationId) {
+        return this.active.get(correlationId)?.agentId ?? null;
+    }
+    /**
+     * Settle the active execution as a deliberate skip (AGENT_DEFINITIONS_DESIGN.md
+     * §5.2 — `result='skipped'` is a reserved non-error terminal that does NOT
+     * count toward `errorRate`). Called from a dispatch path that opened a row via
+     * {@link begin} but then decided not to run the routine this tick — e.g. a
+     * review routine blocked by the morning-routine-pending gate, or skill
+     * curation when the optimizer workdir is unwired. Success criteria are NOT
+     * evaluated (the run never happened); `reason` is recorded in `output_summary`
+     * so the dashboard can show why. Idempotent — consumes the map entry, so the
+     * trailing `completeFromDispatch` in `dispatchSafe` is a no-op. No-op when no
+     * execution is active (the firing resolved to no Agent, so `begin` opened no
+     * row).
+     */
+    markSkipped(correlationId, reason) {
+        const entry = this.active.get(correlationId);
+        if (entry === undefined)
+            return;
+        this.active.delete(correlationId);
+        this.recorder.complete({
+            executionId: entry.executionId,
+            result: "skipped",
+            ...(reason !== undefined ? { outputSummary: reason } : {}),
+        });
+        this.emitSse("agent.execution.completed", {
+            slug: entry.agentId,
+            executionId: entry.executionId,
+            result: "skipped",
+        });
+    }
+    /**
+     * Settle the active execution at the dispatch boundary. Idempotent — the map
+     * entry is consumed, so a later call (e.g. the error path after the success
+     * path already completed) is a no-op. Evaluates success criteria, writes the
+     * terminal row (+ `agents.last_execution_id`), and emits
+     * `agent.execution.completed`.
+     */
+    completeFromDispatch(correlationId, opts = {}) {
+        const entry = this.active.get(correlationId);
+        if (entry === undefined)
+            return;
+        this.active.delete(correlationId);
+        const thrown = "thrown" in opts;
+        let result;
+        let errorKind = null;
+        let errorMessage = null;
+        if (thrown) {
+            result = "error";
+            errorKind = "exception";
+            errorMessage =
+                opts.thrown instanceof Error
+                    ? opts.thrown.message
+                    : String(opts.thrown);
+        }
+        else if (entry.outcome?.isError === true) {
+            result = "error";
+            errorKind = "agent_error";
+        }
+        else {
+            result = "success";
+        }
+        const { hits, warnings } = evaluateSuccessCriteria(entry.criteria, {
+            db: this.db,
+            contextDir: this.contextDir,
+            agentId: entry.agentId,
+            startedAt: entry.startedAt,
+            dateStr: entry.dateStr,
+        });
+        for (const warning of warnings) {
+            this.logger.warn({ slug: entry.agentId, criterionId: warning.id, kind: warning.kind, message: warning.message }, "success criterion could not be evaluated");
+        }
+        const outcome = entry.outcome;
+        this.recorder.complete({
+            executionId: entry.executionId,
+            result,
+            errorKind,
+            errorMessage,
+            cost: {
+                usd: outcome?.costUsd ?? null,
+                tokensIn: outcome?.tokensIn ?? null,
+                tokensOut: outcome?.tokensOut ?? null,
+                turns: outcome?.turns ?? null,
+            },
+            successCriteriaHits: hits,
+            outputSummary: outcome?.outputSummary ?? null,
+        });
+        this.emitSse("agent.execution.completed", {
+            slug: entry.agentId,
+            executionId: entry.executionId,
+            result,
+            errorKind,
+            successCriteria: hits,
+        });
+    }
+}

package/dist/core/agents/agent-frontmatter.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Agent definition frontmatter parser (AGENT_DEFINITIONS_DESIGN.md §4.3 / §6.1).
+ *
+ * `agent.md` files — both built-in (`agent-assets/agents/<slug>/agent.md`) and
+ * user (`<contextDir>/policies/agents/<slug>/agent.md`) — carry a YAML
+ * frontmatter block fenced by `---` lines, followed by a Markdown body.
+ *
+ * The frontmatter is **deeply nested** (`schedule` / `backend` / `limits` /
+ * `tools` / `success_criteria` / `stop_warning`), so the repo's flat
+ * line-scalar `extractContextFrontmatter` parser cannot read it — it would
+ * silently drop every nested block. This module uses `js-yaml` instead (the
+ * dependency Phase 4 added for exactly this surface; see the Phase 4
+ * design-drift correction in AGENT_DEFINITIONS_IMPLEMENTATION_PLAN.md).
+ *
+ * The fence-splitting logic mirrors `core/context-frontmatter-extract.ts`
+ * (open on a leading `---`, close on the next `---`); only the block parser
+ * changes. This is the same shape Phase 4's `builtin-yaml.test.ts` proved
+ * against the shipped built-ins, lifted into the loader module so production
+ * and the test share one parser.
+ */
+/** Outcome of splitting + parsing an `agent.md` file. */
+export interface AgentFrontmatterParse {
+    /** Parsed frontmatter as a plain object (validate with `agentDefinitionSchema`). */
+    frontmatter: unknown;
+    /** Markdown body after the closing fence, trimmed. */
+    body: string;
+}
+/**
+ * Thrown when the file is not a well-formed frontmatter document: it must open
+ * with a `---` fence on the first line and close with a later `---`, and the
+ * captured block must parse as a YAML mapping. The loader catches this and
+ * records the file as an invalid definition (§6.6) rather than crashing boot.
+ */
+export declare class AgentFrontmatterError extends Error {
+    constructor(message: string);
+}
+/**
+ * Split a Markdown file into its YAML frontmatter object + body.
+ *
+ * Throws {@link AgentFrontmatterError} when the document does not open/close a
+ * frontmatter fence, or when the captured block does not parse to a plain
+ * object (a bare scalar / sequence frontmatter is not a valid agent
+ * definition). `js-yaml` v4 `load` is the safe loader — the code-executing
+ * loader and the `!!js/function` type were removed in v4, so `DEFAULT_SCHEMA`
+ * constructs no arbitrary types.
+ */
+export declare function parseAgentFrontmatter(content: string): AgentFrontmatterParse;
+/**
+ * Render an Agent definition object back into an `agent.md` document: a YAML
+ * frontmatter block + a Markdown body. Used by the auto-import path (§6.5) to
+ * materialise a user Agent file from a legacy `recurring_schedules` row.
+ *
+ * The frontmatter is emitted with `js-yaml` `dump` (stable key order, no
+ * line-wrapping so cron strings / paths stay intact). The result round-trips
+ * cleanly through {@link parseAgentFrontmatter}.
+ */
+export declare function renderAgentMarkdown(frontmatter: Record<string, unknown>, body: string): string;

package/dist/core/agents/agent-frontmatter.js

@@ -0,0 +1,74 @@
+import yaml from "js-yaml";
+/**
+ * Thrown when the file is not a well-formed frontmatter document: it must open
+ * with a `---` fence on the first line and close with a later `---`, and the
+ * captured block must parse as a YAML mapping. The loader catches this and
+ * records the file as an invalid definition (§6.6) rather than crashing boot.
+ */
+export class AgentFrontmatterError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AgentFrontmatterError";
+    }
+}
+/**
+ * Split a Markdown file into its YAML frontmatter object + body.
+ *
+ * Throws {@link AgentFrontmatterError} when the document does not open/close a
+ * frontmatter fence, or when the captured block does not parse to a plain
+ * object (a bare scalar / sequence frontmatter is not a valid agent
+ * definition). `js-yaml` v4 `load` is the safe loader — the code-executing
+ * loader and the `!!js/function` type were removed in v4, so `DEFAULT_SCHEMA`
+ * constructs no arbitrary types.
+ */
+export function parseAgentFrontmatter(content) {
+    // `split` always yields at least one element, so `lines[0]` is defined.
+    const lines = content.split(/\r?\n/);
+    if (lines[0].trim() !== "---") {
+        throw new AgentFrontmatterError("agent.md must open with a `---` frontmatter fence on the first line");
+    }
+    const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+    if (end < 0) {
+        throw new AgentFrontmatterError("agent.md frontmatter block is never closed with `---`");
+    }
+    let frontmatter;
+    try {
+        frontmatter = yaml.load(lines.slice(1, end).join("\n"));
+    }
+    catch (err) {
+        // `${err}` renders js-yaml's YAMLException ("…: bad indentation …") via its
+        // own toString — no `instanceof Error` branch (js-yaml always throws here).
+        throw new AgentFrontmatterError(`agent.md frontmatter is not valid YAML: ${err}`);
+    }
+    if (frontmatter === null || frontmatter === undefined) {
+        throw new AgentFrontmatterError("agent.md frontmatter block is empty");
+    }
+    if (typeof frontmatter !== "object" || Array.isArray(frontmatter)) {
+        throw new AgentFrontmatterError("agent.md frontmatter must be a YAML mapping, not a scalar or sequence");
+    }
+    return {
+        frontmatter,
+        body: lines.slice(end + 1).join("\n").trim(),
+    };
+}
+/**
+ * Render an Agent definition object back into an `agent.md` document: a YAML
+ * frontmatter block + a Markdown body. Used by the auto-import path (§6.5) to
+ * materialise a user Agent file from a legacy `recurring_schedules` row.
+ *
+ * The frontmatter is emitted with `js-yaml` `dump` (stable key order, no
+ * line-wrapping so cron strings / paths stay intact). The result round-trips
+ * cleanly through {@link parseAgentFrontmatter}.
+ */
+export function renderAgentMarkdown(frontmatter, body) {
+    const yamlBlock = yaml.dump(frontmatter, {
+        lineWidth: -1,
+        noRefs: true,
+        sortKeys: false,
+    });
+    const trimmedBody = body.trim();
+    // yaml.dump already ends with a trailing newline; bracket it with fences and
+    // append the body so the file opens/closes a frontmatter block exactly like
+    // the shipped built-ins.
+    return `---\n${yamlBlock}---\n\n${trimmedBody}\n`;
+}

package/dist/core/agents/agent-id-resolver.d.ts

@@ -0,0 +1,47 @@
+import type Database from "better-sqlite3";
+/**
+ * Resolve the owning Agent slug for a firing (AGENT_DEFINITIONS_DESIGN.md
+ * §8.1). Pure over its `AgentIdResolutionInput` (the dispatcher extracts the
+ * fields from the live `Event`) so the resolution order is unit-testable.
+ *
+ * Order (first hit wins):
+ *   1. `task_context.agent_id` — stamped at materialisation for user Agents
+ *      (§7.2, `recurring-schedules.ts:generateNextScheduleRow`).
+ *   2. `recurring_schedule_id` → `agents` join — covers legacy pending rows
+ *      materialised before the §7.2 stamp landed.
+ *   3. `routine` (+ `phase`) → built-in registry slug — routine events carry
+ *      no schedule row, so the routine name maps to its built-in Agent.
+ *   4. else `null` — a firing with no Agent identity (legacy task, roadmap
+ *      refresh, …) records no execution rollup.
+ *
+ * The two no-LLM in-process passes (`roadmap-maintenance`,
+ * `context-index-reconcile`) carry `processKey: null` and fire via the
+ * scheduler's `in_process_callback`, never the dispatcher — so they are never
+ * resolved here and intentionally produce no execution row.
+ */
+export interface AgentIdResolutionInput {
+    /** `task_context.agent_id` if present on the schedule row's context. */
+    taskContextAgentId?: string | null;
+    /** `recurring_schedule_id` (schedule-row column or `task_context`). */
+    recurringScheduleId?: number | null;
+    /** Routine event name (`morning_routine`, `evening_review`, …). */
+    routine?: string | null;
+    /** Routine `data.phase` — disambiguates the two `user_profile_sweep` slugs. */
+    routinePhase?: string | null;
+}
+/**
+ * Map a routine event name (+ phase) to its built-in Agent slug, or `null`
+ * when the routine has no 1:1 Agent. Derived from `BUILTIN_AGENT_REGISTRY`
+ * (`processKey === "routine.<name>"`) so it never drifts from the registry,
+ * with the only many-to-one routine — `user_profile_sweep`, which owns a
+ * morning and an evening Agent — disambiguated by phase.
+ */
+export declare function routineToAgentSlug(routine: string, phase: string | null): string | null;
+/**
+ * Resolve the Agent slug for a firing, verifying the row exists so the caller
+ * can safely `recorder.start` (the `agent_executions.agent_id` FK requires it).
+ * A resolved-but-missing slug (e.g. a hand-set `task_context.agent_id` whose
+ * Agent was deleted, or a built-in whose load failed) returns `null` rather
+ * than risk an FK violation.
+ */
+export declare function resolveAgentId(db: Database.Database, input: AgentIdResolutionInput): string | null;

package/dist/core/agents/agent-id-resolver.js

@@ -0,0 +1,61 @@
+import { BUILTIN_AGENT_REGISTRY } from "./builtin-registry.js";
+/**
+ * Map a routine event name (+ phase) to its built-in Agent slug, or `null`
+ * when the routine has no 1:1 Agent. Derived from `BUILTIN_AGENT_REGISTRY`
+ * (`processKey === "routine.<name>"`) so it never drifts from the registry,
+ * with the only many-to-one routine — `user_profile_sweep`, which owns a
+ * morning and an evening Agent — disambiguated by phase.
+ */
+export function routineToAgentSlug(routine, phase) {
+    if (routine === "user_profile_sweep") {
+        return phase === "evening"
+            ? "user-profile-sweep-evening"
+            : "user-profile-sweep-morning";
+    }
+    const processKey = `routine.${routine}`;
+    const matches = BUILTIN_AGENT_REGISTRY.filter((entry) => entry.processKey === processKey);
+    // A unique match is the Agent; 0 (non-Agent routine like roadmap_refresh)
+    // or >1 (only the sweep, handled above) → no resolution.
+    return matches.length === 1 ? matches[0].slug : null;
+}
+/**
+ * Resolve the Agent slug for a firing, verifying the row exists so the caller
+ * can safely `recorder.start` (the `agent_executions.agent_id` FK requires it).
+ * A resolved-but-missing slug (e.g. a hand-set `task_context.agent_id` whose
+ * Agent was deleted, or a built-in whose load failed) returns `null` rather
+ * than risk an FK violation.
+ */
+export function resolveAgentId(db, input) {
+    const candidate = resolveCandidateSlug(db, input);
+    if (candidate === null)
+        return null;
+    return agentRowExists(db, candidate) ? candidate : null;
+}
+function resolveCandidateSlug(db, input) {
+    // 1. Explicit stamp.
+    if (typeof input.taskContextAgentId === "string"
+        && input.taskContextAgentId.length > 0) {
+        return input.taskContextAgentId;
+    }
+    // 2. recurring_schedule_id → agents join.
+    if (input.recurringScheduleId != null) {
+        const row = db
+            .prepare("SELECT id FROM agents WHERE recurring_schedule_id = ? LIMIT 1")
+            .get(input.recurringScheduleId);
+        if (row)
+            return row.id;
+    }
+    // 3. routine (+ phase) → registry slug.
+    if (input.routine) {
+        const slug = routineToAgentSlug(input.routine, input.routinePhase ?? null);
+        if (slug)
+            return slug;
+    }
+    return null;
+}
+function agentRowExists(db, slug) {
+    const row = db
+        .prepare("SELECT 1 AS one FROM agents WHERE id = ? LIMIT 1")
+        .get(slug);
+    return row !== undefined;
+}

package/dist/core/agents/builtin-registry.d.ts

@@ -0,0 +1,156 @@
+import type { ProcessKey, StopWarning } from "@aitne/shared";
+/**
+ * Built-in Agent registry — the static identity source for the 10 shipped
+ * routines (AGENT_DEFINITIONS_DESIGN.md §5.5 / §5.5.1).
+ *
+ * This module is the **single source of truth** for the slug ↔ cron-callback
+ * ↔ process_key ↔ stop-warning mapping that both the loader (§6) and
+ * `scheduler.ts:setupRecurringJobs` (§7) consult. Two roles:
+ *
+ *   1. **Fallback identity.** When a built-in's `agent-assets/agents/<slug>/`
+ *      `agent.md` is missing, the loader synthesises an `agents` row from the
+ *      matching entry here and logs a warning. This makes the Phase 4 YAML
+ *      rollout incremental — ship the registry first, ship the YAML files
+ *      Agent-by-Agent.
+ *   2. **Cron / stop-warning authority.** The registry's `cronExpression` is
+ *      authoritative over the YAML's `schedule.expression` (the loader emits a
+ *      non-fatal drift warning on mismatch, §6.4); the registry's `stopWarning`
+ *      must stay byte-identical to the shipped YAML's `stop_warning` (§12.1, a
+ *      test enforces it once Phase 4 YAML exists).
+ *
+ * The firing paths below were verified line-by-line against
+ * `scheduler.ts:setupRecurringJobs` during Phase 0 (design §5.5.1, frozen
+ * 2026-05-30). Do NOT re-derive from prose — reproduce these exact cron forms,
+ * process keys, and `schedulerFn` mechanisms.
+ *
+ * This module is intentionally pure (no daemon-only imports beyond the shared
+ * `ProcessKey` / `StopWarning` types) so it stays in the 100%-coverage set and
+ * can be imported by both the loader and the scheduler without a cycle.
+ */
+/**
+ * Resolves a built-in's cron expression from the live `dayBoundaryHour`
+ * config. `null` for the interval-gated `hourly-check`, whose cadence is a
+ * runtime window (`buildHourlyCronExpr(intervalMinutes, activeStart,
+ * activeEnd)`), not a fixed expression — the loader's drift check is a no-op
+ * for a `null` resolver (§5.5.1).
+ */
+export type CronExpressionResolver = (config: {
+    dayBoundaryHour: number;
+}) => string;
+/**
+ * How `setupRecurringJobs` fires a built-in. NB: a non-null `processKey` does
+ * NOT imply `emit_routine`/`queue_wake` — `hourly-check` carries
+ * `routine.hourly_check` yet fires via `in_process_callback`.
+ *
+ *   - `emit_routine`  — `emitRoutine(routine, data?)` puts a `routine.<name>`
+ *     event on the bus. `data` is the fixed payload the scheduler passes; the
+ *     two `user-profile-sweep-*` slugs share `routine.user_profile_sweep` and
+ *     differ only by `data.phase`. `skill-curation` resolves its `cadence` at
+ *     fire time from the DB, so its `data` is intentionally omitted here (a
+ *     baked literal would be wrong).
+ *   - `queue_wake`    — `queueMorningRoutineWake(...)` enqueues a durable wake
+ *     row instead of a transient event (morning-routine only).
+ *   - `in_process_callback` — a typed daemon callback (`onHourlyCheck`,
+ *     `onRoadmapMaintenance`, `onContextIndexReconcile`); the last two are
+ *     no-LLM passes with `processKey: null`.
+ */
+export type BuiltinSchedulerFn = {
+    kind: "emit_routine";
+    routine: string;
+    data?: Record<string, unknown>;
+} | {
+    kind: "queue_wake";
+    routine: string;
+} | {
+    kind: "in_process_callback";
+    callbackName: string;
+};
+export interface BuiltinAgentRegistryEntry {
+    /** Kebab-case slug; also the `agents.id` and the `agent.md` directory name. */
+    slug: string;
+    /** Human-facing display name (dashboard). */
+    name: string;
+    /**
+     * One-line English description of what the routine does. `agentDefinitionSchema`
+     * requires a non-empty `description` with no default, so the registry must
+     * carry it for the loader's registry-fallback synthesis (§6.1 step 3) to build
+     * a valid `AgentDefinition` when a built-in's `agent.md` is missing. The Phase 4
+     * YAML is the complete source; this is the faithful fallback, not a stopgap.
+     */
+    description: string;
+    /**
+     * Cron with `{dayBoundaryHour}` / `{dayBoundaryHour-1}` resolved from live
+     * config, or `null` for the runtime-window `hourly-check` (§5.5.1).
+     */
+    cronExpression: CronExpressionResolver | null;
+    /**
+     * Backend routing key, or `null` for the two no-LLM in-process passes
+     * (`roadmap-maintenance`, `context-index-reconcile`).
+     */
+    processKey: ProcessKey | null;
+    /**
+     * The `enabled` state the registry-fallback synthesis assigns when no YAML is
+     * present (§6.1 step 3). `true` for every built-in EXCEPT `monthly-review`,
+     * which is OFF by default pre-release (frozen decision, §2.1) — without this
+     * the fallback would default `enabled: true` (schema default) and silently
+     * mis-enable it. Operator toggles still win via the §6.4 override path; this
+     * is only the shipped-default base. NB: `backend.tier` is deliberately NOT in
+     * the registry — built-ins defer their tier to `process_backend_config` (the
+     * seed authority), i.e. the synthesised `backend.tier` is `null`.
+     */
+    defaultEnabled: boolean;
+    /** Mandatory stop warning, surfaced when an operator disables the Agent. */
+    stopWarning: StopWarning;
+    /** The mechanism `setupRecurringJobs` uses to fire this slug. */
+    schedulerFn: BuiltinSchedulerFn;
+}
+export declare const BUILTIN_AGENT_REGISTRY: readonly BuiltinAgentRegistryEntry[];
+/** Slug → entry, for O(1) lookup from the loader and the scheduler gate. */
+export declare const BUILTIN_AGENT_REGISTRY_BY_SLUG: ReadonlyMap<string, BuiltinAgentRegistryEntry>;
+/** Every built-in slug, for membership tests (e.g. user-Agent slug collision). */
+export declare const BUILTIN_AGENT_SLUGS: ReadonlySet<string>;
+/** Returns the registry entry for `slug`, or `undefined` if not a built-in. */
+export declare function getBuiltinRegistryEntry(slug: string): BuiltinAgentRegistryEntry | undefined;
+/** True when `slug` names a shipped built-in Agent. */
+export declare function isBuiltinAgentSlug(slug: string): boolean;
+/**
+ * The live config a runtime-window built-in's cadence is resolved from. Today
+ * the only runtime-window built-in is `hourly-check`, whose firing window is
+ * `buildHourlyCronExpr(intervalMinutes, activeStart, activeEnd)` — so the three
+ * `hourlyCheck*` fields are all that's needed. A narrow shape (not the whole
+ * `AgentConfig`) keeps this module pure / coverage-friendly.
+ */
+export interface RuntimeWindowCadenceConfig {
+    hourlyCheckIntervalMinutes: number;
+    hourlyCheckActiveStartHour: number;
+    hourlyCheckActiveEndHour: number;
+}
+/**
+ * The interval cadence of a runtime-window built-in: how often it fires
+ * (`interval_minutes`) and the local active-hours window it fires within. This
+ * is the structured form the `/agents` views surface so the dashboard can show
+ * the REAL cadence ("Every 60 min, 04:00–24:00") instead of the loader-ignored
+ * placeholder cron the `agents` row stores for these slugs (§5.5.1).
+ */
+export interface IntervalCadence {
+    /** Minutes between firings within the active window (e.g. 60, 30). */
+    interval_minutes: number;
+    /** Active-window start hour, local, inclusive (0–23). */
+    active_start_hour: number;
+    /** Active-window end hour, local, exclusive (1–24). */
+    active_end_hour: number;
+}
+/**
+ * Resolve the live interval cadence for a runtime-window built-in, or `null`
+ * for every fixed-cron / one-shot / event Agent.
+ *
+ * A built-in is "runtime-window" iff its registry `cronExpression` resolver is
+ * `null` — the documented marker (§5.5.1) that its cadence is owned by
+ * `buildHourlyCronExpr` from live config, not a baked cron. Today `hourly-check`
+ * is the sole such entry, so the mapping reads the `hourlyCheck*` config. A
+ * second runtime-window built-in would need its own branch here — the
+ * `cronExpression === null` gate plus this comment keep that requirement
+ * visible. Pure: the caller supplies the live config (read at request time so a
+ * runtime interval change via `PATCH /api/config` is reflected immediately).
+ */
+export declare function resolveRuntimeWindowCadence(slug: string, config: RuntimeWindowCadenceConfig): IntervalCadence | null;