pico-cli-sdk 0.1.1__py3-none-any.whl

pico_cli_sdk-0.1.1.dist-info/METADATA

@@ -0,0 +1,28 @@
+Metadata-Version: 2.5
+Name: pico-cli-sdk
+Version: 0.1.1
+Summary: Headless library API and extension/plugin binding.
+Project-URL: Homepage, https://github.com/Arya-Ojha/PicoCLI_Learn
+Project-URL: Repository, https://github.com/Arya-Ojha/PicoCLI_Learn
+Project-URL: Issues, https://github.com/Arya-Ojha/PicoCLI_Learn/issues
+Author-email: Arya-Ojha <aryaojha195@gmail.com>
+License-Expression: MIT
+Keywords: ai-agent,cli,coding-assistant,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: pico-cli-ai
+Requires-Dist: pico-cli-core
+Requires-Dist: pydantic>=2
+Description-Content-Type: text/markdown
+
+# pico-cli-sdk
+
+Headless library API for `pico-cli`: `AgentSession`, curated observe-only hooks, `SKILL.md` skills, provider setup, and the `picocli-chat` command-line interface.
+
+See the [pico-cli README](https://github.com/Arya-Ojha/PicoCLI_Learn#readme) for the full picture.

pico_cli_sdk-0.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+pico_sdk/__init__.py,sha256=VyHjArq8d2BC9yP0Dc8Wm1qLXVMLnIdRI3ZC8vUHhYc,1253
+pico_sdk/__main__.py,sha256=RhLRauBRlaCTsl6hIs0Q6cvhMMu3hRzmAR7su3NPfF8,137
+pico_sdk/cli.py,sha256=G21KpSBC_u1IGmr0mtr39uwFiqnQ49ICwNgsXTFKQXg,5781
+pico_sdk/config.py,sha256=Ecu9mdIbhNrIXeyIJOgk8B4eocvt7dealgXgzHgjFGY,2257
+pico_sdk/extensions.py,sha256=BTQDjfrr_D2cswr8kIa85XuJdS1f8B7e9Ab-qMhsY4A,3657
+pico_sdk/providers.py,sha256=RjXyxVG61Q8x86Eo-sDsEDf4ZeL0Tte1EgNdSDiTfGw,3169
+pico_sdk/py.typed,sha256=s9UQ7wQnXKjmmOWzy7Ds45Se-SUvDNyDnp7jR0CaIgk,2
+pico_sdk/session.py,sha256=P4vZysV7_6WXxEaOEq7Wlq_fila2vcu3moyyooADQeU,12253
+pico_sdk/skills.py,sha256=mSEG1niW2LJvos1OLgvpNYp55hiOvI_MxbnJNPTF-qo,3489
+pico_cli_sdk-0.1.1.dist-info/METADATA,sha256=5UJ0waJJPZLlhQVnCTFPoHE267tgT2kdFjYqdgj6vw4,1183
+pico_cli_sdk-0.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pico_cli_sdk-0.1.1.dist-info/RECORD,,

pico_cli_sdk-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pico_sdk/__init__.py

@@ -0,0 +1,49 @@
+"""pico_sdk: the headless library API and curated hooks/skills."""
+
+from pico_core.fsm import AgentState, LoopEvent, RunResult
+from pico_core.session import (
+    AssistantPayload,
+    CompactionSummaryPayload,
+    Node,
+    Session,
+    ToolRequestPayload,
+    ToolResultPayload,
+    UserPayload,
+)
+from pico_core.subagents import ChildSpec, SpawnTool
+from pico_core.trace import TraceRow, assemble_trace_rows
+
+from .config import Settings, load_settings
+from .extensions import ALLOWED_HOOKS, ExtensionManager
+from .session import DEFAULT_SYSTEM_PROMPT, AgentSession
+from .skills import Skill, discover_skills, merge_skills, parse_skill_file, render_skills_prompt
+
+__all__ = [
+    "AgentSession",
+    "ExtensionManager",
+    "ALLOWED_HOOKS",
+    "Settings",
+    "load_settings",
+    "Skill",
+    "discover_skills",
+    "merge_skills",
+    "parse_skill_file",
+    "render_skills_prompt",
+    "DEFAULT_SYSTEM_PROMPT",
+    "ChildSpec",
+    "SpawnTool",
+    "TraceRow",
+    "assemble_trace_rows",
+    "AgentState",
+    "LoopEvent",
+    "RunResult",
+    "AssistantPayload",
+    "CompactionSummaryPayload",
+    "Node",
+    "Session",
+    "ToolRequestPayload",
+    "ToolResultPayload",
+    "UserPayload",
+]
+
+

pico_sdk/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m pico_sdk`` to run the CLI."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pico_sdk/cli.py

@@ -0,0 +1,157 @@
+"""The ``pico`` command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+
+from pico_core.fsm import LoopEvent
+
+from .config import Settings, load_settings
+from .providers import (
+    FREE_MODEL_ALIAS,
+    create_provider,
+    missing_required,
+    resolve_free_model,
+)
+from .session import AgentSession
+
+
+def format_event(event: LoopEvent) -> str | None:
+    """Return the text to print for an event, or ``None`` to print nothing."""
+    if event.kind == "text":
+        return event.text
+    if event.kind == "tool_request" and event.tool_request is not None:
+        if event.tool_request.tool_call.name == "bash":
+            return "$ " + event.tool_request.tool_call.arguments.get("command", "") + "\n"
+    if event.kind == "tool_result" and event.tool_result is not None:
+        if event.tool_result.name == "bash":
+            return event.tool_result.content.rstrip() + "\n"
+        if event.tool_result.is_error:
+            # Surface failures (denied/unknown/error) for non-bash tools;
+            # successful read/write/edit/grep/fetch/websearch/todo results
+            # stay quiet — the model's summary covers them.
+            return f"error [{event.tool_result.name}]: {event.tool_result.content.rstrip()}\n"
+    return None
+
+
+def apply_cli_overrides(args: argparse.Namespace, settings: Settings) -> bool:
+    """Apply CLI flags onto ``settings`` (permission gating + skills).
+
+    ``--allow-tools`` (comma-separated) wins over ``--no-bash`` per ADR-0003
+    precedence; ``--skills-dir`` overrides the configured skills directory;
+    ``--no-skills`` disables skill loading entirely (returns the flag).
+    """
+    if getattr(args, "allow_tools", None):
+        settings.allowed_tools = [
+            name.strip() for name in args.allow_tools.split(",") if name.strip()
+        ]
+    if getattr(args, "skills_dir", None):
+        settings.skills_dir = args.skills_dir
+    return not getattr(args, "no_skills", False)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="picocli-chat", description="A headless coding agent.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    run = sub.add_parser("run", help="Run the agent on a prompt.")
+    run.add_argument("prompt", nargs="+", help="The prompt to run.")
+    run.add_argument(
+        "--no-bash",
+        action="store_true",
+        help="Disable unsandboxed bash (on by default; ignored when "
+        "allowed_tools is set without 'bash').",
+    )
+    run.add_argument("--model", default=None, help="Override the configured model.")
+    run.add_argument("--cwd", default=None, help="Working directory (default: current).")
+    run.add_argument("--session", default=None, help="Resume an existing session by id.")
+    run.add_argument(
+        "--allow-tools",
+        default=None,
+        help="Comma-separated tool allowlist (e.g. 'read,grep,bash'); "
+        "overrides settings.allowed_tools and --no-bash precedence.",
+    )
+    run.add_argument(
+        "--skills-dir", default=None, help="Override the configured skills directory."
+    )
+    run.add_argument(
+        "--no-skills", action="store_true", help="Disable SKILL.md loading."
+    )
+    run.add_argument(
+        "--provider", default=None, help="Provider id (e.g. 'openai', 'ollama')."
+    )
+    return parser
+
+
+async def run_command(args: argparse.Namespace) -> int:
+    settings = load_settings()
+    if args.provider:
+        settings.provider = args.provider
+    model = args.model or settings.model
+    load_skills = apply_cli_overrides(args, settings)
+    missing = missing_required(settings.provider, settings)
+
+    if missing:
+        sys.stderr.write(
+            f"error: provider '{settings.provider}' is missing required "
+            f"config: {', '.join(missing)}.\n"
+             f"Run `picocli` and use /provider to configure it, or set "
+            f"the corresponding environment variable.\n"
+        )
+        return 1
+
+    provider = create_provider(settings)
+    if model == FREE_MODEL_ALIAS and settings.provider == "openrouter":
+        resolved = await resolve_free_model(provider)
+        if resolved:
+            model = resolved
+            sys.stdout.write(f"using free model: {model}\n")
+    if args.session:
+        session = AgentSession.load(
+            args.session,
+            provider=provider,
+            model=model,
+            settings=settings,
+            working_dir=args.cwd,
+            allow_bash=not args.no_bash,
+            load_skills=load_skills,
+        )
+    else:
+        session = AgentSession(
+            provider=provider,
+            model=model,
+            settings=settings,
+            working_dir=args.cwd,
+            allow_bash=not args.no_bash,
+            load_skills=load_skills,
+        )
+    prompt = " ".join(args.prompt)
+    if prompt.startswith("/compact"):
+        instructions = prompt[len("/compact") :].strip()
+        await session.compact(instructions)
+        sys.stdout.write("compacted context\n")
+        session.save()
+        return 0
+    async for event in session.stream(prompt):
+        rendered = format_event(event)
+        if rendered:
+            sys.stdout.write(rendered)
+            sys.stdout.flush()
+    sys.stdout.write("\n")
+    session.save()
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "run":
+        return asyncio.run(run_command(args))
+    parser.error(f"unknown command: {args.command}")
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pico_sdk/config.py

@@ -0,0 +1,57 @@
+"""Settings loaded from ``~/.pico/settings.json`` with sensible defaults."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+
+class Settings(BaseModel):
+    """User-configurable settings for the agent."""
+
+    model: str = "openrouter/free"  # alias: best available free model
+    context_window: int = 128_000
+    reserve_tokens: int = 16_384
+    session_dir: str = "~/.pico/sessions"
+    api_key_env: str = "OPENROUTER_API_KEY"
+    # Active provider id (see ``pico_ai.providers`` registry).
+    provider: str = "openrouter"
+    # Per-provider stored config, e.g. {"openai": {"api_key": "sk-…"}}.
+    # Secrets live here in plaintext — prefer env vars for shared machines.
+    providers: dict[str, dict[str, str]] = Field(default_factory=dict)
+    # Curated-extension settings (ADR-0003: hardcoded core).
+    skills_dir: str = "~/.pico/skills"
+    # Permission gating: which core tools the model may invoke.
+    # ``None`` (default) allows every core tool; ``[]`` allows none.
+    # When set, this loop-level gate wins over the per-tool ``allow_bash``
+    # flag. Unknown names are ignored with a startup warning.
+    allowed_tools: list[str] | None = None
+
+
+def default_settings_path() -> Path:
+    """Return the default settings file path."""
+    return Path.home() / ".pico" / "settings.json"
+
+
+def load_settings(path: Path | None = None) -> Settings:
+    """Load settings from ``path`` (default ``~/.pico/settings.json``).
+
+    Missing keys fall back to defaults; a missing file yields all defaults.
+    """
+    path = Path(path) if path is not None else default_settings_path()
+    if not path.exists():
+        return Settings()
+    data = json.loads(path.read_text(encoding="utf-8"))
+    return Settings.model_validate(data)
+
+
+def save_settings(settings: Settings, path: Path | None = None) -> Path:
+    """Persist ``settings`` to ``path`` (default ``~/.pico/settings.json``)."""
+    path = Path(path) if path is not None else default_settings_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(settings.model_dump(), indent=2) + "\n", encoding="utf-8"
+    )
+    return path

pico_sdk/extensions.py

@@ -0,0 +1,108 @@
+"""Curated extension hooks (Claude Code-style).
+
+The core (tools, loop, provider, session) is hardcoded and non-replaceable
+(see ADR-0003). Extensions are guests: they observe lifecycle events through
+a small fixed hook vocabulary. Hooks cannot mutate arguments/results or veto
+execution.
+
+Fixed vocabulary:
+- ``session_start`` — fires once per ``AgentSession.stream`` run.
+- ``pre_tool_use`` — fires before a tool runs (observe-only).
+- ``post_tool_use`` — fires after a tool succeeds.
+- ``post_tool_failure`` — fires after a tool returns an error result or raises.
+
+Legacy aliases (``on_session_start``, ``tool.before.*``, ``tool.after.*``)
+are accepted and mapped onto the fixed vocabulary.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections import defaultdict
+from typing import Any, Callable
+
+from pico_core.session import Session, ToolResultPayload
+
+Hook = Callable[..., Any]
+
+#: The only hook names ``on()`` accepts (after alias normalisation).
+ALLOWED_HOOKS = frozenset(
+    {
+        "session_start",
+        "pre_tool_use",
+        "post_tool_use",
+        "post_tool_failure",
+    }
+)
+
+_LEGACY_ALIASES = {
+    "on_session_start": "session_start",
+}
+
+
+def _normalize_event(event: str) -> str:
+    """Map legacy hook names onto the fixed vocabulary."""
+    if event in _LEGACY_ALIASES:
+        return _LEGACY_ALIASES[event]
+    if event.startswith("tool.before."):
+        return "pre_tool_use"
+    if event.startswith("tool.after."):
+        return "post_tool_use"
+    return event
+
+
+class ExtensionManager:
+    """Fixed-vocabulary, observe-only hook surface.
+
+    Implements the loop's ``HookSink``. There is no provider registry and no
+    plugin-directory loader: the provider is built by
+    ``pico_sdk.providers.create_provider`` and tools are wired directly in
+    ``AgentSession._register_core_tools``.
+    """
+
+    def __init__(self) -> None:
+        self._hooks: dict[str, list[Hook]] = defaultdict(list)
+
+    # -- hooks --------------------------------------------------------------
+
+    def on(self, event: str, callback: Hook) -> Callable[[], None]:
+        """Subscribe ``callback`` to a fixed hook. Returns an unsubscribe fn."""
+        name = _normalize_event(event)
+        if name not in ALLOWED_HOOKS:
+            raise ValueError(
+                f"unknown hook: {event!r}; allowed: {sorted(ALLOWED_HOOKS)}"
+            )
+        self._hooks[name].append(callback)
+
+        def _off() -> None:
+            try:
+                self._hooks[name].remove(callback)
+            except ValueError:
+                pass
+
+        return _off
+
+    async def _fire(self, event: str, **kwargs: Any) -> None:
+        for callback in list(self._hooks.get(event, [])):
+            result = callback(**kwargs)
+            if inspect.isawaitable(result):
+                await result
+
+    # HookSink implementation ----------------------------------------------
+
+    async def on_session_start(self, session: Session) -> None:
+        await self._fire("session_start", session=session)
+
+    async def tool_before(self, name: str, arguments: dict) -> None:
+        await self._fire("pre_tool_use", name=name, arguments=arguments)
+
+    async def tool_after(
+        self, name: str, arguments: dict, result: ToolResultPayload
+    ) -> None:
+        await self._fire(
+            "post_tool_use", name=name, arguments=arguments, result=result
+        )
+        if result.is_error:
+            await self._fire(
+                "post_tool_failure", name=name, arguments=arguments, result=result
+            )

pico_sdk/providers.py

@@ -0,0 +1,92 @@
+"""Provider construction from settings and per-provider stored config."""
+
+from __future__ import annotations
+
+import os
+import warnings
+from typing import Any
+
+from pico_ai.providers import create_provider as build_adapter
+from pico_ai.providers import get_spec, provider_ids
+
+from .config import Settings, load_settings
+
+
+def effective_config(provider_id: str, settings: Settings) -> dict[str, str]:
+    """Resolve the working config for ``provider_id``.
+
+    Precedence: field default < environment variable < stored settings value.
+    Clearing a stored value falls back to env/default.
+    """
+    spec = get_spec(provider_id)
+    stored = settings.providers.get(provider_id) or {}
+    resolved: dict[str, str] = {}
+    for f in spec.fields:
+        value = stored.get(f.key, "")
+        if not value and f.env_var:
+            value = os.environ.get(f.env_var, "")
+        if not value:
+            value = f.default
+        resolved[f.key] = value
+    return resolved
+
+
+def missing_required(provider_id: str, settings: Settings) -> list[str]:
+    """Return labels of required fields with no effective value."""
+    spec = get_spec(provider_id)
+    config = effective_config(provider_id, settings)
+    return [f.label for f in spec.required_fields if not config.get(f.key)]
+
+
+def create_provider(settings: Settings | None = None) -> Any:
+    """Build the active provider from settings (id + stored config)."""
+    settings = settings or load_settings()
+    provider_id = settings.provider or "openrouter"
+    if provider_id not in provider_ids():
+        warnings.warn(
+            f"unknown provider {provider_id!r}; falling back to 'openrouter'",
+            stacklevel=2,
+        )
+        provider_id = "openrouter"
+    return build_adapter(provider_id, effective_config(provider_id, settings))
+
+
+def describe_providers(settings: Settings) -> list[dict]:
+    """Return picker rows: id, display name, description, configured, active."""
+    rows = []
+    for pid in provider_ids():
+        spec = get_spec(pid)
+        rows.append(
+            {
+                "id": pid,
+                "display_name": spec.display_name,
+                "description": spec.description,
+                "configured": not missing_required(pid, settings),
+                "active": pid == (settings.provider or "openrouter"),
+            }
+        )
+    return rows
+
+
+FREE_MODEL_ALIAS = "openrouter/free"
+
+
+async def resolve_free_model(provider: Any) -> str | None:
+    """Resolve the ``openrouter/free`` alias to a concrete free model id.
+
+    Picks the first free model (alphabetically) that supports tool calling;
+    falls back to any free model. Returns None if nothing free is available
+    or the lookup fails — callers should keep the alias as-is in that case.
+    """
+    try:
+        models = await provider.list_models()
+    except Exception:
+        return None
+    free = sorted(
+        (m for m in models if m.get("is_free", False)),
+        key=lambda m: str(m.get("name", "")).lower(),
+    )
+    with_tools = [m for m in free if m.get("supports_tools", True)]
+    if with_tools:
+        return with_tools[0]["id"]
+    return free[0]["id"] if free else None

pico_sdk/py.typed

@@ -0,0 +1 @@
+��

pico_sdk/session.py

@@ -0,0 +1,316 @@
+"""The headless library API: ``AgentSession`` (hardcoded core, ADR-0003)."""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import AsyncIterator
+from pathlib import Path
+from typing import Any
+
+from pico_core.fsm import AgentLoop, LoopEvent, RunResult
+from pico_core.session import Session
+from pico_core.subagents import DEFAULT_CHILD_TOOLS, MAX_DEPTH, ChildSpec, SpawnTool
+from pico_core.todos import TodoList, TodoTool
+from pico_core.tools import BashTool, EditTool, FetchTool, GrepTool, ReadTool, ToolOutcome, ToolRegistry, WebSearchTool, WriteTool
+
+from .config import Settings, load_settings
+from .extensions import ExtensionManager
+from .skills import AGENTS_SKILLS_DIR, Skill, discover_skills, merge_skills, render_skills_prompt
+
+DEFAULT_SYSTEM_PROMPT = (
+    "You are pico, a coding agent. You can read, write, and edit files, search "
+    "file contents with grep, fetch URLs, search the web, and run "
+    "bash commands. Work autonomously to complete the user's task, then report "
+    "what you did. For multi-step tasks, track progress with the todo tool "
+    "(add one todo per step, mark each in_progress while you work on it and "
+    "completed when done). The run only ends once every todo is completed — "
+    "do not stop early with unfinished todos."
+)
+
+
+class AgentSession:
+    """A headless agent session: hardcoded provider + tools + session tree.
+
+    The core is non-replaceable (ADR-0003). Curated extensions only: fixed
+    lifecycle hooks via :meth:`on` and model-invoked ``SKILL.md`` skills.
+    """
+
+    #: Core tool names in registration order (permission-gating vocabulary).
+    CORE_TOOLS = (
+        "read",
+        "write",
+        "edit",
+        "grep",
+        "fetch",
+        "websearch",
+        "bash",
+        "todo",
+        "task",
+    )
+
+    def __init__(
+        self,
+        *,
+        provider: Any,
+        model: str | None = None,
+        settings: Settings | None = None,
+        working_dir: str | Path | None = None,
+        allow_bash: bool = True,
+        session_id: str | None = None,
+        session: Session | None = None,
+        system_prompt: str = DEFAULT_SYSTEM_PROMPT,
+        load_skills: bool = True,
+    ) -> None:
+        self.settings = settings or load_settings()
+        self.model = model or self.settings.model
+        self.working_dir = Path(working_dir) if working_dir else Path.cwd()
+        self.allow_bash = allow_bash
+        self.extensions = ExtensionManager()
+        self.provider_id: str = (
+            getattr(provider, "provider_id", None)
+            or self.settings.provider
+            or "openrouter"
+        )
+
+        if self.settings.allowed_tools is not None:
+            unknown = set(self.settings.allowed_tools) - set(self.CORE_TOOLS)
+            if unknown:
+                warnings.warn(
+                    f"unknown tools in allowed_tools (ignored): "
+                    f"{sorted(unknown)}; valid: {list(self.CORE_TOOLS)}",
+                    stacklevel=2,
+                )
+
+        self.system_prompt = system_prompt
+        self.skills: list[Skill] = []
+        if load_skills:
+            # Global skills (shared ~/.agents/skills first, then the
+            # configured skills_dir) plus project-local override
+            # (<cwd>/.pico/skills wins on name conflicts); all loaded.
+            self.skills = merge_skills(
+                [
+                    discover_skills([AGENTS_SKILLS_DIR]),
+                    discover_skills([self.settings.skills_dir]),
+                    discover_skills([self.working_dir / ".pico" / "skills"]),
+                ]
+            )
+            skills_section = render_skills_prompt(self.skills)
+            if skills_section:
+                self.system_prompt = f"{system_prompt}\n\n{skills_section}"
+
+        self.session = session or (Session(id=session_id) if session_id else Session())
+        self.tools = ToolRegistry()
+        self.todos = TodoList()
+        self._register_core_tools(allow_bash)
+
+        self.loop = AgentLoop(
+            provider=provider,
+            session=self.session,
+            tools=self.tools,
+            system_prompt=self.system_prompt,
+            model=self.model,
+            context_window=self.settings.context_window,
+            reserve_tokens=self.settings.reserve_tokens,
+            hooks=self.extensions,
+            allowed_tools=self.settings.allowed_tools,
+        )
+
+    @property
+    def provider(self) -> Any:
+        return self.loop.provider
+
+    @property
+    def provider_name(self) -> str:
+        """Return a human-readable provider name."""
+        display = getattr(self.loop.provider, "display_name", None)
+        if display:
+            return str(display)
+        provider_class = type(self.loop.provider).__name__
+        # Convert CamelCase to readable name
+        if "OpenRouter" in provider_class:
+            return "OpenRouter"
+        return provider_class.replace("Provider", "")
+
+    @property
+    def context_window(self) -> int:
+        """Return the context window size."""
+        return self.loop.context_window
+
+    def estimate_tokens(self) -> int:
+        """Return the current estimated token count."""
+        return self.loop.estimate_tokens()
+
+    # -- core tools (hardcoded, non-replaceable) ------------------------------
+
+    def _register_core_tools(self, allow_bash: bool) -> None:
+        # Precedence: the loop-level ``allowed_tools`` gate (when set) rejects
+        # before any tool runs, so it wins over this per-tool flag. When
+        # ``allowed_tools`` is None, ``allow_bash`` decides for bash.
+        for tool in (
+            ReadTool(self.working_dir),
+            WriteTool(self.working_dir),
+            EditTool(self.working_dir),
+            GrepTool(self.working_dir),
+            FetchTool(),
+            WebSearchTool(),
+            BashTool(self.working_dir, enabled=allow_bash),
+            TodoTool(self.todos),
+            SpawnTool(
+                factory=self._make_child_loop,
+                depth=0,
+                session_dir=Path(self.settings.session_dir).expanduser(),
+            ),
+        ):
+            self.tools.register(tool)
+
+    def _make_child_loop(self, spec: ChildSpec, depth: int) -> AgentLoop:
+        """Build an isolated child loop for a delegated task (ADR-0005).
+
+        The child gets a fresh session, fresh todos, and a restricted tool
+        allowlist (intersected with the parent's own gate so a parent can
+        never escalate). ``task`` is only registered when explicitly granted
+        and the nesting depth allows it.
+        """
+        allowed = (
+            list(spec.allowed_tools)
+            if spec.allowed_tools is not None
+            else list(DEFAULT_CHILD_TOOLS)
+        )
+        if self.settings.allowed_tools is not None:
+            allowed = [t for t in allowed if t in self.settings.allowed_tools]
+        if depth > MAX_DEPTH:
+            allowed = [t for t in allowed if t != "task"]
+        todos = TodoList()
+        registry = ToolRegistry()
+        for tool in (
+            ReadTool(self.working_dir),
+            WriteTool(self.working_dir),
+            EditTool(self.working_dir),
+            GrepTool(self.working_dir),
+            FetchTool(),
+            WebSearchTool(),
+            BashTool(self.working_dir, enabled=self.allow_bash),
+            TodoTool(todos),
+        ):
+            registry.register(tool)
+        if "task" in allowed:
+            registry.register(
+                SpawnTool(
+                    factory=self._make_child_loop,
+                    depth=depth,
+                    session_dir=Path(self.settings.session_dir).expanduser(),
+                )
+            )
+        return AgentLoop(
+            provider=self.loop.provider,
+            session=Session(),
+            tools=registry,
+            system_prompt=self.system_prompt,
+            model=spec.model or self.model,
+            context_window=self.settings.context_window,
+            reserve_tokens=self.settings.reserve_tokens,
+            hooks=self.extensions,
+            allowed_tools=allowed,
+        )
+
+    async def spawn(self, prompt: str, **kwargs: Any) -> ToolOutcome:
+        """Delegate ``prompt`` to a sub-agent and return its summary outcome.
+
+        Accepts the same keyword arguments as the ``task`` tool
+        (``description``, ``allowed_tools``, ``model``, ``max_turns``,
+        ``timeout_s``).
+        """
+        tool = self.tools.get("task")
+        assert tool is not None, "task tool is hardcoded in the core"
+        return await tool.run({"prompt": prompt, **kwargs})
+
+    # -- running ------------------------------------------------------------
+
+    async def run(self, prompt: str) -> RunResult:
+        return await self.loop.run(prompt)
+
+    def stream(self, prompt: str) -> AsyncIterator[LoopEvent]:
+        return self.loop.stream(prompt)
+
+    def fork(self, node_id: str) -> None:
+        self.session.fork(node_id)
+
+    async def compact(self, instructions: str = "") -> None:
+        await self.loop.compact(instructions)
+
+    # -- curated extensions -------------------------------------------------
+    # Hooks are observe-only; see ``pico_sdk.extensions.ALLOWED_HOOKS``.
+
+    def on(self, event: str, callback: Any) -> Any:
+        return self.extensions.on(event, callback)
+
+    # -- providers ----------------------------------------------------------
+
+    def set_provider(
+        self, provider_id: str, values: dict[str, str] | None = None
+    ) -> Any:
+        """Switch the active provider, storing ``values`` into settings.
+
+        Only the given ``values`` are stored (merged over existing stored
+        config); effective config still falls back to env vars and field
+        defaults. The model resets to the stored/default model for the new
+        provider — model ids are provider-specific — and is written back to
+        settings so the next launch reopens on this provider + model.
+        Returns the adapter.
+        """
+        from pico_ai.providers import get_spec
+
+        from .providers import effective_config
+
+        spec = get_spec(provider_id)  # KeyError on unknown id
+        stored = dict(self.settings.providers.get(provider_id, {}))
+        if values:
+            stored.update(values)
+        self.settings.providers[provider_id] = stored
+        self.settings.provider = provider_id
+        self.provider_id = provider_id
+        config = effective_config(provider_id, self.settings)
+        self.loop.provider = spec.create(config)
+        self.model = config.get("model") or spec.default_model
+        self.loop.model = self.model
+        self.settings.model = self.model
+        return self.loop.provider
+
+    # -- persistence --------------------------------------------------------
+
+    def session_path(self) -> Path:
+        directory = Path(self.settings.session_dir).expanduser()
+        return directory / f"{self.session.id}.jsonl"
+
+    def save(self) -> Path:
+        path = self.session_path()
+        self.session.save(path)
+        return path
+
+    @classmethod
+    def load(
+        cls,
+        session_id: str,
+        *,
+        provider: Any,
+        model: str | None = None,
+        settings: Settings | None = None,
+        working_dir: str | Path | None = None,
+        allow_bash: bool = True,
+        system_prompt: str = DEFAULT_SYSTEM_PROMPT,
+        load_skills: bool = True,
+    ) -> "AgentSession":
+        """Resume an existing session persisted under ``session_dir``."""
+        settings = settings or load_settings()
+        directory = Path(settings.session_dir).expanduser()
+        session = Session.load(directory / f"{session_id}.jsonl")
+        return cls(
+            provider=provider,
+            model=model,
+            settings=settings,
+            working_dir=working_dir,
+            allow_bash=allow_bash,
+            session=session,
+            system_prompt=system_prompt,
+            load_skills=load_skills,
+        )

pico_sdk/skills.py

@@ -0,0 +1,102 @@
+"""Curated skills: model-invoked ``SKILL.md`` markdown files (Claude Code-style).
+
+A skill is a directory containing a ``SKILL.md`` file with optional YAML
+frontmatter (``name`` / ``description``) followed by markdown instructions::
+
+    ---
+    name: commit-helper
+    description: Use when the user wants to commit code.
+    ---
+    # Commit helper
+    Run ``git status`` first ...
+
+Skills are discovered from ``~/.pico/skills/*/SKILL.md`` plus
+``~/.agents/skills/*/SKILL.md`` (e.g. shared/opencode skills) plus an
+optional project-local directory, and their descriptions are inlined
+into the system prompt so the model knows when to apply them. Skills
+carry knowledge only — they execute no code.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Skill:
+    name: str
+    description: str
+    content: str
+    path: Path
+
+
+def parse_skill_file(path: Path) -> Skill:
+    """Parse a single ``SKILL.md`` file (frontmatter optional)."""
+    text = path.read_text(encoding="utf-8")
+    name = path.parent.name
+    description = ""
+    content = text
+    if text.startswith("---"):
+        end = text.find("---", 3)
+        if end != -1:
+            front = text[3:end].strip()
+            content = text[end + 3 :].strip()
+            for line in front.splitlines():
+                if ":" not in line:
+                    continue
+                key, _, value = line.partition(":")
+                key = key.strip().lower()
+                value = value.strip().strip("\"'")
+                if key == "name" and value:
+                    name = value
+                elif key == "description" and value:
+                    description = value
+    return Skill(name=name, description=description, content=content, path=path)
+
+
+def discover_skills(directories: list[Path | str]) -> list[Skill]:
+    """Collect skills from ``<dir>/*/SKILL.md`` across ``directories``."""
+    skills: list[Skill] = []
+    for directory in directories:
+        root = Path(directory).expanduser()
+        if not root.is_dir():
+            continue
+        for candidate in sorted(root.glob("*/SKILL.md")):
+            try:
+                skills.append(parse_skill_file(candidate))
+            except OSError:
+                continue
+    return skills
+
+
+#: Second global skills location (shared/opencode-style skills, e.g. Matt
+#: Pocock's). Always searched alongside the configured ``skills_dir``;
+#: ``skills_dir`` wins on name conflicts, project-local wins over both.
+AGENTS_SKILLS_DIR = "~/.agents/skills"
+
+
+def merge_skills(layers: list[list[Skill]]) -> list[Skill]:
+    """Merge skill layers; later layers override earlier ones by name.
+
+    Returns all skills sorted by name (no cap — every discovered skill is
+    inlined into the system prompt).
+    """
+    merged: dict[str, Skill] = {}
+    for layer in layers:
+        for skill in layer:
+            merged[skill.name] = skill
+    return sorted(merged.values(), key=lambda s: s.name)
+
+
+def render_skills_prompt(skills: list[Skill]) -> str:
+    """Render the system-prompt section describing available skills."""
+    if not skills:
+        return ""
+    lines = ["Available skills (apply when relevant):"]
+    for skill in skills:
+        trigger = skill.description or f"skill '{skill.name}'"
+        lines.append(f"- {skill.name}: {trigger}")
+        if skill.content:
+            lines.append(f"  {skill.content[:500]}".rstrip())
+    return "\n".join(lines)