ltcai 11.5.1 → 11.6.0

package/latticeai/api/workspace_scope.py

@@ -1,125 +0,0 @@
-"""One answer to "which workspace is this request talking about?".
-
-Eight routers used to each re-derive this from raw headers. They did not agree:
-some accepted the ``workspace_id`` query parameter and some only the
-``X-Workspace-Id`` header, and only three of them checked that a body's
-``workspace_id`` matched the header instead of silently letting one win. A
-guard that exists in some handlers and not others is not a guard — this module
-is the single implementation they all call, so the rule is stated once and
-holds everywhere.
-
-The rule:
-
-* A caller may name a workspace in the ``X-Workspace-Id`` header, the
-  ``workspace_id`` query parameter, or the request body.
-* If more than one of those is present they must **agree**. Disagreement is a
-  ``403``, never a silent preference — a request that names two workspaces has
-  no single meaning, and picking one is how a scoped write lands in the wrong
-  vault.
-* Naming nothing resolves to ``None``, which every caller passes to
-  :class:`~latticeai.services.workspace_service.WorkspaceService`, where it
-  falls back to the active workspace (Personal by default). That is the
-  pre-1.1 single-workspace behaviour and it stays intact.
-
-Permission is *not* decided here. ``WorkspaceService`` owns read/write gating;
-this module only decides what was asked for and translates the service's
-``PermissionError`` into the HTTP boundary's ``403``.
-"""
-
-from __future__ import annotations
-
-from typing import Any, List, Optional
-
-from fastapi import HTTPException, Request
-
-__all__ = [
-    "WORKSPACE_HEADER",
-    "WORKSPACE_PARAM",
-    "requested_workspace",
-    "resolve_workspace_scope",
-    "workspace_scope_from_request",
-]
-
-WORKSPACE_HEADER = "X-Workspace-Id"
-WORKSPACE_PARAM = "workspace_id"
-
-_MISMATCH_DETAIL = "Workspace selectors must match."
-
-
-def _clean(value: Any) -> Optional[str]:
-    """Normalize one selector to a non-empty string, or ``None``."""
-    if value is None:
-        return None
-    text = str(value).strip()
-    return text or None
-
-
-def workspace_scope_from_request(request: Request) -> Optional[str]:
-    """Resolve the workspace named by header/query, or ``None``.
-
-    ``None`` lets the service fall back to the active workspace (Personal by
-    default), preserving pre-1.1 behaviour for clients that send no header.
-    """
-    header = _clean(request.headers.get(WORKSPACE_HEADER))
-    if header:
-        return header
-    return _clean(request.query_params.get(WORKSPACE_PARAM))
-
-
-def requested_workspace(
-    request: Request,
-    *,
-    body_workspace: Any = None,
-) -> Optional[str]:
-    """The one workspace this request names, or ``None``.
-
-    Raises ``403`` when the header, query parameter, and body disagree.
-    """
-    selectors: List[str] = []
-    for value in (
-        _clean(body_workspace),
-        _clean(request.headers.get(WORKSPACE_HEADER)),
-        _clean(request.query_params.get(WORKSPACE_PARAM)),
-    ):
-        if value is not None:
-            selectors.append(value)
-    if len(set(selectors)) > 1:
-        raise HTTPException(status_code=403, detail=_MISMATCH_DETAIL)
-    return selectors[0] if selectors else None
-
-
-def resolve_workspace_scope(
-    request: Request,
-    *,
-    user: Optional[str],
-    workspace_service: Any = None,
-    write: bool = True,
-    body_workspace: Any = None,
-    allow_unscoped_anonymous: bool = False,
-) -> Optional[str]:
-    """Resolve *and authorize* the workspace a handler should act on.
-
-    ``workspace_service=None`` is the standalone/embedded router contract: the
-    named workspace passes through ungated, exactly as each local copy of this
-    logic did. With a service present, reads are gated on ``read`` and writes
-    on ``write``, and a denial surfaces as ``403``.
-
-    ``allow_unscoped_anonymous`` preserves one deliberate exception: a no-auth
-    local caller that names no workspace keeps its legacy *unscoped* records
-    instead of being resolved onto the active workspace.
-    """
-    requested = requested_workspace(request, body_workspace=body_workspace)
-    if workspace_service is None:
-        return requested
-    if allow_unscoped_anonymous and not user and requested is None:
-        return None
-    resolver = (
-        workspace_service.resolve_write_scope
-        if write
-        else workspace_service.resolve_read_scope
-    )
-    try:
-        scope: Optional[str] = resolver(requested, user or None)
-    except PermissionError as exc:
-        raise HTTPException(status_code=403, detail=str(exc)) from exc
-    return scope

package/latticeai/core/agent/__init__.py

@@ -1,93 +0,0 @@
-"""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

@@ -1,79 +0,0 @@
-"""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

@@ -1,57 +0,0 @@
-"""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

package/latticeai/core/agent/deps.py

@@ -1,125 +0,0 @@
-"""The ports the state machine needs from the outside world.
-
-Everything the loop touches is declared here, which is what lets the whole
-PLAN→EXECUTE→VERIFY cycle run against fakes: production wires these from the
-app layer's router, governance map, audit log and prompts; tests pass an LLM
-that returns canned JSON and a recording tool executor.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Any, Awaitable, Callable, Dict, FrozenSet, Mapping, Optional
-
-from latticeai.core.agent_helpers import PhaseBudgets, TranscriptBudget
-from latticeai.core.agent_profiles import AgentProfile
-
-
-@dataclass
-class AgentDeps:
-    """The ports a :class:`SingleAgentRuntime` needs from the outside world.
-
-    Everything the state machine touches is here, so the loop can be exercised
-    against fakes. See module docstring for the two-adapter rationale.
-    """
-
-    # ── LLM port ─────────────────────────────────────────────────────
-    # generate_as(model_id, message, context, max_tokens, temperature) -> str
-    generate_as: Callable[..., Awaitable[Any]]
-    # generate(message, context, max_tokens, temperature) -> str
-    generate: Callable[..., Awaitable[Any]]
-
-    # ── tool port ────────────────────────────────────────────────────
-    execute_tool: Callable[[str, dict], dict]
-    policy_for: Callable[[str, dict], Mapping[str, Any]]   # name, args -> policy
-    risk_level: Callable[[Any], str]               # policy -> "low"|"medium"|"high"
-    check_role: Callable[[str, str], None]         # tool_name, user -> raises if not allowed
-    tool_governance: Mapping[str, Mapping[str, Any]]  # name -> policy (auto_approve set)
-    file_create_actions: FrozenSet[str]
-
-    # ── context / memory / audit ports ───────────────────────────────
-    recent_chat_context: Callable[..., str]        # (conversation_id=...) -> str
-    clear_history: Callable[[int], dict]
-    knowledge_save: Callable[..., Any]
-    audit: Callable[..., None]                     # (event, **kw) -> None
-
-    # ── prompts + config ─────────────────────────────────────────────
-    planner_prompt: str
-    executor_prompt: str
-    critic_prompt: str
-    memory_updater_prompt: str
-    agent_root: Path
-
-    # ── rollback port (optional) ─────────────────────────────────────
-    # Production injects this from the tool dispatch service so this pure
-    # state machine does not shell out directly. Tests can pass a recorder.
-    rollback_file: Optional[Callable[[str], Dict[str, Any]]] = None
-
-    # ── snapshot rollback ports (optional, review L7) ────────────────
-    # git-only rollback left non-git workspaces and newly created files
-    # unrecoverable. ``snapshot_file(path)`` captures pre-write state
-    # ({"existed", "content", "too_large"}) before a file-create action;
-    # ``restore_snapshot(path, content)`` restores it (content=None deletes
-    # a file the run created). Both are production-wired with workspace
-    # path safety; tests pass recorders.
-    snapshot_file: Optional[Callable[[str], Dict[str, Any]]] = None
-    restore_snapshot: Optional[Callable[[str, Optional[str]], Dict[str, Any]]] = None
-
-    # ── lifecycle hooks port (optional) ──────────────────────────────
-    # When present, every tool execution fires the shared pre_tool/post_tool
-    # lifecycle, so the agent tool path no longer bypasses hooks.
-    hooks: Any = None
-
-    # ── brain memory port (optional) ─────────────────────────────────
-    # When present, completed-run learnings become typed Experience records
-    # through the unified ingestion pipeline (with provenance), replacing
-    # the vault markdown dump.
-    brain_memory: Any = None
-
-    # ── change governor port (optional) ──────────────────────────────
-    # When present, file writes are classified centrally: additive creates
-    # run with minimal friction, while mutations/deletions of existing
-    # content are staged as review proposals instead of applied. The port is
-    # ``review(name, args, policy=..., user_email=..., workspace_id=...)``
-    # returning None (fall through to the classic gates) or a verdict dict.
-    change_governor: Any = None
-
-    # ── phase budgets (optional) ─────────────────────────────────────
-    # Per-phase token caps (plan/execute/verify/memory). None reads the
-    # environment once at first use; tests inject a fixed PhaseBudgets.
-    phase_budgets: Optional[PhaseBudgets] = None
-
-    # ── transcript shaping (optional) ────────────────────────────────
-    # Executor/critic prompt window caps. None reads the environment once;
-    # tests inject a fixed TranscriptBudget.
-    transcript_budget: Optional["TranscriptBudget"] = None
-
-    # ── step observer port (optional) ────────────────────────────────
-    # Default per-runtime observer for live step events; a per-run observer
-    # can also be attached on AgentRunContext.on_step. Both are advisory.
-    on_step: Optional[Callable[[Dict[str, Any]], None]] = None
-
-    # ── agent profile (optional, v9.9.7) ─────────────────────────────
-    # How hard the loop works to keep a weak model on contract. None selects
-    # per-run from the executing model id (``profile_for_model``); tests
-    # inject a fixed profile.
-    agent_profile: Optional["AgentProfile"] = None
-
-    # ── permission mode port (optional, v9.9.8) ──────────────────────
-    # The autonomy dial. Either a static mode, or a resolver callable that
-    # accepts ``user_email``/``workspace_id`` scope kwargs (preferred) or no
-    # arguments at all — see ``call_mode_source``. ``None`` means strict,
-    # which is exactly the pre-9.9.8 behaviour.
-    permission_mode: Any = None
-
-    # ── Self-Model port (optional, v11.2.0) ──────────────────────────
-    # What the Brain has learned about its owner, injected into the executor
-    # prompt. Either a fixed string or a resolver callable taking
-    # ``user_email``/``workspace_id`` scope kwargs (or none at all). 11.1.0
-    # built ``executor_prompt_for(self_model_summary=…)`` and then had nothing
-    # to pass it, because the runtime held its executor prompt as a fixed
-    # string; this is the port that was missing. ``None`` — and an empty
-    # summary — produce exactly the prompt bytes the loop produced before it
-    # existed.
-    self_model_summary: Any = None