@clinebot/agents 0.0.0

package/README.md

@@ -0,0 +1,145 @@
+# @clinebot/agents
+
+`@clinebot/agents` is the runtime-agnostic agent loop package in the Cline SDK.
+It gives you the core primitives for building tool-using LLM agents without
+bringing in session storage, RPC transport, or host-specific default tools.
+
+## What You Get
+
+- `Agent` / `createAgent` for running and continuing agent conversations
+- `createTool` for defining strongly typed tools
+- `AgentHooks` and hook helpers for lifecycle interception
+- event streaming via `onEvent` and `agent.subscribeEvents(...)`
+- sub-agent, team, and MCP bridge primitives for advanced runtimes
+
+## What This Package Does Not Include
+
+`@clinebot/agents` does not ship a full application runtime by itself.
+
+- Default host tools like filesystem access, shell execution, or web fetching live in `@clinebot/core`
+- Session persistence and stateful orchestration live in `@clinebot/core`
+- Remote runtime/session transport lives in `@clinebot/rpc`
+
+That split keeps this package usable in Node, browser, and custom host
+environments where you want to supply your own tools and runtime policy.
+
+## Installation
+
+```bash
+npm install @clinebot/agents @clinebot/llms zod
+```
+
+## Quick Start
+
+```ts
+import { Agent, createTool } from "@clinebot/agents";
+import { z } from "zod";
+
+const getWeather = createTool({
+	name: "get_weather",
+	description: "Return the current weather for a city.",
+	inputSchema: z.object({
+		city: z.string(),
+	}),
+	async execute({ city }) {
+		return {
+			city,
+			forecast: "sunny",
+			temperatureC: 22,
+		};
+	},
+});
+
+const agent = new Agent({
+	providerId: "anthropic",
+	modelId: "claude-sonnet-4-6",
+	apiKey: process.env.ANTHROPIC_API_KEY,
+	systemPrompt: "You are a concise assistant.",
+	tools: [getWeather],
+});
+
+const result = await agent.run("What's the weather in San Francisco?");
+console.log(result.text);
+```
+
+## Core Concepts
+
+### Tools
+
+Use `createTool(...)` to define tools with either JSON Schema or Zod input
+schemas. The agent exposes the tool to the model and calls your `execute(...)`
+handler with validated input plus a `ToolContext`.
+
+```ts
+import { createTool } from "@clinebot/agents";
+import { z } from "zod";
+
+const summarize = createTool({
+	name: "summarize_text",
+	description: "Summarize text into a few bullet points.",
+	inputSchema: z.object({
+		text: z.string(),
+	}),
+	async execute({ text }) {
+		return { summary: text.slice(0, 120) };
+	},
+});
+```
+
+### Events
+
+You can observe execution in two ways:
+
+- pass `onEvent` in `AgentConfig`
+- subscribe later with `agent.subscribeEvents(listener)`
+
+`AgentEvent` covers model text/reasoning chunks, tool lifecycle events, usage,
+iteration boundaries, completion, and errors.
+
+### Conversation Control
+
+- `agent.run(message)` starts a new run
+- `agent.continue(message)` continues the current conversation
+- `initialMessages` and `agent.restore(messages)` support resume flows
+
+### Hooks
+
+`AgentHooks` let hosts observe or influence lifecycle stages such as run start,
+turn start, tool call start/end, and run completion. This is the right place for
+policy checks, telemetry, or injecting additional context.
+
+If you need subprocess-backed hooks, use the Node entrypoint:
+
+```ts
+import { createSubprocessHooks } from "@clinebot/agents/node";
+```
+
+### Teams and Spawn
+
+For multi-agent workflows, the package exports:
+
+- `createSpawnAgentTool(...)`
+- `AgentTeamsRuntime`
+- `createAgentTeamsTools(...)`
+- `bootstrapAgentTeams(...)`
+
+These helpers provide in-memory coordination primitives for delegated runs,
+mailboxes, task management, and outcome convergence.
+
+## Entry Points
+
+- `@clinebot/agents`: main package entrypoint
+- `@clinebot/agents/node`: Node-only exports such as subprocess hook helpers
+- `@clinebot/agents/browser`: browser-safe bundle
+
+## Related Packages
+
+- `@clinebot/llms`: provider settings, model catalogs, and handler creation
+- `@clinebot/core`: stateful runtime assembly, storage, and default tools
+- `@clinebot/rpc`: remote runtime/session transport
+
+## More Examples
+
+- Repo examples: [apps/examples/cline-sdk](https://github.com/cline/sdk/tree/main/apps/examples/cline-sdk)
+- Workspace overview: [README.md](https://github.com/cline/sdk/blob/main/README.md)
+- API and architecture references: [DOC.md](https://github.com/cline/sdk/blob/main/DOC.md), [ARCHITECTURE.md](https://github.com/cline/sdk/blob/main/ARCHITECTURE.md)

package/dist/agent-input.d.ts

@@ -0,0 +1,2 @@
+import type { providers } from "@clinebot/llms";
+export declare function buildInitialUserContent(userMessage: string, userImages?: string[], userFiles?: string[], userFileContentLoader?: (path: string) => Promise<string>): Promise<string | providers.ContentBlock[]>;

package/dist/agent.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Agent Class
+ *
+ * The main class for building and running agentic loops with LLMs.
+ */
+import { providers } from "@clinebot/llms";
+import type { AgentConfig, AgentEvent, AgentExtensionRegistry, AgentResult } from "./types.js";
+export declare class Agent {
+    private config;
+    private handler;
+    private toolRegistry;
+    private abortController;
+    private contributionRegistry;
+    private readonly hookEngine;
+    private messageBuilder;
+    private readonly logger?;
+    private extensionsInitialized;
+    private activeRunId;
+    private runState;
+    private readonly runtimeBus;
+    private readonly conversationStore;
+    private readonly lifecycle;
+    private turnProcessor;
+    private readonly toolOrchestrator;
+    private readonly agentId;
+    private readonly parentAgentId;
+    constructor(config: AgentConfig);
+    run(userMessage: string, userImages?: string[], userFiles?: string[]): Promise<AgentResult>;
+    continue(userMessage: string, userImages?: string[], userFiles?: string[]): Promise<AgentResult>;
+    getMessages(): providers.Message[];
+    clearHistory(): void;
+    restore(messages: providers.Message[]): void;
+    abort(): void;
+    subscribeEvents(listener: (event: AgentEvent) => void): () => void;
+    shutdown(reason?: string): Promise<void>;
+    getExtensionRegistry(): AgentExtensionRegistry;
+    getAgentId(): string;
+    getConversationId(): string;
+    updateConnection(overrides: Partial<Pick<AgentConfig, "providerId" | "modelId" | "apiKey" | "baseUrl" | "headers" | "knownModels" | "reasoningEffort" | "thinkingBudgetTokens" | "thinking" | "abortSignal">>): void;
+    private assertCanStartRun;
+    private createHandlerFromConfig;
+    private executeLoop;
+    private ensureExtensionsInitialized;
+    private prepareUserInput;
+    private buildInitialUserContent;
+    private buildAbortedResult;
+    private emit;
+    private reportRecoverableError;
+    private resolveToolPolicy;
+    private requestToolApproval;
+    private authorizeToolCall;
+    private appendHookContext;
+    private log;
+    private mergeAbortSignals;
+}
+export declare function createAgent(config: AgentConfig): Agent;

package/dist/extensions.d.ts

@@ -0,0 +1,21 @@
+import type { AgentExtension, AgentExtensionRegistry, Tool } from "./types.js";
+export interface ContributionRegistryOptions {
+    extensions?: AgentExtension[];
+}
+export declare class ContributionRegistry {
+    private readonly extensions;
+    private readonly registry;
+    private normalized;
+    private phase;
+    constructor(options?: ContributionRegistryOptions);
+    resolve(): void;
+    validate(): void;
+    setup(): Promise<void>;
+    activate(): void;
+    initialize(): Promise<void>;
+    isActivated(): boolean;
+    getRegistrySnapshot(): AgentExtensionRegistry;
+    getRegisteredTools(): Tool[];
+    getValidatedExtensions(): AgentExtension[];
+}
+export declare function createContributionRegistry(options?: ContributionRegistryOptions): ContributionRegistry;

package/dist/hooks/engine.d.ts

@@ -0,0 +1,42 @@
+import type { AgentHookControl, HookDispatchResult, HookEventEnvelope, HookPolicies, HookStage, HookStagePolicy } from "../types.js";
+export interface HookHandler {
+    name: string;
+    stage: HookStage;
+    priority?: number;
+    handle: (event: HookEventEnvelope) => Promise<AgentHookControl | undefined> | AgentHookControl | undefined;
+}
+export interface HookDispatchInput<TPayload = unknown> {
+    stage: HookStage;
+    runId: string;
+    agentId: string;
+    conversationId: string;
+    parentAgentId: string | null;
+    iteration?: number;
+    parentEventId?: string;
+    payload: TPayload;
+}
+export interface HookEngineOptions {
+    policies?: HookPolicies;
+    onDispatchError?: (error: Error, event: HookEventEnvelope, handlerName: string) => void;
+    onDroppedEvent?: (event: HookEventEnvelope, policy: HookStagePolicy) => void;
+}
+export declare class HookEngine {
+    private readonly handlers;
+    private readonly options;
+    private sequence;
+    private eventCounter;
+    private readonly stageQueues;
+    private readonly inFlight;
+    constructor(options?: HookEngineOptions);
+    register(handler: HookHandler): void;
+    dispatch<TPayload>(input: HookDispatchInput<TPayload>): Promise<HookDispatchResult>;
+    shutdown(drainTimeoutMs?: number): Promise<void>;
+    private getHandlers;
+    private getStageQueueState;
+    private kickQueue;
+    private resolveStagePolicy;
+    private resolveHandlerPolicy;
+    private executeHandlers;
+    private executeHandler;
+    private mergeControlsFromResults;
+}

package/dist/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { type HookDispatchInput, HookEngine, type HookHandler, } from "./engine.js";
+export { registerLifecycleHandlers } from "./lifecycle.js";

package/dist/hooks/lifecycle.d.ts

@@ -0,0 +1,5 @@
+import type { AgentConfig } from "../types.js";
+import type { HookEngine } from "./engine.js";
+type LifecycleConfig = Pick<AgentConfig, "hooks" | "extensions">;
+export declare function registerLifecycleHandlers(hookEngine: HookEngine, config: LifecycleConfig): void;
+export {};

package/dist/hooks/node.d.ts

@@ -0,0 +1,2 @@
+export { createSubprocessHooks, type HookEventName, HookEventNameSchema, type HookEventPayload, HookEventPayloadSchema, parseHookEventPayload, type RunHookOptions, type RunHookResult, runHook, type SubprocessHookControl, type SubprocessHooksOptions, } from "./subprocess.js";
+export { type RunSubprocessEventOptions, type RunSubprocessEventResult, runSubprocessEvent, } from "./subprocess-runner.js";

package/dist/hooks/subprocess-runner.d.ts

@@ -0,0 +1,16 @@
+export interface RunSubprocessEventOptions {
+    command: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    detached?: boolean;
+    timeoutMs?: number;
+}
+export interface RunSubprocessEventResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    parsedJson?: unknown;
+    parseError?: string;
+    timedOut?: boolean;
+}
+export declare function runSubprocessEvent(payload: unknown, options: RunSubprocessEventOptions): Promise<RunSubprocessEventResult | undefined>;

package/dist/hooks/subprocess.d.ts

@@ -0,0 +1,268 @@
+import type { HookSessionContext, HookSessionContextProvider } from "@clinebot/shared";
+import { z } from "zod";
+import type { AgentHooks, AgentHookTurnEndContext, ToolCallRecord } from "../types.js";
+import { type RunSubprocessEventResult } from "./subprocess-runner.js";
+export declare const HookEventNameSchema: z.ZodEnum<{
+    tool_result: "tool_result";
+    session_shutdown: "session_shutdown";
+    tool_call: "tool_call";
+    agent_start: "agent_start";
+    agent_resume: "agent_resume";
+    agent_abort: "agent_abort";
+    agent_end: "agent_end";
+    prompt_submit: "prompt_submit";
+    pre_compact: "pre_compact";
+}>;
+export type HookEventName = z.infer<typeof HookEventNameSchema>;
+export interface HookOutput {
+    contextModification: string;
+    cancel: boolean;
+    review?: boolean;
+    errorMessage: string;
+}
+export declare const HookOutputSchema: z.ZodObject<{
+    contextModification: z.ZodOptional<z.ZodString>;
+    cancel: z.ZodOptional<z.ZodBoolean>;
+    review: z.ZodOptional<z.ZodBoolean>;
+    errorMessage: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodString>;
+    overrideInput: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>;
+export interface PreToolUseData {
+    toolName: string;
+    parameters: Record<string, string>;
+}
+export interface PostToolUseData {
+    toolName: string;
+    parameters: Record<string, string>;
+    result: string;
+    success: boolean;
+    executionTimeMs: number;
+}
+export interface UserPromptSubmitData {
+    prompt: string;
+    attachments: string[];
+}
+export interface TaskStartData {
+    taskMetadata: Record<string, string>;
+}
+export interface TaskResumeData {
+    taskMetadata: Record<string, string>;
+    previousState: Record<string, string>;
+}
+export interface TaskCancelData {
+    taskMetadata: Record<string, string>;
+}
+export interface TaskCompleteData {
+    taskMetadata: Record<string, string>;
+}
+export interface PreCompactData {
+    taskId: string;
+    ulid: string;
+    contextSize: number;
+    compactionStrategy: string;
+    previousApiReqIndex: number;
+    tokensIn: number;
+    tokensOut: number;
+    tokensInCache: number;
+    tokensOutCache: number;
+    deletedRangeStart: number;
+    deletedRangeEnd: number;
+    contextJsonPath: string;
+    contextRawPath: string;
+}
+export interface HookEventPayloadBase {
+    clineVersion: string;
+    hookName: HookEventName;
+    timestamp: string;
+    taskId: string;
+    sessionContext?: HookSessionContext;
+    workspaceRoots: string[];
+    userId: string;
+    agent_id: string;
+    parent_agent_id: string | null;
+    preToolUse?: PreToolUseData | undefined;
+    postToolUse?: PostToolUseData | undefined;
+    userPromptSubmit?: UserPromptSubmitData | undefined;
+    taskStart?: TaskStartData | undefined;
+    taskResume?: TaskResumeData | undefined;
+    taskCancel?: TaskCancelData | undefined;
+    taskComplete?: TaskCompleteData | undefined;
+    preCompact?: PreCompactData | undefined;
+}
+export interface ToolCallHookPayload extends HookEventPayloadBase {
+    hookName: "tool_call";
+    iteration: number;
+    tool_call: {
+        id: string;
+        name: string;
+        input: unknown;
+    };
+}
+export interface ToolResultHookPayload extends HookEventPayloadBase {
+    hookName: "tool_result";
+    iteration: number;
+    tool_result: ToolCallRecord;
+}
+export interface AgentEndHookPayload extends HookEventPayloadBase {
+    hookName: "agent_end";
+    iteration: number;
+    turn: AgentHookTurnEndContext["turn"];
+}
+export interface AgentStartHookPayload extends HookEventPayloadBase {
+    hookName: "agent_start";
+}
+export interface AgentResumeHookPayload extends HookEventPayloadBase {
+    hookName: "agent_resume";
+}
+export interface AgentAbortHookPayload extends HookEventPayloadBase {
+    hookName: "agent_abort";
+    reason?: string;
+}
+export interface PromptSubmitHookPayload extends HookEventPayloadBase {
+    hookName: "prompt_submit";
+}
+export interface PreCompactHookPayload extends HookEventPayloadBase {
+    hookName: "pre_compact";
+    preCompact: PreCompactData;
+}
+export interface SessionShutdownHookPayload extends HookEventPayloadBase {
+    hookName: "session_shutdown";
+    reason?: string;
+}
+export type HookEventPayload = ToolCallHookPayload | ToolResultHookPayload | AgentStartHookPayload | AgentResumeHookPayload | AgentAbortHookPayload | PromptSubmitHookPayload | PreCompactHookPayload | AgentEndHookPayload | SessionShutdownHookPayload;
+export declare const HookEventPayloadSchema: z.ZodObject<{
+    clineVersion: z.ZodString;
+    hookName: z.ZodEnum<{
+        tool_result: "tool_result";
+        session_shutdown: "session_shutdown";
+        tool_call: "tool_call";
+        agent_start: "agent_start";
+        agent_resume: "agent_resume";
+        agent_abort: "agent_abort";
+        agent_end: "agent_end";
+        prompt_submit: "prompt_submit";
+        pre_compact: "pre_compact";
+    }>;
+    timestamp: z.ZodString;
+    taskId: z.ZodString;
+    sessionContext: z.ZodOptional<z.ZodObject<{
+        rootSessionId: z.ZodOptional<z.ZodString>;
+        hookLogPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    workspaceRoots: z.ZodArray<z.ZodString>;
+    userId: z.ZodString;
+    agent_id: z.ZodString;
+    parent_agent_id: z.ZodNullable<z.ZodString>;
+    iteration: z.ZodOptional<z.ZodNumber>;
+    reason: z.ZodOptional<z.ZodString>;
+    tool_call: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        input: z.ZodUnknown;
+    }, z.core.$strip>>;
+    tool_result: z.ZodOptional<z.ZodCustom<ToolCallRecord, ToolCallRecord>>;
+    turn: z.ZodOptional<z.ZodCustom<import("../types.js").ProcessedTurn, import("../types.js").ProcessedTurn>>;
+    preToolUse: z.ZodOptional<z.ZodObject<{
+        toolName: z.ZodString;
+        parameters: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>>;
+    postToolUse: z.ZodOptional<z.ZodObject<{
+        toolName: z.ZodString;
+        parameters: z.ZodRecord<z.ZodString, z.ZodString>;
+        result: z.ZodString;
+        success: z.ZodBoolean;
+        executionTimeMs: z.ZodNumber;
+    }, z.core.$strip>>;
+    userPromptSubmit: z.ZodOptional<z.ZodObject<{
+        prompt: z.ZodString;
+        attachments: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    taskStart: z.ZodOptional<z.ZodObject<{
+        taskMetadata: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>>;
+    taskResume: z.ZodOptional<z.ZodObject<{
+        taskMetadata: z.ZodRecord<z.ZodString, z.ZodString>;
+        previousState: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>>;
+    taskCancel: z.ZodOptional<z.ZodObject<{
+        taskMetadata: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>>;
+    taskComplete: z.ZodOptional<z.ZodObject<{
+        taskMetadata: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>>;
+    preCompact: z.ZodOptional<z.ZodObject<{
+        taskId: z.ZodString;
+        ulid: z.ZodString;
+        contextSize: z.ZodNumber;
+        compactionStrategy: z.ZodString;
+        previousApiReqIndex: z.ZodNumber;
+        tokensIn: z.ZodNumber;
+        tokensOut: z.ZodNumber;
+        tokensInCache: z.ZodNumber;
+        tokensOutCache: z.ZodNumber;
+        deletedRangeStart: z.ZodNumber;
+        deletedRangeEnd: z.ZodNumber;
+        contextJsonPath: z.ZodString;
+        contextRawPath: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$loose>;
+export declare function parseHookEventPayload(value: unknown): HookEventPayload | undefined;
+export interface RunHookOptions {
+    command?: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    detached?: boolean;
+    timeoutMs?: number;
+}
+export type RunHookResult = RunSubprocessEventResult;
+/**
+ * Dispatch a single hook event to an external CLI.
+ * Payload is serialized as JSON and piped via stdin.
+ */
+export declare function runHook(payload: HookEventPayload, options?: RunHookOptions): Promise<RunHookResult | undefined>;
+export interface SubprocessHooksOptions {
+    command?: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Timeout in milliseconds for blocking tool_call hook invocation.
+     */
+    timeoutMs?: number;
+    /**
+     * Optional callback for non-fatal hook dispatch errors.
+     */
+    onDispatchError?: (error: Error, payload: HookEventPayload) => void;
+    /**
+     * Optional callback invoked after a hook dispatch is attempted.
+     */
+    onDispatch?: (event: {
+        payload: HookEventPayload;
+        result?: RunHookResult;
+        detached: boolean;
+    }) => void;
+    /**
+     * Optional context attached to every hook payload.
+     * Use this to scope hook events to a root runtime session without global env state.
+     */
+    sessionContext?: HookSessionContextProvider;
+}
+export interface SubprocessHookControl {
+    hooks: AgentHooks;
+    shutdown: (ctx: {
+        agentId: string;
+        conversationId: string;
+        parentAgentId: string | null;
+        reason?: string;
+    }) => Promise<void>;
+}
+/**
+ * Create lifecycle hooks that mirror Pi-style hook events:
+ * - tool_call (blocking)
+ * - tool_result (fire-and-forget)
+ * - agent_start (fire-and-forget)
+ * - prompt_submit (fire-and-forget)
+ * - agent_end (fire-and-forget)
+ * - session_shutdown (fire-and-forget via returned `shutdown()`)
+ */
+export declare function createSubprocessHooks(options?: SubprocessHooksOptions): SubprocessHookControl;

package/dist/index.browser.d.ts

@@ -0,0 +1 @@
+export * from "./index.js";