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

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

@@ -0,0 +1,188 @@
+/**
+ * `types/events/agent.ts`
+ *
+ * Precise `agent.*` event shapes: `agent.spawn`, `agent.offer`, plus the
+ * op-facing types `AgentSpec` / `AgentInfo` / `AgentCallRecord` / `AgentLoop`.
+ *
+ * Field-for-field aligned with upstream so mods that read `e.subagentType`,
+ * `e.background`, `e.fork`, `e.parentModel`, `e.parentAgentId` etc. type-check
+ * unchanged after switching import specifier to `codebuddy-code`.
+ */
+import type { Origin } from '../events.js';
+/**
+ * What an Agent call a plugin raised answers as `result` once the agent
+ * settles; `text` is its final answer.
+ *
+ * A plugin's spawn always runs in the background, so the call resolves with
+ * this record and not the Agent tool's own `BuiltinToolResults` entry, which
+ * is what a model's Agent call carries at `tool.call`.
+ */
+export interface AgentCallRecord {
+    /** The spawned agent's id, as `$.agent.list()` names it. */
+    agentId: string;
+    /** The model the agent resolved to, when one is known. */
+    resolvedModel?: string;
+}
+/**
+ * One agent loop of this session as `$.agent.list()` returns it: a subagent
+ * or an in-process teammate.
+ */
+export interface AgentInfo {
+    /** The agent's id: same string its loop's `tool.call` events carry as `agentId`. */
+    id: string;
+    /** Its row's label. */
+    description: string;
+    /** The agent definition it runs as, or `teammate` for an in-process teammate. */
+    type: string;
+    /** `running`, `completed`, `failed`, `killed`, or another engine task status. */
+    status: string;
+    /** The id of the subagent whose loop spawned it; absent when the main loop did. */
+    parentId?: string;
+    /** The plugin whose `$.agent.spawn` started it; absent when the model or the person did. */
+    spawnedBy?: string;
+    /** What SendMessage addresses it by, when it has one; not `description` or `type`. */
+    name?: string;
+}
+/**
+ * Which model loop an event happened in: the loop's agent id inside a
+ * subagent's or a teammate's loop, absent on the main loop.
+ *
+ * The agent axis, not the origin axis: `next.origin` names the plugin whose
+ * hook frame caused the dispatch (the recursion skip), whichever loop it ran
+ * in; `agentId` names the loop, whoever caused the call.
+ */
+export interface AgentLoop {
+    /** The id of the loop this call runs in; absent on the main loop. Pinned. */
+    agentId?: string;
+}
+/**
+ * The input of `agent.offer`: one agent type, at the moment the engine
+ * offers it to the model.
+ *
+ * Listed for the model or named by it at dispatch: same event at each.
+ * Model-facing only: a plugin's own `$.agent.spawn` of a type is no offer.
+ */
+export interface AgentOfferInput {
+    /** Which type (`Explore`, `Plan`, a plugin's agent). */
+    agent: string;
+    /** Its listing line's text as the definition states it (`whenToUse`). */
+    description: string;
+    /** Where the definition came from (`built-in`, `plugin`, a settings source). */
+    source: string;
+    /** Who provides this agent. Pinned: a rewrite is refused. */
+    provider: Origin;
+}
+/**
+ * What an `agent.offer` hook returns: whether the model is offered the agent
+ * type, in its listing and at dispatch.
+ */
+export interface AgentOfferResult {
+    isOffered: boolean;
+}
+/**
+ * The input of `agent.spawn`: what the Agent tool decided about the subagent
+ * it is about to start, before its model is resolved.
+ *
+ * A hook rewrites content (prompt, description, subagentType, model,
+ * background, cwd), read back as the tool's parameters; tool_use_id, name,
+ * fork, parentModel, permissionMode, parentAgentId and provider are pinned.
+ */
+export interface AgentSpawnInput {
+    /** The Agent tool call this spawn belongs to. Pinned. */
+    tool_use_id: string;
+    /** The task the subagent is given. A rewrite is the prompt the subagent runs with. */
+    prompt: string;
+    /** The Agent tool's short `description` of the task. */
+    description: string;
+    /** The resolved agent type. A rewrite names another agent this call can dispatch. */
+    subagentType: string;
+    /** Who provides this agent. Pinned with the spawn's identity. */
+    provider: Origin;
+    /** The Agent tool's `model` parameter as given. */
+    model?: string;
+    /** The parent's effective model. Pinned. */
+    parentModel: string;
+    /** The id of the loop the spawn happens in; absent from main. Pinned. */
+    parentAgentId?: string;
+    /** The parent's permission mode. Pinned. */
+    permissionMode?: string;
+    /** True when the subagent will run in the background (or remotely). */
+    background: boolean;
+    /** True for a fork of the parent. Pinned. */
+    fork: boolean;
+    /** Given by the call (`Agent({ name })`); undefined when unnamed. Pinned. */
+    name?: string;
+    /** The directory the subagent runs in when the call set one. */
+    cwd?: string;
+}
+/**
+ * `agent.spawn`'s input as the call takes it: what the Agent tool's caller
+ * says; the engine fills the rest.
+ */
+export type AgentSpawnArgs = Pick<AgentSpawnInput, 'prompt'> & Partial<Pick<AgentSpawnInput, 'description' | 'subagentType' | 'model' | 'name' | 'cwd'>>;
+/**
+ * What an `agent.spawn` hook returns and what `next(e)` resolves to: the
+ * started subagent's `{ model, agentId }`, or `{ deny: reason }`, refusing it.
+ */
+export type AgentSpawnResult = {
+    /** What the subagent runs on. */
+    model: string;
+    /** The started subagent's id. Set by core; absent when a hook answered without `next`. */
+    agentId?: string;
+    deny?: undefined;
+} | {
+    /** Refuses the spawn; the model sees the text as the Agent tool's error. */
+    deny: string;
+    model?: undefined;
+    agentId?: undefined;
+};
+/**
+ * What `$.agent.register` takes: an agent type this plugin defines, spelled
+ * as an agent definition in settings JSON is, plus its `name`.
+ *
+ * Every field an agent file or `--agents` entry may carry is here and takes
+ * effect as it does there; the engine validates it with the same schema.
+ */
+export interface AgentSpec {
+    /** The type's short name (letters, digits, `_`, `-`; up to 64). */
+    name: string;
+    /** When to delegate to this agent: the line the model reads in its listing. */
+    description: string;
+    /** The agent's system prompt, whole: it replaces the session's. */
+    prompt: string;
+    /** What the agent may call, by tool name; a call to any other is refused. */
+    tools?: readonly string[];
+    /** Tools withheld from the agent, out of whatever `tools` allows. */
+    disallowedTools?: readonly string[];
+    /** The agent's model: an alias, a full id, or `inherit`. */
+    model?: string;
+    /** The agent's effort: a level or an integer budget. */
+    effort?: string | number;
+    /** How the agent's permission asks are decided. */
+    permissionMode?: string;
+    /** Servers connected over MCP for the agent's run. */
+    mcpServers?: readonly (string | Record<string, unknown>)[];
+    /** Settings hooks in force while the agent runs, in settings.json's `hooks` shape. */
+    hooks?: Record<string, unknown>;
+    /** The most turns the agent takes before it stops. */
+    maxTurns?: number;
+    /** Preloaded into the agent's context before its first turn: skill names. */
+    skills?: readonly string[];
+    /** The agent's first user turn; `{{intent}}` in it takes the spawn's prompt. */
+    initialPrompt?: string;
+    /** A persistent memory the agent keeps between runs, and where. */
+    memory?: 'user' | 'project' | 'local';
+    /** Set so that every spawn of the agent runs in the background. */
+    background?: true;
+    /** Set so that the agent's context carries no CLAUDE.md block. */
+    omitClaudeMd?: true;
+    /** Where the agent runs apart from the session. */
+    isolation?: 'worktree' | 'remote';
+}
+/**
+ * What `$.agent.register` resolves to: the type's fully-qualified name
+ * (`<plugin>:<name>`).
+ */
+export interface AgentRegisterResult {
+    agent: string;
+}

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

@@ -0,0 +1,114 @@
+/**
+ * `types/events/command.ts`
+ *
+ * Precise `command.*` event shapes: `command.run`, `command.describe`, plus
+ * op-facing types `CommandInfo` / `CommandSpec` / `CommandPresentation` /
+ * `CommandSource`.
+ */
+import type { Origin } from '../events.js';
+import type { PromptOrigin } from './prompt.js';
+/**
+ * Where a slash command comes from, as `$.command.list()` tells them apart.
+ */
+export type CommandSource = 'builtin' | 'plugin' | 'user' | 'mcp';
+/**
+ * Where a command's answer will show: which of the terminal's two layouts
+ * the surface renders, and how wide it is when the command runs.
+ */
+export interface CommandPresentation {
+    /** True under the fullscreen (alternate-screen) layout. */
+    isFullscreen: boolean;
+    /** The terminal's width in cells as the command runs; 80 where headless. */
+    columns: number;
+}
+/**
+ * The input of `command.run`: one slash command about to run, the way the
+ * person typed it (`/name args`), and where the run came from.
+ */
+export interface CommandRunInput {
+    /** Names the command without its slash. Pinned: rewrite refused. */
+    command: string;
+    /** Everything after the name, as typed (`""` when nothing). */
+    args: string;
+    /** Where the run came from. */
+    origin: PromptOrigin;
+    /** Where the command's answer will show. Pinned. */
+    presentation: CommandPresentation;
+}
+/**
+ * `command.run`'s input as a plugin's `$.command.run` takes it: `args` may
+ * be left out (`/command`, bare); `origin` and `presentation` the engine sets.
+ */
+export type CommandRunArgs = Omit<CommandRunInput, 'origin' | 'args' | 'presentation'> & {
+    /** Everything after the name; left out, `""`. */
+    args?: string;
+};
+/**
+ * What a `command.run` hook returns: the command's output text and the notes
+ * it leaves the model.
+ */
+export interface CommandRunResult {
+    /** The command's output as a transcript line, or undefined for silent commands. */
+    text?: string;
+    /** What the model reads after the command's output. */
+    context?: readonly string[];
+    /** Set by core on what `next(e)` resolves to. */
+    ref?: number;
+}
+/**
+ * The input of `command.describe`: how one slash command's menu row presents.
+ */
+export interface CommandDescribeInput {
+    /** Names the command without its slash. Pinned. */
+    command: string;
+    /** The one-line description the menu shows. */
+    description: string;
+    /** The hint drawn dim after the name (`[name]`). */
+    argumentHint?: string;
+    /** Whether the typeahead and `/help` leave the command out. */
+    isHidden: boolean;
+    /**
+     * Whether the command declares it runs at once when typed mid-turn.
+     * Pinned: a rewrite is refused.
+     */
+    immediate: boolean;
+    /** Who provides this command. Pinned: a rewrite is refused. */
+    provider: Origin;
+}
+/**
+ * What a `command.describe` hook returns: the description, hint and hidden
+ * flag the menu uses; the name, `immediate` and `provider` stay as they were.
+ */
+export type CommandDescribeResult = Omit<CommandDescribeInput, 'command' | 'immediate' | 'provider'>;
+/**
+ * One slash command as `$.command.list()` returns it.
+ */
+export interface CommandInfo {
+    /** What the person runs it by, without the slash. */
+    name: string;
+    /** The one line the typeahead shows for it. */
+    description: string;
+    /** Where it comes from. */
+    source: CommandSource;
+    /** Which plugin added it, when `source` is `plugin` and the engine knows. */
+    plugin?: string;
+}
+/**
+ * What `$.command.register` takes: the slash command this plugin serves.
+ */
+export interface CommandSpec {
+    /** The command's name without the slash. */
+    name: string;
+    /** The one line the typeahead and `/help` show for it. */
+    description: string;
+    /** The hint drawn dim after the name (`[name]`). */
+    argumentHint?: string;
+    /** Set so that `/<name>` typed while a turn is in flight runs at once. */
+    immediate?: true;
+}
+/**
+ * What `$.command.register` resolves to: the registered name.
+ */
+export interface CommandRegisterResult {
+    command: string;
+}

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

@@ -0,0 +1,310 @@
+/**
+ * `types/events/prompt.ts`
+ *
+ * Precise `prompt.*` event shapes: `prompt.submit`, `prompt.fill`,
+ * `prompt.suggest`, `prompt.edit`, `prompt.section`, `prompt.context`,
+ * `prompt.attachment`, plus supporting `PromptOrigin` / `PromptBox` /
+ * `PromptContextBlock` / `InstructionFile`.
+ */
+type ClientKeyEvent = Readonly<{
+    key: string;
+    text?: string;
+    shift?: true;
+    alt?: true;
+    ctrl?: true;
+    [k: string]: unknown;
+}>;
+/**
+ * What tier an instruction file belongs to.
+ */
+export type InstructionFileKind = 'managed' | 'user' | 'project' | 'local' | 'memory';
+/**
+ * One instruction file behind the `claudeMd` block.
+ */
+export interface InstructionFile {
+    /** The file's path, absolute. */
+    path: string;
+    /** Its tier. */
+    kind: InstructionFileKind;
+    /** The text as loaded (comments and frontmatter stripped). */
+    content: string;
+    /** The path of the file whose `@` import brought this one. */
+    parent?: string;
+}
+/**
+ * Where a `prompt.submit` submission came from. Closed set, pinned on the
+ * event; a hooks module reads `e.origin.kind` to tell sources apart.
+ */
+export type PromptOrigin = {
+    kind: 'composer';
+} | {
+    kind: 'bridge';
+} | {
+    kind: 'sdk';
+} | {
+    kind: 'task-notification';
+} | {
+    kind: 'scheduled-trigger';
+} | {
+    kind: 'peer';
+} | {
+    kind: 'peer-send-message';
+} | {
+    kind: 'projects-relay';
+} | {
+    kind: 'channel';
+    server: string;
+} | {
+    kind: 'coordinator';
+} | {
+    kind: 'observer';
+} | {
+    kind: 'observer-activity';
+} | {
+    kind: 'auto-continuation';
+} | {
+    kind: 'unclassified';
+} | {
+    kind: 'slack-ping';
+} | {
+    kind: 'plugin';
+    name: string;
+};
+/**
+ * Who authored the text an injected attachment carries.
+ */
+export type PromptAttachmentOrigin = {
+    kind: 'engine';
+} | {
+    kind: 'hook';
+    event: string;
+} | {
+    kind: 'plugin';
+    event: string;
+};
+/**
+ * The input of `prompt.attachment`: one attachment at the moment the engine
+ * frames it for the model.
+ */
+export interface PromptAttachmentInput {
+    /** Kind name; a matcher narrows on this. */
+    type: string;
+    /** What the model reads for this attachment, inside the engine's framing. */
+    text: string;
+    /** Who authored the text. Pinned. */
+    origin: PromptAttachmentOrigin;
+    /** The loop whose request carries the attachment. Pinned. */
+    agentId?: string;
+}
+/**
+ * What a `prompt.attachment` hook returns: the text the model reads, or null.
+ */
+export interface PromptAttachmentResult {
+    text: string | null;
+}
+/**
+ * The person's prompt box as it stands: the draft and where the cursor is.
+ */
+export interface PromptBox {
+    /** The draft as typed so far; `''` where the session draws no box. */
+    text: string;
+    /** Cursor offset into `text` in UTF-16 code units. */
+    cursor: number;
+}
+/**
+ * One block of the context the first user message carries.
+ */
+export interface PromptContextBlock {
+    /** The key the block renders under (`claudeMd`, `userEmail`, ...). */
+    name: string;
+    /** The block's text. */
+    text: string;
+}
+/**
+ * The context blocks of a conversation's first user message.
+ */
+export interface PromptContextBlocks {
+    blocks: readonly PromptContextBlock[];
+}
+/**
+ * The input of `prompt.context`: the context blocks the engine prepends.
+ */
+export interface PromptContextInput {
+    blocks: readonly PromptContextBlock[];
+    /** The files behind `claudeMd`, in the order it renders them. */
+    instructionFiles?: readonly InstructionFile[];
+}
+/**
+ * What a `prompt.context` hook returns: the blocks the conversation carries.
+ */
+export interface PromptContextResult {
+    blocks: readonly PromptContextBlock[];
+    instructionFiles?: readonly InstructionFile[];
+}
+/**
+ * Who edits the prompt box at `prompt.edit`.
+ */
+export type PromptEditOrigin = {
+    kind: 'composer';
+};
+/**
+ * The input of `prompt.edit`: one edit the person makes in the prompt box.
+ */
+export interface PromptEditInput {
+    /** Who edits. Pinned. */
+    origin: PromptEditOrigin;
+    /** The one key that made the edit, when one did; absent for a paste. */
+    key?: ClientKeyEvent;
+    /** The draft before the edit. */
+    text: string;
+    /** Where the person's caret stood in `text` before the edit. */
+    cursor: number;
+    /** Where in `text` the edit begins. */
+    start: number;
+    /** Where the replaced span of `text` ends. */
+    end: number;
+    /** What goes in between `start` and `end`. */
+    inputText: string;
+}
+/**
+ * What a `prompt.edit` hook returns: the box after the edit.
+ */
+export type PromptEditResult = PromptBox;
+/**
+ * Where a `prompt.fill` puts its text: over the whole draft, after it, or
+ * into it at the cursor.
+ */
+export type PromptFillMode = 'replace' | 'append' | 'insert';
+/**
+ * Who writes the prompt box at `prompt.fill`.
+ */
+export type PromptFillOrigin = {
+    kind: 'engine';
+} | {
+    kind: 'plugin';
+    name: string;
+};
+/**
+ * The input of `prompt.fill`: a text about to be put in the prompt box.
+ */
+export interface PromptFillInput {
+    /** What the box takes. */
+    text: string;
+    /** Where the text goes. */
+    mode: PromptFillMode;
+    /** Who writes. Pinned. */
+    origin: PromptFillOrigin;
+}
+/**
+ * `$.prompt.fill(args)` — `origin` filled by engine, `mode` optional.
+ */
+export interface PromptFillArgs {
+    text: string;
+    mode?: PromptFillMode;
+}
+/**
+ * What a `prompt.fill` hook returns.
+ */
+export interface PromptFillResult {
+    isFilled: boolean;
+}
+/**
+ * What `$.prompt.fill` resolves to: whether the box took the text and the
+ * box afterwards.
+ */
+export interface PromptFilled {
+    isFilled: boolean;
+    text: string;
+    cursor: number;
+}
+/**
+ * The input of `prompt.section`: one named section of the system prompt.
+ */
+export interface PromptSectionInput {
+    /** As the engine names the section (`env_info_simple`, `memory`, ...). */
+    name: string;
+    /** The section's text as core computed it, or null when core omits it. */
+    text: string | null;
+}
+/**
+ * What a `prompt.section` hook returns.
+ */
+export interface PromptSectionResult {
+    text: string | null;
+}
+/**
+ * A pasted or attached non-text item of a submitted prompt.
+ */
+export interface PromptSubmitAttachment {
+    type: 'image' | 'audio' | 'document';
+    mediaType?: string;
+    filename?: string;
+}
+/**
+ * The input of `prompt.submit`: the prompt as typed.
+ */
+export interface PromptSubmitInput {
+    /** The prompt's text as it will reach the model. */
+    text: string;
+    /** Non-text items of the submission. */
+    attachments?: readonly PromptSubmitAttachment[];
+    /** What the model reads beside the prompt; each entry one block. */
+    context?: readonly string[];
+    /** The id of the model turn that was running when the prompt was submitted. */
+    turnId?: string;
+    /** Whether the user asked the prompt to wait its turn. */
+    wait: boolean;
+    /** Where the submission came from. */
+    origin: PromptOrigin;
+}
+/**
+ * `$.prompt.submit(args)`: `origin`, `turnId` and `wait` engine's to set.
+ */
+export type PromptSubmitArgs = Omit<PromptSubmitInput, 'origin' | 'turnId' | 'wait' | 'context'>;
+/**
+ * What a `prompt.submit` hook returns.
+ */
+export type PromptSubmitResult = {
+    /** The prompt that entered. */
+    text: string;
+    /** What entered beside the prompt for the model. */
+    context?: readonly string[];
+    /** Where the prompt entered from. */
+    origin?: PromptOrigin;
+    drop?: undefined;
+} | {
+    /** The prompt did not enter. */
+    drop: string;
+    text?: undefined;
+    context?: undefined;
+    origin?: undefined;
+};
+/**
+ * Who proposes the text at `prompt.suggest`.
+ */
+export type PromptSuggestOrigin = {
+    kind: 'suggestion';
+} | {
+    kind: 'plugin';
+    name: string;
+};
+/**
+ * The input of `prompt.suggest`: dim text about to be shown in the empty box.
+ */
+export interface PromptSuggestInput {
+    /** The proposed prompt: shown, not written. */
+    text: string;
+    /** Who proposes. Pinned. */
+    origin: PromptSuggestOrigin;
+}
+/**
+ * `$.prompt.suggest(args)`: `origin` engine's to set.
+ */
+export type PromptSuggestArgs = Omit<PromptSuggestInput, 'origin'>;
+/**
+ * What a `prompt.suggest` hook returns.
+ */
+export interface PromptSuggestResult {
+    isShown: boolean;
+}
+export {};