gencode-agent 1.0.0__tar.gz

gencode_agent-1.0.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.3
+Name: gencode-agent
+Version: 1.0.0
+Summary: A terminal coding agent (run `gencode`) that works in your current folder using Ollama or OpenRouter
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# gencode
+
+A terminal coding agent. Open any folder, run `gencode`, and it reads, writes and runs commands in that folder
+using either a local **Ollama** model or an **OpenRouter** hosted model.
+
+## Install
+
+```
+uv tool install gencode-agent      # or: pipx install gencode-agent / pip install gencode-agent
+```
+
+## Use
+
+```
+cd my-project
+gencode
+```
+
+1. Choose a provider: `ollama` or `openrouter`.
+2. `ollama`: enter the model name (Ollama must be running locally on `http://localhost:11434`).
+   `openrouter`: enter your API key (hidden), then the model name (e.g. `openai/gpt-4o-mini`).
+3. Type prompts at `gencode>`. After each task you get the prompt back. Type `exit` to quit.
+
+Provider, key and model are kept only in memory for that terminal session; nothing is saved to disk.
+Each new terminal asks again.
+
+## Optional environment variables
+
+- `OLLAMA_BASE_URL`: default `http://localhost:11434`
+- `GENCODE_NUM_CTX`: Ollama context window, default `32768`
+
+## Warning
+
+The agent can run any shell command in the current folder without confirmation. Only use it in folders you can afford to change.

gencode_agent-1.0.0/README.md

@@ -0,0 +1,34 @@
+# gencode
+
+A terminal coding agent. Open any folder, run `gencode`, and it reads, writes and runs commands in that folder
+using either a local **Ollama** model or an **OpenRouter** hosted model.
+
+## Install
+
+```
+uv tool install gencode-agent      # or: pipx install gencode-agent / pip install gencode-agent
+```
+
+## Use
+
+```
+cd my-project
+gencode
+```
+
+1. Choose a provider: `ollama` or `openrouter`.
+2. `ollama`: enter the model name (Ollama must be running locally on `http://localhost:11434`).
+   `openrouter`: enter your API key (hidden), then the model name (e.g. `openai/gpt-4o-mini`).
+3. Type prompts at `gencode>`. After each task you get the prompt back. Type `exit` to quit.
+
+Provider, key and model are kept only in memory for that terminal session; nothing is saved to disk.
+Each new terminal asks again.
+
+## Optional environment variables
+
+- `OLLAMA_BASE_URL`: default `http://localhost:11434`
+- `GENCODE_NUM_CTX`: Ollama context window, default `32768`
+
+## Warning
+
+The agent can run any shell command in the current folder without confirmation. Only use it in folders you can afford to change.

gencode_agent-1.0.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "gencode-agent"
+version = "1.0.0"
+description = "A terminal coding agent (run `gencode`) that works in your current folder using Ollama or OpenRouter"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+
+[project.scripts]
+gencode = "gencode.main:main"
+
+[tool.uv.build-backend]
+module-name = "gencode"
+
+[build-system]
+requires = ["uv_build>=0.11.0,<0.12"]
+build-backend = "uv_build"

gencode_agent-1.0.0/src/gencode/__main__.py

@@ -0,0 +1,3 @@
+from .main import main
+
+main()

gencode_agent-1.0.0/src/gencode/agent/loop.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+from ..types import (
+    AssistantMessage,
+    Done,
+    Message,
+    Provider,
+    TextDelta,
+    Tool,
+    ToolCallBlock,
+    ToolResultMessage,
+)
+
+
+# events handed to on_event: dicts with a "type" key
+#   {"type": "text", "delta": str}
+#   {"type": "tool_start", "call": ToolCallBlock}
+#   {"type": "tool_end", "call": ToolCallBlock, "result": str, "is_error": bool}
+#   {"type": "turn_end", "message": AssistantMessage}
+@dataclass
+class AgentOptions:
+    provider: Provider
+    model: str
+    tools: list[Tool]
+    messages: list[Message]
+    on_event: Callable[[dict], None]
+    system: str | None = None
+    max_turns: int = 20
+
+
+def run_agent(opts: AgentOptions) -> None:
+    for _ in range(opts.max_turns):
+        assistant: AssistantMessage | None = None
+        for event in opts.provider.stream(opts.messages, opts.model, opts.system, opts.tools):
+            if isinstance(event, TextDelta):
+                opts.on_event({"type": "text", "delta": event.delta})
+            elif isinstance(event, Done):
+                assistant = event.message
+        if assistant is None:
+            raise RuntimeError("stream ended without a done event")
+
+        opts.messages.append(assistant)
+        opts.on_event({"type": "turn_end", "message": assistant})
+
+        if assistant.stop_reason != "toolUse":
+            return
+
+        for call in assistant.content:
+            if not isinstance(call, ToolCallBlock):
+                continue
+            opts.on_event({"type": "tool_start", "call": call})
+            is_error = False
+            try:
+                if "__parse_error__" in call.arguments:
+                    raise ValueError(
+                        f"tool arguments were not valid JSON: {call.arguments['__parse_error__']!r}"
+                    )
+                tool = next((t for t in opts.tools if t.name == call.name), None)
+                if tool is None:
+                    raise ValueError(f"unknown tool name {call.name}")
+                result = tool.execute(call.arguments)
+            except Exception as e:  # tool errors go back to the model, not up the stack
+                result = f"Error: {e}"
+                is_error = True
+            opts.on_event({"type": "tool_end", "call": call, "result": result, "is_error": is_error})
+            opts.messages.append(ToolResultMessage(call.id, call.name, result, is_error))
+    raise RuntimeError(f"stopped after {opts.max_turns} turns")

gencode_agent-1.0.0/src/gencode/main.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import getpass
+import os
+import sys
+
+from .agent.loop import AgentOptions, run_agent
+from .providers import PROVIDERS, get_provider
+from .tools import tools
+from .types import Message, Provider, UserMessage
+
+SYSTEM_PROMPT = (
+    "You are a coding agent running in the user's current folder. "
+    "Use the tools to inspect and change files: `write` to create files, `read`, `ls`, `find` and `grep` to explore, "
+    "and `bash` to run commands (use `uv` for Python projects). "
+    "All paths are relative to the current folder. Look at the folder before you change anything, "
+    "make the files real by calling `write` instead of only printing code, and finish with a short summary of what you did."
+)
+
+EXIT_WORDS = {"exit", "quit"}
+
+
+def ask(label: str, secret: bool = False) -> str:
+    # keep asking until the user types something; Ctrl+C / Ctrl+D at a setup prompt leaves gencode
+    while True:
+        try:
+            value = (getpass.getpass(label) if secret else input(label)).strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            sys.exit(0)
+        if value.lower() in EXIT_WORDS:
+            sys.exit(0)
+        if value:
+            return value
+
+
+def setup() -> tuple[Provider, str]:
+    # nothing is saved: provider, key and model live only in this process, i.e. this terminal session
+    print("Select a provider:")
+    for i, name in enumerate(PROVIDERS, 1):
+        print(f"  {i}. {name}")
+    while True:
+        choice = ask("Provider (name or number): ").lower()
+        if choice.isdigit() and 1 <= int(choice) <= len(PROVIDERS):
+            choice = PROVIDERS[int(choice) - 1]
+        if choice in PROVIDERS:
+            break
+        print(f"  pick one of: {', '.join(PROVIDERS)}")
+
+    api_key = ask("OpenRouter API key (hidden): ", secret=True) if choice == "openrouter" else None
+    model = ask("Model name: ")
+    return get_provider(choice, api_key), model
+
+
+def make_on_event(provider: Provider, model: str):
+    def on_event(event: dict) -> None:
+        kind = event["type"]
+        if kind == "text":
+            print(event["delta"], end="", flush=True)
+        elif kind == "tool_start":
+            call = event["call"]
+            print(f"\n> {call.name} {call.arguments if call.name != 'write' else call.arguments.get('path', '')}", flush=True)
+        elif kind == "tool_end":
+            shown = event["result"] if event["is_error"] else f"{len(event['result'].splitlines())} lines"
+            print(f"  {shown}", flush=True)
+        elif kind == "turn_end":
+            m = event["message"]
+            print(f"\n[{provider.name} | {model} | in={m.usage.input} out={m.usage.output} | {m.stop_reason}]", flush=True)
+
+    return on_event
+
+
+def main() -> None:
+    # keep Windows consoles from choking on non-ASCII model output
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8", errors="replace")
+
+    print(f"gencode - coding agent working in {os.getcwd()}\n(type 'exit' to quit)\n")
+    provider, model = setup()
+    print(f"\nUsing {provider.name}/{model}. Ask me to do something.\n")
+
+    messages: list[Message] = []  # kept across prompts so follow-ups have context
+    on_event = make_on_event(provider, model)
+
+    while True:
+        try:
+            prompt = input("gencode> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            break
+        if not prompt:
+            continue
+        if prompt.lower() in EXIT_WORDS:
+            break
+
+        messages.append(UserMessage(prompt))
+        try:
+            run_agent(
+                AgentOptions(
+                    provider=provider,
+                    model=model,
+                    tools=tools,
+                    messages=messages,
+                    system=SYSTEM_PROMPT,
+                    on_event=on_event,
+                )
+            )
+        except KeyboardInterrupt:
+            print("\n(interrupted)")
+        except Exception as e:  # a failed task must not end the session
+            print(f"\nerror: {e}", file=sys.stderr)
+        print()
+
+
+if __name__ == "__main__":
+    main()

gencode_agent-1.0.0/src/gencode/providers/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from ..types import Provider
+from .ollama import create_ollama
+from .openrouter import create_openrouter
+
+PROVIDERS = ("ollama", "openrouter")
+
+
+def get_provider(name: str, api_key: str | None = None) -> Provider:
+    if name == "ollama":
+        return create_ollama()
+    if name == "openrouter":
+        if not api_key:
+            raise ValueError("openrouter needs an API key")
+        return create_openrouter(api_key)
+    raise ValueError(f"unknown provider '{name}', available: {', '.join(PROVIDERS)}")

gencode_agent-1.0.0/src/gencode/providers/ollama.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import Any, Iterator
+
+from ..types import (
+    AssistantMessage,
+    ContentBlock,
+    Done,
+    Message,
+    StopReason,
+    TextBlock,
+    TextDelta,
+    Tool,
+    ToolCallBlock,
+    Usage,
+)
+
+DEFAULT_BASE_URL = "http://localhost:11434"
+DEFAULT_NUM_CTX = 32768  # override with GENCODE_NUM_CTX; Ollama's own default is only 4096
+
+
+# our messages -> Ollama native /api/chat format
+def to_ollama(messages: list[Message]) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for m in messages:
+        if m.role == "user":
+            out.append({"role": "user", "content": m.content})
+        elif m.role == "assistant":
+            text = "".join(b.text for b in m.content if isinstance(b, TextBlock))
+            calls = [b for b in m.content if isinstance(b, ToolCallBlock)]
+            msg: dict[str, Any] = {"role": "assistant", "content": text}
+            if calls:
+                # unlike OpenAI, the native API takes arguments as an object, not a JSON string
+                msg["tool_calls"] = [
+                    {"function": {"name": c.name, "arguments": c.arguments}} for c in calls
+                ]
+            out.append(msg)
+        else:  # toolResult -> its own message with role "tool"
+            out.append({"role": "tool", "tool_name": m.tool_name, "content": m.content})
+    return out
+
+
+class OllamaProvider:
+    name = "ollama"
+
+    def __init__(self, base_url: str, num_ctx: int) -> None:
+        # accept an old-style ".../v1" URL too; the native API lives at the root
+        base_url = base_url.rstrip("/")
+        if base_url.endswith("/v1"):
+            base_url = base_url[: -len("/v1")]
+        self.chat_url = f"{base_url}/api/chat"
+        self.num_ctx = num_ctx
+
+    def stream(
+        self,
+        messages: list[Message],
+        model: str,
+        system: str | None = None,
+        tools: list[Tool] | None = None,
+    ) -> Iterator[Any]:
+        tools = tools or []
+        chat = to_ollama(messages)
+        if system:
+            chat = [{"role": "system", "content": system}, *chat]
+
+        body: dict[str, Any] = {
+            "model": model,
+            "messages": chat,
+            "stream": True,
+            "options": {"num_ctx": self.num_ctx},
+        }
+        if tools:
+            body["tools"] = [
+                {
+                    "type": "function",
+                    "function": {"name": t.name, "description": t.description, "parameters": t.parameters},
+                }
+                for t in tools
+            ]
+
+        req = urllib.request.Request(
+            self.chat_url,
+            data=json.dumps(body).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+        )
+        try:
+            resp = urllib.request.urlopen(req)
+        except urllib.error.HTTPError as e:
+            raise RuntimeError(f"Ollama error {e.code}: {e.read().decode('utf-8', 'replace')}") from e
+
+        text = ""
+        calls: list[ToolCallBlock] = []
+        usage = Usage()
+        stop_reason: StopReason = "stop"
+
+        # the response is NDJSON: one JSON object per line
+        with resp:
+            for line in resp:
+                if not line.strip():
+                    continue
+                chunk = json.loads(line)
+                if "error" in chunk:
+                    raise RuntimeError(f"Ollama error: {chunk['error']}")
+                msg = chunk.get("message") or {}
+                if msg.get("content"):
+                    text += msg["content"]
+                    yield TextDelta(msg["content"])
+                # tool calls arrive whole (arguments already parsed), not in pieces
+                for tc in msg.get("tool_calls") or []:
+                    fn = tc.get("function") or {}
+                    args = fn.get("arguments") or {}
+                    if isinstance(args, str):
+                        try:
+                            args = json.loads(args) if args else {}
+                        except json.JSONDecodeError:
+                            # small local models sometimes emit broken JSON; let the loop report it to the model
+                            args = {"__parse_error__": args}
+                    calls.append(
+                        ToolCallBlock(id=tc.get("id") or f"call_{len(calls)}", name=fn.get("name", ""), arguments=args)
+                    )
+                if chunk.get("done"):
+                    if chunk.get("done_reason") == "length":
+                        stop_reason = "length"
+                    usage = Usage(chunk.get("prompt_eval_count", 0), chunk.get("eval_count", 0))
+
+        content: list[ContentBlock] = [TextBlock(text)] if text else []
+        content.extend(calls)
+        if calls:
+            stop_reason = "toolUse"
+
+        yield Done(AssistantMessage(content=content, usage=usage, stop_reason=stop_reason))
+
+
+def create_ollama() -> OllamaProvider:
+    return OllamaProvider(
+        base_url=os.environ.get("OLLAMA_BASE_URL", DEFAULT_BASE_URL),
+        num_ctx=int(os.environ.get("GENCODE_NUM_CTX", DEFAULT_NUM_CTX)),
+    )

gencode_agent-1.0.0/src/gencode/providers/openrouter.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import Any, Iterator
+
+from ..types import (
+    AssistantMessage,
+    ContentBlock,
+    Done,
+    Message,
+    StopReason,
+    TextBlock,
+    TextDelta,
+    Tool,
+    ToolCallBlock,
+    Usage,
+)
+
+DEFAULT_BASE_URL = "https://openrouter.ai/api/v1"
+
+
+# our messages -> OpenAI-style chat format (what OpenRouter speaks)
+def to_openai(messages: list[Message]) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for m in messages:
+        if m.role == "user":
+            out.append({"role": "user", "content": m.content})
+        elif m.role == "assistant":
+            text = "".join(b.text for b in m.content if isinstance(b, TextBlock))
+            calls = [b for b in m.content if isinstance(b, ToolCallBlock)]
+            msg: dict[str, Any] = {"role": "assistant", "content": text or None}
+            if calls:
+                # OpenAI wants arguments as a JSON string
+                msg["tool_calls"] = [
+                    {"id": c.id, "type": "function", "function": {"name": c.name, "arguments": json.dumps(c.arguments)}}
+                    for c in calls
+                ]
+            out.append(msg)
+        else:  # toolResult -> role "tool", linked by tool_call_id
+            out.append({"role": "tool", "tool_call_id": m.tool_call_id, "content": m.content})
+    return out
+
+
+class OpenRouterProvider:
+    name = "openrouter"
+
+    def __init__(self, base_url: str, api_key: str) -> None:
+        self.chat_url = f"{base_url.rstrip('/')}/chat/completions"
+        self.api_key = api_key
+
+    def stream(
+        self,
+        messages: list[Message],
+        model: str,
+        system: str | None = None,
+        tools: list[Tool] | None = None,
+    ) -> Iterator[Any]:
+        tools = tools or []
+        chat = to_openai(messages)
+        if system:
+            chat = [{"role": "system", "content": system}, *chat]
+
+        body: dict[str, Any] = {"model": model, "messages": chat, "stream": True}
+        if tools:
+            body["tools"] = [
+                {
+                    "type": "function",
+                    "function": {"name": t.name, "description": t.description, "parameters": t.parameters},
+                }
+                for t in tools
+            ]
+
+        req = urllib.request.Request(
+            self.chat_url,
+            data=json.dumps(body).encode("utf-8"),
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.api_key}",
+                "X-Title": "gencode",
+            },
+        )
+        try:
+            resp = urllib.request.urlopen(req)
+        except urllib.error.HTTPError as e:
+            raise RuntimeError(f"OpenRouter error {e.code}: {e.read().decode('utf-8', 'replace')}") from e
+
+        text = ""
+        partial: dict[int, dict[str, str]] = {}  # tool call index -> pieces, arguments arrive in fragments
+        usage = Usage()
+        stop_reason: StopReason = "stop"
+
+        # the response is server-sent events: "data: {json}" lines, ending with "data: [DONE]"
+        with resp:
+            for raw in resp:
+                line = raw.decode("utf-8", "replace").strip()
+                if not line.startswith("data:"):
+                    continue  # blank lines and ": OPENROUTER PROCESSING" keep-alives
+                payload = line[len("data:") :].strip()
+                if payload == "[DONE]":
+                    break
+                chunk = json.loads(payload)
+                if "error" in chunk:
+                    raise RuntimeError(f"OpenRouter error: {chunk['error']}")
+                if chunk.get("usage"):
+                    usage = Usage(chunk["usage"].get("prompt_tokens", 0), chunk["usage"].get("completion_tokens", 0))
+                for choice in chunk.get("choices") or []:
+                    delta = choice.get("delta") or {}
+                    if delta.get("content"):
+                        text += delta["content"]
+                        yield TextDelta(delta["content"])
+                    for tc in delta.get("tool_calls") or []:
+                        slot = partial.setdefault(tc.get("index", 0), {"id": "", "name": "", "args": ""})
+                        fn = tc.get("function") or {}
+                        slot["id"] = tc.get("id") or slot["id"]
+                        slot["name"] += fn.get("name") or ""
+                        slot["args"] += fn.get("arguments") or ""
+                    if choice.get("finish_reason") == "length":
+                        stop_reason = "length"
+
+        calls: list[ToolCallBlock] = []
+        for i, slot in sorted(partial.items()):
+            try:
+                args = json.loads(slot["args"]) if slot["args"] else {}
+            except json.JSONDecodeError:
+                # let the loop report the broken JSON back to the model
+                args = {"__parse_error__": slot["args"]}
+            calls.append(ToolCallBlock(id=slot["id"] or f"call_{i}", name=slot["name"], arguments=args))
+
+        content: list[ContentBlock] = [TextBlock(text)] if text else []
+        content.extend(calls)
+        if calls:
+            stop_reason = "toolUse"
+
+        yield Done(AssistantMessage(content=content, usage=usage, stop_reason=stop_reason))
+
+
+def create_openrouter(api_key: str) -> OpenRouterProvider:
+    return OpenRouterProvider(base_url=os.environ.get("OPENROUTER_BASE_URL", DEFAULT_BASE_URL), api_key=api_key)

gencode_agent-1.0.0/src/gencode/tools/__init__.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from ..types import Tool
+from .bash import bash_tool
+from .find import find_tool
+from .grep import grep_tool
+from .ls import ls_tool
+from .read import read_tool
+from .stat import stat_tool
+from .write import write_tool
+
+tools: list[Tool] = [bash_tool, read_tool, write_tool, ls_tool, grep_tool, stat_tool, find_tool]

gencode_agent-1.0.0/src/gencode/tools/bash.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+
+from ..types import Tool
+
+MAX_LINES = 2000
+MAX_BYTES = 50 * 1024
+
+
+def find_bash() -> str:
+    """Prefer Git Bash on Windows; plain 'bash' can be the WSL launcher, which sees another file system."""
+    if sys.platform != "win32":
+        return "bash"
+    candidates = [
+        os.path.join(os.environ.get("ProgramFiles", ""), "Git", "bin", "bash.exe"),
+        os.path.join(os.environ.get("ProgramFiles(x86)", ""), "Git", "bin", "bash.exe"),
+        os.path.join(os.environ.get("LOCALAPPDATA", ""), "Programs", "Git", "bin", "bash.exe"),
+    ]
+    for c in candidates:
+        if os.path.exists(c):
+            return c
+    for d in os.environ.get("PATH", "").split(os.pathsep):
+        if not d or d.rstrip("\\/").lower().endswith("system32"):
+            continue
+        c = os.path.join(d, "bash.exe")
+        if os.path.exists(c):
+            return c
+    return shutil.which("bash") or "bash"
+
+
+def truncate_tail(text: str, max_lines: int = MAX_LINES, max_bytes: int = MAX_BYTES) -> str:
+    """Keep the END of the output (errors/results are at the bottom) and say what was cut."""
+    lines = text.split("\n")
+    kept = lines[-max_lines:]
+    while len(kept) > 1 and len("\n".join(kept).encode()) > max_bytes:
+        kept.pop(0)
+    out = "\n".join(kept)
+    if len(out.encode()) > max_bytes:
+        out = out[-max_bytes:]  # one giant line
+    if len(kept) == len(lines) and len(out) == len(text):
+        return text
+    return f"[truncated: showing the last {len(kept)} of {len(lines)} lines]\n{out}"
+
+
+def run_bash(command: str, timeout_s: float) -> str:
+    try:
+        proc = subprocess.Popen(
+            [find_bash(), "-c", command],
+            cwd=os.getcwd(),
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+    except OSError as e:
+        return f"failed to start bash: {e}"
+    try:
+        out, _ = proc.communicate(timeout=timeout_s)
+        return f"{out}\n[exit code: {proc.returncode}]"
+    except subprocess.TimeoutExpired:
+        # proc.kill() does not kill grandchildren on Windows; taskkill /T kills the whole tree
+        if sys.platform == "win32":
+            subprocess.run(["taskkill", "/F", "/T", "/PID", str(proc.pid)], capture_output=True)
+        else:
+            proc.kill()
+        out, _ = proc.communicate()
+        return f"{out}\n[timed out after {timeout_s:g}s]"
+
+
+def _execute(args: dict) -> str:
+    timeout = args.get("timeout")
+    seconds = timeout if isinstance(timeout, (int, float)) and not isinstance(timeout, bool) else 30
+    return truncate_tail(run_bash(str(args["command"]), seconds))
+
+
+bash_tool = Tool(
+    name="bash",
+    description="Run a bash command in the current folder. Returns stdout, stderr and the exit code.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "command": {"type": "string", "description": "The bash command to run"},
+            "timeout": {"type": "number", "description": "Timeout in seconds (default 30)"},
+        },
+        "required": ["command"],
+    },
+    execute=_execute,
+)

gencode_agent-1.0.0/src/gencode/tools/find.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import re
+
+from ..types import Tool
+from .fsutil import glob_to_regex, resolve_path, walk
+
+LIMIT = 2000
+
+
+def _execute(args: dict) -> str:
+    name = str(args["name"]) if args.get("name") else None
+    glob_pattern = str(args["glob"]) if args.get("glob") else None
+    regex_pattern = str(args["regex"]) if args.get("regex") else None
+    type_filter = str(args["type"]) if args.get("type") else None
+
+    if not (name or glob_pattern or regex_pattern):
+        return "error: provide at least one of 'name', 'glob', or 'regex'"
+
+    glob_re = glob_to_regex(glob_pattern) if glob_pattern else None
+    regex_re = None
+    if regex_pattern:
+        try:
+            regex_re = re.compile(regex_pattern)
+        except re.error as e:
+            return f"invalid regex: {e}"
+
+    root = resolve_path(args.get("path") or ".")
+    results: list[str] = []
+    for entry in walk(root, include_hidden=bool(args.get("includeHidden"))):
+        if type_filter == "file" and entry.is_directory:
+            continue
+        if type_filter == "dir" and not entry.is_directory:
+            continue
+        base = entry.rel_path.split("/")[-1]
+        if name and name.lower() not in base.lower():
+            continue
+        if glob_re and not glob_re.match(entry.rel_path):
+            continue
+        if regex_re and not regex_re.search(entry.rel_path):
+            continue
+        results.append(entry.rel_path + "/" if entry.is_directory else entry.rel_path)
+        if len(results) >= LIMIT:
+            results.append(f"[truncated at {LIMIT} results]")
+            break
+    return "\n".join(results) if results else "(no matches)"
+
+
+find_tool = Tool(
+    name="find",
+    description=(
+        "Find files/directories by name, matching a substring, glob pattern (e.g. '**/*.test.py') "
+        "or regex, recursively under a path."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "name": {"type": "string", "description": "Substring to match against file/directory names"},
+            "glob": {"type": "string", "description": "Glob pattern to match against the relative path, e.g. '**/*.py'"},
+            "regex": {"type": "string", "description": "Regex to match against the relative path"},
+            "path": {"type": "string", "description": "Directory to search under, relative to the current folder (default '.')"},
+            "type": {"type": "string", "description": "Filter by 'file' or 'dir' (default: both)"},
+            "includeHidden": {"type": "boolean", "description": "Include dotfiles/dot-directories (default false)"},
+        },
+    },
+    execute=_execute,
+)

gencode_agent-1.0.0/src/gencode/tools/fsutil.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from typing import Iterator
+
+DEFAULT_IGNORES = [".git", "node_modules", "dist", "build", ".next", "coverage", ".venv", "__pycache__"]
+
+
+def glob_to_regex(pattern: str) -> re.Pattern[str]:
+    """Turn a glob (supports *, ?, **) into a regex for relative, forward-slash paths."""
+    p = pattern.replace("\\", "/")
+    out = ""
+    i = 0
+    while i < len(p):
+        c = p[i]
+        if c == "*":
+            if p[i + 1 : i + 2] == "*":
+                # "**" matches across path segments (including none)
+                i += 1
+                if p[i + 1 : i + 2] == "/":
+                    i += 1
+                out += "(?:.*/)?"
+            else:
+                out += "[^/]*"
+        elif c == "?":
+            out += "[^/]"
+        else:
+            out += re.escape(c)
+        i += 1
+    return re.compile(f"^{out}$")
+
+
+@dataclass
+class WalkEntry:
+    abs_path: str
+    rel_path: str
+    is_directory: bool
+
+
+def walk(
+    root: str,
+    max_depth: float = float("inf"),
+    include_hidden: bool = False,
+    ignores: list[str] | None = None,
+) -> Iterator[WalkEntry]:
+    """Depth-first walk yielding files and directories, sorted by name."""
+    ignores = DEFAULT_IGNORES if ignores is None else ignores
+
+    def recurse(directory: str, depth: int) -> Iterator[WalkEntry]:
+        try:
+            entries = sorted(os.scandir(directory), key=lambda e: e.name.lower())
+        except OSError:
+            return
+        for entry in entries:
+            if entry.name in ignores:
+                continue
+            if not include_hidden and entry.name.startswith("."):
+                continue
+            abs_path = os.path.join(directory, entry.name)
+            rel_path = os.path.relpath(abs_path, root).replace(os.sep, "/")
+            is_dir = entry.is_dir()
+            yield WalkEntry(abs_path, rel_path, is_dir)
+            if is_dir and depth < max_depth:
+                yield from recurse(abs_path, depth + 1)
+
+    yield from recurse(root, 1)
+
+
+def resolve_path(p: object) -> str:
+    return os.path.abspath(os.path.join(os.getcwd(), str(p)))

gencode_agent-1.0.0/src/gencode/tools/grep.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import os
+import re
+
+from ..types import Tool
+from .fsutil import glob_to_regex, resolve_path, walk
+
+MAX_MATCHES = 500
+MAX_FILE_BYTES = 5 * 1024 * 1024  # skip files bigger than 5MB
+
+
+def _execute(args: dict) -> str:
+    root = resolve_path(args.get("path") or ".")
+    max_matches = args["maxMatches"] if isinstance(args.get("maxMatches"), (int, float)) else MAX_MATCHES
+    glob_re = glob_to_regex(str(args["glob"])) if args.get("glob") else None
+    try:
+        regex = re.compile(str(args["pattern"]), re.IGNORECASE if args.get("ignoreCase") else 0)
+    except re.error as e:
+        return f"invalid regex: {e}"
+
+    # a single file is searched directly
+    if os.path.isfile(root):
+        entries = [(root, os.path.basename(root))]
+    else:
+        entries = ((e.abs_path, e.rel_path) for e in walk(root) if not e.is_directory)
+
+    results: list[str] = []
+    for abs_path, rel_path in entries:
+        if glob_re and not glob_re.match(rel_path):
+            continue
+        try:
+            if os.path.getsize(abs_path) > MAX_FILE_BYTES:
+                continue
+            with open(abs_path, "rb") as f:
+                data = f.read()
+        except OSError:
+            continue
+        if b"\x00" in data:  # skip binary files
+            continue
+        for i, line in enumerate(data.decode("utf-8", errors="replace").split("\n"), start=1):
+            if regex.search(line):
+                results.append(f"{rel_path}:{i}:{line.rstrip(chr(13))}")
+                if len(results) >= max_matches:
+                    results.append(f"[truncated at {int(max_matches)} matches]")
+                    return "\n".join(results)
+    return "\n".join(results) if results else "(no matches)"
+
+
+grep_tool = Tool(
+    name="grep",
+    description=(
+        "Search for a regex pattern inside files under a directory (recursively). "
+        "Returns matching file:line:text, like grep -rn."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "pattern": {"type": "string", "description": "Regex pattern to search for"},
+            "path": {"type": "string", "description": "Directory or file to search in, relative to the current folder (default '.')"},
+            "glob": {"type": "string", "description": "Only search files whose relative path matches this glob, e.g. '**/*.py'"},
+            "ignoreCase": {"type": "boolean", "description": "Case-insensitive search (default false)"},
+            "maxMatches": {"type": "number", "description": f"Max number of matches to return (default {MAX_MATCHES})"},
+        },
+        "required": ["pattern"],
+    },
+    execute=_execute,
+)

gencode_agent-1.0.0/src/gencode/tools/ls.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from ..types import Tool
+from .fsutil import resolve_path, walk
+
+LIMIT = 5000
+
+
+def _execute(args: dict) -> str:
+    root = resolve_path(args.get("path") or ".")
+    max_depth = args["maxDepth"] if isinstance(args.get("maxDepth"), (int, float)) else float("inf")
+    include_hidden = bool(args.get("includeHidden"))
+    dirs_only = bool(args.get("dirsOnly"))
+
+    lines: list[str] = []
+    for entry in walk(root, max_depth=max_depth, include_hidden=include_hidden):
+        if dirs_only and not entry.is_directory:
+            continue
+        lines.append(entry.rel_path + "/" if entry.is_directory else entry.rel_path)
+        if len(lines) >= LIMIT:
+            lines.append(f"[truncated at {LIMIT} entries]")
+            break
+    return "\n".join(lines) if lines else "(empty)"
+
+
+ls_tool = Tool(
+    name="ls",
+    description=(
+        "List files and directories recursively under a path. "
+        "Skips common noise dirs (.git, node_modules, dist, build, .venv) and hidden files by default."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Directory to list, relative to the current folder (default '.')"},
+            "maxDepth": {"type": "number", "description": "How many levels deep to recurse (default: unlimited)"},
+            "includeHidden": {"type": "boolean", "description": "Include dotfiles/dot-directories (default false)"},
+            "dirsOnly": {"type": "boolean", "description": "Only list directories (default false)"},
+        },
+    },
+    execute=_execute,
+)

gencode_agent-1.0.0/src/gencode/tools/read.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from ..types import Tool
+from .fsutil import resolve_path
+
+
+def _execute(args: dict) -> str:
+    with open(resolve_path(args["path"]), encoding="utf-8", errors="replace") as f:
+        return f.read()
+
+
+read_tool = Tool(
+    name="read",
+    description="Read a text file and returns its contents",
+    parameters={
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Path to the file, relative to the current folder"},
+        },
+        "required": ["path"],
+    },
+    execute=_execute,
+)

gencode_agent-1.0.0/src/gencode/tools/stat.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import os
+import stat as stat_mod
+from datetime import datetime, timezone
+
+from ..types import Tool
+from .fsutil import resolve_path
+
+
+def format_bytes(n: float) -> str:
+    if n < 1024:
+        return f"{int(n)} B"
+    for unit in ("KB", "MB", "GB", "TB"):
+        n /= 1024
+        if n < 1024 or unit == "TB":
+            return f"{n:.2f} {unit}"
+    return f"{n:.2f} TB"
+
+
+def _iso(ts: float) -> str:
+    return datetime.fromtimestamp(ts, tz=timezone.utc).isoformat()
+
+
+def _execute(args: dict) -> str:
+    target = resolve_path(args["path"])
+    s = os.stat(target)
+    kind = "directory" if stat_mod.S_ISDIR(s.st_mode) else "file" if stat_mod.S_ISREG(s.st_mode) else "other"
+    return "\n".join(
+        [
+            f"path: {target}",
+            f"type: {kind}",
+            f"size: {s.st_size} bytes ({format_bytes(s.st_size)})",
+            f"created: {_iso(s.st_ctime)}",
+            f"modified: {_iso(s.st_mtime)}",
+            f"accessed: {_iso(s.st_atime)}",
+            f"mode: {oct(s.st_mode & 0o777)[2:]}",
+        ]
+    )
+
+
+stat_tool = Tool(
+    name="stat",
+    description="Get metadata for a file or directory: size, type, created/modified times, permissions.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Path to the file or directory, relative to the current folder"},
+        },
+        "required": ["path"],
+    },
+    execute=_execute,
+)

gencode_agent-1.0.0/src/gencode/tools/write.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import os
+
+from ..types import Tool
+from .fsutil import resolve_path
+
+
+def _execute(args: dict) -> str:
+    if "content" not in args:
+        raise ValueError("missing 'content'")
+    target = resolve_path(args["path"])
+    os.makedirs(os.path.dirname(target), exist_ok=True)
+    content = str(args["content"])
+    with open(target, "w", encoding="utf-8", newline="\n") as f:
+        f.write(content)
+    return f"wrote {len(content.encode())} bytes to {args['path']}"
+
+
+write_tool = Tool(
+    name="write",
+    description="Create or overwrite a text file with the given content. Parent folders are created automatically.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Path to the file, relative to the current folder"},
+            "content": {"type": "string", "description": "The full file content"},
+        },
+        "required": ["path", "content"],
+    },
+    execute=_execute,
+)

gencode_agent-1.0.0/src/gencode/types.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Iterator, Literal, Protocol, Union
+
+StopReason = Literal["stop", "length", "toolUse"]
+
+
+@dataclass
+class Usage:
+    input: int = 0
+    output: int = 0
+
+
+@dataclass
+class TextBlock:
+    text: str
+    type: str = "text"
+
+
+@dataclass
+class ToolCallBlock:
+    id: str
+    name: str
+    arguments: dict[str, Any]
+    type: str = "toolCall"
+
+
+ContentBlock = Union[TextBlock, ToolCallBlock]
+
+
+@dataclass
+class UserMessage:
+    content: str
+    role: str = "user"
+
+
+@dataclass
+class AssistantMessage:
+    content: list[ContentBlock]
+    usage: Usage
+    stop_reason: StopReason
+    role: str = "assistant"
+
+
+@dataclass
+class ToolResultMessage:
+    tool_call_id: str
+    tool_name: str
+    content: str
+    is_error: bool
+    role: str = "toolResult"
+
+
+Message = Union[UserMessage, AssistantMessage, ToolResultMessage]
+
+
+@dataclass
+class Tool:
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    execute: Callable[[dict[str, Any]], str]
+
+
+# stream events
+@dataclass
+class TextDelta:
+    delta: str
+
+
+@dataclass
+class Done:
+    message: AssistantMessage
+
+
+StreamEvent = Union[TextDelta, Done]
+
+
+class Provider(Protocol):
+    name: str
+
+    def stream(
+        self,
+        messages: list[Message],
+        model: str,
+        system: str | None = None,
+        tools: list[Tool] | None = None,
+    ) -> Iterator[StreamEvent]: ...