briefloop 0.11.12__py3-none-any.whl

multi_agent_brief/cli/hermes_commands.py

@@ -0,0 +1,356 @@
+"""hermes — Hermes Agent skill / cron plan / prompt commands."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from multi_agent_brief.hermes import (
+    build_hermes_cron_plan,
+    install_hermes_skill,
+    render_hermes_cron_commands,
+    render_hermes_cron_markdown,
+    render_hermes_prompt,
+    render_hermes_skill,
+)
+from multi_agent_brief.hermes.adapter import sync_cached_package_source, write_json
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    """Register the hermes subcommand group."""
+    hermes_parser = subparsers.add_parser(
+        "hermes",
+        help="Generate Hermes Agent skill and cron plans for scheduled briefs.",
+    )
+    hermes_sub = hermes_parser.add_subparsers(
+        dest="hermes_action", required=True
+    )
+
+    hermes_skill = hermes_sub.add_parser(
+        "skill", help="Write the Hermes SKILL.md for MABW cron jobs."
+    )
+    hermes_skill.add_argument(
+        "--output",
+        help="Output SKILL.md path"
+        " (default: .agents/hermes-skills/multi-agent-brief-hermes/SKILL.md).",
+    )
+
+    hermes_plan = hermes_sub.add_parser(
+        "cron-plan",
+        help="Generate a Hermes cron plan JSON/Markdown for a workspace.",
+    )
+    hermes_plan.add_argument(
+        "--config", required=True, help="Path to workspace config.yaml."
+    )
+    hermes_plan.add_argument(
+        "--repo-workdir",
+        help="Repository workdir for Hermes cron --workdir"
+        " (default: current directory).",
+    )
+    hermes_plan.add_argument(
+        "--cadence",
+        help="Comma-separated cadences: weekly,monthly,daily."
+        " Defaults to config cadence or weekly.",
+    )
+    hermes_plan.add_argument(
+        "--deliver",
+        default="local",
+        help="Hermes delivery target, e.g. local, feishu, telegram.",
+    )
+    hermes_plan.add_argument(
+        "--profile",
+        default="",
+        help="Optional existing Hermes profile name.",
+    )
+    hermes_plan.add_argument(
+        "--output",
+        help="Output JSON path"
+        " (default: workspace/output/intermediate/hermes_cron_plan.json).",
+    )
+    hermes_plan.add_argument(
+        "--markdown", help="Optional Markdown output path."
+    )
+
+    hermes_commands = hermes_sub.add_parser(
+        "cron-commands",
+        help="Print Hermes cron create commands for a workspace.",
+    )
+    hermes_commands.add_argument(
+        "--config", required=True, help="Path to workspace config.yaml."
+    )
+    hermes_commands.add_argument(
+        "--repo-workdir",
+        help="Repository workdir for Hermes cron --workdir"
+        " (default: current directory).",
+    )
+    hermes_commands.add_argument(
+        "--cadence",
+        help="Comma-separated cadences: weekly,monthly,daily."
+        " Defaults to config cadence or weekly.",
+    )
+    hermes_commands.add_argument(
+        "--deliver",
+        default="local",
+        help="Hermes delivery target, e.g. local, feishu, telegram.",
+    )
+    hermes_commands.add_argument(
+        "--profile",
+        default="",
+        help="Optional existing Hermes profile name.",
+    )
+
+    hermes_sync = hermes_sub.add_parser(
+        "sync-sources",
+        help="Enable cached_package input/hermes_cache in workspace"
+        " sources.yaml.",
+    )
+    hermes_sync.add_argument(
+        "--config", required=True, help="Path to workspace config.yaml."
+    )
+    hermes_sync.add_argument(
+        "--cache-dir",
+        default="input/hermes_cache",
+        help="Cache path written into sources.yaml.",
+    )
+    hermes_sync.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show changes without writing.",
+    )
+
+    hermes_install = hermes_sub.add_parser(
+        "install-skill",
+        help="Install the MABW Hermes skill to a Hermes-discoverable"
+        " directory.",
+    )
+    hermes_install.add_argument(
+        "--target",
+        help="Target skill directory (auto-detected if omitted).",
+    )
+
+    hermes_plugin = hermes_sub.add_parser(
+        "install-plugin",
+        help="Install the MABW Hermes plugin to ~/.hermes/plugins/mabw.",
+    )
+
+    hermes_prompt = hermes_sub.add_parser(
+        "prompt",
+        help="Generate a Hermes run prompt for a workspace.",
+    )
+    hermes_prompt.add_argument(
+        "--config", required=True, help="Path to workspace config.yaml."
+    )
+    hermes_prompt.add_argument(
+        "--repo-workdir",
+        help="Repository workdir (default: current directory).",
+    )
+    hermes_prompt.add_argument(
+        "--venv",
+        help="Virtual env path"
+        " (default: <repo>/.venv/{bin,Scripts}/activate).",
+    )
+
+
+def handle(args: argparse.Namespace) -> int:
+    """Dispatch hermes subcommands."""
+    if args.hermes_action == "skill":
+        return _hermes_skill(args)
+    if args.hermes_action == "cron-plan":
+        return _hermes_cron_plan(args)
+    if args.hermes_action == "cron-commands":
+        return _hermes_cron_commands(args)
+    if args.hermes_action == "sync-sources":
+        return _hermes_sync_sources(args)
+    if args.hermes_action == "install-skill":
+        return _hermes_install_skill(args)
+    if args.hermes_action == "install-plugin":
+        return _hermes_install_plugin(args)
+    if args.hermes_action == "prompt":
+        return _hermes_prompt(args)
+    return 1
+
+
+def _build_hermes_plan_from_args(args: argparse.Namespace):
+    from multi_agent_brief.core.config import load_config
+
+    config_path = Path(args.config).resolve()
+    if not config_path.exists():
+        print(f"[error] config.yaml not found: {config_path}")
+        return None
+    config = load_config(config_path)
+    cadences = None
+    if getattr(args, "cadence", None):
+        cadences = [
+            c.strip() for c in args.cadence.split(",") if c.strip()
+        ]
+    repo_workdir = (
+        Path(args.repo_workdir).resolve()
+        if getattr(args, "repo_workdir", None)
+        else Path.cwd().resolve()
+    )
+    return build_hermes_cron_plan(
+        config=config,
+        workspace=config_path.parent,
+        repo_workdir=repo_workdir,
+        cadences=cadences,
+        deliver=getattr(args, "deliver", "local"),
+        profile=getattr(args, "profile", ""),
+    )
+
+
+def _hermes_skill(args: argparse.Namespace) -> int:
+    output = (
+        Path(args.output)
+        if args.output
+        else Path(
+            ".agents/hermes-skills/multi-agent-brief-hermes/SKILL.md"
+        )
+    )
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(render_hermes_skill(), encoding="utf-8")
+    print(f"[hermes] Wrote Hermes skill: {output}")
+    print(
+        "[hint] Run 'multi-agent-brief hermes install-skill' to install to"
+        " a Hermes-discoverable directory."
+    )
+    return 0
+
+
+def _hermes_cron_plan(args: argparse.Namespace) -> int:
+    plan = _build_hermes_plan_from_args(args)
+    if plan is None:
+        return 1
+    workspace = Path(plan.workspace)
+    output = (
+        Path(args.output)
+        if args.output
+        else workspace / "output" / "intermediate" / "hermes_cron_plan.json"
+    )
+    write_json(output, plan.to_dict())
+    print(f"[hermes] Wrote cron plan: {output}")
+    if args.markdown:
+        md_path = Path(args.markdown)
+        md_path.parent.mkdir(parents=True, exist_ok=True)
+        md_path.write_text(
+            render_hermes_cron_markdown(plan), encoding="utf-8"
+        )
+        print(f"[hermes] Wrote cron plan Markdown: {md_path}")
+    print(
+        "[hint] Run 'multi-agent-brief hermes cron-commands"
+        " --config <workspace>/config.yaml' to print install commands."
+    )
+    return 0
+
+
+def _hermes_cron_commands(args: argparse.Namespace) -> int:
+    plan = _build_hermes_plan_from_args(args)
+    if plan is None:
+        return 1
+    print(render_hermes_cron_commands(plan), end="")
+    return 0
+
+
+def _hermes_sync_sources(args: argparse.Namespace) -> int:
+    config_path = Path(args.config).resolve()
+    sources_path = config_path.parent / "sources.yaml"
+    try:
+        result = sync_cached_package_source(
+            sources_path=sources_path,
+            cache_dir=args.cache_dir,
+            dry_run=args.dry_run,
+        )
+    except Exception as exc:
+        print(f"[error] {exc}")
+        return 1
+    action = (
+        "would update"
+        if args.dry_run and result["changed"]
+        else "updated"
+        if result["changed"]
+        else "already configured"
+    )
+    print(f"[hermes] sources.yaml {action}: {sources_path}")
+    print(f"[hermes] cached_package path: {result['cache_dir']}")
+    print(
+        "[hermes] enabled providers:"
+        f" {', '.join(result['enabled_providers'])}"
+    )
+    return 0
+
+
+def _hermes_install_skill(args: argparse.Namespace) -> int:
+    result = install_hermes_skill(target_dir=args.target)
+    print(f"[hermes] Installed skill: {result['skill_path']}")
+    if result["auto_detected"]:
+        print(
+            "[hermes] Auto-detected Hermes skill directory:"
+            f" {result['skill_dir']}"
+        )
+    if result["hint"]:
+        print(f"[hint] {result['hint']}")
+    print()
+    print(
+        "[hermes] Next: generate a run prompt for your workspace:"
+    )
+    print(
+        "  multi-agent-brief hermes prompt"
+        " --config <workspace>/config.yaml"
+    )
+    print(
+        "[hermes] Then paste the prompt into Hermes to start the delegated"
+        " brief workflow."
+    )
+    return 0
+
+
+def _hermes_install_plugin(_args: argparse.Namespace) -> int:
+    import shutil
+
+    repo_root = Path.cwd().resolve()
+    source = repo_root / "integrations" / "hermes-plugin" / "mabw"
+    target = Path.home() / ".hermes" / "plugins" / "mabw"
+
+    if not source.exists():
+        print(
+            f"[error] Plugin source not found: {source}"
+        )
+        print(
+            "[hint] Run this command from the MABW source repo root."
+        )
+        return 1
+
+    if target.exists():
+        shutil.rmtree(target)
+
+    shutil.copytree(source, target)
+    print(f"Plugin installed: {target}")
+    print(
+        "Next: restart Hermes or run `hermes plugins enable mabw`"
+    )
+    return 0
+
+
+def _hermes_prompt(args: argparse.Namespace) -> int:
+    config_path = Path(args.config).resolve()
+    workspace = config_path.parent
+    repo_workdir = (
+        Path(args.repo_workdir).resolve()
+        if getattr(args, "repo_workdir", None)
+        else Path.cwd().resolve()
+    )
+    if args.venv:
+        venv_activate = str(Path(args.venv).resolve())
+    else:
+        venv = repo_workdir / ".venv"
+        if sys.platform == "win32":
+            venv_activate = str(venv / "Scripts" / "activate")
+        else:
+            venv_activate = str(venv / "bin" / "activate")
+    prompt = render_hermes_prompt(
+        workspace=workspace,
+        repo_workdir=repo_workdir,
+        venv_path=venv_activate,
+    )
+    print(prompt, end="")
+    return 0

multi_agent_brief/cli/improve_commands.py

@@ -0,0 +1,224 @@
+"""Improvement Ledger CLI commands."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Any
+
+from multi_agent_brief.improvement.contract import (
+    ALLOWED_STATUSES,
+    AUDIENCE_GUIDANCE_CATEGORIES,
+    AUDIENCE_GUIDANCE_SCOPES,
+)
+from multi_agent_brief.improvement.memory import rebuild_improvement_memory
+from multi_agent_brief.improvement.state import (
+    ImprovementLedgerError,
+    approve_improvement,
+    improvement_stats,
+    list_improvements,
+    propose_improvement,
+    reject_improvement,
+    revert_improvement,
+    show_improvement,
+    validate_improvement_ledger,
+)
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    improve_parser = subparsers.add_parser(
+        "improve",
+        help="Manage the append-only Improvement Ledger.",
+    )
+    actions = improve_parser.add_subparsers(dest="improve_action", required=True)
+
+    propose_parser = actions.add_parser(
+        "propose",
+        help="Append a proposed audience-guidance improvement.",
+    )
+    _add_workspace(propose_parser)
+    propose_parser.add_argument("--guidance", required=True, help="Bounded audience guidance text.")
+    propose_parser.add_argument("--category", required=True, choices=sorted(AUDIENCE_GUIDANCE_CATEGORIES))
+    propose_parser.add_argument("--scope", required=True, choices=sorted(AUDIENCE_GUIDANCE_SCOPES))
+    propose_parser.add_argument("--source-summary", help="Required for explicit human proposals.")
+    propose_parser.add_argument("--from-issue", help="Feedback issue id to freeze as source evidence.")
+    propose_parser.add_argument("--supersedes", help="Approved materializable entry id replaced by this proposal.")
+    _add_json(propose_parser)
+
+    list_parser = actions.add_parser(
+        "list",
+        help="List current Improvement Ledger entries.",
+    )
+    _add_workspace(list_parser)
+    list_parser.add_argument("--status", choices=sorted(ALLOWED_STATUSES), help="Filter by current status.")
+    _add_json(list_parser)
+
+    show_parser = actions.add_parser(
+        "show",
+        help="Show one Improvement Ledger entry and its revisions.",
+    )
+    _add_workspace(show_parser)
+    show_parser.add_argument("--entry-id", required=True, help="Improvement entry id, such as AG-0001.")
+    _add_json(show_parser)
+
+    approve_parser = actions.add_parser(
+        "approve",
+        help="Approve a proposed Improvement Ledger entry without applying it.",
+    )
+    _add_workspace(approve_parser)
+    approve_parser.add_argument("--entry-id", required=True, help="Improvement entry id.")
+    approve_parser.add_argument("--by", required=True, help="Operator id approving this entry.")
+    _add_json(approve_parser)
+
+    reject_parser = actions.add_parser(
+        "reject",
+        help="Reject a proposed Improvement Ledger entry.",
+    )
+    _add_workspace(reject_parser)
+    reject_parser.add_argument("--entry-id", required=True, help="Improvement entry id.")
+    reject_parser.add_argument("--by", required=True, help="Operator id rejecting this entry.")
+    reject_parser.add_argument("--reason", required=True, help="Short rejection reason.")
+    _add_json(reject_parser)
+
+    revert_parser = actions.add_parser(
+        "revert",
+        help="Revert an approved Improvement Ledger entry.",
+    )
+    _add_workspace(revert_parser)
+    revert_parser.add_argument("--entry-id", required=True, help="Improvement entry id.")
+    revert_parser.add_argument("--by", required=True, help="Operator id reverting this entry.")
+    revert_parser.add_argument("--reason", required=True, help="Short revert reason.")
+    _add_json(revert_parser)
+
+    stats_parser = actions.add_parser(
+        "stats",
+        help="Summarize ledger-only Improvement counts.",
+    )
+    _add_workspace(stats_parser)
+    _add_json(stats_parser)
+
+    validate_parser = actions.add_parser(
+        "validate",
+        help="Validate the Improvement Ledger without writing files.",
+    )
+    _add_workspace(validate_parser)
+    _add_json(validate_parser)
+
+    rebuild_parser = actions.add_parser(
+        "rebuild",
+        help="Rebuild deterministic improvement/memory.md without touching runtime state.",
+    )
+    _add_workspace(rebuild_parser)
+    _add_json(rebuild_parser)
+
+
+def handle(args: argparse.Namespace) -> int:
+    try:
+        if args.improve_action == "propose":
+            state = propose_improvement(
+                workspace=args.workspace,
+                guidance=args.guidance,
+                category=args.category,
+                scope=args.scope,
+                source_summary=getattr(args, "source_summary", None),
+                from_issue=getattr(args, "from_issue", None),
+                supersedes=getattr(args, "supersedes", None),
+            )
+            _print_state("improve propose", state, as_json=getattr(args, "json", False))
+            return 0
+
+        if args.improve_action == "list":
+            state = list_improvements(
+                workspace=args.workspace,
+                status=getattr(args, "status", None),
+            )
+            _print_state("improve list", state, as_json=getattr(args, "json", False))
+            return 0
+
+        if args.improve_action == "show":
+            state = show_improvement(workspace=args.workspace, entry_id=args.entry_id)
+            _print_state("improve show", state, as_json=getattr(args, "json", False))
+            return 0
+
+        if args.improve_action == "approve":
+            state = approve_improvement(
+                workspace=args.workspace,
+                entry_id=args.entry_id,
+                approved_by=args.by,
+            )
+            _print_state("improve approve", state, as_json=getattr(args, "json", False))
+            return 0
+
+        if args.improve_action == "reject":
+            state = reject_improvement(
+                workspace=args.workspace,
+                entry_id=args.entry_id,
+                rejected_by=args.by,
+                reason=args.reason,
+            )
+            _print_state("improve reject", state, as_json=getattr(args, "json", False))
+            return 0
+
+        if args.improve_action == "revert":
+            state = revert_improvement(
+                workspace=args.workspace,
+                entry_id=args.entry_id,
+                reverted_by=args.by,
+                reason=args.reason,
+            )
+            _print_state("improve revert", state, as_json=getattr(args, "json", False))
+            return 0
+
+        if args.improve_action == "stats":
+            state = improvement_stats(workspace=args.workspace)
+            _print_state("improve stats", state, as_json=getattr(args, "json", False))
+            return 0
+
+        if args.improve_action == "validate":
+            state = validate_improvement_ledger(workspace=args.workspace)
+            _print_state("improve validate", state, as_json=getattr(args, "json", False))
+            return 0 if state.get("ok") else 1
+
+        if args.improve_action == "rebuild":
+            state = rebuild_improvement_memory(workspace=args.workspace)
+            _print_state("improve rebuild", state, as_json=getattr(args, "json", False))
+            return 0
+    except ImprovementLedgerError as exc:
+        _print_error(exc, as_json=getattr(args, "json", False))
+        return 1
+    return 1
+
+
+def _add_workspace(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--workspace", required=True, help="Path to workspace directory.")
+
+
+def _add_json(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+
+
+def _print_state(label: str, state: dict[str, Any], *, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(state, ensure_ascii=False, indent=2, sort_keys=True))
+        return
+    print(f"[{label}] ok: {state.get('ok')}")
+    print(f"[{label}] ledger: {state.get('ledger_path')}")
+    if "entry_id" in state:
+        print(f"[{label}] entry: {state.get('entry_id')}")
+    elif isinstance(state.get("entry"), dict):
+        print(f"[{label}] entry: {state['entry'].get('entry_id')}")
+    print(f"[{label}] entries: {state.get('entry_count', 0)}")
+    for diagnostic in state.get("diagnostics") or []:
+        print(f"  - {diagnostic.get('severity')}: {diagnostic.get('message')}")
+    for warning in state.get("warnings") or []:
+        print(f"  - warning: {warning.get('message')}")
+    if state.get("event_recorded") is False:
+        print(f"[{label}] event: {state.get('event_reason')}")
+
+
+def _print_error(exc: Exception, *, as_json: bool) -> None:
+    payload = exc.to_dict() if hasattr(exc, "to_dict") else {"ok": False, "error": str(exc)}
+    if as_json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True))
+    else:
+        print(f"[improve] {exc}")