aicortexpy 0.1.0__py3-none-any.whl

aicortexpy/runtime_config.py

@@ -0,0 +1,540 @@
+"""Inject provider-native runtime meta docs (CLAUDE.md / AGENTS.md / GEMINI.md).
+
+Port of server/internal/daemon/execenv/runtime_config.go + project_context.go
++ reply_instructions.go (trimmed but behaviour-aligned).
+"""
+
+from __future__ import annotations
+
+import json
+import platform
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+def _is_windows() -> bool:
+    return sys.platform == "win32" or platform.system().lower() == "windows"
+
+
+@dataclass
+class TaskContextForEnv:
+    agent_id: str = ""
+    agent_name: str = ""
+    agent_instructions: str = ""
+    agent_skills: list[dict[str, Any]] = field(default_factory=list)
+    issue_id: str = ""
+    chat_session_id: str = ""
+    trigger_comment_id: str = ""
+    quick_create_prompt: str = ""
+    autopilot_run_id: str = ""
+    autopilot_id: str = ""
+    autopilot_title: str = ""
+    autopilot_source: str = ""
+    autopilot_description: str = ""
+    autopilot_trigger_payload: str = ""
+    design_mode: str = ""
+    design_system_name: str = ""
+    design_system_content: str = ""
+    design_example_hint: str = ""
+    artifact_entry: str = ""
+    project_id: str = ""
+    project_title: str = ""
+    project_prompt: str = ""
+    project_resources: list[dict[str, Any]] = field(default_factory=list)
+    repos: list[dict[str, Any]] = field(default_factory=list)
+    is_squad_leader: bool = False
+    memory_markdown: str = ""
+
+
+def task_context_from_task(task: Any) -> TaskContextForEnv:
+    agent = task.agent or {}
+    skills = agent.get("skills") if isinstance(agent.get("skills"), list) else []
+    return TaskContextForEnv(
+        agent_id=str(agent.get("id") or ""),
+        agent_name=str(agent.get("name") or ""),
+        agent_instructions=str(agent.get("instructions") or "").strip(),
+        agent_skills=[s for s in skills if isinstance(s, dict)],
+        issue_id=task.issue_id,
+        chat_session_id=task.chat_session_id,
+        trigger_comment_id=task.trigger_comment_id,
+        quick_create_prompt=task.quick_create_prompt,
+        autopilot_run_id=task.autopilot_run_id,
+        autopilot_id=task.autopilot_id,
+        autopilot_title=task.autopilot_title,
+        autopilot_source=task.autopilot_source,
+        autopilot_description=task.autopilot_description,
+        autopilot_trigger_payload=task.autopilot_trigger_payload,
+        design_mode=task.design_mode,
+        design_system_name=task.design_system_name,
+        design_system_content=task.design_system_content,
+        design_example_hint=task.design_example_hint,
+        artifact_entry=task.artifact_entry,
+        project_id=task.project_id,
+        project_title=task.project_title,
+        project_prompt=task.project_prompt,
+        project_resources=list(task.project_resources),
+        repos=list(task.repos),
+        is_squad_leader=bool(
+            getattr(task, "raw", {}).get("is_squad_leader")
+            or getattr(task, "raw", {}).get("isSquadLeader")
+        ),
+        memory_markdown=str(
+            getattr(task, "raw", {}).get("memory_markdown")
+            or getattr(task, "raw", {}).get("memoryMarkdown")
+            or ""
+        ),
+    )
+
+
+def inject_runtime_config(work_dir: Path, provider: str, ctx: TaskContextForEnv) -> str:
+    content = build_meta_skill_content(provider, ctx)
+    target: Path | None
+    if provider == "claude":
+        target = work_dir / "CLAUDE.md"
+    elif provider == "gemini":
+        target = work_dir / "GEMINI.md"
+    elif provider in (
+        "codex",
+        "copilot",
+        "opencode",
+        "openclaw",
+        "hermes",
+        "pi",
+        "cursor",
+        "kimi",
+        "kiro",
+        "dsh",
+    ):
+        target = work_dir / "AGENTS.md"
+    else:
+        return content
+    target.write_text(content, encoding="utf-8")
+    return content
+
+
+def build_comment_reply_instructions(provider: str, issue_id: str, trigger_comment_id: str) -> str:
+    if not trigger_comment_id:
+        return ""
+    if _is_windows():
+        return (
+            "If you decide to reply, post it as a comment — always use the trigger comment ID below, "
+            "do NOT reuse --parent values from previous turns in this session.\n\n"
+            "On Windows, write the reply body to a UTF-8 file with your file-write tool, then post it with "
+            "`--content-file`. Do NOT pipe via `--content-stdin` — Windows PowerShell 5.1 may drop non-ASCII "
+            "as `?`. Do NOT use inline `--content` for agent-authored comments.\n\n"
+            "Use this form:\n\n"
+            f"    aicortex issue comment add {issue_id} --parent {trigger_comment_id} "
+            "--content-file ./reply.md\n\n"
+        )
+    if provider == "codex":
+        return (
+            "If you decide to reply, post it as a comment — always use the trigger comment ID below, "
+            "do NOT reuse --parent values from previous turns in this session.\n\n"
+            "Always use `--content-stdin` with a HEREDOC for agent-authored issue comments.\n\n"
+            "Use this form:\n\n"
+            f"    cat <<'COMMENT' | aicortex issue comment add {issue_id} "
+            f"--parent {trigger_comment_id} --content-stdin\n"
+            "    First paragraph.\n\n"
+            "    Second paragraph.\n"
+            "    COMMENT\n\n"
+        )
+    return (
+        "If you decide to reply, post it as a comment — always use the trigger comment ID below, "
+        "do NOT reuse --parent values from previous turns in this session.\n\n"
+        f"    aicortex issue comment add {issue_id} --parent {trigger_comment_id} --content \"...\"\n\n"
+        "For multi-line bodies prefer `--content-stdin` or `--content-file <path>`.\n"
+    )
+
+
+def build_meta_skill_content(provider: str, ctx: TaskContextForEnv) -> str:
+    parts: list[str] = [
+        "# AICortex Agent Runtime\n\n",
+        "You are a coding agent in the AICortex platform. "
+        "Use the `aicortex` CLI to interact with the platform.\n\n",
+    ]
+
+    if ctx.agent_name or ctx.agent_id:
+        parts.append("## Agent Identity\n\n")
+        if ctx.agent_name:
+            line = f"**You are: {ctx.agent_name}**"
+            if ctx.agent_id:
+                line += f" (ID: `{ctx.agent_id}`)"
+            parts.append(line + "\n\n")
+        if ctx.agent_instructions:
+            parts.append(ctx.agent_instructions + "\n\n")
+    elif ctx.agent_instructions:
+        parts.append("## Agent Identity\n\n")
+        parts.append(ctx.agent_instructions + "\n\n")
+
+    if ctx.design_mode:
+        parts.append(_design_studio_runtime(provider, ctx))
+        return "".join(parts)
+
+    parts.append(_available_commands())
+    if provider == "codex":
+        parts.append(_codex_comment_section())
+
+    if ctx.repos:
+        parts.append(_repos_section(ctx))
+
+    parts.append(_project_context_section(ctx))
+    parts.append(_workflow_section(provider, ctx))
+
+    if ctx.agent_skills:
+        parts.append(_skills_section(provider, ctx.agent_skills))
+
+    if ctx.memory_markdown:
+        parts.append(
+            "## Agent Memory\n\n"
+            "Your working memory is in `.agent_context/memory.md`. "
+            "「记住」defaults to `aicortex memory append` / `write` — never `aicortex graph write`.\n\n"
+        )
+
+    parts.append(_mentions_section())
+    parts.append(_attachments_section())
+    parts.append(_cli_only_section())
+    parts.append(_output_section(ctx))
+    return "".join(parts)
+
+
+def _available_commands() -> str:
+    return (
+        "## Available Commands\n\n"
+        "**Use `--output json` for structured data.** "
+        "Prefer CLI flags over piping through `python`/`jq` (especially on Windows).\n\n"
+        "### Read\n"
+        "- `aicortex issue get <id> --output json`\n"
+        "- `aicortex issue list [--status X] [--assignee-id <uuid>] [--limit N] [--offset N] --output json`\n"
+        "- `aicortex issue comment list <issue-id> [--since <RFC3339>] --output json`\n"
+        "- `aicortex workspace get --output json` / `aicortex workspace members --output json`\n"
+        "- `aicortex agent list --output json` / `aicortex squad list --output json`\n"
+        "- `aicortex repo checkout <url> [--ref <branch-or-sha>]`\n"
+        "- `aicortex attachment download <id> [-o <dir>]`\n"
+        "- `aicortex project get <id> --output json` / `aicortex project resource list <id> --output json`\n\n"
+        "### Write\n"
+        "- `aicortex issue create|update|status|assign ...`\n"
+        "- `aicortex issue comment add <issue-id> [--content \"...\" | --content-stdin | --content-file <path>] "
+        "[--parent <comment-id>]`\n"
+        "  - Windows: prefer `--content-file` for non-ASCII bodies\n"
+        "  - Codex on Unix: prefer `--content-stdin` HEREDOC\n"
+        "- `aicortex issue label add/remove`, `subscriber add/remove`, `label create`\n"
+        "- `aicortex autopilot create|update|trigger|delete ...`\n"
+        "- `aicortex meeting create|advance|summary|close ...`\n\n"
+    )
+
+
+def _codex_comment_section() -> str:
+    if _is_windows():
+        return (
+            "## Codex-Specific Comment Formatting\n\n"
+            "On Windows, **always write the comment body to a UTF-8 file, then post with "
+            "`--content-file <path>`**. Do NOT use `--content-stdin` or inline `--content` "
+            "for agent-authored comments.\n\n"
+        )
+    return (
+        "## Codex-Specific Comment Formatting\n\n"
+        "Always use `--content-stdin` with a HEREDOC for issue comments. "
+        "Never use inline `--content` for agent-authored comments.\n\n"
+    )
+
+
+def _format_project_resource(r: dict[str, Any]) -> str:
+    rtype = str(r.get("resource_type") or r.get("type") or "resource")
+    label = str(r.get("label") or "")
+    ref = r.get("resource_ref") or r.get("ref") or {}
+    if isinstance(ref, str):
+        try:
+            ref = json.loads(ref)
+        except json.JSONDecodeError:
+            ref = {"raw": ref}
+    if not isinstance(ref, dict):
+        ref = {}
+    if rtype == "github_repo":
+        url = str(ref.get("url") or "")
+        out = f"**GitHub repo**: {url}"
+        hint = str(ref.get("default_branch_hint") or "")
+        if hint:
+            out += f" (default branch: `{hint}`)"
+    elif rtype == "local_path":
+        out = f"**Local path**: `{ref.get('path') or ''}`"
+    else:
+        out = f"**{rtype}**: `{json.dumps(ref, ensure_ascii=False)}`"
+    if label:
+        out += f" — {label}"
+    return out
+
+
+def _project_has_local_path(ctx: TaskContextForEnv) -> bool:
+    for r in ctx.project_resources:
+        if str(r.get("resource_type") or r.get("type") or "") == "local_path":
+            return True
+    return False
+
+
+def _has_project_context(ctx: TaskContextForEnv) -> bool:
+    return bool(ctx.project_id or ctx.project_resources or ctx.project_prompt.strip())
+
+
+def _repos_section(ctx: TaskContextForEnv) -> str:
+    parts = ["## Repositories\n\n"]
+    if _project_has_local_path(ctx):
+        parts.append(
+            "Repositories are attached to this project. Your working directory is already "
+            "the configured local path — do **not** run `aicortex repo checkout` for the same codebase.\n\n"
+        )
+    else:
+        parts.append(
+            "Use `aicortex repo checkout <url>` to check out a repository. "
+            "Add `--ref <branch-or-sha>` when needed.\n\n"
+        )
+    for repo in ctx.repos:
+        url = str(repo.get("url") or "")
+        if url:
+            parts.append(f"- {url}\n")
+    parts.append("\n")
+    return "".join(parts)
+
+
+def _project_context_section(ctx: TaskContextForEnv) -> str:
+    if not _has_project_context(ctx):
+        return ""
+    scope = "chat session" if ctx.chat_session_id else (
+        "design session" if ctx.design_mode else "issue"
+    )
+    parts = ["## Project Context\n\n"]
+    if ctx.project_title:
+        parts.append(f"This {scope} belongs to **{ctx.project_title}**.\n\n")
+    if ctx.project_id:
+        parts.append(f"Project working directory (logical): `/workspace/{ctx.project_id}/`\n\n")
+        parts.append(
+            "Use this shared layout:\n\n"
+            "- `docs/` — project materials\n"
+            "- `design/` — design HTML and static mockups\n"
+            "- `app/` — application / development code\n"
+            "- `test/` — tests, fixtures, and reports\n"
+            "- `release/` — build artifacts and release notes\n\n"
+            "Write only in the directory that matches the current task.\n\n"
+        )
+    if ctx.project_resources:
+        parts.append("Project resources (also at `.aicortex/project/resources.json`):\n\n")
+        for r in ctx.project_resources:
+            parts.append(f"- {_format_project_resource(r)}\n")
+        parts.append("\n")
+        if _project_has_local_path(ctx):
+            parts.append(
+                "A `local_path` is configured — do **not** run `aicortex repo checkout` "
+                "for the same codebase.\n\n"
+            )
+    if ctx.project_prompt.strip():
+        title = f" ({ctx.project_title})" if ctx.project_title else ""
+        parts.append(f"### Project Instructions{title}\n\n")
+        parts.append(ctx.project_prompt.strip() + "\n\n")
+        if ctx.project_id:
+            parts.append("Full text is also at `.aicortex/project/instructions.md`.\n\n")
+    return "".join(parts)
+
+
+def _workflow_section(provider: str, ctx: TaskContextForEnv) -> str:
+    parts = ["### Workflow\n\n"]
+    if ctx.chat_session_id:
+        parts.append(
+            "**You are in chat mode.** Respond conversationally. Use the `aicortex` CLI for "
+            "lookups and actions. Keep responses concise.\n\n"
+        )
+        if _project_has_local_path(ctx):
+            parts.append(
+                "- Working directory is already the project's local path; do not checkout the same repo.\n\n"
+            )
+    elif ctx.quick_create_prompt:
+        parts.append(
+            "**This task was triggered by quick-create.** There is NO existing issue.\n\n"
+            "- Run exactly one `aicortex issue create`, then exit.\n"
+            "- Do NOT call `issue get` / `issue status` / `issue comment add` for this run.\n\n"
+        )
+    elif ctx.autopilot_run_id:
+        parts.append(
+            "**This task was triggered by an Autopilot in run-only mode.** "
+            "There is no assigned issue unless instructions say otherwise.\n\n"
+        )
+        parts.append(f"- Autopilot run ID: `{ctx.autopilot_run_id}`\n")
+        if ctx.autopilot_id:
+            parts.append(f"- Autopilot ID: `{ctx.autopilot_id}`\n")
+        if ctx.autopilot_title:
+            parts.append(f"- Autopilot title: {ctx.autopilot_title}\n")
+        if ctx.autopilot_description.strip():
+            parts.append("\nAutopilot instructions:\n\n" + ctx.autopilot_description.strip() + "\n\n")
+        parts.append(
+            "- Complete the autopilot instructions directly.\n"
+            "- Do not run issue get/comment/status unless instructions require it.\n\n"
+        )
+    elif ctx.trigger_comment_id:
+        parts.append(
+            "**This task was triggered by a NEW comment.** Focus on THIS comment.\n\n"
+            f"1. `aicortex issue get {ctx.issue_id} --output json`\n"
+            f"2. `aicortex issue comment list {ctx.issue_id} --output json`\n"
+            f"3. Find triggering comment `{ctx.trigger_comment_id}`\n"
+            "4. Decide whether a reply is warranted — silence is OK for pure acknowledgments.\n"
+            "5. If you reply, decide carefully about `@mention` (default: no mention).\n"
+            "6. "
+        )
+        parts.append(
+            build_comment_reply_instructions(provider, ctx.issue_id, ctx.trigger_comment_id)
+        )
+        parts.append("7. Do NOT change issue status unless the comment asks for it.\n\n")
+    else:
+        parts.append(
+            "You are responsible for managing the issue status throughout your work.\n\n"
+            f"1. `aicortex issue get {ctx.issue_id} --output json`\n"
+            f"2. `aicortex issue comment list {ctx.issue_id} --output json` (mandatory)\n"
+            f"3. `aicortex issue status {ctx.issue_id} in_progress`\n"
+            "4. Follow Skills and Agent Identity to complete the task\n"
+            f"5. Post results: `aicortex issue comment add {ctx.issue_id} ...`\n"
+            f"6. When done: `aicortex issue status {ctx.issue_id} in_review`\n"
+            f"7. If blocked: `aicortex issue status {ctx.issue_id} blocked` + comment\n\n"
+        )
+    return "".join(parts)
+
+
+def _skills_section(provider: str, skills: list[dict[str, Any]]) -> str:
+    parts = ["## Skills\n\n"]
+    if provider in (
+        "claude",
+        "codex",
+        "copilot",
+        "opencode",
+        "openclaw",
+        "pi",
+        "cursor",
+        "kimi",
+        "kiro",
+        "dsh",
+    ):
+        parts.append("You have the following skills installed (discovered automatically):\n\n")
+    else:
+        parts.append(
+            "Detailed skill instructions are in `.agent_context/skills/`. "
+            "Each subdirectory contains a `SKILL.md`.\n\n"
+        )
+    for sk in skills:
+        name = str(sk.get("name") or "").strip()
+        if name:
+            parts.append(f"- **{name}**\n")
+    parts.append("\n")
+    return "".join(parts)
+
+
+def _mentions_section() -> str:
+    return (
+        "## Mentions\n\n"
+        "Mention links are **side-effecting actions**:\n\n"
+        "- `[KEY-123](mention://issue/<issue-id>)` — clickable issue link (safe)\n"
+        "- `[@Name](mention://member/<user-id>)` — notifies a human\n"
+        "- `[@Name](mention://agent/<agent-id>)` — enqueues another agent run\n\n"
+        "Do **not** @mention the agent you are replying to as thanks/sign-off "
+        "(that causes loops). Default to no mention unless escalating or delegating.\n\n"
+    )
+
+
+def _attachments_section() -> str:
+    return (
+        "## Attachments\n\n"
+        "```\naicortex attachment download <attachment-id>\n```\n\n"
+        "Downloads to the current directory (use `-o <dir>` to choose a folder).\n\n"
+    )
+
+
+def _cli_only_section() -> str:
+    return (
+        "## Important: Always Use the `aicortex` CLI\n\n"
+        "All AICortex platform resource access must go through the `aicortex` CLI. "
+        "Do NOT use curl/wget against AICortex URLs.\n\n"
+    )
+
+
+def _output_section(ctx: TaskContextForEnv) -> str:
+    if ctx.autopilot_run_id:
+        return (
+            "## Output\n\n"
+            "Run-only autopilot: final assistant output is captured as the run result. "
+            "Keep it concise.\n"
+        )
+    if ctx.quick_create_prompt:
+        return (
+            "## Output\n\n"
+            "Quick-create: do NOT call `issue comment add`. "
+            "Print `Created <id>: <title>` after successful create.\n"
+        )
+    return (
+        "## Output\n\n"
+        "⚠️ **Final results MUST be delivered via `aicortex issue comment add`.** "
+        "The user does NOT see terminal output or run logs — only issue comments.\n"
+    )
+
+
+def _design_studio_runtime(provider: str, ctx: TaskContextForEnv) -> str:
+    entry = (ctx.artifact_entry or "design/index.html").strip()
+    parts = [
+        "## Design Studio mode\n\n",
+        "You are in **Design Studio**. Deliver a static design artifact under `design/`. "
+        "The user previews files in an iframe — **not** live workspace data.\n\n",
+        f"- Design mode: `{ctx.design_mode}`\n",
+        f"- Primary preview entry: `{entry}`\n\n",
+        "### Hard rules — workspace mutation is forbidden\n\n",
+        "- Do **NOT** run issue/autopilot/meeting mutation commands.\n",
+        "- Use fictional sample data in HTML; do not create real issues.\n",
+        "- Do **NOT** call `aicortex issue comment add`.\n\n",
+        "### Workflow\n\n",
+        "1. Read the design brief / DESIGN.md.\n",
+        "2. Underspecified briefs → emit one `<question-form>` block.\n",
+        f"3. Write `{entry}` (and assets) under `design/`.\n",
+        "4. Tag interactive regions with `data-aicortex-id`.\n",
+        "5. Finish when the artifact renders; keep the summary short.\n\n",
+        "Reference files may already be in `_incoming/`.\n\n",
+    ]
+    if ctx.design_system_content.strip():
+        name = ctx.design_system_name.strip() or "Design System"
+        parts.append(f"Active design system (**{name}**) is in the per-turn prompt.\n\n")
+    if _has_project_context(ctx):
+        parts.append("## Design project context\n\n")
+        if ctx.project_title:
+            parts.append(f"This design session belongs to **{ctx.project_title}**.\n\n")
+        if ctx.project_id:
+            parts.append(
+                f"Project working directory (logical): `/workspace/{ctx.project_id}/`\n"
+                "Write design HTML under `design/`.\n\n"
+            )
+        if ctx.project_resources:
+            parts.append("Project resources (tokens/branding only):\n\n")
+            for r in ctx.project_resources:
+                parts.append(f"- {_format_project_resource(r)}\n")
+            parts.append("\n")
+        if ctx.project_prompt.strip():
+            parts.append(ctx.project_prompt.strip() + "\n\n")
+    if ctx.design_example_hint.strip():
+        parts.append("### Bundled example templates\n\n")
+        parts.append(ctx.design_example_hint.strip() + "\n\n")
+    if ctx.agent_skills:
+        parts.append(_skills_section(provider, ctx.agent_skills))
+    parts.append(
+        "## Output\n\n"
+        "Design Studio: do not post issue comments. "
+        f"Deliverable is `{entry}` in the work directory.\n"
+    )
+    return "".join(parts)
+
+
+def write_project_sidecar(work_dir: Path, ctx: TaskContextForEnv) -> None:
+    """Write `.aicortex/project/` sidecars when project context exists."""
+    if not _has_project_context(ctx):
+        return
+    root = work_dir / ".aicortex" / "project"
+    root.mkdir(parents=True, exist_ok=True)
+    if ctx.project_prompt.strip():
+        (root / "instructions.md").write_text(ctx.project_prompt.strip() + "\n", encoding="utf-8")
+    if ctx.project_resources:
+        (root / "resources.json").write_text(
+            json.dumps(ctx.project_resources, ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+        )