@gajae-code/coding-agent 0.4.3 → 0.4.4

package/src/cli/setup-cli.ts

@@ -14,6 +14,12 @@ import {
 	readGjcManagedCodexHooksStatus,
 } from "../hooks/codex-native-hooks-config";
 import { theme } from "../modes/theme/theme";
+import {
+	formatHermesSetupResult,
+	type HermesSetupFlags,
+	hermesSetupExitCode,
+	runHermesSetup,
+} from "../setup/hermes-setup";
 import {
 	addApiCompatibleProvider,
 	formatProviderPresetList,
@@ -21,7 +27,7 @@ import {
 	parseProviderCompatibility,
 } from "../setup/provider-onboarding";
 
-export type SetupComponent = "defaults" | "hooks" | "provider" | "python" | "stt";
+export type SetupComponent = "defaults" | "hermes" | "hooks" | "provider" | "python" | "stt";
 
 export interface SetupCommandArgs {
 	component: SetupComponent;
@@ -36,10 +42,23 @@ export interface SetupCommandArgs {
 		apiKeyEnv?: string;
 		model?: string[];
 		modelsPath?: string;
+		smoke?: boolean;
+		install?: boolean;
+		root?: string[];
+		repo?: string;
+		profile?: string;
+		sessionCommand?: string;
+		stateRoot?: string;
+		mutation?: string[];
+		artifactByteCap?: string;
+		serverKey?: string;
+		gjcCommand?: string;
+		target?: string;
+		profileDir?: string;
 	};
 }
 
-const VALID_COMPONENTS: SetupComponent[] = ["defaults", "hooks", "provider", "python", "stt"];
+const VALID_COMPONENTS: SetupComponent[] = ["defaults", "hermes", "hooks", "provider", "python", "stt"];
 
 function hasProviderSetupFlags(flags: SetupCommandArgs["flags"]): boolean {
 	return (
@@ -88,6 +107,32 @@ export function parseSetupArgs(args: string[]): SetupCommandArgs | undefined {
 			flags.check = true;
 		} else if (arg === "--force" || arg === "-f") {
 			flags.force = true;
+		} else if (arg === "--smoke") {
+			flags.smoke = true;
+		} else if (arg === "--install") {
+			flags.install = true;
+		} else if (arg === "--root") {
+			flags.root = [...(flags.root ?? []), args[++i] ?? ""];
+		} else if (arg === "--repo") {
+			flags.repo = args[++i];
+		} else if (arg === "--profile") {
+			flags.profile = args[++i];
+		} else if (arg === "--session-command") {
+			flags.sessionCommand = args[++i];
+		} else if (arg === "--state-root") {
+			flags.stateRoot = args[++i];
+		} else if (arg === "--mutation") {
+			flags.mutation = [...(flags.mutation ?? []), args[++i] ?? ""];
+		} else if (arg === "--artifact-byte-cap") {
+			flags.artifactByteCap = args[++i];
+		} else if (arg === "--server-key") {
+			flags.serverKey = args[++i];
+		} else if (arg === "--gjc-command") {
+			flags.gjcCommand = args[++i];
+		} else if (arg === "--target") {
+			flags.target = args[++i];
+		} else if (arg === "--profile-dir") {
+			flags.profileDir = args[++i];
 		} else if (arg === "--compat") {
 			flags.compat = args[++i];
 		} else if (arg === "--preset") {
@@ -177,6 +222,9 @@ export async function runSetupCommand(cmd: SetupCommandArgs): Promise<void> {
 		case "defaults":
 			await handleDefaultsSetup(cmd.flags);
 			break;
+		case "hermes":
+			await handleHermesSetup(cmd.flags);
+			break;
 		case "hooks":
 			await handleHooksSetup(cmd.flags);
 			break;
@@ -192,6 +240,26 @@ export async function runSetupCommand(cmd: SetupCommandArgs): Promise<void> {
 	}
 }
 
+async function handleHermesSetup(flags: HermesSetupFlags): Promise<void> {
+	try {
+		const result = await runHermesSetup(flags);
+		if (flags.json) {
+			process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+			return;
+		}
+		process.stdout.write(`${chalk.green(`${theme.status.success} Hermes MCP setup ready`)}\n`);
+		process.stdout.write(`${chalk.dim(formatHermesSetupResult(result))}\n`);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (flags.json) {
+			process.stdout.write(`${JSON.stringify({ ok: false, error: message }, null, 2)}\n`);
+		} else {
+			process.stderr.write(`${chalk.red(`${theme.status.error} Hermes MCP setup failed`)}\n`);
+			process.stderr.write(`${chalk.dim(message)}\n`);
+		}
+		process.exit(hermesSetupExitCode(error));
+	}
+}
 async function handleProviderSetup(flags: {
 	json?: boolean;
 	force?: boolean;
@@ -410,6 +478,7 @@ ${chalk.bold("Usage:")}
 
 ${chalk.bold("Components:")}
   defaults  Install bundled GJC default workflow skills (default)
+  hermes   Optional: render/install a Hermes MCP bridge setup package
   hooks     Optional: install GJC native Codex UserPromptSubmit/Stop skill-state hooks
   provider  Optional: add a preset, OpenAI-compatible, or Anthropic-compatible API provider
   python    Optional: verify a Python 3 interpreter is reachable for code execution
@@ -421,6 +490,11 @@ ${chalk.bold("Provider example:")}
   ${APP_NAME} setup provider --preset glm
   MY_PROVIDER_KEY=sk-... ${APP_NAME} setup provider --compat openai --provider my-oai --base-url https://api.example.com/v1 --api-key-env MY_PROVIDER_KEY --model gpt-example
 
+${chalk.bold("Hermes example:")}
+  ${APP_NAME} setup hermes --root /path/to/repo
+  ${APP_NAME} setup hermes --root /path/to/repo --profile my-bot --repo gajae-code --profile-dir /path/to/hermes/profile --install
+  ${APP_NAME} setup hermes --root /path/to/repo --session-command "gjc --model <provider/model>"
+
 ${chalk.bold("Options:")}
   -c, --check       Check if dependencies are installed without installing
   -f, --force       Overwrite existing default workflow skill files
@@ -432,6 +506,15 @@ ${chalk.bold("Options:")}
   --api-key-env     Read provider API key from this environment variable
   --model, --models Model id to add (repeat or comma-separate)
   --models-path     Override models config path
+  --smoke           Run Hermes MCP setup smoke checks
+  --install         Install generated Hermes setup files
+  --root            Allowed Hermes MCP workdir/artifact root (repeatable)
+  --profile         Hermes MCP profile namespace
+  --repo            Hermes MCP repo namespace
+  --session-command Explicit GJC session command; omitted by default
+  --mutation        Hermes MCP mutation classes: sessions,questions,reports,all
+  --target          Hermes config file target for config-only install
+  --profile-dir     Hermes profile directory for full setup install
 
 ${chalk.bold("Examples:")}
   ${APP_NAME} setup                  Install bundled GJC default workflow skills
@@ -439,6 +522,7 @@ ${chalk.bold("Examples:")}
   ${APP_NAME} setup defaults --check Check bundled GJC default workflow skills are installed
   ${APP_NAME} setup hooks            Install native Codex skill-state hooks
   ${APP_NAME} setup hooks --check    Check native Codex skill-state hooks
+  ${APP_NAME} setup hermes           Render a model-agnostic Hermes MCP setup preview
   ${APP_NAME} setup python           Install Python execution dependencies
   ${APP_NAME} setup stt              Install speech-to-text dependencies
   ${APP_NAME} setup stt --check      Check if STT dependencies are available

package/src/cli.ts

@@ -36,10 +36,12 @@ const commands: CommandEntry[] = [
 	{ name: "skills", load: () => import("./commands/skills").then(m => m.default) },
 	{ name: "session", load: () => import("./commands/session").then(m => m.default) },
 	{ name: "harness", load: () => import("./commands/harness").then(m => m.default) },
+	{ name: "coordinator", load: () => import("./commands/coordinator").then(m => m.default) },
 	{ name: "team", load: () => import("./commands/team").then(m => m.default) },
 	{ name: "ultragoal", load: () => import("./commands/ultragoal").then(m => m.default) },
 	{ name: "ralplan", load: () => import("./commands/ralplan").then(m => m.default) },
 	{ name: "config", load: () => import("./commands/config").then(m => m.default) },
+	{ name: "mcp-serve", load: () => import("./commands/mcp-serve").then(m => m.default) },
 	{
 		name: "contribute-pr",
 		aliases: ["contribution-prep"],

package/src/commands/coordinator.ts

@@ -0,0 +1,70 @@
+import { Args, Command, Flags } from "@gajae-code/utils/cli";
+import {
+	COORDINATOR_MCP_PROTOCOL_VERSION,
+	COORDINATOR_MCP_SERVER_NAME,
+	COORDINATOR_MCP_TOOL_NAMES,
+} from "../coordinator/contract";
+
+function writeJson(value: unknown): void {
+	process.stdout.write(`${JSON.stringify(value, null, 2)}
+`);
+}
+
+function coordinatorContractPayload(): {
+	ok: true;
+	server: { name: string; protocolVersion: string };
+	readOnly: true;
+	tools: string[];
+} {
+	return {
+		ok: true,
+		server: { name: COORDINATOR_MCP_SERVER_NAME, protocolVersion: COORDINATOR_MCP_PROTOCOL_VERSION },
+		readOnly: true,
+		tools: [...COORDINATOR_MCP_TOOL_NAMES],
+	};
+}
+
+export default class Coordinator extends Command {
+	static description = "Inspect GJC coordinator MCP bridge contracts";
+	static strict = false;
+
+	static args = {
+		action: Args.string({ description: "Action to run (check or tools)", required: false }),
+	};
+
+	static flags = {
+		json: Flags.boolean({ char: "j", description: "Emit machine-readable JSON", default: false }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Coordinator);
+		const action = args.action ?? "check";
+		if (action !== "check" && action !== "tools") {
+			const payload = { ok: false, reason: "unknown_coordinator_subcommand", subcommand: action };
+			if (flags.json) writeJson(payload);
+			else
+				process.stderr.write(`unknown_coordinator_subcommand:${action}
+`);
+			process.exit(1);
+		}
+
+		const payload = coordinatorContractPayload();
+		if (flags.json) {
+			writeJson(action === "tools" ? { ok: true, tools: payload.tools } : payload);
+			return;
+		}
+		if (action === "tools") {
+			for (const tool of payload.tools)
+				process.stdout.write(`${tool}
+`);
+			return;
+		}
+		process.stdout.write(
+			`server: ${payload.server.name}
+protocol: ${payload.server.protocolVersion}
+readOnly: true
+tools: ${payload.tools.length}
+`,
+		);
+	}
+}

package/src/commands/mcp-serve.ts

@@ -0,0 +1,62 @@
+import { Args, Command, Flags } from "@gajae-code/utils/cli";
+import {
+	COORDINATOR_MCP_PROTOCOL_VERSION,
+	COORDINATOR_MCP_SERVER_NAME,
+	COORDINATOR_MCP_TOOL_NAMES,
+} from "../coordinator/contract";
+import { runCoordinatorMcpStdio } from "../coordinator-mcp/server";
+
+function writeJson(value: unknown): void {
+	process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function validateMcpServeSubcommandForTest(server: string | undefined): void {
+	if (server !== "coordinator") throw new Error(`unknown_mcp_serve_subcommand:${server ?? ""}`);
+}
+
+export default class McpServe extends Command {
+	static description = "Serve GJC MCP compatibility bridges";
+	static strict = false;
+
+	static args = {
+		server: Args.string({ description: "MCP server to run (coordinator)", required: false }),
+	};
+
+	static flags = {
+		json: Flags.boolean({ char: "j", description: "Emit machine-readable JSON", default: false }),
+		check: Flags.boolean({ description: "Validate server configuration and print a smoke summary", default: false }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(McpServe);
+		const server = args.server ?? "";
+		try {
+			validateMcpServeSubcommandForTest(server);
+		} catch (error) {
+			const subcommand = server;
+			if (flags.json) {
+				writeJson({ ok: false, reason: "unknown_mcp_serve_subcommand", subcommand });
+			} else {
+				process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+			}
+			return;
+		}
+
+		if (flags.check) {
+			const payload = {
+				ok: true,
+				server: { name: COORDINATOR_MCP_SERVER_NAME, protocolVersion: COORDINATOR_MCP_PROTOCOL_VERSION },
+				readOnly: true,
+				tools: [...COORDINATOR_MCP_TOOL_NAMES],
+			};
+			if (flags.json) writeJson(payload);
+			else
+				process.stdout.write(
+					`server: ${payload.server.name}\nprotocol: ${payload.server.protocolVersion}\ntools: ${payload.tools.length}\n`,
+				);
+			return;
+		}
+
+		await runCoordinatorMcpStdio();
+	}
+}

package/src/commands/setup.ts

@@ -5,7 +5,7 @@ import { Args, Command, Flags } from "@gajae-code/utils/cli";
 import { runSetupCommand, type SetupCommandArgs, type SetupComponent } from "../cli/setup-cli";
 import { initTheme } from "../modes/theme/theme";
 
-const COMPONENTS: SetupComponent[] = ["defaults", "hooks", "provider", "python", "stt"];
+const COMPONENTS: SetupComponent[] = ["defaults", "hermes", "hooks", "provider", "python", "stt"];
 
 export default class Setup extends Command {
 	static description = "Install GJC defaults or optional feature dependencies";
@@ -22,6 +22,22 @@ export default class Setup extends Command {
 		check: Flags.boolean({ char: "c", description: "Check if dependencies are installed" }),
 		force: Flags.boolean({ char: "f", description: "Overwrite existing default workflow skill files" }),
 		json: Flags.boolean({ description: "Output status as JSON" }),
+		smoke: Flags.boolean({ description: "Run Hermes MCP setup smoke checks" }),
+		install: Flags.boolean({ description: "Install generated Hermes setup files" }),
+		root: Flags.string({ description: "Allowed Hermes MCP workdir/artifact root (repeatable)", multiple: true }),
+		repo: Flags.string({ description: "Hermes MCP repo namespace" }),
+		profile: Flags.string({ description: "Hermes MCP profile namespace" }),
+		"session-command": Flags.string({ description: "Explicit GJC session command for Hermes to launch" }),
+		"state-root": Flags.string({ description: "Hermes MCP coordination state root" }),
+		mutation: Flags.string({
+			description: "Hermes MCP mutation classes: sessions,questions,reports,all",
+			multiple: true,
+		}),
+		"artifact-byte-cap": Flags.string({ description: "Hermes MCP artifact read byte cap" }),
+		"server-key": Flags.string({ description: "Hermes MCP server key in coordinator config" }),
+		"gjc-command": Flags.string({ description: "Command used to start `gjc mcp-serve coordinator`" }),
+		target: Flags.string({ description: "Hermes config file target for config-only install" }),
+		"profile-dir": Flags.string({ description: "Hermes profile directory for full setup install" }),
 		preset: Flags.string({ description: "Provider preset: minimax, minimax-cn, or glm" }),
 		compat: Flags.string({ description: "Provider compatibility: openai or anthropic" }),
 		provider: Flags.string({ description: "Provider id to add to models.yml" }),
@@ -46,6 +62,19 @@ export default class Setup extends Command {
 				apiKeyEnv: flags["api-key-env"],
 				model: flags.model,
 				modelsPath: flags["models-path"],
+				smoke: flags.smoke,
+				install: flags.install,
+				root: flags.root,
+				repo: flags.repo,
+				profile: flags.profile,
+				sessionCommand: flags["session-command"],
+				stateRoot: flags["state-root"],
+				mutation: flags.mutation,
+				artifactByteCap: flags["artifact-byte-cap"],
+				serverKey: flags["server-key"],
+				gjcCommand: flags["gjc-command"],
+				target: flags.target,
+				profileDir: flags["profile-dir"],
 			},
 		};
 		await initTheme();

package/src/coordinator/contract.ts

@@ -0,0 +1,20 @@
+export const COORDINATOR_MCP_PROTOCOL_VERSION = "2024-11-05";
+export const COORDINATOR_MCP_SERVER_NAME = "gjc-coordinator-mcp";
+
+export const COORDINATOR_MCP_TOOL_NAMES = [
+	"gjc_coordinator_list_sessions",
+	"gjc_coordinator_read_status",
+	"gjc_coordinator_read_tail",
+	"gjc_coordinator_list_questions",
+	"gjc_coordinator_list_artifacts",
+	"gjc_coordinator_read_artifact",
+	"gjc_coordinator_read_coordination_status",
+	"gjc_coordinator_start_session",
+	"gjc_coordinator_send_prompt",
+	"gjc_coordinator_submit_question_answer",
+	"gjc_coordinator_read_turn",
+	"gjc_coordinator_await_turn",
+	"gjc_coordinator_report_status",
+] as const;
+
+export type CoordinatorToolName = (typeof COORDINATOR_MCP_TOOL_NAMES)[number];

package/src/coordinator-mcp/policy.ts

@@ -0,0 +1,160 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+export type CoordinatorMutationClass = "sessions" | "questions" | "reports";
+
+export interface CoordinatorNamespace {
+	profile: string | null;
+	repo: string | null;
+}
+
+export interface CoordinatorMcpConfig {
+	allowedRoots: string[];
+	mutationClasses: Set<CoordinatorMutationClass>;
+	artifactByteCap: number;
+	namespace: CoordinatorNamespace;
+	stateRoot: string;
+	sessionCommand: string | null;
+}
+
+export interface CoordinatorMutationRequest {
+	allow_mutation?: boolean;
+}
+
+const DEFAULT_ARTIFACT_BYTE_CAP = 64 * 1024;
+const MAX_ARTIFACT_BYTE_CAP = 1024 * 1024;
+const MUTATION_CLASSES = new Set<CoordinatorMutationClass>(["sessions", "questions", "reports"]);
+const LEGACY_MUTATION_CLASS_ALIASES = new Map<string, CoordinatorMutationClass>([
+	["session", "sessions"],
+	["prompt", "sessions"],
+	["question", "questions"],
+	["report", "reports"],
+]);
+
+function parseList(value: string | undefined): string[] {
+	return (value ?? "")
+		.split(/[\n,;:]+/)
+		.map(part => part.trim())
+		.filter(Boolean);
+}
+
+function parseRootList(value: string | undefined): string[] {
+	const normalized = (value ?? "").replace(/[\n,;]+/g, path.delimiter);
+	return normalized
+		.split(path.delimiter)
+		.map(part => part.trim())
+		.filter(Boolean);
+}
+
+function parseMutationClasses(value: string | undefined): Set<CoordinatorMutationClass> {
+	const classes = new Set<CoordinatorMutationClass>();
+	for (const raw of parseList(value)) {
+		const normalized = raw.toLowerCase();
+		if (normalized === "all") {
+			for (const mutationClass of MUTATION_CLASSES) classes.add(mutationClass);
+			continue;
+		}
+		const mutationClass = LEGACY_MUTATION_CLASS_ALIASES.get(normalized) ?? normalized;
+		if (MUTATION_CLASSES.has(mutationClass as CoordinatorMutationClass))
+			classes.add(mutationClass as CoordinatorMutationClass);
+	}
+	return classes;
+}
+
+function parseByteCap(value: string | undefined): number {
+	const parsed = Number.parseInt(value ?? "", 10);
+	if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_ARTIFACT_BYTE_CAP;
+	return Math.min(parsed, MAX_ARTIFACT_BYTE_CAP);
+}
+
+function cleanScope(value: string | undefined): string | null {
+	const trimmed = value?.trim();
+	if (!trimmed) return null;
+	return trimmed.replace(/[^a-zA-Z0-9_.-]+/g, "-").slice(0, 100) || null;
+}
+
+export function buildCoordinatorMcpConfig(env: NodeJS.ProcessEnv = process.env): CoordinatorMcpConfig {
+	const stateRoot =
+		env.GJC_COORDINATOR_MCP_STATE_ROOT?.trim() || path.join(process.cwd(), ".gjc", "state", "coordinator-mcp");
+	return {
+		allowedRoots: parseRootList(env.GJC_COORDINATOR_MCP_WORKDIR_ROOTS).map(root => path.resolve(root)),
+		mutationClasses: parseMutationClasses(
+			env.GJC_COORDINATOR_MCP_MUTATIONS ?? env.GJC_COORDINATOR_MCP_ENABLE_MUTATION_CLASSES,
+		),
+		artifactByteCap: parseByteCap(
+			env.GJC_COORDINATOR_MCP_ARTIFACT_BYTE_CAP ?? env.GJC_COORDINATOR_MCP_ARTIFACT_MAX_BYTES,
+		),
+		namespace: {
+			profile: cleanScope(env.GJC_COORDINATOR_MCP_PROFILE),
+			repo: cleanScope(env.GJC_COORDINATOR_MCP_REPO),
+		},
+		stateRoot: path.resolve(stateRoot),
+		sessionCommand: env.GJC_COORDINATOR_MCP_SESSION_COMMAND?.trim() || null,
+	};
+}
+
+async function realpathIfExists(value: string): Promise<string> {
+	try {
+		return await fs.realpath(value);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		const parent = await fs.realpath(path.dirname(value));
+		return path.join(parent, path.basename(value));
+	}
+}
+
+function isInside(candidate: string, root: string): boolean {
+	const relative = path.relative(root, candidate);
+	return relative === "" || (!!relative && !relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+async function canonicalAllowedRoots(config: CoordinatorMcpConfig): Promise<string[]> {
+	const roots = await Promise.all(config.allowedRoots.map(root => realpathIfExists(root)));
+	return roots.map(root => path.resolve(root));
+}
+
+export async function assertCoordinatorWorkdir(config: CoordinatorMcpConfig, cwd: unknown): Promise<string> {
+	if (typeof cwd !== "string" || cwd.trim().length === 0) throw new Error("coordinator_workdir_required");
+	if (config.allowedRoots.length === 0) throw new Error("coordinator_workdir_roots_required");
+	const requested = path.resolve(cwd);
+	const canonicalRequested = await realpathIfExists(requested);
+	const roots = await canonicalAllowedRoots(config);
+	if (!roots.some(root => isInside(canonicalRequested, root))) {
+		throw new Error(`coordinator_workdir_outside_allowed_roots:${requested}`);
+	}
+	return requested;
+}
+
+export async function assertCoordinatorArtifactPath(
+	config: CoordinatorMcpConfig,
+	artifactPath: unknown,
+): Promise<{ path: string; byteCap: number }> {
+	if (typeof artifactPath !== "string" || artifactPath.trim().length === 0)
+		throw new Error("coordinator_artifact_path_required");
+	if (config.allowedRoots.length === 0) throw new Error("coordinator_artifact_roots_required");
+	const requested = path.resolve(artifactPath);
+	const canonicalRequested = await realpathIfExists(requested);
+	const roots = await canonicalAllowedRoots(config);
+	if (!roots.some(root => isInside(canonicalRequested, root))) {
+		throw new Error(`coordinator_artifact_outside_allowed_roots:${requested}`);
+	}
+	return { path: requested, byteCap: config.artifactByteCap };
+}
+
+export function requireCoordinatorMutation(
+	config: CoordinatorMcpConfig,
+	mutationClass: CoordinatorMutationClass,
+	request: CoordinatorMutationRequest,
+): void {
+	if (!config.mutationClasses.has(mutationClass))
+		throw new Error(`coordinator_mutation_class_disabled:${mutationClass}`);
+	if (request.allow_mutation !== true) throw new Error(`coordinator_mutation_call_not_allowed:${mutationClass}`);
+}
+
+export function coordinatorNamespacePath(config: CoordinatorMcpConfig): string {
+	return path.join(
+		config.stateRoot,
+		config.namespace.profile ?? "unscoped-profile",
+		config.namespace.repo ?? "unscoped-repo",
+	);
+}

package/src/coordinator-mcp/safety.ts

@@ -0,0 +1,80 @@
+import {
+	assertCoordinatorArtifactPath,
+	assertCoordinatorWorkdir,
+	buildCoordinatorMcpConfig,
+	type CoordinatorMcpConfig,
+	type CoordinatorMutationClass,
+	requireCoordinatorMutation,
+} from "./policy";
+
+export const COORDINATOR_MUTATION_CLASSES = ["sessions", "questions", "reports"] as const;
+
+export type { CoordinatorMutationClass };
+
+export interface CoordinatorSafetyConfig {
+	allowedRoots: string[];
+	artifactMaxBytes: number;
+	enabledMutationClasses: Set<CoordinatorMutationClass>;
+	repo?: string;
+	profile?: string;
+}
+
+export interface CoordinatorSafetyPolicy {
+	config: CoordinatorSafetyConfig;
+	resolveWorkdir(input: unknown): Promise<string>;
+	resolveArtifactPath(input: unknown): Promise<string>;
+	assertMutationAllowed(
+		mutationClass: CoordinatorMutationClass,
+		args: Record<string, unknown>,
+	): { ok: true } | CoordinatorFailure;
+}
+
+export interface CoordinatorFailure {
+	ok: false;
+	reason: string;
+	[key: string]: unknown;
+}
+
+function toSafetyConfig(config: CoordinatorMcpConfig): CoordinatorSafetyConfig {
+	return {
+		allowedRoots: config.allowedRoots,
+		artifactMaxBytes: config.artifactByteCap,
+		enabledMutationClasses: config.mutationClasses,
+		repo: config.namespace.repo ?? undefined,
+		profile: config.namespace.profile ?? undefined,
+	};
+}
+
+function toFailure(error: unknown): CoordinatorFailure {
+	const message = error instanceof Error ? error.message : String(error);
+	const [rawReason, detail] = message.split(":", 2);
+	const reason = rawReason.replace(/^coordinator_/, "");
+	return detail === undefined ? { ok: false, reason } : { ok: false, reason, detail };
+}
+
+export async function createCoordinatorSafetyPolicy(
+	options: { env?: NodeJS.ProcessEnv } = {},
+): Promise<CoordinatorSafetyPolicy> {
+	const canonicalConfig = buildCoordinatorMcpConfig(options.env ?? process.env);
+	const config = toSafetyConfig(canonicalConfig);
+	return {
+		config,
+		resolveWorkdir(input: unknown): Promise<string> {
+			return assertCoordinatorWorkdir(canonicalConfig, input);
+		},
+		async resolveArtifactPath(input: unknown): Promise<string> {
+			return (await assertCoordinatorArtifactPath(canonicalConfig, input)).path;
+		},
+		assertMutationAllowed(
+			mutationClass: CoordinatorMutationClass,
+			args: Record<string, unknown>,
+		): { ok: true } | CoordinatorFailure {
+			try {
+				requireCoordinatorMutation(canonicalConfig, mutationClass, args);
+				return { ok: true };
+			} catch (error) {
+				return toFailure(error);
+			}
+		},
+	};
+}