ltcai 7.1.0 → 7.3.0

package/README.md

@@ -200,28 +200,33 @@ See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for developer workflow details.
 
 ## Current Release
 
-The current release is **7.1.0 Brain Usability Completion**:
-
-- First-run onboarding now explains detected hardware, recommendation timing,
-  install progress, and the next action in plain language.
-- Brain Home shows ingestion progress for files, folders, notes, and web pages,
-  including memory emergence after content lands.
-- Knowledge Graph exploration adds search suggestions, type filters, time
-  exploration, focus movement, and neighbor highlighting.
-- Chat answers surface inline source citations and accessible proof payloads.
-- Workspace/profile/admin entry points, empty/error feedback, consent revoke
-  feedback, and VS Code extension sync status are visible in the product shell.
-
-Expected artifacts for 7.1.0 release must use exact filenames:
-
-- `dist/ltcai-7.1.0-py3-none-any.whl`
-- `dist/ltcai-7.1.0.tar.gz`
-- `ltcai-7.1.0.tgz`
-- `dist/ltcai-7.1.0.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_7.1.0_aarch64.dmg`
+The current release is **7.3.0 Runtime Contract & Retrieval Quality**:
+
+- Single-agent and multi-agent execution now share a serializable
+  `agent-run-contract/v1` payload for run identity, mode, status, roles,
+  timeline, retries, artifacts, and terminal state.
+- Agent runtime API responses include the shared contract, keeping real and
+  simulated run history distinguishable as runtime extraction continues.
+- Brain quality evaluation now includes deterministic hybrid recall/ranking
+  regression thresholds, not only "some recall exists" checks.
+- The 7.2.0 preview/diagnostics work remains the admin trust surface while
+  7.3.0 tightens the underlying run and retrieval contracts.
+- The roadmap focus is durability over model choice: knowledge, run evidence,
+  and retrieval quality become measurable product assets.
+
+Expected artifacts for 7.3.0 release must use exact filenames:
+
+- `dist/ltcai-7.3.0-py3-none-any.whl`
+- `dist/ltcai-7.3.0.tar.gz`
+- `ltcai-7.3.0.tgz`
+- `dist/ltcai-7.3.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_7.3.0_aarch64.dmg`
 
 Do not upload `dist/*`. Package registry publishing remains owner-run.
 
+See [docs/ROADMAP_RECOMMENDATIONS.md](docs/ROADMAP_RECOMMENDATIONS.md) for the
+strategic roadmap slice applied in 7.3.0 and the follow-up tracks.
+
 ## Known Limitations
 
 - External package registries are owner-published and can lag behind GitHub.
@@ -237,6 +242,8 @@ Do not upload `dist/*`. Package registry publishing remains owner-run.
 
 | Version | Theme |
 | --- | --- |
+| 7.3.0 | Runtime Contract & Retrieval Quality: shared agent-run contract across runtimes plus deterministic hybrid recall/ranking regression gates |
+| 7.2.0 | Runtime Trust Baseline: agent run preview/readiness, simulation-mode guardrails, live ToolRegistry manifest/diagnostics, and tests for dispatch/governance/catalog drift |
 | 7.1.0 | Brain Usability Completion: clearer first-run onboarding, ingestion progress/emergence, richer graph controls, inline answer proof, workspace/profile/admin discovery, empty/error/consent feedback, and VS Code sync status |
 | 7.0.0 | Brain Productization Loop: first-screen ingestion for files/folders/notes/web, answer-level memory proof and source citations, model-continuity demo flow, five-minute first-run loop, and recall/KG quality eval in CI |
 | 6.7.0 | Brain IA Cleanup: reachable rich pages, separated product routes vs compatibility aliases, shared Brain shell navigation, and lazy-loaded rich pages |

package/docs/CHANGELOG.md

@@ -4,6 +4,47 @@ The top entry is either the current unreleased main-branch work or the current
 release line. Older entries are historical and may describe behavior as it
 existed at that release.
 
+## [7.3.0] - 2026-06-20
+
+> Runtime Contract & Retrieval Quality. Turns the next AgentRuntime extraction
+> step and the uploaded roadmap's hybrid-search quality goals into a small,
+> tested release: shared run contracts and deterministic recall regression.
+
+### Added
+- `lattice_brain.runtime.contracts.AgentRunContract`, a serializable
+  `agent-run-contract/v1` payload shared by single-agent and multi-agent
+  execution paths.
+- Multi-agent API result/run patches now include the shared contract with
+  runtime, mode, status, roles, retries, timeline, and terminal-state data.
+- Single-agent runtime exposes the same contract helper for UI/API/storage
+  convergence in the next extraction pass.
+- `scripts/brain_quality_eval.py` now runs deterministic hybrid recall/ranking
+  regression checks with recall and precision thresholds.
+
+### Changed
+- Package/runtime/static metadata is synchronized to 7.3.0; package publish and
+  deployment remain owner-run only.
+
+## [7.2.0] - 2026-06-20
+
+> Runtime Trust Baseline. Adds execution preview and registry diagnostics so
+> agent runs and tool permissions become inspectable contracts before action.
+
+### Added
+- `POST /agents/api/run/preview` for AgentRuntime readiness, role selection,
+  input keys, retry clamping, and blocking reasons without starting a run.
+- `GET /tools/registry` for the live ToolRegistry manifest across dispatch
+  handlers, governance policy, catalog descriptions, and permissions.
+- `GET /tools/registry/diagnostics` for a compact drift check suitable for CI,
+  admin views, and runtime health panels.
+- Unit coverage for AgentRuntime preview and ToolRegistry manifest diagnostics.
+
+### Changed
+- Tool governance now covers `read_document`, and the catalog describes
+  `create_web_project`, closing the current dispatch/governance/catalog drift.
+- Package/runtime/static metadata is synchronized to 7.2.0; package publish and
+  deployment remain owner-run only.
+
 ## [7.1.0] - 2026-06-20
 
 > Brain Usability Completion. Completes the 7.1.0 first-run through editor-sync

package/docs/ROADMAP_RECOMMENDATIONS.md

@@ -0,0 +1,55 @@
+# Strategic Roadmap Recommendations
+
+This roadmap captures the 2026-06-20 product direction input and maps it to
+small release-sized work. The operating principle stays unchanged:
+
+> Models are temporary. Knowledge is durable. The Brain is the product.
+
+## 7.3.0 Applied Slice
+
+7.3.0 implements the first narrow slice of the roadmap:
+
+- Runtime evolution: single-agent and multi-agent execution share
+  `agent-run-contract/v1`, making mode/status/timeline evidence inspectable.
+- Hybrid search optimization: the Brain quality gate now includes deterministic
+  recall and ranking regression thresholds.
+- Security and trust: run contracts distinguish runtime type and execution mode
+  so simulated output is not presented as real execution.
+
+## Near-Term Tracks
+
+1. Retrieval quality and scale
+   - Expand fixture datasets for hybrid search.
+   - Add latency budgets for large corpora.
+   - Track recall, precision, and ranking regressions in CI.
+   - Tune semantic/graph/keyword fusion by query class.
+
+2. Incremental ingestion
+   - Add background indexing jobs.
+   - Detect duplicates and merge memory candidates.
+   - Surface conflict resolution for contradictory memories.
+
+3. Runtime convergence
+   - Use `agent-run-contract/v1` across single-agent, multi-agent, workflows,
+     audit logs, and UI event streams.
+   - Keep simulation mode explicit and never record it as product success.
+   - Route tools through explicit registry/governance contracts.
+
+4. Brain SDK boundary
+   - Continue extracting `lattice_brain` as a reusable Brain Core package.
+   - Keep compatibility shims until downstream imports are migrated.
+   - Preserve migration rollback paths for graph and memory storage.
+
+5. Trust and operations
+   - Extend audit logging around tool execution and retrieval injection.
+   - Add dependency vulnerability monitoring.
+   - Add Tauri update/rollback planning before enabling auto-update.
+
+## Longer-Term Tracks
+
+- Multi-modal ingestion and retrieval for images, audio, and video.
+- Proactive Brain synthesis, contradiction detection, and recommendations.
+- Temporal reasoning over historical graph states.
+- Interoperability with Obsidian, Notion, Email, Calendar, Git, Slack, and Teams.
+- Encrypted Brain Network sharing.
+- Plugin marketplace and public benchmarks.

package/frontend/src/api/client.ts

@@ -481,7 +481,10 @@ export const latticeApi = {
   unloadModel: (model_id: string) => del(`/models/unload/${encodeURIComponent(model_id)}`, {}),
   embeddingsStatus: () => get("/api/embeddings/status", {}),
   agentRuntime: () => get("/agents/api/runtime/status", { runtime: {}, agents: [], runs: [] }),
+  agentRunPreview: (goal: string, roles: string[] = []) => post("/agents/api/run/preview", { goal, roles }, { ready: false, blocking_reasons: [] }),
   runAgent: (goal: string, roles: string[]) => post("/agents/api/run", { goal, roles }, {}),
+  toolRegistryDiagnostics: () => get("/tools/registry/diagnostics", { diagnostics: { ready: false } }),
+  toolRegistry: () => get("/tools/registry", { status: "unavailable", diagnostics: {}, tools: [] }),
   agentRun: (id: string) => get(`/agents/api/runs/${encodeURIComponent(id)}`, {}),
   stopAgentRun: (id: string) => post(`/agents/api/runs/${encodeURIComponent(id)}/stop`, {}, {}),
   agentRegistry: () => get("/agents/api/registry", { agents: [] }),

package/frontend/src/features/admin/AdminConsole.tsx

@@ -15,7 +15,7 @@ export function AdminConsole({ onBack }: { onBack: () => void }) {
   const qc = useQueryClient();
   const language = useAppStore((state) => state.language);
   const [filters, setFilters] = React.useState<AdminFilterState>({ q: "", actor: "", action: "", severity: "", limit: 50 });
-  const { summaryQ, statsQ, usersQ, auditQ, securityQ, securityEventsQ, policiesQ, rolesQ, retentionQ, indexQ } = useAdminConsoleData(filters);
+  const { summaryQ, statsQ, usersQ, auditQ, securityQ, securityEventsQ, policiesQ, rolesQ, retentionQ, indexQ, agentRuntimeQ, toolRegistryQ } = useAdminConsoleData(filters);
   const rebuildIndex = useMutation({
     mutationFn: latticeApi.rebuildIndex,
     onSuccess: () => void qc.invalidateQueries({ queryKey: ["indexStatus"] }),
@@ -139,6 +139,10 @@ export function AdminConsole({ onBack }: { onBack: () => void }) {
           </div>
         </AdminPanel>
 
+        <AdminPanel title={t(language, "admin.panel.runtimeTrust")} eyebrow={t(language, "admin.panel.contracts")}>
+          <RuntimeTrustPanel runtime={agentRuntimeQ.data?.data as ApiRecord | undefined} registry={toolRegistryQ.data?.data as ApiRecord | undefined} language={language} />
+        </AdminPanel>
+
       </section>
     </main>
   );
@@ -164,9 +168,45 @@ function useAdminConsoleData(filters: AdminFilterState) {
     rolesQ: useQuery({ queryKey: ["adminRoles"], queryFn: latticeApi.adminRoles }),
     retentionQ: useQuery({ queryKey: ["adminLogRetention"], queryFn: latticeApi.adminLogRetention }),
     indexQ: useQuery({ queryKey: ["indexStatus"], queryFn: latticeApi.indexStatus }),
+    agentRuntimeQ: useQuery({ queryKey: ["agentRuntime"], queryFn: latticeApi.agentRuntime }),
+    toolRegistryQ: useQuery({ queryKey: ["toolRegistryDiagnostics"], queryFn: latticeApi.toolRegistryDiagnostics }),
   };
 }
 
+function RuntimeTrustPanel({ runtime, registry, language }: { runtime?: ApiRecord; registry?: ApiRecord; language: "ko" | "en" }) {
+  const runtimeInfo = (runtime?.runtime || {}) as ApiRecord;
+  const health = (runtime?.health || {}) as ApiRecord;
+  const diagnostics = (registry?.diagnostics || {}) as ApiRecord;
+  const ready = Boolean(runtimeInfo.ready);
+  const registryReady = Boolean(diagnostics.ready);
+  const blocking = stringValue(runtimeInfo.unavailable_reason, ready ? t(language, "admin.runtime.readyDetail") : t(language, "admin.runtime.blockedFallback"));
+  return (
+    <div className="admin-runtime-trust">
+      <div className="admin-runtime-row">
+        <strong>{t(language, "admin.runtime.agent")}</strong>
+        <span className={ready ? "is-ok" : "is-warn"}>{ready ? t(language, "admin.status.ready") : t(language, "admin.status.unavailable")}</span>
+        <small>{blocking}</small>
+      </div>
+      <div className="admin-runtime-row">
+        <strong>{t(language, "admin.runtime.tools")}</strong>
+        <span className={registryReady ? "is-ok" : "is-warn"}>{registryReady ? t(language, "admin.runtime.aligned") : t(language, "admin.runtime.drift")}</span>
+        <small>
+          {t(language, "admin.runtime.toolCounts", {
+            registered: stringValue(diagnostics.registered_tools, "0"),
+            governed: stringValue(diagnostics.governed_tools, "0"),
+            described: stringValue(diagnostics.described_tools, "0"),
+          })}
+        </small>
+      </div>
+      <div className="admin-policy-strip">
+        <span>{t(language, "admin.runtime.mode", { mode: stringValue(runtimeInfo.mode, "unknown") })}</span>
+        <span>{t(language, "admin.runtime.execution", { mode: stringValue(runtimeInfo.execution_mode, "unknown") })}</span>
+        <span>{t(language, "admin.runtime.health", { status: stringValue(health.status, "unknown") })}</span>
+      </div>
+    </div>
+  );
+}
+
 function AdminLogFilters({
   filters,
   matched,

package/frontend/src/i18n.ts

@@ -348,6 +348,8 @@ export const COPY: Record<Language, TextMap> = {
     "admin.panel.protection": "보호",
     "admin.panel.brainOps": "Brain 운영",
     "admin.panel.maintenance": "유지보수",
+    "admin.panel.runtimeTrust": "런타임 신뢰도",
+    "admin.panel.contracts": "계약",
     "admin.empty.users": "관리 API가 보고한 사용자가 없습니다.",
     "admin.empty.roles": "보고된 역할 매트릭스가 없습니다.",
     "admin.empty.audit": "최근 감사 이벤트가 없습니다.",
@@ -369,6 +371,16 @@ export const COPY: Record<Language, TextMap> = {
     "admin.brain.summaryFallback": "로컬 Brain 서비스는 사용자 대화와 분리되어 있습니다.",
     "admin.brain.rebuilding": "재구성 중",
     "admin.brain.rebuild": "인덱스 재구성",
+    "admin.runtime.agent": "AgentRuntime",
+    "admin.runtime.tools": "ToolRegistry",
+    "admin.runtime.readyDetail": "실행 preview와 실제 실행이 준비되었습니다.",
+    "admin.runtime.blockedFallback": "실행 전 preview가 차단 사유를 반환합니다.",
+    "admin.runtime.aligned": "정렬됨",
+    "admin.runtime.drift": "점검 필요",
+    "admin.runtime.toolCounts": "등록 {registered} · 정책 {governed} · 설명 {described}",
+    "admin.runtime.mode": "mode {mode}",
+    "admin.runtime.execution": "exec {mode}",
+    "admin.runtime.health": "health {status}",
     "admin.policy.fallback": "정책",
     "admin.policy.quiet": "정책 API 대기 중",
     "admin.retention.days": "{days}일 보관",
@@ -894,6 +906,8 @@ export const COPY: Record<Language, TextMap> = {
     "admin.panel.protection": "Protection",
     "admin.panel.brainOps": "Brain Operations",
     "admin.panel.maintenance": "Maintenance",
+    "admin.panel.runtimeTrust": "Runtime Trust",
+    "admin.panel.contracts": "Contracts",
     "admin.empty.users": "No users reported by the admin API.",
     "admin.empty.roles": "No role matrix reported.",
     "admin.empty.audit": "No recent audit events.",
@@ -915,6 +929,16 @@ export const COPY: Record<Language, TextMap> = {
     "admin.brain.summaryFallback": "Local Brain services are separated from user chat.",
     "admin.brain.rebuilding": "Rebuilding",
     "admin.brain.rebuild": "Rebuild index",
+    "admin.runtime.agent": "AgentRuntime",
+    "admin.runtime.tools": "ToolRegistry",
+    "admin.runtime.readyDetail": "Run preview and execution are ready.",
+    "admin.runtime.blockedFallback": "Run preview returns the blocking reason before execution.",
+    "admin.runtime.aligned": "Aligned",
+    "admin.runtime.drift": "Needs review",
+    "admin.runtime.toolCounts": "Registered {registered} · governed {governed} · described {described}",
+    "admin.runtime.mode": "mode {mode}",
+    "admin.runtime.execution": "exec {mode}",
+    "admin.runtime.health": "health {status}",
     "admin.policy.fallback": "Policy",
     "admin.policy.quiet": "Policy API quiet",
     "admin.retention.days": "{days} day retention",

package/frontend/src/styles.css

@@ -3472,6 +3472,51 @@ body {
   font-size: 0.88rem;
 }
 
+.admin-runtime-trust {
+  display: grid;
+  gap: 0.72rem;
+}
+
+.admin-runtime-row {
+  display: grid;
+  grid-template-columns: minmax(8rem, 1fr) auto;
+  gap: 0.2rem 0.75rem;
+  border: 1px solid hsl(var(--border) / 0.48);
+  border-radius: 8px;
+  background: hsl(var(--bg) / 0.35);
+  padding: 0.72rem;
+}
+
+.admin-runtime-row strong {
+  color: hsl(var(--fg));
+  font-size: 0.88rem;
+}
+
+.admin-runtime-row > span {
+  align-self: start;
+  border-radius: 999px;
+  padding: 0.18rem 0.48rem;
+  font-size: 0.72rem;
+  font-weight: 700;
+}
+
+.admin-runtime-row > small {
+  grid-column: 1 / -1;
+  color: hsl(var(--fg-muted));
+  font-size: 0.78rem;
+  line-height: 1.35;
+}
+
+.admin-runtime-row .is-ok {
+  background: hsl(151 65% 36% / 0.13);
+  color: hsl(151 48% 32%);
+}
+
+.admin-runtime-row .is-warn {
+  background: hsl(36 88% 52% / 0.14);
+  color: hsl(30 82% 35%);
+}
+
 .brain-document-input,
 .brain-image-input {
   display: inline-flex;

package/lattice_brain/__init__.py

@@ -26,7 +26,7 @@ from .storage import (
     storage_from_env,
 )
 
-__version__ = "7.1.0"
+__version__ = "7.3.0"
 
 __all__ = [
     "AgentRuntime",

package/lattice_brain/runtime/agent_runtime.py

@@ -37,6 +37,7 @@ from .multi_agent import (
     MULTI_AGENT_VERSION,
     ROLE_AGENT_IDS,
 )
+from .contracts import multi_agent_contract
 
 ROLE_DESCRIPTIONS = {
     "researcher": "Gathers workspace context and memory for the goal.",
@@ -228,6 +229,57 @@ class AgentRuntime:
             "runs": runs[:25],
         }
 
+    def preview(
+        self,
+        goal: str,
+        *,
+        roles: Optional[List[str]] = None,
+        inputs: Optional[Dict[str, Any]] = None,
+        max_retries: int = 2,
+        scope: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Return the execution contract without reserving or starting a run.
+
+        The preview is the product-facing readiness gate for agent execution:
+        clients can show whether a real LLM-backed run can start, which roles
+        will execute, how retry limits are clamped, and why the run is blocked.
+        """
+
+        requested_roles = list(roles or CORE_PIPELINE)
+        unknown_roles = [role for role in requested_roles if role not in AGENT_ROLES]
+        health = self.health()
+        goal_ready = bool(str(goal or "").strip())
+        retry_budget = max(0, min(int(max_retries or 0), self._max_retries_cap))
+        blocking_reasons: List[str] = []
+        if not goal_ready:
+            blocking_reasons.append("goal is required")
+        if unknown_roles:
+            blocking_reasons.append(f"unknown roles: {', '.join(unknown_roles)}")
+        if not health.get("ready"):
+            orchestrator = (health.get("checks") or {}).get("orchestrator") or {}
+            blocking_reasons.append(str(orchestrator.get("detail") or "agent runtime is unavailable"))
+        can_start = not blocking_reasons
+        return {
+            "ready": can_start,
+            "can_start": can_start,
+            "blocking_reasons": blocking_reasons,
+            "goal": str(goal or "").strip(),
+            "roles": requested_roles,
+            "unknown_roles": unknown_roles,
+            "inputs_keys": sorted((inputs or {}).keys()),
+            "max_retries": retry_budget,
+            "max_retries_requested": max_retries,
+            "scope": scope,
+            "execution_mode": self._execution_mode(),
+            "runtime": {
+                "version": MULTI_AGENT_VERSION,
+                "default_pipeline": list(CORE_PIPELINE),
+                "max_retries_cap": self._max_retries_cap,
+                "simulation_runs_allowed": self._allow_simulation_runs,
+            },
+            "health": health,
+        }
+
     # ── events / state ────────────────────────────────────────────────────
     def list_runs(self, *, scope: Optional[str] = None) -> Dict[str, Any]:
         return self._store.list_agents(workspace_id=scope)
@@ -293,6 +345,7 @@ class AgentRuntime:
             "retry_history": result.retry_history,
             "memory_snapshots": result.memory_snapshots,
             "mode": getattr(result, "mode", "simulation"),
+            "contract": multi_agent_contract(result=result, goal=goal),
             "current_role": None,
         }
 
@@ -458,6 +511,12 @@ class AgentRuntime:
             status=updated.get("status") or result.status,
         )
         result_payload = result.as_dict()
+        result_payload["contract"] = multi_agent_contract(
+            result=result,
+            goal=goal,
+            run_id=run_id,
+            current_role=updated.get("current_role") if isinstance(updated, dict) else None,
+        )
         if updated.get("status") == "cancelled":
             result_payload = {"status": "cancelled", "reason": updated.get("cancel_reason"), "completed_result": result_payload}
         payload = {"run": updated, "result": result_payload}
@@ -550,7 +609,9 @@ class AgentRuntime:
                 user_email=user_email, workspace_id=scope,
             )
 
-        payload = {"run": run, "result": result.as_dict()}
+        result_payload = result.as_dict()
+        result_payload["contract"] = multi_agent_contract(result=result, goal=goal, run_id=run.get("id") if isinstance(run, dict) else None)
+        payload = {"run": run, "result": result_payload}
         if pre_dispatch is not None:
             payload["pre_run_hooks"] = pre_dispatch
         if post_dispatch is not None:

package/lattice_brain/runtime/contracts.py

@@ -0,0 +1,107 @@
+"""Shared runtime contracts for agent execution surfaces.
+
+These contracts are deliberately small and serializable.  The single-agent
+state machine and the multi-agent facade can evolve independently, but callers
+should see the same run identity, mode, status, role, timeline and artifact
+shape across both paths.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+
+def runtime_timestamp() -> str:
+    return datetime.now().isoformat(timespec="seconds")
+
+
+@dataclass(frozen=True)
+class AgentRunContract:
+    run_id: Optional[str]
+    agent_id: str
+    runtime: str
+    mode: str
+    status: str
+    goal: str
+    roles: List[str] = field(default_factory=list)
+    current_role: Optional[str] = None
+    retries: int = 0
+    timeline: List[Dict[str, Any]] = field(default_factory=list)
+    artifacts: List[Dict[str, Any]] = field(default_factory=list)
+    blocking_reasons: List[str] = field(default_factory=list)
+    schema_version: str = "agent-run-contract/v1"
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.status in {"ok", "retried_ok", "failed", "rejected", "cancelled", "interrupted", "partial", "done"}
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "run_id": self.run_id,
+            "agent_id": self.agent_id,
+            "runtime": self.runtime,
+            "mode": self.mode,
+            "status": self.status,
+            "goal": self.goal,
+            "roles": list(self.roles),
+            "current_role": self.current_role,
+            "retries": self.retries,
+            "timeline": list(self.timeline),
+            "artifacts": list(self.artifacts),
+            "blocking_reasons": list(self.blocking_reasons),
+            "is_terminal": self.is_terminal,
+        }
+
+
+def multi_agent_contract(
+    *,
+    result: Any,
+    goal: str,
+    run_id: Optional[str] = None,
+    current_role: Optional[str] = None,
+    blocking_reasons: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    return AgentRunContract(
+        run_id=run_id,
+        agent_id=getattr(result, "agent_id", "agent:executor"),
+        runtime="multi_agent",
+        mode=getattr(result, "mode", "simulation"),
+        status=getattr(result, "status", "unknown"),
+        goal=goal,
+        roles=list(getattr(result, "roles_run", []) or []),
+        current_role=current_role,
+        retries=int(getattr(result, "retries", 0) or 0),
+        timeline=list(getattr(result, "timeline", []) or []),
+        artifacts=[],
+        blocking_reasons=list(blocking_reasons or []),
+    ).as_dict()
+
+
+def single_agent_contract(
+    *,
+    ctx: Any,
+    goal: str,
+    run_id: Optional[str] = None,
+    agent_id: str = "agent:single",
+    mode: str = "llm",
+    blocking_reasons: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    state = getattr(getattr(ctx, "state", None), "value", getattr(ctx, "state", "unknown"))
+    status = "done" if state == "DONE" else "failed" if state == "FAILED" else str(state or "unknown").lower()
+    return AgentRunContract(
+        run_id=run_id,
+        agent_id=agent_id,
+        runtime="single_agent",
+        mode=mode,
+        status=status,
+        goal=goal,
+        roles=["planner", "executor", "critic"],
+        current_role=str(state or ""),
+        retries=int(getattr(ctx, "retry_count", 0) or 0),
+        timeline=list(getattr(ctx, "transcript", []) or []),
+        artifacts=[],
+        blocking_reasons=list(blocking_reasons or []),
+    ).as_dict()

package/lattice_brain/runtime/multi_agent.py

@@ -18,8 +18,10 @@ from dataclasses import dataclass, field
 from datetime import datetime
 from typing import Any, Callable, Dict, List, Optional
 
+from .contracts import multi_agent_contract
 
-MULTI_AGENT_VERSION = "7.1.0"
+
+MULTI_AGENT_VERSION = "7.3.0"
 
 AGENT_ROLES = ("researcher", "planner", "executor", "reviewer", "release")
 CORE_PIPELINE = ("planner", "executor", "reviewer")
@@ -288,7 +290,7 @@ class AgentRunResult:
     mode: str = "simulation"
 
     def as_dict(self) -> Dict[str, Any]:
-        return {
+        payload = {
             "agent_id": self.agent_id,
             "mode": self.mode,
             "status": self.status,
@@ -305,6 +307,8 @@ class AgentRunResult:
             "plan_review": self.plan_review,
             "memory_snapshots": self.memory_snapshots,
         }
+        payload["contract"] = multi_agent_contract(result=self, goal=self.output)
+        return payload
 
 
 def default_role_runner(

package/latticeai/__init__.py

@@ -1,3 +1,3 @@
 """Lattice AI - modular server package."""
 
-__version__ = "7.1.0"
+__version__ = "7.3.0"

package/latticeai/api/agents.py

@@ -192,4 +192,16 @@ def create_agents_router(
             # A pre_run hook gated this run (e.g. a policy/permission hook).
             raise HTTPException(status_code=403, detail=str(exc)) from exc
 
+    @router.post("/agents/api/run/preview")
+    async def agent_run_preview(req: AgentRunRequest, request: Request):
+        require_user(request)
+        scope = gate_read(request)
+        return runtime.preview(
+            req.goal,
+            scope=scope,
+            roles=req.roles or None,
+            inputs=req.inputs,
+            max_retries=req.max_retries,
+        )
+
     return router

package/latticeai/api/tools.py

@@ -25,6 +25,8 @@ from latticeai.services.tool_dispatch import (
     check_tool_role as _check_tool_role,
     get_tool_permission,
     list_tool_permissions,
+    tool_registry_diagnostics,
+    tool_registry_manifest,
 )
 from latticeai.services.router_context import ToolRouterContext
 from latticeai.services.p_reinforce import BRAIN_DIR
@@ -602,6 +604,18 @@ def create_tools_router(
         """
         require_user(request)
         return {"status": "ok", "permissions": list_tool_permissions()}
+
+    @api_router.get("/tools/registry")
+    async def tools_registry(request: Request):
+        """Full ToolRegistry contract: handlers, governance, catalog, diagnostics."""
+        require_user(request)
+        return tool_registry_manifest()
+
+    @api_router.get("/tools/registry/diagnostics")
+    async def tools_registry_diagnostics(request: Request):
+        """Small drift check for CI/admin runtime readiness views."""
+        require_user(request)
+        return {"status": "ok", "diagnostics": tool_registry_diagnostics()}
     
     
     # ── MCP / skills / plugins router (latticeai.api.mcp, v1.3.0) ────────────────