@aitne/daemon 0.1.9 → 0.1.11

package/dist/core/feedback/scope-parser.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Feedback Learning Loop — scope grammar (FEEDBACK_LEARNING_LOOP_DESIGN.md §3.3).
+ *
+ * A feedback signal / lesson carries a **scope** that decides *who sees it*.
+ * This module is the single source of truth that maps the DB row's
+ * `(scope_type, scope_ref)` pair onto:
+ *   - a canonical, human-readable scope string (`user`, `agent`,
+ *     `agent:report-writer`, `channel:slack`, …) used in worksheet XML and
+ *     lesson-file headers, and
+ *   - the writable vault file that stores that scope's lessons.
+ *
+ * Pure logic, no I/O — the §4 division-of-labour "scope parser" covered module.
+ * Phase 2 only *stores* `user` + `agent`; the parser still recognises the full
+ * v2 grammar (`agent_slug`, `channel`, `task`, `integration`) so forward-compat
+ * rows round-trip rather than throwing, but `scopeStoreFile` returns `null` for
+ * the not-yet-stored classes — the caller treats that as "surface but do not
+ * persist a lesson file yet".
+ */
+import type { FeedbackScopeType } from "../../db/feedback-signals-store.js";
+/** Parsed, normalised scope. `agent_slug` collapses to `kind: "agent_slug"`. */
+export type CanonicalScope = {
+    kind: "user";
+} | {
+    kind: "agent";
+} | {
+    kind: "agent_slug";
+    ref: string;
+} | {
+    kind: "channel";
+    ref: string;
+} | {
+    kind: "task";
+    ref: string;
+} | {
+    kind: "integration";
+    ref: string;
+};
+/**
+ * Parse a `(scope_type, scope_ref)` pair into a {@link CanonicalScope}.
+ * Returns `null` when the type is unknown or a ref-required class is missing
+ * its ref — the caller drops such rows from the worksheet rather than guessing.
+ */
+export declare function parseScope(scopeType: string, scopeRef: string | null | undefined): CanonicalScope | null;
+/**
+ * Canonical human-readable scope label used in worksheet XML attributes and
+ * the `<!-- scope: … -->` lesson-file header. `agent:<slug>` is the literal
+ * answer to requirement #3 ("feedback on a generated agent's output").
+ */
+export declare function formatScope(scope: CanonicalScope): string;
+/**
+ * Stable grouping key for a scope — used by the consolidation pre-step to
+ * bucket unconsumed signals by `(scope_type, scope_ref)` (§4 step 1). Equal
+ * for two signals that target the same lesson destination.
+ */
+export declare function scopeKey(scope: CanonicalScope): string;
+/**
+ * Resolve the writable-vault relative path that stores a scope's lessons.
+ *   - `user`       → `identity/profile.md` (`## Learned Context` section)
+ *   - `agent`      → `policies/agent-lessons.md`
+ *   - `agent:slug` → `policies/agents/<slug>/lessons.md`
+ *   - everything else (v2 channel/task/integration) → `null` (not yet stored)
+ *
+ * The `agent:<slug>` ref is path-validated with {@link isSafeAgentSlug} before
+ * it is composed into a vault path — the same guard the inject side applies to
+ * `event.data.agentId` (`context-builder.ts`), so both consumers of a slug
+ * reject the same unsafe shapes (`agentLessonsPath` itself trusts a
+ * pre-validated slug). A path-unsafe ref yields `null` ("surface but do not
+ * persist"), so the consolidation worksheet never emits an unsafe `store=` for
+ * the LLM to PATCH. In practice the `/api/feedback` route + the behavioral
+ * sink only ever write a real `agents.id` ref, so this is pure defence-in-depth
+ * against a malformed / forged row.
+ */
+export declare function scopeStoreFile(scope: CanonicalScope): string | null;
+export declare function isSafeAgentSlug(value: string): boolean;
+/**
+ * The markdown section a scope's lessons live under, for PATCH `section=`
+ * targeting. `user` folds into the existing `## Learned Context`; lesson
+ * stores use `## Lessons`.
+ */
+export declare function scopeSectionSlug(scope: CanonicalScope): string;
+/**
+ * True when a scope type needs a ref to be valid. Exposed for the route /
+ * worksheet validators that mirror the §3.5.2 "scope_ref present iff
+ * scope_type=agent_slug" rule across the extended grammar.
+ */
+export declare function scopeNeedsRef(scopeType: FeedbackScopeType): boolean;

package/dist/core/feedback/scope-parser.js

@@ -0,0 +1,141 @@
+/**
+ * Feedback Learning Loop — scope grammar (FEEDBACK_LEARNING_LOOP_DESIGN.md §3.3).
+ *
+ * A feedback signal / lesson carries a **scope** that decides *who sees it*.
+ * This module is the single source of truth that maps the DB row's
+ * `(scope_type, scope_ref)` pair onto:
+ *   - a canonical, human-readable scope string (`user`, `agent`,
+ *     `agent:report-writer`, `channel:slack`, …) used in worksheet XML and
+ *     lesson-file headers, and
+ *   - the writable vault file that stores that scope's lessons.
+ *
+ * Pure logic, no I/O — the §4 division-of-labour "scope parser" covered module.
+ * Phase 2 only *stores* `user` + `agent`; the parser still recognises the full
+ * v2 grammar (`agent_slug`, `channel`, `task`, `integration`) so forward-compat
+ * rows round-trip rather than throwing, but `scopeStoreFile` returns `null` for
+ * the not-yet-stored classes — the caller treats that as "surface but do not
+ * persist a lesson file yet".
+ */
+import { agentLessonsPath, CONTEXT_RELATIVE_PATHS } from "../context-paths.js";
+/** Scope classes that require a `scope_ref` to be meaningful. */
+const REF_REQUIRED = new Set([
+    "agent_slug",
+    "channel",
+    "task",
+    "integration",
+]);
+/**
+ * Parse a `(scope_type, scope_ref)` pair into a {@link CanonicalScope}.
+ * Returns `null` when the type is unknown or a ref-required class is missing
+ * its ref — the caller drops such rows from the worksheet rather than guessing.
+ */
+export function parseScope(scopeType, scopeRef) {
+    const ref = typeof scopeRef === "string" ? scopeRef.trim() : "";
+    switch (scopeType) {
+        case "user":
+            return { kind: "user" };
+        case "agent":
+            return { kind: "agent" };
+        case "agent_slug":
+            return ref.length > 0 ? { kind: "agent_slug", ref } : null;
+        case "channel":
+            return ref.length > 0 ? { kind: "channel", ref } : null;
+        case "task":
+            return ref.length > 0 ? { kind: "task", ref } : null;
+        case "integration":
+            return ref.length > 0 ? { kind: "integration", ref } : null;
+        default:
+            return null;
+    }
+}
+/**
+ * Canonical human-readable scope label used in worksheet XML attributes and
+ * the `<!-- scope: … -->` lesson-file header. `agent:<slug>` is the literal
+ * answer to requirement #3 ("feedback on a generated agent's output").
+ */
+export function formatScope(scope) {
+    switch (scope.kind) {
+        case "user":
+            return "user";
+        case "agent":
+            return "agent";
+        case "agent_slug":
+            return `agent:${scope.ref}`;
+        case "channel":
+            return `channel:${scope.ref}`;
+        case "task":
+            return `task:${scope.ref}`;
+        case "integration":
+            return `integration:${scope.ref}`;
+    }
+}
+/**
+ * Stable grouping key for a scope — used by the consolidation pre-step to
+ * bucket unconsumed signals by `(scope_type, scope_ref)` (§4 step 1). Equal
+ * for two signals that target the same lesson destination.
+ */
+export function scopeKey(scope) {
+    return formatScope(scope);
+}
+/**
+ * Resolve the writable-vault relative path that stores a scope's lessons.
+ *   - `user`       → `identity/profile.md` (`## Learned Context` section)
+ *   - `agent`      → `policies/agent-lessons.md`
+ *   - `agent:slug` → `policies/agents/<slug>/lessons.md`
+ *   - everything else (v2 channel/task/integration) → `null` (not yet stored)
+ *
+ * The `agent:<slug>` ref is path-validated with {@link isSafeAgentSlug} before
+ * it is composed into a vault path — the same guard the inject side applies to
+ * `event.data.agentId` (`context-builder.ts`), so both consumers of a slug
+ * reject the same unsafe shapes (`agentLessonsPath` itself trusts a
+ * pre-validated slug). A path-unsafe ref yields `null` ("surface but do not
+ * persist"), so the consolidation worksheet never emits an unsafe `store=` for
+ * the LLM to PATCH. In practice the `/api/feedback` route + the behavioral
+ * sink only ever write a real `agents.id` ref, so this is pure defence-in-depth
+ * against a malformed / forged row.
+ */
+export function scopeStoreFile(scope) {
+    switch (scope.kind) {
+        case "user":
+            return CONTEXT_RELATIVE_PATHS.user.profile;
+        case "agent":
+            return CONTEXT_RELATIVE_PATHS.agentLessons;
+        case "agent_slug":
+            return isSafeAgentSlug(scope.ref) ? agentLessonsPath(scope.ref) : null;
+        default:
+            return null;
+    }
+}
+/**
+ * Path-safety guard for an `agent:<slug>` ref before it is interpolated into a
+ * vault file path (`agentLessonsPath`). The Phase-4 inject path reads
+ * `event.data.agentId` — a `Record<string, unknown>` value set by the dispatch
+ * site from `resolveAgentId()` — and joins it under `policies/agents/`. Although
+ * `resolveAgentId` only ever returns DB-verified / built-in-registry slugs,
+ * defence-in-depth requires the consuming side validate the shape rather than
+ * trust the carrier: the slug must be a single safe segment (kebab-case-ish,
+ * the same `[a-z0-9._-]` alphabet `deriveSlug` and the context-write whitelist
+ * use), start alphanumeric (so `.`/`..` are rejected outright), and contain no
+ * `..` traversal or `/` separator. A failing value yields no self block rather
+ * than a path escape.
+ */
+const SAFE_AGENT_SLUG_RE = /^[a-z0-9][a-z0-9._-]*$/;
+export function isSafeAgentSlug(value) {
+    return SAFE_AGENT_SLUG_RE.test(value) && !value.includes("..");
+}
+/**
+ * The markdown section a scope's lessons live under, for PATCH `section=`
+ * targeting. `user` folds into the existing `## Learned Context`; lesson
+ * stores use `## Lessons`.
+ */
+export function scopeSectionSlug(scope) {
+    return scope.kind === "user" ? "learned_context" : "lessons";
+}
+/**
+ * True when a scope type needs a ref to be valid. Exposed for the route /
+ * worksheet validators that mirror the §3.5.2 "scope_ref present iff
+ * scope_type=agent_slug" rule across the extended grammar.
+ */
+export function scopeNeedsRef(scopeType) {
+    return REF_REQUIRED.has(scopeType);
+}

package/dist/core/feedback/self-performance-prep.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Self-Tuning Review Cycle — Measure stage (SELF_TUNING_REVIEW_CYCLE_DESIGN.md
+ * §3.1, Phase 1).
+ *
+ * The daemon-side, deterministic Measure step ($0 — LLM tokens buy judgment
+ * only, P1). On the weekly-review dispatch it computes SQL aggregates over
+ * `agent_actions`, `notification_log`, and the `runtime_state` self-tuning
+ * ledger for a 7-day window plus a 7-day-prior baseline (trend column), and
+ * renders one compact `<self_performance>` block — hard-capped at
+ * {@link SELF_PERFORMANCE_MAX_BYTES} — so the weekly review's "Metrics (agent
+ * side)" section copies daemon-computed facts instead of paying Sonnet prices
+ * to re-count them.
+ *
+ * Two layers, mirroring `consolidation-prep.ts`:
+ *   - {@link gatherSelfPerformanceData} — the single DB read (side-effect
+ *     free): per-`action_type` run/cost/duration aggregates (`agent_actions`
+ *     has no process_key column; `action_type` carries the routine identity),
+ *     the `routine.fetch_window` empty-run rate per integration (from the
+ *     fan-out audit rows' `detail.prePass` payload the runner persists), the
+ *     `activity_scan.gate` stage distribution (from `buildGateAuditDetail`'s
+ *     historical per-tick rows), per-notification-type `user_reaction`
+ *     breakdowns (the first reader of the column `signal-detector.ts`
+ *     populates), and the `runtime_state.self_tuning:*` ledger.
+ *   - {@link buildSelfPerformanceBlock} — pure renderer. Deterministic
+ *     byte-capped output: per-section row budgets shrink one row at a time
+ *     (largest section first) until the block fits the cap, and clipped rows
+ *     surface as `omitted="N"` so truncation is never silent.
+ *
+ * Phase 1 carries no actuator: nothing here writes config, schedules, or
+ * lessons. Later phases (Recommend / Judge / Actuate) consume the same data
+ * shape; {@link SELF_TUNING_LEDGER_PREFIX} is exported so the Phase 3
+ * actuator writes the ledger keys this module already reads.
+ */
+import type Database from "better-sqlite3";
+/** Measurement window length; the baseline is the same span immediately prior. */
+export declare const SELF_PERFORMANCE_WINDOW_DAYS = 7;
+/** §3.1 — hard cap on the rendered `<self_performance>` block, in UTF-8 bytes. */
+export declare const SELF_PERFORMANCE_MAX_BYTES = 1500;
+/**
+ * §3.4 ledger key prefix. Phase 3's actuator writes
+ * `runtime_state.self_tuning:<key> = {prev, applied_at, baselineMetric, rule}`;
+ * Phase 1 already reads (and renders) whatever sits under the prefix so the
+ * weekly review sees applied changes the cycle they land.
+ */
+export declare const SELF_TUNING_LEDGER_PREFIX = "self_tuning:";
+/** Fan-out audit rows carry the fetcher event's type as `action_type`. */
+export declare const FETCH_WINDOW_ACTION_TYPE = "routine.fetch_window";
+/** Per-tick gate audit rows (`buildGateAuditDetail` payload in `detail`). */
+export declare const ACTIVITY_SCAN_GATE_ACTION_TYPE = "activity_scan.gate";
+export interface ActionTypeStats {
+    actionType: string;
+    runs: number;
+    success: number;
+    partial: number;
+    failed: number;
+    skipped: number;
+    costUsd: number;
+    /** Median over rows with a non-null `duration_ms`; null when none have one. */
+    p50DurationMs: number | null;
+}
+export interface FetchWindowIntegrationStats {
+    integrationKey: string;
+    /** Completed fan-out attempts (prePass status success|partial). */
+    runs: number;
+    /** Completed attempts with `fetched=0 ∧ posted=0` (§3.1 empty-run def). */
+    empty: number;
+}
+export interface HourlyGateStats {
+    /** Every audited cron tick, including rows whose detail failed to parse. */
+    ticks: number;
+    stage0: number;
+    /**
+     * Lite-triage ticks that stayed silent. The writer persists the alias
+     * `stage2_log_only` verbatim (`dispatcher-activity-scan.ts:logGateAuditRow`
+     * overrides `stage_reached` with the applied decision, and a Stage-2 tick
+     * only ever settles to log_only-silent or stage3); a bare `stage2` is
+     * accepted defensively but never occurs in production rows.
+     */
+    stage2: number;
+    /**
+     * Full-session escalations that actually ran. Rows the legacy
+     * min-observations floor short-circuited (`result='skipped'` with
+     * `stage_reached='stage3'`) are excluded — no session ran, no spend.
+     */
+    stage3: number;
+    /**
+     * …of those, ticks whose `gate_reason` was the low-signal fallback (R3).
+     * Forced ticks (`!run` / run-now, `detail.forced=true`) are excluded:
+     * they escalate at any signal level and say nothing about the gate.
+     */
+    stage3LowSignal: number;
+    /** …of those, ticks whose snapshot max novelty was ≤ 1 (null counts as ≤1). */
+    stage3LowSignalLowNovelty: number;
+}
+export interface NotificationTypeStats {
+    notificationType: string;
+    /** Rows with status delivered|batched (suppressed/failed are not "sent"). */
+    sent: number;
+    replied: number;
+    acted: number;
+    corrected: number;
+    ignored: number;
+    /** No-reaction-yet (incl. unrecognised reaction values, clamped ≥ 0). */
+    pending: number;
+}
+export interface SelfPerformanceWindow {
+    actions: ActionTypeStats[];
+    fetchWindow: FetchWindowIntegrationStats[];
+    gate: HourlyGateStats;
+    notifications: NotificationTypeStats[];
+}
+export interface SelfTuningLedgerEntry {
+    /** Knob name — the runtime_state key with the prefix stripped. */
+    key: string;
+    prev: unknown;
+    appliedAt: string | null;
+    rule: string | null;
+    /**
+     * §3.4 — the rule's target metric captured at apply time, so the weekly
+     * review can compare it against the current `<self_performance>` numbers
+     * (the "measured effect" §3.1 asks the ledger section to carry). Absent
+     * until Phase 3's actuator writes it.
+     */
+    baselineMetric?: unknown;
+    /**
+     * §3.4 — stamped by the Phase 3 auto-revert monitor. Present means the
+     * change regressed and was rolled back; the Phase 2 recommender reads it
+     * to apply the extended 28-day cool-down (vs the normal 14-day
+     * hysteresis) so the apply→revert→re-apply cycle can't flap.
+     */
+    revertedAt?: string;
+    /**
+     * §3.4 — stamped by the auto-revert monitor after a clean 7-day verify
+     * window (`pass`, `no_baseline`, …). Rendered so the weekly judge can
+     * tell a verified-clean change from one still inside its window.
+     */
+    verifyResult?: string;
+}
+export interface SelfPerformanceData {
+    windowDays: number;
+    current: SelfPerformanceWindow;
+    baseline: SelfPerformanceWindow;
+    ledger: SelfTuningLedgerEntry[];
+}
+/** §3.5 — lesson-store byte pressure, the standing cost multiplier to watch. */
+export interface LessonStoreUtilization {
+    /** Canonical scope label — `agent` or `agent:<slug>`. */
+    scope: string;
+    /** UTF-8 byte size of the `## Lessons` section body (the §6 cap unit). */
+    bytes: number;
+    capBytes: number;
+    entries: number;
+    /** Median `ev=` across all entries (R5's evidence signal); null when empty. */
+    medianEv: number | null;
+}
+/**
+ * The single DB read. Computes the current window `[now − windowDays, now)`
+ * and the baseline window `[now − 2·windowDays, now − windowDays)` over
+ * `agent_actions` / `notification_log` (both store SQLite UTC
+ * `YYYY-MM-DD HH:MM:SS` timestamps, so lexicographic comparison against
+ * `formatSqliteDatetime` cutoffs is exact), plus the self-tuning ledger.
+ */
+export declare function gatherSelfPerformanceData(db: Database.Database, opts: {
+    now: Date;
+    windowDays?: number;
+}): SelfPerformanceData;
+/**
+ * §3.5 — summarise one lesson store's byte pressure from its raw file
+ * contents. Pure (the caller does the FS read); a file with no `## Lessons`
+ * section degrades to an empty store, never a throw. `medianEv` carries the
+ * evidence signal R5's Phase 2 rule keys on (utilization > 90% with median
+ * evidence ≤ 1), so the measurement lands one phase ahead of the rule.
+ */
+export declare function summarizeLessonStoreUtilization(scope: string, fileMd: string, capBytes: number): LessonStoreUtilization;
+/**
+ * Compose the `<self_performance>` block. Returns `null` when there is no
+ * telemetry at all (fresh install) so the caller stamps nothing — no empty
+ * block in the prompt. The byte cap is a hard guarantee: row budgets shrink
+ * until the block fits; in the (synthetic) case where even the skeleton
+ * exceeds the cap, a minimal self-closing element is emitted instead.
+ */
+export declare function buildSelfPerformanceBlock(data: SelfPerformanceData, opts: {
+    generatedAt: string;
+    lessonStores?: ReadonlyArray<LessonStoreUtilization>;
+    maxBytes?: number;
+}): string | null;