stackops 26.9.2__tar.gz → 26.9.3__tar.gz

{stackops-26.9.2/src/stackops.egg-info → stackops-26.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackops
-Version: 26.9.2
+Version: 26.9.3
 Summary: Developer Stack Manager
 Author-email: Alex Al-Saffar <programmer@usa.com>
 License: Apache 2.0

{stackops-26.9.2 → stackops-26.9.3}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stackops"
-version = "26.9.2"
+version = "26.9.3"
 description = "Developer Stack Manager"
 readme = "README.md"
 license = {text = "Apache 2.0"}

{stackops-26.9.2 → stackops-26.9.3}/src/stackops/cluster/sessions_managers/utils/maker.py

@@ -6,7 +6,7 @@ from typing import Final, Literal
 from stackops.utils.schemas.layouts.layout_types import LayoutConfig, TabConfig
 
 
-PYTHON_PROCESS_LAUNCHERS: Final[frozenset[str]] = frozenset({"uv", "python", "python3", "fire", "b", "bi", "bo", "bp"})
+PYTHON_PROCESS_LAUNCHERS: Final[frozenset[str]] = frozenset({"uv", "python", "python3", "fire", "f", "b", "bi", "bo", "bp"})
 WRAP_STACKOPS_PYTHON_SUBCOMMANDS: Final[frozenset[str]] = frozenset({"fire", "uv"})
 
 
@@ -35,11 +35,11 @@ def _prepend_random_stagger(command: str, max_stagger: float | None) -> str:
     system = platform.system().lower()
     if system == "windows":
         sleep_milliseconds = round(random_time * 1000)
-        ps_script = f"Start-Sleep -Milliseconds {sleep_milliseconds}\n{command}"
+        ps_script = f"$env:UV_NO_SYNC = '1'\nStart-Sleep -Milliseconds {sleep_milliseconds}\n{command}"
         encoded_script = base64.b64encode(ps_script.encode("utf-16-le")).decode("ascii")
         return f"powershell -NoProfile -ExecutionPolicy Bypass -EncodedCommand {encoded_script}"
     if system == "linux" or system == "darwin":
-        shell_script = f"sleep {random_time:.6f}; {command}"
+        shell_script = f"export UV_NO_SYNC=1; sleep {random_time:.6f}; {command}"
         return f"bash -lc {shlex.quote(shell_script)}"
     raise ValueError(f"Unsupported platform: {platform.system()}")
 
@@ -53,7 +53,8 @@ def get_fire_tab_using_uv(func: FunctionType, tab_weight: int, import_module: bo
         py_script =  lambda_to_python_script(lambda: func(),
                                              in_global=True, import_module=import_module)
     from stackops.utils.code import get_uv_command_executing_python_script
-    command_to_run, py_script_path = get_uv_command_executing_python_script(python_script=py_script, uv_with=uv_with, uv_project_dir=uv_project_dir, uv_run_flags=uv_run_flags)
+    no_sync_uv_run_flags = "--no-sync" if uv_run_flags == "" else f"--no-sync {uv_run_flags}"
+    command_to_run, py_script_path = get_uv_command_executing_python_script(python_script=py_script, uv_with=uv_with, uv_project_dir=uv_project_dir, uv_run_flags=no_sync_uv_run_flags)
     tab_config: TabConfig = {
         "command": command_to_run,
         "startDir": start_dir,

{stackops-26.9.2 → stackops-26.9.3}/src/stackops/scripts/python/agents.py

@@ -12,6 +12,7 @@ from typer.core import TyperGroup
 from stackops.scripts.python.helpers.helpers_agents.mcp_types import MCP_CATALOG_SOURCE
 from stackops.scripts.python.helpers.helpers_agents.reasoning_capabilities import ReasoningEffort, ReasoningShortcut
 from stackops.utils.cli_utils.alias_markers import apply_alias_markers
+from stackops.utils.sandbox.options import SandboxBackend, SandboxOptions
 from stackops.utils.schemas.fire_agents.fire_agents_types import AGENTS, CONFIG_AGENT_VALUES, CONFIG_AGENTS, DEFAULT_AGENT
 
 _MCP_INSTALL_SCOPE: TypeAlias = Literal["local", "global"]
@@ -57,7 +58,6 @@ _AGENTS_COMMAND_PANEL_ORDER: Final[tuple[str, ...]] = (
     "ask",
     "parallel",
     "iter",
-    "clean",
 )
 
 
@@ -247,6 +247,31 @@ def run_interactive(
         bool,
         typer.Option(..., "--fork", "-F", help="Fork the selected follow-up into a new session instead of resuming it."),
     ] = False,
+    sandbox: Annotated[
+        SandboxBackend,
+        typer.Option(
+            "--sandbox", "-S",
+            help=(
+                "Sandbox provider (default: none). Docker/Podman need Linux containers and --sandbox-image; "
+                "bwrap provides Linux write isolation with host reads/network allowed; ai-jail supports Linux/macOS (Windows via WSL2); "
+                "srt needs --sandbox-settings (native Windows is alpha and requires a native .exe agent)."
+            ),
+        ),
+    ] = SandboxBackend.NONE,
+    sandbox_image: Annotated[
+        str | None,
+        typer.Option(
+            "--sandbox-image",
+            help="Docker/Podman Linux image with agent/tools installed globally on PATH, outside HOME. Workspace and agent state are mounted writable.",
+        ),
+    ] = None,
+    sandbox_settings: Annotated[
+        Path | None,
+        typer.Option(
+            "--sandbox-settings", exists=True, dir_okay=False, resolve_path=True,
+            help="SRT JSON policy granting agent network, executable, workspace and state access. Windows also needs srt windows-install.",
+        ),
+    ] = None,
 ) -> None:
     """Launch an agent with reasonable defaults."""
     import shlex
@@ -254,6 +279,15 @@ def run_interactive(
     try:
         if fork and not followup:
             raise ValueError("--fork requires --followup.")
+        from stackops.scripts.python.helpers.helpers_agents.agents_shell import is_windows_host
+        from stackops.utils.sandbox.launch import build_sandbox_command, validate_sandbox_options
+
+        sandbox_options = SandboxOptions(backend=sandbox, image=sandbox_image, settings=sandbox_settings)
+        validate_sandbox_options(sandbox_options)
+        if headroom and sandbox in (SandboxBackend.DOCKER, SandboxBackend.PODMAN, SandboxBackend.AI_JAIL):
+            raise ValueError("--headroom can be sandboxed with bwrap or an srt policy granting both headroom and agent access.")
+        if followup and sandbox in (SandboxBackend.DOCKER, SandboxBackend.PODMAN) and is_windows_host():
+            raise ValueError("Container follow-up on Windows cannot reuse host session paths. Run agents inside WSL2.")
 
         with _agent_working_directory(second_brain=second_brain or followup) as working_directory:
             if followup:
@@ -271,7 +305,24 @@ def run_interactive(
                 command = _interactive_agent_command(agent=resolved_agent, caveman=caveman)
 
             command = _apply_headroom(command=command, agent=resolved_agent, headroom=headroom)
-            script = shlex.join(command)
+            if sandbox != SandboxBackend.NONE:
+                import sys
+
+                from stackops.scripts.python.helpers.helpers_agents.agents_sandbox import resolve_sandbox_access
+                from stackops.scripts.python.helpers.helpers_agents.agents_shell import quote_for_shell
+
+                access = resolve_sandbox_access(agent=resolved_agent)
+                command = build_sandbox_command(
+                    command=command, options=sandbox_options, directory=Path.cwd(),
+                    access=access, read_only_paths=(),
+                    interactive=sys.stdin.isatty() and sys.stdout.isatty(),
+                )
+                if is_windows_host():
+                    script = "& " + " ".join(quote_for_shell(argument, is_windows=True) for argument in command)
+                else:
+                    script = shlex.join(command)
+            else:
+                script = shlex.join(command)
             if working_directory is not None:
                 from stackops.scripts.python.helpers.helpers_agents.agents_shell import render_command_in_directory
 
@@ -332,7 +383,7 @@ def run_prompt(
         typer.Option(
             ...,
             "--skill",
-            "-S",
+            "-k",
             help="Reference a supported agent skill on the fly (see agents add-skill). The skill is referenced, never installed. Pass an empty value to pick interactively.",
         ),
     ] = None,
@@ -358,6 +409,27 @@ def run_prompt(
             help="Open prompts YAML in an editor (hx preferred, nano fallback). If no prompt/context input is provided, exits after editing.",
         ),
     ] = False,
+    sandbox: Annotated[
+        SandboxBackend,
+        typer.Option(
+            "--sandbox", "-S",
+            help=(
+                "Sandbox provider (default: none). Docker/Podman require --sandbox-image; bwrap requires Linux; "
+                "ai-jail supports Linux/macOS (Windows via WSL2); srt requires --sandbox-settings."
+            ),
+        ),
+    ] = SandboxBackend.NONE,
+    sandbox_image: Annotated[
+        str | None,
+        typer.Option("--sandbox-image", help="Linux image with agent/tools installed globally on PATH, outside HOME."),
+    ] = None,
+    sandbox_settings: Annotated[
+        Path | None,
+        typer.Option(
+            "--sandbox-settings", exists=True, dir_okay=False, resolve_path=True,
+            help="SRT JSON policy granting network, workspace, agent state and prompt/config-file access. Native Windows needs srt windows-install and an agent .exe.",
+        ),
+    ] = None,
 ) -> None:
     """Run one prompt via selected agent."""
     from stackops.scripts.python.helpers.helpers_agents.agents_run_impl import run as impl
@@ -377,6 +449,7 @@ def run_prompt(
                 edit=edit,
                 show_prompts_yaml_format=show_prompts_yaml_format,
                 working_directory=working_directory,
+                sandbox_options=SandboxOptions(backend=sandbox, image=sandbox_image, settings=sandbox_settings),
             )
     except ValueError as e:
         raise typer.BadParameter(str(e)) from e
@@ -465,18 +538,6 @@ def add_skill(
     raise typer.Exit(code=return_code)
 
 
-def clean(
-    directory: Annotated[str | None, typer.Argument(help="Directory containing repositories to clean.")] = None,
-    recursive: Annotated[bool, typer.Option("--recursive", "-r", help="Recurse into nested repositories.")] = False,
-) -> None:
-    """Delete the .ai directory from each selected repository."""
-    from stackops.scripts.python.helpers.helpers_agents.agents_clean import clean_agent_directories
-
-    repositories_found = clean_agent_directories(directory=directory, recursive=recursive)
-    if not repositories_found:
-        raise typer.Exit(code=1)
-
-
 def doctor(
     agent: Annotated[
         str,
@@ -502,11 +563,19 @@ def doctor(
             help="Comma-separated resource focuses: all, configuration, mcp, hook, plugin, skill, or instructions.",
         ),
     ] = "all",
+    tui: Annotated[bool, typer.Option("--tui", "-t", help="Browse agent health and resources in a terminal app.")] = False,
 ) -> None:
     """Inspect agent binaries, configuration, hooks, plugins, skills, and instruction provenance."""
     from stackops.scripts.python.helpers.helpers_agents.agents_doctor.command import run_doctor
 
     working_directory = directory if directory is not None else Path.cwd()
+    if tui:
+        from stackops.scripts.python.helpers.helpers_agents.agents_doctor.tui_launch import launch_agent_tui
+
+        launch_agent_tui(
+            mode="doctor", agent=agent, directory=str(working_directory), resource=resource, scope="all", match=None, recursive=False,
+        )
+        return
     try:
         complete = run_doctor(requested_agent=agent, working_directory=working_directory, requested_resources=resource)
     except ValueError as error:
@@ -554,11 +623,13 @@ def get_app() -> typer.Typer:
         "add-config", no_args_is_help=True, help=init_config.__doc__, short_help="<c> Initialize AI configurations in the current repository"
     )(init_config)
     agents_app.command("c", no_args_is_help=True, help=init_config.__doc__, hidden=True)(init_config)
-    agents_app.command(name="clean", no_args_is_help=False, short_help="<C> Delete .ai directories from repositories")(clean)
-    agents_app.command(name="C", no_args_is_help=False, hidden=True)(clean)
+    agents_app.command(
+        name="depoison", no_args_is_help=False, short_help="<D> Preview or reset agent customizations and .ai folders",
+        help="Preview or reset agent customizations and repository .ai folders. Use --resource workspace for .ai folders only. Changes require --apply or interactive confirmation and preserve backups.",
+    )(depoison)
+    agents_app.command(name="D", no_args_is_help=False, hidden=True)(depoison)
     agents_app.command(name="doctor", no_args_is_help=False, short_help="<d> Inspect agent health and resource provenance")(doctor)
     agents_app.command(name="d", no_args_is_help=False, hidden=True)(doctor)
-    agents_app.command(name="depoison", no_args_is_help=False, short_help="Preview or reset agent customizations")(depoison)
 
     agents_app.command(name="run-prompt", no_args_is_help=False, short_help="<r> Run one prompt via selected agent")(run_prompt)
     agents_app.command(name="r", no_args_is_help=False, hidden=True)(run_prompt)
@@ -566,6 +637,7 @@ def get_app() -> typer.Typer:
         run_interactive
     )
     agents_app.command(name="i", no_args_is_help=False, hidden=True)(run_interactive)
+    agents_app.command(name="run", no_args_is_help=False, hidden=True)(run_interactive)
     agents_app.command(name="ask", no_args_is_help=True, short_help="<a> Ask a selected agent directly")(ask)
     agents_app.command(name="a", no_args_is_help=True, hidden=True)(ask)
     return apply_alias_markers(agents_app)

stackops-26.9.3/src/stackops/scripts/python/agents_depoison.py

@@ -0,0 +1,151 @@
+import subprocess
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from stackops.scripts.python.helpers.helpers_agents.agents_doctor.cleanup_models import CleanupScope
+
+
+def depoison(
+    agent: Annotated[str, typer.Argument(help="Agent to reset, or all.")] = "all",
+    directory: Annotated[Path | None, typer.Option("--directory", "-d", exists=True, file_okay=False, help="Inspect a project or a directory containing repositories.")] = None,
+    scope: Annotated[CleanupScope, typer.Option("--scope", "-s", help="Select local, global, or all resources. Workspace folders are local.")] = "all",
+    resource: Annotated[str, typer.Option("--resource", "-r", help="Comma-separated resources: all, workspace (.ai folders), hook, plugin, mcp, skill, instructions, configuration.")] = "all",
+    recursive: Annotated[bool, typer.Option("--recursive", "-R", help="Recurse into nested repositories when collecting .ai folders.")] = False,
+    match: Annotated[str | None, typer.Option("--match", "-m", help="Select resources by name, command, or source path substring.")] = None,
+    apply: Annotated[bool, typer.Option("--apply", "-a", help="Apply the displayed reset and keep original files in quarantine.")] = False,
+    interactive: Annotated[
+        bool, typer.Option("--interactive", "-i", help="Choose targets, inspect status, and confirm a reset step by step (even with --apply).")
+    ] = False,
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Show every resource, state, command, and source path.")] = False,
+    tui: Annotated[
+        bool, typer.Option("--tui", "-t", help="Browse resources and select resets in a terminal app; always confirm before applying, even with --apply.")
+    ] = False,
+) -> None:
+    if tui:
+        from stackops.scripts.python.helpers.helpers_agents.agents_doctor.tui_launch import launch_agent_tui
+
+        launch_agent_tui(
+            mode="depoison", agent=agent, directory=str(directory if directory is not None else Path.cwd()),
+            resource=resource, scope=scope, match=match, recursive=recursive,
+        )
+        return
+    from stackops.utils.meta import lambda_to_python_script
+
+    worker_source = lambda_to_python_script(
+        lambda: _run_depoison(
+            agent=agent,
+            directory=str(directory if directory is not None else Path.cwd()),
+            scope=scope,
+            resource=resource,
+            recursive=recursive,
+            match=match,
+            apply=apply,
+            interactive=interactive,
+            verbose=verbose,
+        ),
+        in_global=True,
+        import_module=False,
+    )
+    result = subprocess.run(
+        ["uv", "run", "--no-project", "--python", sys.executable, "--with", "tomlkit", "python", "-c", worker_source],
+        check=False,
+    )
+    raise typer.Exit(code=result.returncode)
+
+
+def _run_depoison(
+    *, agent: str, directory: str, scope: CleanupScope, resource: str, recursive: bool,
+    match: str | None, apply: bool, interactive: bool, verbose: bool,
+) -> None:
+    from pathlib import Path
+
+    import typer
+    from rich.console import Console
+    from rich.panel import Panel
+    from rich.text import Text
+
+    from stackops.scripts.python.helpers.helpers_agents.agents_doctor.cleanup_apply import apply_cleanup_plan
+    from stackops.scripts.python.helpers.helpers_agents.agents_doctor.cleanup_interactive import (
+        CleanupSelection,
+        choose_cleanup_action,
+        prompt_cleanup_selection,
+    )
+    from stackops.scripts.python.helpers.helpers_agents.agents_doctor.cleanup_output import render_cleanup_plan, render_cleanup_result
+    from stackops.scripts.python.helpers.helpers_agents.agents_doctor.cleanup_plan import build_cleanup_plan
+    from stackops.scripts.python.helpers.helpers_agents.agents_doctor.cleanup_resources import collect_cleanup_resources
+    from stackops.scripts.python.helpers.helpers_agents.agents_doctor.cleanup_workspace import collect_workspace_resources, resolve_cleanup_resources
+    from stackops.scripts.python.helpers.helpers_agents.agents_doctor.hooks.discovery import collect_hooks
+    from stackops.scripts.python.helpers.helpers_agents.agents_doctor.hooks.models import HookInventory
+    from stackops.scripts.python.helpers.helpers_agents.agents_doctor.registry import resolve_doctor_definitions
+    from stackops.scripts.python.helpers.helpers_agents.agents_doctor.scanning import create_doctor_context
+
+    console = Console()
+    error_console = Console(stderr=True)
+    try:
+        selection = CleanupSelection(agent=agent, directory=directory, scope=scope, resource=resource, match=match, recursive=recursive)
+        while True:
+            if interactive:
+                selection = prompt_cleanup_selection(selection=selection, console=console)
+                console.rule("Step 2/4 · Inspect current resources", style="cyan")
+            context = create_doctor_context(working_directory=Path(selection.directory))
+            definitions = resolve_doctor_definitions(requested_agent=selection.agent)
+            focuses, include_workspace = resolve_cleanup_resources(requested_resources=selection.resource)
+            with console.status("Inspecting resources...") as status:
+                inventories: list[HookInventory] = []
+                for definition in definitions:
+                    status.update(Text(f"""Inspecting {definition.display_name}..."""))
+                    if "all" in focuses or "hook" in focuses:
+                        inventories.append(collect_hooks(agent=definition.agent, context=context))
+                    if focuses and focuses != ("hook",):
+                        inventories.append(collect_cleanup_resources(agent=definition.agent, context=context, resource_focuses=focuses))
+                if include_workspace and selection.scope != "global":
+                    status.update("Inspecting repository .ai folders...")
+                    inventories.append(collect_workspace_resources(context=context, recursive=selection.recursive))
+                inventory = HookInventory(
+                    entries=tuple(entry for item in inventories for entry in item.entries),
+                    diagnostics=tuple(diagnostic for item in inventories for diagnostic in item.diagnostics),
+                )
+                status.update("Building reset plan...")
+                plan = build_cleanup_plan(inventory=inventory, scope=selection.scope, match=selection.match, home_directory=context.home_directory)
+            if interactive:
+                console.rule("Step 3/4 · Review the reset plan", style="cyan")
+            render_cleanup_plan(
+                console=console, error_console=error_console, plan=plan, inventory=inventory,
+                context=context, selection=selection, applying=apply and not interactive, verbose=verbose,
+            )
+            if interactive:
+                action = choose_cleanup_action(
+                    plan=plan, backup_root=context.home_directory / ".local" / "state" / "stackops" / "depoison", console=console,
+                )
+                if action == "revise":
+                    continue
+                if action == "exit":
+                    console.rule("Step 4/4 · Finished", style="cyan")
+                    console.print("[dim]No files changed.[/dim]")
+                    raise SystemExit(1 if plan.blockers else 0)
+                console.rule("Step 4/4 · Back up originals and apply", style="cyan")
+            elif plan.blockers:
+                raise SystemExit(1)
+            elif not apply:
+                if plan.changes:
+                    console.print(Panel(
+                        "Preview only. Add [bold]--apply[/bold] to perform this reset and preserve backups.",
+                        title="Next step", border_style="cyan",
+                    ))
+                raise SystemExit(0)
+            break
+        result = apply_cleanup_plan(
+            plan=plan,
+            backup_root=context.home_directory / ".local" / "state" / "stackops" / "depoison",
+            home_directory=context.home_directory,
+        )
+        render_cleanup_result(console=console, result=result)
+    except (typer.Abort, KeyboardInterrupt) as error:
+        error_console.print("[yellow]Cancelled.[/yellow]")
+        raise SystemExit(1) from error
+    except (OSError, ValueError) as error:
+        error_console.print(Panel(Text(str(error)), title="Error: reset failed", border_style="red"))
+        raise SystemExit(2) from error

{stackops-26.9.2 → stackops-26.9.3}/src/stackops/scripts/python/agents_parallel_commands.py

@@ -245,6 +245,7 @@ def create_context(
 
     from stackops.scripts.python.helpers.helpers_agents.agents_run_impl import run as impl
     from stackops.utils.accessories import get_repo_root
+    from stackops.utils.sandbox.options import SandboxBackend, SandboxOptions
 
     repo_root = get_repo_root(Path.cwd())
     if repo_root is None:
@@ -276,6 +277,7 @@ def create_context(
                 edit=False,
                 show_prompts_yaml_format=False,
                 working_directory=repo_root,
+                sandbox_options=SandboxOptions(backend=SandboxBackend.NONE, image=None, settings=None),
             )
     except SystemExit as e:
         exit_code = e.code if isinstance(e.code, int) else 0 if e.code is None else 1

{stackops-26.9.2 → stackops-26.9.3}/src/stackops/scripts/python/agents_second_brain.instructions.md

@@ -12,6 +12,10 @@ Columns are: agent, session-id, topic, actionsTaken, date
 create the file if it doesn't exist.
 session id is the agent session id, you probably have it in env variables or somewhere, its agent dependent. This allows user to follow up on discussion or get more context on work done.
 
+# Ethos of maintinance of second-brain
+* The second-brain is meant to be a mirror of the human user. Thus, if the agent was creating and dumping files around the place, we quickly run a risk of developing a place that the human user cannot recognize nor associate with, even though, those files are absolutely necessary context to get the jobs done, or keep track of details of how the job was done etc. To solve this dilemma, we either put those byproduct files in a space relevant to the job, e.g. a repo, or (more preferrably) we put those files in `.agents` directories across the relevant folders in second-brain, in order to distinguish them from md files that contain kknowledge that the human user is aware of of, because they talked about it. Still, even within .agents dir, please make sure to behave and keep it a clean spaces, so other agents in the future can find there way around easily.
+
+
 # Specialized agents, skills, connectors, and other resources:
 They live under `~/code/agents`. For a matching task, use the relevant project and read its local `AGENTS.md`, `SKILL.md`, or `README.md` before starting. When it comes to outlook, confluence or slack, please never every use standard browser/chrome skills, always make sure to use the specialized connections instead of using generic browser-use or computer-use capability if that's under your disposal.