gemcode 0.2.2__py3-none-any.whl

gemcode/query/engine.py

@@ -0,0 +1,55 @@
+"""
+Outer session engine (cf. claude-code `QueryEngine.ts`).
+
+Owns config + runner + one `submit_message` path per user turn.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from google.adk.runners import Runner
+
+from gemcode.config import GemCodeConfig
+from gemcode.invoke import run_turn
+from gemcode.session_runtime import create_runner
+
+
+class GemCodeQueryEngine:
+  """One engine per workspace session; reuse runner for multiple turns."""
+
+  def __init__(
+      self,
+      cfg: GemCodeConfig,
+      *,
+      extra_tools: list | None = None,
+      runner_factory: Callable[[GemCodeConfig, list | None], Runner] | None = None,
+  ) -> None:
+    self.cfg = cfg
+    self._extra_tools = extra_tools
+    self._runner_factory = runner_factory or create_runner
+    self._runner: Runner | None = None
+
+  @property
+  def runner(self) -> Runner:
+    if self._runner is None:
+      self._runner = self._runner_factory(self.cfg, self._extra_tools)
+    return self._runner
+
+  async def submit_message(
+      self,
+      prompt: str,
+      *,
+      user_id: str = "local",
+      session_id: str,
+  ) -> list[Any]:
+    """Run one user message; returns collected ADK events."""
+    return await run_turn(
+        self.runner,
+        user_id=user_id,
+        session_id=session_id,
+        prompt=prompt,
+        max_llm_calls=self.cfg.max_llm_calls,
+        cfg=self.cfg,
+    )

gemcode/query/stop_hooks.py

@@ -0,0 +1,63 @@
+"""
+Post-turn hooks (subset of claude-code `query/stopHooks.ts`).
+
+Runs after a user message finishes streaming through the agent. Optional:
+- `GEMCODE_POST_TURN_HOOK` — path to an executable
+- `.gemcode/hooks/post_turn` — if executable exists (and env not set)
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import subprocess
+from pathlib import Path
+
+from gemcode.audit import append_audit
+from gemcode.config import GemCodeConfig
+
+
+def _is_executable(p: Path) -> bool:
+  try:
+    return p.is_file() and (p.stat().st_mode & stat.S_IXUSR)
+  except OSError:
+    return False
+
+
+def run_post_turn_hooks(
+    cfg: GemCodeConfig,
+    *,
+    session_id: str,
+    user_id: str = "local",
+    timeout_sec: float = 120.0,
+) -> None:
+  """Fire-and-forget-safe: catches errors, logs to audit."""
+  hook = os.environ.get("GEMCODE_POST_TURN_HOOK")
+  if not hook:
+    candidate = cfg.project_root / ".gemcode" / "hooks" / "post_turn"
+    if _is_executable(candidate):
+      hook = str(candidate)
+  if not hook:
+    return
+  path = Path(hook)
+  if not path.is_file():
+    append_audit(cfg.project_root, {"hook": "post_turn", "error": "missing_file", "path": hook})
+    return
+  env = os.environ.copy()
+  env["GEMCODE_PROJECT_ROOT"] = str(cfg.project_root)
+  env["GEMCODE_SESSION_ID"] = session_id
+  env["GEMCODE_USER_ID"] = user_id
+  try:
+    subprocess.run(
+        [str(path)],
+        cwd=str(cfg.project_root),
+        env=env,
+        timeout=timeout_sec,
+        capture_output=True,
+        check=False,
+    )
+    append_audit(cfg.project_root, {"hook": "post_turn", "path": hook, "ok": True})
+  except subprocess.TimeoutExpired:
+    append_audit(cfg.project_root, {"hook": "post_turn", "path": hook, "error": "timeout"})
+  except OSError as e:
+    append_audit(cfg.project_root, {"hook": "post_turn", "path": hook, "error": str(e)})

gemcode/query/token_budget.py

@@ -0,0 +1,109 @@
+"""
+Per-turn token budget continuation (cf. claude-code `query/tokenBudget.ts`).
+
+Used with a *single* agent (no sub-agent id): decide whether to inject a
+continuation nudge vs stop when cumulative turn tokens approach `budget`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+COMPLETION_THRESHOLD = 0.9
+DIMINISHING_THRESHOLD = 500
+
+
+@dataclass
+class BudgetTracker:
+  continuation_count: int = 0
+  last_delta_tokens: int = 0
+  last_global_turn_tokens: int = 0
+  started_at_ms: int = 0
+
+
+def create_budget_tracker() -> BudgetTracker:
+  import time
+
+  return BudgetTracker(started_at_ms=int(time.time() * 1000))
+
+
+@dataclass(frozen=True)
+class _ContinueDecision:
+  action: Literal["continue"]
+  nudge_message: str
+  continuation_count: int
+  pct: int
+  turn_tokens: int
+  budget: int
+
+
+@dataclass(frozen=True)
+class _StopDecision:
+  action: Literal["stop"]
+  completion_event: dict | None
+
+
+TokenBudgetDecision = _ContinueDecision | _StopDecision
+
+
+def get_budget_continuation_message(pct: int, turn_tokens: int, budget: int) -> str:
+  def fmt(n: int) -> str:
+    return f"{n:,}"
+
+  return (
+      f"Stopped at {pct}% of token target ({fmt(turn_tokens)} / {fmt(budget)}). "
+      "Keep working — do not summarize."
+  )
+
+
+def check_token_budget(
+    tracker: BudgetTracker,
+    agent_id: str | None,
+    budget: int | None,
+    global_turn_tokens: int,
+) -> TokenBudgetDecision:
+  """Same control flow as Claude Code `checkTokenBudget`."""
+  if agent_id or budget is None or budget <= 0:
+    return _StopDecision(action="stop", completion_event=None)
+
+  turn_tokens = global_turn_tokens
+  pct = min(100, round((turn_tokens / budget) * 100))
+  delta_since_last = global_turn_tokens - tracker.last_global_turn_tokens
+
+  is_diminishing = (
+      tracker.continuation_count >= 3
+      and delta_since_last < DIMINISHING_THRESHOLD
+      and tracker.last_delta_tokens < DIMINISHING_THRESHOLD
+  )
+
+  if not is_diminishing and turn_tokens < budget * COMPLETION_THRESHOLD:
+    tracker.continuation_count += 1
+    tracker.last_delta_tokens = delta_since_last
+    tracker.last_global_turn_tokens = global_turn_tokens
+    return _ContinueDecision(
+        action="continue",
+        nudge_message=get_budget_continuation_message(pct, turn_tokens, budget),
+        continuation_count=tracker.continuation_count,
+        pct=pct,
+        turn_tokens=turn_tokens,
+        budget=budget,
+    )
+
+  if is_diminishing or tracker.continuation_count > 0:
+    import time
+
+    duration_ms = int(time.time() * 1000) - tracker.started_at_ms
+    return _StopDecision(
+        action="stop",
+        completion_event={
+            "continuation_count": tracker.continuation_count,
+            "pct": pct,
+            "turn_tokens": turn_tokens,
+            "budget": budget,
+            "diminishing_returns": is_diminishing,
+            "duration_ms": duration_ms,
+        },
+    )
+
+  return _StopDecision(action="stop", completion_event=None)

gemcode/query/transitions.py

@@ -0,0 +1,41 @@
+"""
+Transition types for the model↔tool loop (cf. claude-code `query/transitions.ts`).
+
+Terminal: why a turn or invocation ended.
+Continue: why another model iteration was scheduled (conceptual; ADK handles scheduling).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass(frozen=True)
+class Terminal:
+  """The loop exited."""
+
+  reason: Literal[
+      "completed",
+      "blocking_limit",
+      "model_error",
+      "aborted",
+      "prompt_too_long",
+      "stop_hook_prevented",
+      "max_llm_calls",
+      "session_token_limit",
+      "tool_circuit_breaker",
+  ] | str
+  error: object | None = None
+
+
+@dataclass(frozen=True)
+class Continue:
+  """Another iteration would run (documentation / logging; ADK runs internally)."""
+
+  reason: Literal[
+      "tool_use",
+      "reactive_compact_retry",
+      "token_budget_continuation",
+      "queued_command",
+  ] | str

gemcode/session_runtime.py

@@ -0,0 +1,81 @@
+"""
+Session runtime (Claude Code: outer engine ≈ QueryEngine + session store).
+
+- **SqliteSessionService**: durable session + events (like transcript persistence).
+- **Runner**: wires the root agent to the session, equivalent to “submit query → stream events”.
+
+The inner turn loop (model ↔ tools) is implemented inside ADK (analogous to `query.ts` +
+StreamingToolExecutor + runTools orchestration). See `gemcode.query` for transition types,
+token budget helpers, and `GemCodeQueryEngine`.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from google.adk.runners import Runner
+from google.adk.sessions.sqlite_session_service import SqliteSessionService
+
+from gemcode.agent import build_root_agent
+from gemcode.config import GemCodeConfig
+from gemcode.modality_tools import build_extra_tools as build_modality_extra_tools
+from gemcode.memory.embedding_memory_service import EmbeddingFileMemoryService
+from gemcode.memory.file_memory_service import FileMemoryService
+from gemcode.plugins.terminal_hooks_plugin import GemCodeTerminalHooksPlugin
+from gemcode.plugins.tool_recovery_plugin import GemCodeReflectAndRetryToolPlugin
+
+
+def session_db_path(cfg: GemCodeConfig) -> Path:
+  return cfg.project_root / ".gemcode" / "sessions.sqlite"
+
+
+def create_runner(cfg: GemCodeConfig, extra_tools: list | None = None) -> Runner:
+  """Construct Runner + SQLite session service + root LlmAgent."""
+  modality_tools = build_modality_extra_tools(cfg)
+  merged_extra_tools: list | None
+  if extra_tools:
+    merged_extra_tools = [*extra_tools, *modality_tools] if modality_tools else list(extra_tools)
+  else:
+    merged_extra_tools = modality_tools or None
+
+  # Computer-use: ADK ComputerUseToolset backed by our Playwright BrowserComputer.
+  if getattr(cfg, "enable_computer_use", False):
+    headless_env = os.environ.get("GEMCODE_COMPUTER_HEADLESS", "1").lower()
+    headless = headless_env in ("1", "true", "yes", "on")
+    from gemcode.computer_use.browser_computer import BrowserComputer
+    from google.adk.tools.computer_use.computer_use_toolset import ComputerUseToolset
+
+    computer = BrowserComputer(headless=headless)
+    computer_toolset = ComputerUseToolset(computer=computer)
+    merged_extra_tools = list(merged_extra_tools or [])
+    merged_extra_tools.append(computer_toolset)
+
+  agent = build_root_agent(cfg, extra_tools=merged_extra_tools)
+  db = session_db_path(cfg)
+  db.parent.mkdir(parents=True, exist_ok=True)
+  session_service = SqliteSessionService(str(db))
+
+  plugins = [GemCodeTerminalHooksPlugin(cfg)]
+  # Place recovery plugin before terminal hooks so it can influence tool results
+  # during the invocation.
+  if True:
+    plugins.insert(0, GemCodeReflectAndRetryToolPlugin(cfg))
+  memory_service = None
+  if getattr(cfg, "enable_memory", False):
+    mem_path = cfg.project_root / ".gemcode" / "memories.jsonl"
+    if getattr(cfg, "enable_embeddings", False):
+      memory_service = EmbeddingFileMemoryService(
+        mem_path, embeddings_model=getattr(cfg, "embeddings_model", None)
+      )
+    else:
+      memory_service = FileMemoryService(mem_path)
+
+  return Runner(
+      app_name="gemcode",
+      agent=agent,
+      session_service=session_service,
+      plugins=plugins,
+      memory_service=memory_service,
+      auto_create_session=True,
+  )

gemcode/thinking.py

@@ -0,0 +1,136 @@
+"""
+Gemini thinking configuration helper.
+
+Conceptual mapping to Claude Code:
+- thinking is enabled by default (Gemini adaptive/dynamic)
+- only when user explicitly disables or sets a budget/level we override
+- Gemini 3 uses `thinkingLevel`; Gemini 2.5 uses `thinkingBudget`
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from google.genai import types
+
+from gemcode.config import GemCodeConfig
+
+
+def _is_gemini_2_5_series(model_id: str) -> bool:
+  return "2.5" in (model_id or "")
+
+
+def _is_gemini_3_pro(model_id: str) -> bool:
+  # Gemini 3.1 Pro preview doesn't support `thinkingLevel=minimal`.
+  return "3.1-pro" in (model_id or "") or "3-pro" in (model_id or "")
+
+
+def build_thinking_config(cfg: GemCodeConfig) -> Optional[types.ThinkingConfig]:
+  """
+  Returns a `types.ThinkingConfig` to pass to ADK's LlmAgent.generate_content_config.
+
+  If `None` is returned, GemCode lets Gemini use its default dynamic thinking
+  behavior (Claude-like adaptive default).
+  """
+  model_id = getattr(cfg, "model", "") or ""
+  is_25 = _is_gemini_2_5_series(model_id)
+
+  # Claude-like disable semantics:
+  # - Gemini 3 can't fully disable, so approximate with `minimal`.
+  # - Gemini 2.5 can be disabled by setting thinkingBudget=0 (if supported).
+  disable = bool(getattr(cfg, "disable_thinking", False))
+
+  include = bool(getattr(cfg, "include_thought_summaries", False))
+  thinking_level = getattr(cfg, "thinking_level", None)
+  thinking_budget = getattr(cfg, "thinking_budget", None)
+
+  if disable:
+    if is_25:
+      # 2.5 Pro doesn't support fully disabling thinking.
+      if "2.5-pro" in model_id:
+        return types.ThinkingConfig(
+          thinking_budget=512,
+          include_thoughts=include or None,
+        )
+      if "flash-lite" in model_id:
+        return types.ThinkingConfig(
+          thinking_budget=0,
+          include_thoughts=include or None,
+        )
+      return types.ThinkingConfig(
+        thinking_budget=0,
+        include_thoughts=include or None,
+      )
+    # Gemini 3: minimal is the closest available "disable" knob.
+    if _is_gemini_3_pro(model_id):
+      return types.ThinkingConfig(
+        thinking_level="low",
+        include_thoughts=include or None,
+      )
+    return types.ThinkingConfig(
+      thinking_level="minimal",
+      include_thoughts=include or None,
+    )
+
+  # Explicit user overrides take precedence.
+  if thinking_level is not None and not is_25:
+    level = str(thinking_level)
+    if _is_gemini_3_pro(model_id) and level == "minimal":
+      level = "low"
+    return types.ThinkingConfig(
+      thinking_level=level,
+      include_thoughts=include or None,
+    )
+
+  if thinking_budget is not None and is_25:
+    return types.ThinkingConfig(
+      thinking_budget=int(thinking_budget),
+      include_thoughts=include or None,
+    )
+
+  # If the user only wants thought summaries, we can set include_thoughts
+  # without forcing a budget/level.
+  if include:
+    return types.ThinkingConfig(include_thoughts=True)
+
+  # Otherwise: Claude-like auto mapping based on model_mode.
+  mode = (getattr(cfg, "model_mode", "auto") or "auto").lower()
+  if mode == "auto":
+    # Let Gemini choose its dynamic/adaptive thinking.
+    return None
+
+  if not is_25:
+    # Gemini 3 thinkingLevel mapping.
+    if mode == "fast":
+      return types.ThinkingConfig(
+        thinking_level="low" if _is_gemini_3_pro(model_id) else "minimal",
+        include_thoughts=None,
+      )
+    if mode == "balanced":
+      return types.ThinkingConfig(
+        thinking_level="medium",
+        include_thoughts=None,
+      )
+    # quality
+    return types.ThinkingConfig(
+      thinking_level="high",
+      include_thoughts=None,
+    )
+
+  # Gemini 2.5 thinkingBudget mapping.
+  if mode == "fast":
+    if "2.5-pro" in model_id:
+      return types.ThinkingConfig(thinking_budget=512, include_thoughts=None)
+    # flash/flash-preview/flash-lite
+    return types.ThinkingConfig(
+      thinking_budget=0 if "flash-lite" in model_id else 0, include_thoughts=None
+    )
+  if mode == "balanced":
+    if "2.5-pro" in model_id:
+      return types.ThinkingConfig(thinking_budget=4096, include_thoughts=None)
+    return types.ThinkingConfig(thinking_budget=1024, include_thoughts=None)
+
+  # quality
+  # For 2.5 Pro this remains dynamic because disable isn't supported.
+  return types.ThinkingConfig(thinking_budget=-1, include_thoughts=None)
+

gemcode/tool_prompt_manifest.py

@@ -0,0 +1,118 @@
+"""
+Tool system prompt manifest.
+
+Claude Code's "tool system" approach is largely prompt-driven: it provides the
+model a clear, consistent contract about what tools exist, what categories they
+fall into, and what the model is allowed to do with each tool.
+
+GemCode primarily enforces policy via ADK callbacks, but adding a short,
+deterministic tool manifest to the model instruction improves behavior and
+reduces tool-call mistakes.
+
+This module builds a compact manifest string from GemCodeConfig.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Iterable
+
+from gemcode.config import GemCodeConfig
+from gemcode.tool_registry import MUTATING_TOOLS, READ_ONLY_TOOLS, SHELL_TOOLS
+
+
+def _truthy_env(name: str, *, default: bool = False) -> bool:
+  v = os.environ.get(name)
+  if v is None:
+    return default
+  return v.lower() in ("1", "true", "yes", "on")
+
+
+def _cap(s: str, *, max_chars: int) -> str:
+  if len(s) <= max_chars:
+    return s
+  return s[: max_chars - 3] + "..."
+
+
+def _fmt_list(items: Iterable[str]) -> str:
+  xs = [x for x in items if x]
+  xs.sort(key=lambda a: a.lower())
+  return ", ".join(xs)
+
+
+def build_tool_manifest(cfg: GemCodeConfig) -> str | None:
+  """
+  Returns a compact "tool system" section to append to the LLM instruction,
+  or None if disabled.
+  """
+  enabled = _truthy_env("GEMCODE_ENABLE_TOOL_SYSTEM_PROMPT", default=True)
+  if not enabled:
+    return None
+
+  max_chars = int(os.environ.get("GEMCODE_TOOL_SYSTEM_PROMPT_MAX_CHARS", "2400"))
+
+  permission_mode = getattr(cfg, "permission_mode", "default")
+  yes_to_all = bool(getattr(cfg, "yes_to_all", False))
+  interactive_ask_on = bool(getattr(cfg, "interactive_permission_ask", False))
+
+  # Core custom tools.
+  read_only = sorted(READ_ONLY_TOOLS)
+  mutating = sorted(MUTATING_TOOLS)
+  shell = sorted(SHELL_TOOLS)
+
+  # Deep research built-ins are not always safe to combine; we only describe
+  # what's actually enabled by config.
+  deep_research_on = bool(getattr(cfg, "enable_deep_research", False))
+  embeddings_on = bool(getattr(cfg, "enable_embeddings", False))
+  computer_on = bool(getattr(cfg, "enable_computer_use", False))
+
+  maps_grounding_on = bool(getattr(cfg, "enable_maps_grounding", False))
+  tool_comb_mode = getattr(cfg, "tool_combination_mode", None) or "deep_research"
+
+  allow_cmds = getattr(cfg, "allow_commands", None)
+  allow_cmds_str = ""
+  if allow_cmds:
+    allow_cmds_str = _fmt_list(list(allow_cmds))
+
+  # Provide Gemini 3 tool-context circulation contract (best-effort).
+  # We can't guarantee exact tool combination semantics, but the model can
+  # align expectations with GemCode's behavior.
+  gemini3_combination_contract = (
+    f"tool-context-circulation mode is {tool_comb_mode}. "
+    "When enabled, built-in tool results may appear in context for subsequent function tool calls."
+  )
+
+  manifest = f"""## Tool system (GemCode)
+
+Permission policy:
+- permission_mode={permission_mode}
+- user_confirmation_provided(--yes)={yes_to_all}
+- user_in_run_hitl_prompt_enabled={interactive_ask_on}
+
+You may call tools as follows:
+- Read-only tools: {_fmt_list(read_only)}
+- Mutating tools (WRITE/EDIT): {_fmt_list(mutating)}.
+  Only call if user_confirmation_provided(--yes) is true OR user_in_run_hitl_prompt_enabled is true.
+  If neither is true, you must ask the user to re-run with --yes.
+- Shell tool (run_command): {_fmt_list(shell)}.
+  Only use commands from GEMCODE_ALLOW_COMMANDS. Allowed={allow_cmds_str or "<none>"}.
+  Only call if user_confirmation_provided(--yes) is true OR user_in_run_hitl_prompt_enabled is true.
+  Notes:
+  - Prefer `python -m pip ...` (or `python3 -m pip ...`) so installs stay in the active virtualenv.
+  - Do not assume sudo/system package manager access.
+
+Optional capability tools:
+- Deep research built-ins are {'ON' if deep_research_on else 'OFF'}.
+  Active built-ins: google_search, url_context{', google_maps' if deep_research_on and maps_grounding_on else ''}.
+  {gemini3_combination_contract}
+- Embeddings semantic retrieval is {'ON' if embeddings_on else 'OFF'}:
+  semantic_search_files.
+- Computer use is {'ON' if computer_on else 'OFF'}:
+  browser automation actions via Computer Use toolset.
+  Only call if permission_mode != strict AND (user_confirmation_provided(--yes) is true OR user_in_run_hitl_prompt_enabled is true).
+
+If a tool call is rejected by policy, do NOT retry the same mutation without the required user confirmation.
+"""
+
+  return _cap(manifest, max_chars=max_chars)
+

gemcode/tool_registry.py

@@ -0,0 +1,50 @@
+"""
+Tool catalog and concurrency class (Claude Code–style partitioning, clean-room).
+
+In Claude Code, `tools.ts` registers tools and `toolOrchestration.ts` runs
+concurrency-safe batches in parallel and serializes mutating work. Here we
+classify tools so permissions and docs stay aligned; ADK executes calls as the
+model emits them, but we still enforce policy in order (before_tool_callback).
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+# Mirrors "safe read" tools — can be interleaved / parallel-friendly in principle.
+READ_ONLY_TOOLS: frozenset[str] = frozenset(
+  {
+    "read_file",
+    "list_directory",
+    "glob_files",
+    "grep_content",
+  }
+)
+
+# Disk mutations (require --yes / not strict)
+MUTATING_TOOLS: frozenset[str] = frozenset(
+  {
+    "write_file",
+    "search_replace",
+  }
+)
+
+# Subprocess (allowlist enforced inside tool)
+SHELL_TOOLS: frozenset[str] = frozenset({"run_command"})
+
+ToolConcurrency = Literal["parallel_safe", "serial_mutating", "shell"]
+
+
+def concurrency_class(tool_name: str) -> ToolConcurrency:
+  if tool_name in READ_ONLY_TOOLS:
+    return "parallel_safe"
+  if tool_name in MUTATING_TOOLS:
+    return "serial_mutating"
+  if tool_name in SHELL_TOOLS:
+    return "shell"
+  # MCP and unknown tools: treat as serial / cautious
+  return "serial_mutating"
+
+
+def is_mutating(tool_name: str) -> bool:
+  return tool_name in MUTATING_TOOLS

gemcode/tools/__init__.py

@@ -0,0 +1,25 @@
+"""Build function tools for the LlmAgent."""
+
+from __future__ import annotations
+
+from gemcode.config import GemCodeConfig
+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
+
+
+def build_function_tools(cfg: GemCodeConfig) -> list:
+  read_file, list_directory, glob_files = make_filesystem_tools(cfg)
+  grep_content = make_grep_tool(cfg)
+  run_command = make_run_command(cfg)
+  write_file, search_replace = make_edit_tools(cfg)
+  return [
+    read_file,
+    list_directory,
+    glob_files,
+    grep_content,
+    run_command,
+    write_file,
+    search_replace,
+  ]