kolega-code 0.4.0__tar.gz → 0.5.0__tar.gz

{kolega_code-0.4.0 → kolega_code-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kolega-code
-Version: 0.4.0
+Version: 0.5.0
 Summary: Local-first AI coding agent for the terminal
 Project-URL: Homepage, https://kolega-ai.github.io/kolega-code/
 Project-URL: Documentation, https://kolega-ai.github.io/kolega-code/

{kolega_code-0.4.0 → kolega_code-0.5.0}/docs/astro.config.mjs

@@ -44,7 +44,7 @@ export default defineConfig({
         {
           label: "Getting Started",
           items: [
-            { label: "Introduction", slug: "getting-started/introduction" },
+            { label: "Introduction", link: "/" },
             { label: "Installation", slug: "getting-started/installation" },
             { label: "Quick Start", slug: "getting-started/quick-start" },
           ],
@@ -93,6 +93,10 @@ export default defineConfig({
           label: "Hooks",
           items: [{ label: "Lifecycle Hooks", slug: "hooks" }],
         },
+        {
+          label: "Gigacode",
+          items: [{ label: "Workflow Orchestration", slug: "gigacode" }],
+        },
         {
           label: "How It Works",
           items: [

{kolega_code-0.4.0 → kolega_code-0.5.0}/docs/src/content/docs/concepts/agents.md

@@ -27,6 +27,10 @@ findings. The available dispatch targets include:
 - `dispatch_coding_agent` — hand off a self-contained coding task.
 - `dispatch_general_agent` — a general-purpose helper.
 
+When [gigacode](../../gigacode/) is enabled, the main agent can also orchestrate
+**many** of these sub-agents at once through a workflow — running them in parallel
+or in pipelines and collecting the results.
+
 Sub-agent activity is reported live. In the TUI each sub-agent gets a live card in
 the conversation, and pressing `Ctrl+G` opens the
 [sub-agent inspector](../../tui/interface/#sub-agent-inspector) — a full-screen view

kolega_code-0.5.0/docs/src/content/docs/gigacode.mdx

@@ -0,0 +1,108 @@
+---
+title: Gigacode
+description: Dynamic multi-agent workflow orchestration — fan out many sub-agents with one command.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+**Gigacode** lets the agent take on work that's too big for a single pass by
+**orchestrating many sub-agents at once**. When it's enabled and a task calls for
+it, the agent writes a small workflow that fans sub-agents out in parallel,
+pipelines them, or loops over them — then collects the results.
+
+It's built for work that's wide rather than deep:
+
+- Broad audits and multi-file reviews.
+- Large migrations or mechanical changes spread across many files.
+- Judge panels and adversarial verification, where several agents cross-check each
+  other.
+- Implementing a plan whose parts are independent, in parallel.
+
+For a quick question or a small, focused edit, the agent just does it directly —
+gigacode is for genuine fan-out.
+
+## Turning it on
+
+Gigacode is **off by default**. Toggle it with the `/gigacode`
+[slash command](../tui/slash-commands/):
+
+| Command | Effect |
+| --- | --- |
+| `/gigacode` | Toggle gigacode on or off |
+| `/gigacode on` | Enable workflow orchestration for the session |
+| `/gigacode off` | Disable it |
+
+Once on, it stays on for the session, and the agent decides when a task is worth
+orchestrating. It works in both [Build and Plan modes](../tui/modes/) — see
+[Behavior and safety](#behavior-and-safety) for how each differs.
+
+## What you'll see
+
+When the agent runs a workflow, the transcript shows **phase headers** and short
+**progress lines** as it works. Each sub-agent it launches appears in the
+[sub-agent inspector](../tui/interface/#sub-agent-inspector) — press `Ctrl+G` to
+watch every agent's live trajectory, grouped by phase.
+
+## How it works
+
+Under the hood, the agent authors a short **Python script** and runs it with a
+single `run_workflow` tool call. The script uses a handful of primitives:
+
+| Primitive | What it does |
+| --- | --- |
+| `agent(...)` | Dispatch one sub-agent and get its result back |
+| `parallel([...])` | Run several sub-agents at once and wait for all of them |
+| `pipeline(items, ...)` | Run each item through a series of stages independently |
+| `phase(...)` / `log(...)` | Report progress to the UI |
+
+You don't write these scripts — the agent does. A sketch of what it generates:
+
+```python
+# Review three areas in parallel, then synthesize.
+phase("Review")
+findings = await parallel([
+    (lambda area=area: agent(f"Review the {area} module for bugs"))
+    for area in ["auth", "api", "cli"]
+])
+return findings
+```
+
+<Aside type="note">
+Workflows are deterministic and **resumable**. Each run is saved under Kolega
+Code's state directory (`workflows/<run-id>/`) with its script, a journal, and each
+sub-agent's transcript, so an interrupted run can pick up where it left off instead
+of redoing finished work.
+</Aside>
+
+## Behavior and safety
+
+How workflow sub-agents behave depends on the mode you're in.
+
+**Plan mode** — every workflow sub-agent is **read-only** (an investigation agent),
+no matter what the workflow asks for. Use it to fan out parallel research and
+synthesis while planning; it never edits your code.
+
+**Build mode** — sub-agents have the full toolset and can edit files and run
+commands.
+
+<Aside type="caution" title="Workflows run unattended">
+In Build mode, workflow sub-agents run in **auto permission mode** — they execute
+shell commands and file edits **without prompting**, even when your session is set
+to `ask`. A workflow is a deliberate batch operation, and pausing dozens of
+parallel agents for individual approvals isn't practical. Keep this in mind before
+running a workflow for risky changes.
+</Aside>
+
+A few more guarantees:
+
+- Workflow sub-agents don't touch your [task list](../tui/modes/) — only the main
+  agent manages it, so agents running in parallel can't clobber it.
+- Concurrency is capped, and there's a hard ceiling on the total number of agents a
+  single workflow can spawn, as a runaway-loop backstop.
+
+## See also
+
+- [Build & Plan Modes](../tui/modes/) — how modes shape what agents can do.
+- [Agents](../concepts/agents/) — the sub-agent types a workflow draws on.
+- [Slash Commands](../tui/slash-commands/) — the full command reference.
+- [Interface Tour](../tui/interface/#sub-agent-inspector) — the sub-agent inspector.

kolega_code-0.4.0/docs/src/content/docs/getting-started/introduction.md → kolega_code-0.5.0/docs/src/content/docs/index.mdx

@@ -24,8 +24,11 @@ and your sessions, settings, and API keys are stored on your own machine.
 - **Dispatches sub-agents.** For larger tasks, the main agent can hand off to
   specialized agents (investigation, browser, coding, general) and track their
   activity live.
+- **Orchestrates workflows.** With [gigacode](gigacode/), the agent can fan out
+  many sub-agents in parallel — for broad audits, large migrations, or
+  implementing a plan's independent parts at once.
 - **Works non-interactively too.** Run a single prompt with
-  [`kolega-code ask`](../../cli/ask/), get JSON output, and save or resume
+  [`kolega-code ask`](cli/ask/), get JSON output, and save or resume
   sessions.
 
 ## Two ways to use it
@@ -36,8 +39,8 @@ and your sessions, settings, and API keys are stored on your own machine.
 | **One-shot** | `kolega-code ask "…"` | Scripting, automation, quick questions, CI |
 
 There are also helper commands for managing
-[sessions](../../cli/sessions/) and checking your
-[configuration](../../cli/doctor/).
+[sessions](cli/sessions/) and checking your
+[configuration](cli/doctor/).
 
 ## Bring your own model
 
@@ -45,7 +48,7 @@ Kolega Code talks to a range of LLM providers — including Anthropic, OpenAI,
 Google, Moonshot, and DeepSeek — and lets you assign **different models to
 different roles** (a strong long-context model for coding, a fast cheap model for
 small utility calls, and one for extended "thinking"). See
-[Providers & Models](../../configuration/providers-and-models/).
+[Providers & Models](configuration/providers-and-models/).
 
 ## What you need
 
@@ -53,5 +56,31 @@ small utility calls, and one for extended "thinking"). See
 - An **API key** for at least one supported provider
 - A terminal that supports a modern TUI (most do)
 
-Head to [Installation](../installation/) to set it up, then the
-[Quick Start](../quick-start/) to run your first session.
+## Install
+
+Install with the script:
+
+```bash
+curl -fsSL https://kolega.dev/install-kolega-code.sh | sh
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install kolega-code
+```
+
+Verify the install and start a session in your project:
+
+```bash
+kolega-code --version
+kolega-code .
+```
+
+See [Installation](getting-started/installation/) for requirements, other install
+methods, and upgrade/uninstall commands.
+
+## Next steps
+
+Once you're installed and have a provider key set, head to the
+[Quick Start](getting-started/quick-start/) to run your first session.

{kolega_code-0.4.0 → kolega_code-0.5.0}/docs/src/content/docs/tui/modes.md

@@ -22,6 +22,10 @@ default to `ask`, so shell commands and file edits prompt before they run. Press
 When you choose an “always allow” approval, Kolega Code stores the local rule in
 `.kolega/permissions.json` for that project.
 
+If [gigacode](../../gigacode/) is enabled, the sub-agents inside a workflow run in
+`auto` permission mode regardless of this setting — see
+[Behavior and safety](../../gigacode/#behavior-and-safety).
+
 ## Plan mode
 
 A **read-only** planning pass. Plan mode uses a standalone planning agent that does
@@ -39,7 +43,9 @@ happens next — typically to **implement the plan** or to **keep discussing** i
 The decision is presented as a vertical, arrow-key-selectable option list.
 
 Use Plan mode when a change is non-trivial and you want to agree on the approach
-before any files are touched.
+before any files are touched. With [gigacode](../../gigacode/) on, a planning agent
+can fan out parallel research across the codebase; those workflow sub-agents stay
+read-only too.
 
 ## A typical loop
 

{kolega_code-0.4.0 → kolega_code-0.5.0}/docs/src/content/docs/tui/slash-commands.md

@@ -40,6 +40,7 @@ These control the app and your session.
 | `/permissions` | Show or switch the shell/edit permission mode |
 | `/model` | Choose the active model |
 | `/effort` | Choose the active model's thinking effort |
+| `/gigacode` | Toggle [gigacode](../../gigacode/) workflow orchestration on or off |
 | `/copy` | Copy the last response to the clipboard |
 | `/version` | Show the Kolega Code version |
 | `/update` | Update Kolega Code to the latest version |

{kolega_code-0.4.0 → kolega_code-0.5.0}/kolega_code/__init__.py

@@ -148,4 +148,4 @@ __all__ = [
     "parse_git_status_output",
 ]
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"

{kolega_code-0.4.0 → kolega_code-0.5.0}/kolega_code/agent/__init__.py

@@ -39,4 +39,4 @@ __all__ = [
     "ToolExtension",
 ]
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"

{kolega_code-0.4.0 → kolega_code-0.5.0}/kolega_code/agent/baseagent.py

@@ -231,6 +231,11 @@ class BaseAgent(LogMixin):
         self.usage_recorder = context.telemetry.usage_recorder
         self.sub_agent_recorder = context.telemetry.sub_agent_recorder
 
+        # gigacode (workflow orchestration) opt-in. Off by default; the host toggles
+        # it via apply_gigacode(). The run_workflow tool gate reads this live, so
+        # toggling takes effect on the next turn without rebuilding the agent.
+        self.gigacode_enabled = False
+
         self.available_ports = "9001-9999"
 
         # Validate that the project path exists and is a directory using the filesystem
@@ -364,6 +369,22 @@ class BaseAgent(LogMixin):
         """Serializes the message history into a list of dictionaries using custom methods."""
         return self.conversation.dump()
 
+    def apply_gigacode(self, enabled: bool, prompt_extension=None) -> None:
+        """Enable or disable gigacode workflow orchestration for this session.
+
+        Flips the ``run_workflow`` tool gate and refreshes the system prompt to
+        include or drop the authoring guide. Safe to call mid-session; the tool
+        registry and the next turn pick up the change.
+        """
+        self.gigacode_enabled = enabled
+        extensions = [ext for ext in (self.prompt_extensions or []) if getattr(ext, "id", None) != "gigacode"]
+        if enabled and prompt_extension is not None:
+            extensions.append(prompt_extension)
+        self.prompt_extensions = extensions
+        initialize = getattr(self, "_initialize_system_prompt", None)
+        if callable(initialize):
+            initialize()
+
     def restore_message_history(self, serialized_history: List[Dict[str, Any]]) -> None:
         """Restores the message history from a list of dictionaries using custom methods."""
         self.conversation.restore(serialized_history)

kolega_code-0.5.0/kolega_code/agent/orchestration/__init__.py

@@ -0,0 +1,46 @@
+"""gigacode — dynamic multi-agent workflow orchestration.
+
+A workflow is a short authored Python script whose primitives (``agent``,
+``parallel``, ``pipeline``, ``phase``, ``log``) fan out sub-agents with real
+control flow. The pieces:
+
+- :mod:`executor`  — validate ``meta``, wrap the body, run it in a curated namespace
+- :mod:`runtime`   — the primitives, concurrency caps, and resume
+- :mod:`budget`    — token ceiling shared across the run
+- :mod:`journal`   — state-dir artifacts and the resume journal
+- :mod:`types`     — the dispatch/emit interface the production adapter implements
+"""
+
+from .budget import Budget
+from .errors import (
+    WorkflowAgentCapExceeded,
+    WorkflowBudgetExceeded,
+    WorkflowError,
+    WorkflowScriptError,
+)
+from .executor import extract_meta, run_script, safe_builtins
+from .journal import RunJournal, saved_workflows_dir, workflows_root
+from .runtime import DEFAULT_AGENT_CAP, MAX_FANOUT, WorkflowRuntime, default_concurrency
+from .types import AgentRunResult, AgentRunSpec, DispatchFn, EmitFn
+
+__all__ = [
+    "Budget",
+    "WorkflowError",
+    "WorkflowScriptError",
+    "WorkflowBudgetExceeded",
+    "WorkflowAgentCapExceeded",
+    "extract_meta",
+    "run_script",
+    "safe_builtins",
+    "RunJournal",
+    "workflows_root",
+    "saved_workflows_dir",
+    "WorkflowRuntime",
+    "default_concurrency",
+    "MAX_FANOUT",
+    "DEFAULT_AGENT_CAP",
+    "AgentRunSpec",
+    "AgentRunResult",
+    "DispatchFn",
+    "EmitFn",
+]

kolega_code-0.5.0/kolega_code/agent/orchestration/budget.py

@@ -0,0 +1,46 @@
+"""Token budget for a workflow run.
+
+Mirrors the ultracode ``budget`` global: a hard ceiling on output tokens spent
+across every sub-agent the run dispatches. ``total`` of ``None`` means unbounded
+(``remaining()`` is ``inf``), which is the common case when no ``+Nk`` directive
+was given.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Union
+
+from .errors import WorkflowBudgetExceeded
+
+
+class Budget:
+    """Aggregate token accounting shared across all agents in a run."""
+
+    def __init__(self, total: Optional[int] = None) -> None:
+        self.total: Optional[int] = total
+        self._spent: int = 0
+
+    def add(self, tokens: Optional[int]) -> None:
+        """Fold one sub-agent's token usage into the running total."""
+        try:
+            self._spent += max(0, int(tokens or 0))
+        except (TypeError, ValueError):
+            # Defensive: a provider that doesn't report usage shouldn't crash a run.
+            pass
+
+    def spent(self) -> int:
+        """Output tokens spent so far across the whole run."""
+        return self._spent
+
+    def remaining(self) -> Union[int, float]:
+        """Tokens left before the ceiling, or ``inf`` when unbounded."""
+        if self.total is None:
+            return float("inf")
+        return max(0, self.total - self._spent)
+
+    def check(self) -> None:
+        """Raise if the ceiling has been reached. Called before each dispatch."""
+        if self.total is not None and self._spent >= self.total:
+            raise WorkflowBudgetExceeded(
+                f"workflow token budget exhausted: spent {self._spent} of {self.total}"
+            )

kolega_code-0.5.0/kolega_code/agent/orchestration/errors.py

@@ -0,0 +1,22 @@
+"""Exceptions raised by the gigacode workflow runtime."""
+
+
+class WorkflowError(RuntimeError):
+    """Base class for all workflow orchestration failures."""
+
+
+class WorkflowScriptError(WorkflowError):
+    """The authored script is malformed or used a primitive incorrectly.
+
+    Raised for problems the model can fix by rewriting the script: a missing or
+    non-literal ``meta`` block, a non-string prompt, an over-large fan-out, or an
+    illegally nested ``workflow()`` call.
+    """
+
+
+class WorkflowBudgetExceeded(WorkflowError):
+    """The run reached its token budget ceiling; further ``agent()`` calls abort."""
+
+
+class WorkflowAgentCapExceeded(WorkflowError):
+    """The run exceeded the lifetime agent-count backstop (runaway-loop guard)."""

kolega_code-0.5.0/kolega_code/agent/orchestration/executor.py

@@ -0,0 +1,118 @@
+"""Load and run an authored Python orchestration script.
+
+The script runs in-process in a *curated namespace*: a restricted ``__builtins__``
+(no ``import``/``open``/``eval``/``exec``, no ``time``/``random`` so resume stays
+deterministic) plus the injected primitives (``agent``/``parallel``/``pipeline``/
+``phase``/``log``/``workflow``) and the ``args``/``budget`` globals.
+
+This is a *soft* sandbox, not a security boundary — the agent already runs
+arbitrary shell via its command tools. The restrictions exist to keep scripts
+deterministic (a hard requirement for resume) and to fail loudly on the easy
+mistakes rather than to contain a hostile script.
+"""
+
+from __future__ import annotations
+
+import ast
+import builtins
+from typing import Any, Dict
+
+from .errors import WorkflowScriptError
+
+WRAPPER_NAME = "__workflow_main__"
+
+# Builtins the script may use. Deliberately omits __import__, open, eval, exec,
+# compile, input, and the time/random surface. __build_class__ is included so a
+# script that defines a helper class doesn't crash.
+_SAFE_BUILTIN_NAMES = (
+    "abs", "all", "any", "ascii", "bin", "bool", "bytearray", "bytes", "callable",
+    "chr", "dict", "divmod", "enumerate", "filter", "float", "format", "frozenset",
+    "getattr", "hasattr", "hash", "hex", "int", "isinstance", "issubclass", "iter",
+    "len", "list", "map", "max", "min", "next", "oct", "ord", "pow", "range",
+    "repr", "reversed", "round", "set", "setattr", "slice", "sorted", "str", "sum",
+    "tuple", "type", "zip",
+    # exception types scripts may raise/catch
+    "Exception", "ValueError", "KeyError", "IndexError", "TypeError", "RuntimeError",
+    "StopIteration", "StopAsyncIteration", "ArithmeticError", "ZeroDivisionError",
+    "AttributeError", "NotImplementedError", "AssertionError",
+    # class definition support
+    "__build_class__",
+)
+
+
+def safe_builtins() -> Dict[str, Any]:
+    """A restricted ``__builtins__`` mapping for workflow script execution."""
+    table: Dict[str, Any] = {name: getattr(builtins, name) for name in _SAFE_BUILTIN_NAMES if hasattr(builtins, name)}
+    table["True"] = True
+    table["False"] = False
+    table["None"] = None
+    return table
+
+
+def extract_meta(source: str) -> Dict[str, Any]:
+    """Parse and validate the module-level ``meta = {...}`` literal.
+
+    Mirrors the ultracode rule that ``meta`` must be a pure literal (no variables,
+    calls, or interpolation) so it can be read without executing the script.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as exc:
+        raise WorkflowScriptError(f"workflow script has a syntax error: {exc}") from exc
+
+    for node in tree.body:
+        if isinstance(node, ast.Assign):
+            for target in node.targets:
+                if isinstance(target, ast.Name) and target.id == "meta":
+                    try:
+                        value = ast.literal_eval(node.value)
+                    except (ValueError, SyntaxError) as exc:
+                        raise WorkflowScriptError(
+                            "`meta` must be a pure literal dict (no variables, calls, or f-strings)."
+                        ) from exc
+                    if not isinstance(value, dict):
+                        raise WorkflowScriptError("`meta` must be a dict literal.")
+                    if not value.get("name") or not value.get("description"):
+                        raise WorkflowScriptError("`meta` must include non-empty `name` and `description`.")
+                    return value
+
+    raise WorkflowScriptError(
+        "workflow script must define a top-level `meta = {\"name\": ..., \"description\": ...}` literal."
+    )
+
+
+def _wrap_as_coroutine(source: str) -> ast.Module:
+    """Wrap the whole script body in an ``async def`` so top-level ``await`` and
+    ``return`` are legal. Done at the AST level (not by text indentation) so
+    multi-line string literals are never corrupted.
+    """
+    tree = ast.parse(source)
+    func = ast.AsyncFunctionDef(
+        name=WRAPPER_NAME,
+        args=ast.arguments(
+            posonlyargs=[], args=[], vararg=None, kwonlyargs=[], kw_defaults=[], kwarg=None, defaults=[]
+        ),
+        body=tree.body or [ast.Pass()],
+        decorator_list=[],
+        returns=None,
+        type_comment=None,
+    )
+    module = ast.Module(body=[func], type_ignores=[])
+    ast.fix_missing_locations(module)
+    return module
+
+
+async def run_script(source: str, namespace: Dict[str, Any]) -> Any:
+    """Compile and run ``source`` in ``namespace``; return the script's value.
+
+    ``namespace`` must already carry ``__builtins__`` and the injected globals.
+    """
+    try:
+        module = _wrap_as_coroutine(source)
+        code = compile(module, "<workflow>", "exec")
+    except SyntaxError as exc:
+        raise WorkflowScriptError(f"workflow script has a syntax error: {exc}") from exc
+
+    exec(code, namespace)  # noqa: S102 - curated namespace; see module docstring
+    main = namespace[WRAPPER_NAME]
+    return await main()