spurline-dashboard 0.3.0

data/lib/spurline/errors.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+# Eagerly loaded by lib/spurline.rb and ignored by Zeitwerk.
+# This is the one file that breaks the autoloading convention, because
+# error classes must be available before any framework code runs and
+# they define multiple constants directly under Spurline.
+
+module Spurline
+  # Base error for all Spurline errors. Rescue this to catch any framework error.
+  class AgentError < StandardError; end
+
+  # Raised when tainted content (trust: :external or :untrusted) is converted
+  # to a string via #to_s. Use Content#render instead, which applies data fencing.
+  class TaintedContentError < AgentError; end
+
+  # Raised when the injection scanner detects a prompt injection pattern
+  # in content flowing through the context pipeline.
+  class InjectionAttemptError < AgentError; end
+
+  # Raised when the PII filter in :block mode detects personally identifiable
+  # information in content. Switch to :redact mode to allow content through
+  # with PII replaced, or :off to disable filtering.
+  class PIIDetectedError < AgentError; end
+
+  # Raised when a tool execution is denied by the permission system.
+  # Check config/permissions.yml for the tool's permission requirements.
+  class PermissionDeniedError < AgentError; end
+
+  # Raised when code attempts to modify a compiled persona at runtime.
+  # Personas are frozen on class load — define a new persona instead.
+  class PersonaFrozenError < AgentError; end
+
+  # Raised when an agent attempts an invalid lifecycle state transition.
+  # Check Spurline::Lifecycle::States for valid transitions.
+  class InvalidStateError < AgentError; end
+
+  # Raised when a tool call references a tool name not in the registry.
+  # Ensure the tool's spur gem is installed and required.
+  class ToolNotFoundError < AgentError; end
+
+  # Raised when the per-turn tool call limit (guardrails.max_tool_calls) is exceeded.
+  # Increase the limit in the agent's guardrails block or restructure the task.
+  class MaxToolCallsError < AgentError; end
+
+  # Raised when a tool attempts to invoke another tool. Tools are leaf nodes (ADR-003).
+  # Use a Spurline::Skill if you need to compose multiple tools.
+  class NestedToolCallError < AgentError; end
+
+  # Raised when an adapter symbol cannot be resolved in the adapter registry.
+  # Ensure the adapter is registered before referencing it in use_model.
+  class AdapterNotFoundError < AgentError; end
+
+  # Raised when the sqlite3 gem is unavailable but the SQLite session store is used.
+  # Add gem "sqlite3" to the application bundle when configuring :sqlite session storage.
+  class SQLiteUnavailableError < AgentError; end
+
+  # Raised when the pg gem is unavailable but the Postgres session store is used.
+  # Add gem "pg" to the application bundle when configuring :postgres session storage.
+  class PostgresUnavailableError < AgentError; end
+
+  # Raised when persisted session payloads cannot be decoded into Session/Turn objects.
+  # This indicates corrupted or incompatible serialized session data.
+  class SessionDeserializationError < AgentError; end
+
+  # Raised when Spurline.configure or a DSL method receives invalid configuration.
+  # This always fires at class load time, never at runtime.
+  class ConfigurationError < AgentError; end
+
+  # Raised when encrypted credentials exist but no master key can be resolved.
+  class CredentialsMissingKeyError < AgentError; end
+
+  # Raised when encrypted credentials cannot be decrypted (bad key or tampered file).
+  class CredentialsDecryptionError < AgentError; end
+
+  # Raised when a required tool secret cannot be resolved from any configured source.
+  class SecretNotFoundError < AgentError; end
+
+  # Raised when an embedding provider or model fails to produce a valid vector.
+  class EmbedderError < AgentError; end
+
+  # Raised when long-term memory persistence or retrieval fails.
+  class LongTermMemoryError < AgentError; end
+
+  # Raised when a session cannot be suspended from its current state.
+  class SuspensionError < AgentError; end
+
+  # Raised when a resume is attempted for a non-suspended session.
+  class InvalidResumeError < AgentError; end
+
+  # Raised when Cartographer cannot access the target repository path.
+  class CartographerAccessError < AgentError; end
+
+  # Raised when an individual analyzer fails to produce valid output.
+  class AnalyzerError < AgentError; end
+  class ScopeViolationError < AgentError; end
+  class IdempotencyKeyConflictError < AgentError; end
+  class PrivilegeEscalationError < AgentError; end
+  class LedgerError < AgentError; end
+  class TaskEnvelopeError < AgentError; end
+  class MergeConflictError < AgentError; end
+
+  # Raised when a spawned child agent fails during execution.
+  # The message includes parent/child session IDs for audit correlation.
+  class SpawnError < AgentError; end
+
+  # Raised when a toolkit name cannot be resolved in the toolkit registry.
+  # Ensure the toolkit class is defined and loaded before referencing it.
+  class ToolkitNotFoundError < AgentError; end
+end

data/lib/spurline/lifecycle/CLAUDE.md

@@ -0,0 +1,18 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+### Feb 21, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #3782 | 10:23 PM | 🔵 | Spurline session and state machine architecture analyzed for suspended sessions feature | ~700 |
+| #3632 | 6:00 PM | ⚖️ | OpenAI adapter architecture with stop reason normalization and tool call accumulation | ~541 |
+
+### Feb 23, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #4214 | 12:07 AM | 🔴 | Fixed message history accumulation in LLM loop | ~327 |
+</claude-mem-context>

data/lib/spurline/lifecycle/deterministic_runner.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Lifecycle
+    # Executes a fixed sequence of tools without LLM involvement.
+    # This is the deterministic counterpart to Lifecycle::Runner.
+    #
+    # Each tool in the sequence receives accumulated results from previous tools.
+    #
+    # Stop conditions:
+    #   - All tools in the sequence have executed
+    #   - max_tool_calls guardrail exceeded
+    #   - A tool raises an error
+    class DeterministicRunner
+      def initialize(
+        tool_runner:,
+        audit_log:,
+        session:,
+        guardrails: {},
+        scope: nil,
+        idempotency_ledger: nil
+      )
+        @tool_runner = tool_runner
+        @audit_log = audit_log
+        @session = session
+        @guardrails = guardrails
+        @scope = scope
+        @idempotency_ledger = idempotency_ledger
+      end
+
+      # ASYNC-READY: executes tools sequentially, each is a blocking boundary
+      def run(tool_sequence:, input:, session:, &chunk_handler)
+        turn = session.start_turn(input: input)
+        @audit_log.record(:turn_start, turn: turn.number)
+
+        results = {}
+
+        tool_sequence.each_with_index do |step, idx|
+          tool_name, arguments = resolve_step(step, results, input)
+          check_max_tool_calls!(session)
+
+          filtered_arguments = redact_arguments(tool_name, arguments)
+          chunk_handler&.call(
+            Streaming::Chunk.new(
+              type: :tool_start,
+              turn: turn.number,
+              session_id: session.id,
+              metadata: { tool_name: tool_name.to_s, arguments: filtered_arguments }
+            )
+          )
+
+          started = Time.now
+          tool_call = { name: tool_name.to_s, arguments: arguments }
+          result = @tool_runner.execute(
+            tool_call,
+            session: session,
+            scope: @scope,
+            idempotency_ledger: @idempotency_ledger
+          )
+          duration_ms = ((Time.now - started) * 1000).round
+
+          @audit_log.record(
+            :tool_call,
+            tool: tool_name.to_s,
+            arguments: filtered_arguments,
+            duration_ms: duration_ms,
+            turn: turn.number,
+            step: idx + 1
+          )
+
+          chunk_handler&.call(
+            Streaming::Chunk.new(
+              type: :tool_end,
+              turn: turn.number,
+              session_id: session.id,
+              metadata: { tool_name: tool_name.to_s, duration_ms: duration_ms }
+            )
+          )
+
+          results[tool_name.to_sym] = result
+        end
+
+        output_text = build_output_summary(results)
+        output_content = Security::Gates::OperatorConfig.wrap(
+          output_text, key: "deterministic_result"
+        )
+        turn.finish!(output: output_content)
+
+        chunk_handler&.call(
+          Streaming::Chunk.new(
+            type: :done,
+            turn: turn.number,
+            session_id: session.id,
+            metadata: {
+              stop_reason: "deterministic_sequence_complete",
+              tool_count: tool_sequence.length,
+            }
+          )
+        )
+
+        @audit_log.record(
+          :turn_end,
+          turn: turn.number,
+          duration_ms: turn.duration_ms,
+          tool_calls: turn.tool_call_count,
+          mode: :deterministic
+        )
+
+        results
+      end
+
+      private
+
+      # Resolves a step definition into a tool name and arguments hash.
+      #
+      # Steps can be:
+      #   - Symbol: tool name with default arguments (passes input through)
+      #   - Hash with :name and :arguments (static args)
+      #   - Hash with :name and Proc/Lambda :arguments (dynamic args)
+      def resolve_step(step, results_so_far, input)
+        case step
+        when Symbol
+          [step, { input: serialize_input(input) }]
+        when Hash
+          name = step[:name] || step[:tool]
+          unless name
+            raise Spurline::ConfigurationError,
+              "Deterministic sequence step must have a :name or :tool key. " \
+              "Got: #{step.inspect}"
+          end
+
+          args = step[:arguments] || step[:args]
+          [name.to_sym, resolve_arguments(args, results_so_far, input)]
+        else
+          raise Spurline::ConfigurationError,
+            "Deterministic sequence step must be a Symbol or Hash. " \
+            "Got: #{step.class} (#{step.inspect})"
+        end
+      end
+
+      def resolve_arguments(args, results_so_far, input)
+        case args
+        when Proc
+          resolved = args.call(results_so_far, input)
+          unless resolved.is_a?(Hash)
+            raise Spurline::ConfigurationError,
+              "Tool arguments proc/lambda must return a Hash. " \
+              "Got: #{resolved.class} (#{resolved.inspect})"
+          end
+          resolved
+        when Hash
+          args
+        when nil
+          { input: serialize_input(input) }
+        else
+          raise Spurline::ConfigurationError,
+            "Tool arguments must be a Hash, Proc/Lambda, or nil. " \
+            "Got: #{args.class} (#{args.inspect})"
+        end
+      end
+
+      def serialize_input(input)
+        if input.is_a?(Security::Content)
+          input.respond_to?(:render) ? input.render : input.text
+        else
+          input.to_s
+        end
+      end
+
+      def check_max_tool_calls!(session)
+        max = resolve_max_tool_calls
+        return if session.tool_call_count < max
+
+        @audit_log.record(:max_tool_calls_reached, limit: max)
+        raise Spurline::MaxToolCallsError,
+          "Tool call limit reached (#{max}). " \
+          "Increase max_tool_calls in the agent's guardrails block."
+      end
+
+      def resolve_max_tool_calls
+        @guardrails[:max_tool_calls] || 10
+      end
+
+      def redact_arguments(tool_name, arguments)
+        Audit::SecretFilter.filter(
+          arguments,
+          tool_name: tool_name.to_s,
+          registry: @tool_runner.registry
+        )
+      end
+
+      def build_output_summary(results)
+        results.map do |tool_name, result|
+          text =
+            if result.respond_to?(:render)
+              result.render
+            elsif result.respond_to?(:text)
+              result.text.to_s
+            else
+              result.inspect
+            end
+          "#{tool_name}: #{text[0..200]}"
+        end.join("\n")
+      end
+    end
+  end
+end