ltcai 11.1.0 → 11.4.0

package/latticeai/api/local_files.py

@@ -60,12 +60,36 @@ class FolderWatchEnableRequest(BaseModel):
     path: str
     recursive: bool = True
     workspace_id: Optional[str] = None
+    #: ``folder`` (default, unchanged) or ``vault`` — a watched external
+    #: Obsidian vault, which re-runs the whole bridge sync when it changes and
+    #: carries its own opt-in gate on top of this approval.
+    kind: str = "folder"
     # Watching continuously reads local disk → same approval dance as
     # /api/ingestion/folder. This is the explicit opt-in the review requires.
     approved: bool = False
     approval_token: Optional[str] = None
 
 
+class InteropIngestRequest(BaseModel):
+    """Read one local interop source through the one ingestion gate (v11.2.0).
+
+    ``source`` picks the bridge — ``notion`` (an export directory or ``.zip``),
+    ``git`` (a local repository), ``mail`` (``.eml``/``.ics`` files or a folder
+    of them). Every one of them reads a path the user approves through the same
+    local-read dance as ``/api/ingestion/folder``, and ``dry_run`` reports what
+    a real run would touch without writing anything.
+    """
+
+    source: str
+    path: str
+    workspace_id: Optional[str] = None
+    dry_run: bool = False
+    #: Git only: how far back to read. Ignored by the other bridges.
+    max_commits: Optional[int] = None
+    approved: bool = False
+    approval_token: Optional[str] = None
+
+
 class ObsidianSyncRequest(BaseModel):
     """One-shot sync of an *external* Obsidian vault (v11.1.0).
 
@@ -107,10 +131,18 @@ def create_local_files_router(
     if folder_watch is None and ingestion_pipeline is not None and data_dir is not None:
         try:
             from latticeai.services.folder_watch import FolderWatchService
+            from latticeai.services.obsidian_bridge import ObsidianVaultBridge
 
             folder_watch = FolderWatchService(
                 pipeline=ingestion_pipeline,
                 config_path=Path(data_dir) / "folder_watch.json",
+                # A watched vault re-runs the *whole* bridge sync, which is what
+                # makes its link edges real; the bridge is handed in rather than
+                # imported inside the poller so the watch service keeps knowing
+                # nothing about how a vault is parsed.
+                vault_bridge=ObsidianVaultBridge(
+                    pipeline=ingestion_pipeline, knowledge_graph=knowledge_graph,
+                ),
             )
             folder_watch.restore()
         except Exception:  # noqa: BLE001 — watch mode is optional, never blocks routes
@@ -405,6 +437,66 @@ def create_local_files_router(
             dry_run=req.dry_run,
         )
 
+    # ── interop bridges: Notion export / git history / mail + calendar ───────
+    @router.get("/api/ingestion/interop")
+    async def interop_status(request: Request):
+        """Which interop bridges this machine can actually run, and why not."""
+        require_user(request)
+        from latticeai.services.interop_bridges import bridge_status
+
+        return bridge_status()
+
+    @router.post("/api/ingestion/interop")
+    async def interop_ingest(req: InteropIngestRequest, request: Request):
+        """Read an approved local interop source through the one gate.
+
+        Same approval dance and the same ``IngestionPipeline`` door as the
+        vault bridge: no vendor API, no credentials, nothing leaves the
+        machine. ``dry_run`` writes nothing and reports what a real run would.
+        """
+        current_user = permission_gateway.require_local_user(request)
+        _require_pipeline()
+        workspace_id = _ingestion_write_workspace(request, req.workspace_id, current_user)
+        path = (req.path or "").strip()
+        if not path:
+            raise http_error(400, "ingestion.interop_path_required", resolve_language(request))
+        from latticeai.services.interop_bridges import build_bridge
+
+        try:
+            bridge = build_bridge(
+                req.source, pipeline=ingestion_pipeline, knowledge_graph=knowledge_graph,
+            )
+        except ValueError:
+            raise http_error(
+                400,
+                "ingestion.interop_unknown_source",
+                resolve_language(request),
+                source=req.source,
+            )
+        if not req.approved:
+            return permission_gateway.local_permission_response(path, "read", current_user)
+        permission_gateway.require_local_approval(
+            token=req.approval_token,
+            path=path,
+            action="read",
+            user_email=current_user,
+        )
+        options: Dict[str, Any] = {}
+        if req.max_commits is not None:
+            options["max_commits"] = req.max_commits
+        # Walking an export and embedding its pages is blocking work; the server
+        # owns one event loop and it may not sit here (10.9.0 ASYNC gate).
+        return await asyncio.to_thread(
+            lambda: bridge.sync(
+                path,
+                owner=current_user or None,
+                workspace_id=workspace_id,
+                user_email=current_user or None,
+                dry_run=req.dry_run,
+                **options,
+            )
+        )
+
     # ── folder watch mode: opt-in, off by default (backlog #8) ────────────────
     def _require_folder_watch(request: Request):
         _require_pipeline()
@@ -446,7 +538,16 @@ def create_local_files_router(
             owner=current_user or None,
             workspace_id=workspace_id,
             recursive=req.recursive,
+            kind=req.kind,
         )
+        if result.get("status") == "disabled":
+            # Turned off rather than broken: 403 with the reason, the same shape
+            # every other opt-in gate in this product answers with.
+            raise HTTPException(
+                status_code=403,
+                detail=result.get("detail")
+                or translate("ingestion.vault_watch_disabled", resolve_language(request)),
+            )
         if result.get("status") != "ok":
             raise HTTPException(
                 status_code=400,
@@ -518,6 +619,7 @@ def create_local_files_router(
 __all__ = [
     "FolderIngestRequest",
     "FolderWatchEnableRequest",
+    "InteropIngestRequest",
     "LocalAccessRequest",
     "LocalWriteRequest",
     "ObsidianSyncRequest",

package/latticeai/api/portability.py

@@ -87,8 +87,16 @@ class SubgraphSelection(BaseModel):
 
 
 class SubgraphArchiveRequest(SubgraphSelection):
+    """Exactly one recipient mechanism — a passphrase, or a public key.
+
+    Both optional at the schema level and validated in the service, so the
+    error a caller gets names the rule ("choose one") instead of a field.
+    """
+
     path: Optional[str] = None
-    passphrase: str
+    passphrase: Optional[str] = None
+    #: The recipient's X25519 public key, from their ``/share/recipient-key``.
+    recipient_public_key: Optional[str] = None
 
 
 class SubgraphImportRequest(BaseModel):
@@ -269,6 +277,22 @@ def create_portability_router(
         except (ValueError, RuntimeError) as exc:
             raise HTTPException(status_code=400, detail=str(exc))
 
+    @router.get("/api/knowledge-graph/share/recipient-key")
+    async def share_recipient_key(request: Request):
+        """This Brain's X25519 receiving key, for a sender to seal a bundle to.
+
+        Public by construction — a public key encrypts, it does not decrypt —
+        so handing it out is the whole point. Still admin-gated and still
+        behind the share flag, because minting the key is a decision to
+        participate in sharing at all.
+        """
+        require_admin(request)
+        _require_service(request)
+        try:
+            return service.recipient_key()
+        except PermissionError:
+            raise http_error(403, "portability.brain_network_disabled", resolve_language(request))
+
     @router.post("/api/knowledge-graph/share/archive")
     async def share_archive(req: SubgraphArchiveRequest, request: Request):
         """Same bundle, written as an encrypted ``.latticebrain`` file."""
@@ -277,8 +301,14 @@ def create_portability_router(
         body = req.model_dump()
         path = body.pop("path")
         passphrase = body.pop("passphrase")
+        recipient_public_key = body.pop("recipient_public_key")
         try:
-            return service.export_subgraph_archive(path, passphrase=passphrase, **body)
+            return service.export_subgraph_archive(
+                path,
+                passphrase=passphrase,
+                recipient_public_key=recipient_public_key,
+                **body,
+            )
         except PermissionError:
             raise http_error(403, "portability.brain_network_disabled", resolve_language(request))
         except (ValueError, RuntimeError) as exc:
@@ -294,8 +324,13 @@ def create_portability_router(
         try:
             artifact = req.artifact
             if artifact is None:
-                if not req.path or not req.passphrase:
-                    raise ValueError("Provide an artifact, or a path with its passphrase.")
+                if not req.path:
+                    raise ValueError(
+                        "Provide an artifact, or the path of a bundle on disk."
+                    )
+                # A sealed bundle needs no passphrase — the envelope says which
+                # mechanism it used and the service refuses if the wrong one is
+                # supplied, so the route does not have to guess here.
                 artifact = service.read_subgraph_archive(req.path, passphrase=req.passphrase)
             return service.import_subgraph_proposals(
                 artifact,

package/latticeai/api/review_queue.py

@@ -70,6 +70,39 @@ class ReviewCounts(BaseModel):
     pending_by_source: Dict[str, int] = Field(default_factory=dict)
 
 
+class BulkActionRequest(BaseModel):
+    """Decide several review items at once, named explicitly.
+
+    ``ids`` is required and never defaults to "everything pending": a bulk
+    action whose scope is implicit is how an inbox gets emptied by accident.
+    """
+
+    ids: List[str] = Field(default_factory=list)
+    reason: str = ""
+
+
+class BulkActionOutcome(BaseModel):
+    """Per-item verdict, so a partial success is legible rather than a total."""
+
+    id: str
+    status: str  # ok | not_found | conflict | failed
+    item_status: Optional[str] = None
+    detail: Optional[str] = None
+
+
+class BulkActionResult(BaseModel):
+    action: str
+    requested: int
+    succeeded: int
+    failed: int
+    results: List[BulkActionOutcome] = Field(default_factory=list)
+
+
+#: Ceiling on one bulk call. Large enough for "clear today's inbox", small
+#: enough that one request cannot walk the whole table inside a web worker.
+BULK_ACTION_CAP = 200
+
+
 def create_review_queue_router(
     *,
     service: ReviewQueueService,
@@ -123,6 +156,19 @@ def create_review_queue_router(
         scope = gate_read(request)
         return service.counts(workspace_id=scope, user_email=user)
 
+    # NOTE: declared *before* /automation/reviews/{item_id} for the same reason
+    # "counts" is — routes match in declaration order, so a later /bulk/... would
+    # be swallowed by the {item_id} matcher and answer 404 for a missing item.
+    @router.post("/automation/reviews/bulk/approve", response_model=BulkActionResult)
+    async def bulk_approve(req: BulkActionRequest, request: Request):
+        """Approve several items, reporting each one's outcome individually."""
+        return _bulk(request, req, "approve")
+
+    @router.post("/automation/reviews/bulk/dismiss", response_model=BulkActionResult)
+    async def bulk_dismiss(req: BulkActionRequest, request: Request):
+        """Dismiss several items, reporting each one's outcome individually."""
+        return _bulk(request, req, "dismiss")
+
     @router.get("/automation/reviews/{item_id}", response_model=ReviewItem)
     async def get_item(item_id: str, request: Request):
         require_user(request)
@@ -205,6 +251,86 @@ def create_review_queue_router(
     async def unsnooze_item(item_id: str, request: Request):
         return _act(request, item_id, "unsnooze")
 
+    def _bulk(request: Request, req: BulkActionRequest, action: str) -> Dict[str, Any]:
+        """One transition applied N times through the *same* single-item guard.
+
+        Deliberately not a bulk UPDATE. Every id goes through the ordinary
+        service call, so an already-approved item still 409s, a
+        ``change_proposal`` still applies its staged content, and the audit
+        trail records N decisions — because that is what happened. A failure
+        on one id never aborts the rest, and the response says exactly which
+        ones did not land instead of returning a single number the caller has
+        to interpret.
+        """
+        user = require_user(request)
+        scope = gate_write(request)
+        language = resolve_language(request)
+        wanted = [str(item).strip() for item in req.ids if str(item).strip()]
+        if not wanted:
+            raise http_error(422, "review.bulk_ids_required", language)
+        if len(wanted) > BULK_ACTION_CAP:
+            raise http_error(422, "review.bulk_too_many", language, cap=BULK_ACTION_CAP)
+        results: List[Dict[str, Any]] = []
+        succeeded = 0
+        for item_id in wanted:
+            outcome = _bulk_one(request, item_id, action, user=user, scope=scope, reason=req.reason)
+            if outcome["status"] == "ok":
+                succeeded += 1
+            results.append(outcome)
+        return {
+            "action": action,
+            "requested": len(wanted),
+            "succeeded": succeeded,
+            "failed": len(wanted) - succeeded,
+            "results": results,
+        }
+
+    def _bulk_one(
+        request: Request,
+        item_id: str,
+        action: str,
+        *,
+        user: str,
+        scope: Optional[str],
+        reason: str,
+    ) -> Dict[str, Any]:
+        try:
+            if action == "dismiss":
+                item = service.dismiss(item_id, workspace_id=scope, reason=reason or None)
+            else:
+                item = _approve_one(request, item_id, user=user, scope=scope)
+        except (FileNotFoundError, KeyError):
+            return {"id": item_id, "status": "not_found", "detail": None}
+        except InvalidReviewTransition as exc:
+            return {"id": item_id, "status": "conflict", "detail": str(exc)}
+        except ProposalConflictError as exc:
+            return {"id": item_id, "status": "conflict", "detail": str(exc)}
+        except HTTPException as exc:
+            return {
+                "id": item_id,
+                "status": "conflict" if exc.status_code == 409 else "failed",
+                "detail": str(exc.detail),
+            }
+        except ValueError as exc:
+            return {"id": item_id, "status": "failed", "detail": str(exc)}
+        append_audit_event(f"review_item_{action}", user_email=user, item_id=item_id)
+        return {"id": item_id, "status": "ok", "item_status": item.get("status"), "detail": None}
+
+    def _approve_one(
+        request: Request, item_id: str, *, user: str, scope: Optional[str]
+    ) -> Dict[str, Any]:
+        """Approve exactly the way the single-item route does, staged content included."""
+        if change_proposals is not None:
+            stored = service.get(item_id, workspace_id=scope)
+            if stored.get("source") == "change_proposal":
+                if stored.get("effective_status") not in ("pending", "snoozed"):
+                    raise InvalidReviewTransition("approve", str(stored.get("status")))
+                applied = change_proposals.approve_and_apply(
+                    item_id, user_email=user, workspace_id=scope
+                )
+                return dict(applied["item"])
+        return service.approve(item_id, workspace_id=scope)
+
     @router.post("/automation/reviews/{item_id}/run_now", response_model=ReviewItem)
     async def run_now_item(item_id: str, request: Request):
         user = require_user(request)

package/latticeai/api/search.py

@@ -25,6 +25,11 @@ class HybridSearchRequest(SearchRequest):
     vector_limit: int = 30
     graph_limit: int = 30
     weights: Optional[Dict[str, float]] = None
+    #: Opt in to scoring this text query against the *image* index too
+    #: (v11.2.0). Only possible when a shared-space vision model is
+    #: configured; when it is not, the response says so instead of quietly
+    #: returning the text-only ranking as if fusion had happened.
+    image_fusion: bool = False
 
 
 class GraphNodeRequest(BaseModel):
@@ -106,17 +111,26 @@ def create_search_router(
                 vector_limit=req.vector_limit,
                 graph_limit=req.graph_limit,
                 weights=req.weights or DEFAULT_HYBRID_WEIGHTS,
+                image_fusion=req.image_fusion,
             )
         except ValueError as exc:
             _raise_graph_error(exc)
 
     @router.get("/api/search/hybrid")
-    async def hybrid_search_get(q: str, request: Request, limit: int = 30) -> Dict[str, Any]:
+    async def hybrid_search_get(
+        q: str, request: Request, limit: int = 30, image_fusion: bool = False,
+    ) -> Dict[str, Any]:
         try:
-            return _guarded(request).hybrid_search(q, limit=limit)
+            return _guarded(request).hybrid_search(q, limit=limit, image_fusion=image_fusion)
         except ValueError as exc:
             _raise_graph_error(exc)
 
+    @router.get("/api/search/image-query")
+    async def image_query_status(request: Request) -> Dict[str, Any]:
+        """Whether a typed question can reach the image index on this install."""
+        require_user(request)
+        return service.image_query_status()
+
     @router.post("/api/search/keyword")
     async def keyword_search(req: SearchRequest, request: Request) -> Dict[str, Any]:
         try:

package/latticeai/core/agent/__init__.py

@@ -0,0 +1,93 @@
+"""Single-agent runtime — the Discover→Plan→Implement→Verify state machine.
+
+This package is the deep single-agent loop: a small interface (``AgentDeps``
+ports + ``SingleAgentRuntime.run_to_completion``) over the whole role-phased
+state machine (planner → executor → critic → rollback → memory). It carries no
+FastAPI, no globals, and no I/O of its own — every collaborator is injected
+through ``AgentDeps``.
+
+Two adapters justify the seam:
+
+* production wires ``AgentDeps`` from ``latticeai.server_app``'s ``LLMRouter``, governance
+  map, audit log, and prompts;
+* tests pass fake ports (an LLM that returns canned JSON, a recording tool
+  executor) and drive a full PLAN→EXECUTE→VERIFY→DONE cycle without a server.
+
+HTTP concerns — request parsing, chat-history persistence, response shaping,
+scheduling the background memory update — stay in the app layer. This package
+only owns the state machine.
+
+v10.0.1 split the pure helpers and the state vocabulary out to sibling modules
+(``agent_state``, ``agent_helpers``, ``agent_trace``, …). v11.3.0 finished the
+job on what was left, turning the module into a package whose submodules are
+one phase each:
+
+* :mod:`.context` — ``AgentRunContext``, the state one run carries;
+* :mod:`.deps` — ``AgentDeps``, the ports;
+* :mod:`.planning` / :mod:`.execution` / :mod:`.verification` / :mod:`.recovery`
+  — the four phase mixins;
+* :mod:`.runtime` — ``SingleAgentRuntime``, which composes them and drives the
+  loop;
+* :mod:`._contract` — the typing-only seam the mixins share.
+
+Every name this module exported still resolves from ``latticeai.core.agent``.
+
+Stubbing note: a name rebound *here* changes only this module's binding — the
+submodule that calls it holds its own, so a test standing in for a collaborator
+patches the submodule that reads it.
+"""
+
+from __future__ import annotations
+
+# The state vocabulary and the pure helpers live in sibling modules so the loop
+# holds only the loop. They are re-exported (see ``__all__``) because callers —
+# the HTTP layer, run_store, the eval harness, and the tests — have always
+# imported them from here, and that contract does not change.
+from latticeai.core.agent_helpers import PhaseBudgets as PhaseBudgets
+from latticeai.core.agent_helpers import TranscriptBudget as TranscriptBudget
+from latticeai.core.agent_helpers import _truncate_strings as _truncate_strings
+from latticeai.core.agent_helpers import artifact_checklist as artifact_checklist
+from latticeai.core.agent_helpers import compact_transcript as compact_transcript
+from latticeai.core.agent_helpers import extract_action as extract_action
+from latticeai.core.agent_helpers import (
+    extract_action_details as extract_action_details,
+)
+from latticeai.core.agent_helpers import files_written as files_written
+from latticeai.core.agent_helpers import filter_learnings as filter_learnings
+from latticeai.core.agent_helpers import (
+    format_artifact_checklist as format_artifact_checklist,
+)
+from latticeai.core.agent_helpers import (
+    format_requirement_coverage as format_requirement_coverage,
+)
+from latticeai.core.agent_helpers import normalize_plan as normalize_plan
+from latticeai.core.agent_helpers import requirement_coverage as requirement_coverage
+from latticeai.core.agent_state import AGENT_TERMINAL_STATES as AGENT_TERMINAL_STATES
+from latticeai.core.agent_state import AgentState as AgentState
+
+from .context import AgentRunContext as AgentRunContext
+from .deps import AgentDeps as AgentDeps
+from .runtime import SingleAgentRuntime as SingleAgentRuntime
+
+__all__ = [
+    # this module
+    "AgentDeps",
+    "AgentRunContext",
+    "SingleAgentRuntime",
+    # re-exported from agent_state
+    "AGENT_TERMINAL_STATES",
+    "AgentState",
+    # re-exported from agent_helpers
+    "PhaseBudgets",
+    "TranscriptBudget",
+    "artifact_checklist",
+    "compact_transcript",
+    "extract_action",
+    "extract_action_details",
+    "files_written",
+    "filter_learnings",
+    "format_artifact_checklist",
+    "format_requirement_coverage",
+    "normalize_plan",
+    "requirement_coverage",
+]

package/latticeai/core/agent/_contract.py

@@ -0,0 +1,79 @@
+"""The seam the four phase mixins share.
+
+``SingleAgentRuntime`` is assembled from the planning, execution, verification
+and recovery mixins. Each of them reads state it does not own and calls back
+into helpers defined on the runtime itself — the point of the split is that
+"how a plan is approved" and "how a tool call is gated" stop sharing a
+1,465-line file, not that they stop sharing ``self``.
+
+Typing-only, exactly like :mod:`lattice_brain.ingestion._contract`: the
+declarations below are never the implementation, so the MRO and every method
+resolution stay byte-for-byte what the single-file class had. Adding a
+cross-mixin call without declaring it here is a type error.
+"""
+
+from __future__ import annotations
+
+from typing import Any, FrozenSet, Optional
+
+from latticeai.core.agent_helpers import PhaseBudgets, TranscriptBudget
+from latticeai.core.agent_profiles import AgentProfile
+from latticeai.core.permission_mode import PermissionMode
+
+from .context import AgentRunContext
+from .deps import AgentDeps
+
+
+class AgentCore:
+    """What any phase mixin may assume about ``self``.
+
+    Never instantiated directly — see the module docstring. Members are
+    declared, not implemented: the implementation lives in ``runtime.py`` or in
+    whichever mixin owns it.
+    """
+
+    # ── State owned by SingleAgentRuntime.__init__ ───────────────────────────
+    deps: AgentDeps
+    _env_phase_budgets: Optional[PhaseBudgets]
+    _env_transcript_budget: Optional[TranscriptBudget]
+
+    # ── runtime.py: budgets, resolved from deps or the environment once ──────
+    @property
+    def phase_budgets(self) -> PhaseBudgets:
+        raise NotImplementedError
+
+    @property
+    def transcript_budget(self) -> TranscriptBudget:
+        raise NotImplementedError
+
+    # ── runtime.py: the autonomy dial every gate in one run agrees on ────────
+    def resolve_permission_mode(
+        self,
+        ctx: Optional[AgentRunContext] = None,
+        *,
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ) -> PermissionMode:
+        raise NotImplementedError
+
+    # ── runtime.py: change-governance classification helpers ─────────────────
+    def _governed_tools(self) -> FrozenSet[str]:
+        raise NotImplementedError
+
+    def _governed_path_exists(self, name: str, path: str) -> bool:
+        raise NotImplementedError
+
+    # ── runtime.py: how hard the loop works to keep this model on contract ───
+    def profile_for(self, model_id: Optional[str]) -> AgentProfile:
+        raise NotImplementedError
+
+    # ── runtime.py: advisory telemetry every phase emits ─────────────────────
+    def _emit_step(
+        self, ctx: AgentRunContext, phase: str, event: str, **details: Any
+    ) -> None:
+        raise NotImplementedError
+
+    # ── runtime.py: project-session prompt block, or "" for a standalone run ─
+    @staticmethod
+    def _project_block(ctx: AgentRunContext) -> str:
+        raise NotImplementedError

package/latticeai/core/agent/context.py

@@ -0,0 +1,57 @@
+"""The mutable state one agent run carries from phase to phase.
+
+Every phase reads and writes this object and nothing else: the loop itself is
+stateless, so a run is exactly what its :class:`AgentRunContext` says it is.
+``__slots__`` is deliberate — a typo'd attribute is an error, not a silently
+ignored write that a later phase never sees.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+
+from latticeai.core.agent_state import AgentState
+from latticeai.core.agent_trace import LoopTrace
+
+
+class AgentRunContext:
+    """Mutable state carrier passed through all agent phases."""
+    __slots__ = ("state", "plan", "transcript", "retry_count",
+                 "state_history", "corrections", "final_message", "rollback_log",
+                 "executing_model", "reviewing_model", "approved_by_human", "trace",
+                 "on_step", "project_context", "permission_mode",
+                 "self_model_summary")
+
+    def __init__(self) -> None:
+        self.state:           AgentState   = AgentState.IDLE
+        self.trace:           LoopTrace    = LoopTrace()
+        self.plan:            dict         = {}
+        self.transcript:      list         = []
+        self.retry_count:     int          = 0
+        self.state_history:   list         = []
+        self.corrections:     list         = []
+        self.final_message:   str          = ""
+        self.rollback_log:    list         = []
+        self.executing_model: Optional[str] = None
+        self.reviewing_model: Optional[str] = None
+        self.approved_by_human: bool       = False
+        # Per-run step observer (review Wave 1.1): the HTTP layer attaches a
+        # callback here so live SSE clients see progress while EXECUTING.
+        # Never serialized; a broken observer never breaks the loop.
+        self.on_step: Optional[Callable[[Dict[str, Any]], None]] = None
+        # Multi-turn project loop (v9.9.6): a prompt block describing where the
+        # project stands — files already produced, open TODOs, the last honest
+        # verification. Empty for a standalone run, which behaves exactly as
+        # before. Set by the HTTP layer, read by plan/execute/verify.
+        self.project_context: str = ""
+        # Autonomy dial resolved once per run (v9.9.8). The HTTP layer stamps
+        # the user/workspace-scoped mode here so the plan gate and every
+        # per-tool gate in the same run agree; ``None`` falls back to the
+        # process-wide resolver on ``deps``.
+        self.permission_mode: Optional[str] = None
+        # Self-Model summary resolved once per run (v11.2.0). The executor
+        # prompt is rebuilt on every turn of the loop; reading the profile
+        # once and reusing it keeps a graph query off that hot path — and
+        # keeps every turn of one run describing the same person. ``None``
+        # means "not resolved yet"; ``""`` is a resolved, empty profile.
+        self.self_model_summary: Optional[str] = None