kunchi 0.1.0__py3-none-any.whl

kunchi/__init__.py

@@ -0,0 +1,8 @@
+"""Kunchi — a simple coding harness."""
+
+from kunchi.config import HarnessConfig
+from kunchi.harness import Harness, default_harness_config
+from kunchi.hello import hello
+from kunchi.models import PlanStatus, RunReport
+
+__all__ = ["Harness", "HarnessConfig", "PlanStatus", "RunReport", "default_harness_config", "hello"]

kunchi/agents/__init__.py

@@ -0,0 +1,4 @@
+from kunchi.agents.fake import FakeImplementorAgent, FakePlannerAgent, FakeValidatorAgent
+from kunchi.agents.registry import AgentRegistry
+
+__all__ = ["AgentRegistry", "FakeImplementorAgent", "FakePlannerAgent", "FakeValidatorAgent"]

kunchi/agents/executor.py

@@ -0,0 +1,155 @@
+from kunchi.plan.parsing import PlanDraftParseError, parse_plan_draft
+from kunchi.agents.prompts import PromptBuilder
+from kunchi.agents.registry import AgentRegistry
+from kunchi.config.resolver import ConfigResolver
+from kunchi.events.bus import EventBus
+from kunchi.models.agent import AgentInput, AgentResult, AgentRole, AgentSpec
+from kunchi.models.context import PlanContext, TaskContext
+from kunchi.models.events import AgentCompleted, AgentInvoked
+from kunchi.models.plan import PlanDraft
+from kunchi.models.task import FixRequest, Task
+from kunchi.models.validation import ValidationResult
+from kunchi.tracing.preview import preview_text
+from kunchi.tracing.trace import (
+    invocation_from_metadata,
+    traced_agent_result,
+    traced_validation_result,
+)
+
+
+class AgentExecutor:
+    def __init__(
+        self,
+        registry: AgentRegistry,
+        prompts: PromptBuilder,
+        resolver: ConfigResolver,
+        events: EventBus | None = None,
+    ) -> None:
+        self._registry = registry
+        self._prompts = prompts
+        self._resolver = resolver
+        self._events = events
+
+    async def invoke_planner(self, spec: AgentSpec, goal: str, context: PlanContext) -> PlanDraft:
+        agent = self._registry.resolve(spec)
+        prompt = self._prompts.build_planner_prompt(goal, context)
+        result = await self._invoke_agent(
+            agent,
+            AgentInput(role=AgentRole.PLANNER, prompt=prompt, context=context),
+            spec,
+            prompt,
+            context,
+        )
+        if not isinstance(result, AgentResult):
+            raise TypeError("Planner must return AgentResult")
+        return parse_plan_draft(result)
+
+    async def invoke_implementor(
+        self,
+        task: Task,
+        ctx: TaskContext,
+        fix: FixRequest | None = None,
+    ) -> AgentResult:
+        agent = self._registry.resolve(task.implementor)
+        prompt = self._prompts.build_implementor_prompt(task, ctx, fix)
+        result = await self._invoke_agent(
+            agent,
+            AgentInput(role=AgentRole.IMPLEMENTOR, prompt=prompt, context=ctx),
+            task.implementor,
+            prompt,
+            ctx,
+        )
+        if not isinstance(result, AgentResult):
+            raise TypeError("Implementor must return AgentResult")
+        return result
+
+    async def invoke_validator(
+        self,
+        task: Task,
+        validator: AgentSpec,
+        ctx: TaskContext,
+        implementor: AgentResult,
+        attempt: int,
+    ) -> ValidationResult:
+        agent = self._registry.resolve(validator)
+        prompt = self._prompts.build_validator_prompt(task, validator, ctx, implementor)
+        ctx.metadata["attempt"] = attempt
+        result = await self._invoke_agent(
+            agent,
+            AgentInput(role=AgentRole.VALIDATOR, prompt=prompt, context=ctx),
+            validator,
+            prompt,
+            ctx,
+        )
+        if not isinstance(result, ValidationResult):
+            raise TypeError("Validator must return ValidationResult")
+        return result
+
+    async def _invoke_agent(
+        self,
+        agent: object,
+        agent_input: AgentInput,
+        spec: AgentSpec,
+        prompt: str,
+        context: PlanContext | TaskContext,
+    ) -> AgentResult | ValidationResult:
+        plan_id, task_id, attempt = self._context_ids(context)
+        preview_limit = self._resolver.trace_preview_chars()
+
+        await self._emit(
+            AgentInvoked(
+                agent_id=spec.id,
+                role=agent_input.role,
+                prompt=preview_text(prompt, preview_limit),
+                plan_id=plan_id,
+                task_id=task_id,
+                attempt=attempt,
+            )
+        )
+
+        result = await agent.invoke(agent_input)  # type: ignore[union-attr]
+
+        agent_result: AgentResult | None = None
+        validation_result: ValidationResult | None = None
+        invocation = None
+
+        if isinstance(result, AgentResult):
+            agent_result = traced_agent_result(result, preview_limit)
+            invocation = invocation_from_metadata(agent_result.metadata)
+        elif isinstance(result, ValidationResult):
+            validation_result = traced_validation_result(result, preview_limit)
+            invocation = invocation_from_metadata(validation_result.metadata)
+
+        await self._emit(
+            AgentCompleted(
+                agent_id=spec.id,
+                role=agent_input.role,
+                prompt=preview_text(prompt, preview_limit),
+                plan_id=plan_id,
+                task_id=task_id,
+                attempt=attempt,
+                agent_result=agent_result,
+                validation_result=validation_result,
+                invocation=invocation,
+            )
+        )
+        return result
+
+    async def _emit(self, event: AgentInvoked | AgentCompleted) -> None:
+        if self._events is None:
+            return
+        await self._events.emit(event)
+
+    @staticmethod
+    def _context_ids(context: PlanContext | TaskContext) -> tuple[str | None, str | None, int | None]:
+        if not isinstance(context, TaskContext):
+            return None, None, None
+        metadata = context.metadata
+        plan_id = metadata.get("plan_id")
+        task_id = metadata.get("task_id")
+        attempt = metadata.get("attempt")
+        return (
+            str(plan_id) if plan_id is not None else None,
+            str(task_id) if task_id is not None else None,
+            int(attempt) if attempt is not None else None,
+        )

kunchi/agents/fake.py

@@ -0,0 +1,98 @@
+import json
+from typing import Protocol
+
+from kunchi.models.agent import AgentInput, AgentResult, AgentRole, AgentSpec
+from kunchi.models.validation import ValidationResult
+
+
+class Agent(Protocol):
+    spec: AgentSpec
+
+    async def invoke(self, input: AgentInput) -> AgentResult | ValidationResult: ...
+
+
+class FakePlannerAgent:
+    def __init__(self, spec: AgentSpec) -> None:
+        self.spec = spec
+
+    async def invoke(self, input: AgentInput) -> AgentResult:
+        goal = input.prompt
+        if "invalid-plan" in goal.lower():
+            raw = "{not valid json"
+        else:
+            draft = {
+                "tasks": [
+                    {
+                        "title": "Setup foundation",
+                        "description": f"Initial work for: {goal[:80]}",
+                        "acceptance_criteria": ["Foundation exists"],
+                        "depends_on": [],
+                    },
+                    {
+                        "title": "Complete feature",
+                        "description": "Finish the requested feature",
+                        "acceptance_criteria": ["Feature works"],
+                        "depends_on": ["task-1"],
+                    },
+                ]
+            }
+            raw = json.dumps(draft)
+        return AgentResult(
+            agent_id=self.spec.id,
+            role=AgentRole.PLANNER,
+            summary="Fake planner produced a two-task plan",
+            raw_output=raw,
+            metadata={"kind": "fake-planner"},
+        )
+
+
+class FakeImplementorAgent:
+    def __init__(self, spec: AgentSpec) -> None:
+        self.spec = spec
+        self._attempts: dict[str, int] = {}
+
+    async def invoke(self, input: AgentInput) -> AgentResult:
+        task_key = input.prompt[:64]
+        attempt = self._attempts.get(task_key, 0) + 1
+        self._attempts[task_key] = attempt
+
+        fail_output_attempts = int(self.spec.config.get("fail_output_attempts", 0))
+        if attempt <= fail_output_attempts:
+            raw = json.dumps({"summary": "missing required structure"})
+        else:
+            raw = json.dumps(
+                {
+                    "summary": f"Implemented task (attempt {attempt})",
+                    "result_code": "ok",
+                }
+            )
+
+        return AgentResult(
+            agent_id=self.spec.id,
+            role=AgentRole.IMPLEMENTOR,
+            summary=f"Fake implementor attempt {attempt}",
+            raw_output=raw,
+            metadata={"attempt": attempt, "kind": "fake-implementor"},
+        )
+
+
+class FakeValidatorAgent:
+    def __init__(self, spec: AgentSpec) -> None:
+        self.spec = spec
+
+    async def invoke(self, input: AgentInput) -> ValidationResult:
+        fail_until_attempt = int(self.spec.config.get("fail_until_attempt", 0))
+        attempt = int(input.context.metadata.get("attempt", 1))  # type: ignore[union-attr]
+
+        if attempt <= fail_until_attempt:
+            return ValidationResult(
+                validator_id=self.spec.id,
+                passed=False,
+                feedback=f"{self.spec.id} rejected attempt {attempt}",
+            )
+
+        return ValidationResult(
+            validator_id=self.spec.id,
+            passed=True,
+            feedback=f"{self.spec.id} approved",
+        )

kunchi/agents/implementor_contract.py

@@ -0,0 +1,3 @@
+IMPLEMENTOR_OUTPUT_INSTRUCTIONS = """Return ONLY a single JSON object matching the required output contract (no markdown fences, no commentary).
+Use snake_case field names exactly as specified in the contract.
+When git_commit is required, create a git commit with your changes before responding."""

kunchi/agents/parsing.py

@@ -0,0 +1,129 @@
+import json
+import re
+
+from kunchi.models.validation import ValidationResult
+
+
+def extract_json_from_stdout(text: str) -> dict[str, object]:
+    """Extract a JSON object from CLI stdout, tolerating leading/trailing noise."""
+    text = text.strip()
+    if not text:
+        raise ValueError("Empty stdout")
+
+    for line in text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            data = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(data, dict):
+            return data
+
+    try:
+        data = json.loads(text)
+        if isinstance(data, dict):
+            return data
+    except json.JSONDecodeError:
+        pass
+
+    block = _find_json_object(text)
+    if block is None:
+        raise ValueError("No JSON object found in stdout")
+    data = json.loads(block)
+    if not isinstance(data, dict):
+        raise ValueError("Parsed JSON is not an object")
+    return data
+
+
+def unwrap_cursor_cli_text(data: dict[str, object]) -> str | None:
+    """Extract assistant/plan text from a Cursor CLI JSON envelope."""
+    if data.get("type") == "result":
+        inner = data.get("result")
+        if isinstance(inner, str) and inner.strip():
+            return inner.strip()
+        if isinstance(inner, dict):
+            nested = extract_assistant_text(inner)
+            return nested or json.dumps(inner)
+
+    direct = extract_assistant_text(data)
+    if direct:
+        return direct
+
+    for key in ("text", "output", "content", "message"):
+        value = data.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+
+    return None
+
+
+def extract_assistant_text(data: dict[str, object]) -> str | None:
+    message = data.get("message")
+    if isinstance(message, dict):
+        content = message.get("content")
+        if isinstance(content, list):
+            parts: list[str] = []
+            for item in content:
+                if isinstance(item, dict):
+                    text = item.get("text")
+                    if isinstance(text, str) and text.strip():
+                        parts.append(text.strip())
+            if parts:
+                return "\n".join(parts)
+        text = message.get("text")
+        if isinstance(text, str) and text.strip():
+            return text.strip()
+
+    if "tasks" in data and isinstance(data.get("tasks"), list):
+        return json.dumps(data)
+
+    return None
+
+
+def _find_json_object(text: str) -> str | None:
+    start = text.find("{")
+    if start == -1:
+        return None
+    depth = 0
+    for index, char in enumerate(text[start:], start=start):
+        if char == "{":
+            depth += 1
+        elif char == "}":
+            depth -= 1
+            if depth == 0:
+                return text[start : index + 1]
+    return None
+
+
+def extract_json_object_from_text(text: str) -> dict[str, object] | None:
+    """Extract a JSON object from prose, fenced blocks, or CLI envelope text."""
+    text = text.strip()
+    if not text:
+        return None
+
+    try:
+        return extract_json_from_stdout(text)
+    except ValueError:
+        pass
+
+    for block in re.findall(r"```(?:json)?\s*([\s\S]*?)```", text, flags=re.IGNORECASE):
+        try:
+            return extract_json_from_stdout(block)
+        except ValueError:
+            continue
+
+    return None
+
+
+def parse_validation_result(data: dict[str, object], validator_id: str) -> ValidationResult:
+    passed = bool(data.get("passed", False))
+    feedback = str(data.get("feedback", ""))
+    if not passed and not feedback:
+        feedback = "Validation failed"
+    return ValidationResult(
+        validator_id=validator_id,
+        passed=passed,
+        feedback=feedback,
+    )

kunchi/agents/planner_contract.py

@@ -0,0 +1,21 @@
+PLAN_DRAFT_JSON_EXAMPLE = """{
+  "tasks": [
+    {
+      "title": "Short task title",
+      "description": "What to implement",
+      "acceptance_criteria": ["Criterion one", "Criterion two"],
+      "depends_on": []
+    }
+  ]
+}"""
+
+PLANNER_OUTPUT_INSTRUCTIONS = f"""Return ONLY a single JSON object matching this schema (no markdown fences, no commentary):
+
+{PLAN_DRAFT_JSON_EXAMPLE}
+
+Rules:
+- "tasks" is required and must contain at least one task object.
+- Each task requires "title" and "description" strings.
+- Use snake_case field names exactly as shown.
+- "depends_on" lists task titles or ids that must finish first (use [] when none).
+- Keep the plan focused and actionable for the given goal."""

kunchi/agents/prompts.py

@@ -0,0 +1,57 @@
+from kunchi.agents.implementor_contract import IMPLEMENTOR_OUTPUT_INSTRUCTIONS
+from kunchi.agents.planner_contract import PLANNER_OUTPUT_INSTRUCTIONS
+from kunchi.agents.validator_contract import VALIDATOR_OUTPUT_INSTRUCTIONS
+from kunchi.models.agent import AgentResult, AgentSpec
+from kunchi.models.context import PlanContext, TaskContext
+from kunchi.models.task import FixRequest, Task
+from kunchi.models.validation import ValidationResult
+
+
+class PromptBuilder:
+    def build_planner_prompt(self, goal: str, context: PlanContext) -> str:
+        return (
+            f"Goal: {goal}\n"
+            f"Workspace: {context.workspace.path}\n\n"
+            f"{PLANNER_OUTPUT_INSTRUCTIONS}"
+        )
+
+    def build_implementor_prompt(
+        self,
+        task: Task,
+        ctx: TaskContext,
+        fix: FixRequest | None = None,
+    ) -> str:
+        parts = [
+            f"Task: {task.title}",
+            f"Description: {task.description}",
+            task.output_contract.to_prompt_instructions(),
+            IMPLEMENTOR_OUTPUT_INSTRUCTIONS,
+        ]
+        if task.acceptance_criteria:
+            parts.append("Acceptance criteria:\n- " + "\n- ".join(task.acceptance_criteria))
+        if ctx.upstream_outputs:
+            parts.append("Upstream completed tasks:")
+            for task_id, result in ctx.upstream_outputs.items():
+                parts.append(f"- {task_id}: {result.summary}")
+        if fix and fix.accumulated_feedback:
+            parts.append(f"Fix the following issues:\n{fix.accumulated_feedback}")
+        return "\n\n".join(parts)
+
+    def build_validator_prompt(
+        self,
+        task: Task,
+        validator: AgentSpec,
+        ctx: TaskContext,
+        implementor: AgentResult,
+    ) -> str:
+        del ctx
+        field_lines = [f"- {key}: {value}" for key, value in implementor.fields.items()]
+        criteria = "\n- ".join(task.acceptance_criteria) or "(none)"
+        return (
+            f"Validator: {validator.id}\n"
+            f"Task: {task.title}\n"
+            f"Implementor summary: {implementor.summary}\n"
+            f"Implementor fields:\n" + "\n".join(field_lines) + "\n"
+            f"Acceptance criteria:\n- {criteria}\n\n"
+            f"{VALIDATOR_OUTPUT_INSTRUCTIONS}"
+        )

kunchi/agents/registry.py

@@ -0,0 +1,61 @@
+from typing import Protocol
+
+from kunchi.agents.fake import FakeImplementorAgent, FakePlannerAgent, FakeValidatorAgent
+from kunchi.config.resolver import ConfigResolver
+from kunchi.models.agent import AgentInput, AgentResult, AgentSpec, AgentRole
+from kunchi.models.validation import ValidationResult
+from kunchi.providers.agents.cli_agent import CLIAgent
+from kunchi.providers.agents.registry import AgentClientRegistry
+from kunchi.providers.agents.runner import CLIRunner
+from kunchi.providers.agents.shell import ShellAgent
+from kunchi.providers.vcs.artifacts import ArtifactCollector
+
+
+class Agent(Protocol):
+    spec: AgentSpec
+
+    async def invoke(self, input: AgentInput) -> AgentResult | ValidationResult: ...
+
+
+class AgentRegistry:
+    def __init__(
+        self,
+        resolver: ConfigResolver,
+        runner: CLIRunner | None = None,
+        artifact_collector: ArtifactCollector | None = None,
+        agent_clients: AgentClientRegistry | None = None,
+    ) -> None:
+        self._resolver = resolver
+        self._runner = runner or CLIRunner()
+        self._artifact_collector = artifact_collector or ArtifactCollector()
+        self._agent_clients = agent_clients or AgentClientRegistry.default()
+
+    def resolve(self, spec: AgentSpec) -> Agent:
+        if spec.config.get("backend") == "fake":
+            return self._resolve_fake(spec)
+
+        cli_name = spec.config.get("cli")
+        if cli_name is None:
+            return self._resolve_fake(spec)
+
+        cli_name = str(cli_name)
+        if cli_name == "shell":
+            return ShellAgent(spec, self._runner, self._resolver)
+
+        provider = self._agent_clients.get(cli_name)
+        return CLIAgent(
+            spec,
+            provider,
+            self._runner,
+            self._artifact_collector,
+            self._resolver,
+        )
+
+    def _resolve_fake(self, spec: AgentSpec) -> Agent:
+        if spec.role is AgentRole.PLANNER:
+            return FakePlannerAgent(spec)
+        if spec.role is AgentRole.IMPLEMENTOR:
+            return FakeImplementorAgent(spec)
+        if spec.role is AgentRole.VALIDATOR:
+            return FakeValidatorAgent(spec)
+        raise ValueError(f"Unsupported fake agent role: {spec.role}")

kunchi/agents/validator_contract.py

@@ -0,0 +1,6 @@
+VALIDATOR_OUTPUT_INSTRUCTIONS = """Return ONLY a single JSON object (no markdown fences, no commentary):
+{"passed": true|false, "feedback": "short explanation"}
+
+Rules:
+- "passed" is required and must be a boolean.
+- "feedback" is required when passed is false; may be brief when passed is true."""

kunchi/auth/__init__.py

@@ -0,0 +1,11 @@
+from kunchi.auth.models import AuthConfig, AuthToken, UserCredentials
+from kunchi.auth.provider import AuthProvider
+from kunchi.auth.providers.memory import InMemoryAuthProvider
+
+__all__ = [
+    "AuthConfig",
+    "AuthProvider",
+    "AuthToken",
+    "InMemoryAuthProvider",
+    "UserCredentials",
+]

kunchi/auth/models.py

@@ -0,0 +1,24 @@
+from pydantic import BaseModel, Field
+
+
+class AuthConfig(BaseModel):
+    """Configuration for authentication providers."""
+
+    secret_key: str = Field(min_length=1, description="Signing key for tokens")
+    token_ttl_seconds: int = Field(default=3600, ge=1)
+    algorithm: str = "HS256"
+
+
+class UserCredentials(BaseModel):
+    """Credentials supplied during login."""
+
+    username: str = Field(min_length=1)
+    password: str = Field(min_length=1)
+
+
+class AuthToken(BaseModel):
+    """Issued authentication token."""
+
+    access_token: str
+    token_type: str = "bearer"
+    expires_in: int | None = None

kunchi/auth/provider.py

@@ -0,0 +1,15 @@
+from typing import Protocol
+
+from kunchi.auth.models import AuthToken, UserCredentials
+
+
+class AuthProvider(Protocol):
+    """Contract for authentication backends."""
+
+    async def authenticate(self, credentials: UserCredentials) -> AuthToken | None:
+        """Validate credentials and return a token, or None if invalid."""
+        ...
+
+    async def verify_token(self, token: str) -> str | None:
+        """Return the authenticated subject for a valid token, or None."""
+        ...

kunchi/auth/providers/__init__.py

@@ -0,0 +1,3 @@
+from kunchi.auth.providers.memory import InMemoryAuthProvider
+
+__all__ = ["InMemoryAuthProvider"]

kunchi/auth/providers/memory.py

@@ -0,0 +1,44 @@
+import secrets
+from datetime import UTC, datetime, timedelta
+
+from kunchi.auth.models import AuthConfig, AuthToken, UserCredentials
+
+
+class InMemoryAuthProvider:
+    """Simple in-memory auth backend for development and tests."""
+
+    def __init__(
+        self,
+        config: AuthConfig,
+        users: dict[str, str] | None = None,
+    ) -> None:
+        self._config = config
+        self._users = dict(users or {})
+        self._tokens: dict[str, tuple[str, datetime]] = {}
+
+    def register_user(self, username: str, password: str) -> None:
+        self._users[username] = password
+
+    async def authenticate(self, credentials: UserCredentials) -> AuthToken | None:
+        if self._users.get(credentials.username) != credentials.password:
+            return None
+
+        token = secrets.token_urlsafe(32)
+        expires_at = datetime.now(UTC) + timedelta(seconds=self._config.token_ttl_seconds)
+        self._tokens[token] = (credentials.username, expires_at)
+        return AuthToken(
+            access_token=token,
+            expires_in=self._config.token_ttl_seconds,
+        )
+
+    async def verify_token(self, token: str) -> str | None:
+        entry = self._tokens.get(token)
+        if entry is None:
+            return None
+
+        username, expires_at = entry
+        if datetime.now(UTC) >= expires_at:
+            del self._tokens[token]
+            return None
+
+        return username

kunchi/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Kunchi command-line interface."""
+
+from kunchi.cli.main import main
+
+__all__ = ["main"]