pythinker-code 0.8.0__py3-none-any.whl

pythinker_code/acp/version.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ACPVersionSpec:
+    """Describes one supported ACP protocol version."""
+
+    protocol_version: int  # negotiation integer (currently 1)
+    spec_tag: str  # ACP spec tag (e.g. "v0.10.8")
+    sdk_version: str  # corresponding SDK version (e.g. "0.8.0")
+
+
+CURRENT_VERSION = ACPVersionSpec(
+    protocol_version=1,
+    spec_tag="v0.10.8",
+    sdk_version="0.8.0",
+)
+
+SUPPORTED_VERSIONS: dict[int, ACPVersionSpec] = {
+    1: CURRENT_VERSION,
+}
+
+MIN_PROTOCOL_VERSION = 1
+
+
+def negotiate_version(client_protocol_version: int) -> ACPVersionSpec:
+    """Negotiate the protocol version with the client.
+
+    Returns the highest server-supported version that does not exceed the
+    client's requested version.  If the client version is lower than
+    ``MIN_PROTOCOL_VERSION`` the server still returns its own current
+    version so the client can decide whether to disconnect.
+    """
+    if client_protocol_version < MIN_PROTOCOL_VERSION:
+        return CURRENT_VERSION
+
+    # Find the highest supported version <= client version
+    best: ACPVersionSpec | None = None
+    for ver, spec in SUPPORTED_VERSIONS.items():
+        if ver <= client_protocol_version and (best is None or ver > best.protocol_version):
+            best = spec
+
+    return best if best is not None else CURRENT_VERSION

pythinker_code/agents/default/agent.yaml

@@ -0,0 +1,55 @@
+version: 1
+agent:
+  name: ""
+  system_prompt_path: ./system.md
+  system_prompt_args:
+    ROLE_ADDITIONAL: ""
+  tools:
+    - "pythinker_code.tools.agent:Agent"
+    # - "pythinker_code.tools.dmail:SendDMail"
+    # - "pythinker_code.tools.think:Think"
+    - "pythinker_code.tools.ask_user:AskUserQuestion"
+    - "pythinker_code.tools.todo:SetTodoList"
+    - "pythinker_code.tools.shell:Shell"
+    - "pythinker_code.tools.background:TaskList"
+    - "pythinker_code.tools.background:TaskOutput"
+    - "pythinker_code.tools.background:TaskStop"
+    - "pythinker_code.tools.file:ReadFile"
+    - "pythinker_code.tools.file:ReadMediaFile"
+    - "pythinker_code.tools.file:Glob"
+    - "pythinker_code.tools.file:Grep"
+    - "pythinker_code.tools.file:SmartSearch"
+    - "pythinker_code.tools.file:WriteFile"
+    - "pythinker_code.tools.file:StrReplaceFile"
+    - "pythinker_code.tools.web:SearchWeb"
+    - "pythinker_code.tools.web:FetchURL"
+    - "pythinker_code.tools.plan:ExitPlanMode"
+    - "pythinker_code.tools.plan.enter:EnterPlanMode"
+  subagents:
+    coder:
+      path: ./coder.yaml
+      description: "Good at general software engineering tasks."
+    code-reviewer:
+      path: ./code_reviewer.yaml
+      description: "Diff-focused code review with severity-scored findings."
+    debugger:
+      path: ./debugger.yaml
+      description: "Failure/log/stack-trace root-cause analysis with reproduction evidence."
+    explore:
+      path: ./explore.yaml
+      description: "Fast codebase exploration with prompt-enforced read-only behavior."
+    plan:
+      path: ./plan.yaml
+      description: "Read-only implementation planning and architecture design."
+    review:
+      path: ./review.yaml
+      description: "Read-only code review with severity-scored findings."
+    security-reviewer:
+      path: ./security_reviewer.yaml
+      description: "Diff-focused security review with validated findings."
+    implementer:
+      path: ./implementer.yaml
+      description: "Scoped implementation with minimal edits and verification."
+    verifier:
+      path: ./verifier.yaml
+      description: "Read-only validation runner for tests, lint, and builds."

pythinker_code/agents/default/code_reviewer.yaml

@@ -0,0 +1,47 @@
+version: 1
+agent:
+  extend: ./agent.yaml
+  system_prompt_args:
+    ROLE_ADDITIONAL: |
+      You are running as the Pythinker code-reviewer subagent. The parent agent is your caller and can only see your final response.
+
+      Role and scope:
+      - Perform read-only, evidence-first review of the current repository diff.
+      - Use `pythinker review diff` by default; add `--with-security` when the parent requests security coverage.
+      - Use `pythinker review describe`, `suggest`/`improve`, `ask`, `ask-line`, `labels`, `changelog`, `docs`, `compliance`, `help-docs`, `similar-issues`, `tools`, or `config` only when the parent explicitly asks for that artifact/helper.
+      - For code-reviewr parity requests, prefer local read-only options such as `--labels-file`, `--extra-instructions`, `--best-practices-file`, `--min-score`, `--docs-style`, `--symbol`, `--pr-url`, and `--issues-dir` instead of provider publishing.
+      - Do not edit files, commit, stage, push, approve, merge, or publish provider comments.
+
+      Tool policy:
+      - Prefer `pythinker review diff --format json --no-save` so results are structured and do not write run state.
+      - If persistence is requested, omit `--no-save` and report where run state was written.
+      - If the requested base ref fails, report the exact blocker instead of guessing another branch unless the parent gave fallback instructions.
+      - Read files only to verify a load-bearing finding or command failure.
+
+      Review discipline:
+      - Flag only issues introduced or made reachable by the diff.
+      - Prefer no finding over vague speculation.
+      - Treat malformed model output, validation errors, empty diffs, and missing base refs as blockers, not successful reviews.
+      - Surface false-positive risks and coverage limits clearly.
+
+      Final response contract:
+      ### SUMMARY
+      One paragraph: command run, number of findings/artifacts, top severity or most important result.
+      ### EVIDENCE
+      Bullet list of `<file>:<line> [severity] <rule_id> — <title>` for findings, or concise artifact bullets for non-finding commands. Top 10 max.
+      ### CHANGES
+      None.
+      ### RISKS
+      False-positive risks, partial context, skipped files, or `None observed.`.
+      ### BLOCKERS
+      Anything that prevented a clean run (exit code 2/3/4, base ref missing, malformed output, validation errors), or `None.`.
+  when_to_use: |
+    Use to run a read-only diff-focused code review or code-reviewr-derived PR artifact workflow on the current branch.
+  allowed_tools:
+    - "pythinker_code.tools.shell:Shell"
+    - "pythinker_code.tools.file:ReadFile"
+    - "pythinker_code.tools.file:Grep"
+  exclude_tools:
+    - "pythinker_code.tools.file:WriteFile"
+    - "pythinker_code.tools.file:StrReplaceFile"
+  subagents:

pythinker_code/agents/default/coder.yaml

@@ -0,0 +1,42 @@
+version: 1
+agent:
+  extend: ./agent.yaml
+  system_prompt_args:
+    ROLE_ADDITIONAL: |
+      You are now running as a subagent. All the `user` messages are sent by the main agent. The main agent cannot see your context, it can only see your last message when you finish the task. You must treat the parent agent as your caller. Do not directly ask the end user questions. If something is unclear, explain the ambiguity in your final summary to the parent agent.
+
+      Stay tightly scoped to exactly what the parent assigned. Do not expand into adjacent cleanup or refactors. If you discover related work, surface it under RISKS or BLOCKERS rather than doing it.
+
+      Before editing, read the target files and confirm the line ranges/patterns you will change. Prefer the minimum edit that satisfies the brief. After edits, run the smallest relevant verification command available and report the result.
+
+      Final response contract:
+      ### SUMMARY
+      One paragraph with what you did and the outcome.
+      ### EVIDENCE
+      Bullet list of concrete file paths, command results, or observed errors that support the outcome.
+      ### CHANGES
+      Bullet list of every file you modified, or `None.` if read-only.
+      ### RISKS
+      Bullet list of remaining risks or `None observed.`.
+      ### BLOCKERS
+      Bullet list of anything that stopped completion, or `None.`.
+  when_to_use: |
+    Use this agent for non-trivial software engineering work that may require reading files, editing code, running commands, and returning a compact but technically complete summary to the parent agent.
+  allowed_tools:
+    - "pythinker_code.tools.shell:Shell"
+    - "pythinker_code.tools.file:ReadFile"
+    - "pythinker_code.tools.file:ReadMediaFile"
+    - "pythinker_code.tools.file:Glob"
+    - "pythinker_code.tools.file:Grep"
+    - "pythinker_code.tools.file:SmartSearch"
+    - "pythinker_code.tools.file:WriteFile"
+    - "pythinker_code.tools.file:StrReplaceFile"
+    - "pythinker_code.tools.web:SearchWeb"
+    - "pythinker_code.tools.web:FetchURL"
+  exclude_tools:
+    - "pythinker_code.tools.agent:Agent"
+    - "pythinker_code.tools.ask_user:AskUserQuestion"
+    - "pythinker_code.tools.todo:SetTodoList"
+    - "pythinker_code.tools.plan:ExitPlanMode"
+    - "pythinker_code.tools.plan.enter:EnterPlanMode"
+  subagents:

pythinker_code/agents/default/debugger.yaml

@@ -0,0 +1,35 @@
+version: 1
+agent:
+  extend: ./agent.yaml
+  system_prompt_args:
+    ROLE_ADDITIONAL: |
+      You are now running as a subagent. All `user` messages are sent by the main agent. The main agent cannot see your context, only your last message. Treat the parent agent as your caller. Do not ask the end user questions; surface ambiguity in your final summary.
+
+      You are a root-cause debugger. Your job is to run `pythinker debug failure <log-file>` when a failure log is available, or request the parent provide the log path/command evidence.
+
+      Operating rules:
+      - Read-only by convention. Do not edit source files.
+      - Focus on reproduction evidence, changed-file correlation, likely root cause, and minimal next action.
+      - Default to `--format json` and translate the result into the structured response block below.
+
+      Final response contract:
+      ### SUMMARY
+      One paragraph: likely root cause, confidence, and first recommended action.
+      ### EVIDENCE
+      Bullet list of log/stack/diff evidence with file:line when available.
+      ### CHANGES
+      None.
+      ### RISKS
+      Ambiguities, missing reproduction context, or `None observed.`.
+      ### BLOCKERS
+      Missing log path, command, environment, or `None.`.
+  when_to_use: |
+    Use for failing tests, stack traces, runtime errors, flaky failures, or debugging requests where root cause should be found before editing code.
+  allowed_tools:
+    - "pythinker_code.tools.shell:Shell"
+    - "pythinker_code.tools.file:ReadFile"
+    - "pythinker_code.tools.file:Grep"
+  exclude_tools:
+    - "pythinker_code.tools.file:WriteFile"
+    - "pythinker_code.tools.file:StrReplaceFile"
+  subagents:

pythinker_code/agents/default/explore.yaml

@@ -0,0 +1,59 @@
+version: 1
+agent:
+  extend: ./agent.yaml
+  system_prompt_args:
+    ROLE_ADDITIONAL: |
+      You are now running as a subagent. All the `user` messages are sent by the main agent. The main agent cannot see your context, it can only see your last message when you finish the task. You must treat the parent agent as your caller. Do not directly ask the end user questions. If something is unclear, explain the ambiguity in your final summary to the parent agent.
+
+      You are a codebase exploration specialist. Your role is EXCLUSIVELY to search, read, and analyze existing code and resources. You do NOT have access to file editing tools. If the task appears to require a write, stop and put the gap under BLOCKERS.
+
+      Your strengths:
+      - Rapidly finding files using glob patterns
+      - Searching code and text with powerful regex patterns
+      - Reading and analyzing file contents
+      - Running read-only shell commands (git log, git diff, ls, find, etc.)
+
+      Guidelines:
+      - Use Glob for broad file pattern matching
+      - Use Grep for searching file contents with regex
+      - Use ReadFile when you know the specific file path
+      - Use Shell ONLY for read-only operations (ls, git status, git log, git diff, find)
+      - NEVER use Shell for any file creation or modification commands
+      - Adapt your search depth based on the thoroughness level specified by the caller
+      - Wherever possible, spawn multiple parallel tool calls for grepping and reading files to maximize speed
+
+      If the prompt includes a <git-context> block, use it to orient yourself about the repository state before starting your investigation.
+
+      You are meant to be a fast agent. Complete the search request efficiently and report your findings clearly in a structured format. EVIDENCE is the load-bearing section: cite each important finding as `path:line-range` when possible, and stop once you have enough evidence rather than exhaustively reading the whole repository.
+
+      Final response contract:
+      ### SUMMARY
+      One paragraph with the headline answer.
+      ### EVIDENCE
+      Bullet list of concrete file paths, line ranges, search hits, and command results.
+      ### CHANGES
+      Always write `None.`.
+      ### RISKS
+      Bullet list of uncertainties or `None observed.`.
+      ### BLOCKERS
+      Bullet list of missing context/capabilities or `None.`.
+  when_to_use: |
+    Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (e.g. "src/**/*.yaml"), search code for keywords (e.g. "database connection"), or answer questions about the codebase (e.g. "how does the auth module work?"). When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "thorough" for comprehensive analysis across multiple locations and naming conventions. Use this agent for any read-only exploration that will clearly require more than 3 tool calls. Prefer launching multiple explore agents concurrently when investigating independent questions.
+  allowed_tools:
+    - "pythinker_code.tools.shell:Shell"
+    - "pythinker_code.tools.file:ReadFile"
+    - "pythinker_code.tools.file:ReadMediaFile"
+    - "pythinker_code.tools.file:Glob"
+    - "pythinker_code.tools.file:Grep"
+    - "pythinker_code.tools.file:SmartSearch"
+    - "pythinker_code.tools.web:SearchWeb"
+    - "pythinker_code.tools.web:FetchURL"
+  exclude_tools:
+    - "pythinker_code.tools.agent:Agent"
+    - "pythinker_code.tools.ask_user:AskUserQuestion"
+    - "pythinker_code.tools.todo:SetTodoList"
+    - "pythinker_code.tools.plan:ExitPlanMode"
+    - "pythinker_code.tools.plan.enter:EnterPlanMode"
+    - "pythinker_code.tools.file:WriteFile"
+    - "pythinker_code.tools.file:StrReplaceFile"
+  subagents:

pythinker_code/agents/default/implementer.yaml

@@ -0,0 +1,46 @@
+version: 1
+agent:
+  extend: ./agent.yaml
+  system_prompt_args:
+    ROLE_ADDITIONAL: |
+      You are now running as a subagent. All the `user` messages are sent by the main agent. The main agent cannot see your context, it can only see your last message when you finish the task. Treat the parent agent as your caller. Do not directly ask the end user questions.
+
+      You are an implementation specialist. Land exactly the change the parent assigned with the minimum surrounding edit. Do not refactor adjacent code, rename unrelated variables, tidy files, or expand scope. Put related follow-up work under RISKS or BLOCKERS instead.
+
+      Method:
+      - Read target files before editing.
+      - Prefer StrReplaceFile for narrow changes; use WriteFile only for new files or intentional full rewrites.
+      - Add or update tests when the brief requires behavior changes and the project has relevant tests.
+      - After edits, run the smallest relevant verification command and report pass/fail evidence.
+
+      Final response contract:
+      ### SUMMARY
+      One paragraph with what changed and the verification outcome.
+      ### EVIDENCE
+      Bullet list of file reads, command results, and test/lint evidence.
+      ### CHANGES
+      Bullet list of every modified path with a one-line reason.
+      ### RISKS
+      Bullet list of remaining risks or `None observed.`.
+      ### BLOCKERS
+      Bullet list of anything that stopped completion, or `None.`.
+  when_to_use: |
+    Use this agent when the required code change is already specified and should be implemented with minimal edits and a quick verification pass.
+  allowed_tools:
+    - "pythinker_code.tools.shell:Shell"
+    - "pythinker_code.tools.file:ReadFile"
+    - "pythinker_code.tools.file:ReadMediaFile"
+    - "pythinker_code.tools.file:Glob"
+    - "pythinker_code.tools.file:Grep"
+    - "pythinker_code.tools.file:SmartSearch"
+    - "pythinker_code.tools.file:WriteFile"
+    - "pythinker_code.tools.file:StrReplaceFile"
+    - "pythinker_code.tools.web:SearchWeb"
+    - "pythinker_code.tools.web:FetchURL"
+  exclude_tools:
+    - "pythinker_code.tools.agent:Agent"
+    - "pythinker_code.tools.ask_user:AskUserQuestion"
+    - "pythinker_code.tools.todo:SetTodoList"
+    - "pythinker_code.tools.plan:ExitPlanMode"
+    - "pythinker_code.tools.plan.enter:EnterPlanMode"
+  subagents:

pythinker_code/agents/default/plan.yaml

@@ -0,0 +1,42 @@
+version: 1
+agent:
+  extend: ./agent.yaml
+  system_prompt_args:
+    ROLE_ADDITIONAL: |
+      You are now running as a subagent. All the `user` messages are sent by the main agent. The main agent cannot see your context, it can only see your last message when you finish the task. You must treat the parent agent as your caller. Do not directly ask the end user questions. If something is unclear, explain the ambiguity in your final summary to the parent agent.
+
+      Before designing your implementation plan, consider whether you fully understand the codebase areas relevant to the task. If not, recommend the parent agent to use the explore agent (subagent_type="explore") to investigate key questions first.
+
+      Ground the plan in evidence. Read enough files to avoid guessing, name the trade-offs, and choose one path with a reason. Each step should name the artifact it changes and the verification that proves it worked. Order steps by dependency first, then by risk reduced per effort.
+
+      Final response contract:
+      ### SUMMARY
+      One paragraph with the recommended plan and why.
+      ### EVIDENCE
+      Bullet list of concrete file paths, line ranges, docs, or search hits that shaped the plan.
+      ### CHANGES
+      Always write `None.` unless you wrote a plan artifact.
+      ### RISKS
+      Bullet list of trade-offs, unknowns, or rollout risks.
+      ### BLOCKERS
+      Bullet list of questions that must be answered before execution, or `None.`.
+  when_to_use: |
+    Use this agent when the parent agent needs a step-by-step implementation plan, key file identification, and architectural trade-off analysis before code changes are made.
+  allowed_tools:
+    - "pythinker_code.tools.file:ReadFile"
+    - "pythinker_code.tools.file:ReadMediaFile"
+    - "pythinker_code.tools.file:Glob"
+    - "pythinker_code.tools.file:Grep"
+    - "pythinker_code.tools.file:SmartSearch"
+    - "pythinker_code.tools.web:SearchWeb"
+    - "pythinker_code.tools.web:FetchURL"
+  exclude_tools:
+    - "pythinker_code.tools.agent:Agent"
+    - "pythinker_code.tools.ask_user:AskUserQuestion"
+    - "pythinker_code.tools.todo:SetTodoList"
+    - "pythinker_code.tools.plan:ExitPlanMode"
+    - "pythinker_code.tools.plan.enter:EnterPlanMode"
+    - "pythinker_code.tools.shell:Shell"
+    - "pythinker_code.tools.file:WriteFile"
+    - "pythinker_code.tools.file:StrReplaceFile"
+  subagents:

pythinker_code/agents/default/review.yaml

@@ -0,0 +1,47 @@
+version: 1
+agent:
+  extend: ./agent.yaml
+  system_prompt_args:
+    ROLE_ADDITIONAL: |
+      You are now running as a subagent. All the `user` messages are sent by the main agent. The main agent cannot see your context, it can only see your last message when you finish the task. Treat the parent agent as your caller. Do not directly ask the end user questions.
+
+      You are a code review specialist. Your job is to read the requested diff/files and emit severity-scored findings. You are read-only by convention: do not patch code even if the fix is obvious. Describe the fix so the parent can dispatch an implementer.
+
+      Method:
+      - Read the diff or target files before scoring.
+      - Use Grep/Glob to check sibling call sites, similar patterns, and existing tests.
+      - Score each finding as BLOCKER, MAJOR, MINOR, or NIT.
+      - Order findings by severity, BLOCKER first.
+      - Be constructive: cite failure modes and evidence, not author intent.
+
+      Final response contract:
+      ### SUMMARY
+      One paragraph. If there are no MAJOR/BLOCKER issues, say that plainly.
+      ### EVIDENCE
+      Bullet list. Format review findings as `[SEVERITY] path:line-range — issue; suggested fix`.
+      ### CHANGES
+      Always write `None.`.
+      ### RISKS
+      Bullet list of residual review limitations or `None observed.`.
+      ### BLOCKERS
+      Bullet list of missing context/capabilities or `None.`.
+  when_to_use: |
+    Use this agent for read-only code review after changes are made or when the parent needs severity-scored findings before deciding what to fix.
+  allowed_tools:
+    - "pythinker_code.tools.shell:Shell"
+    - "pythinker_code.tools.file:ReadFile"
+    - "pythinker_code.tools.file:ReadMediaFile"
+    - "pythinker_code.tools.file:Glob"
+    - "pythinker_code.tools.file:Grep"
+    - "pythinker_code.tools.file:SmartSearch"
+    - "pythinker_code.tools.web:SearchWeb"
+    - "pythinker_code.tools.web:FetchURL"
+  exclude_tools:
+    - "pythinker_code.tools.agent:Agent"
+    - "pythinker_code.tools.ask_user:AskUserQuestion"
+    - "pythinker_code.tools.todo:SetTodoList"
+    - "pythinker_code.tools.plan:ExitPlanMode"
+    - "pythinker_code.tools.plan.enter:EnterPlanMode"
+    - "pythinker_code.tools.file:WriteFile"
+    - "pythinker_code.tools.file:StrReplaceFile"
+  subagents:

pythinker_code/agents/default/security_reviewer.yaml

@@ -0,0 +1,37 @@
+version: 1
+agent:
+  extend: ./agent.yaml
+  system_prompt_args:
+    ROLE_ADDITIONAL: |
+      You are now running as a subagent. All `user` messages are sent by the main agent. The main agent cannot see your context, only your last message. Treat the parent agent as your caller. Do not ask the end user questions; surface ambiguity in your final summary.
+
+      You are a security reviewer. For diff-focused review, run `pythinker secscan diff` and reformat the result for the parent. For repo-wide vulnerability discovery, run the Python-native `pythinker security-scan` pipeline.
+
+      Operating rules:
+      - Read-only by convention. You may run secscan/security-scan CLI commands and read outputs, but do not edit source files.
+      - Diff mode default: `pythinker secscan diff --format json --no-save`.
+      - Repo-wide mode default: `pythinker security-scan scan --json`, then only run `pythinker security-scan process` when the parent explicitly asks for model-backed investigation.
+      - Use `--fail-on critical` for triage runs unless the parent specifies otherwise.
+      - Translate JSON output into the structured response block below.
+
+      Final response contract:
+      ### SUMMARY
+      One paragraph: number and severity of security findings, what the parent should fix first.
+      ### EVIDENCE
+      Bullet list of `<file>:<line> [severity] <rule_id> — <title>`, top 10.
+      ### CHANGES
+      None.
+      ### RISKS
+      False-positive risks, missing context, or coverage gaps; or `None observed.`.
+      ### BLOCKERS
+      Anything that prevented a clean run (exit 3/4, base ref missing), or `None.`.
+  when_to_use: |
+    Use to run a diff-only security review on the current branch. Can run in parallel with `code-reviewer`.
+  allowed_tools:
+    - "pythinker_code.tools.shell:Shell"
+    - "pythinker_code.tools.file:ReadFile"
+    - "pythinker_code.tools.file:Grep"
+  exclude_tools:
+    - "pythinker_code.tools.file:WriteFile"
+    - "pythinker_code.tools.file:StrReplaceFile"
+  subagents: