@clinebot/agents 0.0.0

package/src/index.ts

@@ -0,0 +1,133 @@
+/**
+ * @clinebot/agents
+ *
+ * Public API for building agentic loops.
+ */
+
+// =============================================================================
+// Core Agent
+// =============================================================================
+
+export { Agent, createAgent } from "./agent.js";
+
+// =============================================================================
+// Tooling (consumer-facing)
+// =============================================================================
+
+export {
+	type AskQuestionExecutor,
+	type AskQuestionInput,
+	AskQuestionInputSchema,
+	type AskQuestionToolConfig,
+	createAskQuestionTool,
+	createTool,
+	toToolDefinition,
+	toToolDefinitions,
+} from "./tools/index.js";
+
+// =============================================================================
+// Hooks
+// =============================================================================
+
+export {
+	type HookDispatchInput,
+	HookEngine,
+	type HookHandler,
+} from "./hooks/index.js";
+export type {
+	HookEventName,
+	HookEventPayload,
+	RunHookOptions,
+	RunHookResult,
+	RunSubprocessEventOptions,
+	RunSubprocessEventResult,
+	SubprocessHookControl,
+	SubprocessHooksOptions,
+} from "./hooks/node.js";
+export {
+	createSubprocessHooks,
+	HookEventNameSchema,
+	HookEventPayloadSchema,
+	parseHookEventPayload,
+	runHook,
+	runSubprocessEvent,
+} from "./hooks/node.js";
+
+// =============================================================================
+// Prompts and formatting
+// =============================================================================
+
+export { formatFileContentBlock } from "@clinebot/shared";
+export { getClineDefaultSystemPrompt } from "./prompts/index.js";
+
+// =============================================================================
+// Teams and spawn support
+// =============================================================================
+
+export {
+	AgentTeamsRuntime,
+	type AgentTeamsRuntimeOptions,
+	type BootstrapAgentTeamsOptions,
+	type BootstrapAgentTeamsResult,
+	bootstrapAgentTeams,
+	type CreateAgentTeamsToolsOptions,
+	createAgentTeamsTools,
+	createSpawnAgentTool,
+	type SubAgentEndContext,
+	type SubAgentStartContext,
+	type TeamEvent,
+	type TeammateLifecycleSpec,
+	type TeamOutcome,
+	type TeamOutcomeFragment,
+	type TeamRunRecord,
+	type TeamRunStatus,
+	type TeamRuntimeState,
+	type TeamTeammateRuntimeConfig,
+	type TeamTeammateSpec,
+} from "./teams/index.js";
+
+// =============================================================================
+// MCP bridge
+// =============================================================================
+
+export {
+	type CreateDisabledMcpToolPoliciesOptions,
+	type CreateDisabledMcpToolPolicyOptions,
+	type CreateMcpToolsOptions,
+	createDisabledMcpToolPolicies,
+	createDisabledMcpToolPolicy,
+	createMcpTools,
+	type McpToolCallRequest,
+	type McpToolCallResult,
+	type McpToolDescriptor,
+	type McpToolNameTransform,
+	type McpToolProvider,
+} from "./mcp/index.js";
+
+// =============================================================================
+// Public types
+// =============================================================================
+
+export {
+	type AgentConfig,
+	AgentConfigSchema,
+	type AgentEvent,
+	type AgentHooks,
+	type AgentResult,
+	AgentResultSchema,
+	type AgentUsage,
+	AgentUsageSchema,
+	type BasicLogger,
+	type ContentBlock,
+	type HookErrorMode,
+	type Message,
+	type ModelInfo,
+	type Tool,
+	type ToolApprovalRequest,
+	type ToolApprovalResult,
+	type ToolCallRecord,
+	ToolCallRecordSchema,
+	type ToolContext,
+	ToolContextSchema,
+	type ToolPolicy,
+} from "./types.js";

package/src/mcp/index.ts

@@ -0,0 +1,17 @@
+export type {
+	CreateDisabledMcpToolPoliciesOptions,
+	CreateDisabledMcpToolPolicyOptions,
+} from "./policies.js";
+export {
+	createDisabledMcpToolPolicies,
+	createDisabledMcpToolPolicy,
+} from "./policies.js";
+export { createMcpTools } from "./tools.js";
+export type {
+	CreateMcpToolsOptions,
+	McpToolCallRequest,
+	McpToolCallResult,
+	McpToolDescriptor,
+	McpToolNameTransform,
+	McpToolProvider,
+} from "./types.js";

package/src/mcp/policies.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import {
+	createDisabledMcpToolPolicies,
+	createDisabledMcpToolPolicy,
+} from "./policies.js";
+
+describe("mcp policy helpers", () => {
+	it("creates a disabled policy for a single MCP tool", () => {
+		expect(
+			createDisabledMcpToolPolicy({
+				serverName: "docs",
+				toolName: "search",
+			}),
+		).toEqual({
+			docs__search: {
+				enabled: false,
+			},
+		});
+	});
+
+	it("creates disabled policies for multiple MCP tools", () => {
+		expect(
+			createDisabledMcpToolPolicies({
+				serverName: "docs",
+				toolNames: ["search", "read"],
+			}),
+		).toEqual({
+			docs__search: {
+				enabled: false,
+			},
+			docs__read: {
+				enabled: false,
+			},
+		});
+	});
+
+	it("respects custom MCP tool name transforms", () => {
+		expect(
+			createDisabledMcpToolPolicy({
+				serverName: "docs",
+				toolName: "search",
+				nameTransform: ({ serverName, toolName }) =>
+					`mcp:${serverName}:${toolName}`,
+			}),
+		).toEqual({
+			"mcp:docs:search": {
+				enabled: false,
+			},
+		});
+	});
+});

package/src/mcp/policies.ts

@@ -0,0 +1,53 @@
+import type { ToolPolicy } from "../types.js";
+import type { McpToolNameTransform } from "./types.js";
+
+function defaultMcpToolNameTransform(input: {
+	serverName: string;
+	toolName: string;
+}): string {
+	return `${input.serverName}__${input.toolName}`;
+}
+
+export interface CreateDisabledMcpToolPolicyOptions {
+	serverName: string;
+	toolName: string;
+	nameTransform?: McpToolNameTransform;
+}
+
+export interface CreateDisabledMcpToolPoliciesOptions {
+	serverName: string;
+	toolNames: readonly string[];
+	nameTransform?: McpToolNameTransform;
+}
+
+export function createDisabledMcpToolPolicy(
+	options: CreateDisabledMcpToolPolicyOptions,
+): Record<string, ToolPolicy> {
+	const nameTransform = options.nameTransform ?? defaultMcpToolNameTransform;
+	const name = nameTransform({
+		serverName: options.serverName,
+		toolName: options.toolName,
+	});
+	return {
+		[name]: {
+			enabled: false,
+		},
+	};
+}
+
+export function createDisabledMcpToolPolicies(
+	options: CreateDisabledMcpToolPoliciesOptions,
+): Record<string, ToolPolicy> {
+	const policies: Record<string, ToolPolicy> = {};
+	for (const toolName of options.toolNames) {
+		Object.assign(
+			policies,
+			createDisabledMcpToolPolicy({
+				serverName: options.serverName,
+				toolName,
+				nameTransform: options.nameTransform,
+			}),
+		);
+	}
+	return policies;
+}

package/src/mcp/tools.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it, vi } from "vitest";
+import { createMcpTools } from "./tools.js";
+import type { McpToolDescriptor, McpToolProvider } from "./types.js";
+
+describe("createMcpTools", () => {
+	it("converts MCP tools into agent tools and delegates execution", async () => {
+		const descriptors: readonly McpToolDescriptor[] = [
+			{
+				name: "search_docs",
+				description: "Search documentation",
+				inputSchema: {
+					type: "object",
+					properties: { query: { type: "string" } },
+					required: ["query"],
+				},
+			},
+		];
+		const provider: McpToolProvider = {
+			listTools: vi.fn(async () => descriptors),
+			callTool: vi.fn(async (request) => ({ ok: true, request })),
+		};
+
+		const tools = await createMcpTools({
+			serverName: "docs",
+			provider,
+			timeoutMs: 12000,
+		});
+
+		expect(tools).toHaveLength(1);
+		expect(tools[0].name).toBe("docs__search_docs");
+		expect(tools[0].description).toBe("Search documentation");
+		expect(tools[0].inputSchema.required).toEqual(["query"]);
+		expect(tools[0].timeoutMs).toBe(12000);
+
+		const result = await tools[0].execute(
+			{ query: "mcp auth" },
+			{
+				agentId: "agent-1",
+				conversationId: "conv-1",
+				iteration: 1,
+			},
+		);
+
+		expect(result).toMatchObject({ ok: true });
+		expect(provider.callTool).toHaveBeenCalledWith(
+			expect.objectContaining({
+				serverName: "docs",
+				toolName: "search_docs",
+				arguments: { query: "mcp auth" },
+			}),
+		);
+	});
+
+	it("supports custom MCP tool name transforms", async () => {
+		const provider: McpToolProvider = {
+			listTools: async () => [
+				{
+					name: "list_files",
+					inputSchema: {
+						type: "object",
+						properties: {},
+					},
+				},
+			],
+			callTool: async () => ({ ok: true }),
+		};
+
+		const tools = await createMcpTools({
+			serverName: "workspace",
+			provider,
+			nameTransform: ({ serverName, toolName }) => `${toolName}@${serverName}`,
+		});
+
+		expect(tools[0].name).toBe("list_files@workspace");
+	});
+});

package/src/mcp/tools.ts

@@ -0,0 +1,60 @@
+import { createTool } from "../tools/create.js";
+import type { Tool } from "../types.js";
+import type { CreateMcpToolsOptions, McpToolDescriptor } from "./types.js";
+
+function defaultMcpToolNameTransform(input: {
+	serverName: string;
+	toolName: string;
+}): string {
+	return `${input.serverName}__${input.toolName}`;
+}
+
+function defaultMcpDescription(
+	serverName: string,
+	tool: McpToolDescriptor,
+): string {
+	const base = tool.description?.trim();
+	if (base) {
+		return base;
+	}
+	return `Execute MCP tool "${tool.name}" from server "${serverName}".`;
+}
+
+/**
+ * Convert tools exposed by an MCP server into regular Agent tools.
+ *
+ * The adapter is intentionally thin: the provider remains the source of truth
+ * for connectivity, authorization, caching, and execution behavior.
+ */
+export async function createMcpTools(
+	options: CreateMcpToolsOptions,
+): Promise<Tool[]> {
+	const descriptors = await options.provider.listTools(options.serverName);
+	const nameTransform = options.nameTransform ?? defaultMcpToolNameTransform;
+
+	return descriptors.map((descriptor) => {
+		const agentToolName = nameTransform({
+			serverName: options.serverName,
+			toolName: descriptor.name,
+		});
+
+		return createTool({
+			name: agentToolName,
+			description: defaultMcpDescription(options.serverName, descriptor),
+			inputSchema: descriptor.inputSchema,
+			timeoutMs: options.timeoutMs,
+			retryable: options.retryable,
+			maxRetries: options.maxRetries,
+			execute: async (input: unknown, context) =>
+				options.provider.callTool({
+					serverName: options.serverName,
+					toolName: descriptor.name,
+					arguments:
+						input && typeof input === "object" && !Array.isArray(input)
+							? (input as Record<string, unknown>)
+							: undefined,
+					context,
+				}),
+		});
+	});
+}

package/src/mcp/types.ts

@@ -0,0 +1,41 @@
+import type { ToolContext } from "../types.js";
+
+export interface McpToolDescriptor {
+	name: string;
+	description?: string;
+	inputSchema: Record<string, unknown>;
+}
+
+export interface McpToolCallRequest {
+	serverName: string;
+	toolName: string;
+	arguments?: Record<string, unknown>;
+	context?: ToolContext;
+}
+
+export type McpToolCallResult = unknown;
+
+/**
+ * Minimal MCP capability contract required by the agent package.
+ *
+ * Implementations can be local, remote, cached, persistent, or fully managed by
+ * another package (for example, @clinebot/core).
+ */
+export interface McpToolProvider {
+	listTools(serverName: string): Promise<readonly McpToolDescriptor[]>;
+	callTool(request: McpToolCallRequest): Promise<McpToolCallResult>;
+}
+
+export type McpToolNameTransform = (input: {
+	serverName: string;
+	toolName: string;
+}) => string;
+
+export interface CreateMcpToolsOptions {
+	serverName: string;
+	provider: McpToolProvider;
+	nameTransform?: McpToolNameTransform;
+	timeoutMs?: number;
+	retryable?: boolean;
+	maxRetries?: number;
+}

package/src/message-builder.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it } from "vitest";
+import { MessageBuilder } from "./message-builder.js";
+
+describe("MessageBuilder", () => {
+	it("keeps cached indexes consistent across append and reset flows", () => {
+		const builder = new MessageBuilder();
+		const firstReadUse = {
+			role: "assistant" as const,
+			content: [
+				{
+					type: "tool_use" as const,
+					id: "call_1",
+					name: "read",
+					input: { path: "src/app.ts" },
+				},
+			],
+		};
+		const firstReadResult = {
+			role: "user" as const,
+			content: [
+				{
+					type: "tool_result" as const,
+					tool_use_id: "call_1",
+					content: '[{"path":"src/app.ts","content":"export const v = 1;"}]',
+					is_error: false,
+				},
+			],
+		};
+		const secondReadUse = {
+			role: "assistant" as const,
+			content: [
+				{
+					type: "tool_use" as const,
+					id: "call_2",
+					name: "read",
+					input: { path: "src/app.ts" },
+				},
+			],
+		};
+		const secondReadResult = {
+			role: "user" as const,
+			content: [
+				{
+					type: "tool_result" as const,
+					tool_use_id: "call_2",
+					content: '[{"path":"src/app.ts","content":"export const v = 2;"}]',
+					is_error: false,
+				},
+			],
+		};
+
+		const initial = builder.buildForApi([firstReadUse, firstReadResult]);
+		expect(initial[1]?.content).toEqual(firstReadResult.content);
+
+		const appended = builder.buildForApi([
+			firstReadUse,
+			firstReadResult,
+			secondReadUse,
+			secondReadResult,
+		]);
+		const firstContent = (
+			appended[1] as { content: Array<{ content: string }> }
+		).content[0]?.content;
+		expect(firstContent).toContain("[outdated - see the latest file content]");
+
+		const reset = builder.buildForApi([secondReadUse, secondReadResult]);
+		expect(reset[1]?.content).toEqual(secondReadResult.content);
+	});
+
+	it("truncates long file blocks in user messages", () => {
+		const builder = new MessageBuilder();
+		const longFileContent = "a".repeat(120_500);
+		const messages = [
+			{
+				role: "user" as const,
+				content: [
+					{
+						type: "text" as const,
+						text: "Please review this file.",
+					},
+					{
+						type: "file" as const,
+						path: "src/big.ts",
+						content: longFileContent,
+					},
+				],
+			},
+		];
+
+		const built = builder.buildForApi(messages);
+		const fileBlock = (
+			built[0] as { content: Array<{ type: string; content?: string }> }
+		).content.find((block) => block.type === "file");
+
+		expect(fileBlock?.content).toContain("...[truncated 20500 chars]...");
+		expect(fileBlock?.content).not.toBe(longFileContent);
+	});
+
+	it("replaces outdated file blocks in read tool results", () => {
+		const builder = new MessageBuilder();
+		const firstReadUse = {
+			role: "assistant" as const,
+			content: [
+				{
+					type: "tool_use" as const,
+					id: "call_1",
+					name: "read",
+					input: { path: "src/app.ts" },
+				},
+			],
+		};
+		const firstReadResult = {
+			role: "user" as const,
+			content: [
+				{
+					type: "tool_result" as const,
+					tool_use_id: "call_1",
+					content: [
+						{
+							type: "file" as const,
+							path: "src/app.ts",
+							content: "export const v = 1;",
+						},
+					],
+					is_error: false,
+				},
+			],
+		};
+		const secondReadUse = {
+			role: "assistant" as const,
+			content: [
+				{
+					type: "tool_use" as const,
+					id: "call_2",
+					name: "read",
+					input: { path: "src/app.ts" },
+				},
+			],
+		};
+		const secondReadResult = {
+			role: "user" as const,
+			content: [
+				{
+					type: "tool_result" as const,
+					tool_use_id: "call_2",
+					content: [
+						{
+							type: "file" as const,
+							path: "src/app.ts",
+							content: "export const v = 2;",
+						},
+					],
+					is_error: false,
+				},
+			],
+		};
+
+		const built = builder.buildForApi([
+			firstReadUse,
+			firstReadResult,
+			secondReadUse,
+			secondReadResult,
+		]);
+		const firstToolResult = (
+			built[1] as { content: Array<{ content: unknown }> }
+		).content[0] as {
+			content: Array<{ type: string; content?: string }>;
+		};
+		const firstFile = firstToolResult.content.find(
+			(entry) => entry.type === "file",
+		);
+
+		expect(firstFile?.content).toBe("[outdated - see the latest file content]");
+	});
+});