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

package/dist/tools/breaker.d.ts

@@ -1,5 +1,5 @@
 import type { Redis } from "ioredis";
-import type { KernelConfig } from "../config/schema.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 /** 熔断器键：每个组织 × 连接器一个 hash（`f` = 连续失败次数，`o` = 打开到期的毫秒时间戳）。 */
 export declare const breakerKey: (orgId: string, connectorId: string) => string;
 export type BreakerState = {
@@ -19,7 +19,7 @@ export declare function breakerOpenMessage(connectorName: string, failures: numb
 export declare class Breaker {
     private readonly redis;
     private readonly config;
-    constructor(redis: Redis, config: () => KernelConfig);
+    constructor(redis: Redis, config: Pick<KernelConfigService, "get">);
     check(orgId: string, connectorId: string): Promise<BreakerState>;
     /** 记一次失败，返回当前连续失败次数。 */
     failure(orgId: string, connectorId: string): Promise<number>;

package/dist/tools/breaker.js

@@ -1,3 +1,15 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { REDIS } from "../infra/tokens.js";
 /** 熔断器键：每个组织 × 连接器一个 hash（`f` = 连续失败次数，`o` = 打开到期的毫秒时间戳）。 */
 export const breakerKey = (orgId, connectorId) => `capk:breaker:${orgId}:${connectorId}`;
 /**
@@ -47,7 +59,7 @@ export function breakerOpenMessage(connectorName, failures, retryAfterSeconds) {
  * `tools.breakerOpenSeconds` 秒，期间直接拒绝；到期后半开放行，成功清零、失败立即重新打开。
  * 状态只在 Redis（多副本共享），计数与打开状态都带 TTL。
  */
-export class Breaker {
+let Breaker = class Breaker {
     redis;
     config;
     constructor(redis, config) {
@@ -62,11 +74,17 @@ export class Breaker {
     }
     /** 记一次失败，返回当前连续失败次数。 */
     async failure(orgId, connectorId) {
-        const { breakerFailures, breakerOpenSeconds } = this.config().tools;
+        const { breakerFailures, breakerOpenSeconds } = this.config.get().tools;
         return Number(await this.redis.eval(FAILURE, 1, breakerKey(orgId, connectorId), breakerFailures, breakerOpenSeconds * 1000, COUNT_TTL_MS));
     }
     /** 调用成功：清零。 */
     async success(orgId, connectorId) {
         await this.redis.del(breakerKey(orgId, connectorId));
     }
-}
+};
+Breaker = __decorate([
+    Injectable(),
+    __param(0, Inject(REDIS)),
+    __param(1, Inject(KernelConfigService))
+], Breaker);
+export { Breaker };

package/dist/tools/builtin-names.d.ts

@@ -0,0 +1,109 @@
+import type { ToolKind } from "./info.js";
+/**
+ * The names (model-visible keys) of the kernel's builtin tools, following Claude Code (tool naming
+ * spec §4.1). Plain constants: `BuiltinTools`, the tool factories, the registry, policy and the
+ * runtime import them from here. The web keeps its own copy (`apps/web/src/lib/agents.ts`,
+ * `lib/timeline.ts`), checked equal by `test/tools/builtin-names.test.ts`. The release-candidate
+ * names are in `legacy-keys.ts`, never here.
+ */
+export declare const BUILTIN: {
+    readonly Bash: "Bash";
+    readonly Read: "Read";
+    readonly Write: "Write";
+    readonly Edit: "Edit";
+    readonly Glob: "Glob";
+    readonly Grep: "Grep";
+    readonly Deliver: "Deliver";
+    readonly Skill: "Skill";
+    readonly SkillWrite: "SkillWrite";
+    readonly AskUserQuestion: "AskUserQuestion";
+    readonly ReadToolOutput: "ReadToolOutput";
+    readonly ToolSearch: "ToolSearch";
+    readonly Agent: "Agent";
+    readonly SendMessage: "SendMessage";
+    readonly SubagentHandback: "SubagentHandback";
+    readonly TaskOutput: "TaskOutput";
+    readonly TaskStop: "TaskStop";
+    readonly WebSearch: "WebSearch";
+    readonly WebFetch: "WebFetch";
+    readonly Platform: "Platform";
+    readonly CurrentTime: "CurrentTime";
+};
+export type BuiltinName = (typeof BUILTIN)[keyof typeof BUILTIN];
+/**
+ * The builtin tools that run in the conversation's sandbox. `TaskOutput` and `TaskStop` read and
+ * stop the background tasks `Bash` started (background Bash spec §2.2, §2.3).
+ */
+export declare const SANDBOX_TOOL_NAMES: readonly BuiltinName[];
+/** The builtin tools that reach the web through the org's web-search / web-fetch providers. */
+export declare const WEB_TOOL_NAMES: readonly BuiltinName[];
+/**
+ * The tools offered with `Bash` whenever it is offered (background Bash: a model that can start a
+ * background task can read and stop it). `ToolRegistry` adds them; an explicit ref is harmless.
+ */
+export declare const BASH_COMPANION_TOOLS: readonly BuiltinName[];
+/**
+ * Sandbox tools that need approval when the org setting `sandboxToolPolicy` is `ask` (not the
+ * read-only ones). Not `TaskOutput` or `TaskStop`: they only read or stop a task whose launch
+ * already went through `Bash`'s policy (background Bash spec §4.5).
+ */
+export declare const SANDBOX_ASK_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * Every builtin name. Saving an agent checks turned-off builtins against this list, not against
+ * what is registered now, so the order the implementations land in never affects a saved
+ * definition. `ToolSearch` and `Skill` are added
+ * by the registry; `Agent` dispatches sub-agents and its description is built per agent;
+ * `SendMessage` and `SubagentHandback` are added by the registry ({@link SUBAGENT_MESSAGE_TOOLS}).
+ * `Platform` calls the platform's own operations as the run's person (Platform tool spec).
+ * `CurrentTime` reads the clock (the run context carries only the date).
+ */
+export declare const BUILTIN_TOOL_NAMES: readonly BuiltinName[];
+/** The builtin that loads a skill (added by the registry when the log has a skills catalog). */
+export declare const SKILL_LOAD: "Skill";
+/** The builtin that searches the tool catalog (added by the registry by org setting and threshold). */
+export declare const TOOL_SEARCH: "ToolSearch";
+/** The builtin that dispatches sub-agents. */
+export declare const AGENT_TOOL: "Agent";
+/** The builtin that sends a message to one of the caller's sub-agents or to its parent. */
+export declare const SEND_MESSAGE: "SendMessage";
+/** The builtin that hands a sub-agent's report back to its parent (sub-agents only). */
+export declare const SUBAGENT_HANDBACK: "SubagentHandback";
+/**
+ * The tools between the agents of one tree (agent map spec §4.2, §4.3), added by the registry
+ * whatever a definition names: `SendMessage` to an agent that has `Agent` or a parent, and
+ * `SubagentHandback` to a sub-agent. A definition's ref to either is ignored.
+ */
+export declare const SUBAGENT_MESSAGE_TOOLS: ReadonlySet<string>;
+/**
+ * Tool keys on the spec 3.6 R3 fixed list ("allowed is not confirmed"): their policy is at least
+ * `ask` and remembered grants never let them through. `SkillWrite` changes shared skills.
+ * Connector and extension tools express the same rule with `annotations.requiresUserInteraction`.
+ */
+export declare const R3_FIXED_ASK_TOOL_KEYS: ReadonlySet<string>;
+/**
+ * R3 keys that apply only to shared agents: a private agent's skills are not shared, so its
+ * `SkillWrite` takes effect without asking (R4).
+ */
+export declare const R3_SHARED_AGENT_ONLY_TOOL_KEYS: ReadonlySet<string>;
+/**
+ * Tools a sub-agent never gets (sub-agents spec §5.3, §5.5): `AskUserQuestion` (the person does
+ * not see the child), `Deliver` (delivering files is the parent's job) and `SkillWrite`. `Agent`
+ * is removed only from a child at `subagents.maxDepth` (agent map spec §4.1, `effectiveDefinition`).
+ */
+export declare const CHILD_REMOVED_TOOLS: readonly ["AskUserQuestion", "Deliver", "SkillWrite"];
+/**
+ * The builtins every agent has unless it turns them off (tools default-on spec §4), in this
+ * order: {@link BUILTIN_TOOL_NAMES} without the ones the registry manages by rule (`ToolSearch`,
+ * `Skill`, `SendMessage`, `SubagentHandback`) and without `TaskOutput` / `TaskStop`, which come
+ * with `Bash` ({@link BASH_COMPANION_TOOLS}). These are also the builtins an agent can turn off.
+ */
+export declare const AGENT_BUILTIN_NAMES: readonly BuiltinName[];
+/** Kinds of the builtin tools (display only); a builtin missing here is a plain `tool`. */
+export declare const BUILTIN_TOOL_KINDS: Readonly<Record<string, ToolKind>>;
+/**
+ * Input fields left out when matching a replayed call with a recorded one (full-run replay), per
+ * tool: display-only arguments the model writes that do not change what the tool does. `Bash`'s
+ * `description` became required in UI refresh B, so a recording without it and a replayed call
+ * with one (or a different wording) still match.
+ */
+export declare const MATCH_IGNORED_FIELDS: Readonly<Record<string, readonly string[]>>;

package/dist/tools/builtin-names.js

@@ -0,0 +1,173 @@
+/**
+ * The names (model-visible keys) of the kernel's builtin tools, following Claude Code (tool naming
+ * spec §4.1). Plain constants: `BuiltinTools`, the tool factories, the registry, policy and the
+ * runtime import them from here. The web keeps its own copy (`apps/web/src/lib/agents.ts`,
+ * `lib/timeline.ts`), checked equal by `test/tools/builtin-names.test.ts`. The release-candidate
+ * names are in `legacy-keys.ts`, never here.
+ */
+export const BUILTIN = {
+    Bash: "Bash",
+    Read: "Read",
+    Write: "Write",
+    Edit: "Edit",
+    Glob: "Glob",
+    Grep: "Grep",
+    Deliver: "Deliver",
+    Skill: "Skill",
+    SkillWrite: "SkillWrite",
+    AskUserQuestion: "AskUserQuestion",
+    ReadToolOutput: "ReadToolOutput",
+    ToolSearch: "ToolSearch",
+    Agent: "Agent",
+    SendMessage: "SendMessage",
+    SubagentHandback: "SubagentHandback",
+    TaskOutput: "TaskOutput",
+    TaskStop: "TaskStop",
+    WebSearch: "WebSearch",
+    WebFetch: "WebFetch",
+    Platform: "Platform",
+    CurrentTime: "CurrentTime",
+};
+/**
+ * The builtin tools that run in the conversation's sandbox. `TaskOutput` and `TaskStop` read and
+ * stop the background tasks `Bash` started (background Bash spec §2.2, §2.3).
+ */
+export const SANDBOX_TOOL_NAMES = [
+    BUILTIN.Bash,
+    BUILTIN.Read,
+    BUILTIN.Write,
+    BUILTIN.Edit,
+    BUILTIN.Glob,
+    BUILTIN.Grep,
+    BUILTIN.Deliver,
+    BUILTIN.TaskOutput,
+    BUILTIN.TaskStop,
+];
+/** The builtin tools that reach the web through the org's web-search / web-fetch providers. */
+export const WEB_TOOL_NAMES = [BUILTIN.WebSearch, BUILTIN.WebFetch];
+/**
+ * The tools offered with `Bash` whenever it is offered (background Bash: a model that can start a
+ * background task can read and stop it). `ToolRegistry` adds them; an explicit ref is harmless.
+ */
+export const BASH_COMPANION_TOOLS = [BUILTIN.TaskOutput, BUILTIN.TaskStop];
+/**
+ * Sandbox tools that need approval when the org setting `sandboxToolPolicy` is `ask` (not the
+ * read-only ones). Not `TaskOutput` or `TaskStop`: they only read or stop a task whose launch
+ * already went through `Bash`'s policy (background Bash spec §4.5).
+ */
+export const SANDBOX_ASK_TOOL_NAMES = new Set([
+    BUILTIN.Bash,
+    BUILTIN.Write,
+    BUILTIN.Edit,
+    BUILTIN.Deliver,
+]);
+/**
+ * Every builtin name. Saving an agent checks turned-off builtins against this list, not against
+ * what is registered now, so the order the implementations land in never affects a saved
+ * definition. `ToolSearch` and `Skill` are added
+ * by the registry; `Agent` dispatches sub-agents and its description is built per agent;
+ * `SendMessage` and `SubagentHandback` are added by the registry ({@link SUBAGENT_MESSAGE_TOOLS}).
+ * `Platform` calls the platform's own operations as the run's person (Platform tool spec).
+ * `CurrentTime` reads the clock (the run context carries only the date).
+ */
+export const BUILTIN_TOOL_NAMES = [
+    BUILTIN.AskUserQuestion,
+    BUILTIN.ReadToolOutput,
+    BUILTIN.ToolSearch,
+    BUILTIN.Skill,
+    BUILTIN.SkillWrite,
+    ...SANDBOX_TOOL_NAMES,
+    BUILTIN.Agent,
+    BUILTIN.SendMessage,
+    BUILTIN.SubagentHandback,
+    ...WEB_TOOL_NAMES,
+    BUILTIN.Platform,
+    BUILTIN.CurrentTime,
+];
+/** The builtin that loads a skill (added by the registry when the log has a skills catalog). */
+export const SKILL_LOAD = BUILTIN.Skill;
+/** The builtin that searches the tool catalog (added by the registry by org setting and threshold). */
+export const TOOL_SEARCH = BUILTIN.ToolSearch;
+/** The builtin that dispatches sub-agents. */
+export const AGENT_TOOL = BUILTIN.Agent;
+/** The builtin that sends a message to one of the caller's sub-agents or to its parent. */
+export const SEND_MESSAGE = BUILTIN.SendMessage;
+/** The builtin that hands a sub-agent's report back to its parent (sub-agents only). */
+export const SUBAGENT_HANDBACK = BUILTIN.SubagentHandback;
+/**
+ * The tools between the agents of one tree (agent map spec §4.2, §4.3), added by the registry
+ * whatever a definition names: `SendMessage` to an agent that has `Agent` or a parent, and
+ * `SubagentHandback` to a sub-agent. A definition's ref to either is ignored.
+ */
+export const SUBAGENT_MESSAGE_TOOLS = new Set([
+    SEND_MESSAGE,
+    SUBAGENT_HANDBACK,
+]);
+/**
+ * Tool keys on the spec 3.6 R3 fixed list ("allowed is not confirmed"): their policy is at least
+ * `ask` and remembered grants never let them through. `SkillWrite` changes shared skills.
+ * Connector and extension tools express the same rule with `annotations.requiresUserInteraction`.
+ */
+export const R3_FIXED_ASK_TOOL_KEYS = new Set([BUILTIN.SkillWrite]);
+/**
+ * R3 keys that apply only to shared agents: a private agent's skills are not shared, so its
+ * `SkillWrite` takes effect without asking (R4).
+ */
+export const R3_SHARED_AGENT_ONLY_TOOL_KEYS = new Set([
+    BUILTIN.SkillWrite,
+]);
+/**
+ * Tools a sub-agent never gets (sub-agents spec §5.3, §5.5): `AskUserQuestion` (the person does
+ * not see the child), `Deliver` (delivering files is the parent's job) and `SkillWrite`. `Agent`
+ * is removed only from a child at `subagents.maxDepth` (agent map spec §4.1, `effectiveDefinition`).
+ */
+export const CHILD_REMOVED_TOOLS = [
+    BUILTIN.AskUserQuestion,
+    BUILTIN.Deliver,
+    BUILTIN.SkillWrite,
+];
+/**
+ * The builtins every agent has unless it turns them off (tools default-on spec §4), in this
+ * order: {@link BUILTIN_TOOL_NAMES} without the ones the registry manages by rule (`ToolSearch`,
+ * `Skill`, `SendMessage`, `SubagentHandback`) and without `TaskOutput` / `TaskStop`, which come
+ * with `Bash` ({@link BASH_COMPANION_TOOLS}). These are also the builtins an agent can turn off.
+ */
+export const AGENT_BUILTIN_NAMES = BUILTIN_TOOL_NAMES.filter((n) => n !== BUILTIN.ToolSearch &&
+    n !== BUILTIN.Skill &&
+    n !== BUILTIN.SendMessage &&
+    n !== BUILTIN.SubagentHandback &&
+    !BASH_COMPANION_TOOLS.includes(n));
+/** Kinds of the builtin tools (display only); a builtin missing here is a plain `tool`. */
+export const BUILTIN_TOOL_KINDS = {
+    [BUILTIN.Bash]: "command",
+    [BUILTIN.Read]: "read",
+    [BUILTIN.Write]: "edit",
+    [BUILTIN.Edit]: "edit",
+    [BUILTIN.Glob]: "search",
+    [BUILTIN.Grep]: "search",
+    [BUILTIN.Deliver]: "tool",
+    [BUILTIN.TaskOutput]: "read",
+    [BUILTIN.TaskStop]: "command",
+    [BUILTIN.ToolSearch]: "meta",
+    [BUILTIN.Skill]: "meta",
+    [BUILTIN.SkillWrite]: "meta",
+    [BUILTIN.ReadToolOutput]: "meta",
+    [BUILTIN.AskUserQuestion]: "meta",
+    [BUILTIN.SendMessage]: "meta",
+    [BUILTIN.SubagentHandback]: "meta",
+    [BUILTIN.WebSearch]: "search",
+    [BUILTIN.WebFetch]: "read",
+    [BUILTIN.Platform]: "tool",
+    [BUILTIN.CurrentTime]: "tool",
+};
+/**
+ * Input fields left out when matching a replayed call with a recorded one (full-run replay), per
+ * tool: display-only arguments the model writes that do not change what the tool does. `Bash`'s
+ * `description` became required in UI refresh B, so a recording without it and a replayed call
+ * with one (or a different wording) still match.
+ */
+export const MATCH_IGNORED_FIELDS = {
+    // `run_in_background` is matched on purpose: it changes what the call did (a launch that
+    // returns at once instead of the command's output; background Bash spec §4.4)
+    [BUILTIN.Bash]: ["description"],
+};

package/dist/tools/builtins/agent.d.ts

@@ -1,17 +1,17 @@
 import type { ToolSpec } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
-import type { EventPayload } from "../../conversations/events.js";
 import { type RosterEntry } from "../../runtime/subagents/roster.js";
+import { type SubagentAbortedBy, type SubagentStatus } from "../../runtime/subagents/status.js";
 import type { BuiltinTool } from "../registry.js";
+export { AGENT_TOOL } from "../builtin-names.js";
 /**
- * The `agent` builtin tool (sub-agents spec §4): dispatches a sub-agent. Its description is built
- * per parent agent version from the roster ({@link agentToolSpec}); the tool pipeline handles the
- * call itself (dispatch, suspend, resume), so {@link agentTool}'s `run` is only a guard.
+ * The `Agent` builtin tool (sub-agents spec §4, agent map spec §4.1): dispatches a sub-agent in
+ * the background. Its description is built per parent agent version from the roster
+ * ({@link agentToolSpec}); the tool pipeline handles the call itself (the dispatch writes the
+ * call's result, {@link agentStartedText}), so {@link agentTool}'s `run` is only a guard. The
+ * sub-agent's reports and its finish reach the parent as `subagent_delivery` events.
  */
-export declare const AGENT_TOOL = "agent";
-/** How a sub-agent's run ended (`subagent_finished.status`). */
-export type SubagentStatus = EventPayload<"subagent_finished">["status"];
-/** The input of an `agent` call (§4.2). */
+/** The input of an `Agent` call (§4.2). */
 export declare const AgentToolInput: z.ZodObject<{
     description: z.ZodString;
     prompt: z.ZodString;
@@ -22,11 +22,10 @@ export declare const AgentToolInput: z.ZodObject<{
         inherit: "inherit";
         standard: "standard";
     }>>;
-    resume: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type AgentToolInputT = z.infer<typeof AgentToolInput>;
 /**
- * The `agent` tool definition of a parent agent version (§4.3): the fixed text with
+ * The `Agent` tool definition of a parent agent version (§4.3): the fixed text with
  * `maxConcurrent`, then one line per roster entry in roster order. Built at tool resolution, so the
  * spec hash changes with the roster or the limit (logged per request in `tool_specs`).
  */
@@ -37,21 +36,29 @@ export declare const AGENT_REFUSALS: {
     readonly tooManyConcurrent: (n: number) => string;
     readonly tooManyDispatches: (n: number) => string;
     readonly budget: (n: number) => string;
-    readonly noSuchAgent: (id: string) => string;
-    readonly stillRunning: (id: string) => string;
-    readonly resumeWithType: "resume cannot be combined with subagent_type or model.";
+    readonly depthLimit: (maxDepth: number) => string;
     readonly notAvailableHere: "Sub-agents are not available in this conversation.";
     readonly agentNotAvailable: (name: string) => string;
 };
 /**
- * The parent run was stopped while this sub-agent worked (§4.4, §12): the result of a stopped
- * parent's open `agent` call, and the text of a child stopped with its parent.
+ * The run was stopped while this sub-agent worked (§4.4, §12): the report of a stopped run's fork
+ * invocation whose sub-agent was still active (it is stopped with the run).
  */
 export declare const AGENT_STOPPED_WITH_RUN_TEXT = "The run was stopped while this sub-agent was working; it was stopped too.";
 /**
- * The tool result of a finished sub-agent (§4.4): the text for how its run ended, a blank line, and
- * the status line with its `agentId`. `ownModel`: an org agent dispatched with a `model` that was
- * ignored. `abortedBy: "parent"`: stopped together with the parent run (seen only in logs).
+ * The immediate result of an `Agent` call (agent map spec §4.1): the sub-agent runs in the
+ * background, its reports and its finish arrive later as notifications (`subagent_delivery`).
+ * `ownModel`: an org agent dispatched with a `model`, which runs on its own model instead.
+ */
+export declare const agentStartedText: (agentId: string, opts?: {
+    ownModel?: boolean;
+}) => string;
+/**
+ * The result text of a finished sub-agent (§4.4): the text for how its run ended, a blank line, and
+ * the status line with its `agentId`. Used for a fork invocation's report (phase D); a background
+ * `Agent` call's sub-agent reports through `subagent_delivery` instead. `ownModel`: an org agent
+ * dispatched with a `model` that was ignored. `abortedBy: "parent"`: stopped together with the
+ * parent run.
  */
 export declare function agentResultText(r: {
     reply: string;
@@ -63,19 +70,14 @@ export declare function agentResultText(r: {
     durationMs: number;
     tokens: number;
     ownModel?: boolean;
-    abortedBy?: "user" | "parent";
-    /**
-     * Phase D: the report of a person's fork invocation, whose parent need not have the `agent`
-     * tool: the status line leaves out the resume hint (batch 3 review m2).
-     */
-    noResumeHint?: boolean;
+    abortedBy?: SubagentAbortedBy;
 }): {
     content: string;
     isError: boolean;
 };
 /**
  * The builtin. `defaultPolicy: "allow"` (§4.6): a sub-agent runs only tools its parent may run,
- * each under its own policy. The tool pipeline dispatches `agent` calls itself; `run` answers only
+ * each under its own policy. The tool pipeline dispatches `Agent` calls itself; `run` answers only
  * when a call reaches it anyway.
  */
 export declare const agentTool: BuiltinTool;