@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/self-mcp-descriptions.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared schema description for the optional per-chat `model` override on the spawn
+ * tools (create_chat / fork_chat / fork_chat_batch, issue #336). Lists the valid
+ * ids from the SAME allow-list the web picker uses so the model stays in sync.
+ */
+export declare const MODEL_ARG_DESC: string;
+export declare const LIST_PROJECTS_DESC: string;
+export declare const LIST_CHATS_DESC: string;
+export declare const READ_CHAT_DESC: string;
+export declare const CREATE_CHAT_DESC: string;
+export declare const FORK_CHAT_DESC: string;
+export declare const SEND_MESSAGE_DESC: string;
+export declare const ARCHIVE_CHAT_DESC: string;
+export declare const UNARCHIVE_CHAT_DESC: string;
+export declare const FORK_CHAT_BATCH_DESC: string;
+export declare const CREATE_PROJECT_DESC: string;
+export declare const SET_TRIGGER_DESC: string;
+export declare const REMOVE_TRIGGER_DESC: string;
+export declare const RUN_TRIGGER_DESC: string;
+export declare const LIST_TRIGGERS_DESC: string;

package/packages/server/dist/self-mcp-descriptions.js

@@ -0,0 +1,145 @@
+/**
+ * Agent-facing tool descriptions for the Paddock self-management MCP (issue #214).
+ *
+ * The long `*_DESC` prose the injected tools surface to the keeper agent, plus the
+ * shared `MODEL_ARG_DESC` for the per-chat `model` override. Pure strings, split
+ * out of `self-mcp.ts` so the logic file isn't dominated by prose. Some interpolate
+ * the numeric caps from `self-mcp-util.ts` (which stay the single source of truth).
+ */
+import { MODELS } from "./models.js";
+import { FORK_BATCH_MAX, READ_CHAT_DEFAULT_LIMIT, READ_CHAT_MAX_LIMIT, READ_CHAT_MAX_TEXT, } from "./self-mcp-util.js";
+/**
+ * Shared schema description for the optional per-chat `model` override on the spawn
+ * tools (create_chat / fork_chat / fork_chat_batch, issue #336). Lists the valid
+ * ids from the SAME allow-list the web picker uses so the model stays in sync.
+ */
+export const MODEL_ARG_DESC = "Optional model for the spawned chat ONLY (not the project default). One of: " +
+    `${MODELS.map((m) => m.id).join(", ")}. Omit to inherit the project/box default.`;
+// ── Read tools ──────────────────────────────────────────────────────────────
+export const LIST_PROJECTS_DESC = "List all Paddock projects (across every area). Returns each project's slug, " +
+    "display name, area, and status. Use the slug to target `list_chats`/`read_chat`. " +
+    "Also returns `root`: the ROOT WORKSPACE — the instance's own top-level " +
+    "directory, which has chats of its own but is NOT a project and so is not in " +
+    '`projects`/`count`. Its key is the EMPTY STRING: pass `project: ""` to ' +
+    "`list_chats`/`read_chat` to target it.";
+export const LIST_CHATS_DESC = "List chats. Pass `project` (a workspace key) to list only that workspace's " +
+    "chats, or omit it to list chats across ALL workspaces — every project AND the " +
+    'root workspace. The ROOT workspace\'s key is the EMPTY STRING (`project: ""`), ' +
+    "and its chats are reported with `project: \"\"`; pass that same value back to " +
+    "`read_chat`. Returns each chat's owning project, " +
+    "sessionId, display name, last-updated time, whether a turn is currently " +
+    "running, and whether it is archived. ARCHIVED chats are EXCLUDED by default " +
+    "(matching the web UI, which files them away in a collapsed section); the " +
+    "result's `omittedArchived` count says how many were hidden — pass " +
+    "`include_archived: true` to get them back. You MUST do that to obtain the " +
+    "session_id of an archived chat: this tool is the only source of session ids, " +
+    "so an archived chat is otherwise unreachable by `read_chat`/`unarchive_chat`. " +
+    "`name` falls back to an 8-character sessionId prefix when the chat has no " +
+    "stored title — read that as \"untitled\", NOT as a meaningful name, and do not " +
+    "pass it anywhere a full session_id is wanted. " +
+    "Cheap — does not read full transcripts; use `read_chat` for content.";
+export const READ_CHAT_DESC = "Read a trimmed tail of a chat's transcript. Pass `project` (a workspace key: a " +
+    'project slug, or the empty string `""` for the ROOT workspace) and ' +
+    "`session_id` (from `list_chats`) — use whichever `project` value `list_chats` " +
+    "reported for the chat, verbatim. Returns the last `limit` messages (default " +
+    `${READ_CHAT_DEFAULT_LIMIT}, max ${READ_CHAT_MAX_LIMIT}) as {role, text, timestamp}; each ` +
+    `message's text is capped at ${READ_CHAT_MAX_TEXT} chars. ` +
+    "Use it to see what another chat is about or what was decided there. " +
+    "LOSSY — know what you are NOT getting. Tool calls come back as `role: \"tool\"` " +
+    "entries with EMPTY text (no tool name, no input, no output) and they still " +
+    "count against `limit`, so on a tool-heavy chat most of the reply is blank " +
+    "padding; thinking blocks, attachments and sub-agent transcripts are dropped " +
+    "outright. So this tool CANNOT show you how a chat went — errors, tool " +
+    "failures, stalls, cost. For that, read the transcript yourself: it is JSONL " +
+    "(one JSON object per line) at " +
+    "`<paddock-data-dir>/projects/<slug>/.chats/<sessionId>.jsonl`, with any " +
+    "sub-agents alongside it under `<sessionId>/subagents/agent-*.jsonl`. " +
+    "Also note an unknown session_id returns `total: 0` and no error — that means " +
+    "NOT FOUND, not \"empty chat\"; re-check the id before concluding anything.";
+// ── Write tools (Phase 2) ───────────────────────────────────────────────────
+export const CREATE_CHAT_DESC = "Start a BRAND-NEW chat and kick it off with `prompt` (a full first turn to the " +
+    "new keeper). Defaults to the current project; pass `project` (a slug) to create " +
+    "it elsewhere. Set `name` to a concise 3–5 word title for the chat (STRONGLY " +
+    "recommended — without it the title falls back to a long auto-summary of the " +
+    "first turn). Optionally set `preload_context` to seed the new chat with the " +
+    "project's OVERVIEW.md + CHANGELOG.md. Optionally set `model` to run the spawned " +
+    "chat on a specific model (e.g. a cheaper/faster one) without changing the " +
+    "project default. Returns the new chat's sessionId.";
+export const FORK_CHAT_DESC = "Fork an existing chat into a NEW child chat that inherits its history, then " +
+    "optionally kick the child off with `prompt`. Defaults to forking the CURRENT " +
+    "chat (the one you're in) — omit `session_id` to fork yourself, or pass a " +
+    "`session_id` (from list_chats) to fork another. Defaults to the current project; " +
+    "pass `project` to fork one elsewhere. Optionally set `name`, and `model` to run " +
+    "the child's kickoff turn on a specific model. Returns the new " +
+    "chat's sessionId. For fanning one source out into many children, use " +
+    "`fork_chat_batch` instead.";
+export const SEND_MESSAGE_DESC = "Send `prompt` as a NEW turn to an existing chat (identified by `session_id` from " +
+    "list_chats). Defaults to the current project; pass `project` to target a chat in " +
+    "another project. Use this to hand work or context to a chat that already exists.";
+export const ARCHIVE_CHAT_DESC = "Archive a chat — file it away into the collapsible \"Archived\" section without " +
+    "touching its transcript (it stays fully openable/resumable/forkable). " +
+    "Defaults to the CURRENT chat (the one you're in) — omit `session_id` to archive " +
+    "YOURSELF, or pass a `session_id` (from list_chats) to archive another. Defaults " +
+    "to the current project; pass `project` to target a chat elsewhere. This powers " +
+    "the self-reporting convention: do the work, then archive yourself on success so " +
+    "an un-archived chat is the signal that something needs a human's attention.";
+export const UNARCHIVE_CHAT_DESC = "Unarchive a chat — bring it back out of the \"Archived\" section into the active " +
+    "list. Defaults to the CURRENT chat — omit `session_id` to unarchive yourself, or " +
+    "pass a `session_id` (from list_chats) to unarchive another. Defaults to the " +
+    "current project; pass `project` to target a chat elsewhere.";
+export const FORK_CHAT_BATCH_DESC = "FAN-OUT primitive: fork ONE source chat into many child chats at once — one child " +
+    "per entry in `prompts`, each kicked off with its own prompt. Classic use: you " +
+    "found N items (e.g. 10 changes) and want to fork this chat N times, one worker per " +
+    "item. Pass `prompts` as one directive PER LINE. " +
+    "Defaults the source to the CURRENT chat; pass `session_id` to fork a different " +
+    "one, and `project` to target another project. With `name_prefix`, each fork is named " +
+    `"<name_prefix> <i>" (1-based). With \`model\`, every fork's kickoff turn runs on ` +
+    `that model. Up to ${FORK_BATCH_MAX} forks per call; they run ` +
+    "concurrently. Returns the source and every new child's sessionId.";
+// ── Project tools (issue #467) ──────────────────────────────────────────────
+export const CREATE_PROJECT_DESC = "Create a BRAND-NEW Paddock project — the workspace a keeper agent lives in — and " +
+    "register its keeper. `name` is the only required argument; the kebab-case `slug` " +
+    "is derived from it unless you pass one. Two kinds: pass a `repo` git URL for a " +
+    "REPO-BACKED project (the repo is cloned into a nested checkout that becomes the " +
+    "keeper's working directory — this is what you want for a project that IS a " +
+    "codebase), or omit `repo` for a NOTEBOOK project (a notes/docs workspace whose " +
+    "own directory is the working directory). Optionally set `summary` (a one-line " +
+    "description), `area` (the grouping shown in the sidebar) and `status`. Returns " +
+    "the new project's slug, its working directory, and whether it is repo-backed — " +
+    "pass that slug to `create_chat` to start working in it. A bad or unreachable " +
+    "repo URL fails cleanly and leaves NO half-created project behind, so it is safe " +
+    "to retry with a corrected URL.";
+// ── Unified trigger tools (Epic T / T3) ─────────────────────────────────────
+export const SET_TRIGGER_DESC = "Create or update a unified project TRIGGER — a standing rule that runs an agent " +
+    "turn when something happens, keyed by `name`. Enable/disable is just this call " +
+    "with `enabled` flipped (no separate verb); a NEW trigger defaults disabled. " +
+    "WHEN (`type`): \"schedule\" — a cron/interval fires it (give a 5-field `cron`, e.g. " +
+    "\"0 9 * * *\" = 9am daily host-local, OR an `interval` like \"30m\"/\"1h\"); \"event\" — a " +
+    "lifecycle `event` fires it (v1: \"onArchive\" — after a chat is archived; \"afterTurn\" " +
+    "reserved); \"webhook\" — reserved (give a `path`), not yet fired. WHAT (the run): the " +
+    "instruction as `prompt` (inline) OR `prompt_file` — a git-tracked `.md` under the " +
+    "project's `.paddock/triggers/` dir (e.g. \"daily.md\"), read at fire time; `session` " +
+    "\"new\" (a FRESH chat each fire, default) or \"resume\" (accrete the trigger's ONE owned " +
+    "session); `tools` = the deny-by-default capability allow-list (one per line or " +
+    "comma-separated, e.g. \"Bash, Read\"; omit / empty = a tool-less curator that only " +
+    "returns text; a JSON array is also accepted); `model`, `permission_mode` " +
+    "(\"default\"/\"acceptEdits\"/\"bypassPermissions\"/\"plan\"), `max_spawn_depth` (0 = may not " +
+    "spawn), `max_turns`. Editing preserves omitted fields (so an `enabled`-only call " +
+    "just flips the toggle); supplying `prompt` clears an inherited `prompt_file` and " +
+    "vice versa; supplying `type` re-specifies the whole trigger. Defaults to the " +
+    "current project; pass `project` (a slug) to target another.";
+export const REMOVE_TRIGGER_DESC = "Delete a unified project trigger by `name` (removes it from `project.yaml` and " +
+    "disarms its agent/schedule). Safe when absent — returns `removed: false` if no " +
+    "such trigger. Defaults to the current project; pass `project` to target another.";
+export const RUN_TRIGGER_DESC = "Fire a trigger NOW, on demand, by `name` — runs it through the SAME path a cron / " +
+    "event fire uses, so the resulting chat is a first-class, badged run. Works for any " +
+    "trigger type and regardless of its `enabled` flag (a manual run is deliberate). Use " +
+    "this to test a trigger you just wrote or to kick one off out of band. Returns the " +
+    "started chat's `sessionId`. Defaults to the current project; pass `project` to " +
+    "target another.";
+export const LIST_TRIGGERS_DESC = "List a project's unified triggers: each trigger's name, agent, `type` " +
+    "(schedule/event/webhook), its WHEN fields (cron/interval, event, path), its run " +
+    "(prompt/promptFile, session, tools, model, permissionMode, maxSpawnDepth, " +
+    "maxTurns), and `enabled` — plus live runtime state (status, lastRunAt, nextRunAt, " +
+    "lastError) for an armed schedule trigger. Read-only. Defaults to the current " +
+    "project; pass `project` (a slug) to target another.";

package/packages/server/dist/self-mcp-read.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Read-only handler factories for the Paddock self-management MCP (issue #214).
+ *
+ * The three always-on tools — list_projects / list_chats / read_chat — bound to a
+ * per-turn {@link SelfMcpContext}. Each factory returns an async handler that
+ * validates/normalizes args, delegates to the context callbacks, and shapes the
+ * plain-JSON tool result. read_chat applies the tail/limit + per-message
+ * truncation here (the context returns the FULL message list) so that logic stays
+ * unit-testable without the fleet.
+ */
+import type { McpToolCallResult } from "@herdctl/core";
+import type { SelfMcpContext } from "./self-mcp-types.js";
+export declare function listProjectsHandler(context: SelfMcpContext): () => Promise<McpToolCallResult>;
+export declare function listChatsHandler(context: SelfMcpContext): (args: Record<string, unknown>) => Promise<McpToolCallResult>;
+export declare function readChatHandler(context: SelfMcpContext): (args: Record<string, unknown>) => Promise<McpToolCallResult>;

package/packages/server/dist/self-mcp-read.js

@@ -0,0 +1,97 @@
+import { isRootKey } from "./project-paths.js";
+import { ok, fail, errText, clampLimit, coerceBoolean, truncateText } from "./self-mcp-util.js";
+/**
+ * The workspace key an arg names, or `undefined` when the arg is ABSENT (#560).
+ *
+ * Load-bearing distinction: the ROOT workspace's key is the empty string, so a
+ * truthiness test on this value silently collapses "the root" into "unspecified".
+ * Callers must therefore branch on `=== undefined`, never on falsiness. A
+ * whitespace-only value trims to `""` and so addresses the root, which is the
+ * same normalisation a slug already gets.
+ */
+function workspaceArg(value) {
+    return typeof value === "string" ? value.trim() : undefined;
+}
+export function listProjectsHandler(context) {
+    return async () => {
+        try {
+            const all = await context.listProjects();
+            // #560: the root workspace is NOT a project and is deliberately absent from
+            // `ProjectStore.list()` (enumeration walks children only) — but a caller
+            // that can't learn it exists can't reach its chats either. So it rides
+            // along as its OWN field, exactly the shape `GET /api/projects` settled on
+            // (`{ projects, root }`): reachable without being enumerated. `count` stays
+            // the project count. `root` is null when the caller's scope excludes it.
+            const projects = all.filter((p) => !isRootKey(p.slug));
+            const root = all.find((p) => isRootKey(p.slug)) ?? null;
+            return ok({ count: projects.length, projects, root });
+        }
+        catch (error) {
+            return fail(`Error listing projects: ${errText(error)}`);
+        }
+    };
+}
+export function listChatsHandler(context) {
+    return async (args) => {
+        try {
+            const project = workspaceArg(args.project);
+            const includeArchived = coerceBoolean(args.include_archived, false);
+            // #560: `""` is the ROOT workspace's key, so it is passed THROUGH as an
+            // address. The old `project && project.length > 0` collapsed it into "no
+            // filter", which answered an explicitly-named target with a different
+            // target's chats — silently. Absent (`undefined`) still means every
+            // workspace, root included.
+            const all = await context.listChats(project);
+            // #489: archived chats are hidden by default so the tool agrees with the web
+            // UI (which files them into a collapsed section). Filtering HERE rather than
+            // in the op keeps the blast radius off `SelfMcpContext`, the policy wrapper
+            // and both test fakes. The omitted count is reported rather than dropped
+            // silently: `list_chats` is the ONLY source of session ids, so a silent
+            // filter would make an archived chat unaddressable — no read_chat, no
+            // unarchive_chat — with nothing in the response to hint at why.
+            const chats = includeArchived ? all : all.filter((c) => !c.archived);
+            return ok({
+                count: chats.length,
+                omittedArchived: all.length - chats.length,
+                project: project ?? null,
+                chats,
+            });
+        }
+        catch (error) {
+            return fail(`Error listing chats: ${errText(error)}`);
+        }
+    };
+}
+export function readChatHandler(context) {
+    return async (args) => {
+        try {
+            const project = workspaceArg(args.project);
+            const sessionId = typeof args.session_id === "string" ? args.session_id.trim() : "";
+            // ABSENT, not empty (#560): `""` is the root workspace's key and a perfectly
+            // valid target. The old truthiness check made the root unaddressable AND
+            // reported a supplied argument as missing.
+            if (project === undefined) {
+                return fail('Error: `project` (a workspace key — a project slug, or "" for the root workspace) is required.');
+            }
+            if (!sessionId)
+                return fail("Error: `session_id` is required (get it from list_chats).");
+            const limit = clampLimit(args.limit);
+            const all = await context.readChat(project, sessionId);
+            const tail = all.slice(-limit).map((m) => ({
+                role: m.role,
+                text: truncateText(m.text),
+                timestamp: m.timestamp,
+            }));
+            return ok({
+                project,
+                sessionId,
+                total: all.length,
+                returned: tail.length,
+                messages: tail,
+            });
+        }
+        catch (error) {
+            return fail(`Error reading chat: ${errText(error)}`);
+        }
+    };
+}

package/packages/server/dist/self-mcp-triggers.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Unified trigger-management handler factories for the Paddock self-management MCP
+ * (Epic T "Unify Triggers" / T3 — issue #214). Collapse the paired schedule
+ * (issue #289) + hook (Epic G / G5) verbs onto ONE TriggerService over
+ * `project.yaml`'s single `triggers` block. A trigger is WHEN (`type`
+ * schedule|event|webhook) + WHAT (the shared run) + `enabled`. These tools are
+ * injected ONLY when the project opted into the trigger-management MCP
+ * (`triggersMcpEnabled`) — a coarse binary gate. Enable/disable is `set_trigger`
+ * with `enabled` flipped (GG-3), not a separate verb.
+ */
+import type { McpToolCallResult } from "@herdctl/core";
+import type { SelfMcpWriteContext } from "./self-mcp-types.js";
+/**
+ * Assemble the PARTIAL structured `{ trigger?, run?, enabled? }` record the
+ * `set_trigger` handler passes to `write.setTrigger` (which merges it over the
+ * existing trigger via `mergeTriggerUpdate`, then validates). Only fields the
+ * caller actually supplied are set, so an edit that omits a field preserves it
+ * (create-or-update patch semantics) — the classic being an `enabled`-only flip.
+ * Flat MCP args are the portable transport: the CLI runtime was observed dropping
+ * nested/array args, so the discriminant is rebuilt here from scalar args. Chats now
+ * run on the SDK runtime, but the flat shape is kept — it also has to survive
+ * the CLI runtime that a `driveMode: batch` project (or a trigger) still uses.
+ * Returns a string error message instead of a partial when a supplied `type`'s
+ * required WHEN field is missing; `null` on none.
+ */
+export declare function buildTriggerUpdate(args: Record<string, unknown>): Record<string, unknown> | string;
+export declare function setTriggerHandler(write: SelfMcpWriteContext): (args: Record<string, unknown>) => Promise<McpToolCallResult>;
+export declare function removeTriggerHandler(write: SelfMcpWriteContext): (args: Record<string, unknown>) => Promise<McpToolCallResult>;
+export declare function listTriggersHandler(write: SelfMcpWriteContext): (args: Record<string, unknown>) => Promise<McpToolCallResult>;
+export declare function runTriggerHandler(write: SelfMcpWriteContext): (args: Record<string, unknown>) => Promise<McpToolCallResult>;

package/packages/server/dist/self-mcp-triggers.js

@@ -0,0 +1,144 @@
+import { ok, fail, errText, coerceToolList } from "./self-mcp-util.js";
+/**
+ * Assemble the PARTIAL structured `{ trigger?, run?, enabled? }` record the
+ * `set_trigger` handler passes to `write.setTrigger` (which merges it over the
+ * existing trigger via `mergeTriggerUpdate`, then validates). Only fields the
+ * caller actually supplied are set, so an edit that omits a field preserves it
+ * (create-or-update patch semantics) — the classic being an `enabled`-only flip.
+ * Flat MCP args are the portable transport: the CLI runtime was observed dropping
+ * nested/array args, so the discriminant is rebuilt here from scalar args. Chats now
+ * run on the SDK runtime, but the flat shape is kept — it also has to survive
+ * the CLI runtime that a `driveMode: batch` project (or a trigger) still uses.
+ * Returns a string error message instead of a partial when a supplied `type`'s
+ * required WHEN field is missing; `null` on none.
+ */
+export function buildTriggerUpdate(args) {
+    const incoming = {};
+    // WHEN: only when `type` is supplied does the caller (re)specify the discriminant;
+    // an omitted `type` inherits the existing trigger's WHEN unchanged (partial edit).
+    const type = typeof args.type === "string" ? args.type.trim() : "";
+    if (type) {
+        if (type === "schedule") {
+            const cron = typeof args.cron === "string" ? args.cron.trim() : "";
+            const interval = typeof args.interval === "string" ? args.interval.trim() : "";
+            if (!cron && !interval) {
+                return 'Error: a "schedule" trigger needs `cron` (a 5-field expression, e.g. "0 9 * * *") or `interval` (e.g. "30m").';
+            }
+            if (cron && interval) {
+                return 'Error: a "schedule" trigger takes exactly ONE of `cron` or `interval`, not both.';
+            }
+            incoming.trigger = cron ? { type, cron } : { type, interval };
+        }
+        else if (type === "event") {
+            const event = typeof args.event === "string" ? args.event.trim() : "";
+            if (!event)
+                return 'Error: an "event" trigger needs `event` (the lifecycle trigger, e.g. "onArchive").';
+            incoming.trigger = { type, on: event };
+        }
+        else if (type === "webhook") {
+            const p = typeof args.path === "string" ? args.path.trim() : "";
+            if (!p)
+                return 'Error: a "webhook" trigger needs `path` (the ingress path; reserved — not yet fired).';
+            incoming.trigger = { type, path: p };
+        }
+        else {
+            return 'Error: `type` must be "schedule", "event", or "webhook".';
+        }
+    }
+    // WHAT: assemble only the run fields the caller supplied.
+    const run = {};
+    const prompt = typeof args.prompt === "string" ? args.prompt.trim() : "";
+    const promptFile = typeof args.prompt_file === "string" ? args.prompt_file.trim() : "";
+    if (prompt)
+        run.prompt = prompt;
+    if (promptFile)
+        run.promptFile = promptFile;
+    if (typeof args.session === "string" && (args.session === "new" || args.session === "resume")) {
+        run.session = args.session;
+    }
+    if (typeof args.model === "string" && args.model.trim() !== "")
+        run.model = args.model.trim();
+    // `tools` is present (even as "") → set it (an empty list = a tool-less curator);
+    // absent → leave the existing grant untouched on an edit.
+    if (args.tools !== undefined)
+        run.tools = coerceToolList(args.tools);
+    if (typeof args.max_spawn_depth === "number")
+        run.maxSpawnDepth = args.max_spawn_depth;
+    if (typeof args.permission_mode === "string" && args.permission_mode.trim() !== "") {
+        run.permissionMode = args.permission_mode.trim();
+    }
+    if (typeof args.max_turns === "number")
+        run.maxTurns = args.max_turns;
+    if (Object.keys(run).length > 0)
+        incoming.run = run;
+    if (typeof args.enabled === "boolean")
+        incoming.enabled = args.enabled;
+    return incoming;
+}
+export function setTriggerHandler(write) {
+    return async (args) => {
+        try {
+            const name = typeof args.name === "string" ? args.name.trim() : "";
+            if (!name)
+                return fail("Error: `name` is required (the trigger's key).");
+            const incoming = buildTriggerUpdate(args);
+            if (typeof incoming === "string")
+                return fail(incoming);
+            const projectArg = typeof args.project === "string" ? args.project.trim() : "";
+            const project = projectArg.length > 0 ? projectArg : write.currentProjectSlug;
+            const saved = await write.setTrigger(project, name, incoming);
+            return ok({ set: true, project, trigger: saved });
+        }
+        catch (error) {
+            return fail(`Error setting trigger: ${errText(error)}`);
+        }
+    };
+}
+export function removeTriggerHandler(write) {
+    return async (args) => {
+        try {
+            const name = typeof args.name === "string" ? args.name.trim() : "";
+            if (!name)
+                return fail("Error: `name` is required (the trigger to remove).");
+            const projectArg = typeof args.project === "string" ? args.project.trim() : "";
+            const project = projectArg.length > 0 ? projectArg : write.currentProjectSlug;
+            const removed = await write.removeTrigger(project, name);
+            return ok({ removed, project, name });
+        }
+        catch (error) {
+            return fail(`Error removing trigger: ${errText(error)}`);
+        }
+    };
+}
+export function listTriggersHandler(write) {
+    return async (args) => {
+        try {
+            const projectArg = typeof args.project === "string" ? args.project.trim() : "";
+            const project = projectArg.length > 0 ? projectArg : write.currentProjectSlug;
+            const triggers = await write.listTriggers(project);
+            return ok({ project, count: triggers.length, triggers });
+        }
+        catch (error) {
+            return fail(`Error listing triggers: ${errText(error)}`);
+        }
+    };
+}
+export function runTriggerHandler(write) {
+    return async (args) => {
+        try {
+            const name = typeof args.name === "string" ? args.name.trim() : "";
+            if (!name)
+                return fail("Error: `name` is required (the trigger to run).");
+            const projectArg = typeof args.project === "string" ? args.project.trim() : "";
+            const project = projectArg.length > 0 ? projectArg : write.currentProjectSlug;
+            const sessionId = await write.runTrigger(project, name);
+            if (!sessionId) {
+                return fail(`Error running trigger “${name}”: no such trigger, or it did not start a chat.`);
+            }
+            return ok({ ran: true, project, name, sessionId });
+        }
+        catch (error) {
+            return fail(`Error running trigger: ${errText(error)}`);
+        }
+    };
+}