@kitsy/coop-ai 0.0.1 → 1.0.0

package/dist/index.d.cts

@@ -1,7 +1,205 @@
-type CoopAiRuntimePlaceholder = {
-    readonly package: "@kitsy/coop-ai";
-    readonly status: "planned";
-};
-declare const coopAiRuntime: CoopAiRuntimePlaceholder;
+import { Task, TaskGraph, Run, RunStatus, RunStepResult } from '@kitsy/coop-core';
 
-export { type CoopAiRuntimePlaceholder, coopAiRuntime };
+interface AgentContractPermissions {
+    read_paths: string[];
+    write_paths: string[];
+    allowed_commands: string[];
+    forbidden_commands: string[];
+}
+interface AgentContractConstraints {
+    max_tokens: number;
+    max_duration_minutes: number;
+    max_file_changes: number;
+    require_tests: boolean;
+}
+interface AgentContractRelatedArtifacts {
+    task_id: string;
+    artifacts: Array<{
+        type: string;
+        target?: string;
+        path?: string;
+    }>;
+}
+interface AgentContractContext {
+    paths: string[];
+    files: string[];
+    tasks: string[];
+    acceptance_criteria: string[];
+    related_task_artifacts: AgentContractRelatedArtifacts[];
+}
+interface AgentContract {
+    task_id: string;
+    goal: string;
+    executor: string;
+    permissions: AgentContractPermissions;
+    constraints: AgentContractConstraints;
+    context: AgentContractContext;
+    output_requirements: string[];
+}
+
+/**
+ * Builds a sandboxed AI agent contract from a task and repo graph context.
+ * [SPEC: Architecture v2.0 §13.1, Task Schema v2.0 §8]
+ */
+declare function build_contract(task: Task, graph: TaskGraph, config: unknown): AgentContract;
+
+/**
+ * Selects the AI executor for a task based on complexity/type/review signals.
+ * [SPEC: Architecture v2.0 §13.3]
+ */
+declare function select_agent(task: Task, config: unknown): string;
+
+type FileAccessMode = "read" | "write";
+interface SandboxRunState {
+    tokens_used: number;
+    duration_minutes: number;
+    file_changes: number;
+}
+/**
+ * Validates whether a shell command is permitted by the contract sandbox.
+ * [SPEC: Architecture v2.0 §13.2]
+ */
+declare function validate_command(command: string, contract: AgentContract): boolean;
+/**
+ * Validates whether the requested file access is within sandboxed paths.
+ * [SPEC: Architecture v2.0 §13.2]
+ */
+declare function validate_file_access(pathValue: string, mode: FileAccessMode, contract: AgentContract): boolean;
+declare function constraint_violation_reasons(runState: SandboxRunState, contract: AgentContract): string[];
+/**
+ * Enforces token/time/file-change constraints for an active run.
+ * [SPEC: Architecture v2.0 §13.2]
+ */
+declare function enforce_constraints(runState: SandboxRunState, contract: AgentContract): boolean;
+
+/**
+ * Creates an execution run envelope for a task and executor.
+ * [SPEC: Architecture v2.0 §12]
+ */
+declare function create_run(task: Task, executor: string, now?: Date): Run;
+/**
+ * Appends a step result to an existing run.
+ * [SPEC: Architecture v2.0 §12]
+ */
+declare function log_step(run: Run, step: RunStepResult): Run;
+/**
+ * Finalizes a run status and completion timestamp.
+ * [SPEC: Architecture v2.0 §12]
+ */
+declare function finalize_run(run: Run, status: RunStatus, now?: Date): Run;
+/**
+ * Persists a run log under .coop/runs/.
+ * [SPEC: Architecture v2.0 §12]
+ */
+declare function write_run(run: Run, coopDir: string): string;
+
+interface AgentResponse {
+    summary: string;
+    tokens_used?: number;
+    file_changes?: number;
+}
+interface AgentClient {
+    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>;
+}
+interface ExecuteTaskOptions {
+    repo_root?: string;
+    coop_dir?: string;
+    step?: string;
+    on_progress?: (message: string) => void;
+    agent_client?: AgentClient;
+}
+interface RunResult {
+    status: RunStatus;
+    run: Run;
+    log_path: string;
+}
+/**
+ * Executes a task runbook in a sandbox and writes an immutable run log.
+ * [SPEC: Architecture v2.0 §12, §13.2]
+ */
+declare function execute_task(task: Task, contract: AgentContract, _graph: TaskGraph, options?: ExecuteTaskOptions): Promise<RunResult>;
+
+interface IdeaDecompositionInput {
+    idea_id: string;
+    title: string;
+    body: string;
+}
+interface DecomposedTaskDraft {
+    title: string;
+    body?: string;
+    type?: "feature" | "bug" | "chore" | "spike";
+    priority?: "p0" | "p1" | "p2" | "p3";
+    track?: string;
+}
+interface IdeaDecomposerClient {
+    decompose(prompt: string, input: IdeaDecompositionInput): Promise<DecomposedTaskDraft[]>;
+}
+/**
+ * Builds a decomposition prompt used for idea-to-task expansion.
+ * [SPEC: Architecture v2.0 §Phase 4]
+ */
+declare function build_decomposition_prompt(input: IdeaDecompositionInput): string;
+/**
+ * Decomposes an idea into task drafts using a provided AI client or a deterministic fallback.
+ * [SPEC: Architecture v2.0 §Phase 4]
+ */
+declare function decompose_idea_to_tasks(input: IdeaDecompositionInput, client?: IdeaDecomposerClient): Promise<DecomposedTaskDraft[]>;
+
+type AiProviderName = "mock" | "openai" | "anthropic" | "gemini" | "ollama";
+interface ProviderConfig {
+    provider: AiProviderName;
+    model: string;
+    base_url?: string;
+    api_key?: string;
+    temperature: number;
+    max_output_tokens: number;
+    timeout_ms: number;
+}
+interface CompletionInput {
+    system: string;
+    prompt: string;
+}
+interface CompletionResult {
+    text: string;
+    total_tokens?: number;
+}
+interface LlmProvider {
+    readonly name: AiProviderName;
+    complete(input: CompletionInput): Promise<CompletionResult>;
+}
+
+/**
+ * Resolves provider runtime settings from config and environment variables.
+ * [SPEC: Architecture v2.0 §13]
+ */
+declare function resolve_provider_config(config: unknown): ProviderConfig;
+
+/**
+ * Creates an LLM provider instance from COOP config.
+ * [SPEC: Architecture v2.0 §13]
+ */
+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;
+/**
+ * Creates an idea decomposition client backed by configured LLM provider(s).
+ * [SPEC: Architecture v2.0 §Phase 4]
+ */
+declare function create_provider_idea_decomposer(config: unknown): IdeaDecomposerClient;
+
+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 LlmProvider, type ProviderConfig, type RunResult, type SandboxRunState, build_contract, build_decomposition_prompt, constraint_violation_reasons, create_provider, create_provider_agent_client, create_provider_idea_decomposer, create_run, decompose_idea_to_tasks, enforce_constraints, execute_task, finalize_run, log_step, resolve_provider_config, select_agent, validate_command, validate_file_access, write_run };

package/dist/index.d.ts

@@ -1,7 +1,205 @@
-type CoopAiRuntimePlaceholder = {
-    readonly package: "@kitsy/coop-ai";
-    readonly status: "planned";
-};
-declare const coopAiRuntime: CoopAiRuntimePlaceholder;
+import { Task, TaskGraph, Run, RunStatus, RunStepResult } from '@kitsy/coop-core';
 
-export { type CoopAiRuntimePlaceholder, coopAiRuntime };
+interface AgentContractPermissions {
+    read_paths: string[];
+    write_paths: string[];
+    allowed_commands: string[];
+    forbidden_commands: string[];
+}
+interface AgentContractConstraints {
+    max_tokens: number;
+    max_duration_minutes: number;
+    max_file_changes: number;
+    require_tests: boolean;
+}
+interface AgentContractRelatedArtifacts {
+    task_id: string;
+    artifacts: Array<{
+        type: string;
+        target?: string;
+        path?: string;
+    }>;
+}
+interface AgentContractContext {
+    paths: string[];
+    files: string[];
+    tasks: string[];
+    acceptance_criteria: string[];
+    related_task_artifacts: AgentContractRelatedArtifacts[];
+}
+interface AgentContract {
+    task_id: string;
+    goal: string;
+    executor: string;
+    permissions: AgentContractPermissions;
+    constraints: AgentContractConstraints;
+    context: AgentContractContext;
+    output_requirements: string[];
+}
+
+/**
+ * Builds a sandboxed AI agent contract from a task and repo graph context.
+ * [SPEC: Architecture v2.0 §13.1, Task Schema v2.0 §8]
+ */
+declare function build_contract(task: Task, graph: TaskGraph, config: unknown): AgentContract;
+
+/**
+ * Selects the AI executor for a task based on complexity/type/review signals.
+ * [SPEC: Architecture v2.0 §13.3]
+ */
+declare function select_agent(task: Task, config: unknown): string;
+
+type FileAccessMode = "read" | "write";
+interface SandboxRunState {
+    tokens_used: number;
+    duration_minutes: number;
+    file_changes: number;
+}
+/**
+ * Validates whether a shell command is permitted by the contract sandbox.
+ * [SPEC: Architecture v2.0 §13.2]
+ */
+declare function validate_command(command: string, contract: AgentContract): boolean;
+/**
+ * Validates whether the requested file access is within sandboxed paths.
+ * [SPEC: Architecture v2.0 §13.2]
+ */
+declare function validate_file_access(pathValue: string, mode: FileAccessMode, contract: AgentContract): boolean;
+declare function constraint_violation_reasons(runState: SandboxRunState, contract: AgentContract): string[];
+/**
+ * Enforces token/time/file-change constraints for an active run.
+ * [SPEC: Architecture v2.0 §13.2]
+ */
+declare function enforce_constraints(runState: SandboxRunState, contract: AgentContract): boolean;
+
+/**
+ * Creates an execution run envelope for a task and executor.
+ * [SPEC: Architecture v2.0 §12]
+ */
+declare function create_run(task: Task, executor: string, now?: Date): Run;
+/**
+ * Appends a step result to an existing run.
+ * [SPEC: Architecture v2.0 §12]
+ */
+declare function log_step(run: Run, step: RunStepResult): Run;
+/**
+ * Finalizes a run status and completion timestamp.
+ * [SPEC: Architecture v2.0 §12]
+ */
+declare function finalize_run(run: Run, status: RunStatus, now?: Date): Run;
+/**
+ * Persists a run log under .coop/runs/.
+ * [SPEC: Architecture v2.0 §12]
+ */
+declare function write_run(run: Run, coopDir: string): string;
+
+interface AgentResponse {
+    summary: string;
+    tokens_used?: number;
+    file_changes?: number;
+}
+interface AgentClient {
+    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>;
+}
+interface ExecuteTaskOptions {
+    repo_root?: string;
+    coop_dir?: string;
+    step?: string;
+    on_progress?: (message: string) => void;
+    agent_client?: AgentClient;
+}
+interface RunResult {
+    status: RunStatus;
+    run: Run;
+    log_path: string;
+}
+/**
+ * Executes a task runbook in a sandbox and writes an immutable run log.
+ * [SPEC: Architecture v2.0 §12, §13.2]
+ */
+declare function execute_task(task: Task, contract: AgentContract, _graph: TaskGraph, options?: ExecuteTaskOptions): Promise<RunResult>;
+
+interface IdeaDecompositionInput {
+    idea_id: string;
+    title: string;
+    body: string;
+}
+interface DecomposedTaskDraft {
+    title: string;
+    body?: string;
+    type?: "feature" | "bug" | "chore" | "spike";
+    priority?: "p0" | "p1" | "p2" | "p3";
+    track?: string;
+}
+interface IdeaDecomposerClient {
+    decompose(prompt: string, input: IdeaDecompositionInput): Promise<DecomposedTaskDraft[]>;
+}
+/**
+ * Builds a decomposition prompt used for idea-to-task expansion.
+ * [SPEC: Architecture v2.0 §Phase 4]
+ */
+declare function build_decomposition_prompt(input: IdeaDecompositionInput): string;
+/**
+ * Decomposes an idea into task drafts using a provided AI client or a deterministic fallback.
+ * [SPEC: Architecture v2.0 §Phase 4]
+ */
+declare function decompose_idea_to_tasks(input: IdeaDecompositionInput, client?: IdeaDecomposerClient): Promise<DecomposedTaskDraft[]>;
+
+type AiProviderName = "mock" | "openai" | "anthropic" | "gemini" | "ollama";
+interface ProviderConfig {
+    provider: AiProviderName;
+    model: string;
+    base_url?: string;
+    api_key?: string;
+    temperature: number;
+    max_output_tokens: number;
+    timeout_ms: number;
+}
+interface CompletionInput {
+    system: string;
+    prompt: string;
+}
+interface CompletionResult {
+    text: string;
+    total_tokens?: number;
+}
+interface LlmProvider {
+    readonly name: AiProviderName;
+    complete(input: CompletionInput): Promise<CompletionResult>;
+}
+
+/**
+ * Resolves provider runtime settings from config and environment variables.
+ * [SPEC: Architecture v2.0 §13]
+ */
+declare function resolve_provider_config(config: unknown): ProviderConfig;
+
+/**
+ * Creates an LLM provider instance from COOP config.
+ * [SPEC: Architecture v2.0 §13]
+ */
+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;
+/**
+ * Creates an idea decomposition client backed by configured LLM provider(s).
+ * [SPEC: Architecture v2.0 §Phase 4]
+ */
+declare function create_provider_idea_decomposer(config: unknown): IdeaDecomposerClient;
+
+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 LlmProvider, type ProviderConfig, type RunResult, type SandboxRunState, build_contract, build_decomposition_prompt, constraint_violation_reasons, create_provider, create_provider_agent_client, create_provider_idea_decomposer, create_run, decompose_idea_to_tasks, enforce_constraints, execute_task, finalize_run, log_step, resolve_provider_config, select_agent, validate_command, validate_file_access, write_run };