prompt_objects 0.5.0 → 0.7.0

data/lib/prompt_objects/environment.rb

@@ -16,6 +16,19 @@ module PromptObjects
       @tui_mode = false
     end
 
+    # Resolve the workspace scope for shared environment data.
+    # @return [String, nil] Scope id, or nil if it can't be resolved
+    def env_data_scope
+      store = env.session_store
+      return nil unless store
+
+      if env.respond_to?(:env_data_scope)
+        env.env_data_scope
+      elsif env.respond_to?(:active_session_id) && env.active_session_id
+        env.active_session_id
+      end
+    end
+
     # Log a message to the bus.
     # @param to [String] Destination capability
     # @param message [String, Hash] The message
@@ -34,14 +47,31 @@ module PromptObjects
   # The runtime environment that holds all capabilities and coordinates execution.
   # Can be initialized either from:
   # - A user environment directory (with manifest.yml, git integration)
-  # - A simple objects directory (legacy/development mode)
+  # - A simple objects directory backed by an in-memory runtime store
   class Runtime
+    DEFAULT_SCHEDULER_OPTIONS = {
+      worker_limit: 4,
+      provider_limit: 4,
+      tool_limit: 8,
+      cpu_limit: 2,
+      max_active_runs: 64,
+      max_active_per_po: 4,
+      max_queued_per_thread: 20,
+      max_delegation_depth: 8,
+      max_descendants: 64,
+      run_event_retention: Operations::Retention::DEFAULT_RUN_EVENT_LIMIT,
+      workspace_event_retention: Operations::Retention::DEFAULT_WORKSPACE_EVENT_LIMIT
+    }.freeze
+
     attr_reader :llm, :registry, :objects_dir, :bus, :primitives_dir, :human_queue,
                 :manifest, :env_path, :auto_commit, :session_store,
-                :current_provider, :current_model
+                :current_provider, :current_model, :services, :connectors, :active_session_id,
+                :runtime_model
     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
+    attr_accessor :on_broadcast  # Callback for services to push messages to all WebSocket clients
 
     # Initialize from an environment path (with manifest) or objects directory.
     # @param env_path [String, nil] Path to environment directory (preferred)
@@ -51,12 +81,15 @@ module PromptObjects
     # @param provider [String, nil] LLM provider (openai, anthropic, gemini)
     # @param model [String, nil] Model name
     # @param auto_commit [Boolean] Auto-commit changes to git (default: true for env_path)
-    def initialize(env_path: nil, objects_dir: nil, primitives_dir: nil, llm: nil, provider: nil, model: nil, auto_commit: nil)
+    def initialize(env_path: nil, objects_dir: nil, primitives_dir: nil, llm: nil, provider: nil, model: nil,
+                   auto_commit: nil, runtime_model: nil, scheduler_options: nil)
       if env_path
         # Environment-based initialization
         @env_path = env_path
         @objects_dir = File.join(env_path, "objects")
         @primitives_dir = primitives_dir || File.join(env_path, "primitives")
+        @services_dir = File.join(env_path, "services")
+        @connectors_dir = File.join(env_path, "connectors")
         @manifest = Env::Manifest.load_from_dir(env_path)
         @auto_commit = auto_commit.nil? ? true : auto_commit
         @manifest.touch_opened!
@@ -70,10 +103,20 @@ module PromptObjects
         @env_path = nil
         @objects_dir = objects_dir || "objects"
         @primitives_dir = primitives_dir || File.join(File.dirname(@objects_dir), "primitives")
+        @services_dir = nil
+        @connectors_dir = nil
         @manifest = nil
         @auto_commit = auto_commit || false
-        @session_store = nil  # No persistent sessions in legacy mode
+        @session_store = Session::Store.new(":memory:")
+      end
+
+      @runtime_model = "runs"
+      if @manifest && @manifest.runtime_model != "runs"
+        @manifest.runtime_model = "runs"
+        @manifest.save_to_dir(@env_path)
       end
+      @scheduler_options = DEFAULT_SCHEDULER_OPTIONS.merge(scheduler_options || {})
+      @child_admission_mutex = Mutex.new
 
       # Initialize LLM - prefer explicit llm, then use factory with provider/model
       if llm
@@ -81,17 +124,43 @@ module PromptObjects
         @current_provider = nil
         @current_model = nil
       else
-        @current_provider = provider || LLM::Factory::DEFAULT_PROVIDER
-        @current_model = model || LLM::Factory.default_model(@current_provider)
+        manifest_llm = @manifest&.llm || {}
+        @current_provider = provider || manifest_llm["provider"] || LLM::Factory::DEFAULT_PROVIDER
+        manifest_model = manifest_llm["model"] unless provider
+        @current_model = model || manifest_model || LLM::Factory.default_model(@current_provider)
         @llm = LLM::Factory.create(provider: @current_provider, model: @current_model)
       end
 
       @registry = Registry.new
       @bus = MessageBus.new(session_store: @session_store)
       @human_queue = HumanQueue.new
+      # In-memory boot-cycle activity. Autonomous POs can opt to stay dormant
+      # until a human has initialized them during this server run; persisted
+      # sessions from a previous run intentionally do not arm the timer.
+      @human_message_received = {}
+      @autonomous_schedule_states = {}
+      @autonomous_schedule_mutex = Mutex.new
+
+      # Paths the app just wrote itself (via PO#save / #update_source). The
+      # FileWatcher consults this so an in-app save doesn't trigger a redundant,
+      # disruptive reload of a PO that's mid-conversation — the in-memory PO is
+      # already up to date. Manual/external edits aren't registered, so they
+      # still hot-reload normally.
+      @suppressed_reloads = {}
+      @suppressed_reloads_mutex = Mutex.new
+
+      validate_dependencies if @manifest&.dependencies&.any?
 
       register_primitives
       register_universal_capabilities
+
+      @services = []
+      load_custom_services
+
+      @connectors = []
+      load_custom_connectors
+
+      recover_interrupted_runs
     end
 
     # Create runtime from a user environment by name.
@@ -111,7 +180,7 @@ module PromptObjects
       @manifest&.name || File.basename(@objects_dir)
     end
 
-    # Check if this is an environment-based runtime (vs legacy objects_dir).
+    # Check if this runtime has a persisted environment directory.
     # @return [Boolean]
     def environment?
       !@env_path.nil?
@@ -139,15 +208,24 @@ module PromptObjects
     # @param model [String, nil] Model name (defaults to provider's default)
     # @return [Hash] New provider/model info
     def switch_llm(provider:, model: nil)
-      @current_provider = provider
-      @current_model = model || LLM::Factory.default_model(provider)
-      @llm = LLM::Factory.create(provider: @current_provider, model: @current_model)
+      new_provider = provider
+      new_model = model || LLM::Factory.default_model(provider)
+      new_llm = LLM::Factory.create(provider: new_provider, model: new_model)
+
+      @current_provider = new_provider
+      @current_model = new_model
+      @llm = new_llm
 
       # Update all loaded POs to use the new LLM
       @registry.prompt_objects.each do |po|
         po.instance_variable_set(:@llm, @llm)
       end
 
+      if @manifest
+        @manifest.llm = { "provider" => @current_provider, "model" => @current_model }
+        @manifest.save_to_dir(@env_path)
+      end
+
       { provider: @current_provider, model: @current_model }
     end
 
@@ -216,6 +294,27 @@ module PromptObjects
       @on_po_modified&.call(po)
     end
 
+    # Mark a file path as just-written-by-the-app, so the FileWatcher skips the
+    # next reload event for it. Idempotent; absolute paths recommended.
+    # @param path [String]
+    def suppress_next_reload(path)
+      return unless path
+
+      key = File.expand_path(path)
+      @suppressed_reloads_mutex.synchronize { @suppressed_reloads[key] = true }
+    end
+
+    # Whether a pending in-app save should suppress the next reload of this path.
+    # Consumes the suppression (returns true at most once per registration).
+    # @param path [String]
+    # @return [Boolean]
+    def reload_suppressed?(path)
+      return false unless path
+
+      key = File.expand_path(path)
+      @suppressed_reloads_mutex.synchronize { !!@suppressed_reloads.delete(key) }
+    end
+
     # Notify that a PO-to-PO delegation has started or completed.
     # @param event_type [Symbol] :started or :completed
     # @param payload [Hash] { target:, caller:, thread_id:, tool_call_id: }
@@ -223,6 +322,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]
@@ -267,22 +375,1162 @@ module PromptObjects
       @registry.primitives.map(&:name)
     end
 
+    # --- Environment Session API ---
+
+    # Get or create the active environment session.
+    # @param initiated_by [String] Who initiated the session (default: "human")
+    # @return [Hash] Session data
+    def active_session(initiated_by: "human")
+      @active_session_id ||= find_or_create_environment_session(initiated_by: initiated_by)
+      @session_store&.get_session(@active_session_id)
+    end
+
+    # Resolve the env_data scope id for a given session, preferring the
+    # environment-level session (v8). Used by server-side readers (REST API,
+    # WebSocket, broadcasts) so they read from the same scope writers use.
+    # @param session_id [String, nil] A session to fall back to if no env session
+    # @return [String, nil] Scope id
+    def env_data_scope(session_id = nil)
+      return @active_session_id if @active_session_id
+      return nil unless @session_store && session_id
+
+      @session_store.resolve_root_thread(session_id)
+    end
+
+    # Create a new environment session, making it the active one.
+    # @param name [String, nil] Optional session name
+    # @param initiated_by [String] Who initiated (human, timer, api, etc.)
+    # @return [Hash] Session data
+    def create_environment_session(name: nil, initiated_by: "human")
+      return nil unless @session_store
+
+      id = SecureRandom.uuid
+      workspace_repository.create(id: id, name: name)
+      id = @session_store.create_session(
+        id: id,
+        po_name: nil,
+        name: name,
+        source: "web",
+        thread_type: "root",
+        workspace_session_id: id
+      )
+      @active_session_id = id
+      @session_store.get_session(id)
+    end
+
+    # List the environment-level sessions (the shared-context "jams") with a
+    # flag marking which one is active. Side-effect-free: reads the already-
+    # resolved @active_session_id rather than calling active_session (which
+    # would create a session on read), and queries the store once.
+    # @return [Array<Hash>]
+    def environment_sessions
+      return [] unless @session_store
+
+      active = @active_session_id
+      @session_store.list_environment_sessions.map do |s|
+        s.merge(active: s[:id] == active)
+      end
+    end
+
+    # Switch the active environment session (changes the shared env_data scope).
+    # @param session_id [String]
+    # @return [Hash, nil] The now-active session, or nil if not found
+    def switch_active_session(session_id)
+      return nil unless @session_store
+
+      session = @session_store.get_session(session_id)
+      return nil unless session
+
+      @active_session_id = session_id
+      session
+    end
+
+    # Rename an environment session.
+    # @return [Hash, nil] The updated session
+    def rename_session(session_id, name)
+      return nil unless @session_store && @session_store.get_session(session_id)
+
+      @session_store.update_session(session_id, name: name)
+      @session_store.get_session(session_id)
+    end
+
+    # Delete an environment session (and its messages). If it was active, the
+    # next active_session call will find or create another.
+    # @return [Boolean]
+    def delete_environment_session(session_id)
+      return false unless @session_store && @session_store.get_session(session_id)
+
+      @session_store.delete_session(session_id)
+      @active_session_id = nil if @active_session_id == session_id
+      true
+    end
+
+    # Inject a message through the run scheduler. All sources share this entry
+    # point and differ only in their provenance and source-specific thread.
+    #
+    # @param target_po [String] Name of the PO to receive the message
+    # @param content [String] Message content
+    # @param from_source [String] Message source (human, timer:name, service:name, api)
+    # @return [String] The PO's response
+    def inject_message(target_po:, content:, from_source: "human",
+                       workspace_session_id: nil, thread_id: nil, client_request_id: nil, deadline: nil)
+      po = @registry.get(target_po)
+      raise Error, "Unknown prompt object: #{target_po}" unless po.is_a?(PromptObject)
+
+      inject_run_message(
+        po: po,
+        content: content,
+        from_source: from_source,
+        workspace_session_id: workspace_session_id,
+        thread_id: thread_id,
+        client_request_id: client_request_id,
+        deadline: deadline
+      )
+    end
+
+    def enqueue_run(target_po:, content:, from_source: "human", workspace_session_id: nil,
+                    thread_id: nil, client_request_id: nil, deadline: nil)
+      po = @registry.get(target_po)
+      raise Error, "Unknown prompt object: #{target_po}" unless po.is_a?(PromptObject)
+
+      workspace_id = resolve_workspace_id(workspace_session_id, initiated_by: from_source)
+      thread = resolve_run_thread(
+        workspace_id: workspace_id,
+        po: po,
+        from_source: from_source,
+        thread_id: thread_id
+      )
+      # enqueue_run is the canonical entry point used by WebSocket, REST, CLI,
+      # connectors, and inject_message. Arm wait-for-human schedules here so a
+      # valid human run wakes autonomous POs regardless of which surface sent it.
+      @human_message_received[target_po] = true if from_source == "human"
+      definition = execution_definition_for(po)
+      source_type = source_type_for(from_source)
+      if source_type == "autonomous"
+        active = run_repository.active_for_source(
+          workspace_session_id: workspace_id,
+          po_name: po.name,
+          source_type: source_type,
+          source_name: from_source
+        )
+        return active if active
+      end
+      normalized_deadline = normalize_deadline(deadline)
+      run, created = run_repository.enqueue_with_result(
+        workspace_session_id: workspace_id,
+        thread_id: thread.id,
+        po_name: po.name,
+        input_content: content,
+        definition_version: definition.version,
+        provider: definition.provider,
+        model: definition.model,
+        capability_policy_version: definition.capability_policy_version,
+        source_type: source_type,
+        source_name: from_source,
+        client_request_id: client_request_id,
+        priority: priority_for(from_source),
+        metadata: { deadline: normalized_deadline&.iso8601(6) }.compact
+      )
+      definition_repository.attach(run_id: run.id, definition: definition) unless definition_repository.get(run.id)
+      if created
+        broadcast_workspace_snapshot(workspace_id)
+        publish_run_event(event_repository.append_run_event(
+          run_id: run.id,
+          kind: "run_queued",
+          data: { source_type: run.source_type, turn_ordinal: run.turn_ordinal }
+        ))
+        broadcast_po_runtime_status(run)
+      end
+      run
+    end
+
+    def execution_definition_for(po)
+      po.execution_definition(
+        provider: current_provider,
+        model: current_model,
+        capability_policy_version: capability_policy_version_for_config(po.config)
+      )
+    end
+
+    def capability_policy_version_for_config(config)
+      names = Array(config["capabilities"] || config[:capabilities]) + UNIVERSAL_CAPABILITIES
+      signatures = names.uniq.sort.map do |name|
+        capability = registry.get(name)
+        [name, capability&.execution_policy_signature || "missing"]
+      end
+      Digest::SHA256.hexdigest(JSON.generate(signatures))
+    end
+
+    def execute_run(run_id, tui_mode: true)
+      run = run_repository.get(run_id)
+      raise Error, "Unknown run: #{run_id}" unless run
+      return run.final_response if run.status == "completed"
+      return :queued unless run.status == "queued"
+
+      run_scheduler.submit(run, deadline: run_deadline(run), tui_mode: tui_mode).wait
+    rescue Execution::Scheduler::RejectedError => e
+      reject_queued_run(run, e.message)
+      raise Error, e.message
+    end
+
+    def execute_message_run(target_po:, content:, from_source:, workspace_session_id: nil,
+                            thread_id: nil, client_request_id: nil, deadline: nil, tui_mode: false)
+      run = enqueue_run(
+        target_po: target_po,
+        content: content,
+        from_source: from_source,
+        workspace_session_id: workspace_session_id,
+        thread_id: thread_id,
+        client_request_id: client_request_id,
+        deadline: deadline
+      )
+      response = execute_run(run.id, tui_mode: tui_mode)
+      [run_repository.get(run.id), response]
+    end
+
+    def cancel_run(run_id, reason: "cancelled")
+      run = run_repository.get(run_id)
+      return false unless run
+
+      cancelled = @run_scheduler&.cancel(run_id, reason: reason)
+      unless cancelled
+        return false unless run.status == "queued"
+
+        cancel_queued_run(run, reason)
+        cancelled = true
+      end
+      run_repository.active_children(parent_run_id: run_id).each do |child|
+        next if metadata_value(child, :child_lifetime) == "detached"
+
+        cancel_run(child.id, reason: "parent cancelled: #{reason}")
+      end
+      cancelled
+    end
+
+    def schedule_run(run_id, tui_mode: true)
+      run = run_repository.get(run_id)
+      raise Error, "Unknown run: #{run_id}" unless run
+      return nil unless run.status == "queued"
+
+      run_scheduler.submit(run, deadline: run_deadline(run), tui_mode: tui_mode)
+    rescue Execution::Scheduler::RejectedError => e
+      reject_queued_run(run, e.message)
+      raise Error, e.message
+    end
+
+    def with_child_run_admission(parent)
+      @child_admission_mutex.synchronize do
+        depth = run_depth(parent) + 1
+        raise Error, "Maximum delegation depth exceeded" if depth > @scheduler_options.fetch(:max_delegation_depth)
+        if run_repository.descendant_count(root_run_id: parent.root_run_id) >= @scheduler_options.fetch(:max_descendants)
+          raise Error, "Maximum run descendant count exceeded"
+        end
+
+        yield depth
+      end
+    end
+
+    def dispatch_run(target_po:, content:, context:, thread_id: nil, lifetime: "attached", on_complete: nil)
+      raise Error, "Dispatch requires a run context" unless context.run_id
+      raise Error, "lifetime must be attached or detached" unless %w[attached detached].include?(lifetime)
+
+      parent = run_repository.get(context.run_id)
+      raise Error, "Unknown parent run: #{context.run_id}" unless parent
+      validate_dispatch_target!(parent.po_name, target_po)
+      target = registry.get(target_po)
+      definition = execution_definition_for(target)
+      thread = nil
+      child = nil
+      with_child_run_admission(parent) do |depth|
+        thread = if thread_id
+                   required_dispatch_thread(thread_id, parent, target_po)
+                 else
+                   thread_repository.create(
+                     workspace_session_id: parent.workspace_session_id,
+                     po_name: target_po,
+                     thread_type: "delegation",
+                     parent_thread_id: parent.thread_id,
+                     parent_run_id: parent.id,
+                     retention_policy: "full"
+                   )
+                 end
+        child = run_repository.enqueue(
+          workspace_session_id: parent.workspace_session_id,
+          thread_id: thread.id,
+          po_name: target_po,
+          input_content: content,
+          definition_version: definition.version,
+          provider: definition.provider,
+          model: definition.model,
+          capability_policy_version: definition.capability_policy_version,
+          source_type: "delegation",
+          source_name: parent.po_name,
+          parent_run_id: parent.id,
+          priority: 80,
+          metadata: {
+            dispatch_mode: "dispatch",
+            child_lifetime: lifetime,
+            delegation_depth: depth,
+            deadline: context.deadline&.iso8601(6),
+            on_complete: on_complete
+          }
+        )
+      end
+      definition_repository.attach(run_id: child.id, definition: definition)
+      publish_workspace_snapshot(parent.workspace_session_id)
+      publish_run_event(event_repository.append_run_event(
+        run_id: child.id,
+        kind: "run_queued",
+        data: { source_type: child.source_type, turn_ordinal: child.turn_ordinal, mode: "dispatch" }
+      ))
+      publish_run_event(event_repository.append_run_event(
+        run_id: parent.id,
+        kind: "delegation_started",
+        data: {
+          child_run_id: child.id,
+          child_thread_id: thread.id,
+          target_po: target_po,
+          mode: "dispatch",
+          lifetime: lifetime
+        }
+      ))
+      schedule_run(child.id, tui_mode: context.tui_mode)
+      { run_id: child.id, thread_id: thread.id, status: child.status, lifetime: lifetime }
+    end
+
+    def join_runs(run_ids, context:, timeout: nil)
+      Array(run_ids).map { |run_id| join_run(run_id, context: context, timeout: timeout) }
+    end
+
+    def run_status(run_id, context:)
+      run = authorized_related_run(run_id, context)
+      serialize_runtime_value(run.to_h)
+    end
+
+    def join_run(run_id, context:, timeout: nil)
+      run = authorized_related_run(run_id, context)
+      unless terminal_run_status?(run.status)
+        ticket = run_scheduler.ticket(run.id)
+        ticket ||= schedule_run(run.id, tui_mode: context.tui_mode)
+        ticket = run_scheduler.help(run.id) || ticket
+        ticket&.wait(timeout: timeout)
+        run = run_repository.get(run.id)
+      end
+      {
+        run_id: run.id,
+        thread_id: run.thread_id,
+        status: run.status,
+        response: run.final_response,
+        error: run.error_message
+      }
+    rescue Timeout::Error
+      { run_id: run_id, status: "waiting", error: "join timed out" }
+    end
+
+    def shutdown_execution(wait: true)
+      @run_scheduler&.shutdown(wait: wait)
+      @run_scheduler = nil
+    end
+
+    def operational_diagnostics
+      Operations::Diagnostics.new(@session_store).snapshot(
+        scheduler: {
+          queued: @run_scheduler&.queued_count || 0,
+          running: @run_scheduler&.running_count || 0,
+          provider_permits_available: provider_permits.available,
+          tool_permits_available: tool_permits.available,
+          cpu_permits_available: cpu_permits.available,
+          locked_resource_count: resource_lock_manager.locked_keys.length
+        },
+        limits: @scheduler_options.slice(
+          :worker_limit, :provider_limit, :tool_limit, :cpu_limit, :max_active_runs,
+          :max_active_per_po, :max_queued_per_thread, :max_delegation_depth, :max_descendants,
+          :run_event_retention, :workspace_event_retention
+        )
+      )
+    end
+
+    def enforce_retention
+      Operations::Retention.new(@session_store).prune_events!(
+        run_event_limit: @scheduler_options.fetch(:run_event_retention),
+        workspace_event_limit: @scheduler_options.fetch(:workspace_event_retention)
+      )
+    end
+
+    def create_runtime_thread(workspace_session_id:, po_name:, thread_type: "human", name: nil,
+                              parent_thread_id: nil, parent_run_id: nil)
+      workspace_id = resolve_workspace_id(workspace_session_id, initiated_by: "human")
+      po = @registry.get(po_name)
+      raise Error, "Unknown prompt object: #{po_name}" unless po.is_a?(PromptObject)
+
+      thread = thread_repository.create(
+        workspace_session_id: workspace_id,
+        po_name: po_name,
+        thread_type: thread_type,
+        name: name,
+        parent_thread_id: parent_thread_id,
+        parent_run_id: parent_run_id,
+        retention_policy: thread_type == "autonomous" ? "summary" : "full"
+      )
+      broadcast_workspace_snapshot(workspace_id)
+      broadcast(**thread_snapshot_envelope(thread))
+      thread
+    end
+
+    def rename_runtime_thread(thread_id, name:)
+      thread = required_runtime_thread(thread_id)
+      renamed = thread_repository.rename(thread.id, name)
+      broadcast_workspace_snapshot(thread.workspace_session_id)
+      renamed
+    end
+
+    def archive_runtime_thread(thread_id)
+      thread = required_runtime_thread(thread_id)
+      archived = thread_repository.archive(thread.id)
+      broadcast_workspace_snapshot(thread.workspace_session_id)
+      archived
+    end
+
+    def runtime_snapshot_envelopes(workspace_session_id: nil)
+      workspace_id = resolve_workspace_id(workspace_session_id, initiated_by: "reconnect")
+      threads = thread_repository.list(workspace_session_id: workspace_id, include_archived: true)
+      active_runs = run_repository.list(
+        workspace_session_id: workspace_id,
+        statuses: %w[queued running waiting],
+        limit: 500
+      )
+      events = active_runs.flat_map do |run|
+        event_repository.run_events(run_id: run.id).map do |event|
+          {
+            version: Execution::Contracts::PROTOCOL_VERSION,
+            type: "run_event",
+            payload: serialize_runtime_value(event.to_h)
+          }
+        end
+      end
+      [workspace_snapshot_envelope(workspace_id)] +
+        threads.map { |thread| thread_snapshot_envelope(thread) } +
+        events +
+        [env_data_snapshot_envelope(workspace_id)]
+    end
+
+    def publish_workspace_snapshot(workspace_session_id)
+      broadcast_workspace_snapshot(workspace_session_id)
+    end
+
+    def publish_thread_snapshot(thread_id, po_name: nil)
+      thread = thread_repository.get(thread_id)
+      raise Error, "Unknown thread: #{thread_id}" unless thread
+
+      broadcast_thread_snapshot(thread, po_name || thread.po_name)
+    end
+
+    # Persist an artifact before exposing it to clients. The artifact repository
+    # is authoritative for identity, provenance, and revision history.
+    def persist_artifact(title:, html:, mode:, context:)
+      workspace_id = artifact_workspace_id(context)
+      owner_po = context.calling_po || (context.respond_to?(:target_po) ? context.target_po : nil) || "unknown"
+      owner_thread_id = artifact_owner_thread_id(context, owner_po)
+      producing_run_id = context.respond_to?(:run_id) ? context.run_id : nil
+      mutation = artifact_repository.upsert_with_cursor(
+        workspace_session_id: workspace_id,
+        owner_po: owner_po,
+        owner_thread_id: owner_thread_id,
+        producing_run_id: producing_run_id,
+        title: title,
+        html: html,
+        mode: mode,
+        metadata: {}
+      )
+      artifact = mutation.artifact
+
+      broadcast(
+        version: Execution::Contracts::PROTOCOL_VERSION,
+        type: "artifact_upserted",
+        payload: {
+          cursor: mutation.cursor,
+          artifact: serialize_runtime_value(artifact.to_h)
+        }
+      )
+      if producing_run_id
+        publish_run_event(event_repository.append_run_event(
+          run_id: producing_run_id,
+          kind: "artifact_upserted",
+          data: {
+            artifact_id: artifact.id,
+            title: artifact.title,
+            revision: artifact.revision,
+            owner_thread_id: artifact.owner_thread_id,
+            mode: artifact.mode
+          }
+        ))
+      end
+      artifact
+    end
+
+    def set_environment_data(key:, short_description:, value:, context:)
+      workspace_id = environment_data_workspace_id(context)
+      stored_by = context.calling_po || (context.respond_to?(:target_po) ? context.target_po : nil) || "unknown"
+      unless workspace_repository.get(workspace_id)
+        @session_store.store_env_data(
+          root_thread_id: workspace_id,
+          key: key,
+          short_description: short_description,
+          value: value,
+          stored_by: stored_by
+        )
+        notify_env_data_changed(
+          action: "set", root_thread_id: workspace_id, key: key, stored_by: stored_by
+        )
+        return @session_store.get_env_data(root_thread_id: workspace_id, key: key)
+      end
+      mutation = env_data_repository.set_with_cursor(
+        workspace_session_id: workspace_id,
+        key: key,
+        short_description: short_description,
+        value: value,
+        stored_by: stored_by
+      )
+      publish_env_data_snapshot(workspace_id, cursor: mutation.cursor)
+      publish_environment_data_run_event(context, action: "set", key: key, stored_by: stored_by)
+      notify_env_data_changed(
+        action: "set",
+        root_thread_id: workspace_id,
+        key: key,
+        stored_by: stored_by
+      )
+      mutation.entry
+    end
+
+    def get_environment_data(key:, context:)
+      workspace_id = environment_data_workspace_id(context)
+      if workspace_repository.get(workspace_id)
+        env_data_repository.get(workspace_session_id: workspace_id, key: key)
+      else
+        @session_store.get_env_data(root_thread_id: workspace_id, key: key)
+      end
+    end
+
+    def list_environment_data(context:)
+      workspace_id = environment_data_workspace_id(context)
+      if workspace_repository.get(workspace_id)
+        env_data_repository.list(workspace_session_id: workspace_id)
+      else
+        @session_store.list_env_data_full(root_thread_id: workspace_id)
+      end
+    end
+
+    def delete_environment_data(key:, context:)
+      workspace_id = environment_data_workspace_id(context)
+      stored_by = context.calling_po || (context.respond_to?(:target_po) ? context.target_po : nil) || "unknown"
+      unless workspace_repository.get(workspace_id)
+        deleted = @session_store.delete_env_data(root_thread_id: workspace_id, key: key)
+        if deleted
+          notify_env_data_changed(
+            action: "delete", root_thread_id: workspace_id, key: key, stored_by: stored_by
+          )
+        end
+        return deleted
+      end
+      removal = env_data_repository.delete_with_cursor(
+        workspace_session_id: workspace_id,
+        key: key,
+        stored_by: stored_by
+      )
+      return false unless removal.deleted
+
+      publish_env_data_snapshot(workspace_id, cursor: removal.cursor)
+      publish_environment_data_run_event(context, action: "delete", key: key, stored_by: stored_by)
+      notify_env_data_changed(
+        action: "delete",
+        root_thread_id: workspace_id,
+        key: key,
+        stored_by: stored_by
+      )
+      true
+    end
+
+    def inject_run_message(po:, content:, from_source:, workspace_session_id: nil,
+                           thread_id: nil, client_request_id: nil, deadline: nil)
+      run = enqueue_run(
+        target_po: po.name,
+        content: content,
+        from_source: from_source,
+        workspace_session_id: workspace_session_id,
+        thread_id: thread_id,
+        client_request_id: client_request_id,
+        deadline: deadline
+      )
+      execute_run(run.id)
+    end
+
+    # Whether a PO has received a new human message during this runtime boot.
+    # Used by opt-in autonomous schedules that must not preempt initialization.
+    def human_message_received?(po_name)
+      !!@human_message_received[po_name]
+    end
+
+    # Publish truthful autonomous scheduling state for reconnectable UI
+    # countdowns. The scheduler owns these transitions; clients only render the
+    # server-provided next_run_at instead of guessing from page-load time.
+    def update_autonomous_schedule(po_name, **state)
+      payload = @autonomous_schedule_mutex.synchronize do
+        current = @autonomous_schedule_states[po_name] || { po_name: po_name }
+        @autonomous_schedule_states[po_name] = current.merge(state).freeze
+      end
+      broadcast(type: "autonomous_schedule", payload: payload)
+      payload
+    end
+
+    def autonomous_schedule_states
+      @autonomous_schedule_mutex.synchronize do
+        @autonomous_schedule_states.transform_values(&:dup)
+      end
+    end
+
+    # Broadcast a message to all connected WebSocket clients.
+    # No-op if on_broadcast callback isn't set (e.g., in tests or CLI mode).
+    # @param message [Hash] WebSocket message to broadcast
+    def broadcast(**message)
+      @on_broadcast&.call(message)
+    rescue => e
+      # Don't crash if broadcast fails
+    end
+
+    def publish_run_event(event)
+      broadcast(
+        version: Execution::Contracts::PROTOCOL_VERSION,
+        type: "run_event",
+        payload: serialize_runtime_value(event.to_h)
+      )
+    end
+
     private
 
+    def normalize_deadline(deadline)
+      return nil if deadline.nil? || deadline.to_s.empty?
+      return deadline if deadline.is_a?(Time)
+
+      Time.iso8601(deadline.to_s)
+    rescue ArgumentError
+      raise Error, "deadline must be an ISO 8601 timestamp"
+    end
+
+    def run_deadline(run)
+      normalize_deadline(metadata_value(run, :deadline))
+    end
+
+    def workspace_repository
+      @workspace_repository ||= Repositories::WorkspaceSessionRepository.new(@session_store)
+    end
+
+    def thread_repository
+      @thread_repository ||= Repositories::ThreadRepository.new(@session_store)
+    end
+
+    def run_repository
+      @run_repository ||= Repositories::RunRepository.new(@session_store)
+    end
+
+    def definition_repository
+      @definition_repository ||= Repositories::DefinitionRepository.new(@session_store)
+    end
+
+    def runtime_message_repository
+      @runtime_message_repository ||= Repositories::MessageRepository.new(@session_store)
+    end
+
+    def event_repository
+      @event_repository ||= Repositories::EventRepository.new(@session_store)
+    end
+
+    def artifact_repository
+      @artifact_repository ||= Repositories::ArtifactRepository.new(@session_store)
+    end
+
+    def env_data_repository
+      @env_data_repository ||= Repositories::EnvDataRepository.new(@session_store)
+    end
+
+    def artifact_workspace_id(context)
+      context_workspace = context.respond_to?(:workspace_session_id) ? context.workspace_session_id : nil
+      workspace_id = context_workspace || active_session(initiated_by: "artifact")&.dig(:id)
+      raise Error, "No active workspace for artifact" unless workspace_id
+
+      workspace_id
+    end
+
+    def artifact_owner_thread_id(context, owner_po)
+      context_thread = context.respond_to?(:thread_id) ? context.thread_id : nil
+      return context_thread if context_thread
+
+      nil
+    end
+
+    def environment_data_workspace_id(context)
+      context_workspace = context.respond_to?(:workspace_session_id) ? context.workspace_session_id : nil
+      workspace_id = context_workspace || context.env_data_scope
+      raise Error, "No active workspace for environment data" unless workspace_id
+
+      workspace_id
+    end
+
+    def publish_env_data_snapshot(workspace_id, cursor: nil)
+      broadcast(**env_data_snapshot_envelope(workspace_id, cursor: cursor))
+    end
+
+    def publish_environment_data_run_event(context, action:, key:, stored_by:)
+      run_id = context.respond_to?(:run_id) ? context.run_id : nil
+      return unless run_id
+
+      publish_run_event(event_repository.append_run_event(
+        run_id: run_id,
+        kind: "env_data_changed",
+        data: { action: action, key: key, stored_by: stored_by }
+      ))
+    end
+
+    def execution_runner
+      @execution_runner ||= Execution::Runner.new(
+        self,
+        event_publisher: method(:publish_run_event),
+        provider_permits: provider_permits,
+        tool_permits: tool_permits,
+        cpu_permits: cpu_permits,
+        resource_lock_manager: resource_lock_manager
+      )
+    end
+
+    def provider_permits
+      @provider_permits ||= Execution::PermitPool.new(@scheduler_options.fetch(:provider_limit))
+    end
+
+    def tool_permits
+      @tool_permits ||= Execution::PermitPool.new(@scheduler_options.fetch(:tool_limit))
+    end
+
+    def cpu_permits
+      @cpu_permits ||= Execution::PermitPool.new(@scheduler_options.fetch(:cpu_limit))
+    end
+
+    def resource_lock_manager
+      @resource_lock_manager ||= Execution::ResourceLockManager.new
+    end
+
+    def run_scheduler
+      @run_scheduler ||= begin
+        Execution::Scheduler.new(
+          worker_limit: @scheduler_options.fetch(:worker_limit),
+          max_active_runs: @scheduler_options.fetch(:max_active_runs),
+          max_active_per_po: @scheduler_options.fetch(:max_active_per_po),
+          max_queued_per_thread: @scheduler_options.fetch(:max_queued_per_thread),
+          execute: method(:execute_scheduled_run),
+          ready: ->(run) { run_repository.thread_head?(run) },
+          cancel_queued: method(:cancel_queued_run)
+        )
+      end
+    end
+
+    def execute_scheduled_run(run, cancellation_token, options)
+      thread = thread_repository.get(run.thread_id)
+      raise Error, "Unknown thread: #{run.thread_id}" unless thread
+
+      broadcast_po_runtime_status(run)
+      execution_runner.execute(
+        run.id,
+        cancellation_token: cancellation_token,
+        tui_mode: options.fetch(:tui_mode, true)
+      )
+    ensure
+      publish_dispatch_completion(run)
+      broadcast_thread_snapshot(thread, run.po_name) if thread && thread.thread_type != "autonomous"
+      broadcast_workspace_snapshot(run.workspace_session_id)
+      broadcast_po_runtime_status(run)
+    end
+
+    def cancel_queued_run(run, reason)
+      cancelled = run_repository.transition(run.id, status: "cancelled", cancellation_reason: reason)
+      publish_run_event(event_repository.append_run_event(
+        run_id: run.id,
+        kind: "run_cancelled",
+        data: { reason: reason }
+      ))
+      broadcast_workspace_snapshot(run.workspace_session_id)
+      broadcast_po_runtime_status(cancelled)
+      @run_scheduler&.wake
+      publish_dispatch_completion(cancelled)
+      cancelled
+    end
+
+    def reject_queued_run(run, reason)
+      skipped = run_repository.transition(run.id, status: "skipped", cancellation_reason: reason)
+      publish_run_event(event_repository.append_run_event(
+        run_id: run.id,
+        kind: "run_skipped",
+        data: { reason: reason }
+      ))
+      broadcast_workspace_snapshot(run.workspace_session_id)
+      broadcast_po_runtime_status(skipped)
+      @run_scheduler&.wake
+      publish_dispatch_completion(skipped)
+      skipped
+    end
+
+    def recover_interrupted_runs
+      return if @recovery_complete
+
+      workspace_id = active_session(initiated_by: "recovery")[:id]
+      run_repository.list(
+        workspace_session_id: workspace_id,
+        statuses: %w[running waiting],
+        limit: 10_000
+      ).each do |run|
+        run_repository.transition(run.id, status: "interrupted")
+        publish_run_event(event_repository.append_run_event(
+          run_id: run.id,
+          kind: "run_interrupted",
+          data: { reason: "process restarted" }
+        ))
+      end
+      @recovery_complete = true
+    end
+
+    def broadcast_po_runtime_status(run)
+      active = run_repository.active_count(
+        workspace_session_id: run.workspace_session_id,
+        po_name: run.po_name
+      )
+      broadcast(
+        type: "po_state",
+        payload: { name: run.po_name, state: { status: active.positive? ? "thinking" : "idle" } }
+      )
+    end
+
+    def validate_dispatch_target!(caller_name, target_name)
+      target = registry.get(target_name)
+      raise Error, "Unknown dispatch target: #{target_name}" unless target.is_a?(PromptObject)
+
+      caller = registry.get(caller_name)
+      allowed = Array(caller&.config&.dig("capabilities"))
+      raise Error, "#{caller_name} cannot dispatch to #{target_name}" unless allowed.include?(target_name)
+    end
+
+    def required_dispatch_thread(thread_id, parent, target_po)
+      thread = thread_repository.get(thread_id)
+      unless thread && thread.workspace_session_id == parent.workspace_session_id && thread.po_name == target_po
+        raise Error, "Thread not found for dispatch target #{target_po}: #{thread_id}"
+      end
+
+      thread
+    end
+
+    def run_depth(run)
+      depth = metadata_value(run, :delegation_depth)
+      return depth.to_i if depth
+
+      current = run
+      count = 0
+      while current.parent_run_id
+        count += 1
+        current = run_repository.get(current.parent_run_id)
+        break unless current
+      end
+      count
+    end
+
+    def authorized_related_run(run_id, context)
+      parent = run_repository.get(context.run_id)
+      run = run_repository.get(run_id)
+      raise Error, "Unknown run: #{run_id}" unless run
+      unless parent && run.workspace_session_id == parent.workspace_session_id && run.root_run_id == parent.root_run_id
+        raise Error, "Run is outside the caller's execution tree: #{run_id}"
+      end
+
+      run
+    end
+
+    def terminal_run_status?(status)
+      %w[completed failed cancelled skipped interrupted].include?(status)
+    end
+
+    def publish_dispatch_completion(run)
+      return unless metadata_value(run, :dispatch_mode) == "dispatch" && run.parent_run_id
+      return unless terminal_run_status?(run_repository.get(run.id)&.status)
+
+      existing = event_repository.run_events(run_id: run.parent_run_id).any? do |event|
+        event.kind == "delegation_completed" && event.data[:child_run_id] == run.id
+      end
+      return if existing
+
+      current = run_repository.get(run.id)
+      publish_run_event(event_repository.append_run_event(
+        run_id: run.parent_run_id,
+        kind: "delegation_completed",
+        data: {
+          child_run_id: run.id,
+          child_thread_id: run.thread_id,
+          target_po: run.po_name,
+          mode: "dispatch",
+          status: current.status
+        }
+      ))
+      enqueue_dispatch_followup(current)
+    end
+
+    def metadata_value(run, key)
+      return nil unless run
+
+      run.metadata.key?(key) ? run.metadata[key] : run.metadata[key.to_s]
+    end
+
+    def enqueue_dispatch_followup(child)
+      instruction = metadata_value(child, :on_complete)
+      return if instruction.to_s.empty?
+
+      parent = run_repository.get(child.parent_run_id)
+      return unless parent
+      return if %w[cancelled interrupted].include?(parent.status)
+
+      target = registry.get(parent.po_name)
+      return unless target.is_a?(PromptObject)
+
+      definition = execution_definition_for(target)
+      followup = run_repository.enqueue(
+        workspace_session_id: parent.workspace_session_id,
+        thread_id: parent.thread_id,
+        po_name: parent.po_name,
+        input_content: "#{instruction}\n\nDispatched run #{child.id} finished with status #{child.status}.",
+        definition_version: definition.version,
+        provider: definition.provider,
+        model: definition.model,
+        capability_policy_version: definition.capability_policy_version,
+        source_type: "delegation",
+        source_name: child.po_name,
+        client_request_id: "dispatch_completion:#{child.id}",
+        parent_run_id: child.id,
+        priority: 80,
+        metadata: { completion_trigger_for: child.id }
+      )
+      definition_repository.attach(run_id: followup.id, definition: definition) unless definition_repository.get(followup.id)
+      return unless followup.status == "queued" && event_repository.run_events(run_id: followup.id).empty?
+
+      publish_workspace_snapshot(parent.workspace_session_id)
+      publish_run_event(event_repository.append_run_event(
+        run_id: followup.id,
+        kind: "run_queued",
+        data: { source_type: followup.source_type, turn_ordinal: followup.turn_ordinal, trigger_run_id: child.id }
+      ))
+      schedule_run(followup.id)
+    end
+
+    def resolve_workspace_id(requested_id, initiated_by:)
+      active_id = active_session(initiated_by: initiated_by)[:id]
+      if requested_id && requested_id != active_id
+        raise Error, "Workspace session is not active: #{requested_id}"
+      end
+
+      active_id
+    end
+
+    def required_runtime_thread(thread_id)
+      thread = thread_repository.get(thread_id)
+      raise Error, "Unknown thread: #{thread_id}" unless thread
+
+      resolve_workspace_id(thread.workspace_session_id, initiated_by: "human")
+      thread
+    end
+
+    def resolve_run_thread(workspace_id:, po:, from_source:, thread_id:)
+      if thread_id
+        thread = thread_repository.get(thread_id)
+        unless thread && thread.workspace_session_id == workspace_id && thread.po_name == po.name
+          raise Error, "Thread not found for #{po.name}: #{thread_id}"
+        end
+        return thread
+      end
+
+      thread_type = thread_type_for(from_source)
+      existing = thread_repository.list(workspace_session_id: workspace_id, po_name: po.name)
+        .find { |thread| thread.thread_type == thread_type }
+      existing || thread_repository.create(
+        workspace_session_id: workspace_id,
+        po_name: po.name,
+        thread_type: thread_type,
+        retention_policy: thread_type == "autonomous" ? "summary" : "full"
+      )
+    end
+
+    def thread_type_for(from_source)
+      return "human" if from_source == "human"
+      return "autonomous" if from_source.start_with?("timer:")
+      return "artifact" if from_source.start_with?("artifact:")
+      return "service" if from_source.start_with?("service:")
+
+      "api"
+    end
+
+    def source_type_for(from_source)
+      thread_type_for(from_source)
+    end
+
+    def priority_for(from_source)
+      case thread_type_for(from_source)
+      when "human" then 100
+      when "artifact" then 90
+      when "delegation" then 80
+      when "api" then 60
+      when "service" then 40
+      else 10
+      end
+    end
+
+    def broadcast_thread_snapshot(thread, _po_name)
+      messages = runtime_message_repository.list(thread_id: thread.id, limit: 10_000)
+      broadcast(**thread_snapshot_envelope(thread, messages: messages))
+    end
+
+    def broadcast_workspace_snapshot(workspace_id)
+      broadcast(**workspace_snapshot_envelope(workspace_id))
+    end
+
+    def workspace_snapshot_envelope(workspace_id)
+      workspace = workspace_repository.get(workspace_id)
+      raise Error, "Unknown workspace session: #{workspace_id}" unless workspace
+
+      {
+        version: Execution::Contracts::PROTOCOL_VERSION,
+        type: "workspace_snapshot",
+        payload: {
+          cursor: event_repository.current_cursor(workspace_session_id: workspace_id),
+          workspace: serialize_runtime_value(workspace.to_h),
+          threads: thread_repository.list(
+            workspace_session_id: workspace_id,
+            include_archived: true
+          ).map { |thread| serialize_runtime_value(thread.to_h) },
+          runs: run_repository.list(
+            workspace_session_id: workspace_id,
+            limit: 500
+          ).map { |run| serialize_runtime_value(run.to_h) },
+          artifacts: artifact_repository.list(
+            workspace_session_id: workspace_id
+          ).map { |artifact| serialize_runtime_value(artifact.to_h) }
+        }
+      }
+    end
+
+    def env_data_snapshot_envelope(workspace_id, cursor: nil)
+      {
+        version: Execution::Contracts::PROTOCOL_VERSION,
+        type: "env_data_snapshot",
+        payload: {
+          workspace_session_id: workspace_id,
+          cursor: cursor || event_repository.current_cursor(workspace_session_id: workspace_id),
+          entries: env_data_repository.list(
+            workspace_session_id: workspace_id
+          ).map { |entry| serialize_runtime_value(entry) }
+        }
+      }
+    end
+
+    def thread_snapshot_envelope(thread, messages: nil)
+      messages ||= runtime_message_repository.list(thread_id: thread.id, limit: 10_000)
+      {
+        version: Execution::Contracts::PROTOCOL_VERSION,
+        type: "thread_snapshot",
+        payload: {
+          cursor: event_repository.current_cursor(workspace_session_id: thread.workspace_session_id),
+          thread: serialize_runtime_value(thread.to_h),
+          messages: messages.map { |message| serialize_runtime_message(message) }
+        }
+      }
+    end
+
+    def serialize_runtime_value(value)
+      case value
+      when Time then value.iso8601
+      when Hash then value.to_h { |key, nested| [key, serialize_runtime_value(nested)] }
+      when Array then value.map { |nested| serialize_runtime_value(nested) }
+      else value
+      end
+    end
+
+    def serialize_runtime_message(message)
+      serialize_runtime_value(message).merge(
+        id: message[:message_uid] || message[:id].to_s,
+        cursor_id: message[:id]
+      )
+    end
+
+    # Find the most recent environment session or create one. Looks only at
+    # environment-level sessions (po_name IS NULL), not per-PO sessions, so the
+    # active session is a real shared-context container.
+    def find_or_create_environment_session(initiated_by: "human")
+      return nil unless @session_store
+
+      existing = @session_store.list_environment_sessions(limit: 1)
+      return existing.first[:id] if existing.any?
+
+      create_environment_session(initiated_by: initiated_by)[:id]
+    end
+
+    # Load vendored gems and validate declared dependencies.
+    # Templates can vendor gems in vendor/<gem-name>/lib/ to avoid
+    # requiring users to install gems or fight Bundler isolation.
+    # Falls back to system gem activation for non-vendored deps.
+    def validate_dependencies
+      load_vendored_gems
+
+      gems = @manifest.dependencies["gems"]
+      return unless gems.is_a?(Array) && gems.any?
+
+      missing = gems.filter_map do |gem_info|
+        name = gem_info["name"]
+        # Check if the gem is already loadable (vendored or system)
+        begin
+          require name
+          nil
+        rescue LoadError
+          gem_info
+        end
+      end
+
+      return if missing.empty?
+
+      install_cmds = missing.map { |g| "  gem install #{g['name']}  # #{g['purpose']}" }
+      warn "Warning: Missing dependencies for environment '#{@manifest.name}':"
+      install_cmds.each { |cmd| warn cmd }
+      warn "\nSome primitives may not load. Install the gems and restart."
+    end
+
+    # Add vendor/<gem>/lib directories to $LOAD_PATH so vendored
+    # gems are requireable without system installation.
+    def load_vendored_gems
+      return unless @env_path
+
+      vendor_dir = File.join(@env_path, "vendor")
+      return unless Dir.exist?(vendor_dir)
+
+      Dir.glob(File.join(vendor_dir, "*", "lib")).sort.each do |lib_path|
+        $LOAD_PATH.unshift(lib_path) unless $LOAD_PATH.include?(lib_path)
+      end
+    end
+
     # Register built-in primitive capabilities.
     def register_primitives
       @registry.register(Primitives::ReadFile.new)
       @registry.register(Primitives::ListFiles.new)
       @registry.register(Primitives::WriteFile.new)
       @registry.register(Primitives::HttpGet.new)
+      @registry.register(Primitives::Think.new)
 
       # Load custom primitives from environment's primitives directory
       load_custom_primitives
     end
 
     # Load custom primitives from the environment's primitives/ directory.
-    # Follows the same pattern as Universal::CreatePrimitive for class naming
-    # and loading. Warns on errors rather than crashing so a broken primitive
+    # Derives the class name from the filename (snake_case -> CamelCase), the
+    # same convention create_capability uses when it generates a primitive.
+    # Warns on errors rather than crashing so a broken primitive
     # file doesn't prevent the environment from starting (a PO can fix it).
     def load_custom_primitives
       return unless @primitives_dir && Dir.exist?(@primitives_dir)
@@ -294,7 +1542,7 @@ module PromptObjects
           load(path)
           klass = PromptObjects::Primitives.const_get(class_name)
           @registry.register(klass.new)
-        rescue SyntaxError, StandardError => e
+        rescue SyntaxError, LoadError, StandardError => e
           warn "Warning: Failed to load custom primitive #{path}: #{e.message}"
         end
       end
@@ -302,20 +1550,104 @@ module PromptObjects
 
     # Register universal capabilities (available to all prompt objects).
     def register_universal_capabilities
-      @registry.register(Universal::AskHuman.new)
-      @registry.register(Universal::Think.new)
       @registry.register(Universal::CreateCapability.new)
       @registry.register(Universal::AddCapability.new)
       @registry.register(Universal::RemoveCapability.new)
       @registry.register(Universal::ListCapabilities.new)
-      @registry.register(Universal::ListPrimitives.new)
-      @registry.register(Universal::AddPrimitive.new)
-      @registry.register(Universal::CreatePrimitive.new)
       @registry.register(Universal::DeletePrimitive.new)
       @registry.register(Universal::VerifyPrimitive.new)
       @registry.register(Universal::ModifyPrimitive.new)
       @registry.register(Universal::RequestPrimitive.new)
       @registry.register(Universal::ModifyPrompt.new)
+      @registry.register(Universal::SetEnvData.new)
+      @registry.register(Universal::GetEnvData.new)
+      @registry.register(Universal::ListEnvData.new)
+      @registry.register(Universal::DeleteEnvData.new)
+      @registry.register(Universal::RenderArtifact.new)
+      @registry.register(Universal::DispatchPO.new)
+      @registry.register(Universal::GetRunStatus.new)
+      @registry.register(Universal::JoinRuns.new)
+    end
+
+    # Load custom services from the environment's services/ directory.
+    # Services are background processes with a tick loop, following
+    # the same loading pattern as custom primitives.
+    def load_custom_services
+      return unless @services_dir && Dir.exist?(@services_dir)
+
+      Dir.glob(File.join(@services_dir, "*.rb")).sort.each do |path|
+        begin
+          filename = File.basename(path, ".rb")
+          class_name = filename.split("_").map(&:capitalize).join
+          load(path)
+          klass = PromptObjects::Services.const_get(class_name)
+          service = klass.new(runtime: self)
+          @services << service
+        rescue SyntaxError, LoadError, StandardError => e
+          warn "Warning: Failed to load service #{path}: #{e.message}"
+        end
+      end
+    end
+
+    public
+
+    # Start all loaded services by calling their start method.
+    # Does NOT schedule tick loops — that's the server's responsibility
+    # using Async tasks (see Server.start).
+    def start_services
+      @services.each do |service|
+        begin
+          service.start
+        rescue => e
+          warn "Warning: Failed to start service #{service.name}: #{e.message}"
+        end
+      end
+    end
+
+    # Stop all running services.
+    def stop_services
+      @services.each do |service|
+        service.stop
+      rescue => e
+        warn "Warning: Failed to stop service #{service.name}: #{e.message}"
+      end
+    end
+
+    # Load connectors from the environment's connectors/ directory. A connector
+    # is a Connectors::Base subclass that bridges an external system (Discord,
+    # Slack, a webhook listener, …) to POs by calling inject_message. Loaded
+    # like services; started/stopped with the server.
+    def load_custom_connectors
+      return unless @connectors_dir && Dir.exist?(@connectors_dir)
+
+      Dir.glob(File.join(@connectors_dir, "*.rb")).sort.each do |path|
+        begin
+          class_name = File.basename(path, ".rb").split("_").map(&:capitalize).join
+          load(path)
+          klass = PromptObjects::Connectors.const_get(class_name)
+          @connectors << klass.new(runtime: self)
+        rescue SyntaxError, LoadError, StandardError => e
+          warn "Warning: Failed to load connector #{path}: #{e.message}"
+        end
+      end
+    end
+
+    # Start all loaded connectors. Each connector manages its own loop/thread.
+    def start_connectors
+      @connectors.each do |connector|
+        connector.start
+      rescue => e
+        warn "Warning: Failed to start connector #{connector.source_name}: #{e.message}"
+      end
+    end
+
+    # Stop all running connectors.
+    def stop_connectors
+      @connectors.each do |connector|
+        connector.stop
+      rescue => e
+        warn "Warning: Failed to stop connector #{connector.source_name}: #{e.message}"
+      end
     end
   end