@clinebot/agents 0.0.0

package/src/message-builder.ts

@@ -0,0 +1,429 @@
+import type { providers as LlmsProviders } from "@clinebot/llms";
+
+const DEFAULT_MAX_TOOL_RESULT_CHARS = 50_000;
+const TARGET_TOOL_NAMES = new Set([
+	"read",
+	"read_files",
+	"bash",
+	"run_commands",
+]);
+const READ_TOOL_NAMES = new Set(["read", "read_files"]);
+const KEEP_CHARS_PER_SIDE = 50_000;
+const OUTDATED_FILE_CONTENT = "[outdated - see the latest file content]";
+
+interface ReadResultRecord {
+	toolUseId: string;
+	paths: string[];
+}
+
+/**
+ * Builds an API-safe message copy without mutating original conversation history.
+ */
+export class MessageBuilder {
+	private indexedMessageCount = 0;
+	private indexedTailRef: LlmsProviders.Message | undefined;
+	private readonly toolNameByIdCache = new Map<string, string>();
+	private readonly readPathsByToolUseIdCache = new Map<string, string[]>();
+	private readonly latestReadToolUseByPathCache = new Map<string, string>();
+	private readResultPathCache = new WeakMap<object, string[]>();
+
+	constructor(
+		private readonly maxToolResultChars = DEFAULT_MAX_TOOL_RESULT_CHARS,
+		private readonly targetToolNames = TARGET_TOOL_NAMES,
+	) {}
+
+	buildForApi(messages: LlmsProviders.Message[]): LlmsProviders.Message[] {
+		this.reindex(messages);
+		const toolNameById = this.toolNameByIdCache;
+		const readPathsByToolUseId = this.readPathsByToolUseIdCache;
+		const latestReadToolUseByPath = this.latestReadToolUseByPathCache;
+
+		return messages.map((message) => {
+			if (!Array.isArray(message.content)) {
+				return message;
+			}
+
+			const content = message.content.map((block) => {
+				if (block.type === "file") {
+					const truncated = this.truncateMiddle(block.content);
+					if (truncated === block.content) {
+						return block;
+					}
+					return {
+						...block,
+						content: truncated,
+					};
+				}
+
+				if (block.type !== "tool_result") {
+					return block;
+				}
+
+				const toolName = toolNameById.get(block.tool_use_id);
+				let nextContent = block.content;
+
+				if (this.isReadTool(toolName)) {
+					const readRecord = this.getReadResultRecord(
+						block,
+						readPathsByToolUseId.get(block.tool_use_id),
+					);
+					if (readRecord) {
+						const outdatedPaths = readRecord.paths.filter(
+							(path) => latestReadToolUseByPath.get(path) !== block.tool_use_id,
+						);
+						if (outdatedPaths.length > 0) {
+							nextContent = this.replaceOutdatedReadContent(
+								nextContent,
+								outdatedPaths,
+							);
+						}
+					}
+				}
+
+				if (this.shouldTruncateTool(toolName)) {
+					nextContent = this.truncateToolResultContent(nextContent);
+				}
+
+				if (nextContent === block.content) {
+					return block;
+				}
+
+				return {
+					...block,
+					content: nextContent,
+				};
+			});
+
+			return {
+				...message,
+				content,
+			};
+		});
+	}
+
+	private reindex(messages: LlmsProviders.Message[]): void {
+		if (messages.length < this.indexedMessageCount) {
+			this.resetIndexes();
+		}
+		if (
+			this.indexedMessageCount > 0 &&
+			messages.length >= this.indexedMessageCount &&
+			messages[this.indexedMessageCount - 1] !== this.indexedTailRef
+		) {
+			this.resetIndexes();
+		}
+
+		for (let i = this.indexedMessageCount; i < messages.length; i++) {
+			const message = messages[i];
+			if (!Array.isArray(message.content)) {
+				continue;
+			}
+
+			for (const block of message.content) {
+				if (block.type === "tool_use") {
+					const normalizedName = block.name.toLowerCase();
+					this.toolNameByIdCache.set(block.id, normalizedName);
+					if (this.isReadTool(normalizedName)) {
+						const paths = this.extractPathsFromReadToolInput(block.input);
+						if (paths.length > 0) {
+							this.readPathsByToolUseIdCache.set(block.id, paths);
+						}
+					}
+					continue;
+				}
+				if (block.type === "tool_result") {
+					const toolName = this.toolNameByIdCache.get(block.tool_use_id);
+					if (!this.isReadTool(toolName)) {
+						continue;
+					}
+					const readRecord = this.getReadResultRecord(
+						block,
+						this.readPathsByToolUseIdCache.get(block.tool_use_id),
+					);
+					if (!readRecord) {
+						continue;
+					}
+					for (const path of readRecord.paths) {
+						this.latestReadToolUseByPathCache.set(path, readRecord.toolUseId);
+					}
+				}
+			}
+		}
+		this.indexedMessageCount = messages.length;
+		this.indexedTailRef =
+			messages.length > 0 ? messages[messages.length - 1] : undefined;
+	}
+
+	private resetIndexes(): void {
+		this.indexedMessageCount = 0;
+		this.indexedTailRef = undefined;
+		this.toolNameByIdCache.clear();
+		this.readPathsByToolUseIdCache.clear();
+		this.latestReadToolUseByPathCache.clear();
+		this.readResultPathCache = new WeakMap<object, string[]>();
+	}
+
+	private getReadResultRecord(
+		block: LlmsProviders.ToolResultContent,
+		fallbackPaths: string[] | undefined,
+	): ReadResultRecord | undefined {
+		const blockRef = block as unknown as object;
+		const cachedParsedPaths = this.readResultPathCache.get(blockRef);
+		const parsedPaths =
+			cachedParsedPaths ??
+			this.extractReadPathsFromToolResultContent(block.content);
+		if (!cachedParsedPaths) {
+			this.readResultPathCache.set(blockRef, parsedPaths);
+		}
+		const paths = parsedPaths.length > 0 ? parsedPaths : (fallbackPaths ?? []);
+		if (paths.length === 0) {
+			return undefined;
+		}
+
+		return {
+			toolUseId: block.tool_use_id,
+			paths,
+		};
+	}
+
+	private extractPathsFromReadToolInput(
+		input: Record<string, unknown>,
+	): string[] {
+		const paths: string[] = [];
+		const maybePath = input.path;
+		const maybeFilePath = input.file_path;
+		const maybeFilePaths = input.file_paths;
+
+		if (typeof maybePath === "string" && maybePath.length > 0) {
+			paths.push(maybePath);
+		}
+		if (typeof maybeFilePath === "string" && maybeFilePath.length > 0) {
+			paths.push(maybeFilePath);
+		}
+		if (Array.isArray(maybeFilePaths)) {
+			for (const value of maybeFilePaths) {
+				if (typeof value === "string" && value.length > 0) {
+					paths.push(value);
+				}
+			}
+		}
+
+		return Array.from(new Set(paths));
+	}
+
+	private extractReadPathsFromToolResultContent(
+		content: LlmsProviders.ToolResultContent["content"],
+	): string[] {
+		if (typeof content !== "string") {
+			return [];
+		}
+
+		try {
+			const parsed = JSON.parse(content);
+			return this.extractPathsFromParsedReadResult(parsed);
+		} catch {
+			return [];
+		}
+	}
+
+	private extractPathsFromParsedReadResult(value: unknown): string[] {
+		if (Array.isArray(value)) {
+			const paths = value
+				.map((item) => this.extractPathFromResultEntry(item))
+				.filter(
+					(path): path is string => typeof path === "string" && path.length > 0,
+				);
+			return Array.from(new Set(paths));
+		}
+
+		const path = this.extractPathFromResultEntry(value);
+		return path ? [path] : [];
+	}
+
+	private extractPathFromResultEntry(value: unknown): string | undefined {
+		if (!value || typeof value !== "object") {
+			return undefined;
+		}
+
+		const record = value as Record<string, unknown>;
+		const candidates = [
+			record.path,
+			record.file_path,
+			record.filePath,
+			record.query,
+		];
+		for (const candidate of candidates) {
+			if (typeof candidate === "string" && candidate.length > 0) {
+				return candidate;
+			}
+		}
+
+		return undefined;
+	}
+
+	private replaceOutdatedReadContent(
+		content: LlmsProviders.ToolResultContent["content"],
+		outdatedPaths: string[],
+	): LlmsProviders.ToolResultContent["content"] {
+		const outdatedPathSet = new Set(outdatedPaths);
+
+		if (typeof content === "string") {
+			const replaced = this.replaceOutdatedReadContentInString(
+				content,
+				outdatedPathSet,
+			);
+			return replaced ?? OUTDATED_FILE_CONTENT;
+		}
+
+		return content.map((entry) => {
+			if (entry.type === "file") {
+				if (!outdatedPathSet.has(entry.path)) {
+					return entry;
+				}
+				return {
+					...(entry as LlmsProviders.FileContent),
+					content: OUTDATED_FILE_CONTENT,
+				};
+			}
+
+			if (entry.type !== "text") {
+				return entry;
+			}
+			const replaced = this.replaceOutdatedReadContentInString(
+				entry.text,
+				outdatedPathSet,
+			);
+			if (replaced === null) {
+				return {
+					...(entry as LlmsProviders.TextContent),
+					text: OUTDATED_FILE_CONTENT,
+				};
+			}
+			if (replaced === entry.text) {
+				return entry;
+			}
+			return {
+				...(entry as LlmsProviders.TextContent),
+				text: replaced,
+			};
+		});
+	}
+
+	private replaceOutdatedReadContentInString(
+		text: string,
+		outdatedPathSet: Set<string>,
+	): string | null {
+		try {
+			const parsed = JSON.parse(text);
+			const replaced = this.replaceOutdatedReadContentInParsed(
+				parsed,
+				outdatedPathSet,
+			);
+			return JSON.stringify(replaced);
+		} catch {
+			return null;
+		}
+	}
+
+	private replaceOutdatedReadContentInParsed(
+		value: unknown,
+		outdatedPathSet: Set<string>,
+	): unknown {
+		if (Array.isArray(value)) {
+			return value.map((entry) =>
+				this.replaceOutdatedReadEntry(entry, outdatedPathSet),
+			);
+		}
+
+		return this.replaceOutdatedReadEntry(value, outdatedPathSet);
+	}
+
+	private replaceOutdatedReadEntry(
+		entry: unknown,
+		outdatedPathSet: Set<string>,
+	): unknown {
+		if (!entry || typeof entry !== "object") {
+			return entry;
+		}
+
+		const record = { ...(entry as Record<string, unknown>) };
+		const path = this.extractPathFromResultEntry(record);
+		if (!path || !outdatedPathSet.has(path)) {
+			return entry;
+		}
+
+		if (typeof record.result === "string") {
+			record.result = OUTDATED_FILE_CONTENT;
+		} else if (typeof record.content === "string") {
+			record.content = OUTDATED_FILE_CONTENT;
+		} else {
+			record.result = OUTDATED_FILE_CONTENT;
+		}
+
+		return record;
+	}
+
+	private isReadTool(toolName: string | undefined): boolean {
+		if (!toolName) {
+			return false;
+		}
+		return READ_TOOL_NAMES.has(toolName.toLowerCase());
+	}
+
+	private shouldTruncateTool(toolName: string | undefined): boolean {
+		if (!toolName) {
+			return false;
+		}
+		return this.targetToolNames.has(toolName.toLowerCase());
+	}
+
+	private truncateToolResultContent(
+		content: LlmsProviders.ToolResultContent["content"],
+	): LlmsProviders.ToolResultContent["content"] {
+		if (typeof content === "string") {
+			return this.truncateMiddle(content);
+		}
+
+		return content.map((entry) => {
+			if (entry.type === "file") {
+				const fileContent = this.truncateMiddle(entry.content);
+				if (fileContent === entry.content) {
+					return entry;
+				}
+				return {
+					...(entry as LlmsProviders.FileContent),
+					content: fileContent,
+				};
+			}
+
+			if (entry.type !== "text") {
+				return entry;
+			}
+
+			const text = this.truncateMiddle(entry.text);
+			if (text === entry.text) {
+				return entry;
+			}
+
+			return {
+				...(entry as LlmsProviders.TextContent),
+				text,
+			};
+		});
+	}
+
+	private truncateMiddle(text: string): string {
+		if (text.length <= this.maxToolResultChars) {
+			return text;
+		}
+
+		const retainedChars = KEEP_CHARS_PER_SIDE * 2;
+		const removedChars = Math.max(0, text.length - retainedChars);
+		const marker = `\n\n...[truncated ${removedChars} chars]...\n\n`;
+
+		const start = text.slice(0, KEEP_CHARS_PER_SIDE);
+		const end = text.slice(-KEEP_CHARS_PER_SIDE);
+
+		return `${start}${marker}${end}`;
+	}
+}

package/src/prompts/cline.ts

@@ -0,0 +1,49 @@
+const DEFAULT_CLINE_SYSTEM_PROMPT = `You are Cline, an AI coding agent. Your primary goal is to assist users with various coding tasks by leveraging your knowledge and the tools at your disposal. Given the user's prompt, you should use the tools available to you to answer user's question.
+
+Always gather all the necessary context before starting to work on a task. For example, if you are generating a unit test or new code, make sure you understand the requirement, the naming conventions, frameworks and libraries used and aligned in the current codebase, and the environment and commands used to run and test the code etc. Always validate the new unit test at the end including running the code if possible for live feedback.
+Review each question carefully and answer it with detailed, accurate information.
+If you need more information, use one of the available tools or ask for clarification instead of making assumptions or lies.
+
+Environment you are running in:
+<env>
+1. Platform: {{PLATFORM_NAME}}
+2. Date: {{CURRENT_DATE}}
+3. IDE: {{IDE_NAME}}
+4. Working Directory: {{CWD}}
+</env>
+
+Remember:
+- Always adhere to existing code conventions and patterns.
+- Use only libraries and frameworks that are confirmed to be in use in the current codebase.
+- Provide complete and functional code without omissions or placeholders.
+- Be explicit about any assumptions or limitations in your solution.
+- Always show your planning process before executing any task. This will help ensure that you have a clear understanding of the requirements and that your approach aligns with the user's needs.
+
+Begin by analyzing the user's input and gathering any necessary additional context. Then, present your plan at the start of your response before proceeding with the task. It's OK for this section to be quite long.
+
+REMEMBER, always be helpful and proactive! Don't ask for permission to do something when you can do it! Do not indicates you will be using a tool unless you are actually going to use it.
+
+When you have completed the task, please provide a summary of what you did and any relevant information that the user should know. This will help ensure that the user understands the changes made and can easily follow up if they have any questions or need further assistance. Do not indicate that you will perform an action without actually doing it. Always provide the final result in your response.
+
+If user asked a simple question without any coding context, answer it directly without using any tools.
+{{CLINE_RULES}}
+{{CLINE_METADATA}}`;
+
+export function getClineDefaultSystemPrompt(
+	ide: string,
+	cwd: string,
+	metadata = "",
+	rules = "",
+) {
+	const platform =
+		typeof process !== "undefined" && process?.platform
+			? process.platform
+			: "unknown";
+	return DEFAULT_CLINE_SYSTEM_PROMPT.replace("{{PLATFORM_NAME}}", platform)
+		.replace("{{CWD}}", cwd)
+		.replace("{{CURRENT_DATE}}", new Date().toLocaleDateString())
+		.replace("{{IDE_NAME}}", ide)
+		.replace("{{CLINE_METADATA}}", metadata)
+		.replace("{{CLINE_RULES}}", rules)
+		.trim();
+}

package/src/prompts/index.ts

@@ -0,0 +1 @@
+export { getClineDefaultSystemPrompt } from "./cline.js";

package/src/runtime/agent-runtime-bus.ts

@@ -0,0 +1,53 @@
+import type { AgentEvent, HookStage } from "../types.js";
+
+export interface LifecycleBusEvent<TPayload = unknown> {
+	stage: HookStage;
+	iteration?: number;
+	payload: TPayload;
+}
+
+export interface AgentRuntimeBus {
+	subscribeRuntimeEvent: (listener: (event: AgentEvent) => void) => () => void;
+	subscribeLifecycleEvent: (
+		listener: (event: LifecycleBusEvent) => void,
+	) => () => void;
+	emitRuntimeEvent: (event: AgentEvent) => void;
+	emitLifecycleEvent: <TPayload>(event: LifecycleBusEvent<TPayload>) => void;
+}
+
+export function createAgentRuntimeBus(): AgentRuntimeBus {
+	let runtimeSeq = 0;
+	let lifecycleSeq = 0;
+	const runtimeListeners = new Map<number, (event: AgentEvent) => void>();
+	const lifecycleListeners = new Map<
+		number,
+		(event: LifecycleBusEvent) => void
+	>();
+
+	return {
+		subscribeRuntimeEvent: (listener) => {
+			const id = ++runtimeSeq;
+			runtimeListeners.set(id, listener);
+			return () => {
+				runtimeListeners.delete(id);
+			};
+		},
+		subscribeLifecycleEvent: (listener) => {
+			const id = ++lifecycleSeq;
+			lifecycleListeners.set(id, listener);
+			return () => {
+				lifecycleListeners.delete(id);
+			};
+		},
+		emitRuntimeEvent: (event) => {
+			for (const listener of runtimeListeners.values()) {
+				listener(event);
+			}
+		},
+		emitLifecycleEvent: (event) => {
+			for (const listener of lifecycleListeners.values()) {
+				listener(event);
+			}
+		},
+	};
+}

package/src/runtime/conversation-store.ts

@@ -0,0 +1,61 @@
+import type { providers } from "@clinebot/llms";
+
+function createConversationId(): string {
+	return `conv_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+}
+
+export class ConversationStore {
+	private messages: providers.Message[] = [];
+	private conversationId = createConversationId();
+	private sessionStarted = false;
+
+	constructor(initialMessages?: providers.Message[]) {
+		if ((initialMessages?.length ?? 0) > 0) {
+			this.restore(initialMessages ?? []);
+		}
+	}
+
+	getConversationId(): string {
+		return this.conversationId;
+	}
+
+	getMessages(): providers.Message[] {
+		return [...this.messages];
+	}
+
+	appendMessage(message: providers.Message): void {
+		this.messages.push(message);
+	}
+
+	appendMessages(messages: providers.Message[]): void {
+		if (messages.length === 0) {
+			return;
+		}
+		this.messages.push(...messages);
+	}
+
+	resetForRun(): void {
+		this.messages = [];
+		this.conversationId = createConversationId();
+		this.sessionStarted = false;
+	}
+
+	clearHistory(): void {
+		this.messages = [];
+		this.conversationId = createConversationId();
+		this.sessionStarted = false;
+	}
+
+	restore(messages: providers.Message[]): void {
+		this.messages = [...messages];
+		this.sessionStarted = false;
+	}
+
+	isSessionStarted(): boolean {
+		return this.sessionStarted;
+	}
+
+	markSessionStarted(): void {
+		this.sessionStarted = true;
+	}
+}

package/src/runtime/lifecycle-orchestrator.ts

@@ -0,0 +1,90 @@
+import type { HookDispatchInput, HookEngine } from "../hooks/index.js";
+import type { AgentEvent, AgentHookControl, HookStage } from "../types.js";
+import type { AgentRuntimeBus } from "./agent-runtime-bus.js";
+
+export interface LifecycleOrchestratorOptions {
+	hookEngine: HookEngine;
+	runtimeBus: AgentRuntimeBus;
+	getRunId: () => string;
+	getAgentId: () => string;
+	getConversationId: () => string;
+	getParentAgentId: () => string | null;
+	onHookContext?: (source: string, context: string) => void;
+	onDispatchError?: (error: unknown) => void;
+}
+
+export class LifecycleOrchestrator {
+	private readonly hookEngine: HookEngine;
+	private readonly runtimeBus: AgentRuntimeBus;
+	private readonly getRunId: () => string;
+	private readonly getAgentId: () => string;
+	private readonly getConversationId: () => string;
+	private readonly getParentAgentId: () => string | null;
+	private readonly onHookContext?: (source: string, context: string) => void;
+	private readonly onDispatchError?: (error: unknown) => void;
+
+	constructor(options: LifecycleOrchestratorOptions) {
+		this.hookEngine = options.hookEngine;
+		this.runtimeBus = options.runtimeBus;
+		this.getRunId = options.getRunId;
+		this.getAgentId = options.getAgentId;
+		this.getConversationId = options.getConversationId;
+		this.getParentAgentId = options.getParentAgentId;
+		this.onHookContext = options.onHookContext;
+		this.onDispatchError = options.onDispatchError;
+	}
+
+	async dispatch(
+		source: string,
+		input: Pick<
+			HookDispatchInput,
+			"stage" | "payload" | "iteration" | "parentEventId"
+		>,
+	): Promise<AgentHookControl | undefined> {
+		this.runtimeBus.emitLifecycleEvent({
+			stage: input.stage,
+			iteration: input.iteration,
+			payload: input.payload,
+		});
+
+		const dispatchResult = await this.hookEngine.dispatch({
+			...input,
+			runId: this.getRunId(),
+			agentId: this.getAgentId(),
+			conversationId: this.getConversationId(),
+			parentAgentId: this.getParentAgentId(),
+		});
+		if (dispatchResult.control?.context) {
+			this.onHookContext?.(source, dispatchResult.control.context);
+		}
+		return dispatchResult.control;
+	}
+
+	dispatchRuntimeEvent(event: AgentEvent): void {
+		void this.hookEngine
+			.dispatch({
+				stage: "runtime_event",
+				runId: this.getRunId(),
+				agentId: this.getAgentId(),
+				conversationId: this.getConversationId(),
+				parentAgentId: this.getParentAgentId(),
+				payload: {
+					agentId: this.getAgentId(),
+					conversationId: this.getConversationId(),
+					parentAgentId: this.getParentAgentId(),
+					event,
+				},
+			})
+			.catch((error) => {
+				this.onDispatchError?.(error);
+			});
+	}
+
+	async shutdown(timeoutMs?: number): Promise<void> {
+		await this.hookEngine.shutdown(timeoutMs);
+	}
+}
+
+export function isBlockingLifecycleStage(stage: HookStage): boolean {
+	return stage !== "runtime_event";
+}