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

package/dist/tools/builtins/agent.js

@@ -1,19 +1,22 @@
 import { z } from "zod";
 import { ROSTER_DESCRIPTION_MAX } from "../../runtime/subagents/roster.js";
+import { subagentStatusText, } from "../../runtime/subagents/status.js";
+import { AGENT_TOOL } from "../builtin-names.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 const AGENT_TOOL = "agent";
-/** The input of an `agent` call (§4.2). */
+/** The input of an `Agent` call (§4.2). */
 export const AgentToolInput = z
     .object({
     description: z.string().min(1).max(80),
     prompt: z.string().min(1).max(100_000),
     subagent_type: z.string().min(1).max(130).optional(),
     model: z.enum(["inherit", "fast", "standard", "capable"]).optional(),
-    resume: z.string().max(64).optional(),
 })
     .strict();
 /** Display only (UI refresh B): the task name, then the type; never sent to the model. */
@@ -32,7 +35,7 @@ const INPUT_SCHEMA = {
             minLength: 1,
             maxLength: 100000,
             description: "The complete task for the sub-agent. It sees nothing else of this conversation: include " +
-                "every fact, file path and constraint it needs, and say what its final reply must contain.",
+                "every fact, file path and constraint it needs, and say what its report must contain.",
         },
         subagent_type: {
             type: "string",
@@ -48,25 +51,22 @@ const INPUT_SCHEMA = {
                 "integration and judgment, capable for design and final reviews. Defaults to the agent " +
                 "type's own setting, else your model.",
         },
-        resume: {
-            type: "string",
-            maxLength: 64,
-            description: "The agentId from an earlier result of this tool: sends prompt to that sub-agent as a " +
-                "follow-up, with its earlier context intact. Leave subagent_type and model unset.",
-        },
     },
     required: ["description", "prompt"],
     additionalProperties: false,
 };
-/** The text before the roster (§4.3), with the concurrency limit. */
-const head = (maxConcurrent) => "Dispatch a sub-agent: a fresh agent with its own context that works on one task and returns its " +
-    "final reply as this tool's result. The sub-agent sees only your prompt, not this conversation, so " +
-    "include everything it needs and say what its final reply must contain. It shares your sandbox " +
-    "files. You wait until it finishes. To run several at once, call this tool several times in the " +
-    `same response (at most ${maxConcurrent} at a time); their commands run in the sandbox at the ` +
-    "same time, so give parallel sub-agents separate files or directories. Sub-agents cannot " +
-    "dispatch sub-agents or ask the user questions. To send a finished sub-agent a follow-up while " +
-    "keeping its context, pass the agentId from its result as resume.\n" +
+/** The text before the roster (§4.3, agent map spec §4.1), with the concurrency limit. */
+const head = (maxConcurrent) => "Dispatch a sub-agent: a fresh agent with its own context that works on one task in the " +
+    "background. This tool returns at once with the sub-agent's agentId; keep working or end your " +
+    "turn, and do not wait for it. When the sub-agent hands back a report or finishes, its result " +
+    "arrives in this conversation as a notification. The sub-agent sees only your prompt, not this " +
+    "conversation, so include everything it needs and say what its report must contain. It shares " +
+    "your sandbox files. To run several at once, call this tool several times (at most " +
+    `${maxConcurrent} of your sub-agents run at a time); their commands run in the sandbox at the ` +
+    "same time, so give parallel sub-agents separate files or directories. To give a sub-agent more " +
+    "instructions while it works, or a follow-up after it finished, use SendMessage with its " +
+    "agentId. Sub-agents can dispatch sub-agents of their own up to the nesting limit; they cannot " +
+    "ask the user questions.\n" +
     "\n" +
     "Agent types (subagent_type):\n";
 /**
@@ -86,7 +86,7 @@ function rosterLine(e) {
         : `${line} (the agent "${inert(e.agentName).replaceAll('"', "'")}", with its own tools and model)`;
 }
 /**
- * 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`).
  */
@@ -100,20 +100,23 @@ export function agentToolSpec(roster, maxConcurrent) {
 }
 /**
  * The static definition: the rendering for a roster of only general-purpose at the default
- * `subagents.maxConcurrentPerRun` (what an agent without `subagents` gets under the defaults).
+ * `subagents.maxConcurrentPerConversation` (what an agent without `subagents` gets under the defaults).
  * Written out as a literal for the tool design check; a test pins it equal to
  * `agentToolSpec([general-purpose], 4)`.
  */
 const SPEC = {
-    name: "agent",
-    description: "Dispatch a sub-agent: a fresh agent with its own context that works on one task and returns its " +
-        "final reply as this tool's result. The sub-agent sees only your prompt, not this conversation, so " +
-        "include everything it needs and say what its final reply must contain. It shares your sandbox " +
-        "files. You wait until it finishes. To run several at once, call this tool several times in the " +
-        "same response (at most 4 at a time); their commands run in the sandbox at the same time, so give " +
-        "parallel sub-agents separate files or directories. Sub-agents cannot dispatch sub-agents or ask " +
-        "the user questions. To send a finished sub-agent a follow-up while keeping its context, pass the " +
-        "agentId from its result as resume.\n" +
+    name: "Agent",
+    description: "Dispatch a sub-agent: a fresh agent with its own context that works on one task in the " +
+        "background. This tool returns at once with the sub-agent's agentId; keep working or end your " +
+        "turn, and do not wait for it. When the sub-agent hands back a report or finishes, its result " +
+        "arrives in this conversation as a notification. The sub-agent sees only your prompt, not this " +
+        "conversation, so include everything it needs and say what its report must contain. It shares " +
+        "your sandbox files. To run several at once, call this tool several times (at most 4 of your " +
+        "sub-agents run at a time); their commands run in the sandbox at the same time, so give " +
+        "parallel sub-agents separate files or directories. To give a sub-agent more instructions " +
+        "while it works, or a follow-up after it finished, use SendMessage with its agentId. " +
+        "Sub-agents can dispatch sub-agents of their own up to the nesting limit; they cannot ask the " +
+        "user questions.\n" +
         "\n" +
         "Agent types (subagent_type):\n" +
         "- general-purpose: a copy of you with your tools and skills, for multi-step work.",
@@ -123,18 +126,16 @@ const SPEC = {
 /** Refusals (§4.5): `isError` results written without starting anything (model-visible). */
 export const AGENT_REFUSALS = {
     unknownType: (x, roster) => `Unknown subagent_type "${x}". Available: ${roster.join(", ")}.`,
-    tooManyConcurrent: (n) => `At most ${n} sub-agents can run at once in this run; dispatch the remaining tasks after these finish.`,
-    tooManyDispatches: (n) => `This run has dispatched ${n} sub-agents, the limit; do the remaining work yourself.`,
-    budget: (n) => `Sub-agents of this run have used their token budget (${count(n)} tokens); do the remaining work yourself.`,
-    noSuchAgent: (id) => `No sub-agent with agentId "${id}" in this conversation.`,
-    stillRunning: (id) => `Sub-agent "${id}" is still running; wait for its result before sending a follow-up.`,
-    resumeWithType: "resume cannot be combined with subagent_type or model.",
+    tooManyConcurrent: (n) => `At most ${n} of your sub-agents can run at once in this conversation; dispatch the remaining tasks after one of them finishes.`,
+    tooManyDispatches: (n) => `${n} sub-agents have been dispatched since the user's latest message, counted across all levels of sub-agents; that is the limit, so do the remaining work yourself.`,
+    budget: (n) => `Sub-agents have used their token budget since the user's latest message (${count(n)} tokens, counted across all levels of sub-agents); do the remaining work yourself.`,
+    depthLimit: (maxDepth) => `Sub-agents can be nested at most ${maxDepth} levels deep, and you are at the deepest level; do this task yourself.`,
     notAvailableHere: "Sub-agents are not available in this conversation.",
     agentNotAvailable: (name) => `The agent "${name}" is not available to the person who started this conversation; do this task yourself or use another agent type.`,
 };
 /**
- * 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 const AGENT_STOPPED_WITH_RUN_TEXT = "The run was stopped while this sub-agent was working; it was stopped too.";
 /** `12345` → `12,345` (no locale data involved, so the text is the same on every replica). */
@@ -149,46 +150,50 @@ function duration(ms) {
     return `${Math.floor(s / 3600)}h ${String(Math.floor((s % 3600) / 60)).padStart(2, "0")}m`;
 }
 /**
- * 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 const agentStartedText = (agentId, opts = {}) => `agentId: ${agentId} (running in the background)\n` +
+    "The sub-agent is working on the task. Its result arrives in this conversation as a " +
+    "notification when it hands back a report or finishes; keep working or end your turn. To send " +
+    "it more instructions, use SendMessage with this agentId." +
+    (opts.ownModel === true ? " It runs on its own model; the model you passed was ignored." : "");
+/**
+ * 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 function agentResultText(r) {
     const reply = r.reply.trim();
-    let status;
+    const status = subagentStatusText(r.status, r);
     let text;
     let isError = true;
     switch (r.status) {
         case "completed":
-            [status, text, isError] = ["completed", reply, false];
+            [text, isError] = [reply, false];
             break;
         case "max_steps":
-            [status, text, isError] = [
-                "stopped at the step limit; the reply may be partial",
-                reply,
-                false,
-            ];
+            [text, isError] = [reply, false];
             break;
         case "max_duration":
-            status = "stopped at the time limit; the reply may be partial";
             text = reply === "" ? "The sub-agent produced no reply before the time limit." : reply;
             isError = false;
             break;
         case "budget":
-            [status, text] = ["stopped: token budget used up", reply];
+            text = reply;
             break;
         case "aborted":
-            [status, text] =
-                r.abortedBy === "parent"
-                    ? ["stopped with this run", AGENT_STOPPED_WITH_RUN_TEXT]
-                    : ["stopped by the user", "The user stopped this sub-agent."];
+            text =
+                r.abortedBy === "parent" ? AGENT_STOPPED_WITH_RUN_TEXT : "The user stopped this sub-agent.";
             break;
         case "timed_out":
             // the parent's sub-agents wait timed out (§7.2) and stopped it; the parent goes on
-            [status, text] = ["timed out", "stopped: the sub-agent wait timed out"];
+            text = "stopped: the sub-agent wait timed out";
             break;
         case "failed":
-            status = r.errorCode === undefined ? "failed" : `failed (${r.errorCode})`;
             text =
                 r.errorMessage === undefined
                     ? "The sub-agent failed."
@@ -201,16 +206,14 @@ export function agentResultText(r) {
         ...(r.ownModel === true ? ["model: the agent's own"] : []),
         `${r.toolCalls} tool ${r.toolCalls === 1 ? "call" : "calls"}`,
         duration(r.durationMs),
-        r.noResumeHint === true
-            ? `${count(r.tokens)} tokens.`
-            : `${count(r.tokens)} tokens. Pass the agentId as resume to send this sub-agent a follow-up.`,
+        `${count(r.tokens)} tokens.`,
     ];
     const line = `[${parts.join(" · ")}]`;
     return { content: text === "" ? line : `${text}\n\n${line}`, isError };
 }
 /**
  * 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 const agentTool = {

package/dist/tools/builtins/ask-user.d.ts

@@ -1,5 +1,5 @@
 import { type FormAnswer, type InputForm } from "@capybara-hq/plugin-sdk";
-import type { KernelConfig } from "../../config/schema.js";
+import type { KernelConfigService } from "../../infra/config/kernel-config.service.js";
 import type { BuiltinTool } from "../registry.js";
 interface Question {
     question: string;
@@ -18,11 +18,11 @@ export declare function questionsForm(questions: Question[]): InputForm;
 /** 答案 → 给模型的结果文本：`User answered: "<question>" = "<answer>"; …`。 */
 export declare function answerText(questions: Question[], answer: FormAnswer): string;
 /**
- * 内置工具 `ask_user`：用通用的输入请求机制实现——首次调用返回 `input_required`，
+ * 内置工具 `AskUserQuestion`：用通用的输入请求机制实现——首次调用返回 `input_required`，
  * 内核暂停运行并展示表单；用户回答（或超时）后用同一 input 再次调用，按 `ctx.resume` 生成结果。
  * 默认 allow（提问本身就是让用户参与，不再审批）。
  */
 export declare function askUserTool(deps: {
-    config: () => KernelConfig;
+    config: Pick<KernelConfigService, "get">;
 }): BuiltinTool;
 export {};

package/dist/tools/builtins/ask-user.js

@@ -1,6 +1,6 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
 const SPEC = {
-    name: "ask_user",
+    name: "AskUserQuestion",
     description: "Ask the user one or more multiple-choice questions and wait for the answers. Use it when you " +
         "need the user's preference or decision to continue, or when a request is ambiguous; do not use " +
         "it for questions you can answer yourself. Each question has a short header, 2-4 options with a " +
@@ -103,7 +103,7 @@ const text = (t, zh, en) => ({
     display: { summary: { zh, en } },
 });
 /**
- * 内置工具 `ask_user`：用通用的输入请求机制实现——首次调用返回 `input_required`，
+ * 内置工具 `AskUserQuestion`：用通用的输入请求机制实现——首次调用返回 `input_required`，
  * 内核暂停运行并展示表单；用户回答（或超时）后用同一 input 再次调用，按 `ctx.resume` 生成结果。
  * 默认 allow（提问本身就是让用户参与，不再审批）。
  */
@@ -132,7 +132,7 @@ export function askUserTool(deps) {
                     throw new ToolError(`Option labels must be unique within a question; "${q.question}" has duplicates. Provide distinct labels.`);
                 }
             }
-            const state = { hours: deps.config().tools.approvalTimeoutHours };
+            const state = { hours: deps.config.get().tools.approvalTimeoutHours };
             return { kind: "input_required", form: questionsForm(questions), state };
         },
     };

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

@@ -0,0 +1,41 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import { BackgroundTaskFinisher } from "../../background/finish.js";
+import { BackgroundTaskStopper } from "../../background/stop.js";
+import { BackgroundTaskStore } from "../../background/store.js";
+import { AttachmentsService } from "../../conversations/attachments.service.js";
+import { EventLog } from "../../conversations/event-log.js";
+import { ConversationEnvironments } from "../../environments/conversation-environments.js";
+import { ExtensionPointDefaults } from "../../extensions/point-defaults.js";
+import { KernelConfigService } from "../../infra/config/kernel-config.service.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { ModelPurposesService } from "../../models/purposes.js";
+import { PlatformActor } from "../../platform/actor.js";
+import { AgentDocs } from "../../platform/agent-docs.js";
+import { PlatformOperations } from "../../platform/registry.js";
+import type { HookRunner } from "../../runtime/hook-calls.js";
+import { StepLog } from "../../runtime/step-log.js";
+import { UsageReporter } from "../../runtime/usage-report.js";
+import { SandboxService } from "../../sandbox/sandbox.service.js";
+import { SkillChangesService } from "../../skills/changes.service.js";
+import { StorageService } from "../../storage/storage.service.js";
+import { ToolOutputs } from "../outputs.js";
+import type { BuiltinTool } from "../registry.js";
+import { WebPages } from "./web/index.js";
+/**
+ * The kernel's builtin tools, built once from the injected services (their specs: names,
+ * descriptions and schemas, are the factories' own and unchanged). `ToolSearch` and `Skill`
+ * are added to a run by the registry (`forAgent`: organization setting and threshold, a skills
+ * catalog snapshot), not by agent definitions; `SkillWrite` only when a definition names it.
+ */
+export declare class BuiltinTools {
+    private readonly tools;
+    constructor(db: KernelDb, config: KernelConfigService, outputs: ToolOutputs, storage: StorageService, skillChanges: SkillChangesService, attachments: AttachmentsService, eventLog: EventLog, sandbox: SandboxService, environments: ConversationEnvironments, points: ExtensionPointDefaults, webPages: WebPages, 
+    /** The WebFetch extraction call: the `web_fetch` purpose, its hooks, usage and denials. */
+    purposes: ModelPurposesService, host: {
+        readonly hooks?: HookRunner;
+    } | undefined, usageReport: UsageReporter, stepLog: StepLog, log: Logger, background: BackgroundTaskStore, finisher: BackgroundTaskFinisher, stopper: BackgroundTaskStopper, platformOps: PlatformOperations, platformActor: PlatformActor, agentDocs: AgentDocs, 
+    /** The clock `CurrentTime` reads (the run context's clock seam; `Date.now` by default). */
+    now?: () => number);
+    /** The builtin tools, in a fixed order. */
+    list(): readonly BuiltinTool[];
+}

package/dist/tools/builtins/builtin-tools.js

@@ -0,0 +1,151 @@
+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, Optional } from "@nestjs/common";
+import { BackgroundTaskFinisher } from "../../background/finish.js";
+import { BackgroundTaskStopper } from "../../background/stop.js";
+import { BackgroundTaskStore } from "../../background/store.js";
+import { AttachmentsService } from "../../conversations/attachments.service.js";
+import { EventLog } from "../../conversations/event-log.js";
+import { ConversationEnvironments } from "../../environments/conversation-environments.js";
+import { ExtensionHost } from "../../extensions/host.js";
+import { ExtensionPointDefaults } from "../../extensions/point-defaults.js";
+import { KernelConfigService } from "../../infra/config/kernel-config.service.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { KERNEL_LOGGER } from "../../infra/tokens.js";
+import { ModelPurposesService } from "../../models/purposes.js";
+import { readOrgSettings } from "../../orgs/settings.service.js";
+import { PlatformActor } from "../../platform/actor.js";
+import { AgentDocs } from "../../platform/agent-docs.js";
+import { PlatformOperations } from "../../platform/registry.js";
+import { conversationTimeZone, RUN_CONTEXT_CLOCK } from "../../runtime/run-context.service.js";
+import { StepLog } from "../../runtime/step-log.js";
+import { UsageReporter } from "../../runtime/usage-report.js";
+import { SandboxService } from "../../sandbox/sandbox.service.js";
+import { SkillChangesService } from "../../skills/changes.service.js";
+import { StorageService } from "../../storage/storage.service.js";
+import { ToolOutputs } from "../outputs.js";
+import { agentTool } from "./agent.js";
+import { askUserTool } from "./ask-user.js";
+import { currentTimeTool } from "./current-time.js";
+import { handbackTool } from "./handback.js";
+import { platformTool } from "./platform.js";
+import { readToolOutputTool } from "./read-tool-output.js";
+import { sandboxTools } from "./sandbox/index.js";
+import { sendMessageTool } from "./send-message.js";
+import { skillLoadTool } from "./skill-load.js";
+import { skillWriteTool } from "./skill-write.js";
+import { toolSearchTool } from "./tool-search.js";
+import { extractAnswer, WebPages, webTools } from "./web/index.js";
+/**
+ * The kernel's builtin tools, built once from the injected services (their specs: names,
+ * descriptions and schemas, are the factories' own and unchanged). `ToolSearch` and `Skill`
+ * are added to a run by the registry (`forAgent`: organization setting and threshold, a skills
+ * catalog snapshot), not by agent definitions; `SkillWrite` only when a definition names it.
+ */
+let BuiltinTools = class BuiltinTools {
+    tools;
+    constructor(db, config, outputs, storage, skillChanges, attachments, eventLog, sandbox, environments, points, webPages, 
+    /** The WebFetch extraction call: the `web_fetch` purpose, its hooks, usage and denials. */
+    purposes, host, usageReport, stepLog, log, background, finisher, stopper, platformOps, platformActor, agentDocs, 
+    /** The clock `CurrentTime` reads (the run context's clock seam; `Date.now` by default). */
+    now) {
+        const sandboxDeps = {
+            sandbox,
+            environments,
+            background,
+            tasks: { finisher, stopper },
+            attachments,
+            storage,
+            eventLog,
+            config,
+            log,
+        };
+        this.tools = [
+            askUserTool({ config }),
+            readToolOutputTool({ outputs, config }),
+            toolSearchTool(),
+            // dispatches sub-agents; the tool pipeline handles its calls (sub-agents spec §4, §7.1)
+            agentTool,
+            // messages between the agents of one tree; the registry offers them and the tool pipeline
+            // handles their calls (agent map spec §4.2, §4.3)
+            sendMessageTool,
+            handbackTool,
+            ...sandboxTools(sandboxDeps),
+            // 技能加载：对话日志里有技能目录快照时由注册表自动加入（Ruling M17）
+            skillLoadTool({
+                storage,
+                config,
+                sandbox,
+                environments,
+                attachments,
+                eventLog,
+                log,
+                get db() {
+                    return db.db;
+                },
+            }),
+            // 自写技能：agent 定义显式引用才可用
+            skillWriteTool({ changes: skillChanges }),
+            // web search / fetch through the org's default provider (web tools spec §3); WebFetch answers
+            // from the page with one call on the `web_fetch` purpose (§5), never returning the page
+            ...webTools({
+                points,
+                config,
+                cache: webPages,
+                extract: (ctx, page, prompt) => extractAnswer({ purposes, eventLog, stepLog, config, log, hooks: host?.hooks, usageReport }, ctx, page, prompt),
+            }),
+            // the platform's own operations and docs, as the run's person (Platform tool spec)
+            platformTool({
+                ops: platformOps,
+                actor: platformActor,
+                docs: agentDocs,
+                setting: async (orgId) => (await readOrgSettings(db.db, orgId)).platformTool,
+                log,
+            }),
+            // the clock in the run context's time zone (the run context carries only the date)
+            currentTimeTool({
+                now: now ?? Date.now,
+                timeZoneOf: ({ orgId, conversationId }) => conversationTimeZone(db.db, orgId, conversationId),
+            }),
+        ];
+    }
+    /** The builtin tools, in a fixed order. */
+    list() {
+        return this.tools;
+    }
+};
+BuiltinTools = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(KernelConfigService)),
+    __param(2, Inject(ToolOutputs)),
+    __param(3, Inject(StorageService)),
+    __param(4, Inject(SkillChangesService)),
+    __param(5, Inject(AttachmentsService)),
+    __param(6, Inject(EventLog)),
+    __param(7, Inject(SandboxService)),
+    __param(8, Inject(ConversationEnvironments)),
+    __param(9, Inject(ExtensionPointDefaults)),
+    __param(10, Inject(WebPages)),
+    __param(11, Inject(ModelPurposesService)),
+    __param(12, Inject(ExtensionHost)),
+    __param(13, Inject(UsageReporter)),
+    __param(14, Inject(StepLog)),
+    __param(15, Inject(KERNEL_LOGGER)),
+    __param(16, Inject(BackgroundTaskStore)),
+    __param(17, Inject(BackgroundTaskFinisher)),
+    __param(18, Inject(BackgroundTaskStopper)),
+    __param(19, Inject(PlatformOperations)),
+    __param(20, Inject(PlatformActor)),
+    __param(21, Inject(AgentDocs)),
+    __param(22, Optional()),
+    __param(22, Inject(RUN_CONTEXT_CLOCK))
+], BuiltinTools);
+export { BuiltinTools };

package/dist/tools/builtins/current-time.d.ts

@@ -0,0 +1,26 @@
+import type { BuiltinTool } from "../registry.js";
+/** An unknown zone: what was wrong and how to call again. */
+export declare const unknownTimeZoneText: (zone: string) => string;
+/** The local wall clock of `now` in `timeZone`, with its offset from UTC. */
+export interface LocalTime {
+    /** `YYYY-MM-DDTHH:mm:ss±HH:MM`. */
+    local: string;
+    weekday: string;
+    /** `+08:00`, `-05:00`, `+00:00`. */
+    offset: string;
+    /** `YYYY-MM-DDTHH:mm:ssZ`. */
+    utc: string;
+}
+/** Formats `now` in `timeZone` (a zone {@link isTimeZone} accepts). Seconds precision. */
+export declare function localTime(now: Date, timeZone: string): LocalTime;
+export interface CurrentTimeDeps {
+    /** The clock (epoch ms): the kernel's `RUN_CONTEXT_CLOCK` seam, `Date.now` by default. */
+    now: () => number;
+    /** The conversation's time zone (its run context's, else the org default, else UTC). */
+    timeZoneOf: (ctx: {
+        orgId: string;
+        conversationId: string;
+    }) => Promise<string>;
+}
+/** The `CurrentTime` builtin. */
+export declare function currentTimeTool(deps: CurrentTimeDeps): BuiltinTool;

package/dist/tools/builtins/current-time.js

@@ -0,0 +1,99 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+import { isTimeZone } from "../../time-zone.js";
+import { BUILTIN } from "../builtin-names.js";
+/**
+ * The `CurrentTime` builtin: the current local date-time in a time zone. The run context gives the
+ * model the date only (day granularity, run context spec §3), so the time of day, durations and
+ * other zones come from this tool. Read-only, no side effects: `defaultPolicy` is allow. The
+ * result goes into the log like any tool result, so replays read the recorded answer.
+ */
+const SPEC = {
+    name: BUILTIN.CurrentTime,
+    description: "Get the current time: the local date and time with its UTC offset, the weekday, the time " +
+        "zone and the UTC instant. Today's date is already in your context; call this when you need " +
+        "the time of day, to work out a duration or how long ago something happened, or to know the " +
+        "time in another time zone. Without timeZone it uses the time zone of the person you work " +
+        "for. Read-only, no side effects.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            timeZone: {
+                type: "string",
+                minLength: 1,
+                maxLength: 64,
+                description: "An IANA time zone name, e.g. Asia/Shanghai, America/New_York or UTC. Omit it to use " +
+                    "the time zone of the person you work for.",
+            },
+        },
+        additionalProperties: false,
+    },
+};
+const Input = z.object({ timeZone: z.string().min(1).max(64).optional() }).strict();
+/** An unknown zone: what was wrong and how to call again. */
+export const unknownTimeZoneText = (zone) => `Unknown time zone '${zone}'; use an IANA name such as Asia/Shanghai or America/New_York, ` +
+    "or omit timeZone to use the time zone of the person you work for.";
+/** The input did not parse (the schema check runs first, so this is a guard). */
+const INVALID_INPUT_TEXT = "Invalid input; pass an object with an optional timeZone string (an IANA name such as Asia/Shanghai).";
+const pad = (n, w = 2) => String(n).padStart(w, "0");
+/** Formats `now` in `timeZone` (a zone {@link isTimeZone} accepts). Seconds precision. */
+export function localTime(now, timeZone) {
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+        weekday: "long",
+        hourCycle: "h23",
+    }).formatToParts(now);
+    const part = (type) => parts.find((p) => p.type === type)?.value ?? "";
+    const [y, mo, d, h, mi, s] = ["year", "month", "day", "hour", "minute", "second"].map((t) => Number(part(t)));
+    const seconds = Math.floor(now.getTime() / 1000) * 1000;
+    // the zone's offset: the wall clock read as if it were UTC, minus the instant
+    const offsetMin = Math.round((Date.UTC(y, mo - 1, d, h, mi, s) - seconds) / 60_000);
+    const abs = Math.abs(offsetMin);
+    const offset = `${offsetMin < 0 ? "-" : "+"}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`;
+    return {
+        local: `${pad(y, 4)}-${pad(mo)}-${pad(d)}T${pad(h)}:${pad(mi)}:${pad(s)}${offset}`,
+        weekday: part("weekday"),
+        offset,
+        utc: `${new Date(seconds).toISOString().slice(0, 19)}Z`,
+    };
+}
+/** The `CurrentTime` builtin. */
+export function currentTimeTool(deps) {
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        async run(input, ctx) {
+            const parsed = Input.safeParse(input ?? {});
+            if (!parsed.success)
+                throw new ToolError(INVALID_INPUT_TEXT);
+            const asked = parsed.data.timeZone?.trim();
+            if (asked !== undefined && !isTimeZone(asked)) {
+                throw new ToolError(unknownTimeZoneText(asked));
+            }
+            const zone = asked ?? (await deps.timeZoneOf({ orgId: ctx.orgId, conversationId: ctx.conversationId }));
+            const t = localTime(new Date(deps.now()), zone);
+            const text = `Current time: ${t.local} (${t.weekday})\n` +
+                `Time zone: ${zone} (UTC${t.offset})\n` +
+                `UTC: ${t.utc}`;
+            // the row's key argument already shows a zone the model passed; the summary then gives the
+            // time alone, and names the zone only when it came from the run context
+            const hm = t.local.slice(11, 16);
+            const where = asked === undefined ? { zh: `（${zone}）`, en: ` (${zone})` } : { zh: "", en: "" };
+            return {
+                content: [{ type: "text", text }],
+                display: {
+                    summary: {
+                        zh: `已获取当前时间 · ${hm}${where.zh}`,
+                        en: `Got the current time · ${hm}${where.en}`,
+                    },
+                },
+            };
+        },
+    };
+}

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

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import type { BuiltinTool } from "../registry.js";
+export { SUBAGENT_HANDBACK } from "../builtin-names.js";
+/**
+ * The `SubagentHandback` builtin tool (agent map spec §4.3, children only): delivers a report to
+ * the agent that dispatched the sub-agent, as a `report` `subagent_delivery` in the parent's log.
+ * The sub-agent keeps its turn and may go on working; several handbacks are allowed. A run that
+ * handed back and then completes delivers nothing more (it only logs `subagent_finished`); one that
+ * ends otherwise (failed, stopped, a limit) is delivered as a one-line status. The tool pipeline handles the call itself
+ * (`SubagentMessages`), so {@link handbackTool}'s `run` is only a guard.
+ */
+/** The input of a `SubagentHandback` call. */
+export declare const HandbackInput: z.ZodObject<{
+    message: z.ZodString;
+}, z.core.$strict>;
+export type HandbackInputT = z.infer<typeof HandbackInput>;
+/** The result of a handback (agent map spec §4.3). */
+export declare const HANDBACK_RESULT_TEXT = "Report delivered to your caller.";
+/** A call outside a sub-agent (the tool is never offered there). */
+export declare const HANDBACK_NOT_A_CHILD_TEXT = "Only sub-agents can hand back a report; reply in this conversation instead.";
+/** A fork invocation's child (phase D): its parent reads its final reply as the report. */
+export declare const HANDBACK_FORK_TEXT = "You run a skill for the agent that dispatched you, which reads your final reply as the report; end your turn with the report instead.";
+/**
+ * The builtin. `defaultPolicy: "allow"`: it only moves text inside one tree the person already
+ * started. The tool pipeline handles `SubagentHandback` calls itself; `run` answers only when a
+ * call reaches it anyway.
+ */
+export declare const handbackTool: BuiltinTool;