@aitne/daemon 0.1.8 → 0.1.10

package/dist/api/routes/agents/index.js

@@ -0,0 +1,404 @@
+import { Hono } from "hono";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { formatSqliteDatetime } from "@aitne/shared";
+import { createLogger } from "../../../logging.js";
+import { readJsonBody } from "../../json-body.js";
+import { deleteAgent, getAgent, getOverrideSnapshot, listAgents, setEnabled, setOverrideSnapshot, } from "../../../db/agents-store.js";
+import { byErrorKind, getExecution, listExecutions, metricsWindow, } from "../../../db/agent-executions-store.js";
+import { deleteRecurringSchedule, getRecurringSchedule, updateRecurringSchedule, } from "../../../db/recurring-schedules.js";
+import { loadEffectiveDefinition } from "../../../core/agents/effective-definition.js";
+import { loadAgents } from "../../../core/agents/loader.js";
+import { buildAgentLoadOptions } from "../../../core/agents/loader-boot.js";
+import { resolveRuntimeWindowCadence } from "../../../core/agents/builtin-registry.js";
+import { buildDetail, buildListItem, buildRow, planCreate, planPatch, planRunNow, serializeExecution, } from "./views.js";
+/**
+ * `/api/agents/*` route surface (AGENT_DEFINITIONS_DESIGN.md §9). Thin Hono
+ * glue over the `agents` / `agent_executions` stores + the pure view/plan
+ * helpers in `views.ts` and the effective-definition composer. Auto-excluded
+ * from the coverage gate as an `index.ts` barrel-style entry — the JSON shapes,
+ * the run-now / patch planners, and the definition composition all live in the
+ * peer-tested pure modules; this file is the I/O orchestration around them and
+ * is pinned by the behavioural `agents.test.ts`.
+ */
+const logger = createLogger("agents-api");
+/** Per-Agent 7d-metrics cache (§9.1 — "cached in-memory for 60 seconds"). */
+const METRICS_TTL_MS = 60_000;
+const EXECUTION_RESULTS = new Set([
+    "success",
+    "error",
+    "skipped",
+    "timeout",
+]);
+export function createAgentDefinitionRoutes(deps) {
+    const app = new Hono();
+    const { db, config } = deps;
+    const dayBoundaryHour = config.dayBoundaryHour;
+    // Live interval cadence for a runtime-window built-in (hourly-check), or null
+    // for every other Agent. Reads `config` at call time — `applyConfigUpdates`
+    // mutates it in place (Object.assign), so a runtime interval/active-hours
+    // change via PATCH /api/config is reflected here without a daemon restart.
+    const cadenceFor = (slug) => resolveRuntimeWindowCadence(slug, {
+        hourlyCheckIntervalMinutes: config.hourlyCheckIntervalMinutes,
+        hourlyCheckActiveStartHour: config.hourlyCheckActiveStartHour,
+        hourlyCheckActiveEndHour: config.hourlyCheckActiveEndHour,
+    });
+    const readDefinitionFile = (path) => {
+        try {
+            return existsSync(path) ? readFileSync(path, "utf-8") : null;
+        }
+        catch (err) {
+            logger.warn({ err, path }, "Failed to read agent definition file");
+            return null;
+        }
+    };
+    const metricsCache = new Map();
+    const metrics7dCached = (slug) => {
+        const now = Date.now();
+        const hit = metricsCache.get(slug);
+        if (hit && now - hit.at < METRICS_TTL_MS)
+            return hit.value;
+        const value = metricsWindow(db, slug, 7);
+        metricsCache.set(slug, { at: now, value });
+        return value;
+    };
+    const emit = (kind, payload) => {
+        deps.eventBroadcaster?.broadcastEvent({ kind, ...payload });
+    };
+    const recordAudit = (actionType, slug, detail) => {
+        try {
+            db.prepare(`INSERT INTO agent_actions (action_type, trigger, result, detail, agent_id, started_at, completed_at)
+         VALUES (?, 'api', 'success', json(?), ?, datetime('now'), datetime('now'))`).run(actionType, JSON.stringify({ slug, ...detail }), slug);
+        }
+        catch (err) {
+            logger.warn({ err, slug, actionType }, "Failed to record agent config-change audit row");
+        }
+    };
+    // ── GET /agents (§9.1) ──────────────────────────────────────────────────
+    app.get("/agents", (c) => {
+        const filter = { includeInvalid: false };
+        const source = c.req.query("source");
+        if (source === "builtin" || source === "user")
+            filter.source = source;
+        const enabled = c.req.query("enabled");
+        if (enabled === "true")
+            filter.enabled = true;
+        else if (enabled === "false")
+            filter.enabled = false;
+        if (c.req.query("include_invalid") === "true")
+            filter.includeInvalid = true;
+        const agents = listAgents(db, filter).map((dto) => {
+            const lastExecution = dto.lastExecutionId !== null ? getExecution(db, dto.lastExecutionId) : null;
+            return buildListItem(dto, {
+                metrics7d: metrics7dCached(dto.slug),
+                lastExecution,
+                intervalCadence: cadenceFor(dto.slug),
+            });
+        });
+        return c.json({ agents });
+    });
+    // ── POST /agents — create a recurring user Agent ────────────────────────
+    // The programmatic counterpart to the dashboard's "+ New Agent" form. The
+    // pure `planCreate` assembles + validates the agent.md (recurring-only — a
+    // one_shot schedule is rejected with a pointer to POST /api/schedule); the
+    // route writes the file to the user agents root then synchronously reloads so
+    // the row + paired recurring_schedules row exist before the 201 (the file
+    // watcher also fires later, an idempotent no-op).
+    app.post("/agents", async (c) => {
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        if (typeof parsedBody.body !== "object" ||
+            parsedBody.body === null ||
+            Array.isArray(parsedBody.body)) {
+            return c.json({ error: "invalid_body", message: "body must be a JSON object" }, 400);
+        }
+        const body = parsedBody.body;
+        const existingSlugs = new Set(listAgents(db, { includeInvalid: true }).map((a) => a.slug));
+        const plan = planCreate(body, existingSlugs);
+        if (!plan.ok) {
+            if (plan.status === 409) {
+                return c.json({ error: plan.error, slug: plan.slug }, 409);
+            }
+            return c.json({
+                error: plan.error,
+                ...(plan.hint ? { hint: plan.hint } : {}),
+                ...(plan.field ? { field: plan.field } : {}),
+                ...(plan.issues ? { issues: plan.issues } : {}),
+            }, 400);
+        }
+        const opts = buildAgentLoadOptions({
+            db,
+            config,
+            ...(deps.eventBroadcaster ? { eventBroadcaster: deps.eventBroadcaster } : {}),
+        });
+        const dir = join(opts.userDir, plan.slug);
+        try {
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(join(dir, "agent.md"), plan.markdown, "utf-8");
+        }
+        catch (err) {
+            logger.error({ err, slug: plan.slug, dir }, "Failed to write agent.md");
+            return c.json({ error: "agent_write_failed", slug: plan.slug }, 500);
+        }
+        // Synchronous load pairs the recurring row + upserts the agents row. The
+        // loader runs the FULL cross-check (e.g. tools.allowed vs the absolute-block
+        // layer) the schema can't express; if it flags the fresh file invalid, undo
+        // the write so a bad create leaves no junk.
+        loadAgents(db, opts);
+        const dto = getAgent(db, plan.slug);
+        if (!dto || dto.invalid) {
+            const detail = dto?.metadata.last_error ?? null;
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch (err) {
+                logger.warn({ err, slug: plan.slug, dir }, "Failed to clean up invalid agent dir");
+            }
+            if (dto)
+                deleteAgent(db, plan.slug);
+            deps.agentEnabledCache?.invalidate();
+            return c.json({ error: "invalid_definition", slug: plan.slug, detail }, 400);
+        }
+        deps.agentEnabledCache?.invalidate();
+        emit("agent.updated", { slug: plan.slug, source: "user" });
+        recordAudit("agent.created", plan.slug, { source: "user" });
+        logger.info({ slug: plan.slug }, "Agent created via POST /api/agents");
+        return c.json({ status: "created", slug: plan.slug }, 201);
+    });
+    // ── GET /agents/:slug (§9.2) ────────────────────────────────────────────
+    app.get("/agents/:slug", (c) => {
+        const slug = c.req.param("slug");
+        const dto = getAgent(db, slug);
+        if (!dto)
+            return c.json({ error: "agent_not_found", slug }, 404);
+        const effective = loadEffectiveDefinition(dto, {
+            readFile: readDefinitionFile,
+            dayBoundaryHour,
+        });
+        const detail = buildDetail({
+            dto,
+            definition: effective.definition,
+            definitionYaml: effective.yaml,
+            recentExecutions: listExecutions(db, slug, { limit: 25 }),
+            metrics7d: metricsWindow(db, slug, 7),
+            metrics30d: metricsWindow(db, slug, 30),
+            byErrorKind7d: byErrorKind(db, slug, 7),
+            intervalCadence: cadenceFor(slug),
+        });
+        return c.json(detail);
+    });
+    // ── GET /agents/:slug/executions (§9.3) ─────────────────────────────────
+    app.get("/agents/:slug/executions", (c) => {
+        const slug = c.req.param("slug");
+        if (!getAgent(db, slug))
+            return c.json({ error: "agent_not_found", slug }, 404);
+        const limitRaw = Number.parseInt(c.req.query("limit") ?? "25", 10);
+        const limit = Number.isFinite(limitRaw) && limitRaw > 0 ? Math.min(limitRaw, 200) : 25;
+        const opts = { limit };
+        const beforeRaw = c.req.query("before");
+        if (beforeRaw !== undefined) {
+            const before = Number.parseInt(beforeRaw, 10);
+            if (Number.isFinite(before) && before > 0)
+                opts.before = before;
+        }
+        const result = c.req.query("result");
+        if (result !== undefined && EXECUTION_RESULTS.has(result)) {
+            opts.result = result;
+        }
+        const executions = listExecutions(db, slug, opts).map(serializeExecution);
+        return c.json({ slug, limit, executions });
+    });
+    // ── POST /agents/:slug/run-now (§9.4) ───────────────────────────────────
+    app.post("/agents/:slug/run-now", async (c) => {
+        const slug = c.req.param("slug");
+        const dto = getAgent(db, slug);
+        if (!dto)
+            return c.json({ error: "agent_not_found", slug }, 404);
+        // User Agents carry their recurring row's prompt AND routing pins
+        // (backend_id / model / tier_override) so the manual run does the real task
+        // on the same backend a cron fire would use — `generateNextScheduleRow`
+        // copies the identical fields off this row. Built-ins drive the prompt from
+        // the routine / process key and resolve their backend there, so these stay
+        // null.
+        let taskPrompt = null;
+        let pinnedBackendId = null;
+        let pinnedModel = null;
+        let pinnedTier = null;
+        if (dto.source === "user" && dto.recurringScheduleId !== null) {
+            const recurring = getRecurringSchedule(db, dto.recurringScheduleId);
+            taskPrompt = recurring?.prompt ?? null;
+            pinnedBackendId = recurring?.backendId ?? null;
+            pinnedModel = recurring?.model ?? null;
+            pinnedTier = recurring?.tier ?? null;
+        }
+        // §9.4 optional `trigger_note`. Tolerant of an empty/absent/malformed body
+        // (the dashboard posts no body) — a missing note never 400s, it just stays
+        // undefined; only a string value is honoured.
+        const parsedBody = await readJsonBody(c);
+        const note = parsedBody.ok
+            && typeof parsedBody.body === "object"
+            && parsedBody.body !== null
+            && !Array.isArray(parsedBody.body)
+            && typeof parsedBody.body.trigger_note === "string"
+            ? parsedBody.body.trigger_note
+            : undefined;
+        const plan = planRunNow(dto, {
+            taskPrompt,
+            ...(note !== undefined ? { triggerNote: note } : {}),
+            backendId: pinnedBackendId,
+            model: pinnedModel,
+            tier: pinnedTier,
+        });
+        if (!plan.ok) {
+            return c.json({ error: plan.error, hint: plan.hint }, plan.status);
+        }
+        // System Agents: DM the owner before enqueueing (§9.4 Notify convention).
+        if (plan.emitDm && deps.sendNotification) {
+            try {
+                await deps.sendNotification({
+                    message: `Manually triggered ${slug} at ${new Date().toISOString()}`,
+                    priority: "normal",
+                    notificationType: "agent",
+                });
+            }
+            catch (err) {
+                logger.warn({ err, slug }, "run-now owner DM failed (continuing to enqueue)");
+            }
+        }
+        const insert = db
+            .prepare(`INSERT INTO agent_schedule
+           (scheduled_for, task_type, task_description, task_prompt, task_context, model, tier_override, backend_id, status)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'pending')`)
+            .run(formatSqliteDatetime(new Date()), plan.taskType, plan.taskDescription, 
+        // System agents drive their body from the routine/process key and
+        // leave taskPrompt null; the dispatcher reads task_prompt directly
+        // (no task_description fallback), so coalesce to the description body.
+        plan.taskPrompt ?? plan.taskDescription, JSON.stringify(plan.taskContext), plan.model, plan.tier, plan.backendId);
+        const scheduleRowId = Number(insert.lastInsertRowid);
+        recordAudit("agent.run_now", slug, {
+            scheduleRowId,
+            source: dto.source,
+            ...(note !== undefined ? { trigger_note: note } : {}),
+        });
+        logger.info({ slug, scheduleRowId, source: dto.source }, "Agent run-now enqueued");
+        // The `agent_executions` row is opened by the dispatcher when it fires the
+        // queued schedule row (§8.1), so no execution id exists yet at enqueue time.
+        return c.json({ status: "queued", schedule_row_id: scheduleRowId, execution_id: null }, 202);
+    });
+    // ── PATCH /agents/:slug (§9.5) ──────────────────────────────────────────
+    app.patch("/agents/:slug", async (c) => {
+        const slug = c.req.param("slug");
+        const dto = getAgent(db, slug);
+        if (!dto)
+            return c.json({ error: "agent_not_found", slug }, 404);
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        if (typeof parsedBody.body !== "object" || parsedBody.body === null || Array.isArray(parsedBody.body)) {
+            return c.json({ error: "invalid_body", message: "body must be a JSON object" }, 400);
+        }
+        const body = parsedBody.body;
+        const plan = planPatch(dto, body);
+        if (!plan.ok) {
+            if (plan.status === 409) {
+                return c.json({ error: plan.error, warning: plan.warning }, 409);
+            }
+            return c.json({ error: plan.error, ...(plan.hint ? { hint: plan.hint } : {}), ...(plan.field ? { field: plan.field } : {}) }, 400);
+        }
+        const now = Date.now();
+        if (plan.setEnabled !== undefined) {
+            setEnabled(db, slug, plan.setEnabled, now, now);
+            deps.agentEnabledCache?.invalidate();
+            emit("agent.enabled_changed", { slug, enabled: plan.setEnabled });
+            // Persist the stop-warning consent (§12.3): a built-in stop is gated on an
+            // explicit `ack_warning`, so record that ack in the audit detail — the
+            // audit trail should show the operator consented, not just that the flag
+            // flipped. (Reaching here for a built-in disable means the ack passed.)
+            recordAudit("agent.enabled_changed", slug, {
+                enabled: plan.setEnabled,
+                ...(plan.setEnabled === false && dto.source === "builtin"
+                    ? { ack_warning: body.ack_warning === true }
+                    : {}),
+            });
+        }
+        if (plan.mirrorRecurringEnabled !== undefined && dto.recurringScheduleId !== null) {
+            updateRecurringSchedule(db, dto.recurringScheduleId, { enabled: plan.mirrorRecurringEnabled });
+        }
+        if (Object.keys(plan.overrideSet).length > 0 || plan.overrideReset.length > 0) {
+            const snapshot = getOverrideSnapshot(db, slug);
+            for (const [path, value] of Object.entries(plan.overrideSet))
+                snapshot[path] = value;
+            for (const path of plan.overrideReset)
+                delete snapshot[path];
+            setOverrideSnapshot(db, slug, snapshot, now);
+            recordAudit("agent.override_changed", slug, {
+                set: Object.keys(plan.overrideSet),
+                reset: plan.overrideReset,
+            });
+        }
+        if (plan.stripped.length > 0) {
+            logger.info({ slug, stripped: plan.stripped }, "PATCH /agents stripped read-only fields");
+        }
+        emit("agent.updated", { slug, source: dto.source });
+        const updated = getAgent(db, slug);
+        return c.json({ status: "updated", row: buildRow(updated, cadenceFor(slug)), stripped: plan.stripped });
+    });
+    // ── DELETE /agents/:slug (§9.6) ─────────────────────────────────────────
+    app.delete("/agents/:slug", async (c) => {
+        const slug = c.req.param("slug");
+        const dto = getAgent(db, slug);
+        if (!dto)
+            return c.json({ error: "agent_not_found", slug }, 404);
+        if (dto.source === "builtin") {
+            return c.json({
+                error: "system_agent_undeletable",
+                warning: dto.stopWarning,
+                hint: "system Agents can be stopped but not deleted",
+            }, 409);
+        }
+        const rawBody = await c.req.json().catch(() => ({}));
+        const keepHistory = rawBody.keep_history !== false;
+        const now = Date.now();
+        if (keepHistory) {
+            // Disable (retain) the paired recurring row so the schedule stops firing
+            // but its definition + the Agent's execution history survive.
+            if (dto.recurringScheduleId !== null) {
+                updateRecurringSchedule(db, dto.recurringScheduleId, { enabled: false });
+            }
+            setEnabled(db, slug, false, now, now);
+            deps.agentEnabledCache?.invalidate();
+            emit("agent.enabled_changed", { slug, enabled: false });
+            recordAudit("agent.disabled", slug, { keepHistory: true });
+            return c.json({ status: "disabled", slug });
+        }
+        // Hard delete — remove the paired recurring row ENTIRELY (cancels its
+        // pending agent_schedule rows + clears the FK), not just disable it.
+        // Disabling alone leaves a row that no Agent references once we drop the
+        // `agents` row below, and the loader's first-boot auto-import (§6.5) re-
+        // creates that orphan as `imported-<id>/agent.md` on the next boot —
+        // resurrecting the Agent the operator just hard-deleted. Deleting the
+        // recurring row removes the orphan so the deletion is permanent.
+        if (dto.recurringScheduleId !== null) {
+            deleteRecurringSchedule(db, dto.recurringScheduleId);
+        }
+        // Snapshot the file, remove it, then drop the row (cascades executions).
+        // Best-effort fs ops never block the DB delete.
+        try {
+            if (existsSync(dto.definitionPath)) {
+                const content = readFileSync(dto.definitionPath, "utf-8");
+                db.prepare("INSERT INTO md_file_snapshots (file_path, content, trigger, session_id) VALUES (?, ?, 'agent_delete', NULL)").run(dto.definitionPath, content);
+                rmSync(dirname(dto.definitionPath), { recursive: true, force: true });
+            }
+        }
+        catch (err) {
+            logger.warn({ err, slug, path: dto.definitionPath }, "Failed to remove agent definition file");
+        }
+        deleteAgent(db, slug);
+        deps.agentEnabledCache?.invalidate();
+        emit("agent.updated", { slug, source: "user" });
+        recordAudit("agent.deleted", slug, { keepHistory: false });
+        return c.json({ status: "deleted", slug });
+    });
+    return app;
+}

package/dist/api/routes/agents/views.d.ts

@@ -0,0 +1,185 @@
+import type { AgentDefinition, StopWarning } from "@aitne/shared";
+import { OVERRIDE_EDIT_PATHS } from "@aitne/shared";
+import type { IntervalCadence } from "../../../core/agents/builtin-registry.js";
+import type { AgentDTO } from "../../../db/agents-store.js";
+import type { AgentExecutionDTO, AgentMetricsWindow } from "../../../db/agent-executions-store.js";
+/**
+ * Pure response shapers + mutation planners for the `/api/agents` routes
+ * (AGENT_DEFINITIONS_DESIGN.md §9). The Hono handlers in `index.ts` stay thin —
+ * fetch rows, call these, `c.json(...)`. Keeping the JSON-shape + validation
+ * logic here (no DB / fs / Hono) puts it in the 100%-coverage set; the route
+ * file is the I/O-shaped glue (auto-excluded as an `index.ts`).
+ */
+/** epoch-ms → ISO-8601, null-safe (execution timestamps are epoch-ms, §5.2). */
+export declare function epochToIso(ms: number | null): string | null;
+/** Full execution row for the detail / executions endpoints (§9.2 / §9.3). */
+export declare function serializeExecution(e: AgentExecutionDTO): Record<string, unknown>;
+/** Slim last-execution summary for the list view (§9.1). */
+export declare function serializeLastExecution(e: AgentExecutionDTO | null): Record<string, unknown> | null;
+/** Full metric window incl. p95 for the detail view (§9.2). */
+export declare function serializeMetricsWindow(w: AgentMetricsWindow): Record<string, unknown>;
+/** Compact metric window (no p95) for the list view (§9.1). */
+export declare function serializeListMetrics(w: AgentMetricsWindow): Record<string, unknown>;
+export interface ListItemInputs {
+    metrics7d: AgentMetricsWindow;
+    lastExecution: AgentExecutionDTO | null;
+    /**
+     * Live interval cadence for a runtime-window built-in (hourly-check), or
+     * `null` for fixed-cron / one-shot / event Agents. Resolved by the route from
+     * live config via `resolveRuntimeWindowCadence` so the schedule block carries
+     * the REAL cadence rather than the stored placeholder cron (§5.5.1).
+     */
+    intervalCadence?: IntervalCadence | null;
+}
+/** One row of `GET /api/agents` (§9.1). `kind` mirrors the stored `source`. */
+export declare function buildListItem(dto: AgentDTO, inputs: ListItemInputs): Record<string, unknown>;
+/**
+ * snake_case projection of the stored DB columns for the detail `row` block.
+ * `intervalCadence` (resolved by the route from live config) is surfaced as
+ * `schedule_interval` so the detail view renders the real runtime-window
+ * cadence; `null` for fixed-cron / one-shot / event Agents (§5.5.1).
+ */
+export declare function buildRow(dto: AgentDTO, intervalCadence?: IntervalCadence | null): Record<string, unknown>;
+export interface DetailInputs {
+    dto: AgentDTO;
+    definition: AgentDefinition | null;
+    definitionYaml: string | null;
+    recentExecutions: AgentExecutionDTO[];
+    metrics7d: AgentMetricsWindow;
+    metrics30d: AgentMetricsWindow;
+    byErrorKind7d: Record<string, number>;
+    /** Live runtime-window cadence for the detail `row.schedule_interval` (§5.5.1). */
+    intervalCadence?: IntervalCadence | null;
+}
+/** Full `GET /api/agents/:slug` envelope (§9.2). */
+export declare function buildDetail(inputs: DetailInputs): Record<string, unknown>;
+export type RunNowPlan = {
+    ok: false;
+    status: 409;
+    error: string;
+    hint: string;
+} | {
+    ok: true;
+    taskType: string;
+    taskDescription: string;
+    taskPrompt: string | null;
+    taskContext: Record<string, unknown>;
+    /**
+     * Routing pins copied from the user Agent's recurring row so a manual
+     * `run-now` routes identically to a cron fire (the scheduler resolves
+     * `backend_id`/`model`/`tier_override` the same way for both). Null for
+     * built-ins (they resolve from the process key) and for unpinned Agents.
+     */
+    backendId: string | null;
+    model: string | null;
+    tier: string | null;
+    /** True for built-in Agents — the handler DMs the owner before enqueue. */
+    emitDm: boolean;
+};
+/**
+ * Plan a manual run (§9.4): produce the `agent_schedule` insert payload. The
+ * owning Agent is stamped into `task_context.agent_id` (resolver step 1, §8.1)
+ * so the execution is attributed regardless of which dispatch flow runs;
+ * built-in routine Agents additionally carry `task_context.routine` (+ phase
+ * for the two sweeps) so the dispatcher's routine special-cases fire the real
+ * flow where it supports them.
+ *
+ * Rejects (409) the no-LLM in-process passes (`process_key: null`) — they fire
+ * via the scheduler's in-process callback, not the `agent_schedule` queue — and
+ * any row currently flagged invalid.
+ */
+export declare function planRunNow(dto: AgentDTO, opts?: {
+    taskPrompt?: string | null;
+    triggerNote?: string;
+    backendId?: string | null;
+    model?: string | null;
+    tier?: string | null;
+}): RunNowPlan;
+/** One field-level validation issue surfaced to the caller for self-correction. */
+export interface CreateIssue {
+    field: string;
+    message: string;
+}
+export type CreatePlan = {
+    ok: false;
+    status: 400;
+    error: string;
+    hint?: string;
+    field?: string;
+    issues?: CreateIssue[];
+} | {
+    ok: false;
+    status: 409;
+    error: "slug_collision";
+    slug: string;
+} | {
+    ok: true;
+    slug: string;
+    markdown: string;
+};
+/**
+ * Plan a `POST /api/agents` create from a structured JSON body — the
+ * programmatic counterpart to the dashboard's "+ New Agent" form (which writes
+ * the same `agent.md` via the context-vault PUT). Pure: assembles the
+ * frontmatter, validates it through `agentDefinitionSchema`, enforces the
+ * recurring-only contract, checks slug uniqueness, and renders the `agent.md`
+ * the route then writes. No DB / fs / Hono — fully unit-testable to 100%.
+ *
+ * `/agents` is recurring-only. The caller picks ONE of two schedule input forms:
+ *   - `{ kind: "cron", expression }` — a 5-field cron (incl. hourly `M * * * *`
+ *     / `M *​/N * * *`, now that the loader pairs those).
+ *   - `{ kind: "recurring", recurrence: <recurrenceRule> }` — the structured
+ *     frequency form (`hourly`/`daily`/`weekly`/`monthly` + its fields), the
+ *     clear path the dashboard + agent-create skill use. It is rendered to the
+ *     canonical cron here so the stored `agent.md` stays cron-based and
+ *     round-trips through the loader's recurring pairing.
+ * Any other `schedule.kind` (one_shot/event) is rejected with a pointer at the
+ * `/schedule` queue. `backend.process_key` defaults to `agent.task` (user
+ * recurring Agents always run an LLM turn) so the caller need not know the key.
+ */
+export declare function planCreate(body: Record<string, unknown>, existingSlugs: ReadonlySet<string>): CreatePlan;
+export { OVERRIDE_EDIT_PATHS };
+/**
+ * Parent block → its editable leaf keys (everything else under it is read-only).
+ * Derived structurally from the shared `OVERRIDE_EDIT_PATHS` so this PATCH edit
+ * gate — the fourth consumer of the allow-list — can never omit a path a future
+ * 7th entry adds. Same `{backend:{tier,model}, limits:{…}, on_error:{…}}` shape
+ * as before; pinned by a drift-guard test against `OVERRIDE_EDIT_PATHS`.
+ */
+export declare const EDITABLE_NESTED: Record<string, ReadonlySet<string>>;
+export type PatchPlan = {
+    ok: false;
+    status: 409;
+    error: "stop_warning_required";
+    warning: StopWarning | null;
+} | {
+    ok: false;
+    status: 400;
+    error: string;
+    hint?: string;
+    field?: string;
+} | {
+    ok: true;
+    /** undefined = no enabled change; otherwise the new `agents.enabled`. */
+    setEnabled?: boolean;
+    /** Built-in override-snapshot keys to set (dot-path → value). */
+    overrideSet: Record<string, unknown>;
+    /** Built-in override-snapshot keys to delete. */
+    overrideReset: string[];
+    /** For a user Agent enabled toggle: mirror onto its recurring row. */
+    mirrorRecurringEnabled?: boolean;
+    /** Read-only / unknown body keys ignored (logged in the response). */
+    stripped: string[];
+};
+/**
+ * Plan a `PATCH /api/agents/:slug` (§9.5). Splits the body into:
+ *   - an `enabled` toggle (column authority; built-in disable needs `ack_warning`);
+ *   - built-in override-snapshot field edits (validated against the schema);
+ *   - override `reset` of those same fields;
+ * and reports every read-only / unknown key it ignored under `stripped`.
+ *
+ * User Agents may only toggle `enabled` here — field edits go through the
+ * `agent.md` file (the dashboard editor → context-vault PATCH path, §9.5), so a
+ * field-edit / reset on a user Agent is rejected with a pointer.
+ */
+export declare function planPatch(dto: AgentDTO, body: Record<string, unknown>): PatchPlan;