@capybara-hq/kernel 0.1.0-rc.13 → 0.1.0-rc.14

package/dist/http/api.module.js

@@ -60,6 +60,9 @@ import { OrgsModule } from "../orgs/orgs.module.js";
 import { OrgSettingsController } from "../orgs/settings.controller.js";
 import { RuntimeModule } from "../runtime/runtime.module.js";
 import { ConversationStreamController } from "../runtime/stream.controller.js";
+import { SetupModule } from "../setup/setup.module.js";
+import { SetupChecksController } from "../setup/setup-checks.controller.js";
+import { SetupGuidesController } from "../setup/setup-guides.controller.js";
 import { AgentSkillsController, InboxController, SkillChangesController, } from "../skills/changes.controller.js";
 import { InvocableSkillsController } from "../skills/invocable.controller.js";
 import { SkillsController } from "../skills/skills.controller.js";
@@ -138,6 +141,8 @@ const CONTROLLERS = [
     EvalRunsController,
     ModelPurposesController,
     OrgCatalogController,
+    SetupChecksController,
+    SetupGuidesController,
     OrgPluginUploadsController,
     OrgOwnedPluginsController,
     OrgComponentsController,
@@ -179,6 +184,7 @@ ApiModule = __decorate([
             UiModule,
             InboxModule,
             ThemesModule,
+            SetupModule,
         ],
         controllers: CONTROLLERS,
         providers: [{ provide: APP_GUARD, useClass: AuthGuard }],

package/dist/infra/lock/lock.service.d.ts

@@ -74,6 +74,14 @@ export declare class LockService {
     holderOf(key: string): Promise<string | null>;
     /** Deletes `key` when `holder` still owns it. */
     releaseIf(key: string, holder: string): Promise<boolean>;
+    /**
+     * Takes one of `limit` slots of the counting semaphore `key` for `holder` (a unique token), for at
+     * most `ttlMs` (a crashed holder's slot frees itself then; no renewal). False when every slot is
+     * taken. Release with {@link releaseSlot}.
+     */
+    takeSlot(key: string, holder: string, limit: number, ttlMs: number): Promise<boolean>;
+    /** Gives back `holder`'s slot of the semaphore `key` (nothing when it already expired). */
+    releaseSlot(key: string, holder: string): Promise<void>;
     /**
      * Takes `key` (no `lock:` prefix) with the caller's `holder` value for `ttlMs`, unless it is
      * held, and renews it every TTL/3 like {@link acquire} (a run longer than the TTL keeps it, a

package/dist/infra/lock/lock.service.js

@@ -20,6 +20,20 @@ import { ACQUIRE_EXCLUSIVE, ACQUIRE_SHARED, COUNT_SHARED_LEASES, DOWNGRADE_SHARE
 const RELEASE_IF = `if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end`;
 /** Extends the key only while it holds our token. */
 const RENEW_IF = `if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('pexpire', KEYS[1], tonumber(ARGV[2])) else return 0 end`;
+/**
+ * Takes a slot of a counting semaphore: a sorted set of holder tokens scored by expiry time. Expired
+ * holders (a crashed replica's) drop out first, so a slot is never lost for longer than its TTL;
+ * then the token is added when fewer than ARGV[2] slots are taken. The set itself expires with
+ * its last slot. KEYS[1] the set; ARGV: token, limit, ttl ms. Returns 1 when taken.
+ */
+const TAKE_SLOT = `local now = redis.call('time')
+local ms = tonumber(now[1]) * 1000 + math.floor(tonumber(now[2]) / 1000)
+redis.call('zremrangebyscore', KEYS[1], '-inf', ms)
+if redis.call('zcard', KEYS[1]) >= tonumber(ARGV[2]) then return 0 end
+redis.call('zadd', KEYS[1], ms + tonumber(ARGV[3]), ARGV[1])
+local last = redis.call('zrange', KEYS[1], -1, -1, 'withscores')
+redis.call('pexpireat', KEYS[1], tonumber(last[2]))
+return 1`;
 /** Resolves after `ms`; rejects with the abort reason when `signal` aborts first. */
 function sleep(ms, signal) {
     return new Promise((resolve, reject) => {
@@ -117,6 +131,19 @@ let LockService = class LockService {
     async releaseIf(key, holder) {
         return (await this.redis.eval(RELEASE_IF, 1, key, holder)) === 1;
     }
+    /**
+     * Takes one of `limit` slots of the counting semaphore `key` for `holder` (a unique token), for at
+     * most `ttlMs` (a crashed holder's slot frees itself then; no renewal). False when every slot is
+     * taken. Release with {@link releaseSlot}.
+     */
+    async takeSlot(key, holder, limit, ttlMs) {
+        assertNoTransaction("takeSlot");
+        return ((await this.redis.eval(TAKE_SLOT, 1, key, holder, String(limit), String(Math.ceil(ttlMs)))) === 1);
+    }
+    /** Gives back `holder`'s slot of the semaphore `key` (nothing when it already expired). */
+    async releaseSlot(key, holder) {
+        await this.redis.zrem(key, holder);
+    }
     /**
      * Takes `key` (no `lock:` prefix) with the caller's `holder` value for `ttlMs`, unless it is
      * held, and renews it every TTL/3 like {@link acquire} (a run longer than the TTL keeps it, a

package/dist/infra/throttler/named-throttlers.d.ts

@@ -8,6 +8,8 @@ export interface NamedThrottler {
     ttl: number;
     /** The 429 message (today's text of the route that used the limiter). */
     message: string;
+    /** The 429 error code; default `auth.rate_limited` (the credential routes'). */
+    code?: "auth.rate_limited" | "rate_limited";
     /** The credential group: throttlers of one group are reserved together (one Redis hash tag). */
     group: string;
     /** What a successful attempt does to this counter: delete it, or give one attempt back. */
@@ -29,7 +31,8 @@ export interface NamedThrottler {
  *
  * `POST /api/v1/device/authorize` and `POST /api/v1/device/token` opt in to `device-authorize-ip`
  * and `device-token-ip` with `@Throttled` (every request counts; neither checks a guessable
- * credential: the device code is 32 random bytes).
+ * credential: the device code is 32 random bytes). `POST …/guides/:guideId/checks/:checkId/run`
+ * opts in to `setup-check` (setup guides v2 §10.3: each run may call a third party).
  */
 export declare const NAMED_THROTTLERS: readonly NamedThrottler[];
 /** The storage key of a named throttler's counter for a tracker (shared by the guard and success paths). */

package/dist/infra/throttler/named-throttlers.js

@@ -32,7 +32,8 @@ const LOGIN_MSG = "Too many failed login attempts; try again later";
  *
  * `POST /api/v1/device/authorize` and `POST /api/v1/device/token` opt in to `device-authorize-ip`
  * and `device-token-ip` with `@Throttled` (every request counts; neither checks a guessable
- * credential: the device code is 32 random bytes).
+ * credential: the device code is 32 random bytes). `POST …/guides/:guideId/checks/:checkId/run`
+ * opts in to `setup-check` (setup guides v2 §10.3: each run may call a third party).
  */
 export const NAMED_THROTTLERS = [
     // (login, IP): 10; an attacker filling one login from one IP leaves the owner's other IPs alone (R25)
@@ -152,6 +153,20 @@ export const NAMED_THROTTLERS = [
         message: "Too many device code attempts; try again later",
         getTracker: (req) => sha256(principalAccountId(req)),
     },
+    // setup check runs per signed-in person (setup guides v2 §10.5): 30 a minute, every request
+    // counts (@Throttled); a cached answer costs no third-party call but still counts, as the page
+    // asks at most once per row and stale result. The edge of the route (with `retry-after`): the
+    // budget shared with the Platform tool's setup.check is SetupChecksService's own counter
+    {
+        name: "setup-check",
+        group: "setup-check",
+        onSuccess: "clear",
+        limit: 30,
+        ttl: 60_000,
+        message: "Too many setup check runs; try again in a minute",
+        code: "rate_limited",
+        getTracker: (req) => sha256(principalAccountId(req)),
+    },
 ];
 /** The storage key of a named throttler's counter for a tracker (shared by the guard and success paths). */
 export const throttlerKey = (name, tracker) => sha256(`${name}:${tracker}`);

package/dist/infra/throttler/throttler.guard.js

@@ -56,7 +56,7 @@ let KernelThrottlerGuard = class KernelThrottlerGuard extends ThrottlerGuard {
         const known = NAMED_THROTTLERS.find((t) => t.name === name);
         if (!known)
             throw new Error(`unknown throttler "${name}"`);
-        throw new ApiError("auth.rate_limited", known.message);
+        throw new ApiError(known.code ?? "auth.rate_limited", known.message);
     }
 };
 KernelThrottlerGuard = __decorate([

package/dist/overrides.d.ts

@@ -12,6 +12,7 @@ import { RUN_HOOKS, type RunHooks } from "./runtime/run-worker.js";
 import { SUBAGENT_MESSAGES_HOOKS, type SubagentMessagesHooks } from "./runtime/subagents/messages.js";
 import { USAGE_REPORT_RETRY, type UsageReportRetry } from "./runtime/usage-report.js";
 import { SANDBOX_LEASE_TIMINGS, type SandboxLeaseTimings } from "./sandbox/leases.js";
+import { SETUP_CHECK_TIMEOUT } from "./setup/setup-checks.service.js";
 import { TOOL_PIPELINE_HOOKS, type ToolPipelineHooks } from "./tools/pipeline.js";
 import { EMBED_TOKEN_CLOCK } from "./ui/embed-token.js";
 /**
@@ -24,7 +25,7 @@ import { EMBED_TOKEN_CLOCK } from "./ui/embed-token.js";
  * - `TOOL_PIPELINE_HOOKS`: the tool pipeline's hooks and policy decision;
  * - `SUBAGENT_MESSAGES_HOOKS`: the sub-agent message tools' hooks (a send raced by a run's end);
  * - `BOOTSTRAP_LOCK_TTL`, `FILE_PREVIEW_TIMEOUT`, `LIST_MODELS_TIMEOUT`, `USAGE_REPORT_RETRY`,
- *   `SANDBOX_LEASE_TIMINGS`, `CHANNEL_WEBHOOK_TIMINGS`: shorter timings;
+ *   `SANDBOX_LEASE_TIMINGS`, `CHANNEL_WEBHOOK_TIMINGS`, `SETUP_CHECK_TIMEOUT`: shorter timings;
  * - `EMBED_TOKEN_CLOCK`: the clock embed tokens are issued and checked with;
  * - `RUN_CONTEXT_CLOCK`: the clock run start reads the run context's date from, and the
  *   `CurrentTime` builtin the time;
@@ -42,6 +43,7 @@ interface KernelSeams {
     [USAGE_REPORT_RETRY]: UsageReportRetry;
     [SANDBOX_LEASE_TIMINGS]: Partial<SandboxLeaseTimings>;
     [CHANNEL_WEBHOOK_TIMINGS]: Partial<ChannelWebhookTimings>;
+    [SETUP_CHECK_TIMEOUT]: number;
     [EMBED_TOKEN_CLOCK]: () => number;
     [RUN_CONTEXT_CLOCK]: () => number;
     [APP_INTERCEPTOR]: NestInterceptor;

package/dist/overrides.js

@@ -10,6 +10,7 @@ import { RUN_HOOKS } from "./runtime/run-worker.js";
 import { SUBAGENT_MESSAGES_HOOKS, } from "./runtime/subagents/messages.js";
 import { USAGE_REPORT_RETRY } from "./runtime/usage-report.js";
 import { SANDBOX_LEASE_TIMINGS } from "./sandbox/leases.js";
+import { SETUP_CHECK_TIMEOUT } from "./setup/setup-checks.service.js";
 import { TOOL_PIPELINE_HOOKS } from "./tools/pipeline.js";
 import { EMBED_TOKEN_CLOCK } from "./ui/embed-token.js";
 const SEAM_TOKENS = [
@@ -24,6 +25,7 @@ const SEAM_TOKENS = [
     USAGE_REPORT_RETRY,
     SANDBOX_LEASE_TIMINGS,
     CHANNEL_WEBHOOK_TIMINGS,
+    SETUP_CHECK_TIMEOUT,
     EMBED_TOKEN_CLOCK,
     RUN_CONTEXT_CLOCK,
     APP_INTERCEPTOR,

package/dist/platform/exclusions.js

@@ -95,6 +95,11 @@ export const PLATFORM_EXCLUSIONS = [
         category: "transport",
         reason: "Serves icon image bytes",
     },
+    {
+        route: "GET /api/v1/admin/catalog/:itemId/guides/:guideId",
+        category: "internal",
+        reason: "The super admin's preview of a plugin's setup guide for the admin console, with no org and no target; agents assist with the org guides an org member sees",
+    },
     {
         route: "POST /api/v1/admin/catalog/items/:id/confirm",
         category: "human-only",
@@ -128,11 +133,6 @@ export const PLATFORM_EXCLUSIONS = [
         category: "transport",
         reason: "Serves icon image bytes",
     },
-    {
-        route: "GET /api/v1/orgs/:orgId/catalog/:itemId/guides/:guideId",
-        category: "internal",
-        reason: "A plugin's setup guide (an app manifest, URLs, steps) for the web's setup section; a person pastes it into the third-party platform's console, which an agent cannot reach",
-    },
     {
         route: "POST /api/v1/orgs/:orgId/catalog/:itemId/install",
         category: "secret",
@@ -593,6 +593,11 @@ export const PLATFORM_EXCLUSIONS = [
         category: "secret",
         reason: "Edits connector endpoint config that can carry credentials",
     },
+    {
+        route: "POST /api/v1/orgs/:orgId/connectors/:connectorId/guide-ack",
+        category: "human-only",
+        reason: "A person confirms they updated the app on the third-party platform after a connector template's setup guide changed; only that person knows it was done",
+    },
     {
         route: "POST /api/v1/orgs/:orgId/connectors/:connectorId/tools/:name/review",
         category: "human-only",

package/dist/platform/operation.js

@@ -87,6 +87,10 @@ export const PLATFORM_DOMAINS = [
         id: "devices",
         description: "Your own cloud devices (the workspaces your conversations run in): list, read, create, rename, delete, wipe the files.",
     },
+    {
+        id: "setup",
+        description: "Plugin setup guides: list the guides you may help with, read one as Markdown, the state of its checks for a channel connection or a connector, and running one check. Entering secrets, connecting an account and confirming the app was updated stay with the person on the web; read the docs topic `setup` first.",
+    },
     {
         id: "themes",
         description: "The themes on in this org, the one in effect for you and the org's theme setting: list. Themes are set through your preferences, the org settings and the deployment settings.",

package/dist/platform/ops/connectors.ops.js

@@ -120,6 +120,8 @@ let ConnectorsOperations = class ConnectorsOperations {
                         on: t.on,
                         switchable: t.switchable,
                         owner: t.owner,
+                        // where the template's setup guide is (catalog item and guide id), null without one
+                        guide: t.guide ?? null,
                     }));
                     return pageOf(templates, startOf(input.cursor), PAGE);
                 },

package/dist/platform/ops/setup.ops.d.ts

@@ -0,0 +1,24 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { SetupChecksService } from "../../setup/setup-checks.service.js";
+import { SetupGuidesService } from "../../setup/setup-guides.service.js";
+import { PlatformOperations } from "../registry.js";
+/**
+ * Setup guide operations of the `Platform` tool (spec 2026-11-09-setup-guides-v2-design.md §12),
+ * the `setup` domain: the guides a person may see, one guide rendered as Markdown, the cached check
+ * states of a guide and running one check. All are reads (a check never writes anywhere; its cost
+ * is bounded by the cache, the cooldown and the org's concurrency cap) and use the routes'
+ * services, so a guide carries no secret (§6.3) and check results only the fixed, redacted fields.
+ * Entering a secret, OAuth consent and the guide ack stay with the person on the web (`human-only`
+ * and `secret` exclusions); no setup operation takes a value.
+ */
+export declare class SetupOperations implements OnModuleInit {
+    private readonly registry;
+    private readonly checks;
+    private readonly guides;
+    private readonly kdb;
+    constructor(registry: PlatformOperations, checks: SetupChecksService, guides: SetupGuidesService, kdb: KernelDb);
+    /** The actor as the routes see a caller: the org, their role there now and their account. */
+    private caller;
+    onModuleInit(): void;
+}

package/dist/platform/ops/setup.ops.js

@@ -0,0 +1,212 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { CatalogGuidePathParams, CatalogGuideQuery } from "../../catalog/org-catalog.schemas.js";
+import { ApiError } from "../../errors.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { SetupCheckPathParams, SetupCheckRunBody, SetupChecksQuery, SetupGuidePathParams, } from "../../setup/setup-checks.schemas.js";
+import { SetupChecksService } from "../../setup/setup-checks.service.js";
+import { SetupGuidesQuery } from "../../setup/setup-guides.schemas.js";
+import { SetupGuidesService } from "../../setup/setup-guides.service.js";
+import { defineOperation } from "../operation.js";
+import { PlatformOperations } from "../registry.js";
+import { roleOf } from "./role.js";
+const ITEM = "00000000-0000-4000-8000-000000000000";
+const CONNECTION = "00000000-0000-4000-8000-000000000001";
+/**
+ * Setup guide operations of the `Platform` tool (spec 2026-11-09-setup-guides-v2-design.md §12),
+ * the `setup` domain: the guides a person may see, one guide rendered as Markdown, the cached check
+ * states of a guide and running one check. All are reads (a check never writes anywhere; its cost
+ * is bounded by the cache, the cooldown and the org's concurrency cap) and use the routes'
+ * services, so a guide carries no secret (§6.3) and check results only the fixed, redacted fields.
+ * Entering a secret, OAuth consent and the guide ack stay with the person on the web (`human-only`
+ * and `secret` exclusions); no setup operation takes a value.
+ */
+let SetupOperations = class SetupOperations {
+    registry;
+    checks;
+    guides;
+    kdb;
+    constructor(registry, checks, guides, kdb) {
+        this.registry = registry;
+        this.checks = checks;
+        this.guides = guides;
+        this.kdb = kdb;
+    }
+    /** The actor as the routes see a caller: the org, their role there now and their account. */
+    async caller(ctx) {
+        const role = await roleOf(this.kdb.db, ctx.orgId, ctx.actorAccountId);
+        if (role === null)
+            throw new ApiError("forbidden", "Insufficient organization role");
+        return { orgId: ctx.orgId, role, accountId: ctx.actorAccountId };
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "setup.guides",
+                description: "List the plugin setup guides this person may help with in the org: per guide its targets (channel connections, connectors made from a template, templates switched on without a connector yet), whether the guide changed since a target was set up (drift), a count of the cached check states and the web page where the person does the setup. Org admins get the admin guides; members get the guides for connecting their own account. Read a guide with setup.read.",
+                input: SetupGuidesQuery,
+                example: {},
+                authz: { orgAction: "catalog.read" },
+                mirrors: ["GET /api/v1/orgs/:orgId/setup-guides"],
+                confirm: "read",
+                run: async (input, ctx) => ({
+                    guides: await this.guides.list(await this.caller(ctx), input),
+                }),
+            }),
+            defineOperation({
+                id: "setup.read",
+                description: "Read one plugin setup guide rendered for a target as a Markdown document: the steps, the app manifest and URLs to paste at the third-party platform, and the checks as '- [check <id>] <label>' lines (run them with setup.check), with the modes, the variables that have no value yet and why, and the web page of the target. Explain the step the person is on. Secrets are never in the guide: ask the person to paste each token or secret into its field on the returned webPath, never into the conversation.",
+                input: CatalogGuidePathParams.extend(CatalogGuideQuery.shape).strict(),
+                example: { itemId: ITEM, guideId: "slack-app", connectionId: CONNECTION },
+                authz: { orgAction: "catalog.read" },
+                mirrors: ["GET /api/v1/orgs/:orgId/catalog/:itemId/guides/:guideId"],
+                confirm: "read",
+                errors: [
+                    {
+                        code: "catalog.item_not_found",
+                        next: "The plugin is not in this org's catalog; list the guides with setup.guides.",
+                    },
+                    {
+                        code: "catalog.guide_not_found",
+                        next: "The plugin has no setup guide with that id; list the guides with setup.guides.",
+                    },
+                    {
+                        code: "channel.not_found",
+                        next: "No channel connection with that id in this org; list the targets with setup.guides.",
+                    },
+                    {
+                        code: "connector.not_found",
+                        next: "No connector made from this guide's template with that id in this org; list the targets with setup.guides.",
+                    },
+                    {
+                        code: "validation_failed",
+                        next: "Pass a mode and audience the guide has (setup.guides lists the audience) and the target of its place: connectionId for a channel guide, connectorId for a connector template guide.",
+                    },
+                    {
+                        code: "forbidden",
+                        next: {
+                            member: "Only org admins read the admin guides; members read the member section of a connector template guide (audience member).",
+                        },
+                    },
+                ],
+                run: async (input, ctx) => {
+                    const { itemId, guideId, ...q } = input;
+                    return { guide: await this.guides.read(await this.caller(ctx), itemId, guideId, q) };
+                },
+            }),
+            defineOperation({
+                id: "setup.status",
+                description: "Read the cached state of every check of a plugin's setup guide for one target (a channel connection or a connector made from a template), by check id: ok, failing, unknown, running or not_run, with the reason and fix to show the person. Runs nothing; run a check with setup.check.",
+                input: SetupGuidePathParams.extend(SetupChecksQuery.shape).strict(),
+                example: { itemId: ITEM, guideId: "slack-app", connectionId: CONNECTION },
+                authz: { orgAction: "catalog.read" },
+                mirrors: ["GET /api/v1/orgs/:orgId/catalog/:itemId/guides/:guideId/checks"],
+                confirm: "read",
+                errors: [
+                    {
+                        code: "catalog.item_not_found",
+                        next: "The plugin is not in this org's catalog; check the item id on the plugin's page.",
+                    },
+                    {
+                        code: "catalog.guide_not_found",
+                        next: "The plugin has no setup guide with that id; read the guide id from the connection or connector page.",
+                    },
+                    {
+                        code: "channel.not_found",
+                        next: "No channel connection with that id in this org; list the targets with setup.guides.",
+                    },
+                    {
+                        code: "connector.not_found",
+                        next: "No connector made from this guide's template with that id in this org; list the targets with setup.guides.",
+                    },
+                    {
+                        code: "validation_failed",
+                        next: "Checks need a saved target: pass connectionId for a channel guide or connectorId for a connector template guide, and a mode and audience the guide has.",
+                    },
+                    {
+                        code: "forbidden",
+                        next: {
+                            member: "Only org admins run the admin checks of a guide; members run the member checks (audience member).",
+                        },
+                    },
+                ],
+                run: async (input, ctx) => {
+                    const { itemId, guideId, ...q } = input;
+                    return { results: await this.checks.states(await this.caller(ctx), itemId, guideId, q) };
+                },
+            }),
+            defineOperation({
+                id: "setup.check",
+                description: "Run one check of a plugin's setup guide for one target (a channel connection or a connector made from a template) and return its state: ok, failing (with a reason and a fix to explain), unknown, or running (try again in a moment). A fresh cached result is returned as is; force reruns it, at most once per 10 seconds per check and target. A check only reads; run it after the person says they finished a step.",
+                input: SetupCheckPathParams.extend(SetupCheckRunBody.shape).strict(),
+                example: {
+                    itemId: ITEM,
+                    guideId: "slack-app",
+                    checkId: "bot-token",
+                    connectionId: CONNECTION,
+                },
+                authz: { orgAction: "catalog.read" },
+                mirrors: ["POST /api/v1/orgs/:orgId/catalog/:itemId/guides/:guideId/checks/:checkId/run"],
+                confirm: "read",
+                errors: [
+                    {
+                        code: "catalog.item_not_found",
+                        next: "The plugin is not in this org's catalog; check the item id on the plugin's page.",
+                    },
+                    {
+                        code: "catalog.guide_not_found",
+                        next: "The plugin has no setup guide with that id; read the guide id from the connection or connector page.",
+                    },
+                    {
+                        code: "channel.not_found",
+                        next: "No channel connection with that id in this org; list the targets with setup.guides.",
+                    },
+                    {
+                        code: "connector.not_found",
+                        next: "No connector made from this guide's template with that id in this org; list the targets with setup.guides.",
+                    },
+                    {
+                        code: "validation_failed",
+                        next: "Checks need a saved target: pass connectionId for a channel guide or connectorId for a connector template guide, and a mode and audience the guide has.",
+                    },
+                    {
+                        code: "forbidden",
+                        next: {
+                            member: "Only org admins run the admin checks of a guide; members run the member checks (audience member).",
+                        },
+                    },
+                    {
+                        code: "catalog.check_not_found",
+                        next: "That check is not in the guide for this mode and audience; read the check ids with setup.status.",
+                    },
+                    {
+                        code: "rate_limited",
+                        next: "This person ran 30 checks in the last minute; wait a minute before running another, and read the cached states with setup.status meanwhile.",
+                    },
+                ],
+                run: async (input, ctx) => {
+                    const { itemId, guideId, checkId, ...body } = input;
+                    return {
+                        result: await this.checks.run(await this.caller(ctx), itemId, guideId, checkId, body),
+                    };
+                },
+            }),
+        ]);
+    }
+};
+SetupOperations = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations)),
+    __param(1, Inject(SetupChecksService)),
+    __param(2, Inject(SetupGuidesService)),
+    __param(3, Inject(KernelDb))
+], SetupOperations);
+export { SetupOperations };

package/dist/platform/platform-ops.module.d.ts

@@ -24,6 +24,7 @@ import { PlatformOperationsProvider } from "./ops/platform.ops.js";
 import { PluginsOperations } from "./ops/plugins.ops.js";
 import { PreviewersOperations } from "./ops/previewers.ops.js";
 import { RequestsOperations } from "./ops/requests.ops.js";
+import { SetupOperations } from "./ops/setup.ops.js";
 import { SkillsOperations } from "./ops/skills.ops.js";
 import { ThemesOperations } from "./ops/themes.ops.js";
 import { UiOperations } from "./ops/ui.ops.js";
@@ -31,7 +32,7 @@ import { UiOperations } from "./ops/ui.ops.js";
  * One provider per domain, each taking `PlatformOperations` as its first constructor argument:
  * the parity test in `tools/checks` builds the operations from it without a Nest app.
  */
-export declare const PLATFORM_OPERATION_PROVIDERS: readonly [typeof PlatformOperationsProvider, typeof SkillsOperations, typeof AgentsOperations, typeof AgentTemplatesOperations, typeof PluginsOperations, typeof MarketplacesOperations, typeof RequestsOperations, typeof ConnectorsOperations, typeof ExtensionsOperations, typeof ConversationsOperations, typeof ComponentsOperations, typeof AccountsOperations, typeof OrgsOperations, typeof AdminOperations, typeof CatalogAdminOperations, typeof OrgPluginsOperations, typeof ExtensionsAdminOperations, typeof ModelsOperations, typeof InboxOperations, typeof ApprovalsOperations, typeof ChannelsOperations, typeof OrgSettingsOperations, typeof EvalsOperations, typeof BackgroundOperations, typeof PreviewersOperations, typeof DevicesOperations, typeof AgentSkillsOperations, typeof ThemesOperations, typeof UiOperations];
+export declare const PLATFORM_OPERATION_PROVIDERS: readonly [typeof PlatformOperationsProvider, typeof SkillsOperations, typeof AgentsOperations, typeof AgentTemplatesOperations, typeof PluginsOperations, typeof MarketplacesOperations, typeof RequestsOperations, typeof ConnectorsOperations, typeof ExtensionsOperations, typeof ConversationsOperations, typeof ComponentsOperations, typeof AccountsOperations, typeof OrgsOperations, typeof AdminOperations, typeof CatalogAdminOperations, typeof OrgPluginsOperations, typeof ExtensionsAdminOperations, typeof ModelsOperations, typeof InboxOperations, typeof ApprovalsOperations, typeof ChannelsOperations, typeof OrgSettingsOperations, typeof EvalsOperations, typeof BackgroundOperations, typeof PreviewersOperations, typeof DevicesOperations, typeof AgentSkillsOperations, typeof ThemesOperations, typeof SetupOperations, typeof UiOperations];
 /**
  * The `Platform` tool's operations (ruling P2): one provider per domain, each registering its
  * operations into `PlatformOperations` from `onModuleInit`. It imports the domain modules, which

package/dist/platform/platform-ops.module.js

@@ -19,6 +19,7 @@ import { InboxModule } from "../inbox/inbox.module.js";
 import { ModelsModule } from "../models/models.module.js";
 import { OrgsModule } from "../orgs/orgs.module.js";
 import { ProvidersModule } from "../runtime/providers.js";
+import { SetupModule } from "../setup/setup.module.js";
 import { SkillsModule } from "../skills/skills.module.js";
 import { ThemesModule } from "../themes/themes.module.js";
 import { ToolsModule } from "../tools/tools.module.js";
@@ -48,6 +49,7 @@ import { PlatformOperationsProvider } from "./ops/platform.ops.js";
 import { PluginsOperations } from "./ops/plugins.ops.js";
 import { PreviewersOperations } from "./ops/previewers.ops.js";
 import { RequestsOperations } from "./ops/requests.ops.js";
+import { SetupOperations } from "./ops/setup.ops.js";
 import { SkillsOperations } from "./ops/skills.ops.js";
 import { ThemesOperations } from "./ops/themes.ops.js";
 import { UiOperations } from "./ops/ui.ops.js";
@@ -92,6 +94,8 @@ export const PLATFORM_OPERATION_PROVIDERS = [
     AgentSkillsOperations,
     // themes (themes spec §9)
     ThemesOperations,
+    // setup guide checks (setup guides v2 §12; plan task 13 adds the rest of the domain)
+    SetupOperations,
     // UI slot catalog (UI slots spec §3)
     UiOperations,
 ];
@@ -123,6 +127,7 @@ PlatformOpsModule = __decorate([
             BackgroundModule,
             FilesModule,
             ThemesModule,
+            SetupModule,
         ],
         providers: [...PLATFORM_OPERATION_PROVIDERS],
     })

package/dist/platform/route-schemas.js

@@ -19,6 +19,8 @@ import { ME_ROUTES } from "../identity/me.schemas.js";
 import { INBOX_ROUTES } from "../inbox/inbox.schemas.js";
 import { ORG_MODEL_ROUTES } from "../models/org-models.schemas.js";
 import { ORG_ROUTES, ORG_SETTINGS_ROUTES } from "../orgs/orgs.schemas.js";
+import { SETUP_CHECK_ROUTES } from "../setup/setup-checks.schemas.js";
+import { SETUP_GUIDE_ROUTES } from "../setup/setup-guides.schemas.js";
 import { SKILL_ROUTES } from "../skills/skills.schemas.js";
 import { THEME_ROUTES } from "../themes/themes.schemas.js";
 import { APPROVAL_ROUTES } from "../tools/approvals.schemas.js";
@@ -64,6 +66,9 @@ export const ROUTE_SCHEMAS = [
     ...ME_ROUTES,
     // themes (themes spec §9)
     ...THEME_ROUTES,
+    // setup guide checks (setup guides v2 §10.3, §12)
+    ...SETUP_CHECK_ROUTES,
+    ...SETUP_GUIDE_ROUTES,
     // UI slots (UI slots spec §3)
     ...UI_ROUTES,
 ];