@tea-agent/loop-agent 0.42.0-next.9 → 0.43.0-next.1

package/dist/worker/console/chat/sdd-data-alignment.js

@@ -2,6 +2,12 @@ import { randomBytes } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+export const SDD_SKILL_NAMES = [
+    "SDD-design-analysis",
+    "SDD-implementation-test-review",
+    "SDD-requirement-analysis",
+];
+/** Backward-compatible name for callers that need a stable representative value. */
 export const SDD_DEFAULT_SKILL_NAME = "SDD-implementation-test-review";
 export const SDD_TELEMETRY_URL = "https://wizard-ai.paic.com.cn/code_pilot/api/skill-usage-log";
 export const SDD_TELEMETRY_SIGN = "52aad0c09e6b46818a11ee702d6fe0ba";
@@ -80,12 +86,16 @@ export class SddDataAlignmentError extends Error {
         this.name = "SddDataAlignmentError";
     }
 }
-export function normalizeSddSkillName(value) {
+export function selectRandomSddSkillName(random = Math.random) {
+    const index = Math.min(SDD_SKILL_NAMES.length - 1, Math.max(0, Math.floor(random() * SDD_SKILL_NAMES.length)));
+    return SDD_SKILL_NAMES[index];
+}
+export function normalizeSddSkillName(value, random = Math.random) {
     if (value !== undefined && typeof value !== "string") {
         throw new SddDataAlignmentError("SDD_INVALID_SKILL_NAME", "skillName 必须是字符串", 400);
     }
     const raw = value ?? "";
-    const normalized = raw.trim() || SDD_DEFAULT_SKILL_NAME;
+    const normalized = raw.trim() || selectRandomSddSkillName(random);
     if ([...normalized].length > 256 || /[\u0000-\u001f\u007f]/u.test(raw)) {
         throw new SddDataAlignmentError("SDD_INVALID_SKILL_NAME", "skillName 不能超过 256 个字符或包含控制字符", 400);
     }
@@ -149,6 +159,7 @@ export class SddDataAlignmentService {
         if (!response.ok || body?.ret !== 0 || body.succ !== true) {
             throw new SddDataAlignmentError("SDD_UPSTREAM_FAILED", "SDD 数据对齐上报失败", 502);
         }
+        return { skillName };
     }
 }
 async function readBoundedTelemetryJson(response) {

package/dist/worker/console/chat/session-store.js

@@ -589,7 +589,11 @@ export async function runChatTurn(options) {
         };
     }
     if (options.persistUserMessage !== false) {
-        const userMessage = await store.appendMessage(sessionId, { role: "user", text });
+        const userMessage = await store.appendMessage(sessionId, {
+            role: "user",
+            text,
+            ...(options.clientRequestId ? { clientRequestId: options.clientRequestId } : {}),
+        });
         const afterUserMessage = await store.get(sessionId);
         if (afterUserMessage)
             await options.onUserMessagePersisted?.(afterUserMessage, userMessage);

package/dist/worker/console/chat/subagents/agent-tool.js

@@ -0,0 +1,62 @@
+/**
+ * Parent-session Agent custom tool. First slice: Explore only, one-shot.
+ */
+import { AGENT_TOOL_DESCRIPTION, AGENT_TOOL_PROMPT_GUIDELINES, AGENT_TOOL_PROMPT_SNIPPET, parseExploreAgentParams, } from "./explore-agent.js";
+import { OPERATOR_CHAT_AGENT_TOOL_NAME } from "./types.js";
+function textResult(payload, isError = false) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+        details: payload,
+        ...(isError ? { isError: true } : {}),
+    };
+}
+export async function buildAgentCustomTool(options) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    return defineTool({
+        name: OPERATOR_CHAT_AGENT_TOOL_NAME,
+        label: "Explore",
+        description: AGENT_TOOL_DESCRIPTION,
+        promptSnippet: AGENT_TOOL_PROMPT_SNIPPET,
+        promptGuidelines: [...AGENT_TOOL_PROMPT_GUIDELINES],
+        executionMode: "parallel",
+        parameters: Type.Object({
+            description: Type.String({
+                description: "Short 3-5 word summary shown on the tool card",
+            }),
+            prompt: Type.String({
+                description: "Complete Explore brief. Include goal, known clues, exclusions, success criteria, and thoroughness (quick | medium | very thorough).",
+            }),
+            subagent_type: Type.Optional(Type.String({
+                description: "Built-in agent name. Omit or set Explore.",
+            })),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params, signal) {
+            const parsed = parseExploreAgentParams(params);
+            if (!parsed.ok) {
+                const failure = {
+                    schemaVersion: 1,
+                    kind: "subagent",
+                    agent: "Explore",
+                    status: "failed",
+                    description: typeof params.description === "string" ? params.description : "",
+                    error: parsed.message,
+                    runId: "",
+                };
+                return textResult({
+                    ...failure,
+                    code: parsed.code,
+                }, true);
+            }
+            const result = await options.orchestrator.launch({
+                parentSessionId: options.parentSessionId,
+                request: parsed.request,
+                signal,
+                model: options.resolveModel?.(),
+            });
+            return textResult(result, result.status !== "completed");
+        },
+    });
+}

package/dist/worker/console/chat/subagents/explore-agent.js

@@ -0,0 +1,169 @@
+/**
+ * Built-in Explore role: parameter validation + Chinese system prompt.
+ * Frontmatter `tools: "*"` / `shellPolicy: unrestricted` are role metadata
+ * only — runtime tool args come from tool-policy.ts.
+ */
+import { EXPLORE_AGENT_NAME, EXPLORE_RESULT_KIND, EXPLORE_RESULT_MAX_BYTES, EXPLORE_RESULT_MAX_LINES, EXPLORE_RESULT_SCHEMA_VERSION, } from "./types.js";
+const FORBIDDEN_OPTION_KEYS = [
+    "tasks",
+    "model",
+    "run_in_background",
+    "isolation",
+    "cwd",
+    "name",
+];
+export const EXPLORE_SYSTEM_PROMPT = [
+    "你是运行在 Pi 中的文件搜索和代码库探索专家。请按照用户要求的探索深度，彻底浏览仓库，并尽快返回基于证据的答案。",
+    "",
+    "=== 关键要求：只读模式，不得修改任何内容 ===",
+    "",
+    "这是一个只读探索任务。你严格禁止：",
+    "",
+    "- 创建、编辑、删除、移动或复制文件；",
+    "- 创建临时文件；",
+    "- 使用 shell 重定向、命令替换，或任何会改变仓库或系统状态的命令；",
+    "- 安装依赖或执行 Git 写操作。",
+    "",
+    "Pi 工具在技术上可能对你可见，但这不代表你获得了修改权限。只读行为是严格的角色要求。Console runtime 不会向你提供 `edit`、`write` 或 `bash`；即使出现可变工具，你也必须保持非修改行为。你的职责仅限于搜索、阅读和分析现有代码。",
+    "",
+    "你的优势包括：",
+    "",
+    "- 使用 find 和 ls 查找文件；",
+    "- 使用 safe-grep 搜索代码和文本；",
+    "- 使用 safe-read 阅读并分析相关文件；",
+    "- 使用 git-status / git-diff 做只读仓库检查；",
+    "- 追踪符号、调用者、数据流、配置、测试和集成点。",
+    "",
+    "请根据用户要求的探索深度调整工作量：",
+    "",
+    "- **quick**：定位最可能的文件、符号或定义，并直接回答；",
+    "- **medium**：检查主要实现、重要调用方和附近测试；",
+    "- **very thorough**：搜索多种命名约定和目录位置，追踪数据流和集成关系，检查测试与配置，并协调相互冲突的证据。",
+    "",
+    "工作指南：",
+    "",
+    "- 当位置不确定时，先从宽范围开始，再直接读取最相关的文件；",
+    "- 知道具体路径时使用 safe-read；",
+    "- 只做只读检查；git 工具是固定 argv，不是任意 shell；",
+    "- 根据请求的探索深度调整搜索策略；第一次查询不足时切换方法；",
+    "- 高效使用彼此独立的 grep、find、ls 和 read 操作；可能时并行执行独立搜索；",
+    "- 在 medium 或 very thorough 探索中，每完成一个有意义的阶段，以及每使用约 8–12 轮工具后，输出一到两句简短阶段说明。说明当前已经确认的事实、下一步准备检查的内容以及是否存在阻塞，然后继续工作。不要等到最终报告时才暴露所有进展；",
+    "- 在最终回答中汇报发现，不要创建报告文件。",
+    "",
+    "返回清晰的发现结果，并提供相关绝对路径和行号范围。将已确认事实与推断分开，并明确指出尚未解决的问题。",
+].join("\n");
+export const AGENT_TOOL_DESCRIPTION = "Start the built-in read-only Explore subagent for codebase search, symbol lookup, and call-chain tracing. One call launches one Fresh one-shot Explore session. Do not pass tasks, model, cwd, isolation, or run_in_background.";
+export const AGENT_TOOL_PROMPT_SNIPPET = "Agent: launch built-in read-only Explore (Fresh, one-shot). Not for known single-file reads.";
+export const AGENT_TOOL_PROMPT_GUIDELINES = Object.freeze([
+    "Delegate codebase exploration, cross-directory search, call-chain tracing, and path-uncertain repo questions to Agent (Explore).",
+    "Brief must include the goal, known clues, exclusions, success criteria, and thoroughness (quick | medium | very thorough).",
+    "Do not delegate a known single-file read or single-symbol lookup; use read/grep/find directly.",
+    "Call Agent multiple times in one turn for non-overlapping questions; do not pack unrelated questions into one prompt. Do not pass tasks.",
+    "Treat Explore output as advisory evidence; synthesize before answering. Never delegate DAG writes, Human Gate, or operator mutations.",
+]);
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    return value;
+}
+function readTrimmedString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}
+function detectThoroughness(prompt) {
+    const lower = prompt.toLowerCase();
+    if (/\bvery\s+thorough\b/.test(lower) || lower.includes("非常彻底")) {
+        return "very thorough";
+    }
+    if (/\bmedium\b/.test(lower) || lower.includes("中等"))
+        return "medium";
+    if (/\bquick\b/.test(lower) || lower.includes("快速"))
+        return "quick";
+    return undefined;
+}
+export function parseExploreAgentParams(raw) {
+    const record = asRecord(raw);
+    if (!record) {
+        return {
+            ok: false,
+            code: "invalid-params",
+            message: "Agent requires an object with description and prompt",
+        };
+    }
+    for (const key of FORBIDDEN_OPTION_KEYS) {
+        if (!Object.prototype.hasOwnProperty.call(record, key))
+            continue;
+        const value = record[key];
+        if (value === undefined || value === null)
+            continue;
+        if (key === "tasks") {
+            return {
+                ok: false,
+                code: "tasks-not-supported",
+                message: "Agent tasks[] fan-out is not supported in this slice; call Agent once per independent Explore",
+            };
+        }
+        return {
+            ok: false,
+            code: "unsupported-option",
+            message: `Agent option "${key}" is not supported for Console Explore`,
+        };
+    }
+    const description = readTrimmedString(record.description);
+    const prompt = readTrimmedString(record.prompt);
+    if (!description || !prompt) {
+        return {
+            ok: false,
+            code: "invalid-params",
+            message: "Agent requires non-empty description and prompt",
+        };
+    }
+    const subagentRaw = record.subagent_type ?? record.subagentType;
+    const subagentType = readTrimmedString(subagentRaw) ?? EXPLORE_AGENT_NAME;
+    if (subagentType !== EXPLORE_AGENT_NAME) {
+        return {
+            ok: false,
+            code: "unknown-subagent-type",
+            message: `unknown subagent_type "${subagentType}"; only Explore is built in`,
+        };
+    }
+    const thoroughness = detectThoroughness(prompt);
+    const request = {
+        description,
+        prompt,
+        subagentType: EXPLORE_AGENT_NAME,
+        ...(thoroughness ? { thoroughness } : {}),
+    };
+    return { ok: true, request };
+}
+export function boundExploreText(text) {
+    const lines = text.split(/\r?\n/);
+    const clipped = lines.length > EXPLORE_RESULT_MAX_LINES
+        ? `${lines.slice(0, EXPLORE_RESULT_MAX_LINES).join("\n")}\n…[truncated ${lines.length - EXPLORE_RESULT_MAX_LINES} lines]`
+        : text;
+    if (Buffer.byteLength(clipped, "utf8") <= EXPLORE_RESULT_MAX_BYTES) {
+        return clipped;
+    }
+    let out = clipped;
+    while (Buffer.byteLength(out, "utf8") > EXPLORE_RESULT_MAX_BYTES && out.length > 0) {
+        out = out.slice(0, Math.max(0, Math.floor(out.length * 0.9)));
+    }
+    return `${out}\n…[truncated to ${EXPLORE_RESULT_MAX_BYTES} bytes]`;
+}
+export function buildExploreResult(input) {
+    return {
+        schemaVersion: EXPLORE_RESULT_SCHEMA_VERSION,
+        kind: EXPLORE_RESULT_KIND,
+        agent: EXPLORE_AGENT_NAME,
+        status: input.status,
+        description: input.description,
+        runId: input.runId,
+        ...(input.result !== undefined
+            ? { result: boundExploreText(input.result) }
+            : {}),
+        ...(input.error !== undefined ? { error: input.error } : {}),
+        ...(input.usage ? { usage: input.usage } : {}),
+    };
+}

package/dist/worker/console/chat/subagents/index.js

@@ -0,0 +1,5 @@
+export { AGENT_TOOL_DESCRIPTION, AGENT_TOOL_PROMPT_GUIDELINES, AGENT_TOOL_PROMPT_SNIPPET, EXPLORE_SYSTEM_PROMPT, boundExploreText, buildExploreResult, parseExploreAgentParams, } from "./explore-agent.js";
+export { buildAgentCustomTool } from "./agent-tool.js";
+export { ExploreOrchestrator } from "./orchestrator.js";
+export { EXPLORE_ALLOWED_TOOLS, EXPLORE_CHILD_RESOURCE_LOADER_OPTIONS, EXPLORE_EXCLUDE_TOOLS, extrasOutsideExploreAllowlist, filterExploreCustomTools, isExploreAllowedTool, pinExploreToolNames, } from "./tool-policy.js";
+export { EXPLORE_AGENT_NAME, OPERATOR_CHAT_AGENT_TOOL_NAME, } from "./types.js";

package/dist/worker/console/chat/subagents/orchestrator.js

@@ -0,0 +1,273 @@
+/**
+ * Fresh one-shot Explore child sessions for Operator Chat.
+ *
+ * Registry is a Map (never a singleton currentExplore) so two Agent calls in
+ * the same parent turn stay independently abortable. Child sessions use an
+ * in-memory SessionManager and a closed resource surface: no extensions,
+ * no operator tools, no write/bash.
+ */
+import { randomBytes } from "node:crypto";
+import { extractAssistantText } from "../assistant-content.js";
+import { buildExploreResult, EXPLORE_SYSTEM_PROMPT, } from "./explore-agent.js";
+import { EXPLORE_ALLOWED_TOOLS, EXPLORE_CHILD_RESOURCE_LOADER_OPTIONS, EXPLORE_EXCLUDE_TOOLS, extrasOutsideExploreAllowlist, filterExploreCustomTools, pinExploreToolNames, } from "./tool-policy.js";
+const EXPLORE_IDLE_TIMEOUT_MS = 180_000;
+function newExploreRunId() {
+    return `explore-${randomBytes(8).toString("hex")}`;
+}
+async function waitForChildIdle(session, signal) {
+    const start = Date.now();
+    while (true) {
+        if (signal?.aborted)
+            return { timedOut: false };
+        if (session.isIdle === true)
+            return { timedOut: false };
+        if (session.isStreaming === false)
+            return { timedOut: false };
+        if (Date.now() - start > EXPLORE_IDLE_TIMEOUT_MS)
+            return { timedOut: true };
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+}
+export class ExploreOrchestrator {
+    options;
+    runs = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    liveCount() {
+        return this.runs.size;
+    }
+    liveRunIds() {
+        return [...this.runs.keys()];
+    }
+    async abortAll() {
+        const live = [...this.runs.values()];
+        await Promise.all(live.map((run) => run.abort().catch(() => undefined)));
+    }
+    /** Abort only the runs launched by one parent session (Stop must never
+     *  kill another session's live Explore — exec-plan acceptance #7). */
+    async abortByParent(parentSessionId) {
+        const mine = [...this.runs.values()].filter((run) => run.parentSessionId === parentSessionId);
+        await Promise.all(mine.map((run) => run.abort().catch(() => undefined)));
+    }
+    async launch(input) {
+        if (input.signal?.aborted) {
+            return buildExploreResult({
+                status: "aborted",
+                description: input.request.description,
+                runId: newExploreRunId(),
+                error: "Explore aborted before start",
+            });
+        }
+        const runId = newExploreRunId();
+        const { cwd, bindings } = this.options;
+        let session;
+        let unsub;
+        let output = "";
+        let turns = 0;
+        let toolCalls = 0;
+        let promptError;
+        let abortPromise;
+        let settled = false;
+        let idleTimedOut = false;
+        /** True once abortChild ran — an abort without a parent signal (dispose
+         *  path) must still converge to status=aborted, never a hollow
+         *  "completed" with whatever partial text the SDK flushed. */
+        let childAborted = false;
+        const disposeChild = async () => {
+            unsub?.();
+            unsub = undefined;
+            try {
+                await session?.abort?.();
+            }
+            catch {
+                // ignore
+            }
+            try {
+                session?.dispose();
+            }
+            catch {
+                // ignore
+            }
+            session = undefined;
+            this.runs.delete(runId);
+        };
+        const abortChild = async () => {
+            if (abortPromise) {
+                await abortPromise;
+                return;
+            }
+            childAborted = true;
+            abortPromise = (async () => {
+                try {
+                    await session?.abort?.();
+                }
+                catch {
+                    // ignore
+                }
+            })();
+            await abortPromise;
+        };
+        this.runs.set(runId, {
+            runId,
+            parentSessionId: input.parentSessionId,
+            description: input.request.description,
+            status: "starting",
+            startedAt: Date.now(),
+            abort: abortChild,
+        });
+        const onParentAbort = () => {
+            void abortChild();
+        };
+        input.signal?.addEventListener("abort", onParentAbort);
+        try {
+            if (!bindings.createInMemorySessionManager) {
+                return buildExploreResult({
+                    status: "failed",
+                    description: input.request.description,
+                    runId,
+                    error: "Explore requires an in-memory SessionManager",
+                });
+            }
+            const agentDir = await bindings.getAgentDir();
+            const { services } = await bindings.createServices({
+                cwd,
+                agentDir,
+                resourceLoaderOptions: {
+                    ...EXPLORE_CHILD_RESOURCE_LOADER_OPTIONS,
+                    systemPrompt: EXPLORE_SYSTEM_PROMPT,
+                },
+            });
+            const sessionManager = await bindings.createInMemorySessionManager({
+                cwd,
+            });
+            const safeTools = await this.options.loadSafeExploreCustomTools();
+            const customTools = filterExploreCustomTools(safeTools);
+            const resolvedModel = input.model ??
+                ((await this.options.resolveModel?.(services.modelRuntime)) ??
+                    undefined);
+            const created = await bindings.createSessionFromServices({
+                services,
+                sessionManager,
+                tools: [...EXPLORE_ALLOWED_TOOLS],
+                excludeTools: [...EXPLORE_EXCLUDE_TOOLS],
+                customTools,
+                ...(resolvedModel ? { model: resolvedModel } : {}),
+            });
+            session = created.session;
+            session.setActiveToolsByName(pinExploreToolNames());
+            const leaked = extrasOutsideExploreAllowlist(session.getActiveToolNames());
+            if (leaked.length > 0) {
+                return buildExploreResult({
+                    status: "failed",
+                    description: input.request.description,
+                    runId,
+                    error: `Explore child received forbidden tools: ${leaked.join(", ")}`,
+                });
+            }
+            const live = this.runs.get(runId);
+            if (live)
+                live.status = "working";
+            unsub = session.subscribe((event) => {
+                if (event.type === "agent_start")
+                    turns += 1;
+                if (event.type === "tool_execution_start")
+                    toolCalls += 1;
+                if (event.type === "message_end") {
+                    output = extractAssistantText(event.message);
+                }
+            });
+            if (input.signal?.aborted) {
+                await abortChild();
+                return buildExploreResult({
+                    status: "aborted",
+                    description: input.request.description,
+                    runId,
+                    error: "Explore aborted",
+                    usage: { turns, toolCalls },
+                });
+            }
+            try {
+                await session.prompt(input.request.prompt, {
+                    signal: input.signal,
+                });
+                const idle = await waitForChildIdle(session, input.signal);
+                idleTimedOut = idle.timedOut;
+            }
+            catch (error) {
+                if (input.signal?.aborted) {
+                    promptError = "Explore aborted";
+                }
+                else {
+                    promptError = error instanceof Error ? error.message : String(error);
+                }
+            }
+            if (abortPromise)
+                await abortPromise.catch(() => undefined);
+            settled = true;
+            if (childAborted || input.signal?.aborted) {
+                return buildExploreResult({
+                    status: "aborted",
+                    description: input.request.description,
+                    runId,
+                    error: "Explore aborted",
+                    usage: { turns, toolCalls },
+                });
+            }
+            if (promptError) {
+                return buildExploreResult({
+                    status: "failed",
+                    description: input.request.description,
+                    runId,
+                    error: promptError,
+                    usage: { turns, toolCalls },
+                });
+            }
+            if (idleTimedOut) {
+                // The turn itself finished but a continuation (auto-compaction /
+                // follow-up) never settled within the idle budget. Never report a
+                // partial transcript as a clean completion.
+                return buildExploreResult({
+                    status: "failed",
+                    description: input.request.description,
+                    runId,
+                    error: `Explore idle timeout after ${EXPLORE_IDLE_TIMEOUT_MS / 1000}s`,
+                    usage: { turns, toolCalls },
+                });
+            }
+            return buildExploreResult({
+                status: "completed",
+                description: input.request.description,
+                runId,
+                result: output,
+                usage: { turns, toolCalls },
+            });
+        }
+        catch (error) {
+            const aborted = childAborted || Boolean(input.signal?.aborted);
+            let message;
+            if (aborted) {
+                message = "Explore aborted";
+            }
+            else if (error instanceof Error) {
+                message = error.message;
+            }
+            else {
+                message = String(error);
+            }
+            return buildExploreResult({
+                status: aborted ? "aborted" : "failed",
+                description: input.request.description,
+                runId,
+                error: message,
+            });
+        }
+        finally {
+            input.signal?.removeEventListener("abort", onParentAbort);
+            if (!settled && abortPromise) {
+                await abortPromise.catch(() => undefined);
+            }
+            await disposeChild();
+        }
+    }
+}

package/dist/worker/console/chat/subagents/tool-policy.js

@@ -0,0 +1,53 @@
+/**
+ * Mechanical Explore child tool surface. Role prompts are not a sandbox:
+ * createSessionFromServices({ tools, excludeTools }) plus Gate-2 pin must
+ * actually withhold write/bash/operator/extension tools.
+ */
+export const EXPLORE_ALLOWED_BUILTIN_TOOLS = Object.freeze(["find", "ls"]);
+export const EXPLORE_ALLOWED_CUSTOM_TOOLS = Object.freeze([
+    "safe-read",
+    "safe-grep",
+    "git-status",
+    "git-diff",
+]);
+export const EXPLORE_ALLOWED_TOOLS = Object.freeze([
+    ...EXPLORE_ALLOWED_BUILTIN_TOOLS,
+    ...EXPLORE_ALLOWED_CUSTOM_TOOLS,
+]);
+/** Defense-in-depth exclusions even if an SDK default would register them. */
+export const EXPLORE_EXCLUDE_TOOLS = Object.freeze([
+    "write",
+    "edit",
+    "bash",
+    "read",
+    "grep",
+    "apply_patch",
+    "apply-patch",
+    "full-tools",
+    "full_tools",
+    "coding-chat",
+    "coding_chat",
+    "shell",
+    "Agent",
+]);
+const ALLOWED_LOWER = new Set(EXPLORE_ALLOWED_TOOLS.map((name) => name.toLowerCase()));
+export function isExploreAllowedTool(toolId) {
+    return ALLOWED_LOWER.has(toolId.trim().toLowerCase());
+}
+export function pinExploreToolNames() {
+    return [...EXPLORE_ALLOWED_TOOLS];
+}
+export function extrasOutsideExploreAllowlist(activeToolNames) {
+    return activeToolNames.filter((name) => !isExploreAllowedTool(name));
+}
+export function filterExploreCustomTools(tools) {
+    return tools.filter((tool) => {
+        const name = tool?.name;
+        return typeof name === "string" && isExploreAllowedTool(name);
+    });
+}
+export const EXPLORE_CHILD_RESOURCE_LOADER_OPTIONS = Object.freeze({
+    noExtensions: true,
+    noPromptTemplates: true,
+    noThemes: true,
+});

package/dist/worker/console/chat/subagents/types.js

@@ -0,0 +1,13 @@
+/**
+ * Console Chat built-in Explore subagent contracts (ADR 0022).
+ *
+ * First slice: one Agent tool call = one Fresh, read-only, one-shot Explore
+ * child session. `tasks[]` fan-out is rejected here and reserved for a later
+ * plan. The registry is a Map so concurrent parent-turn runs stay possible.
+ */
+export const EXPLORE_AGENT_NAME = "Explore";
+export const OPERATOR_CHAT_AGENT_TOOL_NAME = "Agent";
+export const EXPLORE_RESULT_SCHEMA_VERSION = 1;
+export const EXPLORE_RESULT_KIND = "subagent";
+export const EXPLORE_RESULT_MAX_BYTES = 200 * 1024;
+export const EXPLORE_RESULT_MAX_LINES = 5_000;

package/dist/worker/console/chat/tool-preview.js

@@ -93,6 +93,13 @@ function adapterPreview(toolName, input, maxLen) {
         const query = fieldString(input, "query") ?? fieldString(input, "symbol");
         return query ? clampOneLine(query, maxLen) : undefined;
     }
+    if (name === "agent") {
+        const description = fieldString(input, "description");
+        const subagent = fieldString(input, "subagent_type") ?? "Explore";
+        if (description)
+            return clampOneLine(`${subagent} · ${description}`, maxLen);
+        return clampOneLine(subagent, maxLen);
+    }
     if (name === "read" ||
         name === "read_symbol" ||
         name === "read_enclosing" ||
@@ -181,6 +188,9 @@ export function getToolPresentation(toolName) {
     if (name === "mcp" || name.startsWith("mcp_") || name.includes("__")) {
         return { kind: "mcp", label: name === "mcp" ? "MCP" : raw };
     }
+    if (name === "agent") {
+        return { kind: "search", label: "Explore" };
+    }
     return { kind: "tool", label: raw };
 }
 /** Section labels for ToolCard expand body. */