@cerebriline/core 4.100.240

package/dist/extensions/tools/team/batch-report.d.ts

@@ -0,0 +1,151 @@
+import type { AgentOracleResult } from "./agent-check";
+import { type MemberUsage } from "./token-split";
+/**
+ * The most the whole result may take, in characters of its JSON.
+ *
+ * The transcript sends at most 32,000 characters of one tool result; this
+ * leaves room for the wrapping the provider adds and for estimates that run
+ * short.
+ */
+export declare const SPAWN_BATCH_RESULT_BUDGET_CHARS = 28000;
+/** The longest index line per agent, before the index has to shrink. */
+export declare const SPAWN_BATCH_INDEX_LINE_CHARS = 120;
+/**
+ * `awaiting_lead`: stopped at its iteration cap and still waiting, work kept --
+ * only when nothing could ask the lead while the round ran.
+ */
+export type SpawnBatchStatus = "completed" | "errored" | "cancelled" | "awaiting_lead";
+/**
+ * Whose failure it was. `infra` is the transport, a refusal or the server --
+ * nothing the agent did, and worth trying again as is. `task` is the model,
+ * a tool or the iteration budget -- the job itself did not get done.
+ */
+export type SpawnBatchFailureClass = "infra" | "task";
+/** What one agent of the round came back with, as the batch sees it. */
+export interface SpawnBatchMemberResult {
+    name: string;
+    /** Configured agent type, when the entry named one. */
+    type?: string;
+    text?: string;
+    finishReason?: string;
+    iterations?: number;
+    usage?: Partial<MemberUsage>;
+    /** Set when the agent could not be run or threw. */
+    error?: string;
+    /** Its own id, for `resume_agent` and the status tool. */
+    agentId?: string;
+    maxIterations?: number;
+    stopReason?: "iteration_cap" | "loop_guard" | "supervisor" | "wrap_up";
+    state?: "awaiting_lead";
+    oracle?: AgentOracleResult;
+    /**
+     * Times the engine evicted it and it was sent again. Each one is an
+     * engine bug: no session is ever meant to be evicted.
+     */
+    evicted?: number;
+    /** Its id in the round (`r2-3`), what the lead's controls take. */
+    id?: string;
+    /** Why it stopped, in the round's taxonomy. */
+    stop?: string;
+    /**
+     * State, stop reason, iterations, tokens, compactions, check, sampler and
+     * node, on one line (section F of the lead-control spec).
+     */
+    facts?: string;
+}
+export interface SpawnBatchIndexEntry {
+    /** Its id in the round, for `agents_status` and the controls. */
+    id?: string;
+    name: string;
+    status: SpawnBatchStatus;
+    failureClass?: SpawnBatchFailureClass;
+    /** One line: the start of its summary, or what went wrong. */
+    line?: string;
+    /** For an agent that did not complete: why, short. */
+    error?: string;
+    /** Iterations used, and the cap, where there is one. */
+    iterations?: number;
+    maxIterations?: number;
+    /** `iteration_cap` when the cap is what ended it. */
+    stopReason?: "iteration_cap" | "loop_guard" | "supervisor" | "wrap_up";
+    /** For an agent waiting at its cap: the id to resume it by. */
+    agentId?: string;
+    /** Its check's verdict in a word: `pass`, `fail (exit N)`, `not run: why`. */
+    oracle?: string;
+    /** Times the engine evicted it, when it did. */
+    evicted?: number;
+    /** Why it stopped, in the round's taxonomy. */
+    stop?: string;
+}
+export interface SpawnBatchSummary {
+    total: number;
+    completed: number;
+    errored: number;
+    cancelled: number;
+    /** Stopped at the iteration cap and waiting on you; see `agents`. */
+    awaitingLead: number;
+    /** Per configured type, or per name with its `-<n>` copy suffix dropped. */
+    byType: Record<string, {
+        total: number;
+        completed: number;
+        errored: number;
+        cancelled: number;
+    }>;
+    byFailureClass: {
+        infra: number;
+        task: number;
+    };
+    /**
+     * Engine evictions across the round, every agent's summed. Each one is an
+     * engine bug and was retried; stated even at 0, so its absence says so.
+     */
+    evicted: number;
+    totalIterations: number;
+    /** `cached` and `fresh` split `input`; absent when no agent reported a cache figure. */
+    totalTokens: {
+        input: number;
+        output: number;
+        cached?: number;
+        fresh?: number;
+    };
+}
+export interface SpawnBatchReport {
+    /** What the harness changed about the call while reading it. */
+    notes?: string[];
+    summary: SpawnBatchSummary;
+    /** What every agent ran on, when it is the same: left out of each `facts`. */
+    ranOn?: string;
+    /**
+     * One per agent, in the order asked for. An object normally; for a round
+     * too large for that, `name|status` or `name|status|failureClass`.
+     */
+    agents: Array<SpawnBatchIndexEntry | string>;
+    reports: Array<{
+        name: string;
+        /** Its id in the round (`r2-3`). */
+        id?: string;
+        /** Section F's facts on one line. */
+        facts?: string;
+        text: string;
+        /** Its check, with the end of the output, when one was set. */
+        oracle?: Pick<AgentOracleResult, "status" | "exitCode" | "output"> & {
+            reason?: string;
+        };
+    }>;
+    /** The round this call opened: its id, for `agents_status` and `retry_failed`. */
+    round?: string;
+    notShown?: {
+        names: string[];
+        note: string;
+    };
+    usage: MemberUsage;
+}
+/** Whose failure an agent's was; see {@link SpawnBatchFailureClass}. */
+export declare function failureClassOf(result: SpawnBatchMemberResult): SpawnBatchFailureClass | undefined;
+/**
+ * Build the round's result within {@link SPAWN_BATCH_RESULT_BUDGET_CHARS}.
+ *
+ * `sessionId` is the lead's: a report left out is filed there, so
+ * `read_agent_report` finds it by the name the result gives.
+ */
+export declare function buildSpawnBatchReport(results: readonly SpawnBatchMemberResult[], sessionId: string | undefined, budget?: number, round?: string): SpawnBatchReport;

package/dist/extensions/tools/team/configured-agent-config.d.ts

@@ -0,0 +1,37 @@
+export interface ConfiguredAgentConfig {
+    name: string;
+    description: string;
+    tools?: string[];
+    skills?: string[];
+    providerId?: string;
+    modelId?: string;
+    /** A saved API configuration profile this agent runs on, by name. */
+    profile?: string;
+    maxIterations?: number;
+    systemPrompt: string;
+    path?: string;
+}
+export interface ConfiguredAgentReadError {
+    path: string;
+    error: Error;
+}
+export interface ConfiguredAgentLoadResult {
+    configs: ConfiguredAgentConfig[];
+    errors: ConfiguredAgentReadError[];
+    /**
+     * The directories that were looked in, whether or not they exist.
+     *
+     * Returned so the caller can say where it looked. A user who has turned
+     * subagents on and written no agent file gets no tool and no error -- there
+     * is nothing wrong to report -- and "none found, looked in these two places"
+     * is the difference between that and a feature that appears broken.
+     */
+    searchPaths: string[];
+}
+export declare function parseConfiguredAgentConfig(content: string, options?: {
+    path?: string;
+}): ConfiguredAgentConfig;
+export declare function loadConfiguredAgentConfigs(input: {
+    workspaceRoot?: string;
+    searchPaths?: string[];
+}): ConfiguredAgentLoadResult;

package/dist/extensions/tools/team/configured-agent-tool.d.ts

@@ -0,0 +1,135 @@
+import { type AgentEvent, type AgentTool, type AgentToolContext, type BasicLogger, type HookErrorMode, type ToolApprovalRequest, type ToolApprovalResult, type ToolPolicy } from "@cerebriline/shared";
+import { z } from "zod";
+import type { OracleSpawnWrapper } from "../../../runtime/atomic/oracle";
+import type { ConfiguredAgentConfig } from "./configured-agent-config";
+import { type DelegatedAgentConfigProvider, type DelegatedAgentRuntimeConfig } from "./delegated-agent";
+import { type SubAgentEndContext, type SubAgentSettledContext, type SubAgentStartContext } from "./spawn-agent-tool";
+declare const ConfiguredAgentInputSchema: z.ZodObject<{
+    wait: z.ZodOptional<z.ZodBoolean>;
+    check: z.ZodOptional<z.ZodObject<{
+        command: z.ZodString;
+        expect: z.ZodString;
+        must: z.ZodOptional<z.ZodEnum<{
+            match: "match";
+            not_match: "not_match";
+        }>>;
+    }, z.core.$strip>>;
+    temperature: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"random">]>>;
+    seed: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"random">]>>;
+    temperature_range: z.ZodOptional<z.ZodNumber>;
+    prompt: z.ZodString;
+}, z.core.$strip>;
+export type ConfiguredAgentInput = z.infer<typeof ConfiguredAgentInputSchema>;
+export interface ConfiguredAgentToolDescriptor {
+    toolName: string;
+    config: ConfiguredAgentConfig;
+}
+/**
+ * The connection a provider other than the session's runs on.
+ *
+ * Supplied by the host because only the host knows where its provider store
+ * lives: the CLI's follows `--config`, and the extension's follows its own data
+ * directory, so core reaching for a default path would read the wrong file in
+ * one of them and silently call the wrong server with the wrong key.
+ */
+export interface AgentProviderConnection {
+    apiKey?: string;
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    providerConfig?: unknown;
+    knownModels?: DelegatedAgentRuntimeConfig["knownModels"];
+}
+/**
+ * A saved API configuration profile, resolved.
+ *
+ * Carries the provider and the model as well as the connection, because that is
+ * what a profile is: the user picked a provider, a model and the settings around
+ * them and gave the three of them a name. An agent naming a profile is therefore
+ * saying more than an agent naming a provider, and gets the model with it.
+ */
+export interface AgentProfileConnection extends AgentProviderConnection {
+    providerId: string;
+    modelId?: string;
+}
+export interface ConfiguredAgentToolConfig {
+    /**
+     * Optional logger, for the things only the log can carry.
+     *
+     * Specifically a node that could not run an agent at all: the agent is
+     * re-queued elsewhere and succeeds, so the run looks clean, and without a
+     * line here the misconfigured node is invisible until someone counts the
+     * spawns.
+     */
+    logger?: BasicLogger;
+    configProvider: DelegatedAgentConfigProvider;
+    agents: ConfiguredAgentConfig[];
+    /**
+     * Resolves a second provider's own connection, for an agent whose
+     * frontmatter names one.
+     *
+     * Without it an agent on another provider is refused rather than run: it
+     * used to inherit the lead's base URL, key and context window along with the
+     * new provider id, which is a request to the wrong server that fails as an
+     * auth error or, worse, succeeds against a model nobody chose.
+     */
+    resolveProviderConnection?: (providerId: string) => AgentProviderConnection | undefined;
+    /**
+     * Resolves a saved API configuration profile by name, for an agent whose
+     * frontmatter names one.
+     *
+     * Host-supplied for the same reason as the provider resolver: only the host
+     * knows where its profiles live. A host with no profiles at all supplies
+     * nothing, and an agent naming one is refused rather than run on the
+     * session's connection under a name the user chose for something else.
+     */
+    resolveProfileConnection?: (name: string) => AgentProfileConnection | undefined;
+    /**
+     * The profile names this host currently has, for the refusal message.
+     *
+     * A profile can be deleted long after an agent was written to name it, and
+     * the agent file is not rewritten when that happens. Being told the name is
+     * unresolvable answers "what went wrong" and not "what do I put instead",
+     * which is the question the user is actually left holding.
+     */
+    listProfileNames?: () => string[];
+    createSubAgentTools?: (agent: ConfiguredAgentConfig, input: ConfiguredAgentInput, context: AgentToolContext) => AgentTool[] | Promise<AgentTool[]>;
+    onSubAgentEvent?: (event: AgentEvent) => void;
+    hookErrorMode?: HookErrorMode;
+    toolPolicies?: Record<string, ToolPolicy>;
+    requestToolApproval?: (request: ToolApprovalRequest) => Promise<ToolApprovalResult> | ToolApprovalResult;
+    onSubAgentStart?: (context: SubAgentStartContext) => void | Promise<void>;
+    onSubAgentEnd?: (context: SubAgentEndContext) => void | Promise<void>;
+    /** See `SpawnAgentToolConfig.onSubAgentSettled`. */
+    onSubAgentSettled?: (context: SubAgentSettledContext) => void | Promise<void>;
+    /** See `SpawnAgentToolConfig.commandSandboxFor`: where its check runs. */
+    commandSandboxFor?: (toolCallId: string | undefined) => {
+        wrapSpawn: OracleSpawnWrapper;
+        cwd: string;
+    } | undefined;
+    /**
+     * The lead's session, when the tools are built for one: a call opens a
+     * round there, and `retry_failed` can run the agent again from it.
+     */
+    sessionId?: string;
+}
+export declare function buildConfiguredAgentToolName(agentName: string): string;
+export declare function buildConfiguredAgentToolDescriptors(agents: readonly ConfiguredAgentConfig[]): ConfiguredAgentToolDescriptor[];
+/**
+ * The connection one configured agent runs on.
+ *
+ * Two cases, and only the first used to work. An agent that names a *model*
+ * inherits the session's connection and swaps the model — including inside
+ * `providerConfig`, which carries its own copy that the gateway reads, and
+ * which left the request naming one model at the top level and another
+ * underneath.
+ *
+ * An agent that names a *provider* needs that provider's own credentials, base
+ * URL, catalog and context window. Inheriting the session's meant a request to
+ * the wrong server with the wrong key, which is what "we have multiple
+ * providers that I would like to create agents to handle specific tasks" ran
+ * into. The host's proxy/CA-aware `fetch` is carried across from the session's
+ * config either way: it belongs to the process, not to the provider.
+ */
+export declare function buildAgentRuntimeConfig(base: DelegatedAgentRuntimeConfig, agent: ConfiguredAgentConfig, resolveProviderConnection?: (providerId: string) => AgentProviderConnection | undefined, resolveProfileConnection?: (name: string) => AgentProfileConnection | undefined, listProfileNames?: () => string[]): DelegatedAgentRuntimeConfig;
+export declare function createConfiguredAgentTools(options: ConfiguredAgentToolConfig): AgentTool[];
+export {};

package/dist/extensions/tools/team/create-agent-tool.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `create_agent` -- the model writes an agent file.
+ *
+ * "Create an agent for software engineering and one for network
+ * troubleshooting" is a reasonable thing to ask for and, until this tool, an
+ * impossible one: the format is documented nowhere the model can read, the
+ * directory is not somewhere it would guess, and the VS Code editor that knows
+ * both is reachable only by a human with a mouse.
+ *
+ * A tool rather than a skill because skills have to be installed by hand --
+ * `resolveSkillsConfigSearchPaths` looks only in the workspace and the Cline
+ * data directory -- so a skill that teaches this would need the user to already
+ * know the thing it was going to tell them.
+ */
+import { type AgentTool } from "@cerebriline/shared";
+import { z } from "zod";
+declare const CreateAgentInputSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    systemPrompt: z.ZodString;
+    scope: z.ZodOptional<z.ZodEnum<{
+        workspace: "workspace";
+        global: "global";
+    }>>;
+    profile: z.ZodOptional<z.ZodString>;
+    providerId: z.ZodOptional<z.ZodString>;
+    modelId: z.ZodOptional<z.ZodString>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    maxIterations: z.ZodOptional<z.ZodNumber>;
+    overwrite: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type CreateAgentInput = z.infer<typeof CreateAgentInputSchema>;
+export interface CreateAgentOutput {
+    path: string;
+    name: string;
+    scope: "workspace" | "global";
+    overwritten: boolean;
+    /** What the caller still has to do for the agent to be reachable. */
+    note: string;
+}
+export declare function createCreateAgentTool(options: {
+    workspaceRoot?: string;
+}): AgentTool;
+export {};

package/dist/extensions/tools/team/delegate-to-agent.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Delegation the *user* asked for, rather than delegation the model chose.
+ *
+ * A configured agent already reaches the model as a `subagent_<name>` tool, and
+ * the model decides whether to call it. That is the right default and the wrong
+ * only option: "run the QA agent on this" is an instruction, and a session
+ * where the lead model quietly does the work itself instead is not delegation,
+ * it is a suggestion that was declined.
+ *
+ * So the host runs the agent directly. The same tool object the model would
+ * have called is executed here, which is the point -- provider resolution,
+ * profile resolution, the per-agent skill and tool filtering and the endpoint
+ * slot gate are the ones the tool path already got right, and a second
+ * implementation of any of them would be a second thing to keep correct.
+ */
+import type { AgentHooks, AgentTool } from "@cerebriline/shared";
+import type { ConfiguredAgentConfig } from "./configured-agent-config";
+import { type DelegationEngineSessionBinder } from "./delegation-call-hooks";
+/** One configured agent, as a host needs to show it in a picker. */
+export interface ConfiguredAgentSummary {
+    name: string;
+    description: string;
+    /** The tool the model would call to reach this agent. */
+    toolName: string;
+    /** Where the agent runs, when it names somewhere other than the session. */
+    profile?: string;
+    providerId?: string;
+    modelId?: string;
+    skills?: string[];
+    /** The file it was read from, so a host can offer to open it. */
+    path?: string;
+}
+export interface ConfiguredAgentDelegationResult {
+    agentName: string;
+    toolName: string;
+    text: string;
+    iterations: number;
+    finishReason?: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /** Milliseconds the delegated run took, wall clock. */
+    durationMs: number;
+}
+export declare function listConfiguredAgentSummaries(agents: readonly ConfiguredAgentConfig[] | undefined): ConfiguredAgentSummary[];
+/**
+ * Resolve an agent by the name a user typed.
+ *
+ * Case-insensitive, because the name in a picker and the name in a command line
+ * are the same name to everyone except a string comparison.
+ */
+export declare function findConfiguredAgent(agents: readonly ConfiguredAgentConfig[] | undefined, name: string): ConfiguredAgentSummary | undefined;
+export declare class UnknownConfiguredAgentError extends Error {
+    readonly requested: string;
+    readonly available: readonly string[];
+    constructor(requested: string, available: readonly string[]);
+}
+export interface DelegateToConfiguredAgentInput {
+    agents: readonly ConfiguredAgentConfig[] | undefined;
+    /** The session's built tools, which already contain the `subagent_*` ones. */
+    tools: readonly AgentTool[];
+    agentName: string;
+    prompt: string;
+    sessionId?: string;
+    /** The lead agent's id, so the delegated run is parented to it. */
+    parentAgentId: string;
+    conversationId?: string;
+    signal?: AbortSignal;
+    /**
+     * Hooks for this run alone, on top of the session's.
+     *
+     * How a background delegation gets its pause barrier: the run is otherwise
+     * identical to a foreground one, and giving it a second code path to run
+     * down would be a second path to keep correct.
+     */
+    hooks?: AgentHooks;
+    /** Where the run binds the release of its engine session, for a pause. */
+    bindEngineSession?: DelegationEngineSessionBinder;
+    /**
+     * The id the run goes by as a tool call. The agent's sandbox, its
+     * hand-back and its stop button are all keyed on it; a background run
+     * passes the id it was registered under, a foreground one gets its own.
+     */
+    toolCallId?: string;
+}
+/**
+ * Run one configured agent on a task, on the host's say-so.
+ *
+ * Throws {@link UnknownConfiguredAgentError} for a name nobody has, and lets a
+ * failure inside the agent surface as itself: a delegated run that failed is
+ * not a delegation that did not happen, and flattening the two would hide which
+ * one the user is looking at.
+ */
+export declare function delegateToConfiguredAgent(input: DelegateToConfiguredAgentInput): Promise<ConfiguredAgentDelegationResult>;
+/**
+ * How a delegated run enters the conversation.
+ *
+ * As a user-role message rather than a synthesized tool call: the lead model
+ * never made a call, and manufacturing one would put a tool result in the
+ * transcript answering a request that was never sent -- which some providers
+ * reject outright and every reader of the transcript would misread. This says
+ * what actually happened, in the voice of the person it happened on behalf of.
+ */
+export declare function renderDelegationForTranscript(result: ConfiguredAgentDelegationResult, task: string): string;