ms-tau-sdk 1.2.12.dev20__tar.gz → 1.2.13.dev22__tar.gz

{ms_tau_sdk-1.2.12.dev20 → ms_tau_sdk-1.2.13.dev22}/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 ## Unreleased
 
+- Local mode no longer needs a token in the environment or in the project `.env`. With neither
+  `MAINSEQUENCE_ACCESS_TOKEN` nor `MAINSEQUENCE_REFRESH_TOKEN` set, it asks a Main Sequence CLI
+  for the access token with `mainsequence auth token --json`: log in once with
+  `mainsequence login`. The SDK looks for the CLI in the new `MAINSEQUENCE_CLI` setting, then
+  beside the Python interpreter, then on `PATH`. It keeps the token in memory, reuses it until 60
+  seconds before it expires, and asks again after a rejected request. It refuses an answer for
+  another backend. A missing CLI, a CLI too old for the command, a missing or expired session, a
+  machine without a credential store, a time-out, and malformed output each have their own error.
+  The SDK still does not depend on or import the `mainsequence` package and does not read the
+  CLI's credential store. The token pair stays supported in the process environment, for
+  launchers and CI, and with both tokens set the CLI is never run. A pair read from the project
+  `.env` file still works but is deprecated: startup logs one warning that names the file and the
+  two variables, and `mainsequence refresh-token` run in that directory removes them. `/health`
+  and `/ready` report the source in `mainsequence_auth_source` (`cli`, `environment`, or
+  `env_file`; `null` in managed mode), and Tau Board shows it in Connect. The owner scope of local
+  chat sessions and direct A2A conversations is derived from the subject of the CLI token, so a
+  user keeps the same local sessions with either source. See the 2026-09-30 amendments of ADR 0005
+  and ADR 0017.
+- Tau Board again reads the local state the SDK writes. 1.2.12 raised the local SQLite schema
+  version to 6 without raising the version Tau Board accepts, so the board refused every store
+  that 1.2.12 had created or opened: the State, session, Task, and Task-log views returned
+  "Unknown Tau local SQLite schema version". Schema 6 only adds the `local_chat_sessions` table,
+  and the board's queries are unchanged. The board still accepts exactly one schema version, so a
+  store last opened by 1.2.11 or earlier is refused until Tau starts once and migrates it. A Board
+  test now reads a store written by the SDK's local backend, so a schema change the board has not
+  followed fails the Board suite.
+
+## 1.2.12 — 2026-09-27
+
+- Local `/api/chat` sessions now survive a UI reload and a Tau restart. Local mode records each chat
+  session and adds `GET /api/local/v1/chat-sessions` to list them and
+  `GET /api/local/v1/chat-sessions/{sessionUid}/history` to read one back. The history uses the
+  shape of the platform's `GET /api/v1/agent-sessions/{uid}/history/`: user and assistant text,
+  reasoning, and tool calls with their arguments, results, and `isError`, projected from the Tau
+  transcript by the platform's rules. A turn still running is returned in `inProgressMessage`.
+  `GET /api/local/v1/agent` returns the Agent's name and description from the workspace's
+  `.agents/agent_card.json`. A local chat turn now runs to its durable end when its client
+  disconnects or reloads, and only `POST /api/chat/session/cancel` stops it. A second turn for a
+  session that is still running returns 409 `session_busy`. After a Stop, the next turn in a local
+  session used to fail with "Runtime cancellation was requested" until the idle runtime was
+  evicted; the session's next turn now runs on a fresh runtime. Managed chat behavior is unchanged.
+  With `MAINSEQUENCE_TAU_TRUSTED_ORIGINS` set, CORS also exposes `X-Agent-Session-Uid` and
+  `x-vercel-ai-ui-message-stream`. See ADR 0018. Fixes #47.
 - Added `MAINSEQUENCE_TAU_PROVIDER_TIMEOUT_SECONDS`, the HTTP timeout for model-provider calls.
   It was fixed at 60 seconds for every provider hydrated from the platform, with no setting
   or environment variable to change it. A self-hosted OpenAI-compatible provider such as an
@@ -9,15 +52,15 @@
   prompt exhausted all three attempts, and Tau reported only an empty transport failure. The
   default stays 60 seconds, and an explicit `timeout_seconds` passed to `ProviderFactory.build`
   still takes precedence.
+
+## 1.2.11 — 2026-09-27
+
 - Added authenticated-process-scoped discovery and bounded hydration for direct local A2A Message
   conversations. The SDK now persists exact public requester/responder Messages independently from
   Tau execution entries, returns stable context and Message identities across restart, supports
   cursor pagination and exact completed-request replay, and exposes
   `GET /api/local/v1/conversations` plus its bounded Message-history route. Existing internal
   sessions are not heuristically reconstructed. Fixes #45.
-
-## 1.2.11 — 2026-09-27
-
 - Added a version-locked `tau-ai==0.4.2` compatibility patch for OpenAI-compatible transport
   failures that exhausted retries with an empty terminal message. The SDK now preserves the
   concrete HTTPX error type, transport phase, retry evidence, total provider duration, one failure

{ms_tau_sdk-1.2.12.dev20 → ms_tau_sdk-1.2.13.dev22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ms-tau-sdk
-Version: 1.2.12.dev20
+Version: 1.2.13.dev22
 Summary: Workspace-bound Tau application primitives for Main Sequence projects
 Project-URL: Changelog, https://github.com/mainsequence-sdk/ms-tau-sdk/blob/development/CHANGELOG.md
 Project-URL: Documentation, https://github.com/mainsequence-sdk/ms-tau-sdk/tree/development/docs
@@ -129,9 +129,9 @@ project selects a provider and model explicitly, while Main Sequence still autho
 the provider credential and supplies the live MCP catalog:
 
 ```bash
+mainsequence login   # once; the session is kept by the CLI, not in .env
+
 export MAINSEQUENCE_AUTH_MODE=jwt
-export MAINSEQUENCE_ACCESS_TOKEN="<exported-user-access-token>"
-export MAINSEQUENCE_REFRESH_TOKEN="<exported-user-refresh-token>"
 export TAU_LOCAL_MODE=true
 export TAU_LOCAL_PROVIDER=openai
 export TAU_LOCAL_MODEL=gpt-5.4
@@ -139,10 +139,21 @@ export TAU_LOCAL_MODEL=gpt-5.4
 uv run ms-tau
 ```
 
-The normal Main Sequence login or project launcher may provision those JWT variables, but
-`ms-tau-sdk` does not install, import, or invoke the `mainsequence` Python package. It consumes the
-environment handoff and public refresh API directly. Provider secrets are never environment
-settings and are never persisted locally.
+Log in once with the Main Sequence CLI. Local mode then asks that CLI for a short-lived access
+token with `mainsequence auth token --json`, and again when the token is about to expire. No token
+is exported and none is written to the project `.env`. The SDK looks for the CLI in
+`MAINSEQUENCE_CLI`, then beside the Python interpreter, then on `PATH`. `ms-tau-sdk` does not
+install or import the `mainsequence` Python package and does not read the CLI's credential store.
+
+Launchers and CI can hand the process a token pair instead. With both variables set, the SDK
+uses them and the public refresh API and never runs the CLI:
+
+```bash
+export MAINSEQUENCE_ACCESS_TOKEN="<user-access-token>"
+export MAINSEQUENCE_REFRESH_TOKEN="<user-refresh-token>"
+```
+
+Provider secrets are never environment settings and are never persisted locally.
 
 Local conversations and public A2A Tasks are stored at
 `~/.tau/mainsequence/<workspace-hash>/runtime.sqlite3`; an omitted chat `sessionUid` uses the
@@ -172,6 +183,15 @@ events as distinct sections. Correlated provider failures appear first as one hu
 incident with cause, phase, retries, duration, and bounded traceback frames; raw JSON is an
 expandable secondary view.
 
+Local `/api/chat` sessions are reload-safe as well. List them with
+`GET /api/local/v1/chat-sessions` and read one back with
+`GET /api/local/v1/chat-sessions/{sessionUid}/history`, which returns the platform's chat history
+shape: user and assistant text, reasoning, and tool calls with their results, plus a turn still
+running in `inProgressMessage`. Continue a session by sending its `sessionUid` to `POST /api/chat`.
+A local chat turn keeps running when its client disconnects; stop it with
+`POST /api/chat/session/cancel`. `GET /api/local/v1/agent` returns the Agent's name and description
+from the workspace's `.agents/agent_card.json`.
+
 Direct local A2A Message conversations are also reload-safe without becoming Tasks. List them with
 `GET /api/local/v1/conversations`, then hydrate one with
 `GET /api/local/v1/conversations/{contextId}/messages`; both reads are bounded and scoped to the
@@ -234,7 +254,8 @@ are not bundled into the SDK. Main Sequence transport and protocol behavior rema
 ## Included capabilities
 
 - FastAPI application construction and lifecycle management
-- runtime-credential exchange, local user-JWT refresh, and authenticated Main Sequence access
+- runtime-credential exchange, local sign-in through the Main Sequence CLI session or a user-JWT
+  environment pair, and authenticated Main Sequence access
 - provider validation and credential hydration
 - durable Tau sessions, leases, restore, persistence, cancellation, eviction, and shutdown
 - local Tau execution without backend AgentSession pre-creation

{ms_tau_sdk-1.2.12.dev20 → ms_tau_sdk-1.2.13.dev22}/README.md

@@ -98,9 +98,9 @@ project selects a provider and model explicitly, while Main Sequence still autho
 the provider credential and supplies the live MCP catalog:
 
 ```bash
+mainsequence login   # once; the session is kept by the CLI, not in .env
+
 export MAINSEQUENCE_AUTH_MODE=jwt
-export MAINSEQUENCE_ACCESS_TOKEN="<exported-user-access-token>"
-export MAINSEQUENCE_REFRESH_TOKEN="<exported-user-refresh-token>"
 export TAU_LOCAL_MODE=true
 export TAU_LOCAL_PROVIDER=openai
 export TAU_LOCAL_MODEL=gpt-5.4
@@ -108,10 +108,21 @@ export TAU_LOCAL_MODEL=gpt-5.4
 uv run ms-tau
 ```
 
-The normal Main Sequence login or project launcher may provision those JWT variables, but
-`ms-tau-sdk` does not install, import, or invoke the `mainsequence` Python package. It consumes the
-environment handoff and public refresh API directly. Provider secrets are never environment
-settings and are never persisted locally.
+Log in once with the Main Sequence CLI. Local mode then asks that CLI for a short-lived access
+token with `mainsequence auth token --json`, and again when the token is about to expire. No token
+is exported and none is written to the project `.env`. The SDK looks for the CLI in
+`MAINSEQUENCE_CLI`, then beside the Python interpreter, then on `PATH`. `ms-tau-sdk` does not
+install or import the `mainsequence` Python package and does not read the CLI's credential store.
+
+Launchers and CI can hand the process a token pair instead. With both variables set, the SDK
+uses them and the public refresh API and never runs the CLI:
+
+```bash
+export MAINSEQUENCE_ACCESS_TOKEN="<user-access-token>"
+export MAINSEQUENCE_REFRESH_TOKEN="<user-refresh-token>"
+```
+
+Provider secrets are never environment settings and are never persisted locally.
 
 Local conversations and public A2A Tasks are stored at
 `~/.tau/mainsequence/<workspace-hash>/runtime.sqlite3`; an omitted chat `sessionUid` uses the
@@ -141,6 +152,15 @@ events as distinct sections. Correlated provider failures appear first as one hu
 incident with cause, phase, retries, duration, and bounded traceback frames; raw JSON is an
 expandable secondary view.
 
+Local `/api/chat` sessions are reload-safe as well. List them with
+`GET /api/local/v1/chat-sessions` and read one back with
+`GET /api/local/v1/chat-sessions/{sessionUid}/history`, which returns the platform's chat history
+shape: user and assistant text, reasoning, and tool calls with their results, plus a turn still
+running in `inProgressMessage`. Continue a session by sending its `sessionUid` to `POST /api/chat`.
+A local chat turn keeps running when its client disconnects; stop it with
+`POST /api/chat/session/cancel`. `GET /api/local/v1/agent` returns the Agent's name and description
+from the workspace's `.agents/agent_card.json`.
+
 Direct local A2A Message conversations are also reload-safe without becoming Tasks. List them with
 `GET /api/local/v1/conversations`, then hydrate one with
 `GET /api/local/v1/conversations/{contextId}/messages`; both reads are bounded and scoped to the
@@ -203,7 +223,8 @@ are not bundled into the SDK. Main Sequence transport and protocol behavior rema
 ## Included capabilities
 
 - FastAPI application construction and lifecycle management
-- runtime-credential exchange, local user-JWT refresh, and authenticated Main Sequence access
+- runtime-credential exchange, local sign-in through the Main Sequence CLI session or a user-JWT
+  environment pair, and authenticated Main Sequence access
 - provider validation and credential hydration
 - durable Tau sessions, leases, restore, persistence, cancellation, eviction, and shutdown
 - local Tau execution without backend AgentSession pre-creation

{ms_tau_sdk-1.2.12.dev20 → ms_tau_sdk-1.2.13.dev22}/packages/tau-board/src/ms_tau_board/state.py

@@ -9,7 +9,9 @@ from contextlib import closing
 from pathlib import Path
 from typing import Any
 
-SCHEMA_VERSION = "5"
+# The version `ms_tau_sdk.backend.local` stamps on the store. The board never imports the SDK,
+# so this follows it by hand.
+SCHEMA_VERSION = "6"
 TABLES = (
     "sessions",
     "entries",

{ms_tau_sdk-1.2.12.dev20 → ms_tau_sdk-1.2.13.dev22}/packages/tau-board/src/ms_tau_board/static/app.js

@@ -210,6 +210,7 @@ async function checkConnection() {
   detailLine(box, "Mode", result.health.mode);
   detailLine(box, "Version", result.health.version);
   detailLine(box, "Ready", result.ready ? "Yes" : "No");
+  detailLine(box, "Credential source", result.health.mainsequence_auth_source);
   detailLine(box, "Workspace digest", result.health.workspace_digest);
   detailLine(box, "State directory", result.stateDir);
   detailLine(box, "MCP tools", result.health.mcp_tool_count);

{ms_tau_sdk-1.2.12.dev20 → ms_tau_sdk-1.2.13.dev22}/packages/tau-board/src/ms_tau_board/static/index.html

@@ -192,7 +192,7 @@
             <button class="button is-primary" id="settings-apply-board">Apply to this session</button>
             <p class="help mt-2">This updates the selected profile immediately. It does not write <code>.env</code>.</p>
           </div>
-          <div class="box"><h2 class="title is-6">Credential presence</h2><p class="help mb-3">Board process and local <code>.env</code> are shown separately. Credential values are never sent to the browser.</p><div id="settings-credentials" class="detail-list"></div></div>
+          <div class="box"><h2 class="title is-6">Credential presence</h2><p class="help mb-3">Board process and local <code>.env</code> are shown separately. Credential values are never sent to the browser. A Tau process that uses the Main Sequence CLI session needs no token here. Connect shows its credential source.</p><div id="settings-credentials" class="detail-list"></div></div>
         </div>
         <div class="column">
           <div class="box">

{ms_tau_sdk-1.2.12.dev20 → ms_tau_sdk-1.2.13.dev22}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ms-tau-sdk"
-version = "1.2.12.dev20"
+version = "1.2.13.dev22"
 description = "Workspace-bound Tau application primitives for Main Sequence projects"
 readme = "README.md"
 requires-python = ">=3.13"

{ms_tau_sdk-1.2.12.dev20 → ms_tau_sdk-1.2.13.dev22}/src/ms_tau_sdk/agent_skills/tau_local_development/SKILL.md

@@ -11,14 +11,15 @@ an offline, mock-provider, or mock-MCP mode.
 
 ## Start the process
 
-Obtain the user's access and refresh JWTs through the supported Main Sequence login or
-project-launcher flow. The SDK consumes that environment handoff directly; it does not install,
-import, or invoke the `mainsequence` Python package and does not read its private credential store.
+The user logs in once with a Main Sequence CLI that provides `mainsequence auth token`. Local mode
+then asks that CLI for a short-lived access token, at startup and again when the token is about to
+expire. No token is exported and none is written to the project `.env`. The SDK does not install or
+import the `mainsequence` Python package and does not read the CLI's private credential store.
 
 ```bash
+mainsequence login   # once; the session is kept by the CLI, not in .env
+
 export MAINSEQUENCE_AUTH_MODE=jwt
-export MAINSEQUENCE_ACCESS_TOKEN="<user-access-token>"
-export MAINSEQUENCE_REFRESH_TOKEN="<user-refresh-token>"
 export TAU_LOCAL_MODE=true
 export TAU_LOCAL_PROVIDER="<provider>"
 export TAU_LOCAL_MODEL="<model>"
@@ -28,12 +29,20 @@ export TAU_LOCAL_THINKING="<thinking-level>"
 uv run ms-tau
 ```
 
-Set `MAINSEQUENCE_ENDPOINT` only for a non-default platform endpoint. Local mode binds to
-`127.0.0.1:8787` by default. Treat an explicit public bind as privileged exposure: each accepted
-request can use the authenticated user's live Main Sequence permissions.
+The SDK looks for the CLI in `MAINSEQUENCE_CLI`, then beside the Python interpreter that runs
+`ms-tau`, then on `PATH`. Launchers and CI can export `MAINSEQUENCE_ACCESS_TOKEN` and
+`MAINSEQUENCE_REFRESH_TOKEN` instead. With both set, the SDK uses that pair and never runs the
+CLI. Do not add token lines to `.env`. A pair found there still works, but it is deprecated and
+startup logs a warning. `mainsequence refresh-token` run in that directory removes the lines.
+
+Set `MAINSEQUENCE_ENDPOINT` only for a non-default platform endpoint. The CLI session must be for
+the same endpoint. Local mode binds to `127.0.0.1:8787` by default. Treat an explicit public bind
+as privileged exposure: each accepted request can use the authenticated user's live Main Sequence
+permissions.
 
 Never place JWTs or provider credentials in source control, `.tau`, copied skills, command output,
-or debugging artifacts. The user JWT is sent only to Main Sequence. Main Sequence validates the
+or debugging artifacts. Do not run `mainsequence auth token` to read its output: it prints the
+access token. The user JWT is sent only to Main Sequence. Main Sequence validates the
 explicit `TAU_LOCAL_PROVIDER` and `TAU_LOCAL_MODEL`, returns provider-control evidence, and hydrates
 the provider credential used for inference. Provider secrets are neither environment settings nor
 local state.
@@ -45,7 +54,7 @@ local state.
 | Agent or AgentSession registration | Never created or updated |
 | Chat history, snapshots, leases, activity, and cancellation | Workspace SQLite |
 | Public A2A Message and Task state | Workspace SQLite |
-| Main Sequence authentication and token refresh | Remote, using the exported JWT pair |
+| Main Sequence authentication and token refresh | Remote. The token comes from the Main Sequence CLI session, or from an exported JWT pair |
 | Provider authorization, hydration, and inference | Remote and real |
 | Main Sequence MCP catalog and tool calls | Remote and real; platform mutations remain possible |
 | Project instructions, skills, hooks, and extensions | Normal repository `.tau` composition |
@@ -81,6 +90,16 @@ a platform AgentSession. Local mode supports:
   rescheduling safe unclaimed work and terminalizing stale uncertain work rather than replaying
   possible side effects.
 
+For a chat UI over `POST /api/chat`, do not read `runtime.sqlite3` or keep a browser-only
+transcript either. List sessions with `GET /api/local/v1/chat-sessions?limit=<n>&cursor=<opaque>`
+and hydrate one with `GET /api/local/v1/chat-sessions/{sessionUid}/history`. The history has the
+platform's `GET /api/v1/agent-sessions/{uid}/history/` shape, including reasoning, tool calls with
+results, and a running turn in `inProgressMessage`, so one reader serves local and deployed
+Agents. Reuse the listed `sessionUid` in `POST /api/chat`. A local chat turn keeps running when
+the client disconnects or reloads; stop it only with `POST /api/chat/session/cancel`, and queue a
+new message while a session is `working` (`POST /api/chat` returns 409 `session_busy`). Title the
+UI from `GET /api/local/v1/agent`, which reads the workspace's `.agents/agent_card.json`.
+
 For the default direct Message flow, do not read `runtime.sqlite3` or keep a browser-only source of
 truth. Discover conversations with `GET /api/local/v1/conversations?limit=<n>&cursor=<opaque>` and
 hydrate the latest bounded Message tail with
@@ -179,7 +198,8 @@ platform resources under the authenticated user's permissions.
 
 Check the process in this order:
 
-1. `GET /health` reports `mode: local` and safe composition diagnostics.
+1. `GET /health` reports `mode: local`, safe composition diagnostics, and
+   `mainsequence_auth_source`: `cli`, `environment`, or `env_file`.
 2. `GET /ready` confirms user authentication, provider control, local storage, and MCP readiness.
 3. `GET /version` reports the expected installed SDK release.
 4. A chat request without `sessionUid` returns an effective identifier in
@@ -193,8 +213,10 @@ Check the process in this order:
 ## Classify failures
 
 - Startup setting failure: inspect the exact missing or conflicting environment variable.
-- Authentication failure: refresh or re-export the JWT pair; do not substitute a runtime
-  credential in local mode.
+- Authentication failure: read the error, which names its remedy. The user runs
+  `mainsequence login`, upgrades a Main Sequence CLI that is too old for `auth token`, sets
+  `MAINSEQUENCE_CLI`, or provides the JWT pair. With an exported pair, export a fresh one. Do not
+  substitute a runtime credential in local mode.
 - Provider/model rejection: verify the exact configured names against the authenticated live
   catalog; do not silently select a different model.
 - OpenAI-compatible transport failure: open the Task's failure incident in Tau Board. Use its

{ms_tau_sdk-1.2.12.dev20 → ms_tau_sdk-1.2.13.dev22}/src/ms_tau_sdk/api/chat.py

@@ -95,11 +95,24 @@ async def chat(
             message_count=len(body.messages) if body.messages else None,
         ),
     )
+    # A local turn is recorded as a chat session and outlives this request, so a
+    # reload or a closed tab leaves it running; only session/cancel stops it. A
+    # managed turn stays bound to the request that streams it.
+    local_turn = (
+        await manager.start_local_chat_turn(session_uid, prompt, provenance=provenance)
+        if manager.settings.local_mode
+        else None
+    )
+    events = (
+        local_turn.events()
+        if local_turn is not None
+        else manager.prompt(session_uid, prompt, provenance=provenance)
+    )
 
     async def stream() -> AsyncIterator[bytes]:
         encoder = AssistantUiEncoder()
         try:
-            async for event in manager.prompt(session_uid, prompt, provenance=provenance):
+            async for event in events:
                 for payload in encoder.encode(event):
                     yield encoder.sse(payload)
             try:
@@ -107,9 +120,10 @@ async def chat(
                     yield encoder.sse(payload)
                 yield encoder.done()
             finally:
-                manager.mark_response_delivered(session_uid)
+                if local_turn is None:
+                    manager.mark_response_delivered(session_uid)
         except asyncio.CancelledError:
-            if not encoder.finished:
+            if local_turn is None and not encoder.finished:
                 await manager.cancel(session_uid)
             raise
         except Exception as error:
@@ -144,6 +158,9 @@ async def chat(
                     }
                 )
             yield encoder.done()
+        finally:
+            if local_turn is not None:
+                local_turn.detach()
 
     return StreamingResponse(
         stream(),

ms_tau_sdk-1.2.13.dev22/src/ms_tau_sdk/api/local_chat.py

@@ -0,0 +1,256 @@
+"""Reload-safe local `/api/chat` sessions and the local Agent's identity (ADR 0018)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Annotated, Any
+
+import structlog
+from fastapi import APIRouter, Depends, HTTPException, Query
+
+from ms_tau_sdk.backend.client import MainSequenceClient
+from ms_tau_sdk.backend.models import LocalChatSessionSummary
+from ms_tau_sdk.protocols.chat_history import (
+    HISTORY_VERSION,
+    HistoryMessage,
+    current_branch,
+    iso_timestamp,
+    latest_message_preview,
+    project_history,
+)
+from ms_tau_sdk.runtime.manager import SessionRuntimeManager
+from ms_tau_sdk.settings import TauSDKSettings
+
+from .dependencies import backend, runtime_manager, settings
+
+router = APIRouter(prefix="/api/local/v1")
+BackendDep = Annotated[MainSequenceClient, Depends(backend)]
+RuntimeManagerDep = Annotated[SessionRuntimeManager, Depends(runtime_manager)]
+SettingsDep = Annotated[TauSDKSettings, Depends(settings)]
+logger = structlog.get_logger(__name__)
+
+AGENT_CARD_PATH = Path(".agents") / "agent_card.json"
+LOCAL_AGENT_NAME = "Local Main Sequence TAU Agent"
+
+
+def _require_local(config: TauSDKSettings) -> None:
+    if not config.local_mode:
+        raise HTTPException(
+            status_code=409,
+            detail="Local chat sessions require TAU_LOCAL_MODE=true",
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class AgentIdentity:
+    name: str | None = None
+    description: str | None = None
+
+
+def _read_agent_identity(workspace: Path) -> AgentIdentity:
+    """Read the name and description of the workspace's `.agents/agent_card.json`.
+
+    The platform takes a deployed Agent's name and description from the same file.
+    A missing or unreadable card leaves both unset rather than inventing them.
+    """
+
+    path = workspace / AGENT_CARD_PATH
+    try:
+        card = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return AgentIdentity()
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error:
+        logger.warning(
+            "local_agent.card_unreadable",
+            message="The workspace Agent Card could not be read",
+            path=str(AGENT_CARD_PATH),
+            error_type=type(error).__name__,
+        )
+        return AgentIdentity()
+    if not isinstance(card, dict):
+        return AgentIdentity()
+
+    def text(key: str) -> str | None:
+        value = card.get(key)
+        return value.strip() if isinstance(value, str) and value.strip() else None
+
+    return AgentIdentity(name=text("name"), description=text("description"))
+
+
+async def workspace_agent_identity(workspace: Path) -> AgentIdentity:
+    return await asyncio.to_thread(_read_agent_identity, workspace)
+
+
+@dataclass(frozen=True, slots=True)
+class _SessionProjection:
+    summary: LocalChatSessionSummary
+    messages: list[HistoryMessage]
+    in_progress: HistoryMessage | None
+    status: str
+    error: str | None
+    updated_at: datetime
+
+
+async def _project_session(
+    client: MainSequenceClient,
+    manager: SessionRuntimeManager,
+    config: TauSDKSettings,
+    session_uid: str,
+) -> _SessionProjection:
+    """Project a session's durable branch plus the turn this process is running.
+
+    The running turn is read before the durable entries. If that turn committed in
+    between, its durable entries already hold everything the live view had.
+    """
+
+    live_turn = manager.live_turn(session_uid)
+    live_entries = live_turn.entries() if live_turn is not None else None
+    transcript = await client.get_local_chat_transcript(
+        session_uid,
+        turn_uid=live_turn.turn_uid if live_turn is not None else None,
+    )
+    if transcript.turn_committed:
+        live_entries = None
+    durable = [
+        item.entry
+        for item in transcript.entries
+        if live_entries is None or live_turn is None or item.turn_uid != live_turn.turn_uid
+    ]
+    branch = current_branch(durable)
+    projected = project_history(
+        [*branch, *(live_entries or [])],
+        target_agent_uid=config.local_agent_uid,
+    )
+    messages = projected.messages
+    in_progress: HistoryMessage | None = None
+    if (
+        live_entries is not None
+        and messages
+        and messages[-1]["role"] == "assistant"
+        and projected.source_indexes[-1] >= len(branch)
+    ):
+        # The running turn's newest assistant message, streaming or awaiting a tool.
+        in_progress = {**messages.pop(), "completedAt": None}
+    running = (
+        live_entries is not None
+        or transcript.session.working
+        or manager.local_session_running(session_uid)
+    )
+    status = "running" if running else ("error" if projected.last_turn_error else "completed")
+    updated_at = transcript.session.updated_at
+    if projected.last_timestamp is not None:
+        updated_at = max(updated_at, projected.last_timestamp)
+    return _SessionProjection(
+        summary=transcript.session,
+        messages=messages,
+        in_progress=in_progress,
+        status=status,
+        error=projected.last_turn_error if status == "error" else None,
+        updated_at=updated_at,
+    )
+
+
+def _session_summary(
+    summary: LocalChatSessionSummary,
+    *,
+    message_count: int,
+    latest_message_preview: str | None,
+    updated_at: datetime,
+    working: bool,
+) -> dict[str, Any]:
+    return {
+        "sessionUid": summary.session_uid,
+        "title": summary.title,
+        "messageCount": message_count,
+        "latestMessagePreview": latest_message_preview,
+        "createdAt": iso_timestamp(summary.created_at),
+        "updatedAt": iso_timestamp(updated_at),
+        "working": working,
+    }
+
+
+@router.get("/chat-sessions")
+async def list_chat_sessions(
+    client: BackendDep,
+    manager: RuntimeManagerDep,
+    config: SettingsDep,
+    limit: int = Query(default=50, ge=1, le=100),
+    cursor: str | None = Query(default=None, min_length=1, max_length=1024),
+) -> dict[str, Any]:
+    _require_local(config)
+    try:
+        page = await client.list_local_chat_sessions(limit=limit, cursor=cursor)
+    except ValueError as error:
+        raise HTTPException(status_code=400, detail=str(error)) from error
+    sessions: list[dict[str, Any]] = []
+    for summary in page.sessions:
+        if manager.live_turn(summary.session_uid) is None:
+            sessions.append(
+                _session_summary(
+                    summary,
+                    message_count=summary.message_count,
+                    latest_message_preview=summary.latest_message_preview,
+                    updated_at=summary.updated_at,
+                    working=(summary.working or manager.local_session_running(summary.session_uid)),
+                )
+            )
+            continue
+        projection = await _project_session(client, manager, config, summary.session_uid)
+        visible = [
+            *projection.messages,
+            *([projection.in_progress] if projection.in_progress is not None else []),
+        ]
+        sessions.append(
+            _session_summary(
+                summary,
+                message_count=len(visible),
+                latest_message_preview=latest_message_preview(visible),
+                updated_at=max(summary.updated_at, projection.updated_at),
+                working=projection.status == "running",
+            )
+        )
+    return {"sessions": sessions, "nextCursor": page.next_cursor}
+
+
+@router.get("/chat-sessions/{session_uid}/history")
+async def chat_session_history(
+    session_uid: str,
+    client: BackendDep,
+    manager: RuntimeManagerDep,
+    config: SettingsDep,
+) -> dict[str, Any]:
+    _require_local(config)
+    canonical = config.local_session_uid(session_uid)
+    projection = await _project_session(client, manager, config, canonical)
+    identity = await workspace_agent_identity(config.workspace)
+    return {
+        "version": HISTORY_VERSION,
+        "session": {
+            "sessionId": canonical,
+            "threadId": canonical,
+            "agentName": identity.name or LOCAL_AGENT_NAME,
+            "agentUid": config.local_agent_uid,
+            "agentSessionUid": canonical,
+            "status": projection.status,
+            "startedAt": iso_timestamp(projection.summary.created_at),
+            "updatedAt": iso_timestamp(projection.updated_at),
+            "error": projection.error,
+        },
+        "messages": projection.messages,
+        "inProgressMessage": projection.in_progress,
+    }
+
+
+@router.get("/agent")
+async def local_agent(config: SettingsDep) -> dict[str, str | None]:
+    _require_local(config)
+    identity = await workspace_agent_identity(config.workspace)
+    return {
+        "name": identity.name,
+        "displayName": identity.name,
+        "description": identity.description,
+    }