prompt_objects 0.4.0 → 0.6.0

data/frontend/src/store/index.ts

@@ -7,6 +7,7 @@ import type {
   Environment,
   Message,
   LLMConfig,
+  EnvDataEntry,
 } from '../types'
 
 interface Store {
@@ -41,6 +42,8 @@ interface Store {
   addBusMessage: (message: BusMessage) => void
   busOpen: boolean
   toggleBus: () => void
+  topPaneCollapsed: boolean
+  toggleTopPane: () => void
 
   // Notifications
   notifications: Notification[]
@@ -66,6 +69,15 @@ interface Store {
   usageData: Record<string, unknown> | null
   setUsageData: (data: Record<string, unknown>) => void
   clearUsageData: () => void
+
+  // Env Data
+  envData: Record<string, EnvDataEntry[]>
+  setEnvData: (rootThreadId: string, entries: EnvDataEntry[]) => void
+  clearEnvData: (rootThreadId: string) => void
+  sessionRootMap: Record<string, string>
+  setSessionRoot: (sessionId: string, rootThreadId: string) => void
+  envDataPaneCollapsed: boolean
+  toggleEnvDataPane: () => void
 }
 
 export const useStore = create<Store>((set) => ({
@@ -203,6 +215,8 @@ export const useStore = create<Store>((set) => ({
     })),
   busOpen: false,
   toggleBus: () => set((s) => ({ busOpen: !s.busOpen })),
+  topPaneCollapsed: false,
+  toggleTopPane: () => set((s) => ({ topPaneCollapsed: !s.topPaneCollapsed })),
 
   // Notifications
   notifications: [],
@@ -259,6 +273,25 @@ export const useStore = create<Store>((set) => ({
   usageData: null,
   setUsageData: (data) => set({ usageData: data }),
   clearUsageData: () => set({ usageData: null }),
+
+  // Env Data
+  envData: {},
+  setEnvData: (rootThreadId, entries) =>
+    set((s) => ({
+      envData: { ...s.envData, [rootThreadId]: entries },
+    })),
+  clearEnvData: (rootThreadId) =>
+    set((s) => {
+      const { [rootThreadId]: _, ...rest } = s.envData
+      return { envData: rest }
+    }),
+  sessionRootMap: {},
+  setSessionRoot: (sessionId, rootThreadId) =>
+    set((s) => ({
+      sessionRootMap: { ...s.sessionRootMap, [sessionId]: rootThreadId },
+    })),
+  envDataPaneCollapsed: true,
+  toggleEnvDataPane: () => set((s) => ({ envDataPaneCollapsed: !s.envDataPaneCollapsed })),
 }))
 
 // Selectors - use useShallow to prevent infinite re-renders with derived arrays
@@ -273,3 +306,6 @@ export const useNotificationCount = () =>
 
 export const usePONotifications = (poName: string) =>
   useStore(useShallow((s) => s.notifications.filter((n) => n.po_name === poName)))
+
+export const useEnvData = (rootThreadId: string | undefined) =>
+  useStore(useShallow((s) => (rootThreadId ? s.envData[rootThreadId] || [] : [])))

data/frontend/src/types/index.ts

@@ -102,6 +102,15 @@ export interface LLMConfig {
   providers: LLMProvider[]
 }
 
+export interface EnvDataEntry {
+  key: string
+  short_description: string
+  value: unknown
+  stored_by: string
+  created_at: string
+  updated_at: string
+}
+
 // WebSocket message types
 export type WSMessageType =
   | 'environment'
@@ -126,6 +135,10 @@ export type WSMessageType =
   | 'llm_switched'
   | 'session_usage'
   | 'thread_export'
+  | 'prompt_updated'
+  | 'llm_error'
+  | 'env_data_changed'
+  | 'env_data_list'
   | 'error'
   | 'pong'
 

data/frontend/tailwind.config.js

@@ -7,18 +7,37 @@ export default {
   theme: {
     extend: {
       colors: {
-        // Custom colors for PromptObjects
         po: {
-          bg: '#0f0f1a',
-          surface: '#1a1a2e',
-          border: '#2d2d44',
-          accent: '#7c3aed',
-          'accent-hover': '#9061f9',
-          success: '#22c55e',
-          warning: '#f59e0b',
-          error: '#ef4444',
+          bg: '#1a1918',
+          surface: '#222120',
+          'surface-2': '#2c2a28',
+          'surface-3': '#363432',
+          border: '#3d3a37',
+          'border-focus': '#5c5752',
+          accent: '#d4952a',
+          'accent-muted': '#9a6d20',
+          'accent-wash': 'rgba(212,149,42,0.08)',
+          'text-primary': '#e8e2da',
+          'text-secondary': '#a8a29a',
+          'text-tertiary': '#78726a',
+          'text-ghost': '#524e48',
+          'status-idle': '#78726a',
+          'status-active': '#d4952a',
+          'status-calling': '#3b9a6e',
+          'status-error': '#c45c4a',
+          'status-delegated': '#5a8fc2',
+          success: '#3b9a6e',
+          warning: '#d4952a',
+          error: '#c45c4a',
         },
       },
+      fontFamily: {
+        ui: ['Geist', 'system-ui', 'sans-serif'],
+        mono: ['"Geist Mono"', '"IBM Plex Mono"', 'monospace'],
+      },
+      fontSize: {
+        '2xs': ['11px', { lineHeight: '15px' }],
+      },
     },
   },
   plugins: [],

data/lib/prompt_objects/capability.rb

@@ -27,11 +27,33 @@ module PromptObjects
         function: {
           name: name,
           description: description,
-          parameters: parameters
+          parameters: sanitize_schema(parameters)
         }
       }
     end
 
+    private
+
+    # Ensure array-typed properties have an `items` field.
+    # LLM APIs (Gemini, OpenAI, Ollama) reject array schemas without items.
+    def sanitize_schema(schema)
+      return schema unless schema.is_a?(Hash)
+
+      schema = schema.dup
+
+      if schema[:type] == "array" && !schema.key?(:items) && !schema.key?("items")
+        schema[:items] = {}
+      end
+
+      if schema[:properties].is_a?(Hash)
+        schema[:properties] = schema[:properties].transform_values { |v| sanitize_schema(v) }
+      end
+
+      schema
+    end
+
+    public
+
     # Define the parameters this capability accepts.
     # Override in subclasses for specific parameter schemas.
     # @return [Hash] JSON Schema for parameters

data/lib/prompt_objects/connectors/mcp.rb

@@ -183,12 +183,7 @@ module PromptObjects
             env = server_context[:env]
 
             pos = env.registry.prompt_objects.map do |po|
-              {
-                name: po.name,
-                description: po.description,
-                state: po.state.to_s,
-                capabilities: po.config["capabilities"] || []
-              }
+              po.to_summary_hash(registry: env.registry)
             end
 
             ::MCP::Tool::Response.new([{
@@ -499,16 +494,7 @@ module PromptObjects
               }])
             end
 
-            info = {
-              name: po.name,
-              description: po.description,
-              state: po.state.to_s,
-              prompt: po.body,
-              capabilities: po.config["capabilities"] || [],
-              config: po.config,
-              session_id: po.instance_variable_get(:@session_id),
-              history_length: po.history.length
-            }
+            info = po.to_inspect_hash(registry: env.registry)
 
             ::MCP::Tool::Response.new([{
               type: "text",

data/lib/prompt_objects/environment.rb

@@ -42,6 +42,7 @@ module PromptObjects
     attr_accessor :on_po_registered  # Callback for when a PO is registered
     attr_accessor :on_po_modified    # Callback for when a PO is modified (capabilities changed, etc.)
     attr_accessor :on_delegation_event  # Callback for PO-to-PO delegation start/complete
+    attr_accessor :on_env_data_changed  # Callback for env data store/update/delete
 
     # Initialize from an environment path (with manifest) or objects directory.
     # @param env_path [String, nil] Path to environment directory (preferred)
@@ -223,6 +224,15 @@ module PromptObjects
       @on_delegation_event&.call(event_type, payload)
     end
 
+    # Notify that environment data has changed (stored, updated, or deleted).
+    # @param action [String] "store", "update", or "delete"
+    # @param root_thread_id [String] Root thread scope
+    # @param key [String] The data key that changed
+    # @param stored_by [String] PO name that made the change
+    def notify_env_data_changed(action:, root_thread_id:, key:, stored_by:)
+      @on_env_data_changed&.call(action: action, root_thread_id: root_thread_id, key: key, stored_by: stored_by)
+    end
+
     # Load a prompt object by name from the objects directory.
     # @param name [String] Name of the prompt object (without .md extension)
     # @return [PromptObject]
@@ -316,6 +326,11 @@ module PromptObjects
       @registry.register(Universal::ModifyPrimitive.new)
       @registry.register(Universal::RequestPrimitive.new)
       @registry.register(Universal::ModifyPrompt.new)
+      @registry.register(Universal::StoreEnvData.new)
+      @registry.register(Universal::GetEnvData.new)
+      @registry.register(Universal::ListEnvData.new)
+      @registry.register(Universal::UpdateEnvData.new)
+      @registry.register(Universal::DeleteEnvData.new)
     end
   end
 

data/lib/prompt_objects/llm/openai_adapter.rb

@@ -37,7 +37,29 @@ module PromptObjects
         end
 
         raw_response = @client.chat(parameters: params)
+
+        # Check for error responses (Ollama and some providers return errors inline)
+        if raw_response.is_a?(Hash) && raw_response["error"]
+          error_msg = raw_response["error"]
+          error_msg = error_msg["message"] if error_msg.is_a?(Hash)
+          raise Error, "#{@provider_name} API error: #{error_msg}"
+        end
+
         parse_response(raw_response)
+      rescue Faraday::ClientError => e
+        # Extract error body from 4xx responses (ruby-openai wraps these)
+        body = e.response&.dig(:body) rescue nil
+        detail = if body.is_a?(String)
+                   begin
+                     parsed = JSON.parse(body)
+                     parsed.dig("error", "message") || parsed["error"] || body
+                   rescue JSON::ParserError
+                     body
+                   end
+                 elsif body.is_a?(Hash)
+                   body.dig("error", "message") || body["error"] || body.to_s
+                 end
+        raise Error, "#{@provider_name} API error (#{e.response&.dig(:status)}): #{detail || e.message}"
       end
 
       private

data/lib/prompt_objects/mcp/tools/inspect_po.rb

@@ -30,37 +30,7 @@ module PromptObjects
             }])
           end
 
-          # Categorize capabilities
-          declared_caps = po.config["capabilities"] || []
-          universal_caps = PromptObjects::UNIVERSAL_CAPABILITIES
-
-          # Resolve which are POs vs primitives
-          delegates = []
-          primitives = []
-
-          declared_caps.each do |cap_name|
-            cap = env.registry.get(cap_name)
-            if cap.is_a?(PromptObjects::PromptObject)
-              delegates << cap_name
-            elsif cap.is_a?(PromptObjects::Primitive)
-              primitives << cap_name
-            end
-          end
-
-          info = {
-            name: po.name,
-            description: po.description,
-            state: po.state || :idle,
-            config: po.config,
-            capabilities: {
-              universal: universal_caps,
-              primitives: primitives,
-              delegates: delegates,
-              all_declared: declared_caps
-            },
-            prompt_body: po.body,
-            history_length: po.history.length
-          }
+          info = po.to_inspect_hash(registry: env.registry)
 
           ::MCP::Tool::Response.new([{
             type: "text",

data/lib/prompt_objects/mcp/tools/list_prompt_objects.rb

@@ -17,12 +17,7 @@ module PromptObjects
           env = server_context[:env]
 
           pos = env.registry.prompt_objects.map do |po|
-            {
-              name: po.name,
-              description: po.description,
-              state: po.state || :idle,
-              capabilities: po.config["capabilities"] || []
-            }
+            po.to_summary_hash(registry: env.registry)
           end
 
           ::MCP::Tool::Response.new([{

data/lib/prompt_objects/prompt_object.rb

@@ -232,8 +232,134 @@ module PromptObjects
       @session_id
     end
 
+    # --- Serialization ---
+    # Canonical methods for converting PO state to hashes for broadcasting,
+    # REST API responses, and MCP tool output. All consumers should use these
+    # to ensure consistent capability format across WebSocket, REST, and MCP.
+
+    # Full state hash for WebSocket/broadcast consumers.
+    # Matches the frontend's PromptObject TypeScript type.
+    # @param registry [Registry, nil] Registry for resolving capability descriptions
+    # @return [Hash]
+    def to_state_hash(registry: nil)
+      {
+        status: (@state || :idle).to_s,
+        description: description,
+        capabilities: resolve_capabilities(registry: registry),
+        universal_capabilities: resolve_universal_capabilities(registry: registry),
+        current_session: serialize_current_session,
+        sessions: list_sessions.map { |s| self.class.serialize_session(s) },
+        prompt: body,
+        config: config
+      }
+    end
+
+    # Summary hash for list endpoints (REST API, MCP list tools).
+    # Lightweight: no prompt, no session messages, no universal capabilities.
+    # @param registry [Registry, nil] Registry for resolving capability descriptions
+    # @return [Hash]
+    def to_summary_hash(registry: nil)
+      {
+        name: name,
+        description: description,
+        status: (@state || :idle).to_s,
+        capabilities: resolve_capabilities(registry: registry),
+        session_count: list_sessions.size
+      }
+    end
+
+    # Detailed inspection hash for single-PO endpoints (REST GET, MCP inspect).
+    # Everything in summary plus prompt, config, sessions, and universals.
+    # @param registry [Registry, nil] Registry for resolving capability descriptions
+    # @return [Hash]
+    def to_inspect_hash(registry: nil)
+      {
+        name: name,
+        description: description,
+        status: (@state || :idle).to_s,
+        capabilities: resolve_capabilities(registry: registry),
+        universal_capabilities: resolve_universal_capabilities(registry: registry),
+        prompt: body,
+        config: config,
+        session_id: session_id,
+        sessions: list_sessions.map { |s| self.class.serialize_session(s) },
+        history_length: history.length
+      }
+    end
+
+    # Serialize a message (in-memory or from DB) to a JSON-ready hash.
+    # Handles both ToolCall objects and plain Hashes (from SQLite).
+    # @param msg [Hash] The message to serialize
+    # @return [Hash]
+    def self.serialize_message(msg)
+      case msg[:role]
+      when :user
+        from = msg[:from] || msg[:from_po]
+        { role: "user", content: msg[:content], from: from }
+      when :assistant
+        hash = { role: "assistant", content: msg[:content] }
+        if msg[:tool_calls]
+          hash[:tool_calls] = msg[:tool_calls].map do |tc|
+            if tc.respond_to?(:id)
+              { id: tc.id, name: tc.name, arguments: tc.arguments }
+            else
+              { id: tc[:id] || tc["id"], name: tc[:name] || tc["name"], arguments: tc[:arguments] || tc["arguments"] || {} }
+            end
+          end
+        end
+        hash
+      when :tool
+        results = msg[:results] || msg[:tool_results]
+        { role: "tool", results: results }
+      else
+        { role: msg[:role].to_s, content: msg[:content] }
+      end
+    end
+
+    # Serialize a session record to a JSON-ready hash with thread fields.
+    # @param session [Hash] Session record from session store
+    # @return [Hash]
+    def self.serialize_session(session)
+      {
+        id: session[:id],
+        name: session[:name],
+        message_count: session[:message_count] || 0,
+        updated_at: session[:updated_at]&.iso8601,
+        parent_session_id: session[:parent_session_id],
+        parent_po: session[:parent_po],
+        thread_type: session[:thread_type] || "root"
+      }
+    end
+
     private
 
+    # Build capability info objects for this PO's declared capabilities.
+    def resolve_capabilities(registry: nil)
+      declared = @config["capabilities"] || []
+      return declared.map { |n| { name: n, description: n } } unless registry
+
+      declared.map do |cap_name|
+        cap = registry.get(cap_name)
+        { name: cap_name, description: cap&.description || "Capability not found", parameters: cap&.parameters }
+      end
+    end
+
+    # Build capability info objects for universal capabilities.
+    def resolve_universal_capabilities(registry: nil)
+      return [] unless registry
+
+      UNIVERSAL_CAPABILITIES.map do |cap_name|
+        cap = registry.get(cap_name)
+        { name: cap_name, description: cap&.description || "Universal capability", parameters: cap&.parameters }
+      end
+    end
+
+    # Serialize current session with messages for real-time state.
+    def serialize_current_session
+      return nil unless session_id
+      { id: session_id, messages: history.map { |m| self.class.serialize_message(m) } }
+    end
+
     def normalize_message(message)
       case message
       when String
@@ -259,23 +385,118 @@ module PromptObjects
     end
 
     def build_system_prompt
-      # Build context about this PO's identity
       declared_caps = @config["capabilities"] || []
-      all_caps = declared_caps + UNIVERSAL_CAPABILITIES
 
       context_block = <<~CONTEXT
         ## System Context
 
-        You are a prompt object named "#{name}".
+        You are a prompt object named "#{name}" running in a PromptObjects environment.
+
+        ### What is a Prompt Object?
+        You are an autonomous entity defined by a markdown file. You have an identity (your prompt),
+        capabilities (tools you can use), and you communicate by receiving messages and responding.
+        You exist alongside other prompt objects and primitive tools in a shared environment.
+
+        ### How you get called
+        You may receive messages from:
+        - **A human** interacting with you directly through the UI
+        - **Another prompt object** that has delegated a task to you as part of a larger workflow
+
+        When called by another PO, you'll see a delegation context block in the message with details
+        about who called you and why. You can also check shared environment data (via `list_env_data`)
+        for context that other POs in the same workflow have stored.
+
+        ### Your capabilities
         When using tools that target a PO (like add_capability), you can use "self" or "#{name}" to target yourself.
+        - Declared capabilities: #{declared_caps.empty? ? '(none)' : declared_caps.join(', ')}
+        - Universal capabilities (always available): #{UNIVERSAL_CAPABILITIES.join(', ')}
 
-        Your declared capabilities: #{declared_caps.empty? ? '(none)' : declared_caps.join(', ')}
-        Universal capabilities (always available): #{UNIVERSAL_CAPABILITIES.join(', ')}
+        You can create new tools (`create_primitive`) and new prompt objects (`create_capability`) at runtime if needed. Use `list_capabilities` to see everything available.
       CONTEXT
 
       "#{@body}\n\n#{context_block}"
     end
 
+    # Build a delegation preamble for a PO-to-PO call.
+    # @param target_po [PromptObject] The PO being called
+    # @param delegation_thread [String, nil] The delegation thread ID
+    # @param context [Context] Execution context
+    # @return [String, nil] Preamble text or nil if caller isn't a PO
+    def build_delegation_preamble(target_po, delegation_thread, context)
+      return nil unless context.calling_po
+
+      caller_po = context.env.registry.get(context.calling_po)
+      return nil unless caller_po.is_a?(PromptObject)
+
+      parts = []
+      parts << "---"
+      parts << "[Delegation Context]"
+      parts << "Called by: #{caller_po.name}"
+      parts << "#{caller_po.name} is: \"#{caller_po.description}\""
+
+      chain = build_delegation_chain(delegation_thread)
+      parts << "Delegation chain: #{chain}" if chain
+
+      if delegation_thread && env_data_available?(delegation_thread)
+        parts << "Shared environment data is available — call list_env_data() to see what context has been stored."
+      end
+
+      parts << "---"
+      parts.join("\n")
+    end
+
+    # Build a human-readable delegation chain from thread lineage.
+    # @param delegation_thread [String, nil] The delegation thread ID
+    # @return [String, nil] Chain like "human → coordinator → solver → you (observer)"
+    def build_delegation_chain(delegation_thread)
+      return nil unless delegation_thread && session_store
+
+      lineage = session_store.get_thread_lineage(delegation_thread)
+      return nil if lineage.empty?
+
+      chain = ["human"]
+      lineage[0..-2].each do |session|
+        chain << session[:po_name] if session[:po_name]
+      end
+      chain << "you (#{lineage.last[:po_name]})"
+
+      chain.join(" → ")
+    end
+
+    # Check if any shared environment data exists for a delegation thread.
+    # @param delegation_thread [String] The delegation thread ID
+    # @return [Boolean]
+    def env_data_available?(delegation_thread)
+      return false unless session_store
+
+      root_thread = session_store.resolve_root_thread(delegation_thread)
+      entries = session_store.list_env_data(root_thread_id: root_thread)
+      !entries.empty?
+    end
+
+    # Build enriched arguments with delegation preamble prepended to the message.
+    # Returns a NEW hash — does not mutate the original arguments.
+    # @param target_po [PromptObject] The PO being called
+    # @param arguments [Hash, String] Original tool call arguments
+    # @param delegation_thread [String, nil] The delegation thread ID
+    # @param context [Context] Execution context
+    # @return [Hash, String] Enriched arguments with preamble, or original if no preamble
+    def enrich_delegation_message(target_po, arguments, delegation_thread, context)
+      preamble = build_delegation_preamble(target_po, delegation_thread, context)
+      return arguments unless preamble
+
+      original_message = normalize_message(arguments)
+      enriched_message = "#{preamble}\n\n#{original_message}"
+
+      if arguments.is_a?(Hash)
+        # Create a new hash with the enriched message
+        key = arguments.key?(:message) ? :message : "message"
+        arguments.merge(key => enriched_message)
+      else
+        enriched_message
+      end
+    end
+
     def execute_tool_calls(tool_calls, context)
       # Track the caller for nested calls
       previous_capability = context.current_capability
@@ -284,6 +505,13 @@ module PromptObjects
       tool_calls.map do |tc|
         capability = @env.registry&.get(tc.name)
 
+        # Guard: only execute tools the PO is allowed to use (declared + universal).
+        # Without this, the LLM can hallucinate calls to tools it shouldn't have access to.
+        allowed = (@config["capabilities"] || []) + UNIVERSAL_CAPABILITIES
+        unless allowed.include?(tc.name)
+          next { tool_call_id: tc.id, name: tc.name, content: "Capability '#{tc.name}' is not available. Your declared capabilities are: #{(@config["capabilities"] || []).join(', ')}. Use add_capability to add it first, or use list_primitives / list_capabilities to discover what's available." }
+        end
+
         if capability
           # Log the outgoing message
           @env.bus.publish(from: name, to: tc.name, message: tc.arguments)
@@ -328,6 +556,10 @@ module PromptObjects
         parent_message_id: get_last_message_id
       )
 
+      # Enrich the message with delegation context (must happen after thread creation
+      # so build_delegation_chain can walk the lineage)
+      enriched_args = enrich_delegation_message(target_po, tool_call.arguments, delegation_thread, context)
+
       # Notify delegation start so WebSocket clients see the target PO activate
       @env.notify_delegation(:started, {
         target: target_po.name,
@@ -339,10 +571,10 @@ module PromptObjects
       begin
         if delegation_thread
           # Execute in isolated thread
-          target_po.receive_in_thread(tool_call.arguments, context: context, thread_id: delegation_thread)
+          target_po.receive_in_thread(enriched_args, context: context, thread_id: delegation_thread)
         else
           # Fallback: execute in target's current session (no session store)
-          target_po.receive(tool_call.arguments, context: context)
+          target_po.receive(enriched_args, context: context)
         end
       ensure
         # Notify delegation complete — target PO is done