@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/management-ops.js

@@ -0,0 +1,449 @@
+import { keeperAgentName } from "./herdctl.js";
+import { isKnownModel, isKnownDriveMode } from "./models.js";
+import { ROOT_KEY } from "./projects.js";
+import { childOf } from "./run-provenance.js";
+import { resolveMaxSpawnDepth } from "./spawn-capability.js";
+import { isCuratorTrigger, mergeTriggerUpdate } from "./trigger-config.js";
+import { assertOperation, assertProject, isOperationAllowed, isProjectAllowed, isInternalPrincipal, TRIGGER_OPERATIONS, WRITE_OPERATIONS, } from "./management-policy.js";
+/**
+ * Frame an agent-initiated FORK kickoff (issue #214 Phase 2). A fork inherits the
+ * parent's transcript as context — and when the parent is the *live* chat doing
+ * the forking, that snapshot is taken mid-turn, so the child would otherwise
+ * inherit the parent's "I am still mid-task" identity and reject the seeded
+ * instruction (observed in QA). This preamble tells the child the history above
+ * is inherited background and that its job now is the given directive — which is
+ * exactly the fan-out contract ("fork this chat N times, one work-item each").
+ */
+export function forkKickoffPrompt(directive) {
+    return ("[Paddock fan-out] You are a NEW chat forked from the conversation above. " +
+        "That history is INHERITED CONTEXT — you are NOT in the middle of the prior " +
+        "turn, and its final exchange may be truncated at the fork point; do not try " +
+        "to continue it. Use it as background, then carry out this instruction as your " +
+        "task now:\n\n" +
+        directive);
+}
+/**
+ * Project a persisted {@link TriggerDto} (+ optional herdctl runtime state for a
+ * schedule trigger) onto the flat {@link SelfMcpTrigger} shape the unified trigger
+ * tools return (Epic T / T3).
+ */
+function toSelfMcpTrigger(dto, info) {
+    const when = dto.trigger;
+    const run = dto.run;
+    const isSchedule = when.type === "schedule";
+    return {
+        name: dto.name,
+        agentName: dto.agentName,
+        type: when.type,
+        cron: when.type === "schedule" ? when.cron ?? null : null,
+        interval: when.type === "schedule" ? when.interval ?? null : null,
+        event: when.type === "event" ? when.on : null,
+        path: when.type === "webhook" ? when.path : null,
+        prompt: run.prompt ?? null,
+        promptFile: run.promptFile ?? null,
+        session: run.session,
+        tools: run.tools ?? [],
+        maxSpawnDepth: run.maxSpawnDepth ?? null,
+        permissionMode: run.permissionMode ?? null,
+        model: run.model ?? null,
+        maxTurns: run.maxTurns ?? null,
+        enabled: dto.enabled === true,
+        status: isSchedule ? info?.status ?? (dto.enabled === false ? "disabled" : "idle") : null,
+        lastRunAt: isSchedule ? info?.lastRunAt ?? null : null,
+        nextRunAt: isSchedule ? info?.nextRunAt ?? null : null,
+        lastError: isSchedule ? info?.lastError ?? null : null,
+    };
+}
+/**
+ * Build the management operations bound to one caller's context.
+ *
+ * `parentProvenance` is the provenance of the chat these ops run IN — so any
+ * child they spawn is `childOf(parentProvenance)` (origin `spawned`, depth+1).
+ * The human path passes a human root (depth 0 → children depth 1); the spawned
+ * path passes the current turn's own `{ origin, depth }`, so the `maxSpawnDepth`
+ * bound descends and the tree can't run away.
+ */
+export function buildManagementOps(ctx, params) {
+    const { currentProjectSlug, currentSessionId, parentProvenance, includeWrite, includeTriggers, includeProjects, spawnDepthCap, } = params;
+    const { deps, hub, startAgentTurn, composePreloadedPrompt, fireTrigger } = ctx;
+    /**
+     * Every workspace an unfiltered enumeration should cover (#560): the ROOT plus
+     * its child projects.
+     *
+     * `ProjectStore.list()` deliberately returns children only — the root is
+     * reachable, never enumerated (pinned by `root-workspace.test.ts`) — so the
+     * root is fetched separately and prepended here, the same way
+     * `GET /api/projects` folds it into its response. Its read is tolerated rather
+     * than fatal: a root record that won't parse should not 500 the whole listing.
+     */
+    const allWorkspaces = async () => {
+        const [root, children] = await Promise.all([
+            deps.projects.get(ROOT_KEY).catch(() => null),
+            deps.projects.list(),
+        ]);
+        return root ? [root, ...children] : children;
+    };
+    const read = {
+        listProjects: async () => {
+            // The root rides along as an ordinary member here so the policy wrapper's
+            // `isProjectAllowed` filter covers it for free (a scoped client whose
+            // `projects` list doesn't match `""` never sees it). The MCP handler is what
+            // splits it back out into its own `root` field — it is not a project.
+            const projects = await allWorkspaces();
+            return projects.map((p) => ({
+                slug: p.slug,
+                name: p.name,
+                area: p.group && p.group.length > 0 ? p.group : undefined,
+                status: p.status,
+            }));
+        },
+        listChats: async (projectSlug) => {
+            // ABSENT vs EMPTY (#560). `""` is the root workspace's key: an explicit
+            // address that must resolve to the root, not degrade into "every project".
+            const targets = projectSlug !== undefined
+                ? [await deps.projects.get(projectSlug)]
+                : await allWorkspaces();
+            const chats = [];
+            for (const p of targets) {
+                const sessions = await deps.herdctl.listSessions(p);
+                // Hoisted: every session in this project is keyed by the SAME keeper agent.
+                const agent = keeperAgentName(p.slug);
+                for (const s of sessions) {
+                    chats.push({
+                        project: p.slug,
+                        sessionId: s.sessionId,
+                        name: s.customName ?? s.autoName ?? s.sessionId.slice(0, 8),
+                        updatedAt: s.mtime,
+                        running: hub.isRunning(s.sessionId),
+                        // #489: the archived flag the web UI has always had (`chat-dto.ts`) but
+                        // the MCP surface never reported — so the two disagreed about what "the
+                        // chat list" is. Cost is nil: ArchiveStore lazy-loads once and caches,
+                        // so this is a `Set.has()` per chat, not a read per chat.
+                        archived: await deps.archive.isArchived(agent, s.sessionId),
+                    });
+                }
+            }
+            return chats;
+        },
+        readChat: async (projectSlug, chatSessionId) => {
+            const project = await deps.projects.get(projectSlug);
+            const messages = await deps.herdctl.sessionMessages(keeperAgentName(project.slug), chatSessionId);
+            return messages.map((m) => ({
+                role: m.role,
+                text: m.content,
+                timestamp: m.timestamp,
+            }));
+        },
+    };
+    if (!includeWrite)
+        return { read };
+    const driveModeFor = (p) => p.driveMode && isKnownDriveMode(p.driveMode) ? p.driveMode : deps.cfg.driveMode;
+    // The child runs in its TARGET project, so its spawn bound comes from THAT
+    // project's override (else the instance default), not the parent's (#262) —
+    // then narrowed by any caller-scoped cap (never widened).
+    const maxSpawnDepthFor = (p) => {
+        const resolved = resolveMaxSpawnDepth(p.maxSpawnDepth, deps.cfg.maxSpawnDepth);
+        return spawnDepthCap === undefined ? resolved : Math.min(resolved, spawnDepthCap);
+    };
+    const spawnedChild = childOf(parentProvenance);
+    // #290: the SENDER of any message these ops inject is THIS chat. Resolve its
+    // display name at injection time (best effort) so the recipient's history can
+    // say "↩ sent by <name>" and deep-link back.
+    const senderForCurrentChat = async () => {
+        const sid = currentSessionId();
+        if (!sid)
+            return { kind: "agent" };
+        let name;
+        try {
+            const cur = await deps.projects.get(currentProjectSlug);
+            const sessions = await deps.herdctl.listSessions(cur);
+            const found = sessions.find((s) => s.sessionId === sid);
+            name = found?.customName ?? found?.autoName ?? undefined;
+        }
+        catch {
+            /* name is best-effort — the link still resolves without it */
+        }
+        return { kind: "chat", project: currentProjectSlug, sessionId: sid, name };
+    };
+    /**
+     * THIS chat, as the parent edge to record on anything it creates (#509).
+     * Deliberately id-only and name-free: unlike the message sender above, a
+     * lineage edge is resolved against the live chat list at render time, so
+     * caching a display name here would just go stale.
+     *
+     * Null when there is no calling chat — the external `/mcp` transport binds
+     * `currentSessionId: () => null`, and a schedule/hook fire has no parent.
+     */
+    const parentRefForCurrentChat = () => {
+        const sid = currentSessionId();
+        return sid ? { project: currentProjectSlug, sessionId: sid } : undefined;
+    };
+    const write = {
+        currentProjectSlug,
+        currentSessionId,
+        createChat: async (projectSlug, kickoff, o) => {
+            const p = await deps.projects.get(projectSlug);
+            const composed = o?.preloadContext
+                ? await composePreloadedPrompt(projectSlug, kickoff)
+                : kickoff;
+            const overrideModel = o?.model && isKnownModel(o.model) ? o.model : undefined;
+            if (overrideModel)
+                await deps.herdctl.ensureAgentModel(p, overrideModel);
+            const newId = await startAgentTurn({
+                projectSlug,
+                agentName: keeperAgentName(projectSlug),
+                workingDir: p.workingDir,
+                resume: null,
+                prompt: composed,
+                driveMode: driveModeFor(p),
+                fallbackModel: overrideModel ?? p.model,
+                origin: spawnedChild.origin,
+                depth: spawnedChild.depth,
+                parent: parentRefForCurrentChat(),
+                maxSpawnDepth: maxSpawnDepthFor(p),
+                sender: await senderForCurrentChat(),
+            });
+            if (o?.name) {
+                await deps.herdctl
+                    .renameSession(keeperAgentName(projectSlug), newId, o.name)
+                    .catch(() => undefined);
+            }
+            return { sessionId: newId };
+        },
+        forkChat: async ({ projectSlug, sourceSessionId, prompt: kickoff, name, model }) => {
+            const p = await deps.projects.get(projectSlug);
+            if (!(await deps.herdctl.sessionExists(p, sourceSessionId))) {
+                throw new Error(`chat not found: ${sourceSessionId} in project ${projectSlug}`);
+            }
+            const newId = await deps.herdctl.forkSession(p, sourceSessionId, name);
+            // Stamp the forked CHILD's provenance here (not via startAgentTurn, which
+            // only stamps a brand-new `resume:null` chat): a fork with no kickoff never
+            // calls startAgentTurn, so this covers both cases.
+            //
+            // A fork's parent is the chat it was forked FROM, not the chat that called
+            // the tool — a fork belongs under its source in the tree. This is the only
+            // record of that edge: forkSession rewrites the source id out of the child's
+            // transcript, and a kickoff-less fork injects no message to infer it from.
+            await deps.runProvenance
+                ?.stamp(newId, childOf(parentProvenance, { project: projectSlug, sessionId: sourceSessionId }))
+                .catch(() => undefined);
+            if (kickoff && kickoff.trim().length > 0) {
+                const overrideModel = model && isKnownModel(model) ? model : undefined;
+                if (overrideModel)
+                    await deps.herdctl.ensureAgentModel(p, overrideModel);
+                await startAgentTurn({
+                    projectSlug,
+                    agentName: keeperAgentName(projectSlug),
+                    workingDir: p.workingDir,
+                    resume: newId,
+                    prompt: forkKickoffPrompt(kickoff),
+                    driveMode: driveModeFor(p),
+                    fallbackModel: overrideModel ?? p.model,
+                    origin: spawnedChild.origin,
+                    depth: spawnedChild.depth,
+                    maxSpawnDepth: maxSpawnDepthFor(p),
+                    sender: await senderForCurrentChat(),
+                });
+            }
+            return { sessionId: newId };
+        },
+        sendMessage: async (projectSlug, targetSessionId, kickoff) => {
+            const p = await deps.projects.get(projectSlug);
+            if (!(await deps.herdctl.sessionExists(p, targetSessionId))) {
+                throw new Error(`chat not found: ${targetSessionId} in project ${projectSlug}`);
+            }
+            await startAgentTurn({
+                projectSlug,
+                agentName: keeperAgentName(projectSlug),
+                workingDir: p.workingDir,
+                resume: targetSessionId,
+                prompt: kickoff,
+                driveMode: driveModeFor(p),
+                fallbackModel: p.model,
+                origin: spawnedChild.origin,
+                depth: spawnedChild.depth,
+                maxSpawnDepth: maxSpawnDepthFor(p),
+                sender: await senderForCurrentChat(),
+            });
+        },
+        setArchived: async (projectSlug, targetSessionId, archived) => {
+            await deps.projects.get(projectSlug);
+            const changed = await deps.archive.setArchived(keeperAgentName(projectSlug), targetSessionId, archived);
+            // Epic G / G1: after the archive COMMITS, emit the `onArchive` lifecycle
+            // event (only on a real transition INTO archived) so the dispatcher fires
+            // the project's enabled onArchive hooks.
+            if (changed && archived) {
+                deps.events?.emit("onArchive", { slug: projectSlug, sessionId: targetSessionId });
+            }
+        },
+        // Project provisioning (#467). Behind its OWN gate, separate from the other
+        // write tools, because this is the one that creates INSTANCE-level state. The
+        // body is deliberately the SAME two calls, in the same order, that
+        // `POST /api/projects` makes — store create, then keeper registration — so the
+        // REST and MCP paths can't drift: all validation, the #187 repo clone and its
+        // rollback live in `ProjectStore.create`.
+        projectsMcpEnabled: includeProjects,
+        createProject: async (input) => {
+            // The handler already validated `status` against PROJECT_STATUSES (the same
+            // list ProjectStatus is derived from), so narrowing it here is sound — it's
+            // only `string` on the MCP input type to keep that module free of the
+            // project layer's types.
+            const project = await deps.projects.create({
+                ...input,
+                status: input.status,
+            });
+            // Mirror the route's non-fatal treatment: the project IS created even if
+            // registering its keeper/sweeper agents fails. Unlike the route (which only
+            // logs) we report it, since the agent's very next step is usually a
+            // `create_chat` into this project, which needs a live keeper.
+            let agentRegistered = true;
+            try {
+                await deps.herdctl.ensureProjectAgent(project);
+            }
+            catch {
+                agentRegistered = false;
+            }
+            return {
+                slug: project.slug,
+                name: project.name,
+                dir: project.dir,
+                workingDir: project.workingDir,
+                repoBacked: project.repoBacked === true,
+                ...(project.repo ? { repo: project.repo } : {}),
+                agentRegistered,
+            };
+        },
+        triggersMcpEnabled: includeTriggers,
+        listTriggers: async (projectSlug) => {
+            if (!deps.triggers)
+                return [];
+            const dtos = await deps.triggers.list(projectSlug);
+            const p = await deps.projects.get(projectSlug).catch(() => null);
+            const runtime = p ? await deps.herdctl.listAgentSchedules(p).catch(() => []) : [];
+            const byName = new Map(runtime.map((s) => [s.name, s]));
+            return dtos.map((dto) => toSelfMcpTrigger(dto, byName.get(dto.name)));
+        },
+        setTrigger: async (projectSlug, name, incoming) => {
+            if (!deps.triggers)
+                throw new Error("trigger management is unavailable");
+            const existing = await deps.triggers.get(projectSlug, name).catch(() => null);
+            const record = mergeTriggerUpdate(existing, incoming);
+            const dto = await deps.triggers.set(projectSlug, name, record);
+            const p = await deps.projects.get(projectSlug).catch(() => null);
+            const runtime = p ? await deps.herdctl.listAgentSchedules(p).catch(() => []) : [];
+            const info = runtime.find((s) => s.name === name);
+            return toSelfMcpTrigger(dto, info);
+        },
+        removeTrigger: async (projectSlug, name) => {
+            if (!deps.triggers)
+                return false;
+            return deps.triggers.remove(projectSlug, name);
+        },
+        runTrigger: async (projectSlug, name) => {
+            if (!deps.triggers)
+                return null;
+            // Reject the post-turn curator up front with a clear message (the generic
+            // fire path can't run it — it has no scoped agent; see fireTrigger).
+            const p = await deps.projects.get(projectSlug).catch(() => null);
+            const rec = p?.triggers?.[name];
+            if (rec && isCuratorTrigger(rec)) {
+                throw new Error("the post-turn curator trigger runs automatically after each turn and can't be run on demand");
+            }
+            return fireTrigger(projectSlug, name);
+        },
+    };
+    return { read, write };
+}
+/**
+ * Wrap built ops so every call is checked against `principal`.
+ *
+ * Returns the ops UNCHANGED for the internal principal — the keeper path must be
+ * byte-for-byte identical to its pre-#312 behaviour, and skipping the wrapper
+ * entirely is the most honest way to guarantee that.
+ *
+ * The write bag is dropped wholesale when the principal is granted no write
+ * operation, so a read-only client's write tools are ABSENT rather than
+ * present-and-refusing — matching how the existing capability gates behave.
+ */
+export function enforceManagementPolicy(ops, principal) {
+    if (isInternalPrincipal(principal))
+        return ops;
+    const { scope } = principal;
+    const read = {
+        listProjects: async () => {
+            assertOperation(principal, "list_projects");
+            // Enumeration filters rather than denies — see the module header.
+            return (await ops.read.listProjects()).filter((p) => isProjectAllowed(scope, p.slug));
+        },
+        listChats: async (projectSlug) => {
+            assertOperation(principal, "list_chats");
+            if (projectSlug !== undefined)
+                assertProject(principal, "list_chats", projectSlug);
+            return (await ops.read.listChats(projectSlug)).filter((c) => isProjectAllowed(scope, c.project));
+        },
+        readChat: async (projectSlug, sessionId) => {
+            assertOperation(principal, "read_chat");
+            assertProject(principal, "read_chat", projectSlug);
+            return ops.read.readChat(projectSlug, sessionId);
+        },
+    };
+    const grantsAnyWrite = WRITE_OPERATIONS.some((op) => isOperationAllowed(scope, op));
+    const grantsAnyTrigger = TRIGGER_OPERATIONS.some((op) => isOperationAllowed(scope, op));
+    if (!ops.write || (!grantsAnyWrite && !grantsAnyTrigger))
+        return { read };
+    const w = ops.write;
+    // `async` so a denial surfaces as a REJECTED PROMISE, never a synchronous
+    // throw: these callbacks are typed as returning promises, and a caller that
+    // only attaches `.catch()` (rather than awaiting inside a try) would otherwise
+    // see the error escape as an unhandled exception.
+    const guard = async (operation, projectSlug, run) => {
+        assertOperation(principal, operation);
+        assertProject(principal, operation, projectSlug);
+        return run();
+    };
+    const write = {
+        currentProjectSlug: w.currentProjectSlug,
+        currentSessionId: w.currentSessionId,
+        // Instance-level, so there is no project to scope-check — only the verb.
+        projectsMcpEnabled: w.projectsMcpEnabled && isOperationAllowed(scope, "create_project"),
+        createProject: (input) => {
+            assertOperation(principal, "create_project");
+            return w.createProject(input);
+        },
+        createChat: (projectSlug, prompt, o) => guard("create_chat", projectSlug, () => w.createChat(projectSlug, prompt, o)),
+        // NOTE: `fork_chat_batch` is a convenience wrapper that calls this same
+        // callback N times, so it is gated on `fork_chat` here AND on
+        // `fork_chat_batch` at tool-assembly time (see managementToolFilter).
+        forkChat: (args) => guard("fork_chat", args.projectSlug, () => w.forkChat(args)),
+        sendMessage: (projectSlug, sessionId, prompt) => guard("send_message", projectSlug, () => w.sendMessage(projectSlug, sessionId, prompt)),
+        setArchived: (projectSlug, sessionId, archived) => guard(archived ? "archive_chat" : "unarchive_chat", projectSlug, () => w.setArchived(projectSlug, sessionId, archived)),
+        // Only offer the trigger tools when the principal is granted at least one.
+        triggersMcpEnabled: w.triggersMcpEnabled && grantsAnyTrigger,
+        listTriggers: (projectSlug) => guard("list_triggers", projectSlug, () => w.listTriggers(projectSlug)),
+        setTrigger: (projectSlug, name, trigger) => guard("set_trigger", projectSlug, () => w.setTrigger(projectSlug, name, trigger)),
+        removeTrigger: (projectSlug, name) => guard("remove_trigger", projectSlug, () => w.removeTrigger(projectSlug, name)),
+        runTrigger: (projectSlug, name) => guard("run_trigger", projectSlug, () => w.runTrigger(projectSlug, name)),
+    };
+    return { read, write };
+}
+/**
+ * A predicate selecting which MCP tools a principal should even SEE.
+ *
+ * Tool-list filtering is presentation, not enforcement — the ops wrapper above
+ * is what actually refuses a call. But hiding out-of-scope tools means a client
+ * never offers its model a verb it cannot use, which avoids a whole class of
+ * confusing "the tool exists but always errors" behaviour.
+ */
+export function managementToolFilter(principal) {
+    if (isInternalPrincipal(principal))
+        return () => true;
+    return (toolName) => {
+        if (!isOperationAllowed(principal.scope, toolName))
+            return false;
+        // The batch fan-out executes through `fork_chat`, so offering it without
+        // that grant would produce a tool that is present but denied on every call.
+        if (toolName === "fork_chat_batch")
+            return isOperationAllowed(principal.scope, "fork_chat");
+        return true;
+    };
+}

package/packages/server/dist/management-policy.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Management API policy primitives (issue #312 M1).
+ *
+ * The `ManagementPrincipal` (WHO is calling) + `ManagementScope` (WHAT they may
+ * reach) and the pure predicates that decide a single call. This module is
+ * deliberately transport-free and dependency-free: it knows nothing about MCP,
+ * HTTP, Fastify or the ops callbacks. Everything here is a pure function over
+ * plain data, so the security-critical decisions are unit-testable without a
+ * fleet, a socket, or a server.
+ *
+ * ── Why policy lives HERE and not in the MCP transport ──────────────────────
+ * The ticket's central structural decision: enforcement happens at the OPS
+ * layer, not in whichever transport happens to be calling. Paddock will grow a
+ * REST surface for the same turn-spawning operations (#465); if policy lived in
+ * the MCP handler, REST would have to reimplement it and the two would drift.
+ * So the transports authenticate (producing a principal) and the ops layer
+ * enforces (consuming one) — see management-ops.ts.
+ *
+ * ── The blast-radius framing that drives the defaults ───────────────────────
+ * `create_chat` / `send_message` / `fork_chat*` / `run_trigger` START KEEPER
+ * TURNS, and a keeper runs with Bash + Write. So **any write scope is
+ * effectively remote code execution on the host.** Read-only is therefore the
+ * default for a configured client, writes are opt-in per client, and the
+ * grammar below is deny-biased at every ambiguity: deny beats allow, an unknown
+ * operation is denied, and an empty allow-list grants nothing.
+ */
+/** How a principal proved its identity. Transports set this; policy ignores it. */
+export type ManagementCredentialKind = "internal" | "token" | "oauth";
+/**
+ * What a principal may reach. Both dimensions are independently constrained:
+ * WHICH operations (`allow`/`deny`) and WHICH projects (`projects`/
+ * `denyProjects`). A call must satisfy both.
+ */
+export interface ManagementScope {
+    /**
+     * Project slugs this principal may touch. `["*"]` = every project. Matching
+     * is exact-or-`*` (see {@link matchesPattern}); an empty list reaches nothing.
+     */
+    projects: string[];
+    /**
+     * Operation names this principal may invoke. Supports a trailing `*` wildcard
+     * (`"list_*"`) and the bare `"*"`. Empty grants nothing.
+     */
+    allow: string[];
+    /** Operation names explicitly refused. Deny ALWAYS beats allow. */
+    deny: string[];
+    /** Project slugs explicitly refused. Deny ALWAYS beats allow. */
+    denyProjects?: string[];
+    /**
+     * Recursion bound applied to turns this principal spawns. Absent ⇒ the
+     * instance/project default resolves as it does for an internal caller.
+     */
+    maxSpawnDepth?: number;
+}
+/** The authenticated caller of a management operation. */
+export interface ManagementPrincipal {
+    /**
+     * Stable per-client identity — the `managementApi.clients` key for an external
+     * caller, or `"internal"` for the in-process keeper path. This is what gets
+     * LOGGED and stamped as provenance; the credential itself never is.
+     */
+    clientId: string;
+    kind: ManagementCredentialKind;
+    scope: ManagementScope;
+}
+/** Read-only operations: no state change, no turn started. */
+export declare const READ_OPERATIONS: readonly ["list_projects", "list_chats", "read_chat"];
+/** Chat write operations. The first four START TURNS (see the RCE note above). */
+export declare const WRITE_OPERATIONS: readonly ["create_project", "create_chat", "fork_chat", "send_message", "fork_chat_batch", "archive_chat", "unarchive_chat"];
+/** Unified trigger operations (Epic T / T3). `list_triggers` is the read one. */
+export declare const TRIGGER_OPERATIONS: readonly ["list_triggers", "set_trigger", "remove_trigger", "run_trigger"];
+/** Every operation the management surface knows about. */
+export declare const ALL_OPERATIONS: readonly string[];
+/**
+ * Operations that cause a keeper turn to run — directly (`create_chat`,
+ * `send_message`, `fork_chat*`, `run_trigger`) or by arming something that will
+ * (`set_trigger`). Granting ANY of these to a principal is granting code
+ * execution on the host; kept as an explicit set so that fact stays greppable
+ * and so docs/UI can warn on it.
+ */
+/**
+ * Operations that grant code execution on the host, and so define the risk class
+ * a write scope really is. A superset of {@link TURN_SPAWNING_OPERATIONS}:
+ * `create_project` starts no turn, but it clones a CALLER-SUPPLIED git URL and
+ * creates instance-level state, which belongs in the same warning.
+ */
+export declare const HIGH_RISK_OPERATIONS: readonly string[];
+export declare const TURN_SPAWNING_OPERATIONS: readonly string[];
+/**
+ * The DEFAULT scope for a configured client that specifies none — read-only
+ * across all projects. Matches the shape written on issue #312 verbatim
+ * (`allow: ["list_*", "read_chat"]`), which covers the three read tools plus
+ * `list_triggers` while excluding every mutating verb.
+ */
+export declare const DEFAULT_READ_ONLY_SCOPE: ManagementScope;
+/** Unrestricted scope — used ONLY for the in-process keeper principal. */
+export declare const FULL_SCOPE: ManagementScope;
+/**
+ * The implicit full-trust principal for the in-process keeper path.
+ *
+ * The internal caller is bounded by DEPTH (`maxSpawnDepth`, shipped in #278),
+ * not by auth+scope — it has no credential because it isn't a distinct identity.
+ * Handing it a full scope keeps a single enforcement path (every op checks a
+ * principal) while guaranteeing the keeper behaviour is byte-for-byte unchanged:
+ * every check below short-circuits to allow.
+ */
+export declare const INTERNAL_PRINCIPAL: ManagementPrincipal;
+/** True for the implicit in-process principal (bounded by depth, not scope). */
+export declare function isInternalPrincipal(principal: ManagementPrincipal): boolean;
+/**
+ * Match one pattern against one value. Supports exactly two forms — a bare `"*"`
+ * (everything) and a trailing-`*` prefix (`"list_*"`) — plus exact equality.
+ *
+ * Deliberately NOT a general glob: a security predicate should be trivially
+ * auditable by the operator writing it, and the ticket calls for starting with
+ * explicit lists and adding globs only as needed. Anything fancier (`?`, `[]`,
+ * embedded `*`) is treated as a literal, so a typo'd pattern fails CLOSED
+ * (matches nothing) rather than accidentally widening a grant.
+ */
+export declare function matchesPattern(pattern: string, value: string): boolean;
+/**
+ * Whether `scope` permits invoking `operation`. Deny beats allow; an operation
+ * outside {@link ALL_OPERATIONS} is refused regardless of the allow-list, so a
+ * typo in config (or a tool added later that policy hasn't been taught about)
+ * can never be reached through a stale `"*"` grant.
+ */
+export declare function isOperationAllowed(scope: ManagementScope, operation: string): boolean;
+/** Whether `scope` permits touching `projectSlug`. Deny beats allow. */
+export declare function isProjectAllowed(scope: ManagementScope, projectSlug: string): boolean;
+/** The concrete operations `scope` grants, in catalogue order. */
+export declare function allowedOperations(scope: ManagementScope): string[];
+/** True when `scope` grants at least one operation that starts a keeper turn. */
+export declare function grantsTurnSpawning(scope: ManagementScope): boolean;
+export declare const OAUTH_SCOPE_READ = "paddock:read";
+export declare const OAUTH_SCOPE_WRITE = "paddock:write";
+/** Every OAuth scope this resource server understands (for discovery). */
+export declare const OAUTH_SCOPES_SUPPORTED: readonly string[];
+/**
+ * The coarse OAuth scope an operation needs. Anything that mutates state or
+ * starts a turn is `write`; everything else is `read`.
+ */
+export declare function requiredOauthScope(operation: string): string;
+/** The coarse OAuth scopes a fine-grained scope amounts to. */
+export declare function oauthScopesFor(scope: ManagementScope): string[];
+/** True when `scope` grants any operation that amounts to code execution. */
+export declare function grantsCodeExecution(scope: ManagementScope): boolean;
+/**
+ * Thrown when policy refuses a call. Carries the structured facts a transport
+ * needs to render its own error (MCP `isError` text, or an HTTP 403) and that
+ * the server log wants — `clientId` + `operation`, never the credential.
+ */
+export declare class ManagementDeniedError extends Error {
+    readonly code: "operation_denied" | "project_denied";
+    readonly clientId: string;
+    readonly operation: string;
+    readonly projectSlug?: string;
+    constructor(args: {
+        code: "operation_denied" | "project_denied";
+        clientId: string;
+        operation: string;
+        projectSlug?: string;
+    });
+}
+/** Throw unless `principal` may invoke `operation`. */
+export declare function assertOperation(principal: ManagementPrincipal, operation: string): void;
+/**
+ * Throw unless `principal` may reach `projectSlug` via `operation`. Callers that
+ * ENUMERATE (list_projects/list_chats) must filter with {@link isProjectAllowed}
+ * instead — a scoped client listing its two projects should see those two, not a
+ * denial. This assert is for calls that name a target explicitly.
+ */
+export declare function assertProject(principal: ManagementPrincipal, operation: string, projectSlug: string): void;