@aitne/daemon 0.1.7 → 0.1.9

package/dist/db/agent-executions-store.d.ts

@@ -0,0 +1,149 @@
+import type Database from "better-sqlite3";
+/**
+ * Agent executions store — the per-firing rollup layer
+ * (AGENT_DEFINITIONS_DESIGN.md §5.2 / §7.4). One row per fired Execution:
+ * inserted at start (`result = NULL`), updated at completion, and force-closed
+ * by the boot-time janitor if a crash leaves it non-terminal.
+ *
+ * This module is the persistence layer the Phase-6 recorder
+ * (`core/agent-execution-recorder.ts`) wraps — the recorder owns agent-day
+ * stamping and the same-transaction `agents.last_execution_id` update; this
+ * store owns the raw `agent_executions` SQL.
+ *
+ * Timestamps (`started_at` / `ended_at`) are epoch-millisecond integers, so
+ * the metrics windows are plain `now - days * 86_400_000` cutoffs and the
+ * crash janitor compares against `daemon_boot_time` directly (§5.1 note).
+ */
+export type AgentExecutionTrigger = "cron" | "manual" | "event" | "self";
+export type AgentExecutionResult = "success" | "error" | "skipped" | "timeout";
+/** Raw row as stored in SQLite. */
+export interface AgentExecutionRow {
+    id: number;
+    agent_id: string;
+    schedule_row_id: number | null;
+    trigger: AgentExecutionTrigger;
+    started_at: number;
+    ended_at: number | null;
+    result: AgentExecutionResult | null;
+    error_kind: string | null;
+    error_message: string | null;
+    cost_usd: number | null;
+    tokens_input: number | null;
+    tokens_output: number | null;
+    turns: number | null;
+    success_criteria_json: string | null;
+    output_summary: string | null;
+    metadata_json: string;
+}
+/** Parsed, camelCase view returned to callers. */
+export interface AgentExecutionDTO {
+    id: number;
+    agentId: string;
+    scheduleRowId: number | null;
+    trigger: AgentExecutionTrigger;
+    startedAt: number;
+    endedAt: number | null;
+    result: AgentExecutionResult | null;
+    errorKind: string | null;
+    errorMessage: string | null;
+    costUsd: number | null;
+    tokensInput: number | null;
+    tokensOutput: number | null;
+    turns: number | null;
+    /** Per-criterion hit map; `null` until the criteria are evaluated. */
+    successCriteria: Record<string, boolean> | null;
+    outputSummary: string | null;
+}
+export interface StartExecutionInput {
+    agentId: string;
+    scheduleRowId?: number | null;
+    trigger: AgentExecutionTrigger;
+}
+export interface ExecutionCost {
+    usd?: number | null;
+    tokensIn?: number | null;
+    tokensOut?: number | null;
+    turns?: number | null;
+}
+export interface CompleteExecutionInput {
+    executionId: number;
+    result: AgentExecutionResult;
+    errorKind?: string | null;
+    errorMessage?: string | null;
+    cost?: ExecutionCost;
+    successCriteriaHits?: Record<string, boolean>;
+    outputSummary?: string | null;
+}
+export interface ListExecutionsOptions {
+    /** Max rows (default 25). */
+    limit?: number;
+    /** Keyset cursor — return rows with `id < before`. */
+    before?: number;
+    /** Filter by terminal result. */
+    result?: AgentExecutionResult;
+}
+/** Per-window metrics (§9.1 / §9.2). */
+export interface AgentMetricsWindow {
+    /** Rows fired in the window (any result, incl. in-flight). */
+    executions: number;
+    /** errors / terminal rows; 0 when there are no terminal rows. */
+    errorRate: number;
+    /** Mean `cost_usd` over rows that recorded one; null when none did. */
+    avgCostUsd: number | null;
+    /** Σtrue / Σtotal across recorded criteria maps; null when none recorded. */
+    criteriaHitRate: number | null;
+    /**
+     * p95 of (ended-started)/1000 over completed rows; null when none.
+     * Crash-swept rows (`error_kind = 'crash'`) are EXCLUDED: their `ended_at`
+     * is the daemon's boot instant stamped by `sweepAbandoned`, not the real
+     * runtime, so a long daemon outage would otherwise inflate the percentile
+     * with a fictional multi-hour/day "duration". They still count toward
+     * `errorRate` (they are genuine failures) — only the duration sample drops
+     * them.
+     */
+    p95DurationSeconds: number | null;
+}
+export interface SweepAbandonedResult {
+    count: number;
+    ids: number[];
+}
+/**
+ * Insert a new in-flight Execution (`result = NULL`). Returns the new id.
+ * The `agent_id` FK requires the Agent row to already exist — the recorder
+ * always upserts the Agent first.
+ */
+export declare function startExecution(db: Database.Database, input: StartExecutionInput, now?: number): number;
+/**
+ * Finalise an Execution row with its result, cost, criteria, and summary.
+ * Returns true when a row matched the id. Does NOT touch
+ * `agents.last_execution_id` — the recorder pairs this with
+ * `agents-store.setLastExecutionId` in one transaction (§8.2).
+ */
+export declare function completeExecution(db: Database.Database, input: CompleteExecutionInput, now?: number): boolean;
+/**
+ * Boot-time crash janitor (§7.4). Flips every still-in-flight row whose
+ * `started_at` predates `beforeTs` (the daemon boot instant) to
+ * `error / crash`, stamping `ended_at = now`. Returns the affected ids so the
+ * caller can surface an audit line. Idempotent: a second call finds nothing
+ * left non-terminal.
+ */
+export declare function sweepAbandoned(db: Database.Database, beforeTs: number, now?: number): SweepAbandonedResult;
+export declare function getExecution(db: Database.Database, id: number): AgentExecutionDTO | null;
+/**
+ * Paginated execution history for one Agent, newest first (§9.3). `before` is
+ * a keyset cursor on `id`; `result` filters by terminal state.
+ */
+export declare function listExecutions(db: Database.Database, agentId: string, opts?: ListExecutionsOptions): AgentExecutionDTO[];
+/**
+ * Rollup metrics over the trailing `days` window (§9.1 / §9.2). All derived
+ * fields are computed in JS over a single `(agent_id, started_at DESC)` index
+ * scan so the math (error_rate, avg_cost, criteria_hit_rate, p95) stays
+ * unit-testable without SQL fixtures.
+ */
+export declare function metricsWindow(db: Database.Database, agentId: string, days: number, now?: number): AgentMetricsWindow;
+/**
+ * Count of error executions grouped by `error_kind` over the trailing `days`
+ * window (§9.2 `by_error_kind_7d`). A NULL `error_kind` is bucketed as
+ * `"unknown"`.
+ */
+export declare function byErrorKind(db: Database.Database, agentId: string, days: number, now?: number): Record<string, number>;

package/dist/db/agent-executions-store.js

@@ -0,0 +1,209 @@
+const DAY_MS = 86_400_000;
+function parseSuccessCriteria(json) {
+    if (json === null)
+        return null;
+    try {
+        const parsed = JSON.parse(json);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const out = {};
+            for (const [key, value] of Object.entries(parsed)) {
+                out[key] = value === true;
+            }
+            return out;
+        }
+    }
+    catch {
+        /* fall through to {} */
+    }
+    return {};
+}
+function rowToDTO(row) {
+    return {
+        id: row.id,
+        agentId: row.agent_id,
+        scheduleRowId: row.schedule_row_id,
+        trigger: row.trigger,
+        startedAt: row.started_at,
+        endedAt: row.ended_at,
+        result: row.result,
+        errorKind: row.error_kind,
+        errorMessage: row.error_message,
+        costUsd: row.cost_usd,
+        tokensInput: row.tokens_input,
+        tokensOutput: row.tokens_output,
+        turns: row.turns,
+        successCriteria: parseSuccessCriteria(row.success_criteria_json),
+        outputSummary: row.output_summary,
+    };
+}
+// ── Lifecycle writes ──────────────────────────────────────────────────
+/**
+ * Insert a new in-flight Execution (`result = NULL`). Returns the new id.
+ * The `agent_id` FK requires the Agent row to already exist — the recorder
+ * always upserts the Agent first.
+ */
+export function startExecution(db, input, now = Date.now()) {
+    const result = db
+        .prepare(`INSERT INTO agent_executions
+         (agent_id, schedule_row_id, trigger, started_at, result)
+       VALUES (?, ?, ?, ?, NULL)`)
+        .run(input.agentId, input.scheduleRowId ?? null, input.trigger, now);
+    return Number(result.lastInsertRowid);
+}
+/**
+ * Finalise an Execution row with its result, cost, criteria, and summary.
+ * Returns true when a row matched the id. Does NOT touch
+ * `agents.last_execution_id` — the recorder pairs this with
+ * `agents-store.setLastExecutionId` in one transaction (§8.2).
+ */
+export function completeExecution(db, input, now = Date.now()) {
+    const cost = input.cost ?? {};
+    const result = db
+        .prepare(`UPDATE agent_executions SET
+          ended_at = ?,
+          result = ?,
+          error_kind = ?,
+          error_message = ?,
+          cost_usd = ?,
+          tokens_input = ?,
+          tokens_output = ?,
+          turns = ?,
+          success_criteria_json = ?,
+          output_summary = ?
+        WHERE id = ?`)
+        .run(now, input.result, input.errorKind ?? null, input.errorMessage ?? null, cost.usd ?? null, cost.tokensIn ?? null, cost.tokensOut ?? null, cost.turns ?? null, input.successCriteriaHits !== undefined
+        ? JSON.stringify(input.successCriteriaHits)
+        : null, input.outputSummary ?? null, input.executionId);
+    return result.changes > 0;
+}
+/**
+ * Boot-time crash janitor (§7.4). Flips every still-in-flight row whose
+ * `started_at` predates `beforeTs` (the daemon boot instant) to
+ * `error / crash`, stamping `ended_at = now`. Returns the affected ids so the
+ * caller can surface an audit line. Idempotent: a second call finds nothing
+ * left non-terminal.
+ */
+export function sweepAbandoned(db, beforeTs, now = Date.now()) {
+    const sweep = db.transaction(() => {
+        const rows = db
+            .prepare("SELECT id FROM agent_executions WHERE result IS NULL AND started_at < ?")
+            .all(beforeTs);
+        if (rows.length === 0)
+            return [];
+        db.prepare(`UPDATE agent_executions
+          SET result = 'error', error_kind = 'crash', ended_at = ?
+        WHERE result IS NULL AND started_at < ?`).run(now, beforeTs);
+        return rows.map((r) => r.id);
+    });
+    const ids = sweep();
+    return { count: ids.length, ids };
+}
+// ── Reads ────────────────────────────────────────────────────────────
+export function getExecution(db, id) {
+    const row = db
+        .prepare("SELECT * FROM agent_executions WHERE id = ?")
+        .get(id);
+    return row ? rowToDTO(row) : null;
+}
+/**
+ * Paginated execution history for one Agent, newest first (§9.3). `before` is
+ * a keyset cursor on `id`; `result` filters by terminal state.
+ */
+export function listExecutions(db, agentId, opts = {}) {
+    const limit = opts.limit ?? 25;
+    const where = ["agent_id = ?"];
+    const params = [agentId];
+    if (opts.before !== undefined) {
+        where.push("id < ?");
+        params.push(opts.before);
+    }
+    if (opts.result !== undefined) {
+        where.push("result = ?");
+        params.push(opts.result);
+    }
+    const rows = db
+        .prepare(`SELECT * FROM agent_executions
+        WHERE ${where.join(" AND ")}
+        ORDER BY id DESC
+        LIMIT ?`)
+        .all(...params, limit);
+    return rows.map(rowToDTO);
+}
+/** Nearest-rank p95 over a non-empty ascending-sortable sample. */
+function p95(samples) {
+    if (samples.length === 0)
+        return null;
+    const sorted = [...samples].sort((a, b) => a - b);
+    const rank = Math.ceil(0.95 * sorted.length);
+    return sorted[rank - 1];
+}
+/**
+ * Rollup metrics over the trailing `days` window (§9.1 / §9.2). All derived
+ * fields are computed in JS over a single `(agent_id, started_at DESC)` index
+ * scan so the math (error_rate, avg_cost, criteria_hit_rate, p95) stays
+ * unit-testable without SQL fixtures.
+ */
+export function metricsWindow(db, agentId, days, now = Date.now()) {
+    const cutoff = now - days * DAY_MS;
+    const rows = db
+        .prepare(`SELECT result, error_kind, cost_usd, started_at, ended_at, success_criteria_json
+         FROM agent_executions
+        WHERE agent_id = ? AND started_at >= ?`)
+        .all(agentId, cutoff);
+    let terminal = 0;
+    let errors = 0;
+    let costSum = 0;
+    let costCount = 0;
+    let criteriaTrue = 0;
+    let criteriaTotal = 0;
+    const durations = [];
+    for (const row of rows) {
+        if (row.result !== null) {
+            terminal += 1;
+            if (row.result === "error")
+                errors += 1;
+        }
+        if (row.cost_usd !== null) {
+            costSum += row.cost_usd;
+            costCount += 1;
+        }
+        // Exclude crash-swept rows: their ended_at is the boot instant, not the
+        // real runtime, and would inflate the percentile (see p95DurationSeconds).
+        if (row.ended_at !== null && row.error_kind !== "crash") {
+            durations.push((row.ended_at - row.started_at) / 1000);
+        }
+        const criteria = parseSuccessCriteria(row.success_criteria_json);
+        if (criteria !== null) {
+            for (const hit of Object.values(criteria)) {
+                criteriaTotal += 1;
+                if (hit)
+                    criteriaTrue += 1;
+            }
+        }
+    }
+    return {
+        executions: rows.length,
+        errorRate: terminal === 0 ? 0 : errors / terminal,
+        avgCostUsd: costCount === 0 ? null : costSum / costCount,
+        criteriaHitRate: criteriaTotal === 0 ? null : criteriaTrue / criteriaTotal,
+        p95DurationSeconds: p95(durations),
+    };
+}
+/**
+ * Count of error executions grouped by `error_kind` over the trailing `days`
+ * window (§9.2 `by_error_kind_7d`). A NULL `error_kind` is bucketed as
+ * `"unknown"`.
+ */
+export function byErrorKind(db, agentId, days, now = Date.now()) {
+    const cutoff = now - days * DAY_MS;
+    const rows = db
+        .prepare(`SELECT COALESCE(error_kind, 'unknown') AS kind, COUNT(*) AS n
+         FROM agent_executions
+        WHERE agent_id = ? AND started_at >= ? AND result = 'error'
+        GROUP BY COALESCE(error_kind, 'unknown')`)
+        .all(agentId, cutoff);
+    const out = {};
+    for (const row of rows)
+        out[row.kind] = row.n;
+    return out;
+}

package/dist/db/agents-store.d.ts

@@ -0,0 +1,179 @@
+import type Database from "better-sqlite3";
+import type { AgentKind, ScheduleKind, StopWarning } from "@aitne/shared";
+/**
+ * Agents store — durable identity layer for the Agent Definitions feature
+ * (AGENT_DEFINITIONS_DESIGN.md §5.1). One `agents` row per built-in routine
+ * and per user-authored recurring task. This module is the only place that
+ * reads/writes the `agents` table; the loader (§6), the `/api/agents` routes
+ * (§9), and the scheduler enabled-gate (§7) all go through it.
+ *
+ * Design notes encoded here:
+ *
+ *   - **Timestamps are epoch-millisecond integers**, not ISO strings. The
+ *     store is the sole writer and always supplies an explicit value, so the
+ *     loader's §6.4 override resolution can compare `enabledOverriddenAt`
+ *     directly against an `fs.stat().mtimeMs` with no coercion.
+ *   - **`upsertAgent` is a pure column writer.** All policy — enabled-override
+ *     resolution, override-snapshot merge, hash-change version bump — lives in
+ *     the loader (Phase 5), which composes the final values and hands them to
+ *     `upsertAgent`. On conflict the upsert preserves `created_at` and
+ *     `last_execution_id` (those are owned by insert-time and the recorder
+ *     respectively); the dedicated `setEnabled` / `setLastExecutionId` /
+ *     `setOverrideSnapshot` mutators own their narrow slices.
+ *   - **`process_key` is nullable**: the two no-LLM in-process passes
+ *     (roadmap-maintenance, context-index-reconcile) have no routing key.
+ */
+/** `source` column vocabulary — identical to the YAML `kind` discriminator. */
+export type AgentSource = AgentKind;
+/**
+ * Structured shape of the `metadata_json` blob (§5.1). Carries everything not
+ * worth a dedicated column. The index signature keeps forward-compatibility
+ * with reserved future fields without forcing a schema change.
+ */
+export interface AgentMetadata {
+    /** Bumped by the loader on every `definition_hash` change (§6.3). */
+    version_counter?: number;
+    /** Set on the invalid-definition path (§6.6); presence == "invalid". */
+    last_error?: string;
+    /** Built-in field-level edits that must survive `npm i -g` (§6.4.1). */
+    override_snapshot?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** Raw row as stored in SQLite (snake_case, JSON columns unparsed). */
+export interface AgentRow {
+    id: string;
+    name: string;
+    description: string | null;
+    source: AgentSource;
+    definition_path: string;
+    definition_hash: string;
+    enabled: number;
+    enabled_overridden_at: number | null;
+    process_key: string | null;
+    schedule_kind: ScheduleKind;
+    schedule_expression: string | null;
+    schedule_timezone: string;
+    tags_json: string;
+    stop_warning_json: string | null;
+    recurring_schedule_id: number | null;
+    last_execution_id: number | null;
+    metadata_json: string;
+    created_at: number;
+    updated_at: number;
+}
+/** Parsed, camelCase view returned to callers. */
+export interface AgentDTO {
+    slug: string;
+    name: string;
+    description: string | null;
+    source: AgentSource;
+    definitionPath: string;
+    definitionHash: string;
+    enabled: boolean;
+    enabledOverriddenAt: number | null;
+    processKey: string | null;
+    scheduleKind: ScheduleKind;
+    scheduleExpression: string | null;
+    scheduleTimezone: string;
+    tags: string[];
+    stopWarning: StopWarning | null;
+    recurringScheduleId: number | null;
+    lastExecutionId: number | null;
+    metadata: AgentMetadata;
+    /** True when `metadata.last_error` is set (parse-failure row, §6.6). */
+    invalid: boolean;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Everything the loader resolves before persisting a row. The shared
+ * `AgentDefinition` is decomposed into columns here plus the loader-only
+ * fields (`definitionPath`, `definitionHash`, resolved `scheduleTimezone`,
+ * `recurringScheduleId`, post-override `enabled`, `metadata`). `upsertAgent`
+ * writes exactly these — it computes nothing.
+ */
+export interface AgentUpsertInput {
+    slug: string;
+    name: string;
+    description?: string | null;
+    source: AgentSource;
+    definitionPath: string;
+    definitionHash: string;
+    enabled: boolean;
+    enabledOverriddenAt?: number | null;
+    processKey?: string | null;
+    scheduleKind: ScheduleKind;
+    scheduleExpression?: string | null;
+    scheduleTimezone: string;
+    tags?: string[];
+    stopWarning?: StopWarning | null;
+    recurringScheduleId?: number | null;
+    metadata?: AgentMetadata;
+}
+export interface AgentListFilter {
+    source?: AgentSource;
+    enabled?: boolean;
+    /**
+     * When `false`, parse-failure rows (`metadata.last_error` set) are excluded.
+     * Omitted / `true` returns every row. The `/api/agents` route applies the
+     * product default (false) on top of this; the store stays a faithful data
+     * layer that returns everything unless asked to filter.
+     */
+    includeInvalid?: boolean;
+}
+export declare function getAgent(db: Database.Database, slug: string): AgentDTO | null;
+export declare function listAgents(db: Database.Database, filter?: AgentListFilter): AgentDTO[];
+/**
+ * Insert or update an Agent identity row by slug. On conflict, `created_at`
+ * and `last_execution_id` are preserved (not in the DO UPDATE set); every
+ * other column is overwritten from `input`. Returns the resulting DTO.
+ */
+export declare function upsertAgent(db: Database.Database, input: AgentUpsertInput, now?: number): AgentDTO;
+/**
+ * Toggle the enabled flag and stamp `enabled_overridden_at` (the dashboard
+ * PATCH path, §6.4 / §9.5). Pass `overriddenAt = now` for an operator toggle;
+ * the loader never calls this (it writes enabled via `upsertAgent`). Returns
+ * the updated DTO, or `null` when no row matches the slug.
+ */
+export declare function setEnabled(db: Database.Database, slug: string, enabled: boolean, overriddenAt: number | null, now?: number): AgentDTO | null;
+/**
+ * Point `last_execution_id` at a freshly-recorded execution (the recorder
+ * runs this inside the same transaction as `completeExecution`, §8.2).
+ * `null` clears the pointer. Returns true when a row was updated.
+ */
+export declare function setLastExecutionId(db: Database.Database, slug: string, executionId: number | null, now?: number): boolean;
+/**
+ * Defensive cleanup for any row that still carries `schedule_kind='one_shot'`.
+ *
+ * As of the scheduling split, `/agents` is recurring-only — the loader rejects
+ * a user one_shot definition outright, so no NEW one_shot Agents are created.
+ * This guard is retained because a legacy/pre-split DB row (or a manual edit)
+ * could still be `one_shot`: when such a row fires, disable it (so it stays as a
+ * re-runnable record the operator can re-fire via run-now) and skip any other
+ * still-pending firing for it (defends against a run-now + scheduled pair, or a
+ * stale row, double-firing). No-op for cron / event Agents — they keep their
+ * materialised pending rows. Returns true only when this call disabled a
+ * still-enabled one_shot Agent. Called unconditionally by the execution
+ * recorder; the `schedule_kind !== 'one_shot'` guard makes it a cheap no-op for
+ * the now-universal cron case.
+ */
+export declare function disableOneShotAfterFire(db: Database.Database, slug: string, now?: number): boolean;
+/**
+ * Delete an Agent row. The FK on `agent_executions.agent_id` cascades, so the
+ * Agent's execution history is removed too (the `/api/agents` DELETE handler's
+ * `keep_history` path stops short of this and disables instead — §9.6).
+ * Returns true when a row was removed.
+ */
+export declare function deleteAgent(db: Database.Database, slug: string): boolean;
+/**
+ * Read the built-in override snapshot. Returns `{}` when the Agent is missing
+ * or carries no snapshot, so callers can treat the result uniformly.
+ */
+export declare function getOverrideSnapshot(db: Database.Database, slug: string): Record<string, unknown>;
+/**
+ * Replace the override snapshot, preserving every other `metadata_json` key.
+ * An empty snapshot removes the `override_snapshot` key entirely (so a fully
+ * reset Agent's metadata is clean). Returns the updated DTO, or `null` when no
+ * row matches.
+ */
+export declare function setOverrideSnapshot(db: Database.Database, slug: string, snapshot: Record<string, unknown>, now?: number): AgentDTO | null;