multi-forge 0.2.1__tar.gz → 0.4.0__tar.gz

{multi_forge-0.2.1 → multi_forge-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multi-forge
-Version: 0.2.1
+Version: 0.4.0
 Summary: Multi-runtime agent toolkit: proxy routing, cost control, session management, policy enforcement, and workflow orchestration
 Project-URL: Homepage, https://github.com/hapa1i/multi-forge
 Project-URL: Repository, https://github.com/hapa1i/multi-forge
@@ -41,9 +41,13 @@ Description-Content-Type: text/markdown
 
 # Multi-Forge
 
+<p align="left">
+  <img src="assets/logo.jpg" alt="Dusk" width=240">
+</p>
+
 [![PyPI](https://img.shields.io/pypi/v/multi-forge)](https://pypi.org/project/multi-forge/)
 [![Python](https://img.shields.io/pypi/pyversions/multi-forge)](https://pypi.org/project/multi-forge/)
-[![License](https://img.shields.io/github/license/hapa1i/multi-forge)](LICENSE)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
 
 > [!WARNING]
 > **Research Preview** -- Forge is under active development. APIs, commands, and file formats may change without notice
@@ -92,7 +96,7 @@ Running `claude` directly bypasses session tracking. When you launch through For
 | Hook-driven artifacts  | No                | Yes -- plan snapshots, transcript capture     |
 | Policy enforcement     | No                | Yes -- TDD, coding standards, supervisor      |
 | Search across sessions | No                | Yes -- `forge search` indexes transcripts     |
-| Handoff agent          | No                | Yes -- auto-updates project docs on exit      |
+| Project memory         | No                | Yes -- passported docs auto-updated on exit   |
 
 Even without a proxy, `forge session start` gives you session tracking, hooks, and the status line (direct mode is the
 default). The proxy adds multi-model routing on top. (`forge claude start` is also available as a bare launcher with
@@ -205,9 +209,10 @@ inside Claude Code for an interactive walkthrough.
 | ---------------------- | -------------------------------------------- |
 | `forge claude`         | Bare launch, settings preset management      |
 | `forge session`        | Named sessions, worktrees, resume, fork      |
+| `forge memory`         | Project memory passports, shadow proposals   |
 | `forge proxy`          | Model routing, templates, tier mappings      |
 | `forge authentication` | Credential management (`credentials.yaml`)   |
-| `forge guard`          | Policy enforcement, plan supervision         |
+| `forge policy`         | Policy enforcement, plan supervision         |
 | `forge workflow`       | Workflow runners (panel, analyze, debate)    |
 | `forge search`         | Transcript search across sessions            |
 | `forge config`         | Runtime preferences (`~/.forge/config.yaml`) |
@@ -218,11 +223,12 @@ Run `forge <command> --help` for details on any command.
 
 ## Documentation
 
-| Audience         | Location                           | Contents                                          |
-| ---------------- | ---------------------------------- | ------------------------------------------------- |
-| **Users**        | [docs/end-user/](docs/end-user/)   | Tour, guides for sessions, proxies, policies, ... |
-| **Developers**   | [docs/developer/](docs/developer/) | Setup, coding standards, testing guidelines       |
-| **Architecture** | [docs/design.md](docs/design.md)   | System narrative, data flow, invariants           |
+| Audience         | Location                           | Contents                                             |
+| ---------------- | ---------------------------------- | ---------------------------------------------------- |
+| **Users**        | [docs/end-user/](docs/end-user/)   | Tour, guides for sessions, proxies, policies, ...    |
+| **Developers**   | [docs/developer/](docs/developer/) | Setup, coding standards, testing guidelines          |
+| **Architecture** | [docs/design.md](docs/design.md)   | System narrative, data flow, invariants              |
+| **Work Board**   | [docs/board/](docs/board/)         | Cards, checklists, change log, implementation memory |
 
 ## Contributing
 

{multi_forge-0.2.1 → multi_forge-0.4.0}/README.md

@@ -1,8 +1,12 @@
 # Multi-Forge
 
+<p align="left">
+  <img src="assets/logo.jpg" alt="Dusk" width=240">
+</p>
+
 [![PyPI](https://img.shields.io/pypi/v/multi-forge)](https://pypi.org/project/multi-forge/)
 [![Python](https://img.shields.io/pypi/pyversions/multi-forge)](https://pypi.org/project/multi-forge/)
-[![License](https://img.shields.io/github/license/hapa1i/multi-forge)](LICENSE)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
 
 > [!WARNING]
 > **Research Preview** -- Forge is under active development. APIs, commands, and file formats may change without notice
@@ -51,7 +55,7 @@ Running `claude` directly bypasses session tracking. When you launch through For
 | Hook-driven artifacts  | No                | Yes -- plan snapshots, transcript capture     |
 | Policy enforcement     | No                | Yes -- TDD, coding standards, supervisor      |
 | Search across sessions | No                | Yes -- `forge search` indexes transcripts     |
-| Handoff agent          | No                | Yes -- auto-updates project docs on exit      |
+| Project memory         | No                | Yes -- passported docs auto-updated on exit   |
 
 Even without a proxy, `forge session start` gives you session tracking, hooks, and the status line (direct mode is the
 default). The proxy adds multi-model routing on top. (`forge claude start` is also available as a bare launcher with
@@ -164,9 +168,10 @@ inside Claude Code for an interactive walkthrough.
 | ---------------------- | -------------------------------------------- |
 | `forge claude`         | Bare launch, settings preset management      |
 | `forge session`        | Named sessions, worktrees, resume, fork      |
+| `forge memory`         | Project memory passports, shadow proposals   |
 | `forge proxy`          | Model routing, templates, tier mappings      |
 | `forge authentication` | Credential management (`credentials.yaml`)   |
-| `forge guard`          | Policy enforcement, plan supervision         |
+| `forge policy`         | Policy enforcement, plan supervision         |
 | `forge workflow`       | Workflow runners (panel, analyze, debate)    |
 | `forge search`         | Transcript search across sessions            |
 | `forge config`         | Runtime preferences (`~/.forge/config.yaml`) |
@@ -177,11 +182,12 @@ Run `forge <command> --help` for details on any command.
 
 ## Documentation
 
-| Audience         | Location                           | Contents                                          |
-| ---------------- | ---------------------------------- | ------------------------------------------------- |
-| **Users**        | [docs/end-user/](docs/end-user/)   | Tour, guides for sessions, proxies, policies, ... |
-| **Developers**   | [docs/developer/](docs/developer/) | Setup, coding standards, testing guidelines       |
-| **Architecture** | [docs/design.md](docs/design.md)   | System narrative, data flow, invariants           |
+| Audience         | Location                           | Contents                                             |
+| ---------------- | ---------------------------------- | ---------------------------------------------------- |
+| **Users**        | [docs/end-user/](docs/end-user/)   | Tour, guides for sessions, proxies, policies, ...    |
+| **Developers**   | [docs/developer/](docs/developer/) | Setup, coding standards, testing guidelines          |
+| **Architecture** | [docs/design.md](docs/design.md)   | System narrative, data flow, invariants              |
+| **Work Board**   | [docs/board/](docs/board/)         | Cards, checklists, change log, implementation memory |
 
 ## Contributing
 

{multi_forge-0.2.1 → multi_forge-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "multi-forge"
-version = "0.2.1"
+version = "0.4.0"
 description = "Multi-runtime agent toolkit: proxy routing, cost control, session management, policy enforcement, and workflow orchestration"
 readme = "README.md"
 license = "Apache-2.0"
@@ -104,10 +104,9 @@ markers = [
 asyncio_mode = "auto"
 
 [tool.mypy]
-# qa/ ships a copy of walkthrough-state.py generated from the walkthrough/ copy
-# by scripts/sync-walkthrough-state.py (pre-commit) and verified by
-# test_walkthrough_state_sync.py. Exclude it to avoid a duplicate-module
-# collision; the walkthrough/ copy is the one type-checked.
+# Same-named standalone scripts in separate skill directories collide in mypy's
+# module map during broad scans. Keep this exclusion local to the duplicate
+# script name; it is not a source-of-truth relationship between the skills.
 exclude = [
     'src/skills/qa/scripts/walkthrough-state\.py$',
 ]
@@ -123,10 +122,11 @@ disallow_untyped_calls = false
 constraint-dependencies = [
     "filelock>=3.20.3",
     "virtualenv>=20.36.1",
-    "aiohttp>=3.13.4",
+    "aiohttp>=3.14.0",
     "cryptography>=46.0.7",
     "python-multipart>=0.0.26",
     "Pygments>=2.20.0",
+    "starlette>=1.0.1",
 ]
 # litellm pins fastapi-sso<0.17.0 but 0.16.x has a CSRF vulnerability.
 # Forge doesn't use fastapi-sso directly; override to force the patched version.
@@ -149,6 +149,7 @@ dev = [
     "types-PyYAML>=6.0.0",
     "types-requests>=2.31.0",
     "python-dotenv>=1.2.1",
+    "httpx2>=2.3.0",
 ]
 provider-check = [
     "anthropic>=0.100.0",

{multi_forge-0.2.1 → multi_forge-0.4.0}/src/forge/__init__.py

@@ -1,3 +1,3 @@
 """Multi-Forge - Multi-runtime agent toolkit."""
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"

multi_forge-0.4.0/src/forge/cli/activity.py

@@ -0,0 +1,151 @@
+"""``forge activity`` — per-session Forge *automation* activity (supervisor, memory
+writer, workflow verbs) + policy decisions. NOT your full interactive Claude usage.
+
+Reads the two already-captured planes (usage ledger + ``confirmed.policy.decisions``)
+via :func:`forge.core.ops.usage_summary.build_session_activity_summary` and renders a
+table. Cost is reported-or-estimated (best-effort attribution) — ``forge proxy costs show``
+stays the authoritative spend view.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import asdict
+from datetime import datetime, timedelta, timezone
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from forge.cli.output import print_error_with_tip
+from forge.core.ops.session_context import (
+    SessionContextError,
+    resolve_session_identifier,
+)
+from forge.core.ops.usage_summary import (
+    SessionActivitySummary,
+    build_session_activity_summary,
+)
+
+console = Console()
+
+
+@click.command("activity")
+@click.argument("session", required=False)
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+@click.option("--days", "-d", type=int, default=30, help="Look back this many days (default: 30)")
+@click.option("--all", "all_time", is_flag=True, help="Report all time (ignore --days)")
+def activity_cmd(session: str | None, as_json: bool, days: int, all_time: bool) -> None:
+    """Show Forge's automation activity for a session: supervisor checks, cost, tokens.
+
+    This is what Forge did *on top of* your session — the supervisor, memory writer,
+    and workflow verbs (panel/debate/...) — plus policy decisions. It is **not** your
+    full interactive Claude usage. Reads the usage ledger and the session's
+    policy-decision log. Cost is reported-or-estimated (best-effort attribution);
+    'forge proxy costs show' is the authoritative spend view.
+
+    \b
+    Examples:
+        forge activity                  # current session ($FORGE_SESSION)
+        forge activity planner          # a named session (or Claude UUID)
+        forge activity --all --json     # full history, JSON
+    """
+    try:
+        session_name, forge_root = resolve_session_identifier(session)
+    except SessionContextError as e:
+        if as_json:
+            click.echo(json.dumps({"error": str(e)}))
+        else:
+            print_error_with_tip(
+                str(e),
+                "Run 'forge session list' to see sessions.",
+                console=console,
+            )
+        sys.exit(1)
+
+    since = None if all_time else datetime.now(timezone.utc) - timedelta(days=days)
+    summary = build_session_activity_summary(session_name, forge_root, since=since)
+
+    if as_json:
+        console.print_json(data=asdict(summary))
+        return
+    _render(summary, days=None if all_time else days)
+
+
+def _render(summary: SessionActivitySummary, *, days: int | None) -> None:
+    scope = "all time" if days is None else f"last {days}d"
+    if summary.is_empty:
+        console.print(f"[dim]No Forge activity for session '{summary.session}' ({scope}).[/dim]")
+        return
+
+    console.print(f"\n[bold]Forge activity — {summary.session}[/bold] [dim]({scope})[/dim]")
+    console.print(
+        "[dim]Forge automation (supervisor, memory writer, workflow verbs) — "
+        "not your full interactive session.[/dim]"
+    )
+
+    if summary.commands:
+        # The Workers column only earns its width when a fan-out (panel/debate/...) ran;
+        # supervisor/memory-writer have no workers, so most sessions skip it.
+        show_workers = any(c.workers for c in summary.commands)
+        table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+        table.add_column("Command", style="cyan")
+        table.add_column("Calls", justify="right")
+        if show_workers:
+            table.add_column("Workers", justify="right", style="dim")
+        table.add_column("Errors", justify="right")
+        table.add_column("Tokens in/out", justify="right", style="dim")
+        table.add_column("Cost", justify="right", style="dim")
+        for c in summary.commands:
+            errors = f"[red]{c.errors}[/red]" if c.errors else "0"
+            tokens = f"{c.input_tokens}/{c.output_tokens}" if (c.input_tokens or c.output_tokens) else "-"
+            cost = f"~{_fmt_usd(c.cost_micro_usd)}" if c.cost_micro_usd is not None else "-"
+            row = [c.command, str(c.calls)]
+            if show_workers:
+                row.append(str(c.workers) if c.workers else "-")
+            row += [errors, tokens, cost]
+            table.add_row(*row)
+        console.print(table)
+
+    pol = summary.policy
+    if pol and pol.has_content:
+        console.print(
+            f"\n[bold]Supervisor[/bold]: {pol.supervisor_allow} allow · "
+            f"{pol.supervisor_warn} warn · {pol.supervisor_deny} block"
+        )
+        for warning in pol.recent_warnings:
+            console.print(f"  [yellow]•[/yellow] {warning}")
+
+    if summary.subagents:
+        console.print(f"\n[bold]Subagents[/bold]: {summary.subagents}")
+
+    total_cost = f"~{_fmt_usd(summary.total_cost_micro_usd)}" if summary.total_cost_micro_usd is not None else "n/a"
+    console.print(
+        f"\n[dim]Total:[/dim] {summary.total_events} events · "
+        f"{summary.total_input_tokens}/{summary.total_output_tokens} tok · {total_cost}"
+    )
+
+    for note in _footnotes(summary):
+        console.print(f"[dim]{note}[/dim]")
+
+
+def _footnotes(summary: SessionActivitySummary) -> list[str]:
+    notes: list[str] = []
+    if summary.cost_partial:
+        notes.append("cost is best-effort and partial (some calls report no cost)")
+    if summary.policy is not None and summary.policy.log_capped:
+        notes.append("policy decision log is at capacity — older decisions may not be shown")
+    if summary.session_tagging_partial:
+        notes.append("some calls (e.g. the action tagger) are not session-attributed")
+    notes.append("cost is reported-or-estimated, best-effort; 'forge proxy costs show' is the authoritative spend view")
+    return notes
+
+
+def _fmt_usd(micros: int | None) -> str:
+    if micros is None:
+        return "-"
+    dollars = micros / 1_000_000
+    if dollars and abs(dollars) < 0.01:
+        return f"${dollars:.4f}"
+    return f"${dollars:.2f}"

{multi_forge-0.2.1 → multi_forge-0.4.0}/src/forge/cli/auth.py

@@ -408,8 +408,7 @@ def status(profile: str | None) -> None:
     help="Profile to remove credentials from (default: 'default' or FORGE_PROFILE)",
 )
 @click.option("--yes", "-y", is_flag=True, help="Skip confirmation prompt")
-@click.option("--force", "-f", is_flag=True, hidden=True, help="Deprecated alias for --yes")
-def logout(profile: str | None, yes: bool, force: bool) -> None:
+def logout(profile: str | None, yes: bool) -> None:
     """Remove stored credentials for a profile.
 
     Deletes the profile from ~/.forge/credentials.yaml.
@@ -421,7 +420,6 @@ def logout(profile: str | None, yes: bool, force: bool) -> None:
         forge authentication logout --profile work
         forge authentication logout -y  # Skip confirmation
     """
-    yes = yes or force
     profile_name = resolve_profile(profile)
 
     if not yes:

{multi_forge-0.2.1 → multi_forge-0.4.0}/src/forge/cli/backend.py

@@ -21,6 +21,7 @@ from forge.backend import BackendManager
 from forge.backend.adapters import get_adapter
 from forge.backend.creation import create_backend_config, get_backend_config_path
 from forge.backend.registry import BackendRegistryStore, is_pid_alive
+from forge.cli.output import print_error_with_tip, print_tip
 from forge.core.paths import display_path, get_forge_home
 
 
@@ -64,7 +65,7 @@ def list_cmd(as_json: bool) -> None:
 
     if not backends:
         console.print("No backends found.")
-        console.print("\n[dim]Tip: Run 'forge backend create litellm'.[/dim]")
+        print_tip("Run 'forge backend create litellm'.", console=console)
         return
 
     table = Table(title="Forge Backends")
@@ -146,7 +147,7 @@ def show_cmd(backend_id: str, raw: bool) -> None:
             console.print(syntax)
     else:
         console.print(f"\n[dim]No config found for adapter '{adapter_type}'.[/dim]")
-        console.print(f"[dim]Tip: Run 'forge backend create {adapter_type}'.[/dim]")
+        print_tip(f"Run 'forge backend create {adapter_type}'.", blank_before=False, console=console)
 
 
 @backend.command("create")
@@ -166,10 +167,13 @@ def create_cmd(adapter: str, config: Path | None) -> None:
 
     config_path = get_backend_config_path(adapter)
     if config_path.exists():
-        console.print(f"[yellow]Backend config already exists:[/yellow] {display_path(config_path)}")
-        console.print("\n[dim]Start an instance with:[/dim]")
-        console.print(f"  forge backend start {adapter} --port 4000")
-        return
+        print_error_with_tip(
+            f"Backend config already exists: {display_path(config_path)}",
+            "Start an instance with:",
+            commands=[f"forge backend start {adapter} --port 4000"],
+            console=console,
+        )
+        sys.exit(1)
 
     try:
         config_path = create_backend_config(
@@ -194,9 +198,12 @@ def start_cmd(adapter: str, port: int) -> None:
 
     config_path = get_backend_config_path(adapter)
     if not config_path.exists():
-        console.print(f"[red]Error:[/red] Backend config not found for '{adapter}'")
-        console.print("\n[dim]Create it first:[/dim]")
-        console.print(f"  forge backend create {adapter}")
+        print_error_with_tip(
+            f"Backend config not found for '{adapter}'",
+            "Create it first:",
+            commands=[f"forge backend create {adapter}"],
+            console=console,
+        )
         sys.exit(1)
 
     backend_id = f"{adapter}-{port}"
@@ -244,8 +251,7 @@ def stop_cmd(adapter: str, port: int) -> None:
     help="Delete specific instance (if not specified, deletes config)",
 )
 @click.option("--yes", "-y", is_flag=True, help="Skip confirmation prompt")
-@click.option("--force", "-f", is_flag=True, hidden=True, help="Deprecated alias for --yes")
-def delete_cmd(adapter: str, port: int | None, yes: bool, force: bool) -> None:
+def delete_cmd(adapter: str, port: int | None, yes: bool) -> None:
     """Delete a backend instance or config.
 
     Without --port: Deletes the backend config (stops all instances first).
@@ -253,7 +259,6 @@ def delete_cmd(adapter: str, port: int | None, yes: bool, force: bool) -> None:
     """
     import shutil
 
-    yes = yes or force
     console = Console(width=200)
 
     if port is not None:
@@ -271,7 +276,12 @@ def delete_cmd(adapter: str, port: int | None, yes: bool, force: bool) -> None:
     else:
         backend_dir = get_forge_home() / "backends" / adapter
         if not backend_dir.exists():
-            console.print(f"[red]Error:[/red] Backend config not found for '{adapter}'")
+            print_error_with_tip(
+                f"Backend config not found for '{adapter}'",
+                "Create it first:",
+                commands=[f"forge backend create {adapter}"],
+                console=console,
+            )
             sys.exit(1)
 
         if not yes and not click.confirm(f"Delete backend config for '{adapter}' (stops all instances)?"):

{multi_forge-0.2.1 → multi_forge-0.4.0}/src/forge/cli/claude.py

@@ -20,10 +20,9 @@ from rich.console import Console
 
 from forge.core.paths import display_path
 from forge.proxy.proxies import (
+    ProxyNotFoundError,
     ProxyRegistryCorruptedError,
-    ProxyRegistryStore,
     ProxyResolutionError,
-    resolve_proxy,
 )
 from forge.session.direct_model import apply_direct_model_env
 
@@ -208,20 +207,22 @@ def start_cmd(
     proxy_display: str | None = None
 
     if proxy_id:
-        proxy_store = ProxyRegistryStore()
+        from forge.proxy.proxy_orchestrator import ProxyStartError, ensure_proxy
 
         try:
-            registry = proxy_store.read()
+            entry, started = ensure_proxy(proxy_id)
         except ProxyRegistryCorruptedError as e:
             click.echo(f"Error: {e}")
             sys.exit(1)
-
-        try:
-            entry = resolve_proxy(registry, proxy_id)
-        except ProxyResolutionError as e:
+        except (ProxyResolutionError, ProxyStartError) as e:
             click.echo(f"Error: {e}")
+            if isinstance(e, ProxyNotFoundError):
+                click.echo("Tip: Run 'forge proxy template list' to see available templates.")
             sys.exit(1)
 
+        if started:
+            console.print(f"[dim]Started proxy '{entry.proxy_id}' from template '{proxy_id}'.[/dim]")
+
         try:
             _healthcheck_proxy(
                 base_url=entry.base_url,
@@ -391,13 +392,11 @@ def preset_edit() -> None:
 
 @preset.command("reset")
 @click.option("--yes", "-y", is_flag=True, help="Skip confirmation prompt")
-@click.option("--force", "-f", is_flag=True, hidden=True, help="Deprecated alias for --yes")
-def preset_reset(yes: bool, force: bool) -> None:
+def preset_reset(yes: bool) -> None:
     """Reset settings preset to built-in defaults."""
     from forge.core.state import atomic_write_text
     from forge.install.preset import get_builtin_preset_json, get_preset_path
 
-    yes = yes or force
     preset_path = get_preset_path()
 
     if not yes: