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

package/dist/tools/builtin-names.js

@@ -19,10 +19,13 @@ export const BUILTIN = {
     ReadToolOutput: "ReadToolOutput",
     ToolSearch: "ToolSearch",
     Agent: "Agent",
+    SendMessage: "SendMessage",
+    SubagentHandback: "SubagentHandback",
     TaskOutput: "TaskOutput",
     TaskStop: "TaskStop",
     WebSearch: "WebSearch",
     WebFetch: "WebFetch",
+    Platform: "Platform",
 };
 /**
  * The builtin tools that run in the conversation's sandbox. `TaskOutput` and `TaskStop` read and
@@ -61,7 +64,9 @@ export const SANDBOX_ASK_TOOL_NAMES = new Set([
  * Every builtin name. Saving an agent checks builtin refs against this list, not against what is
  * registered now, so the order the implementations land in never affects a saved definition.
  * `SkillWrite` is available only when a definition names it; `ToolSearch` and `Skill` are added
- * by the registry; `Agent` dispatches sub-agents and its description is built per agent.
+ * 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).
  */
 export const BUILTIN_TOOL_NAMES = [
     BUILTIN.AskUserQuestion,
@@ -71,7 +76,10 @@ export const BUILTIN_TOOL_NAMES = [
     BUILTIN.SkillWrite,
     ...SANDBOX_TOOL_NAMES,
     BUILTIN.Agent,
+    BUILTIN.SendMessage,
+    BUILTIN.SubagentHandback,
     ...WEB_TOOL_NAMES,
+    BUILTIN.Platform,
 ];
 /** The builtin that loads a skill (added by the registry when the log has a skills catalog). */
 export const SKILL_LOAD = BUILTIN.Skill;
@@ -79,6 +87,19 @@ export const SKILL_LOAD = BUILTIN.Skill;
 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.
@@ -93,12 +114,11 @@ 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): `Agent` (depth 1), `AskUserQuestion`
- * (the person does not see the child), `Deliver` (delivering files is the parent's job) and
- * `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.Agent,
     BUILTIN.AskUserQuestion,
     BUILTIN.Deliver,
     BUILTIN.SkillWrite,
@@ -106,10 +126,12 @@ export const CHILD_REMOVED_TOOLS = [
 /**
  * The tools of a new agent created without `tools` (`ToolSearch` is added by the registry, never
  * by a definition). Only for create requests; updates and stored versions get no defaults.
+ * `Platform` is on by default (Platform tool spec §3: reads are harmless, every write confirmed).
  */
 export const DEFAULT_AGENT_TOOLS = [
     { kind: "builtin", name: BUILTIN.AskUserQuestion },
     { kind: "builtin", name: BUILTIN.ReadToolOutput },
+    { kind: "builtin", name: BUILTIN.Platform },
 ];
 /** Kinds of the builtin tools (display only); a builtin missing here is a plain `tool`. */
 export const BUILTIN_TOOL_KINDS = {
@@ -127,8 +149,11 @@ export const BUILTIN_TOOL_KINDS = {
     [BUILTIN.SkillWrite]: "meta",
     [BUILTIN.ReadToolOutput]: "meta",
     [BUILTIN.AskUserQuestion]: "meta",
+    [BUILTIN.SendMessage]: "meta",
+    [BUILTIN.SubagentHandback]: "meta",
     [BUILTIN.WebSearch]: "search",
     [BUILTIN.WebFetch]: "read",
+    [BUILTIN.Platform]: "tool",
 };
 /**
  * Input fields left out when matching a replayed call with a recorded one (full-run replay), per

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

@@ -1,16 +1,16 @@
 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.
  */
-/** 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). */
 export declare const AgentToolInput: z.ZodObject<{
     description: z.ZodString;
@@ -22,7 +22,6 @@ 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>;
 /**
@@ -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,12 +70,7 @@ 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;

package/dist/tools/builtins/agent.js

@@ -1,7 +1,15 @@
 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, 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.
+ */
 /** The input of an `Agent` call (§4.2). */
 export const AgentToolInput = z
     .object({
@@ -9,7 +17,6 @@ export const AgentToolInput = z
     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. */
@@ -28,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",
@@ -44,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";
 /**
@@ -96,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" +
+    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.",
@@ -119,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). */
@@ -145,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."
@@ -197,9 +206,7 @@ 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 };

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

@@ -4,10 +4,14 @@ 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";
@@ -25,11 +29,11 @@ import { WebPages } from "./web/index.js";
  */
 export declare class BuiltinTools {
     private readonly tools;
-    constructor(db: KernelDb, config: KernelConfigService, outputs: ToolOutputs, storage: StorageService, skillChanges: SkillChangesService, attachments: AttachmentsService, eventLog: EventLog, sandbox: SandboxService, points: ExtensionPointDefaults, webPages: WebPages, 
+    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);
+    } | undefined, usageReport: UsageReporter, stepLog: StepLog, log: Logger, background: BackgroundTaskStore, finisher: BackgroundTaskFinisher, stopper: BackgroundTaskStopper, platformOps: PlatformOperations, platformActor: PlatformActor, agentDocs: AgentDocs);
     /** The builtin tools, in a fixed order. */
     list(): readonly BuiltinTool[];
 }

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

@@ -13,12 +13,17 @@ 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 { StepLog } from "../../runtime/step-log.js";
 import { UsageReporter } from "../../runtime/usage-report.js";
 import { SandboxService } from "../../sandbox/sandbox.service.js";
@@ -27,8 +32,11 @@ import { StorageService } from "../../storage/storage.service.js";
 import { ToolOutputs } from "../outputs.js";
 import { agentTool } from "./agent.js";
 import { askUserTool } from "./ask-user.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";
@@ -41,11 +49,12 @@ import { extractAnswer, WebPages, webTools } from "./web/index.js";
  */
 let BuiltinTools = class BuiltinTools {
     tools;
-    constructor(db, config, outputs, storage, skillChanges, attachments, eventLog, sandbox, points, webPages, 
+    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) {
+    purposes, host, usageReport, stepLog, log, background, finisher, stopper, platformOps, platformActor, agentDocs) {
         const sandboxDeps = {
             sandbox,
+            environments,
             background,
             tasks: { finisher, stopper },
             attachments,
@@ -59,12 +68,17 @@ let BuiltinTools = class BuiltinTools {
             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,
                 get db() {
@@ -81,6 +95,13 @@ let BuiltinTools = class BuiltinTools {
                 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,
+            }),
         ];
     }
     /** The builtin tools, in a fixed order. */
@@ -98,15 +119,19 @@ BuiltinTools = __decorate([
     __param(5, Inject(AttachmentsService)),
     __param(6, Inject(EventLog)),
     __param(7, Inject(SandboxService)),
-    __param(8, Inject(ExtensionPointDefaults)),
-    __param(9, Inject(WebPages)),
-    __param(10, Inject(ModelPurposesService)),
-    __param(11, Inject(ExtensionHost)),
-    __param(12, Inject(UsageReporter)),
-    __param(13, Inject(StepLog)),
-    __param(14, Inject(KERNEL_LOGGER)),
-    __param(15, Inject(BackgroundTaskStore)),
-    __param(16, Inject(BackgroundTaskFinisher)),
-    __param(17, Inject(BackgroundTaskStopper))
+    __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))
 ], BuiltinTools);
 export { BuiltinTools };

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;

package/dist/tools/builtins/handback.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+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 const HandbackInput = z.object({ message: z.string().min(1).max(200_000) }).strict();
+const SPEC = {
+    name: "SubagentHandback",
+    description: "Hand your report back to the agent that dispatched you. It receives the message as your " +
+        "report, so include everything it needs: what you did, what you found, and anything left " +
+        "open. You keep your turn after this call: go on working if something remains, then end your " +
+        "turn. You can hand back more than once, for example a partial report and then the final " +
+        "one. Once you handed back, your final reply is not delivered again. For a short note while " +
+        'you work, use SendMessage with to "parent" instead.',
+    inputSchema: {
+        type: "object",
+        properties: {
+            message: {
+                type: "string",
+                minLength: 1,
+                maxLength: 200000,
+                description: "Your report for the agent that dispatched you.",
+            },
+        },
+        required: ["message"],
+        additionalProperties: false,
+    },
+};
+/** The result of a handback (agent map spec §4.3). */
+export const HANDBACK_RESULT_TEXT = "Report delivered to your caller.";
+/** A call outside a sub-agent (the tool is never offered there). */
+export 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 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 const handbackTool = {
+    spec: SPEC,
+    defaultPolicy: "allow",
+    run: async () => ({
+        content: [{ type: "text", text: HANDBACK_NOT_A_CHILD_TEXT }],
+        isError: true,
+    }),
+};