prompt_objects 0.5.0 → 0.7.0

data/lib/prompt_objects/server/api/routes.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "rack"
+require "yaml"
 
 module PromptObjects
   module Server
@@ -11,11 +12,27 @@ module PromptObjects
       class Routes
         def initialize(runtime)
           @runtime = runtime
+          if runtime.session_store
+            @workspace_repository = Repositories::WorkspaceSessionRepository.new(runtime.session_store)
+            @thread_repository = Repositories::ThreadRepository.new(runtime.session_store)
+            @run_repository = Repositories::RunRepository.new(runtime.session_store)
+            @message_repository = Repositories::MessageRepository.new(runtime.session_store)
+            @event_repository = Repositories::EventRepository.new(runtime.session_store)
+            @artifact_repository = Repositories::ArtifactRepository.new(runtime.session_store)
+            @env_data_repository = Repositories::EnvDataRepository.new(runtime.session_store)
+            @run_trace_builder = Operations::RunTraceBuilder.new(runtime.session_store)
+          end
         end
 
         def call(env)
           request = Rack::Request.new(env)
-          path = request.path_info.sub("/api", "")
+          # Falcon delivers PATH_INFO as ASCII-8BIT. SQLite binds binary strings
+          # as BLOBs, which never compare equal to TEXT columns — so any keyed
+          # lookup from a URL path (artifacts, sessions) would silently miss.
+          # Normalize to UTF-8 before routing.
+          path = request.path_info.dup.force_encoding(Encoding::UTF_8)
+          path = path.scrub unless path.valid_encoding?
+          path = path.sub("/api", "")
 
           response = route(request, path)
           json_response(response)
@@ -42,6 +59,8 @@ module PromptObjects
           case path
           when "/environment"
             get_environment
+          when "/diagnostics"
+            @runtime.operational_diagnostics
           when "/prompt_objects"
             list_prompt_objects
           when "/primitives"
@@ -56,8 +75,38 @@ module PromptObjects
             list_sessions($1)
           when %r{^/prompt_objects/([^/]+)$}
             get_prompt_object($1)
+          when "/sessions"
+            get_environment_sessions
+          when "/workspaces"
+            list_workspaces
+          when %r{^/workspaces/([^/]+)/snapshot$}
+            get_workspace_snapshot($1)
+          when %r{^/workspaces/([^/]+)/threads$}
+            list_runtime_threads($1, _request)
+          when %r{^/workspaces/([^/]+)/runs$}
+            list_runtime_runs($1, _request)
+          when %r{^/workspaces/([^/]+)/events$}
+            list_workspace_events($1, _request)
+          when %r{^/workspaces/([^/]+)/artifacts$}
+            list_runtime_artifacts($1)
+          when %r{^/workspaces/([^/]+)/env_data$}
+            list_runtime_env_data($1)
+          when %r{^/threads/([^/]+)/messages$}
+            list_runtime_messages($1, _request)
+          when %r{^/threads/([^/]+)$}
+            get_runtime_thread($1)
+          when %r{^/runs/([^/]+)/events$}
+            list_run_events($1, _request)
+          when %r{^/runs/([^/]+)/trace$}
+            get_run_trace($1)
+          when %r{^/runs/([^/]+)$}
+            get_runtime_run($1)
           when %r{^/events/session/([^/]+)$}
             get_session_events($1)
+          when %r{^/artifacts/([^/]+)$}
+            get_artifact($1)
+          when %r{^/sessions/([^/]+)/env_data$}
+            get_session_env_data($1)
           when %r{^/sessions/([^/]+)/usage$}
             get_session_usage($1, _request)
           when %r{^/sessions/([^/]+)/export$}
@@ -69,12 +118,32 @@ module PromptObjects
 
         def route_post(request, path)
           case path
+          when "/messages"
+            inject_message(request.body.read)
           when "/prompt_objects"
             create_prompt_object(request.body.read)
           when %r{^/prompt_objects/([^/]+)/message$}
             send_message($1, request.body.read)
           when %r{^/prompt_objects/([^/]+)/sessions$}
             create_session($1, request.body.read)
+          when "/sessions"
+            create_environment_session_endpoint(request.body.read)
+          when %r{^/sessions/([^/]+)/activate$}
+            activate_session($1)
+          when %r{^/sessions/([^/]+)/rename$}
+            rename_session_endpoint($1, request.body.read)
+          when %r{^/sessions/([^/]+)/delete$}
+            delete_session_endpoint($1)
+          when %r{^/artifacts/([^/]+)/message$}
+            artifact_message($1, request.body.read)
+          when %r{^/runs/([^/]+)/cancel$}
+            cancel_runtime_run($1, request.body.read)
+          when %r{^/workspaces/([^/]+)/threads$}
+            create_runtime_thread($1, request.body.read)
+          when %r{^/threads/([^/]+)/rename$}
+            rename_runtime_thread($1, request.body.read)
+          when %r{^/threads/([^/]+)/archive$}
+            archive_runtime_thread($1)
           else
             { error: "Not found", path: path }
           end
@@ -122,13 +191,89 @@ module PromptObjects
           po_full(po)
         end
 
+        # POST /api/prompt_objects — create a new Prompt-Object from JSON.
+        # Body: { name, description, capabilities?, identity?, behavior? }
+        # Mirrors the create_capability universal: writes a .md and loads it.
         def create_prompt_object(body)
-          # TODO: Implement PO creation via API
-          { error: "Not implemented" }
+          params = JSON.parse(body)
+          name = params["name"].to_s
+          description = params["description"].to_s
+          capabilities = params["capabilities"] || []
+          identity = params["identity"] || "You are a helpful prompt object."
+          behavior = params["behavior"] || "Help with the request."
+
+          return { error: "name is required" } if name.empty?
+          unless name.match?(/\A[a-z][a-z0-9_]*\z/)
+            return { error: "name must be lowercase letters, numbers, and underscores, starting with a letter" }
+          end
+          return { error: "A capability named '#{name}' already exists" } if @runtime.registry.exists?(name)
+          return { error: "No objects directory available" } unless @runtime.objects_dir
+
+          frontmatter = { "name" => name, "description" => description, "capabilities" => capabilities }
+          body_md = <<~MD
+            # #{name.split('_').map(&:capitalize).join(' ')}
+
+            ## Identity
+
+            #{identity}
+
+            ## Behavior
+
+            #{behavior}
+          MD
+          content = "#{frontmatter.to_yaml}---\n\n#{body_md}"
+
+          path = File.join(@runtime.objects_dir, "#{name}.md")
+          File.write(path, content, encoding: "UTF-8")
+          po = @runtime.load_prompt_object(path)
+
+          po_summary(po)
+        rescue JSON::ParserError
+          { error: "Invalid JSON body" }
+        rescue => e
+          { error: e.message }
         end
 
         # === Messages ===
 
+        # POST /api/messages — Universal message injection endpoint.
+        # External systems (webhooks, cron, bots) use this to trigger POs.
+        # Uses runtime.inject_message — same code path as human/timer messages.
+        def inject_message(body)
+          params = JSON.parse(body)
+          target_po = params["target_po"]
+          content = params["content"]
+          from_source = params["from_source"] || "api"
+
+          return { error: "target_po is required" } unless target_po && !target_po.empty?
+          return { error: "content is required" } unless content && !content.empty?
+
+          run, response = @runtime.execute_message_run(
+            target_po: target_po,
+            content: content,
+            from_source: from_source,
+            workspace_session_id: params["workspace_session_id"],
+            thread_id: params["thread_id"],
+            client_request_id: params["client_request_id"],
+            deadline: params["deadline"],
+            tui_mode: false
+          )
+          {
+            response: response,
+            run_id: run.id,
+            thread_id: run.thread_id,
+            workspace_session_id: run.workspace_session_id,
+            status: run.status,
+            target_po: target_po,
+            from_source: from_source
+          }
+        rescue JSON::ParserError
+          { error: "Invalid JSON body" }
+        rescue PromptObjects::Error => e
+          { error: e.message }
+        end
+
+        # POST /api/prompt_objects/:name/message — Legacy per-PO message endpoint.
         def send_message(po_name, body)
           po = @runtime.registry.get(po_name)
 
@@ -138,50 +283,76 @@ module PromptObjects
 
           params = JSON.parse(body)
           message = params["message"]
-          session_id = params["session_id"]
           new_thread = params["new_thread"]
 
           return { error: "Message is required" } unless message && !message.empty?
 
-          # Create a new thread if requested
+          workspace_id = params["workspace_session_id"] || @runtime.active_session(initiated_by: "api")[:id]
+          thread_id = params["thread_id"] || params["session_id"]
           if new_thread
-            session_id = po.new_thread
+            thread_id = @runtime.create_runtime_thread(
+              workspace_session_id: workspace_id,
+              po_name: po_name,
+              thread_type: "api",
+              name: params["name"]
+            ).id
           end
-
-          # Switch to specified session if provided
-          if session_id && session_id != po.session_id
-            po.switch_session(session_id)
-          end
-
-          request_session_id = po.session_id
-
-          # Send the message through the same path as WebSocket
-          context = @runtime.context(tui_mode: false)
-          context.current_capability = "human"
-
-          # Log to bus
-          @runtime.bus.publish(from: "human", to: po.name, message: message, session_id: request_session_id)
-
-          response = po.receive(message, context: context)
-
-          # Log response to bus
-          @runtime.bus.publish(from: po.name, to: "human", message: response, session_id: request_session_id)
-
-          # Count events for this session
-          event_count = if @runtime.session_store
-            @runtime.session_store.get_events(session_id: request_session_id).length
-          end
-
+          run, response = @runtime.execute_message_run(
+            target_po: po_name,
+            content: message,
+            from_source: params["from_source"] || "api",
+            workspace_session_id: workspace_id,
+            thread_id: thread_id,
+            client_request_id: params["client_request_id"],
+            deadline: params["deadline"],
+            tui_mode: false
+          )
           {
             response: response,
-            po_name: po.name,
-            session_id: request_session_id,
-            event_count: event_count
+            po_name: po_name,
+            session_id: run.thread_id,
+            thread_id: run.thread_id,
+            run_id: run.id,
+            workspace_session_id: run.workspace_session_id,
+            status: run.status,
+            event_count: @event_repository.run_events(run_id: run.id).length
           }
         rescue JSON::ParserError
           { error: "Invalid JSON body" }
         end
 
+        def cancel_runtime_run(run_id, body)
+          params = body.to_s.empty? ? {} : JSON.parse(body)
+          cancelled = @runtime.cancel_run(run_id, reason: params["reason"] || "api request")
+          { run_id: run_id, cancelled: cancelled }
+        rescue JSON::ParserError
+          { error: "Invalid JSON body" }
+        end
+
+        def create_runtime_thread(workspace_id, body)
+          params = JSON.parse(body)
+          thread = @runtime.create_runtime_thread(
+            workspace_session_id: workspace_id,
+            po_name: params["po_name"],
+            thread_type: params["thread_type"] || "human",
+            name: params["name"]
+          )
+          serialize_record(thread)
+        rescue JSON::ParserError
+          { error: "Invalid JSON body" }
+        end
+
+        def rename_runtime_thread(thread_id, body)
+          params = JSON.parse(body)
+          serialize_record(@runtime.rename_runtime_thread(thread_id, name: params["name"]))
+        rescue JSON::ParserError
+          { error: "Invalid JSON body" }
+        end
+
+        def archive_runtime_thread(thread_id)
+          serialize_record(@runtime.archive_runtime_thread(thread_id))
+        end
+
         # === Sessions ===
 
         def list_sessions(po_name)
@@ -191,9 +362,12 @@ module PromptObjects
             return { error: "Not found", name: po_name }
           end
 
-          sessions = po.list_sessions.map do |s|
-            PromptObject.serialize_session(s)
-          end
+          workspace_id = @runtime.active_session(initiated_by: "api")[:id]
+          sessions = @thread_repository.list(
+            workspace_session_id: workspace_id,
+            po_name: po_name,
+            include_archived: true
+          ).map { |thread| serialize_record(thread) }
 
           { sessions: sessions }
         end
@@ -205,23 +379,19 @@ module PromptObjects
             return { error: "Prompt object not found", name: po_name }
           end
 
-          return { error: "No session store" } unless @runtime.session_store
-
-          session = @runtime.session_store.get_session(session_id)
-
-          unless session && session[:po_name] == po_name
+          thread = @thread_repository.get(session_id)
+          unless thread && thread.po_name == po_name
             return { error: "Session not found", id: session_id }
           end
-
-          messages = @runtime.session_store.get_messages(session_id)
+          messages = @message_repository.list(thread_id: session_id, limit: 10_000)
 
           {
-            id: session[:id],
-            name: session[:name],
-            po_name: session[:po_name],
+            id: thread.id,
+            name: thread.name,
+            po_name: thread.po_name,
             messages: messages.map { |m| format_message(m) },
-            created_at: session[:created_at]&.iso8601,
-            updated_at: session[:updated_at]&.iso8601
+            created_at: thread.created_at&.iso8601,
+            updated_at: thread.updated_at&.iso8601
           }
         end
 
@@ -235,15 +405,173 @@ module PromptObjects
           params = body.empty? ? {} : JSON.parse(body)
           session_name = params["name"]
 
-          session_id = po.new_session(name: session_name)
+          workspace_id = params["workspace_session_id"] || @runtime.active_session(initiated_by: "api")[:id]
+          thread = @runtime.create_runtime_thread(
+            workspace_session_id: workspace_id,
+            po_name: po_name,
+            thread_type: "human",
+            name: session_name
+          )
 
           {
             success: true,
-            session_id: session_id,
+            session_id: thread.id,
+            thread_id: thread.id,
+            workspace_session_id: thread.workspace_session_id,
             name: session_name
           }
         end
 
+        # === Run runtime queries ===
+
+        def list_workspaces
+          return no_runtime_store unless @workspace_repository
+
+          { workspaces: @workspace_repository.list.map { |workspace| serialize_record(workspace) } }
+        end
+
+        def get_workspace_snapshot(id)
+          return no_runtime_store unless @workspace_repository
+
+          workspace = @workspace_repository.get(id)
+          return { error: "Workspace not found", id: id } unless workspace
+
+          {
+            version: Execution::Contracts::PROTOCOL_VERSION,
+            type: "workspace_snapshot",
+            payload: {
+              cursor: @event_repository.current_cursor(workspace_session_id: id),
+              workspace: serialize_record(workspace),
+              threads: @thread_repository.list(
+                workspace_session_id: id,
+                include_archived: true
+              ).map { |thread| serialize_record(thread) },
+              runs: @run_repository.list(
+                workspace_session_id: id,
+                limit: 500
+              ).map { |run| serialize_record(run) },
+              artifacts: @artifact_repository.list(
+                workspace_session_id: id
+              ).map { |artifact| serialize_record(artifact) }
+            }
+          }
+        end
+
+        def list_runtime_threads(workspace_id, request)
+          return no_runtime_store unless @thread_repository
+          return { error: "Workspace not found", id: workspace_id } unless @workspace_repository.get(workspace_id)
+
+          threads = @thread_repository.list(
+            workspace_session_id: workspace_id,
+            po_name: request.params["po_name"],
+            include_archived: request.params["include_archived"] == "true"
+          )
+          { threads: threads.map { |thread| serialize_record(thread) } }
+        end
+
+        def get_runtime_thread(id)
+          return no_runtime_store unless @thread_repository
+
+          thread = @thread_repository.get(id)
+          thread ? serialize_record(thread) : { error: "Thread not found", id: id }
+        end
+
+        def list_runtime_messages(thread_id, request)
+          return no_runtime_store unless @message_repository
+          return { error: "Thread not found", id: thread_id } unless @thread_repository.get(thread_id)
+
+          after_id = nonnegative_integer(request.params["after_id"])
+          limit = bounded_limit(request.params["limit"], maximum: 500)
+          messages = @message_repository.list(thread_id: thread_id, after_id: after_id, limit: limit)
+          {
+            thread_id: thread_id,
+            messages: messages.map { |message| serialize_runtime_message(message) },
+            next_after_id: messages.last&.dig(:id)
+          }
+        end
+
+        def list_runtime_runs(workspace_id, request)
+          return no_runtime_store unless @run_repository
+          return { error: "Workspace not found", id: workspace_id } unless @workspace_repository.get(workspace_id)
+
+          statuses = request.params["status"]&.split(",")
+          runs = @run_repository.list(
+            workspace_session_id: workspace_id,
+            thread_id: request.params["thread_id"],
+            statuses: statuses,
+            limit: bounded_limit(request.params["limit"], maximum: 500)
+          )
+          { runs: runs.map { |run| serialize_record(run) } }
+        rescue ArgumentError => e
+          { error: e.message }
+        end
+
+        def get_runtime_run(id)
+          return no_runtime_store unless @run_repository
+
+          run = @run_repository.get(id)
+          run ? serialize_record(run) : { error: "Run not found", id: id }
+        end
+
+        def list_run_events(run_id, request)
+          return no_runtime_store unless @event_repository
+          return { error: "Run not found", id: run_id } unless @run_repository.get(run_id)
+
+          events = @event_repository.run_events(
+            run_id: run_id,
+            after_sequence: nonnegative_integer(request.params["after_sequence"])
+          )
+          { run_id: run_id, events: events.map { |event| serialize_record(event) } }
+        end
+
+        def get_run_trace(run_id)
+          return no_runtime_store unless @run_trace_builder
+          return { error: "Run not found", id: run_id } unless @run_repository.get(run_id)
+
+          { trace: serialize_value(@run_trace_builder.build(run_id)) }
+        end
+
+        def list_workspace_events(workspace_id, request)
+          return no_runtime_store unless @event_repository
+          return { error: "Workspace not found", id: workspace_id } unless @workspace_repository.get(workspace_id)
+
+          events = @event_repository.workspace_events(
+            workspace_session_id: workspace_id,
+            after_cursor: nonnegative_integer(request.params["after_cursor"]),
+            limit: bounded_limit(request.params["limit"], maximum: 1_000)
+          )
+          {
+            workspace_session_id: workspace_id,
+            events: events.map { |event| serialize_value(event) },
+            next_cursor: events.last&.dig(:cursor) || nonnegative_integer(request.params["after_cursor"])
+          }
+        end
+
+        def list_runtime_artifacts(workspace_id)
+          return no_runtime_store unless @artifact_repository
+          return { error: "Workspace not found", id: workspace_id } unless @workspace_repository.get(workspace_id)
+
+          {
+            workspace_session_id: workspace_id,
+            cursor: @event_repository.current_cursor(workspace_session_id: workspace_id),
+            artifacts: @artifact_repository.list(
+              workspace_session_id: workspace_id
+            ).map { |artifact| serialize_record(artifact) }
+          }
+        end
+
+        def list_runtime_env_data(workspace_id)
+          return no_runtime_store unless @env_data_repository
+          return { error: "Workspace not found", id: workspace_id } unless @workspace_repository.get(workspace_id)
+
+          {
+            workspace_session_id: workspace_id,
+            entries: @env_data_repository.list(
+              workspace_session_id: workspace_id
+            ).map { |entry| serialize_value(entry) }
+          }
+        end
+
         # === Primitives ===
 
         def list_primitives
@@ -314,6 +642,144 @@ module PromptObjects
           }
         end
 
+        # === Artifacts ===
+
+        def get_artifact(key)
+          return { error: "No session store" } unless @runtime.session_store
+
+          artifact = @artifact_repository&.get(key)
+          return serialize_record(artifact).merge(rendered_by: artifact.owner_po) if artifact
+
+          { error: "Artifact not found", key: key }
+        rescue => e
+          { error: "Artifact lookup failed: #{e.message}", key: key }
+        end
+
+        # POST /api/artifacts/:key/message — BURP (Bidirectional UI Rendering
+        # Protocol). Interactive artifacts call PromptObjects.send(...) in the
+        # browser, which lands here; the message is injected into the PO that
+        # rendered the artifact, with provenance "artifact:<title>".
+        MAX_ARTIFACT_MESSAGE_LENGTH = 4_000
+
+        def artifact_message(key, body)
+          params = JSON.parse(body)
+          content = params["content"]
+
+          return { error: "content is required" } unless content.is_a?(String) && !content.strip.empty?
+          if content.length > MAX_ARTIFACT_MESSAGE_LENGTH
+            return { error: "content too long (max #{MAX_ARTIFACT_MESSAGE_LENGTH} characters)" }
+          end
+
+          artifact = get_artifact(key)
+          return artifact if artifact[:error]
+
+          target_po = artifact[:owner_po] || artifact[:rendered_by]
+          unless target_po && @runtime.registry.get(target_po).is_a?(PromptObject)
+            return { error: "Rendering PO '#{target_po}' not found for artifact", key: key }
+          end
+
+          from_source = "artifact:#{artifact[:title] || key}"
+          # The from_source provenance is UI metadata the LLM never sees — make
+          # the interface origin visible in the message itself, so the PO knows
+          # to respond by re-rendering the artifact rather than with prose.
+          framed_content = %([via your artifact "#{artifact[:title] || key}"] #{content}\n\n) +
+            "(The human is looking at the artifact, not this chat — respond by re-rendering " \
+            "\"#{artifact[:title] || key}\" with render_artifact in replace mode, updated for this action.)"
+          run = @runtime.enqueue_run(
+            target_po: target_po,
+            content: framed_content,
+            from_source: from_source,
+            workspace_session_id: artifact[:workspace_session_id],
+            thread_id: artifact[:owner_thread_id],
+            client_request_id: params["client_request_id"],
+            deadline: params["deadline"]
+          )
+          @runtime.schedule_run(run.id, tui_mode: false)
+          {
+            queued: true,
+            run_id: run.id,
+            thread_id: run.thread_id,
+            workspace_session_id: run.workspace_session_id,
+            target_po: target_po,
+            from_source: from_source
+          }
+        rescue JSON::ParserError
+          { error: "Invalid JSON body" }
+        rescue PromptObjects::Error => e
+          { error: e.message }
+        end
+
+        # === Environment Sessions (shared-context "jams") ===
+
+        # GET /api/sessions — list environment sessions, with which is active.
+        def get_environment_sessions
+          return { error: "No session store" } unless @runtime.session_store
+
+          { sessions: @runtime.environment_sessions.map { |s| serialize_environment_session(s) } }
+        end
+
+        # POST /api/sessions — create a new environment session (becomes active).
+        def create_environment_session_endpoint(body)
+          return { error: "No session store" } unless @runtime.session_store
+
+          name = parse_json(body)["name"]
+          session = @runtime.create_environment_session(name: name)
+          serialize_environment_session(session.merge(active: true))
+        end
+
+        # POST /api/sessions/:id/activate — switch the active environment session.
+        def activate_session(id)
+          session = @runtime.switch_active_session(id)
+          return { error: "Session not found", id: id } unless session
+
+          serialize_environment_session(session.merge(active: true))
+        end
+
+        # POST /api/sessions/:id/rename — rename an environment session.
+        def rename_session_endpoint(id, body)
+          name = parse_json(body)["name"]
+          return { error: "name is required" } if name.nil? || name.to_s.empty?
+
+          session = @runtime.rename_session(id, name)
+          return { error: "Session not found", id: id } unless session
+
+          serialize_environment_session(session)
+        end
+
+        # POST /api/sessions/:id/delete — delete an environment session.
+        def delete_session_endpoint(id)
+          ok = @runtime.delete_environment_session(id)
+          ok ? { deleted: id } : { error: "Session not found", id: id }
+        end
+
+        def serialize_environment_session(s)
+          {
+            id: s[:id],
+            name: s[:name],
+            active: s[:active] || false,
+            message_count: s[:message_count] || 0,
+            created_at: s[:created_at]&.iso8601,
+            updated_at: s[:updated_at]&.iso8601
+          }
+        end
+
+        def parse_json(body)
+          JSON.parse(body.to_s.empty? ? "{}" : body)
+        rescue JSON::ParserError
+          {}
+        end
+
+        # === Env Data ===
+
+        def get_session_env_data(session_id)
+          return { error: "No session store" } unless @runtime.session_store
+
+          root_thread_id = @runtime.env_data_scope(session_id)
+          entries = @runtime.session_store.list_env_data_full(root_thread_id: root_thread_id)
+
+          { root_thread_id: root_thread_id, entries: entries }
+        end
+
         # === Usage ===
 
         def get_session_usage(session_id, request)
@@ -365,6 +831,44 @@ module PromptObjects
 
         # === Helpers ===
 
+        def no_runtime_store
+          { error: "Run runtime storage is unavailable" }
+        end
+
+        def bounded_limit(value, maximum:)
+          requested = value.to_i
+          requested = 100 unless requested.positive?
+          [requested, maximum].min
+        end
+
+        def nonnegative_integer(value)
+          [value.to_i, 0].max
+        end
+
+        def serialize_record(record)
+          serialize_value(record.to_h)
+        end
+
+        def serialize_runtime_message(message)
+          serialize_value(message).merge(
+            id: message[:message_uid] || message[:id].to_s,
+            cursor_id: message[:id]
+          )
+        end
+
+        def serialize_value(value)
+          case value
+          when Time
+            value.iso8601
+          when Hash
+            value.to_h { |key, nested| [key, serialize_value(nested)] }
+          when Array
+            value.map { |nested| serialize_value(nested) }
+          else
+            value
+          end
+        end
+
         def po_summary(po)
           po.to_summary_hash(registry: @runtime.registry)
         end
@@ -398,7 +902,12 @@ module PromptObjects
             status,
             {
               "content-type" => "application/json",
-              "access-control-allow-origin" => "*"
+              "access-control-allow-origin" => "*",
+              # The API is live state — sessions, artifacts, PO status all change
+              # constantly. Without this, browsers heuristically cache same-URL
+              # GETs, so a refresh after creating a session (or rendering an
+              # artifact) re-reads a stale list and the new thing never appears.
+              "cache-control" => "no-store, must-revalidate"
             },
             [body]
           ]