@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/ingestion/composio/gateway.js

@@ -0,0 +1,469 @@
+import { IngestionError } from "../errors.js";
+import { fingerprint } from "../fingerprint.js";
+/**
+ * Gateway for Composio, the second aggregator.
+ *
+ * It speaks Composio's REST v3.1 through plain `fetch`. Authorization is a
+ * single `x-api-key` header on every request, with no OAuth dance, which is
+ * why this adapter carries no SDK and adds no npm dependency.
+ *
+ * Three properties this module holds on purpose:
+ *
+ *  - The platform key is SERVER SIDE ONLY. It is read from the environment,
+ *    never returned to a client, never logged, and only ever placed in an
+ *    outbound header (and in the per-turn MCP header set).
+ *  - NOTHING here writes to disk. There is no `node:fs` import anywhere under
+ *    `ingestion/composio/`, and `no-persistence.test.ts` fails the build if one
+ *    appears. The ids below are PLATFORM state, shared by every user of this
+ *    daemon; a persisted copy would rot the moment someone deletes the resource
+ *    in the Composio dashboard, which is exactly why the caches are in-memory
+ *    and list-first: after a restart the first call rediscovers by name.
+ *  - `mcpTarget` results are per turn. The returned object carries a live
+ *    credential, so it is never assigned to a stored object and never crosses
+ *    back to a client.
+ *
+ * The lifecycle this adapter hides from the rest of the daemon:
+ *
+ *  - one AUTH CONFIG per toolkit (Composio-managed OAuth), created lazily on
+ *    the first connect and reused by every user;
+ *  - one MCP SERVER per toolkit, named deterministically `paseo-<slug>`, also
+ *    shared. Isolation between users comes from the `user_id` baked into the
+ *    generated per-user MCP URL, not from a per-user server.
+ */
+const API_BASE = "https://backend.composio.dev/api/v3.1";
+/** One catalogue page: the infinite scroll in the client loads 20 at a time. */
+const TOOLKITS_LIMIT = 20;
+/**
+ * The event body, parsed out of the JSON string Composio wraps it in.
+ *
+ * A body that is absent, unparseable or not an object becomes `{}` rather than
+ * an exception: a filter clause resolving against `{}` simply does not match,
+ * which is the honest outcome for an item whose content we could not read.
+ */
+function parseTriggerPayload(raw) {
+    if (!raw) {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function notConfigured() {
+    throw new IngestionError("COMPOSIO_OFF", "Composio sources are not configured on this daemon.", 422);
+}
+/**
+ * The internal 404 sentinel: an id we cached no longer exists upstream.
+ *
+ * Module-private on purpose. It is never exported and is never allowed to
+ * escape a public method: every path either converts it (COMPOSIO_NEEDS_SETUP
+ * at the create site, SOURCE_GONE after the single retry) or recovers from it.
+ */
+class GoneError extends Error {
+}
+/**
+ * Not defensive padding: the id genuinely arrives under a different key on the
+ * list endpoint than on the create endpoint.
+ */
+function readAuthConfigId(raw) {
+    return raw?.auth_config?.id ?? raw?.id ?? raw?.nanoid ?? null;
+}
+/** Composio has more account states than the flow needs; reduce to the contract's three. */
+function normalizeStatus(raw) {
+    const status = (raw ?? "").toUpperCase();
+    if (status === "ACTIVE") {
+        return "active";
+    }
+    // Both spellings mean the same thing: the user is still inside the popup.
+    if (status === "INITIALIZING" || status === "INITIATED") {
+        return "pending";
+    }
+    return "inactive";
+}
+/**
+ * Deterministic MCP server name (Composio accepts 4-30 alphanumeric-or-hyphen
+ * characters). Deterministic so a daemon restart rediscovers the server by name
+ * instead of creating a duplicate on every boot.
+ */
+function serverNameFor(slug) {
+    const cleaned = slug.toLowerCase().replace(/[^a-z0-9-]+/g, "-");
+    return `paseo-${cleaned}`.slice(0, 30);
+}
+export function createComposioGateway(config) {
+    const apiKey = config.apiKey;
+    const configured = Boolean(apiKey);
+    /** The platform key, narrowed. Nothing reaches the network without it. */
+    function platformKey() {
+        if (!apiKey) {
+            notConfigured();
+        }
+        return apiKey;
+    }
+    /**
+     * The single outbound seam. Every request in this file goes through it, so
+     * the status mapping below is exhaustive by construction:
+     *
+     *   fetch throws  -> COMPOSIO_OFFLINE  (the host is unreachable)
+     *   401 / 403     -> COMPOSIO_AUTH     (Composio rejected OUR platform key)
+     *   404           -> GoneError         (internal; the caller decides meaning)
+     *   other non-ok  -> COMPOSIO_ERROR    (a 500 is Composio failing, not "offline")
+     */
+    async function call(method, path, body) {
+        const key = platformKey();
+        let response;
+        try {
+            response = await fetch(`${API_BASE}${path}`, {
+                method,
+                headers: {
+                    "x-api-key": key,
+                    ...(body !== undefined ? { "content-type": "application/json" } : {}),
+                },
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+            });
+        }
+        catch {
+            throw new IngestionError("COMPOSIO_OFFLINE", "Could not reach Composio. Check this machine's network connection.", 502);
+        }
+        if (response.status === 401 || response.status === 403) {
+            throw new IngestionError("COMPOSIO_AUTH", "Composio rejected this daemon's API key (PASEO_COMPOSIO_API_KEY).", 502);
+        }
+        if (response.status === 404) {
+            throw new GoneError(path);
+        }
+        if (!response.ok) {
+            throw new IngestionError("COMPOSIO_ERROR", `Composio responded with an error (${response.status}). Try again.`, 502);
+        }
+        return (await response.json());
+    }
+    /**
+     * Memoizes the PROMISE, not the value: two concurrent turns asking for the
+     * same toolkit perform ONE creation. A rejected promise is evicted, so a
+     * network blip cannot poison the slug for the life of the process.
+     */
+    function memo(cache, key, produce) {
+        const hit = cache.get(key);
+        if (hit) {
+            return hit;
+        }
+        const promise = produce().catch((error) => {
+            cache.delete(key);
+            throw error;
+        });
+        cache.set(key, promise);
+        return promise;
+    }
+    // Instance-local, never module scope and never persisted: two gateways in one
+    // process must not share ids, and a stored id would rot silently.
+    const authConfigs = new Map();
+    const servers = new Map();
+    /** Generated per-user MCP URL, keyed `slug:externalUserId`. In memory only. */
+    const userUrls = new Map();
+    /**
+     * List-first: reuse whatever already exists, including an auth config created
+     * by hand in the dashboard and one created before the last restart. Only an
+     * empty list leads to a create.
+     */
+    function ensureAuthConfig(slug) {
+        return memo(authConfigs, slug, async () => {
+            // Deliberately OUTSIDE the try/catch below: a 404 on the LIST is a rotted
+            // request, not a setup requirement, so it must stay a GoneError and reach
+            // the recovery wrapper.
+            const found = await call("GET", `/auth_configs?toolkit_slug=${encodeURIComponent(slug)}&limit=10`);
+            for (const item of found.items ?? []) {
+                const id = readAuthConfigId(item);
+                if (id) {
+                    return id;
+                }
+            }
+            let created;
+            try {
+                created = await call("POST", "/auth_configs", {
+                    toolkit: { slug },
+                    auth_config: { type: "use_composio_managed_auth" },
+                });
+            }
+            catch (error) {
+                /*
+                 * No self-service for this toolkit: Composio refuses to create the
+                 * config. 404 (their code 306, "no managed credentials") for SAML apps
+                 * like SAP SuccessFactors, 400 for own-OAuth apps like Workday.
+                 *
+                 * A 404 HERE is not a rotted id, because there is no id yet. Converting
+                 * it inside this function is the mechanism that keeps it away from
+                 * `withRecovery`: the GoneError simply never reaches the wrapper, so no
+                 * retry can fire. Do not replace this with a flag threaded through the
+                 * wrapper.
+                 */
+                if (error instanceof GoneError ||
+                    (error instanceof IngestionError && error.code === "COMPOSIO_ERROR")) {
+                    throw new IngestionError("COMPOSIO_NEEDS_SETUP", "This app needs its own OAuth or SAML setup. Create the auth config for it in the Composio dashboard, then try again.", 422);
+                }
+                throw error;
+            }
+            const id = readAuthConfigId(created);
+            if (!id) {
+                throw new IngestionError("COMPOSIO_ERROR", "Composio returned no auth config id.", 502);
+            }
+            return id;
+        });
+    }
+    /** Create, or rediscover by deterministic name, the MCP server for a toolkit. */
+    function ensureMcpServer(slug) {
+        return memo(servers, slug, async () => {
+            const authConfigId = await ensureAuthConfig(slug);
+            const name = serverNameFor(slug);
+            const list = await call("GET", "/mcp/servers?limit=100");
+            const existing = (list.items ?? []).find((server) => server.name === name);
+            if (existing?.id) {
+                return existing.id;
+            }
+            const created = await call("POST", "/mcp/servers", {
+                name,
+                auth_config_ids: [authConfigId],
+                managed_auth_via_composio: true,
+            });
+            if (!created.id) {
+                throw new IngestionError("COMPOSIO_ERROR", "Composio returned no MCP server id.", 502);
+            }
+            return created.id;
+        });
+    }
+    /**
+     * Recovery for the OTHER 404, the one that means an id we cached rotted.
+     *
+     * Composio answers 404 for two unrelated conditions and the right response to
+     * each is the opposite of the other:
+     *
+     *  - "no Composio-managed credentials for this toolkit", raised by the CREATE
+     *    call, means nobody has set the app up yet. Retrying it is pointless and
+     *    the message must say "create the auth config in the dashboard". That
+     *    case never arrives here: `ensureAuthConfig` converts it at the create
+     *    site, before the GoneError can escape.
+     *  - "the auth config or MCP server whose id we cached was deleted in the
+     *    dashboard", raised mid-flow by a call carrying that id. That IS
+     *    recoverable: drop the caches for the slug and run once more.
+     *
+     * Conflating them fails in both directions. In integrahr this exact
+     * conflation told SAP SuccessFactors "no longer exists... reconnect" when the
+     * truth was "nobody has created the auth config yet".
+     *
+     * The retry is bounded to one. A second GoneError is a permanently deleted
+     * resource, so it becomes SOURCE_GONE rather than another attempt.
+     */
+    async function withRecovery(slug, externalUserId, run) {
+        try {
+            return await run();
+        }
+        catch (error) {
+            if (!(error instanceof GoneError)) {
+                throw error;
+            }
+            authConfigs.delete(slug);
+            servers.delete(slug);
+            userUrls.delete(`${slug}:${externalUserId}`);
+            try {
+                return await run();
+            }
+            catch (again) {
+                if (!(again instanceof GoneError)) {
+                    throw again;
+                }
+                throw new IngestionError("SOURCE_GONE", "This app's setup no longer exists in Composio; reconnect this source.", 502);
+            }
+        }
+    }
+    /**
+     * The boundary for the two methods that carry no cached id. A 404 from either
+     * is a real answer from Composio about a real resource, so it must surface
+     * rather than trigger the eviction-and-retry path. The GoneError sentinel is
+     * module-private though, so it is converted here rather than escaping: no
+     * caller of this gateway ever sees anything but an IngestionError.
+     */
+    async function surfacing(run) {
+        try {
+            return await run();
+        }
+        catch (error) {
+            if (error instanceof GoneError) {
+                throw new IngestionError("COMPOSIO_ERROR", "Composio responded with an error (404). Try again.", 502);
+            }
+            throw error;
+        }
+    }
+    function mcpHeaders() {
+        return { "x-api-key": platformKey() };
+    }
+    return {
+        configured,
+        async listSources(query, cursor) {
+            if (!configured) {
+                notConfigured();
+            }
+            const params = new URLSearchParams({
+                limit: String(TOOLKITS_LIMIT),
+                // With no search term, popular first (Gmail, Slack...), not alphabetical.
+                sort_by: "usage",
+            });
+            const trimmed = query.trim();
+            if (trimmed) {
+                params.set("search", trimmed);
+            }
+            if (cursor) {
+                params.set("cursor", cursor);
+            }
+            // Not wrapped in withRecovery: the catalogue carries no cached id.
+            const body = await surfacing(() => call("GET", `/toolkits?${params.toString()}`));
+            const items = [];
+            for (const toolkit of body.items ?? []) {
+                if (!toolkit.slug) {
+                    continue;
+                }
+                items.push({
+                    slug: toolkit.slug,
+                    name: toolkit.name ?? toolkit.slug,
+                    imgSrc: toolkit.meta?.logo ?? "",
+                    description: toolkit.meta?.description ?? "",
+                });
+                if (items.length >= TOOLKITS_LIMIT) {
+                    break;
+                }
+            }
+            return {
+                items,
+                // A next page is only offered when this one came back full. A cursor
+                // handed out from a partial page makes the UI request blank pages
+                // forever.
+                nextCursor: items.length === TOOLKITS_LIMIT ? (body.next_cursor ?? null) : null,
+            };
+        },
+        async connect(externalUserId, appSlug) {
+            if (!configured) {
+                notConfigured();
+            }
+            return withRecovery(appSlug, externalUserId, async () => {
+                const authConfigId = await ensureAuthConfig(appSlug);
+                const body = await call("POST", "/connected_accounts/link", {
+                    auth_config_id: authConfigId,
+                    user_id: externalUserId,
+                });
+                if (!body.redirect_url) {
+                    throw new IngestionError("COMPOSIO_ERROR", "Composio returned no authorization URL.", 502);
+                }
+                // Composio's link response carries no expiry, and the contract says to
+                // report that as null rather than invent one.
+                return { redirectUrl: body.redirect_url, expiresAt: null };
+            });
+        },
+        async listAccounts(externalUserId, appSlug) {
+            if (!configured) {
+                notConfigured();
+            }
+            // Deliberately NOT wrapped in withRecovery: this call carries no cached
+            // id, so a 404 here is a real answer from Composio and must surface.
+            const params = new URLSearchParams({
+                user_ids: externalUserId,
+                toolkit_slugs: appSlug,
+            });
+            const body = await surfacing(() => call("GET", `/connected_accounts?${params.toString()}`));
+            const accounts = [];
+            for (const item of body.items ?? []) {
+                if (!item.id) {
+                    continue;
+                }
+                accounts.push({ id: item.id, status: normalizeStatus(item.status) });
+            }
+            return accounts;
+        },
+        /**
+         * One page of history, read from Composio's trigger event log.
+         *
+         * `POST /internal/trigger/logs` is the only endpoint Composio exposes that
+         * returns what actually arrived on a connected account (verified against
+         * the live OpenAPI document at `backend.composio.dev/api/v3/openapi.json`
+         * on 2026-08-22). It is under `/internal/`, so `RawTriggerLog` treats every
+         * field as optional and an unreadable row is skipped rather than thrown.
+         *
+         * `accountId` narrows nothing here on purpose: the log is scoped by
+         * `userId`, and Composio's `connectionId` is the connected-account id only
+         * for accounts created through this daemon. Filtering on it would silently
+         * hide a user's own dashboard-created connection.
+         *
+         * A read, and only a read: no MCP server is ensured, no auth config is
+         * created, nothing is cached and nothing is written.
+         */
+        async listItems(input) {
+            if (!configured) {
+                notConfigured();
+            }
+            // Not wrapped in withRecovery: this path carries no cached id, so a 404
+            // is a real answer about a real resource rather than a rotted reference.
+            const body = await surfacing(() => call("POST", "/internal/trigger/logs", {
+                userId: input.externalUserId,
+                from: input.sinceMs,
+                limit: input.limit,
+                include_payload: true,
+                ...(input.cursor ? { cursor: input.cursor } : {}),
+            }));
+            const items = [];
+            for (const log of body.data ?? []) {
+                if (!log.id) {
+                    continue;
+                }
+                // The log is not filterable by toolkit upstream, so the app match
+                // happens here. Case-insensitive: Composio writes `appName` in display
+                // casing ("Gmail") while a source stores the slug ("gmail").
+                if ((log.appName ?? "").toLowerCase() !== input.appSlug.toLowerCase()) {
+                    continue;
+                }
+                // An item we cannot date cannot be placed in the window, and inventing
+                // a timestamp would silently move it into or out of one.
+                const timestampMs = Date.parse(log.createdAt ?? "");
+                if (!Number.isFinite(timestampMs)) {
+                    continue;
+                }
+                const payload = parseTriggerPayload(log.meta?.triggerClientPayload);
+                const triggerName = log.meta?.triggerName ?? input.appSlug;
+                items.push({
+                    key: fingerprint("composio", input.appSlug, log.id),
+                    contentHash: fingerprint(JSON.stringify(payload)),
+                    timestampMs,
+                    title: triggerName,
+                    subtitle: log.status ?? "",
+                    payload,
+                });
+            }
+            return { items, cursor: body.nextCursor ?? null };
+        },
+        async mcpTarget(externalUserId, appSlug) {
+            if (!configured) {
+                notConfigured();
+            }
+            const key = `${appSlug}:${externalUserId}`;
+            const cached = userUrls.get(key);
+            if (cached) {
+                return { url: cached, headers: mcpHeaders() };
+            }
+            const url = await withRecovery(appSlug, externalUserId, async () => {
+                const serverId = await ensureMcpServer(appSlug);
+                const generated = await call("POST", "/mcp/servers/generate", { mcp_server_id: serverId, user_ids: [externalUserId] });
+                const perUser = generated.user_ids_url?.[0];
+                if (perUser) {
+                    return perUser;
+                }
+                if (generated.mcp_url) {
+                    const separator = generated.mcp_url.includes("?") ? "&" : "?";
+                    return `${generated.mcp_url}${separator}user_id=${encodeURIComponent(externalUserId)}`;
+                }
+                throw new IngestionError("COMPOSIO_ERROR", "Composio returned no MCP server URL.", 502);
+            });
+            userUrls.set(key, url);
+            return { url, headers: mcpHeaders() };
+        },
+    };
+}
+//# sourceMappingURL=gateway.js.map

package/dist/server/server/ingestion/dry-run.d.ts

@@ -0,0 +1,70 @@
+import type { StoredFilter } from "@hyperdrive.bot/fleet-protocol/ingestion/filter-types";
+import type { CapReport, DryRunResult } from "@hyperdrive.bot/fleet-protocol/ingestion/types";
+import type { CapLimiter } from "./cap-limiter.js";
+import type { MatchedItemGroup } from "./types.js";
+/** Everything the dispatcher needs for one group, and nothing it does not. */
+export interface DryRunPlan {
+    runId: string;
+    groupKey: string;
+    itemKeys: string[];
+    prompt: string;
+    labels: Record<string, string>;
+    /** Empty on purpose. Replaces filter.target.config.mcpServers verbatim. See D-5.2-B. */
+    mcpServers: Record<string, never>;
+}
+/**
+ * The narrow view of `ScheduleService` this module dispatches through.
+ *
+ * Structural, with no adapter class: `ScheduleService` satisfies it directly, so
+ * the dry run mints its session through the SAME code path the overnight tick
+ * uses. A second minting path is how the two would drift on `unattended`, on
+ * archival, or on title derivation.
+ */
+export interface DryRunDispatcher {
+    runUnattendedSession(input: {
+        targetConfig: StoredFilter["target"]["config"];
+        prompt: string;
+        labels: Record<string, string>;
+        mcpServersOverride?: Record<string, unknown>;
+    }): Promise<{
+        agentId: string;
+        output: string | null;
+    }>;
+}
+/**
+ * Everything one dry-run session needs, computed without touching anything.
+ *
+ * Pure and synchronous: no clock, no `randomUUID`, no I/O. The `runId` is a
+ * parameter precisely so this stays true - two calls with identical arguments
+ * return a deeply-equal object, which is what makes the prompt and the
+ * MCP-stripping assertable without an agent runtime.
+ */
+export declare function planDryRun(params: {
+    filter: StoredFilter;
+    group: MatchedItemGroup;
+    runId: string;
+}): DryRunPlan;
+/**
+ * The single admission point for the dry-run verb.
+ *
+ * Admission happens HERE, once, rather than in Story 5.3's `applySelection`,
+ * so the ceiling sits in the same module as the loop it bounds (D-5.2-C).
+ * `applySelection` delegates to this function for `mode: "dry-run"` and calls no
+ * admit method of its own.
+ *
+ * The limiter admits GROUPS, not items, because `cap.runsPerDay` counts sessions
+ * (D-5.2-E). Group first, admit second: admitting items and then grouping would
+ * let a filter capped at 10 dispatch 10 sessions covering far more than 10 items,
+ * and the number on the confirmation screen would stop meaning anything.
+ */
+export declare function runDryRun(params: {
+    filter: StoredFilter;
+    groups: MatchedItemGroup[];
+    limiter: Pick<CapLimiter, "admitDryRun">;
+    dispatcher: DryRunDispatcher;
+    runIdFactory?: () => string;
+}): Promise<{
+    results: DryRunResult[];
+    report: CapReport;
+}>;
+//# sourceMappingURL=dry-run.d.ts.map

package/dist/server/server/ingestion/dry-run.js

@@ -0,0 +1,142 @@
+// The dry-run verb: run a filter's brief over a selection and read back what each
+// session WOULD read, produce and stop at, with nothing outward happening.
+//
+// Three guarantees, and each one is expressed as an ABSENT PARAMETER rather than
+// as a rule somebody has to remember:
+//
+//   1. Nothing is written to `ingestion_items` or `ingestion_dispatch_budget`.
+//      Neither function here receives the on-disk item store, the budget store or
+//      a database handle, so there is no method on any object in scope that could
+//      write a row. Freshness is not consumed either: a dry run followed by an
+//      apply dispatches the full set.
+//   2. No source reach. Neither function receives a `SourceGateway`, so the method
+//      that hands a session its source tools cannot be called from here, and the
+//      minted session's config carries zero MCP servers.
+//   3. No schedule run. Nothing here touches `ScheduleStore` or the single-flight
+//      set, so a dry run leaves `runs`, `lastRunAt` and `nextRunAt` alone.
+//
+// WHAT `mcpServers: {}` DOES AND DOES NOT GUARANTEE. It is a guarantee about what
+// PASEO contributes: the dry-run session receives zero MCP servers from us, and
+// the module that builds it never holds a gateway to ask one for. It is NOT a
+// guarantee about the provider CLI's own ambient MCP configuration on the opt-in
+// PTY transport: `buildInteractiveFlags`
+// (`agent/providers/claude/pty-session-launcher.ts:120`) only passes
+// `--mcp-config` when the record is non-empty, so an empty record leaves the CLI
+// free to load `~/.claude.json` and project `.mcp.json` servers. That is true of
+// every paseo session including the overnight tick, it is not introduced here,
+// and closing it means adding `--strict-mcp-config` to a pinned claude build.
+// Tracked in `~/super-repo/docs/tech-debt.md`; deliberately not fixed in this
+// story, because a flag the pinned build does not recognise aborts the spawn.
+import { randomUUID } from "node:crypto";
+import { FILTER_ID_LABEL, INGESTION_MODE_LABEL, ITEM_GROUP_LABEL, ITEM_KEYS_LABEL, } from "@hyperdrive.bot/fleet-protocol/agent-labels";
+import { buildSourceRunPrompt } from "../schedule/source-prompt.js";
+/**
+ * Everything one dry-run session needs, computed without touching anything.
+ *
+ * Pure and synchronous: no clock, no `randomUUID`, no I/O. The `runId` is a
+ * parameter precisely so this stays true - two calls with identical arguments
+ * return a deeply-equal object, which is what makes the prompt and the
+ * MCP-stripping assertable without an agent runtime.
+ */
+export function planDryRun(params) {
+    const { filter, group, runId } = params;
+    const itemKeys = group.items.map((item) => item.key);
+    return {
+        runId,
+        groupKey: group.key,
+        itemKeys,
+        prompt: buildSourceRunPrompt({
+            filter,
+            items: group.items,
+            runId,
+            mode: "dry-run",
+        }),
+        // Four labels, and no `paseo.schedule-id` / `paseo.schedule-run`: a dry run is
+        // not a schedule run, so labelling it as one would put a phantom row in every
+        // surface that walks schedule provenance.
+        labels: {
+            [FILTER_ID_LABEL]: filter.id,
+            [ITEM_GROUP_LABEL]: group.key,
+            [ITEM_KEYS_LABEL]: itemKeys.join(","),
+            [INGESTION_MODE_LABEL]: "dry-run",
+        },
+        // An empty RECORD, not an empty array: `ScheduleTargetSchema.config.mcpServers`
+        // is `z.record(...)` and `AgentSessionConfig.mcpServers` is
+        // `Record<string, McpServerConfig>`, so `[]` would not type-check against
+        // either. `{}` expresses the same decision in the type this codebase has, and
+        // it replaces the filter's stored record entirely rather than merging with it.
+        // See D-5.2-B.
+        mcpServers: {},
+    };
+}
+/**
+ * The single admission point for the dry-run verb.
+ *
+ * Admission happens HERE, once, rather than in Story 5.3's `applySelection`,
+ * so the ceiling sits in the same module as the loop it bounds (D-5.2-C).
+ * `applySelection` delegates to this function for `mode: "dry-run"` and calls no
+ * admit method of its own.
+ *
+ * The limiter admits GROUPS, not items, because `cap.runsPerDay` counts sessions
+ * (D-5.2-E). Group first, admit second: admitting items and then grouping would
+ * let a filter capped at 10 dispatch 10 sessions covering far more than 10 items,
+ * and the number on the confirmation screen would stop meaning anything.
+ */
+export async function runDryRun(params) {
+    const { filter, groups, limiter, dispatcher } = params;
+    // Matches `service.ts`'s run-id minting. A parameter so tests are deterministic;
+    // `planDryRun` itself stays free of `randomUUID` so it can stay pure.
+    const runIdFactory = params.runIdFactory ?? (() => randomUUID());
+    const admission = limiter.admitDryRun(filter.id, groups, filter.cap.runsPerDay);
+    const results = [];
+    // SEQUENTIAL, one session at a time, never a parallel fan-out: a selection of 40
+    // groups must not open 40 provider sessions in one working directory. Awaiting
+    // each dispatch is what bounds concurrency here, and it is also why no
+    // single-flight lock is taken - a dry run persists nothing and produces no
+    // outward artifact, so it cannot race the overnight tick's dedupe. Widening
+    // the schedule service's in-flight set to cover it would only make a rehearsal
+    // able to block a real run.
+    //
+    // A dispatch that rejects does NOT abort the rest: one bad group is one failed
+    // card, not a lost run over the other 39.
+    for (const group of admission.admitted) {
+        const plan = planDryRun({ filter, group, runId: runIdFactory() });
+        try {
+            const outcome = await dispatcher.runUnattendedSession({
+                targetConfig: filter.target.config,
+                prompt: plan.prompt,
+                labels: plan.labels,
+                mcpServersOverride: plan.mcpServers,
+            });
+            results.push({
+                groupKey: plan.groupKey,
+                itemKeys: plan.itemKeys,
+                runId: plan.runId,
+                agentId: outcome.agentId,
+                status: "succeeded",
+                // A session that ended with nothing to say is a succeeded run with an
+                // empty plan, surfaced as an empty state rather than as a blank card.
+                // It is NOT reported as a failure: empty output is not evidence of a
+                // crash any more than it is evidence of success.
+                plan: outcome.output ?? "",
+                error: null,
+            });
+        }
+        catch (error) {
+            results.push({
+                groupKey: plan.groupKey,
+                itemKeys: plan.itemKeys,
+                runId: plan.runId,
+                agentId: null,
+                status: "failed",
+                plan: "",
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    // The report goes back verbatim, `truncated` included. A dry run that covered
+    // 10 of the 40 selected groups has to be able to say so; a cap nobody renders
+    // is a silent cap.
+    return { results, report: admission.report };
+}
+//# sourceMappingURL=dry-run.js.map