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

package/dist/devices/dto.d.ts

@@ -1,66 +1,25 @@
 import { z } from "zod";
-/** `POST /api/v1/device/authorize`: the machine as the program describes it. */
-export declare const DeviceAuthorizeBody: z.ZodObject<{
+/** A device's name: trimmed, 1-64 characters (unique per person, case-insensitive). */
+export declare const DeviceName: z.ZodString;
+export declare const DeviceNameBody: z.ZodObject<{
     name: z.ZodString;
-    os: z.ZodEnum<{
-        darwin: "darwin";
-        linux: "linux";
-    }>;
-    arch: z.ZodString;
-    programVersion: z.ZodString;
 }, z.core.$strict>;
-/** `POST /api/v1/device/token`: the secret device code from `authorize`. */
-export declare const DeviceTokenBody: z.ZodObject<{
-    deviceCode: z.ZodString;
-}, z.core.$strict>;
-export declare const DeviceUserCodeParams: z.ZodObject<{
-    userCode: z.ZodString;
+export declare const DeviceParams: z.ZodObject<{
+    id: z.ZodString;
 }, z.core.$strip>;
-export declare const DeviceUserCodeBody: z.ZodObject<{
-    userCode: z.ZodString;
-}, z.core.$strict>;
-/**
- * `POST /api/v1/device/confirm`: the org and exactly one of an existing device environment of the
- * person's (`environmentId`) or the name of a new one (`name`).
- */
-export declare const DeviceConfirmBody: z.ZodObject<{
-    userCode: z.ZodString;
-    orgId: z.ZodString;
-    environmentId: z.ZodOptional<z.ZodUUID>;
-    name: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
-declare const DeviceAuthorizeBodyDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
+declare const DeviceCreateBodyDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
     name: z.ZodString;
-    os: z.ZodEnum<{
-        darwin: "darwin";
-        linux: "linux";
-    }>;
-    arch: z.ZodString;
-    programVersion: z.ZodString;
 }, z.core.$strict>>;
-export declare class DeviceAuthorizeBodyDto extends DeviceAuthorizeBodyDto_base {
+export declare class DeviceCreateBodyDto extends DeviceCreateBodyDto_base {
 }
-declare const DeviceTokenBodyDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
-    deviceCode: z.ZodString;
+declare const DeviceRenameBodyDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
+    name: z.ZodString;
 }, z.core.$strict>>;
-export declare class DeviceTokenBodyDto extends DeviceTokenBodyDto_base {
+export declare class DeviceRenameBodyDto extends DeviceRenameBodyDto_base {
 }
-declare const DeviceUserCodeParamsDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
-    userCode: z.ZodString;
+declare const DeviceParamsDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
+    id: z.ZodString;
 }, z.core.$strip>>;
-export declare class DeviceUserCodeParamsDto extends DeviceUserCodeParamsDto_base {
-}
-declare const DeviceUserCodeBodyDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
-    userCode: z.ZodString;
-}, z.core.$strict>>;
-export declare class DeviceUserCodeBodyDto extends DeviceUserCodeBodyDto_base {
-}
-declare const DeviceConfirmBodyDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
-    userCode: z.ZodString;
-    orgId: z.ZodString;
-    environmentId: z.ZodOptional<z.ZodUUID>;
-    name: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>>;
-export declare class DeviceConfirmBodyDto extends DeviceConfirmBodyDto_base {
+export declare class DeviceParamsDto extends DeviceParamsDto_base {
 }
 export {};

package/dist/devices/dto.js

@@ -1,44 +1,12 @@
 import { z } from "zod";
-import { EnvironmentName } from "../environments/dto.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
-/** `POST /api/v1/device/authorize`: the machine as the program describes it. */
-export const DeviceAuthorizeBody = z
-    .object({
-    name: z.string().trim().min(1).max(64),
-    os: z.enum(["darwin", "linux"]),
-    arch: z.string().trim().min(1).max(32),
-    programVersion: z.string().trim().min(1).max(64),
-})
-    .strict();
-/** `POST /api/v1/device/token`: the secret device code from `authorize`. */
-export const DeviceTokenBody = z.object({ deviceCode: z.string().min(1).max(200) }).strict();
-/** A user code as typed (`XXXX-XXXX`; case, spaces and the dash are forgiven). */
-const UserCode = z.string().min(1).max(32);
-export const DeviceUserCodeParams = z.object({ userCode: UserCode });
-export const DeviceUserCodeBody = z.object({ userCode: UserCode }).strict();
-/**
- * `POST /api/v1/device/confirm`: the org and exactly one of an existing device environment of the
- * person's (`environmentId`) or the name of a new one (`name`).
- */
-export const DeviceConfirmBody = z
-    .object({
-    userCode: UserCode,
-    orgId: z.string().min(1).max(100),
-    environmentId: z.uuid().optional(),
-    name: EnvironmentName.optional(),
-})
-    .strict()
-    .refine((b) => (b.environmentId === undefined) !== (b.name === undefined), {
-    message: "Give exactly one of environmentId and name",
-    path: ["environmentId"],
-});
-export class DeviceAuthorizeBodyDto extends createZodDto(DeviceAuthorizeBody, "DeviceAuthorizeBody") {
+/** A device's name: trimmed, 1-64 characters (unique per person, case-insensitive). */
+export const DeviceName = z.string().trim().min(1).max(64);
+export const DeviceNameBody = z.object({ name: DeviceName }).strict();
+export const DeviceParams = z.object({ id: z.string().min(1).max(100) });
+export class DeviceCreateBodyDto extends createZodDto(DeviceNameBody, "DeviceCreateBody") {
 }
-export class DeviceTokenBodyDto extends createZodDto(DeviceTokenBody, "DeviceTokenBody") {
+export class DeviceRenameBodyDto extends createZodDto(DeviceNameBody, "DeviceRenameBody") {
 }
-export class DeviceUserCodeParamsDto extends createZodDto(DeviceUserCodeParams, "DeviceUserCodeParams") {
-}
-export class DeviceUserCodeBodyDto extends createZodDto(DeviceUserCodeBody, "DeviceUserCodeBody") {
-}
-export class DeviceConfirmBodyDto extends createZodDto(DeviceConfirmBody, "DeviceConfirmBody") {
+export class DeviceParamsDto extends createZodDto(DeviceParams, "DeviceParams") {
 }

package/dist/devices/label.d.ts

@@ -0,0 +1,11 @@
+import type { DeviceView } from "./devices.service.js";
+/**
+ * A device's name for people outside the web (the IM `/device` list, the `Platform` tool): its
+ * own name, else 「个人设备」 / "Personal" for the default, else for a default demoted by a provider
+ * switch the default's name plus the provider's display name (its plugin id when it has none),
+ * e.g. 「个人设备（Docker 沙箱）」 / "Personal (Docker sandbox)", with " 2", " 3", … after the
+ * first of the same provider. The web builds the same label from its own messages.
+ */
+export declare function deviceLabel(v: Pick<DeviceView, "name" | "demotedFrom">, locale: "zh" | "en"): string;
+/** The words the default device answers to in `/device <name>` besides its label. */
+export declare const DEFAULT_DEVICE_ALIASES: readonly string[];

package/dist/{environments → devices}/label.js

@@ -1,12 +1,12 @@
-const PERSONAL = { zh: "个人环境", en: "Personal" };
+const PERSONAL = { zh: "个人设备", en: "Personal" };
 /**
- * An environment's name for people outside the web (the IM `/env` list, the `Platform` tool): its
- * own name, else 「个人环境」 / "Personal" for the default, else for a default demoted by a provider
+ * A device's name for people outside the web (the IM `/device` list, the `Platform` tool): its
+ * own name, else 「个人设备」 / "Personal" for the default, else for a default demoted by a provider
  * switch the default's name plus the provider's display name (its plugin id when it has none),
- * e.g. 「个人环境（Docker 沙箱）」 / "Personal (Docker sandbox)", with " 2", " 3", … after the
+ * e.g. 「个人设备（Docker 沙箱）」 / "Personal (Docker sandbox)", with " 2", " 3", … after the
  * first of the same provider. The web builds the same label from its own messages.
  */
-export function environmentLabel(v, locale) {
+export function deviceLabel(v, locale) {
     if (v.name !== null)
         return v.name;
     const d = v.demotedFrom;
@@ -18,8 +18,8 @@ export function environmentLabel(v, locale) {
         ? `${PERSONAL.zh}（${provider}）${nth}`
         : `${PERSONAL.en} (${provider})${nth}`;
 }
-/** The words the default environment answers to in `/env <name>` besides its label. */
-export const DEFAULT_ENVIRONMENT_ALIASES = [
+/** The words the default device answers to in `/device <name>` besides its label. */
+export const DEFAULT_DEVICE_ALIASES = [
     PERSONAL.zh.toLowerCase(),
     PERSONAL.en.toLowerCase(),
 ];

package/dist/{environments → devices}/legacy-cleanup.job.d.ts

@@ -3,15 +3,15 @@ import { KernelDb } from "../infra/database/kernel-db.js";
 import { LockService } from "../infra/lock/lock.service.js";
 import type { KernelLogger } from "../log.js";
 import { SandboxProviders } from "../sandbox/providers.js";
-/** The job's name (`@LockedInterval`, run lock `cron:environments-legacy-cleanup`). */
-export declare const LEGACY_CLEANUP_JOB = "environments-legacy-cleanup";
+/** The job's name (`@LockedInterval`, run lock `cron:devices-legacy-cleanup`). */
+export declare const LEGACY_CLEANUP_JOB = "devices-legacy-cleanup";
 /** What one run did: rows destroyed and deleted, rows kept because their provider is not loaded. */
 export interface LegacyCleanupResult {
     destroyed: number;
     kept: number;
 }
 /**
- * The cleanup of the per-conversation sandboxes of before environments (spec
+ * The cleanup of the per-conversation sandboxes of before devices (spec
  * 2026-11-07-environments-design §4.2 item 9): for up to {@link BATCH} rows of the legacy
  * `sandboxes` table per tick, the row's provider destroys the instance and the file system named
  * `cap-<conversationId>` (`destroyByName`, `destroyFileSystemByName`; also the instance of the

package/dist/{environments → devices}/legacy-cleanup.job.js

@@ -14,8 +14,8 @@ import { LockService } from "../infra/lock/lock.service.js";
 import { LockedInterval } from "../infra/schedule/locked-interval.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { SandboxProviders } from "../sandbox/providers.js";
-/** The job's name (`@LockedInterval`, run lock `cron:environments-legacy-cleanup`). */
-export const LEGACY_CLEANUP_JOB = "environments-legacy-cleanup";
+/** The job's name (`@LockedInterval`, run lock `cron:devices-legacy-cleanup`). */
+export const LEGACY_CLEANUP_JOB = "devices-legacy-cleanup";
 /** Every 5 minutes, once per tick across replicas. */
 const PERIOD_MS = 5 * 60_000;
 /** Rows handled per tick. */
@@ -23,7 +23,7 @@ const BATCH = 50;
 /** The time limit of one provider call. */
 const CALL_TIMEOUT_MS = 120_000;
 /**
- * The cleanup of the per-conversation sandboxes of before environments (spec
+ * The cleanup of the per-conversation sandboxes of before devices (spec
  * 2026-11-07-environments-design §4.2 item 9): for up to {@link BATCH} rows of the legacy
  * `sandboxes` table per tick, the row's provider destroys the instance and the file system named
  * `cap-<conversationId>` (`destroyByName`, `destroyFileSystemByName`; also the instance of the

package/dist/errors.d.ts

@@ -159,6 +159,8 @@ export declare const ERROR_CODES: {
     readonly "catalog.not_deployed": 409;
     readonly "catalog.icon_not_found": 404;
     readonly "catalog.guide_not_found": 404;
+    /** The check is not in the setup guide rendered for that mode and audience (setup guides v2 §10.3). */
+    readonly "catalog.check_not_found": 404;
     readonly "marketplace.not_found": 404;
     readonly "marketplace.entry_not_found": 404;
     readonly "marketplace.fetch_failed": 502;
@@ -246,6 +248,8 @@ export declare const ERROR_CODES: {
     readonly "background_task.output_unavailable": 409;
     readonly "connector.not_found": 404;
     readonly "connector.slug_taken": 409;
+    /** The connector template's setup guide moved on since the person was shown it (guide-ack). */
+    readonly "connector.guide_changed": 409;
     readonly "connector.kind_unavailable": 409;
     readonly "connector.connect_failed": 502;
     readonly "connector.tool_not_found": 404;
@@ -283,40 +287,40 @@ export declare const ERROR_CODES: {
     readonly "attachment.too_many_pending": 429;
     readonly "sandbox.unavailable": 503;
     readonly "sandbox.busy": 409;
-    /** The environment is missing, deleted, or not the caller's (never 403, so ids cannot be probed). */
-    readonly "environment.not_found": 404;
-    /** The environment's file system is gone at the provider; reset its files to start empty. */
-    readonly "environment.files_lost": 409;
-    /** The caller may see the environment but not use it (project environments, later phases). */
-    readonly "environment.forbidden": 403;
-    /** The environment's provider is not the deployment's current one, or there is none. */
-    readonly "environment.unavailable": 503;
-    /** The person already has a live environment with this name (case-insensitive). */
-    readonly "environment.name_taken": 409;
-    /** The person already has `environments.maxPersonal` live personal environments. */
-    readonly "environment.limit_reached": 409;
+    /** The device is missing, deleted, or not the caller's (never 403, so ids cannot be probed). */
+    readonly "device.not_found": 404;
+    /** The cloud device's file system is gone at the provider; reset its files to start empty. */
+    readonly "device.files_lost": 409;
+    /** The caller may see the device but not use it (shared devices, later phases). */
+    readonly "device.forbidden": 403;
+    /** The device's provider is not the deployment's current one, or there is none. */
+    readonly "device.unavailable": 503;
+    /** The person already has a live device with this name (case-insensitive). */
+    readonly "device.name_taken": 409;
+    /** The person already has `devices.maxPersonal` live personal devices. */
+    readonly "device.limit_reached": 409;
     /**
-     * A connected environment's files are on its machine: they cannot be reset from the platform;
-     * run `capybara-device logout`, then `capybara-device login` into the environment, on the machine
+     * A local device's files are on its machine: they cannot be reset from the platform; run
+     * `capybara-device logout`, then `capybara-device login` into the device, on the machine
      * (ruling R24).
      */
-    readonly "environment.files_on_device": 409;
-    /** The environment's connected machine is not connected now (no replica holds its lease). */
-    readonly "environment.offline": 503;
-    /** The connected machine runs a device program too old for this kernel; update the program. */
-    readonly "environment.program_outdated": 426;
+    readonly "device.files_on_device": 409;
+    /** The local device's machine is not connected now (no replica holds its lease). */
+    readonly "device.offline": 503;
+    /** The local device's machine runs a `capybara-device` too old for this kernel; update it. */
+    readonly "device.program_outdated": 426;
     /** Device sign-in (RFC 8628 style): the person has not approved the code yet; keep polling. */
-    readonly "device.authorization_pending": 400;
+    readonly "device_sign_in.authorization_pending": 400;
     /** Device sign-in: the program polls faster than the interval; add 5 seconds and keep polling. */
-    readonly "device.slow_down": 400;
+    readonly "device_sign_in.slow_down": 400;
     /** Device sign-in: the code expired before it was approved; start over. */
-    readonly "device.expired": 400;
+    readonly "device_sign_in.expired": 400;
     /** Device sign-in: the person denied the code. */
-    readonly "device.denied": 400;
+    readonly "device_sign_in.denied": 400;
     /** Device sign-in: no pending code matches the one given. */
-    readonly "device.code_invalid": 404;
+    readonly "device_sign_in.code_invalid": 404;
     /** Device sign-in: the confirmation could not hand the credential to the program; start over. */
-    readonly "device.unavailable": 503;
+    readonly "device_sign_in.unavailable": 503;
     /** The machine credential is unknown or revoked. */
     readonly "device.credential_invalid": 401;
     readonly "skill.not_found": 404;

package/dist/errors.js

@@ -159,6 +159,8 @@ export const ERROR_CODES = {
     "catalog.not_deployed": 409,
     "catalog.icon_not_found": 404,
     "catalog.guide_not_found": 404,
+    /** The check is not in the setup guide rendered for that mode and audience (setup guides v2 §10.3). */
+    "catalog.check_not_found": 404,
     "marketplace.not_found": 404,
     "marketplace.entry_not_found": 404,
     "marketplace.fetch_failed": 502,
@@ -246,6 +248,8 @@ export const ERROR_CODES = {
     "background_task.output_unavailable": 409,
     "connector.not_found": 404,
     "connector.slug_taken": 409,
+    /** The connector template's setup guide moved on since the person was shown it (guide-ack). */
+    "connector.guide_changed": 409,
     "connector.kind_unavailable": 409,
     "connector.connect_failed": 502,
     "connector.tool_not_found": 404,
@@ -283,40 +287,40 @@ export const ERROR_CODES = {
     "attachment.too_many_pending": 429,
     "sandbox.unavailable": 503,
     "sandbox.busy": 409,
-    /** The environment is missing, deleted, or not the caller's (never 403, so ids cannot be probed). */
-    "environment.not_found": 404,
-    /** The environment's file system is gone at the provider; reset its files to start empty. */
-    "environment.files_lost": 409,
-    /** The caller may see the environment but not use it (project environments, later phases). */
-    "environment.forbidden": 403,
-    /** The environment's provider is not the deployment's current one, or there is none. */
-    "environment.unavailable": 503,
-    /** The person already has a live environment with this name (case-insensitive). */
-    "environment.name_taken": 409,
-    /** The person already has `environments.maxPersonal` live personal environments. */
-    "environment.limit_reached": 409,
+    /** The device is missing, deleted, or not the caller's (never 403, so ids cannot be probed). */
+    "device.not_found": 404,
+    /** The cloud device's file system is gone at the provider; reset its files to start empty. */
+    "device.files_lost": 409,
+    /** The caller may see the device but not use it (shared devices, later phases). */
+    "device.forbidden": 403,
+    /** The device's provider is not the deployment's current one, or there is none. */
+    "device.unavailable": 503,
+    /** The person already has a live device with this name (case-insensitive). */
+    "device.name_taken": 409,
+    /** The person already has `devices.maxPersonal` live personal devices. */
+    "device.limit_reached": 409,
     /**
-     * A connected environment's files are on its machine: they cannot be reset from the platform;
-     * run `capybara-device logout`, then `capybara-device login` into the environment, on the machine
+     * A local device's files are on its machine: they cannot be reset from the platform; run
+     * `capybara-device logout`, then `capybara-device login` into the device, on the machine
      * (ruling R24).
      */
-    "environment.files_on_device": 409,
-    /** The environment's connected machine is not connected now (no replica holds its lease). */
-    "environment.offline": 503,
-    /** The connected machine runs a device program too old for this kernel; update the program. */
-    "environment.program_outdated": 426,
+    "device.files_on_device": 409,
+    /** The local device's machine is not connected now (no replica holds its lease). */
+    "device.offline": 503,
+    /** The local device's machine runs a `capybara-device` too old for this kernel; update it. */
+    "device.program_outdated": 426,
     /** Device sign-in (RFC 8628 style): the person has not approved the code yet; keep polling. */
-    "device.authorization_pending": 400,
+    "device_sign_in.authorization_pending": 400,
     /** Device sign-in: the program polls faster than the interval; add 5 seconds and keep polling. */
-    "device.slow_down": 400,
+    "device_sign_in.slow_down": 400,
     /** Device sign-in: the code expired before it was approved; start over. */
-    "device.expired": 400,
+    "device_sign_in.expired": 400,
     /** Device sign-in: the person denied the code. */
-    "device.denied": 400,
+    "device_sign_in.denied": 400,
     /** Device sign-in: no pending code matches the one given. */
-    "device.code_invalid": 404,
+    "device_sign_in.code_invalid": 404,
     /** Device sign-in: the confirmation could not hand the credential to the program; start over. */
-    "device.unavailable": 503,
+    "device_sign_in.unavailable": 503,
     /** The machine credential is unknown or revoked. */
     "device.credential_invalid": 401,
     "skill.not_found": 404,

package/dist/evals/recorded-tools.d.ts

@@ -25,13 +25,13 @@ export interface RecordedCall {
     /** The recorded call used release-candidate names; `toolKey` and `inputKey` are already the current ones. */
     legacy?: true;
     /**
-     * The roots of the latest `environment_paths` event the original run had logged by this call's
+     * The roots of the latest `device_paths` event the original run had logged by this call's
      * step (environments spec §13.1, ruling R22): set on every recorded call from the step where an
      * event was logged onward. A replay that matches the call writes the event when the eval
      * conversation's latest one differs, so a candidate whose first sandbox call lands in another
      * step still gets the line, once.
      */
-    environmentPaths?: SandboxRoots;
+    devicePaths?: SandboxRoots;
 }
 /**
  * The connectors and extensions an rc `<x>__<tool>` key can name, from positive evidence in the

package/dist/evals/recorded-tools.js

@@ -1,4 +1,4 @@
-import { environmentPathsChange } from "../runtime/context/environment-paths.js";
+import { devicePathsChange } from "../runtime/context/device-paths.js";
 import { assistantIdemKey } from "../runtime/model-call.js";
 import { MATCH_IGNORED_FIELDS } from "../tools/builtin-names.js";
 import { isLegacyPrefixedKey, legacyToolInput, legacyToolKey, } from "../tools/legacy-keys.js";
@@ -138,7 +138,7 @@ export function recordedCalls(s) {
                 started.set(p.callId, p.specHash);
         }
     }
-    // an environment_paths event belongs to the step of the assistant message before it, and holds
+    // a device_paths event belongs to the step of the assistant message before it, and holds
     // for that step's calls and every later step's (until the next one)
     const pathsOf = new Map();
     const assistants = own.filter((e) => e.type === "assistant_message").map((e) => e.seq);
@@ -148,7 +148,7 @@ export function recordedCalls(s) {
         const end = assistants[i + 1] ?? Number.POSITIVE_INFINITY;
         for (; next < own.length && own[next].seq < end; next++) {
             const e = own[next];
-            if (e.type === "environment_paths" && e.seq > a) {
+            if (e.type === "device_paths" && e.seq > a) {
                 current = e.payload.roots;
             }
         }
@@ -179,7 +179,7 @@ export function recordedCalls(s) {
                 ...(r.loadedTools !== undefined && { loadedTools: r.loadedTools }),
                 ...(r.contentTypes !== undefined && { contentTypes: r.contentTypes }),
                 specHash: started.get(call.id) ?? "",
-                ...(paths !== undefined && { environmentPaths: paths }),
+                ...(paths !== undefined && { devicePaths: paths }),
             });
         }
     }
@@ -235,10 +235,10 @@ export class RecordedToolPipeline {
                 this.misses++;
             // the original run had told the model the instance's directories by this call: so does the
             // replay, when the eval conversation's latest record differs (as the sandbox tools write it)
-            const paths = rec?.environmentPaths;
+            const paths = rec?.devicePaths;
             const change = paths === undefined
                 ? null
-                : environmentPathsChange(await eventLog.latestOfType(ctx.conversationId, "environment_paths"), paths, ctx.runId);
+                : devicePathsChange(await eventLog.latestOfType(ctx.conversationId, "device_paths"), paths, ctx.runId);
             await eventLog.append(ctx.conversationId, [
                 ...(change ? [change] : []),
                 {

package/dist/extensions/admin-ops.js

@@ -519,6 +519,7 @@ function fallbackView(name, known, err) {
         enabledOrgs: 0,
         builtin: false,
         installSource: null,
+        uiDropped: [],
         error: `the change was saved, but its current status cannot be read: ${err instanceof Error ? err.message : String(err)}`,
     };
 }

package/dist/extensions/admin-view.js

@@ -440,6 +440,7 @@ let ExtensionAdmin = class ExtensionAdmin {
                     required: install?.required === true,
                     ...scopeInfo,
                     installSource: install?.source ?? null,
+                    uiDropped: this.host.uiDropped(s.name),
                     error: s.broken,
                 };
             }
@@ -493,6 +494,7 @@ let ExtensionAdmin = class ExtensionAdmin {
                 required: install?.required === true,
                 ...scopeInfo,
                 installSource: install?.source ?? null,
+                uiDropped: this.host.uiDropped(s.name),
             };
         });
     }

package/dist/extensions/effective-config.d.ts

@@ -92,6 +92,12 @@ export declare class EffectiveConfigs {
     /** Secret values of a copy read here are masked in the logs. */
     log: KernelLogger);
     private get db();
+    /**
+     * The config of `plugin` for work done for the platform (a `platform.page` view, UI slots spec
+     * §7): the running instance's deployment config, no org copy applies; `notRunning` when the
+     * extension is not running on this replica.
+     */
+    platform(plugin: string): EffectiveConfig;
     /**
      * The effective config of `plugin` for `orgId`. Following: the running platform config, `ok:
      * false` when it leaves a required overridable field empty (the host loaded it with those

package/dist/extensions/effective-config.js

@@ -37,6 +37,11 @@ const OVERRIDE_KEY_PREFIX = "plugin-override:";
  * distinct from the org-only `plugin-config:<plugin>:<path>` (spec A §5.8).
  */
 export const overrideSecretKey = (plugin, path) => `${OVERRIDE_KEY_PREFIX}${plugin}:${path}`;
+const notRunning = () => ({
+    ok: false,
+    notRunning: true,
+    issues: [{ path: "", segments: [], message: "the extension is not running" }],
+});
 /** The secret leaf paths of a deployment schema. */
 export function secretLeafPaths(schema) {
     return configFields(schema)
@@ -171,6 +176,17 @@ let EffectiveConfigs = class EffectiveConfigs {
     get db() {
         return this.kdb.db;
     }
+    /**
+     * The config of `plugin` for work done for the platform (a `platform.page` view, UI slots spec
+     * §7): the running instance's deployment config, no org copy applies; `notRunning` when the
+     * extension is not running on this replica.
+     */
+    platform(plugin) {
+        const inst = this.registry.current(plugin);
+        if (!inst)
+            return notRunning();
+        return { ok: true, config: inst.config, source: "platform" };
+    }
     /**
      * The effective config of `plugin` for `orgId`. Following: the running platform config, `ok:
      * false` when it leaves a required overridable field empty (the host loaded it with those
@@ -180,13 +196,8 @@ let EffectiveConfigs = class EffectiveConfigs {
      */
     async get(orgId, plugin) {
         const inst = this.registry.current(plugin);
-        if (!inst) {
-            return {
-                ok: false,
-                notRunning: true,
-                issues: [{ path: "", segments: [], message: "the extension is not running" }],
-            };
-        }
+        if (!inst)
+            return notRunning();
         const schema = inst.manifest.config?.deployment;
         if (!schema)
             return { ok: true, config: inst.config, source: "platform" };

package/dist/extensions/guide-places.d.ts

@@ -0,0 +1,66 @@
+import { type PluginSetupGuide, type SetupGuideAudience, type SetupGuidePlace } from "@capybara-hq/plugin-sdk";
+import type { KernelConfig } from "../config/schema.js";
+import type { KernelDb } from "../infra/database/kernel-db.js";
+import type { OrgAction } from "../orgs/roles.js";
+/** Why a known variable has no value: what the web and the `Platform` tool tell the reader. */
+export type UnresolvedReason = 
+/** The target is not saved yet (the webhook URL, a connection name nobody typed). */
+"not_saved"
+/** `http.publicUrl` is not set (the URLs built from it). */
+ | "public_url"
+/** `channels.webhookBaseUrl` is not set or unusable. */
+ | "webhook_base"
+/** No connector is made from the template yet. */
+ | "no_connector"
+/** Rendered for the platform (the super admin's preview), not for an org. */
+ | "no_org";
+/** The org action each audience of a place needs besides `catalog.read` (spec §9.1). */
+export declare const PLACE_ACTIONS: Readonly<Record<SetupGuidePlace, Readonly<Partial<Record<SetupGuideAudience, OrgAction>>>>>;
+/** The object a guide is rendered for. */
+export interface GuideTarget {
+    kind: "channel-connection" | "connector";
+    id: string;
+}
+/** The target parameters of the guide route, per place. */
+export interface GuideTargetQuery {
+    connectionId?: string | undefined;
+    name?: string | undefined;
+    connectorId?: string | undefined;
+}
+/** What a place resolves for one rendering (the mode is the caller's: it picks it from these). */
+export interface PlaceResolution {
+    /** Every variable of the place except `mode`; null = known without a value. */
+    values: Record<string, string | null>;
+    /** The reason of each variable that is null in `values`. */
+    reasons: Record<string, UnresolvedReason>;
+    target: GuideTarget | null;
+    /** The target's stored mode (a channel connection's `inbound_mode`), null without one. */
+    storedMode: string | null;
+}
+/** Where the values come from. */
+export interface PlaceContext {
+    db: KernelDb;
+    config: Pick<KernelConfig, "http" | "channels"> & {
+        tools: Pick<KernelConfig["tools"], "oauthAllowInsecureLoopback">;
+    };
+    item: {
+        id: string;
+        name: string;
+        version: string;
+    };
+    guide: PluginSetupGuide;
+    locale: "en" | "zh";
+    /** The org rendered for; null for the platform preview (no org, no target). */
+    org: {
+        orgId: string;
+        name: string;
+    } | null;
+    query: GuideTargetQuery;
+}
+/**
+ * The variable values of a place for one rendering (spec §6.3): the common ones, then the place's
+ * own from its target. Throws 400 `validation_failed` for another place's target parameter and 404
+ * (`channel.not_found`, `connector.not_found`) for a target that is not a live object of the org on
+ * the guide's plugin.
+ */
+export declare function resolvePlace(ctx: PlaceContext): Promise<PlaceResolution>;