@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/herdctl-agent-names.js

@@ -0,0 +1,228 @@
+import { agentKeyFor, keyFromAgentKey } from "./project-paths.js";
+/**
+ * Maps a workspace key to its keeper agent name. Kept deterministic so the
+ * runtime registration and runtime lookups always agree.
+ *
+ * The key is encoded through {@link agentKeyFor}, because the root workspace's
+ * key is `""` and a bare `keeper-` is not a legal herdctl agent name. Every
+ * builder below goes through the same encoding, so none of them needs a root
+ * branch. See `project-paths.ts` for why the encoding lives at this boundary
+ * rather than in the identity.
+ */
+export function keeperAgentName(slug) {
+    return `keeper-${agentKeyFor(slug)}`;
+}
+/**
+ * Inverse of {@link keeperAgentName}: recover a workspace key from a keeper
+ * agent name (`keeper-<agentKey>` → `<key>`). Returns `null` for a non-keeper
+ * agent (e.g. a sweeper or a trigger agent), which is how a scheduler-fired wake
+ * tells "this is a chat to route back to a workspace" from "this is not a chat
+ * at all".
+ *
+ * **Callers must distinguish `null` from `""`.** The root workspace's key IS the
+ * empty string, so a falsy check (`if (!key) return;`) silently drops every root
+ * chat from wake/turn/job routing. Compare against `null` explicitly.
+ */
+export function keeperSlugFromAgent(agentName) {
+    if (!agentName.startsWith("keeper-"))
+        return null;
+    return keyFromAgentKey(agentName.slice("keeper-".length));
+}
+/**
+ * The lightweight curator agent used by the post-turn sweep. Runs on a cheap
+ * model (Haiku 4.5) with only read/write tools, no Bash.
+ *
+ * NOTE: herdctl agents bind working_directory per agent. Because a single
+ * shared sweeper can only have one cwd, the SweepService registers ONE sweeper
+ * agent PER PROJECT (keeper-style) so each has the right cwd. The name is
+ * derived from the slug; the agent reads/writes that project's files.
+ */
+export const SWEEPER_PREFIX = "sweeper-";
+/** Maps a project slug to its sweeper agent name. */
+export function sweeperAgentName(slug) {
+    return `${SWEEPER_PREFIX}${agentKeyFor(slug)}`;
+}
+/**
+ * The agent-name prefix for event hooks (Epic G / G1). Each hook is its OWN herdctl
+ * agent `hook-<slug>-<name>` (GG-1) — registered alongside the keeper/sweeper — whose
+ * tool config IS the hook's capability set.
+ */
+export const HOOK_AGENT_PREFIX = "hook-";
+/**
+ * Maps a project slug + hook name to its agent name `hook-<slug>-<name>`. Kept
+ * deterministic so runtime registration and firing (`startAgentTurn`) always agree.
+ * (`slug` is a kebab id and `name` matches `[A-Za-z0-9._-]+`, so the composed name is
+ * a valid herdctl agent name; the reverse mapping for visibility (G3) is resolved
+ * from a project's declared hooks, not by parsing this string.)
+ */
+export function hookAgentName(slug, hookName) {
+    return `${HOOK_AGENT_PREFIX}${agentKeyFor(slug)}-${hookName}`;
+}
+/**
+ * The agent-name prefix for unified triggers (Epic T / T1). An EVENT trigger is its
+ * OWN herdctl agent `trigger-<slug>-<name>` (tool config = capability), registered
+ * alongside the keeper/sweeper — exactly like a hook agent. Schedule triggers run on
+ * the keeper (T1) and webhook triggers are reserved, but every trigger carries this
+ * deterministic name in its DTO so the mapping is stable across T2–T5.
+ */
+export const TRIGGER_AGENT_PREFIX = "trigger-";
+/**
+ * Maps a project slug + trigger name to its agent name `trigger-<slug>-<name>`. Kept
+ * deterministic so runtime registration and firing always agree. The reverse mapping
+ * (for visibility) is resolved from a project's declared triggers, not by parsing this
+ * string (a slug may contain hyphens). Mirrors {@link hookAgentName}.
+ */
+export function triggerAgentName(slug, triggerName) {
+    return `${TRIGGER_AGENT_PREFIX}${agentKeyFor(slug)}-${triggerName}`;
+}
+/**
+ * The agents whose chats are VISIBLE in a project's chat list (Epic G / G3, GG-5):
+ * the keeper plus every event hook the project declares (`hook-<slug>-<name>`). This
+ * is the generalization of the old hard "keeper-only" listing — "all of a project's
+ * agents EXCEPT those marked hidden."
+ *
+ * The **sweeper** (`sweeper-<slug>`) is the one hidden agent: it is deliberately
+ * omitted here so its post-turn curation chats never surface (the `hideChats` case),
+ * exactly as before. Disabled hooks are still included — a hook chat that already ran should stay
+ * visible regardless of whether the hook is currently armed.
+ *
+ * Kept pure + exported so the listing filter is unit-testable in isolation (the
+ * sweeper-stays-hidden regression lives here), and so future callers have ONE place
+ * that answers "which of a project's agents' chats do we show?".
+ */
+export function visibleProjectAgentNames(project) {
+    const names = [keeperAgentName(project.slug)];
+    for (const hookName of Object.keys(project.hooks ?? {})) {
+        names.push(hookAgentName(project.slug, hookName));
+    }
+    // Unified triggers (Epic T): a trigger that runs on its OWN `trigger-<slug>-<name>`
+    // agent produces visible chats (like a hook) — every event trigger, plus a scoped
+    // schedule trigger (T2: one with a `run.tools` allow-list). An unscoped schedule runs
+    // on the keeper (already listed) and a webhook never fires, so they add no distinct
+    // agent — but registering the deterministic name for every trigger is harmless (a name
+    // with no chats simply contributes nothing to the listing).
+    for (const triggerName of Object.keys(project.triggers ?? {})) {
+        names.push(triggerAgentName(project.slug, triggerName));
+    }
+    return names;
+}
+/**
+ * The Claude Code tool pattern for the Playwright browser MCP. Must live on the
+ * agent allowlist (both runtimes auto-deny any tool not on the allow-list —
+ * `--allowedTools` on the CLI, `options.allowedTools` on the SDK — same reason
+ * `Skill` is listed) — so it is added to `defaults.allowed_tools`,
+ * which the keeper agents inherit and the tool-less sweeper overrides
+ * away. Harmless when the server isn't enabled: an allowed-but-absent tool is a
+ * no-op.
+ */
+export const BROWSER_MCP_TOOL = "mcp__playwright__*";
+/**
+ * The keeper's default `denied_tools` — a **best-effort, defence-in-depth**
+ * denylist, NOT a sandbox. Real isolation (per-agent filesystem confinement)
+ * is tracked in #7; these string patterns are trivially bypassable (a relative
+ * path, a `$VAR`, a `find -delete`) and are here only to make the obvious
+ * catastrophic footguns require deliberate rephrasing.
+ *
+ * Claude Code Bash patterns are prefix-with-`*` matches: `Bash(foo *)` denies
+ * any command starting with `foo `, and `Bash(foo)` denies EXACTLY `foo`.
+ *
+ * History (#179): this list used to carry `Bash(rm -rf /*)`, intended as "don't
+ * wipe root". But `/*` is a trailing wildcard, so it actually denied
+ * `rm -rf /<ANYTHING>` — i.e. every absolute-path delete, including the keeper
+ * cleaning up its OWN scratch/clone dirs (`rm -rf /tmp/foo`,
+ * `rm -rf /var/lib/.../clones/x`). That was both over-broad (blocked legitimate
+ * work, wasted turns, confusing "denied" cards) and false security (the agent
+ * just switched to a relative `rm -rf clones/x` and it went through).
+ *
+ * The honest replacement targets genuinely-catastrophic *bare* roots:
+ * - `rm -rf /` and `rm -rf / *` (root, incl. `--no-preserve-root` variants),
+ * - `rm -rf ~` / `rm -rf $HOME` (home, exact — a trailing wildcard would block
+ *   `rm -rf ~/.cache/foo`, which is legitimate),
+ * - bare top-level system dirs matched EXACTLY (`Bash(rm -rf /etc)`, …) so that
+ *   real subpath deletes under them (notably `/var/lib/paddock/...` and
+ *   `/tmp/...`) are NOT denied.
+ *
+ * Note the deliberate gaps: a literal `rm -rf /*` glob command and
+ * `rm -rf /usr/local/...` are NOT caught, because the only pattern that would
+ * catch them (`Bash(rm -rf /*)`, `Bash(rm -rf /usr*)`) also re-blocks the
+ * legitimate absolute-path deletes we exist to allow. Narrow-and-honest beats
+ * broad-and-leaky; the sandbox (#7) is the real fix.
+ */
+export const DENIED_TOOLS = [
+    // Privilege / permission footguns (unchanged from the original list).
+    "Bash(sudo *)",
+    "Bash(chmod 777 *)",
+    // Root wipes: exact `rm -rf /`, plus `rm -rf / <args>` (the trailing space
+    // means this does NOT match `rm -rf /tmp...`, only `rm -rf / --no-preserve-root`
+    // and friends).
+    "Bash(rm -rf /)",
+    "Bash(rm -rf / *)",
+    // Home-directory wipes (exact — no trailing wildcard, see doc-comment).
+    "Bash(rm -rf ~)",
+    "Bash(rm -rf ~/)",
+    "Bash(rm -rf $HOME)",
+    "Bash(rm -rf $HOME/)",
+    // Bare top-level system directories, matched EXACTLY so legitimate subpath
+    // deletes (e.g. `/var/lib/paddock/...`, `/tmp/...`) still pass.
+    "Bash(rm -rf /bin)",
+    "Bash(rm -rf /boot)",
+    "Bash(rm -rf /dev)",
+    "Bash(rm -rf /etc)",
+    "Bash(rm -rf /home)",
+    "Bash(rm -rf /lib)",
+    "Bash(rm -rf /lib64)",
+    "Bash(rm -rf /opt)",
+    "Bash(rm -rf /proc)",
+    "Bash(rm -rf /root)",
+    "Bash(rm -rf /sbin)",
+    "Bash(rm -rf /srv)",
+    "Bash(rm -rf /sys)",
+    "Bash(rm -rf /usr)",
+    "Bash(rm -rf /var)",
+];
+/**
+ * The Playwright browser MCP server given to the keeper agents so
+ * Claude Code can drive a headless Chromium (navigate / click / fill / snapshot
+ * / screenshot). Returns `undefined` when `enabled` is false (sourced from
+ * `cfg.browserMcp`, i.e. `PADDOCK_BROWSER_MCP=1` — issue #269), so a box WITHOUT
+ * the browser stack simply omits the server (no failed spawns) and enabling it
+ * is a per-box env flip — no code change.
+ *
+ * The browser is installed box-side by the homelab `paddock` Ansible role
+ * (`npm i -g @playwright/mcp` + `playwright install chromium`, exposing the
+ * `playwright-mcp` bin on PATH). The boxes are unprivileged LXCs, so Chromium
+ * must run headless + `--no-sandbox` (the container is the isolation boundary);
+ * `--isolated` keeps each session's profile in-memory (no persisted user-data
+ * dir). `--browser chromium` is REQUIRED: @playwright/mcp defaults to the
+ * `chrome` channel (branded Google Chrome), which isn't installed — without this
+ * flag the server tries to `playwright install chrome` at first use and stalls.
+ * The role installs the open-source `chromium` engine, so we select it here.
+ * The tool-less sweeper deliberately never receives this server.
+ */
+export function browserMcpServers(enabled) {
+    if (!enabled)
+        return undefined;
+    return {
+        playwright: {
+            command: "playwright-mcp",
+            args: ["--headless", "--no-sandbox", "--isolated", "--browser", "chromium"],
+        },
+    };
+}
+/**
+ * How many chat turns a project's keeper may run at once. herdctl defaults an
+ * agent to `max_concurrent: 1`, which would serialize a project's chats and make
+ * a second turn (e.g. the first message of a freshly *forked* chat sent while the
+ * parent is still streaming) fail with a ConcurrencyLimitError. Paddock is a
+ * single-user box that explicitly wants parallel chats per project — especially
+ * forks — so we lift the keeper's limit. (The shared-keeper model is still
+ * last-write-wins across concurrent chats of the same project; forks default to
+ * the parent's model, so that caveat rarely bites in practice.)
+ */
+export const KEEPER_MAX_CONCURRENT = 10;
+/**
+ * How long herdctl keeps a keeper's fallback session alive (Paddock#111). Sized
+ * to the reaper's 7-day recurring-wake expiry so a fallback resume still finds
+ * the session; explicit-id resume (Paddock's norm) bypasses this anyway.
+ */
+export const KEEPER_SESSION_TIMEOUT = "168h";

package/packages/server/dist/herdctl-jobs-index.d.ts

@@ -0,0 +1,65 @@
+/** The shared jobs directory herdctl writes `job-*.yaml` records into. */
+export declare function jobsDirOf(stateDir: string): string;
+/**
+ * The only three fields any caller of this index reads, lifted off a job record.
+ *
+ * Only records that resolved to a session AND completed are represented — the
+ * same records the un-indexed scan kept. `agent` is `null` when the record
+ * carries no usable agent name (such a record counts for the flat
+ * session→timestamp map but cannot be grouped by project).
+ */
+export interface JobIndexEntry {
+    readonly sessionId: string;
+    readonly finishedAt: string;
+    readonly agent: string | null;
+}
+/**
+ * An incremental view of one jobs directory.
+ *
+ * One instance per {@link import("./herdctl.js").HerdctlService} (mirroring core's
+ * "a single builder instance must be reused across builds to get the benefit"),
+ * so a test server, a fork of the app, and production each get their own — no
+ * module-level state keyed by path.
+ */
+export declare class JobsDirIndex {
+    private readonly cache;
+    private inFlight;
+    private readonly jobsDir;
+    /**
+     * Diagnostics only (exercised by tests): scans performed, and files parsed /
+     * reused on the last scan, plus how many files the cache currently tracks.
+     */
+    stats: {
+        scans: number;
+        parsed: number;
+        reused: number;
+        tracked: number;
+    };
+    constructor(stateDir: string);
+    /**
+     * Every completed, session-resolved job record in the directory, in no
+     * particular order.
+     *
+     * Concurrent callers COALESCE onto one scan: the `/projects` grid fires seven
+     * parallel `/chats` requests, and running seven identical directory passes
+     * helps nobody. A caller that arrives mid-scan therefore observes the directory
+     * as of that scan's `readdir` — at most one scan (~20 ms) stale, against the
+     * ~850 ms of drift the un-indexed version already had between its own `readdir`
+     * and its last parse. A call made AFTER a write always sees that write.
+     *
+     * Never throws: an unreadable directory yields `[]`, and an unreadable or
+     * half-written record is skipped, exactly as before.
+     */
+    read(): Promise<readonly JobIndexEntry[]>;
+    /**
+     * Forget everything, forcing the next {@link read} to re-parse.
+     *
+     * The mtime+size key already self-heals after Paddock's own jobs-dir writes
+     * (`reattributeSession` rewrites records, `writeAgentAdoptionJob` adds them),
+     * so this is belt-and-braces called alongside the existing
+     * `invalidateSessions` at those sites — it makes the freshness guarantee
+     * independent of filesystem timestamp granularity.
+     */
+    invalidate(): void;
+    private scan;
+}

package/packages/server/dist/herdctl-jobs-index.js

@@ -0,0 +1,225 @@
+/**
+ * herdctl-jobs-index — an incremental, mtime-keyed index of the shared
+ * `<stateDir>/jobs` directory (issue #529).
+ *
+ * ## Why this exists
+ *
+ * {@link import("./herdctl-jobs.js").lastTurnCompletedAt} and its per-project
+ * sibling are the server signal behind the unread affordance, so they run on
+ * `GET /api/projects`, `GET /api/projects/:slug` and
+ * `GET /api/projects/:slug/chats` — i.e. on essentially every page load. They
+ * used to `readdir` + `YAML.parse` EVERY `job-*.yaml` on every one of those
+ * requests, with no cache. On a real instance (1,996 records, 46.6 MB) a CPU
+ * profile attributed **61% of all busy server CPU** to that parse. Because it is
+ * synchronous work on the single event loop it pinned throughput at ~1.1 req/s
+ * and made an unrelated 2 ms endpoint take ~850 ms while a scan was in flight.
+ * The jobs dir is shared fleet-wide and never pruned, so the cost was flat in
+ * project size and linear in instance age.
+ *
+ * ## The invariant that makes an index safe
+ *
+ * A job record is written when a turn starts and rewritten when it finishes; it
+ * is **immutable once `finished_at` is set**, and the directory is append-only.
+ * So a warm index only ever has to parse files it has not seen before. Measured
+ * on the same 1,996-record dir: full parse 821 ms → stat-only pass 18 ms (45×) →
+ * `readdir` alone 2.8 ms (290×).
+ *
+ * Two deliberate belts on that invariant, because a wrong unread badge is worse
+ * than a slow one:
+ *
+ * 1. **An entry is only cached once its record has a `finished_at`.** Anything
+ *    still running (or half-written, or corrupt) is re-read on every scan, so a
+ *    mid-turn record can never be memoized as if it were final. That is the one
+ *    mutable case, and it is tiny — 4 of 1,996 records on the production corpus.
+ * 2. **The cache key is `mtimeMs` AND `size`**, not mtime alone (core's
+ *    `AttributionIndexBuilder` uses mtime only). `mtimeMs` carries sub-millisecond
+ *    precision here, and adding size closes the theoretical same-tick rewrite.
+ *
+ * Entries for files that have disappeared are dropped each scan, so the cache
+ * tracks the directory rather than growing without bound: it holds one ~100-byte
+ * tuple per record, never the 24.5 KB average record body (97.3% of which is
+ * `prompt`/`summary` prose no caller reads).
+ *
+ * ## Why not reuse core's index
+ *
+ * `@herdctl/core` exports {@link AttributionIndexBuilder}, which keeps exactly
+ * this kind of mtime-keyed `jobFileCache` — but its public `AttributionIndex`
+ * surfaces only `getAttribute(sessionId) -> { origin, agentName, triggerType }`.
+ * It carries **no `finished_at`** and cannot enumerate its sessions, so it cannot
+ * answer "the latest completed turn per session" at all. The only core API that
+ * returns whole records, `listJobs`, is itself uncached (herdctl#415). So this
+ * reuses core's *pattern* — the shape it validated — rather than its *code*.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+/** The shared jobs directory herdctl writes `job-*.yaml` records into. */
+export function jobsDirOf(stateDir) {
+    return path.join(stateDir, "jobs");
+}
+/**
+ * An incremental view of one jobs directory.
+ *
+ * One instance per {@link import("./herdctl.js").HerdctlService} (mirroring core's
+ * "a single builder instance must be reused across builds to get the benefit"),
+ * so a test server, a fork of the app, and production each get their own — no
+ * module-level state keyed by path.
+ */
+export class JobsDirIndex {
+    cache = new Map();
+    inFlight = null;
+    jobsDir;
+    /**
+     * Diagnostics only (exercised by tests): scans performed, and files parsed /
+     * reused on the last scan, plus how many files the cache currently tracks.
+     */
+    stats = { scans: 0, parsed: 0, reused: 0, tracked: 0 };
+    constructor(stateDir) {
+        this.jobsDir = jobsDirOf(stateDir);
+    }
+    /**
+     * Every completed, session-resolved job record in the directory, in no
+     * particular order.
+     *
+     * Concurrent callers COALESCE onto one scan: the `/projects` grid fires seven
+     * parallel `/chats` requests, and running seven identical directory passes
+     * helps nobody. A caller that arrives mid-scan therefore observes the directory
+     * as of that scan's `readdir` — at most one scan (~20 ms) stale, against the
+     * ~850 ms of drift the un-indexed version already had between its own `readdir`
+     * and its last parse. A call made AFTER a write always sees that write.
+     *
+     * Never throws: an unreadable directory yields `[]`, and an unreadable or
+     * half-written record is skipped, exactly as before.
+     */
+    async read() {
+        if (this.inFlight)
+            return this.inFlight;
+        const scan = this.scan();
+        this.inFlight = scan;
+        try {
+            return await scan;
+        }
+        finally {
+            if (this.inFlight === scan)
+                this.inFlight = null;
+        }
+    }
+    /**
+     * Forget everything, forcing the next {@link read} to re-parse.
+     *
+     * The mtime+size key already self-heals after Paddock's own jobs-dir writes
+     * (`reattributeSession` rewrites records, `writeAgentAdoptionJob` adds them),
+     * so this is belt-and-braces called alongside the existing
+     * `invalidateSessions` at those sites — it makes the freshness guarantee
+     * independent of filesystem timestamp granularity.
+     */
+    invalidate() {
+        this.cache.clear();
+    }
+    async scan() {
+        let names;
+        try {
+            names = await fs.readdir(this.jobsDir);
+        }
+        catch {
+            // No jobs dir yet (fresh instance). Drop any stale entries with it.
+            this.cache.clear();
+            return [];
+        }
+        this.stats.scans++;
+        let parsed = 0;
+        let reused = 0;
+        // Only `.yaml` records are candidates — the sibling `.jsonl` output files are
+        // half the directory and are never stat'd, let alone read.
+        const yamls = names.filter((n) => n.endsWith(".yaml"));
+        const out = [];
+        await Promise.all(yamls.map(async (name) => {
+            const file = path.join(this.jobsDir, name);
+            let st;
+            try {
+                st = await fs.stat(file);
+            }
+            catch {
+                return; // vanished between readdir and stat
+            }
+            const cached = this.cache.get(name);
+            if (cached && cached.mtimeMs === st.mtimeMs && cached.size === st.size) {
+                reused++;
+                if (cached.entry)
+                    out.push(cached.entry);
+                return;
+            }
+            parsed++;
+            const entry = await parseJobFile(file);
+            // Only a COMPLETED record is immutable, so only a completed record is
+            // safe to memoize. A running/half-written/corrupt one is re-read next
+            // scan — there are a handful of those, and being wrong about one would
+            // freeze a chat's unread state.
+            if (entry)
+                this.cache.set(name, { mtimeMs: st.mtimeMs, size: st.size, entry });
+            else
+                this.cache.delete(name);
+            if (entry)
+                out.push(entry);
+        }));
+        // Track the directory: forget files that are no longer there, so the cache
+        // stays the size of the dir rather than growing across a process's lifetime.
+        // (Unconditional — comparing sizes first would miss a scan that deletes and
+        // adds the same number of files, for no measurable saving.)
+        const present = new Set(yamls);
+        for (const name of this.cache.keys())
+            if (!present.has(name))
+                this.cache.delete(name);
+        this.stats.parsed = parsed;
+        this.stats.reused = reused;
+        this.stats.tracked = this.cache.size;
+        return out;
+    }
+}
+/**
+ * Return a standalone copy of a string.
+ *
+ * The `yaml` parser produces scalars by slicing the whole document text, and V8
+ * represents those as SlicedStrings that keep the entire ~24 KB source alive. So
+ * caching a scalar verbatim retains the record body this index exists to avoid
+ * holding — the ~100-byte tuple promised above is really 24.5 KB.
+ *
+ * Measured over this instance's 2,016 records: **95.6 MB retained verbatim
+ * versus 1.8 MB detached**, a 53× overhead for identical data (issue #543).
+ * Core's own job index hit this and fixed it the same way
+ * (`state/job-index.ts` `detachString`, measured there at 99 MB → 2.1 MB); this
+ * matches that implementation deliberately rather than inventing a variant.
+ */
+function detachString(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * Parse one `job-*.yaml` down to the three fields the index keeps.
+ *
+ * Returns `null` — meaning "nothing to index, and nothing to cache" — for a
+ * record that is unreadable, half-written, still running (`finished_at` unset),
+ * or not yet session-resolved. That is the same skip the un-indexed scan applied;
+ * it never throws.
+ *
+ * Every retained string is {@link detachString}'d: these three scalars outlive
+ * the parse, and holding them verbatim pins the whole source document.
+ */
+async function parseJobFile(file) {
+    let parsedYaml = null;
+    try {
+        parsedYaml = YAML.parse(await fs.readFile(file, "utf8"));
+    }
+    catch {
+        return null; // skip an unreadable/half-written record
+    }
+    const sid = parsedYaml?.session_id;
+    const finished = parsedYaml?.finished_at;
+    if (typeof sid !== "string" || typeof finished !== "string")
+        return null;
+    const agent = parsedYaml?.agent;
+    return {
+        sessionId: detachString(sid),
+        finishedAt: detachString(finished),
+        agent: typeof agent === "string" ? detachString(agent) : null,
+    };
+}

package/packages/server/dist/herdctl-jobs.d.ts

@@ -0,0 +1,98 @@
+import { type JobMetadata } from "@herdctl/core";
+import type { Project } from "./projects.js";
+import { type JobsDirIndex } from "./herdctl-jobs-index.js";
+/**
+ * Map each chat session id to the ISO timestamp of its most recent COMPLETED
+ * turn, read cheaply from herdctl's job-metadata records (NOT by parsing
+ * transcripts). In `batch` drive mode every keeper turn runs via `trigger()`,
+ * which writes a `job-*.yaml` whose `finished_at` is stamped when the turn
+ * finishes and whose `session_id` is filled in on completion — so the latest
+ * `finished_at` across a session's records is exactly "the agent last finished a
+ * turn." NOTE the default drive mode is `session`, whose turns write NO job
+ * record (see the caveat on {@link listProjectRuns}); on that path this map is
+ * fed only by paddock's synthetic adoption records. This is the server signal
+ * for the unread affordance (#160, reused per-project by #161): unlike the
+ * transcript mtime (`DiscoveredSession.mtime`) it does NOT tick on the user's
+ * own sends.
+ *
+ * Records still running (no `finished_at`) or not yet session-resolved (no
+ * `session_id`) are skipped. The synthetic adoption records paddock writes
+ * carry an earlier, mid-turn `finished_at`, so the max naturally prefers the
+ * real completion. Session-mode turns (`openChatSession`) write no job record,
+ * so their chats have no server timestamp and rely on the client live event.
+ *
+ * Reads through {@link JobsDirIndex}, which keeps the parse incremental
+ * (mtime+size keyed, completed records only) — see there for why that is safe
+ * and what it is worth. This function itself is a pure fold over the index.
+ */
+export declare function lastTurnCompletedAt(index: JobsDirIndex): Promise<Map<string, string>>;
+/**
+ * Per-project variant of {@link lastTurnCompletedAt} for the sidebar unread
+ * badge (#161): group the same cheap job-record scan by the KEEPER agent that
+ * owns each session, so the projects-list payload can carry a compact
+ * `{ sessionId, lastTurnCompletedAt }` list per project WITHOUT the N+1
+ * `listSessions` fan-out or any transcript parse. Returns `slug -> (sessionId
+ * -> latest finished_at)`.
+ *
+ * Only keeper-attributed records (`agent: keeper-<slug>`) are kept — sweeper,
+ * trigger and hook records carry their own session ids that are not chats, so
+ * `keeperSlugFromAgent` returning `null` naturally filters them out. A promoted
+ * chat is grouped under its keeper slug (its keeper record).
+ */
+export declare function lastTurnCompletedAtByProject(index: JobsDirIndex): Promise<Map<string, Map<string, string>>>;
+/**
+ * The raw herdctl job records for one project's keeper agent, most-recent
+ * first — the data source for the "while you were away" run-history view (E3 /
+ * #268 / DD-6). Each `trigger()` (batch drive mode) turn writes one
+ * `job-*.yaml` carrying `trigger_type`, `status`, `started_at`/`finished_at`,
+ * `duration_seconds`, `session_id`, `schedule` and `forked_from`; this reads
+ * them via core's `listJobs` (importable from `@herdctl/core`, sorted by
+ * `started_at` descending) filtered to `keeper-<slug>`, so sweeper/trigger
+ * records are excluded.
+ *
+ * The true human/scheduled/spawned provenance is carried by Paddock's
+ * {@link RunProvenanceStore} (origin/depth keyed by `session_id`), NOT by
+ * `trigger_type` — paddock-initiated turns still write `trigger_type:"manual"`
+ * (see ws.ts). The caller joins the two.
+ *
+ * Caveat (documented at {@link lastTurnCompletedAt}): session-mode turns
+ * (`openChatSession`) write NO job record, so runs driven that way don't
+ * appear here — only batch `trigger()` turns and paddock's synthetic adoption
+ * records do. Cost columns (DD-4) are P3 and not yet on the record.
+ */
+export declare function listProjectRuns(stateDir: string, project: Project, limit?: number): Promise<JobMetadata[]>;
+/**
+ * Job records for a SET of agents, most-recent first (Epic T follow-up / #327) —
+ * the data source for the Triggers tab's per-trigger last-run column. Used to pull
+ * one project's keeper AND every scoped `trigger-<slug>-<name>` agent in a single
+ * pass so {@link import("./trigger-runtime.js").buildTriggerRuntime} can attribute a
+ * scoped trigger's newest run by agent name. `listJobs` has no multi-agent filter,
+ * so this scans the jobs dir once (unfiltered) and keeps only the requested agents;
+ * order (started_at descending) is preserved. Errors swallow to `[]` so the runtime
+ * view degrades to config-only rather than failing to render.
+ */
+export declare function listRunsForAgents(stateDir: string, agents: string[], limit?: number): Promise<JobMetadata[]>;
+/**
+ * Point every herdctl job record for `sessionId` at the project's keeper so
+ * the core attribution index (last-write-wins per session) lists the session
+ * under the project. A session can already have MANY job records (one per
+ * turn) attributed elsewhere; simply adding a keeper record alongside them is
+ * not enough — whichever record the index visits last wins. So we rewrite the
+ * `agent` field of all existing records for the session. When none exist
+ * (e.g. a transcript migrated from outside paddock), we synthesize one.
+ */
+export declare function reattributeSession(stateDir: string, sessionId: string, project: Project, when: Date): Promise<void>;
+/**
+ * Write a herdctl job-metadata YAML mapping `sessionId -> keeper agent` so the
+ * core attribution index lists the session under the project. Mirrors the shape
+ * of a real job record (and the JobMetadataSchema: the id must match
+ * `job-YYYY-MM-DD-[a-z0-9]{6}`).
+ */
+export declare function writeAdoptionJob(stateDir: string, sessionId: string, project: Project, when: Date): Promise<void>;
+/**
+ * Underlying adoption-record writer, parametrized by the target agent name so
+ * every caller (fork/promote/adopt — see {@link attributeRunningSession}) shares
+ * one implementation. Writes a `<jobId>.yaml` mapping the
+ * session id to `agentName` plus a matching empty `.jsonl` output file.
+ */
+export declare function writeAgentAdoptionJob(stateDir: string, sessionId: string, agentName: string, when: Date): Promise<void>;