@sctg/cline-agents 3.84.0-beta.20260524130712

package/README.md

@@ -0,0 +1,278 @@
+# [experimental] @cline/agents
+
+`@cline/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, hub transport, or host-specific default tools.
+
+## What You Get
+
+- `Agent` / `AgentRuntime` — the same class under two names — for running and
+  continuing tool-using agent conversations
+- `createAgent` / `createAgentRuntime` — factory-function equivalents
+- `AgentRuntimeHooks` for lifecycle interception (`beforeRun`, `afterRun`,
+  `beforeModel`, `afterModel`, `beforeTool`, `afterTool`, `onEvent`)
+- Event streaming via `agent.subscribe(listener)` and the `hooks.onEvent`
+  callback
+- Plugin setup callbacks for contributing tools and hooks at boot
+
+## What This Package Does Not Include
+
+`@cline/agents` does not ship a full application runtime by itself.
+
+- Default host tools like filesystem access, shell execution, or web fetching live in `@cline/core`
+- Session persistence and stateful orchestration live in `@cline/core`
+- Shared hub runtime/session transport lives in `@cline/core` (see `@cline/core/hub`)
+- Sub-agent and team coordination primitives live in `@cline/core`
+
+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 @cline/agents @cline/shared @cline/llms
+```
+
+## Quick Start
+
+```ts
+import { Agent } from "@cline/agents";
+import type { AgentTool } from "@cline/shared";
+
+const getWeather: AgentTool<{ city: string }, { forecast: string }> = {
+	name: "get_weather",
+	description: "Return the current weather for a city.",
+	inputSchema: {
+		type: "object",
+		properties: { city: { type: "string" } },
+		required: ["city"],
+	},
+	async execute({ city }) {
+		return { forecast: `sunny in ${city}` };
+	},
+};
+
+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.outputText);
+```
+
+## Two Ways to Configure
+
+`Agent` / `AgentRuntime` accepts two config shapes:
+
+**Provider form** — friendly entrypoint. The runtime builds an `AgentModel` for
+you via `@cline/llms`:
+
+```ts
+new Agent({
+	providerId: "openai",
+	modelId: "gpt-5",
+	apiKey: process.env.OPENAI_API_KEY,
+	// baseUrl, headers also supported
+	tools: [/* ... */],
+});
+```
+
+**Model form** — advanced. Supply a pre-built `AgentModel` directly. Useful
+when the host already owns gateway construction (this is what `@cline/core`
+uses internally):
+
+```ts
+import { createGateway } from "@cline/llms";
+
+const gateway = createGateway({ providerConfigs: [/* ... */] });
+const model = gateway.createAgentModel({ providerId, modelId });
+
+new Agent({
+	model,
+	tools: [/* ... */],
+});
+```
+
+## Core Concepts
+
+### Tools
+
+Tools conform to the `AgentTool<TInput, TOutput>` interface from
+`@cline/shared`. Each tool has a JSON Schema `inputSchema` and an
+`execute(input, context)` function that returns the tool output directly:
+
+```ts
+import type { AgentTool } from "@cline/shared";
+
+const summarize: AgentTool<{ text: string }, { summary: string }> = {
+	name: "summarize_text",
+	description: "Summarize text into a short preview.",
+	inputSchema: {
+		type: "object",
+		properties: { text: { type: "string" } },
+		required: ["text"],
+	},
+	async execute({ text }, context) {
+		// context.signal — aborts when the run is cancelled
+		// context.emitUpdate(...) — stream progress as `tool-updated` events
+		return { summary: text.slice(0, 120) };
+	},
+};
+```
+
+The runtime wraps successful tool outputs in an internal tool-result message.
+Throw from `execute(...)` to report a tool failure, or use an `afterTool` hook
+to transform the internal `AgentToolResult` envelope.
+
+### Events
+
+Subscribe to the `AgentRuntimeEvent` stream in one of two ways:
+
+```ts
+// 1. Attach a listener after construction. Returns an unsubscribe function.
+const unsubscribe = agent.subscribe((event) => {
+	if (event.type === "assistant-text-delta") {
+		process.stdout.write(event.text);
+	}
+});
+
+// 2. Register an `onEvent` hook at construction time.
+new Agent({
+	providerId,
+	modelId,
+	apiKey,
+	hooks: {
+		onEvent(event) {
+			// fires for every runtime event
+		},
+	},
+});
+```
+
+`AgentRuntimeEvent` covers run/turn boundaries, assistant text and reasoning
+deltas, tool lifecycle, usage updates, and run completion/failure. See
+`AgentRuntimeEvent` in `@cline/shared` for the full union.
+
+### Conversation Control
+
+- `agent.run(input)` — start a run. `input` may be a string, an `AgentMessage`,
+  or an array of messages. Also accepts `undefined` to continue without adding
+  a new user turn.
+- `agent.continue(input?)` — convenience alias for `run(input?)`.
+- `agent.abort(reason?)` — cancel the active run. `.run()` resolves with
+  `status: "aborted"`.
+- `agent.snapshot()` — immutable view of the current
+  `AgentRuntimeStateSnapshot` (messages, usage, iteration, status, etc.).
+- `agent.restore(messages)` — replace the conversation with a persisted
+  message array. Resets run/turn state but preserves subscribers, tools,
+  hooks, plugins, and the model.
+- `initialMessages` in the constructor seeds the conversation on boot.
+
+### Hooks
+
+Pass a `hooks` bag (`AgentRuntimeHooks`) to observe or influence the loop.
+All hooks may be async; any that return `{ stop: true, reason }` will halt the
+run with an `aborted` status.
+
+```ts
+new Agent({
+	providerId,
+	modelId,
+	apiKey,
+	tools: [/* ... */],
+	hooks: {
+		beforeModel({ request }) {
+			// mutate messages/tools/options before the model call
+			return { options: { temperature: 0.2 } };
+		},
+		beforeTool({ tool, input }) {
+			// block a tool call based on policy
+			if (tool.name === "get_weather" && !(input as { city?: string }).city) {
+				return { skip: true, reason: "city required" };
+			}
+			return undefined;
+		},
+		afterRun({ result }) {
+			console.log("done", result.usage);
+		},
+	},
+});
+```
+
+For richer, host-side hook orchestration (15-stage `HookEngine`,
+subprocess-backed hooks, MCP extensions), use `@cline/core`.
+
+### Plugins
+
+Plugins can contribute tools and hooks at setup time:
+
+```ts
+import type { AgentRuntimePlugin } from "@cline/shared";
+
+const loggingPlugin: AgentRuntimePlugin = {
+	name: "logging",
+	setup({ agentId }) {
+		return {
+			hooks: {
+				afterTool({ tool, result }) {
+					console.log(agentId, tool.name, result.isError);
+					return undefined; // hook may return an AgentAfterToolResult
+				},
+			},
+		};
+	},
+};
+
+new Agent({
+	providerId,
+	modelId,
+	apiKey,
+	plugins: [loggingPlugin],
+});
+```
+
+### Teams and Spawn
+
+For multi-agent workflows, use `@cline/core`:
+
+```ts
+import {
+	createSpawnAgentTool,
+	AgentTeamsRuntime,
+	createAgentTeamsTools,
+	bootstrapAgentTeams,
+} from "@cline/core";
+```
+
+These helpers provide coordination primitives for delegated runs,
+mailboxes, task management, and outcome convergence.
+
+## Entry Point
+
+- `@cline/agents` — the single package entrypoint. The `package.json`
+  `exports` map automatically serves a browser-safe bundle when bundlers
+  resolve the `browser` condition.
+
+## Related Packages
+
+- `@cline/shared`: shared types (`AgentTool`, `AgentMessage`,
+  `AgentRuntimeEvent`, `AgentRuntimeHooks`, etc.)
+- `@cline/llms`: provider settings, model catalogs, and gateway/handler
+  creation
+- `@cline/core`: stateful runtime assembly, storage, default tools,
+  subprocess hooks, hub transport, and MCP integration
+
+## More Examples
+
+- Repo examples:
+  [examples/plugins](https://github.com/cline/sdk/tree/main/examples/plugins),
+  [examples/hooks](https://github.com/cline/sdk/tree/main/examples/hooks),
+  [examples/cron](https://github.com/cline/sdk/tree/main/examples/cron)
+- 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-runtime.d.ts

@@ -0,0 +1,99 @@
+import type { AgentMessage, AgentModel, AgentRunResult, AgentRuntimeEvent, AgentRuntimeStateSnapshot, AgentRuntimeConfig as BaseAgentRuntimeConfig } from "@cline/shared";
+export type AgentRunInput = string | AgentMessage | readonly AgentMessage[];
+export type AgentEventListener = (event: AgentRuntimeEvent) => void;
+/**
+ * Advanced form: caller supplies a pre-built `AgentModel`. Used by
+ * `@cline/core`, which constructs models itself to share gateway/telemetry
+ * wiring with the rest of the session runtime.
+ */
+export interface AgentRuntimeConfigWithModel extends BaseAgentRuntimeConfig {
+    model: AgentModel;
+}
+/**
+ * Friendly form: caller supplies provider/model IDs and credentials, and the
+ * runtime builds an `AgentModel` internally via `@cline/llms`. This is the
+ * entry point most standalone users want.
+ */
+export interface AgentRuntimeConfigWithProvider extends Omit<BaseAgentRuntimeConfig, "model"> {
+    /** Provider ID (e.g., "anthropic", "openai") */
+    providerId: string;
+    /** Model ID to use */
+    modelId: string;
+    /** API key for the provider */
+    apiKey?: string;
+    /** Custom base URL for the API */
+    baseUrl?: string;
+    /** Additional headers for API requests */
+    headers?: Record<string, string>;
+}
+/**
+ * Config accepted by `new AgentRuntime(...)` / `createAgentRuntime(...)` /
+ * `new Agent(...)` / `createAgent(...)`. Either supply a pre-built `model`
+ * (advanced) or `providerId` + `modelId` (+ credentials) and the runtime will
+ * construct the model itself via `@cline/llms`.
+ */
+export type AgentRuntimeConfig = AgentRuntimeConfigWithModel | AgentRuntimeConfigWithProvider;
+export declare class AgentRuntime {
+    private config;
+    private readonly listeners;
+    private readonly tools;
+    private hooks;
+    private readonly state;
+    private initialization?;
+    private abortController?;
+    constructor(config: AgentRuntimeConfig);
+    run(input: AgentRunInput): Promise<AgentRunResult>;
+    continue(input?: AgentRunInput): Promise<AgentRunResult>;
+    abort(reason?: unknown): void;
+    subscribe(listener: AgentEventListener): () => void;
+    /**
+     * Replace the conversation with a fresh set of messages, discarding any
+     * in-flight run and usage state while preserving the underlying model,
+     * tools, hooks, plugins, and active event subscribers.
+     *
+     * Useful for standalone callers that persist conversations externally and
+     * want to re-seed the runtime from storage without recreating subscribers.
+     */
+    restore(messages: readonly AgentMessage[]): void;
+    snapshot(): AgentRuntimeStateSnapshot;
+    private ensureInitialized;
+    private initialize;
+    private registerHooks;
+    private getRequiredCompletionToolNames;
+    private getCompletionToolReminderMessage;
+    private getCompletionReminderMessages;
+    private addUserReminderMessage;
+    private execute;
+    private callBeforeRunHooks;
+    private callAfterRunHooks;
+    private generateAssistantMessage;
+    private prepareTurnForModelRequest;
+    private consumePendingUserMessage;
+    private updateUsage;
+    private executeToolCalls;
+    private findCompletingToolMessage;
+    private prepareToolExecution;
+    private requestToolApproval;
+    private executePreparedTool;
+    private finishRun;
+    private findLastAssistantMessage;
+    private throwIfAborted;
+    private normalizeAbortError;
+    private emit;
+    private applyStopControl;
+}
+export declare function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime;
+/**
+ * `Agent` is the user-friendly name for `AgentRuntime`. They are the same
+ * class; this alias exists so standalone callers can write:
+ *
+ *     const agent = new Agent({ providerId, modelId, apiKey });
+ *     await agent.run("hello");
+ *
+ * while `@cline/core` (which owns model construction) continues to use
+ * the `AgentRuntime` name with `{ model, ... }` configs.
+ */
+export declare const Agent: typeof AgentRuntime;
+export type Agent = AgentRuntime;
+export declare function createAgent(config: AgentRuntimeConfig): AgentRuntime;
+//# sourceMappingURL=agent-runtime.d.ts.map

package/dist/agent-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runtime.d.ts","sourceRoot":"","sources":["../src/agent-runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAIX,YAAY,EAEZ,UAAU,EAGV,cAAc,EACd,iBAAiB,EAEjB,yBAAyB,EAOzB,kBAAkB,IAAI,sBAAsB,EAI5C,MAAM,eAAe,CAAC;AAavB,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,YAAY,GAAG,SAAS,YAAY,EAAE,CAAC;AAC5E,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAEpE;;;;GAIG;AACH,MAAM,WAAW,2BAA4B,SAAQ,sBAAsB;IAC1E,KAAK,EAAE,UAAU,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,8BAChB,SAAQ,IAAI,CAAC,sBAAsB,EAAE,OAAO,CAAC;IAC7C,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAC3B,2BAA2B,GAC3B,8BAA8B,CAAC;AAsQlC,qBAAa,YAAY;IACxB,OAAO,CAAC,MAAM,CACU;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAE3D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0C;IAChE,OAAO,CAAC,KAAK,CAQX;IACF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAWpB;IACF,OAAO,CAAC,cAAc,CAAC,CAAgB;IACvC,OAAO,CAAC,eAAe,CAAC,CAAkB;gBAE9B,MAAM,EAAE,kBAAkB;IAYhC,GAAG,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;IAIlD,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;IAI9D,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAgB7B,SAAS,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,IAAI;IAOnD;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,GAAG,IAAI;IAkBhD,QAAQ,IAAI,yBAAyB;YAgBvB,iBAAiB;YAKjB,UAAU;IAkBxB,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,8BAA8B;IAUtC,OAAO,CAAC,gCAAgC;IAUxC,OAAO,CAAC,6BAA6B;YAOvB,sBAAsB;YAWtB,OAAO;YAqLP,kBAAkB;YASlB,iBAAiB;YAMjB,wBAAwB;YA4OxB,0BAA0B;YA6C1B,yBAAyB;YAmBzB,WAAW;YAiBX,gBAAgB;IAqB9B,OAAO,CAAC,yBAAyB;YAsBnB,oBAAoB;YA+EpB,mBAAmB;YAwCnB,mBAAmB;IAkGjC,OAAO,CAAC,SAAS;IAoBjB,OAAO,CAAC,wBAAwB;IAMhC,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,mBAAmB;YAWb,IAAI;IAwDlB,OAAO,CAAC,gBAAgB;CAWxB;AAkHD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAE3E;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,KAAK,qBAAe,CAAC;AAClC,MAAM,MAAM,KAAK,GAAG,YAAY,CAAC;AAEjC,wBAAgB,WAAW,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAEpE"}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @cline/agents
+ *
+ * Browser-safe agent runtime for the next-generation Cline SDK.
+ *
+ * Exports:
+ *   - `AgentRuntime` / `Agent` — the agentic loop class (two names for the
+ *     same class). Use `Agent` when supplying provider/model IDs, or
+ *     `AgentRuntime` when supplying a pre-built `AgentModel`.
+ *   - `createAgentRuntime` / `createAgent` — factory-function equivalents.
+ *   - `AgentRuntimeConfig` and its two variants (`AgentRuntimeConfigWithModel`,
+ *     `AgentRuntimeConfigWithProvider`) — the discriminated config union.
+ *   - `AgentRunInput` / `AgentEventListener` — convenience type aliases.
+ *   - `createTool` — re-exported from `@cline/shared` for authoring tools.
+ *
+ * Shared types (`AgentMessage`, `AgentRunResult`, etc.) should be imported
+ * directly from `@cline/shared`.
+ */
+export type { AgentAfterToolResult, AgentBeforeModelResult, AgentBeforeToolResult, AgentMessage, AgentMessagePart, AgentModel, AgentModelFinishReason, AgentModelRequest, AgentRunResult, AgentRuntimeConfig as BaseAgentRuntimeConfig, AgentRuntimeEvent, AgentRuntimeHooks, AgentRuntimeStateSnapshot, AgentStopControl, AgentTool, AgentToolCallPart, AgentToolDefinition, AgentToolResult, AgentUsage, ToolApprovalResult, ToolPolicy, } from "@cline/shared";
+export { createTool } from "@cline/shared";
+export type { AgentEventListener, AgentRunInput, AgentRuntimeConfig, AgentRuntimeConfigWithModel, AgentRuntimeConfigWithProvider, } from "./agent-runtime";
+export { Agent, AgentRuntime, createAgent, createAgentRuntime, } from "./agent-runtime";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,YAAY,EACX,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,sBAAsB,EACtB,iBAAiB,EACjB,cAAc,EACd,kBAAkB,IAAI,sBAAsB,EAC5C,iBAAiB,EACjB,iBAAiB,EACjB,yBAAyB,EACzB,gBAAgB,EAChB,SAAS,EACT,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,UAAU,EACV,kBAAkB,EAClB,UAAU,GACV,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,YAAY,EACX,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,2BAA2B,EAC3B,8BAA8B,GAC9B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACN,KAAK,EACL,YAAY,EACZ,WAAW,EACX,kBAAkB,GAClB,MAAM,iBAAiB,CAAC"}