@kitsy/coop-ai 2.1.0 → 2.1.2

package/dist/index.cjs

@@ -30,6 +30,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CliAgentClient: () => CliAgentClient,
+  CliCompletionProvider: () => CliCompletionProvider,
   buildIdeaRefinementPrompt: () => buildIdeaRefinementPrompt,
   buildTaskRefinementPrompt: () => buildTaskRefinementPrompt,
   build_contract: () => build_contract,
@@ -928,7 +930,15 @@ var DEFAULT_MODELS = {
   openai: "gpt-5-mini",
   anthropic: "claude-3-5-sonnet-latest",
   gemini: "gemini-2.0-flash",
-  ollama: "llama3.2"
+  ollama: "llama3.2",
+  codex_cli: "gpt-5-codex",
+  claude_cli: "sonnet",
+  gemini_cli: "gemini-2.5-pro"
+};
+var DEFAULT_COMMAND = {
+  codex_cli: "codex",
+  claude_cli: "claude",
+  gemini_cli: "gemini"
 };
 var DEFAULT_KEY_ENV = {
   openai: "OPENAI_API_KEY",
@@ -958,7 +968,7 @@ function asFinite(value) {
 }
 function readProvider(value) {
   const normalized = asString(value)?.toLowerCase();
-  if (normalized === "openai" || normalized === "anthropic" || normalized === "gemini" || normalized === "ollama" || normalized === "mock") {
+  if (normalized === "openai" || normalized === "anthropic" || normalized === "gemini" || normalized === "ollama" || normalized === "mock" || normalized === "codex_cli" || normalized === "claude_cli" || normalized === "gemini_cli") {
     return normalized;
   }
   return "mock";
@@ -979,15 +989,34 @@ function resolve_provider_config(config) {
       timeout_ms: 6e4
     };
   }
+  if (provider === "codex_cli" || provider === "claude_cli" || provider === "gemini_cli") {
+    const section2 = lookupProviderSection(ai, provider);
+    const model2 = asString(section2.model) ?? asString(ai.model) ?? DEFAULT_MODELS[provider];
+    const timeout_ms2 = asFinite(section2.timeout_ms) ?? asFinite(ai.timeout_ms) ?? 3e5;
+    const command = asString(section2.command) ?? DEFAULT_COMMAND[provider];
+    const argsRaw = Array.isArray(section2.args) ? section2.args : Array.isArray(ai.args) ? ai.args : [];
+    const args = argsRaw.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+    return {
+      provider,
+      model: model2,
+      command,
+      args,
+      temperature: 0.2,
+      max_output_tokens: 4096,
+      timeout_ms: timeout_ms2
+    };
+  }
   const section = lookupProviderSection(ai, provider);
-  const model = asString(section.model) ?? asString(ai.model) ?? DEFAULT_MODELS[provider];
-  const base_url = asString(section.base_url) ?? asString(ai.base_url) ?? DEFAULT_BASE_URL[provider];
+  const cloudProvider = provider;
+  const model = asString(section.model) ?? asString(ai.model) ?? DEFAULT_MODELS[cloudProvider];
+  const base_url = asString(section.base_url) ?? asString(ai.base_url) ?? DEFAULT_BASE_URL[cloudProvider];
   const temperature = asFinite(section.temperature) ?? asFinite(ai.temperature) ?? 0.2;
   const max_output_tokens = asFinite(section.max_output_tokens) ?? asFinite(ai.max_output_tokens) ?? 1024;
   const timeout_ms = asFinite(section.timeout_ms) ?? asFinite(ai.timeout_ms) ?? 6e4;
   let api_key;
   if (provider !== "ollama") {
-    const envName = asString(section.api_key_env) ?? asString(ai.api_key_env) ?? DEFAULT_KEY_ENV[provider];
+    const keyedProvider = provider;
+    const envName = asString(section.api_key_env) ?? asString(ai.api_key_env) ?? DEFAULT_KEY_ENV[keyedProvider];
     const envValue = envName ? asString(process.env[envName]) : null;
     api_key = asString(section.api_key) ?? asString(ai.api_key) ?? envValue ?? void 0;
     if (!api_key) {
@@ -1007,6 +1036,250 @@ function resolve_provider_config(config) {
   };
 }
 
+// src/providers/cli.ts
+var import_node_fs2 = __toESM(require("fs"), 1);
+var import_node_os = __toESM(require("os"), 1);
+var import_node_path3 = __toESM(require("path"), 1);
+var import_node_child_process2 = require("child_process");
+function defaultRunner(invocation) {
+  const result = (0, import_node_child_process2.spawnSync)(invocation.command, invocation.args, {
+    cwd: invocation.cwd,
+    encoding: "utf8",
+    input: invocation.input,
+    timeout: invocation.timeout_ms,
+    windowsHide: true
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    error: result.error
+  };
+}
+function asText(result) {
+  return [result.stdout, result.stderr].map((value) => value.trim()).filter(Boolean).join("\n").trim();
+}
+function requireSuccess(provider, result) {
+  if ((result.status ?? 1) === 0 && !result.error) {
+    return;
+  }
+  const details = asText(result) || result.error?.message || "unknown error";
+  throw new Error(`${provider} execution failed: ${details}`);
+}
+function tempOutputFile(prefix) {
+  return import_node_path3.default.join(import_node_os.default.tmpdir(), `${prefix}-${Date.now()}-${Math.random().toString(16).slice(2)}.txt`);
+}
+function combinedPrompt(input) {
+  return [input.system.trim(), input.prompt.trim()].filter(Boolean).join("\n\n");
+}
+function completionInvocation(config, input, cwd) {
+  if (config.provider === "codex_cli") {
+    const outputFile = tempOutputFile("coop-codex-complete");
+    return {
+      command: config.command ?? "codex",
+      args: [
+        "exec",
+        "-C",
+        cwd,
+        "--skip-git-repo-check",
+        "--sandbox",
+        "read-only",
+        ...config.model ? ["--model", config.model] : [],
+        "--output-last-message",
+        outputFile,
+        ...config.args ?? [],
+        "-"
+      ],
+      cwd,
+      input: combinedPrompt(input),
+      timeout_ms: config.timeout_ms
+    };
+  }
+  if (config.provider === "claude_cli") {
+    return {
+      command: config.command ?? "claude",
+      args: [
+        "-p",
+        combinedPrompt(input),
+        "--output-format",
+        "text",
+        "--permission-mode",
+        "plan",
+        ...config.model ? ["--model", config.model] : [],
+        ...config.args ?? []
+      ],
+      cwd,
+      timeout_ms: config.timeout_ms
+    };
+  }
+  return {
+    command: config.command ?? "gemini",
+    args: [
+      "-p",
+      combinedPrompt(input),
+      "--output-format",
+      "text",
+      "--approval-mode",
+      "plan",
+      ...config.model ? ["--model", config.model] : [],
+      ...config.args ?? []
+    ],
+    cwd,
+    timeout_ms: config.timeout_ms
+  };
+}
+function readCodexOutput(invocation) {
+  const index = invocation.args.indexOf("--output-last-message");
+  const outputFile = index >= 0 ? invocation.args[index + 1] : void 0;
+  if (!outputFile) return null;
+  if (!import_node_fs2.default.existsSync(outputFile)) return null;
+  try {
+    return import_node_fs2.default.readFileSync(outputFile, "utf8").trim();
+  } finally {
+    import_node_fs2.default.rmSync(outputFile, { force: true });
+  }
+}
+var CliCompletionProvider = class {
+  name;
+  config;
+  cwd;
+  runner;
+  constructor(config, options = {}) {
+    this.name = config.provider;
+    this.config = config;
+    this.cwd = import_node_path3.default.resolve(options.cwd ?? process.cwd());
+    this.runner = options.runner ?? defaultRunner;
+  }
+  async complete(input) {
+    const invocation = completionInvocation(this.config, input, this.cwd);
+    const result = this.runner(invocation);
+    requireSuccess(this.name, result);
+    const codexOutput = this.config.provider === "codex_cli" ? readCodexOutput(invocation) : null;
+    return {
+      text: codexOutput || result.stdout.trim() || result.stderr.trim()
+    };
+  }
+};
+function buildExecutionPrompt(task, contract, step, prompt, mode) {
+  const sections = [
+    mode === "execute" ? "You are executing a COOP task inside the repo. Make the necessary file changes, run allowed commands when needed, and finish with a concise summary." : "You are reviewing a COOP task inside the repo. Inspect the current workspace and return concise review findings only.",
+    `Task: ${task.id} - ${task.title}`,
+    `Goal: ${contract.goal}`,
+    `Step: ${step.step} (${step.action})`,
+    contract.context.acceptance_criteria.length > 0 ? `Acceptance: ${contract.context.acceptance_criteria.join(" | ")}` : "",
+    contract.context.tests_required.length > 0 ? `Tests Required: ${contract.context.tests_required.join(" | ")}` : "",
+    contract.context.authority_refs.length > 0 ? `Authority Refs: ${contract.context.authority_refs.join(" | ")}` : "",
+    contract.context.derived_refs.length > 0 ? `Derived Refs: ${contract.context.derived_refs.join(" | ")}` : "",
+    contract.permissions.read_paths.length > 0 ? `Allowed Read Paths: ${contract.permissions.read_paths.join(", ")}` : "",
+    contract.permissions.write_paths.length > 0 ? `Allowed Write Paths: ${contract.permissions.write_paths.join(", ")}` : "",
+    contract.permissions.allowed_commands.length > 0 ? `Allowed Commands: ${contract.permissions.allowed_commands.join(", ")}` : "",
+    contract.permissions.forbidden_commands.length > 0 ? `Forbidden Commands: ${contract.permissions.forbidden_commands.join(", ")}` : "",
+    prompt
+  ].filter(Boolean);
+  return sections.join("\n\n");
+}
+function countGitChanges(repoRoot, runner, timeoutMs) {
+  const result = runner({
+    command: "git",
+    args: ["status", "--porcelain"],
+    cwd: repoRoot,
+    timeout_ms: timeoutMs
+  });
+  if ((result.status ?? 1) !== 0) return 0;
+  return result.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).length;
+}
+function executionInvocation(config, prompt, repoRoot, mode) {
+  if (config.provider === "codex_cli") {
+    const outputFile = tempOutputFile("coop-codex-run");
+    return {
+      command: config.command ?? "codex",
+      args: [
+        "exec",
+        "-C",
+        repoRoot,
+        "--skip-git-repo-check",
+        "--sandbox",
+        mode === "execute" ? "workspace-write" : "read-only",
+        ...mode === "execute" ? ["--full-auto"] : [],
+        ...config.model ? ["--model", config.model] : [],
+        "--output-last-message",
+        outputFile,
+        ...config.args ?? [],
+        "-"
+      ],
+      cwd: repoRoot,
+      input: prompt,
+      timeout_ms: config.timeout_ms
+    };
+  }
+  if (config.provider === "claude_cli") {
+    return {
+      command: config.command ?? "claude",
+      args: [
+        "-p",
+        prompt,
+        "--output-format",
+        "text",
+        "--permission-mode",
+        mode === "execute" ? "bypassPermissions" : "plan",
+        ...config.model ? ["--model", config.model] : [],
+        ...config.args ?? []
+      ],
+      cwd: repoRoot,
+      timeout_ms: config.timeout_ms
+    };
+  }
+  return {
+    command: config.command ?? "gemini",
+    args: [
+      "-p",
+      prompt,
+      "--output-format",
+      "text",
+      "--approval-mode",
+      mode === "execute" ? "yolo" : "plan",
+      ...config.model ? ["--model", config.model] : [],
+      ...config.args ?? []
+    ],
+    cwd: repoRoot,
+    timeout_ms: config.timeout_ms
+  };
+}
+var CliAgentClient = class {
+  config;
+  repoRoot;
+  runner;
+  constructor(config, options = {}) {
+    this.config = config;
+    this.repoRoot = import_node_path3.default.resolve(options.cwd ?? process.cwd());
+    this.runner = options.runner ?? defaultRunner;
+  }
+  async generate(input) {
+    const before = countGitChanges(this.repoRoot, this.runner, this.config.timeout_ms);
+    const prompt = buildExecutionPrompt(input.task, input.contract, input.step, input.prompt, "execute");
+    const invocation = executionInvocation(this.config, prompt, this.repoRoot, "execute");
+    const result = this.runner(invocation);
+    requireSuccess(this.config.provider, result);
+    const after = countGitChanges(this.repoRoot, this.runner, this.config.timeout_ms);
+    const codexOutput = this.config.provider === "codex_cli" ? readCodexOutput(invocation) : null;
+    return {
+      summary: codexOutput || result.stdout.trim() || result.stderr.trim() || `Completed ${input.step.step}.`,
+      file_changes: Math.max(0, after - before)
+    };
+  }
+  async review(input) {
+    const prompt = buildExecutionPrompt(input.task, input.contract, input.step, input.prompt, "review");
+    const invocation = executionInvocation(this.config, prompt, this.repoRoot, "review");
+    const result = this.runner(invocation);
+    requireSuccess(this.config.provider, result);
+    const codexOutput = this.config.provider === "codex_cli" ? readCodexOutput(invocation) : null;
+    return {
+      summary: codexOutput || result.stdout.trim() || result.stderr.trim() || `Reviewed ${input.step.step}.`,
+      file_changes: 0
+    };
+  }
+};
+
 // src/providers/http.ts
 async function post_json(url, init) {
   const controller = new AbortController();
@@ -1203,6 +1476,10 @@ function create_provider(config) {
       return new GeminiProvider(resolved);
     case "ollama":
       return new OllamaProvider(resolved);
+    case "codex_cli":
+    case "claude_cli":
+    case "gemini_cli":
+      return new CliCompletionProvider(resolved);
     case "mock":
     default:
       return new MockProvider();
@@ -1266,7 +1543,11 @@ function asAgentResponse(text, tokens) {
     tokens_used: tokens
   };
 }
-function create_provider_agent_client(config) {
+function create_provider_agent_client(config, runtime = {}) {
+  const resolved = resolve_provider_config(config);
+  if (resolved.provider === "codex_cli" || resolved.provider === "claude_cli" || resolved.provider === "gemini_cli") {
+    return new CliAgentClient(resolved, runtime);
+  }
   const provider = create_provider(config);
   return {
     async generate(input) {
@@ -1322,6 +1603,8 @@ function create_provider_refinement_client(config) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CliAgentClient,
+  CliCompletionProvider,
   buildIdeaRefinementPrompt,
   buildTaskRefinementPrompt,
   build_contract,

package/dist/index.d.cts

@@ -216,12 +216,14 @@ declare function refine_idea_to_draft(input: IdeaRefinementInput, client?: Refin
 declare function refine_task_to_draft(input: TaskRefinementInput, client?: RefinementClient): Promise<RefinementDraft>;
 declare function parseRefinementDraftResponse(text: string, mode: "idea" | "task", sourceId: string, sourceTitle: string): RefinementDraft | null;
 
-type AiProviderName = "mock" | "openai" | "anthropic" | "gemini" | "ollama";
+type AiProviderName = "mock" | "openai" | "anthropic" | "gemini" | "ollama" | "codex_cli" | "claude_cli" | "gemini_cli";
 interface ProviderConfig {
     provider: AiProviderName;
     model: string;
     base_url?: string;
     api_key?: string;
+    command?: string;
+    args?: string[];
     temperature: number;
     max_output_tokens: number;
     timeout_ms: number;
@@ -245,6 +247,52 @@ interface LlmProvider {
  */
 declare function resolve_provider_config(config: unknown): ProviderConfig;
 
+type CliProviderName = Extract<ProviderConfig["provider"], "codex_cli" | "claude_cli" | "gemini_cli">;
+interface CliRunnerInvocation {
+    command: string;
+    args: string[];
+    cwd: string;
+    input?: string;
+    timeout_ms: number;
+}
+interface CliRunnerResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+}
+type CliRunner = (invocation: CliRunnerInvocation) => CliRunnerResult;
+interface CliRuntimeOptions {
+    cwd?: string;
+    runner?: CliRunner;
+}
+declare class CliCompletionProvider implements LlmProvider {
+    readonly name: CliProviderName;
+    private readonly config;
+    private readonly cwd;
+    private readonly runner;
+    constructor(config: ProviderConfig, options?: CliRuntimeOptions);
+    complete(input: CompletionInput): Promise<CompletionResult>;
+}
+declare class CliAgentClient implements AgentClient {
+    private readonly config;
+    private readonly repoRoot;
+    private readonly runner;
+    constructor(config: ProviderConfig, options?: CliRuntimeOptions);
+    generate(input: {
+        task: Task;
+        step: NonNullable<NonNullable<Task["execution"]>["runbook"]>[number];
+        contract: AgentContract;
+        prompt: string;
+    }): Promise<AgentResponse>;
+    review(input: {
+        task: Task;
+        step: NonNullable<NonNullable<Task["execution"]>["runbook"]>[number];
+        contract: AgentContract;
+        prompt: string;
+    }): Promise<AgentResponse>;
+}
+
 /**
  * Creates an LLM provider instance from COOP config.
  * [SPEC: Architecture v2.0 §13]
@@ -255,7 +303,7 @@ declare function create_provider(config: unknown): LlmProvider;
  * Creates an executor client backed by configured LLM provider(s).
  * [SPEC: Architecture v2.0 §13]
  */
-declare function create_provider_agent_client(config: unknown): AgentClient;
+declare function create_provider_agent_client(config: unknown, runtime?: CliRuntimeOptions): AgentClient;
 /**
  * Creates an idea decomposition client backed by configured LLM provider(s).
  * [SPEC: Architecture v2.0 §Phase 4]
@@ -263,4 +311,4 @@ declare function create_provider_agent_client(config: unknown): AgentClient;
 declare function create_provider_idea_decomposer(config: unknown): IdeaDecomposerClient;
 declare function create_provider_refinement_client(config: unknown): RefinementClient;
 
-export { type AgentClient, type AgentContract, type AgentContractConstraints, type AgentContractContext, type AgentContractPermissions, type AgentContractRelatedArtifacts, type AgentResponse, type AiProviderName, type CompletionInput, type CompletionResult, type DecomposedTaskDraft, type ExecuteTaskOptions, type FileAccessMode, type IdeaDecomposerClient, type IdeaDecompositionInput, type IdeaRefinementInput, type LlmProvider, type ProviderConfig, type RefinementClient, type RefinementDraft, type RefinementProposalAction, type RefinementTaskProposal, type RunResult, type SandboxRunState, type TaskRefinementInput, buildIdeaRefinementPrompt, buildTaskRefinementPrompt, build_contract, build_decomposition_prompt, constraint_violation_reasons, create_provider, create_provider_agent_client, create_provider_idea_decomposer, create_provider_refinement_client, create_run, decompose_idea_to_tasks, enforce_constraints, execute_task, finalize_run, log_step, parseRefinementDraftResponse, refine_idea_to_draft, refine_task_to_draft, resolve_provider_config, select_agent, validate_command, validate_file_access, write_run };
+export { type AgentClient, type AgentContract, type AgentContractConstraints, type AgentContractContext, type AgentContractPermissions, type AgentContractRelatedArtifacts, type AgentResponse, type AiProviderName, CliAgentClient, CliCompletionProvider, type CliRunner, type CliRunnerInvocation, type CliRunnerResult, type CliRuntimeOptions, type CompletionInput, type CompletionResult, type DecomposedTaskDraft, type ExecuteTaskOptions, type FileAccessMode, type IdeaDecomposerClient, type IdeaDecompositionInput, type IdeaRefinementInput, type LlmProvider, type ProviderConfig, type RefinementClient, type RefinementDraft, type RefinementProposalAction, type RefinementTaskProposal, type RunResult, type SandboxRunState, type TaskRefinementInput, buildIdeaRefinementPrompt, buildTaskRefinementPrompt, build_contract, build_decomposition_prompt, constraint_violation_reasons, create_provider, create_provider_agent_client, create_provider_idea_decomposer, create_provider_refinement_client, create_run, decompose_idea_to_tasks, enforce_constraints, execute_task, finalize_run, log_step, parseRefinementDraftResponse, refine_idea_to_draft, refine_task_to_draft, resolve_provider_config, select_agent, validate_command, validate_file_access, write_run };

package/dist/index.d.ts

@@ -216,12 +216,14 @@ declare function refine_idea_to_draft(input: IdeaRefinementInput, client?: Refin
 declare function refine_task_to_draft(input: TaskRefinementInput, client?: RefinementClient): Promise<RefinementDraft>;
 declare function parseRefinementDraftResponse(text: string, mode: "idea" | "task", sourceId: string, sourceTitle: string): RefinementDraft | null;
 
-type AiProviderName = "mock" | "openai" | "anthropic" | "gemini" | "ollama";
+type AiProviderName = "mock" | "openai" | "anthropic" | "gemini" | "ollama" | "codex_cli" | "claude_cli" | "gemini_cli";
 interface ProviderConfig {
     provider: AiProviderName;
     model: string;
     base_url?: string;
     api_key?: string;
+    command?: string;
+    args?: string[];
     temperature: number;
     max_output_tokens: number;
     timeout_ms: number;
@@ -245,6 +247,52 @@ interface LlmProvider {
  */
 declare function resolve_provider_config(config: unknown): ProviderConfig;
 
+type CliProviderName = Extract<ProviderConfig["provider"], "codex_cli" | "claude_cli" | "gemini_cli">;
+interface CliRunnerInvocation {
+    command: string;
+    args: string[];
+    cwd: string;
+    input?: string;
+    timeout_ms: number;
+}
+interface CliRunnerResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+}
+type CliRunner = (invocation: CliRunnerInvocation) => CliRunnerResult;
+interface CliRuntimeOptions {
+    cwd?: string;
+    runner?: CliRunner;
+}
+declare class CliCompletionProvider implements LlmProvider {
+    readonly name: CliProviderName;
+    private readonly config;
+    private readonly cwd;
+    private readonly runner;
+    constructor(config: ProviderConfig, options?: CliRuntimeOptions);
+    complete(input: CompletionInput): Promise<CompletionResult>;
+}
+declare class CliAgentClient implements AgentClient {
+    private readonly config;
+    private readonly repoRoot;
+    private readonly runner;
+    constructor(config: ProviderConfig, options?: CliRuntimeOptions);
+    generate(input: {
+        task: Task;
+        step: NonNullable<NonNullable<Task["execution"]>["runbook"]>[number];
+        contract: AgentContract;
+        prompt: string;
+    }): Promise<AgentResponse>;
+    review(input: {
+        task: Task;
+        step: NonNullable<NonNullable<Task["execution"]>["runbook"]>[number];
+        contract: AgentContract;
+        prompt: string;
+    }): Promise<AgentResponse>;
+}
+
 /**
  * Creates an LLM provider instance from COOP config.
  * [SPEC: Architecture v2.0 §13]
@@ -255,7 +303,7 @@ declare function create_provider(config: unknown): LlmProvider;
  * Creates an executor client backed by configured LLM provider(s).
  * [SPEC: Architecture v2.0 §13]
  */
-declare function create_provider_agent_client(config: unknown): AgentClient;
+declare function create_provider_agent_client(config: unknown, runtime?: CliRuntimeOptions): AgentClient;
 /**
  * Creates an idea decomposition client backed by configured LLM provider(s).
  * [SPEC: Architecture v2.0 §Phase 4]
@@ -263,4 +311,4 @@ declare function create_provider_agent_client(config: unknown): AgentClient;
 declare function create_provider_idea_decomposer(config: unknown): IdeaDecomposerClient;
 declare function create_provider_refinement_client(config: unknown): RefinementClient;
 
-export { type AgentClient, type AgentContract, type AgentContractConstraints, type AgentContractContext, type AgentContractPermissions, type AgentContractRelatedArtifacts, type AgentResponse, type AiProviderName, type CompletionInput, type CompletionResult, type DecomposedTaskDraft, type ExecuteTaskOptions, type FileAccessMode, type IdeaDecomposerClient, type IdeaDecompositionInput, type IdeaRefinementInput, type LlmProvider, type ProviderConfig, type RefinementClient, type RefinementDraft, type RefinementProposalAction, type RefinementTaskProposal, type RunResult, type SandboxRunState, type TaskRefinementInput, buildIdeaRefinementPrompt, buildTaskRefinementPrompt, build_contract, build_decomposition_prompt, constraint_violation_reasons, create_provider, create_provider_agent_client, create_provider_idea_decomposer, create_provider_refinement_client, create_run, decompose_idea_to_tasks, enforce_constraints, execute_task, finalize_run, log_step, parseRefinementDraftResponse, refine_idea_to_draft, refine_task_to_draft, resolve_provider_config, select_agent, validate_command, validate_file_access, write_run };
+export { type AgentClient, type AgentContract, type AgentContractConstraints, type AgentContractContext, type AgentContractPermissions, type AgentContractRelatedArtifacts, type AgentResponse, type AiProviderName, CliAgentClient, CliCompletionProvider, type CliRunner, type CliRunnerInvocation, type CliRunnerResult, type CliRuntimeOptions, type CompletionInput, type CompletionResult, type DecomposedTaskDraft, type ExecuteTaskOptions, type FileAccessMode, type IdeaDecomposerClient, type IdeaDecompositionInput, type IdeaRefinementInput, type LlmProvider, type ProviderConfig, type RefinementClient, type RefinementDraft, type RefinementProposalAction, type RefinementTaskProposal, type RunResult, type SandboxRunState, type TaskRefinementInput, buildIdeaRefinementPrompt, buildTaskRefinementPrompt, build_contract, build_decomposition_prompt, constraint_violation_reasons, create_provider, create_provider_agent_client, create_provider_idea_decomposer, create_provider_refinement_client, create_run, decompose_idea_to_tasks, enforce_constraints, execute_task, finalize_run, log_step, parseRefinementDraftResponse, refine_idea_to_draft, refine_task_to_draft, resolve_provider_config, select_agent, validate_command, validate_file_access, write_run };

package/dist/index.js

@@ -870,7 +870,15 @@ var DEFAULT_MODELS = {
   openai: "gpt-5-mini",
   anthropic: "claude-3-5-sonnet-latest",
   gemini: "gemini-2.0-flash",
-  ollama: "llama3.2"
+  ollama: "llama3.2",
+  codex_cli: "gpt-5-codex",
+  claude_cli: "sonnet",
+  gemini_cli: "gemini-2.5-pro"
+};
+var DEFAULT_COMMAND = {
+  codex_cli: "codex",
+  claude_cli: "claude",
+  gemini_cli: "gemini"
 };
 var DEFAULT_KEY_ENV = {
   openai: "OPENAI_API_KEY",
@@ -900,7 +908,7 @@ function asFinite(value) {
 }
 function readProvider(value) {
   const normalized = asString(value)?.toLowerCase();
-  if (normalized === "openai" || normalized === "anthropic" || normalized === "gemini" || normalized === "ollama" || normalized === "mock") {
+  if (normalized === "openai" || normalized === "anthropic" || normalized === "gemini" || normalized === "ollama" || normalized === "mock" || normalized === "codex_cli" || normalized === "claude_cli" || normalized === "gemini_cli") {
     return normalized;
   }
   return "mock";
@@ -921,15 +929,34 @@ function resolve_provider_config(config) {
       timeout_ms: 6e4
     };
   }
+  if (provider === "codex_cli" || provider === "claude_cli" || provider === "gemini_cli") {
+    const section2 = lookupProviderSection(ai, provider);
+    const model2 = asString(section2.model) ?? asString(ai.model) ?? DEFAULT_MODELS[provider];
+    const timeout_ms2 = asFinite(section2.timeout_ms) ?? asFinite(ai.timeout_ms) ?? 3e5;
+    const command = asString(section2.command) ?? DEFAULT_COMMAND[provider];
+    const argsRaw = Array.isArray(section2.args) ? section2.args : Array.isArray(ai.args) ? ai.args : [];
+    const args = argsRaw.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+    return {
+      provider,
+      model: model2,
+      command,
+      args,
+      temperature: 0.2,
+      max_output_tokens: 4096,
+      timeout_ms: timeout_ms2
+    };
+  }
   const section = lookupProviderSection(ai, provider);
-  const model = asString(section.model) ?? asString(ai.model) ?? DEFAULT_MODELS[provider];
-  const base_url = asString(section.base_url) ?? asString(ai.base_url) ?? DEFAULT_BASE_URL[provider];
+  const cloudProvider = provider;
+  const model = asString(section.model) ?? asString(ai.model) ?? DEFAULT_MODELS[cloudProvider];
+  const base_url = asString(section.base_url) ?? asString(ai.base_url) ?? DEFAULT_BASE_URL[cloudProvider];
   const temperature = asFinite(section.temperature) ?? asFinite(ai.temperature) ?? 0.2;
   const max_output_tokens = asFinite(section.max_output_tokens) ?? asFinite(ai.max_output_tokens) ?? 1024;
   const timeout_ms = asFinite(section.timeout_ms) ?? asFinite(ai.timeout_ms) ?? 6e4;
   let api_key;
   if (provider !== "ollama") {
-    const envName = asString(section.api_key_env) ?? asString(ai.api_key_env) ?? DEFAULT_KEY_ENV[provider];
+    const keyedProvider = provider;
+    const envName = asString(section.api_key_env) ?? asString(ai.api_key_env) ?? DEFAULT_KEY_ENV[keyedProvider];
     const envValue = envName ? asString(process.env[envName]) : null;
     api_key = asString(section.api_key) ?? asString(ai.api_key) ?? envValue ?? void 0;
     if (!api_key) {
@@ -949,6 +976,250 @@ function resolve_provider_config(config) {
   };
 }
 
+// src/providers/cli.ts
+import fs2 from "fs";
+import os from "os";
+import path3 from "path";
+import { spawnSync as spawnSync2 } from "child_process";
+function defaultRunner(invocation) {
+  const result = spawnSync2(invocation.command, invocation.args, {
+    cwd: invocation.cwd,
+    encoding: "utf8",
+    input: invocation.input,
+    timeout: invocation.timeout_ms,
+    windowsHide: true
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    error: result.error
+  };
+}
+function asText(result) {
+  return [result.stdout, result.stderr].map((value) => value.trim()).filter(Boolean).join("\n").trim();
+}
+function requireSuccess(provider, result) {
+  if ((result.status ?? 1) === 0 && !result.error) {
+    return;
+  }
+  const details = asText(result) || result.error?.message || "unknown error";
+  throw new Error(`${provider} execution failed: ${details}`);
+}
+function tempOutputFile(prefix) {
+  return path3.join(os.tmpdir(), `${prefix}-${Date.now()}-${Math.random().toString(16).slice(2)}.txt`);
+}
+function combinedPrompt(input) {
+  return [input.system.trim(), input.prompt.trim()].filter(Boolean).join("\n\n");
+}
+function completionInvocation(config, input, cwd) {
+  if (config.provider === "codex_cli") {
+    const outputFile = tempOutputFile("coop-codex-complete");
+    return {
+      command: config.command ?? "codex",
+      args: [
+        "exec",
+        "-C",
+        cwd,
+        "--skip-git-repo-check",
+        "--sandbox",
+        "read-only",
+        ...config.model ? ["--model", config.model] : [],
+        "--output-last-message",
+        outputFile,
+        ...config.args ?? [],
+        "-"
+      ],
+      cwd,
+      input: combinedPrompt(input),
+      timeout_ms: config.timeout_ms
+    };
+  }
+  if (config.provider === "claude_cli") {
+    return {
+      command: config.command ?? "claude",
+      args: [
+        "-p",
+        combinedPrompt(input),
+        "--output-format",
+        "text",
+        "--permission-mode",
+        "plan",
+        ...config.model ? ["--model", config.model] : [],
+        ...config.args ?? []
+      ],
+      cwd,
+      timeout_ms: config.timeout_ms
+    };
+  }
+  return {
+    command: config.command ?? "gemini",
+    args: [
+      "-p",
+      combinedPrompt(input),
+      "--output-format",
+      "text",
+      "--approval-mode",
+      "plan",
+      ...config.model ? ["--model", config.model] : [],
+      ...config.args ?? []
+    ],
+    cwd,
+    timeout_ms: config.timeout_ms
+  };
+}
+function readCodexOutput(invocation) {
+  const index = invocation.args.indexOf("--output-last-message");
+  const outputFile = index >= 0 ? invocation.args[index + 1] : void 0;
+  if (!outputFile) return null;
+  if (!fs2.existsSync(outputFile)) return null;
+  try {
+    return fs2.readFileSync(outputFile, "utf8").trim();
+  } finally {
+    fs2.rmSync(outputFile, { force: true });
+  }
+}
+var CliCompletionProvider = class {
+  name;
+  config;
+  cwd;
+  runner;
+  constructor(config, options = {}) {
+    this.name = config.provider;
+    this.config = config;
+    this.cwd = path3.resolve(options.cwd ?? process.cwd());
+    this.runner = options.runner ?? defaultRunner;
+  }
+  async complete(input) {
+    const invocation = completionInvocation(this.config, input, this.cwd);
+    const result = this.runner(invocation);
+    requireSuccess(this.name, result);
+    const codexOutput = this.config.provider === "codex_cli" ? readCodexOutput(invocation) : null;
+    return {
+      text: codexOutput || result.stdout.trim() || result.stderr.trim()
+    };
+  }
+};
+function buildExecutionPrompt(task, contract, step, prompt, mode) {
+  const sections = [
+    mode === "execute" ? "You are executing a COOP task inside the repo. Make the necessary file changes, run allowed commands when needed, and finish with a concise summary." : "You are reviewing a COOP task inside the repo. Inspect the current workspace and return concise review findings only.",
+    `Task: ${task.id} - ${task.title}`,
+    `Goal: ${contract.goal}`,
+    `Step: ${step.step} (${step.action})`,
+    contract.context.acceptance_criteria.length > 0 ? `Acceptance: ${contract.context.acceptance_criteria.join(" | ")}` : "",
+    contract.context.tests_required.length > 0 ? `Tests Required: ${contract.context.tests_required.join(" | ")}` : "",
+    contract.context.authority_refs.length > 0 ? `Authority Refs: ${contract.context.authority_refs.join(" | ")}` : "",
+    contract.context.derived_refs.length > 0 ? `Derived Refs: ${contract.context.derived_refs.join(" | ")}` : "",
+    contract.permissions.read_paths.length > 0 ? `Allowed Read Paths: ${contract.permissions.read_paths.join(", ")}` : "",
+    contract.permissions.write_paths.length > 0 ? `Allowed Write Paths: ${contract.permissions.write_paths.join(", ")}` : "",
+    contract.permissions.allowed_commands.length > 0 ? `Allowed Commands: ${contract.permissions.allowed_commands.join(", ")}` : "",
+    contract.permissions.forbidden_commands.length > 0 ? `Forbidden Commands: ${contract.permissions.forbidden_commands.join(", ")}` : "",
+    prompt
+  ].filter(Boolean);
+  return sections.join("\n\n");
+}
+function countGitChanges(repoRoot, runner, timeoutMs) {
+  const result = runner({
+    command: "git",
+    args: ["status", "--porcelain"],
+    cwd: repoRoot,
+    timeout_ms: timeoutMs
+  });
+  if ((result.status ?? 1) !== 0) return 0;
+  return result.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).length;
+}
+function executionInvocation(config, prompt, repoRoot, mode) {
+  if (config.provider === "codex_cli") {
+    const outputFile = tempOutputFile("coop-codex-run");
+    return {
+      command: config.command ?? "codex",
+      args: [
+        "exec",
+        "-C",
+        repoRoot,
+        "--skip-git-repo-check",
+        "--sandbox",
+        mode === "execute" ? "workspace-write" : "read-only",
+        ...mode === "execute" ? ["--full-auto"] : [],
+        ...config.model ? ["--model", config.model] : [],
+        "--output-last-message",
+        outputFile,
+        ...config.args ?? [],
+        "-"
+      ],
+      cwd: repoRoot,
+      input: prompt,
+      timeout_ms: config.timeout_ms
+    };
+  }
+  if (config.provider === "claude_cli") {
+    return {
+      command: config.command ?? "claude",
+      args: [
+        "-p",
+        prompt,
+        "--output-format",
+        "text",
+        "--permission-mode",
+        mode === "execute" ? "bypassPermissions" : "plan",
+        ...config.model ? ["--model", config.model] : [],
+        ...config.args ?? []
+      ],
+      cwd: repoRoot,
+      timeout_ms: config.timeout_ms
+    };
+  }
+  return {
+    command: config.command ?? "gemini",
+    args: [
+      "-p",
+      prompt,
+      "--output-format",
+      "text",
+      "--approval-mode",
+      mode === "execute" ? "yolo" : "plan",
+      ...config.model ? ["--model", config.model] : [],
+      ...config.args ?? []
+    ],
+    cwd: repoRoot,
+    timeout_ms: config.timeout_ms
+  };
+}
+var CliAgentClient = class {
+  config;
+  repoRoot;
+  runner;
+  constructor(config, options = {}) {
+    this.config = config;
+    this.repoRoot = path3.resolve(options.cwd ?? process.cwd());
+    this.runner = options.runner ?? defaultRunner;
+  }
+  async generate(input) {
+    const before = countGitChanges(this.repoRoot, this.runner, this.config.timeout_ms);
+    const prompt = buildExecutionPrompt(input.task, input.contract, input.step, input.prompt, "execute");
+    const invocation = executionInvocation(this.config, prompt, this.repoRoot, "execute");
+    const result = this.runner(invocation);
+    requireSuccess(this.config.provider, result);
+    const after = countGitChanges(this.repoRoot, this.runner, this.config.timeout_ms);
+    const codexOutput = this.config.provider === "codex_cli" ? readCodexOutput(invocation) : null;
+    return {
+      summary: codexOutput || result.stdout.trim() || result.stderr.trim() || `Completed ${input.step.step}.`,
+      file_changes: Math.max(0, after - before)
+    };
+  }
+  async review(input) {
+    const prompt = buildExecutionPrompt(input.task, input.contract, input.step, input.prompt, "review");
+    const invocation = executionInvocation(this.config, prompt, this.repoRoot, "review");
+    const result = this.runner(invocation);
+    requireSuccess(this.config.provider, result);
+    const codexOutput = this.config.provider === "codex_cli" ? readCodexOutput(invocation) : null;
+    return {
+      summary: codexOutput || result.stdout.trim() || result.stderr.trim() || `Reviewed ${input.step.step}.`,
+      file_changes: 0
+    };
+  }
+};
+
 // src/providers/http.ts
 async function post_json(url, init) {
   const controller = new AbortController();
@@ -1145,6 +1416,10 @@ function create_provider(config) {
       return new GeminiProvider(resolved);
     case "ollama":
       return new OllamaProvider(resolved);
+    case "codex_cli":
+    case "claude_cli":
+    case "gemini_cli":
+      return new CliCompletionProvider(resolved);
     case "mock":
     default:
       return new MockProvider();
@@ -1208,7 +1483,11 @@ function asAgentResponse(text, tokens) {
     tokens_used: tokens
   };
 }
-function create_provider_agent_client(config) {
+function create_provider_agent_client(config, runtime = {}) {
+  const resolved = resolve_provider_config(config);
+  if (resolved.provider === "codex_cli" || resolved.provider === "claude_cli" || resolved.provider === "gemini_cli") {
+    return new CliAgentClient(resolved, runtime);
+  }
   const provider = create_provider(config);
   return {
     async generate(input) {
@@ -1263,6 +1542,8 @@ function create_provider_refinement_client(config) {
   };
 }
 export {
+  CliAgentClient,
+  CliCompletionProvider,
   buildIdeaRefinementPrompt,
   buildTaskRefinementPrompt,
   build_contract,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitsy/coop-ai",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "type": "module",
   "main": "./dist/index.cjs",
   "types": "./dist/index.d.ts",
@@ -17,7 +17,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@kitsy/coop-core": "2.1.0"
+    "@kitsy/coop-core": "2.1.2"
   },
   "devDependencies": {
     "@types/node": "^24.12.0",