@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

package/src/migrations/0085_agent_templates_phase4.sql

@@ -0,0 +1,45 @@
+-- Agent templates, phase 4 (spec 2026-11-05-plugin-component-management-design.md §15.2: P4-7
+-- connector_setup requests, P4-8 provenance). Expand-only: every new column is nullable, existing
+-- rows keep their shape, and the only dropped objects are two checks replaced in this file.
+
+-- P4-8: where an agent came from. Display data only (no FK: the template may be deleted or
+-- renamed later), written when an agent is created from a template.
+ALTER TABLE agents ADD COLUMN IF NOT EXISTS created_from_template_id text;
+ALTER TABLE agents ADD COLUMN IF NOT EXISTS created_from_template_version int;
+ALTER TABLE agents ADD COLUMN IF NOT EXISTS created_from_template_name text;
+
+-- P4-7: a `connector_setup` request asks an org admin to set up the connectors an agent made from a
+-- template needs (`pending_keys`: the template's connector keys still without an instance). It
+-- names its agent and no item or marketplace entry.
+ALTER TABLE catalog_requests ADD COLUMN IF NOT EXISTS agent_id text
+  REFERENCES agents(id) ON DELETE CASCADE;
+ALTER TABLE catalog_requests ADD COLUMN IF NOT EXISTS pending_keys jsonb;
+
+-- capybara:allow-destructive the check is added back with `connector_setup` in the next statement; existing rows (access, import, enable) satisfy it
+ALTER TABLE catalog_requests DROP CONSTRAINT IF EXISTS catalog_requests_kind_check;
+ALTER TABLE catalog_requests ADD CONSTRAINT catalog_requests_kind_check
+  CHECK (kind IN ('access', 'import', 'enable', 'connector_setup'));
+
+-- item_id is already nullable (0077). The target check of 0077 required an item for every kind but
+-- `import`; a connector_setup row needs an agent instead.
+-- capybara:allow-destructive the check is added back with the connector_setup branch in the next statement; existing rows satisfy its first and third branches
+ALTER TABLE catalog_requests DROP CONSTRAINT IF EXISTS catalog_requests_target_check;
+ALTER TABLE catalog_requests ADD CONSTRAINT catalog_requests_target_check
+  CHECK (
+    kind = 'import' AND entry_name IS NOT NULL
+    OR kind = 'connector_setup' AND agent_id IS NOT NULL
+      AND item_id IS NULL AND entry_name IS NULL
+    OR kind NOT IN ('import', 'connector_setup') AND item_id IS NOT NULL
+  );
+
+-- `pending_keys` is a JSON array of keys when set.
+ALTER TABLE catalog_requests DROP CONSTRAINT IF EXISTS catalog_requests_pending_keys_check;
+ALTER TABLE catalog_requests ADD CONSTRAINT catalog_requests_pending_keys_check
+  CHECK (pending_keys IS NULL OR jsonb_typeof(pending_keys) = 'array');
+
+-- At most one pending setup request per agent (P4-7).
+CREATE UNIQUE INDEX IF NOT EXISTS catalog_requests_pending_setup_uq
+  ON catalog_requests (agent_id) WHERE kind = 'connector_setup' AND status = 'pending';
+
+CREATE INDEX IF NOT EXISTS catalog_requests_agent_idx
+  ON catalog_requests (agent_id) WHERE agent_id IS NOT NULL;

package/src/migrations/0086_org_layering.sql

@@ -0,0 +1,30 @@
+-- Platform / org layering (spec 2026-11-07-platform-org-layering-design.md). Expand-only: two new
+-- tables, nothing existing changes.
+
+-- 0086, spec §5.4 / §5.8: an org's copy of an extension's overridable deployment config fields. A
+-- row is a copy; no row means the org follows the platform ("no copy" and "a copy equal to the
+-- platform" stay distinct). `config` holds the copy's non-secret values; its secrets live in
+-- `secrets` under the org (namespace `kernel`, key `plugin-override:<plugin>:<path>`). Rows are kept
+-- when the extension is disabled or uninstalled, like `extension_org_configs`.
+CREATE TABLE IF NOT EXISTS extension_org_overrides (
+  plugin text NOT NULL,
+  org_id text NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  config jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_by text REFERENCES accounts(id) ON DELETE SET NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_by text REFERENCES accounts(id) ON DELETE SET NULL,
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (plugin, org_id)
+);
+
+-- 0086, spec §7: an org admin's switch of one tool of an extension that is on in the org. No row
+-- means the tool follows the extension (on).
+CREATE TABLE IF NOT EXISTS org_tool_switches (
+  org_id text NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  plugin text NOT NULL,
+  tool text NOT NULL,
+  enabled boolean NOT NULL,
+  updated_by text REFERENCES accounts(id) ON DELETE SET NULL,
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (org_id, plugin, tool)
+);

package/src/migrations/0087_approval_summary.sql

@@ -0,0 +1,6 @@
+-- Platform tool (spec 2026-11-07-platform-tool-design.md §6.2, §6.3): an approval carries the
+-- kernel-rendered summary of the call ({zh, en}) and the scopes the person may choose. Expand-only:
+-- both columns are nullable; null keeps today's behavior (no summary; scopes derived from the row:
+-- "once" for a role escalation, else once / session / always).
+ALTER TABLE approvals ADD COLUMN IF NOT EXISTS summary jsonb;
+ALTER TABLE approvals ADD COLUMN IF NOT EXISTS scopes text[];

package/src/migrations/0088_environments.sql

@@ -0,0 +1,80 @@
+-- Environments phase 1 (spec 2026-11-07-environments-design §4.2, §10): a long-lived environment
+-- is one sandbox instance plus a file system kept until the environment is deleted. This replaces
+-- the per-conversation `sandboxes` table with `environment_instances`; the old table stays only
+-- for the cleanup job that destroys its remaining instances. The CHECK lists of owner_kind and
+-- source grow in phases 2 and 3 through new migrations.
+CREATE TABLE IF NOT EXISTS capybara.environments (
+  id text PRIMARY KEY,
+  org_id text NOT NULL REFERENCES capybara.orgs(id) ON DELETE CASCADE,
+  owner_kind text NOT NULL CHECK (owner_kind IN ('personal')),
+  owner_account_id text NOT NULL REFERENCES capybara.accounts(id),
+  name text,
+  is_default boolean NOT NULL DEFAULT false,
+  source text NOT NULL CHECK (source IN ('cloud')),
+  provider text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  deleted_at timestamptz
+);
+CREATE UNIQUE INDEX IF NOT EXISTS environments_default_uq
+  ON capybara.environments (org_id, owner_account_id)
+  WHERE is_default AND deleted_at IS NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS environments_name_uq
+  ON capybara.environments (org_id, owner_account_id, lower(name))
+  WHERE name IS NOT NULL AND deleted_at IS NULL;
+
+-- Same columns and meaning as the old sandboxes table (0023), keyed by environment. fs_handle and
+-- fs_status describe the kept file system; status 'none' means no instance exists yet.
+CREATE TABLE IF NOT EXISTS capybara.environment_instances (
+  environment_id text PRIMARY KEY REFERENCES capybara.environments(id) ON DELETE CASCADE,
+  org_id text NOT NULL,
+  provider text,
+  fs_handle jsonb,
+  fs_status text NOT NULL DEFAULT 'none' CHECK (fs_status IN ('none', 'ready', 'lost')),
+  handle jsonb,
+  status text NOT NULL DEFAULT 'none'
+    CHECK (status IN ('none', 'creating', 'running', 'suspended', 'destroyed')),
+  last_used_at timestamptz NOT NULL DEFAULT now(),
+  running_since timestamptz,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  suspended_at timestamptz,
+  destroyed_at timestamptz,
+  generation integer NOT NULL DEFAULT 0,
+  had_instance boolean NOT NULL DEFAULT false,
+  prev_provider text,
+  prev_handle jsonb,
+  sweep_failed_at timestamptz
+);
+CREATE INDEX IF NOT EXISTS environment_instances_running_idx
+  ON capybara.environment_instances (last_used_at)
+  WHERE status = 'running';
+CREATE INDEX IF NOT EXISTS environment_instances_live_idx
+  ON capybara.environment_instances (last_used_at)
+  WHERE status <> 'destroyed';
+CREATE INDEX IF NOT EXISTS environment_instances_org_idx
+  ON capybara.environment_instances (org_id);
+
+-- The environment a member's new conversations use when they pick none.
+CREATE TABLE IF NOT EXISTS capybara.environment_defaults (
+  org_id text NOT NULL,
+  account_id text NOT NULL,
+  environment_id text NOT NULL REFERENCES capybara.environments(id) ON DELETE CASCADE,
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (org_id, account_id)
+);
+
+-- No cascade: a deleted environment is soft-deleted and the conversation keeps pointing at it.
+ALTER TABLE capybara.conversations
+  ADD COLUMN IF NOT EXISTS environment_id text REFERENCES capybara.environments(id);
+
+ALTER TABLE capybara.background_tasks ADD COLUMN IF NOT EXISTS environment_id text;
+CREATE INDEX IF NOT EXISTS background_tasks_environment_running_idx
+  ON capybara.background_tasks (environment_id) WHERE status = 'running';
+
+-- Tasks that ran in a per-conversation sandbox lose it with the move to environments (the
+-- instances are destroyed by the cleanup job).
+UPDATE capybara.background_tasks
+  SET status = 'lost',
+      lost_reason = COALESCE(lost_reason, 'sandbox_replaced_by_environment'),
+      finished_at = COALESCE(finished_at, now())
+  WHERE status = 'running';

package/src/migrations/0089_model_kinds_usage.sql

@@ -0,0 +1,38 @@
+-- Model platform providers (spec 2026-11-06-model-platform-providers-design.md). Expand-only: two
+-- new tables, nothing existing changes.
+
+-- 0089, spec §5.3: models disabled on two layers. `org_id` null is the platform's list (the super
+-- admin; such a model is invisible to every org), otherwise the org's own list (an org admin, among
+-- the models the platform left on). No row means the model is enabled; a model a provider lists
+-- later is enabled everywhere until someone disables it. Keyed on the model id, so a row applies to
+-- whichever list the org sees (the platform's config or the org's own copy); an id the list does
+-- not contain is kept harmlessly.
+CREATE TABLE IF NOT EXISTS model_disabled (
+  org_id text NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  provider text NOT NULL,
+  model text NOT NULL,
+  disabled_by text REFERENCES accounts(id) ON DELETE SET NULL,
+  disabled_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX IF NOT EXISTS model_disabled_scope_key
+  ON model_disabled ((coalesce(org_id, '')), provider, model);
+
+-- 0089, spec §5.4: model usage outside conversations (an extension's `ctx.models.embed` call). One
+-- row per call; `reported_at` is set once the `usage.report` job for the row (eventId = id) has
+-- nothing left to deliver (delivered, no subscriber, or a definite drop); `report_failed_at` once
+-- the job gave up after its last attempt. The sweeper re-enqueues recent rows where both are null.
+CREATE TABLE IF NOT EXISTS model_usage (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  org_id text NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  extension text NOT NULL,
+  purpose text NOT NULL,
+  provider text NOT NULL,
+  model text NOT NULL,
+  input_tokens integer NOT NULL,
+  occurred_at timestamptz NOT NULL DEFAULT now(),
+  reported_at timestamptz NULL,
+  report_failed_at timestamptz NULL
+);
+CREATE INDEX IF NOT EXISTS model_usage_org_time ON model_usage (org_id, occurred_at DESC);
+CREATE INDEX IF NOT EXISTS model_usage_unreported ON model_usage (occurred_at)
+  WHERE reported_at IS NULL AND report_failed_at IS NULL;

package/src/migrations/0090_initial_passwords.sql

@@ -0,0 +1,27 @@
+-- Platform tool phase 2 (spec 2026-11-07-platform-tool-design.md §14.5 item 2): the super admin's
+-- agent creates an account with a kernel-generated one-time password. Expand-only.
+--
+-- must_change_password: the account must set its own password before anything else (the auth
+-- guard refuses every route but the password change, /me and logout until it does).
+ALTER TABLE capybara.accounts ADD COLUMN IF NOT EXISTS must_change_password boolean NOT NULL DEFAULT false;
+
+-- The generated password, sealed with the master keyring (AES-256-GCM, AAD = account id), waiting
+-- for the person who approved the creation to read it once on the web. Keyed by the account; the
+-- tool call it came from (conversation_id, run_id, call_id: a call id is unique only within its run)
+-- and its recipient decide who may read it. Read once (deleted as it is read), dropped when the
+-- account changes its password, and dropped after expires_at by the hourly cleanup job.
+CREATE TABLE IF NOT EXISTS capybara.account_initial_passwords (
+  account_id text PRIMARY KEY REFERENCES capybara.accounts(id) ON DELETE CASCADE,
+  recipient_account_id text NOT NULL REFERENCES capybara.accounts(id) ON DELETE CASCADE,
+  conversation_id text NOT NULL REFERENCES capybara.conversations(id) ON DELETE CASCADE,
+  run_id text NOT NULL,
+  call_id text NOT NULL,
+  master_key_id text NOT NULL,
+  ciphertext bytea NOT NULL,
+  expires_at timestamptz NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS account_initial_passwords_call_idx
+  ON capybara.account_initial_passwords (conversation_id, run_id, call_id);
+CREATE INDEX IF NOT EXISTS account_initial_passwords_expires_idx
+  ON capybara.account_initial_passwords (expires_at);

package/src/migrations/0091_account_time_zone.sql

@@ -0,0 +1,4 @@
+-- Run context (spec 2026-11-08-run-context-design.md §3.4): a person's time zone setting (IANA
+-- name). Null, the default, follows the browser's time zone sent with each message; a set value
+-- overrides it. Expand-only.
+ALTER TABLE accounts ADD COLUMN IF NOT EXISTS time_zone text;

package/src/migrations/0092_tools_default_on.sql

@@ -0,0 +1,27 @@
+-- Tools are on by default (spec 2026-11-08-tools-default-on-design.md §3): an agent stores only
+-- what it turns off (`disabledTools`), not an enabled list (`tools`). Every stored agent version,
+-- older ones included (a rollback reads the same shape), becomes "nothing turned off". Idempotent:
+-- a definition without `tools` is left alone, one without `disabledTools` gets the empty list.
+UPDATE agent_versions
+SET definition = (definition - 'tools') || jsonb_build_object('disabledTools', '[]'::jsonb)
+WHERE definition ? 'tools' OR NOT definition ? 'disabledTools';
+
+-- Org-made agent templates (saved from an agent by an org admin: no plugin, no catalog item)
+-- lose their `tools` allowlist, so they turn nothing off either. Templates from plugin packages
+-- keep what the package wrote.
+UPDATE agent_template_versions AS v
+SET definition = v.definition - 'tools'
+FROM agent_templates AS t
+WHERE t.id = v.template_id
+  AND t.plugin_name IS NULL
+  AND t.catalog_item_id IS NULL
+  AND v.definition ? 'tools';
+
+UPDATE platform_agent_template_versions AS v
+SET definition = v.definition - 'tools'
+FROM platform_agent_templates AS t
+WHERE t.id = v.template_id
+  AND t.plugin_name IS NULL
+  AND t.catalog_item_id IS NULL
+  AND v.object_prefix IS NULL
+  AND v.definition ? 'tools';

package/src/migrations/0093_connected_environments.sql

@@ -0,0 +1,37 @@
+-- Environments phase 2 (spec 2026-11-07-environments-design §6, §13): a person's own machine,
+-- connected through the device program, becomes an environment with source 'device'. Expand-only:
+-- the source CHECK list grows and a new table holds the connected machine.
+
+-- 0088 left the CHECK unnamed, so Postgres named it environments_source_check; re-add it under
+-- the same name with the longer list.
+ALTER TABLE environments DROP CONSTRAINT IF EXISTS environments_source_check;
+ALTER TABLE environments
+  ADD CONSTRAINT environments_source_check CHECK (source IN ('cloud', 'device'));
+
+-- The machine connected to a device environment. credential_hash is a hash of the machine's
+-- long-lived credential (cap_dev_...), never the credential itself; revoking a machine sets
+-- revoked_at and keeps the row, so only one unrevoked machine exists per environment.
+-- program_version, mode, roots and session_isolation are what the program reported on its last
+-- connection; last_seen_at is the last time it connected or pinged.
+CREATE TABLE IF NOT EXISTS environment_machines (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  org_id text NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  environment_id text NOT NULL REFERENCES environments(id) ON DELETE CASCADE,
+  account_id text NOT NULL,
+  credential_hash text NOT NULL UNIQUE,
+  name text NOT NULL,
+  os text NOT NULL,
+  arch text NOT NULL,
+  program_version text,
+  mode text CHECK (mode IN ('os', 'docker')),
+  roots jsonb,
+  session_isolation boolean NOT NULL DEFAULT false,
+  last_seen_at timestamptz,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  revoked_at timestamptz
+);
+CREATE UNIQUE INDEX IF NOT EXISTS environment_machines_active_uq
+  ON environment_machines (environment_id)
+  WHERE revoked_at IS NULL;
+-- The org cascade delete looks rows up by org (as environment_instances_org_idx in 0088).
+CREATE INDEX IF NOT EXISTS environment_machines_org_idx ON environment_machines (org_id);

package/src/migrations/0094_environment_paths_idx.sql

@@ -0,0 +1,7 @@
+-- Environments phase 2 (spec 2026-11-07-environments-design §13.1, ruling R22): every sandbox tool
+-- call reads the conversation's latest environment_paths event; a partial index answers it
+-- without scanning the conversation's events backwards. Not CONCURRENTLY, like the other index
+-- migrations (0025).
+CREATE INDEX IF NOT EXISTS conversation_events_environment_paths_idx
+  ON conversation_events (conversation_id, seq)
+  WHERE type = 'environment_paths';

package/src/migrations/0095_environment_files_resets.sql

@@ -0,0 +1,5 @@
+-- How many times an environment's files were reset. A provider may give the new file system the id
+-- of the destroyed one (sandbox-docker names its volumes after the environment), so the kernel
+-- counts resets itself: a conversation that last used the environment under another count is told
+-- its files were reset, not that the instance restarted on kept files.
+ALTER TABLE capybara.environment_instances ADD COLUMN IF NOT EXISTS fs_resets integer NOT NULL DEFAULT 0;

package/src/migrations/0096_environment_demoted_default.sql

@@ -0,0 +1,18 @@
+-- A default environment demoted by a sandbox provider switch (environments spec §4.2 item 13)
+-- records the provider it was demoted from; NULL for every other environment. The UI names such an
+-- environment after the default plus that provider's display name (「个人环境（Docker 沙箱）」), and
+-- when the deployment switches back to that provider the row is restored as the person's default.
+ALTER TABLE capybara.environments ADD COLUMN IF NOT EXISTS demoted_from_provider text;
+
+-- Backfill: until now a demoted default was renamed `Personal (<provider>)` (` 2`, ` 3`, … when
+-- taken). Those rows get the marker and lose the generated name. A person-made environment with
+-- such a name is caught too; that is accepted before 0.1.0 (AGENTS.md "Before 0.1.0": no real
+-- users yet). Idempotent: a backfilled row has a NULL name and no longer matches.
+UPDATE capybara.environments
+   SET demoted_from_provider = substring(name FROM '^Personal \(([^)]+)\)'),
+       name = NULL
+ WHERE owner_kind = 'personal'
+   AND NOT is_default
+   AND deleted_at IS NULL
+   AND demoted_from_provider IS NULL
+   AND name ~ '^Personal \([^)]+\)( [0-9]+)?$';

package/src/migrations/0097_extension_installs_enabled_at.sql

@@ -0,0 +1,16 @@
+-- When an install record's desired state last became `enabled` (NULL while disabled). A
+-- single-provider extension point (sandbox, object-store, secret-store, config-source) takes one
+-- enabled provider; enabling a second one is refused. A deployment that already has two enabled
+-- (enabled before that rule) loads the one enabled first on every replica and after every restart,
+-- never the first by name. `updated_at` cannot tell: an upgrade or a source change rewrites it.
+ALTER TABLE extension_installs ADD COLUMN IF NOT EXISTS enabled_at timestamptz;
+
+-- Backfill the enabled rows: the latest `extension.enabled` audit of the extension (every enable
+-- path writes one), else the install time. Idempotent: a filled row is skipped.
+UPDATE extension_installs i
+   SET enabled_at = COALESCE(
+         (SELECT max(a.at) FROM audit_events a
+           WHERE a.action = 'extension.enabled' AND a.target = i.name),
+         i.installed_at)
+ WHERE i.desired_state = 'enabled'
+   AND i.enabled_at IS NULL;

package/src/migrations/0098_single_provider_running_first.sql

@@ -0,0 +1,41 @@
+-- A deployment that already has two enabled providers of one single-provider extension point
+-- (sandbox, object-store, secret-store, config-source; enabled before the second enable was
+-- refused) loads the one with the earliest `enabled_at` (0097). 0097 backfilled it from the audit
+-- or the install time, which can name a provider other than the one the replicas run now: the
+-- rolling deploy would switch the provider. Prefer what is running: of the enabled providers of a
+-- contested point, the one with a `loaded` replica status row (the most recent heartbeat) gets an
+-- `enabled_at` just before every other provider of that point. A point with no loaded provider
+-- keeps the 0097 values. Idempotent: once the running provider is the earliest, nothing matches.
+WITH provided AS (
+  SELECT i.name, split_part(p.ref, '@', 1) AS point, i.enabled_at
+    FROM extension_installs i
+    JOIN extension_packages k ON k.sha256 = i.sha256
+   CROSS JOIN LATERAL jsonb_array_elements_text(
+           CASE WHEN jsonb_typeof(k.section -> 'manifest' -> 'provides') = 'array'
+                THEN k.section -> 'manifest' -> 'provides' ELSE '[]'::jsonb END) AS p(ref)
+   WHERE i.desired_state = 'enabled'
+     AND split_part(p.ref, '@', 1) IN ('sandbox', 'object-store', 'secret-store', 'config-source')
+),
+contested AS (
+  SELECT point FROM provided GROUP BY point HAVING count(DISTINCT name) > 1
+),
+running AS (
+  SELECT DISTINCT ON (pr.point) pr.point, pr.name
+    FROM provided pr
+    JOIN contested c ON c.point = pr.point
+    JOIN extension_replica_status s
+      ON s.plugin = pr.name AND s.source = 'install' AND s.state = 'loaded'
+   ORDER BY pr.point, s.heartbeat_at DESC, pr.name
+),
+target AS (
+  SELECT r.name, min(o.enabled_at) AS others_first
+    FROM running r
+    JOIN provided o ON o.point = r.point AND o.name <> r.name
+   GROUP BY r.name
+)
+UPDATE extension_installs i
+   SET enabled_at = t.others_first - interval '1 millisecond'
+  FROM target t
+ WHERE i.name = t.name
+   AND t.others_first IS NOT NULL
+   AND (i.enabled_at IS NULL OR i.enabled_at >= t.others_first);

package/src/migrations/0099_channel_connection_guide_ack.sql

@@ -0,0 +1,6 @@
+-- The setup guide a channel connection was last set up with (plugin setup guides spec
+-- 2026-11-08-plugin-setup-guides-design.md §6): { guideId, version, hash, mode } of the plugin's
+-- channel-connection guide, recorded on create, on an inbound mode switch and when an admin
+-- confirms the platform app was updated. NULL = unknown (rows before this column, or a plugin
+-- without a guide): no drift notice for those.
+ALTER TABLE channel_connections ADD COLUMN IF NOT EXISTS guide_ack jsonb;

package/src/migrations/0100_catalog_files.sql

@@ -0,0 +1,13 @@
+-- Catalog display files kept in PG (bootstrap catalog files fix, 2026-11-08): a plugin's icon, its
+-- connector templates' icons and its setup guide files, each capped at 64 KiB by the plugin format.
+-- Content-addressed: one row per sha256, shared by every version (and org) whose
+-- catalog_item_versions.files lists it; a reader only asks for the sha256 its version row records
+-- and re-checks it. They are in PG, not object storage, so a bootstrap plugin's icon is stored
+-- before any object-store extension runs (the object store's own icon included). touched_at: set
+-- by every import that stores the file again; the staging cleanup removes rows no version or
+-- staging lists once they are older than the staging TTL.
+CREATE TABLE IF NOT EXISTS catalog_files (
+  sha256 text PRIMARY KEY CHECK (sha256 ~ '^[0-9a-f]{64}$'),
+  data bytea NOT NULL,
+  touched_at timestamptz NOT NULL DEFAULT now()
+);

package/src/migrations/0101_marketplace_icons.sql

@@ -0,0 +1,32 @@
+-- Marketplace entry icons (maintainer decision 2026-11-08): the svg / png an entry's `icon` names
+-- (an https URL, or a path in a git marketplace's repository), downloaded on refresh through the
+-- marketplace network rules and kept here so the market list never hits the network per request
+-- and every replica serves the same bytes. One row per (marketplace, icon as the entry writes it);
+-- entries naming the same icon share it. Each is at most 64 KiB (the plugin icon limit). A URL's
+-- content is treated as fixed (fetched once); a repository path is read again at every new commit.
+-- Rows no entry names any more are removed by the refresh; deleting the marketplace removes them.
+CREATE TABLE IF NOT EXISTS marketplace_icons (
+  source_id text NOT NULL REFERENCES marketplaces(id) ON DELETE CASCADE,
+  ref text NOT NULL,
+  sha256 text NOT NULL CHECK (sha256 ~ '^[0-9a-f]{64}$'),
+  content_type text NOT NULL CHECK (content_type IN ('image/svg+xml', 'image/png')),
+  data bytea NOT NULL,
+  fetched_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (source_id, ref)
+);
+
+-- Icon URLs whose last download failed (HTTP error, invalid content, refused by the network rules,
+-- timeout): retried only after a backoff, and after the URLs never tried, so a few broken URLs never
+-- starve the rest of a refresh's download cap. Removed when the URL is stored or no entry names it.
+CREATE TABLE IF NOT EXISTS marketplace_icon_failures (
+  source_id text NOT NULL REFERENCES marketplaces(id) ON DELETE CASCADE,
+  ref text NOT NULL,
+  failed_at timestamptz NOT NULL DEFAULT now(),
+  attempts integer NOT NULL DEFAULT 1,
+  PRIMARY KEY (source_id, ref)
+);
+
+-- The git commit whose repository-path icons were last stored completely (null: none yet, or a
+-- refresh that predates icons). A refresh at last_commit is not_modified only when this equals it;
+-- otherwise the commit is read again, so a failed icon write recovers at the same commit.
+ALTER TABLE marketplaces ADD COLUMN IF NOT EXISTS icons_commit text;

package/src/migrations/0102_themes.sql

@@ -0,0 +1,64 @@
+-- Themes as a platform component kind (themes spec 2026-11-08-themes-design.md §6, §7): rows and
+-- versions shaped like platform agent templates, with the owner columns of org-owned items; the
+-- `theme` kind in the component scope, switch and install component tables; the person's pick on
+-- the account. Expand-only: the only dropped objects are the three kind checks, re-added wider in
+-- the next statement each.
+
+CREATE TABLE IF NOT EXISTS platform_themes (
+  id text PRIMARY KEY,
+  catalog_item_id uuid REFERENCES catalog_items(id) ON DELETE SET NULL,
+  plugin_name text,
+  name text NOT NULL,
+  description text,
+  description_zh text,
+  current_version integer NOT NULL CHECK (current_version >= 1),
+  scope_mode text NOT NULL DEFAULT 'follow' CHECK (scope_mode IN ('follow', 'own')),
+  scope text NOT NULL DEFAULT 'optional' CHECK (scope IN ('all', 'optional', 'named')),
+  disabled boolean NOT NULL DEFAULT false,
+  shown_to_others boolean NOT NULL DEFAULT true,
+  scope_version integer NOT NULL DEFAULT 0,
+  -- The owning org (NULL = the platform), the org it was created in (no FK, immutable) and the
+  -- share switch, as on the other platform components (0084).
+  owner_org_id text REFERENCES orgs(id) ON DELETE SET NULL,
+  origin_org_id text,
+  shareable boolean NOT NULL DEFAULT false,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  deleted_at timestamptz
+);
+CREATE UNIQUE INDEX IF NOT EXISTS platform_themes_live_name_origin_uq
+  ON platform_themes ((coalesce(plugin_name, '')), name, (coalesce(origin_org_id, '')))
+  WHERE deleted_at IS NULL;
+
+-- One version of a theme: `definition` is the parsed theme file (`ParsedTheme`); fonts and logo
+-- live under `object_prefix` in `deployment/` (NULL for a theme without assets).
+CREATE TABLE IF NOT EXISTS platform_theme_versions (
+  theme_id text NOT NULL REFERENCES platform_themes(id) ON DELETE CASCADE,
+  version integer NOT NULL CHECK (version >= 1),
+  definition jsonb NOT NULL,
+  object_prefix text,
+  catalog_version text,
+  updated_on_own boolean NOT NULL DEFAULT false,
+  created_by text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (theme_id, version)
+);
+
+-- 0081 declared these checks inline, so they carry the default names.
+-- capybara:allow-destructive the check is added back with 'theme' in the next statement; existing rows satisfy it
+ALTER TABLE component_scope_orgs DROP CONSTRAINT IF EXISTS component_scope_orgs_kind_check;
+ALTER TABLE component_scope_orgs ADD CONSTRAINT component_scope_orgs_kind_check
+  CHECK (kind IN ('skill', 'agent_template', 'connector_template', 'theme'));
+-- capybara:allow-destructive the check is added back with 'theme' in the next statement; existing rows satisfy it
+ALTER TABLE component_org_switches DROP CONSTRAINT IF EXISTS component_org_switches_kind_check;
+ALTER TABLE component_org_switches ADD CONSTRAINT component_org_switches_kind_check
+  CHECK (kind IN ('skill', 'agent_template', 'connector_template', 'theme'));
+-- NOT VALID as in 0053: existing rows were checked by the narrower constraint already.
+-- capybara:allow-destructive the check is added back with 'theme' in the next statement; existing rows satisfy it
+ALTER TABLE plugin_install_components DROP CONSTRAINT IF EXISTS plugin_install_components_kind_check;
+ALTER TABLE plugin_install_components ADD CONSTRAINT plugin_install_components_kind_check
+  CHECK (kind IN ('extension', 'connector', 'skill', 'plugin', 'agent_template', 'theme')) NOT VALID;
+
+-- The person's theme (§7): one value across all their orgs; NULL follows the org. No FK: a pick
+-- that is not on in the current org (or no longer exists) is skipped, never an error.
+ALTER TABLE accounts ADD COLUMN IF NOT EXISTS theme text;

package/src/migrations/0103_ui_theme_setting.sql

@@ -0,0 +1,7 @@
+-- The platform default theme setting `uiTheme` (themes spec §7) always has a row: the guards that
+-- refuse taking the default theme away from an org read it FOR SHARE, and the setting's write
+-- locks it FOR UPDATE before checking the chosen theme, so the two serialize on this row.
+-- `{"id": null}` is the built-in theme (the default when the key is missing).
+INSERT INTO deployment_settings (key, value)
+VALUES ('uiTheme', '{"id": null}'::jsonb)
+ON CONFLICT (key) DO NOTHING;

package/dist/catalog/upgrade-targets.d.ts

@@ -1,59 +0,0 @@
-import type { Transaction } from "kysely";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
-import type { ExtensionHost } from "../extensions/host.js";
-type Trx = Transaction<KernelDatabase>;
-/**
- * Which versions an org may upgrade an installed plugin to (package ecosystem spec §10, Decision
- * 10, Ruling 8):
- * - a plugin with an extension follows the deployment: the only target is the catalog version
- *   whose extension package (sha256) is the one installed on the deployment, the newest import on
- *   ties (`1.0.0` and `1.0.0+sha256.x` can share an extension version with different bytes); an
- *   extension loaded from the startup config (config, no package) is matched by its
- *   version;
- * - a purely declarative plugin may move to any other imported version (an older one is a
- *   rollback).
- */
-/** The extension the deployment runs for a plugin name. */
-export interface DeployedExtension {
-    /** The installed package's sha256 (null for a config extension). */
-    sha256: string | null;
-    version: string;
-}
-/** A catalog version row as the target rules read it. */
-export interface TargetVersion {
-    version: string;
-    manifest: unknown;
-    extension_sha256: string | null;
-    imported_at: Date;
-}
-/**
- * The deployment's extension for plugin `name`: its install record (`extension_installs`, the
- * deployment's desired package; disabled on the deployment counts as none), else the extension
- * this replica loaded from the startup config; undefined when the deployment runs none (then no
- * upgrade target and no "upgrade pending").
- */
-export declare function deployedExtension(db: KernelDb | Trx, host: Pick<ExtensionHost, "manifests">, name: string): Promise<DeployedExtension | undefined>;
-/** Whether catalog version `v` carries the deployment's extension `d`. */
-export declare const runsDeployed: (v: TargetVersion, d: DeployedExtension) => boolean;
-/**
- * The catalog version an org install of an extension-bearing plugin may move to: the one carrying
- * the deployment's extension, the newest import on ties; undefined when none does.
- */
-export declare function deploymentTarget(versions: readonly TargetVersion[], d: DeployedExtension | undefined): TargetVersion | undefined;
-/** What an install view says about upgrades (Decision 10). */
-export interface UpgradeInfo {
-    /** The version an upgrade can move to now (the highest allowed target), null when none. */
-    upgradeAvailable: string | null;
-    /** An extension-bearing plugin whose org version is not the one the deployment runs. */
-    deploymentPending: boolean;
-}
-/**
- * The upgrade info of org installs (`itemId`, `name`, `version`), keyed by `itemId@version`; reads
- * the items' catalog versions and the deployment's extensions in a few queries.
- */
-export declare function upgradeInfo(db: KernelDb, host: Pick<ExtensionHost, "manifests">, installs: readonly {
-    itemId: string;
-    name: string;
-    version: string;
-}[]): Promise<Map<string, UpgradeInfo>>;
-export {};