@clinebot/core 0.0.0

package/src/runtime/sandbox/subprocess-sandbox.ts

@@ -0,0 +1,207 @@
+import { type ChildProcess, spawn } from "node:child_process";
+
+interface SandboxCallMessage {
+	type: "call";
+	id: string;
+	method: string;
+	args: unknown;
+}
+
+interface SandboxResponseMessage {
+	type: "response";
+	id: string;
+	ok: boolean;
+	result?: unknown;
+	error?: { message: string; stack?: string };
+}
+
+export interface SubprocessSandboxOptions {
+	bootstrapScript: string;
+	name?: string;
+}
+
+export interface SandboxCallOptions {
+	timeoutMs?: number;
+}
+
+type PendingRequest = {
+	resolve: (value: unknown) => void;
+	reject: (error: Error) => void;
+	timeout?: NodeJS.Timeout;
+};
+
+function asError(value: unknown): Error {
+	if (value instanceof Error) {
+		return value;
+	}
+	return new Error(String(value));
+}
+
+export class SubprocessSandbox {
+	private readonly options: SubprocessSandboxOptions;
+	private process: ChildProcess | null = null;
+	private requestCounter = 0;
+	private readonly pending = new Map<string, PendingRequest>();
+
+	constructor(options: SubprocessSandboxOptions) {
+		this.options = options;
+	}
+
+	start(): void {
+		if (this.process && this.process.exitCode === null) {
+			return;
+		}
+
+		const child = spawn(
+			process.execPath,
+			["-e", this.options.bootstrapScript],
+			{
+				stdio: ["ignore", "ignore", "ignore", "ipc"],
+			},
+		);
+		this.process = child;
+		child.on("message", (message) => {
+			this.onMessage(message as SandboxResponseMessage);
+		});
+		child.on("error", (error) => {
+			this.failPending(
+				new Error(
+					`${this.options.name ?? "sandbox"} process error: ${asError(error).message}`,
+				),
+			);
+		});
+		child.on("exit", (code, signal) => {
+			this.process = null;
+			this.failPending(
+				new Error(
+					`${this.options.name ?? "sandbox"} process exited (code=${String(code)}, signal=${String(signal)})`,
+				),
+			);
+		});
+	}
+
+	async call<TResult = unknown>(
+		method: string,
+		args: unknown,
+		options: SandboxCallOptions = {},
+	): Promise<TResult> {
+		this.start();
+		const child = this.process;
+		if (!child || child.exitCode !== null) {
+			throw new Error(
+				`${this.options.name ?? "sandbox"} process is not available`,
+			);
+		}
+
+		const id = `req_${++this.requestCounter}`;
+		const message: SandboxCallMessage = {
+			type: "call",
+			id,
+			method,
+			args,
+		};
+
+		return await new Promise<TResult>((resolve, reject) => {
+			const pending: PendingRequest = {
+				resolve: (value) => resolve(value as TResult),
+				reject,
+			};
+			if ((options.timeoutMs ?? 0) > 0) {
+				pending.timeout = setTimeout(() => {
+					this.pending.delete(id);
+					this.shutdown().catch(() => {
+						// Best-effort process shutdown after timeout.
+					});
+					reject(
+						new Error(
+							`${this.options.name ?? "sandbox"} call timed out after ${options.timeoutMs}ms: ${method}`,
+						),
+					);
+				}, options.timeoutMs);
+			}
+			this.pending.set(id, pending);
+			child.send(message, (error) => {
+				if (!error) {
+					return;
+				}
+				const entry = this.pending.get(id);
+				if (!entry) {
+					return;
+				}
+				this.pending.delete(id);
+				if (entry.timeout) {
+					clearTimeout(entry.timeout);
+				}
+				entry.reject(
+					new Error(
+						`${this.options.name ?? "sandbox"} failed to send call "${method}": ${asError(error).message}`,
+					),
+				);
+			});
+		});
+	}
+
+	async shutdown(): Promise<void> {
+		const child = this.process;
+		this.process = null;
+		if (!child || child.exitCode !== null) {
+			this.failPending(new Error(`${this.options.name ?? "sandbox"} shutdown`));
+			return;
+		}
+		await new Promise<void>((resolve) => {
+			const timeout = setTimeout(() => {
+				try {
+					child.kill("SIGKILL");
+				} catch {
+					// Ignore kill failures.
+				}
+				resolve();
+			}, 300);
+			child.once("exit", () => {
+				clearTimeout(timeout);
+				resolve();
+			});
+			try {
+				child.kill("SIGTERM");
+			} catch {
+				clearTimeout(timeout);
+				resolve();
+			}
+		});
+		this.failPending(new Error(`${this.options.name ?? "sandbox"} shutdown`));
+	}
+
+	private onMessage(message: SandboxResponseMessage): void {
+		if (!message || message.type !== "response" || !message.id) {
+			return;
+		}
+		const pending = this.pending.get(message.id);
+		if (!pending) {
+			return;
+		}
+		this.pending.delete(message.id);
+		if (pending.timeout) {
+			clearTimeout(pending.timeout);
+		}
+		if (message.ok) {
+			pending.resolve(message.result);
+			return;
+		}
+		pending.reject(
+			new Error(
+				message.error?.message ||
+					`${this.options.name ?? "sandbox"} call failed`,
+			),
+		);
+	}
+
+	private failPending(error: Error): void {
+		for (const [id, pending] of this.pending.entries()) {
+			this.pending.delete(id);
+			if (pending.timeout) {
+				clearTimeout(pending.timeout);
+			}
+			pending.reject(error);
+		}
+	}
+}

package/src/runtime/session-runtime.ts

@@ -0,0 +1,44 @@
+import type {
+	AgentConfig,
+	AgentHooks,
+	AgentResult,
+	AgentTeamsRuntime,
+	Tool,
+} from "@clinebot/agents";
+import type { BasicLogger } from "@clinebot/shared";
+import type { UserInstructionConfigWatcher } from "../agents";
+import type { ToolExecutors } from "../default-tools";
+import type { CoreSessionConfig } from "../types/config";
+
+export interface BuiltRuntime {
+	tools: Tool[];
+	hooks?: AgentHooks;
+	logger?: BasicLogger;
+	teamRuntime?: AgentTeamsRuntime;
+	completionGuard?: () => string | undefined;
+	shutdown: (reason: string) => Promise<void> | void;
+}
+
+export interface RuntimeBuilderInput {
+	config: CoreSessionConfig;
+	hooks?: AgentHooks;
+	extensions?: AgentConfig["extensions"];
+	onTeamEvent?: (event: import("@clinebot/agents").TeamEvent) => void;
+	createSpawnTool?: () => Tool;
+	onTeamRestored?: () => void;
+	userInstructionWatcher?: UserInstructionConfigWatcher;
+	defaultToolExecutors?: Partial<ToolExecutors>;
+	logger?: BasicLogger;
+}
+
+export interface RuntimeBuilder {
+	build(input: RuntimeBuilderInput): BuiltRuntime;
+}
+
+export interface SessionRuntime {
+	start(config: CoreSessionConfig): Promise<{ sessionId: string }>;
+	send(sessionId: string, prompt: string): Promise<AgentResult | undefined>;
+	abort(sessionId: string): Promise<void>;
+	stop(sessionId: string): Promise<void>;
+	poll(): Promise<string[]>;
+}

package/src/runtime/tool-approval.ts

@@ -0,0 +1,104 @@
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ToolApprovalRequest, ToolApprovalResult } from "@clinebot/agents";
+
+export type DesktopToolApprovalOptions = {
+	approvalDir?: string;
+	sessionId?: string;
+	timeoutMs?: number;
+	pollIntervalMs?: number;
+	nowIso?: () => string;
+};
+
+function sanitizeApprovalToken(value: string): string {
+	return value.replace(/[^a-zA-Z0-9._-]+/g, "_");
+}
+
+function delay(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function requestDesktopToolApproval(
+	request: ToolApprovalRequest,
+	options: DesktopToolApprovalOptions = {},
+): Promise<ToolApprovalResult> {
+	const approvalDir = options.approvalDir?.trim();
+	const sessionId = options.sessionId?.trim();
+	if (!approvalDir || !sessionId) {
+		return {
+			approved: false,
+			reason: "Desktop tool approval IPC is not configured",
+		};
+	}
+
+	await mkdir(approvalDir, { recursive: true });
+	const requestId = sanitizeApprovalToken(`${request.toolCallId}`);
+	const requestPath = join(
+		approvalDir,
+		`${sessionId}.request.${requestId}.json`,
+	);
+	const decisionPath = join(
+		approvalDir,
+		`${sessionId}.decision.${requestId}.json`,
+	);
+	const nowIso = options.nowIso ?? (() => new Date().toISOString());
+
+	await writeFile(
+		requestPath,
+		`${JSON.stringify(
+			{
+				requestId,
+				sessionId,
+				createdAt: nowIso(),
+				toolCallId: request.toolCallId,
+				toolName: request.toolName,
+				input: request.input,
+				iteration: request.iteration,
+				agentId: request.agentId,
+				conversationId: request.conversationId,
+			},
+			null,
+			2,
+		)}\n`,
+		"utf8",
+	);
+
+	const timeoutMs = options.timeoutMs ?? 5 * 60_000;
+	const pollIntervalMs = options.pollIntervalMs ?? 200;
+	const startedAt = Date.now();
+	while (Date.now() - startedAt < timeoutMs) {
+		try {
+			const raw = await readFile(decisionPath, "utf8");
+			const parsed = JSON.parse(raw) as {
+				approved?: boolean;
+				reason?: string;
+			};
+			const result = {
+				approved: parsed.approved === true,
+				reason: typeof parsed.reason === "string" ? parsed.reason : undefined,
+			};
+			try {
+				await unlink(decisionPath);
+			} catch {
+				// Best-effort cleanup.
+			}
+			try {
+				await unlink(requestPath);
+			} catch {
+				// Best-effort cleanup.
+			}
+			return result;
+		} catch {
+			// Decision not available yet.
+		}
+		await delay(pollIntervalMs);
+	}
+
+	try {
+		await unlink(requestPath);
+	} catch {
+		// Best-effort cleanup.
+	}
+
+	return { approved: false, reason: "Tool approval request timed out" };
+}

package/src/runtime/workflows.test.ts

@@ -0,0 +1,119 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { createUserInstructionConfigWatcher } from "../agents";
+import {
+	listAvailableWorkflowsFromWatcher,
+	resolveWorkflowSlashCommandFromWatcher,
+} from "./workflows";
+
+describe("runtime workflows helpers", () => {
+	const tempRoots: string[] = [];
+
+	afterEach(async () => {
+		await Promise.all(
+			tempRoots.map((dir) => rm(dir, { recursive: true, force: true })),
+		);
+		tempRoots.length = 0;
+	});
+
+	it("lists only enabled workflows from watcher snapshots", async () => {
+		const tempRoot = await mkdtemp(join(tmpdir(), "core-runtime-workflows-"));
+		tempRoots.push(tempRoot);
+		const workflowsDir = join(tempRoot, "workflows");
+		await mkdir(workflowsDir, { recursive: true });
+		await writeFile(
+			join(workflowsDir, "enabled.md"),
+			`---
+name: enabled-workflow
+---
+Run enabled workflow.`,
+		);
+		await writeFile(
+			join(workflowsDir, "disabled.md"),
+			`---
+name: disabled-workflow
+disabled: true
+---
+Run disabled workflow.`,
+		);
+
+		const watcher = createUserInstructionConfigWatcher({
+			skills: { directories: [] },
+			rules: { directories: [] },
+			workflows: { directories: [workflowsDir] },
+		});
+
+		try {
+			await watcher.start();
+			expect(listAvailableWorkflowsFromWatcher(watcher)).toEqual([
+				{
+					id: "enabled-workflow",
+					name: "enabled-workflow",
+					instructions: "Run enabled workflow.",
+				},
+			]);
+		} finally {
+			watcher.stop();
+		}
+	});
+
+	it("expands leading slash commands and preserves trailing user text", async () => {
+		const tempRoot = await mkdtemp(join(tmpdir(), "core-runtime-workflows-"));
+		tempRoots.push(tempRoot);
+		const workflowsDir = join(tempRoot, "workflows");
+		await mkdir(workflowsDir, { recursive: true });
+		await writeFile(
+			join(workflowsDir, "release.md"),
+			`---
+name: release
+---
+Run the release workflow.`,
+		);
+		await writeFile(
+			join(workflowsDir, "disabled.md"),
+			`---
+name: disabled
+disabled: true
+---
+Do not run this workflow.`,
+		);
+
+		const watcher = createUserInstructionConfigWatcher({
+			skills: { directories: [] },
+			rules: { directories: [] },
+			workflows: { directories: [workflowsDir] },
+		});
+
+		try {
+			await watcher.start();
+			expect(resolveWorkflowSlashCommandFromWatcher("/release", watcher)).toBe(
+				"Run the release workflow.",
+			);
+			expect(
+				resolveWorkflowSlashCommandFromWatcher("  /release  ", watcher),
+			).toBe("  /release  ");
+			expect(resolveWorkflowSlashCommandFromWatcher("/disabled", watcher)).toBe(
+				"/disabled",
+			);
+			expect(resolveWorkflowSlashCommandFromWatcher("/missing", watcher)).toBe(
+				"/missing",
+			);
+			expect(
+				resolveWorkflowSlashCommandFromWatcher("/release now", watcher),
+			).toBe("Run the release workflow. now");
+			expect(
+				resolveWorkflowSlashCommandFromWatcher(
+					"/release   use javascript",
+					watcher,
+				),
+			).toBe("Run the release workflow.   use javascript");
+			expect(
+				resolveWorkflowSlashCommandFromWatcher("please run /release", watcher),
+			).toBe("please run /release");
+		} finally {
+			watcher.stop();
+		}
+	});
+});

package/src/runtime/workflows.ts

@@ -0,0 +1,54 @@
+import type { UserInstructionConfigWatcher, WorkflowConfig } from "../agents";
+
+export type AvailableWorkflow = {
+	id: string;
+	name: string;
+	instructions: string;
+};
+
+function isWorkflowEnabled(workflow: WorkflowConfig): boolean {
+	return workflow.disabled !== true;
+}
+
+export function listAvailableWorkflowsFromWatcher(
+	watcher: UserInstructionConfigWatcher,
+): AvailableWorkflow[] {
+	const snapshot = watcher.getSnapshot("workflow");
+	return [...snapshot.entries()]
+		.map(([id, record]) => ({ id, workflow: record.item as WorkflowConfig }))
+		.filter(({ workflow }) => isWorkflowEnabled(workflow))
+		.map(({ id, workflow }) => ({
+			id,
+			name: workflow.name,
+			instructions: workflow.instructions,
+		}))
+		.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Expands a leading slash command (e.g. "/release") to workflow instructions.
+ * If the input starts with "/<workflow-name>", that prefix is replaced and the
+ * remaining input is preserved unchanged.
+ */
+export function resolveWorkflowSlashCommandFromWatcher(
+	input: string,
+	watcher: UserInstructionConfigWatcher,
+): string {
+	if (!input.startsWith("/") || input.length < 2) {
+		return input;
+	}
+	const match = input.match(/^\/(\S+)/);
+	if (!match) {
+		return input;
+	}
+	const workflowName = match[1];
+	if (!workflowName) {
+		return input;
+	}
+	const commandLength = workflowName.length + 1;
+	const remainder = input.slice(commandLength);
+	const matched = listAvailableWorkflowsFromWatcher(watcher).find(
+		(workflow) => workflow.name === workflowName,
+	);
+	return matched ? `${matched.instructions}${remainder}` : input;
+}