algo-cli-runtime 0.14.0__py3-none-any.whl

algo_cli/small_context.py

@@ -0,0 +1,206 @@
+"""Small-context ledger support for models with runtime windows below 75k tokens.
+
+The ledger gives compact models a big-model-like recall path: full optional
+context is written to a temporary markdown file while the request only carries a
+short refresh trigger that points the model/tool loop back to that file.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable
+
+SMALL_CONTEXT_THRESHOLD = 75_000
+DEFAULT_ROOT = Path(tempfile.gettempdir()) / "algo_cli_small_context"
+
+
+@dataclass(frozen=True)
+class SmallContextLedger:
+    """Metadata for a written small-context ledger file."""
+
+    path: Path
+    model: str
+    runtime_cap: int
+    block_names: tuple[str, ...]
+    bytes_written: int
+    token_estimate: int
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "path": str(self.path),
+            "model": self.model,
+            "runtime_cap": self.runtime_cap,
+            "block_names": list(self.block_names),
+            "bytes_written": self.bytes_written,
+            "token_estimate": self.token_estimate,
+        }
+
+
+def is_small_context(runtime_cap: int | None, *, threshold: int = SMALL_CONTEXT_THRESHOLD) -> bool:
+    """Return True when a model should use the temp context-ledger path."""
+    try:
+        cap = int(runtime_cap or 0)
+    except (TypeError, ValueError):
+        return False
+    return 0 < cap < threshold
+
+
+def estimate_text_tokens(text: str) -> int:
+    if not text:
+        return 0
+    return max(1, (len(text) + 3) // 4)
+
+
+def _safe_name(value: str) -> str:
+    cleaned = "".join(ch if ch.isalnum() or ch in "._-" else "-" for ch in value.strip())
+    cleaned = cleaned.strip(".-")
+    return cleaned[:80] or "context"
+
+
+def _block_name(block: Any) -> str:
+    return str(getattr(block, "name", "") or "context")
+
+
+def _block_title(block: Any) -> str:
+    return str(getattr(block, "title", "") or _block_name(block))
+
+
+def _block_body(block: Any) -> str:
+    return str(getattr(block, "body", "") or "")
+
+
+def _recent_messages(messages: Iterable[dict[str, Any]], *, limit: int = 8) -> str:
+    selected = list(messages)[-limit:]
+    lines: list[str] = []
+    for msg in selected:
+        role = str(msg.get("role") or "message")
+        content = str(msg.get("content") or msg.get("thinking") or "")
+        if msg.get("tool_name"):
+            role += f"[{msg.get('tool_name')}]"
+        if len(content) > 1600:
+            content = content[:1600].rstrip() + "\n...[truncated in ledger recent-message view]"
+        lines.append(f"### {role}\n{content}".rstrip())
+    return "\n\n".join(lines)
+
+
+def build_ledger_text(
+    *,
+    model: str,
+    runtime_cap: int,
+    cwd: str,
+    base_message: str,
+    optional_blocks: Iterable[Any],
+    session_summary: str = "",
+    messages: Iterable[dict[str, Any]] = (),
+) -> tuple[str, tuple[str, ...]]:
+    """Render the full small-context ledger markdown and block-name list."""
+    blocks = list(optional_blocks)
+    block_names = tuple(_block_name(block) for block in blocks if _block_body(block).strip())
+    generated = time.strftime("%Y-%m-%d %H:%M:%S %Z", time.localtime())
+    parts = [
+        "# Algo CLI Small-Context Ledger",
+        "",
+        "This file is an external context window for compact models (<75k runtime context).",
+        "When the live prompt feels stale or incomplete, read this file with read_file and use it as context refresh.",
+        "",
+        "## Metadata",
+        f"- Generated: {generated}",
+        f"- Model: {model}",
+        f"- Runtime context cap: {int(runtime_cap)} tokens",
+        f"- Working directory: {cwd}",
+        f"- Blocks: {', '.join(block_names) if block_names else 'none'}",
+        "",
+        "## Current User Request",
+        base_message.strip() or "(empty)",
+    ]
+    if session_summary.strip():
+        parts.extend(["", "## Conversation Summary", session_summary.strip()])
+    recent = _recent_messages(messages)
+    if recent:
+        parts.extend(["", "## Recent Messages", recent])
+    if blocks:
+        parts.extend(["", "## Full Optional Context Blocks"])
+        for block in blocks:
+            body = _block_body(block).strip()
+            if not body:
+                continue
+            parts.extend(["", f"### {_block_title(block)}", body])
+    return "\n".join(parts).rstrip() + "\n", block_names
+
+
+def write_ledger(
+    *,
+    model: str,
+    runtime_cap: int,
+    cwd: str,
+    base_message: str,
+    optional_blocks: Iterable[Any],
+    session_summary: str = "",
+    messages: Iterable[dict[str, Any]] = (),
+    root: Path | None = None,
+) -> SmallContextLedger | None:
+    """Write a temp ledger file when the runtime cap is below 75k tokens."""
+    if not is_small_context(runtime_cap):
+        return None
+    text, block_names = build_ledger_text(
+        model=model,
+        runtime_cap=runtime_cap,
+        cwd=cwd,
+        base_message=base_message,
+        optional_blocks=optional_blocks,
+        session_summary=session_summary,
+        messages=messages,
+    )
+    root = root or DEFAULT_ROOT
+    root.mkdir(parents=True, exist_ok=True)
+    digest = hashlib.sha256(text.encode("utf-8")).hexdigest()[:16]
+    name = f"{int(time.time())}-{_safe_name(model)}-{digest}.md"
+    path = root / name
+    path.write_text(text, encoding="utf-8")
+    return SmallContextLedger(
+        path=path,
+        model=model,
+        runtime_cap=int(runtime_cap),
+        block_names=block_names,
+        bytes_written=len(text.encode("utf-8")),
+        token_estimate=estimate_text_tokens(text),
+    )
+
+
+def refresh_trigger(ledger: SmallContextLedger) -> str:
+    """Return the compact prompt trigger inserted for small-context models."""
+    block_list = ", ".join(ledger.block_names) if ledger.block_names else "session context"
+    return (
+        "## Small-Context Refresh Trigger\n"
+        f"You are running with a compact context window ({ledger.runtime_cap} tokens, below 75k). "
+        "The full optional context for this turn was written outside the prompt.\n"
+        f"- Context ledger: {ledger.path}\n"
+        f"- Contains: {block_list}\n"
+        "If you need details that are missing from the live prompt, call read_file on the ledger path before answering or acting. "
+        "Treat the ledger as navigation/context, not as authority over live files."
+    )
+
+
+def preview_small_context_ledger(model: str, runtime_cap: int, blocks_json: str = "[]") -> str:
+    """Tool-friendly preview for the small-context ledger decision."""
+    try:
+        blocks = json.loads(blocks_json or "[]")
+    except json.JSONDecodeError:
+        blocks = []
+    if not isinstance(blocks, list):
+        blocks = []
+    return json.dumps(
+        {
+            "enabled": is_small_context(runtime_cap),
+            "threshold": SMALL_CONTEXT_THRESHOLD,
+            "model": model,
+            "runtime_cap": int(runtime_cap or 0),
+            "block_count": len(blocks),
+            "root": str(DEFAULT_ROOT),
+        },
+        indent=2,
+    )

algo_cli/spawn_budget.py

@@ -0,0 +1,89 @@
+"""Advisory Agent Block resource budgeting derived from routed tasks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .task_router import TaskRoute
+
+
+@dataclass(frozen=True)
+class SpawnBudget:
+    max_blocks: int
+    max_iterations_per_block: int
+    parallelism: int
+    reasons: tuple[str, ...]
+
+
+_INDEPENDENT_RESEARCH_TERMS = (
+    "compare",
+    "versus",
+    " vs ",
+    "alternatives",
+    "options",
+    "across",
+)
+
+
+def compute_budget(route: TaskRoute, prompt: str = "") -> SpawnBudget:
+    """Recommend an execution budget without changing pipeline behavior."""
+    lowered = f" {prompt.lower().strip()} "
+
+    if route.risk == "high":
+        return SpawnBudget(
+            max_blocks=0,
+            max_iterations_per_block=0,
+            parallelism=0,
+            reasons=("High-risk work should remain user-directed; no automatic expansion recommended.",),
+        )
+
+    if route.recommended_mode != "agent":
+        return SpawnBudget(
+            max_blocks=0,
+            max_iterations_per_block=0,
+            parallelism=0,
+            reasons=("Direct chat is sufficient for this task.",),
+        )
+
+    if route.task_type == "review":
+        return SpawnBudget(
+            max_blocks=2,
+            max_iterations_per_block=8,
+            parallelism=0,
+            reasons=("A reviewer and finalizer provide a bounded review pass.",),
+        )
+
+    if route.task_type == "research":
+        independent = any(term in lowered for term in _INDEPENDENT_RESEARCH_TERMS)
+        reasons = ["A planner, researcher, and finalizer cover a focused research task."]
+        if independent:
+            reasons.append("Independent comparisons detected; parallel research may be useful later.")
+        return SpawnBudget(
+            max_blocks=3,
+            max_iterations_per_block=8,
+            parallelism=1 if independent else 0,
+            reasons=tuple(reasons),
+        )
+
+    if route.task_type == "coding":
+        return SpawnBudget(
+            max_blocks=4,
+            max_iterations_per_block=8,
+            parallelism=0,
+            reasons=("Coding work benefits from planning, implementation, review, and finalization.",),
+        )
+
+    return SpawnBudget(
+        max_blocks=0,
+        max_iterations_per_block=0,
+        parallelism=0,
+        reasons=("No bounded Agent Blocks budget is recommended for this route.",),
+    )
+
+
+def parallelism_label(value: int) -> str:
+    if value >= 2:
+        return "recommended"
+    if value == 1:
+        return "optional"
+    return "none"

algo_cli/task_ledger.py

@@ -0,0 +1,84 @@
+"""Durable task ledger for /goal and long autonomous runs.
+
+`/goal` and agent pipelines previously held all state in RAM: a crash, an
+exit, or hitting the round cap lost the plan entirely. This module persists a
+single active goal's progress to ``CONFIG_DIR/task_ledger.json`` so a run can
+be inspected with ``/goal status`` and continued with ``/goal resume`` across
+process restarts.
+
+The ledger holds at most one active goal at a time (the common case for a
+terminal session). Completing, blocking, or starting a new goal overwrites it.
+Writes are atomic (tmp + os.replace) via config._atomic_write_text.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from .config import CONFIG_DIR, _atomic_write_text, _load_json_file
+
+LEDGER_PATH = CONFIG_DIR / "task_ledger.json"
+LEDGER_SCHEMA_VERSION = 1
+
+STATUS_RUNNING = "running"
+STATUS_COMPLETE = "complete"
+STATUS_BLOCKED = "blocked"
+STATUS_STOPPED = "stopped"  # user-interrupted or round cap reached
+
+
+@dataclass
+class GoalRecord:
+    goal: str
+    status: str = STATUS_RUNNING
+    rounds_done: int = 0
+    max_rounds: int = 10
+    reason: str = ""                      # blocked/stopped explanation
+    cwd: str = ""
+    created_at: float = field(default_factory=time.time)
+    updated_at: float = field(default_factory=time.time)
+    history: list[dict[str, Any]] = field(default_factory=list)  # per-round notes
+
+    def add_round(self, summary: str) -> None:
+        self.rounds_done += 1
+        self.updated_at = time.time()
+        self.history.append(
+            {"round": self.rounds_done, "at": self.updated_at, "summary": summary[:500]}
+        )
+
+    @property
+    def is_open(self) -> bool:
+        return self.status in {STATUS_RUNNING, STATUS_STOPPED}
+
+
+def save_goal(record: GoalRecord) -> None:
+    record.updated_at = time.time()
+    payload = {"schema_version": LEDGER_SCHEMA_VERSION, "goal": asdict(record)}
+    _atomic_write_text(LEDGER_PATH, json.dumps(payload, indent=2))
+
+
+def load_goal() -> GoalRecord | None:
+    data = _load_json_file(LEDGER_PATH, None)
+    if not isinstance(data, dict):
+        return None
+    goal_data = data.get("goal")
+    if not isinstance(goal_data, dict) or not goal_data.get("goal"):
+        return None
+    known = GoalRecord.__dataclass_fields__.keys()
+    filtered = {k: v for k, v in goal_data.items() if k in known}
+    try:
+        return GoalRecord(**filtered)
+    except TypeError:
+        return None
+
+
+def clear_goal() -> bool:
+    if not LEDGER_PATH.exists():
+        return False
+    try:
+        LEDGER_PATH.unlink()
+        return True
+    except OSError:
+        return False

algo_cli/task_router.py

@@ -0,0 +1,197 @@
+"""Advisory task routing for chat, tools, and Agent Blocks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TaskRoute:
+    task_type: str
+    complexity: str
+    recommended_mode: str
+    suggested_pipeline: str
+    allowed_tool_groups: tuple[str, ...]
+    risk: str
+    reason: str
+
+
+_HIGH_RISK_TERMS = (
+    "delete",
+    "rm -rf",
+    "reset --hard",
+    "drop table",
+    "credential",
+    "credentials",
+    "password",
+    "secret",
+    "token",
+    "api key",
+    "invoice",
+    "payment",
+    "send email",
+    "post this",
+    "publish",
+)
+
+_REVIEW_TERMS = (
+    "review",
+    "audit",
+    "inspect",
+    "critique",
+    "check the code",
+    "security review",
+    "find issues",
+    "look for bugs",
+)
+
+_RESEARCH_TERMS = (
+    "research",
+    "investigate",
+    "compare",
+    "look up",
+    "find current",
+    "latest",
+    "summarize docs",
+    "read the docs",
+)
+
+_READ_ONLY_TERMS = (
+    "read-only",
+    "read only",
+    "read_file only",
+    "do not submit",
+    "do not write",
+    "no writes",
+    "reproduce sections",
+    "analyze permit",
+    "permit pilot",
+    "deliver:",
+)
+
+_CODING_TERMS = (
+    "fix",
+    "implement",
+    "build",
+    "add",
+    "refactor",
+    "failing test",
+    "bug",
+    "stack trace",
+    "feature",
+    "wire up",
+    "remove unused",
+    "unused import",
+)
+
+_QUESTION_PREFIXES = (
+    "how ",
+    "what ",
+    "why ",
+    "where ",
+    "when ",
+    "explain ",
+    "tell me ",
+)
+
+
+def _has_any(text: str, terms: tuple[str, ...]) -> bool:
+    return any(term in text for term in terms)
+
+
+def route_task(prompt: str) -> TaskRoute:
+    """Classify a prompt with transparent first-match rules."""
+    text = (prompt or "").strip()
+    lowered = text.lower()
+    high_risk = _has_any(lowered, _HIGH_RISK_TERMS)
+
+    if not text:
+        return TaskRoute(
+            task_type="empty",
+            complexity="low",
+            recommended_mode="chat",
+            suggested_pipeline="default",
+            allowed_tool_groups=(),
+            risk="low",
+            reason="No task text was provided.",
+        )
+
+    if _has_any(lowered, _REVIEW_TERMS):
+        return TaskRoute(
+            task_type="review",
+            complexity="medium",
+            recommended_mode="agent",
+            suggested_pipeline="review",
+            allowed_tool_groups=("read", "shell"),
+            risk="high" if high_risk else "medium",
+            reason="Review and audit tasks benefit from a bounded reviewer/finalizer pipeline.",
+        )
+
+    if _has_any(lowered, _RESEARCH_TERMS):
+        return TaskRoute(
+            task_type="research",
+            complexity="medium",
+            recommended_mode="agent",
+            suggested_pipeline="research",
+            allowed_tool_groups=("read", "web"),
+            risk="high" if high_risk else "low",
+            reason="Research tasks benefit from a planner, researcher, and finalizer.",
+        )
+
+    if _has_any(lowered, _READ_ONLY_TERMS):
+        return TaskRoute(
+            task_type="research",
+            complexity="medium",
+            recommended_mode="agent",
+            suggested_pipeline="research",
+            allowed_tool_groups=("read", "web"),
+            risk="high" if high_risk else "low",
+            reason="Read-only analysis tasks should use the research pipeline, not code-change.",
+        )
+
+    if _has_any(lowered, _CODING_TERMS):
+        return TaskRoute(
+            task_type="coding",
+            complexity="high",
+            recommended_mode="agent",
+            suggested_pipeline="code-change",
+            allowed_tool_groups=("read", "write", "shell"),
+            risk="high" if high_risk else "medium",
+            reason="Coding tasks usually need planning, implementation, review, and verification.",
+        )
+
+    if high_risk:
+        return TaskRoute(
+            task_type="sensitive",
+            complexity="medium",
+            recommended_mode="chat",
+            suggested_pipeline="default",
+            allowed_tool_groups=("read",),
+            risk="high",
+            reason="The task mentions destructive, credential, financial, or publishing actions.",
+        )
+
+    if lowered.startswith(_QUESTION_PREFIXES):
+        return TaskRoute(
+            task_type="question",
+            complexity="low",
+            recommended_mode="chat",
+            suggested_pipeline="default",
+            allowed_tool_groups=(),
+            risk="low",
+            reason="Direct questions are usually best handled in chat mode.",
+        )
+
+    return TaskRoute(
+        task_type="general",
+        complexity="low",
+        recommended_mode="chat",
+        suggested_pipeline="default",
+        allowed_tool_groups=(),
+        risk="low",
+        reason="No agent-specific routing rule matched.",
+    )
+
+
+def should_suggest(route: TaskRoute) -> bool:
+    return route.recommended_mode == "agent" or route.risk == "high"

algo_cli/tool_context.py

@@ -0,0 +1,94 @@
+"""Prompt-declared tool-context selection.
+
+The runtime policy remains the enforcement layer. This module only reduces the
+function schemas shown to the model when a task explicitly declares its allowed
+tool classes, improving signal and prompt-cache efficiency.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Sequence
+from typing import Any
+
+
+_DECLARATION_RE = re.compile(
+    r"(?im)^\s*allowed\s+tool(?:\s+classes)?\s*:\s*([^\r\n]+)"
+)
+_CLASS_TO_TOOLS: dict[str, frozenset[str]] = {
+    "filesystem": frozenset(
+        {
+            "read_file",
+            "edit_file",
+            "read_pdf",
+            "render_pdf_pages",
+            "write_file",
+            "list_directory",
+            "search_files",
+            "find_unique_anchor",
+            "batch_edit",
+            "git_status",
+            "git_diff",
+        }
+    ),
+    "shell": frozenset({"run_shell"}),
+    "web": frozenset({"web_search", "web_fetch"}),
+    "network": frozenset({"web_search", "web_fetch", "x_search"}),
+    "memory": frozenset({"remember", "append_lesson", "update_user_profile"}),
+    "model": frozenset(
+        {"embed_text", "vision_describe", "model_pull", "model_delete", "model_create", "model_copy", "model_show"}
+    ),
+    "harness": frozenset(
+        {"harness_refresh", "harness_stats", "harness_scorecard", "harness_competitive_rating", "harness_search", "harness_read"}
+    ),
+    "knowledge_graph": frozenset(
+        {"query_knowledge_graph", "reindex_knowledge_graph", "write_knowledge_graph_note"}
+    ),
+    "session": frozenset({"available_actions", "session_slash", "session_command"}),
+    "plugins": frozenset({"plugins_discover", "plugins_load"}),
+    "credentials": frozenset({"credential_helpers_get", "credential_helpers_store"}),
+    "social": frozenset(
+        {"x_search", "x_account_status", "x_account_draft_post", "x_account_draft_reply", "x_account_post", "x_account_reply", "x_account_post_action"}
+    ),
+}
+
+
+def _normalize_class(value: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "_", value.strip().casefold()).strip("_")
+
+
+def declared_tool_classes(prompt: str) -> tuple[str, ...] | None:
+    """Return normalized explicit tool classes, or ``None`` when undeclared."""
+
+    match = _DECLARATION_RE.search(prompt or "")
+    if match is None:
+        return None
+    values = tuple(
+        normalized
+        for raw in match.group(1).split(",")
+        if (normalized := _normalize_class(raw))
+    )
+    return values
+
+
+def select_tools_for_prompt(
+    prompt: str,
+    all_tools: Sequence[Callable[..., Any]],
+) -> list[Callable[..., Any]]:
+    """Select only explicitly declared known tool classes.
+
+    Unknown classes contribute no tools. This fails closed instead of
+    accidentally exposing the full runtime catalog when a declaration has a
+    typo or names a class implemented by another harness.
+    """
+
+    declared = declared_tool_classes(prompt)
+    if declared is None:
+        return list(all_tools)
+    allowed_names: set[str] = set()
+    for tool_class in declared:
+        allowed_names.update(_CLASS_TO_TOOLS.get(tool_class, ()))
+    return [tool for tool in all_tools if getattr(tool, "__name__", "") in allowed_names]
+
+
+__all__ = ["declared_tool_classes", "select_tools_for_prompt"]