@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

package/src/migrations/0003_identity.sql

@@ -0,0 +1,117 @@
+CREATE TABLE IF NOT EXISTS capybara.accounts (
+  id text PRIMARY KEY,
+  display_name text NOT NULL,
+  email text,
+  email_verified boolean NOT NULL DEFAULT false,
+  status text NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'disabled')),
+  is_enterprise_admin boolean NOT NULL DEFAULT false,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS capybara.identities (
+  source text NOT NULL,
+  external_id text NOT NULL,
+  account_id text NOT NULL REFERENCES capybara.accounts(id) ON DELETE CASCADE,
+  email text,
+  email_verified boolean NOT NULL DEFAULT false,
+  profile jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (source, external_id)
+);
+CREATE INDEX IF NOT EXISTS identities_account_idx ON capybara.identities (account_id);
+CREATE TABLE IF NOT EXISTS capybara.local_passwords (
+  account_id text PRIMARY KEY REFERENCES capybara.accounts(id) ON DELETE CASCADE,
+  password_hash text NOT NULL,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS capybara.orgs (
+  id text PRIMARY KEY,
+  slug text NOT NULL,
+  name text NOT NULL,
+  created_by text REFERENCES capybara.accounts(id),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  deleted_at timestamptz
+);
+CREATE UNIQUE INDEX IF NOT EXISTS orgs_slug_live_uq ON capybara.orgs (slug) WHERE deleted_at IS NULL;
+CREATE TABLE IF NOT EXISTS capybara.memberships (
+  org_id text NOT NULL REFERENCES capybara.orgs(id) ON DELETE CASCADE,
+  account_id text NOT NULL REFERENCES capybara.accounts(id) ON DELETE CASCADE,
+  role text NOT NULL CHECK (role IN ('owner', 'admin', 'member', 'guest')),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (org_id, account_id)
+);
+CREATE INDEX IF NOT EXISTS memberships_account_idx ON capybara.memberships (account_id);
+CREATE TABLE IF NOT EXISTS capybara.invitations (
+  id text PRIMARY KEY,
+  org_id text NOT NULL REFERENCES capybara.orgs(id) ON DELETE CASCADE,
+  role text NOT NULL CHECK (role IN ('admin', 'member', 'guest')),
+  token_hash text NOT NULL UNIQUE,
+  created_by text NOT NULL REFERENCES capybara.accounts(id),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  expires_at timestamptz NOT NULL,
+  accepted_at timestamptz,
+  accepted_by text REFERENCES capybara.accounts(id),
+  revoked_at timestamptz
+);
+CREATE INDEX IF NOT EXISTS invitations_org_idx ON capybara.invitations (org_id);
+CREATE TABLE IF NOT EXISTS capybara.sessions (
+  id text PRIMARY KEY,
+  account_id text NOT NULL REFERENCES capybara.accounts(id) ON DELETE CASCADE,
+  current_org_id text REFERENCES capybara.orgs(id) ON DELETE SET NULL,
+  refresh_hash text NOT NULL UNIQUE,
+  prev_refresh_hash text,
+  rotated_at timestamptz,
+  user_agent text,
+  ip text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  last_used_at timestamptz NOT NULL DEFAULT now(),
+  expires_at timestamptz NOT NULL,
+  revoked_at timestamptz
+);
+CREATE INDEX IF NOT EXISTS sessions_account_idx ON capybara.sessions (account_id);
+CREATE INDEX IF NOT EXISTS sessions_prev_refresh_idx ON capybara.sessions (prev_refresh_hash);
+CREATE TABLE IF NOT EXISTS capybara.api_tokens (
+  id text PRIMARY KEY,
+  kind text NOT NULL CHECK (kind IN ('personal', 'service')),
+  account_id text REFERENCES capybara.accounts(id) ON DELETE CASCADE,
+  org_id text REFERENCES capybara.orgs(id) ON DELETE CASCADE,
+  role text CHECK (role IN ('admin', 'member', 'guest')),
+  name text NOT NULL,
+  token_hash text NOT NULL UNIQUE,
+  created_by text NOT NULL REFERENCES capybara.accounts(id),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  last_used_at timestamptz,
+  expires_at timestamptz,
+  revoked_at timestamptz,
+  CHECK (
+    (kind = 'personal' AND account_id IS NOT NULL AND org_id IS NULL AND role IS NULL)
+    OR (kind = 'service' AND account_id IS NULL AND org_id IS NOT NULL AND role IS NOT NULL)
+  )
+);
+CREATE TABLE IF NOT EXISTS capybara.deployment_settings (
+  key text PRIMARY KEY,
+  value jsonb NOT NULL,
+  updated_by text REFERENCES capybara.accounts(id),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS capybara.plugin_org_configs (
+  plugin text NOT NULL,
+  org_id text NOT NULL REFERENCES capybara.orgs(id) ON DELETE CASCADE,
+  enabled boolean NOT NULL DEFAULT false,
+  config jsonb NOT NULL DEFAULT '{}'::jsonb,
+  updated_by text REFERENCES capybara.accounts(id),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (plugin, org_id)
+);
+CREATE TABLE IF NOT EXISTS capybara.audit_events (
+  id bigserial PRIMARY KEY,
+  at timestamptz NOT NULL DEFAULT now(),
+  actor_account_id text,
+  actor_token_id text,
+  org_id text,
+  action text NOT NULL,
+  target text,
+  detail jsonb NOT NULL DEFAULT '{}'::jsonb
+);
+CREATE INDEX IF NOT EXISTS audit_events_org_at_idx ON capybara.audit_events (org_id, at DESC);

package/src/migrations/0004_plugin_org_config_nullable.sql

@@ -0,0 +1,3 @@
+-- 插件组织配置：没有配置时存 NULL（而不是 '{}'），区分「从未配置」与「配置为空对象」。
+ALTER TABLE plugin_org_configs ALTER COLUMN config DROP NOT NULL;
+ALTER TABLE plugin_org_configs ALTER COLUMN config DROP DEFAULT;

package/src/migrations/0005_agents.sql

@@ -0,0 +1,27 @@
+-- Agent 定义与版本：agents 为当前元数据，agent_versions 只追加（定义每变化一次一个版本），agent_members 为 visibility='members' 的名单。
+CREATE TABLE IF NOT EXISTS capybara.agents (
+  id text PRIMARY KEY,
+  org_id text NOT NULL REFERENCES capybara.orgs(id) ON DELETE CASCADE,
+  owner_account_id text NOT NULL REFERENCES capybara.accounts(id),
+  visibility text NOT NULL CHECK (visibility IN ('private', 'org', 'members')),
+  org_role text NOT NULL DEFAULT 'member' CHECK (org_role IN ('admin', 'member', 'guest')),
+  current_version integer NOT NULL,
+  needs_reassignment boolean NOT NULL DEFAULT false,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  deleted_at timestamptz
+);
+CREATE INDEX IF NOT EXISTS agents_org_idx ON capybara.agents (org_id) WHERE deleted_at IS NULL;
+CREATE TABLE IF NOT EXISTS capybara.agent_versions (
+  agent_id text NOT NULL REFERENCES capybara.agents(id) ON DELETE CASCADE,
+  version integer NOT NULL,
+  definition jsonb NOT NULL,
+  created_by text NOT NULL REFERENCES capybara.accounts(id),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (agent_id, version)
+);
+CREATE TABLE IF NOT EXISTS capybara.agent_members (
+  agent_id text NOT NULL REFERENCES capybara.agents(id) ON DELETE CASCADE,
+  account_id text NOT NULL REFERENCES capybara.accounts(id) ON DELETE CASCADE,
+  PRIMARY KEY (agent_id, account_id)
+);

package/src/migrations/0006_conversations.sql

@@ -0,0 +1,37 @@
+-- 会话与事件日志：conversation_events 只追加，是 agent 运行的唯一事实来源；seq 由 conversations.last_seq 在行锁内连续分配。
+-- runs 记录每次运行的状态（运行流水线在后续任务接入）。
+CREATE TABLE IF NOT EXISTS capybara.conversations (
+  id text PRIMARY KEY,
+  org_id text NOT NULL REFERENCES capybara.orgs(id) ON DELETE CASCADE,
+  agent_id text NOT NULL REFERENCES capybara.agents(id),
+  account_id text NOT NULL REFERENCES capybara.accounts(id),
+  title text,
+  last_seq bigint NOT NULL DEFAULT 0,
+  consumed_seq bigint NOT NULL DEFAULT 0,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS conversations_account_idx ON capybara.conversations (org_id, account_id, updated_at DESC);
+CREATE TABLE IF NOT EXISTS capybara.conversation_events (
+  conversation_id text NOT NULL REFERENCES capybara.conversations(id) ON DELETE CASCADE,
+  seq bigint NOT NULL,
+  type text NOT NULL,
+  run_id text,
+  idem_key text,
+  payload jsonb NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (conversation_id, seq)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS conversation_events_idem_uq
+  ON capybara.conversation_events (conversation_id, idem_key) WHERE idem_key IS NOT NULL;
+CREATE TABLE IF NOT EXISTS capybara.runs (
+  id text PRIMARY KEY,
+  conversation_id text NOT NULL REFERENCES capybara.conversations(id) ON DELETE CASCADE,
+  status text NOT NULL CHECK (status IN ('queued', 'running', 'completed', 'failed', 'aborted')),
+  agent_version integer NOT NULL,
+  trigger_account_id text NOT NULL REFERENCES capybara.accounts(id),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  started_at timestamptz,
+  finished_at timestamptz
+);
+CREATE INDEX IF NOT EXISTS runs_conversation_idx ON capybara.runs (conversation_id, created_at DESC);

package/src/migrations/0007_checkpoints.sql

@@ -0,0 +1,26 @@
+-- LangGraph checkpoint 存储（KyselyCheckpointSaver）：thread_id 约定为 runId；checkpoint / metadata / value
+-- 为 serde.dumpsTyped 的字节，*_type 为其类型标记。运行结束后 pruneToLatest 只保留根命名空间最新一份。
+CREATE TABLE IF NOT EXISTS capybara.lg_checkpoints (
+  thread_id text NOT NULL,
+  checkpoint_ns text NOT NULL DEFAULT '',
+  checkpoint_id text NOT NULL,
+  parent_checkpoint_id text,
+  checkpoint_type text NOT NULL,
+  checkpoint bytea NOT NULL,
+  metadata_type text NOT NULL,
+  metadata bytea NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id)
+);
+CREATE TABLE IF NOT EXISTS capybara.lg_checkpoint_writes (
+  thread_id text NOT NULL,
+  checkpoint_ns text NOT NULL DEFAULT '',
+  checkpoint_id text NOT NULL,
+  task_id text NOT NULL,
+  idx integer NOT NULL,
+  channel text NOT NULL,
+  value_type text NOT NULL,
+  value bytea NOT NULL,
+  task_path text NOT NULL DEFAULT '',
+  PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id, task_id, idx)
+);

package/src/migrations/0008_runs_trigger_seq.sql

@@ -0,0 +1,3 @@
+-- runs.trigger_seq：创建该运行时最新 user_message 的 seq（投递点）。运行以任何终态结束时 consumed_seq
+-- 至少推进到它，触发消息不会因运行失败 / 中止 / 超时而被无限重试，会话也不会卡住。
+ALTER TABLE capybara.runs ADD COLUMN IF NOT EXISTS trigger_seq bigint NOT NULL DEFAULT 0;

package/src/migrations/0009_runs_active_unique.sql

@@ -0,0 +1,4 @@
+-- 同一会话同一时刻至多一个未结束（queued / running）的运行：RunQueue.ensureRun 已在会话行锁内检查，
+-- 这里再由数据库兜底，任何代码路径都不可能插入第二个活跃运行。
+CREATE UNIQUE INDEX IF NOT EXISTS runs_one_active_per_conversation
+  ON capybara.runs (conversation_id) WHERE status IN ('queued', 'running');

package/src/migrations/0010_tools.sql

@@ -0,0 +1,125 @@
+-- 工具与连接器（M3）：应用、应用工具、授权、审批、提问、工具输出存档；runs 增加 waiting 状态；orgs.settings。
+
+-- 已安装的应用（一个连接器实例）。auth 只存 {type, ownership, ...非密钥字段}，凭据在 capybara.secrets。
+CREATE TABLE IF NOT EXISTS capybara.apps (
+  id text PRIMARY KEY,
+  org_id text NOT NULL REFERENCES capybara.orgs(id) ON DELETE CASCADE,
+  slug text NOT NULL,
+  name text NOT NULL,
+  connector text NOT NULL,
+  endpoint jsonb NOT NULL DEFAULT '{}'::jsonb,
+  auth jsonb NOT NULL DEFAULT '{}'::jsonb,
+  status text NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'disabled')),
+  created_by text NOT NULL REFERENCES capybara.accounts(id),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  deleted_at timestamptz
+);
+CREATE UNIQUE INDEX IF NOT EXISTS apps_org_slug_uniq
+  ON capybara.apps (org_id, slug) WHERE deleted_at IS NULL;
+
+-- 应用暴露的工具；spec_hash 变化后回到 pending_review，由管理员重新审阅。
+CREATE TABLE IF NOT EXISTS capybara.app_tools (
+  app_id text NOT NULL REFERENCES capybara.apps(id) ON DELETE CASCADE,
+  name text NOT NULL,
+  spec jsonb NOT NULL,
+  spec_hash text NOT NULL,
+  status text NOT NULL CHECK (status IN ('enabled', 'disabled', 'pending_review')),
+  default_policy text NOT NULL CHECK (default_policy IN ('allow', 'ask', 'deny')),
+  reviewed_at timestamptz,
+  PRIMARY KEY (app_id, name)
+);
+
+-- 「以后都允许」：按 (账号, agent, 工具) 记住，spec_hash 变化后失效。
+-- app_id：应用工具的来源应用（插件 / 内置工具为空）；授权只对同一个应用有效——删除后用同一 slug
+-- 重新安装的应用 id 不同，不继承旧授权。应用是软删除，不用外键级联（删除应用时由代码清掉其授权）。
+CREATE TABLE IF NOT EXISTS capybara.tool_grants (
+  org_id text NOT NULL REFERENCES capybara.orgs(id) ON DELETE CASCADE,
+  account_id text NOT NULL REFERENCES capybara.accounts(id) ON DELETE CASCADE,
+  agent_id text NOT NULL REFERENCES capybara.agents(id) ON DELETE CASCADE,
+  tool_key text NOT NULL,
+  spec_hash text NOT NULL,
+  app_id text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (org_id, account_id, agent_id, tool_key)
+);
+
+-- 「本会话都允许」；app_id 同上。
+CREATE TABLE IF NOT EXISTS capybara.conversation_tool_grants (
+  conversation_id text NOT NULL REFERENCES capybara.conversations(id) ON DELETE CASCADE,
+  tool_key text NOT NULL,
+  spec_hash text NOT NULL,
+  app_id text,
+  PRIMARY KEY (conversation_id, tool_key)
+);
+
+-- 工具调用审批。requested_for（指定账号）与 approver_role（指定角色）至少一个非空。
+CREATE TABLE IF NOT EXISTS capybara.approvals (
+  id text PRIMARY KEY,
+  org_id text NOT NULL REFERENCES capybara.orgs(id) ON DELETE CASCADE,
+  conversation_id text NOT NULL REFERENCES capybara.conversations(id) ON DELETE CASCADE,
+  run_id text NOT NULL REFERENCES capybara.runs(id) ON DELETE CASCADE,
+  call_id text NOT NULL,
+  tool_key text NOT NULL,
+  input jsonb NOT NULL DEFAULT '{}'::jsonb,
+  -- 指定处理人的账号被删除时审批一并删除：SET NULL 会让只指定了处理人的行违反 approvals_target_chk，
+  -- 删除账号失败；这类审批只有那个人能处理，人不在了审批也没有意义（等待中的运行由超时收尾）。
+  requested_for text REFERENCES capybara.accounts(id) ON DELETE CASCADE,
+  approver_role text,
+  status text NOT NULL DEFAULT 'pending'
+    CHECK (status IN ('pending', 'approved', 'denied', 'expired', 'cancelled')),
+  scope text CHECK (scope IS NULL OR scope IN ('once', 'session', 'always')),
+  decided_by text REFERENCES capybara.accounts(id) ON DELETE SET NULL,
+  decided_at timestamptz,
+  expires_at timestamptz NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT approvals_run_call_uniq UNIQUE (run_id, call_id),
+  CONSTRAINT approvals_target_chk CHECK (requested_for IS NOT NULL OR approver_role IS NOT NULL)
+);
+CREATE INDEX IF NOT EXISTS approvals_pending_for_idx
+  ON capybara.approvals (requested_for) WHERE status = 'pending';
+
+-- ask_user 提问。
+CREATE TABLE IF NOT EXISTS capybara.questions (
+  id text PRIMARY KEY,
+  org_id text NOT NULL REFERENCES capybara.orgs(id) ON DELETE CASCADE,
+  conversation_id text NOT NULL REFERENCES capybara.conversations(id) ON DELETE CASCADE,
+  run_id text NOT NULL REFERENCES capybara.runs(id) ON DELETE CASCADE,
+  call_id text NOT NULL,
+  spec jsonb NOT NULL,
+  status text NOT NULL DEFAULT 'pending'
+    CHECK (status IN ('pending', 'answered', 'expired', 'cancelled')),
+  answer jsonb,
+  answered_by text REFERENCES capybara.accounts(id) ON DELETE SET NULL,
+  answered_at timestamptz,
+  expires_at timestamptz NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT questions_run_call_uniq UNIQUE (run_id, call_id)
+);
+
+-- 超大工具输出的存档（read_tool_output 读取），到期清理。
+CREATE TABLE IF NOT EXISTS capybara.tool_outputs (
+  id text PRIMARY KEY,
+  org_id text NOT NULL REFERENCES capybara.orgs(id) ON DELETE CASCADE,
+  conversation_id text NOT NULL REFERENCES capybara.conversations(id) ON DELETE CASCADE,
+  call_id text NOT NULL,
+  size_chars integer NOT NULL,
+  line_count integer NOT NULL,
+  content text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  expires_at timestamptz NOT NULL
+);
+CREATE INDEX IF NOT EXISTS tool_outputs_expires_idx ON capybara.tool_outputs (expires_at);
+
+-- runs 增加 waiting（等待审批 / 回答）；约束名为 PG 对 0006 内联 CHECK 的默认命名。
+ALTER TABLE capybara.runs DROP CONSTRAINT IF EXISTS runs_status_check;
+ALTER TABLE capybara.runs ADD CONSTRAINT runs_status_check
+  CHECK (status IN ('queued', 'running', 'waiting', 'completed', 'failed', 'aborted'));
+
+-- 每会话至多一个活动运行：waiting 也算活动。
+DROP INDEX IF EXISTS capybara.runs_one_active_per_conversation;
+CREATE UNIQUE INDEX IF NOT EXISTS runs_one_active_per_conversation
+  ON capybara.runs (conversation_id) WHERE status IN ('queued', 'running', 'waiting');
+
+-- 组织级设置（如工具策略）。
+ALTER TABLE capybara.orgs ADD COLUMN IF NOT EXISTS settings jsonb NOT NULL DEFAULT '{}'::jsonb;

package/src/migrations/0011_approvals_spec.sql

@@ -0,0 +1,10 @@
+-- 审批记录所批准的工具定义：spec_hash 用于写「本会话 / 以后都允许」授权（定义变化后授权失效）；
+-- app_id 为应用工具的来源应用（详情展示用，插件 / 内置工具为空）。
+-- 必填：approvals 是本版本（0010）新建的表，尚无数据，可直接加 NOT NULL 列。
+ALTER TABLE capybara.approvals ADD COLUMN IF NOT EXISTS spec_hash text NOT NULL;
+ALTER TABLE capybara.approvals ADD COLUMN IF NOT EXISTS app_id text
+  REFERENCES capybara.apps(id) ON DELETE SET NULL;
+
+-- 按角色升级的待处理审批（列表查询用）。
+CREATE INDEX IF NOT EXISTS approvals_pending_role_idx
+  ON capybara.approvals (org_id, approver_role) WHERE status = 'pending' AND approver_role IS NOT NULL;

package/src/migrations/0012_run_waits.sql

@@ -0,0 +1,24 @@
+-- 运行等待人处理（审批 / 输入请求）时暂停、处理后续跑。
+
+-- 进入 waiting 的时刻；续跑时把等待时长累加进 waited_ms 并清空。
+ALTER TABLE runs ADD COLUMN IF NOT EXISTS waiting_since timestamptz;
+-- 累计等待时长（毫秒）：运行截止时间 = started_at + waited_ms + maxRunSeconds，等人不计入运行时长。
+ALTER TABLE runs ADD COLUMN IF NOT EXISTS waited_ms bigint NOT NULL DEFAULT 0;
+-- 续跑任务的 jobId（`run-<conversationId>-resume-<waitId>`）；为空表示按触发消息生成的 jobId。孤儿判定用它查任务。
+ALTER TABLE runs ADD COLUMN IF NOT EXISTS job_id text;
+-- 最近一次回到 queued 的时刻（续跑）；孤儿判定的宽限期从它起算（为空时用 created_at）。
+ALTER TABLE runs ADD COLUMN IF NOT EXISTS queued_at timestamptz;
+
+-- 同一工具调用可以连续请求输入（最多 3 轮）：每轮一行，按 attempt 区分。
+ALTER TABLE questions ADD COLUMN IF NOT EXISTS attempt integer NOT NULL DEFAULT 1;
+CREATE UNIQUE INDEX IF NOT EXISTS questions_run_call_attempt_uniq
+  ON questions (run_id, call_id, attempt);
+-- 0010 的 (run_id, call_id) 唯一约束改由上面的唯一索引取代（questions 表在本版本新建，尚无代码依赖旧约束）。
+ALTER TABLE questions DROP CONSTRAINT IF EXISTS questions_run_call_uniq;
+
+-- 同一工具调用可能需要再次审批（等待期间工具定义变了，原批准不再适用）：每次审批一行，按 attempt 区分。
+ALTER TABLE approvals ADD COLUMN IF NOT EXISTS attempt integer NOT NULL DEFAULT 1;
+CREATE UNIQUE INDEX IF NOT EXISTS approvals_run_call_attempt_uniq
+  ON approvals (run_id, call_id, attempt);
+-- 0010 的 (run_id, call_id) 唯一约束改由上面的唯一索引取代（approvals 表在本版本新建，尚无代码依赖旧约束）。
+ALTER TABLE approvals DROP CONSTRAINT IF EXISTS approvals_run_call_uniq;

package/src/migrations/0013_app_tools_source.sql

@@ -0,0 +1,4 @@
+-- 应用工具的来源：connector = 连接器 listTools 返回的工具；resources = 应用支持 resources 时内核补上的
+-- list_resources / read_resource 两个工具（执行时路由到会话的 listResources / readResource）。
+ALTER TABLE capybara.app_tools ADD COLUMN IF NOT EXISTS source text NOT NULL DEFAULT 'connector'
+  CHECK (source IN ('connector', 'resources'));

package/src/migrations/0014_tool_specs.sql

@@ -0,0 +1,8 @@
+-- 工具定义快照（内容寻址）：model_call 只记 {key, specHash}，定义本身按指纹存这里，只增不改。
+-- 应用刷新、插件升级改了定义之后，早先 model_call 用过的定义仍可按指纹取回，模型请求可由日志还原。
+-- spec 为 ToolSpec（name 为来源内的原名；模型可见名是 model_call 里的 key）。
+CREATE TABLE IF NOT EXISTS tool_specs (
+  spec_hash text PRIMARY KEY,
+  spec jsonb NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now()
+);

package/src/migrations/0015_tool_drift.sql

@@ -0,0 +1,20 @@
+-- 工具定义漂移检测与复核（spec 7.3）：新增 / 变化的工具在管理员复核前不可用。
+
+-- 变化后待复核的新定义（复核前 spec / spec_hash / source 仍是上次复核通过的定义，供对比；通过后采用这里的）。
+ALTER TABLE capybara.app_tools ADD COLUMN IF NOT EXISTS pending_spec jsonb;
+ALTER TABLE capybara.app_tools ADD COLUMN IF NOT EXISTS pending_spec_hash text;
+ALTER TABLE capybara.app_tools ADD COLUMN IF NOT EXISTS pending_source text
+  CHECK (pending_source IS NULL OR pending_source IN ('connector', 'resources'));
+-- 默认策略的来历：derived = 按注解推导（定义变化复核通过后重新推导）；admin = 管理员设定（保留）。
+ALTER TABLE capybara.app_tools ADD COLUMN IF NOT EXISTS policy_source text NOT NULL DEFAULT 'derived'
+  CHECK (policy_source IN ('derived', 'admin'));
+-- 远端不再提供该工具的时间（工具随之停用，行保留）；又出现时清空并按新增处理（待复核）。
+ALTER TABLE capybara.app_tools ADD COLUMN IF NOT EXISTS missing_since timestamptz;
+
+-- 最近一次成功拿到工具清单（安装 / 刷新 / 漂移检查）的时间。为空 = 从未拍过快照（OAuth 授权码应用安装时
+-- 不 listTools，A16）：首个快照按安装处理（直接启用）。定时扫描据此跳过本周期内已检查过的应用。
+ALTER TABLE capybara.apps ADD COLUMN IF NOT EXISTS tools_synced_at timestamptz;
+UPDATE capybara.apps SET tools_synced_at = updated_at
+  WHERE tools_synced_at IS NULL
+    AND (auth->>'type' IS DISTINCT FROM 'oauth_code'
+      OR EXISTS (SELECT 1 FROM capybara.app_tools t WHERE t.app_id = apps.id));

package/src/migrations/0016_plugin_permissions.sql

@@ -0,0 +1,11 @@
+-- 插件已批准的权限快照（扩展模型 7.3）：插件首次出现或升级后清单比快照多出任何一项时不加载，待批准。
+-- permissions = 规范化的权限集合（computePermissionSet）；source：cli = 管理员经 CLI 批准，auto = autoApprove 自动写入。
+-- approved_by 为批准人账号 id（CLI 与自动批准没有账号，为空）。
+CREATE TABLE IF NOT EXISTS capybara.plugin_permission_snapshots (
+  plugin text PRIMARY KEY,
+  version text NOT NULL,
+  permissions jsonb NOT NULL,
+  approved_by text,
+  approved_at timestamptz NOT NULL DEFAULT now(),
+  source text NOT NULL CHECK (source IN ('cli', 'auto'))
+);

package/src/migrations/0017_identity_sources.sql

@@ -0,0 +1,6 @@
+-- 外部身份（M4）：成员关系的来源。NULL = 手动加入 / 凭邀请；"directory:<插件名>" = 通讯录同步加入
+-- （通讯录同步只撤销由它自己加入的成员关系）。
+ALTER TABLE capybara.memberships ADD COLUMN IF NOT EXISTS source text;
+-- 第三方登录按已验证邮箱合并时按 lower(email) 查找账号。
+CREATE INDEX IF NOT EXISTS accounts_verified_email_idx
+  ON capybara.accounts (lower(email)) WHERE email_verified;

package/src/migrations/0018_channels.sql

@@ -0,0 +1,74 @@
+-- 渠道（M4）：组织拥有的渠道连接（bot 凭据 + 绑定的 agent）、IM 话题 ↔ 会话映射、出站投递进度（Task 11），
+-- 以及每个组织一个的匿名访客账号。连接配置里的密钥字段不在这里，存 capybara.secrets（kernel / channels:<id>:config）。
+CREATE TABLE IF NOT EXISTS capybara.channel_connections (
+  id text PRIMARY KEY,
+  org_id text NOT NULL REFERENCES capybara.orgs(id) ON DELETE CASCADE,
+  plugin text NOT NULL,
+  name text NOT NULL,
+  agent_id text NOT NULL REFERENCES capybara.agents(id),
+  config jsonb NOT NULL DEFAULT '{}'::jsonb,
+  unbound_policy text NOT NULL DEFAULT 'bind' CHECK (unbound_policy IN ('bind', 'anonymous')),
+  status text NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'disabled', 'error')),
+  last_error text,
+  bot_user_id text,
+  tenant_id text,
+  created_by text NOT NULL REFERENCES capybara.accounts(id),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  deleted_at timestamptz
+);
+CREATE INDEX IF NOT EXISTS channel_connections_org_idx
+  ON capybara.channel_connections (org_id) WHERE deleted_at IS NULL;
+CREATE INDEX IF NOT EXISTS channel_connections_active_idx
+  ON capybara.channel_connections (id) WHERE status = 'active' AND deleted_at IS NULL;
+-- 私聊 thread_key = 'dm:<externalId>'，群聊 = 平台话题 id（新话题用起始消息 id）；匿名访客 account_id 为 NULL。
+-- 私聊 /new 把当前行标记 archived_at 后新建，所以唯一性只约束未归档的行（部分唯一索引）。
+CREATE TABLE IF NOT EXISTS capybara.channel_threads (
+  id text PRIMARY KEY,
+  connection_id text NOT NULL REFERENCES capybara.channel_connections(id) ON DELETE CASCADE,
+  chat_id text NOT NULL,
+  thread_key text NOT NULL,
+  account_id text REFERENCES capybara.accounts(id) ON DELETE CASCADE,
+  conversation_id text NOT NULL REFERENCES capybara.conversations(id) ON DELETE CASCADE,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  archived_at timestamptz
+);
+CREATE UNIQUE INDEX IF NOT EXISTS channel_threads_live_uq
+  ON capybara.channel_threads (connection_id, chat_id, thread_key, coalesce(account_id::text, ''))
+  WHERE archived_at IS NULL;
+CREATE INDEX IF NOT EXISTS channel_threads_conversation_idx
+  ON capybara.channel_threads (conversation_id);
+-- 会话的 IM 投递目标与已投递到的事件序号（Task 11 的出站投递按 last_seq 续投）。
+CREATE TABLE IF NOT EXISTS capybara.channel_deliveries (
+  conversation_id text PRIMARY KEY REFERENCES capybara.conversations(id) ON DELETE CASCADE,
+  connection_id text NOT NULL REFERENCES capybara.channel_connections(id) ON DELETE CASCADE,
+  target jsonb NOT NULL,
+  last_seq bigint NOT NULL DEFAULT 0,
+  draft_message_id text,
+  -- 不可重试的发送失败落在哪个事件、连续失败几次（同一事件失败 3 次即跳过，见 channels/outbound.ts）
+  fail_seq bigint,
+  fail_count integer NOT NULL DEFAULT 0,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS channel_deliveries_connection_idx
+  ON capybara.channel_deliveries (connection_id);
+-- 每个组织一个匿名访客账号（无登录方式，组织角色 guest），渠道连接开启匿名策略时首次使用才创建。
+CREATE TABLE IF NOT EXISTS capybara.org_anonymous_accounts (
+  org_id text PRIMARY KEY REFERENCES capybara.orgs(id) ON DELETE CASCADE,
+  account_id text NOT NULL UNIQUE REFERENCES capybara.accounts(id) ON DELETE CASCADE,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+-- 出站投递发出的审批 / 提问卡片对应的 IM 消息（Task 11）：approval_decided / question_answered 到达时据此更新卡片，
+-- 崩溃后由其他副本续投时同样能找到。每个 (会话, 连接, 卡片) 只记一条。
+CREATE TABLE IF NOT EXISTS capybara.channel_card_messages (
+  conversation_id text NOT NULL REFERENCES capybara.conversations(id) ON DELETE CASCADE,
+  connection_id text NOT NULL REFERENCES capybara.channel_connections(id) ON DELETE CASCADE,
+  card_kind text NOT NULL CHECK (card_kind IN ('approval', 'question')),
+  card_id text NOT NULL,
+  message_id text NOT NULL,
+  target jsonb NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (conversation_id, connection_id, card_kind, card_id)
+);
+CREATE INDEX IF NOT EXISTS channel_card_messages_connection_idx
+  ON capybara.channel_card_messages (connection_id);

package/src/migrations/0019_identity_trust.sql

@@ -0,0 +1,17 @@
+-- 第一段修复波 W1（Ruling A18 / A20）。
+-- 身份行是怎么建立的：bind = IM 里点绑定链接确认（只证明网页登录者点了链接，不证明他控制该 IM 身份），
+-- sso = 第三方登录，directory = 通讯录同步，local = 本地登录名。NULL 为此前的旧行，按 sso 处理。
+-- 第三方登录拒绝 bind（以及不受信任租户的 directory）身份，除非本人已登录同一账号（此时升级为 sso）。
+ALTER TABLE capybara.identities ADD COLUMN IF NOT EXISTS linked_via text
+  CHECK (linked_via IN ('bind', 'sso', 'directory', 'local'));
+UPDATE capybara.identities SET linked_via = 'local' WHERE source = 'local' AND linked_via IS NULL;
+-- 通讯录排除：管理员手动移出（或本人离开）由通讯录同步加入的成员后，同步不再把此人加回该组织，
+-- 直到有人手动重新加入（接受邀请等），届时删除这一行。
+CREATE TABLE IF NOT EXISTS capybara.directory_exclusions (
+  org_id text NOT NULL REFERENCES capybara.orgs(id) ON DELETE CASCADE,
+  account_id text NOT NULL REFERENCES capybara.accounts(id) ON DELETE CASCADE,
+  plugin text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  created_by text REFERENCES capybara.accounts(id) ON DELETE SET NULL,
+  PRIMARY KEY (org_id, account_id, plugin)
+);

package/src/migrations/0020_channel_card_lookup.sql

@@ -0,0 +1,10 @@
+-- 第一段修复波 W2。
+-- 卡片操作按 (连接, 卡片类型, 卡片 id) 找发出的卡片消息（channels/actions.ts，Ruling A13）；主键以会话打头用不上。
+-- 卡片 id 是审批 / 提问 id（全局唯一，只属于一个会话），所以这三列本身唯一。
+CREATE UNIQUE INDEX IF NOT EXISTS channel_card_messages_lookup_uq
+  ON capybara.channel_card_messages (connection_id, card_kind, card_id);
+-- 通讯录排除（0019）的外键列：删除账号时的级联 / 置空按它们查找。
+CREATE INDEX IF NOT EXISTS directory_exclusions_account_idx
+  ON capybara.directory_exclusions (account_id);
+CREATE INDEX IF NOT EXISTS directory_exclusions_created_by_idx
+  ON capybara.directory_exclusions (created_by);

package/src/migrations/0021_org_storage_purge.sql

@@ -0,0 +1,9 @@
+-- M5 T2：组织软删除后，维护任务按 storage.purgeDeletedOrgsAfterDays 清理其对象存储（storage/purge.ts）。
+-- storage_purged_at 记录已清理的时间，之后不再处理该组织。
+-- storage_purge_claimed_at 是某次运行的认领时间：认领在短事务里完成，删除对象在事务外进行；
+-- 认领超时（运行中途退出）后可被重新认领。
+ALTER TABLE orgs ADD COLUMN IF NOT EXISTS storage_purged_at timestamptz;
+ALTER TABLE orgs ADD COLUMN IF NOT EXISTS storage_purge_claimed_at timestamptz;
+CREATE INDEX IF NOT EXISTS orgs_storage_purge_pending_idx
+  ON orgs (deleted_at)
+  WHERE deleted_at IS NOT NULL AND storage_purged_at IS NULL;

package/src/migrations/0022_attachments.sql

@@ -0,0 +1,29 @@
+-- M5 T3：对话附件（图片 / 文档）。字节在对象存储 kernel/<org_id>/attachments/<id>，这里只存元数据；
+-- 用户的文件名只在 name 列，不进对象键。
+-- status：pending（已登记、等浏览器直传并 finalize）→ ready（大小与类型已核对）；
+-- deleting 是清理任务的认领状态（删对象失败时下次重试）。
+-- conversation_id 在第一次被消息引用时绑定，之后不再变；未绑定的附件 expires_at 到期后由维护任务删除
+-- （对象一并删除），绑定后 expires_at 置空。
+CREATE TABLE IF NOT EXISTS attachments (
+  id text PRIMARY KEY,
+  org_id text NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  conversation_id text REFERENCES conversations(id) ON DELETE CASCADE,
+  account_id text NOT NULL REFERENCES accounts(id),
+  name text NOT NULL,
+  content_type text NOT NULL,
+  size bigint NOT NULL CHECK (size >= 0),
+  object_key text NOT NULL,
+  status text NOT NULL CHECK (status IN ('pending', 'ready', 'deleting')),
+  -- finalize 时记下的对象 etag：之后经同一预签名表单重传会改变 etag，取字节与下载时不符即视为不再可用
+  etag text,
+  -- PDF 的页数（finalize 时数出，用于 token 估算）；不是 PDF 或数不到为 NULL
+  pages integer,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  expires_at timestamptz
+);
+CREATE INDEX IF NOT EXISTS attachments_unbound_expiry_idx
+  ON attachments (expires_at)
+  WHERE conversation_id IS NULL;
+CREATE INDEX IF NOT EXISTS attachments_conversation_idx
+  ON attachments (conversation_id)
+  WHERE conversation_id IS NOT NULL;

package/src/migrations/0023_sandboxes.sql

@@ -0,0 +1,37 @@
+-- M5 T7：按对话的沙箱（sandbox@1 提供方的实例，见 sandbox/sandbox.service.ts）。每个对话至多一行。
+-- 创建、恢复、休眠、销毁都在 Redis 锁 capk:sandbox:<conversation_id> 下进行；空闲休眠与不活跃销毁由维护队列扫描。
+-- 不对 conversations / orgs 建外键：对话或组织删除后这一行要留着，直到维护任务销毁提供方那边的实例
+-- （否则实例会泄漏）；对话已不存在的行在销毁后删除。
+-- status：creating（正在创建，handle 为 NULL；创建失败或中途退出时停在这里，下次使用重新创建）
+--   → running ⇄ suspended → destroyed（销毁后保留 handle 备查，下次使用重建）。
+-- provider：创建它的插件名；与当前提供方不同时当作已不在，下次使用重建。
+-- running_since：本次连续运行的开始时间（创建或恢复时写，休眠时清空），用于超时强制休眠。
+-- generation：防护号。持锁方在锁内读到它，此后每次改 status / handle 都带 WHERE generation = 读到的值
+--   并加一；没有匹配行说明锁已丢失、别人改过，放弃。
+-- had_instance：曾经成功创建过实例（只会置 true，重置时不清）：之后的创建都算重建（recreated）。
+-- prev_provider / prev_handle：换了提供方时旧提供方的实例（新提供方销毁不了），旧提供方还加载时用它销毁后清空。
+-- sweep_failed_at：上次维护扫描处理它失败的时间（成功后清空）；扫描时排在后面，免得总卡在同一批。
+CREATE TABLE IF NOT EXISTS sandboxes (
+  conversation_id text PRIMARY KEY,
+  org_id text NOT NULL,
+  provider text NOT NULL,
+  handle jsonb,
+  status text NOT NULL CHECK (status IN ('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 sandboxes_running_idx
+  ON sandboxes (last_used_at)
+  WHERE status = 'running';
+CREATE INDEX IF NOT EXISTS sandboxes_live_idx
+  ON sandboxes (last_used_at)
+  WHERE status <> 'destroyed';
+CREATE INDEX IF NOT EXISTS sandboxes_org_idx ON sandboxes (org_id);