feat!: agent session persistence (#14143)

* agent session persistence

Co-authored-by: Tony Powell <apowell@arize.com>

* fix(ci): regenerate UI message stream fixtures for ai@7.0.58 (#15320)

The committed fixtures were generated against ai@7.0.48, but the lockfile
now resolves ai@7.0.58, so the fixture codegen check in Typescript CI
produced a diff. Only the upstreamTag provenance fields change.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

* fix: don't error in-flight client tool calls on transcript poll sync (#15321)

* fix: don't error in-flight client tool calls on transcript poll sync

While a pending client tool (e.g. execute_ui) is paused awaiting an
approval, the session poll can observe the mid-turn persisted transcript
tail, replace chat.messages, and run recoverPendingToolCalls — which was
designed for fresh page loads and classified every pending client call as
either rehydratable (re-dispatch) or stale (resolve with the "can't be
restored" error). That falsely errored calls whose script worker and
approval promise were still alive in this page.

partitionPendingClientToolCalls now takes an isToolCallInFlight predicate
and skips those calls entirely — a live handler owns its pending part. The
predicate comes from the client-tool timing recorder, which already
brackets every dispatch, via a new isInFlight method. Genuinely orphaned
calls (page reload, or after an interrupt resolves the run) are still
errored or rehydrated as before, and poll syncs no longer redundantly
re-dispatch in-flight rehydratable tools like ask_user.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: bake client tool timing metadata into the local transcript on resolution (#15326)

* fix: bake client tool timing metadata into the local transcript on resolution

A resend of an already-resolved client tool output is rejected (409
agent_session_tool_outputs_conflict) when it differs from the persisted
part, but the client could not always reproduce the persisted bytes:
enrichMessageWithClientToolMetadata stamps phoenix.clientStartedAt /
clientEndedAt onto the request payload only, never onto the local
chat.messages copy, and the per-turn timing recorder clears when the
turn completes. Any resend between turn completion and the next poll
sync (e.g. accepting an edit_prompt suggestion and immediately sending
a message, which re-carries the preceding assistant message's resolved
outputs) lacked the timing fields and read as a divergent result.

Write the recorder's timings back into the resolved part right after
chat.addToolOutput, using the same enrichment the wire payload gets, so
the local transcript stays byte-identical to what the server persists
and resends survive the recorder clearing.

The CLI needs no counterpart: it executes no client tools and never
submits toolOutputs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Tony Powell <apowell@arize.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

.agents/skills/phoenix-design/references/icons.md

@@ -20,6 +20,8 @@ Phoenix has a curated icon set in `app/src/components/core/icon/Icons.tsx`. Use
 | Video | `Icons.PlayCircle` | Video-typed file attachments (no dedicated `Video*` icon). |
 | Code-evaluator form | `Icons.Edit` | Task-role context pill for the code-evaluator create/edit form the user is working in. The edit glyph reads as an action, distinct from entity icons used by surface pills. |
 | Context (generic) | `Icons.Info` | Default for an `AttachmentContextData` whose category has no canonical icon yet. |
+| Chat (temporary) | `Icons.ChatEphemeralityOn` | A temporary conversation that is excluded from durable session history. The check communicates that ephemeral mode is enabled. |
+| Chat (saved) | `Icons.ChatEphemeralityOff` | A conversation retained in durable session history because ephemeral mode is disabled. |
 | Update / release notice | `Icons.Gift` | New-version notices and release prompts. |
 | Bypass / unguarded approvals | `Icons.Shield` | Warning shield for bypass/auto-approval modes where approvals are skipped. |
 | Undo / rewind | `Icons.RotateCcw` | Counterclockwise arrow for reverting/undoing an action (e.g. rewinding a chat). Distinct from `History` (clock = history/session list). |

.github/workflows/claude-weekly-deps-upgrade.yml

@@ -123,6 +123,7 @@ jobs:
           run gen-graphql         make graphql
           run gen-openapi         make openapi
           run gen-generative-ui   make schema-generative-ui
+          run gen-ui-reducer      make ui-message-stream-fixtures
           run python-format       make format-python
           run python-lint         make lint-python
           run python-typecheck    make typecheck-python
@@ -264,6 +265,7 @@ jobs:
               - `.scratch/verify/gen-graphql.log`
               - `.scratch/verify/gen-openapi.log`
               - `.scratch/verify/gen-generative-ui.log`
+              - `.scratch/verify/gen-ui-reducer.log`
               - `.scratch/verify/python-format.log`
               - `.scratch/verify/python-lint.log`
               - `.scratch/verify/python-typecheck.log`

.github/workflows/openapi-schema.yaml

@@ -25,17 +25,15 @@ jobs:
         env:
           BASE_REF: ${{ github.base_ref || github.event.before }}
         run: |
-          jq '.paths |= with_entries(select(.key | startswith("/agent") | not))' \
-            schemas/openapi.json > head.json
+          cp schemas/openapi.json head.json
           if [ -z "$BASE_REF" ]; then
             echo "::error::Could not determine base ref for OpenAPI schema comparison"
             exit 1
           fi
           git checkout "$BASE_REF"
       - name: Snapshot base schema
         run: |
-          jq '.paths |= with_entries(select(.key | startswith("/agent") | not))' \
-            schemas/openapi.json > base.json
+          cp schemas/openapi.json base.json
       - uses: docker://openapitools/openapi-diff@sha256:82291446e5554742d9c0725d7b315d18e93958c5526f9a663e8885227bdd6cb6 # latest
         with:
           args: --fail-on-incompatible base.json head.json

.github/workflows/typescript-CI.yml

@@ -33,6 +33,7 @@ jobs:
               - "app/**"
               - "schemas/openapi.json"
               - "src/phoenix/server/generative_ui/**"
+              - "tests/unit/server/agents/fixtures/ui_message_stream/**"
               - ".oxlintrc.json"
               - ".oxfmtrc.jsonc"
               - ".nvmrc"
@@ -85,6 +86,10 @@ jobs:
         run: |
           make schema-generative-ui
           git diff --exit-code
+      - name: UI Message Stream Fixture Codegen
+        run: |
+          make ui-message-stream-fixtures
+          git diff --exit-code
       - name: Test
         working-directory: ./app
         run: |

Makefile

@@ -32,7 +32,7 @@ NC := \033[0m # No Color
 .PHONY: help check-tools \
 	setup setup-remote-export install-python install-node \
 	graphql schema-graphql relay-build \
-	openapi schema-openapi schema-generative-ui codegen-python-client codegen-ts-client codegen-ts-app \
+	openapi schema-openapi schema-generative-ui ui-message-stream-fixtures codegen-python-client codegen-ts-client codegen-ts-app \
 	dev dev-backend dev-frontend dev-docker dev-mock-llm \
 	test test-python test-frontend test-ts test-helm test-jcs doctest typecheck typecheck-python typecheck-python-ty typecheck-frontend typecheck-ts \
 	format format-python format-frontend format-ts lint lint-python lint-frontend lint-ts clean-notebooks \
@@ -54,6 +54,7 @@ help: ## Show this help message
 	@echo -e "  relay-build            - Build Relay from existing schema"
 	@echo -e "  schema-openapi         - Generate OpenAPI schema only"
 	@echo -e "  schema-generative-ui   - Generate Generative UI catalog schema artifacts"
+	@echo -e "  ui-message-stream-fixtures - Generate AI SDK reducer conformance fixtures"
 	@echo -e "  codegen-python-client  - Generate Python client types from OpenAPI"
 	@echo -e "  codegen-ts-client      - Generate TypeScript client types from OpenAPI"
 	@echo -e "  codegen-ts-app         - Generate TypeScript OpenAPI types for frontend (app/)"
@@ -219,6 +220,11 @@ codegen-ts-client: ## Generate TypeScript client types from OpenAPI
 	@cd $(JS_DIR)/packages/phoenix-testing && $(PNPM) run --silent generate
 	@echo -e "$(GREEN)✓ Done$(NC)"
 
+codegen-ts-testing: ## Generate phoenix-testing TypeScript types from OpenAPI
+	@echo -e "$(CYAN)Generating phoenix-testing TypeScript types...$(NC)"
+	@cd $(JS_DIR)/packages/phoenix-testing && $(PNPM) run --silent generate
+	@echo -e "$(GREEN)✓ Done$(NC)"
+
 codegen-ts-app: ## Generate TypeScript OpenAPI types for app/
 	@echo -e "$(CYAN)Generating TypeScript OpenAPI types for app...$(NC)"
 	@cd $(APP_DIR) && $(PNPM) run --silent generate:openapi
@@ -229,7 +235,12 @@ schema-generative-ui: ## Generate generative UI catalog schema artifacts
 	@cd $(APP_DIR) && $(PNPM) run --silent generate:generative-ui-catalog
 	@echo -e "$(GREEN)✓ src/phoenix/server/generative_ui$(NC)"
 
-openapi: schema-openapi codegen-python-client codegen-ts-client codegen-ts-app ## Generate OpenAPI schema and all clients (full workflow)
+ui-message-stream-fixtures: ## Generate AI SDK UI-message reducer conformance fixtures
+	@echo -e "$(CYAN)Generating UI-message stream conformance fixtures...$(NC)"
+	@cd $(APP_DIR) && $(PNPM) run --silent generate:ui-message-stream-fixtures
+	@echo -e "$(GREEN)✓ tests/unit/server/agents/fixtures/ui_message_stream$(NC)"
+
+openapi: schema-openapi codegen-python-client codegen-ts-client codegen-ts-testing codegen-ts-app ## Generate OpenAPI schema and all clients (full workflow)
 	@echo -e "$(GREEN)✓ OpenAPI schema workflow complete$(NC)"
 
 #=============================================================================

app/package.json

@@ -24,6 +24,7 @@
     "fmt:check": "oxfmt --check --config ../.oxfmtrc.jsonc",
     "generate:generative-ui-catalog": "tsx scripts/generate-generative-ui-catalog.ts",
     "generate:openapi": "openapi-typescript --empty-objects-unknown=true --default-non-nullable=false ../schemas/openapi.json -o ./src/api/__generated__/v1.ts",
+    "generate:ui-message-stream-fixtures": "tsx scripts/generate-ui-message-stream-fixtures.ts",
     "lint": "oxlint",
     "lint:fix": "oxlint --fix",
     "preinstall": "npx only-allow pnpm",
@@ -84,7 +85,6 @@
     "d3-format": "^3.1.2",
     "d3-scale-chromatic": "^3.1.0",
     "date-fns": "^4.4.0",
-    "just-bash": "^2.14.5",
     "lodash": "^4.18.1",
     "motion": "^12.43.0",
     "mustache": "^4.2.0",