praisonai-code 0.0.53__tar.gz → 0.0.55__tar.gz

{praisonai_code-0.0.53 → praisonai_code-0.0.55}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: praisonai-code
-Version: 0.0.53
+Version: 0.0.55
 Summary: Agentic terminal CLI for PraisonAI — the terminal-native agent (run, chat, code, runtime, cli backends) extracted from the praisonai wrapper.
 Author: Mervin Praison
 License: MIT

{praisonai_code-0.0.53 → praisonai_code-0.0.55}/praisonai_code/__init__.py

@@ -12,6 +12,6 @@ the remaining terminal-agent modules, with PEP 562 shims left behind at the
 old ``praisonai.*`` paths for backward compatibility.
 """
 
-__version__ = "0.0.53"
+__version__ = "0.0.55"
 
 __all__ = ["__version__"]

{praisonai_code-0.0.53 → praisonai_code-0.0.55}/praisonai_code/cli/app.py

@@ -147,6 +147,7 @@ _LAZY_COMMANDS: Dict[str, Tuple[str, str, str]] = {
     "env": (".commands.environment", "app", "Environment and diagnostics"),
     "auth": (".commands.auth", "app", "Credential management"),
     "session": (".commands.session", "app", "Session management"),
+    "usage": (".commands.usage", "app", "Local token/cost usage reporting"),
     "completion": (".commands.completion", "app", "Shell completion scripts"),
     "version": (".commands.version", "app", "Version information"),
     "upgrade": (".commands.upgrade", "app", "Update the managed PraisonAI CLI install"),
@@ -852,6 +853,7 @@ def main_callback(
     if ctx.invoked_subcommand is None:
         # Check for credentials before starting TUI
         from praisonai_code.llm.credentials import (
+            detect_local_endpoint,
             inject_credentials_into_env,
             is_configured,
         )
@@ -859,43 +861,57 @@ def main_callback(
         
         inject_credentials_into_env()
         if not is_configured():  # Check for any configured credentials
+            # Keyless local-first: if a local OpenAI-compatible endpoint is
+            # reachable (e.g. Ollama), use it as the zero-config default so the
+            # first run works before any auth. Detection is timeout-bounded.
+            local = detect_local_endpoint()
+            if local is not None:
+                typer.echo(
+                    f"No cloud key found; using local model {local.model}. "
+                    "Run `praisonai setup` to add a hosted provider.",
+                    err=True,
+                )
+                # Fall through to the TUI; no gate.
             # In non-interactive mode, just show error
-            if not sys.stdin.isatty() or quiet:
+            elif not sys.stdin.isatty() or quiet:
                 typer.echo(
-                    "Error: No API key configured. Run: praisonai setup",
+                    "Error: No API key configured. Run: praisonai setup\n"
+                    "(a running local endpoint such as Ollama would be used "
+                    "automatically)",
                     err=True
                 )
                 raise typer.Exit(1)
             
-            # In interactive mode, offer to run setup
-            typer.echo("No API key configured.")
-            run_setup = typer.confirm("Would you like to run the setup wizard now?")
-            
-            if run_setup:
-                # Import and run setup
-                from .commands.setup import _run_setup
-                exit_code = _run_setup(
-                    non_interactive=False,
-                    provider=None,
-                    api_key=None,
-                    model=None
-                )
-                if exit_code != 0:
-                    typer.echo("Setup failed. Exiting.", err=True)
-                    raise typer.Exit(exit_code)
-                
-                # Re-check credentials after setup
-                inject_credentials_into_env()
-                if not is_configured():
-                    typer.echo("Setup completed but credentials still not detected.", err=True)
-                    raise typer.Exit(1)
-                
-                # After successful setup, continue to TUI
-                typer.echo("\nSetup complete! Starting interactive mode...\n")
+            # In interactive mode, offer to run setup (non-blocking suggestion)
             else:
-                typer.echo("\nTo configure credentials later, run: praisonai setup")
-                typer.echo("or set environment variables like OPENAI_API_KEY")
-                raise typer.Exit(0)
+                typer.echo("No API key configured.")
+                run_setup = typer.confirm("Would you like to run the setup wizard now?")
+
+                if run_setup:
+                    # Import and run setup
+                    from .commands.setup import _run_setup
+                    exit_code = _run_setup(
+                        non_interactive=False,
+                        provider=None,
+                        api_key=None,
+                        model=None
+                    )
+                    if exit_code != 0:
+                        typer.echo("Setup failed. Exiting.", err=True)
+                        raise typer.Exit(exit_code)
+
+                    # Re-check credentials after setup
+                    inject_credentials_into_env()
+                    if not is_configured():
+                        typer.echo("Setup completed but credentials still not detected.", err=True)
+                        raise typer.Exit(1)
+
+                    # After successful setup, continue to TUI
+                    typer.echo("\nSetup complete! Starting interactive mode...\n")
+                else:
+                    typer.echo("\nTo configure credentials later, run: praisonai setup")
+                    typer.echo("or set environment variables like OPENAI_API_KEY")
+                    raise typer.Exit(0)
         
         from .interactive.async_tui import AsyncTUI, AsyncTUIConfig
 

{praisonai_code-0.0.53 → praisonai_code-0.0.55}/praisonai_code/cli/commands/__init__.py

@@ -15,6 +15,7 @@ __all__ = [
     'traces_app',
     'env_app',
     'session_app',
+    'usage_app',
     'schedule_app',
     'serve_app',
     'completion_app',
@@ -54,6 +55,9 @@ def __getattr__(name: str):
     elif name == 'session_app':
         from .session import app as session_app
         return session_app
+    elif name == 'usage_app':
+        from .usage import app as usage_app
+        return usage_app
     elif name == 'schedule_app':
         from .schedule import app as schedule_app
         return schedule_app

{praisonai_code-0.0.53 → praisonai_code-0.0.55}/praisonai_code/cli/commands/run.py

@@ -4,6 +4,7 @@ Run command group for PraisonAI CLI.
 Provides agent execution commands.
 """
 
+from contextlib import contextmanager
 from typing import Any, Dict, Optional, List
 
 import typer
@@ -663,6 +664,140 @@ def _try_attach_runtime(
     return True
 
 
+@contextmanager
+def _worktree_isolation(enabled: bool, name: str, *, keep: bool = False):
+    """Run the enclosed block inside an isolated git worktree/branch.
+
+    Provisions a fresh worktree via the core ``GitWorktreeAdapter`` and chdirs
+    into it for the duration of the run so the agent edits an isolated branch
+    instead of the working tree. On exit it reports the branch name and a
+    summary of changes (tracked *and* untracked), then tears the worktree down.
+    Degrades to a transparent no-op when isolation is disabled or the directory
+    is not a git repository (the adapter reports ``available=False``), so callers
+    can wrap unconditionally.
+
+    Per-run isolation: a short random token is appended to ``name`` so two
+    concurrent or repeated runs of the same target never resolve to the same
+    worktree/branch and mix each other's uncommitted changes.
+
+    Data-safety on teardown: the agent's output may be entirely *untracked* new
+    files, which ``git diff`` does not see. So before removing the worktree we
+    snapshot any change (tracked or untracked, via ``git status --porcelain``)
+    onto the branch with an automatic commit and *retain that branch* — only the
+    worktree checkout directory is pruned. A run that produced no changes is
+    torn down completely (worktree + branch). ``--keep`` additionally retains the
+    worktree checkout itself for in-place review.
+    """
+    if not enabled:
+        yield None
+        return
+
+    import os
+    import subprocess
+    import uuid
+
+    from praisonaiagents.workspace import GitWorktreeAdapter
+
+    output = get_output_controller()
+    adapter = GitWorktreeAdapter()
+    if not adapter.available:
+        output.print_warning(
+            "Not a git repository; running without worktree isolation."
+        )
+        yield None
+        return
+
+    def _git(*args, cwd):
+        try:
+            return subprocess.run(
+                ["git", *args], cwd=cwd, capture_output=True, text=True
+            )
+        except (FileNotFoundError, OSError):
+            return None
+
+    def _branch_of(worktree_path: str) -> str:
+        result = _git("rev-parse", "--abbrev-ref", "HEAD", cwd=worktree_path)
+        if result is not None and result.returncode == 0:
+            return result.stdout.strip() or "?"
+        return "?"
+
+    def _has_changes(worktree_path: str) -> bool:
+        # ``--porcelain`` reports staged, unstaged *and* untracked entries, so a
+        # run that only creates brand-new files (invisible to ``git diff``) is
+        # still recognised as having produced output.
+        result = _git("status", "--porcelain", cwd=worktree_path)
+        if result is None or result.returncode != 0:
+            return False
+        return bool((result.stdout or "").strip())
+
+    def _summary(worktree_path: str) -> str:
+        result = _git("status", "--short", cwd=worktree_path)
+        if result is None or result.returncode != 0:
+            return ""
+        return (result.stdout or "").strip()
+
+    # Make the run's worktree/branch unique per invocation so identical targets
+    # (same prompt/YAML) run concurrently without sharing state.
+    unique_name = f"{name}-{uuid.uuid4().hex[:8]}"
+
+    original_cwd = os.getcwd()
+    path = adapter.create(unique_name)
+    branch = _branch_of(path)
+    if not output.is_json_mode:
+        output.print_info(f"Isolated run on branch '{branch}' ({path})")
+    os.chdir(path)
+    try:
+        yield path
+    finally:
+        os.chdir(original_cwd)
+
+        summary = _summary(path)
+        changed = _has_changes(path)
+        if not output.is_json_mode:
+            if summary:
+                output.print_info(f"Changes on '{branch}':\n{summary}")
+            else:
+                output.print_info(f"No changes on '{branch}'.")
+
+        if keep:
+            if not output.is_json_mode:
+                output.print_info(
+                    f"Worktree kept at {path} (branch '{branch}'). "
+                    "Review/merge then remove with: git worktree remove."
+                )
+            return
+
+        if changed:
+            # Never destroy the agent's output. Persist every change (tracked +
+            # untracked) as a commit on the isolated branch and retain the
+            # branch; only the worktree checkout directory is pruned.
+            _git("add", "-A", cwd=path)
+            committed = _git(
+                "commit", "--no-verify", "-m", f"praisonai run: {name}", cwd=path
+            )
+            if committed is None or committed.returncode != 0:
+                # Couldn't persist the work (e.g. no git identity configured):
+                # keep the worktree checkout in place so output is never lost.
+                if not output.is_json_mode:
+                    output.print_warning(
+                        f"Could not commit isolated changes; worktree kept at "
+                        f"{path} (branch '{branch}') for manual review."
+                    )
+                return
+            # ``worktree remove`` deletes the checkout but leaves the branch
+            # intact for review/merge (unlike ``adapter.remove`` which also
+            # force-deletes the branch and would lose the committed work).
+            _git("worktree", "remove", "--force", path, cwd=original_cwd)
+            if not output.is_json_mode:
+                output.print_info(
+                    f"Committed changes to branch '{branch}'. "
+                    f"Review/merge with: git merge {branch}"
+                )
+        else:
+            # No output produced: safe to remove worktree and branch entirely.
+            adapter.remove(unique_name)
+
+
 @app.callback(invoke_without_command=True)
 def run_main(
     ctx: typer.Context,
@@ -706,6 +841,9 @@ def run_main(
     restore: Optional[str] = typer.Option(None, "--restore", help="Restore the workspace to a checkpoint id (or 'last') and exit"),
     # Warm-runtime live session: tag this run so other terminals can `attach`.
     attach: Optional[str] = typer.Option(None, "--attach", help="Run on the warm runtime under this session id so other terminals can observe it via `praisonai attach <id>`"),
+    # Per-run git-worktree isolation: run on a fresh branch/worktree.
+    worktree: bool = typer.Option(False, "--worktree", help="Run on an isolated git worktree/branch (branch-per-task); no-op when not a git repo"),
+    keep: bool = typer.Option(False, "--keep", help="With --worktree, keep the worktree/branch after the run for review instead of tearing it down"),
 ):
     """
     Run agents from a file or prompt.
@@ -760,6 +898,7 @@ def run_main(
     # Early credential check before any processing
     if target:  # Only check if we actually have something to run
         from praisonai_code.llm.credentials import (
+            detect_local_endpoint,
             inject_credentials_into_env,
             is_configured,
         )
@@ -768,43 +907,62 @@ def run_main(
         # Check if credentials are configured (use model if provided, else check general)
         inject_credentials_into_env()
         if not is_configured(model):
+            # Keyless local-first: when no explicit model was requested and no
+            # cloud key is configured, prefer a reachable local endpoint (e.g.
+            # Ollama) so `praisonai run "..."` just works before any auth. An
+            # explicit --model is left to its own provider gate.
+            local = detect_local_endpoint() if not model else None
+            if local is not None:
+                output.print_info(
+                    f"No cloud key found; using local model {local.model}. "
+                    "Run `praisonai setup` to add a hosted provider."
+                )
+                # Adopt the detected local model + base URL for this run so the
+                # Agent reaches the local endpoint. An explicit env base_url,
+                # if any, is left untouched.
+                import os as _os_local
+                model = local.model
+                _os_local.environ.setdefault("OPENAI_BASE_URL", local.base_url)
             # In non-interactive mode, show clear error
-            if not sys.stdin.isatty() or output.is_json_mode:
+            elif not sys.stdin.isatty() or output.is_json_mode:
                 output.print_error(
                     "No API key configured. Run: praisonai setup\n"
-                    "or set environment variables like OPENAI_API_KEY"
+                    "or set environment variables like OPENAI_API_KEY\n"
+                    "(a running local endpoint such as Ollama would be used "
+                    "automatically)"
                 )
                 raise typer.Exit(1)
             
             # In interactive mode, offer to run setup
-            typer.echo(f"No API key configured{f' for model {model}' if model else ''}.")
-            run_setup = typer.confirm("Would you like to run the setup wizard now?")
-            
-            if run_setup:
-                from praisonai_code.cli.commands.setup import _run_setup
-                exit_code = _run_setup(
-                    non_interactive=False,
-                    provider=None,
-                    api_key=None,
-                    model=None
-                )
-                if exit_code != 0:
-                    output.print_error("Setup failed. Exiting.")
-                    raise typer.Exit(exit_code)
-                
-                output.print_success("Setup complete! Continuing with your run...")
-                # Re-check after setup
-                inject_credentials_into_env()
-                if not is_configured(model):
-                    output.print_error("Setup completed but credentials still not detected.")
-                    raise typer.Exit(1)
             else:
-                output.print_info(
-                    "To configure credentials:\n"
-                    "  - Run: praisonai setup\n"
-                    "  - Or set environment variables like OPENAI_API_KEY"
-                )
-                raise typer.Exit(0)
+                typer.echo(f"No API key configured{f' for model {model}' if model else ''}.")
+                run_setup = typer.confirm("Would you like to run the setup wizard now?")
+
+                if run_setup:
+                    from praisonai_code.cli.commands.setup import _run_setup
+                    exit_code = _run_setup(
+                        non_interactive=False,
+                        provider=None,
+                        api_key=None,
+                        model=None
+                    )
+                    if exit_code != 0:
+                        output.print_error("Setup failed. Exiting.")
+                        raise typer.Exit(exit_code)
+
+                    output.print_success("Setup complete! Continuing with your run...")
+                    # Re-check after setup
+                    inject_credentials_into_env()
+                    if not is_configured(model):
+                        output.print_error("Setup completed but credentials still not detected.")
+                        raise typer.Exit(1)
+                else:
+                    output.print_info(
+                        "To configure credentials:\n"
+                        "  - Run: praisonai setup\n"
+                        "  - Or set environment variables like OPENAI_API_KEY"
+                    )
+                    raise typer.Exit(0)
     
     # Resolve configuration if model not explicitly provided
     if model is None:
@@ -828,6 +986,24 @@ def run_main(
         output.print_error("Cannot use both --continue and --session together")
         raise typer.Exit(1)
 
+    # Worktree isolation runs the agent in a chdir'd worktree in-process; the
+    # warm runtime is a separate process whose cwd we can't redirect, so reject
+    # the combination up front rather than silently ignoring isolation.
+    if worktree and attach:
+        output.print_error("--worktree cannot be combined with --attach")
+        raise typer.Exit(1)
+    if keep and not worktree:
+        output.print_error("--keep requires --worktree")
+        raise typer.Exit(1)
+    # Scope isolation to the primary `run "<task>"` / `run agents.yaml` surfaces.
+    # Custom agent/command and profiling flows have their own execution paths;
+    # keep the feature focused rather than threading a worktree through each.
+    if worktree and (agent or command or profile or profile_deep):
+        output.print_error(
+            "--worktree is only supported for direct prompt and YAML file runs"
+        )
+        raise typer.Exit(1)
+
     # --attach tags a warm-runtime run so other terminals can observe it, but
     # only the direct-prompt path forwards to the warm runtime. Reject it up
     # front on profile/custom-agent/custom-command flows so users never
@@ -1017,58 +1193,72 @@ def run_main(
             )
         return
     
-    if is_file:
-        # Run from file
-        _run_from_file(
-            target,
-            model=model,
-            framework=framework,
-            interactive=interactive,
-            verbose=verbose,
-            stream=stream,
-            trace=trace,
-            memory=memory,
-            tools=tools,
-            max_tokens=max_tokens,
-            output_mode=output_mode,
-            continue_session=continue_session,
-            session=session,
-            fork=fork,
-            no_save=no_save,
-        )
-    else:
-        # Run as prompt
-        permissions_config = _parse_permissions(allow, deny, permissions, permission_default)
-        mcp_command, mcp_env, permissions_config, mcp_servers = _apply_config_defaults(
-            None, None, permissions_config
-        )
-        _run_prompt(
-            target,
-            model=model,
-            verbose=verbose,
-            stream=stream,
-            trace=trace,
-            memory=memory,
-            tools=tools,
-            toolset=toolset,
-            max_tokens=max_tokens,
-            output_mode=output_mode,
-            approval=approval,
-            approve_all_tools=approve_all_tools,
-            approval_timeout=approval_timeout,
-            no_rules=no_rules,
-            permissions_config=permissions_config,
-            mcp=mcp_command,
-            mcp_env=mcp_env,
-            mcp_servers=mcp_servers,
-            continue_session=continue_session,
-            session=session,
-            fork=fork,
-            no_save=no_save,
-            attach_session=attach,
-            thinking_budget=thinking_budget,
-            allow_local_tools=allow_local_tools,
-        )
+    # Resolve a YAML file target to an absolute path *before* isolation chdirs
+    # away. The config is loaded from the original checkout so an untracked or
+    # git-ignored ``./agents.yaml`` (absent from the fresh worktree) still loads;
+    # the agent then produces its output inside the isolated worktree.
+    run_target = target
+    if worktree and is_file:
+        import os as _os_ff
+        run_target = _os_ff.path.abspath(target)
+
+    # Provision a per-run git worktree/branch when --worktree is set and the cwd
+    # is a git repo; otherwise this is a transparent no-op. The agent runs with
+    # its cwd redirected into the isolated worktree for the duration of the run.
+    with _worktree_isolation(worktree, target, keep=keep):
+        if is_file:
+            # Run from file
+            _run_from_file(
+                run_target,
+                model=model,
+                framework=framework,
+                interactive=interactive,
+                verbose=verbose,
+                stream=stream,
+                trace=trace,
+                memory=memory,
+                tools=tools,
+                max_tokens=max_tokens,
+                output_mode=output_mode,
+                continue_session=continue_session,
+                session=session,
+                fork=fork,
+                no_save=no_save,
+            )
+        else:
+            # Run as prompt
+            permissions_config = _parse_permissions(allow, deny, permissions, permission_default)
+            mcp_command, mcp_env, permissions_config, mcp_servers = _apply_config_defaults(
+                None, None, permissions_config
+            )
+            _run_prompt(
+                target,
+                model=model,
+                verbose=verbose,
+                stream=stream,
+                trace=trace,
+                memory=memory,
+                tools=tools,
+                toolset=toolset,
+                max_tokens=max_tokens,
+                output_mode=output_mode,
+                approval=approval,
+                approve_all_tools=approve_all_tools,
+                approval_timeout=approval_timeout,
+                no_rules=no_rules,
+                permissions_config=permissions_config,
+                mcp=mcp_command,
+                mcp_env=mcp_env,
+                mcp_servers=mcp_servers,
+                continue_session=continue_session,
+                session=session,
+                fork=fork,
+                no_save=no_save,
+                attach_session=attach,
+                thinking_budget=thinking_budget,
+                allow_local_tools=allow_local_tools,
+                isolated=worktree,
+            )
 
 
 def _run_from_file(
@@ -1203,6 +1393,7 @@ def _run_prompt(
     attach_session: Optional[str] = None,
     thinking_budget: Optional[int] = None,
     allow_local_tools: bool = False,
+    isolated: bool = False,
 ):
     """Run a direct prompt."""
     output = get_output_controller()
@@ -1280,7 +1471,10 @@ def _run_prompt(
         # approval/memory), so it stays in-process: the warm runtime reuses a
         # cached agent and does not carry a per-call thinking budget, so attaching
         # would silently drop the requested setting.
-        runtime_eligible = no_save and thinking_budget is None and not any([
+        # Isolated (--worktree) runs must stay in-process: the warm runtime is a
+        # separate process whose cwd we can't redirect into the worktree, so
+        # attaching would run the task outside the isolated branch.
+        runtime_eligible = no_save and thinking_budget is None and not isolated and not any([
             mcp, mcp_servers, tools, toolset, approval, approve_all_tools,
             memory, permissions_config, continue_session, session, fork,
         ])

{praisonai_code-0.0.53 → praisonai_code-0.0.55}/praisonai_code/cli/commands/session.py

@@ -19,14 +19,23 @@ app = typer.Typer(help="Session management")
 
 
 def _create_backend(backend_type: str, storage_path: Optional[str]):
-    """Create storage backend from CLI options."""
+    """Create storage backend from CLI options.
+
+    Defaults anchor under the *canonical* data home (``get_sessions_dir()`` →
+    ``~/.praisonai/sessions``) rather than the legacy ``~/.praison`` root, so a
+    backend-selected store lives under the same home as the project/global
+    stores instead of silently splitting sessions across two home roots
+    (Issue #3201).
+    """
     try:
+        from praisonaiagents.paths import get_data_dir, get_sessions_dir
+
         if backend_type == "file":
             from praisonaiagents.storage import FileBackend
-            return FileBackend(storage_dir=storage_path or "~/.praison/sessions")
+            return FileBackend(storage_dir=storage_path or str(get_sessions_dir()))
         elif backend_type == "sqlite":
             from praisonaiagents.storage import SQLiteBackend
-            db_path = storage_path or "~/.praison/sessions.db"
+            db_path = storage_path or str(get_data_dir() / "sessions.db")
             return SQLiteBackend(db_path=db_path)
         elif backend_type.startswith("redis://"):
             from praisonaiagents.storage import RedisBackend