gemcode 0.3.17__tar.gz → 0.3.18__tar.gz

{gemcode-0.3.17/src/gemcode.egg-info → gemcode-0.3.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gemcode
-Version: 0.3.17
+Version: 0.3.18
 Summary: Local-first coding agent on Google Gemini + ADK
 Author: GemCode Contributors
 License:                                  Apache License

{gemcode-0.3.17 → gemcode-0.3.18}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gemcode"
-version = "0.3.17"
+version = "0.3.18"
 description = "Local-first coding agent on Google Gemini + ADK"
 readme = "README.md"
 requires-python = ">=3.11"

{gemcode-0.3.17 → gemcode-0.3.18}/src/gemcode/agent.py

@@ -151,10 +151,24 @@ You have native deep thinking capability — use it actively:
   - `web_fetch("https://registry.npmjs.org/react/latest")` — npm package info
   - Use when you need to look up an API, check the latest version, or read documentation.
 
-### Planning
+### Reasoning and planning
+- **`think`** — private reasoning scratchpad. Write your analysis, plan, or hypothesis here before acting. Not shown to the user. Use before:
+  - A complex multi-file edit or refactor
+  - A debugging session where you need to trace logic before touching code
+  - Any destructive action (delete, force-push) — think first
+  - Choosing between approaches with real trade-offs
+
 - **`todo_write`** — track work items. Use for any task with 3+ steps.
   - Create at task start, mark completed as you finish, merge updates.
 
+- **`run_subtask`** — spawn an isolated sub-agent with its own fresh context window.
+  - The sub-agent has the same tools (bash, read_file, grep, etc.) but starts from scratch.
+  - Use when a task would bloat your context too much: e.g. "read all 40 test files and find patterns"
+  - Use to parallelize: issue multiple `run_subtask` calls in one turn for concurrent exploration
+  - Use for verification passes: "check all files I edited for consistency and syntax errors"
+  - Always give the sub-agent enough context to operate independently.
+  - End your task prompt with "Summarise your findings clearly." so the result is useful.
+
 ## Multi-step task execution
 One user message = many model↔tool rounds (up to 256 LLM calls by default). This is intentional — you are expected to do complete tasks autonomously.
 
@@ -174,8 +188,25 @@ Issue independent tool calls in the same turn when outputs don't depend on each
 - Reading multiple files simultaneously ✓
 - Grepping for different patterns at once ✓
 - `list_directory` + `glob_files` in parallel ✓
+- Multiple `run_subtask` calls in one turn for parallel sub-agent exploration ✓
 Sequential: when step B needs step A's result.
 
+## Sub-agent delegation (orchestrator-worker pattern)
+Use `run_subtask` when the work is better done in an isolated context:
+- **Context preservation**: offload reading/analysing large areas of the codebase so your own context stays clean and focused on the high-level task.
+- **Parallel exploration**: launch multiple sub-agents simultaneously to research different subsystems ("analyse auth module", "analyse payment module") then synthesise.
+- **Verification**: after completing work, spawn a sub-agent to review it independently — "verify the changes in src/ are syntactically correct and don't break imports."
+- **Deep research**: when you need to exhaustively search something (50+ files, long documentation pages) delegate it rather than polluting the main conversation.
+
+The sub-agent inherits your permission settings and returns its final text as `result`. Treat it as a trusted colleague returning a written summary.
+
+## Evaluator-optimizer loop
+For tasks where quality matters:
+1. Complete the task (execute tools, write code, run commands)
+2. Spawn a verification `run_subtask` or use `bash` to run tests/lint
+3. If verification fails, read the error, fix, re-verify
+4. Report done only when verified
+
 ## Error recovery
 - **Test/build failures**: read the full error, identify the exact line, fix, re-run.
 - **Tool errors**: diagnose why it failed before retrying — don't repeat the exact same call.
@@ -207,9 +238,25 @@ All file tools use paths **relative to the project root** (where GemCode was sta
   return base
 
 
-def build_root_agent(cfg: GemCodeConfig, extra_tools: list | None = None) -> LlmAgent:
-  """Create the root LlmAgent with tools and callbacks (no Runner)."""
-  tools = build_function_tools(cfg)
+def build_root_agent(
+  cfg: GemCodeConfig,
+  extra_tools: list | None = None,
+  *,
+  _tools: list | None = None,
+) -> LlmAgent:
+  """Create the root LlmAgent with tools and callbacks (no Runner).
+
+  Args:
+    cfg: Runtime configuration.
+    extra_tools: Additional tools to append (e.g. modality tools from session_runtime).
+    _tools: Override the entire tool list (used by run_subtask sub-agents to pass a
+            pre-built list that excludes run_subtask itself, preventing recursion).
+            When set, build_function_tools() is NOT called.
+  """
+  if _tools is not None:
+    tools = list(_tools)
+  else:
+    tools = build_function_tools(cfg)
   if getattr(cfg, "enable_memory", False):
     # ADK preload_memory injects retrieved memories into the next llm_request.
     from google.adk.tools import preload_memory

{gemcode-0.3.17 → gemcode-0.3.18}/src/gemcode/tool_prompt_manifest.py

@@ -108,7 +108,10 @@ Permission policy:
 - session_sticky_hitl={sticky_hitl}: when true, after the user approves **one** tool in this session, further mutating/shell tools may run without re-prompting (set GEMCODE_HITL_STICKY_SESSION=0 to prompt every time).
 
 You may call tools as follows:
-- Session planning: {_fmt_list(planning)}. In-memory task list for this session (no disk writes). Use for non-trivial multi-step work; set merge=true to upsert by id.
+- Session planning / reasoning: {_fmt_list(planning)}.
+  - `todo_write`: in-memory task list (no disk writes). Use for non-trivial multi-step work; merge=true to upsert by id.
+  - `think`: private scratchpad — write reasoning/analysis before risky or complex actions. Not shown to user.
+  - `run_subtask(task, context)`: spawn an isolated sub-agent to handle context-heavy work in parallel or in sequence. Sub-agent inherits your permissions and returns its final text as `result`. Exclude run_subtask from sub-agent by design (no recursion).
 - Read-only tools: {_fmt_list(read_only)}.
   Use these proactively to locate files and code before asking the user for paths.
 - Mutating tools (WRITE/EDIT/DELETE): {_fmt_list(mutating)}.

{gemcode-0.3.17 → gemcode-0.3.18}/src/gemcode/tool_registry.py

@@ -36,7 +36,9 @@ MUTATING_TOOLS: frozenset[str] = frozenset(
 SHELL_TOOLS: frozenset[str] = frozenset({"run_command", "bash"})
 
 # Session planning only (no disk / shell; no extra permission)
-PLANNING_TOOLS: frozenset[str] = frozenset({"todo_write"})
+# think — in-context reasoning scratchpad (no-op, no side effects)
+# run_subtask — spawns a sub-agent; inherits parent permission settings
+PLANNING_TOOLS: frozenset[str] = frozenset({"todo_write", "think", "run_subtask"})
 
 ToolConcurrency = Literal["parallel_safe", "serial_mutating", "shell"]
 

{gemcode-0.3.17 → gemcode-0.3.18}/src/gemcode/tools/__init__.py

@@ -8,20 +8,25 @@ from gemcode.tools.edit import make_edit_tools
 from gemcode.tools.filesystem import make_filesystem_tools
 from gemcode.tools.search import make_grep_tool
 from gemcode.tools.shell import make_run_command
+from gemcode.tools.subtask import make_run_subtask_tool
+from gemcode.tools.think import make_think_tool
 from gemcode.tools.todo import make_todo_tool
 from gemcode.tools.web import make_web_fetch_tool
 
 
-def build_function_tools(cfg: GemCodeConfig) -> list:
+def build_function_tools(cfg: GemCodeConfig, *, include_subtask: bool = True) -> list:
   read_file, list_directory, glob_files, delete_file, move_file = make_filesystem_tools(cfg)
   grep_content = make_grep_tool(cfg)
   run_command = make_run_command(cfg)
   bash = make_bash_tool(cfg)
   write_file, search_replace = make_edit_tools(cfg)
   todo_write = make_todo_tool(cfg)
+  think = make_think_tool()
   web_fetch = make_web_fetch_tool()
-  return [
+
+  tools = [
     todo_write,
+    think,
     read_file,
     list_directory,
     glob_files,
@@ -34,3 +39,9 @@ def build_function_tools(cfg: GemCodeConfig) -> list:
     delete_file,
     web_fetch,
   ]
+
+  # run_subtask is excluded when building sub-agent tools (prevents recursion).
+  if include_subtask:
+    tools.append(make_run_subtask_tool(cfg))
+
+  return tools

gemcode-0.3.18/src/gemcode/tools/subtask.py

@@ -0,0 +1,137 @@
+"""
+Sub-agent tool — spawn an isolated focused agent for context-heavy tasks.
+
+Analogous to OpenClaude's AgentTool / AI SDK's ToolLoopAgent subagent pattern.
+
+Key insight (from AI SDK docs "Subagents"):
+  "Some tasks require exploring large amounts of information — reading files,
+   searching codebases, or researching topics. Running these in the main agent
+   consumes context quickly, making the agent less coherent over time.
+   With subagents, you can spin up a dedicated agent that uses hundreds of
+   thousands of tokens and have it return only a focused summary."
+
+The sub-agent:
+- Gets the same tools as the parent (read_file, bash, grep, etc.) EXCEPT
+  run_subtask itself (prevents infinite recursion).
+- Uses an in-memory session (no DB writes, fully isolated).
+- Respects the same permission settings (yes_to_all, permission_mode) as the parent.
+- Is depth-capped (max 48 LLM calls) to prevent runaway cost.
+"""
+
+from __future__ import annotations
+
+from gemcode.config import GemCodeConfig
+
+
+def make_run_subtask_tool(cfg: GemCodeConfig):
+    async def run_subtask(task: str, context: str = "") -> dict:
+        """
+        Spawn an isolated sub-agent to complete a focused, self-contained task.
+
+        The sub-agent starts with a fresh context window — it does NOT inherit this
+        conversation's history. It has access to all the same tools (read_file, bash,
+        grep_content, web_fetch, etc.) and returns its final response as `result`.
+
+        Use when:
+        - Exploring a large codebase section that would bloat your context
+          ("read all 40 test files and summarise what each group tests")
+        - Running deep analysis in parallel — issue multiple run_subtask calls
+          in the same turn for genuine parallel execution
+        - Delegating a focused research or investigation task while staying
+          high-level yourself
+        - Getting a verification or review pass on your own changes
+          ("check my edits in src/ for syntax errors and consistency")
+        - Any task that requires 10+ file reads or multiple bash commands but
+          whose output can be summarised in a paragraph
+
+        The sub-agent reasons and acts like a full Gemini coding agent.
+        Give it a clear, self-contained task — include all context it needs
+        since it cannot see this conversation.
+
+        Tip: end your task description with "Summarise your findings clearly
+        since your full output will be returned to the main agent."
+
+        Args:
+            task: Clear, self-contained description of what to do.
+            context: Extra context the sub-agent needs (file paths, relevant
+                     code snippets, constraints, acceptance criteria).
+        """
+        import uuid
+
+        try:
+            from google.adk.runners import Runner
+            from google.adk.sessions.in_memory_session_service import (
+                InMemorySessionService,
+            )
+        except ImportError:
+            try:
+                from google.adk.runners import Runner
+                from google.adk.sessions import InMemorySessionService
+            except ImportError:
+                return {"error": "google-adk not available for sub-agent"}
+
+        from gemcode.agent import build_root_agent
+        from gemcode.tools import build_function_tools
+        from gemcode.invoke import run_turn
+
+        # Build the sub-agent tool set WITHOUT run_subtask (no recursion).
+        sub_tools = build_function_tools(cfg, include_subtask=False)
+
+        # Build a standalone LlmAgent with the limited tool set.
+        sub_agent = build_root_agent(cfg, _tools=sub_tools)
+
+        # Isolated in-memory session — never writes to the parent SQLite DB.
+        sub_runner = Runner(
+            app_name="gemcode_sub",
+            agent=sub_agent,
+            session_service=InMemorySessionService(),
+        )
+        sub_session_id = str(uuid.uuid4())
+
+        # Compose the sub-agent prompt.
+        prompt = task.strip()
+        if context and context.strip():
+            prompt = f"{task.strip()}\n\nAdditional context:\n{context.strip()}"
+
+        # Cap sub-agent depth to avoid runaway API cost.
+        sub_max_calls = min(int(cfg.max_llm_calls or 48), 48)
+
+        try:
+            events = await run_turn(
+                sub_runner,
+                user_id="local",
+                session_id=sub_session_id,
+                prompt=prompt,
+                max_llm_calls=sub_max_calls,
+                cfg=cfg,
+            )
+        except Exception as e:
+            return {"error": f"Sub-agent error: {type(e).__name__}: {e}"}
+
+        # Extract only non-thinking text parts from the sub-agent's output.
+        parts: list[str] = []
+        for ev in events:
+            try:
+                if not ev.content or not ev.content.parts:
+                    continue
+                if getattr(ev, "author", None) == "user":
+                    continue
+                for part in ev.content.parts:
+                    t = getattr(part, "text", None)
+                    is_thought = getattr(part, "thought", None)
+                    if isinstance(t, str) and t.strip() and not is_thought:
+                        parts.append(t)
+            except Exception:
+                continue
+
+        result_text = "".join(parts).strip()
+        if not result_text:
+            result_text = (
+                "(Sub-agent completed the task but produced no text output. "
+                "It may have only called tools. Consider a more explicit task "
+                "that asks the sub-agent to summarise its findings.)"
+            )
+
+        return {"result": result_text}
+
+    return run_subtask

gemcode-0.3.18/src/gemcode/tools/think.py

@@ -0,0 +1,41 @@
+"""
+Think tool — structured reasoning scratchpad before acting.
+
+Inspired by Anthropic's documented "think" tool pattern:
+https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking
+
+Even though Gemini 2.5 has native dynamic thinking, an explicit think() call
+improves quality on hard tasks because:
+1. It forces a structured reasoning checkpoint before irreversible actions.
+2. The written thought persists in the conversation history so later tool calls
+   can reference it.
+3. It creates a visible chain-of-reasoning the model can revise.
+"""
+
+from __future__ import annotations
+
+
+def make_think_tool():
+    def think(thought: str) -> dict:
+        """
+        Write out your reasoning, plan, or analysis before taking action.
+
+        This is a private scratchpad — the content is NOT shown to the user.
+        Use it when you need to think clearly before executing tools:
+
+        - Planning a multi-step edit: map out what files to touch and in what order
+        - Debugging an error: trace the execution path before deciding on a fix
+        - Weighing approaches: compare trade-offs before committing to one
+        - Verifying understanding: articulate your model of the code before editing
+        - Decomposing a complex task: break it into concrete sub-steps
+        - After reading multiple files: synthesise before writing
+
+        Call think() BEFORE a sequence of tool calls, especially before destructive
+        or irreversible actions (deletes, overwrites, force-pushes).
+
+        The return value is intentionally empty — the value is in the reasoning
+        itself being part of the conversation context.
+        """
+        return {"ok": True}
+
+    return think

{gemcode-0.3.17 → gemcode-0.3.18/src/gemcode.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gemcode
-Version: 0.3.17
+Version: 0.3.18
 Summary: Local-first coding agent on Google Gemini + ADK
 Author: GemCode Contributors
 License:                                  Apache License

{gemcode-0.3.17 → gemcode-0.3.18}/src/gemcode.egg-info/SOURCES.txt

@@ -69,6 +69,8 @@ src/gemcode/tools/filesystem.py
 src/gemcode/tools/search.py
 src/gemcode/tools/shell.py
 src/gemcode/tools/shell_gate.py
+src/gemcode/tools/subtask.py
+src/gemcode/tools/think.py
 src/gemcode/tools/todo.py
 src/gemcode/tools/web.py
 src/gemcode/tui/input_handler.py