@aitne/daemon 0.1.7 → 0.1.9

package/dist/core/agents/override-merge.d.ts

@@ -0,0 +1,57 @@
+import type { AgentDefinition } from "@aitne/shared";
+/**
+ * Built-in override merge (AGENT_DEFINITIONS_DESIGN.md §6.4.1).
+ *
+ * Built-in Agents ship inside `@aitne-sh/aitne`, so their YAML at
+ * `agent-assets/agents/<slug>/agent.md` is overwritten on every `npm i -g`.
+ * Operator edits to a built-in therefore must NOT be written back to disk —
+ * they live in `agents.metadata_json.override_snapshot` (a flat dot-path →
+ * value map) and are re-applied on top of the shipped definition every boot.
+ *
+ * This module is the pure reducer that composes the effective definition:
+ *
+ *     effective = (shippedYaml ?? registryFallback)  then  override snapshot
+ *
+ * Override wins. Only the allow-listed fields are mergeable; any other key in
+ * the snapshot is dropped (the API validates on write, this re-validates on
+ * read — defence-in-depth). The merge is total and never throws: an
+ * out-of-contract value for an allow-listed path is dropped, leaving the base
+ * value, so a corrupt snapshot can never produce an invalid definition or
+ * crash boot.
+ *
+ * Pure + dependency-free (beyond the shared schema) so it stays in the
+ * 100%-coverage set and is reused by the loader (§6) and the `/api/agents`
+ * PATCH handler (§9.5).
+ */
+/**
+ * The ONLY fields a built-in override snapshot may carry (§6.4.1). The API's
+ * PATCH handler restricts writes to these; `mergeAgentDefinition` applies only
+ * these. Flat dot-path keys so a reset (`PATCH { reset: ["limits.max_budget_usd"] }`)
+ * is a single `delete snapshot[path]`.
+ *
+ * `enabled_overridden_at` is part of the canonical allow-list because it
+ * travels with an `enabled` override (§6.4.1 step 4: an empty snapshot clears
+ * it), but it is a metadata timestamp, NOT an `AgentDefinition` field — the
+ * merge recognises it as allow-listed and applies nothing to the definition
+ * (no target). The loader resolves the real enabled-state from the
+ * `agents.enabled_overridden_at` column via the §6.4 timestamp comparison.
+ */
+export declare const MERGEABLE_OVERRIDE_PATHS: readonly ["enabled", "enabled_overridden_at", "backend.tier", "backend.model", "limits.max_turns", "limits.max_budget_usd", "limits.timeout_minutes", "on_error.notify_owner"];
+export type MergeableOverridePath = (typeof MERGEABLE_OVERRIDE_PATHS)[number];
+/** True when `path` is one of the allow-listed override keys. */
+export declare function isMergeableOverridePath(path: string): path is MergeableOverridePath;
+/**
+ * Compose the effective Agent definition from the shipped YAML (or the
+ * registry fallback when no YAML is present) plus the operator's override
+ * snapshot (§6.4.1).
+ *
+ * @param shippedYaml      parsed `agent.md` frontmatter, or `null` when the
+ *                         built-in has no YAML on disk yet.
+ * @param registryFallback synthesised-from-registry definition; the base used
+ *                         when `shippedYaml` is `null`.
+ * @param overrideSnapshot flat dot-path → value map from
+ *                         `metadata_json.override_snapshot`; non-allow-listed
+ *                         keys are ignored.
+ * @returns a fresh, valid `AgentDefinition` — inputs are never mutated.
+ */
+export declare function mergeAgentDefinition(shippedYaml: AgentDefinition | null, registryFallback: AgentDefinition, overrideSnapshot: Record<string, unknown>): AgentDefinition;

package/dist/core/agents/override-merge.js

@@ -0,0 +1,131 @@
+import { AGENT_TIERS, OVERRIDE_EDIT_PATHS } from "@aitne/shared";
+/**
+ * Built-in override merge (AGENT_DEFINITIONS_DESIGN.md §6.4.1).
+ *
+ * Built-in Agents ship inside `@aitne-sh/aitne`, so their YAML at
+ * `agent-assets/agents/<slug>/agent.md` is overwritten on every `npm i -g`.
+ * Operator edits to a built-in therefore must NOT be written back to disk —
+ * they live in `agents.metadata_json.override_snapshot` (a flat dot-path →
+ * value map) and are re-applied on top of the shipped definition every boot.
+ *
+ * This module is the pure reducer that composes the effective definition:
+ *
+ *     effective = (shippedYaml ?? registryFallback)  then  override snapshot
+ *
+ * Override wins. Only the allow-listed fields are mergeable; any other key in
+ * the snapshot is dropped (the API validates on write, this re-validates on
+ * read — defence-in-depth). The merge is total and never throws: an
+ * out-of-contract value for an allow-listed path is dropped, leaving the base
+ * value, so a corrupt snapshot can never produce an invalid definition or
+ * crash boot.
+ *
+ * Pure + dependency-free (beyond the shared schema) so it stays in the
+ * 100%-coverage set and is reused by the loader (§6) and the `/api/agents`
+ * PATCH handler (§9.5).
+ */
+/**
+ * The ONLY fields a built-in override snapshot may carry (§6.4.1). The API's
+ * PATCH handler restricts writes to these; `mergeAgentDefinition` applies only
+ * these. Flat dot-path keys so a reset (`PATCH { reset: ["limits.max_budget_usd"] }`)
+ * is a single `delete snapshot[path]`.
+ *
+ * `enabled_overridden_at` is part of the canonical allow-list because it
+ * travels with an `enabled` override (§6.4.1 step 4: an empty snapshot clears
+ * it), but it is a metadata timestamp, NOT an `AgentDefinition` field — the
+ * merge recognises it as allow-listed and applies nothing to the definition
+ * (no target). The loader resolves the real enabled-state from the
+ * `agents.enabled_overridden_at` column via the §6.4 timestamp comparison.
+ */
+// Derived from the shared `OVERRIDE_EDIT_PATHS` single source of truth so the
+// loader/merge allow-list can never drift from the API PATCH allow-list. The
+// two `enabled*` keys are merge-only (column-authority, no definition target —
+// see the doc above) and prepend the shared field-edit paths.
+export const MERGEABLE_OVERRIDE_PATHS = [
+    "enabled",
+    "enabled_overridden_at",
+    ...OVERRIDE_EDIT_PATHS,
+];
+/** True when `path` is one of the allow-listed override keys. */
+export function isMergeableOverridePath(path) {
+    return MERGEABLE_OVERRIDE_PATHS.includes(path);
+}
+// ── Per-path value guards (defence-in-depth; mirror agentDefinitionSchema) ──
+function isAgentTier(value) {
+    return typeof value === "string" && AGENT_TIERS.includes(value);
+}
+function isPositiveInt(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+function isNonNegativeFinite(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+/**
+ * Apply a single allow-listed override path to a (mutable, already-cloned)
+ * definition. Each branch type-guards the value against the same contract
+ * `agentDefinitionSchema` enforces; a value that fails its guard is dropped so
+ * the base value survives. `enabled_overridden_at` has no definition target
+ * and is a deliberate no-op.
+ */
+function applyOverridePath(def, path, value) {
+    switch (path) {
+        case "enabled":
+            if (typeof value === "boolean")
+                def.enabled = value;
+            break;
+        case "enabled_overridden_at":
+            // Metadata sidecar — no AgentDefinition target (see MERGEABLE_OVERRIDE_PATHS).
+            break;
+        case "backend.tier":
+            if (value === null || isAgentTier(value))
+                def.backend.tier = value;
+            break;
+        case "backend.model":
+            // `null` defers to process_backend_config; a non-empty string pins a
+            // model. An empty string is neither (matches the schema's `.min(1)`).
+            if (value === null || (typeof value === "string" && value.length > 0)) {
+                def.backend.model = value;
+            }
+            break;
+        case "limits.max_turns":
+            if (isPositiveInt(value))
+                def.limits.max_turns = value;
+            break;
+        case "limits.max_budget_usd":
+            if (isNonNegativeFinite(value))
+                def.limits.max_budget_usd = value;
+            break;
+        case "limits.timeout_minutes":
+            if (isPositiveInt(value))
+                def.limits.timeout_minutes = value;
+            break;
+        case "on_error.notify_owner":
+            if (typeof value === "boolean")
+                def.on_error.notify_owner = value;
+            break;
+    }
+}
+/**
+ * Compose the effective Agent definition from the shipped YAML (or the
+ * registry fallback when no YAML is present) plus the operator's override
+ * snapshot (§6.4.1).
+ *
+ * @param shippedYaml      parsed `agent.md` frontmatter, or `null` when the
+ *                         built-in has no YAML on disk yet.
+ * @param registryFallback synthesised-from-registry definition; the base used
+ *                         when `shippedYaml` is `null`.
+ * @param overrideSnapshot flat dot-path → value map from
+ *                         `metadata_json.override_snapshot`; non-allow-listed
+ *                         keys are ignored.
+ * @returns a fresh, valid `AgentDefinition` — inputs are never mutated.
+ */
+export function mergeAgentDefinition(shippedYaml, registryFallback, overrideSnapshot) {
+    const base = structuredClone(shippedYaml ?? registryFallback);
+    // Iterate the allow-list (not the snapshot) so non-allow-listed snapshot
+    // keys are inherently ignored — they are never read.
+    for (const path of MERGEABLE_OVERRIDE_PATHS) {
+        if (Object.prototype.hasOwnProperty.call(overrideSnapshot, path)) {
+            applyOverridePath(base, path, overrideSnapshot[path]);
+        }
+    }
+    return base;
+}

package/dist/core/agents/recurrence-convert.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Cron ⇄ recurrence-spec conversion for user-Agent recurring pairing and
+ * first-boot auto-import (AGENT_DEFINITIONS_DESIGN.md §6.1 step 5 / §6.5).
+ *
+ * User Agents declare their schedule as a cron `expression` in YAML, but the
+ * backing `recurring_schedules` row stores a *structured* recurrence rule
+ * (frequency / time / days). The loader therefore needs both directions:
+ *
+ *   - **pairing** (cron → spec): when a user Agent's YAML has no paired
+ *     recurring row yet, derive a structured spec to create one.
+ *   - **auto-import** (spec → cron): when a legacy recurring row has no Agent
+ *     YAML, derive a cron expression for the synthesised `agent.md`.
+ *
+ * To keep this module pure and dependency-free (so it stays in the
+ * 100%-coverage set and never imports a daemon-only / DB type), it deals in a
+ * loader-local {@link AgentRecurrenceSpec} that is a 1:1 structural mirror of
+ * the daemon's `recurrence_rule` JSON. The Phase-7 production adapter maps
+ * `AgentRecurrenceSpec` ↔ the real `recurring_schedules` `RecurrenceRule`
+ * with a field copy — no logic.
+ *
+ * Both functions are **total**: a cron shape the structured rule cannot
+ * represent (sub-hourly step minutes like `*​/30`, hour ranges/lists, `?` in
+ * the day fields, an OR of day-of-month AND day-of-week, etc.) yields `null`
+ * from {@link cronToRecurrenceSpec}, and the caller keeps the raw cron string
+ * instead of fabricating a lossy rule. `recurrenceSpecToCron` always produces a
+ * valid 5-field expression.
+ *
+ * **`hourly` IS mirrored** (the former Phase-7 gap, now closed). The daemon's
+ * `recurrenceRuleSchema` (schemas.ts) carries an `hourly` frequency
+ * (`intervalHours` 1..23 / `minuteOfHour` 0..59); this module round-trips it
+ * through the step-form cron `M * * * *` (every hour at :M) and `M *​/N * * *`
+ * (every N hours at :M). So a user Agent CAN declare an hourly cadence and the
+ * loader pairs it to a real `recurring_schedules.hourly` row. The remaining gap
+ * is the monthly `onMissingDay` policy, which cron cannot carry — it is dropped
+ * on conversion (a `daysOfMonth` cron uses node-cron's own missing-day
+ * behaviour). Sub-hourly intervals (every N minutes) are NOT representable —
+ * only the built-in hourly-check supports those, via config.
+ */
+/** Loader-local mirror of the daemon `recurrence_rule` JSON (§2.2). Covers the
+ *  four cron-representable frequencies (`hourly` via the step-form cron). The
+ *  monthly `onMissingDay` policy is not mirrored — it cannot round-trip through
+ *  cron (see the module header). */
+export interface AgentRecurrenceSpec {
+    frequency: "hourly" | "daily" | "weekly" | "monthly";
+    /** `HH:MM`, 24-hour, zero-padded. Present for daily/weekly/monthly only. */
+    time?: string;
+    /** IANA timezone resolved by the loader (never null on the stored row). */
+    timezone: string;
+    /** 0=Sunday … 6=Saturday — present only for `weekly`. */
+    daysOfWeek?: number[];
+    /** 1…31 — present only for `monthly`. */
+    daysOfMonth?: number[];
+    /** 1…23 — present only for `hourly` (fire every N hours). Default 1. */
+    intervalHours?: number;
+    /** 0…59 — present only for `hourly` (minute-of-hour to fire at). Default 0. */
+    minuteOfHour?: number;
+}
+import type { RecurrenceRule } from "@aitne/shared";
+/**
+ * Convert a standard 5-field cron expression (`m h dom mon dow`) into a
+ * structured {@link AgentRecurrenceSpec}, or `null` when the expression is not
+ * one of the three shapes the recurrence rule can represent:
+ *
+ *   - **hourly**  `M * * * *` / `M *​/N * * *`     (hour wild or step)
+ *   - **daily**   `M H * * *`
+ *   - **weekly**  `M H * * <dow-list>`            (day-of-month wild)
+ *   - **monthly** `M H <dom-list> * *`            (day-of-week wild)
+ *
+ * The minute field must be a single integer. The hour field is either a single
+ * integer (daily/weekly/monthly) or `*` / `*​/N` (hourly). The month field must
+ * be `*` (the rule has no month selector). A `null` return is the signal to
+ * keep the raw cron string rather than fabricate a lossy rule.
+ */
+export declare function cronToRecurrenceSpec(cronExpr: string, timezone: string): AgentRecurrenceSpec | null;
+/**
+ * Convert a structured {@link AgentRecurrenceSpec} into a standard 5-field
+ * cron expression. Always total — `hourly` emits the step-form (`M * * * *` /
+ * `M *​/N * * *`), `daily` collapses both day fields to `*`, `weekly` lists the
+ * days-of-week, `monthly` lists the days-of-month. An empty / missing day list
+ * falls back to the wildcard so the expression is always schedulable.
+ */
+export declare function recurrenceSpecToCron(spec: AgentRecurrenceSpec): string;
+/**
+ * Convert a daemon `RecurrenceRule` (the schedule-API structured shape, incl.
+ * `hourly`) into a 5-field cron expression for storage in a user Agent's
+ * `agent.md`. Used by `POST /api/agents` so a caller can declare a structured
+ * `recurrence` (frequency + fields) and the route renders the canonical cron
+ * the loader then re-pairs. The monthly `onMissingDay` policy is intentionally
+ * not carried (cron cannot express it). Delegates to {@link recurrenceSpecToCron}
+ * after a field copy so the two stay byte-identical.
+ */
+export declare function recurrenceRuleToCron(rule: RecurrenceRule): string;

package/dist/core/agents/recurrence-convert.js

@@ -0,0 +1,207 @@
+/**
+ * Cron ⇄ recurrence-spec conversion for user-Agent recurring pairing and
+ * first-boot auto-import (AGENT_DEFINITIONS_DESIGN.md §6.1 step 5 / §6.5).
+ *
+ * User Agents declare their schedule as a cron `expression` in YAML, but the
+ * backing `recurring_schedules` row stores a *structured* recurrence rule
+ * (frequency / time / days). The loader therefore needs both directions:
+ *
+ *   - **pairing** (cron → spec): when a user Agent's YAML has no paired
+ *     recurring row yet, derive a structured spec to create one.
+ *   - **auto-import** (spec → cron): when a legacy recurring row has no Agent
+ *     YAML, derive a cron expression for the synthesised `agent.md`.
+ *
+ * To keep this module pure and dependency-free (so it stays in the
+ * 100%-coverage set and never imports a daemon-only / DB type), it deals in a
+ * loader-local {@link AgentRecurrenceSpec} that is a 1:1 structural mirror of
+ * the daemon's `recurrence_rule` JSON. The Phase-7 production adapter maps
+ * `AgentRecurrenceSpec` ↔ the real `recurring_schedules` `RecurrenceRule`
+ * with a field copy — no logic.
+ *
+ * Both functions are **total**: a cron shape the structured rule cannot
+ * represent (sub-hourly step minutes like `*​/30`, hour ranges/lists, `?` in
+ * the day fields, an OR of day-of-month AND day-of-week, etc.) yields `null`
+ * from {@link cronToRecurrenceSpec}, and the caller keeps the raw cron string
+ * instead of fabricating a lossy rule. `recurrenceSpecToCron` always produces a
+ * valid 5-field expression.
+ *
+ * **`hourly` IS mirrored** (the former Phase-7 gap, now closed). The daemon's
+ * `recurrenceRuleSchema` (schemas.ts) carries an `hourly` frequency
+ * (`intervalHours` 1..23 / `minuteOfHour` 0..59); this module round-trips it
+ * through the step-form cron `M * * * *` (every hour at :M) and `M *​/N * * *`
+ * (every N hours at :M). So a user Agent CAN declare an hourly cadence and the
+ * loader pairs it to a real `recurring_schedules.hourly` row. The remaining gap
+ * is the monthly `onMissingDay` policy, which cron cannot carry — it is dropped
+ * on conversion (a `daysOfMonth` cron uses node-cron's own missing-day
+ * behaviour). Sub-hourly intervals (every N minutes) are NOT representable —
+ * only the built-in hourly-check supports those, via config.
+ */
+/** Zero-pad a single clock field to two digits. */
+function pad2(value) {
+    return value < 10 ? `0${value}` : String(value);
+}
+/**
+ * Parse the hour field of an hourly cron into its interval in hours:
+ *   - `*`     → 1   (every hour)
+ *   - `*​/N`  → N   (every N hours, N in 1..23 to match `recurrenceRuleSchema`)
+ * Returns `null` for a single integer (that is a daily/weekly/monthly hour) or
+ * any other shape (range / list / out-of-range step).
+ */
+function parseHourInterval(field) {
+    if (field === "*")
+        return 1;
+    const match = /^\*\/(\d+)$/.exec(field);
+    if (!match)
+        return null;
+    const n = Number.parseInt(match[1], 10);
+    return n >= 1 && n <= 23 ? n : null;
+}
+/**
+ * Parse a single cron field that must be a single non-negative integer in
+ * `[min, max]`. Returns `null` for wildcards, lists, ranges, or steps — the
+ * caller treats that as "not representable as a structured rule".
+ */
+function parseSingleInt(field, min, max) {
+    if (field === undefined || !/^\d+$/.test(field))
+        return null;
+    const value = Number.parseInt(field, 10);
+    if (value < min || value > max)
+        return null;
+    return value;
+}
+/**
+ * Parse a comma-separated list of single integers in `[min, max]` (e.g. the
+ * day-of-week or day-of-month field). Returns `null` if any element is a
+ * wildcard / range / step / out-of-range value. An empty result is impossible
+ * because a non-empty field always yields at least one element or `null`.
+ */
+function parseIntList(field, min, max) {
+    const parts = field.split(",");
+    const out = [];
+    for (const part of parts) {
+        const value = parseSingleInt(part, min, max);
+        if (value === null)
+            return null;
+        out.push(value);
+    }
+    return out;
+}
+/**
+ * Convert a standard 5-field cron expression (`m h dom mon dow`) into a
+ * structured {@link AgentRecurrenceSpec}, or `null` when the expression is not
+ * one of the three shapes the recurrence rule can represent:
+ *
+ *   - **hourly**  `M * * * *` / `M *​/N * * *`     (hour wild or step)
+ *   - **daily**   `M H * * *`
+ *   - **weekly**  `M H * * <dow-list>`            (day-of-month wild)
+ *   - **monthly** `M H <dom-list> * *`            (day-of-week wild)
+ *
+ * The minute field must be a single integer. The hour field is either a single
+ * integer (daily/weekly/monthly) or `*` / `*​/N` (hourly). The month field must
+ * be `*` (the rule has no month selector). A `null` return is the signal to
+ * keep the raw cron string rather than fabricate a lossy rule.
+ */
+export function cronToRecurrenceSpec(cronExpr, timezone) {
+    const fields = cronExpr.trim().split(/\s+/);
+    if (fields.length !== 5)
+        return null;
+    const [minuteField, hourField, domField, monthField, dowField] = fields;
+    const minute = parseSingleInt(minuteField, 0, 59);
+    if (minute === null)
+        return null;
+    // The structured rule has no month selector, so a non-wildcard month field
+    // is not representable.
+    if (monthField !== "*")
+        return null;
+    const domWild = domField === "*";
+    // cron treats both `*` and `?` as "no constraint" for day-of-week; the
+    // structured rule only emits `*`, so normalise `?` to wild here.
+    const dowWild = dowField === "*" || dowField === "?";
+    // Hourly: the hour field is `*` (every hour) or `*​/N` (every N hours). An
+    // hourly rule fires on every day, so a constrained day-of-month / day-of-week
+    // is not representable (use a daily/weekly/monthly cadence for that).
+    const intervalHours = parseHourInterval(hourField);
+    if (intervalHours !== null) {
+        if (!(domWild && dowWild))
+            return null;
+        return { frequency: "hourly", timezone, intervalHours, minuteOfHour: minute };
+    }
+    // Daily / weekly / monthly: the hour field must be a single integer.
+    const hour = parseSingleInt(hourField, 0, 23);
+    if (hour === null)
+        return null;
+    const time = `${pad2(hour)}:${pad2(minute)}`;
+    if (domWild && dowWild) {
+        return { frequency: "daily", time, timezone };
+    }
+    if (domWild && !dowWild) {
+        const daysOfWeek = parseIntList(dowField, 0, 6);
+        if (daysOfWeek === null)
+            return null;
+        return { frequency: "weekly", time, timezone, daysOfWeek };
+    }
+    if (!domWild && dowWild) {
+        const daysOfMonth = parseIntList(domField, 1, 31);
+        if (daysOfMonth === null)
+            return null;
+        return { frequency: "monthly", time, timezone, daysOfMonth };
+    }
+    // Both day-of-month AND day-of-week constrained — cron ORs them, which the
+    // structured rule cannot express. Not representable.
+    return null;
+}
+/**
+ * Convert a structured {@link AgentRecurrenceSpec} into a standard 5-field
+ * cron expression. Always total — `hourly` emits the step-form (`M * * * *` /
+ * `M *​/N * * *`), `daily` collapses both day fields to `*`, `weekly` lists the
+ * days-of-week, `monthly` lists the days-of-month. An empty / missing day list
+ * falls back to the wildcard so the expression is always schedulable.
+ */
+export function recurrenceSpecToCron(spec) {
+    if (spec.frequency === "hourly") {
+        const minute = spec.minuteOfHour ?? 0;
+        const n = spec.intervalHours ?? 1;
+        // `*​/1` is just `*`; emit the simpler form for every-hour cadences.
+        return `${minute} ${n === 1 ? "*" : `*/${n}`} * * *`;
+    }
+    const [hourStr, minuteStr] = (spec.time ?? "").split(":");
+    // Defensive: a malformed / absent time falls back to midnight rather than
+    // emitting an unschedulable field. parseSingleInt tolerates an absent field.
+    const hour = parseSingleInt(hourStr, 0, 23) ?? 0;
+    const minute = parseSingleInt(minuteStr, 0, 59) ?? 0;
+    let dom = "*";
+    let dow = "*";
+    if (spec.frequency === "weekly") {
+        dow = spec.daysOfWeek && spec.daysOfWeek.length > 0
+            ? spec.daysOfWeek.join(",")
+            : "*";
+    }
+    else if (spec.frequency === "monthly") {
+        dom = spec.daysOfMonth && spec.daysOfMonth.length > 0
+            ? spec.daysOfMonth.join(",")
+            : "*";
+    }
+    return `${minute} ${hour} ${dom} * ${dow}`;
+}
+/**
+ * Convert a daemon `RecurrenceRule` (the schedule-API structured shape, incl.
+ * `hourly`) into a 5-field cron expression for storage in a user Agent's
+ * `agent.md`. Used by `POST /api/agents` so a caller can declare a structured
+ * `recurrence` (frequency + fields) and the route renders the canonical cron
+ * the loader then re-pairs. The monthly `onMissingDay` policy is intentionally
+ * not carried (cron cannot express it). Delegates to {@link recurrenceSpecToCron}
+ * after a field copy so the two stay byte-identical.
+ */
+export function recurrenceRuleToCron(rule) {
+    return recurrenceSpecToCron({
+        frequency: rule.frequency,
+        // timezone is unused by the cron emitter (it carries no zone); a placeholder
+        // keeps the spec well-formed.
+        timezone: rule.timezone ?? "UTC",
+        ...(rule.time !== undefined ? { time: rule.time } : {}),
+        ...(rule.daysOfWeek !== undefined ? { daysOfWeek: rule.daysOfWeek } : {}),
+        ...(rule.daysOfMonth !== undefined ? { daysOfMonth: rule.daysOfMonth } : {}),
+        ...(rule.intervalHours !== undefined ? { intervalHours: rule.intervalHours } : {}),
+        ...(rule.minuteOfHour !== undefined ? { minuteOfHour: rule.minuteOfHour } : {}),
+    });
+}

package/dist/core/agents/recurring-schedule-adapter.d.ts

@@ -0,0 +1,24 @@
+import type Database from "better-sqlite3";
+import type { RecurrenceRule } from "@aitne/shared";
+import type { RecurringSchedulePort } from "./loader.js";
+import type { AgentRecurrenceSpec } from "./recurrence-convert.js";
+/**
+ * Map a daemon `RecurrenceRule` to the loader's {@link AgentRecurrenceSpec}.
+ * Total over all four frequencies (`hourly` now round-trips via the step-form
+ * cron). `time` / `timezone` are guaranteed on daily/weekly/monthly rows by
+ * `recurrenceRuleSchema`, but a defensive fallback keeps the mapping total
+ * against a hand-edited row.
+ */
+export declare function recurrenceRuleToSpec(rule: RecurrenceRule, fallbackTimezone: string): AgentRecurrenceSpec;
+/**
+ * Map the loader's {@link AgentRecurrenceSpec} back to a daemon
+ * `RecurrenceRule`. Total — the spec carries the four cron-representable
+ * frequencies, all of which are valid `RecurrenceRule` shapes.
+ */
+export declare function specToRecurrenceRule(spec: AgentRecurrenceSpec): RecurrenceRule;
+/**
+ * Build the loader's {@link RecurringSchedulePort} over a live DB. The
+ * `fallbackTimezone` (resolved from `config.timezone`) fills a hand-edited
+ * row that somehow stored no zone; well-formed rows always carry their own.
+ */
+export declare function createRecurringSchedulePort(db: Database.Database, fallbackTimezone: string): RecurringSchedulePort;

package/dist/core/agents/recurring-schedule-adapter.js

@@ -0,0 +1,157 @@
+import { createRecurringSchedule, getRecurringSchedule, listRecurringSchedules, updateRecurringSchedule, } from "../../db/recurring-schedules.js";
+/**
+ * Concrete {@link RecurringSchedulePort} over `db/recurring-schedules.ts`
+ * (AGENT_DEFINITIONS_DESIGN.md §6.1 step 5 / §6.5 — the Phase-7 adapter the
+ * Phase-5 loader's DI seam expects).
+ *
+ * The loader speaks the cron-representable {@link AgentRecurrenceSpec}; the
+ * store speaks the richer daemon `RecurrenceRule` (which additionally carries
+ * `hourly` + the monthly `onMissingDay` policy). This adapter maps between the
+ * two with a field copy in the three directions the loader needs:
+ *
+ *   - `list()` / `get()`  — `RecurrenceRule` → `AgentRecurrenceSpec`.
+ *   - `create()` / `update()` — `AgentRecurrenceSpec` → `RecurrenceRule`.
+ *
+ * **`hourly` round-trips** (the former Phase-5/7 gap, now closed). An `hourly`
+ * recurring row maps to an `hourly` {@link AgentRecurrenceSpec} (and back via
+ * the step-form cron), so the loader pairs hourly user Agents and auto-imports
+ * legacy `hourly` `agent.task` rows like any other cadence. Subsystem-owned
+ * rows (managed-tasks / automation / the dm_session seed) are still skipped by
+ * the loader's own `isSubsystemOwnedRow` gate, not here.
+ *
+ * Every `update()` carries `cancelReason: "agent_definition_changed"` so a
+ * superseded pending materialisation is tagged in its `task_context`
+ * (§11.3.2) — the adapter is only ever called for Agent-owned rows, so the
+ * reason is always accurate.
+ */
+const AGENT_CANCEL_REASON = "agent_definition_changed";
+/**
+ * Map a daemon `RecurrenceRule` to the loader's {@link AgentRecurrenceSpec}.
+ * Total over all four frequencies (`hourly` now round-trips via the step-form
+ * cron). `time` / `timezone` are guaranteed on daily/weekly/monthly rows by
+ * `recurrenceRuleSchema`, but a defensive fallback keeps the mapping total
+ * against a hand-edited row.
+ */
+export function recurrenceRuleToSpec(rule, fallbackTimezone) {
+    const timezone = rule.timezone && rule.timezone.length > 0 ? rule.timezone : fallbackTimezone;
+    if (rule.frequency === "hourly") {
+        return {
+            frequency: "hourly",
+            timezone,
+            intervalHours: rule.intervalHours ?? 1,
+            minuteOfHour: rule.minuteOfHour ?? 0,
+        };
+    }
+    const time = rule.time && rule.time.length > 0 ? rule.time : "00:00";
+    if (rule.frequency === "weekly") {
+        return {
+            frequency: "weekly",
+            time,
+            timezone,
+            daysOfWeek: rule.daysOfWeek ?? [],
+        };
+    }
+    if (rule.frequency === "monthly") {
+        return {
+            frequency: "monthly",
+            time,
+            timezone,
+            daysOfMonth: rule.daysOfMonth ?? [],
+        };
+    }
+    return { frequency: "daily", time, timezone };
+}
+/**
+ * Map the loader's {@link AgentRecurrenceSpec} back to a daemon
+ * `RecurrenceRule`. Total — the spec carries the four cron-representable
+ * frequencies, all of which are valid `RecurrenceRule` shapes.
+ */
+export function specToRecurrenceRule(spec) {
+    if (spec.frequency === "hourly") {
+        return {
+            frequency: "hourly",
+            timezone: spec.timezone,
+            intervalHours: spec.intervalHours ?? 1,
+            minuteOfHour: spec.minuteOfHour ?? 0,
+        };
+    }
+    // Single defensive fallback for the three timed frequencies (well-formed
+    // daily/weekly/monthly specs always carry a time).
+    const time = spec.time ?? "00:00";
+    if (spec.frequency === "weekly") {
+        return { frequency: "weekly", time, timezone: spec.timezone, daysOfWeek: spec.daysOfWeek ?? [] };
+    }
+    if (spec.frequency === "monthly") {
+        return { frequency: "monthly", time, timezone: spec.timezone, daysOfMonth: spec.daysOfMonth ?? [] };
+    }
+    return { frequency: "daily", time, timezone: spec.timezone };
+}
+/** Map a store DTO to the loader row shape. Total — every `recurrence_rule`
+ *  frequency (incl. `hourly`) is now representable as an `AgentRecurrenceSpec`. */
+function dtoToAgentRow(dto, fallbackTimezone) {
+    return {
+        id: dto.id,
+        enabled: dto.enabled,
+        taskType: dto.taskType,
+        description: dto.description,
+        prompt: dto.prompt,
+        model: dto.model,
+        tier: dto.tier,
+        backendId: dto.backendId,
+        recurrence: recurrenceRuleToSpec(dto.recurrenceRule, fallbackTimezone),
+        // Carried so the loader's auto-import sweep can skip subsystem-owned rows
+        // (managed-tasks `mt_id`, automation-trigger `triggerSource`).
+        taskContext: dto.taskContext,
+    };
+}
+/**
+ * Build the loader's {@link RecurringSchedulePort} over a live DB. The
+ * `fallbackTimezone` (resolved from `config.timezone`) fills a hand-edited
+ * row that somehow stored no zone; well-formed rows always carry their own.
+ */
+export function createRecurringSchedulePort(db, fallbackTimezone) {
+    return {
+        list() {
+            return listRecurringSchedules(db).map((dto) => dtoToAgentRow(dto, fallbackTimezone));
+        },
+        get(id) {
+            const dto = getRecurringSchedule(db, id);
+            return dto === null ? null : dtoToAgentRow(dto, fallbackTimezone);
+        },
+        create(input) {
+            const dto = createRecurringSchedule(db, {
+                // §6.4-resolved enabled (mirrors `agents.enabled`); the store defaults
+                // to enabled when omitted, but the loader always resolves it explicitly.
+                enabled: input.enabled,
+                taskType: input.taskType,
+                description: input.description,
+                ...(input.prompt !== null ? { prompt: input.prompt } : {}),
+                recurrenceRule: specToRecurrenceRule(input.recurrence),
+                ...(input.model !== null ? { model: input.model } : {}),
+                ...(input.tier !== null ? { tier: input.tier } : {}),
+                ...(input.backendId !== null ? { backendId: input.backendId } : {}),
+            });
+            return dto.id;
+        },
+        update(id, patch) {
+            updateRecurringSchedule(db, id, {
+                ...(patch.enabled !== undefined ? { enabled: patch.enabled } : {}),
+                ...(patch.description !== undefined
+                    ? { description: patch.description }
+                    : {}),
+                ...(patch.prompt !== undefined ? { prompt: patch.prompt } : {}),
+                ...(patch.model !== undefined ? { model: patch.model } : {}),
+                ...(patch.tier !== undefined ? { tier: patch.tier } : {}),
+                ...(patch.backendId !== undefined
+                    ? { backendId: patch.backendId }
+                    : {}),
+                ...(patch.recurrence !== undefined
+                    ? { recurrenceRule: specToRecurrenceRule(patch.recurrence) }
+                    : {}),
+            }, 
+            // Agent-driven edits tag a superseded pending row so the dispatcher /
+            // dashboard can attribute the skip to a definition change (§11.3.2).
+            AGENT_CANCEL_REASON);
+        },
+    };
+}