codna 0.1.0__py3-none-any.whl

codna/agent-core/vendor/cline/algenta/acp-editor.ts

@@ -0,0 +1,176 @@
+const DEFAULT_SERVER_NAME = "algenta";
+const DEFAULT_COMMAND = "python";
+const DEFAULT_ARGS = ["-m", "apps.mcp_server.server"] as const;
+const DEFAULT_API_KEY_PLACEHOLDER =
+	"<SET ALGENTA_API_KEY OR DE_API_KEY BEFORE LAUNCH>";
+
+export type EditorIntegrationName =
+	| "cursor"
+	| "zed"
+	| "claude_desktop";
+
+export interface EditorEnvInput {
+	apiKeyPlaceholder?: string;
+	baseUrl?: string;
+	extraEnv?: Readonly<Record<string, string>>;
+}
+
+export interface EditorServerInput extends EditorEnvInput {
+	serverName?: string;
+	command?: string;
+	args?: readonly string[];
+}
+
+export interface EditorIntegrationSurface {
+	editor: EditorIntegrationName;
+	config_path: string;
+	transport: "mcp_stdio";
+	entrypoint_tools: string[];
+	example_prompts: string[];
+	config: Record<string, unknown>;
+}
+
+function requiredString(value: string | undefined, field: string): string {
+	if (typeof value !== "string" || value.trim().length === 0) {
+		throw new Error(`${field} must be a non-empty string.`);
+	}
+	return value.trim();
+}
+
+function optionalString(value: string | undefined): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function normalizeArgs(args: readonly string[] | undefined): string[] {
+	if (!args || args.length === 0) return [...DEFAULT_ARGS];
+	return args.map((arg, index) => requiredString(arg, `args[${index}]`));
+}
+
+function normalizeEnv(input: EditorEnvInput | undefined): Record<string, string> {
+	const env: Record<string, string> = {
+		ALGENTA_API_KEY:
+			optionalString(input?.apiKeyPlaceholder) || DEFAULT_API_KEY_PLACEHOLDER,
+	};
+	const baseUrl = optionalString(input?.baseUrl);
+	if (baseUrl) {
+		env.ALGENTA_BASE_URL = baseUrl;
+	}
+	for (const [key, value] of Object.entries(input?.extraEnv ?? {})) {
+		env[requiredString(key, "extraEnv key")] = requiredString(
+			value,
+			`extraEnv.${key}`,
+		);
+	}
+	return env;
+}
+
+function normalizeServerInput(input: EditorServerInput | undefined): {
+	serverName: string;
+	command: string;
+	args: string[];
+	env: Record<string, string>;
+} {
+	return {
+		serverName:
+			optionalString(input?.serverName) || DEFAULT_SERVER_NAME,
+		command: optionalString(input?.command) || DEFAULT_COMMAND,
+		args: normalizeArgs(input?.args),
+		env: normalizeEnv(input),
+	};
+}
+
+export function buildCursorMcpConfig(
+	input: EditorServerInput = {},
+): Record<string, unknown> {
+	const server = normalizeServerInput(input);
+	return {
+		mcpServers: {
+			[server.serverName]: {
+				command: server.command,
+				args: server.args,
+				env: server.env,
+			},
+		},
+	};
+}
+
+export function buildZedContextServerConfig(
+	input: EditorServerInput = {},
+): Record<string, unknown> {
+	const server = normalizeServerInput(input);
+	return {
+		context_servers: {
+			[server.serverName]: {
+				command: {
+					path: server.command,
+					args: server.args,
+					env: server.env,
+				},
+			},
+		},
+	};
+}
+
+export function buildClaudeDesktopMcpConfig(
+	input: EditorServerInput = {},
+): Record<string, unknown> {
+	return buildCursorMcpConfig({
+		...input,
+		baseUrl: optionalString(input.baseUrl) || "http://localhost:8000",
+	});
+}
+
+function repositoryFixPrompt(serverName: string): string {
+	return `@${serverName} run_repository_fix repository_id='repo_123' pipeline={"signals":{"issue_text":"Null dereference in src/service.py"}} apply={"mode":"patch_only"}`;
+}
+
+function pipelinePrompt(serverName: string): string {
+	return `@${serverName} run_repository_pipeline repository_id='repo_123' pipeline={"signals":{"issue_text":"Investigate elevated p95 latency in src/runtime.ts"}}`;
+}
+
+export function buildEditorIntegrationManifest(
+	input: EditorServerInput = {},
+): EditorIntegrationSurface[] {
+	const server = normalizeServerInput(input);
+	const tools = [
+		"run_repository_pipeline",
+		"simulate_repository_patch",
+		"run_repository_fix",
+	];
+	const prompts = [
+		repositoryFixPrompt(server.serverName),
+		pipelinePrompt(server.serverName),
+	];
+	return [
+		{
+			editor: "cursor",
+			config_path: "~/.cursor/mcp.json",
+			transport: "mcp_stdio",
+			entrypoint_tools: tools,
+			example_prompts: prompts,
+			config: buildCursorMcpConfig(input),
+		},
+		{
+			editor: "zed",
+			config_path: "~/.config/zed/settings.json",
+			transport: "mcp_stdio",
+			entrypoint_tools: tools,
+			example_prompts: prompts,
+			config: buildZedContextServerConfig(input),
+		},
+		{
+			editor: "claude_desktop",
+			config_path: "~/Library/Application Support/Claude/claude_desktop_config.json",
+			transport: "mcp_stdio",
+			entrypoint_tools: tools,
+			example_prompts: prompts,
+			config: buildClaudeDesktopMcpConfig(input),
+		},
+	];
+}
+
+export function renderEditorConfigJson(value: unknown): string {
+	return `${JSON.stringify(value, null, 2)}\n`;
+}

codna/agent-core/vendor/cline/algenta/adapter.ts

@@ -0,0 +1,452 @@
+// Algenta Repositories — real agent-core adapter over the vendored Cline SDK.
+//
+// The helper exports below are shared by the sidecar session server and the
+// single-shot runAgent() wrapper. They resolve provider/model credentials,
+// build a deterministic local ClineCore config, and derive proof-friendly file
+// and tool metadata from the SDK result surface.
+import { ClineCore, Llms } from "@cline/core";
+import { mojoGateAfterTool } from "./mojo-gate";
+import { writeScopeBeforeTool } from "./write-scope";
+import {
+	ALGENTA_PROOF_API_KEY_ENV,
+	ALGENTA_PROOF_MODEL_ID,
+	ALGENTA_PROOF_PROVIDER_ID,
+	ensureAlgentaProofProviderRegistered,
+} from "./proof-provider";
+import {
+	EXACT_RESTORE_SHELL_ONLY_DISABLED_TOOLS,
+	WRITE_TOOLS,
+	exactRestoreDisablesPatchTools,
+	exactRestoreShellOnlyTools,
+	hasExactRestoreContract,
+	suppressedToolsForArgs,
+} from "./task-policy";
+import { type EngineContext, algentaTools, engineContext } from "./tools";
+
+export interface RunAgentArgs {
+	working_dir: string;
+	prompt: string; // the task
+	task_kind?: "fix" | "triage";
+	injected_context?: string; // token-compressed evidence bundle (repo intelligence)
+	provider?: string; // default "anthropic"
+	model?: string; // default = provider's defaultModelId
+	// B10 PR11b: the per-tenant LLM provider key, resolved server-side from the authenticated org
+	// and threaded in per-run (never process-global env). When set it OVERRIDES the env key for
+	// args.provider's backend; when require_provider_api_key is set, a missing per-tenant key FAILS
+	// CLOSED instead of borrowing the shared env key (multi-tenant BYOK).
+	provider_api_key?: string;
+	require_provider_api_key?: boolean;
+	base_url?: string;
+	headers?: Record<string, string>;
+	suppress_exploration?: boolean; // legacy token-reduction flag: block read/search/fetch tools
+	tool_profile?: string; // AR-OPT-4 tool profile (takes precedence over suppress_exploration)
+	limits?: { maxIterations?: number; timeoutMs?: number };
+	enable_spawn_agent?: boolean;
+	enable_agent_teams?: boolean;
+	// Per-run engine config (B3/PR8): threaded into AsyncLocalStorage for the run instead of
+	// process-global env, so concurrent runs are isolated and no API key bleeds across tenants.
+	engine?: { enabled: boolean } & EngineContext;
+}
+
+export interface RunAgentResult {
+	status: string; // AgentFinishReason: completed | max_iterations | aborted | mistake_limit | error
+	agent_run_id: string;
+	text: string;
+	iterations: number;
+	files_changed: string[];
+	usage?: {
+		inputTokens: number;
+		outputTokens: number;
+		cacheReadTokens?: number;
+		cacheWriteTokens?: number;
+		totalCost?: number;
+	};
+	provider: string;
+	model: string;
+}
+
+export { hasExactRestoreContract } from "./task-policy";
+
+// AR-OPT-4 tool profiles — trim the agent's tool surface to cut exploration tokens.
+//   no_exploration_no_shell         -> block exploration AND the shell (most token-frugal;
+//                                       the agent edits purely from the injected bundle).
+//   no_exploration_local_validation -> block exploration; keep the shell so the agent may
+//                                       validate its patch in-sandbox after editing.
+// Falls back to the legacy suppress_exploration flag when no profile is given.
+function suppressedTools(args: RunAgentArgs): string[] {
+	return suppressedToolsForArgs(args);
+}
+
+export interface ResolvedProviderConfig {
+	providerId: string;
+	modelId: string;
+	apiKey: string;
+	baseUrl?: string;
+	headers?: Record<string, string>;
+}
+
+// B10 PR11b: the per-tenant key (set server-side from the authenticated org) wins; otherwise the
+// pooled env key — UNLESS require_provider_api_key is set, in which case a missing per-tenant key
+// FAILS CLOSED (returns undefined -> resolveProviderConfig throws) rather than borrowing the
+// shared env key across tenants. Pure (no SDK) so it is unit-testable.
+export function selectProviderApiKey(
+	args: RunAgentArgs,
+	envNames: string[],
+): string | undefined {
+	const perTenant = args.provider_api_key?.trim();
+	if (perTenant) return perTenant;
+	if (args.require_provider_api_key) return undefined;
+	return envNames.map((k) => process.env[k]?.trim()).find(Boolean);
+}
+
+export async function resolveProviderConfig(
+	args: RunAgentArgs,
+): Promise<ResolvedProviderConfig> {
+	// Resolve provider/model/apiKey from .env via the SDK catalog — any provider.
+	const requested = args.provider || "anthropic";
+	const providerId =
+		(
+			Llms as { normalizeProviderId?: (p: string) => string }
+		).normalizeProviderId?.(requested) ?? requested;
+	if (
+		providerId === ALGENTA_PROOF_PROVIDER_ID ||
+		args.model === ALGENTA_PROOF_MODEL_ID
+	) {
+		ensureAlgentaProofProviderRegistered();
+	}
+	const collection = await Llms.getProviderCollection(providerId);
+	const envNames: string[] = collection?.provider?.env ?? [];
+	const apiKey = selectProviderApiKey(args, envNames);
+	const modelId = args.model || collection?.provider?.defaultModelId;
+	if (!modelId) throw new Error(`no model id for provider '${providerId}'`);
+	if (!apiKey) {
+		if (args.require_provider_api_key) {
+			throw new Error(
+				`no per-tenant API key for provider '${providerId}' and per-tenant keys are required (no shared env-key fallback)`,
+			);
+		}
+		const proofHint =
+			modelId === ALGENTA_PROOF_MODEL_ID
+				? ` (proof model requires ${ALGENTA_PROOF_API_KEY_ENV})`
+				: "";
+		throw new Error(
+			`no API key in env for '${providerId}' (tried: ${envNames.join(", ") || "none"})${proofHint}`,
+		);
+	}
+	return {
+		providerId,
+		modelId,
+		apiKey,
+		baseUrl: args.base_url?.trim() || undefined,
+		headers:
+			args.headers && Object.keys(args.headers).length > 0
+				? { ...args.headers }
+				: undefined,
+	};
+}
+
+export function buildToolPolicies(
+	args: RunAgentArgs,
+	options?: { autoApproveAll?: boolean },
+): Record<string, { enabled?: boolean; autoApprove?: boolean }> {
+	// Auto-approve everything (headless); optionally hard-suppress exploration tools.
+	const autoApproveAll = options?.autoApproveAll !== false;
+	const disabledTools = suppressedTools(args);
+	const toolPolicies: Record<
+		string,
+		{ enabled?: boolean; autoApprove?: boolean }
+	> = {
+		"*": { enabled: true, autoApprove: autoApproveAll },
+	};
+	for (const t of disabledTools) toolPolicies[t] = { enabled: false };
+	if (exactRestoreShellOnlyTools(args)) {
+		for (const toolName of EXACT_RESTORE_SHELL_ONLY_DISABLED_TOOLS) {
+			toolPolicies[toolName] = { enabled: false, autoApprove: false };
+		}
+	}
+	if (exactRestoreDisablesPatchTools(args)) {
+		toolPolicies.editor = { enabled: false, autoApprove: false };
+		toolPolicies.apply_patch = { enabled: false, autoApprove: false };
+	}
+	if (args.task_kind === "triage") {
+		for (const toolName of WRITE_TOOLS) {
+			toolPolicies[toolName] = { enabled: false };
+		}
+	}
+	return toolPolicies;
+}
+
+export function buildSystemPrompt(args: RunAgentArgs): string {
+	const disabledTools = suppressedTools(args);
+	const taskKind = args.task_kind ?? "fix";
+	const guidance =
+		taskKind === "triage"
+			? [
+					"You are Algenta's repository analysis agent.",
+					"Inspect the repository and answer the task directly.",
+					"Do not modify files.",
+					"Do not ask questions.",
+					"The repository root is the current working directory.",
+					"When using file tools, use repository-relative paths only (for example: src/app.ts). Never use absolute paths.",
+				]
+			: [
+					"You are Algenta's automated repository-fixing agent.",
+					"Apply the requested change using your file-editing tools, then stop.",
+					"Do not ask questions.",
+					"The repository root is the current working directory.",
+					"When using file tools, use repository-relative paths only (for example: src/app.ts). Never use absolute paths.",
+				];
+	if (taskKind === "fix" && (disabledTools.length > 0 || args.injected_context)) {
+		guidance.push(
+			"Prefer apply_patch for minimal textual edits. Use editor only when apply_patch is impractical.",
+		);
+	}
+	if (taskKind === "fix" && hasExactRestoreContract(args)) {
+		guidance.push(
+			"This task includes an exact restore contract. Prefer run_commands and execute the provided restore command verbatim before considering any file rewrite.",
+		);
+		guidance.push(
+			"If the prompt provides a fallback restore helper artifact or fallback restore command, do not try git restore first; execute the fallback helper first because local workspace snapshots may not contain the original git tree.",
+		);
+		guidance.push(
+			"When the prompt provides both a fallback restore command and a validator command, run both commands in one run_commands request, in that order, then stop after success.",
+		);
+		guidance.push(
+			"Do not reconstruct, approximate, truncate, or delete-and-recreate the target file when an exact restore path is already provided.",
+		);
+		guidance.push(
+			"After the exact restore succeeds, run the provided validator command and then stop.",
+		);
+	}
+	if (disabledTools.length > 0) {
+		guidance.push(
+			`Do not call policy-disabled tools: ${disabledTools.join(", ")}.`,
+		);
+	}
+	if (args.injected_context) {
+		guidance.push(
+			"Treat the injected repository evidence bundle as authoritative. If it names the target file, edit that file directly instead of exploring the repository.",
+		);
+		guidance.push(
+			"If the bundle includes TARGET FILE EXCERPTS, use those exact lines for the edit and do not spend turns re-reading the same file.",
+		);
+		guidance.push(
+			"If a TARGET FILE EXCERPT already marks the focus line or that the excerpt reaches EOF, do not call localize, read_files, or run_commands just to inspect that same file again before attempting the edit.",
+		);
+	}
+	return (
+		guidance.join(" ") +
+		(args.injected_context
+			? `\n\n[REPOSITORY EVIDENCE BUNDLE — authoritative; prefer it over exploring the repo]\n${args.injected_context}`
+			: "")
+	);
+}
+
+export function buildStartConfig(
+	args: RunAgentArgs,
+	provider: ResolvedProviderConfig,
+): Parameters<typeof ClineCore.prototype.start>[0] {
+	const engineEnabled = Boolean(args.engine?.enabled && args.engine.url);
+	// Cap gemini's reasoning budget. gemini-2.5-pro leaves thinking effectively unbounded and
+	// over-generates (~9k output tokens for a 1-line fix → minutes/turn), whereas gpt-5.4/claude are
+	// efficient. AGENT_CORE_THINKING_BUDGET_TOKENS caps it FOR GEMINI ONLY (leave others at their
+	// defaults). gemini-2.5-pro requires >=128 and cannot disable thinking, so use a small positive cap.
+	const budgetEnv = Number(process.env.AGENT_CORE_THINKING_BUDGET_TOKENS || 0);
+	const isGemini = /gemini|google/i.test(provider.providerId);
+	const thinkingBudgetTokens =
+		budgetEnv > 0 && isGemini ? Math.max(128, budgetEnv) : undefined;
+	return {
+		config: {
+			providerId: provider.providerId,
+			modelId: provider.modelId,
+			apiKey: provider.apiKey,
+			...(thinkingBudgetTokens !== undefined ? { thinkingBudgetTokens } : {}),
+			...(provider.baseUrl ? { baseUrl: provider.baseUrl } : {}),
+			...(provider.headers ? { headers: { ...provider.headers } } : {}),
+			cwd: args.working_dir,
+			workspaceRoot: args.working_dir,
+			systemPrompt: buildSystemPrompt(args),
+			enableTools: true,
+			enableSpawnAgent: Boolean(args.enable_spawn_agent),
+			enableAgentTeams: Boolean(args.enable_agent_teams),
+			// Engine-behind seam: load the Algenta tools plugin (localize/graph_query/
+			// simulate_patch) AND the govern hook ONLY when an engine URL is configured.
+			// Additive — without ALGENTA_ENGINE_URL the run is exactly as before.
+			// The govern hook is wired via `config.hooks` (not the plugin's top-level
+			// hooks): in backendMode "local" the runtime merges config.hooks into the
+			// loop, but a pluginPaths plugin only contributes its setup()/tools — its
+			// hooks are not wired. Tools come from the plugin; the hook comes from here.
+			// B7: the write-scope guard is ALWAYS on (blocks out-of-scope writes pre-disk),
+			// independent of engine mode. The govern (risk) hook is engine-gated.
+			hooks: engineEnabled
+				? { beforeTool: writeScopeBeforeTool, afterTool: mojoGateAfterTool }
+				: { beforeTool: writeScopeBeforeTool },
+			...(engineEnabled
+				? {
+						pluginPaths: [
+							new URL("./algenta-plugin.ts", import.meta.url).pathname,
+						],
+						extraTools: algentaTools,
+					}
+				: {}),
+			// Always bound iterations: a non-converging suppressed run otherwise loops
+			// and (uncached) re-bills the whole context per turn — the 466k-token blowup
+			// the G0 run caught. Cursor/Claude-Code-class ceiling (50) so a hard fix has room
+			// to iterate; loop/mistake detection stops non-progress earlier. Env-tunable;
+			// callers may tighten via limits.maxIterations.
+			execution: {
+				maxIterations:
+					args.limits?.maxIterations ?? Number(process.env.AGENT_CORE_MAX_ITERATIONS || 50),
+			},
+		},
+		...(engineEnabled
+			? {
+					localRuntime: {
+						configExtensions: ["plugins", "skills"] as const,
+					},
+				}
+			: {}),
+		source: "api",
+		interactive: false,
+	} as Parameters<typeof ClineCore.prototype.start>[0];
+}
+
+export function collectFilesChangedFromToolCalls(
+	toolCalls:
+		| {
+				name: string;
+				input?: unknown;
+				error?: string;
+		  }[]
+		| undefined,
+): string[] {
+	const filesChanged = new Set<string>();
+	for (const call of toolCalls ?? []) {
+		if (!WRITE_TOOLS.has(call.name) || call.error) continue;
+		const input = call.input as
+			| { path?: string; file?: string; files?: unknown }
+			| undefined;
+		const filesField = input?.files;
+		const candidates = [
+			input?.path,
+			input?.file,
+			...(Array.isArray(filesField) ? filesField : []),
+		];
+		for (const p of candidates) if (typeof p === "string") filesChanged.add(p);
+	}
+	return [...filesChanged];
+}
+
+export async function runAgent(args: RunAgentArgs): Promise<RunAgentResult> {
+	// B3/PR8: thread the engine config for the whole run (start + tool-calling turn)
+	// through AsyncLocalStorage so the Algenta tools read this run's config, never a global.
+	const inner = () => runAgentImpl(args);
+	if (args.engine?.enabled && args.engine.url) {
+		const { url, repositoryId, snapshotId, apiKey, workingDir } = args.engine;
+		return engineContext.run({ url, repositoryId, snapshotId, apiKey, workingDir }, inner);
+	}
+	return inner();
+}
+
+async function runAgentImpl(args: RunAgentArgs): Promise<RunAgentResult> {
+	const provider = await resolveProviderConfig(args);
+	const toolPolicies = buildToolPolicies(args);
+
+	const cline = await ClineCore.create({
+		clientName: "algenta-agent-core",
+		backendMode: "local",
+		toolPolicies,
+	} as Parameters<typeof ClineCore.create>[0]);
+
+	let agentRunId = "";
+	try {
+		const started = await cline.start(buildStartConfig(args, provider));
+		agentRunId = started.sessionId;
+
+		const result = await (
+			cline as unknown as {
+				send: (i: unknown) => Promise<
+					| {
+							finishReason?: string;
+							text?: string;
+							iterations?: number;
+							usage?: {
+								inputTokens?: number;
+								outputTokens?: number;
+								totalCost?: number;
+							};
+							toolCalls?: { name: string; input?: unknown; error?: string }[];
+					  }
+					| undefined
+				>;
+			}
+		).send({
+			sessionId: agentRunId,
+			prompt: args.prompt,
+			mode: "act",
+			timeoutMs: args.limits?.timeoutMs ?? Number(process.env.AGENT_CORE_TURN_TIMEOUT_MS || 600_000),
+		});
+
+		// Authoritative usage incl. prompt-cache read/write. Research: getAccumulatedUsage's
+		// aggregateUsage is the real breakdown (and includes subagents); send().usage omits
+		// cache fields, which is why earlier G0 runs reported cache_w=0 even though the
+		// anthropic provider declares the prompt-cache capability. Prefer accumulated usage.
+		let usage = result?.usage as
+			| {
+					inputTokens?: number;
+					outputTokens?: number;
+					cacheReadTokens?: number;
+					cacheWriteTokens?: number;
+					totalCost?: number;
+			  }
+			| undefined;
+		try {
+			const acc = await (
+				cline as unknown as {
+					getAccumulatedUsage?: (id: string) => Promise<
+						| {
+								aggregateUsage?: Record<string, number>;
+								usage?: Record<string, number>;
+						  }
+						| undefined
+					>;
+				}
+			).getAccumulatedUsage?.(agentRunId);
+			const agg = acc?.aggregateUsage ?? acc?.usage;
+			if (agg) usage = { ...usage, ...agg };
+		} catch {
+			/* fall back to send().usage */
+		}
+		return {
+			status: result?.finishReason ?? "unknown",
+			agent_run_id: agentRunId,
+			text: result?.text ?? "",
+			iterations: result?.iterations ?? 0,
+			files_changed: collectFilesChangedFromToolCalls(result?.toolCalls),
+			usage: usage
+				? {
+						inputTokens: usage.inputTokens ?? 0,
+						outputTokens: usage.outputTokens ?? 0,
+						cacheReadTokens: usage.cacheReadTokens ?? 0,
+						cacheWriteTokens: usage.cacheWriteTokens ?? 0,
+						totalCost: usage.totalCost,
+					}
+				: undefined,
+			provider: provider.providerId,
+			model: provider.modelId,
+		};
+	} catch (err) {
+		// Surface the real failure — the engine only sees `status: failed`; without this the
+		// root cause (e.g. an optional extension/MCP load error) is swallowed and undebuggable.
+		const e = err as Error;
+		console.error(`AGENT_CORE_RUN_ERROR ${e?.stack || e?.message || String(err)}`);
+		throw err;
+	} finally {
+		const anyCline = cline as unknown as {
+			dispose?: (r?: string) => Promise<void>;
+		};
+		if (typeof anyCline.dispose === "function") {
+			await anyCline.dispose("run_complete").catch(() => {});
+		}
+	}
+}

codna/agent-core/vendor/cline/algenta/algenta-plugin.ts

@@ -0,0 +1,30 @@
+// Algenta engine plugin — the "engine behind" tool seam: Cline drives the loop, this
+// plugin contributes the Algenta tools (localize / graph_query / simulate_patch). Loaded
+// via the start config's `pluginPaths` (see adapter.ts), only when ALGENTA_ENGINE_URL is
+// set. The runtime calls setup(api) and the registered tools become available to the loop.
+//
+// Hooks: the write-scope guard (beforeTool) and the Mojo Monte-Carlo govern gate (afterTool)
+// are declared HERE, on the plugin — NOT via the start config's `config.hooks`. The vendored
+// Cline runtime merges hooks from validated EXTENSIONS (getValidatedExtensions().hooks) into the
+// agent loop, but `config.hooks` is NOT wired for the local backend — so passing them through the
+// adapter's config.hooks silently dropped them, and engine-behind runs failed `plugin_evidence_missing`
+// (the govern gate never reached `observed`). Declaring them as plugin hooks is what actually fires them.
+import type { AgentPlugin } from "@cline/core";
+import { mojoGateAfterTool } from "./mojo-gate";
+import { algentaTools } from "./tools";
+import { writeScopeBeforeTool } from "./write-scope";
+
+const plugin: AgentPlugin = {
+	name: "algenta-engine",
+	manifest: { capabilities: ["tools", "hooks"], hooks: ["beforeTool", "afterTool"] },
+	hooks: {
+		beforeTool: writeScopeBeforeTool,
+		afterTool: mojoGateAfterTool,
+	},
+	setup(api) {
+		// `api` is contextually typed as AgentExtensionApi from the AgentPlugin annotation.
+		for (const tool of algentaTools) api.registerTool(tool);
+	},
+};
+
+export default plugin;