@edspencer/paddock 0.0.1 → 0.57.0

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

@@ -0,0 +1,42 @@
+/**
+ * Encode a working directory the way Claude Code names its transcript dir.
+ * For paths under 200 chars this is just the non-alphanumeric→'-' replacement
+ * (paddock's project dirs are always short, so the truncate+hash branch Claude
+ * Code uses for very long paths never applies here).
+ */
+export declare function encodeProjectDir(dir: string): string;
+/** Absolute path to the project's local transcript directory. */
+export declare function projectChatsDir(projectDir: string): string;
+/**
+ * Ensure `<chatsHostDir>/.chats/` exists and that Claude Code's encoded
+ * transcript path for `workingDir` is a symlink pointing at it (migrating an
+ * existing real transcript dir in the process). Safe to call on every agent
+ * registration. Never throws — a failure here must not block agent registration
+ * or chat.
+ *
+ * `workingDir` is the agent's cwd (which Claude encodes into the transcript dir
+ * name); `chatsHostDir` is where the `.chats/` store actually lives. For a
+ * notebook project these are the same dir (the default). For a REPO-BACKED
+ * project (issue #187) the keeper's cwd is the nested checkout but the `.chats/`
+ * store stays in the project's metadata dir (the data repo) — so transcripts
+ * never pollute the external repo's working tree — hence the two are split.
+ *
+ * `claudeHomePath` is the Claude home to plant the symlink in. Callers holding a
+ * config MUST pass `cfg.claudeHome` (#588): the engine is constructed with that
+ * same resolved value, and a symlink planted in a different home than the one
+ * the engine reads is exactly the "chats list but open empty" failure. The
+ * env-derived default is kept only for callers with no config (unit tests).
+ */
+export declare function ensureProjectChats(workingDir: string, chatsHostDir?: string, claudeHomePath?: string): Promise<void>;
+/**
+ * Read a session's FIRST user message text, untruncated, straight from its
+ * transcript JSONL (issue #62). Claude Code's own `preview` is capped at 100
+ * chars — for a preload chat that cap falls inside the injected OVERVIEW block,
+ * so the preview can't be un-wrapped. Reading the full first user message lets
+ * the chat-list strip the wrapper and show the user's real request.
+ *
+ * Streams line-by-line and stops at the first user text, so it only reads the
+ * head of the file. Returns undefined if the transcript is missing/unreadable or
+ * has no user text. The sessionId is validated to keep it inside `.chats/`.
+ */
+export declare function readFirstUserText(projectDir: string, sessionId: string): Promise<string | undefined>;

package/packages/server/dist/transcripts.js

@@ -0,0 +1,164 @@
+/**
+ * Transcript relocation (backing-store Phase 3).
+ *
+ * Claude Code writes a session transcript to `~/.claude/projects/<encoded-cwd>/`,
+ * where `<encoded-cwd>` is the agent's absolute working directory with every
+ * non-[A-Za-z0-9] char replaced by '-'. That makes transcripts path-coupled and
+ * not portable. We relocate them INTO the project by making the encoded path a
+ * **symlink to `<projectDir>/.chats/`** — Claude then writes through the symlink
+ * into the project dir (validated empirically), and herdctl's discovery, resume,
+ * delete and rename all resolve through it transparently. The project dir becomes
+ * self-contained and travels with the repo / NAS.
+ *
+ * `ensureProjectChats` is idempotent and self-healing: on first run for a project
+ * whose encoded path is still a real directory (existing transcripts), it migrates
+ * those files into `.chats/` and replaces the directory with the symlink.
+ */
+import { promises as fs, createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+import path from "node:path";
+import { claudeHome } from "./config.js";
+/**
+ * Encode a working directory the way Claude Code names its transcript dir.
+ * For paths under 200 chars this is just the non-alphanumeric→'-' replacement
+ * (paddock's project dirs are always short, so the truncate+hash branch Claude
+ * Code uses for very long paths never applies here).
+ */
+export function encodeProjectDir(dir) {
+    return dir.replace(/[^a-zA-Z0-9]/g, "-");
+}
+/** Absolute path to the project's local transcript directory. */
+export function projectChatsDir(projectDir) {
+    return path.join(projectDir, ".chats");
+}
+/**
+ * Ensure `<chatsHostDir>/.chats/` exists and that Claude Code's encoded
+ * transcript path for `workingDir` is a symlink pointing at it (migrating an
+ * existing real transcript dir in the process). Safe to call on every agent
+ * registration. Never throws — a failure here must not block agent registration
+ * or chat.
+ *
+ * `workingDir` is the agent's cwd (which Claude encodes into the transcript dir
+ * name); `chatsHostDir` is where the `.chats/` store actually lives. For a
+ * notebook project these are the same dir (the default). For a REPO-BACKED
+ * project (issue #187) the keeper's cwd is the nested checkout but the `.chats/`
+ * store stays in the project's metadata dir (the data repo) — so transcripts
+ * never pollute the external repo's working tree — hence the two are split.
+ *
+ * `claudeHomePath` is the Claude home to plant the symlink in. Callers holding a
+ * config MUST pass `cfg.claudeHome` (#588): the engine is constructed with that
+ * same resolved value, and a symlink planted in a different home than the one
+ * the engine reads is exactly the "chats list but open empty" failure. The
+ * env-derived default is kept only for callers with no config (unit tests).
+ */
+export async function ensureProjectChats(workingDir, chatsHostDir = workingDir, claudeHomePath = claudeHome()) {
+    try {
+        const chatsDir = projectChatsDir(chatsHostDir);
+        await fs.mkdir(chatsDir, { recursive: true });
+        const encoded = path.join(claudeHomePath, "projects", encodeProjectDir(workingDir));
+        await fs.mkdir(path.dirname(encoded), { recursive: true });
+        const st = await fs.lstat(encoded).catch(() => null);
+        // Already a symlink — point it at .chats if it drifted, else done.
+        if (st?.isSymbolicLink()) {
+            const target = await fs.readlink(encoded).catch(() => "");
+            const resolved = path.resolve(path.dirname(encoded), target);
+            if (resolved !== path.resolve(chatsDir)) {
+                await fs.rm(encoded, { force: true });
+                await fs.symlink(chatsDir, encoded);
+            }
+            return;
+        }
+        // A real directory of existing transcripts — migrate into .chats, then link.
+        if (st?.isDirectory()) {
+            for (const entry of await fs.readdir(encoded)) {
+                const from = path.join(encoded, entry);
+                const to = path.join(chatsDir, entry);
+                if (await fs.lstat(to).then(() => true).catch(() => false))
+                    continue; // don't clobber
+                // cp+rm is robust across filesystems (rename would EXDEV across mounts).
+                // `preserveTimestamps` is load-bearing, not cosmetic (#588): fs.cp
+                // defaults to stamping the copy with NOW, and a transcript's mtime is
+                // both the chat-list sort key and the cache key for auto-name / preview /
+                // sidechain detection — so without it, relocating a months-old archive
+                // collapses every one of those chats to "today".
+                await fs.cp(from, to, { recursive: true, preserveTimestamps: true });
+                await fs.rm(from, { recursive: true, force: true });
+            }
+            await fs.rmdir(encoded).catch(() => undefined);
+            await fs.symlink(chatsDir, encoded);
+            return;
+        }
+        // Nothing there yet — just create the symlink so future turns land in .chats.
+        await fs.symlink(chatsDir, encoded);
+    }
+    catch {
+        /* non-fatal: fall back to Claude Code's default location for this project */
+    }
+}
+/**
+ * Read a session's FIRST user message text, untruncated, straight from its
+ * transcript JSONL (issue #62). Claude Code's own `preview` is capped at 100
+ * chars — for a preload chat that cap falls inside the injected OVERVIEW block,
+ * so the preview can't be un-wrapped. Reading the full first user message lets
+ * the chat-list strip the wrapper and show the user's real request.
+ *
+ * Streams line-by-line and stops at the first user text, so it only reads the
+ * head of the file. Returns undefined if the transcript is missing/unreadable or
+ * has no user text. The sessionId is validated to keep it inside `.chats/`.
+ */
+export async function readFirstUserText(projectDir, sessionId) {
+    if (!/^[A-Za-z0-9._-]+$/.test(sessionId))
+        return undefined;
+    const file = path.join(projectChatsDir(projectDir), `${sessionId}.jsonl`);
+    const stream = createReadStream(file, { encoding: "utf8" });
+    // A missing/unreadable file rejects on the stream; swallow and return undefined.
+    stream.on("error", () => undefined);
+    const rl = createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+        for await (const line of rl) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(trimmed);
+            }
+            catch {
+                continue;
+            }
+            if (parsed.type !== "user")
+                continue;
+            const text = extractUserText(parsed.message?.content);
+            if (text)
+                return text;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        rl.close();
+        stream.destroy();
+    }
+    return undefined;
+}
+/**
+ * Text of a transcript user message's `content` (string, or an array of blocks).
+ * A message carrying tool_result blocks isn't a real prompt — return "" so the
+ * caller skips it.
+ */
+function extractUserText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    if (content.some((b) => b?.type === "tool_result"))
+        return "";
+    return content
+        .filter((b) => {
+        const blk = b;
+        return blk?.type === "text" && typeof blk.text === "string";
+    })
+        .map((b) => b.text)
+        .join("");
+}

package/packages/server/dist/trigger-config.d.ts

@@ -0,0 +1,278 @@
+import { z } from "zod";
+/** The trigger kinds. `webhook` is shape-reserved (no ingress in T1 — deferred T6). */
+export declare const TRIGGER_TYPES: readonly ["schedule", "event", "webhook"];
+export type TriggerType = (typeof TRIGGER_TYPES)[number];
+/**
+ * The lifecycle events an `event`-type trigger may fire on. `onArchive` is wired
+ * (fired after a chat-archive commits — the Epic G motivating cleanup). `afterTurn`
+ * is a KNOWN value (validation accepts it) reserved for the sweeper fold-in (T5) —
+ * it validates + persists now but isn't emitted until then, exactly as `webhook` is
+ * shape-reserved. Adding a sibling event stays a ~3-line change (new value here + a
+ * payload + one `emit()` at the commit site).
+ */
+export declare const TRIGGER_EVENTS: readonly ["onArchive", "afterTurn"];
+export type TriggerEvent = (typeof TRIGGER_EVENTS)[number];
+/** New-vs-accrete for a fired trigger (design §2.3). */
+export type TriggerSession = "new" | "resume";
+/** Claude Code permission mode a trigger agent's turns run under. */
+export type TriggerPermissionMode = "default" | "acceptEdits" | "bypassPermissions" | "plan";
+/** The dir (relative to a project's working dir) holding keeper-editable prompts. */
+export declare const TRIGGER_PROMPT_DIR: string;
+/** Default max agent turns for a trigger when its run doesn't set one. */
+export declare const TRIGGER_DEFAULT_MAX_TURNS = 30;
+/**
+ * The canonical name of the built-in post-turn CURATOR trigger — the sweeper folded
+ * in as the default `event`/`afterTurn` trigger (T5, design §2.1 #4). A project need
+ * NOT declare it: absent, the curator runs with default behaviour (exactly the shipped
+ * sweeper). Declaring a `curate-overview` trigger only CUSTOMISES that default (extend
+ * its prompt, override its model, or `enabled: false` to switch curation off). Resolved
+ * by NAME as a convenience, but recognised structurally by {@link isCuratorTrigger}.
+ */
+export declare const CURATE_TRIGGER_NAME = "curate-overview";
+/**
+ * The frozen trigger schema: `trigger` (discriminated union) + `run` + `enabled`.
+ * Two cross-field refinements the discriminatedUnion can't express inline:
+ *  - a `schedule` trigger requires EXACTLY ONE of `cron` / `interval`;
+ *  - `run` requires EXACTLY ONE of `prompt` / `promptFile`.
+ *
+ * `enabled` **defaults `false`** — a trigger created programmatically (or via a
+ * hand-edit that omits it) is inert until deliberately switched on (design §2.3,
+ * mirroring the Epic G safe-create default).
+ */
+export declare const PaddockTriggerSchema: z.ZodObject<{
+    trigger: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"schedule">;
+        cron: z.ZodOptional<z.ZodString>;
+        interval: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"event">;
+        on: z.ZodEnum<{
+            onArchive: "onArchive";
+            afterTurn: "afterTurn";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"webhook">;
+        path: z.ZodString;
+    }, z.core.$strip>], "type">;
+    run: z.ZodObject<{
+        prompt: z.ZodOptional<z.ZodString>;
+        promptFile: z.ZodOptional<z.ZodString>;
+        session: z.ZodDefault<z.ZodEnum<{
+            new: "new";
+            resume: "resume";
+        }>>;
+        model: z.ZodOptional<z.ZodString>;
+        tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        maxSpawnDepth: z.ZodOptional<z.ZodNumber>;
+        permissionMode: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            acceptEdits: "acceptEdits";
+            plan: "plan";
+            bypassPermissions: "bypassPermissions";
+        }>>;
+        maxTurns: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/** A validated trigger — the persisted per-project record (`project.yaml` `triggers`). */
+export type PaddockTrigger = z.infer<typeof PaddockTriggerSchema>;
+/** The `when` discriminated union, on its own (WHEN a trigger fires). */
+export type TriggerWhen = PaddockTrigger["trigger"];
+/** The `schedule` variant of {@link TriggerWhen}. */
+export type ScheduleTriggerWhen = Extract<TriggerWhen, {
+    type: "schedule";
+}>;
+/** The `event` variant of {@link TriggerWhen}. */
+export type EventTriggerWhen = Extract<TriggerWhen, {
+    type: "event";
+}>;
+/** The `webhook` variant of {@link TriggerWhen}. */
+export type WebhookTriggerWhen = Extract<TriggerWhen, {
+    type: "webhook";
+}>;
+/** The shared agent-run definition (WHAT a fired trigger does). */
+export type TriggerRun = PaddockTrigger["run"];
+/**
+ * The CRUD/DTO shape the trigger service ({@link import("./triggers.js").TriggerService})
+ * returns — a {@link PaddockTrigger} plus its map key `name` and the deterministic
+ * herdctl agent it registers as (`trigger-<slug>-<name>`). This is the frozen contract
+ * T2–T5 build against (the analogue of the shipped `HookDto`).
+ */
+export type TriggerDto = PaddockTrigger & {
+    /** The trigger's name — the `project.yaml` map key + the `<name>` in its agent name. */
+    name: string;
+    /** The herdctl agent this trigger registers as (`trigger-<slug>-<name>`). */
+    agentName: string;
+};
+/** A trigger name we're willing to key on (also a safe herdctl agent-name segment). */
+export declare function isValidTriggerName(name: string): boolean;
+/**
+ * Validate + normalise one untrusted trigger record into a {@link PaddockTrigger},
+ * or `null` if it's malformed (bad discriminant, both/neither cron+interval, unknown
+ * `on`, both/neither prompt+promptFile, …). Defaults are applied (`enabled: false`,
+ * `session: "new"`, `tools: []`). Unknown fields are stripped (Zod default).
+ */
+export declare function sanitizeTrigger(raw: unknown): PaddockTrigger | null;
+/**
+ * Sanitise a whole `triggers` map, DROPPING malformed entries and entries with an
+ * unsafe name — so one bad hand-edit can't brick the project's agent registration
+ * (an invalid trigger agent config would throw in `addAgent`). Returns `undefined`
+ * when nothing survives (so it stays absent on disk / off the project record),
+ * exactly like its `sanitizeHooks` / `sanitizeSchedules` ancestors.
+ */
+export declare function sanitizeTriggers(raw: unknown): Record<string, PaddockTrigger> | undefined;
+/**
+ * Overlay a PARTIAL trigger update onto an existing trigger, producing an untrusted
+ * record for {@link sanitizeTrigger} to validate — the unified successor to
+ * {@link import("./hook-config.js").mergeHookUpdate}, used by the self-MCP `set_trigger`
+ * tool so an edit that supplies only some fields (the classic being "enable/disable",
+ * an `enabled`-only set — GG-3) preserves everything else rather than wiping it.
+ *
+ * The three parts merge independently:
+ *  - `trigger` (the WHEN discriminant): supplied wholesale or inherited. Because the
+ *    variants carry different fields (`cron`/`interval` vs `on` vs `path`), a partial
+ *    trigger can't be merged field-by-field — so `incoming.trigger` is taken WHOLE
+ *    when the caller supplies one (i.e. re-specifies `type` + its fields), else the
+ *    existing `trigger` is inherited unchanged.
+ *  - `run` (the WHAT): merged field-by-field over the existing run, so an edit that
+ *    touches only `enabled`/`model`/`tools` keeps the rest. `prompt` and `promptFile`
+ *    are MUTUALLY EXCLUSIVE, so supplying one clears the inherited counterpart —
+ *    otherwise switching a file-backed trigger to an inline prompt would leave the
+ *    stale `promptFile` and the merged record would carry BOTH (rejected by the
+ *    schema's prompt-xor-promptFile refinement). Supplying neither leaves the prompt
+ *    source untouched.
+ *  - `enabled`: the supplied value, else the existing flag, else `false` (safe-create).
+ *
+ * A brand-new trigger (`existing` null) starts from the incoming record verbatim
+ * (its `trigger`/`run` must be complete — the schema rejects it otherwise).
+ */
+export declare function mergeTriggerUpdate(existing: PaddockTrigger | null | undefined, incoming: {
+    trigger?: Record<string, unknown>;
+    run?: Record<string, unknown>;
+    enabled?: boolean;
+}): Record<string, unknown>;
+/**
+ * Whether a trigger runs on its OWN scoped `trigger-<slug>-<name>` agent (so
+ * {@link triggerToAgentToolConfig} governs its capability) rather than as the keeper.
+ *
+ *  - **event** → ALWAYS its own agent (Epic G / T1). Its `tools` allow-list IS the
+ *    capability; an empty `[]` means a deliberately tool-less curator.
+ *  - **schedule** → its own scoped agent ONLY when it declares a NON-EMPTY `run.tools`
+ *    allow-list (T2 — the per-trigger tool-scoping this ticket adds). A schedule with NO
+ *    tools inherits the project agent's default toolset by running as the keeper,
+ *    preserving the pre-T2 behaviour (ticket #307: "a schedule with no tools inherits
+ *    the project-agent default"). This is the one asymmetry with events — a schedule's
+ *    empty `tools` reads as "unscoped, run as keeper", NOT "tool-less curator", because
+ *    schedules historically ran with the keeper's full tools and there are no users to
+ *    migrate off that default.
+ *  - **webhook** → reserved (never fired in T1), so it registers no agent.
+ *
+ * The ONE place the keeper-vs-own-agent routing decision lives, shared by the herdctl
+ * agent registration ({@link import("./herdctl.js").HerdctlService.registerTriggerAgents})
+ * and the fire path (`fireTriggerForProject` in `ws.ts`) so arming and firing always agree.
+ */
+export declare function triggerRunsOnOwnAgent(trigger: PaddockTrigger): boolean;
+/**
+ * Whether a trigger is the post-turn CURATOR (the folded-in sweeper, T5): an
+ * `event`/`afterTurn` trigger. The curator is SPECIAL — it does NOT run as a generic
+ * `trigger-<slug>-<name>` agent turn. It is tool-less by nature (returns marked text,
+ * Paddock's `SweepService` parses it and writes OVERVIEW.md/CHANGELOG.md), so it is
+ * executed by the SweepService via the project's `sweeper-<slug>` agent, NOT by the
+ * event dispatcher and NOT by its own herdctl agent. Its `run` therefore only tunes the
+ * sweep (prompt extension, model, `enabled`), which is why (unlike every OTHER event
+ * trigger — see {@link triggerRunsOnOwnAgent}) a curator trigger registers NO scoped
+ * agent and is skipped by the generic fire path. This keeps the sweeper's single
+ * dispatch (no double-curation): the `afterTurn` event → SweepService, once.
+ */
+export declare function isCuratorTrigger(trigger: PaddockTrigger): boolean;
+/**
+ * Resolve a project's post-turn CURATOR trigger from its `triggers` map (T5) — the
+ * canonical {@link CURATE_TRIGGER_NAME} if it IS a curator, else the first structural
+ * curator ({@link isCuratorTrigger}) declared. `null` when the project declares none
+ * (the IMPLICIT built-in default — an un-customised project sweeps exactly as the
+ * shipped sweeper). Pure, so both `SweepService` (enabled gate + prompt extension) and
+ * `HerdctlService` (sweeper model override) resolve the ONE curator the same way.
+ */
+export declare function curatorTriggerOf(triggers: Record<string, PaddockTrigger> | undefined): PaddockTrigger | null;
+/**
+ * Project a trigger's {@link TriggerRun} onto the exact herdctl agent tool-config
+ * fields (snake_case), so an event/webhook trigger's OWN `trigger-<slug>-<name>`
+ * agent enforces the capability BY CONSTRUCTION. Always sets `allowed_tools` +
+ * `max_turns` so a trigger agent never silently inherits the keeper's broad default
+ * toolset; a tool-less trigger yields `allowed_tools: []` (the CLI runtime then
+ * denies every tool). The ONE place run→agent-config translation lives. (The exact
+ * analogue of `hookToAgentToolConfig`.)
+ */
+export declare function triggerToAgentToolConfig(run: TriggerRun): Record<string, unknown>;
+/**
+ * Project ONE schedule-type trigger onto the herdctl `ScheduleSchema` fields the
+ * cron engine reads (`type` `cron`|`interval`, the timer field, `resume_session`,
+ * `enabled`), for forwarding into the keeper agent's `schedules` block. The
+ * Paddock-only prompt (inline/`promptFile`) is resolved at fire time by the trigger
+ * handler, so herdctl only ever sees a plain `prompt` (or none) — kept pure. The
+ * `resume_session` flag is derived from `run.session` so herdctl's own new-vs-accrete
+ * stays in agreement with Paddock's (the handler still owns the OWNED-session sidecar).
+ */
+export declare function scheduleTriggerToHerdctl(when: ScheduleTriggerWhen, run: TriggerRun, enabled: boolean): Record<string, unknown>;
+/**
+ * Build the `schedules` block to forward into the keeper agent config from a
+ * project's SCHEDULE-type triggers, or `undefined` when it declares none. Non-schedule
+ * triggers (event/webhook) are skipped — they don't arm the cron engine. Keyed by
+ * trigger name (the same key the fire handler resolves back to a trigger).
+ */
+export declare function triggersToHerdctlSchedules(map: Record<string, PaddockTrigger> | undefined): Record<string, Record<string, unknown>> | undefined;
+/**
+ * The compact, web-facing capability descriptor for a TRIGGER chat (Epic T / T4 —
+ * the unified successor to {@link import("./hook-config.js").ChatHookInfo}). Rides on
+ * the chat DTO whenever a chat's attributed agent is a `trigger-<slug>-<name>` agent,
+ * so the floating capability banner can state — TRUTHFULLY FROM CONFIG — what the
+ * trigger agent is: its trigger {@link type} (schedule / event / webhook) and WHEN it
+ * fires (an event `on`, a `cron`/`interval`, or a webhook `path`), its herdctl agent
+ * name, whether it's armed, and the exact tool grant herdctl enforces on its turns.
+ * Built by {@link toChatTriggerInfo} from the same {@link TriggerRun} that
+ * {@link triggerToAgentToolConfig} projects onto the registered agent, so the banner
+ * and the enforced capability can never disagree.
+ */
+export interface ChatTriggerInfo {
+    /** The trigger's name (`project.yaml` map key + the `<name>` in its agent name). */
+    name: string;
+    /** WHICH kind of trigger fires this chat (schedule / event / webhook). */
+    type: TriggerType;
+    /** For an `event` trigger: the lifecycle event that fires it (`onArchive`/`afterTurn`). */
+    event?: TriggerEvent;
+    /** For a `schedule` trigger: the cron expression, when timer-driven by cron. */
+    cron?: string;
+    /** For a `schedule` trigger: the interval string, when timer-driven by interval. */
+    interval?: string;
+    /** For a `webhook` trigger: the reserved ingress path. */
+    path?: string;
+    /** The herdctl agent enforcing the capability (`trigger-<slug>-<name>`). */
+    agentName: string;
+    /** Whether the trigger is armed (a disabled trigger's past chats are still shown). */
+    enabled: boolean;
+    /** The exact tool grant (herdctl `allowed_tools`); `[]` = a tool-less trigger. */
+    allowedTools: string[];
+    /** The permission mode the trigger's turns run under, when it sets one. */
+    permissionMode?: TriggerPermissionMode;
+    /** The trigger agent's model override, when set (else the keeper default applies). */
+    model?: string;
+    /** The trigger's max agent turns (its runaway bound). */
+    maxTurns: number;
+}
+/**
+ * Project a persisted trigger ({@link TriggerDto} fields) onto the web-facing
+ * {@link ChatTriggerInfo}, resolving the SAME capability defaults
+ * {@link triggerToAgentToolConfig} uses so the banner mirrors the enforced grant
+ * exactly: an absent/empty allow-list surfaces as a tool-less `[]`, and an unset
+ * `maxTurns` surfaces the {@link TRIGGER_DEFAULT_MAX_TURNS} bound herdctl applies.
+ * The WHEN fields are read off the discriminated `trigger` so the banner can state
+ * the trigger type and the exact firing condition.
+ */
+export declare function toChatTriggerInfo(dto: TriggerDto): ChatTriggerInfo;
+/**
+ * Resolve a `promptFile` to an absolute path under the project's `.paddock/triggers/`
+ * dir, or `null` if it escapes that dir, is absolute, or isn't a `.md` file. The name
+ * is treated as relative to the triggers dir (so a bare `"daily.md"` resolves to
+ * `<workingDir>/.paddock/triggers/daily.md`). Byte-for-byte the hook/schedule twin's guard.
+ */
+export declare function triggerPromptFileAbsPath(workingDir: string, promptFile: string): string | null;