@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.4

package/src/migrations/0063_tool_keys_claude_code.sql

@@ -0,0 +1,220 @@
+-- Tool naming (spec docs/superpowers/specs/2026-10-29-tool-naming-claude-code-design.md §8.2):
+-- the release candidates' tool keys in mutable state become the current keys. Builtins by the
+-- frozen map of packages/kernel/src/tools/legacy-keys.ts (LEGACY_BUILTINS); an rc `<x>__<tool>`
+-- key becomes `mcp__<x>__<tool>` when `x` is a connector of the row's org (or the row records its
+-- connector) and `plugin__<x>__<tool>` when `x` is an extension of the deployment
+-- (extension_installs, or extension_name_owners for config-declared ones); when both or neither,
+-- the row stays and the kernel's startup notice `tools.legacy_key_unmapped` counts it.
+-- Keys in the current format never match. A grant whose new key already exists for the same
+-- owner is left as it is (the primary key). Decided approvals and answered questions are
+-- history and stay. Logs and recordings are never rewritten (§8). Idempotent: a second run
+-- matches nothing it could change.
+
+-- capybara:allow-destructive rewrites rc tool keys in place (the old keys no longer name a tool; the kernel reads only the new ones)
+UPDATE tool_grants g
+SET tool_key = m.new_key
+FROM (VALUES
+  ('sandbox_bash', 'Bash'), ('sandbox_read', 'Read'), ('sandbox_write', 'Write'),
+  ('sandbox_edit', 'Edit'), ('sandbox_glob', 'Glob'), ('sandbox_grep', 'Grep'),
+  ('sandbox_deliver', 'Deliver'), ('skill_load', 'Skill'), ('skill_write', 'SkillWrite'),
+  ('ask_user', 'AskUserQuestion'), ('read_tool_output', 'ReadToolOutput'),
+  ('tool_search', 'ToolSearch'), ('agent', 'Agent')
+) AS m(old_key, new_key)
+WHERE g.tool_key = m.old_key
+  AND NOT EXISTS (
+    SELECT 1 FROM tool_grants x
+    WHERE x.org_id = g.org_id AND x.account_id = g.account_id AND x.agent_id = g.agent_id
+      AND x.tool_key = m.new_key
+  );
+
+-- capybara:allow-destructive rewrites rc tool keys in place (the old keys no longer name a tool; the kernel reads only the new ones)
+UPDATE tool_grants g
+SET tool_key = CASE
+  WHEN g.connector_id IS NOT NULL OR (
+    EXISTS (SELECT 1 FROM connectors c
+            WHERE c.org_id = g.org_id AND c.deleted_at IS NULL
+              AND c.slug = split_part(g.tool_key, '__', 1))
+    AND split_part(g.tool_key, '__', 1) NOT IN (
+      SELECT name FROM extension_installs UNION SELECT name FROM extension_name_owners)
+  ) THEN 'mcp__' || g.tool_key
+  ELSE 'plugin__' || g.tool_key
+END
+WHERE g.tool_key ~ '^[a-z0-9][a-z0-9_-]*__.' AND g.tool_key !~ '^(mcp|plugin)__'
+  AND (
+    g.connector_id IS NOT NULL
+    OR (
+      EXISTS (SELECT 1 FROM connectors c
+              WHERE c.org_id = g.org_id AND c.deleted_at IS NULL
+                AND c.slug = split_part(g.tool_key, '__', 1))
+    ) <> (
+      split_part(g.tool_key, '__', 1) IN (
+        SELECT name FROM extension_installs UNION SELECT name FROM extension_name_owners)
+    )
+  )
+  AND NOT EXISTS (
+    SELECT 1 FROM tool_grants x
+    WHERE x.org_id = g.org_id AND x.account_id = g.account_id AND x.agent_id = g.agent_id
+      AND x.tool_key IN ('mcp__' || g.tool_key, 'plugin__' || g.tool_key)
+  );
+
+-- capybara:allow-destructive rewrites rc tool keys in place (the old keys no longer name a tool; the kernel reads only the new ones)
+UPDATE conversation_tool_grants g
+SET tool_key = m.new_key
+FROM (VALUES
+  ('sandbox_bash', 'Bash'), ('sandbox_read', 'Read'), ('sandbox_write', 'Write'),
+  ('sandbox_edit', 'Edit'), ('sandbox_glob', 'Glob'), ('sandbox_grep', 'Grep'),
+  ('sandbox_deliver', 'Deliver'), ('skill_load', 'Skill'), ('skill_write', 'SkillWrite'),
+  ('ask_user', 'AskUserQuestion'), ('read_tool_output', 'ReadToolOutput'),
+  ('tool_search', 'ToolSearch'), ('agent', 'Agent')
+) AS m(old_key, new_key)
+WHERE g.tool_key = m.old_key
+  AND NOT EXISTS (
+    SELECT 1 FROM conversation_tool_grants x
+    WHERE x.conversation_id = g.conversation_id AND x.tool_key = m.new_key
+  );
+
+-- capybara:allow-destructive rewrites rc tool keys in place (the old keys no longer name a tool; the kernel reads only the new ones)
+UPDATE conversation_tool_grants g
+SET tool_key = CASE
+  WHEN g.connector_id IS NOT NULL OR (
+    EXISTS (SELECT 1 FROM connectors c
+            WHERE c.org_id = v.org_id AND c.deleted_at IS NULL
+              AND c.slug = split_part(g.tool_key, '__', 1))
+    AND split_part(g.tool_key, '__', 1) NOT IN (
+      SELECT name FROM extension_installs UNION SELECT name FROM extension_name_owners)
+  ) THEN 'mcp__' || g.tool_key
+  ELSE 'plugin__' || g.tool_key
+END
+FROM conversations v
+WHERE v.id = g.conversation_id
+  AND g.tool_key ~ '^[a-z0-9][a-z0-9_-]*__.' AND g.tool_key !~ '^(mcp|plugin)__'
+  AND (
+    g.connector_id IS NOT NULL
+    OR (
+      EXISTS (SELECT 1 FROM connectors c
+              WHERE c.org_id = v.org_id AND c.deleted_at IS NULL
+                AND c.slug = split_part(g.tool_key, '__', 1))
+    ) <> (
+      split_part(g.tool_key, '__', 1) IN (
+        SELECT name FROM extension_installs UNION SELECT name FROM extension_name_owners)
+    )
+  )
+  AND NOT EXISTS (
+    SELECT 1 FROM conversation_tool_grants x
+    WHERE x.conversation_id = g.conversation_id
+      AND x.tool_key IN ('mcp__' || g.tool_key, 'plugin__' || g.tool_key)
+  );
+
+-- capybara:allow-destructive rewrites rc tool keys of pending approvals in place (resumed by run and call id, never by key)
+UPDATE approvals a
+SET tool_key = m.new_key
+FROM (VALUES
+  ('sandbox_bash', 'Bash'), ('sandbox_read', 'Read'), ('sandbox_write', 'Write'),
+  ('sandbox_edit', 'Edit'), ('sandbox_glob', 'Glob'), ('sandbox_grep', 'Grep'),
+  ('sandbox_deliver', 'Deliver'), ('skill_load', 'Skill'), ('skill_write', 'SkillWrite'),
+  ('ask_user', 'AskUserQuestion'), ('read_tool_output', 'ReadToolOutput'),
+  ('tool_search', 'ToolSearch'), ('agent', 'Agent')
+) AS m(old_key, new_key)
+WHERE a.status = 'pending' AND a.tool_key = m.old_key;
+
+-- capybara:allow-destructive rewrites rc tool keys of pending approvals in place (resumed by run and call id, never by key)
+UPDATE approvals a
+SET tool_key = CASE
+  WHEN a.connector_id IS NOT NULL OR (
+    EXISTS (SELECT 1 FROM connectors c
+            WHERE c.org_id = a.org_id AND c.deleted_at IS NULL
+              AND c.slug = split_part(a.tool_key, '__', 1))
+    AND split_part(a.tool_key, '__', 1) NOT IN (
+      SELECT name FROM extension_installs UNION SELECT name FROM extension_name_owners)
+  ) THEN 'mcp__' || a.tool_key
+  ELSE 'plugin__' || a.tool_key
+END
+WHERE a.status = 'pending'
+  AND a.tool_key ~ '^[a-z0-9][a-z0-9_-]*__.' AND a.tool_key !~ '^(mcp|plugin)__'
+  AND (
+    a.connector_id IS NOT NULL
+    OR (
+      EXISTS (SELECT 1 FROM connectors c
+              WHERE c.org_id = a.org_id AND c.deleted_at IS NULL
+                AND c.slug = split_part(a.tool_key, '__', 1))
+    ) <> (
+      split_part(a.tool_key, '__', 1) IN (
+        SELECT name FROM extension_installs UNION SELECT name FROM extension_name_owners)
+    )
+  );
+
+-- capybara:allow-destructive rewrites rc tool keys of pending questions in place (resumed by run and call id, never by key)
+UPDATE questions q
+SET spec = jsonb_set(q.spec, '{toolKey}', to_jsonb(m.new_key))
+FROM (VALUES
+  ('sandbox_bash', 'Bash'), ('sandbox_read', 'Read'), ('sandbox_write', 'Write'),
+  ('sandbox_edit', 'Edit'), ('sandbox_glob', 'Glob'), ('sandbox_grep', 'Grep'),
+  ('sandbox_deliver', 'Deliver'), ('skill_load', 'Skill'), ('skill_write', 'SkillWrite'),
+  ('ask_user', 'AskUserQuestion'), ('read_tool_output', 'ReadToolOutput'),
+  ('tool_search', 'ToolSearch'), ('agent', 'Agent')
+) AS m(old_key, new_key)
+WHERE q.status = 'pending' AND q.spec->>'toolKey' = m.old_key;
+
+-- capybara:allow-destructive rewrites rc tool keys of pending questions in place (resumed by run and call id, never by key)
+UPDATE questions q
+SET spec = jsonb_set(
+  q.spec,
+  '{toolKey}',
+  to_jsonb(CASE
+    WHEN EXISTS (SELECT 1 FROM connectors c
+                 WHERE c.org_id = q.org_id AND c.deleted_at IS NULL
+                   AND c.slug = split_part(q.spec->>'toolKey', '__', 1))
+    THEN 'mcp__' || (q.spec->>'toolKey')
+    ELSE 'plugin__' || (q.spec->>'toolKey')
+  END)
+)
+WHERE q.status = 'pending'
+  AND q.spec->>'toolKey' ~ '^[a-z0-9][a-z0-9_-]*__.' AND q.spec->>'toolKey' !~ '^(mcp|plugin)__'
+  AND (
+    EXISTS (SELECT 1 FROM connectors c
+            WHERE c.org_id = q.org_id AND c.deleted_at IS NULL
+              AND c.slug = split_part(q.spec->>'toolKey', '__', 1))
+  ) <> (
+    split_part(q.spec->>'toolKey', '__', 1) IN (
+      SELECT name FROM extension_installs UNION SELECT name FROM extension_name_owners)
+  );
+
+-- What the startup notice counts (rows the statements above could not map), each over a partial
+-- index holding only such rows, so the count at every start reads nearly empty indexes. The
+-- predicate is the one of countLegacyToolKeys (packages/kernel/src/tools/legacy-data.ts).
+CREATE INDEX IF NOT EXISTS tool_grants_legacy_key_idx ON tool_grants (org_id)
+  WHERE (tool_key = ANY (ARRAY['sandbox_bash', 'sandbox_read', 'sandbox_write', 'sandbox_edit',
+    'sandbox_glob', 'sandbox_grep', 'sandbox_deliver', 'skill_load', 'skill_write', 'ask_user',
+    'read_tool_output', 'tool_search', 'agent']::text[])
+    OR (tool_key ~ '^[a-z0-9][a-z0-9_-]*__.' AND tool_key !~ '^(mcp|plugin)__'));
+CREATE INDEX IF NOT EXISTS conversation_tool_grants_legacy_key_idx
+  ON conversation_tool_grants (conversation_id)
+  WHERE (tool_key = ANY (ARRAY['sandbox_bash', 'sandbox_read', 'sandbox_write', 'sandbox_edit',
+    'sandbox_glob', 'sandbox_grep', 'sandbox_deliver', 'skill_load', 'skill_write', 'ask_user',
+    'read_tool_output', 'tool_search', 'agent']::text[])
+    OR (tool_key ~ '^[a-z0-9][a-z0-9_-]*__.' AND tool_key !~ '^(mcp|plugin)__'));
+CREATE INDEX IF NOT EXISTS approvals_legacy_key_idx ON approvals (org_id)
+  WHERE status = 'pending'
+    AND (tool_key = ANY (ARRAY['sandbox_bash', 'sandbox_read', 'sandbox_write', 'sandbox_edit',
+    'sandbox_glob', 'sandbox_grep', 'sandbox_deliver', 'skill_load', 'skill_write', 'ask_user',
+    'read_tool_output', 'tool_search', 'agent']::text[])
+    OR (tool_key ~ '^[a-z0-9][a-z0-9_-]*__.' AND tool_key !~ '^(mcp|plugin)__'));
+CREATE INDEX IF NOT EXISTS questions_legacy_key_idx ON questions (org_id)
+  WHERE status = 'pending'
+    AND ((spec->>'toolKey') = ANY (ARRAY['sandbox_bash', 'sandbox_read', 'sandbox_write',
+    'sandbox_edit', 'sandbox_glob', 'sandbox_grep', 'sandbox_deliver', 'skill_load', 'skill_write',
+    'ask_user', 'read_tool_output', 'tool_search', 'agent']::text[])
+    OR ((spec->>'toolKey') ~ '^[a-z0-9][a-z0-9_-]*__.' AND (spec->>'toolKey') !~ '^(mcp|plugin)__'));
+
+-- Read before Write / Edit (spec §4.5): EventLog.latestFileState reads the latest tool_result of
+-- a conversation whose view names a file, on every Write and Edit. Without this index it scans
+-- the conversation's events backwards through the primary key, filtering each payload (EXPLAIN
+-- on a 20 000-event conversation: every row removed by the filter for a path never read); with
+-- it, one index probe. Partial: only tool_result rows. Built without CONCURRENTLY (a migration
+-- runs in one transaction), which locks conversation_events against writes while it builds: this
+-- assumes release-candidate-sized event tables, as the event indexes of 0025 and 0040 did. A
+-- deployment with a large table builds it CONCURRENTLY by hand before upgrading; IF NOT EXISTS
+-- then skips it here.
+CREATE INDEX IF NOT EXISTS conversation_events_file_state_idx
+  ON conversation_events (conversation_id, ((payload->'view'->'file'->>'path')), seq DESC)
+  WHERE type = 'tool_result';

package/src/migrations/0064_account_last_org.sql

@@ -0,0 +1,7 @@
+-- The organization an account last chose as its current one: a new web session (login, SSO, setup,
+-- an accepted invitation) starts in it while the account is still a member and the org is not
+-- deleted, so people don't pick their org again at every sign-in. Written with the session's
+-- current org by `PUT /me/current-org`; NULL = never chosen (a new session then starts in the only
+-- org when there is exactly one). Additive: older replicas never read or write it.
+ALTER TABLE capybara.accounts
+  ADD COLUMN IF NOT EXISTS last_org_id text REFERENCES capybara.orgs(id) ON DELETE SET NULL;

package/src/migrations/0065_conversation_archive.sql

@@ -0,0 +1,8 @@
+-- A person archives a conversation (hidden from the default lists, still readable and unarchived
+-- by a new message) or deletes it (soft: hidden everywhere for the owner; the event log, runs and
+-- trajectories stay for enterprise admins).
+ALTER TABLE capybara.conversations ADD COLUMN IF NOT EXISTS archived_at timestamptz;
+ALTER TABLE capybara.conversations ADD COLUMN IF NOT EXISTS deleted_at timestamptz;
+CREATE INDEX IF NOT EXISTS conversations_live_idx
+  ON capybara.conversations (org_id, account_id, updated_at DESC)
+  WHERE deleted_at IS NULL AND archived_at IS NULL;

package/src/migrations/0066_extension_display_name.sql

@@ -0,0 +1,4 @@
+-- The plugin.json `displayName` ({ zh, en }) of an extension package, written when the package is
+-- stored; NULL when the plugin has none and for packages stored before this migration (no
+-- backfill: a name arrives with the next version). Additive: older replicas never read it.
+ALTER TABLE capybara.extension_packages ADD COLUMN IF NOT EXISTS display_name jsonb;

package/src/migrations/0067_agent_profiles.sql

@@ -0,0 +1,20 @@
+-- The agent profile (avatar, description, quick actions): display data stored beside the agent,
+-- outside agent_versions, so changing it creates no version. Expand-only.
+-- profile_updated_at is kept at millisecond precision so a client can send it back as expectedUpdatedAt.
+ALTER TABLE capybara.agents ADD COLUMN IF NOT EXISTS profile_avatar jsonb;
+ALTER TABLE capybara.agents ADD COLUMN IF NOT EXISTS profile_description text NOT NULL DEFAULT '';
+ALTER TABLE capybara.agents
+  ADD COLUMN IF NOT EXISTS profile_quick_actions jsonb NOT NULL DEFAULT '[]';
+ALTER TABLE capybara.agents
+  ADD COLUMN IF NOT EXISTS profile_updated_at timestamptz NOT NULL
+  DEFAULT date_trunc('milliseconds', now());
+
+-- A definition's avatarUrl becomes an external avatar (once: only where none is set yet).
+UPDATE capybara.agents a
+SET profile_avatar = jsonb_build_object('kind', 'external', 'url', v.definition->>'avatarUrl')
+FROM capybara.agent_versions v
+WHERE v.agent_id = a.id
+  AND v.version = a.current_version
+  AND a.profile_avatar IS NULL
+  AND jsonb_typeof(v.definition->'avatarUrl') = 'string'
+  AND v.definition->>'avatarUrl' <> '';

package/src/migrations/0068_agent_avatar_uploads.sql

@@ -0,0 +1,7 @@
+-- Agent avatar uploads reuse the presigned attachment flow: a new purpose 'agent-avatar' and the
+-- agent whose profile uses the upload (set once on save; a used upload has no expiry).
+ALTER TABLE capybara.attachments DROP CONSTRAINT IF EXISTS attachments_purpose_check;
+ALTER TABLE capybara.attachments
+  ADD CONSTRAINT attachments_purpose_check
+  CHECK (purpose IN ('chat', 'skill-package', 'agent-avatar'));
+ALTER TABLE capybara.attachments ADD COLUMN IF NOT EXISTS agent_id text;

package/src/migrations/0069_attachments_agent_idx.sql

@@ -0,0 +1,3 @@
+-- The agent avatar lookup and the cleanup of an agent's uploads filter attachments by agent_id;
+-- a partial index keeps it small, since most attachments belong to no agent.
+CREATE INDEX IF NOT EXISTS attachments_agent_idx ON capybara.attachments (agent_id) WHERE agent_id IS NOT NULL;

package/src/migrations/0070_background_tasks.sql

@@ -0,0 +1,37 @@
+-- Background Bash (spec 2026-11-05-background-bash-design §4.1): a command started with
+-- run_in_background keeps running in the conversation's sandbox after its tool call returns. One
+-- row per task; the owner is `conversation_id` (the child conversation for a sub-agent) and
+-- `sandbox_conversation_id` is the root conversation that owns the sandbox. Rows go with their
+-- conversations; finished rows are pruned after tools.outputRetentionDays.
+CREATE TABLE IF NOT EXISTS capybara.background_tasks (
+  id text PRIMARY KEY,
+  org_id text NOT NULL,
+  conversation_id text NOT NULL REFERENCES capybara.conversations(id) ON DELETE CASCADE,
+  sandbox_conversation_id text NOT NULL REFERENCES capybara.conversations(id) ON DELETE CASCADE,
+  run_id text NOT NULL,
+  call_id text NOT NULL,
+  trigger_account_id text NOT NULL,
+  description text NOT NULL,
+  command text NOT NULL,
+  -- the session id: the pid `setsid` started; stopping and liveness go by the session
+  sid text NOT NULL,
+  -- relative to /workspace
+  output_path text NOT NULL,
+  status text NOT NULL DEFAULT 'running'
+    CHECK (status IN ('running', 'completed', 'failed', 'stopped', 'timed_out', 'lost')),
+  lost_reason text,
+  exit_code integer,
+  started_at timestamptz NOT NULL DEFAULT now(),
+  finished_at timestamptz,
+  deadline_at timestamptz NOT NULL,
+  -- the sandbox instance the task runs in (the handle plus created_at identify an instance)
+  sandbox_created_at timestamptz NOT NULL,
+  -- a task marked lost while its process may still exist
+  kill_pending boolean NOT NULL DEFAULT false,
+  -- the bytes TaskOutput has already returned
+  read_offset bigint NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS background_tasks_running_idx
+  ON capybara.background_tasks (sandbox_conversation_id) WHERE status = 'running';
+CREATE INDEX IF NOT EXISTS background_tasks_conversation_idx
+  ON capybara.background_tasks (conversation_id, started_at DESC);

package/src/migrations/0071_background_tasks_reserve.sql

@@ -0,0 +1,6 @@
+-- Background Bash: a launch reserves its row (status running, counted against
+-- sandbox.background.maxTasks under a transaction-scoped lock) before the launch exec, and sets
+-- sid and sandbox_created_at once the command started. A row without a sid is a reservation: the
+-- poller skips it, and a failed launch finishes it as failed.
+ALTER TABLE IF EXISTS capybara.background_tasks ALTER COLUMN sid DROP NOT NULL;
+ALTER TABLE IF EXISTS capybara.background_tasks ALTER COLUMN sandbox_created_at DROP NOT NULL;

package/src/migrations/0072_background_tasks_stopping.sql

@@ -0,0 +1,5 @@
+-- Background Bash: a stop claims its task before it signals the session (stopping_at), so the
+-- poller, which skips a claimed task, cannot finish it meanwhile from what the signals leave
+-- behind (no process, or the wrapper's exit status); the stop's own finish is then the only one.
+-- A launch that finds its reservation claimed kills the command it started at once.
+ALTER TABLE IF EXISTS capybara.background_tasks ADD COLUMN IF NOT EXISTS stopping_at timestamptz;

package/src/migrations/0073_org_extension_point_defaults.sql

@@ -0,0 +1,11 @@
+-- Web tools (spec §6): an org's default provider of an extension point with `selection:
+-- "org-default"` (`point` is the name without the major, e.g. `web-search`). A row naming an
+-- extension that is disabled or uninstalled stays and is ignored until it is a candidate again.
+CREATE TABLE IF NOT EXISTS capybara.org_extension_point_defaults (
+  org_id text NOT NULL REFERENCES capybara.orgs(id) ON DELETE CASCADE,
+  point text NOT NULL,
+  extension text NOT NULL,
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  updated_by text REFERENCES capybara.accounts(id) ON DELETE SET NULL,
+  PRIMARY KEY (org_id, point)
+);

package/dist/tools/builtins/sandbox/names.d.ts

@@ -1,7 +0,0 @@
-/**
- * 沙箱内置工具的名字（M5 T8，Ruling M12：工具 key 只能含字母数字、`_`、`-`，所以是 `sandbox_<动作>`）。
- * 单独成文件：注册表与策略判定只需要名字，不引入工具实现。
- */
-export declare const SANDBOX_TOOL_NAMES: readonly ["sandbox_bash", "sandbox_read", "sandbox_write", "sandbox_edit", "sandbox_glob", "sandbox_grep", "sandbox_deliver"];
-/** 组织设置 `sandboxToolPolicy` 为 `ask` 时需要审批的沙箱工具（只读的 read / glob / grep 除外）。 */
-export declare const SANDBOX_ASK_TOOL_NAMES: ReadonlySet<string>;

package/dist/tools/builtins/sandbox/names.js

@@ -1,20 +0,0 @@
-/**
- * 沙箱内置工具的名字（M5 T8，Ruling M12：工具 key 只能含字母数字、`_`、`-`，所以是 `sandbox_<动作>`）。
- * 单独成文件：注册表与策略判定只需要名字，不引入工具实现。
- */
-export const SANDBOX_TOOL_NAMES = [
-    "sandbox_bash",
-    "sandbox_read",
-    "sandbox_write",
-    "sandbox_edit",
-    "sandbox_glob",
-    "sandbox_grep",
-    "sandbox_deliver",
-];
-/** 组织设置 `sandboxToolPolicy` 为 `ask` 时需要审批的沙箱工具（只读的 read / glob / grep 除外）。 */
-export const SANDBOX_ASK_TOOL_NAMES = new Set([
-    "sandbox_bash",
-    "sandbox_write",
-    "sandbox_edit",
-    "sandbox_deliver",
-]);