prompt_objects 0.5.0 → 0.7.0

data/lib/prompt_objects/universal/add_capability.rb

@@ -10,7 +10,7 @@ module PromptObjects
       end
 
       def description
-        "Add a capability to a prompt object, allowing it to use new tools. Can target self or another PO."
+        "Add an existing capability (a primitive tool or another prompt object) to a prompt object, allowing it to use that capability. Can target self or another PO. Use list_capabilities to discover what's available."
       end
 
       def parameters

data/lib/prompt_objects/universal/create_capability.rb

@@ -13,7 +13,9 @@ module PromptObjects
       end
 
       def description
-        "Create a new capability. Use type='prompt_object' for LLM-backed specialists, or type='primitive' for deterministic Ruby tools."
+        "Create a new capability. Use type='prompt_object' for LLM-backed specialists, or type='primitive' for deterministic Ruby tools. " \
+          "For prompt objects, capabilities are the exact callable tools/delegates the new object receives; an informational delegate " \
+          "does not grant access to that delegate's tools."
       end
 
       def parameters
@@ -37,7 +39,7 @@ module PromptObjects
             capabilities: {
               type: "array",
               items: { type: "string" },
-              description: "(prompt_object only) List of capabilities this PO can use"
+              description: "(prompt_object only) Exact tools and delegates this PO may call. Grant direct action tools for every action it must perform; do not use a related PO as a proxy for tools it does not expose."
             },
             identity: {
               type: "string",

data/lib/prompt_objects/universal/delete_env_data.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Universal
+    # Universal capability to delete a key from the shared environment data.
+    class DeleteEnvData < Primitive
+      execution_policy(
+        parallel_safe: true,
+        side_effect: :write,
+        resource_keys: ->(arguments, context, _capability) {
+          key = arguments[:key] || arguments["key"]
+          ["workspace:#{context.workspace_session_id}:env_data:#{key}"]
+        }
+      )
+
+      def name
+        "delete_env_data"
+      end
+
+      def description
+        "Delete a key from the shared environment data for this delegation chain."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            key: {
+              type: "string",
+              description: "The key to delete"
+            }
+          },
+          required: ["key"]
+        }
+      end
+
+      def receive(message, context:)
+        key = message[:key] || message["key"]
+        return "Error: 'key' is required" unless key
+
+        root_thread_id = context.env_data_scope
+        return "Error: Could not resolve thread scope (no active session)" unless root_thread_id
+
+        store = context.env.session_store
+        return "Error: Session store not available" unless store
+
+        deleted = if context.env.respond_to?(:delete_environment_data)
+                    context.env.delete_environment_data(key: key, context: context)
+                  else
+                    store.delete_env_data(root_thread_id: root_thread_id, key: key)
+                  end
+
+        unless deleted
+          return "Key '#{key}' not found in environment data."
+        end
+
+        stored_by = context.calling_po || "unknown"
+
+        context.bus.publish(
+          from: stored_by,
+          to: "env_data",
+          message: { action: "delete", key: key }
+        )
+
+        unless context.env.respond_to?(:delete_environment_data)
+          context.env.notify_env_data_changed(
+            action: "delete",
+            root_thread_id: root_thread_id,
+            key: key,
+            stored_by: stored_by
+          )
+        end
+
+        "Deleted '#{key}' from environment data."
+      end
+    end
+  end
+end

data/lib/prompt_objects/universal/delete_primitive.rb

@@ -7,7 +7,7 @@ module PromptObjects
     # USE WITH CAUTION - this permanently deletes the primitive file.
     class DeletePrimitive < Primitive
       # Built-in primitives that cannot be deleted
-      PROTECTED_PRIMITIVES = %w[read_file list_files write_file http_get].freeze
+      PROTECTED_PRIMITIVES = %w[read_file list_files write_file http_get think].freeze
 
       def name
         "delete_primitive"

data/lib/prompt_objects/universal/dispatch_po.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Universal
+    # Enqueue independent PO work and return its durable identity immediately.
+    class DispatchPO < Primitive
+      execution_policy parallel_safe: true, side_effect: :write, resource_keys: ->(_arguments, _context, _capability) { [] }
+
+      def name = "dispatch_po"
+
+      def description
+        "Dispatch work to an allowed Prompt Object without waiting for its response. " \
+          "Returns run_id and thread_id; use get_run_status or join_runs when the result is needed later."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            target_po: { type: "string", description: "Prompt Object listed in your capabilities" },
+            message: { type: "string", description: "Work to enqueue" },
+            thread_id: { type: "string", description: "Optional existing target thread" },
+            lifetime: {
+              type: "string", enum: %w[attached detached],
+              description: "attached cancels with the parent; detached may finish independently"
+            },
+            on_complete: {
+              type: "string",
+              description: "Optional follow-up instruction enqueued on your thread when the child finishes"
+            }
+          },
+          required: %w[target_po message]
+        }
+      end
+
+      def receive(message, context:)
+        target = message[:target_po] || message["target_po"]
+        content = message[:message] || message["message"]
+        raise Error, "target_po is required" if target.to_s.empty?
+        raise Error, "message is required" if content.to_s.empty?
+
+        result = context.env.dispatch_run(
+          target_po: target,
+          content: content,
+          context: context,
+          thread_id: message[:thread_id] || message["thread_id"],
+          lifetime: message[:lifetime] || message["lifetime"] || "attached",
+          on_complete: message[:on_complete] || message["on_complete"]
+        )
+        JSON.generate(result)
+      end
+    end
+  end
+end

data/lib/prompt_objects/universal/get_env_data.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Universal
+    # Universal capability to retrieve shared data by key from the current delegation chain.
+    class GetEnvData < Primitive
+      execution_policy parallel_safe: true, side_effect: :read
+
+      def name
+        "get_env_data"
+      end
+
+      def description
+        "Retrieve a specific key's full value from the shared environment data. " \
+        "Use list_env_data first to see what keys are available."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            key: {
+              type: "string",
+              description: "The key to retrieve"
+            }
+          },
+          required: ["key"]
+        }
+      end
+
+      def receive(message, context:)
+        key = message[:key] || message["key"]
+        return "Error: 'key' is required" unless key
+
+        root_thread_id = context.env_data_scope
+        return "Error: Could not resolve thread scope (no active session)" unless root_thread_id
+
+        store = context.env.session_store
+        return "Error: Session store not available" unless store
+
+        entry = if context.env.respond_to?(:get_environment_data)
+                  context.env.get_environment_data(key: key, context: context)
+                else
+                  store.get_env_data(root_thread_id: root_thread_id, key: key)
+                end
+        return "Key '#{key}' not found in environment data." unless entry
+
+        context.bus.publish(
+          from: context.calling_po || "unknown",
+          to: "env_data",
+          message: { action: "get", key: key }
+        )
+
+        JSON.generate(entry[:value])
+      end
+    end
+  end
+end

data/lib/prompt_objects/universal/get_run_status.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Universal
+    class GetRunStatus < Primitive
+      execution_policy parallel_safe: true, side_effect: :read
+
+      def name = "get_run_status"
+
+      def description
+        "Get the current durable status and result fields for a related dispatched run."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: { run_id: { type: "string" } },
+          required: ["run_id"]
+        }
+      end
+
+      def receive(message, context:)
+        run_id = message[:run_id] || message["run_id"]
+        raise Error, "run_id is required" if run_id.to_s.empty?
+
+        JSON.generate(context.env.run_status(run_id, context: context))
+      end
+    end
+  end
+end

data/lib/prompt_objects/universal/join_runs.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Universal
+    class JoinRuns < Primitive
+      execution_policy parallel_safe: true, side_effect: :read
+
+      def name = "join_runs"
+
+      def description
+        "Wait for one or more related dispatched runs and return their terminal statuses/results in input order."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            run_ids: { type: "array", items: { type: "string" } },
+            timeout: { type: "number", description: "Optional timeout in seconds" }
+          },
+          required: ["run_ids"]
+        }
+      end
+
+      def receive(message, context:)
+        run_ids = message[:run_ids] || message["run_ids"]
+        raise Error, "run_ids must not be empty" unless run_ids.is_a?(Array) && run_ids.any?
+
+        timeout = message[:timeout] || message["timeout"]
+        timeout = [[timeout.to_f, 0.1].max, 300].min if timeout
+        JSON.generate(context.env.join_runs(run_ids, context: context, timeout: timeout))
+      end
+    end
+  end
+end

data/lib/prompt_objects/universal/list_env_data.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Universal
+    # Universal capability to list all shared environment data keys and descriptions.
+    # Returns a lightweight manifest without loading full values.
+    class ListEnvData < Primitive
+      execution_policy parallel_safe: true, side_effect: :read
+
+      def name
+        "list_env_data"
+      end
+
+      def description
+        "List all keys and descriptions in the shared environment data for this delegation chain. " \
+        "Returns keys and short descriptions only (no values). " \
+        "Use get_env_data to retrieve a specific key's full value."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {},
+          required: []
+        }
+      end
+
+      def receive(message, context:)
+        root_thread_id = context.env_data_scope
+        return "Error: Could not resolve thread scope (no active session)" unless root_thread_id
+
+        store = context.env.session_store
+        return "Error: Session store not available" unless store
+
+        entries = if context.env.respond_to?(:list_environment_data)
+                    context.env.list_environment_data(context: context).map do |entry|
+                      { key: entry[:key], short_description: entry[:short_description] }
+                    end
+                  else
+                    store.list_env_data(root_thread_id: root_thread_id)
+                  end
+
+        if entries.empty?
+          return "No environment data stored for this delegation chain."
+        end
+
+        context.bus.publish(
+          from: context.calling_po || "unknown",
+          to: "env_data",
+          message: { action: "list", count: entries.size }
+        )
+
+        JSON.generate(entries)
+      end
+    end
+  end
+end

data/lib/prompt_objects/universal/modify_primitive.rb

@@ -8,7 +8,7 @@ module PromptObjects
     # Allows POs to fix or improve their primitives.
     class ModifyPrimitive < Primitive
       # Stdlib primitives cannot be modified
-      STDLIB_PRIMITIVES = %w[read_file list_files write_file http_get].freeze
+      STDLIB_PRIMITIVES = %w[read_file list_files write_file http_get think].freeze
 
       def name
         "modify_primitive"

data/lib/prompt_objects/universal/render_artifact.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Universal
+    # Universal capability to render interactive HTML in the UI artifact panel.
+    # Artifacts are environment-wide — any PO can create or update any artifact.
+    #
+    # Modes:
+    #   replace (default) — updates existing artifact with the same title in place
+    #   version — always creates a new artifact entry
+    #
+    # The frontend renders artifacts in a sandboxed iframe with React 18,
+    # Tailwind CSS, and Babel (for JSX) available.
+    #
+    # Artifacts are bidirectional (BURP — Bidirectional UI Rendering Protocol):
+    # a PromptObjects.send(message) function is injected into every artifact.
+    # Calling it sends a natural-language message back to the PO that rendered
+    # the artifact (provenance "artifact:<title>"), so POs can build UIs the
+    # human interacts with instead of chatting.
+    class RenderArtifact < Primitive
+      execution_policy(
+        parallel_safe: true,
+        side_effect: :write,
+        resource_keys: ->(arguments, context, _capability) {
+          title = arguments[:title] || arguments["title"]
+          ["workspace:#{context.workspace_session_id}:artifact:#{title}"]
+        }
+      )
+
+      def name
+        "render_artifact"
+      end
+
+      def description
+        "Render an interactive HTML/JSX artifact in the UI panel. The sandboxed iframe ALREADY provides " \
+        "React 18, ReactDOM, Babel, and Tailwind, plus a <div id='root'> mount point. " \
+        "IMPORTANT: send ONLY your component markup — do NOT include <html>/<head>/<body> wrappers or your " \
+        "own <script src=...> CDN tags for React/Babel/Tailwind (the iframe provides them; your own copies " \
+        "conflict). Do NOT use `import` or `export` (it is not an ES module; those silently fail to render). " \
+        "Put JSX in <script type='text/babel'>, define a component, and you MUST mount it yourself with: " \
+        "ReactDOM.createRoot(document.getElementById('root')).render(<App />); " \
+        "BIDIRECTIONAL: PromptObjects.send('...') is available inside the artifact — wire it to " \
+        "buttons/forms/controls so the human can talk back to YOU through the UI instead of chatting " \
+        "(messages arrive from 'artifact:<title>'). Respond to them by re-rendering this artifact " \
+        "(mode 'replace') with the updated UI. A re-render resets the artifact's local JS state, so " \
+        "bake the current state into the HTML you render. " \
+        "Default mode is 'replace' — same title updates in place. Use mode 'version' for a new entry each time."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            title: {
+              type: "string",
+              description: "Short title for the artifact tab. In replace mode, this is the unique identifier — same title overwrites the previous version."
+            },
+            html: {
+              type: "string",
+              description: "Your component markup only — NOT a full page. React 18/ReactDOM/Babel/Tailwind " \
+                "and a <div id='root'> are already provided by the iframe; do NOT add <html>/<head>/<body> " \
+                "or your own <script src=...> CDN tags. No `import`/`export`. Put JSX in <script type='text/babel'> " \
+                "and END with a mount, e.g.: function App(){return <div className='p-4'>…</div>} " \
+                "ReactDOM.createRoot(document.getElementById('root')).render(<App />); — without that mount nothing shows."
+            },
+            mode: {
+              type: "string",
+              enum: %w[replace version],
+              description: "replace (default): update existing artifact with same title. version: always create a new artifact entry."
+            }
+          },
+          required: %w[title html]
+        }
+      end
+
+      def receive(message, context:)
+        title = message[:title] || message["title"]
+        html = message[:html] || message["html"]
+        mode = message[:mode] || message["mode"] || "replace"
+
+        return "Error: 'title' is required" unless title
+        return "Error: 'html' is required" unless html
+
+        return "Error: artifact persistence is unavailable" unless context.env.respond_to?(:persist_artifact)
+
+        context.env.persist_artifact(title: title, html: html, mode: mode, context: context)
+        "Artifact '#{title}' rendered (#{mode}) in the UI."
+      end
+    end
+  end
+end

data/lib/prompt_objects/universal/request_primitive.rb

@@ -3,7 +3,7 @@
 module PromptObjects
   module Universal
     # Universal capability to request a primitive from the human.
-    # Similar to ask_human but specifically for requesting new tools.
+    # Requests explicit approval before installing a new tool implementation.
     # The human can approve, modify, or reject the request.
     class RequestPrimitive < Primitive
       def name

data/lib/prompt_objects/universal/set_env_data.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Universal
+    # Universal capability to create or update shared data scoped to the current delegation chain.
+    # Any PO in the same delegation tree can read this data via get_env_data or list_env_data.
+    # Replaces the previous store_env_data and update_env_data (which were redundant).
+    class SetEnvData < Primitive
+      execution_policy(
+        parallel_safe: true,
+        side_effect: :write,
+        resource_keys: ->(arguments, context, _capability) {
+          key = arguments[:key] || arguments["key"]
+          ["workspace:#{context.workspace_session_id}:env_data:#{key}"]
+        }
+      )
+
+      def name
+        "set_env_data"
+      end
+
+      def description
+        "Create or update a key-value pair in the shared environment data. " \
+        "All POs in the same delegation tree can access this data. " \
+        "If the key already exists, it will be overwritten."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            key: {
+              type: "string",
+              description: "Namespaced identifier for the data (e.g. 'arc_task', 'findings')"
+            },
+            short_description: {
+              type: "string",
+              description: "1-2 sentence summary of what this data contains (for discoverability via list_env_data)"
+            },
+            value: {
+              description: "The data to store (any JSON-serializable value: string, number, object, array)"
+            }
+          },
+          required: %w[key short_description value]
+        }
+      end
+
+      def receive(message, context:)
+        key = message[:key] || message["key"]
+        short_description = message[:short_description] || message["short_description"]
+        # Key-presence check, not `||`, so a literal `false` value isn't dropped.
+        value = message.key?(:value) ? message[:value] : message["value"]
+
+        return "Error: 'key' is required" unless key
+        return "Error: 'short_description' is required" unless short_description
+        return "Error: 'value' is required" if value.nil?
+
+        root_thread_id = context.env_data_scope
+        return "Error: Could not resolve thread scope (no active session)" unless root_thread_id
+
+        store = context.env.session_store
+        return "Error: Session store not available" unless store
+
+        stored_by = context.calling_po || "unknown"
+
+        if context.env.respond_to?(:set_environment_data)
+          context.env.set_environment_data(
+            key: key,
+            short_description: short_description,
+            value: value,
+            context: context
+          )
+          context.bus.publish(
+            from: stored_by,
+            to: "env_data",
+            message: { action: "set", key: key, short_description: short_description }
+          )
+          return "Stored '#{key}' in environment data."
+        end
+
+        store.store_env_data(
+          root_thread_id: root_thread_id,
+          key: key,
+          short_description: short_description,
+          value: value,
+          stored_by: stored_by
+        )
+
+        context.bus.publish(
+          from: stored_by,
+          to: "env_data",
+          message: { action: "set", key: key, short_description: short_description }
+        )
+
+        context.env.notify_env_data_changed(action: "set", root_thread_id: root_thread_id, key: key, stored_by: stored_by)
+
+        "Stored '#{key}' in environment data."
+      end
+    end
+  end
+end

data/lib/prompt_objects/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  VERSION = "0.7.0"
+end

data/lib/prompt_objects.rb

@@ -4,6 +4,9 @@ require "openai"
 require "anthropic"
 require "front_matter_parser"
 require "json"
+require "digest"
+
+require_relative "prompt_objects/version"
 
 # PromptObjects: A framework where markdown files with LLM-backed behavior
 # act as first-class autonomous entities.
@@ -11,11 +14,12 @@ module PromptObjects
   class Error < StandardError; end
 
   # Universal capabilities available to all prompt objects (don't need to be declared)
-  UNIVERSAL_CAPABILITIES = %w[ask_human think create_capability add_capability remove_capability list_capabilities list_primitives add_primitive create_primitive delete_primitive verify_primitive modify_primitive request_primitive modify_prompt].freeze
+  UNIVERSAL_CAPABILITIES = %w[create_capability add_capability remove_capability list_capabilities delete_primitive verify_primitive modify_primitive request_primitive modify_prompt set_env_data get_env_data list_env_data delete_env_data render_artifact dispatch_po get_run_status join_runs].freeze
 end
 
 require_relative "prompt_objects/capability"
 require_relative "prompt_objects/primitive"
+require_relative "prompt_objects/service"
 require_relative "prompt_objects/registry"
 require_relative "prompt_objects/message_bus"
 require_relative "prompt_objects/human_queue"
@@ -26,7 +30,17 @@ require_relative "prompt_objects/llm/anthropic_adapter"
 require_relative "prompt_objects/llm/gemini_adapter"
 require_relative "prompt_objects/llm/factory"
 require_relative "prompt_objects/llm/pricing"
+require_relative "prompt_objects/execution/contracts"
+require_relative "prompt_objects/execution/context"
+require_relative "prompt_objects/execution/blocking_executor"
+require_relative "prompt_objects/execution/permit_pool"
+require_relative "prompt_objects/execution/scheduler"
+require_relative "prompt_objects/execution/policy"
+require_relative "prompt_objects/execution/resource_lock_manager"
+require_relative "prompt_objects/domain/records"
 require_relative "prompt_objects/prompt_object"
+require_relative "prompt_objects/operations/diagnostics"
+require_relative "prompt_objects/operations/retention"
 
 # Environment module (must be loaded before environment.rb which uses them)
 require_relative "prompt_objects/environment/manifest"
@@ -38,28 +52,44 @@ require_relative "prompt_objects/environment"
 
 # Session storage
 require_relative "prompt_objects/session/store"
+require_relative "prompt_objects/repositories/base_repository"
+require_relative "prompt_objects/repositories/workspace_session_repository"
+require_relative "prompt_objects/repositories/thread_repository"
+require_relative "prompt_objects/repositories/run_repository"
+require_relative "prompt_objects/repositories/definition_repository"
+require_relative "prompt_objects/repositories/message_repository"
+require_relative "prompt_objects/repositories/event_repository"
+require_relative "prompt_objects/repositories/tool_execution_repository"
+require_relative "prompt_objects/repositories/artifact_repository"
+require_relative "prompt_objects/repositories/env_data_repository"
+require_relative "prompt_objects/operations/run_trace_builder"
+require_relative "prompt_objects/execution/runner"
 
 # Built-in primitives
 require_relative "prompt_objects/primitives/read_file"
 require_relative "prompt_objects/primitives/list_files"
 require_relative "prompt_objects/primitives/write_file"
 require_relative "prompt_objects/primitives/http_get"
+require_relative "prompt_objects/primitives/think"
 
 # Universal capabilities (available to all prompt objects)
-require_relative "prompt_objects/universal/ask_human"
-require_relative "prompt_objects/universal/think"
 require_relative "prompt_objects/universal/create_capability"
 require_relative "prompt_objects/universal/add_capability"
 require_relative "prompt_objects/universal/remove_capability"
 require_relative "prompt_objects/universal/list_capabilities"
-require_relative "prompt_objects/universal/list_primitives"
-require_relative "prompt_objects/universal/add_primitive"
-require_relative "prompt_objects/universal/create_primitive"
 require_relative "prompt_objects/universal/delete_primitive"
 require_relative "prompt_objects/universal/verify_primitive"
 require_relative "prompt_objects/universal/modify_primitive"
 require_relative "prompt_objects/universal/request_primitive"
 require_relative "prompt_objects/universal/modify_prompt"
+require_relative "prompt_objects/universal/set_env_data"
+require_relative "prompt_objects/universal/get_env_data"
+require_relative "prompt_objects/universal/list_env_data"
+require_relative "prompt_objects/universal/delete_env_data"
+require_relative "prompt_objects/universal/render_artifact"
+require_relative "prompt_objects/universal/dispatch_po"
+require_relative "prompt_objects/universal/get_run_status"
+require_relative "prompt_objects/universal/join_runs"
 
 # Connectors (different interfaces to environments)
 require_relative "prompt_objects/connectors/base"