@aitne/daemon 0.1.7 → 0.1.9

package/dist/core/agent-core.d.ts

@@ -104,6 +104,20 @@ export interface AgentExecuteParams {
      *   - Allow-mode backends ignore the flag (external HTTP already works).
      */
     wikiUrlFetchEnabled?: boolean;
+    /**
+     * AGENT_DEFINITIONS_DESIGN.md §4.2 — the firing Agent's `tools.skills`.
+     * The dispatcher resolves these from the Agent's effective definition and
+     * the core forwards them into `createSessionWorkdir`, where
+     * `composeSkillSet` folds them onto the process-key default bundle (union,
+     * or replace when `skillsReplace` is set). Empty / undefined is a no-op, so
+     * non-Agent executes (DMs, built-in routines, managed tasks) are unaffected.
+     *
+     * Forwarded verbatim on both the main and fallback execute paths so an
+     * Agent's added skills survive a Claude → Codex fallback.
+     */
+    extraSkills?: readonly string[];
+    /** AGENT_DEFINITIONS_DESIGN.md §4.2 — `tools.skills_replace`. See `extraSkills`. */
+    skillsReplace?: boolean;
 }
 export interface AgentResumeParams {
     sessionId: string;
@@ -527,16 +541,34 @@ export declare class LiveProbeUnsupportedError extends Error {
     readonly reason: string;
     constructor(backendId: BackendId, reason: string);
 }
+/**
+ * Optional spend payload attached to BackendQuotaError when the underlying
+ * backend has already consumed tokens before the daemon's per-turn budget
+ * cap rejected the run. Populated by post-hoc budget assertions (Codex /
+ * Gemini CLI) where the model completed a turn whose actual usage exceeded
+ * the cap. The dispatcher's error handler writes this into `agent_actions`
+ * with `result='failed'` so the dashboard reflects what was actually
+ * billed, instead of dropping the row silently on the success-only audit
+ * path.
+ */
+export interface BackendQuotaSpend {
+    usage: import("@aitne/shared").BackendUsage;
+    costUsd: number;
+    modelId: string;
+    numTurns: number;
+    durationMs: number;
+    costSource: AgentResult["costSource"];
+}
 export declare class BackendQuotaError extends Error {
     readonly backendId: BackendId;
     readonly originalCode: string;
     readonly resetHint: BackendQuotaResetHint | null;
-    constructor(backendId: BackendId, originalCode: string, resetHint: BackendQuotaResetHint | null, message: string);
+    readonly spend: BackendQuotaSpend | null;
+    constructor(backendId: BackendId, originalCode: string, resetHint: BackendQuotaResetHint | null, message: string, spend?: BackendQuotaSpend | null);
 }
 export declare class BackendDecisiveFailure extends Error {
     readonly backendId: BackendId;
-    readonly kind: "quota" | "auth" | "max_turns" | "timeout" | "model_unavailable" | "other_non_retryable";
+    readonly kind: "quota" | "auth" | "max_turns" | "timeout" | "model_unavailable" | "policy_denied" | "other_non_retryable";
     readonly cause: unknown;
-    constructor(backendId: BackendId, kind: "quota" | "auth" | "max_turns" | "timeout" | "model_unavailable" | "other_non_retryable", cause: unknown);
+    constructor(backendId: BackendId, kind: "quota" | "auth" | "max_turns" | "timeout" | "model_unavailable" | "policy_denied" | "other_non_retryable", cause: unknown);
 }
-//# sourceMappingURL=agent-core.d.ts.map

package/dist/core/agent-core.js

@@ -79,11 +79,13 @@ export class BackendQuotaError extends Error {
     backendId;
     originalCode;
     resetHint;
-    constructor(backendId, originalCode, resetHint, message) {
+    spend;
+    constructor(backendId, originalCode, resetHint, message, spend = null) {
         super(message);
         this.backendId = backendId;
         this.originalCode = originalCode;
         this.resetHint = resetHint;
+        this.spend = spend;
         this.name = "BackendQuotaError";
     }
 }
@@ -99,4 +101,3 @@ export class BackendDecisiveFailure extends Error {
         this.name = "BackendDecisiveFailure";
     }
 }
-//# sourceMappingURL=agent-core.js.map

package/dist/core/agent-execution-recorder.d.ts

@@ -0,0 +1,78 @@
+import type Database from "better-sqlite3";
+import { type CompleteExecutionInput, type StartExecutionInput, type SweepAbandonedResult } from "../db/agent-executions-store.js";
+/**
+ * Per-firing execution recorder (AGENT_DEFINITIONS_DESIGN.md §8.2 / §7.4).
+ *
+ * A thin lifecycle wrapper over the Phase-2 `agent-executions-store.ts` (which
+ * owns the raw `agent_executions` SQL). The store is a faithful column writer
+ * and intentionally does NOT know about two things the recorder adds:
+ *
+ *   1. **The agent-day `{date}` label**, computed once at `start` and pinned to
+ *      the execution's `started_at` instant. Pinning at start (not at eval
+ *      time) matters: a long routine that begins at 03:55 and finishes at 04:05
+ *      must still evaluate its `{date}`-keyed criteria against the agent-day it
+ *      *started* in, not the one the 04:00 boundary rolled into mid-run. The
+ *      label is returned in the `StartedExecution` handle and threaded into
+ *      success-criteria evaluation by the dispatcher (§8.3) — it is derivable
+ *      from `started_at` so it is intentionally not persisted.
+ *   2. **The same-transaction `agents.last_execution_id` update** at `complete`,
+ *      so a dashboard read can never observe a finished execution whose owning
+ *      Agent still points at the previous run.
+ *
+ * Synchronous by design: better-sqlite3 is synchronous and every store function
+ * is too, so the original Promise-returning design sketch was an artifact (the
+ * design doc §8.2 was reconciled to the shipped sync interface).
+ */
+/** Constructor dependencies. `now`/`timezone` are injectable for tests. */
+export interface AgentExecutionRecorderDeps {
+    db: Database.Database;
+    /** IANA zone (config.timezone). `undefined` → host system zone. */
+    timezone?: string;
+    /** Agent-day boundary hour (config.dayBoundaryHour; 4 in production). */
+    dayBoundaryHour: number;
+    /** Epoch-ms clock; defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Handle returned by `start`. The dispatcher holds it for the run's duration and
+ * threads `dateStr` / `startedAt` (with the resolved `agentId`) into the
+ * success-criteria evaluator at completion (§8.3).
+ */
+export interface StartedExecution {
+    /** New `agent_executions.id`. */
+    executionId: number;
+    /** Epoch-ms start instant — identical to the persisted `started_at`. */
+    startedAt: number;
+    /** Agent-day `YYYY-MM-DD` label pinned to `startedAt`, reused per criterion. */
+    dateStr: string;
+}
+export declare class AgentExecutionRecorder {
+    private readonly db;
+    private readonly timezone?;
+    private readonly dayBoundaryHour;
+    private readonly now;
+    constructor(deps: AgentExecutionRecorderDeps);
+    /**
+     * Open a new in-flight execution: INSERT a row with `result = NULL` and
+     * compute the agent-day label once. The `agent_id` FK requires the Agent row
+     * to already exist (the loader upserts it at boot / the API at create-time).
+     */
+    start(input: StartExecutionInput): StartedExecution;
+    /**
+     * Finalise an execution and re-point `agents.last_execution_id` at it, both
+     * inside a single transaction (§7.4). The owning slug is read back from the
+     * just-updated row — the FK is the single source of truth, so the caller
+     * cannot mis-attribute the pointer. `last_execution_id` is updated for every
+     * terminal result (success, error, timeout, skipped) so the dashboard's
+     * "last run" reflects failures too. Returns false when no row matched the id
+     * (nothing is updated in that case).
+     */
+    complete(input: CompleteExecutionInput): boolean;
+    /**
+     * Boot-time crash janitor (§7.4): flip every still-in-flight row started
+     * before `beforeTs` (the daemon boot instant) to `error / crash`. Delegates
+     * to the store so the recorder is the single start/complete/sweep lifecycle
+     * surface the daemon wires (Phase 7 `bootstrap/db.ts`).
+     */
+    sweepAbandoned(beforeTs: number): SweepAbandonedResult;
+}

package/dist/core/agent-execution-recorder.js

@@ -0,0 +1,60 @@
+import { getAgentDayDateStr } from "@aitne/shared";
+import { completeExecution, getExecution, startExecution, sweepAbandoned as sweepAbandonedRows, } from "../db/agent-executions-store.js";
+import { disableOneShotAfterFire, setLastExecutionId } from "../db/agents-store.js";
+export class AgentExecutionRecorder {
+    db;
+    timezone;
+    dayBoundaryHour;
+    now;
+    constructor(deps) {
+        this.db = deps.db;
+        this.timezone = deps.timezone;
+        this.dayBoundaryHour = deps.dayBoundaryHour;
+        this.now = deps.now ?? Date.now;
+    }
+    /**
+     * Open a new in-flight execution: INSERT a row with `result = NULL` and
+     * compute the agent-day label once. The `agent_id` FK requires the Agent row
+     * to already exist (the loader upserts it at boot / the API at create-time).
+     */
+    start(input) {
+        const startedAt = this.now();
+        const executionId = startExecution(this.db, input, startedAt);
+        const dateStr = getAgentDayDateStr(this.timezone, this.dayBoundaryHour, new Date(startedAt));
+        return { executionId, startedAt, dateStr };
+    }
+    /**
+     * Finalise an execution and re-point `agents.last_execution_id` at it, both
+     * inside a single transaction (§7.4). The owning slug is read back from the
+     * just-updated row — the FK is the single source of truth, so the caller
+     * cannot mis-attribute the pointer. `last_execution_id` is updated for every
+     * terminal result (success, error, timeout, skipped) so the dashboard's
+     * "last run" reflects failures too. Returns false when no row matched the id
+     * (nothing is updated in that case).
+     */
+    complete(input) {
+        const stamp = this.now();
+        const apply = this.db.transaction(() => {
+            const changed = completeExecution(this.db, input, stamp);
+            if (!changed)
+                return false;
+            // changed === true ⇒ the UPDATE matched, so the row is present.
+            const row = getExecution(this.db, input.executionId);
+            setLastExecutionId(this.db, row.agentId, input.executionId, stamp);
+            // §16 Q8: a one_shot Agent disables itself once it has fired, becoming a
+            // re-runnable record (run-now re-fires it). No-op for cron / event Agents.
+            disableOneShotAfterFire(this.db, row.agentId, stamp);
+            return true;
+        });
+        return apply();
+    }
+    /**
+     * Boot-time crash janitor (§7.4): flip every still-in-flight row started
+     * before `beforeTs` (the daemon boot instant) to `error / crash`. Delegates
+     * to the store so the recorder is the single start/complete/sweep lifecycle
+     * surface the daemon wires (Phase 7 `bootstrap/db.ts`).
+     */
+    sweepAbandoned(beforeTs) {
+        return sweepAbandonedRows(this.db, beforeTs, this.now());
+    }
+}

package/dist/core/agents/agent-execution-tracker.d.ts

@@ -0,0 +1,91 @@
+import type Database from "better-sqlite3";
+import type { SuccessCriterion } from "@aitne/shared";
+import type { AgentExecutionTrigger } from "../../db/agent-executions-store.js";
+import type { AgentExecutionRecorder } from "../agent-execution-recorder.js";
+import { createLogger } from "../../logging.js";
+import { type AgentIdResolutionInput } from "./agent-id-resolver.js";
+type TrackerLogger = Pick<ReturnType<typeof createLogger>, "warn" | "debug">;
+/** Terminal outcome the result-processor records before the dispatch settles. */
+export interface AgentExecutionOutcome {
+    /** `AgentResult.isError` — a soft failure that did not throw. */
+    isError: boolean;
+    costUsd?: number | null;
+    tokensIn?: number | null;
+    tokensOut?: number | null;
+    turns?: number | null;
+    outputSummary?: string | null;
+}
+export interface AgentExecutionTrackerDeps {
+    db: Database.Database;
+    recorder: AgentExecutionRecorder;
+    /** Resolved context-vault root for `file_*` success criteria. */
+    contextDir: string;
+    /** SSE emitter for the dashboard's live execution feed (§9.8). */
+    emitSse: (event: string, payload: unknown) => void;
+    /** Loads an Agent's `success_criteria` from its definition file (§8.3). */
+    loadCriteria: (definitionPath: string) => SuccessCriterion[];
+    logger?: TrackerLogger;
+}
+export declare class AgentExecutionTracker {
+    private readonly db;
+    private readonly recorder;
+    private readonly contextDir;
+    private readonly emitSse;
+    private readonly loadCriteria;
+    private readonly logger;
+    private readonly active;
+    constructor(deps: AgentExecutionTrackerDeps);
+    /**
+     * Open an execution for a firing. Resolves the owning Agent (§8.1); when none
+     * resolves, returns `null` and records nothing (legacy task, no-LLM pass).
+     * Otherwise starts the `agent_executions` row, caches the loaded criteria,
+     * and emits `agent.execution.started`. Returns the resolved Agent slug so the
+     * dispatcher can short-circuit stamping when there is no Agent.
+     */
+    begin(correlationId: string, resolution: AgentIdResolutionInput, opts: {
+        scheduleRowId?: number | null;
+        trigger: AgentExecutionTrigger;
+    }): string | null;
+    /**
+     * Record the terminal LLM-level outcome (cost / soft-error) before the
+     * dispatch boundary settles the row. No-op when no execution is active.
+     *
+     * A single-session firing calls this exactly once (merge == replace). A
+     * **multi-stage** firing — today only the morning routine, whose Stage A
+     * (today.md) and Stage B (daily journal) are two separate LLM sessions that
+     * both funnel through the shared `ResultProcessor` carrying the
+     * parent's `correlationId` — calls it once per stage. The outcomes are
+     * therefore *folded* (see {@link mergeOutcome}): cost / tokens / turns are
+     * SUMMED so the rollup reflects the firing's total spend rather than the
+     * last (race-ordered) stage's, and `isError` is sticky-OR.
+     */
+    recordOutcome(correlationId: string, outcome: AgentExecutionOutcome): void;
+    /** The Agent slug currently executing for this correlation id, for
+     *  `agent_actions.agent_id` stamping. `null` when no execution is active. */
+    currentAgentId(correlationId: string): string | null;
+    /**
+     * Settle the active execution as a deliberate skip (AGENT_DEFINITIONS_DESIGN.md
+     * §5.2 — `result='skipped'` is a reserved non-error terminal that does NOT
+     * count toward `errorRate`). Called from a dispatch path that opened a row via
+     * {@link begin} but then decided not to run the routine this tick — e.g. a
+     * review routine blocked by the morning-routine-pending gate, or skill
+     * curation when the optimizer workdir is unwired. Success criteria are NOT
+     * evaluated (the run never happened); `reason` is recorded in `output_summary`
+     * so the dashboard can show why. Idempotent — consumes the map entry, so the
+     * trailing `completeFromDispatch` in `dispatchSafe` is a no-op. No-op when no
+     * execution is active (the firing resolved to no Agent, so `begin` opened no
+     * row).
+     */
+    markSkipped(correlationId: string, reason?: string): void;
+    /**
+     * Settle the active execution at the dispatch boundary. Idempotent — the map
+     * entry is consumed, so a later call (e.g. the error path after the success
+     * path already completed) is a no-op. Evaluates success criteria, writes the
+     * terminal row (+ `agents.last_execution_id`), and emits
+     * `agent.execution.completed`.
+     */
+    completeFromDispatch(correlationId: string, opts?: {
+        thrown?: unknown;
+    }): void;
+}
+export {};

package/dist/core/agents/agent-execution-tracker.js

@@ -0,0 +1,226 @@
+import { getAgent } from "../../db/agents-store.js";
+import { createLogger } from "../../logging.js";
+import { evaluateSuccessCriteria } from "./success-criteria.js";
+import { resolveAgentId, } from "./agent-id-resolver.js";
+/**
+ * Per-firing execution lifecycle (AGENT_DEFINITIONS_DESIGN.md §8.1–§8.3).
+ *
+ * The single owner of the {@link AgentExecutionRecorder} hookup so the
+ * dispatcher + result-processor (both coverage-excluded orchestrators) carry
+ * only three thin calls — `begin` / `recordOutcome` / `completeFromDispatch` —
+ * keyed by the event `correlationId`. Every firing that resolves to a known
+ * Agent opens exactly one `agent_executions` row at start and settles it once
+ * at the dispatch boundary, where success AND both failure modes converge:
+ *
+ *   - a **thrown** dispatch → `result='error'`, `error_kind='exception'`;
+ *   - a **soft** failure (`AgentResult.isError`, recorded via
+ *     {@link recordOutcome}) → `result='error'`, `error_kind='agent_error'`;
+ *   - otherwise → `result='success'`.
+ *
+ * Anchoring completion at the dispatch boundary (not solely at the
+ * result-processor) means a routine that never reaches `processResult` still
+ * settles — the boot janitor only ever sweeps a genuinely abandoned (crashed)
+ * row. Completion is idempotent: the map entry is consumed on the first call.
+ *
+ * Success criteria are evaluated best-effort at completion (§8.3); a throwing
+ * criterion records `false` + a warning and never flips the LLM-level result.
+ */
+const baseLogger = createLogger("agent-execution-tracker");
+/** Sum two nullable numeric fields, preserving `null` only when both are absent. */
+function addNullable(a, b) {
+    if (a == null)
+        return b ?? null;
+    if (b == null)
+        return a;
+    return a + b;
+}
+/**
+ * Fold a stage's outcome into the execution's running rollup. The first call
+ * (`prev === undefined`) adopts the outcome verbatim; a later call (a second
+ * stage of the same firing) sums the spend and keeps `isError` sticky so any
+ * stage's error marks the run, deterministically and independent of the
+ * `Promise.allSettled` completion order. `outputSummary` keeps the latest
+ * non-empty value.
+ */
+function mergeOutcome(prev, next) {
+    if (prev === undefined)
+        return next;
+    return {
+        isError: prev.isError || next.isError,
+        costUsd: addNullable(prev.costUsd, next.costUsd),
+        tokensIn: addNullable(prev.tokensIn, next.tokensIn),
+        tokensOut: addNullable(prev.tokensOut, next.tokensOut),
+        turns: addNullable(prev.turns, next.turns),
+        outputSummary: next.outputSummary ?? prev.outputSummary,
+    };
+}
+export class AgentExecutionTracker {
+    db;
+    recorder;
+    contextDir;
+    emitSse;
+    loadCriteria;
+    logger;
+    active = new Map();
+    constructor(deps) {
+        this.db = deps.db;
+        this.recorder = deps.recorder;
+        this.contextDir = deps.contextDir;
+        this.emitSse = deps.emitSse;
+        this.loadCriteria = deps.loadCriteria;
+        this.logger = deps.logger ?? baseLogger;
+    }
+    /**
+     * Open an execution for a firing. Resolves the owning Agent (§8.1); when none
+     * resolves, returns `null` and records nothing (legacy task, no-LLM pass).
+     * Otherwise starts the `agent_executions` row, caches the loaded criteria,
+     * and emits `agent.execution.started`. Returns the resolved Agent slug so the
+     * dispatcher can short-circuit stamping when there is no Agent.
+     */
+    begin(correlationId, resolution, opts) {
+        const agentId = resolveAgentId(this.db, resolution);
+        if (agentId === null)
+            return null;
+        // resolveAgentId verified the row exists synchronously, so getAgent is
+        // non-null here (better-sqlite3 is single-threaded; no row can vanish
+        // between the two reads).
+        const definitionPath = getAgent(this.db, agentId).definitionPath;
+        const criteria = this.loadCriteria(definitionPath);
+        const handle = this.recorder.start({
+            agentId,
+            scheduleRowId: opts.scheduleRowId ?? null,
+            trigger: opts.trigger,
+        });
+        this.active.set(correlationId, {
+            executionId: handle.executionId,
+            startedAt: handle.startedAt,
+            dateStr: handle.dateStr,
+            agentId,
+            criteria,
+        });
+        this.emitSse("agent.execution.started", {
+            slug: agentId,
+            executionId: handle.executionId,
+            trigger: opts.trigger,
+            startedAt: handle.startedAt,
+        });
+        return agentId;
+    }
+    /**
+     * Record the terminal LLM-level outcome (cost / soft-error) before the
+     * dispatch boundary settles the row. No-op when no execution is active.
+     *
+     * A single-session firing calls this exactly once (merge == replace). A
+     * **multi-stage** firing — today only the morning routine, whose Stage A
+     * (today.md) and Stage B (daily journal) are two separate LLM sessions that
+     * both funnel through the shared `ResultProcessor` carrying the
+     * parent's `correlationId` — calls it once per stage. The outcomes are
+     * therefore *folded* (see {@link mergeOutcome}): cost / tokens / turns are
+     * SUMMED so the rollup reflects the firing's total spend rather than the
+     * last (race-ordered) stage's, and `isError` is sticky-OR.
+     */
+    recordOutcome(correlationId, outcome) {
+        const entry = this.active.get(correlationId);
+        if (entry === undefined)
+            return;
+        entry.outcome = mergeOutcome(entry.outcome, outcome);
+    }
+    /** The Agent slug currently executing for this correlation id, for
+     *  `agent_actions.agent_id` stamping. `null` when no execution is active. */
+    currentAgentId(correlationId) {
+        return this.active.get(correlationId)?.agentId ?? null;
+    }
+    /**
+     * Settle the active execution as a deliberate skip (AGENT_DEFINITIONS_DESIGN.md
+     * §5.2 — `result='skipped'` is a reserved non-error terminal that does NOT
+     * count toward `errorRate`). Called from a dispatch path that opened a row via
+     * {@link begin} but then decided not to run the routine this tick — e.g. a
+     * review routine blocked by the morning-routine-pending gate, or skill
+     * curation when the optimizer workdir is unwired. Success criteria are NOT
+     * evaluated (the run never happened); `reason` is recorded in `output_summary`
+     * so the dashboard can show why. Idempotent — consumes the map entry, so the
+     * trailing `completeFromDispatch` in `dispatchSafe` is a no-op. No-op when no
+     * execution is active (the firing resolved to no Agent, so `begin` opened no
+     * row).
+     */
+    markSkipped(correlationId, reason) {
+        const entry = this.active.get(correlationId);
+        if (entry === undefined)
+            return;
+        this.active.delete(correlationId);
+        this.recorder.complete({
+            executionId: entry.executionId,
+            result: "skipped",
+            ...(reason !== undefined ? { outputSummary: reason } : {}),
+        });
+        this.emitSse("agent.execution.completed", {
+            slug: entry.agentId,
+            executionId: entry.executionId,
+            result: "skipped",
+        });
+    }
+    /**
+     * Settle the active execution at the dispatch boundary. Idempotent — the map
+     * entry is consumed, so a later call (e.g. the error path after the success
+     * path already completed) is a no-op. Evaluates success criteria, writes the
+     * terminal row (+ `agents.last_execution_id`), and emits
+     * `agent.execution.completed`.
+     */
+    completeFromDispatch(correlationId, opts = {}) {
+        const entry = this.active.get(correlationId);
+        if (entry === undefined)
+            return;
+        this.active.delete(correlationId);
+        const thrown = "thrown" in opts;
+        let result;
+        let errorKind = null;
+        let errorMessage = null;
+        if (thrown) {
+            result = "error";
+            errorKind = "exception";
+            errorMessage =
+                opts.thrown instanceof Error
+                    ? opts.thrown.message
+                    : String(opts.thrown);
+        }
+        else if (entry.outcome?.isError === true) {
+            result = "error";
+            errorKind = "agent_error";
+        }
+        else {
+            result = "success";
+        }
+        const { hits, warnings } = evaluateSuccessCriteria(entry.criteria, {
+            db: this.db,
+            contextDir: this.contextDir,
+            agentId: entry.agentId,
+            startedAt: entry.startedAt,
+            dateStr: entry.dateStr,
+        });
+        for (const warning of warnings) {
+            this.logger.warn({ slug: entry.agentId, criterionId: warning.id, kind: warning.kind, message: warning.message }, "success criterion could not be evaluated");
+        }
+        const outcome = entry.outcome;
+        this.recorder.complete({
+            executionId: entry.executionId,
+            result,
+            errorKind,
+            errorMessage,
+            cost: {
+                usd: outcome?.costUsd ?? null,
+                tokensIn: outcome?.tokensIn ?? null,
+                tokensOut: outcome?.tokensOut ?? null,
+                turns: outcome?.turns ?? null,
+            },
+            successCriteriaHits: hits,
+            outputSummary: outcome?.outputSummary ?? null,
+        });
+        this.emitSse("agent.execution.completed", {
+            slug: entry.agentId,
+            executionId: entry.executionId,
+            result,
+            errorKind,
+            successCriteria: hits,
+        });
+    }
+}

package/dist/core/agents/agent-frontmatter.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Agent definition frontmatter parser (AGENT_DEFINITIONS_DESIGN.md §4.3 / §6.1).
+ *
+ * `agent.md` files — both built-in (`agent-assets/agents/<slug>/agent.md`) and
+ * user (`<contextDir>/policies/agents/<slug>/agent.md`) — carry a YAML
+ * frontmatter block fenced by `---` lines, followed by a Markdown body.
+ *
+ * The frontmatter is **deeply nested** (`schedule` / `backend` / `limits` /
+ * `tools` / `success_criteria` / `stop_warning`), so the repo's flat
+ * line-scalar `extractContextFrontmatter` parser cannot read it — it would
+ * silently drop every nested block. This module uses `js-yaml` instead (the
+ * dependency Phase 4 added for exactly this surface; see the Phase 4
+ * design-drift correction in AGENT_DEFINITIONS_IMPLEMENTATION_PLAN.md).
+ *
+ * The fence-splitting logic mirrors `core/context-frontmatter-extract.ts`
+ * (open on a leading `---`, close on the next `---`); only the block parser
+ * changes. This is the same shape Phase 4's `builtin-yaml.test.ts` proved
+ * against the shipped built-ins, lifted into the loader module so production
+ * and the test share one parser.
+ */
+/** Outcome of splitting + parsing an `agent.md` file. */
+export interface AgentFrontmatterParse {
+    /** Parsed frontmatter as a plain object (validate with `agentDefinitionSchema`). */
+    frontmatter: unknown;
+    /** Markdown body after the closing fence, trimmed. */
+    body: string;
+}
+/**
+ * Thrown when the file is not a well-formed frontmatter document: it must open
+ * with a `---` fence on the first line and close with a later `---`, and the
+ * captured block must parse as a YAML mapping. The loader catches this and
+ * records the file as an invalid definition (§6.6) rather than crashing boot.
+ */
+export declare class AgentFrontmatterError extends Error {
+    constructor(message: string);
+}
+/**
+ * Split a Markdown file into its YAML frontmatter object + body.
+ *
+ * Throws {@link AgentFrontmatterError} when the document does not open/close a
+ * frontmatter fence, or when the captured block does not parse to a plain
+ * object (a bare scalar / sequence frontmatter is not a valid agent
+ * definition). `js-yaml` v4 `load` is the safe loader — the code-executing
+ * loader and the `!!js/function` type were removed in v4, so `DEFAULT_SCHEMA`
+ * constructs no arbitrary types.
+ */
+export declare function parseAgentFrontmatter(content: string): AgentFrontmatterParse;
+/**
+ * Render an Agent definition object back into an `agent.md` document: a YAML
+ * frontmatter block + a Markdown body. Used by the auto-import path (§6.5) to
+ * materialise a user Agent file from a legacy `recurring_schedules` row.
+ *
+ * The frontmatter is emitted with `js-yaml` `dump` (stable key order, no
+ * line-wrapping so cron strings / paths stay intact). The result round-trips
+ * cleanly through {@link parseAgentFrontmatter}.
+ */
+export declare function renderAgentMarkdown(frontmatter: Record<string, unknown>, body: string): string;

package/dist/core/agents/agent-frontmatter.js

@@ -0,0 +1,74 @@
+import yaml from "js-yaml";
+/**
+ * Thrown when the file is not a well-formed frontmatter document: it must open
+ * with a `---` fence on the first line and close with a later `---`, and the
+ * captured block must parse as a YAML mapping. The loader catches this and
+ * records the file as an invalid definition (§6.6) rather than crashing boot.
+ */
+export class AgentFrontmatterError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AgentFrontmatterError";
+    }
+}
+/**
+ * Split a Markdown file into its YAML frontmatter object + body.
+ *
+ * Throws {@link AgentFrontmatterError} when the document does not open/close a
+ * frontmatter fence, or when the captured block does not parse to a plain
+ * object (a bare scalar / sequence frontmatter is not a valid agent
+ * definition). `js-yaml` v4 `load` is the safe loader — the code-executing
+ * loader and the `!!js/function` type were removed in v4, so `DEFAULT_SCHEMA`
+ * constructs no arbitrary types.
+ */
+export function parseAgentFrontmatter(content) {
+    // `split` always yields at least one element, so `lines[0]` is defined.
+    const lines = content.split(/\r?\n/);
+    if (lines[0].trim() !== "---") {
+        throw new AgentFrontmatterError("agent.md must open with a `---` frontmatter fence on the first line");
+    }
+    const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+    if (end < 0) {
+        throw new AgentFrontmatterError("agent.md frontmatter block is never closed with `---`");
+    }
+    let frontmatter;
+    try {
+        frontmatter = yaml.load(lines.slice(1, end).join("\n"));
+    }
+    catch (err) {
+        // `${err}` renders js-yaml's YAMLException ("…: bad indentation …") via its
+        // own toString — no `instanceof Error` branch (js-yaml always throws here).
+        throw new AgentFrontmatterError(`agent.md frontmatter is not valid YAML: ${err}`);
+    }
+    if (frontmatter === null || frontmatter === undefined) {
+        throw new AgentFrontmatterError("agent.md frontmatter block is empty");
+    }
+    if (typeof frontmatter !== "object" || Array.isArray(frontmatter)) {
+        throw new AgentFrontmatterError("agent.md frontmatter must be a YAML mapping, not a scalar or sequence");
+    }
+    return {
+        frontmatter,
+        body: lines.slice(end + 1).join("\n").trim(),
+    };
+}
+/**
+ * Render an Agent definition object back into an `agent.md` document: a YAML
+ * frontmatter block + a Markdown body. Used by the auto-import path (§6.5) to
+ * materialise a user Agent file from a legacy `recurring_schedules` row.
+ *
+ * The frontmatter is emitted with `js-yaml` `dump` (stable key order, no
+ * line-wrapping so cron strings / paths stay intact). The result round-trips
+ * cleanly through {@link parseAgentFrontmatter}.
+ */
+export function renderAgentMarkdown(frontmatter, body) {
+    const yamlBlock = yaml.dump(frontmatter, {
+        lineWidth: -1,
+        noRefs: true,
+        sortKeys: false,
+    });
+    const trimmedBody = body.trim();
+    // yaml.dump already ends with a trailing newline; bracket it with fences and
+    // append the body so the file opens/closes a frontmatter block exactly like
+    // the shipped built-ins.
+    return `---\n${yamlBlock}---\n\n${trimmedBody}\n`;
+}