@tencent-ai/agent-harness 0.2.0-beta.7 → 0.2.0-beta.8

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/mods/types/events/tool.d.ts

@@ -0,0 +1,308 @@
+/**
+ * `types/events/tool.ts`
+ *
+ * Precise `tool.*` event shapes: `tool.call`, `tool.check`, `tool.describe`.
+ *
+ * cbc's own tool set fills `BuiltinToolInputs` / `BuiltinToolResults` via
+ * declaration merging from the agent-cli side; this file only declares the
+ * envelopes and the generic types that narrow off `e.tool`.
+ *
+ * This is one of the "one-namespace-at-a-time" exemplar files establishing
+ * the pattern for the full alignment work (see the plan file). Every field
+ * mirrors upstream shape so mods written against `claude-code` type-check
+ * against `codebuddy-code` unchanged after the import specifier is renamed.
+ */
+import type { Origin } from '../events.js';
+/**
+ * The engine's built-in tools, keyed by the name the model calls them by. A
+ * host — the cbc agent-cli, a plugin's `$.tool.register`, another surface —
+ * augments this interface to register that tool's input schema:
+ *
+ * ```ts
+ * declare module 'codebuddy-code' {
+ *   interface BuiltinToolInputs {
+ *     Bash: { command: string; description?: string; timeout?: number };
+ *   }
+ * }
+ * ```
+ *
+ * Empty by default so any host can drop into a "tool set unknown" fallback
+ * without pulling the CLI's full tool catalog into every consumer. Real
+ * populate happens in agent-cli's tool registration barrel — see
+ * `packages/agent-cli/src/node/tools/**`.
+ */
+export interface BuiltinToolInputs {
+}
+/**
+ * The engine's built-in tools, keyed by the name the model calls them by,
+ * mapped to their structured `result` (what the transcript stores). Same
+ * augmentation model as `BuiltinToolInputs`.
+ */
+export interface BuiltinToolResults {
+}
+/**
+ * The name of a built-in tool (keys of `BuiltinToolInputs`), as a string
+ * literal union; `never` when no host has augmented the table.
+ */
+export type BuiltinToolName = keyof BuiltinToolInputs & string;
+/**
+ * Fallback when the built-in table is empty (no host has populated it): the
+ * envelope keeps its identity but arguments are untyped.
+ */
+export interface BuiltinToolCallInputFallback {
+    tool: string;
+    tool_use_id: string;
+    consent?: string;
+    [arg: string]: unknown;
+}
+/**
+ * The union of `{ tool, tool_use_id, ...args }` records for every built-in
+ * tool, discriminated by `tool`. Falls back to a loose object when nothing
+ * has augmented `BuiltinToolInputs`.
+ */
+export type BuiltinToolCallInput = [BuiltinToolName] extends [never] ? BuiltinToolCallInputFallback : {
+    [K in BuiltinToolName]: {
+        tool: K;
+        tool_use_id: string;
+        consent?: string;
+    } & BuiltinToolInputs[K];
+}[BuiltinToolName];
+/**
+ * `{ tool, tool_use_id, ...args }` for an MCP tool call: the tool name is
+ * `mcp__<server>__<tool>` and arguments are what the model sent.
+ */
+export interface McpToolCallInput {
+    tool: `mcp__${string}__${string}`;
+    tool_use_id: string;
+    consent?: string;
+    [arg: string]: unknown;
+}
+/**
+ * The envelope `tool.call` and `classic.PreToolUse` share: the tool, the call
+ * id, and the tool's arguments spread beside them. A union discriminated by
+ * `tool`.
+ */
+export type ToolCallEnvelope = BuiltinToolCallInput | McpToolCallInput;
+/**
+ * Loop identity carried on every `tool.call` event: which agent's loop the
+ * call happened in (undefined on the main loop).
+ */
+export interface ToolAgentLoop {
+    agentId?: string;
+}
+/**
+ * The input of `tool.call`: the tool, id, args, plus the loop identity.
+ * `tool`, `tool_use_id`, `agentId` are reserved — a rewrite is refused.
+ */
+export type ToolCallInput = ToolCallEnvelope & ToolAgentLoop;
+/**
+ * The keys `tool.call`'s input carries beside the tool's own arguments.
+ * `consent` is the person's words for the press that raised the call.
+ */
+export interface ToolCallReserved<T> {
+    tool: T;
+    tool_use_id?: string;
+    consent?: string;
+}
+/**
+ * The structured result of the tool named `Name`: its `BuiltinToolResults`
+ * entry when known, else `unknown`.
+ */
+export type ToolResultOf<Name extends string> = string extends Name ? unknown : Name extends keyof BuiltinToolResults & string ? BuiltinToolResults[Name] : unknown;
+/**
+ * What a `tool.call` hook returns and what `next(e)` / `$.tool.call(input)`
+ * resolve to: the tool's result, or `{ deny }`.
+ */
+export type ToolCallResult<Name extends string = string> = {
+    /** Refuses the call: the model reads the text as an error result. */
+    deny: string;
+    result?: undefined;
+    context?: undefined;
+    ref?: undefined;
+    text?: undefined;
+    isError?: undefined;
+} | {
+    /** The tool's output, typed per tool once `Name` is narrowed. */
+    result: ToolResultOf<Name>;
+    /** Extra text the model reads after the result; the person never sees it. */
+    context?: readonly string[];
+    /** Set by core: names the messages produced for the call. */
+    ref?: number;
+    /** Set by core: the result as the model reads it (text blocks joined). */
+    text?: string;
+    isError?: undefined;
+    deny?: undefined;
+} | {
+    /** Set by core, present only when the tool reported an error. */
+    isError: true;
+    /** What the transcript stored on error: the error text, or undefined. */
+    result: unknown;
+    /** The error as the model reads it. */
+    text?: string;
+    /** As on an answered result: names the messages core produced. */
+    ref?: number;
+    /** As on an answered result. */
+    context?: readonly string[];
+    deny?: undefined;
+};
+/**
+ * `$.tool.call(input)`'s args as callers pass them: the call envelope minus
+ * the id (the engine sets it).
+ */
+export type ToolCallArgs = ToolCallEnvelope extends infer I ? I extends ToolCallEnvelope ? Omit<I, 'tool_use_id'> & ToolCallReserved<I['tool']> : never : never;
+/**
+ * An input that names its tool as the literal `T`: what `next` and
+ * `$.tool.call` read to type the call's result per tool.
+ */
+export interface ToolNamed<T extends string> {
+    readonly tool: T;
+}
+/**
+ * `{ tool, tool_use_id, ...args }` as one flat object type, generic over
+ * the tool name and its parsed arguments.
+ */
+export type ToolEnvelope<Name, Arguments> = {
+    /**
+     * The name of the tool being called (`Bash`, `mcp__<server>__<tool>`);
+     * comparing it narrows `e`. Reserved: a rewrite of it is ignored by core.
+     */
+    tool: Name;
+    /**
+     * The tool_use block's id: same at every event of the call and in `$.ui.notice`.
+     * Reserved: a rewrite of it is ignored by core.
+     */
+    tool_use_id: string;
+} & Arguments;
+/**
+ * `{ tool, tool_use_id, ...args }` as one flat object type. The docs of
+ * `tool` and `tool_use_id` live on the `keyof` operand: a mapped type takes
+ * its properties' docs from there.
+ */
+export type ToolInputOf<Name extends string, Arguments> = {
+    [K in keyof ToolEnvelope<Name, Arguments>]: ToolEnvelope<Name, Arguments>[K];
+};
+/**
+ * The overload set of `$.tool.call`: return type narrows on the tool name
+ * literal when the caller provides one.
+ */
+export interface ToolCallOverloads {
+    <T extends string>(input: ToolCallArgs & ToolNamed<T>): Promise<ToolCallResult<T>>;
+    (input: ToolCallArgs): Promise<ToolCallResult>;
+}
+/**
+ * The verdict of `tool.check`: run the tool (`allow`), put it to the mode's
+ * decider (`ask`), or refuse it (`deny`).
+ */
+export type ToolCheckDecision = 'allow' | 'ask' | 'deny';
+/**
+ * The input of `tool.check`: the tool, its arguments, and the call's id when
+ * the engine is deciding a real call (absent on a query).
+ *
+ * All three are the question's identity and are pinned: a hook decides
+ * about this call, it does not change it (`tool.call` rewrites a call).
+ */
+export interface ToolCheckInput {
+    /** As the model names it (`Bash`, `mcp__server__tool`). */
+    tool: string;
+    /** The tool's arguments as the permission decision reads them. */
+    input: unknown;
+    /** The call being decided, on a real call only; absent on a query. */
+    tool_use_id?: string;
+}
+/** `$.tool.check(args)`'s args: the tool + its input, no id. */
+export type ToolCheckArgs = Pick<ToolCheckInput, 'tool' | 'input'>;
+/**
+ * What a `tool.check` hook returns: the verdict, why, and the settings rule
+ * behind it when one decided.
+ */
+export interface ToolCheckResult {
+    /** `allow` runs the tool; `ask` puts it to the mode's decider; `deny` refuses it. */
+    decision: ToolCheckDecision;
+    /** Why, in a sentence. */
+    reason?: string;
+    /** The settings rule that decided, as written (`Bash(git push:*)`). */
+    rule?: string;
+}
+/**
+ * Where a `tool.describe` answer places the tool: `true` behind ToolSearch,
+ * `false` in the prompt's list. Left out of an answer, the placement stands.
+ */
+export type ToolDeferral = boolean;
+/**
+ * The input of `tool.describe`: one tool's description, at the moment the
+ * engine first renders the tool's schema for the model.
+ */
+export interface ToolDescribeInput {
+    /** As the model sees the name (`Bash`, `mcp__server__tool`). */
+    tool: string;
+    /** The tool's description as it computed it. */
+    description: string;
+    /** Present, and true, when the engine lists the tool behind ToolSearch. */
+    isDeferred?: true;
+    /** Who provides this tool: the plugin and its tier. Pinned. */
+    provider: Origin;
+}
+/**
+ * What a `tool.describe` hook returns: the description the model sees for
+ * that tool and, when the hook moves it, where the tool waits.
+ */
+export interface ToolDescribeResult {
+    description: string;
+    isDeferred?: ToolDeferral;
+}
+/**
+ * One tool as `$.tool.list()` returns it.
+ */
+export interface ToolInfo {
+    /** What the model calls it by. */
+    name: string;
+    /** What it does, in the tool's own words. */
+    description: string;
+    /** True for an MCP server's tool. */
+    mcp: boolean;
+}
+/**
+ * What `$.tool.register` takes.
+ */
+export interface ToolSpec {
+    /** The tool's short name (letters, digits, `_`, `-`; up to 64). */
+    name: string;
+    /** What the tool does, for the model. */
+    description: string;
+    /** A JSON schema object for the input; default `{ type: "object" }`. */
+    inputSchema?: Record<string, unknown>;
+}
+/**
+ * What `$.tool.register` resolves to: the registered name.
+ */
+export interface ToolRegisterResult {
+    tool: string;
+}
+/**
+ * One tool_use block of an assistant message.
+ */
+export interface ToolUseSummary {
+    /** The call's id. */
+    tool_use_id: string;
+    /** Which tool was called. */
+    tool: string;
+    /** The arguments the model gave it. */
+    input: Record<string, unknown>;
+    /** What the transcript stored on an answered call, or the error text. */
+    result?: unknown;
+    /** True when the tool reported an error. */
+    isError?: boolean;
+}
+/**
+ * One tool_result block of a user message.
+ */
+export interface ToolResultSummary {
+    /** The id of the call this result answers. */
+    tool_use_id: string;
+    /** The result as the model read it (text blocks joined). */
+    text: string;
+    /** True when the tool reported an error. */
+    isError: boolean;
+    /** What the transcript stored for the call. */
+    result?: unknown;
+}