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

package/dist/tools/builtins/web/search.js

@@ -0,0 +1,209 @@
+import { domainToASCII } from "node:url";
+import { ToolError, } from "@capybara-hq/plugin-sdk";
+import { BUILTIN } from "../../builtin-names.js";
+import { webToolError } from "./errors.js";
+/** The extension point name (without the major) the provider is resolved from. */
+const POINT = "web-search";
+/**
+ * The fixed spec (web tools spec §3.1). No date and nothing per org or provider: `specHash` stays
+ * the same across days and providers, so remembered grants survive both and replays match the log.
+ * The date is the first line of every result instead.
+ */
+export const WEB_SEARCH_SPEC = {
+    name: BUILTIN.WebSearch,
+    // Display only (the tool row; not in the fingerprint, never sent to the model).
+    keyArgs: ["query"],
+    description: "Search the web and get a list of results with title, URL and a short snippet. Use it for " +
+        "information newer than your training data, or to check whether something you know is still " +
+        "current. Then use WebFetch to read the pages you need. Do not use it for questions you can " +
+        "answer reliably without the web. Cite the sources you use.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                minLength: 2,
+                maxLength: 500,
+                description: "The search query.",
+            },
+            allowed_domains: {
+                type: "array",
+                items: { type: "string", minLength: 1, maxLength: 253 },
+                maxItems: 50,
+                description: "Only return results from these domains (hostnames such as example.com; subdomains " +
+                    "are included). Do not combine with blocked_domains.",
+            },
+            blocked_domains: {
+                type: "array",
+                items: { type: "string", minLength: 1, maxLength: 253 },
+                maxItems: 50,
+                description: "Never return results from these domains (hostnames such as example.com; subdomains " +
+                    "are included). Do not combine with allowed_domains.",
+            },
+        },
+        required: ["query"],
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+};
+/** The last line of a result with entries (Claude Code tells the model to list its sources). */
+const CITE_LINE = "Cite the sources you use as markdown links in your answer.";
+/** Why the tool is unavailable in an org (web tools spec §3.4; English, actionable). */
+function unavailableText(reason) {
+    if (reason === "none") {
+        return "No web search provider is enabled in this organization; ask an org admin to enable one.";
+    }
+    return "Several web search providers are enabled and none is the default; ask an org admin to choose one in the organization settings.";
+}
+/**
+ * A domain entry as a bare lowercase ASCII hostname: tolerates a scheme, a path, a port, a leading
+ * `*.` / `.` and a trailing dot; a Unicode (IDN) name becomes its punycode form, as result hosts
+ * are (WHATWG URL parsing). Empty when nothing is left.
+ */
+function normalizeDomain(entry) {
+    let d = entry.trim().toLowerCase();
+    d = d.replace(/^[a-z][a-z0-9+.-]*:\/\//, "");
+    d = d.replace(/[/?#].*$/, "").replace(/:\d+$/, "");
+    d = d.replace(/^\*\./, "").replace(/^\.+/, "").replace(/\.+$/, "");
+    if (d === "")
+        return d;
+    // domainToASCII is "" for a name IDNA rejects: keep the entry as given (it matches no host)
+    return domainToASCII(d) || d;
+}
+/**
+ * A domain list normalized; undefined when absent or empty (no filter). A list whose entries all
+ * normalize to nothing stays an empty list, which no host matches.
+ */
+const normalizeDomains = (list) => list === undefined || list.length === 0
+    ? undefined
+    : [...new Set(list.map(normalizeDomain).filter((d) => d !== ""))];
+/** Whether `host` is `domain` or one of its subdomains. */
+const covers = (domain, host) => host === domain || host.endsWith(`.${domain}`);
+const oneLine = (s) => s.replace(/\s+/g, " ").trim();
+/**
+ * The provider's results the model may see (web tools spec §7.2): an absolute http(s) URL, a
+ * non-empty title, each URL once, within the domain lists, at most `max`. The kernel filters even
+ * when the provider honored the domain hints.
+ */
+function usable(results, allowed, blocked, max) {
+    const seen = new Set();
+    const out = [];
+    for (const r of results) {
+        if (out.length >= max)
+            break;
+        if (typeof r?.url !== "string" || typeof r.title !== "string")
+            continue;
+        const title = oneLine(r.title);
+        if (title === "")
+            continue;
+        let u;
+        try {
+            // no base: a relative URL throws
+            u = new URL(r.url.trim());
+        }
+        catch {
+            continue;
+        }
+        if (u.protocol !== "https:" && u.protocol !== "http:")
+            continue;
+        const host = u.hostname.toLowerCase().replace(/\.$/, "");
+        if (host === "")
+            continue;
+        if (allowed !== undefined && !allowed.some((d) => covers(d, host)))
+            continue;
+        if (blocked?.some((d) => covers(d, host)))
+            continue;
+        if (seen.has(u.href))
+            continue;
+        seen.add(u.href);
+        const date = typeof r.publishedAt === "string" ? /^\d{4}-\d{2}-\d{2}/.exec(r.publishedAt.trim()) : null;
+        const snippet = typeof r.snippet === "string" ? oneLine(r.snippet) : "";
+        out.push({
+            title,
+            url: u.href,
+            ...(date !== null && { date: date[0] }),
+            ...(snippet !== "" && { snippet }),
+        });
+    }
+    return out;
+}
+/** The model-visible result (web tools spec §3.1): the date line first, then the entries. */
+function resultText(day, entries) {
+    const head = `Search date: ${day} (UTC).`;
+    if (entries.length === 0)
+        return `${head}\n\nNo results.`;
+    const blocks = entries.map((e, i) => [
+        `${i + 1}. ${e.title}`,
+        `   URL: ${e.url}`,
+        ...(e.date !== undefined ? [`   Published: ${e.date}`] : []),
+        ...(e.snippet !== undefined ? [`   ${e.snippet}`] : []),
+    ].join("\n"));
+    return [head, ...blocks, CITE_LINE].join("\n\n");
+}
+/** The query in the display summary: one line, at most this many code points. */
+const DISPLAY_QUERY_MAX = 120;
+function displayQuery(query) {
+    const cps = [...oneLine(query)];
+    return cps.length > DISPLAY_QUERY_MAX
+        ? `${cps.slice(0, DISPLAY_QUERY_MAX - 1).join("")}…`
+        : cps.join("");
+}
+/**
+ * The builtin `WebSearch` (web tools spec §3.1): searches with the org's `web-search@1` provider
+ * (`ExtensionPointDefaults`, resolved per call and per step, never cached), asking it for
+ * `web.search.maxResults` results with the domain lists as hints and the org's config, then
+ * filters the results again. Default `ask`; unavailable when the org has no provider or several
+ * without a default.
+ */
+export function webSearchTool(deps) {
+    const now = deps.now ?? (() => new Date());
+    return {
+        spec: WEB_SEARCH_SPEC,
+        defaultPolicy: "ask",
+        async unavailable({ orgId }) {
+            const r = await deps.points.resolve(orgId, POINT);
+            return r.ok ? null : unavailableText(r.reason);
+        },
+        async run(input, ctx) {
+            const { query, allowed_domains, blocked_domains } = input;
+            if (allowed_domains !== undefined && blocked_domains !== undefined) {
+                throw new ToolError("Pass either allowed_domains or blocked_domains, not both; call WebSearch again with one of them.");
+            }
+            const allowed = normalizeDomains(allowed_domains);
+            const blocked = normalizeDomains(blocked_domains);
+            // the provider may have changed since the step resolved the tool: resolve again
+            const resolved = await deps.points.resolve(ctx.orgId, POINT);
+            if (!resolved.ok)
+                throw new ToolError(unavailableText(resolved.reason));
+            const max = deps.config.get().web.search.maxResults;
+            const day = now().toISOString().slice(0, 10);
+            let results;
+            try {
+                const out = await resolved.impl.search({
+                    query,
+                    ...(allowed !== undefined && allowed.length > 0 && { allowedDomains: allowed }),
+                    ...(blocked !== undefined && blocked.length > 0 && { blockedDomains: blocked }),
+                    maxResults: max,
+                    orgConfig: resolved.orgConfig,
+                    signal: ctx.signal,
+                });
+                results = Array.isArray(out?.results) ? out.results : [];
+            }
+            catch (e) {
+                webToolError(e, "search");
+            }
+            const entries = usable(results, allowed, blocked, max);
+            const q = displayQuery(query);
+            const n = entries.length;
+            return {
+                content: [{ type: "text", text: resultText(day, entries) }],
+                display: {
+                    summary: {
+                        zh: `搜索网页：${q}（${n} 条结果）`,
+                        en: `Searched the web: ${q} (${n} result${n === 1 ? "" : "s"})`,
+                    },
+                },
+            };
+        },
+    };
+}

package/dist/tools/builtins/web/url.d.ts

@@ -0,0 +1,17 @@
+/** The longest URL `WebFetch` accepts, in characters (Claude Code's limit; web tools spec §7.1). */
+export declare const MAX_FETCH_URL_CHARS = 2000;
+/** The outcome of {@link normalizeFetchUrl}: the URL to fetch, or a model-visible error. */
+export type FetchUrlCheck = {
+    ok: true;
+    url: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * A `WebFetch` URL checked and normalized (web tools spec §7.1): absolute http(s), `http:`
+ * upgraded to `https:`, no user name or password, at most {@link MAX_FETCH_URL_CHARS} characters
+ * (before and after normalization), and a host that can name a public internet host. Pure, no DNS: a public name that resolves to a
+ * private address is the provider's to refuse. Errors are English and tell the model what to pass.
+ */
+export declare function normalizeFetchUrl(raw: string): FetchUrlCheck;

package/dist/tools/builtins/web/url.js

@@ -0,0 +1,43 @@
+import { isPublicHostname } from "@capybara-hq/plugin-sdk";
+/** The longest URL `WebFetch` accepts, in characters (Claude Code's limit; web tools spec §7.1). */
+export const MAX_FETCH_URL_CHARS = 2000;
+const fail = (error) => ({ ok: false, error });
+/**
+ * A `WebFetch` URL checked and normalized (web tools spec §7.1): absolute http(s), `http:`
+ * upgraded to `https:`, no user name or password, at most {@link MAX_FETCH_URL_CHARS} characters
+ * (before and after normalization), and a host that can name a public internet host. Pure, no DNS: a public name that resolves to a
+ * private address is the provider's to refuse. Errors are English and tell the model what to pass.
+ */
+export function normalizeFetchUrl(raw) {
+    const input = raw.trim();
+    // a cheap guard before parsing; the normalized URL is checked again below
+    if (input.length > MAX_FETCH_URL_CHARS) {
+        return fail(`Pass a URL of at most ${MAX_FETCH_URL_CHARS} characters.`);
+    }
+    let u;
+    try {
+        // no base: a relative URL throws
+        u = new URL(input);
+    }
+    catch {
+        return fail("Pass a full absolute URL, such as https://example.com/page.");
+    }
+    if (u.protocol !== "https:" && u.protocol !== "http:") {
+        return fail("Pass an https URL; only http and https URLs can be fetched.");
+    }
+    if (u.username !== "" || u.password !== "") {
+        return fail("Pass the URL without a user name or password.");
+    }
+    u.protocol = "https:";
+    // `u.hostname` is WHATWG-normalized (lowercased, IDNA, numeric IPv4 forms such as `0x7f.0.0.1`
+    // rewritten to dotted decimal, IPv6 in brackets), which is what isPublicHostname expects: never
+    // pass it a hand-parsed host.
+    if (!isPublicHostname(u.hostname)) {
+        return fail("Pass a full public https URL; this host is private or local.");
+    }
+    // the limit is on the URL as fetched: the upgrade, IDNA and percent-encoding can lengthen it
+    if (u.href.length > MAX_FETCH_URL_CHARS) {
+        return fail(`Pass a URL of at most ${MAX_FETCH_URL_CHARS} characters.`);
+    }
+    return { ok: true, url: u.href };
+}

package/dist/tools/oauth/flow-paths.d.ts

@@ -6,7 +6,7 @@ export declare const OAUTH_STATE_TTL_SECONDS = 600;
 /** 浏览器绑定 Cookie：回调必须来自发起连接的同一个浏览器。 */
 export declare const OAUTH_BINDING_COOKIE = "cap_oauth";
 /** 回调失败、或连接时没给回跳页面时回到的网页（next-intl 会补语言前缀）。 */
-export declare const DEFAULT_RETURN_PATH = "/settings/connections";
+export declare const DEFAULT_RETURN_PATH = "/account/connections";
 /** OAuth 连接器需要 `http.publicUrl`（回调地址）；未配置 → 这条校验错误。 */
 export declare const publicUrlRequired: () => ApiError;
 export declare function callbackUrl(publicUrl: string): string;

package/dist/tools/oauth/flow-paths.js

@@ -8,7 +8,7 @@ export const OAUTH_STATE_TTL_SECONDS = 600;
 /** 浏览器绑定 Cookie：回调必须来自发起连接的同一个浏览器。 */
 export const OAUTH_BINDING_COOKIE = "cap_oauth";
 /** 回调失败、或连接时没给回跳页面时回到的网页（next-intl 会补语言前缀）。 */
-export const DEFAULT_RETURN_PATH = "/settings/connections";
+export const DEFAULT_RETURN_PATH = "/account/connections";
 /** OAuth 连接器需要 `http.publicUrl`（回调地址）；未配置 → 这条校验错误。 */
 export const publicUrlRequired = () => new ApiError("validation_failed", "Request validation failed", [
     {

package/dist/tools/pipeline.js

@@ -985,6 +985,21 @@ let ToolPipeline = class ToolPipeline {
             // a sub-agent works in its parent conversation's sandbox (spec §10.1)
             ...(tool.source.kind === "builtin" &&
                 ctx.parent !== undefined && { sandboxConversationId: ctx.parent.conversationId }),
+            ...(tool.source.kind === "builtin" &&
+                ctx.parent !== undefined && { parentRunId: ctx.parent.runId }),
+            // the hook scope of a builtin's own model call (the WebFetch extraction)
+            ...(tool.source.kind === "builtin" && {
+                step: ctx.step,
+                agentVersion: ctx.agentVersion,
+                ...(ctx.conversationKind !== undefined && { conversationKind: ctx.conversationKind }),
+                ...(ctx.parent !== undefined && {
+                    parent: {
+                        conversationId: ctx.parent.conversationId,
+                        runId: ctx.parent.runId,
+                        callId: ctx.parent.callId,
+                    },
+                }),
+            }),
         };
         // 内置工具可按输入给自己的时限（沙箱 bash 按命令超时加余量）；缺省 tools.timeoutMs
         const timeoutMs = tool.timeoutMs?.(input) ?? this.config.get().tools.timeoutMs;

package/dist/tools/registry.d.ts

@@ -1,4 +1,4 @@
-import type { Connector, InputRequired, ToolAnnotations, ToolCallContext, ToolResult, ToolSpec } from "@capybara-hq/plugin-sdk";
+import type { Connector, HookParentScope, InputRequired, ToolAnnotations, ToolCallContext, ToolResult, ToolSpec } from "@capybara-hq/plugin-sdk";
 import type { AgentDefinition } from "../agents/definition.js";
 import type { ToolView } from "../conversations/events.js";
 import { ExtensionHost } from "../extensions/host.js";
@@ -6,6 +6,7 @@ import { ExtensionRegistry } from "../extensions/registry.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import type { OrgRole } from "../orgs/roles.js";
+import type { ConversationKindForHooks } from "../runtime/hook-calls.js";
 import { BuiltinTools } from "./builtins/builtin-tools.js";
 export { BUILTIN_TOOL_NAMES } from "./builtin-names.js";
 export { canonicalJson } from "./canonical-json.js";
@@ -32,6 +33,18 @@ export interface BuiltinCallContext extends ToolCallContext {
      * for a sub-agent's call, the conversation itself otherwise (the default when absent).
      */
     sandboxConversationId?: string;
+    /** The parent run of a sub-agent's run (absent for a top-level run). */
+    parentRunId?: string;
+    /**
+     * The rest of the run's hook scope, for a builtin that makes a model call of its own (the
+     * `WebFetch` extraction fires `model.request` / `model.response`): the step of the call, the
+     * agent version of the run, the conversation kind (hooks fire for `chat` and `subagent` only)
+     * and, for a sub-agent, where it was dispatched from.
+     */
+    step?: number;
+    agentVersion?: number;
+    conversationKind?: ConversationKindForHooks;
+    parent?: HookParentScope;
 }
 /**
  * 内置工具的结果：`ToolResult` 之外可带 `loadedTools`（`ToolSearch` 加载的工具 key，
@@ -58,8 +71,14 @@ export interface BuiltinTool {
     timeoutMs?: (input: unknown) => number;
     /** 结果转存阈值（字符）：与 `tools.outputSpillChars` 取小者。缺省只用配置。 */
     spillChars?: number;
-    /** 本部署当前不可用时返回事实原因（英文、可执行，进「工具不可用」提醒）；可用返回 null。 */
-    unavailable?: () => string | null;
+    /**
+     * The factual reason this tool is unavailable for the org right now (English, actionable; it goes
+     * into the "tool unavailable" reminder), or null when it is available. May be async (e.g. a
+     * per-org extension-point default).
+     */
+    unavailable?: (ctx: {
+        orgId: string;
+    }) => Promise<string | null> | string | null;
 }
 /**
  * agent 定义里对工具的引用（Task 6 在 `AgentDefinitionSchema` 中落地同形的 zod schema）。

package/dist/tools/registry.js

@@ -18,7 +18,7 @@ import { readOrgSettings } from "../orgs/settings.service.js";
 import { estimateTokens } from "../runtime/context/tokens.js";
 import { SUBAGENT_LIMIT_DEFAULTS, subagentLimits } from "../runtime/subagents/limits.js";
 import { resolveRoster } from "../runtime/subagents/roster.js";
-import { AGENT_TOOL, BUILTIN_TOOL_NAMES, SKILL_LOAD, TOOL_SEARCH } from "./builtin-names.js";
+import { AGENT_TOOL, BASH_COMPANION_TOOLS, BUILTIN, BUILTIN_TOOL_NAMES, SKILL_LOAD, TOOL_SEARCH, } from "./builtin-names.js";
 import { agentToolSpec } from "./builtins/agent.js";
 import { BuiltinTools } from "./builtins/builtin-tools.js";
 import { canonicalJson } from "./canonical-json.js";
@@ -71,6 +71,16 @@ const sourceId = (s) => s.kind === "builtin"
     : s.kind === "plugin"
         ? `plugin:${s.plugin}:${s.name}`
         : `connector:${s.connectorId}:${s.name}`;
+/** A builtin as a resolved tool (with `spec`, which `Agent` builds per definition). */
+const builtinTool = (b, spec) => ({
+    key: b.spec.name,
+    source: { kind: "builtin", name: b.spec.name },
+    spec,
+    specHash: specHash(spec),
+    defaultPolicy: b.defaultPolicy,
+    ...(b.timeoutMs !== undefined && { timeoutMs: b.timeoutMs }),
+    ...(b.spillChars !== undefined && { spillChars: b.spillChars }),
+});
 /**
  * Tool registry: resolves the references in an agent definition into the tools available for this
  * run. Not cached (reads PG and the host live every time), so changes take effect right away across
@@ -201,6 +211,11 @@ let ToolRegistry = class ToolRegistry {
                     return;
                 }
                 claim(path, ref.name, `builtin:${ref.name}`);
+                // offered with Bash (see resolve), so their policies validate too
+                if (ref.name === BUILTIN.Bash) {
+                    for (const c of BASH_COMPANION_TOOLS)
+                        claim(path, c, `builtin:${c}`);
+                }
             }
             else if (ref.kind === "plugin") {
                 const key = extensionToolKey(ref.plugin, ref.name);
@@ -316,7 +331,7 @@ let ToolRegistry = class ToolRegistry {
                     unavailable.push({ ref: ref.name, reason: "Built-in tool does not exist" });
                     continue;
                 }
-                const why = b.unavailable?.() ?? null;
+                const why = (await b.unavailable?.({ orgId })) ?? null;
                 if (why !== null) {
                     unavailable.push({ ref: ref.name, reason: why });
                     continue;
@@ -330,15 +345,15 @@ let ToolRegistry = class ToolRegistry {
                         continue;
                     spec = agentToolSpec(roster, await this.maxConcurrentSubagents(orgId));
                 }
-                add({
-                    key: b.spec.name,
-                    source: { kind: "builtin", name: b.spec.name },
-                    spec,
-                    specHash: specHash(spec),
-                    defaultPolicy: b.defaultPolicy,
-                    ...(b.timeoutMs !== undefined && { timeoutMs: b.timeoutMs }),
-                    ...(b.spillChars !== undefined && { spillChars: b.spillChars }),
-                });
+                add(builtinTool(b, spec));
+                // `TaskOutput` and `TaskStop` come with an available `Bash` (background Bash spec §2)
+                if (b.spec.name === BUILTIN.Bash) {
+                    for (const name of BASH_COMPANION_TOOLS) {
+                        const c = this.builtins.find((x) => x.spec.name === name);
+                        if (c && ((await c.unavailable?.({ orgId })) ?? null) === null)
+                            add(builtinTool(c, c.spec));
+                    }
+                }
             }
             else if (ref.kind === "plugin") {
                 const key = extensionToolKey(ref.plugin, ref.name);

package/dist/tools/tools.module.js

@@ -5,20 +5,25 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { Module } from "@nestjs/common";
+import { BackgroundModule } from "../background/background.module.js";
 import { ConversationAccessModule } from "../conversations/access.js";
 import { AttachmentsModule } from "../conversations/attachments.module.js";
 import { EventLogModule } from "../conversations/event-log.js";
 import { ExtensionsModule } from "../extensions/extensions.module.js";
 import { QueueModule } from "../infra/queue/queue.module.js";
+import { ModelsModule } from "../models/models.module.js";
 import { OrgLockModule } from "../orgs/org-lock.js";
 import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
+import { StepLogModule } from "../runtime/step-log.js";
 import { SubagentsModule } from "../runtime/subagents/subagents.service.js";
+import { UsageReportModule } from "../runtime/usage-report.js";
 import { SandboxModule } from "../sandbox/sandbox.module.js";
 import { SkillsModule } from "../skills/skills.module.js";
 import { StorageModule } from "../storage/storage.module.js";
 import { ApprovalsService } from "./approvals.service.js";
 import { Breaker } from "./breaker.js";
 import { BuiltinTools } from "./builtins/builtin-tools.js";
+import { WebPages } from "./builtins/web/page-cache.js";
 import { ConnectorContent } from "./connector-content.js";
 import { ConnectorsService } from "./connectors.service.js";
 import { Credentials } from "./credentials.js";
@@ -52,14 +57,21 @@ ToolsModule = __decorate([
             SubagentsModule,
             // the builtin sandbox and skill tools run in the conversation's sandbox
             SandboxModule,
+            // `Bash` with run_in_background records its task; TaskOutput / TaskStop finish and stop it
+            BackgroundModule,
             // the conversation page's tool metadata reads only what the viewer may see
             ConversationAccessModule,
+            // the WebFetch extraction call: its purpose, usage report and step writes
+            ModelsModule,
+            UsageReportModule,
+            StepLogModule,
             QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
         ],
         providers: [
             Credentials,
             ToolOutputs,
             BuiltinTools,
+            WebPages,
             ToolRegistry,
             ApprovalsService,
             QuestionsService,

package/dist/tools/validate.js

@@ -1,5 +1,5 @@
 import { Ajv2020 } from "ajv/dist/2020.js";
-import { canonicalJson } from "./registry.js";
+import { canonicalJson } from "./canonical-json.js";
 /**
  * 编译结果缓存的上限：超过后整体丢弃（工具定义每步从库里重新读出，缓存不能无限增长）。
  * 缓存的是由定义推导出的只读数据，不是跨进程状态。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/kernel",
-  "version": "0.1.0-rc.3",
+  "version": "0.1.0-rc.4",
   "description": "Capybara kernel: config, database, plugin host and HTTP API of the Capybara agent platform",
   "license": "Apache-2.0",
   "repository": {
@@ -64,14 +64,14 @@
     "yaml": "^2.9.1",
     "yauzl": "3.4.0",
     "zod": "^4.6.7",
-    "@capybara-hq/plugin-sdk": "^0.1.0-rc.1"
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.2"
   },
   "devDependencies": {
     "@langchain/langgraph-checkpoint-validation": "^1.2.0",
     "@types/pg": "^8.23.1",
     "@types/semver": "^7.8.0",
     "@types/yauzl": "3.4.0",
-    "@capybara-hq/testing": "0.1.0-rc.3"
+    "@capybara-hq/testing": "0.1.0-rc.4"
   },
   "scripts": {
     "build": "tsc -b"

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)
+);