polyrob 0.5.0__py3-none-any.whl

cli/commands/skills.py

@@ -0,0 +1,128 @@
+"""polyrob skills commands (P3 cli/commands split)."""
+from typing import Optional
+
+import click
+
+
+def get_skill_manager():
+    """Lazy accessor (kept module-level so it stays cheap to import and patchable)."""
+    from agents.task.agent.skill_manager import get_skill_manager as _gsm
+    return _gsm()
+
+
+@click.group()
+def skills():
+    """List and validate agent skills."""
+    pass
+
+
+@skills.command("list")
+def skills_list():
+    """List registered skill IDs."""
+    try:
+        mgr = get_skill_manager()
+    except Exception as e:
+        click.echo(click.style("[polyrob] ERROR: ", fg="red") + f"skill manager unavailable: {e}")
+        raise SystemExit(1)
+    if hasattr(mgr, "_ensure_rules_loaded"):
+        mgr._ensure_rules_loaded()
+    skill_ids = sorted(getattr(mgr, "skill_rules", {}).keys())
+    if not skill_ids:
+        click.echo("No skills registered.")
+        return
+    click.echo(f"Registered skills ({len(skill_ids)}):")
+    for sid in skill_ids:
+        click.echo(f"  - {sid}")
+
+
+@skills.command("validate")
+@click.argument("skill_id", required=False)
+def skills_validate(skill_id: Optional[str]):
+    """Validate one skill (by id) or the whole authored library.
+
+    With SKILL_ID: the legacy per-skill check (rules.json wiring + content shape).
+    With no argument: the strict agentskills.io frontmatter compliance check
+    (``SkillManager.validate_all_authored``) run across every shipped skill —
+    the same gate `polyrob doctor` and CI's library-invariant test use.
+    """
+    try:
+        mgr = get_skill_manager()
+    except Exception as e:
+        click.echo(click.style("[polyrob] ERROR: ", fg="red") + f"skill manager unavailable: {e}")
+        raise SystemExit(1)
+    if skill_id:
+        # F7: an unknown skill id should fail clearly, not crash with a raw
+        # KeyError/traceback.  Validate against the known ids first.
+        if hasattr(mgr, "_ensure_rules_loaded"):
+            try:
+                mgr._ensure_rules_loaded()
+            except Exception:
+                pass
+        known = getattr(mgr, "skill_rules", {}) or {}
+        if known and skill_id not in known:
+            click.echo(
+                click.style("[polyrob] ERROR: ", fg="red")
+                + f"no such skill: {skill_id!r} (try `polyrob skills list`)"
+            )
+            raise SystemExit(1)
+        try:
+            result = mgr.validate_skill(skill_id)
+        except Exception as e:
+            click.echo(
+                click.style("[polyrob] ERROR: ", fg="red")
+                + f"no such skill: {skill_id!r} ({e})"
+            )
+            raise SystemExit(1)
+        status = click.style("valid", fg="green") if result.is_valid else click.style("INVALID", fg="red")
+        click.echo(f"{result.skill_id:<24} {status}")
+        for err in getattr(result, "errors", []) or []:
+            click.echo(f"    error: {err}")
+        for warn in getattr(result, "warnings", []) or []:
+            click.echo(f"    warn:  {warn}")
+        if not result.is_valid:
+            raise SystemExit(1)
+        return
+
+    # No skill_id: strict library-wide compliance check (Task 4).
+    issues_by_skill = mgr.validate_all_authored()
+    error_count = 0
+    for sid in sorted(issues_by_skill):
+        click.echo(f"{sid}:")
+        for issue in issues_by_skill[sid]:
+            if issue.level == "error":
+                error_count += 1
+            click.echo(f"    {issue.level}: {issue.code} — {issue.msg}")
+    if not issues_by_skill:
+        click.echo(click.style("All authored skills are compliant.", fg="green"))
+    else:
+        click.echo(
+            f"\n{len(issues_by_skill)} skill(s) with issues ({error_count} error(s))"
+        )
+    if error_count:
+        raise SystemExit(1)
+
+
+@skills.command("export")
+@click.argument("skill_id")
+@click.option("--to", "dest", default=None, help="Target dir (default: ~/.agents/skills)")
+def skills_export(skill_id: str, dest: Optional[str]):
+    """Copy a skill folder (SKILL.md + resources) to a portable location.
+
+    Defaults to ``~/.agents/skills/<skill_id>`` (agentskills.io-style layout);
+    ``--to DIR`` targets ``DIR/<skill_id>`` instead. Refuses to clobber an
+    existing target directory.
+    """
+    import shutil
+    from pathlib import Path
+
+    mgr = get_skill_manager()
+    src = mgr.resolve_skill_dir(skill_id)
+    if not src or not (src / "SKILL.md").exists():
+        raise click.ClickException(f"no such skill: {skill_id!r} (try `polyrob skills list`)")
+    target_root = Path(dest) if dest else (Path.home() / ".agents" / "skills")
+    out = target_root / skill_id
+    if out.exists():
+        raise click.ClickException(f"already exists: {out} (remove it first)")
+    out.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(src, out)
+    click.echo(f"exported {skill_id} -> {out}")

cli/commands/subagents.py

@@ -0,0 +1,100 @@
+"""POLYROB subagents commands — inspect background delegations.
+
+Delegations are session-scoped and in-memory. This command can show:
+- General delegation capability info
+- Active delegations for a live session (if attached/queried)
+- Static info about limits and configuration
+"""
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+import click
+
+from agents.task.constants import TimeoutConfig
+
+
+@click.group("subagents")
+def subagents():
+    """Inspect agent delegation and subagent activity."""
+    pass
+
+
+@subagents.command("info")
+@click.option("--json", "as_json", is_flag=True, help="Print machine-readable JSON.")
+def subagents_info(as_json: bool):
+    """Show delegation capability and limits."""
+    # Lazy import to avoid heavy tools import chain
+    try:
+        from tools.controller.delegation import get_blocked_child_tools
+        blocked_tools = sorted(get_blocked_child_tools())
+    except Exception:
+        # Fallback if tools import fails
+        blocked_tools = []
+
+    info = {
+        "delegation_enabled": TimeoutConfig.get_sub_agents_enabled(),
+        "max_concurrent": TimeoutConfig.get_max_concurrent_sub_agents(),
+        "max_depth": TimeoutConfig.get_max_sub_agent_depth(),
+        "max_async": TimeoutConfig.get_max_async_sub_agents(),
+        "sync_timeout": TimeoutConfig.get_sub_agent_timeout(),
+        # The parallel/async (background) delegation path uses its own longer
+        # timeout, not the sync one — report the real value.
+        "async_timeout": TimeoutConfig.get_parallel_subtasks_timeout(),
+        "blocked_tools": blocked_tools,
+    }
+
+    if as_json:
+        click.echo(json.dumps(info, indent=2))
+    else:
+        click.echo("Delegation Capability:")
+        click.echo(f"  Enabled: {info['delegation_enabled']}")
+        click.echo(f"  Max concurrent: {info['max_concurrent']}")
+        click.echo(f"  Max depth: {info['max_depth']}")
+        click.echo(f"  Max background: {info['max_async']}")
+        click.echo(f"  Sync timeout: {info['sync_timeout']}s")
+        click.echo(f"  Async timeout: {info['async_timeout']}s")
+        if info['blocked_tools']:
+            click.echo(f"  Blocked tools: {', '.join(info['blocked_tools'])}")
+
+
+@subagents.command("list")
+@click.option("--session-id", help="Session to inspect (requires live session or persisted data).")
+@click.option("--json", "as_json", is_flag=True, help="Print machine-readable JSON.")
+def subagents_list(session_id: Optional[str], as_json: bool):
+    """List subagents/delegations.
+
+    Note: Delegations are currently in-memory and session-scoped. Without a live
+    session connection, this can only show persisted records (future work).
+    """
+    if as_json:
+        click.echo(json.dumps({
+            "supported": False, "delegations": [],
+            "reason": "CLI delegation introspection is not yet persisted; "
+                      "use /subagents in a live REPL session.",
+        }, indent=2))
+        return
+    if session_id:
+        click.echo(click.style("[polyrob] ", fg="yellow") +
+                   "Live session introspection requires API/WebView connection")
+        click.echo("CLI will support persisted delegation records in a future update")
+    else:
+        click.echo("Use /subagents in an active REPL session, or specify --session-id for persisted records")
+
+
+@subagents.command("show")
+@click.argument("delegation_id")
+@click.option("--json", "as_json", is_flag=True, help="Print machine-readable JSON.")
+def subagents_show(delegation_id: str, as_json: bool):
+    """Show details for a specific delegation."""
+    if as_json:
+        click.echo(json.dumps({
+            "supported": False, "delegation_id": delegation_id,
+            "reason": "CLI delegation introspection is not yet persisted; "
+                      "use /subagents in a live REPL session.",
+        }, indent=2))
+        return
+    click.echo(click.style("[polyrob] ", fg="yellow") +
+               "Live delegation introspection requires API/WebView connection")
+    click.echo("CLI will support persisted delegation records in a future update")

cli/commands/surface.py

@@ -0,0 +1,81 @@
+"""polyrob surface — operator controls for per-surface circuit breakers.
+
+The worker process owns an in-memory SurfaceCircuitBreaker that auto-opens after
+K consecutive failures. The CLI process is SEPARATE, so pause/resume are persisted
+to a tiny SQLite table (data/surface_state.db) that the worker reads on each
+is_open() call (when its breaker is built with a CircuitStore attached).
+
+Commands:
+    polyrob surface list              Show all known surfaces and their paused state.
+    polyrob surface pause <id>        Pause a surface (writes to the store).
+    polyrob surface resume <id>       Resume a surface (clears the stored flag).
+"""
+import os
+
+import click
+
+
+def _data_dir() -> str:
+    # Match the worker's data home (build_cli_container's _resolve_cli_data_home =
+    # <cwd>/.polyrob by default) so pause/resume write the SAME surface_state.db the
+    # worker reads — 'POLYROB_DATA_DIR or data' pointed the CLI at a divergent ./data.
+    from core.bootstrap import _resolve_cli_data_home
+    data_home, _, _ = _resolve_cli_data_home()
+    return str(data_home)
+
+
+def _store():
+    from core.surfaces.circuit import CircuitStore
+    return CircuitStore(os.path.join(_data_dir(), "surface_state.db"))
+
+
+def _warn_if_breaker_inert() -> None:
+    """pause/resume only bite if the worker built a CircuitStore-backed breaker, which
+    it does ONLY when OUTBOUND_QUEUE_ENABLED is on. Warn so the operator isn't misled
+    by a 'paused' that has no effect."""
+    from agents.task.surface_config import SurfaceConfig
+    if not SurfaceConfig.outbound_queue_enabled():
+        click.echo(click.style(
+            "note: OUTBOUND_QUEUE_ENABLED is off — the worker builds no circuit breaker, "
+            "so this is recorded but has NO effect until you enable it.", fg="yellow"))
+
+
+@click.group()
+def surface():
+    """Inspect and control per-surface circuit breakers."""
+
+
+@surface.command("list")
+def list_surfaces():
+    """List surfaces and their persisted paused state."""
+    rows = _store().list_all()
+    if not rows:
+        click.echo(click.style("no surface state entries", dim=True))
+        click.echo(click.style("(surfaces are auto-registered when first paused)", dim=True))
+        return
+    for r in rows:
+        status = (
+            click.style("PAUSED", fg="red", bold=True)
+            if r["paused"]
+            else click.style("active", fg="green")
+        )
+        click.echo(f"  {r['surface_id']:<20} {status}")
+
+
+@surface.command("pause")
+@click.argument("surface_id")
+def pause_surface(surface_id: str):
+    """Pause a surface — the worker will skip it until resumed."""
+    _store().pause(surface_id)
+    click.echo(click.style(f"paused: {surface_id}", fg="yellow"))
+    click.echo(click.style("worker will defer outbound messages for this surface", dim=True))
+    _warn_if_breaker_inert()
+
+
+@surface.command("resume")
+@click.argument("surface_id")
+def resume_surface(surface_id: str):
+    """Resume a paused surface — the worker will start delivering again."""
+    _store().resume(surface_id)
+    click.echo(click.style(f"resumed: {surface_id}", fg="green"))
+    _warn_if_breaker_inert()

cli/commands/telegram.py

@@ -0,0 +1,185 @@
+"""polyrob telegram — chat with the agent over Telegram via local long-polling.
+
+No webhook / public URL / SSL needed: this long-polls getUpdates on your machine and
+runs the full Task agent (same front door as the API webhook path). Owner-locked via
+ALLOWED_TELEGRAM_USER_IDS (raw Telegram numeric ids); with no allowlist set the bot
+replies with your id so you can lock it.
+
+Token: --token or TELEGRAM_BOT_TOKEN (process env or ./.polyrob/.env). Nothing is committed.
+"""
+import asyncio
+import os
+import signal
+import sys
+from typing import Optional
+
+import click
+
+
+class TelegramTokenError(click.ClickException):
+    """No Telegram bot token available."""
+
+
+def resolve_telegram_token(token_opt: Optional[str]) -> str:
+    """--token wins, else TELEGRAM_BOT_TOKEN env; raise a clear error if absent."""
+    tok = (token_opt or os.environ.get("TELEGRAM_BOT_TOKEN") or "").strip()
+    if not tok:
+        raise TelegramTokenError(
+            "No Telegram bot token. Pass --token, or set TELEGRAM_BOT_TOKEN "
+            "(process env or ./.polyrob/.env). Create a bot via @BotFather to get one."
+        )
+    return tok
+
+
+@click.command()
+@click.option("--token", default=None, help="Telegram bot token (else TELEGRAM_BOT_TOKEN env)")
+@click.option("--verbose", "-v", is_flag=True, help="Show debug logging")
+def telegram(token: Optional[str], verbose: bool):
+    """Run the agent as a Telegram bot (local long-polling)."""
+    asyncio.run(_run_telegram(token, verbose))
+
+
+async def _run_telegram(token_opt: Optional[str], verbose: bool):
+    import logging as _logging
+
+    from core.bootstrap import build_cli_container, setup_project_path, setup_sqlite_compat
+
+    # The outbound bus + binding are gated on SINGULAR_CHAT_ENABLED; the surface gate
+    # is TELEGRAM_SURFACE_ENABLED. Default them ON for this command (explicit env wins),
+    # BEFORE the container build so the bus installs during TaskAgent construction too.
+    os.environ.setdefault("SINGULAR_CHAT_ENABLED", "true")
+    os.environ.setdefault("TELEGRAM_SURFACE_ENABLED", "true")
+
+    setup_project_path()
+    setup_sqlite_compat()
+
+    # No usable provider key → clean canonical message + exit (a daemon must not block
+    # on an interactive wizard). Loads env layers internally.
+    from cli.keys import preflight_or_onboard
+    if not preflight_or_onboard(interactive=False):
+        sys.exit(1)
+
+    # Resolve the bot token NOW — preflight_or_onboard already loaded the env layers
+    # (./.polyrob/.env etc.), so fail fast on a missing token (a clean ClickException)
+    # instead of paying a full container build first.
+    token = resolve_telegram_token(token_opt)
+
+    # A headless run (systemd: stderr is the journal, not a TTY) MUST log — a server
+    # with no logs is unoperable. An interactive run keeps the console clean. `-v` always
+    # gives DEBUG. So: verbose->DEBUG; headless->INFO to the journal; interactive->quiet.
+    headless = not sys.stderr.isatty()
+    if verbose:
+        log_level = "DEBUG"
+    elif headless:
+        log_level = "INFO"
+    else:
+        log_level = "ERROR"
+    quiet = (not verbose) and (not headless)
+    if quiet:
+        _logging.disable(_logging.CRITICAL)
+        os.environ["GRPC_VERBOSITY"] = "ERROR"
+        os.environ["GLOG_minloglevel"] = "3"
+
+    try:
+        container = await build_cli_container(log_level=log_level)
+    except Exception as e:
+        click.echo(click.style("[polyrob] ERROR: ", fg="red") + f"failed to start: {e}")
+        sys.exit(1)
+    if quiet:
+        _logging.disable(_logging.ERROR)
+    elif not verbose:
+        # Headless service: app logs at INFO in the journal, but silence the noisy
+        # transport libraries (long-poll getUpdates, aiogram dispatcher, asyncio).
+        for _noisy in ("httpx", "httpcore", "aiogram.event", "asyncio", "hpack"):
+            _logging.getLogger(_noisy).setLevel(_logging.WARNING)
+
+    task_agent = container.get_agent("task_agent")
+    if not task_agent:
+        click.echo(click.style("[polyrob] ERROR: ", fg="red") + "TaskAgent not available in container")
+        sys.exit(1)
+
+    # Install the outbound bus (idempotent; gated on SINGULAR_CHAT_ENABLED) so agent
+    # replies can route out to the Telegram surface.
+    from core.surfaces.bootstrap import install_surface_bus
+    install_surface_bus(container)  # db_path defaults to container.config.data_dir
+
+    dispatcher = container.get_service("outbound_dispatcher")
+    if dispatcher is not None:
+        dispatcher.start()
+
+    from surfaces.telegram.harness import build_telegram_harness
+    # Pin harness state DBs (dedup / user directory) to the container's data_dir so
+    # per-instance isolation holds under POLYROB_DATA_DIR (else they land in ./data).
+    _data_dir = getattr(getattr(container, "config", None), "data_dir", "data") or "data"
+    harness = build_telegram_harness(container, task_agent, token=token, webhook_base=None,
+                                     data_dir=_data_dir)
+
+    # start() registers + subscribes the surface and clears any stale webhook.
+    await harness.start()
+
+    # Start the autonomy background loops under the local profile — the SAME shared
+    # runtime the REPL + API lifespan use. Crucially this is what runs the #6 surface-GC
+    # ticker that prunes stale chat<->session bindings; without it GC would be dead on
+    # the primary Telegram surface (the one that mints those bindings). Fail-open.
+    autonomy_handles = None
+    try:
+        from agents.task.constants import local_mode_enabled
+        if local_mode_enabled():
+            from core.autonomy_runtime import start_autonomy
+            _data_dir = getattr(getattr(container, "config", None), "data_dir", "data")
+            autonomy_handles = start_autonomy(task_agent=task_agent, data_dir=_data_dir)
+    except Exception:
+        autonomy_handles = None
+
+    # Greet: confirm which bot we're driving + the owner-lock state.
+    try:
+        me = await harness.bot.get_me()
+        username = getattr(me, "username", None)
+    except Exception:
+        username = None
+    allow = (os.environ.get("ALLOWED_TELEGRAM_USER_IDS") or "").strip()
+    click.echo(click.style("telegram bot online", fg="green")
+               + (f": @{username}" if username else ""))
+    if allow:
+        click.echo(click.style(f"owner-locked to user id(s): {allow}", dim=True))
+    else:
+        click.echo(click.style(
+            "no allowlist set — message the bot once and it will reply with your id, "
+            "then set ALLOWED_TELEGRAM_USER_IDS and restart.", fg="yellow"))
+    click.echo(click.style("polling… (Ctrl-C to stop)", dim=True))
+
+    # Clean shutdown on Ctrl-C: stop the loop, then close the bot session.
+    loop = asyncio.get_running_loop()
+    poll_task = asyncio.ensure_future(harness.run_polling())
+
+    def _stop(*_a):
+        harness._running = False
+        poll_task.cancel()
+
+    try:
+        loop.add_signal_handler(signal.SIGINT, _stop)
+        loop.add_signal_handler(signal.SIGTERM, _stop)
+    except (NotImplementedError, RuntimeError):
+        for _sig in (signal.SIGINT, signal.SIGTERM):
+            try:
+                signal.signal(_sig, lambda *_a: _stop())
+            except (ValueError, OSError, AttributeError):
+                pass  # SIGTERM may be unavailable on some platforms/threads
+
+    try:
+        await poll_task
+    except asyncio.CancelledError:
+        pass
+    finally:
+        click.echo("\n" + click.style("stopping telegram bot…", dim=True))
+        if autonomy_handles is not None:
+            try:
+                await autonomy_handles.stop()
+            except Exception:
+                pass
+        if dispatcher is not None:
+            try:
+                await dispatcher.stop()
+            except Exception:
+                pass
+        await harness.stop()