praisonai-code 0.0.44__tar.gz → 0.0.45__tar.gz

{praisonai_code-0.0.44 → praisonai_code-0.0.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: praisonai-code
-Version: 0.0.44
+Version: 0.0.45
 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.44 → praisonai_code-0.0.45}/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.44"
+__version__ = "0.0.45"
 
 __all__ = ["__version__"]

{praisonai_code-0.0.44 → praisonai_code-0.0.45}/praisonai_code/cli/app.py

@@ -149,6 +149,8 @@ _LAZY_COMMANDS: Dict[str, Tuple[str, str, str]] = {
     "session": (".commands.session", "app", "Session management"),
     "completion": (".commands.completion", "app", "Shell completion scripts"),
     "version": (".commands.version", "app", "Version information"),
+    "upgrade": (".commands.upgrade", "app", "Update the managed PraisonAI CLI install"),
+    "uninstall": (".commands.uninstall", "app", "Remove the managed PraisonAI CLI install"),
     "debug": (".commands.debug", "app", "Debug and test interactive flows"),
     "lsp": (".commands.lsp", "app", "LSP service lifecycle"),
     "diag": (".commands.diag", "app", "Diagnostics export"),
@@ -787,7 +789,26 @@ def main_callback(
         trace_id=context.trace_id,
     )
     set_output_controller(state.output_controller)
-    
+
+    # Non-blocking "update available" hint from the cached background check.
+    # Text-mode only, opt-out via PRAISONAI_NO_UPDATE_CHECK; never blocks or
+    # raises (only reads a time-boxed cache, never performs network I/O here).
+    if mode == OutputMode.TEXT and not state.quiet:
+        try:
+            from .features.self_manage import (
+                maybe_schedule_update_check,
+                read_cached_hint,
+            )
+
+            hint = read_cached_hint()
+            if hint:
+                typer.echo(hint, err=True)
+            # Warm the cache in a detached child for the next invocation. Never
+            # performs network I/O here and never blocks or raises.
+            maybe_schedule_update_check()
+        except Exception:
+            pass
+
     # If no command provided, start interactive mode
     if ctx.invoked_subcommand is None:
         # Check for credentials before starting TUI

{praisonai_code-0.0.44 → praisonai_code-0.0.45}/praisonai_code/cli/commands/init.py

@@ -8,9 +8,12 @@ Project scaffolding command for the `.praisonai/` convention.
       config.yaml            # sensible defaults (model, output mode)
       agents/assistant.md    # working starter agent (frontmatter + body)
       commands/review.md     # working starter command using $ARGUMENTS / @file
+      tools/example.py       # commented @tool example, auto-discovered on run
 
 The scaffolded files are immediately discoverable and runnable via
 `praisonai run --agent assistant ...` and `praisonai run --command review ...`.
+Tools dropped in `.praisonai/tools/*.py` are auto-loaded on every `run`
+(gated by PRAISONAI_ALLOW_LOCAL_TOOLS).
 """
 
 from pathlib import Path
@@ -62,6 +65,29 @@ If a file path is provided, here are its contents:
 @$ARGUMENTS
 """
 
+STARTER_TOOL_PY = '''\
+"""Project-local tools for this .praisonai/ project.
+
+Every public callable in this directory is auto-discovered and made available
+to the agent on `praisonai run` — no --tools flag required. Decorate a function
+with @tool for a rich schema, or just define a plain function.
+
+Loading executes this file, so it is gated by the PRAISONAI_ALLOW_LOCAL_TOOLS
+opt-in (set PRAISONAI_ALLOW_LOCAL_TOOLS=true to enable local tool loading).
+Uncomment the example below to try it:
+
+    praisonai run "use the greet tool to greet Ada"
+"""
+
+# from praisonaiagents import tool
+#
+#
+# @tool
+# def greet(name: str) -> str:
+#     """Return a friendly greeting for the given name."""
+#     return f"Hello, {name}!"
+'''
+
 
 def _any_provider_credential() -> bool:
     """Return True if any supported provider credential is present in env."""
@@ -136,6 +162,7 @@ def init(
         (base / "config.yaml", STARTER_CONFIG.format(model=scaffold_model)),
         (base / "agents" / "assistant.md", STARTER_AGENT_MD.format(model=scaffold_model)),
         (base / "commands" / "review.md", STARTER_COMMAND_MD),
+        (base / "tools" / "example.py", STARTER_TOOL_PY),
     ]
 
     written = []

{praisonai_code-0.0.44 → praisonai_code-0.0.45}/praisonai_code/cli/commands/run.py

@@ -333,6 +333,49 @@ def _resolve_tools_arg(value: Optional[str], verbose: bool = False) -> list:
     return resolved
 
 
+def _auto_discover_project_tools(existing: list, verbose: bool = False) -> list:
+    """Return auto-discovered ``.praisonai/tools/*.py`` callables to append.
+
+    Mirrors the agents/commands convention: project-local tools are loaded from
+    ``.praisonai/tools/`` (user-global + project walk-up) with no ``--tools``
+    flag. Loading executes user code and is gated by the shared
+    ``PRAISONAI_ALLOW_LOCAL_TOOLS`` opt-in, so this returns an empty list when
+    the opt-in is not set.
+
+    Discovery is additive: explicit ``--tools`` items already in ``existing``
+    take precedence and are not re-added (dedup by callable identity).
+    """
+    try:
+        from praisonai_code.cli.features.custom_definitions import (
+            discover_project_tools,
+        )
+    except Exception:
+        return []
+
+    try:
+        discovered = discover_project_tools()
+    except Exception:
+        return []
+
+    if not discovered:
+        return []
+
+    seen = {id(t) for t in existing}
+    merged: list = []
+    for tool in discovered:
+        if id(tool) in seen:
+            continue
+        seen.add(id(tool))
+        merged.append(tool)
+
+    if merged and verbose:
+        from ..output import get_output_controller
+        get_output_controller().print_info(
+            f"Loaded {len(merged)} project tool(s) from .praisonai/tools/"
+        )
+    return merged
+
+
 def _permissions_from_config(config) -> Optional[dict]:
     """Convert a resolved ``permissions`` config section to a pattern->action dict.
 
@@ -613,6 +656,7 @@ def run_main(
     no_save: bool = typer.Option(False, "--no-save", help="Don't auto-save session after execution"),
     # Custom definitions
     agent: Optional[str] = typer.Option(None, "--agent", "-a", help="Use a named custom agent"),
+    subagents: Optional[str] = typer.Option(None, "--subagents", help="Comma-separated named agents (.praisonai/agents/*.md) the running agent may delegate to. Omit to expose agents marked 'mode: subagent'."),
     command: Optional[str] = typer.Option(None, "--command", help="Execute a named custom command"),
     # Reasoning effort
     thinking: Optional[str] = typer.Option(None, "--thinking", help="Reasoning effort (off, minimal, low, medium, high)"),
@@ -779,6 +823,7 @@ def run_main(
             fork=fork,
             no_save=no_save,
             thinking_budget=thinking_budget,
+            subagents=subagents,
         )
         return
     
@@ -1236,6 +1281,12 @@ def _run_prompt(
                 toolset_names = [t.strip() for t in toolset.split(",") if t.strip()]
                 if toolset_names:
                     selected_tools.extend(_resolve_toolsets(toolset_names))
+            # Auto-discover project-local .praisonai/tools/*.py (additive;
+            # explicit --tools take precedence). Gated by the shared
+            # PRAISONAI_ALLOW_LOCAL_TOOLS opt-in in the safe loader.
+            selected_tools.extend(
+                _auto_discover_project_tools(selected_tools, verbose=verbose)
+            )
             if selected_tools:
                 agent_config["tools"] = list(agent_config.get("tools", [])) + selected_tools
 
@@ -1482,6 +1533,46 @@ def _run_from_file_profiled(
     profiler.print_report()
 
 
+def _wire_subagent_delegation(
+    agent_config: Dict[str, Any],
+    subagents: Optional[str],
+) -> None:
+    """Attach a `spawn_subagent` tool that can delegate to named agents.
+
+    Resolves delegatable ``.praisonai/agents/*.md`` definitions into a
+    core ``create_subagent_tool`` resolver and appends the tool to
+    ``agent_config['tools']``. No-op when there are no delegatable agents so
+    the default run is unchanged.
+
+    ``subagents`` is the raw ``--subagents`` string (comma-separated names);
+    when None, agents marked ``mode: subagent`` are exposed instead.
+    """
+    allow_list = None
+    if subagents:
+        allow_list = [name.strip() for name in subagents.split(",") if name.strip()]
+
+    try:
+        from praisonai_code.cli.features.custom_definitions import (
+            build_subagent_resolver,
+        )
+
+        resolver, descriptions = build_subagent_resolver(allow_list)
+    except Exception:
+        return
+
+    if resolver is None:
+        return
+
+    from praisonaiagents.tools.subagent_tool import create_subagent_tool
+
+    tool = create_subagent_tool(
+        agent_resolver=resolver,
+        allowed_agents=list(descriptions.keys()),
+        resolvable_agents=descriptions,
+    )
+    agent_config["tools"] = list(agent_config.get("tools") or []) + [tool]
+
+
 def _run_custom_agent(
     agent_config: Dict[str, Any],
     prompt: str,
@@ -1503,6 +1594,7 @@ def _run_custom_agent(
     fork: bool = False,
     no_save: bool = False,
     thinking_budget: Optional[int] = None,
+    subagents: Optional[str] = None,
 ):
     """Run a custom agent definition."""
     output = get_output_controller()
@@ -1513,6 +1605,13 @@ def _run_custom_agent(
         # Override model if specified
         if model:
             agent_config["llm"] = model
+
+        # Offer discovered named agents as delegation targets. The primary
+        # agent can then call spawn_subagent(agent_name="researcher", ...) to
+        # hand a sub-task to a user-defined .praisonai/agents/*.md agent, which
+        # runs under its own model/tools/permissions. An explicit --subagents
+        # allow-list wins; otherwise agents marked `mode: subagent` are used.
+        _wire_subagent_delegation(agent_config, subagents)
         
         # Add verbose flag
         if verbose:

{praisonai_code-0.0.44 → praisonai_code-0.0.45}/praisonai_code/cli/commands/session.py

@@ -76,7 +76,11 @@ def session_list(
             get_project_session_store,
             list_project_sessions,
         )
-        from ..utils.project import get_project_id, get_project_name
+        from ..utils.project import (
+            get_project_id,
+            get_project_identity_source,
+            get_project_name,
+        )
 
         # List sessions for specific or current project. For the current
         # project, merge the project-scoped and global default stores so the
@@ -131,7 +135,10 @@ def session_list(
         if not project_id:
             current_project = get_project_name()
             current_id = get_project_id()
-            output.print_info(f"Project: {current_project} (ID: {current_id})")
+            identity_source = get_project_identity_source()
+            output.print_info(
+                f"Project: {current_project} (ID: {current_id}, identity: {identity_source})"
+            )
         
     else:
         # Use global session manager

praisonai_code-0.0.45/praisonai_code/cli/commands/uninstall.py

@@ -0,0 +1,73 @@
+"""``praisonai uninstall`` — cleanly remove the managed CLI install.
+
+Removes the managed PraisonAI environment and global shim provisioned by the
+one-line installer (``uv tool`` / ``pipx``), or uninstalls the ``pip`` package
+for library installs. CLI self-management only; ``praisonaiagents`` is not
+touched by this command.
+"""
+
+import subprocess
+
+import typer
+
+from ..output.console import get_output_controller
+from ..features.self_manage import detect_install, get_installed_version
+
+app = typer.Typer(help="Remove the managed PraisonAI CLI install")
+
+
+@app.callback(invoke_without_command=True)
+def uninstall(
+    ctx: typer.Context,
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        "-y",
+        help="Skip the confirmation prompt (non-interactive/CI).",
+    ),
+):
+    """Remove the managed PraisonAI environment and global ``praisonai`` shim."""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    output = get_output_controller()
+    info = detect_install()
+    current = get_installed_version()
+
+    if info.uninstall_cmd is None:
+        output.print_error(
+            f"Automatic uninstall is not supported for a '{info.manager}' install.\n"
+            "Remove manually with: pip uninstall praisonai"
+        )
+        raise typer.Exit(1)
+
+    if not yes and not output.is_json_mode:
+        confirmed = typer.confirm(
+            f"Remove PraisonAI {current} (installed via {info.manager})?"
+        )
+        if not confirmed:
+            output.print("Uninstall cancelled.")
+            raise typer.Exit(0)
+
+    if not output.is_json_mode:
+        output.print(
+            f"Uninstalling PraisonAI via {info.manager}: "
+            f"{' '.join(info.uninstall_cmd)}"
+        )
+
+    try:
+        result = subprocess.run(info.uninstall_cmd)
+    except Exception as e:  # pragma: no cover - defensive
+        output.print_error(f"Uninstall failed: {e}")
+        raise typer.Exit(1)
+
+    if result.returncode != 0:
+        output.print_error(
+            f"Uninstall command exited with code {result.returncode}."
+        )
+        raise typer.Exit(result.returncode)
+
+    if output.is_json_mode:
+        output.print_json({"manager": info.manager, "removed": current})
+    else:
+        output.print_success(f"PraisonAI {current} removed.")

praisonai_code-0.0.45/praisonai_code/cli/commands/upgrade.py

@@ -0,0 +1,105 @@
+"""``praisonai upgrade`` — self-update the managed CLI install.
+
+Updates the PraisonAI CLI in place using whichever tool manager provisioned it
+(``uv tool`` / ``pipx`` for the one-line installer, or ``pip`` for library
+installs). ``--check`` reports whether a newer release exists without mutating
+anything. This is CLI self-management only; ``praisonaiagents`` is untouched.
+"""
+
+import subprocess
+
+import typer
+
+from ..output.console import get_output_controller
+from ..features.self_manage import (
+    detect_install,
+    get_installed_version,
+    get_latest_version,
+    is_newer,
+    refresh_update_cache,
+)
+
+app = typer.Typer(help="Update the managed PraisonAI CLI install")
+
+
+@app.callback(invoke_without_command=True)
+def upgrade(
+    ctx: typer.Context,
+    check: bool = typer.Option(
+        False,
+        "--check",
+        help="Report whether a newer version exists without upgrading.",
+    ),
+):
+    """Update PraisonAI in place, or check for a newer release with ``--check``."""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    output = get_output_controller()
+    current = get_installed_version()
+
+    if check:
+        latest = get_latest_version()
+        # Warm the background-hint cache so long-lived installs surface the
+        # notice on next start without their own network round-trip.
+        refresh_update_cache()
+        if latest is None:
+            if output.is_json_mode:
+                output.print_json(
+                    {"current": current, "latest": None, "update_available": None,
+                     "error": "Could not reach PyPI"}
+                )
+            else:
+                output.print_error("Could not check for updates (network error).")
+                output.print(f"Current version: {current}")
+            raise typer.Exit(1)
+
+        available = is_newer(latest, current)
+        if output.is_json_mode:
+            output.print_json(
+                {"current": current, "latest": latest, "update_available": available}
+            )
+        elif available:
+            output.print_warning(
+                f"Update available: {current} -> {latest}\nRun: praisonai upgrade"
+            )
+        else:
+            output.print_success(f"You are on the latest version ({current}).")
+        return
+
+    info = detect_install()
+    if info.upgrade_cmd is None:
+        output.print_error(
+            f"Automatic upgrade is not supported for a '{info.manager}' install.\n"
+            "Upgrade manually with: pip install --upgrade praisonai"
+        )
+        raise typer.Exit(1)
+
+    if not output.is_json_mode:
+        output.print(
+            f"Upgrading PraisonAI via {info.manager}: {' '.join(info.upgrade_cmd)}"
+        )
+
+    try:
+        result = subprocess.run(info.upgrade_cmd)
+    except Exception as e:  # pragma: no cover - defensive
+        output.print_error(f"Upgrade failed: {e}")
+        raise typer.Exit(1)
+
+    if result.returncode != 0:
+        output.print_error(
+            f"Upgrade command exited with code {result.returncode}."
+        )
+        raise typer.Exit(result.returncode)
+
+    new_version = get_installed_version()
+    if output.is_json_mode:
+        output.print_json(
+            {"manager": info.manager, "previous": current, "current": new_version}
+        )
+    else:
+        output.print_success(
+            f"PraisonAI upgraded ({current} -> {new_version})."
+            if new_version != current
+            else f"PraisonAI is up to date ({new_version})."
+        )

{praisonai_code-0.0.44 → praisonai_code-0.0.45}/praisonai_code/cli/configuration/config.schema.json

@@ -52,6 +52,41 @@
         "quiet": { "type": "boolean" }
       }
     },
-    "telemetry": { "type": "boolean" }
+    "telemetry": { "type": "boolean" },
+    "model_allowlist": {
+      "type": "array",
+      "description": "Allowed model identifiers. Enforceable when supplied by a managed source.",
+      "items": { "type": "string" }
+    },
+    "permissions": {
+      "type": "object",
+      "description": "Permission policy (rules for auto-running tools). Enforceable when supplied by a managed source.",
+      "additionalProperties": true
+    },
+    "managed": {
+      "type": "object",
+      "description": "Optional centrally-managed / remote config + policy source. Fully opt-in; when absent, resolution is local-only. Also configurable via PRAISONAI_MANAGED_CONFIG_URL / PRAISONAI_MANAGED_CONFIG_DIR.",
+      "additionalProperties": false,
+      "properties": {
+        "url": {
+          "type": "string",
+          "description": "Remote URL to fetch managed config from (short timeout, cached, fail-soft to last good copy or local-only when offline)."
+        },
+        "dir": {
+          "type": "string",
+          "description": "Managed/enterprise directory (populated by MDM/config-management) containing config.yaml|yml|json."
+        },
+        "timeout": {
+          "type": "number",
+          "description": "Fetch timeout in seconds (default 3). Never blocks a run on the network.",
+          "default": 3
+        },
+        "enforce": {
+          "type": "boolean",
+          "description": "When true (default), policy keys (permissions, model_allowlist) are enforced above local config; other keys remain overridable defaults below local config. When false, the whole managed source is advisory.",
+          "default": true
+        }
+      }
+    }
   }
 }