audiagentic 0.2.1__py3-none-any.whl

audiagentic/__init__.py

@@ -0,0 +1,11 @@
+"""AUDiaGentic: Agentic workflow orchestration and execution platform.
+
+Top-level package for the AUDiaGentic system. Domain layout:
+
+  foundation/   — shared contracts, event bus, and the component framework (base layer)
+  components/   — core and optional components (project, session, providers, ledger, ...)
+  runtime/      — lifecycle management, harness, and durable state persistence
+  config/       — component descriptors and provisioning configuration
+"""
+
+__version__ = "0.2.1"

audiagentic/commands/__init__.py

@@ -0,0 +1,4 @@
+from audiagentic.commands.component import _cmd_component
+from audiagentic.commands.launch import _cmd_launch
+
+__all__ = ["_cmd_component", "_cmd_launch"]

audiagentic/commands/bootstrap.py

@@ -0,0 +1,199 @@
+"""Bootstrap and repair commands for AUDiaGentic-owned state."""
+from __future__ import annotations
+
+import argparse
+import logging
+from pathlib import Path
+
+from audiagentic.foundation.cli_io import print_error, print_json, print_message
+from audiagentic.foundation.paths.home import global_harness_runtime
+from audiagentic.runtime.harness import (
+    cleanup_runtime,
+    install_to,
+    refresh_materialized_agent_config,
+    request_runtime_reload,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _install_core_components(project_root: Path) -> list[str]:
+    """Materialize every mandatory project component; return failed ids.
+
+    These components own project scaffold (configuration, prompts and event-bus
+    state).  They are deliberately independent of MCP collection.
+    """
+    from audiagentic.foundation.components.loader import register_all_components
+    from audiagentic.foundation.components.registry import all_descriptors
+    from audiagentic.foundation.lifecycle.components import install_component
+
+    register_all_components()
+    failed: list[str] = []
+    for component_id, descriptor in all_descriptors().items():
+        if not descriptor.core:
+            continue
+        try:
+            result = install_component(component_id, project_root)
+            if not result.get("ok"):
+                failed.append(component_id)
+        except Exception:
+            logger.error("Failed to bootstrap core component %s", component_id, exc_info=True)
+            failed.append(component_id)
+    return failed
+
+
+def _cmd_bootstrap(target: Path, project_root: Path) -> int:
+    print_message(f"Bootstrapping AUDiaGentic into {target}")
+    rc = install_to(target, project_root=project_root)
+    if rc:
+        return rc
+
+    failed = _install_core_components(project_root)
+    if failed:
+        print_error(f"Failed to bootstrap core components: {', '.join(sorted(failed))}")
+        return 1
+
+    print_message("\nBootstrap complete. Run 'audiagentic' from any project directory.")
+    if target != global_harness_runtime():
+        print_message(f"Set AUDIAGENTIC_HOME={target.parent} to use this location.")
+    return 0
+
+
+def cmd_bootstrap(args: argparse.Namespace, project_root: Path) -> int:
+    target = Path(args.target).resolve() if args.target else global_harness_runtime()
+    return _cmd_bootstrap(target, project_root)
+
+
+def cmd_cleanup(args: argparse.Namespace, project_root: Path) -> int:
+    del project_root
+    target = Path(args.target).resolve() if args.target else global_harness_runtime()
+    print_message(f"Removing AUDiaGentic-generated runtime files from {target}")
+    return cleanup_runtime(target)
+
+
+def _omit_empty_values(value: object) -> object:
+    """Return CLI-safe data without null or empty optional fields."""
+    if isinstance(value, dict):
+        return {
+            key: cleaned
+            for key, item in value.items()
+            if (cleaned := _omit_empty_values(item)) is not None
+            and cleaned != ""
+            and cleaned != []
+            and cleaned != {}
+        }
+    if isinstance(value, list):
+        return [_omit_empty_values(item) for item in value]
+    return value
+
+
+def _surface_results_to_json(results: object) -> list[dict[str, object]]:
+    """Serialize generated-surface API results for CLI output."""
+    values = results if isinstance(results, list) else [results]
+    serialized: list[dict[str, object]] = []
+    for value in values:
+        converter = getattr(value, "to_mapping", None)
+        if callable(converter):
+            value = converter()
+        mapping = dict(value) if isinstance(value, dict) else {"result": str(value)}
+        cleaned = _omit_empty_values(mapping)
+        serialized.append(cleaned if isinstance(cleaned, dict) else {})
+    return serialized
+
+
+def _config_summary(
+    *,
+    mode: str,
+    project_root: Path,
+    surface_results: list[dict[str, object]],
+    provider_errors: list[dict[str, object]],
+) -> dict[str, object]:
+    written = sorted({
+        path
+        for result in surface_results
+        for path in result.get("written_paths", [])
+        if isinstance(path, str)
+    })
+    removed = sorted({
+        path
+        for result in surface_results
+        for path in result.get("removed_paths", [])
+        if isinstance(path, str)
+    })
+    surface_errors = [
+        result
+        for result in surface_results
+        if not result.get("ok", False) and result.get("supported", True)
+    ]
+    errors = [*surface_errors, *provider_errors]
+    changed = bool(written or removed or any(result.get("changed") for result in surface_results))
+    summary: dict[str, object] = {
+        "ok": not errors,
+        "mode": mode,
+        "project_root": str(project_root),
+        "changed": changed,
+        "message": (
+            "Configuration refreshed."
+            if changed and mode == "apply"
+            else "Configuration is already synchronized."
+            if mode == "apply"
+            else "Configuration is already clean."
+            if not changed
+            else "Configuration cleaned."
+        ),
+    }
+    if written:
+        summary["written_paths"] = written
+    if removed:
+        summary["removed_paths"] = removed
+    if errors:
+        summary["errors"] = errors
+    return summary
+
+
+def _config_operation(project_root: Path, *, mode: str, clean_runtime: bool) -> int:
+    """Run an ownership-aware config operation and report partial failures."""
+    target = global_harness_runtime()
+    from audiagentic.components.providers import providers_api
+    from audiagentic.components.providers.services.mcp.mcp_sync import (
+        sync_all_provider_mcp_servers,
+    )
+
+    output: dict[str, object] = {"ok": True, "mode": mode, "project_root": str(project_root)}
+    try:
+        surface_results = _surface_results_to_json(
+            providers_api.operate_provider_surfaces(project_root, mode=mode)
+        )
+        provider_errors = sync_all_provider_mcp_servers(project_root)
+        if clean_runtime:
+            cleanup_runtime(target)
+        else:
+            refresh_materialized_agent_config(target, project_root=project_root)
+        request_runtime_reload(project_root, reason=f"config-{mode}")
+    except Exception as exc:  # noqa: BLE001
+        output["ok"] = False
+        output["errors"] = [str(exc)]
+        print_json(_omit_empty_values(output))
+        return 1
+
+    output = _config_summary(
+        mode=mode,
+        project_root=project_root,
+        surface_results=surface_results,
+        provider_errors=provider_errors,
+    )
+    print_json(_omit_empty_values(output))
+    return 0 if output["ok"] else 1
+
+
+def cmd_config_sync(args: argparse.Namespace, project_root: Path) -> int:
+    """Refresh all generated surfaces and configured provider configs."""
+    if args.config_cmd == "clean":
+        return cmd_config_clean(args, project_root)
+    return _config_operation(project_root, mode="apply", clean_runtime=False)
+
+
+def cmd_config_clean(args: argparse.Namespace, project_root: Path) -> int:
+    """Prune owned surfaces, synchronize stale provider entries, and clean runtime."""
+    del args
+    return _config_operation(project_root, mode="prune", clean_runtime=True)

audiagentic/commands/component.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import shutil
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from audiagentic.foundation.cli_io import print_json
+
+logger = logging.getLogger(__name__)
+
+
+def _cmd_component_list(_args: Any, project_root: Path) -> int:
+    from audiagentic.foundation.components.registry import (
+        all_descriptors,
+        get_descriptor,
+        is_enabled,
+        is_installed,
+    )
+
+    rows = []
+    for cid, desc in sorted(all_descriptors().items()):
+        installed = is_installed(cid, project_root)
+        enabled = is_enabled(cid, project_root) if installed else None
+        state = "disabled" if (installed and not enabled) else ("installed" if installed else "not-installed")
+        row: dict[str, Any] = {
+            "component_id": cid,
+            "display_name": desc.display_name,
+            "installed": installed,
+            "enabled": enabled,
+            "state": state,
+            "scope": desc.scope,
+        }
+        if desc.scope == "project" and (getattr(desc, "cli_probe", None)):
+            prov_descriptor = get_descriptor("providers")
+            if prov_descriptor:
+                from audiagentic.components.providers.descriptors.registry import (
+                    get_descriptor as _get_provider_descriptor,
+                )
+                prov_desc = _get_provider_descriptor(cid)
+                if prov_desc and prov_desc.cli_probe:
+                    row["cli_available"] = shutil.which(prov_desc.cli_probe[0]) is not None
+        rows.append(row)
+    print_json(rows)
+    return 0
+
+
+def _cmd_component_status(args: Any, project_root: Path) -> int:
+    from audiagentic.foundation.components.hooks import get_component_status
+    from audiagentic.foundation.components.registry import (
+        get_descriptor,
+        is_enabled,
+        is_installed,
+    )
+
+    component_id: str = args.component_id
+
+    descriptor = get_descriptor(component_id)
+    if descriptor is None:
+        print_json({"ok": False, "error": f"unknown component: {component_id}"})
+        return 1
+
+    installed = is_installed(component_id, project_root)
+    result: dict[str, Any] = {
+        "component_id": component_id,
+        "installed": installed,
+        "enabled": is_enabled(component_id, project_root) if installed else None,
+    }
+    # Surface the component's own status (configuration completeness, next steps)
+    # when it declares a status hook. Generic — the CLI never branches on id.
+    detail = get_component_status(descriptor, project_root)
+    if detail is not None:
+        result["detail"] = detail
+    print_json(result)
+    return 0
+
+
+_SUBCOMMAND_REGISTRY: dict[str, Callable] = {
+    "list": _cmd_component_list,
+    "status": _cmd_component_status,
+}
+
+
+def _cmd_component(args: argparse.Namespace, project_root: Path) -> int:
+    from audiagentic.components.project import project_api
+    from audiagentic.foundation.components.registry import get_descriptor
+
+    sub = args.component_cmd
+
+    handler = _SUBCOMMAND_REGISTRY.get(sub)
+    if handler:
+        return handler(args, project_root)
+
+    component_id: str = args.component_id
+
+    if get_descriptor(component_id) is None:
+        print_json({"ok": False, "error": f"unknown component: {component_id}"})
+        return 1
+
+    DISPATCH = {
+        "install": ("install_component", {}),
+        "uninstall": ("uninstall_component", {"remove_configs": getattr(args, "remove_configs", False)}),
+        "enable": ("enable_component", {}),
+        "disable": ("disable_component", {}),
+    }
+
+    if sub in DISPATCH:
+        api_method, extra_kwargs = DISPATCH[sub]
+        result = getattr(project_api, f"{api_method}")(project_root, component_id, **extra_kwargs)
+        print_json(result)
+        return 0 if result.get("ok", True) else 1
+
+    return 1

audiagentic/commands/gateway.py

@@ -0,0 +1,204 @@
+"""Explicit standalone gateway service command and lifecycle CLI (SH10 Slice A).
+
+This module owns ``gateway serve`` (existing) and the SH10 operator lifecycle
+sub-commands: ``status``, ``drain``, ``resume``, ``stop [--force]``, and
+``recover [--confirm] [--reason]``.  Lifecycle handlers dispatch exactly once
+through the standalone gateway client (HTTP) or the record-only recovery
+helper; they contain no lifecycle/store/signal logic.
+"""
+from __future__ import annotations
+
+import argparse
+import contextlib
+import json
+import os
+import signal
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from audiagentic.components.agents.gateway.remote_client import (
+        StandaloneGatewayClient,
+    )
+    from audiagentic.components.agents.gateway.service.host import GatewayServiceHost
+
+
+def _standalone_client_from_env() -> StandaloneGatewayClient:
+    """Build a StandaloneGatewayClient from environment (same env as get_gateway_client)."""
+    from audiagentic.components.agents.gateway.remote_client import (
+        StandaloneGatewayClient,
+        load_auth_token,
+    )
+
+    endpoint = os.environ.get("AUDIAGENTIC_GATEWAY_ENDPOINT")
+    token_file = os.environ.get("AUDIAGENTIC_GATEWAY_TOKEN_FILE")
+    if not endpoint or not token_file:
+        print(
+            "error: standalone gateway client requires "
+            "AUDIAGENTIC_GATEWAY_ENDPOINT and AUDIAGENTIC_GATEWAY_TOKEN_FILE",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    return StandaloneGatewayClient(endpoint, load_auth_token(Path(token_file)))
+
+
+# - serve (existing) -
+
+
+class _ShutdownState:
+    """Mutable flag set by the signal handler, read after serve_forever() returns.
+
+    A plain attribute container rather than a bool local: the handler is a
+    closure invoked asynchronously by the interpreter's signal machinery, so
+    it needs a mutable object to record onto, not a rebound name.
+    """
+
+    def __init__(self) -> None:
+        self.forced_fallback = False
+
+
+def _shutdown_signals() -> list[int]:
+    """SIGINT/SIGTERM always; SIGBREAK too on Windows (CTRL_CLOSE/taskkill
+    maps there, not to SIGTERM). A hard TerminateProcess/-9 runs no handler —
+    that is covered by the next start's owner-claim liveness check and SH07
+    recovery, not by anything here."""
+    sigs = [signal.SIGINT, signal.SIGTERM]
+    win_break = getattr(signal, "SIGBREAK", None)
+    if win_break is not None:
+        sigs.append(win_break)
+    return sigs
+
+
+def _install_shutdown_signals(host: GatewayServiceHost) -> _ShutdownState:
+    """Drain-first signal handling for the serving process (SH10 Slice B).
+
+    Refuse-force semantics make no sense on an OS kill signal -- there is no
+    interactive way to "drain first" in response to SIGTERM, so this goes
+    straight to a forced stop. If that itself fails for some reason, fall
+    back to a raw server shutdown so the process still exits rather than
+    hanging on a broken lifecycle path.
+    """
+    state = _ShutdownState()
+
+    def _handler(signum: int, _frame: object) -> None:
+        del signum
+        try:
+            if host.lifecycle is not None:
+                host.lifecycle.request_stop(force=True)
+            else:
+                host.shutdown()
+        except Exception:
+            state.forced_fallback = True
+            with contextlib.suppress(Exception):
+                host.shutdown()
+
+    for sig in _shutdown_signals():
+        with contextlib.suppress(OSError, ValueError):
+            signal.signal(sig, _handler)
+    return state
+
+
+def cmd_gateway(args: argparse.Namespace, project_root: Path) -> int:
+    del project_root
+    if args.gateway_cmd != "serve":
+        raise ValueError(f"unsupported gateway command: {args.gateway_cmd}")
+    from audiagentic.components.agents.gateway.service.host import GatewayServiceHost
+
+    host = GatewayServiceHost.create(
+        host=args.host,
+        port=args.port,
+        token_path=Path(args.token_file).resolve() if args.token_file else None,
+    )
+    print(f"gateway endpoint: {host.endpoint}")
+    print(f"gateway token file: {host.token_path}")
+    shutdown_state = _install_shutdown_signals(host)
+    try:
+        host.serve_forever()
+    except KeyboardInterrupt:
+        return 0
+    finally:
+        host.close()
+    return 1 if shutdown_state.forced_fallback else 0
+
+
+# - SH10 lifecycle operators -
+
+def _json_out(data: object) -> None:
+    """Print redacted JSON to stdout."""
+    print(json.dumps(data, indent=2, default=str))
+
+
+def cmd_gateway_status(args: argparse.Namespace, project_root: Path) -> int:
+    """gateway status - query service state via HTTP client."""
+    client = _standalone_client_from_env()
+    try:
+        result = client.service_status(project_root)
+    finally:
+        client.close()
+    _json_out(result)
+    return 0
+
+
+def cmd_gateway_drain(args: argparse.Namespace, project_root: Path) -> int:
+    """gateway drain - begin graceful drain via HTTP client."""
+    del args
+    client = _standalone_client_from_env()
+    try:
+        result = client.service_drain(project_root)
+    finally:
+        client.close()
+    _json_out(result)
+    return 0
+
+
+def cmd_gateway_resume(args: argparse.Namespace, project_root: Path) -> int:
+    """gateway resume - cancel draining via HTTP client."""
+    del args
+    client = _standalone_client_from_env()
+    try:
+        result = client.service_resume(project_root)
+    finally:
+        client.close()
+    _json_out(result)
+    return 0
+
+
+def cmd_gateway_stop(args: argparse.Namespace, project_root: Path) -> int:
+    """gateway stop [--force] - request operator stop via HTTP client."""
+    client = _standalone_client_from_env()
+    try:
+        result = client.service_stop(project_root, force=args.force)
+    finally:
+        client.close()
+    _json_out(result)
+    return 0
+
+
+def cmd_gateway_recover(args: argparse.Namespace, project_root: Path) -> int:
+    """gateway recover - record-only dead-owner recovery (never HTTP).
+
+    Deliberately bypasses the HTTP client because recovery targets a
+    dead/unprovable service; it goes straight to the store via the
+    lifecycle module.
+    """
+    from audiagentic.components.agents.gateway.service.lifecycle import (
+        recover_unprovable_owner,
+    )
+
+    # Automatic gateway ownership is machine-scoped.  Recovery must address
+    # the same default machine store as bootstrap, not synthesize a second
+    # project-local managed-service record beneath ``project_root``.
+    result = recover_unprovable_owner(confirm=args.confirm, reason=args.reason)
+    _json_out(result)
+    return 0
+
+
+__all__ = [
+    "cmd_gateway",
+    "cmd_gateway_drain",
+    "cmd_gateway_recover",
+    "cmd_gateway_resume",
+    "cmd_gateway_status",
+    "cmd_gateway_stop",
+]

audiagentic/commands/internal.py

@@ -0,0 +1,36 @@
+"""Private process-entry handlers used by generated harness configuration."""
+from __future__ import annotations
+
+import argparse
+import importlib
+import sys
+from pathlib import Path
+
+from audiagentic.foundation.contracts.errors import make_error
+
+
+def cmd_mcp(args: argparse.Namespace, project_root: Path) -> int:
+    """Run a configured component MCP module over stdio.
+
+    This is intentionally an internal launcher contract: generated MCP config
+    invokes it, but it is not part of the supported interactive CLI surface.
+    """
+    del project_root
+    module = importlib.import_module(args.module)
+    main = getattr(module, "main", None)
+    if not callable(main):
+        raise make_error(
+            prefix="CFG",
+            component="MCP",
+            number=2,
+            kind="mcp",
+            message="MCP module does not expose a callable main().",
+            details={"module": args.module},
+        )
+    original_argv = sys.argv
+    try:
+        sys.argv = [args.module, *(args.module_args or [])]
+        result = main()
+    finally:
+        sys.argv = original_argv
+    return result if isinstance(result, int) else 0