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

package/dist/ui/views.js

@@ -7,21 +7,27 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { normalizePlace, validateUiView, } from "@capybara-hq/plugin-sdk";
+import { UI_ARRANGEABLE_SLOTS, validateUiView, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
+import { isAgentVisibleIn } from "../agents/agent-lookup.js";
 import { ConversationsService } from "../conversations/conversations.service.js";
 import { ApiError } from "../errors.js";
 import { EffectiveConfigs, NEEDS_CONFIG_REASON } from "../extensions/effective-config.js";
 import { ExtensionHost } from "../extensions/host.js";
 import { PreviewerRegistry } from "../files/previewers.js";
+import { readUiArrangement } from "../identity/settings.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { readOrgSettings } from "../orgs/settings.service.js";
+import { arrange, arrangeBySlot, effectiveEntry, ORG_ARRANGEABLE, orderItems, } from "./arrangement.js";
 import { callExtension } from "./call-extension.js";
-import { canUsePlace, isConversationPlace, UUID_RE } from "./registry.js";
+import { canUseSlot, UUID_RE } from "./registry.js";
 export { callExtension } from "./call-extension.js";
 /** 插件 render / action 的时限（spec §4.2：慢的插件只让那个标签失败）。 */
 export const UI_CALL_TIMEOUT_MS = 5_000;
+/** The log field naming where a target is: its org, or the platform scope. */
+const whereOf = (t) => t.scope === "platform" ? { scope: "platform" } : { orgId: t.orgId };
 /**
  * The card a `tool_result` of the conversation recorded for `callId`, or null (the inline-card
  * attestation of {@link UiViewsDeps.recordedCard}). Scans one conversation's tool results.
@@ -66,6 +72,37 @@ export function dropForeignOpens(view, panels) {
     const { open, ...rest } = view;
     return { ...rest, ...(open !== undefined && ok(open) && { open }), blocks };
 }
+/**
+ * Lists contributions for a listing route: no alias, a view's render registered; base order
+ * (spec §5): extension name, then manifest order (stable).
+ */
+function listed(entries) {
+    return entries
+        .filter((c) => c.contribution.aliasOf === undefined && (c.contribution.kind === "embed" || c.render))
+        .map((c, i) => ({ c, i }))
+        .sort((x, y) => (x.c.plugin === y.c.plugin ? x.i - y.i : x.c.plugin < y.c.plugin ? -1 : 1))
+        .map(({ c: { plugin, contribution: c, slot: s, after } }) => ({
+        plugin,
+        id: c.id,
+        title: c.title,
+        slot: s.id,
+        ...(after !== undefined && { after }),
+        kind: c.kind,
+        ...(c.kind === "embed" && c.path !== undefined && { path: c.path }),
+        icon: c.icon ?? "puzzle",
+    }));
+}
+/** The items in effective order, each marked hidden or not (hidden ones stay in place). */
+function withHidden(items, entry) {
+    const hidden = new Set(entry.hidden);
+    return orderItems(items, entry).map((i) => ({ ...i, hidden: hidden.has(`${i.plugin}/${i.id}`) }));
+}
+/** A platform route's contribution: found, and in `platform.page`; else 404. */
+function platformEntry(entry) {
+    if (entry === undefined || entry.slot.id !== "platform.page")
+        throw notFound();
+    return entry;
+}
 const TOAST_MAX = 500;
 const MAX_LOGGED_PROBLEMS = 10;
 const notFound = () => new ApiError("ui.not_found", "UI contribution not found");
@@ -91,9 +128,11 @@ function actionResultProblems(r) {
 /**
  * 插件视图（第一档：渲染 schema）：列出贡献、调用插件 `render` / `action`。
  * - 只认在该组织已启用、且已在本副本加载的插件（启用状态每次查库）；
- * - 对话视图要求调用者能访问这个对话（与 SSE 流一致），访问不了与不存在一样返回 404 `ui.not_found`；
- * - 组织页面（`place: "page"`，视图与嵌入）只给 member 以上：guest 列表里看不到、取视图 / 动作 / 令牌一律 404；
- * - 组织页面视图不接受 `conversationId`（带了 400，与对话视图缺它一致）；
+ * - every request goes through one gate (`resolve`): the slot's `minRole` (never `platform.page`),
+ *   then its scope rule (conversation: readable, like the SSE stream; agent: readable and in this
+ *   org; org: the role alone); refused is 404 `ui.not_found`, the same as not existing;
+ * - a view takes only the context id of its scope (`conversationId` / `agentId`): a missing one or
+ *   one of another scope is 400 `validation_failed`;
  * - 调用带 5 秒时限与中止信号：render 抛错 502 `ui.render_failed`、action 抛错 502 `ui.action_failed`、
  *   超时 504 `ui.timeout`、返回非法视图 502
  *   `ui.invalid_view`，都记告警日志、不写对话日志（这些不是模型可见的内容）。
@@ -108,57 +147,125 @@ let UiViews = class UiViews {
             // org config rows plus the required bootstrap plugins
             enabledPlugins: (orgId) => host.enabledPlugins(orgId),
             canAccessConversation: (orgId, id, accountId) => conversations.isAccessible(orgId, id, accountId),
+            canReadAgent: (orgId, agentId, accountId) => isAgentVisibleIn(db.db, orgId, agentId, accountId),
             checkWritable: async (orgId, id, accountId) => {
                 await conversations.writable(orgId, id, accountId);
             },
             previewEmbedAllowed: (t) => previewers.embedAllowed(t),
             recordedCard: (conversationId, callId) => recordedCard(db.db, conversationId, callId),
+            orgArrangement: async (orgId) => (await readOrgSettings(db.db, orgId)).uiArrangement,
+            platformArrangement: () => readUiArrangement(db.db),
             log,
         };
     }
-    /** 该组织、该角色可见的界面贡献：插件已启用且已加载；kind view 的要求插件注册了 render；组织页面要 member 以上。 */
-    async contributions(orgId, role) {
+    /**
+     * The contributions the role may use in the org, of one slot or of every org-reachable slot:
+     * the extension enabled and loaded, a view's render registered, the slot's `minRole`
+     * ({@link canUseSlot}, so never `platform.page`); no alias, no `file.preview` contribution (the
+     * file previewers list those). Base order (spec §5): extension name, then manifest order.
+     */
+    async contributions(orgId, role, slot) {
+        const items = await this.orgBase(orgId, role, slot);
+        if (items.length === 0)
+            return items;
+        const [org, platform] = await Promise.all([
+            this.d.orgArrangement(orgId),
+            this.d.platformArrangement(),
+        ]);
+        return arrangeBySlot(items, (s) => effectiveEntry(org, platform, s).entry);
+    }
+    /** {@link contributions} before the arrangement: what the role may use, in base order. */
+    async orgBase(orgId, role, slot) {
         const all = this.d.host.uiContributions();
         if (all.length === 0)
             return [];
         const enabled = await this.d.enabledPlugins(orgId);
-        return all
-            .filter((c) => enabled.has(c.plugin) &&
-            c.contribution.aliasOf === undefined &&
-            c.contribution.place !== "file-preview" &&
-            (c.contribution.kind === "embed" || c.render) &&
-            canUsePlace(c.contribution.place, role))
-            .map(({ plugin, contribution: c }) => ({
-            plugin,
-            id: c.id,
-            title: c.title,
-            place: normalizePlace(c.place),
-            ...(c.place === "conversation" && { legacyPlace: "conversation" }),
-            kind: c.kind,
-            ...(c.kind === "embed" && c.path !== undefined && { path: c.path }),
-            icon: c.icon ?? "puzzle",
-        }));
+        return listed(all.filter((c) => enabled.has(c.plugin) &&
+            c.slot.id !== "file.preview" &&
+            (slot === undefined || c.slot.id === slot) &&
+            canUseSlot(c.slot, role)));
+    }
+    /**
+     * The arrangement page of an org: every org-arrangeable slot with the contributions the role may
+     * use, in effective order with the hidden ones in place, and where the entry comes from.
+     */
+    async arrangementView(orgId, role) {
+        // the page is for people who arrange or at least see the org's UI, not for a guest
+        if (role === "guest")
+            throw notFound();
+        const [base, org, platform] = await Promise.all([
+            this.orgBase(orgId, role, undefined),
+            this.d.orgArrangement(orgId),
+            this.d.platformArrangement(),
+        ]);
+        return ORG_ARRANGEABLE.map((slot) => {
+            const { entry, source } = effectiveEntry(org, platform, slot);
+            return {
+                slot,
+                source,
+                items: withHidden(base.filter((i) => i.slot === slot), entry),
+            };
+        });
+    }
+    /**
+     * The platform's arrangement page: every arrangeable slot with the contributions of every running
+     * extension (whatever its org enablement), ordered by the platform entry, hidden ones in place.
+     */
+    async platformArrangementView() {
+        const [base, platform] = await Promise.all([
+            listed(this.d.host.uiContributions().filter((c) => c.slot.id !== "file.preview")),
+            this.d.platformArrangement(),
+        ]);
+        return UI_ARRANGEABLE_SLOTS.map((slot) => {
+            const { entry, source } = effectiveEntry(undefined, platform, slot);
+            return {
+                slot,
+                source,
+                items: withHidden(base.filter((i) => i.slot === slot), entry),
+            };
+        });
+    }
+    /**
+     * The `platform.page` contributions of the running extensions, for the admin console (super
+     * admins; no org enablement applies): no alias, a view's render registered. Base order like
+     * {@link contributions}.
+     */
+    async platformContributions() {
+        const items = listed(this.d.host.uiContributions().filter((c) => c.slot.id === "platform.page"));
+        const { entry } = effectiveEntry(undefined, await this.d.platformArrangement(), "platform.page");
+        return arrange(items, entry);
     }
     /**
      * 嵌入应用：核对贡献是 embed、插件在该组织启用；对话嵌入要求调用者能访问该对话（否则 404，与视图一致），
      * 组织页面不收 `conversationId`。返回签发令牌所需的目标（令牌由调用方签）。
      */
     async embed(t) {
-        const { fileId, ...target } = t;
-        const { entry, args } = await this.resolve({ ...target, locale: "en" }, "embed");
+        let fileId;
+        let target;
+        if (t.scope === "platform")
+            target = { ...t, locale: "en" };
+        else {
+            const { fileId: f, ...org } = t;
+            fileId = f;
+            target = { ...org, locale: "en" };
+        }
+        const { entry, args } = await this.resolve(target, "embed");
         const path = entry.contribution.path;
         if (path === undefined)
             throw notFound();
-        const preview = entry.contribution.place === "file-preview";
+        const preview = entry.slot.id === "file.preview";
         if (preview !== (fileId !== undefined)) {
             throw new ApiError("validation_failed", preview
                 ? "fileId is required for a file-preview embed"
                 : "fileId is only allowed for a file-preview embed");
         }
         if (fileId !== undefined) {
+            // a file-preview embed is an org's (a platform target never carries a fileId)
+            if (args.orgId === undefined)
+                throw notFound();
             const allowed = this.d.previewEmbedAllowed !== undefined &&
                 (await this.d.previewEmbedAllowed({
-                    orgId: t.orgId,
+                    orgId: args.orgId,
                     accountId: t.accountId,
                     conversationId: args.conversationId,
                     fileId,
@@ -173,6 +280,7 @@ let UiViews = class UiViews {
             contribution: t.id,
             path,
             ...(args.conversationId !== undefined && { conversationId: args.conversationId }),
+            ...(args.agentId !== undefined && { agentId: args.agentId }),
             ...(fileId !== undefined && { fileId }),
         };
     }
@@ -205,10 +313,20 @@ let UiViews = class UiViews {
     panels(plugin) {
         return new Set(this.d.host
             .uiContributions()
-            .filter((c) => c.plugin === plugin && normalizePlace(c.contribution.place) === "panel")
+            .filter((c) => c.plugin === plugin && c.slot.id === "conversation.panel")
             .map((c) => c.contribution.id));
     }
-    /** 找贡献、核对组织启用与对话访问；返回传给插件的参数（不含 signal）。 */
+    /**
+     * The single access gate of the org UI routes (UI slots spec §7): finds the contribution (a
+     * retired alias answers with the one it names), then checks, in order, that its slot is reachable
+     * from an org (not `platform`), the role meets the slot's `minRole`, the extension is enabled in
+     * the org, its effective config is valid, and the slot's scope rule (conversation: readable;
+     * agent: readable and in this org; org: the role alone; file: a conversation the caller reads,
+     * the previewer's grant is checked by `embed`). A platform target (the admin routes) takes the
+     * platform gate instead ({@link platformArgs}): only a `platform.page` contribution. Returns the
+     * args passed to the extension (no signal). Anything refused for a contribution that exists is
+     * 404 `ui.not_found`.
+     */
     async resolve(t, need) {
         const loaded = this.d.host.uiContributions();
         const named = loaded.find((c) => c.plugin === t.plugin && c.contribution.id === t.id);
@@ -221,8 +339,13 @@ let UiViews = class UiViews {
             (need === "embed"
                 ? c.contribution.kind === "embed"
                 : c.contribution.kind === "view" && c[need] !== undefined));
-        if (!entry || !canUsePlace(entry.contribution.place, t.role))
+        if (t.scope === "platform") {
+            const found = platformEntry(entry);
+            return { entry: found, args: this.platformArgs(t, found) };
+        }
+        if (!entry || entry.slot.scope === "platform" || !canUseSlot(entry.slot, t.role)) {
             throw notFound();
+        }
         if (!(await this.d.enabledPlugins(t.orgId)).has(t.plugin))
             throw notFound();
         // spec A §6: the extension is not called for an org whose effective config is not valid
@@ -230,25 +353,46 @@ let UiViews = class UiViews {
         if (!effective.ok) {
             throw new ApiError("extension.needs_config", `Extension ${t.plugin} ${NEEDS_CONFIG_REASON}`);
         }
+        const scope = entry.slot.scope;
         const base = {
             orgId: t.orgId,
             accountId: t.accountId,
             role: t.role,
+            slot: entry.slot.id,
+            scope,
             locale: t.locale,
             config: effective.config,
         };
-        if (!isConversationPlace(entry.contribution.place)) {
-            if (t.item !== undefined || t.card !== undefined) {
-                throw new ApiError("validation_failed", "item and callId are for conversation views");
+        const what = need === "embed" ? "embed" : "view";
+        const conversational = scope === "conversation" || scope === "file";
+        if (!conversational && (t.item !== undefined || t.card !== undefined)) {
+            throw new ApiError("validation_failed", "item and callId are for conversation views");
+        }
+        if (scope !== "agent" && t.agentId !== undefined) {
+            throw new ApiError("validation_failed", `agentId is only allowed for an agent ${what}`);
+        }
+        if (scope === "agent") {
+            if (t.conversationId !== undefined) {
+                throw new ApiError("validation_failed", `conversationId is not allowed for an agent ${what}`);
+            }
+            const agentId = t.agentId;
+            if (agentId === undefined) {
+                throw new ApiError("validation_failed", `agentId is required for an agent ${what}`);
+            }
+            if (!UUID_RE.test(agentId) || !(await this.d.canReadAgent(t.orgId, agentId, t.accountId))) {
+                throw notFound();
             }
+            return { entry, args: { ...base, agentId } };
+        }
+        if (!conversational) {
             if (t.conversationId !== undefined) {
-                throw new ApiError("validation_failed", `conversationId is not allowed for an organization page ${need === "embed" ? "embed" : "view"}`);
+                throw new ApiError("validation_failed", `conversationId is not allowed for an organization page ${what}`);
             }
             return { entry, args: base };
         }
         const conversationId = t.conversationId;
         if (conversationId === undefined) {
-            throw new ApiError("validation_failed", `conversationId is required for a conversation ${need === "embed" ? "embed" : "view"}`);
+            throw new ApiError("validation_failed", `conversationId is required for a conversation ${what}`);
         }
         if (!UUID_RE.test(conversationId) ||
             !(await this.d.canAccessConversation(t.orgId, conversationId, t.accountId))) {
@@ -260,7 +404,7 @@ let UiViews = class UiViews {
         if (t.card !== undefined) {
             // args.card is attested: an inline view, and a tool_result of this conversation recorded this
             // very card (plugin, the requested id or its alias target, key); else it is not found
-            const recorded = normalizePlace(entry.contribution.place) === "inline" && this.d.recordedCard !== undefined
+            const recorded = entry.slot.id === "conversation.tool-result.card" && this.d.recordedCard !== undefined
                 ? await this.d.recordedCard(conversationId, t.card.callId)
                 : null;
             if (recorded === null ||
@@ -280,13 +424,32 @@ let UiViews = class UiViews {
             },
         };
     }
+    /**
+     * The platform gate (UI slots spec §7): the contribution is a `platform.page` of a running
+     * extension (no org enablement applies), given the platform's deployment config. The caller is a
+     * super admin (`@SuperAdmin` on the admin routes); anything else is 404 `ui.not_found`.
+     */
+    platformArgs(t, entry) {
+        const effective = this.d.effective.platform(t.plugin);
+        // `platform()` fails only when the extension is not running here: not found
+        if (!effective.ok)
+            throw notFound();
+        return {
+            scope: "platform",
+            accountId: t.accountId,
+            role: "superAdmin",
+            slot: entry.slot.id,
+            locale: t.locale,
+            config: effective.config,
+        };
+    }
     /** 带时限调用插件：超时中止信号并 504；抛错 502（render / action 各一个码，不回显插件的异常信息）。 */
     call(t, what, fn) {
         return callExtension({
             log: this.d.log,
             plugin: t.plugin,
             what,
-            fields: { plugin: t.plugin, contribution: t.id, orgId: t.orgId },
+            fields: { plugin: t.plugin, contribution: t.id, ...whereOf(t) },
             timeoutMs: UI_CALL_TIMEOUT_MS,
             failCode: what === "render" ? "ui.render_failed" : "ui.action_failed",
             failMessage: `Plugin ${t.plugin} failed to ${what} ${t.id}`,
@@ -300,7 +463,7 @@ let UiViews = class UiViews {
         this.d.log.warn(`plugin ui ${what} returned an invalid view`, {
             plugin: t.plugin,
             contribution: t.id,
-            orgId: t.orgId,
+            ...whereOf(t),
             problems: problems.slice(0, MAX_LOGGED_PROBLEMS),
         });
         throw new ApiError("ui.invalid_view", `Plugin ${t.plugin} returned an invalid view`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/kernel",
-  "version": "0.1.0-rc.12",
+  "version": "0.1.0-rc.14",
   "description": "Capybara kernel: config, database, plugin host and HTTP API of the Capybara agent platform",
   "license": "Apache-2.0",
   "repository": {
@@ -65,7 +65,7 @@
     "yaml": "^2.9.1",
     "yauzl": "3.4.0",
     "zod": "^4.6.7",
-    "@capybara-hq/plugin-sdk": "^0.1.0-rc.8"
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.10"
   },
   "devDependencies": {
     "@langchain/langgraph-checkpoint-validation": "^1.2.0",
@@ -74,7 +74,7 @@
     "@types/ws": "^8.18.2",
     "@types/yauzl": "3.4.0",
     "ws": "^8.22.0",
-    "@capybara-hq/testing": "0.1.0-rc.11"
+    "@capybara-hq/testing": "0.1.0-rc.13"
   },
   "scripts": {
     "build": "tsc -b"

package/src/migrations/0105_devices_rename.sql

@@ -0,0 +1,136 @@
+-- One name: devices (spec 2026-11-07-environments-design §15.2). Every environment table, column,
+-- index and constraint takes the device name; a connected machine's source 'device' becomes
+-- 'local', the kernel-internal provider '@device' becomes '@local', and the log event
+-- 'environment_paths' becomes 'device_paths' (in the log and in eval case snapshots). The kernel
+-- is renamed in the same release; before 0.1.0, so no compatibility layer and no rolling deploy
+-- across this migration. Every statement is guarded, so a rerun changes nothing.
+
+-- capybara:allow-destructive table rename; the kernel is renamed in the same release (not released, no compatibility layer)
+ALTER TABLE IF EXISTS environments RENAME TO devices;
+-- capybara:allow-destructive table rename; the kernel is renamed in the same release (not released, no compatibility layer)
+ALTER TABLE IF EXISTS environment_instances RENAME TO device_instances;
+-- capybara:allow-destructive table rename; the kernel is renamed in the same release (not released, no compatibility layer)
+ALTER TABLE IF EXISTS environment_defaults RENAME TO device_defaults;
+-- capybara:allow-destructive table rename; the kernel is renamed in the same release (not released, no compatibility layer)
+ALTER TABLE IF EXISTS environment_machines RENAME TO device_machines;
+
+-- RENAME COLUMN has no IF EXISTS: checked against information_schema first.
+-- capybara:allow-destructive column rename environment_id -> device_id; the kernel is renamed in the same release (not released)
+DO $$
+DECLARE
+  t text;
+BEGIN
+  FOREACH t IN ARRAY ARRAY['device_instances', 'device_defaults', 'device_machines',
+                           'conversations', 'background_tasks'] LOOP
+    IF EXISTS (
+      SELECT 1 FROM information_schema.columns
+      WHERE table_schema = 'capybara' AND table_name = t AND column_name = 'environment_id'
+    ) THEN
+      EXECUTE format('ALTER TABLE capybara.%I RENAME COLUMN environment_id TO device_id', t);
+    END IF;
+  END LOOP;
+END
+$$;
+
+-- Indexes, including those behind the primary keys and unique constraints (renaming such an
+-- index renames its constraint too).
+-- capybara:allow-destructive index rename; names follow the table rename (not released)
+ALTER INDEX IF EXISTS environments_pkey RENAME TO devices_pkey;
+-- capybara:allow-destructive index rename; names follow the table rename (not released)
+ALTER INDEX IF EXISTS environments_default_uq RENAME TO devices_default_uq;
+-- capybara:allow-destructive index rename; names follow the table rename (not released)
+ALTER INDEX IF EXISTS environments_name_uq RENAME TO devices_name_uq;
+-- capybara:allow-destructive index rename; names follow the table rename (not released)
+ALTER INDEX IF EXISTS environment_instances_pkey RENAME TO device_instances_pkey;
+-- capybara:allow-destructive index rename; names follow the table rename (not released)
+ALTER INDEX IF EXISTS environment_instances_running_idx RENAME TO device_instances_running_idx;
+-- capybara:allow-destructive index rename; names follow the table rename (not released)
+ALTER INDEX IF EXISTS environment_instances_live_idx RENAME TO device_instances_live_idx;
+-- capybara:allow-destructive index rename; names follow the table rename (not released)
+ALTER INDEX IF EXISTS environment_instances_org_idx RENAME TO device_instances_org_idx;
+-- capybara:allow-destructive index rename; names follow the table rename (not released)
+ALTER INDEX IF EXISTS environment_defaults_pkey RENAME TO device_defaults_pkey;
+-- capybara:allow-destructive index rename; names follow the column rename (not released)
+ALTER INDEX IF EXISTS background_tasks_environment_running_idx RENAME TO background_tasks_device_running_idx;
+-- capybara:allow-destructive index rename; names follow the table rename (not released)
+ALTER INDEX IF EXISTS environment_machines_pkey RENAME TO device_machines_pkey;
+-- capybara:allow-destructive index rename; names follow the table rename (not released)
+ALTER INDEX IF EXISTS environment_machines_credential_hash_key RENAME TO device_machines_credential_hash_key;
+-- capybara:allow-destructive index rename; names follow the table rename (not released)
+ALTER INDEX IF EXISTS environment_machines_active_uq RENAME TO device_machines_active_uq;
+-- capybara:allow-destructive index rename; names follow the table rename (not released)
+ALTER INDEX IF EXISTS environment_machines_org_idx RENAME TO device_machines_org_idx;
+
+-- NOT NULL constraints are unnamed on PostgreSQL 17 (the target), so nothing to rename there.
+-- The other CHECK and foreign key constraints: RENAME CONSTRAINT has no IF EXISTS, so each is
+-- checked against pg_constraint first. The source CHECK is not renamed here: it is replaced
+-- below with the new value list.
+-- capybara:allow-destructive constraint rename; names follow the table and column renames (not released)
+DO $$
+DECLARE
+  r record;
+BEGIN
+  FOR r IN
+    SELECT * FROM (VALUES
+      ('devices', 'environments_org_id_fkey', 'devices_org_id_fkey'),
+      ('devices', 'environments_owner_account_id_fkey', 'devices_owner_account_id_fkey'),
+      ('devices', 'environments_owner_kind_check', 'devices_owner_kind_check'),
+      ('device_instances', 'environment_instances_fs_status_check', 'device_instances_fs_status_check'),
+      ('device_instances', 'environment_instances_status_check', 'device_instances_status_check'),
+      ('device_instances', 'environment_instances_environment_id_fkey', 'device_instances_device_id_fkey'),
+      ('device_defaults', 'environment_defaults_environment_id_fkey', 'device_defaults_device_id_fkey'),
+      ('conversations', 'conversations_environment_id_fkey', 'conversations_device_id_fkey'),
+      ('device_machines', 'environment_machines_mode_check', 'device_machines_mode_check'),
+      ('device_machines', 'environment_machines_org_id_fkey', 'device_machines_org_id_fkey'),
+      ('device_machines', 'environment_machines_environment_id_fkey', 'device_machines_device_id_fkey')
+    ) AS v(tbl, old_name, new_name)
+  LOOP
+    IF EXISTS (
+      SELECT 1 FROM pg_constraint c
+      JOIN pg_namespace s ON s.oid = c.connamespace
+      WHERE s.nspname = 'capybara' AND c.conname = r.old_name
+    ) THEN
+      EXECUTE format('ALTER TABLE capybara.%I RENAME CONSTRAINT %I TO %I',
+                     r.tbl, r.old_name, r.new_name);
+    END IF;
+  END LOOP;
+END
+$$;
+
+-- A connected machine's source 'device' becomes 'local': the old CHECK goes, the rows change, and
+-- the CHECK comes back under the new name with the new list.
+ALTER TABLE devices DROP CONSTRAINT IF EXISTS environments_source_check;
+ALTER TABLE devices DROP CONSTRAINT IF EXISTS devices_source_check;
+UPDATE devices SET source = 'local' WHERE source = 'device';
+ALTER TABLE devices
+  ADD CONSTRAINT devices_source_check CHECK (source IN ('cloud', 'local'));
+
+-- The kernel-internal provider '@device' becomes '@local' wherever a provider name is stored.
+UPDATE devices SET provider = '@local' WHERE provider = '@device';
+UPDATE device_instances SET provider = '@local' WHERE provider = '@device';
+UPDATE device_instances SET prev_provider = '@local' WHERE prev_provider = '@device';
+
+-- The log event 'environment_paths' becomes 'device_paths' (its idempotency key prefix too); the
+-- rows are updated first, so the old partial index (0094) finds them, then the index follows.
+UPDATE conversation_events
+  SET type = 'device_paths',
+      idem_key = CASE
+        WHEN idem_key LIKE 'environment_paths:%' THEN 'device_paths:' || substr(idem_key, 19)
+        ELSE idem_key
+      END
+  WHERE type = 'environment_paths';
+DROP INDEX IF EXISTS conversation_events_environment_paths_idx;
+CREATE INDEX IF NOT EXISTS conversation_events_device_paths_idx
+  ON conversation_events (conversation_id, seq)
+  WHERE type = 'device_paths';
+
+-- Eval case snapshots carry the events of their run: the same event type change, order kept.
+-- snapshot_bytes is not recomputed: only type names change (a few bytes shorter), harmless.
+UPDATE eval_cases
+  SET snapshot = jsonb_set(snapshot, '{events}', (
+    SELECT jsonb_agg(
+      CASE WHEN e->>'type' = 'environment_paths' THEN jsonb_set(e, '{type}', '"device_paths"')
+           ELSE e END
+      ORDER BY ord)
+    FROM jsonb_array_elements(snapshot->'events') WITH ORDINALITY AS t(e, ord)))
+  WHERE snapshot @? '$.events[*] ? (@.type == "environment_paths")';

package/src/migrations/0106_setup_guides_v2.sql

@@ -0,0 +1,10 @@
+-- Setup guides v2 (spec 2026-11-09-setup-guides-v2-design.md §11, §15).
+-- A connector made from a connector template records the setup guide it was set up with:
+-- { guideId, version, hash, mode } (mode null: the place has no modes), recorded when the
+-- connector is created from the template and when an org admin confirms the third-party app was
+-- updated. NULL = unknown (connectors before this column, custom ones): no drift notice for those.
+ALTER TABLE connectors ADD COLUMN IF NOT EXISTS guide_ack jsonb;
+-- The v1 acks of channel connections hold v1 template hashes that no v2 hash can equal; keeping
+-- them would show every existing connection a false update notice. Cleared ("no ack, no notice"):
+-- those connections start tracking again at their next mode switch or ack.
+UPDATE channel_connections SET guide_ack = NULL WHERE guide_ack IS NOT NULL;

package/dist/devices/device-auth.module.d.ts

@@ -1,7 +0,0 @@
-/**
- * Device sign-in (environments spec §13.3): {@link DeviceAuthService} behind
- * `DeviceAuthController`. Kept apart from {@link DevicesModule}, which `EnvironmentsModule`
- * imports (deleting an environment revokes its machine), while sign-in needs both.
- */
-export declare class DeviceAuthModule {
-}

package/dist/environments/conversation-environments.d.ts

@@ -1,75 +0,0 @@
-import { ApiError } from "../errors.js";
-import { KernelDb } from "../infra/database/kernel-db.js";
-import { TransactionHost } from "../infra/database/transaction-host.js";
-import { SandboxProviders } from "../sandbox/providers.js";
-import { EnvironmentAccess } from "./access.js";
-import { EnvironmentsService } from "./environments.service.js";
-/** `details[0].reason` of the error an anonymous IM conversation's sandbox call gets. */
-export declare const ANONYMOUS_NO_ENVIRONMENT = "anonymous";
-/** Anonymous IM senders have no environment (spec §4.2 item 8): their sandbox tools are off. */
-export declare const anonymousNoEnvironment: () => ApiError;
-/** How a new conversation picks its environment. */
-export interface NewConversationEnvironment {
-    /** The environment the person chose (the composer's picker); checked with `usable`. */
-    environmentId?: string;
-    /** An IM thread: the person's IM default (`environment_defaults`) when still usable. */
-    im?: boolean;
-}
-/**
- * Which environment a conversation works in (spec 2026-11-07-environments-design §4.1 items 1, 3;
- * §4.2 items 8, 9, 12). A conversation is bound once, to an environment of its owner
- * (`conversations.account_id`): the one chosen at its first send, else the owner's IM default
- * (IM threads), else the owner's default environment. Its sub-agents use the root's. Access is
- * checked when it is bound and again on every sandbox tool call ({@link forTool}); only the owner
- * may use a personal environment, so a conversation never reaches another person's.
- */
-export declare class ConversationEnvironments {
-    private readonly db;
-    readonly txHost: TransactionHost;
-    private readonly providers;
-    private readonly access;
-    private readonly environments;
-    constructor(db: KernelDb, txHost: TransactionHost, providers: Pick<SandboxProviders, "cloud"> & Partial<Pick<SandboxProviders, "forName">>, access: Pick<EnvironmentAccess, "usable">, environments: Pick<EnvironmentsService, "ensureDefault">);
-    /**
-     * The environment a new conversation of `accountId` is bound to: the chosen one when it is
-     * usable by the person (else `environment.not_found` / `environment.unavailable`, and nothing
-     * is created); without a choice the IM default (IM only) or the person's default environment.
-     * Null (unbound) for anonymous IM senders, and without a cloud sandbox provider when no usable
-     * IM default (a connected machine's environment, say) applies.
-     */
-    forNew(orgId: string, accountId: string, pick?: NewConversationEnvironment): Promise<string | null>;
-    /**
-     * The environment a sandbox tool call of the conversation tree rooted at `rootConversationId`
-     * enters, checked for its owner now. A conversation still unbound (created before
-     * environments, or while no provider existed) is bound first, to the owner's IM default when it
-     * is an IM thread, else to the owner's default environment; a racing call binds it once.
-     * Throws `sandbox.unavailable` for a cloud environment (or none to bind) without a cloud
-     * provider and for an anonymous IM conversation, and `environment.not_found` /
-     * `environment.unavailable` when the owner may not use it now. A conversation bound to a
-     * connected machine's environment (`@device`) does not need a cloud provider.
-     */
-    forTool(orgId: string, rootConversationId: string): Promise<string>;
-    /**
-     * Whether a sandbox tool call of the tree rooted at `rootConversationId` has a provider to run
-     * on, for tool listings (ruling R8; no binding, no access check, never throws): a cloud
-     * provider is loaded, or the environment the conversation is bound to (an unbound IM thread:
-     * its owner's IM default) runs on a registered kernel provider (`@device`). A forbidden or gone
-     * environment still counts: the call then says why.
-     */
-    usableNow(orgId: string, rootConversationId: string): Promise<boolean>;
-    /**
-     * The person's IM default when `im` and it is still theirs, live, in this org and usable (the
-     * table has no such guard), else their default environment (created when missing); null when
-     * that is needed and there is no cloud provider to make or use it. The owner having left the org
-     * reads as `environment.not_found`.
-     */
-    private defaultFor;
-    /** Binds an unbound conversation to `environmentId`; returns what it is bound to now. */
-    private bind;
-    /** The environment runs on a kernel-internal provider (`@device`). */
-    private isInternal;
-    /** The account is the org's anonymous IM guest (no person behind it). */
-    private isAnonymous;
-    /** The conversation is (or was) an IM thread's. */
-    private isImThread;
-}