feat(frontend): agent playground sessions, files, and inspector

SESSIONS_BACKEND_QUESTIONS.md

@@ -0,0 +1,109 @@
+# Sessions FE ↔ Backend — points to align on
+
+Tags: **🔴 BLOCKER** (FE can't proceed) · **🟡 CONFIRM** (FE can build once the contract is agreed).
+Ordered by how much FE work each unblocks.
+
+## Framing
+
+PR #4916 shipped the durable **read** plane (transcripts) live — FE step 1 (server-backed
+history) is wired and working. The **control** planes (interactions/HITL, streams/live-run)
+are scaffolded in the API but **not wired to the runner**, so the FE-side API surface is
+built and parked. The points below are what it takes to light those up.
+
+## A. Transcripts (read plane) — LIVE 🟡 confirm contract
+
+1. **Payload stability** — is `payload` guaranteed 1:1 with the ACP `AgentEvent` union
+   (`services/agent/src/protocol.ts`)? Any event types the FE should expect that aren't in
+   that union?
+2. **Ordering & pagination** — is `queryTranscripts` always ordered ascending by uuid7
+   `id`? `SessionTranscriptQueryRequest` only has `session_id` — is there a result cap /
+   cursor for long sessions, or does it return the whole log?
+3. **`sender` values** — confirm the exact set (`user` / `runner` / `system`?). FE groups
+   messages by this.
+4. **User-turn persistence** — is the user's *own* message persisted as a transcript event
+   (`sender=user`), and with what payload shape (plain text? multimodal/files)? Determines
+   how we replay user turns.
+5. **Deltas vs coalesced** — does the transcript store `message_start/delta/end` rows or
+   only the coalesced `message`? (FE handles both; just want to know.)
+6. **64KB truncation** — payloads over the cap become `{"_truncated": true}`. How should
+   the FE render a truncated event?
+
+## B. State / resume — runner-owned 🟡 confirm division of labor
+
+7. Confirm FE treats `/sessions/states` as **read-only** (only `getState` for sandbox
+   awareness) and must **never** `setState(data)` (it'd clobber the runner's
+   `SessionRecord`). Correct?
+8. Is sandbox **resume fully automatic** by `session_id` once a run goes through the runner
+   — i.e. the FE does nothing? Or is there anything FE-side (e.g. `setStateSandboxId`)?
+9. Is there a state value worth surfacing in the UI (e.g. "sandbox alive")?
+
+## C. Interactions / HITL — INCOMPLETE 🔴 blockers
+
+10. **🔴 Rows aren't created** — the runner emits `interaction_request` to the transcript
+    but does **not** create a `SessionInteraction` row, so `queryInteractions` is empty for
+    real runs. Who creates the row, and when (should be on park)?
+11. **🔴 Respond doesn't transition status** — `respondInteraction` enqueues a re-invoke but
+    leaves `status.code = pending` forever (only the admin `transition` endpoint flips it).
+    Should respond transition pending→resolved/denied?
+12. **ID correlation** — transcript `interaction_request.id` appears to map to
+    `SessionInteraction.token`, not `.id` (unique on `project+session+token`). Confirm the
+    intended FE flow: query by token → respond by row id? Or will the transcript event carry
+    the interaction row id directly?
+13. **Answer shape** — `respondInteraction.answer` is an unvalidated `Dict`. What exact
+    shape for approve vs deny (`{approved: true/false}`?), and is there an **"always allow"**
+    option — where is it stored/honored on resume?
+14. **Resume-after-respond** — responding does **not** continue the run inline; does the FE
+    then call `invokeStream`? Confirm the intended sequence (and whether it only applies to
+    the streams path).
+15. **Scope** — confirm v1 = `user_approval` only; FE keeps `user_input`/`tool_call` gated
+    off.
+
+## D. Streams / live run — STUB 🔴 biggest blocker
+
+16. **🔴 invoke is a stub** — `SessionStreamsService.invoke`/`_start_run`
+    (`api/oss/src/core/sessions/streams/service.py`) only acquires Redis locks + writes a
+    `SessionStream`/`session_runners` row; it **does not invoke the runner** and streams
+    nothing.
+17. **🔴 No stream-return path** — there's **no SSE/attach endpoint** delivering v6 chunks.
+    The "watch live run" path is unspecified + NOT STARTED
+    (`docs/designs/sessions/streams/tasks.md`). **What's the planned transport** — a
+    `GET /sessions/streams/attach` returning `text/event-stream` v6 chunks? WebSocket? The
+    FE `useChat` transport needs a `request → streamed-response`, so we need the endpoint +
+    content-type.
+18. **Replace vs complement** — the FE currently streams fine from the **runner** service
+    (`/api/agent/chat`). Does the streams model **replace** that, or is it
+    **invoke = coordination** layered on top of the existing runner stream? This decides
+    whether step 4 is a transport rewire or just adding force/attach/detach/liveness around
+    the current path.
+19. **Mode semantics** — when wired, what should the FE do per
+    `SessionInvokeResponseModel.mode` (`send`/`steer`/`cancel`/`attach`/`detach`) and for
+    `force`/`detached`?
+20. **Timeline** — the brief frames streams as the multi-replica-correct path; what's the
+    rough sequencing for 16–18?
+
+## E. Cross-device session discovery 🟡
+
+21. FE history (the picker) is localStorage-only, so a session this browser never ran won't
+    appear. Transcripts is per-session (no list). Is there / will there be a
+    **sessions-list endpoint** (by project/app), or should FE keep using the observability
+    `ag.session.id`-off-traces aggregation? Align on the canonical "list sessions" source.
+
+## F. Mounts (step 5) 🟡
+
+22. Is `client.mounts.*` (agent working-dir file CRUD) actually live/wired, and what's the
+    priority? (FE panel is optional/last.)
+
+## G. Process / verification 🟡
+
+23. What's the canonical way to get a **populated local env** — which compose profile +
+    entrypoints (e.g. `worker_transcripts`) must be running for `queryTranscripts` to return
+    rows? Several endpoints depend on a runner/worker rebuild.
+24. The design docs are labelled "draft / not implemented." Can they be marked with **what's
+    actually live** so the FE has a contract source of truth?
+
+## What the FE already has ready
+
+The full `@agenta/entities/session` surface — `querySessionTranscripts` (in use), plus
+parked `getSessionState`, `queryInteractions` / `fetchInteraction` / `respondInteraction`,
+and `queryStreams` / `getStreamLiveness` / `invokeSessionStream` — all matching the
+generated client, ready to wire the day each plane lands.

SESSIONS_FE_BRIEF.md

@@ -0,0 +1,81 @@
+# Frontend brief — wire the durable Sessions API into agent chat
+
+## 0. Where you are
+- **Worktree:** `/Users/ardaerzin/Documents/GitHub/agenta_open_source/.claude/worktrees/big-agents-sessions`
+- **Branch:** `big-agents-add-sessions` = `origin/big-agents` + a clean merge of PR #4916 (`feat/add-sessions`).
+- Read `web/AGENTS.md` and the `agenta-package-practices` skill before writing code. Frontend is a pnpm monorepo (Node ≥ 22.13; use Node 24). Run `pnpm lint-fix` in `web/` before committing.
+
+## 1. What PR #4916 actually shipped (read this first)
+It is ~95% **backend + generated client**, almost no FE feature code:
+- New API domains under `api/oss/src/.../sessions/{states,streams,transcripts,interactions}` + standalone `mounts`.
+- The **Fern-generated TS client** for them in `@agentaai/api-client` — this is your entire FE-facing surface. Nothing consumes it yet.
+- Design docs in `docs/designs/sessions/` (states / streams / transcripts / interactions) and `docs/designs/mounts/`. **These docs are labelled "draft for discussion / not implemented"** — treat them as intent, and **verify the actual backend wiring is live before building UI on an endpoint** (esp. transcripts ingest worker, interactions beyond `user_approval`). v1 of interactions implements **`user_approval` only**; `user_input` and `tool_call` exist in the schema but are not wired.
+
+So your job is **integration**, not greenfield: connect the existing agent-chat FE (today localStorage-only) to these durable endpoints.
+
+## 2. The new API surface (`@agentaai/api-client` via `getAgentaSdkClient()`)
+Get the client the standard way (mirror `web/packages/agenta-entities/src/trace/api/client.ts`):
+```ts
+import {getAgentaSdkClient} from "@agenta/sdk"
+const sessions = getAgentaSdkClient().sessions
+const mounts   = getAgentaSdkClient().mounts
+```
+**Project/app scope ALWAYS rides queryParams, never the body** (standing rule, see `projectScopedRequest` in the trace client): pass `{queryParams: {project_id, application_id}, abortSignal}` as the per-request options arg. Fern methods **throw `AgentaApiError` on non-2xx** — wrap at the boundary.
+
+### `client.sessions.*`
+| Method | Endpoint | Purpose |
+|---|---|---|
+| `invokeStream({session_id, prompt?, force?, detached?})` | POST `/sessions/streams/invoke` | **Start/resume a live run.** `force` steals the run lock; `detached` = fire-and-forget (no held connection). |
+| `queryStreams({session_id?, sandbox_live?})` | POST `/sessions/streams/query` | List live stream handles (who's running / attached / sandbox alive). |
+| `getLiveness(...)` | GET `/sessions/streams/liveness` | Is a session's run currently alive. |
+| `queryTranscripts({session_id})` | POST `/sessions/transcripts/query` | **Durable, append-only event log = the replay source for rendering a conversation.** |
+| `getTranscriptEvent({event_id})` | GET `/sessions/transcripts/{event_id}` | One event by id. |
+| `getState({session_id})` / `setState({session_id, data, sandbox_id})` | GET/POST `/sessions/states/{session_id}` | Durable SDK `SessionRecord` (opaque JSON) + sandbox resume pointer. |
+| `setStateSandboxId(...)` | POST `/sessions/states/{session_id}/sandbox-id` | Update just the resume pointer. |
+| `queryInteractions({query, windowing})` | POST `/sessions/interactions/query` | List HITL requests (pending approvals etc.). |
+| `fetchInteraction({interaction_id})` | GET `/sessions/interactions/{interaction_id}` | One interaction. |
+| `respondInteraction({interaction_id, answer})` | POST `/sessions/interactions/{interaction_id}/respond` | **Resolve a HITL request** (approve/deny/input/tool-result). |
+| `querySessionMounts({...})` | POST `/sessions/mounts/query` | Session-scoped view of mounts. |
+
+### `client.mounts.*` (agent working-directory files)
+`queryMounts`, `createMount`, `fetchMount`, `editMount`, `archiveMount`/`unarchiveMount`, plus file ops `getMountFiles`, `uploadMountFile`, `writeMountFile`, `deleteMountFile`, `createMountFolder`.
+
+### Key entity shapes (all under `AgentaApi.*` from the client)
+- **`SessionTranscript`**: `{id, session_id, project_id, event_index?, sender?, session_update?, payload?, created_at?}` — `payload` is the ACP event (text / tool_call / result). This is what you map → chat messages.
+- **`SessionState`**: `{session_id, data (opaque SessionRecord JSON), sandbox_id?}`.
+- **`SessionStream`**: `{id, session_id, attached?, sandbox_live?, last_seen_at?, status:{code, message}}`. `StreamStatusCode = Running | Detached | Idle | Ended`.
+- **`SessionInteraction`**: `{id, session_id, run_id?, token, kind, status?, data}`. `kind = user_approval | user_input | tool_call`. `status = pending | resolved | denied | cancelled`. `data = {request, references, selector, resolution}`.
+- **`SessionMount` / `Mount`**: `{id, session_id, project_id, data: MountData, flags}`.
+
+**Consistency model to respect:** the **transcript renders the question** (append-only, replayable); the **interaction record holds the answer-state** (is it still actionable + what was answered). Don't render HITL from the interactions table — render from the transcript, and use interactions to know if it's still pending/resolved.
+
+## 3. The existing FE you're wiring into — `web/oss/src/components/AgentChatSlice/`
+Today this slice is **localStorage-only** with an **ephemeral runner transport**. Files that matter:
+- `state/sessions.ts` — the multi-session model. HISTORY (`sessionsByAppAtom`) vs OPEN TABS (`openIdsByAppAtom`) vs messages (`sessionMessagesAtom`), all `atomWithStorage` (localStorage), **scope-keyed** (app id, or `drawer:<entityId>` for the create/edit drawer — see `state/scope.tsx`). Messages keyed by globally-unique session id.
+- `assets/loadSession.ts` — **the hydration seam.** `loadSessionMessages(sessionId)` returns `null` today. Its docstring still points at the **old** `/services/agent/v0/load-session` endpoint — that is now **superseded** by `client.sessions.queryTranscripts({session_id})`. This is the single cleanest place to light up server-backed history.
+- `assets/transport.ts` + `assets/AgentChatTransport.ts` — the `useChat` (AI SDK v6) transports. Today they POST the agent-protocol envelope to the runner and stream a v6 UI Message Stream; `AgentChatTransport` also handles a batch→one-shot replay. The live run currently does **not** go through `/sessions/streams/invoke`.
+- `assets/toAgentaMessage.ts`, `assets/trace.ts`, `assets/rewind.ts`, `assets/files.ts`, `assets/attachments.ts` — message adaptation, trace stamping, edit/rewind, inline `data:` file attachments.
+- `components/SessionHistoryMenu.tsx` — the clock-icon history picker (already shipped, localStorage-backed). `components/AgentChatConversation.tsx`, `AgentMessage.tsx`, `ToolActivity.tsx`, `QueuedMessages.tsx` — render surface. `hooks/useAgentChatQueue.ts` — send queue.
+- Pages: `web/oss/src/pages/.../apps/[app_id]/agent-chat/index.tsx` (standalone) and the playground panel `AgentChatPanel.tsx`.
+
+Separately, observability already has a **read-only** session viewer (`web/oss/src/components/SharedDrawers/SessionDrawer/`, `components/pages/observability/components/SessionsTable/`) that lists sessions by aggregating `ag.session.id` off traces. That's a different surface — don't conflate it; but the new transcripts API could eventually back its message panel too.
+
+## 4. Suggested work order (each is independently shippable)
+1. **Server-backed history (highest value, smallest change).** Implement `loadSessionMessages` against `client.sessions.queryTranscripts({session_id})`: map `SessionTranscript.payload` events → v6 `UIMessage[]` (reuse the vercel/`toAgentaMessage` adapters). Caller already writes the result into `sessionMessagesAtom` before opening the tab. This makes open-from-deep-link / open-from-trace render conversations this browser never ran. **Confirm the transcript ingest worker is actually populating rows first** — if empty, this is a no-op.
+2. **Session state / resume.** On session open, `getState` to restore the SDK record + `sandbox_id`; persist via `setState` so a run can resume the same sandbox across reloads/devices. Decide the localStorage-vs-server source-of-truth merge (server wins when present; localStorage is the offline fallback — keep the existing fallback semantics).
+3. **HITL interactions.** When the transcript renders an `interaction_request`, cross-check `queryInteractions`/`fetchInteraction` for live status, and wire the approve/deny control to `respondInteraction({interaction_id, answer})`. Scope v1 to `user_approval` (deny/allow, maybe "always"); leave `user_input`/`tool_call` stubbed behind a flag. Build it as a derived view over the transcript, not a second source of truth.
+4. **Live run via streams (bigger).** Move the live send from the current runner transport onto `/sessions/streams/invoke` (+ `queryStreams`/`getLiveness` for attach/detach/“someone else is running this” state, and `force` to steal). This is the multi-replica-correct path; verify the backend stream endpoint is live and returns the v6 chunk stream the transport expects before committing to it.
+5. **Mounts / files (optional, last).** A file panel over `client.mounts.*` for the agent working directory.
+
+## 5. Conventions (enforced — see memory/AGENTS)
+- **Fern client only** (`@agentaai/api-client` via `getAgentaSdkClient()`), never axios, for all new API code.
+- Package vs app placement per `agenta-package-practices`. New shared session entity logic likely belongs in a `@agenta/entities`-style package (mirror `trace/api/`), not in `web/oss`. OSS lint **blocks re-exporting `@agenta/*` from app barrels**.
+- **Text size 12px (`text-xs`)**, never `text-sm`. **No `size="small"`** on antd controls. Dark mode: use **antd semantic tokens** (`--ag-colorText`, `--ag-colorBorder`, …); `dark:` / `bg-gray-*` / fixed hex are no-ops here.
+- Thin-references pattern: query caches store IDs, the molecule/atom is the source of truth.
+- Don't put `project_id`/`application_id` in request bodies — queryParams only.
+- Before commit: `pnpm lint-fix` in `web/`; run the **oss tsc** manually (relocations can mask new errors — gate on an error-signature diff, not a count).
+- Commit messages: no "Claude"/Anthropic/`Co-Authored-By`.
+
+## 6. Verify before asserting done
+- The fastest reality check is whether the endpoints return data: hit `queryTranscripts` / `queryStreams` / `queryInteractions` for a real session id and confirm non-empty, correctly-shaped responses. Several of these depend on a runner/worker rebuild that may not be running locally.
+- Use the `verify` skill / run the app rather than trusting types — the generated client compiles regardless of whether the backend route is wired.

api/oss/src/core/mounts/dtos.py

@@ -60,6 +60,9 @@ class MountFile(BaseModel):
     path: str
     size: int = 0
     is_folder: bool = False
+    # Object-store LastModified as epoch milliseconds; None when the store omits it. Lets the UI
+    # order files by recency regardless of how they were created (bash, Write tool, upload).
+    mtime: Optional[int] = None
 
 
 class MountFileList(BaseModel):

api/oss/src/core/mounts/service.py

@@ -451,15 +451,16 @@ async def list_files(
         mount_base = base + "/"
         files: List[MountFile] = []
         folders: set[str] = set()
-        for key, size in objects:
+        for obj in objects:
+            key = obj.key
             rel = key[len(mount_base) :] if key.startswith(mount_base) else key
             # Hide bare trailing-slash marker objects (empty-folder markers).
             if key.endswith("/"):
                 folder_rel = rel.rstrip("/")
                 if folder_rel:
                     folders.add(folder_rel)
                 continue
-            files.append(MountFile(path=rel, size=size))
+            files.append(MountFile(path=rel, size=obj.size, mtime=obj.mtime))
 
         existing = {f.path for f in files}
         for folder_rel in sorted(folders):
@@ -559,14 +560,14 @@ async def delete_path(
             bucket=bucket,
             prefix=folder_prefix,
         )
-        keys = [key for key, _ in objects]
+        keys = [obj.key for obj in objects]
 
         # The exact file (or the folder marker) may also exist alongside contents.
         single = await self.mounts_store.list_objects_v2(
             bucket=bucket,
             prefix=exact_key,
         )
-        if any(key == exact_key for key, _ in single):
+        if any(obj.key == exact_key for obj in single):
             keys.append(exact_key)
 
         unique_keys = list(dict.fromkeys(keys))

api/oss/src/core/store/dtos.py

@@ -0,0 +1,12 @@
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class StoreObject(BaseModel):
+    """One object listed from the store: its key, byte size, and LastModified as epoch
+    milliseconds (None when the store omits it)."""
+
+    key: str
+    size: int = 0
+    mtime: Optional[int] = None