@edspencer/paddock 0.0.1 → 0.57.0

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

@@ -0,0 +1,248 @@
+/**
+ * Type declarations for the Paddock self-management MCP (issue #214).
+ *
+ * The agent-facing DTOs (`SelfMcpProject`/`SelfMcpChat`/`SelfMcpMessage`/
+ * `SelfMcpTrigger`) plus the two per-turn context bags (`SelfMcpContext` read-side,
+ * `SelfMcpWriteContext` write-side) the caller wires to ProjectStore/HerdctlService.
+ * Pure declarations — no runtime code — re-exported from `self-mcp.ts` so existing
+ * importers keep working.
+ */
+/** A project as surfaced to the agent. */
+export interface SelfMcpProject {
+    slug: string;
+    name: string;
+    /** The project's area ("Unsorted" when empty); omitted when blank. */
+    area?: string;
+    status: string;
+}
+/**
+ * The arguments `create_project` passes through to the create path (issue #467) —
+ * the subset of {@link import("./project-types.js").CreateProjectInput} the tool
+ * exposes, already trimmed + shape-validated by the handler. Deliberately a local
+ * declaration (not an import of `CreateProjectInput`) so this module keeps zero
+ * runtime coupling; the caller widens it back to the real input at the boundary.
+ */
+export interface SelfMcpCreateProjectInput {
+    name: string;
+    /** Explicit kebab-case slug; absent ⇒ the store derives one from `name`. */
+    slug?: string;
+    /** Git URL ⇒ a REPO-BACKED project (#187): cloned into a nested checkout. */
+    repo?: string;
+    summary?: string;
+    /** The project's area (persisted as `group`; `list_projects` reports it as `area`). */
+    group?: string;
+    status?: string;
+}
+/** A newly-created project as surfaced back to the agent (issue #467). */
+export interface SelfMcpCreatedProject {
+    slug: string;
+    name: string;
+    /** The project's metadata dir (OVERVIEW/CHANGELOG/`.chats` live here). */
+    dir: string;
+    /** The keeper's cwd — the nested checkout when repo-backed, else `dir`. */
+    workingDir: string;
+    /** Whether the project is backed by a cloned external repo (#187). */
+    repoBacked: boolean;
+    /** The repo URL when repo-backed, else undefined. */
+    repo?: string;
+    /**
+     * Whether the keeper agent registered. The REST create path treats a registration
+     * failure as non-fatal (the project IS created), so this mirrors it — but reports
+     * it, because a project with no live keeper can't take a `create_chat` yet.
+     */
+    agentRegistered: boolean;
+}
+/** A chat as surfaced to the agent. */
+export interface SelfMcpChat {
+    /** Owning project slug. */
+    project: string;
+    sessionId: string;
+    /** Display name (custom name, else auto-name, else a short id). */
+    name: string;
+    /** ISO timestamp of the last transcript write (mtime). */
+    updatedAt: string;
+    /** Whether a turn is currently in flight for this chat. */
+    running: boolean;
+    /**
+     * Whether the chat is filed away in the UI's "Archived" section (#489). Always
+     * present — `list_chats` hides archived chats by default, so the flag is what
+     * lets a caller that passed `include_archived: true` tell the two apart, and it
+     * mirrors the REST DTO (`chat-dto.ts`), which has always carried it.
+     */
+    archived: boolean;
+}
+/** One transcript message as surfaced to the agent. */
+export interface SelfMcpMessage {
+    role: "user" | "assistant" | "tool";
+    text: string;
+    timestamp: string;
+}
+/**
+ * A unified project TRIGGER as surfaced to the agent (Epic T "Unify Triggers" / T3
+ * — the successor that collapses `SelfMcpSchedule` + `SelfMcpHook`). Flattens the
+ * persisted {@link import("./trigger-config.js").TriggerDto} — the discriminated
+ * `trigger` (WHEN: `schedule|event|webhook`) + the shared `run` (WHAT) + `enabled`
+ * — plus the `trigger-<slug>-<name>` agent an event/webhook trigger registers as.
+ * Nested `trigger`/`run` fields are flattened + null-normalised so the agent reads
+ * ONE flat record regardless of type. For a `schedule` trigger, best-effort live
+ * runtime state (`status`/`lastRunAt`/`nextRunAt`/`lastError`) is merged in when the
+ * keeper has armed it (absent otherwise — and always absent for event/webhook).
+ */
+export interface SelfMcpTrigger {
+    /** The trigger's stable key (the `project.yaml` map key + `<name>` in its agent). */
+    name: string;
+    /** The herdctl agent an event/webhook trigger registers as (`trigger-<slug>-<name>`). */
+    agentName: string;
+    /** WHEN: the discriminant — `schedule` (cron/interval), `event` (on), or `webhook` (path). */
+    type: "schedule" | "event" | "webhook";
+    /** The cron expression (schedule), else null. */
+    cron: string | null;
+    /** The interval string (schedule), else null. */
+    interval: string | null;
+    /** The lifecycle event this fires on (event trigger, e.g. `onArchive`), else null. */
+    event: string | null;
+    /** The ingress path (webhook trigger — reserved, unbuilt), else null. */
+    path: string | null;
+    /** WHAT: the inline prompt, or null when a `promptFile` drives it. */
+    prompt: string | null;
+    /** The `.paddock/triggers/` prompt-file name, or null. */
+    promptFile: string | null;
+    /** `new` = a fresh chat each fire; `resume` = one owned accreting session. */
+    session: "new" | "resume";
+    /** The tools the fired agent may use (its capability grant); `[]` = tool-less. */
+    tools: string[];
+    /** Recursion bound for internal spawning (0 = may not spawn), or null (default). */
+    maxSpawnDepth: number | null;
+    /** The permission mode the fired agent's turns run under, or null (fleet default). */
+    permissionMode: string | null;
+    /** Model override for the fired agent, or null (keeper default). */
+    model: string | null;
+    /** Max agent turns bounding a runaway trigger, or null (trigger default). */
+    maxTurns: number | null;
+    /** Whether the trigger is armed. New triggers default `false` (GG-3). */
+    enabled: boolean;
+    /** Live status for an armed schedule trigger (`idle`/`running`/`disabled`), else null. */
+    status?: string | null;
+    /** ISO time of the last fire (schedule trigger), or null. */
+    lastRunAt?: string | null;
+    /** ISO time of the next scheduled fire (schedule trigger), or null. */
+    nextRunAt?: string | null;
+    /** The last fire's error message (schedule trigger), or null. */
+    lastError?: string | null;
+}
+/**
+ * Per-turn context: narrow async callbacks the caller wires to the real stores.
+ * `readChat` returns the FULL ordered message list; this module applies the
+ * tail/limit + per-message truncation so that logic stays testable here.
+ */
+export interface SelfMcpContext {
+    listProjects: () => Promise<SelfMcpProject[]>;
+    listChats: (projectSlug?: string) => Promise<SelfMcpChat[]>;
+    readChat: (projectSlug: string, sessionId: string) => Promise<SelfMcpMessage[]>;
+}
+/**
+ * Write-side per-turn context. Present only when the write flag is on. These
+ * callbacks START real keeper turns; this module only validates/normalizes args
+ * and delegates. The caller wires them to HerdctlService/ProjectStore.
+ *
+ * NOTE (guard-ready): these write tools deliberately have NO recursion/depth
+ * guard in this phase (per the product owner) — a keeper can create/fork chats
+ * that themselves have the self-MCP injected. The injection path is intentionally
+ * left guard-ready: a later phase can thread a depth/origin marker through the
+ * caller-supplied callbacks below without changing this module's shape.
+ */
+export interface SelfMcpWriteContext {
+    /** Slug of the project the calling keeper is in (fork/create default target). */
+    currentProjectSlug: string;
+    /** Resolved sessionId of the CURRENT chat, or null if not yet known this turn. */
+    currentSessionId: () => string | null;
+    /**
+     * Start a brand-new chat in `projectSlug` kicked off with `prompt`. Returns its
+     * new sessionId. `opts.model` (issue #336) is a per-chat model override for the
+     * spawned chat's kickoff turn ONLY — already validated against the picker
+     * allow-list by the handler; absent ⇒ inherit the project/box default.
+     */
+    createChat: (projectSlug: string, prompt: string, opts?: {
+        name?: string;
+        preloadContext?: boolean;
+        model?: string;
+    }) => Promise<{
+        sessionId: string;
+    }>;
+    /**
+     * Eager-fork `sourceSessionId` (in `projectSlug`) into a new chat, optionally
+     * kicked off with `prompt`. Returns the new sessionId. `model` (issue #336) is a
+     * per-chat override applied to the kickoff turn ONLY (a fork with no `prompt`
+     * runs no turn, so a `model` without a `prompt` has no effect); absent ⇒ inherit
+     * the project/box default.
+     */
+    forkChat: (args: {
+        projectSlug: string;
+        sourceSessionId: string;
+        prompt?: string;
+        name?: string;
+        model?: string;
+    }) => Promise<{
+        sessionId: string;
+    }>;
+    /** Send `prompt` as a new turn to an existing chat. */
+    sendMessage: (projectSlug: string, sessionId: string, prompt: string) => Promise<void>;
+    /** Set (or clear) a chat's archived flag (presentational metadata only). */
+    setArchived: (projectSlug: string, sessionId: string, archived: boolean) => Promise<void>;
+    /**
+     * Whether the PROJECT tools (`create_project`, issue #467) are enabled for this
+     * instance — the `selfMcpProjectsEnabled` gate, resolved by the caller. When false
+     * the tool is NOT injected at all (absent, not present-but-refusing), the same
+     * binary discipline as {@link triggersMcpEnabled}.
+     */
+    projectsMcpEnabled: boolean;
+    /**
+     * Provision a whole new project and register its keeper agent — the SAME two steps
+     * `POST /api/projects` performs, in the same order (`ProjectStore.create` then
+     * `ensureProjectAgent`), so the REST and MCP paths cannot drift. All the real work
+     * (slug/repo validation, `project.yaml`, seeded CHANGELOG/CLAUDE.md, the #187
+     * repo-backed clone into a nested `.gitignore`d checkout WITH rollback on failure)
+     * stays in the store. Throws on a create failure; a keeper-registration failure is
+     * non-fatal (mirroring the route) and reported via `agentRegistered`.
+     */
+    createProject: (input: SelfMcpCreateProjectInput) => Promise<SelfMcpCreatedProject>;
+    /**
+     * Whether the unified trigger-management MCP is enabled for THIS turn's project
+     * (Epic T / T3 — the successor to the G5 hook-MCP gate, resolved from the SAME
+     * per-project `hooksMcpEnabled` opt-in against the instance default; the gate is
+     * REUSED, not reinvented). When false the trigger tools (`list_triggers`/
+     * `set_trigger`/`remove_trigger`) are NOT injected at all (absent, not present-
+     * but-refusing) — the design's binary "does this project agent get the trigger
+     * MCP at all" gate. The caller resolves this per project (see
+     * {@link import("./hook-config.js").resolveHooksMcpEnabled}).
+     */
+    triggersMcpEnabled: boolean;
+    /**
+     * List a project's unified triggers (Epic T / T3). Read-only; reads the live
+     * project record (merging best-effort schedule runtime state). Present regardless
+     * of {@link triggersMcpEnabled} on the context, but the tools are only injected
+     * when that flag is on.
+     */
+    listTriggers: (projectSlug: string) => Promise<SelfMcpTrigger[]>;
+    /**
+     * Create or update a trigger (keyed by `name`) — persists to `project.yaml`'s
+     * single `triggers` block and arms it. `trigger` is a PARTIAL structured record
+     * (`{ trigger?, run?, enabled? }`, camelCase) the caller merges over the existing
+     * trigger (via `mergeTriggerUpdate`) then validates + sanitises (throwing on a
+     * malformed record), defaulting a brand-new trigger to `enabled: false` (GG-3).
+     * Enable/disable is just this call with `enabled` flipped (GG-3) — no separate
+     * verb. Returns the saved trigger.
+     */
+    setTrigger: (projectSlug: string, name: string, trigger: Record<string, unknown>) => Promise<SelfMcpTrigger>;
+    /**
+     * Remove a trigger by `name` — persisted removal + disarming its agent/schedule.
+     * Returns `true` when a trigger existed, `false` when it was already absent.
+     */
+    removeTrigger: (projectSlug: string, name: string) => Promise<boolean>;
+    /**
+     * Fire a trigger by `name` NOW (Epic T follow-up / #327) — through the same hub
+     * path a cron / event fire uses. Returns the started chat's sessionId, or `null` if
+     * the project/trigger is gone or the turn never produced a session.
+     */
+    runTrigger: (projectSlug: string, name: string) => Promise<string | null>;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Type declarations for the Paddock self-management MCP (issue #214).
+ *
+ * The agent-facing DTOs (`SelfMcpProject`/`SelfMcpChat`/`SelfMcpMessage`/
+ * `SelfMcpTrigger`) plus the two per-turn context bags (`SelfMcpContext` read-side,
+ * `SelfMcpWriteContext` write-side) the caller wires to ProjectStore/HerdctlService.
+ * Pure declarations — no runtime code — re-exported from `self-mcp.ts` so existing
+ * importers keep working.
+ */
+export {};

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

@@ -0,0 +1,73 @@
+/**
+ * Pure helpers + numeric caps for the Paddock self-management MCP (issue #214).
+ *
+ * These are the deliberately-testable primitives the handler factories build on:
+ * the `ok`/`fail` result envelopes, `errText` normalisation, the read_chat
+ * tail/limit + per-message truncation clamps, and the arg-coercion helpers that
+ * tolerate the CLI-runtime MCP transport dropping array-typed args. Several are
+ * unit-test-exported and re-exported from `self-mcp.ts` for the public surface.
+ */
+import type { McpToolCallResult } from "@herdctl/core";
+/** fork_chat_batch: hard cap on how many forks a single fan-out call may spawn. */
+export declare const FORK_BATCH_MAX = 20;
+/** read_chat: default and hard-cap on how many trailing messages to return. */
+export declare const READ_CHAT_DEFAULT_LIMIT = 30;
+export declare const READ_CHAT_MAX_LIMIT = 200;
+/** read_chat: per-message character cap so one huge message can't flood the result. */
+export declare const READ_CHAT_MAX_TEXT = 2000;
+export declare function ok(payload: unknown): McpToolCallResult;
+export declare function fail(text: string): McpToolCallResult;
+export declare function errText(error: unknown): string;
+/**
+ * Strip server filesystem paths out of an error message before it reaches the agent
+ * (issue #467). Motivating case: `create_project` on an unreachable repo surfaces
+ * git's failure through `promisify(execFile)`, whose message is the WHOLE argv —
+ * `Command failed: git clone -- <url> /srv/data/projects/foo/foo` — i.e. the server's
+ * internal layout. The repo URL is the actionable part and is preserved (URLs are
+ * skipped by {@link ABS_PATH_RE}); bare absolute paths become `<path>`.
+ *
+ * A hygiene measure, not a security boundary: a keeper can see its own cwd anyway.
+ * The point is that a tool error reads as a clean, actionable message rather than a
+ * raw subprocess dump — the same cleanup applied to the other write tools' errors.
+ */
+export declare function redactPaths(text: string): string;
+/** Clamp a caller-supplied limit into [1, MAX], defaulting when absent/invalid. */
+export declare function clampLimit(raw: unknown): number;
+/**
+ * Normalize a BOOLEAN tool argument, defaulting when absent/unusable. A real
+ * boolean is taken as-is; `"true"`/`"false"` (any case, padded) are accepted too
+ * because the CLI-runtime MCP transport has proven lossy with non-string args
+ * (see {@link coercePrompts}) — the same defensive parse, one type down. Anything
+ * else falls back rather than erroring: a mistyped flag shouldn't fail a read.
+ */
+export declare function coerceBoolean(raw: unknown, fallback: boolean): boolean;
+/** Truncate a single message's text with an explicit marker. */
+export declare function truncateText(text: string): string;
+/**
+ * Validate the optional `model` argument on the spawn tools (create_chat /
+ * fork_chat / fork_chat_batch, issue #336) against the SAME picker allow-list the
+ * web model-picker uses ({@link isKnownModel}). Returns `{}` when absent/blank (the
+ * spawned chat inherits the project/box default, the unchanged behaviour), `{ model }`
+ * for a recognised id, or an error STRING (listing the valid ids) for a non-blank
+ * unknown id — the handler turns that into an `isError` tool result so the agent
+ * gets an actionable message rather than a silently-ignored override.
+ */
+export declare function resolveModelArg(raw: unknown): {
+    model?: string;
+} | string;
+/**
+ * Normalize the `prompts` argument to a string array. The CLI-runtime MCP path
+ * has proven unreliable at carrying an ARRAY-typed argument to the tool handler
+ * (string args work; the array arrives dropped) — so we ALSO accept the list as a
+ * string: a JSON array (`["a","b"]`) or newline-separated directives. Returns []
+ * when nothing usable is present (handler then reports the required-arg error).
+ */
+export declare function coercePrompts(raw: unknown): string[];
+/**
+ * Normalize a tool-list argument (a hook's `allowed_tools`/`denied_tools`) to a
+ * string array. Like {@link coercePrompts}, tolerant of the CLI-runtime MCP
+ * transport dropping ARRAY-typed args: accepts a real array, a JSON array string,
+ * or a comma/newline-separated string (tool names never contain commas). Blanks
+ * are dropped; returns [] when nothing usable is present (a tool-less hook).
+ */
+export declare function coerceToolList(raw: unknown): string[];

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

@@ -0,0 +1,157 @@
+import { MODELS, isKnownModel } from "./models.js";
+/** fork_chat_batch: hard cap on how many forks a single fan-out call may spawn. */
+export const FORK_BATCH_MAX = 20;
+/** read_chat: default and hard-cap on how many trailing messages to return. */
+export const READ_CHAT_DEFAULT_LIMIT = 30;
+export const READ_CHAT_MAX_LIMIT = 200;
+/** read_chat: per-message character cap so one huge message can't flood the result. */
+export const READ_CHAT_MAX_TEXT = 2000;
+export function ok(payload) {
+    return { content: [{ type: "text", text: JSON.stringify(payload) }] };
+}
+export function fail(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+export function errText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Absolute POSIX paths of two-or-more segments (`/var/lib/paddock/projects/x`), NOT
+ * preceded by `:` or `/` so the path component of a URL (`https://host/owner/repo`)
+ * is left alone. Used by {@link redactPaths}.
+ */
+const ABS_PATH_RE = /(?<![:/\w])\/[\w.@%+-]+(?:\/[\w.@%+-]+)+\/?/g;
+/**
+ * Strip server filesystem paths out of an error message before it reaches the agent
+ * (issue #467). Motivating case: `create_project` on an unreachable repo surfaces
+ * git's failure through `promisify(execFile)`, whose message is the WHOLE argv —
+ * `Command failed: git clone -- <url> /srv/data/projects/foo/foo` — i.e. the server's
+ * internal layout. The repo URL is the actionable part and is preserved (URLs are
+ * skipped by {@link ABS_PATH_RE}); bare absolute paths become `<path>`.
+ *
+ * A hygiene measure, not a security boundary: a keeper can see its own cwd anyway.
+ * The point is that a tool error reads as a clean, actionable message rather than a
+ * raw subprocess dump — the same cleanup applied to the other write tools' errors.
+ */
+export function redactPaths(text) {
+    return text.replace(ABS_PATH_RE, "<path>");
+}
+/** Clamp a caller-supplied limit into [1, MAX], defaulting when absent/invalid. */
+export function clampLimit(raw) {
+    if (typeof raw !== "number" || !Number.isFinite(raw))
+        return READ_CHAT_DEFAULT_LIMIT;
+    const n = Math.floor(raw);
+    if (n < 1)
+        return 1;
+    if (n > READ_CHAT_MAX_LIMIT)
+        return READ_CHAT_MAX_LIMIT;
+    return n;
+}
+/**
+ * Normalize a BOOLEAN tool argument, defaulting when absent/unusable. A real
+ * boolean is taken as-is; `"true"`/`"false"` (any case, padded) are accepted too
+ * because the CLI-runtime MCP transport has proven lossy with non-string args
+ * (see {@link coercePrompts}) — the same defensive parse, one type down. Anything
+ * else falls back rather than erroring: a mistyped flag shouldn't fail a read.
+ */
+export function coerceBoolean(raw, fallback) {
+    if (typeof raw === "boolean")
+        return raw;
+    if (typeof raw === "string") {
+        const s = raw.trim().toLowerCase();
+        if (s === "true")
+            return true;
+        if (s === "false")
+            return false;
+    }
+    return fallback;
+}
+/** Truncate a single message's text with an explicit marker. */
+export function truncateText(text) {
+    if (text.length <= READ_CHAT_MAX_TEXT)
+        return text;
+    const omitted = text.length - READ_CHAT_MAX_TEXT;
+    return `${text.slice(0, READ_CHAT_MAX_TEXT)}… [truncated ${omitted} chars]`;
+}
+/**
+ * Validate the optional `model` argument on the spawn tools (create_chat /
+ * fork_chat / fork_chat_batch, issue #336) against the SAME picker allow-list the
+ * web model-picker uses ({@link isKnownModel}). Returns `{}` when absent/blank (the
+ * spawned chat inherits the project/box default, the unchanged behaviour), `{ model }`
+ * for a recognised id, or an error STRING (listing the valid ids) for a non-blank
+ * unknown id — the handler turns that into an `isError` tool result so the agent
+ * gets an actionable message rather than a silently-ignored override.
+ */
+export function resolveModelArg(raw) {
+    if (typeof raw !== "string")
+        return {};
+    const m = raw.trim();
+    if (m.length === 0)
+        return {};
+    if (!isKnownModel(m)) {
+        return `Error: unknown model "${m}". Valid models: ${MODELS.map((x) => x.id).join(", ")}.`;
+    }
+    return { model: m };
+}
+/**
+ * Normalize the `prompts` argument to a string array. The CLI-runtime MCP path
+ * has proven unreliable at carrying an ARRAY-typed argument to the tool handler
+ * (string args work; the array arrives dropped) — so we ALSO accept the list as a
+ * string: a JSON array (`["a","b"]`) or newline-separated directives. Returns []
+ * when nothing usable is present (handler then reports the required-arg error).
+ */
+export function coercePrompts(raw) {
+    if (Array.isArray(raw)) {
+        return raw.map((p) => (typeof p === "string" ? p : "")).map((p) => p.trim());
+    }
+    if (typeof raw === "string") {
+        const s = raw.trim();
+        if (s.length === 0)
+            return [];
+        if (s.startsWith("[")) {
+            try {
+                const parsed = JSON.parse(s);
+                if (Array.isArray(parsed)) {
+                    return parsed.map((p) => (typeof p === "string" ? p : "")).map((p) => p.trim());
+                }
+            }
+            catch {
+                /* fall through to newline split */
+            }
+        }
+        return s
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+    }
+    return [];
+}
+/**
+ * Normalize a tool-list argument (a hook's `allowed_tools`/`denied_tools`) to a
+ * string array. Like {@link coercePrompts}, tolerant of the CLI-runtime MCP
+ * transport dropping ARRAY-typed args: accepts a real array, a JSON array string,
+ * or a comma/newline-separated string (tool names never contain commas). Blanks
+ * are dropped; returns [] when nothing usable is present (a tool-less hook).
+ */
+export function coerceToolList(raw) {
+    const clean = (arr) => arr.map((t) => (typeof t === "string" ? t.trim() : "")).filter((t) => t.length > 0);
+    if (Array.isArray(raw))
+        return clean(raw);
+    if (typeof raw === "string") {
+        const s = raw.trim();
+        if (s.length === 0)
+            return [];
+        if (s.startsWith("[")) {
+            try {
+                const parsed = JSON.parse(s);
+                if (Array.isArray(parsed))
+                    return clean(parsed);
+            }
+            catch {
+                /* fall through to delimiter split */
+            }
+        }
+        return clean(s.split(/[\n,]/));
+    }
+    return [];
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Write-side handler factories for the Paddock self-management MCP — Phase 2
+ * (issue #214). The create/fork/send/archive/fork-batch tools, each bound to a
+ * per-turn {@link SelfMcpWriteContext}. Every factory returns an async handler
+ * that validates/normalizes args (including the #336 per-chat `model` override and
+ * the CLI-transport-tolerant `prompts` coercion) and delegates to the write
+ * callbacks, which START real keeper turns. Present only when the write flag is on.
+ */
+import type { McpToolCallResult } from "@herdctl/core";
+import type { SelfMcpWriteContext } from "./self-mcp-types.js";
+export declare function createChatHandler(write: SelfMcpWriteContext): (args: Record<string, unknown>) => Promise<McpToolCallResult>;
+export declare function forkChatHandler(write: SelfMcpWriteContext): (args: Record<string, unknown>) => Promise<McpToolCallResult>;
+export declare function sendMessageHandler(write: SelfMcpWriteContext): (args: Record<string, unknown>) => Promise<McpToolCallResult>;
+/**
+ * Handler factory for archive_chat / unarchive_chat. Both resolve the target the
+ * same way — `session_id` OPTIONAL, defaulting to the CURRENT chat so an agent can
+ * archive ITSELF without knowing its own id (mirrors fork_chat's self-default) —
+ * and differ only in the boolean they set. `archived` selects which tool this is.
+ */
+export declare function archiveChatHandler(write: SelfMcpWriteContext, archived: boolean): (args: Record<string, unknown>) => Promise<McpToolCallResult>;
+/**
+ * `create_project` (issue #467) — provision a whole new project. The one write tool
+ * that does NOT act inside an existing project, which is why it sits behind its own
+ * `projectsMcpEnabled` gate.
+ *
+ * Pure, like its siblings: it trims + SHAPE-validates the args (using the very same
+ * `SLUG_RE` / `isValidRepoUrl` / `PROJECT_STATUSES` the store and DTO use, so there
+ * is no second definition of "valid") and delegates to `write.createProject`, which
+ * runs `ProjectStore.create` + `ensureProjectAgent` — literally the REST create path.
+ * The up-front checks are a fast, actionable-error convenience, NOT a replacement for
+ * the store's own validation: the store still rejects a duplicate slug, a bad URL and
+ * an unclonable repo, and still rolls the whole project dir back on a clone failure.
+ */
+export declare function createProjectHandler(write: SelfMcpWriteContext): (args: Record<string, unknown>) => Promise<McpToolCallResult>;
+export declare function forkChatBatchHandler(write: SelfMcpWriteContext): (args: Record<string, unknown>) => Promise<McpToolCallResult>;