@aitne/daemon 0.1.8 → 0.1.10

package/dist/core/agents/loader-boot.d.ts

@@ -0,0 +1,26 @@
+import type Database from "better-sqlite3";
+import type { AgentConfig } from "../../config.js";
+import { AgentEnabledCache, type AgentLoadOptions, type LoadAgentsResult } from "./loader.js";
+import { type AgentsWatcherHandle } from "./loader-watcher.js";
+export interface BootstrapAgentsDeps {
+    db: Database.Database;
+    config: AgentConfig;
+    /** Dashboard SSE broadcaster; omitted in headless installs. */
+    eventBroadcaster?: {
+        broadcastEvent: (data: unknown) => void;
+    };
+}
+export interface BootstrapAgentsResult {
+    result: LoadAgentsResult;
+    enabledCache: AgentEnabledCache;
+    watcher: AgentsWatcherHandle | null;
+}
+/** Resolve the loader's port set + dirs from daemon config. */
+export declare function buildAgentLoadOptions(deps: BootstrapAgentsDeps): AgentLoadOptions;
+/**
+ * Load every Agent definition at boot, build the enabled cache, and start the
+ * user-root watcher. Wire the returned `enabledCache` into the scheduler via
+ * `scheduler.setAgentEnabledCache(...)` and the `watcher` into the shutdown
+ * sequence.
+ */
+export declare function bootstrapAgents(deps: BootstrapAgentsDeps): BootstrapAgentsResult;

package/dist/core/agents/loader-boot.js

@@ -0,0 +1,98 @@
+import { join } from "node:path";
+import { getContextDir } from "../../config.js";
+import { createLogger } from "../../logging.js";
+import { AgentEnabledCache, loadAgents, resolveTimezone, } from "./loader.js";
+import { startAgentsWatcher, } from "./loader-watcher.js";
+import { createRecurringSchedulePort } from "./recurring-schedule-adapter.js";
+import { listAllSkillSlugs } from "../release-assets.js";
+import { resolveUserSkillsRoot } from "../user-skills-root.js";
+/**
+ * Boot adapter for the Agent loader (AGENT_DEFINITIONS_DESIGN.md §6.1 — the
+ * Phase-7 `(db, config)` wrapper the Phase-5 loader's DI seam expects).
+ *
+ * Resolves the concrete ports the loader's pure core takes as injected deps:
+ *   - `builtinDir` = `<workspaceDir>/agent-assets/agents`,
+ *     `userDir`    = `<contextDir>/policies/agents`;
+ *   - `snapshot`   → an `md_file_snapshots` row writer (mirrors the
+ *     daily-journal / roadmap-maintenance snapshot inserts);
+ *   - `events`     → the dashboard SSE broadcaster (`agent.updated`);
+ *   - `recurring`  → the `recurring-schedule-adapter` over `db/recurring-schedules`.
+ *
+ * Runs the boot scan, builds the live {@link AgentEnabledCache} the scheduler
+ * gate consults, and starts the filesystem watcher (user root only — built-ins
+ * ship read-only) so a dashboard-authored `agent.md` reloads without a restart.
+ * Never throws: the loader is crash-proof by contract and a watcher start
+ * failure degrades to a logged warning.
+ */
+const logger = createLogger("agents-loader-boot");
+/** Resolve the loader's port set + dirs from daemon config. */
+export function buildAgentLoadOptions(deps) {
+    const { db, config, eventBroadcaster } = deps;
+    const builtinDir = join(config.workspaceDir, "agent-assets", "agents");
+    const userDir = join(getContextDir(config, db), "policies", "agents");
+    // A concrete zone for the recurring adapter's fallback (well-formed rows
+    // carry their own; this only fills a hand-edited row with none).
+    const fallbackTz = resolveTimezone(undefined, config.timezone);
+    // Snapshot the known skill slugs once at boot for the loader's `tools.skills`
+    // cross-check (§4.3 step 5). A skill added mid-session is a minor staleness
+    // (re-resolved on the next boot), not a correctness gap — the watcher reuses
+    // the same opts, matching the recurring-port snapshot semantics.
+    const skillSlugs = listAllSkillSlugs(resolveUserSkillsRoot(config), config.workspaceDir);
+    const snapshot = {
+        record: ({ filePath, content, trigger }) => {
+            try {
+                db.prepare("INSERT INTO md_file_snapshots (file_path, content, trigger, session_id) VALUES (?, ?, ?, ?)").run(filePath, content, trigger, null);
+            }
+            catch (err) {
+                logger.warn({ err, filePath, trigger }, "Failed to save agent md_file_snapshots row");
+            }
+        },
+    };
+    const events = eventBroadcaster
+        ? {
+            emit: (event, payload) => eventBroadcaster.broadcastEvent({
+                kind: event,
+                ...payload,
+            }),
+        }
+        : undefined;
+    return {
+        builtinDir,
+        userDir,
+        dayBoundaryHour: config.dayBoundaryHour,
+        timezone: config.timezone,
+        snapshot,
+        ...(events ? { events } : {}),
+        recurring: createRecurringSchedulePort(db, fallbackTz),
+        listSkillSlugs: () => skillSlugs,
+    };
+}
+/**
+ * Load every Agent definition at boot, build the enabled cache, and start the
+ * user-root watcher. Wire the returned `enabledCache` into the scheduler via
+ * `scheduler.setAgentEnabledCache(...)` and the `watcher` into the shutdown
+ * sequence.
+ */
+export function bootstrapAgents(deps) {
+    const opts = buildAgentLoadOptions(deps);
+    const result = loadAgents(deps.db, opts);
+    if (result.invalid.length > 0) {
+        logger.warn({ count: result.invalid.length, slugs: result.invalid.map((d) => d.slug) }, "Some Agent definitions failed to load (surfaced under /api/agents include_invalid)");
+    }
+    for (const warning of result.warnings)
+        logger.debug({ warning }, "agent load warning");
+    logger.info({ upserted: result.upserted.length }, "Agents loaded");
+    const enabledCache = new AgentEnabledCache(deps.db);
+    let watcher = null;
+    try {
+        watcher = startAgentsWatcher(deps.db, opts, {
+            reload: () => loadAgents(deps.db, opts),
+            cache: enabledCache,
+            ...(opts.events ? { events: opts.events } : {}),
+        });
+    }
+    catch (err) {
+        logger.warn({ err }, "Agent definitions watcher failed to start — edits apply on next restart");
+    }
+    return { result, enabledCache, watcher };
+}

package/dist/core/agents/loader-watcher.d.ts

@@ -0,0 +1,23 @@
+import type Database from "better-sqlite3";
+import { AgentEnabledCache, type AgentEventPort, type AgentLoadOptions, type LoadAgentsResult } from "./loader.js";
+export interface AgentsWatcherHandle {
+    stop(): Promise<void>;
+}
+export interface AgentsWatcherOptions {
+    /** Also watch the shipped built-in root (dev hot-reload). Off in production. */
+    watchBuiltin?: boolean;
+    /** Debounce window before a reload fires after the last filesystem event. */
+    debounceMs?: number;
+    /** Reload implementation (defaults to `loadAgents`); overridable for tests. */
+    reload?: () => LoadAgentsResult;
+    /** Optional enabled-cache to invalidate after each reload. */
+    cache?: AgentEnabledCache;
+    /** Optional SSE port; an `agent.updated` event fires after each reload. */
+    events?: AgentEventPort;
+}
+/**
+ * Start watching the user (and optionally built-in) agent roots. Returns a
+ * handle whose `stop()` closes the chokidar watcher. Errors in the reload
+ * handler are logged, never thrown — a bad edit must not take down the daemon.
+ */
+export declare function startAgentsWatcher(db: Database.Database, opts: AgentLoadOptions, watcherOpts?: AgentsWatcherOptions): AgentsWatcherHandle;

package/dist/core/agents/loader-watcher.js

@@ -0,0 +1,84 @@
+import { basename } from "node:path";
+import * as chokidar from "chokidar";
+import { createLogger } from "../../logging.js";
+import { loadAgents, } from "./loader.js";
+/**
+ * Filesystem watcher for Agent definitions (AGENT_DEFINITIONS_DESIGN.md §6.2).
+ *
+ * Mirrors the `core/management-md.ts` chokidar pattern: debounced
+ * (`awaitWriteFinish`), `ignoreInitial`, resilient to handler errors, and —
+ * importantly — it watches the agent *directories* and filters events to
+ * `agent.md` basenames rather than passing a glob to `chokidar.watch`
+ * (chokidar v4 dropped glob support, so a `**​/agent.md` argument would be
+ * treated as a literal path and never fire).
+ *
+ * On any add/change/unlink of an `agent.md` it re-runs {@link loadAgents} (the
+ * full pass is cheap — the loader's hash/override efficiency-skip writes only
+ * the rows that actually changed) and invalidates the enabled-cache so the
+ * scheduler gate sees the new state on its next firing.
+ *
+ * The reload is injectable so the unit test can assert it fires without
+ * standing up the whole pass; production defaults to `loadAgents`.
+ */
+const logger = createLogger("agents-watcher");
+const AGENT_FILE_NAME = "agent.md";
+/**
+ * Start watching the user (and optionally built-in) agent roots. Returns a
+ * handle whose `stop()` closes the chokidar watcher. Errors in the reload
+ * handler are logged, never thrown — a bad edit must not take down the daemon.
+ */
+export function startAgentsWatcher(db, opts, watcherOpts = {}) {
+    const roots = [opts.userDir];
+    if (watcherOpts.watchBuiltin) {
+        roots.push(opts.builtinDir);
+    }
+    const debounceMs = watcherOpts.debounceMs ?? 300;
+    const reload = watcherOpts.reload ?? (() => loadAgents(db, opts));
+    const watcher = chokidar.watch(roots, {
+        persistent: true,
+        ignoreInitial: true,
+        awaitWriteFinish: {
+            stabilityThreshold: 300,
+            pollInterval: 100,
+        },
+    });
+    let timer = null;
+    const runReload = (reason) => {
+        try {
+            const result = reload();
+            watcherOpts.cache?.invalidate();
+            watcherOpts.events?.emit("agent.updated", { reason, upserted: result.upserted });
+            logger.info({ reason, upserted: result.upserted.length, invalid: result.invalid.length }, "agents reloaded after filesystem change");
+        }
+        catch (err) {
+            logger.error({ err, reason }, "agents reload failed");
+        }
+    };
+    const schedule = (reason) => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = null;
+            runReload(reason);
+        }, debounceMs);
+        timer.unref?.();
+    };
+    // Only `agent.md` files matter; ignore the surrounding directory churn.
+    const onEvent = (reason) => (filePath) => {
+        if (basename(filePath) === AGENT_FILE_NAME)
+            schedule(reason);
+    };
+    watcher.on("add", onEvent("add"));
+    watcher.on("change", onEvent("change"));
+    watcher.on("unlink", onEvent("unlink"));
+    watcher.on("error", (err) => logger.error({ err }, "agents watcher error"));
+    logger.info({ roots }, "agents watcher started");
+    return {
+        async stop() {
+            if (timer)
+                clearTimeout(timer);
+            await watcher.close();
+            logger.info("agents watcher stopped");
+        },
+    };
+}

package/dist/core/agents/loader.d.ts

@@ -0,0 +1,188 @@
+import type Database from "better-sqlite3";
+import { type AgentDefinition } from "@aitne/shared";
+import { type AgentDTO, type AgentSource } from "../../db/agents-store.js";
+import { createLogger } from "../../logging.js";
+import { type BuiltinAgentRegistryEntry } from "./builtin-registry.js";
+import { type AgentRecurrenceSpec } from "./recurrence-convert.js";
+/** Writes an `md_file_snapshots` row on definition-hash change (§6.3). */
+export interface AgentSnapshotPort {
+    record(input: {
+        filePath: string;
+        content: string;
+        trigger: string;
+    }): void;
+}
+/** Emits an SSE event for live dashboard refresh (§6.2 / §9.8). */
+export interface AgentEventPort {
+    emit(event: string, payload: unknown): void;
+}
+/** A `recurring_schedules` row in the loader-local recurrence vocabulary. */
+export interface RecurringAgentRow {
+    id: number;
+    enabled: boolean;
+    taskType: string;
+    description: string;
+    prompt: string | null;
+    model: string | null;
+    tier: string | null;
+    backendId: string | null;
+    recurrence: AgentRecurrenceSpec;
+    /**
+     * The row's `task_context` (parsed). Used by the auto-import sweep to skip
+     * rows owned by another subsystem (managed-tasks `mt_id`, automation-trigger
+     * `triggerSource`) so they never materialise a bogus `imported-<id>` Agent.
+     */
+    taskContext: Record<string, unknown>;
+}
+/** Fields needed to create a `recurring_schedules` row for a user Agent. */
+export interface RecurringCreateInput {
+    /**
+     * §6.4-resolved enabled (NOT the raw YAML value). The recurring row that the
+     * reconciler gates firing on (`WHERE enabled = 1`) must track the same
+     * last-write-wins resolution as `agents.enabled`, or a dashboard-disabled
+     * Agent silently resumes firing after a restart (and a fresh `enabled: false`
+     * Agent would fire once).
+     */
+    enabled: boolean;
+    taskType: string;
+    description: string;
+    prompt: string | null;
+    model: string | null;
+    tier: string | null;
+    backendId: string | null;
+    recurrence: AgentRecurrenceSpec;
+}
+/** Divergent-field patch applied when reconciling a paired recurring row (YAML wins). */
+export interface RecurringUpdateInput {
+    enabled?: boolean;
+    description?: string;
+    prompt?: string | null;
+    model?: string | null;
+    tier?: string | null;
+    backendId?: string | null;
+    recurrence?: AgentRecurrenceSpec;
+}
+/**
+ * Recurring-schedule pairing + auto-import port (§6.1 step 5 / §6.5). The
+ * Phase-7 adapter maps these to `db/recurring-schedules.ts`; tests pass a fake.
+ */
+export interface RecurringSchedulePort {
+    list(): RecurringAgentRow[];
+    get(id: number): RecurringAgentRow | null;
+    create(input: RecurringCreateInput): number;
+    update(id: number, patch: RecurringUpdateInput): void;
+}
+type LoaderLogger = Pick<ReturnType<typeof createLogger>, "info" | "warn" | "error" | "debug">;
+/** Everything `loadAgents` needs. The boot wiring resolves these from
+ *  `AgentConfig` (`builtinDir = <workspaceDir>/agent-assets/agents`,
+ *  `userDir = <contextDir>/policies/agents`); tests pass temp dirs + fakes. */
+export interface AgentLoadOptions {
+    /** Absolute path to the shipped built-in agents root. */
+    builtinDir: string;
+    /** Absolute path to the user agents root under the context vault. */
+    userDir: string;
+    /** Live day-boundary hour for cron placeholder substitution (§4.2). */
+    dayBoundaryHour: number;
+    /** Resolved IANA timezone stamped on rows whose YAML omits one (§5.1). */
+    timezone: string;
+    snapshot?: AgentSnapshotPort;
+    events?: AgentEventPort;
+    recurring?: RecurringSchedulePort;
+    /** Skill-slug set for the `tools.skills` cross-check (§4.3 step 5). */
+    listSkillSlugs?: () => ReadonlySet<string>;
+    now?: () => number;
+    logger?: LoaderLogger;
+}
+/** A definition that failed to load (parse error, slug collision, cross-check). */
+export interface InvalidAgentDefinition {
+    slug: string;
+    source: AgentSource;
+    path: string;
+    error: string;
+    /** True when the failure is a built-in-slug collision that owns no DB row. */
+    collision: boolean;
+}
+export interface LoadAgentsResult {
+    /** Slugs upserted this run (valid, fallback-synthesised, or invalid rows). */
+    upserted: string[];
+    /** Per-file load failures (§6.6). Collisions have no DB row. */
+    invalid: InvalidAgentDefinition[];
+    /** Non-fatal warnings (cron drift, codex widening, unknown skill, …). */
+    warnings: string[];
+}
+interface ScannedFile {
+    slug: string;
+    path: string;
+    source: AgentSource;
+}
+/**
+ * List `<root>/<slug>/agent.md` entries under a single agents root. Missing
+ * roots return `[]` (a fresh install has no user agents dir yet). Directory
+ * entries without an `agent.md` are skipped.
+ */
+export declare function scanAgentDir(root: string, source: AgentSource): ScannedFile[];
+/** First non-empty string, falling back to the system zone then UTC. The
+ *  config default for `timezone` is `""`, so a plain `??` would store an empty
+ *  zone — guard on truthiness. */
+export declare function resolveTimezone(yamlTz: string | undefined, configTz: string): string;
+/**
+ * Resolve the concrete `schedule_expression` column value for a definition:
+ * cron expressions get `{dayBoundaryHour}` substituted; one_shot / event store
+ * their raw spec field. Returns `null` only when the (refinement-guaranteed)
+ * field is somehow absent — defensively, never throws.
+ */
+export declare function resolveScheduleExpression(def: AgentDefinition, dayBoundaryHour: number): string | null;
+/**
+ * Build a schema-valid `AgentDefinition` from a built-in registry entry, used
+ * as the base when a built-in's `agent.md` is missing or invalid. Parsing
+ * through `agentDefinitionSchema` fills every schema default (limits, tools,
+ * on_error, version) so the result is a complete identity.
+ */
+export declare function synthesizeRegistryDefinition(entry: BuiltinAgentRegistryEntry, dayBoundaryHour: number): AgentDefinition;
+/**
+ * Find the first `tools.allowed` entry that overlaps `ALWAYS_DISALLOWED_TOOLS`
+ * — a definition can never widen past the absolute-block layer. An exact
+ * pattern match (covers bare tool names like `CronCreate`) or a
+ * `classifyAbsoluteBlock` hit on a `Tool(arg)` entry both count. Returns the
+ * offending entry, or `null` when the allow-list is clean.
+ */
+export declare function findAbsoluteBlockOverlap(allowed: readonly string[]): string | null;
+/**
+ * Cross-checks a parsed/synthesised definition beyond what the Zod schema can
+ * express. Returns an error string (→ invalid, §6.6) or `null` when valid;
+ * appends any non-fatal notes to `warnings`.
+ */
+export declare function validateDefinition(def: AgentDefinition, source: AgentSource, expectedSlug: string, opts: {
+    listSkillSlugs?: () => ReadonlySet<string>;
+}, warnings: string[]): string | null;
+/**
+ * Resolve the effective `enabled` for a row given the YAML/base value, the file
+ * mtime, and the operator's last dashboard toggle. The dashboard override wins
+ * only while it is at least as recent as the file; editing the file (or a fresh
+ * row with no override) lets the YAML win.
+ */
+export declare function resolveEnabled(baseEnabled: boolean, existing: AgentDTO | null, fileMtimeMs: number): boolean;
+/**
+ * Load every Agent definition into the `agents` table. Never throws; per-file
+ * failures land in {@link LoadAgentsResult.invalid}. Order: auto-import (writes
+ * orphan files) → scan → parse/validate → registry fallback → resolve & upsert.
+ */
+export declare function loadAgents(db: Database.Database, opts: AgentLoadOptions): LoadAgentsResult;
+/**
+ * In-memory cache of built-in `enabled` state for the scheduler's per-cron gate
+ * (§7.1). The scheduler calls {@link AgentEnabledCache.isEnabled} on every
+ * firing; the loader watcher and the `PATCH /api/agents/:slug` handler call
+ * {@link AgentEnabledCache.invalidate} so the next read re-queries the DB.
+ *
+ * An unknown slug defaults to **enabled** so a not-yet-loaded built-in never
+ * silently stops firing — the conservative direction for a routine.
+ */
+export declare class AgentEnabledCache {
+    private readonly db;
+    private cache;
+    constructor(db: Database.Database);
+    private ensure;
+    isEnabled(slug: string): boolean;
+    invalidate(): void;
+}
+export {};