ltcai 1.7.0 → 2.0.0

package/README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <img src="https://raw.githubusercontent.com/TaeSooPark-PTS/LatticeAI/main/docs/images/logo.svg" alt="Lattice AI" width="280"/>
   <br/>
-  <strong>AI Workspace OS for local-first graph, memory, agents, workflows, skills, and timelines.</strong>
+  <strong>Lattice AI — Local-first Agentic Workspace Platform: plugins, visual workflows, multi-agent runs, and realtime activity over your graph, memory, skills, and timeline.</strong>
   <br/><br/>
 
 [![PyPI](https://img.shields.io/pypi/v/ltcai?label=PyPI&color=blue)](https://pypi.org/project/ltcai/)
@@ -24,7 +24,7 @@
 
 Most AI tools answer one chat at a time. They do not remember your folders, your project history, your previous decisions, or how your files relate to each other.
 
-**Lattice AI turns your local workspace into an AI Workspace OS.**
+**Lattice AI turns your local workspace into a Local-first Agentic Workspace Platform.**
 
 It reads approved local folders, indexes chats and documents, builds a searchable knowledge graph, and connects the graph to snapshots, personal memory, agent runs, workflow history, skills, and an auditable timeline.
 
@@ -156,7 +156,7 @@ See [docs/architecture.md](docs/architecture.md) for request and data-flow detai
 </table>
 
 > Every image in this section is a **real screenshot** of the running app
-> (Lattice AI v1.7.0), captured with a headless browser.
+> (Lattice AI v2.0.0), captured with a headless browser.
 
 ---
 
@@ -353,28 +353,38 @@ Supported routes include OpenAI-compatible APIs, OpenRouter, Groq, Together, xAI
 
 ## Current release
 
-**1.7.0 — Graph & Collaboration Release.** An additive UI and validation release
-for graph exploration, workspace health, Enterprise admin visibility, skills,
-screenshots, and visual smoke coverage.
-
-- **Graph Canvas** — expand/collapse, subgraph focus, relationship/path
-  highlighting, shortest-path visualization, and click-through node navigation.
-- **Workspace Health** — indexed files, graph nodes/relationships, installed
-  skills, memories, agent runs, current model, last sync, and workspace status.
-- **Enterprise Admin UI** — admin policies, audit export, SIEM export preview,
-  organization settings, and capability status surfaced in `/admin`.
-- **Skill Marketplace completion** — install progress, validation status,
-  recommended/popular skills, updates, version, and source metadata.
-- **Screenshot automation + visual smoke tests** — `scripts/capture/*` and a
-  scheduled Playwright workflow cover Workspace, Graph, Skills, Organization,
-  and Enterprise screens.
+**2.0.0 — Agentic Workspace Platform.** Lattice AI graduates from a local-first
+AI *workspace* to a local-first **Agentic Workspace Platform**: four new
+subsystems land as one cohesive, fully integrated platform — all additive, with
+every v1.x surface preserved.
+
+- **Plugin SDK** — versioned, permissioned plugins (`plugin.json` manifest,
+  allow-listed permissions, lifecycle, validation, and a safe execution
+  boundary) that **extend** existing skills/tools/workflows rather than replace
+  them. Ships two example plugins. See [docs/PLUGIN_SDK.md](docs/PLUGIN_SDK.md).
+- **Workflow Designer** — node-based workflows (trigger · tool · skill · plugin ·
+  agent · condition · output) with validation, execution, run history, and
+  export/import. Pre-2.0 workflow history keeps working.
+  See [docs/WORKFLOW_DESIGNER.md](docs/WORKFLOW_DESIGNER.md).
+- **Multi-Agent Runtime 2.0** — Planner · Executor · Reviewer · Researcher ·
+  Release roles with handoff, retry, and an observable timeline, connected to
+  workspace, memory, graph, and workflow runs.
+  See [docs/MULTI_AGENT_RUNTIME.md](docs/MULTI_AGENT_RUNTIME.md).
+- **Realtime Collaboration** — presence + an activity feed over SSE, fed
+  automatically from every workspace timeline event; single-user local mode and
+  workspace isolation preserved. See [docs/REALTIME_COLLABORATION.md](docs/REALTIME_COLLABORATION.md).
+- **Cross-system integration** — workflows run plugins/skills/agents, agent runs
+  run plugins/workflows, and all activity surfaces in the realtime feed, the
+  knowledge graph, and the workspace timeline. See [docs/V2_ARCHITECTURE.md](docs/V2_ARCHITECTURE.md).
 - **Compatibility preserved** — API schemas, `server:app`,
-  `latticeai.server_app.app`, CLI, MCP, model, workspace, chat, KG, and VS Code
-  extension surfaces remain backward compatible.
+  `latticeai.server_app.app`, CLI, MCP, model, workspace, chat, KG, existing
+  skills/snapshots/memories/agent history, and the VS Code extension remain
+  backward compatible. Changes are additive; no destructive migrations.
 
 | Version | Theme |
 |---|---|
-| **1.7.0** | Graph & Collaboration Release |
+| **2.0.0** | Agentic Workspace Platform (Plugin SDK, Workflow Designer, Multi-Agent Runtime, Realtime) |
+| 1.7.0 | Graph & Collaboration Release |
 | 1.6.0 | Product Experience Deepening (UX + real screenshots) |
 | 1.5.0 | Unified Product Release (CI/VSIX recovery, model recommendation, Enterprise PoC) |
 | 1.4.0 | Server App final decomposition |

package/docs/CHANGELOG.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## [2.0.0] - 2026-06-01
+
+> Agentic Workspace Platform — Lattice AI becomes a local-first **Agentic
+> Workspace Platform** with four integrated subsystems: Plugin SDK, Workflow
+> Designer, Multi-Agent Runtime 2.0, and Realtime Collaboration. Backward
+> compatible and additive: API paths/schemas, `server:app`,
+> `latticeai.server_app.app`, CLI, Workspace/Chat/Model/MCP/KG APIs, existing
+> skills/snapshots/memories/agent & workflow history, and VS Code extension
+> commands remain stable. New Workspace OS state keys (`plugin_registry`,
+> `workflow_runs`) are backfilled on load via deep-merge — no destructive
+> migration.
+
+### Added
+
+- **Plugin SDK** (`latticeai/core/plugins.py`, `latticeai/api/plugins.py`) —
+  `plugin.json` manifest, an allow-listed permission model, discovery,
+  validation, lifecycle (install/enable/disable/uninstall), and a permissioned
+  execution boundary. Plugins **extend** the existing skill registry (installing
+  a plugin registers its bundled skills) rather than replacing skills. Ships two
+  example plugins (`plugins/hello-world`, `plugins/git-insights`). Routes under
+  `/plugins/registry`, `/plugins/validate`, `/plugins/install`, `/plugins/enable`,
+  `/plugins/disable`, `/plugins/uninstall`, `/plugins/execute`, page `/plugins/sdk`.
+- **Workflow Designer** (`latticeai/core/workflow_engine.py`,
+  `latticeai/api/workflow_designer.py`) — node-based workflows
+  (trigger/tool/skill/plugin/agent/condition/output), validation, a bounded
+  deterministic execution engine, run history, and JSON export/import. Legacy
+  `steps`-list workflows are auto-normalized so pre-2.0 history still runs.
+  Routes under `/workflows/api/*`, page `/workflows`.
+- **Multi-Agent Runtime 2.0** (`latticeai/core/multi_agent.py`,
+  `latticeai/api/agents.py`) — Planner/Executor/Reviewer/Researcher/Release role
+  orchestration with handoff, bounded retry, and an observable timeline; runs
+  persist to agent history + knowledge graph + timeline. Deterministic by
+  default (no LLM required) with an injectable role runner. Routes under
+  `/agents/api/*`, page `/agents`.
+- **Realtime Collaboration** (`latticeai/core/realtime.py`,
+  `latticeai/api/realtime.py`) — in-process pub/sub bus, presence, and an
+  activity feed over SSE. Wired as the Workspace OS `event_sink`, so every
+  timeline event flows to the feed automatically. Workspace isolation enforced;
+  single-user local mode preserved. Routes `/realtime/stream` (SSE),
+  `/realtime/feed`, `/realtime/presence*`, page `/activity`.
+- **Cross-system integration** (`latticeai/services/platform_runtime.py`) —
+  workflows can run tools/skills/plugins/agents; agent runs can run
+  plugins/workflows; graph entities link to workflow runs and agent runs; all
+  activity surfaces in the unified timeline + realtime feed. Recursion is bounded
+  by construction.
+- **Platform UI** — `static/plugins.html`, `workflows.html`, `agents.html`,
+  `activity.html` (+ shared `static/platform.css`, `static/scripts/platform.js`),
+  linked from the Workspace dashboard.
+- **Docs** — `docs/V2_ARCHITECTURE.md`, `docs/PLUGIN_SDK.md`,
+  `docs/WORKFLOW_DESIGNER.md`, `docs/MULTI_AGENT_RUNTIME.md`,
+  `docs/REALTIME_COLLABORATION.md`.
+
+### Changed
+
+- Python package, npm package, VS Code extension, Workspace OS, FastAPI app, and
+  `/health` version metadata aligned at `2.0.0`.
+- `server_app` cross-system wiring extracted into
+  `latticeai/services/platform_runtime.py` to keep the assembly file lean.
+
+### Validation
+
+- Unit (incl. new plugin/workflow/multi-agent/realtime suites), integration
+  smoke, startup/import, route-compatibility (full v1.x baseline preserved),
+  and release-artifact checks. Package-store publishing remains manual.
+
 ## [1.7.0] - 2026-06-01
 
 > Graph & Collaboration Release — Graph Canvas interactions, Enterprise Admin

package/docs/EDITION_STRATEGY.md

@@ -5,10 +5,12 @@ the boundary stays predictable for contributors and users.
 
 ## Editions
 
-- **Community** — this repository, MIT licensed. Local-first AI Workspace OS:
-  local LLMs, knowledge graph, Personal **and** Organization workspaces,
-  role-based membership, snapshots, memory, agents, workflows, skills, and the
-  auditable timeline. Community is a complete product.
+- **Community** — this repository, MIT licensed. Local-first **Agentic Workspace
+  Platform**: local LLMs, knowledge graph, Personal **and** Organization
+  workspaces, role-based membership, snapshots, memory, agents, workflows,
+  skills, the auditable timeline, and the full v2.0 platform — **Plugin SDK**,
+  **Workflow Designer**, **Multi-Agent Runtime 2.0**, and **Realtime
+  Collaboration**. Community is a complete product.
 - **Enterprise** — a separately-distributed plugin adding organization-scale
   governance, identity, compliance, and deployment capabilities. Distributed and
   licensed separately. See [ENTERPRISE.md](ENTERPRISE.md).
@@ -39,6 +41,10 @@ the boundary stays predictable for contributors and users.
 | Personal & Organization workspaces | ✅ | — |
 | Base roles (owner/admin/member/viewer) | ✅ | — |
 | Snapshots / memory / agents / workflows / skills | ✅ | — |
+| Plugin SDK (manifest, lifecycle, permission boundary) | ✅ | RBAC/ABAC over plugin permissions |
+| Workflow Designer (build/run/run-history) | ✅ | Org approval gates, scheduled triggers |
+| Multi-Agent Runtime 2.0 (roles/handoff/retry) | ✅ | Policy-bounded autonomous runs |
+| Realtime Collaboration (presence + activity feed) | ✅ | Cross-tenant fan-out, retention |
 | Audit timeline (local) | ✅ | — |
 | Capability seam & enum | ✅ (declares) | ✅ (implements) |
 | SSO/SCIM/IdP provisioning | seam only | ✅ |

package/docs/ENTERPRISE.md

@@ -9,7 +9,9 @@ Lattice AI follows an **open-core** model:
 
 - **Community** (this repository, MIT) is fully functional on its own: local
   LLMs, knowledge graph, Personal and Organization workspaces, roles, snapshots,
-  memory, agents, workflows, skills, and the auditable timeline.
+  memory, agents, workflows, skills, the auditable timeline, and the full v2.0
+  Agentic Workspace Platform (Plugin SDK, Workflow Designer, Multi-Agent Runtime
+  2.0, Realtime Collaboration).
 - **Enterprise** is a separately-distributed plugin that attaches advanced,
   organization-scale governance and deployment capabilities through a stable
   runtime seam. It is never bundled into the Community build.

package/docs/MULTI_AGENT_RUNTIME.md

@@ -0,0 +1,410 @@
+# Lattice AI Multi-Agent Runtime 2.0
+
+The Multi-Agent Runtime is the **orchestration layer** introduced in v2.0.0. It sits
+*above* the v1.x single-agent state machine ([`AgentRuntime`](../latticeai/core/agent.py))
+and coordinates a pipeline of named **roles** that hand off work to one another,
+retry on a failing review, and emit a fully observable timeline.
+
+- **Source of truth:** `latticeai/core/multi_agent.py`
+- **HTTP surface:** `latticeai/api/agents.py`
+- **Persistence / Knowledge Graph integration:** `latticeai/core/workspace_os.py`
+  (`WorkspaceOSStore.record_agent_run`)
+
+```python
+MULTI_AGENT_VERSION = "2.0.0"
+```
+
+## How it relates to the v1 single-agent runtime
+
+v1.x shipped a single-agent state machine — `AgentRuntime` driving
+`PLAN → EXECUTE → VERIFY → DONE` (with `ROLLBACK` / `FAILED` recovery paths) over an
+injected `AgentDeps` port. That runtime is unchanged.
+
+v2.0 adds the *orchestration* layer on top: instead of one agent looping through
+internal phases, the `MultiAgentOrchestrator` drives a **pipeline of distinct roles**
+(researcher, planner, executor, reviewer, release) that hand off to one another and
+can rewind on a failing review. The two layers are complementary — the v2
+orchestrator coordinates roles; an individual role's runner could itself be backed by
+the v1 `AgentRuntime` loop or an LLM, but that is an implementation choice behind the
+injected runner port.
+
+> **Compatibility.** The Multi-Agent Runtime is purely additive. The v1
+> `AgentRuntime` state machine and its `/agent` endpoints are untouched, and the v2
+> API is namespaced under `/agents` (plural) so it never collides with the existing
+> single-agent `/agent` routes. Existing v1.x data is preserved; new runs are appended
+> to workspace state and the Knowledge Graph alongside it.
+
+## Built-in roles (`AGENT_ROLES`)
+
+The runtime defines five built-in roles. Each role id matches an entry in
+`latticeai.core.workspace_os.DEFAULT_AGENTS`, so orchestrated runs reference the same
+agents that already appear in the Workspace.
+
+```python
+AGENT_ROLES = ("researcher", "planner", "executor", "reviewer", "release")
+
+ROLE_AGENT_IDS = {
+    "researcher": "agent:researcher",
+    "planner":    "agent:planner",
+    "executor":   "agent:executor",
+    "reviewer":   "agent:reviewer",
+    "release":    "agent:release",
+}
+```
+
+| Role | Agent id | Responsibility |
+| --- | --- | --- |
+| `researcher` | `agent:researcher` | Gathers relevant context (workspace memory / graph) via an injected `context_provider`. |
+| `planner` | `agent:planner` | Decomposes the goal into ordered, inspectable steps. |
+| `executor` | `agent:executor` | Carries out steps; may drive an injected workflow / plugin runner. |
+| `reviewer` | `agent:reviewer` | Judges the result and returns a `pass` / `retry` verdict. |
+| `release` | `agent:release` | Finalizes / packages the outcome (optional). |
+
+The `agent:*` ids correspond one-to-one with `DEFAULT_AGENTS` in `workspace_os`
+(`agent:planner`, `agent:executor`, `agent:reviewer`, `agent:researcher`,
+`agent:release`), which is why an orchestrated run can record relationships against
+agents that the Workspace already knows about.
+
+### The core pipeline
+
+`researcher` and `release` are optional stages — they run only when explicitly
+requested. A quick, default run is therefore three stages:
+
+```python
+CORE_PIPELINE = ("planner", "executor", "reviewer")
+```
+
+When `MultiAgentOrchestrator.run(...)` is called without an explicit `roles` list, it
+uses `CORE_PIPELINE`. Any roles passed in are filtered to the set of known
+`AGENT_ROLES`; if nothing valid remains, it falls back to `CORE_PIPELINE`.
+
+## Orchestration: `MultiAgentOrchestrator.run`
+
+```python
+def run(
+    self,
+    goal: str,
+    *,
+    user_email: Optional[str] = None,
+    workspace_id: Optional[str] = None,
+    inputs: Optional[Dict[str, Any]] = None,
+    roles: Optional[List[str]] = None,
+    max_retries: int = 2,
+) -> AgentRunResult:
+    ...
+```
+
+`run` walks the resolved pipeline, threading a single `OrchestrationContext` through
+every stage. As it goes it appends two kinds of events to an observable timeline:
+
+- **`role` events** — emitted by `_run_role` for each stage, recording the role, its
+  `agent_id`, status (`ok` / `error`), the raw runner result, and start/end timestamps.
+- **`handoff` events** — emitted via `OrchestrationContext.handoff(frm, to, note)`
+  whenever control passes from one role to the next (and on a retry rewind).
+
+The timeline is also bracketed by a `start` event (carrying the goal and resolved
+pipeline) and an `end` event (carrying the final status and retry count).
+
+### Retry: reviewer rewinds to executor
+
+The pipeline is ordinarily linear, but the **reviewer can rewind** the pipeline to the
+executor. After the reviewer runs, if its verdict is `retry` and the retry budget is
+not yet exhausted, the orchestrator:
+
+1. increments `ctx.retries`,
+2. emits a `handoff("reviewer", "executor", note="retry #N: <reason>")`,
+3. resets the pipeline index back to the executor stage, and
+4. re-runs executor → reviewer.
+
+This repeats until the verdict is `pass` or `ctx.retries` reaches `max_retries`.
+
+```text
+planner → executor → reviewer ──pass──▶ (continue / end)
+                        │
+                        └──retry (and retries < max_retries)──▶ executor (rewind)
+```
+
+### Final status
+
+The terminal status is derived from the final reviewer verdict and retry count:
+
+| Condition | `status` |
+| --- | --- |
+| Final verdict `pass`, no retries | `ok` |
+| Final verdict `pass`, after one or more retries | `retried_ok` |
+| Final verdict not `pass` (retries exhausted) | `failed` |
+
+### `OrchestrationContext`
+
+The mutable carrier threaded through every stage:
+
+```python
+@dataclass
+class OrchestrationContext:
+    goal: str
+    user_email: Optional[str] = None
+    workspace_id: Optional[str] = None
+    inputs: Dict[str, Any] = field(default_factory=dict)
+    plan: List[Dict[str, Any]] = field(default_factory=list)
+    research: List[str] = field(default_factory=list)
+    executed: List[Dict[str, Any]] = field(default_factory=list)
+    review: Dict[str, Any] = field(default_factory=dict)
+    timeline: List[Dict[str, Any]] = field(default_factory=list)
+    retries: int = 0
+    output: str = ""
+
+    def handoff(self, frm: str, to: str, note: str = "") -> None: ...
+```
+
+### `AgentRunResult`
+
+`run` returns an `AgentRunResult`, which exposes `as_dict()` for serialization:
+
+```python
+@dataclass
+class AgentRunResult:
+    agent_id: str
+    status: str  # ok | failed | retried_ok
+    output: str
+    timeline: List[Dict[str, Any]]
+    plan: List[Dict[str, Any]]
+    review: Dict[str, Any]
+    roles_run: List[str]
+    retries: int = 0
+```
+
+## The role runner is an injected port
+
+Like the v1 runtime, the orchestrator is **pure logic over an injected `role_runner`
+port**. It runs with no LLM and no server:
+
+```python
+class MultiAgentOrchestrator:
+    def __init__(
+        self,
+        role_runner: Optional[Callable[[str, OrchestrationContext], Dict[str, Any]]] = None,
+    ):
+        self.role_runner = role_runner or default_role_runner()
+```
+
+The runner is a single callable `(role: str, ctx: OrchestrationContext) -> Dict[str, Any]`.
+The orchestration logic — pipeline walking, handoffs, retry rewind, timeline emission,
+status derivation — does not depend on *how* a role does its work. This means a
+**production deployment can swap in an LLM-backed runner without touching the
+orchestration layer**: implement the same callable signature, pass it to the
+constructor, and the pipeline behaves identically while individual roles gain
+model-backed reasoning.
+
+If a runner raises, `_run_role` captures the exception into the `role` event as
+`status: "error"` with an `{"error": ...}` result, rather than crashing the run.
+
+## The default runner is deterministic and useful
+
+`default_role_runner` builds a **dependency-free, deterministic** runner that
+implements every built-in role with real (non-LLM) behavior. This is what makes
+"agent runs can execute workflows / plugins" true in the community edition without
+requiring a model.
+
+```python
+def default_role_runner(
+    *,
+    workflow_runner: Optional[Callable[..., Any]] = None,
+    plugin_runner: Optional[Callable[..., Any]] = None,
+    context_provider: Optional[Callable[[str], List[str]]] = None,
+) -> Callable[[str, OrchestrationContext], Dict[str, Any]]:
+    ...
+```
+
+Behavior by role:
+
+- **`researcher`** — calls the injected `context_provider(goal)` (workspace memory) to
+  pull relevant context into `ctx.research`; returns the count and the first items.
+- **`planner`** — decomposes the goal into ordered steps. If `inputs["steps"]` is a
+  non-empty list, each entry becomes a planned step; otherwise it produces a default
+  three-step plan (`Analyze` / `Execute` / `Verify the result`). Steps are written to
+  `ctx.plan`.
+- **`executor`** — iterates the plan and marks each step `done`. A step may request a
+  workflow or plugin run; when the corresponding runner is injected, the executor
+  drives it (see below). Results are written to `ctx.executed` and a summary line to
+  `ctx.output`.
+- **`reviewer`** — passes only if `ctx.executed` is non-empty and *every* executed step
+  has `status == "done"`; otherwise it returns `retry`. The verdict shape is:
+
+  ```json
+  {
+    "verdict": "pass",
+    "reason": "all steps completed",
+    "confidence": 0.9
+  }
+  ```
+
+  A failing review yields `{"verdict": "retry", "reason": "no steps executed", "confidence": 0.3}`.
+- **`release`** — sets/keeps `ctx.output` and returns `{"released": true, "summary": ...}`.
+
+An unrecognized role returns `{"role": role, "status": "noop"}`.
+
+### Agent → workflow and agent → plugin integration
+
+The executor role is where Lattice's cross-feature integration happens. When the
+`default_role_runner` is built with a `workflow_runner` and/or `plugin_runner`, a plan
+step can drive them:
+
+- A step's `workflow` (or `inputs["workflow"]`) is run via `workflow_runner(wf, ctx)`
+  on the first step (`index == 0`), capturing the result under `workflow_result` (or
+  `workflow_error` on failure).
+- A step's `plugin` is run via `plugin_runner(pl, ctx)`, capturing `plugin_result` (or
+  `plugin_error`).
+
+This is the **agent → workflow** and **agent → plugin** seam: an orchestrated agent run
+can actually execute Workflows and Plugins, in the community edition, with no model
+required.
+
+## Persistence and Knowledge Graph
+
+After a run completes, the API persists it via
+`WorkspaceOSStore.record_agent_run`, which both ingests a Knowledge Graph node and
+records a Workspace timeline event:
+
+```python
+def record_agent_run(
+    self,
+    *,
+    agent_id: str,
+    status: str,
+    input_text: str,
+    output_text: str,
+    user_email: Optional[str],
+    timeline: Optional[List[Dict[str, Any]]] = None,
+    relationships: Optional[List[str]] = None,
+    graph: Any = None,
+    workspace_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    ...
+```
+
+What it does:
+
+- Builds a run record (`id`, `agent_id`, `status`, `input`, `output_preview` truncated
+  to 1000 chars, `user_email`, scoped `workspace_id`, `relationships`, `timeline`,
+  `created_at`).
+- When a `graph` is supplied, calls `graph.ingest_event("AgentRun", ...)` and stores the
+  returned `graph_node_id` on the run (capturing `graph_error` if ingest fails).
+- Appends the run to workspace state (retaining the most recent 300) and records an
+  `agent` / `agent_run` timeline event.
+
+Runs are workspace-scoped; `list_agents(workspace_id=...)` returns the registered
+`agents` plus the most recent runs for that scope.
+
+## HTTP API
+
+The router is created by `create_agents_router(...)` in `latticeai/api/agents.py`. All
+paths live under `/agents` (plural).
+
+> **Compatibility.** `/agents` does **not** collide with the existing single-agent
+> `/agent` endpoints — the trailing `s` keeps the v2 namespace fully separate, so v1
+> clients continue to work unchanged.
+
+### `GET /agents` — UI page
+
+Requires an authenticated user. Serves the `agents.html` Multi-Agent UI from the static
+directory; returns `404` if the UI is not available or not found.
+
+### `GET /agents/api/roles`
+
+Requires an authenticated user. Lists the built-in roles and the default pipeline.
+
+```json
+{
+  "roles": [
+    {"role": "researcher", "agent_id": "agent:researcher"},
+    {"role": "planner",    "agent_id": "agent:planner"},
+    {"role": "executor",   "agent_id": "agent:executor"},
+    {"role": "reviewer",   "agent_id": "agent:reviewer"},
+    {"role": "release",    "agent_id": "agent:release"}
+  ],
+  "default_pipeline": ["planner", "executor", "reviewer"]
+}
+```
+
+### `GET /agents/api/runs`
+
+Requires an authenticated user; reads are scoped via `gate_read`. Returns the registered
+agents plus recent runs for the resolved workspace scope (the result of
+`store.list_agents(workspace_id=scope)`).
+
+```json
+{
+  "agents": [ { "id": "agent:planner", "name": "Planner", "...": "..." } ],
+  "runs":   [ { "id": "agent-run-...", "agent_id": "agent:executor", "status": "ok", "...": "..." } ]
+}
+```
+
+### `POST /agents/api/run`
+
+Requires an authenticated user; writes are scoped via `gate_write`. Runs the
+orchestrator and persists the result.
+
+**Request body** (`AgentRunRequest`):
+
+```json
+{
+  "goal": "Summarize the open incidents and draft a status update",
+  "roles": ["researcher", "planner", "executor", "reviewer"],
+  "inputs": { "steps": ["Collect incidents", "Draft update"] },
+  "max_retries": 2
+}
+```
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `goal` | string | — | Required; a `400` is returned if blank. |
+| `roles` | string[] | `[]` | Empty means the default `CORE_PIPELINE`. Unknown roles are filtered out. |
+| `inputs` | object | `{}` | Passed through to the runner (e.g. `steps`, `workflow`). |
+| `max_retries` | int | `2` | Clamped server-side to the range `0`–`5`. |
+
+The endpoint resolves an orchestrator via the injected `orchestrator_factory(user, scope)`,
+runs it, records the run with `store.record_agent_run(...)` (passing the
+`workspace_graph()` for KG ingest and the run's `roles_run` as `relationships`), and
+appends a `multi_agent_run` audit event.
+
+**Response:**
+
+```json
+{
+  "run": {
+    "id": "agent-run-…",
+    "agent_id": "agent:executor",
+    "status": "ok",
+    "input": "Summarize the open incidents and draft a status update",
+    "output_preview": "Completed 2 planned step(s) for: …",
+    "relationships": ["agent:researcher", "agent:planner", "agent:executor", "agent:reviewer"],
+    "timeline": [ { "event": "start", "...": "..." } ],
+    "graph_node_id": "…",
+    "created_at": "…"
+  },
+  "result": {
+    "agent_id": "agent:executor",
+    "status": "ok",
+    "output": "Completed 2 planned step(s) for: …",
+    "timeline": [ "…" ],
+    "plan": [ { "index": 0, "description": "Collect incidents", "status": "done" } ],
+    "review": { "verdict": "pass", "reason": "all steps completed", "confidence": 0.9 },
+    "roles_run": ["researcher", "planner", "executor", "reviewer"],
+    "retries": 0
+  }
+}
+```
+
+## Timeline event reference
+
+The orchestration timeline is a flat, ordered list of event objects. Event types:
+
+| `event` | Emitted by | Key fields |
+| --- | --- | --- |
+| `start` | `run` (before the pipeline) | `goal`, `pipeline`, `timestamp` |
+| `role` | `_run_role` (per stage) | `role`, `agent_id`, `status`, `result`, `started_at`, `timestamp` |
+| `handoff` | `OrchestrationContext.handoff` | `from`, `to`, `note`, `timestamp` |
+| `end` | `run` (after the pipeline) | `status`, `retries`, `timestamp` |
+
+This timeline is returned on the run result and persisted with the run, so it drops
+straight into the Workspace timeline and Knowledge Graph.