@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/sweep.d.ts

@@ -0,0 +1,122 @@
+import type { HerdctlService } from "./herdctl.js";
+import type { ProjectStore } from "./projects.js";
+import { type CurationConfig } from "./curation-config.js";
+import { type PaddockTrigger } from "./trigger-config.js";
+/** Minimal logger shape (Fastify's logger satisfies this). */
+export interface SweepLogger {
+    info(obj: unknown, msg?: string): void;
+    warn(obj: unknown, msg?: string): void;
+    error(obj: unknown, msg?: string): void;
+}
+export interface SweepServiceOptions {
+    herdctl: HerdctlService;
+    projects: ProjectStore;
+    /** Absolute path to the data dir (where the watermark state file lives). */
+    dataDir: string;
+    /** Minimum ms between sweeps for a single project. Default 5 min. */
+    minIntervalMs?: number;
+    /**
+     * INSTANCE-default per-file token budgets the curated files must stay under
+     * (issue #379). A per-project `project.yaml` `curation` override wins field-by-
+     * field at sweep time (issue #384, via {@link resolveCurationConfig}). Defaults
+     * to {@link DEFAULT_CURATION} when unset.
+     */
+    budget?: CurationConfig;
+    logger?: SweepLogger;
+}
+/**
+ * Whether post-turn curation is ON for a project. A project that has NOT overridden the
+ * default (no curator trigger) → ON (behaves exactly as today). A project that DECLARES
+ * a `curate-overview` trigger uses its `enabled` flag authoritatively — so curation can
+ * be switched OFF by declaring the trigger `enabled: false` (and, per the frozen T1
+ * default of `enabled: false`, a declared curator must set `enabled: true` to sweep).
+ */
+export declare function isCurationEnabled(project: {
+    triggers?: Record<string, PaddockTrigger>;
+}): boolean;
+export declare class SweepService {
+    private readonly herdctl;
+    private readonly projects;
+    private readonly stateFile;
+    private readonly minIntervalMs;
+    private readonly instanceCuration;
+    private readonly log;
+    /** In-memory watermark cache (loaded lazily, written through on change). */
+    private state;
+    /** Pending trailing-sweep timers, keyed by slug (coalescing/debounce). */
+    private timers;
+    /** Slugs with a sweep currently executing (prevents overlap). */
+    private running;
+    constructor(opts: SweepServiceOptions);
+    /**
+     * Request a sweep for a project after a user turn completed. Coalesced and
+     * debounced: schedules a single trailing sweep at most once per
+     * `minIntervalMs`. Safe to call on every turn. Never throws.
+     */
+    enqueue(slug: string): void;
+    /** Stop all pending timers (call on shutdown). */
+    stop(): void;
+    private schedule;
+    /** Run a sweep only if there's new activity since the last one. */
+    private runIfActivity;
+    private runSweep;
+    /**
+     * Build a compact digest of recent session activity to hand to the sweeper,
+     * so it doesn't have to discover transcripts itself. We read the messages of
+     * every session newer than the last sweep's watermark (issue #379 concurrency
+     * fix — so a 4th+ chat active within a debounce window is no longer dropped),
+     * capped at {@link MAX_DIGEST_SESSIONS}. On the first sweep (no watermark) we
+     * fall back to the newest few. Summarizes roles + tool usage + trimmed text.
+     */
+    private buildDigest;
+    /**
+     * Read the OPTIONAL per-project sweeper-instruction file
+     * (`.paddock/hooks/sweep.md`, issue #G2) — extra curator guidance a
+     * user/keeper commits to shape THIS project's OVERVIEW/CHANGELOG curation.
+     *
+     * The file is git-tracked and keeper-editable, and lives alongside the
+     * project's `project.yaml`/OVERVIEW.md/CHANGELOG.md in the metadata dir — the
+     * same directory the sweeper agent runs in (its cwd) and that `readFile`
+     * resolves against (traversal-guarded). When absent or blank the sweep behaves
+     * exactly as before (no append). Never throws: a read error is treated as "no
+     * extra instructions" so curation is never broken by a bad/removed file.
+     *
+     * This is a sweeper-LOCAL convenience: it only appends text to the tool-less
+     * curator's prompt (shaping its output), granting no new capability. It is
+     * deliberately NOT routed through the generic hook framework.
+     */
+    private readSweepInstructions;
+    /**
+     * Read the OPTIONAL curator-trigger prompt extension (T5) — the `run.prompt` /
+     * `run.promptFile` of the project's `curate-overview` (event/afterTurn) trigger,
+     * appended to the sweeper's curation prompt exactly like `.paddock/hooks/sweep.md`.
+     * This is how the design's #4 example (`"Also maintain GLOSSARY.md of domain terms."`)
+     * extends the built-in sweep. `run.promptFile` resolves under `.paddock/triggers/`
+     * (traversal-guarded, `.md`-only) and is read fresh at fire time, exactly as the
+     * generic trigger fire path does. Absent trigger / neither field / a read error ⇒ ""
+     * (no extra instructions), so curation is never broken by a bad/removed file. Capped
+     * like every sibling prompt field so it can't bloat the sweep's token cost.
+     */
+    private readTriggerInstructions;
+    /** The curation prompt handed to the sweeper agent. */
+    private curationPrompt;
+    private watermark;
+    private setWatermark;
+    private loadState;
+    private saveState;
+}
+/**
+ * Belt-and-suspenders normalizer for issue #42: keep box/environment
+ * operational conventions out of a curated OVERVIEW.md even when the sweeper
+ * slips them in despite the prompt. OVERVIEW.md is prepended to every new chat,
+ * so a stray "run the dev server on localhost:4100" line there silently
+ * overrides the box CLAUDE.md — a self-reinforcing wrong-setup loop.
+ *
+ * This drops whole markdown sections whose heading denotes "how to run / build /
+ * expose a dev server on this box" (heading + body, down to the next heading of
+ * the same or higher level). Scope is deliberately narrow: only sections headed
+ * by a recognized dev-ops phrase are removed; prose elsewhere is untouched. If
+ * stripping would empty the document, the original is returned (we never write a
+ * blank OVERVIEW).
+ */
+export declare function stripBoxConventions(overview: string): string;