ak5 1.0.0__py3-none-any.whl

ak5/__init__.py

@@ -0,0 +1,3 @@
+"""AK5 (Agent K5) - Agent-Orchestrated Kanban System."""
+
+__version__ = "1.0.0"

ak5/cli/__init__.py

@@ -0,0 +1,3 @@
+"""AK5 CLI - Terminal tool for Agent-Orchestrated Kanban."""
+
+__version__ = "0.1.0"

ak5/cli/commands/agents.py

@@ -0,0 +1,55 @@
+import click
+import httpx
+from ak5.cli.config import get_api_url
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+@click.command("agents")
+@click.option("--cap", default=None, help="Filter by capability tag (e.g. 'image-resize')")
+@click.option("--status", default=None, help="Filter by status ('idle', 'busy', 'offline')")
+@click.option("--query", default=None, help="Semantic search query")
+def agents_command(cap: str | None, status: str | None, query: str | None) -> None:
+    """Discover agents matching capability tags or search queries."""
+    api_url = get_api_url()
+    params = {}
+    if cap:
+        params["capability"] = cap
+    if status:
+        params["status"] = status
+    if query:
+        params["query"] = query
+
+    try:
+        with httpx.Client(timeout=10.0) as client:
+            resp = client.get(f"{api_url}/actors/discovery", params=params)
+            resp.raise_for_status()
+            agents = resp.json()
+
+        if not agents:
+            console.print("[yellow]No matching agents found.[/yellow]")
+            return
+
+        table = Table(title="Available Autonomous AI Agents", show_lines=True)
+        table.add_column("Agent ID", style="cyan", no_wrap=True)
+        table.add_column("Role", style="magenta")
+        table.add_column("Status", style="green")
+        table.add_column("Capabilities", style="yellow")
+
+        for a in agents:
+            caps_str = ", ".join(a.get("capabilities", []))
+            status_color = "green" if a["status"] == "idle" else ("yellow" if a["status"] == "busy" else "red")
+            table.add_row(
+                f"@{a['actor_id']}",
+                a["role"],
+                f"[{status_color}]{a['status']}[/{status_color}]",
+                caps_str,
+            )
+
+        console.print(table)
+    except httpx.ConnectError:
+        console.print(f"[bold red]✗ Failed to connect to AK5 Gateway at {api_url}[/bold red]")
+    except Exception as e:
+        console.print(f"[bold red]✗ Error querying agents:[/bold red] {e}")

ak5/cli/commands/board.py

@@ -0,0 +1,122 @@
+import asyncio
+
+import click
+import httpx
+from ak5.cli.config import get_api_url
+from rich.console import Console
+from rich.live import Live
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+console = Console()
+
+
+def render_board_view(board_data: dict) -> Table:
+    """Render 4-column Kanban board as a Rich Table."""
+    main_table = Table(
+        title=f"📋 Kanban Board: {board_data['name']} ({board_data['board_id']})",
+        show_header=True,
+        header_style="bold cyan",
+        expand=True,
+    )
+
+    stage_colors = {
+        "open": "blue",
+        "in_progress": "yellow",
+        "review": "magenta",
+        "done": "green",
+    }
+
+    # Add column headers
+    for col in board_data.get("columns", []):
+        color = stage_colors.get(col.get("stage"), "white")
+        count = len(col.get("tickets", []))
+        wip_info = f" [WIP: {count}/{col['wip_limit']}]" if col.get("wip_limit", 0) > 0 else f" ({count})"
+        main_table.add_column(f"[{color}]{col['name']}{wip_info}[/{color}]")
+
+    # Find maximum number of rows among columns
+    max_tickets = max(len(col.get("tickets", [])) for col in board_data.get("columns", [])) if board_data.get("columns") else 0
+
+    if max_tickets == 0:
+        empty_row = [Panel("[dim](Empty)[/dim]", expand=True) for _ in board_data.get("columns", [])]
+        main_table.add_row(*empty_row)
+        return main_table
+
+    for row_idx in range(max_tickets):
+        row_cells = []
+        for col in board_data.get("columns", []):
+            tickets = col.get("tickets", [])
+            if row_idx < len(tickets):
+                t = tickets[row_idx]
+                p_color = "red" if t["priority"] in ("urgent", "high") else ("yellow" if t["priority"] == "medium" else "dim")
+                status_badge = f"[{p_color}][{t['priority'].upper()}][/{p_color}]"
+
+                assignee = f"@{t['assigned_to']}" if t.get("assigned_to") else "[dim]Unassigned[/dim]"
+
+                subtask_badge = ""
+                if t.get("subtask_count", 0) > 0:
+                    subtask_badge = f"\n[bold cyan]Subtasks: {t['subtask_done_count']}/{t['subtask_count']} Done[/bold cyan]"
+
+                content = (
+                    f"[bold white]{t['title']}[/bold white]\n"
+                    f"{status_badge} [dim]{t['ticket_id']}[/dim] | {assignee}"
+                    f"{subtask_badge}"
+                )
+
+                border_color = "yellow" if col.get("stage") == "in_progress" else "white"
+                row_cells.append(Panel(content, border_style=border_color, expand=True))
+            else:
+                row_cells.append(Text(""))
+        main_table.add_row(*row_cells)
+
+    return main_table
+
+
+def fetch_board(api_url: str, board_id: str) -> dict:
+    with httpx.Client(timeout=10.0) as client:
+        resp = client.get(f"{api_url}/boards/{board_id}")
+        resp.raise_for_status()
+        return resp.json()
+
+
+async def watch_board_live(api_url: str, board_id: str) -> None:
+    """Stream SSE events and re-render board on changes."""
+    console.print(f"[bold cyan]Connecting to real-time event stream for board '{board_id}'...[/bold cyan]")
+    board_data = fetch_board(api_url, board_id)
+
+    with Live(render_board_view(board_data), console=console, refresh_per_second=4) as live:
+        async with (
+            httpx.AsyncClient(timeout=None) as client,
+            client.stream("GET", f"{api_url}/events/stream") as stream,
+        ):
+            async for line in stream.aiter_lines():
+                if line.startswith("event:"):
+                    event_type = line.split(":", 1)[1].strip()
+                    if event_type in ("TICKET_CREATED", "TICKET_MOVED", "TICKET_DELEGATED", "TICKET_UPDATED", "COMMENT_ADDED"):
+                        # Refresh board
+                        try:
+                            board_data = fetch_board(api_url, board_id)
+                            live.update(render_board_view(board_data))
+                        except (httpx.HTTPError, OSError):
+                            pass
+
+
+@click.command("board")
+@click.option("--board-id", default="proj-core-engine", help="Target Board ID")
+@click.option("--watch", is_flag=True, help="Watch board with live real-time SSE updates")
+def board_command(board_id: str, watch: bool) -> None:
+    """View Kanban board in terminal."""
+    api_url = get_api_url()
+    try:
+        if watch:
+            asyncio.run(watch_board_live(api_url, board_id))
+        else:
+            board_data = fetch_board(api_url, board_id)
+            console.print(render_board_view(board_data))
+    except httpx.ConnectError:
+        console.print(f"[bold red]✗ Failed to connect to AK5 Gateway at {api_url}[/bold red]")
+    except httpx.HTTPStatusError as e:
+        console.print(f"[bold red]✗ Board query failed ({e.response.status_code}):[/bold red] {e.response.text}")
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Watch stopped.[/yellow]")

ak5/cli/commands/delegate.py

@@ -0,0 +1,66 @@
+import click
+import httpx
+from ak5.cli.config import get_api_url, get_token
+from rich.console import Console
+
+console = Console()
+
+
+@click.command("delegate")
+@click.argument("ticket_id")
+@click.option("--to", "target_actor_id", required=True, help="Target Agent ID to delegate task to")
+@click.option("--title", required=True, help="Subtask title")
+@click.option("--desc", "description", default="", help="Subtask detailed description")
+@click.option("--priority", type=click.Choice(["low", "medium", "high", "urgent"]), default="medium")
+def delegate_command(
+    ticket_id: str,
+    target_actor_id: str,
+    title: str,
+    description: str,
+    priority: str,
+) -> None:
+    """Delegate a subtask to an agent under an existing parent ticket."""
+    api_url = get_api_url()
+    token = get_token()
+
+    headers = {}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    else:
+        # Auto-login as orchestrator if not logged in
+        with httpx.Client(timeout=5.0) as client:
+            resp = client.post(
+                f"{api_url}/auth/identify",
+                json={"actor_id": "cli_user", "actor_type": "human", "name": "CLI User", "role": "PM"},
+            )
+            if resp.is_success:
+                headers["Authorization"] = f"Bearer {resp.json()['access_token']}"
+
+    payload = {
+        "target_actor_id": target_actor_id,
+        "subtask_title": title,
+        "subtask_description": description,
+        "priority": priority,
+        "labels": ["delegated", "cli"],
+    }
+
+    try:
+        with httpx.Client(timeout=10.0) as client:
+            resp = client.post(
+                f"{api_url}/tickets/{ticket_id}/delegate",
+                json=payload,
+                headers=headers,
+            )
+            resp.raise_for_status()
+            subtask = resp.json()
+
+        console.print(
+            f"[bold green]✓[/bold green] Subtask [cyan]{subtask['ticket_id']}[/cyan] created and assigned to "
+            f"[magenta]@{target_actor_id}[/magenta] (Parent: [yellow]{ticket_id}[/yellow])"
+        )
+    except httpx.ConnectError:
+        console.print(f"[bold red]✗ Failed to connect to AK5 Gateway at {api_url}[/bold red]")
+    except httpx.HTTPStatusError as e:
+        console.print(f"[bold red]✗ Delegation failed ({e.response.status_code}):[/bold red] {e.response.text}")
+    except Exception as e:
+        console.print(f"[bold red]✗ Error:[/bold red] {e}")

ak5/cli/commands/demo.py

@@ -0,0 +1,230 @@
+import asyncio
+
+import click
+import httpx
+from ak5.cli.config import get_api_url
+from rich.console import Console
+from rich.panel import Panel
+
+console = Console()
+
+
+async def run_collaboration_simulation(api_url: str) -> None:
+    """Run E2E autonomous multi-agent collaboration scenario.
+
+    1. Human PM creates a feature ticket: "Profile Image Optimization System"
+    2. Orchestrator Agent inspects ticket, discovers available agents via capability search
+    3. Orchestrator delegates Subtask 1 to @agent_image_worker ("WebP Conversion Routine")
+    4. Orchestrator delegates Subtask 2 to @agent_code_reviewer ("Review & Security Audit")
+    5. @agent_image_worker moves subtask to In Progress, writes execution context, moves to Done
+    6. @agent_code_reviewer reviews subtask, signs off with comment, moves to Done
+    7. Orchestrator verifies all subtasks are done, closes parent ticket to Done.
+    """
+    console.print(Panel.fit(
+        "[bold cyan]AK5 Autonomous Multi-Agent Collaboration Simulation[/bold cyan]\n"
+        "[dim]Human PM ➔ Orchestrator Agent ➔ Image Worker Agent & Reviewer Agent[/dim]",
+        border_style="cyan",
+    ))
+
+    async with httpx.AsyncClient(base_url=api_url, timeout=30.0) as client:
+        # Step 0: Ensure actors
+        console.print("\n[bold yellow][Phase 0] Registering Actors...[/bold yellow]")
+        for actor in [
+            {"id": "user_pm", "type": "human", "name": "David (PM)", "role": "PM", "caps": ["planning"]},
+            {"id": "agent_orchestrator", "type": "agent", "name": "Orchestrator Agent", "role": "Lead Architect", "caps": ["orchestration", "breakdown"]},
+            {"id": "agent_image_worker", "type": "agent", "name": "Image Worker", "role": "Media Specialist", "caps": ["image-resize", "webp"]},
+            {"id": "agent_code_reviewer", "type": "agent", "name": "Code Reviewer", "role": "Senior Reviewer", "caps": ["code-review", "security"]},
+        ]:
+            resp = await client.post("/auth/identify", json={
+                "actor_id": actor["id"],
+                "actor_type": actor["type"],
+                "name": actor["name"],
+                "role": actor["role"],
+                "capabilities": actor["caps"],
+            })
+            resp.raise_for_status()
+            token = resp.json()["access_token"]
+            if actor["id"] == "user_pm":
+                pm_token = token
+            elif actor["id"] == "agent_orchestrator":
+                orch_token = token
+            elif actor["id"] == "agent_image_worker":
+                worker_token = token
+            elif actor["id"] == "agent_code_reviewer":
+                reviewer_token = token
+            console.print(f"  ✓ Actor @{actor['id']} active [{actor['type']}]")
+
+        board_id = "proj-core-engine"
+        board_resp = await client.get(f"/boards/{board_id}")
+        board_resp.raise_for_status()
+        board_data = board_resp.json()
+        col_map = {c["stage"]: c["column_id"] for c in board_data["columns"]}
+
+        # Step 1: Human PM registers master ticket
+        console.print("\n[bold yellow][Step 1] Human PM registers master ticket...[/bold yellow]")
+        t_resp = await client.post(
+            "/tickets",
+            json={
+                "title": "Profile Image Optimization System",
+                "description": "Implement automated avatar resizing to 200x200 WebP format with security audit.",
+                "board_id": board_id,
+                "column_id": col_map["open"],
+                "priority": "high",
+                "assigned_to": "agent_orchestrator",
+                "labels": ["avatar", "optimization"],
+            },
+            headers={"Authorization": f"Bearer {pm_token}"},
+        )
+        t_resp.raise_for_status()
+        parent_ticket = t_resp.json()
+        parent_id = parent_ticket["ticket_id"]
+        console.print(f"  ✓ Created Parent Ticket: [cyan]{parent_id}[/cyan] ('{parent_ticket['title']}')")
+        await asyncio.sleep(1)
+
+        # Step 2: Orchestrator agent picks up ticket & moves to In Progress
+        console.print("\n[bold yellow][Step 2] Orchestrator analyzes requirements & searches capabilities...[/bold yellow]")
+        await client.patch(
+            f"/tickets/{parent_id}/move",
+            json={"target_column_id": col_map["in_progress"]},
+            headers={"Authorization": f"Bearer {orch_token}"},
+        )
+        console.print(f"  ✓ Ticket {parent_id} moved to [yellow]In Progress[/yellow] by @agent_orchestrator")
+
+        # Discovery query: find image worker
+        disc_img = (await client.get("/actors/discovery?capability=image-resize")).json()
+        image_agent_id = disc_img[0]["actor_id"]
+        console.print(f"  ✓ Discovered specialist agent for image optimization: [magenta]@{image_agent_id}[/magenta]")
+
+        # Discovery query: find reviewer
+        disc_rev = (await client.get("/actors/discovery?capability=code-review")).json()
+        reviewer_agent_id = disc_rev[0]["actor_id"]
+        console.print(f"  ✓ Discovered specialist agent for review: [magenta]@{reviewer_agent_id}[/magenta]")
+        await asyncio.sleep(1)
+
+        # Step 3: Orchestrator delegates Subtask 1 to Image Worker
+        console.print("\n[bold yellow][Step 3] Orchestrator delegates Subtask 1 to Worker...[/bold yellow]")
+        del1_resp = await client.post(
+            f"/tickets/{parent_id}/delegate",
+            json={
+                "target_actor_id": image_agent_id,
+                "subtask_title": "Implement WebP Converter Routine",
+                "subtask_description": "Convert raw PNG/JPEG buffer to 200x200 WebP with 85% quality factor.",
+                "priority": "high",
+                "labels": ["worker", "webp"],
+            },
+            headers={"Authorization": f"Bearer {orch_token}"},
+        )
+        sub1 = del1_resp.json()
+        sub1_id = sub1["ticket_id"]
+        console.print(f"  ✓ Subtask [cyan]{sub1_id}[/cyan] delegated to [magenta]@{image_agent_id}[/magenta]")
+        await asyncio.sleep(1)
+
+        # Step 4: Worker processes Subtask 1
+        console.print("\n[bold yellow][Step 4] Image Worker processes Subtask 1...[/bold yellow]")
+        await client.patch(
+            f"/tickets/{sub1_id}/move",
+            json={"target_column_id": col_map["in_progress"]},
+            headers={"Authorization": f"Bearer {worker_token}"},
+        )
+        console.print(f"  ✓ {sub1_id} status ➔ [yellow]In Progress[/yellow]")
+
+        await client.post(
+            f"/tickets/{sub1_id}/comments",
+            json={
+                "content": "Generated PIL image transform logic; benchmarked at 12ms per 1024x1024 input.",
+                "is_internal": True,
+                "metadata": {"execution_time_ms": 12, "compression_ratio": "78%"},
+            },
+            headers={"Authorization": f"Bearer {worker_token}"},
+        )
+
+        await client.patch(
+            f"/tickets/{sub1_id}/move",
+            json={"target_column_id": col_map["done"]},
+            headers={"Authorization": f"Bearer {worker_token}"},
+        )
+        console.print(f"  ✓ {sub1_id} status ➔ [green]Done[/green] with artifact context")
+        await asyncio.sleep(1)
+
+        # Step 5: Orchestrator delegates Subtask 2 to Code Reviewer
+        console.print("\n[bold yellow][Step 5] Orchestrator delegates Subtask 2 for Review...[/bold yellow]")
+        del2_resp = await client.post(
+            f"/tickets/{parent_id}/delegate",
+            json={
+                "target_actor_id": reviewer_agent_id,
+                "subtask_title": "Security & Boundary Review for WebP Converter",
+                "subtask_description": "Audit buffer overflow checks and decompression bomb protection.",
+                "priority": "urgent",
+                "labels": ["security", "audit"],
+            },
+            headers={"Authorization": f"Bearer {orch_token}"},
+        )
+        sub2 = del2_resp.json()
+        sub2_id = sub2["ticket_id"]
+        console.print(f"  ✓ Subtask [cyan]{sub2_id}[/cyan] delegated to [magenta]@{reviewer_agent_id}[/magenta]")
+        await asyncio.sleep(1)
+
+        # Step 6: Code Reviewer processes Subtask 2
+        console.print("\n[bold yellow][Step 6] Code Reviewer audits implementation...[/bold yellow]")
+        await client.patch(
+            f"/tickets/{sub2_id}/move",
+            json={"target_column_id": col_map["in_progress"]},
+            headers={"Authorization": f"Bearer {reviewer_token}"},
+        )
+
+        await client.post(
+            f"/tickets/{sub2_id}/comments",
+            json={
+                "content": "LGTM! Input pixel limit set to 4096 to prevent memory denial-of-service. Approved.",
+                "is_internal": False,
+                "metadata": {"approved": True, "cve_checked": ["CVE-2023-4863"]},
+            },
+            headers={"Authorization": f"Bearer {reviewer_token}"},
+        )
+
+        await client.patch(
+            f"/tickets/{sub2_id}/move",
+            json={"target_column_id": col_map["done"]},
+            headers={"Authorization": f"Bearer {reviewer_token}"},
+        )
+        console.print(f"  ✓ {sub2_id} status ➔ [green]Done[/green]")
+        await asyncio.sleep(1)
+
+        # Step 7: Orchestrator closes Parent Ticket
+        console.print("\n[bold yellow][Step 7] Orchestrator closes Parent Ticket...[/bold yellow]")
+        final_check = (await client.get(f"/tickets/{parent_id}")).json()
+        console.print(f"  Subtasks completion status: [green]{final_check['subtask_done_count']}/{final_check['subtask_count']} Done[/green]")
+
+        await client.patch(
+            f"/tickets/{parent_id}/move",
+            json={"target_column_id": col_map["done"]},
+            headers={"Authorization": f"Bearer {orch_token}"},
+        )
+        await client.post(
+            f"/tickets/{parent_id}/comments",
+            json={
+                "content": "All subtasks (implementation + security review) successfully completed. Closing ticket.",
+                "is_internal": False,
+            },
+            headers={"Authorization": f"Bearer {orch_token}"},
+        )
+        console.print(f"  ✓ Master Ticket [cyan]{parent_id}[/cyan] successfully resolved and moved to [green]Done[/green]!")
+
+        console.print(Panel.fit(
+            "[bold green]🎉 E2E Collaboration Simulation Completed Successfully![/bold green]\n"
+            f"View live board: [cyan]ak5 board --board-id {board_id}[/cyan]",
+            border_style="green",
+        ))
+
+
+@click.command("demo")
+def demo_command() -> None:
+    """Run automated autonomous multi-agent collaboration demonstration."""
+    api_url = get_api_url()
+    try:
+        asyncio.run(run_collaboration_simulation(api_url))
+    except httpx.ConnectError:
+        console.print(f"[bold red]✗ Cannot connect to AK5 Gateway at {api_url}[/bold red]")
+        console.print("Please start the backend server in another terminal:\n  [yellow]uv run uvicorn ak5.main:app[/yellow]")
+    except Exception as e:
+        console.print(f"[bold red]✗ Simulation failed:[/bold red] {e}")

ak5/cli/commands/login.py

@@ -0,0 +1,47 @@
+import click
+import httpx
+from ak5.cli.config import get_api_url, save_session
+from rich.console import Console
+
+console = Console()
+
+
+@click.command("login")
+@click.option("--id", "actor_id", required=True, help="Actor ID (e.g. agent-code-reviewer, user_pm)")
+@click.option("--role", required=True, help="Display role (e.g. 'Senior Reviewer', 'PM')")
+@click.option("--caps", default="", help="Comma-separated capabilities (e.g. 'python,rust,security')")
+@click.option("--type", "actor_type", type=click.Choice(["human", "agent"]), default="agent", help="Actor type")
+@click.option("--url", default=None, help="AK5 Gateway API URL")
+def login_command(actor_id: str, role: str, caps: str, actor_type: str, url: str | None) -> None:
+    """Identify and authenticate as an Actor (Human or AI Agent)."""
+    api_url = url or get_api_url()
+    capabilities = [c.strip() for c in caps.split(",") if c.strip()]
+
+    payload = {
+        "actor_id": actor_id,
+        "actor_type": actor_type,
+        "name": actor_id.replace("-", " ").replace("_", " ").title(),
+        "role": role,
+        "capabilities": capabilities,
+    }
+
+    try:
+        with httpx.Client(timeout=10.0) as client:
+            resp = client.post(f"{api_url}/auth/identify", json=payload)
+            resp.raise_for_status()
+            data = resp.json()
+
+        token = data["access_token"]
+        save_session({
+            "token": token,
+            "actor_id": actor_id,
+            "actor_type": actor_type,
+            "role": role,
+            "api_url": api_url,
+        })
+        console.print(f"[bold green]✓[/bold green] Authenticated as [cyan]{actor_id}[/cyan] [{actor_type}]")
+    except httpx.ConnectError:
+        console.print(f"[bold red]✗ Failed to connect to AK5 Gateway at {api_url}[/bold red]")
+        console.print("Make sure the backend server is running: [yellow]uvicorn ak5.main:app[/yellow]")
+    except Exception as e:
+        console.print(f"[bold red]✗ Login failed:[/bold red] {e}")

ak5/cli/commands/mcp.py

@@ -0,0 +1,8 @@
+import click
+
+
+@click.command("mcp")
+def mcp_command() -> None:
+    """Run the AK5 MCP Server in Stdio mode for Claude Desktop, Cursor, or agent harnesses."""
+    from ak5.mcp.server import main as run_mcp
+    run_mcp()

ak5/cli/commands/serve.py

@@ -0,0 +1,18 @@
+import click
+import uvicorn
+from rich.console import Console
+
+console = Console()
+
+
+@click.command("serve")
+@click.option("--host", default="127.0.0.1", help="Host interface to bind")
+@click.option("--port", default=8000, type=int, help="Port to bind")
+@click.option("--reload", is_flag=True, help="Enable auto-reload for development")
+def serve_command(host: str, port: int, reload: bool) -> None:
+    """Start the AK5 Gateway REST API & Embedded MCP Server."""
+    console.print(f"[bold cyan]🚀 Starting AK5 Gateway on http://{host}:{port}...[/bold cyan]")
+    console.print(f"  - REST API & Swagger: [link=http://{host}:{port}/docs]http://{host}:{port}/docs[/link]")
+    console.print(f"  - Embedded MCP SSE:   [link=http://{host}:{port}/mcp/sse]http://{host}:{port}/mcp/sse[/link]")
+    console.print(f"  - SSE Real-time Bus:  [link=http://{host}:{port}/api/v1/events/stream]http://{host}:{port}/api/v1/events/stream[/link]\n")
+    uvicorn.run("ak5.main:app", host=host, port=port, reload=reload)

ak5/cli/config.py

@@ -0,0 +1,35 @@
+import json
+from pathlib import Path
+from typing import Any
+
+SESSION_FILE = Path.home() / ".ak5_session.json"
+DEFAULT_API_URL = "http://127.0.0.1:8000/api/v1"
+
+
+def load_session() -> dict[str, Any]:
+    if SESSION_FILE.exists():
+        try:
+            with open(SESSION_FILE, encoding="utf-8") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, OSError):
+            return {}
+    return {}
+
+
+def save_session(data: dict[str, Any]) -> None:
+    session = load_session()
+    session.update(data)
+    with open(SESSION_FILE, "w", encoding="utf-8") as f:
+        json.dump(session, f, indent=2)
+
+
+def get_token() -> str | None:
+    return load_session().get("token")
+
+
+def get_actor_id() -> str | None:
+    return load_session().get("actor_id")
+
+
+def get_api_url() -> str:
+    return load_session().get("api_url", DEFAULT_API_URL)

ak5/cli/main.py

@@ -0,0 +1,31 @@
+import click
+from rich.console import Console
+
+from ak5.cli.commands.agents import agents_command
+from ak5.cli.commands.board import board_command
+from ak5.cli.commands.delegate import delegate_command
+from ak5.cli.commands.demo import demo_command
+from ak5.cli.commands.login import login_command
+from ak5.cli.commands.mcp import mcp_command
+from ak5.cli.commands.serve import serve_command
+
+console = Console()
+
+
+@click.group()
+@click.version_option(version="1.0.0", prog_name="ak5")
+def cli():
+    """AK5 (Agent K5) - Agent-Orchestrated Kanban Command Line Interface."""
+
+
+cli.add_command(serve_command)
+cli.add_command(mcp_command)
+cli.add_command(board_command)
+cli.add_command(agents_command)
+cli.add_command(delegate_command)
+cli.add_command(demo_command)
+cli.add_command(login_command)
+
+
+if __name__ == "__main__":
+    cli()

ak5/config.py

@@ -0,0 +1,29 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    PROJECT_NAME: str = "AK5"
+    VERSION: str = "1.0.0"
+    API_V1_STR: str = "/api/v1"
+
+    DATABASE_URL: str = "sqlite+aiosqlite:///./ak5.db"
+    SQLITE_BUSY_TIMEOUT: int = 5000
+
+    JWT_SECRET: str = "ak5-dev-secret-key-change-in-production-2026"
+    JWT_ALGORITHM: str = "HS256"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 60 * 24 * 7  # 7 days
+
+    DEFAULT_BOARD_ID: str = "proj-core-engine"
+    DEFAULT_BOARD_NAME: str = "Core Engine Project"
+
+    CORS_ORIGINS: list[str] = [
+        "http://localhost:3000",
+        "http://127.0.0.1:3000",
+        "http://localhost:8000",
+        "http://127.0.0.1:8000",
+    ]
+
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8", extra="ignore")
+
+
+settings = Settings()