@aitne/daemon 0.1.8 → 0.1.10

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;

package/dist/db/agents-store.js

@@ -0,0 +1,264 @@
+// ── JSON parsing (defensive — store is the writer, but never trust bytes) ──
+function parseTags(json) {
+    try {
+        const parsed = JSON.parse(json);
+        if (Array.isArray(parsed)) {
+            return parsed.filter((v) => typeof v === "string");
+        }
+    }
+    catch {
+        /* fall through to [] */
+    }
+    return [];
+}
+function parseStopWarning(json) {
+    if (json === null)
+        return null;
+    try {
+        const parsed = JSON.parse(json);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        /* fall through to null */
+    }
+    return null;
+}
+function parseMetadata(json) {
+    try {
+        const parsed = JSON.parse(json);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        /* fall through to {} */
+    }
+    return {};
+}
+function rowToDTO(row) {
+    const metadata = parseMetadata(row.metadata_json);
+    // Read into a local first: the redaction static guard
+    // (scripts/check-redaction-coverage.mjs) flags the auth-health JSON key name
+    // whenever it is immediately followed by an equals sign anywhere under
+    // daemon/src, to force the `backends` auth-detail column through its
+    // redaction helper. The metadata key read just below is an unrelated
+    // Agent-definition parse error (§6.6), never a secret — so we dodge the
+    // textual pattern by comparing the camelCase local rather than exempting the
+    // whole file. Do NOT inline this back into the comparison.
+    const lastError = metadata.last_error;
+    return {
+        slug: row.id,
+        name: row.name,
+        description: row.description,
+        source: row.source,
+        definitionPath: row.definition_path,
+        definitionHash: row.definition_hash,
+        enabled: row.enabled === 1,
+        enabledOverriddenAt: row.enabled_overridden_at,
+        processKey: row.process_key,
+        scheduleKind: row.schedule_kind,
+        scheduleExpression: row.schedule_expression,
+        scheduleTimezone: row.schedule_timezone,
+        tags: parseTags(row.tags_json),
+        stopWarning: parseStopWarning(row.stop_warning_json),
+        recurringScheduleId: row.recurring_schedule_id,
+        lastExecutionId: row.last_execution_id,
+        metadata,
+        invalid: typeof lastError === "string" && lastError.length > 0,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+// ── Reads ────────────────────────────────────────────────────────────
+export function getAgent(db, slug) {
+    const row = db
+        .prepare("SELECT * FROM agents WHERE id = ?")
+        .get(slug);
+    return row ? rowToDTO(row) : null;
+}
+export function listAgents(db, filter = {}) {
+    const where = [];
+    const params = [];
+    if (filter.source !== undefined) {
+        where.push("source = ?");
+        params.push(filter.source);
+    }
+    if (filter.enabled !== undefined) {
+        where.push("enabled = ?");
+        params.push(filter.enabled ? 1 : 0);
+    }
+    if (filter.includeInvalid === false) {
+        // metadata_json is always valid JSON written by this store (default '{}'),
+        // so json_extract is safe. An absent key returns NULL → the row is kept.
+        where.push("json_extract(metadata_json, '$.last_error') IS NULL");
+    }
+    const sql = "SELECT * FROM agents"
+        + (where.length ? ` WHERE ${where.join(" AND ")}` : "")
+        + " ORDER BY source ASC, id ASC";
+    const rows = db.prepare(sql).all(...params);
+    return rows.map(rowToDTO);
+}
+// ── Writes ───────────────────────────────────────────────────────────
+/**
+ * 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 function upsertAgent(db, input, now = Date.now()) {
+    db.prepare(`INSERT INTO agents (
+        id, name, description, source, definition_path, definition_hash,
+        enabled, enabled_overridden_at, process_key, schedule_kind,
+        schedule_expression, schedule_timezone, tags_json, stop_warning_json,
+        recurring_schedule_id, metadata_json, created_at, updated_at
+     ) VALUES (
+        @id, @name, @description, @source, @definition_path, @definition_hash,
+        @enabled, @enabled_overridden_at, @process_key, @schedule_kind,
+        @schedule_expression, @schedule_timezone, @tags_json, @stop_warning_json,
+        @recurring_schedule_id, @metadata_json, @created_at, @updated_at
+     )
+     ON CONFLICT(id) DO UPDATE SET
+        name = excluded.name,
+        description = excluded.description,
+        source = excluded.source,
+        definition_path = excluded.definition_path,
+        definition_hash = excluded.definition_hash,
+        enabled = excluded.enabled,
+        enabled_overridden_at = excluded.enabled_overridden_at,
+        process_key = excluded.process_key,
+        schedule_kind = excluded.schedule_kind,
+        schedule_expression = excluded.schedule_expression,
+        schedule_timezone = excluded.schedule_timezone,
+        tags_json = excluded.tags_json,
+        stop_warning_json = excluded.stop_warning_json,
+        recurring_schedule_id = excluded.recurring_schedule_id,
+        metadata_json = excluded.metadata_json,
+        updated_at = excluded.updated_at`).run({
+        id: input.slug,
+        name: input.name,
+        description: input.description ?? null,
+        source: input.source,
+        definition_path: input.definitionPath,
+        definition_hash: input.definitionHash,
+        enabled: input.enabled ? 1 : 0,
+        enabled_overridden_at: input.enabledOverriddenAt ?? null,
+        process_key: input.processKey ?? null,
+        schedule_kind: input.scheduleKind,
+        schedule_expression: input.scheduleExpression ?? null,
+        schedule_timezone: input.scheduleTimezone,
+        tags_json: JSON.stringify(input.tags ?? []),
+        stop_warning_json: input.stopWarning != null ? JSON.stringify(input.stopWarning) : null,
+        recurring_schedule_id: input.recurringScheduleId ?? null,
+        metadata_json: JSON.stringify(input.metadata ?? {}),
+        created_at: now,
+        updated_at: now,
+    });
+    // Non-null: the row was just inserted/updated under this id.
+    return getAgent(db, input.slug);
+}
+/**
+ * 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 function setEnabled(db, slug, enabled, overriddenAt, now = Date.now()) {
+    const result = db
+        .prepare(`UPDATE agents
+          SET enabled = ?, enabled_overridden_at = ?, updated_at = ?
+        WHERE id = ?`)
+        .run(enabled ? 1 : 0, overriddenAt, now, slug);
+    if (result.changes === 0)
+        return null;
+    return getAgent(db, slug);
+}
+/**
+ * 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 function setLastExecutionId(db, slug, executionId, now = Date.now()) {
+    const result = db
+        .prepare(`UPDATE agents SET last_execution_id = ?, updated_at = ? WHERE id = ?`)
+        .run(executionId, now, slug);
+    return result.changes > 0;
+}
+// ── One-shot Agent lifecycle (legacy / defensive) ──────────────────────────
+/**
+ * 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 function disableOneShotAfterFire(db, slug, now = Date.now()) {
+    const row = db
+        .prepare("SELECT schedule_kind AS schedule_kind, enabled AS enabled FROM agents WHERE id = ?")
+        .get(slug);
+    if (!row || row.schedule_kind !== "one_shot")
+        return false;
+    // Cancel sibling pending fires so a double-booked one_shot can't fire twice
+    // once one run has settled — independent of the enabled flip below.
+    db.prepare(`UPDATE agent_schedule SET status = 'skipped'
+       WHERE json_extract(task_context, '$.agent_id') = ? AND status = 'pending'`).run(slug);
+    if (row.enabled === 0)
+        return false;
+    db.prepare(`UPDATE agents
+        SET enabled = 0, enabled_overridden_at = ?, updated_at = ?
+      WHERE id = ? AND enabled = 1`).run(now, now, slug);
+    return true;
+}
+/**
+ * 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 function deleteAgent(db, slug) {
+    const result = db.prepare("DELETE FROM agents WHERE id = ?").run(slug);
+    return result.changes > 0;
+}
+// ── Override snapshot (§6.4.1 — built-in edits that survive npm upgrade) ──
+/**
+ * Read the built-in override snapshot. Returns `{}` when the Agent is missing
+ * or carries no snapshot, so callers can treat the result uniformly.
+ */
+export function getOverrideSnapshot(db, slug) {
+    const row = db
+        .prepare("SELECT metadata_json FROM agents WHERE id = ?")
+        .get(slug);
+    if (!row)
+        return {};
+    return parseMetadata(row.metadata_json).override_snapshot ?? {};
+}
+/**
+ * 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 function setOverrideSnapshot(db, slug, snapshot, now = Date.now()) {
+    const row = db
+        .prepare("SELECT metadata_json FROM agents WHERE id = ?")
+        .get(slug);
+    if (!row)
+        return null;
+    const metadata = parseMetadata(row.metadata_json);
+    if (Object.keys(snapshot).length === 0) {
+        delete metadata.override_snapshot;
+    }
+    else {
+        metadata.override_snapshot = snapshot;
+    }
+    db.prepare("UPDATE agents SET metadata_json = ?, updated_at = ? WHERE id = ?").run(JSON.stringify(metadata), now, slug);
+    return getAgent(db, slug);
+}

package/dist/db/automation-triggers.d.ts

@@ -87,4 +87,3 @@ export declare function getCatalog(domain: TriggerDomain): {
     events: CatalogEvent[];
 };
 export type { RecurringScheduleDTO };
-//# sourceMappingURL=automation-triggers.d.ts.map

package/dist/db/automation-triggers.js

@@ -196,4 +196,3 @@ export function getCatalog(domain) {
     }
     return { domain, events: [] };
 }
-//# sourceMappingURL=automation-triggers.js.map