gemcode 0.3.75__py3-none-any.whl → 0.3.77__py3-none-any.whl

gemcode/agent.py

@@ -1,5 +1,5 @@
 """
-Root LlmAgent definition (Claude Code: agent config + tool list, analogous to tools.ts + prompts).
+Root LlmAgent definition (agent config + tool list, analogous to a tools registry + prompts).
 
 See `session_runtime.py` for Runner/session wiring (outer layer).
 See `tool_registry.py` for tool categories (read vs mutating vs shell).
@@ -27,6 +27,9 @@ from gemcode.limits import make_before_model_limits_callback, make_before_model_
 from gemcode.thinking import build_thinking_config
 from gemcode.tools import build_function_tools
 from gemcode.tool_prompt_manifest import build_tool_manifest
+from gemcode.skills import build_skill_manifest_text
+from gemcode.output_styles import build_output_style_section
+from gemcode.rules import build_rules_section
 
 
 def build_global_instruction() -> str:
@@ -61,7 +64,7 @@ def _chain_before_model_callbacks(*callbacks):
 
 def _load_gemini_md(project_root: Path) -> str:
   """
-  Load GEMINI.md / .gemcode/NOTES.md from a Claude Code–style hierarchy.
+  Load GEMINI.md / .gemcode/NOTES.md from a interactive CLI–style hierarchy.
 
   Priority (later entries override earlier ones, all are concatenated):
     1. ~/.gemcode/GEMINI.md           — user-global instructions (all projects)
@@ -86,7 +89,7 @@ def _load_gemini_md(project_root: Path) -> str:
       return ""
     try:
       raw = p.read_text(encoding="utf-8", errors="replace")[:_FILE_CAP]
-      # Strip HTML comments (like Claude Code does — saves tokens)
+      # Strip HTML comments (saves tokens)
       return _COMMENT_RE.sub("", raw).strip()
     except OSError:
       return ""
@@ -137,7 +140,7 @@ def _get_git_context(root) -> str:
   """
   Run a quick git snapshot at session start — branch, recent commits, diff-stat.
   Returns a formatted string or empty string if not a git repo.
-  Mirrors OpenClaude's getGitStatus() pattern.
+  Mirrors Reference UI getGitStatus() pattern.
   """
   import subprocess
   import shutil
@@ -229,18 +232,18 @@ def _build_runtime_facts(cfg: GemCodeConfig) -> str:
   if max_session_tokens:
     budget_line += f" · max_session_tokens={max_session_tokens:,}"
 
-  # ── Kairos ────────────────────────────────────────────────────────────────
-  # The user can run `gemcode kairos -C <project>` in a separate terminal to
+  # ── Kaira ────────────────────────────────────────────────────────────────
+  # The user can run `gemcode kaira -C <project>` in a separate terminal to
   # launch a long-lived scheduler. Jobs submitted to it run concurrently with
   # the current session. This is useful for background / parallel heavy work.
-  kairos_section = (
-    "- **Kairos background scheduler** — `gemcode kairos -C <project>` launches a "
+  kaira_section = (
+    "- **Kaira background scheduler** — `gemcode kaira -C <project>` launches a "
     "long-lived daemon that reads prompts from stdin and runs each as an isolated job "
-    "(up to N concurrently). Each job gets `kairos_sleep_ms(ms)` and "
-    "`kairos_enqueue_prompt(prompt, priority, session_id)` tools so the model can "
+    "(up to N concurrently). Each job gets `kaira_sleep_ms(ms)` and "
+    "`kaira_enqueue_prompt(prompt, priority, session_id)` tools so the model can "
     "schedule follow-up work itself. Useful for: bulk file processing, repeated "
     "polling loops, parallelising large independent tasks. "
-    "Tell the user to open a second terminal and run `gemcode kairos` if a task "
+    "Tell the user to open a second terminal and run `gemcode kaira` if a task "
     "would benefit from background parallelism."
   )
 
@@ -248,6 +251,19 @@ def _build_runtime_facts(cfg: GemCodeConfig) -> str:
   git_ctx = _get_git_context(root)
   git_section = f"\n\n## Git context (snapshot at session start)\n{git_ctx}" if git_ctx else ""
 
+  # ── Curated memory (safe-to-inject) ───────────────────────────────────────
+  curated_section = ""
+  try:
+    snap = getattr(cfg, "_curated_memory_snapshot", None)
+    if isinstance(snap, dict) and (snap.get("text") or "").strip():
+      curated_section = (
+        "\n\n## Curated memory (safe, persistent)\n"
+        "This is small, curated memory that should be treated as durable project/user facts.\n"
+        f"{snap.get('text')}\n"
+      )
+  except Exception:
+    curated_section = ""
+
   return f"""## Runtime facts (authoritative for this session)
 - **Today's date:** {today}
 - **Project root** — every filesystem tool path is relative to: `{root}`
@@ -258,10 +274,10 @@ def _build_runtime_facts(cfg: GemCodeConfig) -> str:
 - **Capability routing** (`capability_mode={getattr(cfg, 'capability_mode', 'auto')}`): in `auto` mode, GemCode automatically enables deep_research when it detects research-intent keywords in your prompt each turn. You can also type `/research on`, `/embeddings on`, `/memory on`, `/computer on` at the prompt.
 - **Your tool palette can grow mid-session:** if the user enables a capability via a slash command, the runner rebuilds and you get new tools on the next turn.
 - **Memory system:** when `memory ON`, ADK automatically searches `.gemcode/memories.jsonl` and injects relevant past context before each turn. Facts the user tells you in one session can appear in future sessions. You do not need to manage memory explicitly — it is loaded automatically.
-{kairos_section}
+{kaira_section}
 - **UI banner** phrases like "GemCode Pro" are terminal marketing, not a separate API tier.
 - **Env toggles** (`GEMCODE_ENABLE_COMPUTER_USE`, `GEMCODE_MODEL`, etc.) affect only the OS process that launched gemcode. Pasting `VAR=1` in chat does NOT reconfigure a running session—tell the user to export in their shell, use project `.env`, or restart the CLI.
-- **Working in subfolders** — call `list_directory("Desktop")`, `glob_files("**/query.ts")`, `read_file("testing/ai-edtech-app/src/app/page.tsx")` directly. Never claim access is blocked unless a tool returned an explicit error.{git_section}"""
+- **Working in subfolders** — call `list_directory(\"Desktop\")`, `glob_files(\"**/query.ts\")`, `read_file(\"testing/ai-edtech-app/src/app/page.tsx\")` directly. Never claim access is blocked unless a tool returned an explicit error.{git_section}{curated_section}"""
 
 
 def _build_memory_section(cfg: GemCodeConfig) -> str:
@@ -664,7 +680,7 @@ Concrete patterns:
 - Grepping different patterns → multiple `grep_content` in one response
 - `list_directory` + `glob_files` → both at once
 
-**Parallel sub-agent exploration (OpenClaude pattern):**
+**Parallel sub-agent exploration (reference terminal UI pattern):**
 When a task requires understanding several subsystems before acting:
 1. Spawn parallel `run_subtask` workers, one per subsystem
 2. Wait for all results to return in the same turn
@@ -828,7 +844,7 @@ Use `gh pr create` via `bash`. When asked to create a PR:
 All file tools use paths **relative to the project root** (where GemCode was started). The root may be the home folder — subfolders like `Desktop`, `Desktop/code`, `Documents` are inside the sandbox. Call `list_directory("Desktop")` or `glob_files("**/*name*.ts")` instead of assuming access is blocked. Only treat access as denied when a tool returns an explicit `error`.
 
 ## Agent notes (.gemcode/notes.md)
-You have two tools to persist project insights across sessions, like Claude Code's auto-memory:
+You have two tools to persist project insights across sessions (auto-memory style):
 
 - **`append_project_note(note)`** — write a note to `.gemcode/notes.md`. Use this proactively when you discover something worth remembering:
   - Build/test/lint commands you discover ("Build: `npm run build` — requires Node 20")
@@ -840,7 +856,12 @@ You have two tools to persist project insights across sessions, like Claude Code
   Call this **immediately** when you discover something useful — not just at the end of tasks.
   Notes are loaded at session start so future sessions inherit this knowledge.
 
-- **`read_project_notes()`** — read current notes **only when starting a real engineering task** (editing, debugging, building). Do NOT call this for greetings or general questions. If notes exist and you're about to work on a task, read them once to avoid re-discovering known information."""
+- **`read_project_notes()`** — read current notes **only when starting a real engineering task** (editing, debugging, building). Do NOT call this for greetings or general questions. If notes exist and you're about to work on a task, read them once to avoid re-discovering known information.
+
+## Do not create vendor-specific instruction files
+- Do NOT create or modify `CLAUDE.md` or `AGENTS.md`. GemCode does not use these.
+- If project instructions are needed and the user asked for it, use `GEMINI.md` (repo root).
+"""
 
   # Inject capability-specific strategy sections only when those caps are on.
   if getattr(cfg, "enable_computer_use", False):
@@ -855,6 +876,18 @@ You have two tools to persist project insights across sessions, like Claude Code
   tool_manifest = build_tool_manifest(cfg)
   if tool_manifest:
     base = f"{base}\n\n{tool_manifest}"
+  # Output style: small, user-selected formatting layer.
+  style_section = build_output_style_section(cfg.project_root, getattr(cfg, "output_style", None))
+  if style_section:
+    base = f"{base}\n\n{style_section}"
+  # Rules: project conventions (path-gated based on files the agent/user touched this session).
+  touched = sorted(getattr(cfg, "_touched_paths", set()) or set())
+  rules_section = build_rules_section(cfg.project_root, touched_paths=touched or None)
+  if rules_section:
+    base = f"{base}\n\n{rules_section}"
+  skill_manifest = build_skill_manifest_text(cfg.project_root)
+  if skill_manifest:
+    base = f"{base}\n\n{skill_manifest}"
   extra = _load_gemini_md(cfg.project_root)
   if extra.strip():
     return f"{base}\n\n## Project instructions (GEMINI.md)\n{extra}"
@@ -903,7 +936,7 @@ def build_root_agent(
   except Exception:
     pass
 
-  # Agent auto-notes: write project insights to .gemcode/notes.md (Claude Code MEMORY.md equivalent)
+  # Agent auto-notes: write project insights to .gemcode/notes.md (project notes file)
   try:
     from gemcode.tools.notes import build_notes_tools
     notes_tools = build_notes_tools(cfg.project_root)
@@ -931,7 +964,7 @@ def build_root_agent(
   if before_model is not None:
     cb_kwargs["before_model_callback"] = before_model
 
-  # Claude-like thinking: enabled by default (Gemini dynamic), but allow
+  # familiar thinking: enabled by default (Gemini dynamic), but allow
   # explicit overrides for disable/budgets/levels.
   gen_cfg = None
   thinking_cfg = build_thinking_config(cfg)

gemcode/autocompact.py

@@ -1,5 +1,5 @@
 """
-Claude Code–style autocompact for ADK/Gemini.
+interactive CLI–style autocompact for ADK/Gemini.
 
 GemCode already has:
 - bounded tool output (after_tool truncation)
@@ -41,7 +41,7 @@ def _autocompact_enabled(cfg: GemCodeConfig) -> bool:
 
 
 def _autocompact_threshold_chars(cfg: GemCodeConfig) -> int:
-  # Claude Code uses token windows; we use a character proxy budget since
+  # uses token windows; we use a character proxy budget since
   # Gemini tokenizers vary and ADK does not expose a cheap exact counter.
   max_chars = int(getattr(cfg, "max_context_chars", 0) or 0)
   if max_chars <= 0:

gemcode/autotune.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import subprocess
+import time
+from pathlib import Path
+from typing import Any
+
+from gemcode.evals.harness import run_eval_suite, write_eval_record
+
+
+def _sh(cmd: list[str], *, cwd: Path) -> tuple[int, str]:
+  p = subprocess.run(cmd, cwd=str(cwd), capture_output=True, text=True)
+  out = (p.stdout or "") + (p.stderr or "")
+  return int(p.returncode), out
+
+
+def _git_head_sha(repo: Path) -> str | None:
+  rc, out = _sh(["git", "rev-parse", "HEAD"], cwd=repo)
+  if rc != 0:
+    return None
+  return (out or "").strip().splitlines()[-1] if (out or "").strip() else None
+
+
+def _git_branch(repo: Path) -> str | None:
+  rc, out = _sh(["git", "rev-parse", "--abbrev-ref", "HEAD"], cwd=repo)
+  if rc != 0:
+    return None
+  return (out or "").strip().splitlines()[-1] if (out or "").strip() else None
+
+
+def init_autotune(*, project_root: Path, tag: str) -> dict[str, Any]:
+  """
+  AutoResearch-style setup:
+  - create branch autotune/<tag> (if not exists)
+  - create results ledger under .gemcode/evals/
+  """
+  repo = project_root
+  if not (repo / ".git").exists():
+    return {"error": "not_a_git_repo"}
+  branch = f"autotune/{tag}"
+  rc, out = _sh(["git", "rev-parse", "--verify", branch], cwd=repo)
+  if rc == 0:
+    return {"status": "exists", "branch": branch}
+  rc2, out2 = _sh(["git", "checkout", "-b", branch], cwd=repo)
+  if rc2 != 0:
+    return {"error": "branch_create_failed", "output": out2[-1200:]}
+  return {"status": "created", "branch": branch}
+
+
+def run_autotune_eval(*, project_root: Path, include_llm: bool, model: str | None = None) -> dict[str, Any]:
+  """
+  Run eval suite and persist last result to .gemcode/evals/last_eval.json.
+  """
+  res = run_eval_suite(project_root=project_root, include_llm=include_llm, model=model)
+  meta = {
+    "ts": time.time(),
+    "git_sha": _git_head_sha(project_root),
+    "git_branch": _git_branch(project_root),
+  }
+  p = write_eval_record(project_root, {**meta, **res})
+  res["record_path"] = str(p)
+
+  # Append ledger line (untracked; .gemcode/ is gitignored)
+  try:
+    ledger = project_root / ".gemcode" / "evals" / "autotune_ledger.jsonl"
+    ledger.parent.mkdir(parents=True, exist_ok=True)
+    import json
+
+    ledger.write_text("", encoding="utf-8") if not ledger.exists() else None
+    with ledger.open("a", encoding="utf-8") as f:
+      f.write(json.dumps({**meta, **res}, ensure_ascii=False) + "\n")
+    res["ledger_path"] = str(ledger)
+  except Exception:
+    pass
+  return res
+

gemcode/callbacks.py

@@ -1,7 +1,7 @@
 """
 ADK callbacks: permissions, audit, tool failure circuit breaker, usage logging.
 
-Maps to Claude Code patterns:
+Maps to patterns:
 - before_tool / after_tool ≈ permission gates + telemetry around tool execution
 - after_model ≈ cost / usage hooks (see cost-tracker.ts role)
 - Session state for streak counters ≈ autoCompact failure tracking (MVP: tool errors)
@@ -60,7 +60,7 @@ def _truthy_env(name: str, *, default: bool = False) -> bool:
 
 
 def _maybe_tool_summary_enabled() -> bool:
-  # Mirrors Claude's "emit tool use summaries" gate conceptually.
+  # Mirrors optional "emit tool use summaries" gating.
   return _truthy_env("GEMCODE_EMIT_TOOL_USE_SUMMARIES", default=False)
 
 
@@ -344,7 +344,7 @@ def make_before_tool_callback(cfg: GemCodeConfig):
 
 
 def make_after_tool_callback(cfg: GemCodeConfig):
-  """Track consecutive tool failures in session state (Claude-style circuit breaker)."""
+  """Track consecutive tool failures in session state (conventional circuit breaker)."""
 
   def after_tool(
     tool: BaseTool,
@@ -548,7 +548,7 @@ def make_after_tool_callback(cfg: GemCodeConfig):
               summary[k] = v
       append_audit(cfg.project_root, summary)
       # Also print a concise, user-visible summary in CLI contexts.
-      # (Claude Code renders tool cards; this is the lightweight equivalent.)
+      # (renders tool cards; this is the lightweight equivalent.)
       try:
         # Full-screen TUIs get corrupted by stray stderr prints.
         if _truthy_env("GEMCODE_TUI_ACTIVE", default=False):
@@ -621,7 +621,7 @@ def make_after_model_callback(cfg: GemCodeConfig):
 
     # ── Expose live token stats to the TUI ───────────────────────────────────
     # The TUI reads cfg._last_turn_stats after each turn to display token counts
-    # and estimated cost in the footer (like OpenClaude's spinner token display).
+    # and estimated cost in the footer (like Reference UI spinner token display).
     try:
       in_tok  = d.get("prompt_token_count", 0) or 0
       out_tok = d.get("candidates_token_count", 0) or 0
@@ -762,7 +762,7 @@ def make_after_model_callback(cfg: GemCodeConfig):
 
 
 def make_on_tool_error_callback(cfg: GemCodeConfig):
-  """Turn tool exceptions into structured tool results (Claude-like is_error)."""
+  """Turn tool exceptions into structured tool results (familiar is_error)."""
 
   async def on_tool_error(
     *, tool: BaseTool, args: dict[str, Any], tool_context, error: Exception

gemcode/capability_routing.py

@@ -1,8 +1,8 @@
 """
-Capability-based routing (Claude Code style conceptually).
+Capability-based routing (style conceptually).
 
 This layer decides which *capabilities* to enable (deep research tools,
-embeddings retrieval, computer-use tools) and leaves the existing Claude-like
+embeddings retrieval, computer-use tools) and leaves the existing familiar
 outer/inner loops intact.
 
 It is intentionally conservative:

gemcode/checkpoints.py

@@ -0,0 +1,144 @@
+"""
+Hermes-style checkpoints for GemCode.
+
+Goal: make file mutations reversible with an explicit, local checkpoint log.
+
+Storage:
+  <project>/.gemcode/checkpoints/<checkpoint_id>/manifest.json
+  <project>/.gemcode/checkpoints/<checkpoint_id>/files/<path>
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+def _now_ms() -> int:
+  return int(time.time() * 1000)
+
+
+def _checkpoints_dir(project_root: Path) -> Path:
+  return project_root / ".gemcode" / "checkpoints"
+
+
+def _safe_rel(project_root: Path, p: Path) -> str:
+  return str(p.resolve().relative_to(project_root.resolve()))
+
+
+@dataclass
+class CheckpointFile:
+  path: str
+  existed: bool
+
+
+@dataclass
+class Checkpoint:
+  id: str
+  ts_ms: int
+  op: str
+  files: list[CheckpointFile]
+
+
+def create_checkpoint(
+  *,
+  project_root: Path,
+  op: str,
+  file_snapshots: list[tuple[Path, bool]],
+) -> Checkpoint:
+  """
+  Create a checkpoint capturing the *previous* contents of the provided files.
+
+  file_snapshots entries are (absolute_path, existed_bool).
+  """
+  ts = _now_ms()
+  cid = f"cp_{ts}"
+  base = _checkpoints_dir(project_root) / cid
+  files_dir = base / "files"
+  files_dir.mkdir(parents=True, exist_ok=True)
+  out_files: list[CheckpointFile] = []
+
+  for abs_path, existed in file_snapshots:
+    try:
+      rel = _safe_rel(project_root, abs_path)
+    except Exception:
+      continue
+    out_files.append(CheckpointFile(path=rel, existed=bool(existed)))
+    if existed and abs_path.is_file():
+      target = files_dir / rel
+      target.parent.mkdir(parents=True, exist_ok=True)
+      target.write_bytes(abs_path.read_bytes())
+
+  manifest = {
+    "id": cid,
+    "ts_ms": ts,
+    "op": op,
+    "files": [{"path": f.path, "existed": f.existed} for f in out_files],
+  }
+  (base / "manifest.json").write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+  return Checkpoint(id=cid, ts_ms=ts, op=op, files=out_files)
+
+
+def list_checkpoints(project_root: Path, limit: int = 20) -> list[dict[str, Any]]:
+  d = _checkpoints_dir(project_root)
+  if not d.is_dir():
+    return []
+  cps = []
+  for p in sorted(d.iterdir(), key=lambda x: x.name, reverse=True):
+    m = p / "manifest.json"
+    if not m.is_file():
+      continue
+    try:
+      obj = json.loads(m.read_text(encoding="utf-8"))
+      cps.append(obj)
+    except Exception:
+      continue
+    if len(cps) >= max(1, int(limit)):
+      break
+  return cps
+
+
+def undo_checkpoint(project_root: Path, checkpoint_id: str | None = None) -> dict[str, Any]:
+  d = _checkpoints_dir(project_root)
+  if not d.is_dir():
+    return {"error": "no_checkpoints"}
+  if checkpoint_id:
+    base = d / checkpoint_id
+  else:
+    # newest
+    items = [p for p in d.iterdir() if p.is_dir()]
+    if not items:
+      return {"error": "no_checkpoints"}
+    base = sorted(items, key=lambda x: x.name, reverse=True)[0]
+  manifest_path = base / "manifest.json"
+  if not manifest_path.is_file():
+    return {"error": "checkpoint_missing_manifest"}
+  try:
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+  except Exception as e:
+    return {"error": f"checkpoint_manifest_invalid:{e}"}
+  files_dir = base / "files"
+  restored = []
+  for f in manifest.get("files") or []:
+    try:
+      rel = str(f.get("path") or "")
+      existed = bool(f.get("existed"))
+      abs_path = (project_root / rel).resolve()
+      if existed:
+        src = files_dir / rel
+        if src.is_file():
+          abs_path.parent.mkdir(parents=True, exist_ok=True)
+          abs_path.write_bytes(src.read_bytes())
+          restored.append(rel)
+      else:
+        # File did not exist previously; remove it if it exists now.
+        if abs_path.is_file():
+          abs_path.unlink()
+          restored.append(rel)
+    except Exception:
+      continue
+  return {"checkpoint_id": manifest.get("id") or base.name, "restored": restored}
+