gemcode 0.3.27__tar.gz → 0.3.29__tar.gz

{gemcode-0.3.27/src/gemcode.egg-info → gemcode-0.3.29}/PKG-INFO

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

{gemcode-0.3.27 → gemcode-0.3.29}/pyproject.toml

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

{gemcode-0.3.27 → gemcode-0.3.29}/src/gemcode/agent.py

@@ -58,17 +58,97 @@ def _load_gemini_md(project_root: Path) -> str:
 
 def _build_runtime_facts(cfg: GemCodeConfig) -> str:
   """
-  Injected every session so the model does not hallucinate deployment, permissions,
-  or "how to switch Pro" the way a product-agnostic base prompt would.
+  Injected every session so the model is fully self-aware of its own capabilities,
+  limits, and the environment — not just generic defaults.
   """
   root = cfg.project_root.resolve()
   model = (getattr(cfg, "model", None) or "").strip() or "(default)"
+
+  # ── Active capabilities ──────────────────────────────────────────────────
+  caps: list[str] = []
+  if getattr(cfg, "enable_deep_research", False):
+    dr_extras = " + google_maps_grounding" if getattr(cfg, "enable_maps_grounding", False) else ""
+    caps.append(f"deep_research ON (tools: google_search, url_context{dr_extras})")
+  if getattr(cfg, "enable_embeddings", False):
+    caps.append(f"embeddings ON (tool: semantic_search_files, model: {getattr(cfg, 'embeddings_model', 'default')})")
+  if getattr(cfg, "enable_memory", False):
+    mem_path = root / ".gemcode" / "memories.jsonl"
+    mem_kind = "embedding-backed" if getattr(cfg, "enable_embeddings", False) else "keyword-backed"
+    caps.append(f"memory ON ({mem_kind}, stored at {mem_path}; ADK preload_memory injects relevant memories before each turn)")
+  if getattr(cfg, "enable_computer_use", False):
+    caps.append("computer_use ON (tools: navigate, click_at, type_text_at, browser_screenshot, browser_find_element, etc.)")
+  if getattr(cfg, "enable_code_executor", False):
+    caps.append("code_executor ON — you can write Python code blocks and they will be executed safely via Gemini's built-in sandboxed executor; results appear as code_execution_result events. Use this for math, data processing, quick tests, and anything that would otherwise require a shell command.")
+  if getattr(cfg, "enable_artifacts", True):
+    caps.append("artifacts ON — use save_artifact(filename, bytes, mime_type) / load_artifact(filename) to store large/binary outputs (screenshots, PDFs, generated files) outside session history. Artifacts are keyed by filename; prefix 'user:' for cross-session persistence.")
+  if not caps:
+    caps.append("none enabled (use /research on, /embeddings on, /memory on, /computer on, /code on to enable)")
+  caps_text = "\n".join(f"  - {c}" for c in caps)
+
+  # ── Limits ───────────────────────────────────────────────────────────────
+  max_calls = getattr(cfg, "max_llm_calls", 256) or 256
+  token_budget = getattr(cfg, "token_budget", None)
+  max_session_tokens = getattr(cfg, "max_session_tokens", None)
+  budget_line = f"{max_calls} model↔tool iterations per user message"
+  if token_budget:
+    budget_line += f" · token_budget={token_budget:,} per turn"
+  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
+  # 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 "
+    "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 "
+    "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 "
+    "would benefit from background parallelism."
+  )
+
   return f"""## Runtime facts (authoritative for this session)
 - **Project root** — every filesystem tool path is relative to: `{root}`
-- **Model id in use:** `{model}`. In this TUI/REPL you can override it for subsequent turns with `/model use <id>` (use `/model list` to browse IDs). For a full restart you can still use `--model <id>` or env `GEMCODE_MODEL`.
-- **UI banner** phrases such as "GemCode Pro" are **terminal marketing**, not a separate API tier or model you enable from chat.
-- **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** — use tools: e.g. `list_directory("Desktop")`, `glob_files("**/query.ts")`, `read_file("testing/ai-edtech-app/src/app/page.tsx")`, or `run_command` with `cwd_subdir`. Never claim the sandbox cannot reach a subpath unless a tool returned an explicit error."""
+- **Model id in use:** `{model}`. Override mid-session with `/model use <id>` or `/mode fast|balanced|quality|auto`.
+- **Execution budget:** {budget_line}.
+- **Active capabilities:**
+{caps_text}
+- **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}
+- **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."""
+
+
+def _build_memory_section(cfg: GemCodeConfig) -> str:
+  """Injected when enable_memory=True so the agent understands and uses memory."""
+  mem_path = cfg.project_root / ".gemcode" / "memories.jsonl"
+  kind = "embedding-based (semantic cosine similarity)" if getattr(cfg, "enable_embeddings", False) else "keyword-based"
+  return f"""
+## Persistent Memory System
+Memory is **ON** ({kind}). Stored at: `{mem_path}`
+
+### How it works
+- Before each turn, ADK automatically searches the memory store for relevant past facts and injects them as context — you do not need to call a tool to load them.
+- After each turn, the session is automatically added to memory by the post-turn plugin.
+- The memory file persists across sessions (JSONL, one entry per session).
+
+### What to do with memory
+- **Reference it naturally** — if the injected context mentions past facts ("last time the user's API key was X", "the user prefers TypeScript"), treat that as trusted context.
+- **Update it proactively** — if the user tells you important facts about their project, preferences, or recurring patterns, note them in your response: "I'll remember that for future sessions."
+- **Don't re-explain already-known context** — if the memory already contains the project structure or preferences, skip the discovery step and act on what's known.
+- **Memory is scoped to this project root** — `{cfg.project_root}`. Different project roots have separate memories.
+
+### When memory helps most
+- Long-running projects (user preferences, patterns, recurring tasks)
+- Multi-session workflows (continuing work from a previous day)
+- Team conventions stored once and reused automatically
+"""
 
 
 def _build_computer_use_section(cfg: GemCodeConfig) -> str:
@@ -350,6 +430,41 @@ Use `run_subtask` when the work is better done in an isolated context:
 
 The sub-agent inherits your permission settings and returns its final text as `result`. Treat it as a trusted colleague returning a written summary.
 
+## ADK Special Tools (always available when ADK supports them)
+
+### `get_user_choice`
+Present the user with a structured multi-option prompt rather than open-ended questions.
+Use when you need the user to pick from 2–6 specific options (e.g. "Which framework would you like?", "Choose migration strategy: A, B, or C").
+This provides a better UX than asking them to type a free-form answer.
+
+### `load_artifacts`
+Load binary/large artifacts that were saved in a previous turn or by a sub-agent.
+Artifacts are keyed by filename (e.g. "report.pdf", "screenshot.png", "output.json").
+Use `user:filename` prefix for user-scoped artifacts that persist across sessions.
+After loading, the artifact bytes are available for further processing (display, analysis, transformation).
+
+### `exit_loop`
+Signal the surrounding LoopAgent to stop iterating and return the final result.
+Only meaningful when this agent is running inside an ADK LoopAgent pipeline.
+Call this when the task is complete and no further iterations are needed.
+
+## Artifacts — storing large outputs
+When `artifacts ON` (see Runtime facts above):
+- **Save** large generated content as artifacts instead of printing them inline:
+  - Screenshots from computer_use: save as "screenshot.png" artifact
+  - Generated reports/PDFs: save as "report.pdf" artifact
+  - Large JSON data: save as "data.json" artifact
+- **Reference** artifacts in instructions via `{artifact.filename?}` template syntax
+- Artifacts are keyed by filename; `user:` prefix = cross-session persistence
+
+## Code Executor (sandboxed Python)
+When `code_executor ON` (see Runtime facts above):
+- You can write Python code blocks in your response and the Gemini API executes them safely
+- The result appears as a `code_execution_result` event with stdout and the outcome
+- Best for: math calculations, data transformation, unit testing logic, quick experiments
+- The sandbox does NOT have internet access or filesystem access — use for pure computation
+- For file I/O or shell commands, use the standard tools (`bash`, `write_file`, etc.)
+
 ## Evaluator-optimizer loop
 For tasks where quality matters:
 1. Complete the task (execute tools, write code, run commands)
@@ -378,10 +493,13 @@ For tasks where quality matters:
 ## Workspace scope
 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`."""
 
-  # Inject computer use strategy when the browser is enabled.
+  # Inject capability-specific strategy sections only when those caps are on.
   if getattr(cfg, "enable_computer_use", False):
     base = f"{base}\n\n{_build_computer_use_section(cfg)}"
 
+  if getattr(cfg, "enable_memory", False):
+    base = f"{base}\n\n{_build_memory_section(cfg)}"
+
   tool_manifest = build_tool_manifest(cfg)
   if tool_manifest:
     base = f"{base}\n\n{tool_manifest}"
@@ -391,6 +509,17 @@ All file tools use paths **relative to the project root** (where GemCode was sta
   return base
 
 
+def _build_code_executor(cfg: GemCodeConfig):
+  """Return an ADK BuiltInCodeExecutor when enable_code_executor=True, else None."""
+  if not getattr(cfg, "enable_code_executor", False):
+    return None
+  try:
+    from google.adk.code_executors import BuiltInCodeExecutor
+    return BuiltInCodeExecutor()
+  except Exception:
+    return None
+
+
 def build_root_agent(
   cfg: GemCodeConfig,
   extra_tools: list | None = None,
@@ -413,8 +542,15 @@ def build_root_agent(
   if getattr(cfg, "enable_memory", False):
     # ADK preload_memory injects retrieved memories into the next llm_request.
     from google.adk.tools import preload_memory
-
     tools = [preload_memory, *tools]
+
+  # ADK built-in interactive + artifact tools — always available when ADK supports them.
+  try:
+    from google.adk.tools import get_user_choice, load_artifacts, exit_loop
+    tools = [*tools, get_user_choice, load_artifacts, exit_loop]
+  except Exception:
+    pass
+
   if extra_tools:
     tools = [*tools, *extra_tools]
 
@@ -469,15 +605,31 @@ def build_root_agent(
       tool_config=tool_cfg,
     )
 
-  return LlmAgent(
+  # global_instruction applies to the entire agent tree (including sub-agents
+  # spawned via run_subtask or multi-agent delegation).  Keep it short — it's
+  # prepended to every agent's effective instruction.
+  global_instr = (
+    "You are GemCode, an expert software engineering agent powered by Google Gemini. "
+    "Act, don't advise. Complete tasks fully and autonomously. "
+    "Think before destructive actions. Use read-only tools before shell/write tools."
+  )
+
+  agent_kwargs: dict = dict(
       model=cfg.model,
       name="gemcode",
       instruction=build_instruction(cfg),
+      global_instruction=global_instr,
       tools=tools,
       generate_content_config=gen_cfg,
       **cb_kwargs,
   )
 
+  code_executor = _build_code_executor(cfg)
+  if code_executor is not None:
+    agent_kwargs["code_executor"] = code_executor
+
+  return LlmAgent(**agent_kwargs)
+
 
 def create_runner(cfg: GemCodeConfig, extra_tools: list | None = None):
   """Backward-compatible: prefer `gemcode.session_runtime.create_runner`."""

{gemcode-0.3.27 → gemcode-0.3.29}/src/gemcode/config.py

@@ -251,6 +251,22 @@ class GemCodeConfig:
     default_factory=lambda: _truthy_env("GEMCODE_SHOW_FULL_THINKING", default=False)
   )
 
+  # Enable ADK BuiltInCodeExecutor for safe sandboxed Python execution via
+  # Gemini's code execution API. When on, the agent can write and run Python
+  # snippets inline (math, data processing, quick tests) without requiring
+  # bash/shell permissions. Requires a Gemini model that supports code execution
+  # (gemini-2.5-flash, gemini-2.5-pro, gemini-3.x).
+  enable_code_executor: bool = field(
+    default_factory=lambda: _truthy_env("GEMCODE_ENABLE_CODE_EXECUTOR", default=False)
+  )
+
+  # Enable ADK artifact service for storing large/binary outputs (screenshots,
+  # generated files, reports) outside of session history.
+  # When on, the agent can save_artifact / load_artifact keyed by filename.
+  enable_artifacts: bool = field(
+    default_factory=lambda: _truthy_env("GEMCODE_ENABLE_ARTIFACTS", default=True)
+  )
+
   def __post_init__(self) -> None:
     self.project_root = self.project_root.resolve()
     # Default agentic depth when env omits GEMCODE_MAX_LLM_CALLS (was: None → SDK default).

gemcode-0.3.29/src/gemcode/refine.py

@@ -0,0 +1,204 @@
+"""
+Iterative refinement pipelines using ADK LoopAgent + SequentialAgent.
+
+This module exposes factory functions for building multi-agent orchestration
+patterns that GemCode can invoke for complex, multi-step tasks:
+
+  - build_refine_loop(): LoopAgent that loops write→test→fix until tests pass
+    or max_iterations is reached (escalates via exit_loop tool).
+
+  - build_sequential_pipeline(): SequentialAgent that runs N specialist agents
+    in order, passing results through session state via output_key.
+
+  - build_parallel_research(): ParallelAgent that fans out N research sub-agents
+    then collects their outputs.
+
+These are "heavy" patterns; they are NOT wired by default — callers instantiate
+them on demand (e.g. via /refine slash command or run_subtask).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Guard: check what's available in the installed ADK version
+# ---------------------------------------------------------------------------
+try:
+    from google.adk.agents import LoopAgent, SequentialAgent, ParallelAgent, LlmAgent  # type: ignore
+    _ADK_WORKFLOW_AGENTS_OK = True
+except ImportError:
+    _ADK_WORKFLOW_AGENTS_OK = False
+    log.warning("google.adk workflow agents (LoopAgent/SequentialAgent/ParallelAgent) "
+                "not available — refine pipelines disabled.")
+
+
+def _require_workflow() -> None:
+    if not _ADK_WORKFLOW_AGENTS_OK:
+        raise RuntimeError(
+            "ADK workflow agents (LoopAgent / SequentialAgent / ParallelAgent) are not "
+            "available in the installed google-adk version. "
+            "Try: pip install -U google-adk"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Write → Test → Fix Loop
+# ---------------------------------------------------------------------------
+
+def build_refine_loop(
+    *,
+    model: str,
+    task_description: str,
+    test_command: str,
+    max_iterations: int = 8,
+    extra_tools: list | None = None,
+) -> Any:
+    """
+    Build a LoopAgent that iteratively writes code, runs tests, and fixes
+    failures until all tests pass or ``max_iterations`` is exhausted.
+
+    Architecture:
+      LoopAgent(max_iterations=N)
+        ├─ writer_agent   — writes / edits code based on current task + test output
+        ├─ tester_agent   — runs the test command via bash, stores result in state
+        └─ checker_agent  — inspects test result; calls exit_loop if tests pass
+
+    State keys used:
+      "task"          — original task description (seeded by caller)
+      "test_command"  — shell command to run tests
+      "test_output"   — stdout/stderr from last test run
+      "test_passed"   — "yes" if tests passed
+      "iteration"     — current loop count (auto-incremented by writer)
+
+    Returns the LoopAgent instance, ready to run via a Runner.
+
+    Example usage:
+      loop = build_refine_loop(model="gemini-2.5-flash",
+                               task_description="add unit tests for parser.py",
+                               test_command="pytest tests/test_parser.py -x")
+      runner = Runner(agent=loop, app_name="refine", session_service=...)
+      async for event in runner.run_async(...):
+          ...
+    """
+    _require_workflow()
+    from google.adk.tools import exit_loop  # type: ignore
+
+    from gemcode.tools import build_function_tools  # type: ignore
+
+    # Shared tools that the sub-agents may use (no run_subtask to avoid recursion)
+    tools = extra_tools or []
+
+    writer = LlmAgent(
+        model=model,
+        name="writer_agent",
+        description="Writes or edits source code to fulfil the task, using test failure output as feedback.",
+        instruction=(
+            "You are a coding agent. Your goal: {task}.\n\n"
+            "Test command: {test_command}\n"
+            "Last test output:\n{test_output?}\n\n"
+            "Write or fix code to make the tests pass. "
+            "After making your edits, update state key 'iteration' by incrementing it."
+        ),
+        tools=tools,
+        output_key="writer_notes",
+    )
+
+    tester = LlmAgent(
+        model=model,
+        name="tester_agent",
+        description="Runs the test suite and stores the output in session state.",
+        instruction=(
+            "Run the test command stored in state: {test_command}.\n"
+            "Use the bash tool to execute it. Store ALL stdout+stderr verbatim in "
+            "state key 'test_output'. "
+            "If the command exits with code 0 (success), set state key 'test_passed' to 'yes'. "
+            "If it fails, set 'test_passed' to 'no'."
+        ),
+        tools=tools,
+        output_key="test_output",
+    )
+
+    checker = LlmAgent(
+        model=model,
+        name="checker_agent",
+        description=(
+            "Checks whether tests passed. If yes, calls exit_loop to terminate the "
+            "refinement cycle. If no, does nothing (loop continues)."
+        ),
+        instruction=(
+            "Check the value of state key 'test_passed'.\n"
+            "If 'test_passed' is 'yes': call the exit_loop tool to stop the loop — "
+            "the task is complete.\n"
+            "If 'test_passed' is 'no': output a brief summary of the failures so the "
+            "writer knows what to fix next. Do NOT call exit_loop."
+        ),
+        tools=[exit_loop, *tools],
+    )
+
+    return LoopAgent(
+        name="refine_loop",
+        description=(
+            f"Iterative write→test→fix loop for: {task_description[:120]}"
+        ),
+        sub_agents=[writer, tester, checker],
+        max_iterations=max_iterations,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Sequential Pipeline
+# ---------------------------------------------------------------------------
+
+def build_sequential_pipeline(
+    agents: list[Any],
+    *,
+    name: str = "sequential_pipeline",
+    description: str = "Runs specialist agents sequentially, passing results via state.",
+) -> Any:
+    """
+    Wrap a list of LlmAgents in a SequentialAgent.
+
+    Each agent should set ``output_key`` so subsequent agents can read its output
+    via {key} template substitution in their instructions.
+
+    Example:
+      pipeline = build_sequential_pipeline([
+          planner_agent,   # output_key="plan"
+          coder_agent,     # reads {plan}, output_key="code"
+          reviewer_agent,  # reads {code}, output_key="review"
+      ])
+    """
+    _require_workflow()
+    return SequentialAgent(name=name, description=description, sub_agents=agents)
+
+
+# ---------------------------------------------------------------------------
+# Parallel Fan-Out
+# ---------------------------------------------------------------------------
+
+def build_parallel_research(
+    agents: list[Any],
+    *,
+    name: str = "parallel_research",
+    description: str = "Runs research agents in parallel, collecting results via state.",
+) -> Any:
+    """
+    Wrap a list of LlmAgents in a ParallelAgent.
+
+    Each agent MUST use a distinct ``output_key`` to avoid state key collisions.
+
+    Example:
+      research = build_parallel_research([
+          web_researcher,   # output_key="web_results"
+          code_searcher,    # output_key="code_results"
+          doc_reader,       # output_key="doc_results"
+      ])
+      # Wrap in a SequentialAgent to collect after:
+      pipeline = build_sequential_pipeline([research, synthesis_agent])
+    """
+    _require_workflow()
+    return ParallelAgent(name=name, description=description, sub_agents=agents)

{gemcode-0.3.27 → gemcode-0.3.29}/src/gemcode/repl_commands.py

@@ -215,4 +215,6 @@ def slash_help_lines() -> list[str]:
       "  Other:",
       "  /permissions          Show permission / HITL settings",
       "  /hooks                Show post-turn hook configuration",
+      "  /kairos               How to launch the background parallel job scheduler",
+      "  /code [on|off]        Toggle sandboxed Python executor (ADK BuiltInCodeExecutor)",
   ]

{gemcode-0.3.27 → gemcode-0.3.29}/src/gemcode/repl_slash.py

@@ -318,6 +318,88 @@ async def process_repl_slash(
   if name in ("exit", "quit"):
     return ReplSlashResult(exit_repl=True)
 
+  # ── /kairos ───────────────────────────────────────────────────────────────
+  if name == "kairos":
+    args_s = (sc.args or "").strip()
+    out("Kairos — background parallel job scheduler")
+    out()
+    out("What it does:")
+    out("  Runs a long-lived daemon that accepts prompts on stdin and executes")
+    out("  each as an isolated GemCode agent job. Jobs run concurrently (up to")
+    out("  --concurrency N, default 2) in a priority queue.")
+    out()
+    out("How to launch (in a separate terminal):")
+    out(f"  gemcode kairos -C {cfg.project_root}")
+    out("  gemcode kairos -C <project> --concurrency 4 --yes")
+    out("  gemcode kairos -C <project> --model gemini-2.5-pro --deep-research")
+    out()
+    out("Options:")
+    out("  --concurrency N      Max parallel jobs (default: 2)")
+    out("  --default-priority N Priority for stdin jobs (higher = runs first, default: 0)")
+    out("  --yes                Auto-approve mutations (like gemcode --yes)")
+    out("  --model <id>         Override model for all jobs")
+    out("  --model-mode <mode>  fast|balanced|quality|auto")
+    out("  --deep-research      Enable Google Search + URL Context for all jobs")
+    out("  --embeddings         Enable semantic file search for all jobs")
+    out("  --max-llm-calls N    Cap model↔tool iterations per job")
+    out("  --session <uuid>     Share session history with a running gemcode session")
+    out()
+    out("Tools available to jobs (in addition to normal GemCode tools):")
+    out("  kairos_sleep_ms(duration_ms)   — pause this job without blocking others")
+    out("  kairos_enqueue_prompt(prompt, priority, session_id)")
+    out("                                  — the model can queue MORE jobs itself")
+    out()
+    out("Use cases:")
+    out("  - Process N files in parallel: each file → one job")
+    out("  - Polling loop: job sleeps, re-enqueues itself with kairos_enqueue_prompt")
+    out("  - Bulk code generation, test runs, or research across many documents")
+    out("  - Background work while you continue chatting in this session")
+    out()
+    return ReplSlashResult(skip_model_turn=True)
+
+  # ── /code ─────────────────────────────────────────────────────────────────
+  if name == "code":
+    args_s = (sc.args or "").strip().lower()
+    if args_s in ("on", "enable", "1", "true"):
+      cfg.enable_code_executor = True
+      out("Code executor: ON  (sandboxed Python via Gemini built-in executor)")
+      out("The agent can now write Python code blocks and execute them safely,")
+      out("without requiring bash/shell permission. Best for: math, data, quick tests.")
+      out()
+      out("Note: the sandbox has no internet/filesystem access — use bash for I/O.")
+      return ReplSlashResult(skip_model_turn=True, force_rebuild_runner=True)
+    elif args_s in ("off", "disable", "0", "false"):
+      cfg.enable_code_executor = False
+      out("Code executor: OFF")
+      return ReplSlashResult(skip_model_turn=True, force_rebuild_runner=True)
+    else:
+      # Status
+      status = "ON" if getattr(cfg, "enable_code_executor", False) else "OFF"
+      out(f"Code executor: {status}")
+      out()
+      out("ADK BuiltInCodeExecutor — safe sandboxed Python execution via Gemini API.")
+      out()
+      out("What it does:")
+      out("  When ON, the agent can write Python code blocks directly in its response")
+      out("  and the Gemini API executes them in a sandboxed environment. The output")
+      out("  (stdout, result) is sent back so the agent can use it for further reasoning.")
+      out()
+      out("Best for:")
+      out("  - Math and numerical calculations")
+      out("  - Data processing and transformations")
+      out("  - Quick tests of logic or algorithms")
+      out("  - Anything that doesn't need filesystem or network access")
+      out()
+      out("Not for:")
+      out("  - Shell commands (use bash)")
+      out("  - Reading/writing files (use read_file / write_file)")
+      out("  - Internet requests (use web_fetch)")
+      out()
+      out("Toggle: /code on   /code off")
+      out()
+      out("Supported models: gemini-2.5-flash, gemini-2.5-pro, gemini-3.x and newer.")
+      return ReplSlashResult(skip_model_turn=True)
+
   # ── /computer ────────────────────────────────────────────────────────────
   if name in ("computer", "browser"):
     args_s = (sc.args or "").strip().lower()

{gemcode-0.3.27 → gemcode-0.3.29}/src/gemcode/session_runtime.py

@@ -30,6 +30,23 @@ def session_db_path(cfg: GemCodeConfig) -> Path:
   return cfg.project_root / ".gemcode" / "sessions.sqlite"
 
 
+def _build_artifact_service(cfg: GemCodeConfig):
+  """
+  Return an ADK ArtifactService for this session, or None if disabled.
+
+  Uses InMemoryArtifactService so artifacts are available within the session
+  without requiring GCS credentials. The agent can save screenshots, generated
+  files, large reports, etc. as artifacts to avoid bloating session history.
+  """
+  if not getattr(cfg, "enable_artifacts", True):
+    return None
+  try:
+    from google.adk.artifacts import InMemoryArtifactService
+    return InMemoryArtifactService()
+  except Exception:
+    return None
+
+
 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)
@@ -86,7 +103,9 @@ def create_runner(cfg: GemCodeConfig, extra_tools: list | None = None) -> Runner
     else:
       memory_service = FileMemoryService(mem_path)
 
-  return Runner(
+  artifact_service = _build_artifact_service(cfg)
+
+  runner_kwargs: dict = dict(
       app_name="gemcode",
       agent=agent,
       session_service=session_service,
@@ -94,3 +113,7 @@ def create_runner(cfg: GemCodeConfig, extra_tools: list | None = None) -> Runner
       memory_service=memory_service,
       auto_create_session=True,
   )
+  if artifact_service is not None:
+    runner_kwargs["artifact_service"] = artifact_service
+
+  return Runner(**runner_kwargs)