codee-agent 0.1.0__py3-none-any.whl

codee/lib/trigger_email_skills.py

@@ -0,0 +1,225 @@
+import email
+import os
+import tempfile
+import uuid
+from dataclasses import dataclass
+from email.message import Message
+from pathlib import Path
+from typing import Callable
+
+from codee_main_context.context import CodeeMainContext
+
+from codee.lib import runs_db
+from codee.lib.trigger_aws_sqs_skills import _parse_skill_file, _skill_key
+from codee_main_context.context import project_root, skills_dir as default_skills_dir
+
+REPO_ROOT = project_root()
+SKILLS_DIR = default_skills_dir(REPO_ROOT)
+EMAILS_DIR = REPO_ROOT / "temp-emails"
+
+# Max emails handled per cron tick (across all email-triggered skills).
+MAX_EMAILS_PER_TICK = 3
+
+# Comma-separated sender domains. When unset, email-triggered skills remain disabled.
+ALLOWED_SENDER_DOMAINS = tuple(
+    domain.strip().lower()
+    for domain in os.environ.get("CODEE_ALLOWED_SENDER_DOMAINS", "").split(",")
+    if domain.strip()
+)
+
+RunClaude = Callable[[str, str, str], str]
+
+
+@dataclass(frozen=True)
+class EmailTriggeredSkill:
+    key: str
+    name: str
+    path: Path
+    address: str
+    body: str
+    model: str
+
+
+def trigger_email_skills(
+    run_claude: RunClaude,
+    *,
+    skills_dir: Path = SKILLS_DIR,
+    emails_dir: Path = EMAILS_DIR,
+    main_context: CodeeMainContext
+) -> None:
+    """Route up to MAX_EMAILS_PER_TICK queued emails to skills by recipient address."""
+    skills_by_address = find_email_triggered_skills(skills_dir)
+    if not skills_by_address:
+        return
+
+    emails_dir.mkdir(parents=True, exist_ok=True)
+    files = sorted(p for p in emails_dir.glob("*.eml") if p.is_file())
+    if not files:
+        return
+
+    for path in files[:MAX_EMAILS_PER_TICK]:
+        try:
+            message = email.message_from_bytes(path.read_bytes())
+        except OSError as exc:
+            print(f"[email_skills] Failed to read {path}: {exc}")
+            continue
+
+        if not _sender_allowed(message):
+            print(
+                f"[email_skills] Sender of {path.name} not in allowed domains; dropping.")
+            path.unlink(missing_ok=True)
+            continue
+
+        skill = _match_skill(message, skills_by_address)
+        if skill is None:
+            print(
+                f"[email_skills] No skill matches recipients of {path.name}; dropping.")
+            path.unlink(missing_ok=True)
+            continue
+
+        print(
+            f"[email_skills] Running {skill.name} for email {path.name} -> {skill.address}")
+        session_id = str(uuid.uuid4())
+        prompt = render_email_prompt(skill.body, message)
+        try:
+            response = run_claude(prompt, session_id, skill.model)
+            print(
+                f"[email_skills] Claude response for {skill.name} ({len(response)} chars)")
+            path.unlink(missing_ok=True)
+            runs_db.record_run(skill.name, "email", session_id,
+                               "succeeded", message=prompt,
+                               main_context=main_context)
+        except Exception as exc:
+            print(
+                f"[email_skills] Failed to run {skill.name} for {path.name}: {exc}")
+            runs_db.record_run(skill.name, "email", session_id, "failed",
+                               error=str(exc)[:500], message=prompt,
+                               main_context=main_context)
+
+
+def find_email_triggered_skills(skills_dir: Path = SKILLS_DIR) -> dict[str, EmailTriggeredSkill]:
+    """Map normalized recipient address -> skill. Duplicate addresses are skipped."""
+    skills_by_address: dict[str, EmailTriggeredSkill] = {}
+    for path in sorted(skills_dir.glob("*/SKILL.md")):
+        try:
+            metadata, body = _parse_skill_file(path.read_text())
+        except OSError as exc:
+            print(f"[email_skills] Failed to read {path}: {exc}")
+            continue
+
+        if metadata.get("x-codee-trigger", "").strip().lower() != "email":
+            continue
+
+        name = metadata.get(
+            "name", path.parent.name).strip() or path.parent.name
+        if metadata.get("disable-model-invocation", "").strip().lower() != "true":
+            print(
+                f"[email_skills] ERROR: {path} declares x-codee-trigger: email but is missing "
+                "disable-model-invocation: true; skipping."
+            )
+            continue
+
+        address = metadata.get("x-codee-email-address", "").strip().lower()
+        if not address:
+            print(
+                f"[email_skills] ERROR: {path} declares x-codee-trigger: email but is missing "
+                "x-codee-email-address; skipping."
+            )
+            continue
+
+        if address in skills_by_address:
+            print(
+                f"[email_skills] WARNING: duplicate x-codee-email-address {address!r} in {path}; "
+                f"already claimed by {skills_by_address[address].path}. Skipping."
+            )
+            continue
+
+        skills_by_address[address] = EmailTriggeredSkill(
+            key=_skill_key(path),
+            name=name,
+            path=path,
+            address=address,
+            body=body.strip(),
+            model=metadata.get("model", "").strip(),
+        )
+    return skills_by_address
+
+
+def _sender_allowed(message: Message) -> bool:
+    _, addr = email.utils.parseaddr(message.get("From", ""))
+    domain = addr.rsplit("@", 1)[-1].lower() if "@" in addr else ""
+    return domain in ALLOWED_SENDER_DOMAINS
+
+
+def _match_skill(
+    message: Message, skills_by_address: dict[str, EmailTriggeredSkill]
+) -> EmailTriggeredSkill | None:
+    for address in _recipients(message):
+        skill = skills_by_address.get(address)
+        if skill is not None:
+            return skill
+    return None
+
+
+def _recipients(message: Message) -> list[str]:
+    """All recipient addresses, normalized to lowercase. Envelope header wins."""
+    headers = ["X-Codee-Rcpt", "Delivered-To", "To", "Cc", "Bcc"]
+    raw = ", ".join(v for h in headers for v in message.get_all(h, []))
+    return [addr.lower() for _, addr in email.utils.getaddresses([raw]) if addr]
+
+
+def render_email_prompt(body: str, message: Message) -> str:
+    content = _format_email(message)
+    if "{CONTENT}" in body:
+        return body.replace("{CONTENT}", content)
+    return f"{body.rstrip()}\n\n{content}"
+
+
+def _format_email(message: Message) -> str:
+    headers = [f"{key}: {value}" for key, value in message.items()]
+    parts = [*headers, "", _body_text(message)]
+    attachments = _save_attachments(message)
+    if attachments:
+        parts.append("")
+        parts.append("Attachments (saved to disk):")
+        parts.extend(f"- {name}: {path}" for name, path in attachments)
+    return "\n".join(parts).strip()
+
+
+def _save_attachments(message: Message) -> list[tuple[str, Path]]:
+    """Write every attachment to a temp dir; return (filename, path) references."""
+    saved: list[tuple[str, Path]] = []
+    dest: Path | None = None
+    for part in message.walk():
+        filename = part.get_filename()
+        if not filename or part.get_content_disposition() == "inline":
+            continue
+        payload = part.get_payload(decode=True)
+        if payload is None:
+            continue
+        if dest is None:
+            dest = Path(tempfile.mkdtemp(prefix="email-attach-"))
+        safe = Path(filename).name  # strip any path components
+        path = dest / safe
+        path.write_bytes(payload)
+        saved.append((safe, path))
+    return saved
+
+
+def _body_text(message: Message) -> str:
+    try:
+        part = message.get_body(preferencelist=("plain", "html"))
+    except (AttributeError, Exception):  # noqa: BLE001 - non-EmailMessage fallback
+        part = None
+    if part is not None:
+        return part.get_content().strip()
+
+    if message.is_multipart():
+        for sub in message.walk():
+            if sub.get_content_type() == "text/plain":
+                return sub.get_payload(decode=True).decode(sub.get_content_charset() or "utf-8", "replace").strip()
+        return ""
+    payload = message.get_payload(decode=True)
+    if payload is None:
+        return message.get_payload()
+    return payload.decode(message.get_content_charset() or "utf-8", "replace").strip()

codee/lib/trigger_issue_skills.py

@@ -0,0 +1,107 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from codee_main_context.context import project_root, skills_dir as default_skills_dir
+
+REPO_ROOT = project_root()
+SKILLS_DIR = default_skills_dir(REPO_ROOT)
+ISSUE_TYPES = ("story", "task")
+
+
+@dataclass(frozen=True)
+class IssueTriggeredSkill:
+    name: str
+    slug: str
+    path: Path
+    statuses: tuple[str, ...]
+    issue_type: str
+    model: str = ""
+
+
+def find_issue_triggered_skills(
+    skills_dir: Path = SKILLS_DIR,
+) -> list[IssueTriggeredSkill]:
+    """Load valid issue-triggered skills from skill frontmatter."""
+    skills: list[IssueTriggeredSkill] = []
+    for path in sorted(skills_dir.glob("*/SKILL.md")):
+        try:
+            metadata = _parse_frontmatter(path.read_text())
+        except (OSError, yaml.YAMLError) as exc:
+            print(f"[issue_skills] Failed to read {path}: {exc}")
+            continue
+
+        if str(metadata.get("x-codee-trigger", "")).strip().lower() != "issue":
+            continue
+        if metadata.get("disable-model-invocation") is not True:
+            print(
+                f"[issue_skills] ERROR: {path} declares x-codee-trigger: issue but is "
+                "missing disable-model-invocation: true; skipping."
+            )
+            continue
+
+        statuses = _status_values(metadata.get("x-codee-issue-status"))
+        if not statuses:
+            print(
+                f"[issue_skills] ERROR: {path} declares x-codee-trigger: issue but is "
+                "missing x-codee-issue-status; skipping."
+            )
+            continue
+
+        raw_issue_type = metadata.get("x-codee-issue-type")
+        issue_type = str(raw_issue_type).strip().lower()
+        if not isinstance(raw_issue_type, str) or issue_type not in ISSUE_TYPES:
+            print(
+                f"[issue_skills] ERROR: {path} declares x-codee-trigger: issue but "
+                "x-codee-issue-type must be story or task; skipping."
+            )
+            continue
+        skills.append(IssueTriggeredSkill(
+            name=str(metadata.get("name", path.parent.name)
+                     ).strip() or path.parent.name,
+            slug=path.parent.name,
+            path=path,
+            statuses=statuses,
+            issue_type=issue_type,
+            model=str(metadata.get("model", "")).strip(),
+        ))
+    return skills
+
+
+def issue_statuses(skills: list[IssueTriggeredSkill]) -> list[str]:
+    """Return unique configured statuses while preserving declaration order."""
+    return list(dict.fromkeys(status for skill in skills for status in skill.statuses))
+
+
+def match_issue_skill(
+    skills: list[IssueTriggeredSkill], status: str, issue_type: str
+) -> IssueTriggeredSkill | None:
+    """Find a skill matching both status and issue type."""
+    normalized_status = status.casefold()
+    normalized_issue_type = issue_type.casefold()
+
+    return next((
+        skill for skill in skills
+        if skill.issue_type.casefold() == normalized_issue_type
+        and any(value.casefold() == normalized_status for value in skill.statuses)
+    ), None)
+
+
+def _parse_frontmatter(contents: str) -> dict[str, Any]:
+    if not contents.startswith("---"):
+        return {}
+    parts = contents.split("---", 2)
+    if len(parts) < 3:
+        return {}
+    parsed = yaml.safe_load(parts[1]) or {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _status_values(value: Any) -> tuple[str, ...]:
+    values = value if isinstance(value, list) else [value]
+    return tuple(
+        status for item in values
+        if item is not None and (status := str(item).strip())
+    )

codee/mail_server.py

@@ -0,0 +1,45 @@
+"""SMTP server that drops each incoming email into temp-emails/ as an .eml file.
+
+The cron tick (trigger_email_skills) picks them up and routes them to skills by
+recipient address. Listens on a non-privileged port; map port 25 -> MAIL_PORT at
+the infra layer (iptables/load balancer), not here.
+"""
+import asyncio
+import os
+import uuid
+from pathlib import Path
+
+from aiosmtpd.controller import Controller
+
+EMAILS_DIR = Path(__file__).parent.parent / "temp-emails"
+MAIL_HOST = os.environ.get("MAIL_HOST", "0.0.0.0")
+MAIL_PORT = int(os.environ.get("MAIL_PORT", "2525"))
+
+
+class FileDropHandler:
+    async def handle_DATA(self, server, session, envelope):
+        EMAILS_DIR.mkdir(parents=True, exist_ok=True)
+        # Prepend envelope recipients so the router matches on the real RCPT TO,
+        # not just the visible To/Cc headers.
+        rcpt = ", ".join(envelope.rcpt_tos)
+        content = f"X-Codee-Rcpt: {rcpt}\r\n".encode() + envelope.content
+        # uuid keeps names unique within a tick; lexical sort ~ arrival order is
+        # good enough for a 3-per-tick drain. ponytail: no timestamp needed.
+        path = EMAILS_DIR / f"{uuid.uuid4().hex}.eml"
+        path.write_bytes(content)
+        print(f"[mail_server] Stored email -> {path.name} for {rcpt}")
+        return "250 Message accepted for delivery"
+
+
+def main() -> None:
+    controller = Controller(FileDropHandler(), hostname=MAIL_HOST, port=MAIL_PORT)
+    controller.start()
+    print(f"[mail_server] Listening on {MAIL_HOST}:{MAIL_PORT}, dropping to {EMAILS_DIR}")
+    try:
+        asyncio.get_event_loop().run_forever()
+    except KeyboardInterrupt:
+        controller.stop()
+
+
+if __name__ == "__main__":
+    main()

codee/start_cli.py

@@ -0,0 +1,98 @@
+import argparse
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from codee_main_context.logging import (
+    configure_logging, enable_debug, get_logger)
+
+from codee.init_cli import (
+    CONFLICT_PATHS, ensure_working_directories, main as init_main)
+
+
+SHUTDOWN_TIMEOUT = 5
+
+log = get_logger(__name__)
+
+
+def _parse_arguments(argv: list[str]) -> tuple[argparse.Namespace, list[str]]:
+    """Pull out codee-start's own flags; everything else goes to the admin UI."""
+    parser = argparse.ArgumentParser(
+        prog="codee-start",
+        epilog="Any other argument (--port, reflex flags) goes to the admin UI.",
+    )
+    parser.add_argument(
+        "-d", "--debug",
+        action="store_true",
+        help="log debug messages from the executor and the admin UI",
+    )
+    parser.add_argument(
+        "--debug-all",
+        action="store_true",
+        help="--debug plus debug output from third-party libraries",
+    )
+    return parser.parse_known_args(argv)
+
+
+def _ensure_initialized() -> None:
+    destination = Path.cwd()
+    if any((destination / path).exists() for path in CONFLICT_PATHS):
+        log.info("Codee is already initialized; skipping codee-init")
+        # codee-init is skipped, but the runtime directories are still needed
+        # here: they may predate this feature, or have been cleaned away.
+        ensure_working_directories(destination)
+        return
+
+    init_main()
+
+
+def _stop_processes(processes: list[subprocess.Popen[bytes]]) -> None:
+    running = [process for process in processes if process.poll() is None]
+    for process in running:
+        process.terminate()
+
+    for process in running:
+        try:
+            process.wait(timeout=SHUTDOWN_TIMEOUT)
+        except subprocess.TimeoutExpired:
+            process.kill()
+            process.wait()
+
+
+def main() -> int:
+    arguments, admin_arguments = _parse_arguments(sys.argv[1:])
+    if arguments.debug or arguments.debug_all:
+        # Exports CODEE_DEBUG, which the subprocesses below inherit.
+        enable_debug(verbose=arguments.debug_all)
+    configure_logging()
+
+    _ensure_initialized()
+
+    commands = [
+        [sys.executable, "-m", "codee.executor"],
+        [sys.executable, "-m", "codee.admin_cli", *admin_arguments],
+    ]
+    processes: list[subprocess.Popen[bytes]] = []
+
+    try:
+        for command in commands:
+            log.debug("starting %s", " ".join(command))
+            processes.append(subprocess.Popen(command))
+
+        while True:
+            for process in processes:
+                return_code = process.poll()
+                if return_code is not None:
+                    log.debug("pid %s exited with %s",
+                              process.pid, return_code)
+                    return return_code
+            time.sleep(0.2)
+    except KeyboardInterrupt:
+        return 130
+    finally:
+        _stop_processes(processes)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

codee/templates/AGENTS.md

@@ -0,0 +1,42 @@
+# Basic
+
+You are Codee, an employee.
+
+# Repository Guidelines
+
+Always read nested `AGENTS.md` and `CLAUDE.md` files in the projects you work with.
+
+## Project Skills
+
+When working with a project, scan its `.claude/skills` directory for relevant skill files. Read and follow applicable skills before starting the task.
+
+- Load debugging guidance for bugs, regressions, failing tests or pipelines, incidents, pasted errors, and reported broken behavior.
+- Load code-review guidance for branch, implementation, and change reviews.
+- Load frontend guidance before UI, UX, styling, browser-validation, user-visible copy, or localization work.
+
+## Development
+
+- Keep changes focused on the requested task.
+- Build and test changed projects before finishing.
+- Do not use unbounded polling loops for CI, deployments, or HTTP readiness. Use a counted timeout and report the final state.
+
+### Repositores
+
+Repositories are located in `repositories` directory. Each repository contains .bare folder with bare git repo.
+
+### Worktrees
+
+Each branch is its own worktree dir under `repositories/<repo>/` — never `git checkout` in place. From `repositories/<repo>` (the `.git` file points git at `.bare`, so no `-C` needed):
+
+```
+git fetch origin                                # get latest
+git worktree add -b <branch> <branch> origin/master  # new branch off master
+git worktree add <branch>                       # check out existing branch
+cd <branch>                                     # this is your working dir; npm install here
+```
+
+`git worktree list` to see them, `git worktree remove <branch>` when done. `git` inside a worktree dir works normally (add/commit/push).
+
+## Temporary Files
+
+Save screenshots, videos, generated configuration, and other temporary artifacts under `./temp` instead of the repository root.

codee/templates/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

codee/templates/skills/aws-sqs-alarm-response/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: aws-sqs-alarm-response
+description: Investigate a production alarm and record the findings in the Issue Tracker.
+disable-model-invocation: true
+x-codee-trigger: aws-sqs
+x-codee-aws-sqs-queue: codee-alarms
+---
+
+# Alarm Response
+
+An alarm was triggered with this content:
+
+{CONTENT}
+
+## Workflow
+
+1. Determine which service or user flow is affected.
+2. Gather relevant logs, metrics, traces, request data, and screenshots.
+3. Identify the likely cause, impact, and any immediate mitigation.
+4. Search the Issue Tracker for an existing open issue about the same problem.
+5. Update the existing issue, or create a new issue with the evidence, impact, and recommended next steps.
+
+For a canary failure, include screenshots from the failed step and inspect the available network trace. If the alarm reports recovery, add that information to the related issue. Ignore confirmed visual false positives.

codee/templates/skills/cron-research-5xx-errors/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: cron-research-5xx-errors
+description: Investigate frequent 5xx errors from the last 24 hours and report the findings.
+disable-model-invocation: true
+x-codee-trigger: cron
+x-codee-cron: 0 0 * * 2-6
+---
+
+# 5xx Error Review
+
+1. Review available gateway, ingress, and application logs for the last 24 hours.
+2. Group 5xx responses by root cause or failing endpoint.
+3. Investigate the three most frequent groups.
+4. For each group, record frequency, impact, evidence, likely cause, and recommended action.
+5. Create one Issue Tracker report, or update an existing open issue when it covers the same errors.
+
+Do not make speculative code changes. Clearly separate confirmed findings from hypotheses.

codee/templates/skills/story-code-reviewer/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: story-code-reviewer
+description: Review a merge request for one subtask in an Issue Tracker story.
+disable-model-invocation: true
+x-codee-trigger: issue
+x-codee-issue-status: ['[AI] CR Needed']
+x-codee-issue-type: story
+argument-hint: <STORY_ID>
+---
+
+# Story Code Reviewer
+
+## Workflow
+
+1. Read the story, acceptance criteria, attachments, comments, and linked subtasks in the Issue Tracker.
+2. Read `story-spec/{STORY_ID}/README.md` when it exists.
+3. Select one subtask with a merge request awaiting review.
+4. Read the project instructions, complete diff, affected files, relevant callers, tests, pipeline results, and unresolved review comments.
+5. Review security, correctness, requirement coverage, performance, tests, error handling, and maintainability.
+6. Post line comments for specific defects and a findings-first merge request review.
+7. Add a concise Issue Tracker comment with the verdict, blocking findings, and verification performed.
+
+## Guidelines
+
+- Review one subtask per invocation.
+- Distinguish blocking defects from optional suggestions.
+- Do not approve changes with unresolved blocking findings.
+- Do not approve a failing pipeline unless the failure is clearly unrelated.
+- Make feedback actionable by naming the observed behavior, expected behavior, and affected location.

codee/templates/skills/story-developer/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: story-developer
+description: Implement one subtask from an Issue Tracker story and submit a merge request.
+disable-model-invocation: true
+x-codee-trigger: issue
+x-codee-issue-status: ['[AI] Ready for development', '[AI] In Progress']
+x-codee-issue-type: story
+argument-hint: <STORY_ID>
+---
+
+# Story Developer
+
+## Workflow
+
+1. Read the story, acceptance criteria, attachments, comments, and subtasks in the Issue Tracker.
+2. Read `story-spec/{STORY_ID}/README.md` and the affected projects' `CLAUDE.md`, `AGENTS.md`, and relevant local skills.
+3. Select one open subtask and inspect any related branches, merge requests, and review comments.
+4. For bugs and regressions, reproduce the problem and identify the root cause before editing code.
+5. Create or reuse a dedicated worktree and branch according to repository conventions.
+6. Install dependencies, implement the smallest complete change, and update the story specification when useful.
+7. Run focused tests, the project build, and any required browser checks.
+8. Review the complete diff for correctness, security, regressions, and missing tests.
+9. Commit, push, and create or update the merge request. Do not merge it unless explicitly requested.
+10. Add a concise Issue Tracker comment describing the change, validation, merge request, and any remaining risk.
+
+For UI work, include screenshots or video evidence when appropriate.

codee/templates/skills/story-planner/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: story-planner
+description: Decompose an Issue Tracker story into actionable subtasks and supporting documentation.
+disable-model-invocation: true
+x-codee-trigger: issue
+x-codee-issue-status: ['[AI] Decomposition Needed']
+x-codee-issue-type: story
+argument-hint: <STORY_ID>
+---
+
+# Story Planner
+
+Decompose an Issue Tracker story into actionable subtasks with supporting documentation.
+
+## Workflow
+
+1. Read the story, acceptance criteria, attachments, comments, and linked issues in the Issue Tracker.
+2. Inspect relevant project instructions and source code to understand the current behavior.
+3. Ask focused questions when requirements, constraints, or expected behavior are unclear. Record the questions in the Issue Tracker and stop until they are answered.
+4. Create a dependency-ordered plan of small, independently implementable subtasks.
+5. Give each subtask a clear title, technical description, acceptance criteria, dependencies, and estimate when useful.
+6. Ensure the subtasks cover every story acceptance criterion, including testing and monitoring work where needed.
+7. Create or update the subtasks in the Issue Tracker using its supported rich-text format.
+8. Write the specification to `story-spec/{STORY_ID}/README.md` using [assets/readme-template.md](assets/readme-template.md). Add `architecture.md` only when architecture or data flow needs explanation.
+9. Post a concise Issue Tracker comment summarizing the plan and linking the subtasks and specification.
+
+## Feedback Rounds
+
+When a plan already exists, re-read new comments and edit the existing subtasks and specification. Create new subtasks only for newly identified work, and avoid duplicates.
+
+## Guidelines
+
+- Prefer subtasks that can be implemented and reviewed independently.
+- Order subtasks by dependency.
+- Keep technical details concrete and acceptance criteria verifiable.