insika 0.0.1 → 0.1.0

data/lib/insika/workflow.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Insika
+  # Workflow surface (item 22 / COMPETITIVE-ANALYSIS §4.4). A workflow is a Ruby
+  # callable orchestrating RubyLLM Agents/Workflows FROM WITHIN (RubyLLM First);
+  # its durable RUN is a Task (checkpointed, recoverable — stronger than Flue's
+  # at-most-once run record). This module adds the EXPOSED surface the consumer
+  # asked for, matching the honest Flue scope (not Temporal):
+  #   · runId          — the run id (== task id; the Task IS the run record).
+  #   · event stream   — :workflow_started / :workflow_completed on the task stream.
+  #   · I/O by schema  — optional input_schema / output_schema validated at the edges.
+  #
+  # A schema is any dry-schema-compatible validator: `#call(value)` returning a
+  # result that responds to `#success?` and `#errors` (dry-schema's own contract).
+  # As a batteries-included default, a plain JSON Schema Hash (the interlingua the
+  # ToolDefinition already speaks) is accepted and validated by the zero-dependency
+  # Schema below — "config over convention": bring dry-schema for richer contracts,
+  # or hand a JSON Schema for the common case.
+  module Workflow
+    # Bundles a registered workflow's callable factory with its metadata (schemas +
+    # description). Built lazily by WorkflowRegistry#definition — it does NOT resolve
+    # the factory (the Executor resolves inside the fiber; the contract forbids
+    # instantiating outside it). Schema validation touches only the schemas.
+    Definition = Data.define(:name, :description, :input_schema, :output_schema, :factory) do
+      # Raises WorkflowSchemaError (< ValidationError) when the input does not
+      # conform. No-op without an input_schema (parity). Called synchronously by
+      # TriggerWorkflow -> a bad input is a 422 with no run created.
+      def validate_input!(input) = enforce!(input_schema, input, :input)
+
+      # Raises WorkflowSchemaError when the RETURN does not conform. No-op without an
+      # output_schema. Called inside the fiber after the workflow returns -> a bad
+      # output fails the run at the :workflow_schema stage.
+      def validate_output!(output) = enforce!(output_schema, output, :output)
+
+      # Resolves the factory (INSIDE the fiber) and invokes the orchestrator with the
+      # canonical signature `#call(input, context:, tools:)`.
+      def call(input, context:, tools:)
+        factory.call.call(input, context: context, tools: tools)
+      end
+
+      # Discovery view (GET /v1/workflows): name + description + the I/O contract.
+      # A JSON-Schema-backed schema exposes its schema Hash; a duck-typed validator
+      # (dry-schema etc.) is opaque to introspection -> "opaque".
+      def catalog_entry
+        {
+          "name" => name,
+          "description" => description,
+          "input_schema" => schema_view(input_schema),
+          "output_schema" => schema_view(output_schema)
+        }
+      end
+
+      private
+
+      def enforce!(schema, value, phase)
+        return if schema.nil?
+
+        result = schema.call(value)
+        return if result.success?
+
+        raise Insika::WorkflowSchemaError.new(
+          "workflow '#{name}' #{phase}", phase: phase, errors: normalize_errors(result.errors)
+        )
+      end
+
+      # dry-schema returns a MessageSet (responds to #to_h); the built-in Schema
+      # already returns a Hash.
+      def normalize_errors(errors) = errors.respond_to?(:to_h) ? errors.to_h : errors
+
+      def schema_view(schema)
+        return nil if schema.nil?
+
+        schema.respond_to?(:json_schema) ? schema.json_schema : "opaque"
+      end
+    end
+
+    # Zero-dependency instance validator for a plain JSON Schema Hash, speaking the
+    # same safe subset (object/array/string/number/integer/boolean + enum) the
+    # ToolDefinition validates its parameters against. It implements the SAME
+    # `#call(value) -> result{#success?, #errors}` contract as dry-schema, so the
+    # Definition treats both uniformly. Not a full JSON Schema engine (no
+    # composition/$ref — the subset the insika supports everywhere); permissive on
+    # unknown keys (JSON Schema's additionalProperties default).
+    class Schema
+      # dry-schema-compatible result. `errors` is { "field.path" => ["message", …] }.
+      Result = Data.define(:errors) do
+        def success? = errors.empty?
+      end
+
+      # nil -> nil; a callable (dry-schema / proc) -> as-is; a JSON Schema Hash ->
+      # wrapped. Idempotent for an existing Schema (it is callable).
+      def self.coerce(schema)
+        return nil if schema.nil?
+        return schema if schema.respond_to?(:call)
+
+        new(schema)
+      end
+
+      attr_reader :json_schema
+
+      def initialize(json_schema)
+        unless json_schema.is_a?(Hash)
+          raise Insika::ValidationError, "workflow schema must be a JSON Schema object or a #call-able validator"
+        end
+
+        @json_schema = Insika::Coercion.deep_stringify(json_schema)
+      end
+
+      def call(value)
+        Result.new(errors: collect(@json_schema, value, "").freeze)
+      end
+
+      private
+
+      # -> { path => [messages] }. Empty = valid.
+      def collect(schema, value, path)
+        type = schema["type"].to_s
+        return { key(path) => ["must be #{type}, got #{ruby_type(value)}"] } unless type.empty? || matches?(type, value)
+
+        errors = {}
+        case type
+        when "object" then check_object(schema, value, path, errors)
+        when "array"  then check_array(schema, value, path, errors)
+        end
+        check_enum(schema, value, path, errors)
+        errors
+      end
+
+      def check_object(schema, value, path, errors)
+        props = schema["properties"] || {}
+        Array(schema["required"]).each do |name|
+          errors[key(join(path, name))] = ["is required"] unless value.key?(name.to_s) || value.key?(name.to_sym)
+        end
+        props.each do |name, subschema|
+          next unless value.key?(name.to_s) || value.key?(name.to_sym)
+
+          sub = value[name.to_s] || value[name.to_sym]
+          errors.merge!(collect(subschema || {}, sub, join(path, name)))
+        end
+      end
+
+      def check_array(schema, value, path, errors)
+        items = schema["items"]
+        return if items.nil?
+
+        value.each_with_index { |el, i| errors.merge!(collect(items, el, "#{join(path, i)}")) }
+      end
+
+      def check_enum(schema, value, path, errors)
+        return unless schema.key?("enum")
+
+        allowed = Array(schema["enum"])
+        errors[key(path)] = ["must be one of #{allowed.inspect}"] unless allowed.include?(value)
+      end
+
+      def matches?(type, value)
+        case type
+        when "object"  then value.is_a?(Hash)
+        when "array"   then value.is_a?(Array)
+        when "string"  then value.is_a?(String)
+        when "integer" then value.is_a?(Integer) && !value.is_a?(TrueClass) && !value.is_a?(FalseClass)
+        when "number"  then value.is_a?(Numeric) && !value.is_a?(TrueClass) && !value.is_a?(FalseClass)
+        when "boolean" then value == true || value == false
+        else true # unknown type in the schema -> do not block (permissive)
+        end
+      end
+
+      def ruby_type(value)
+        case value
+        when Hash then "object"
+        when Array then "array"
+        when String then "string"
+        when Integer then "integer"
+        when Numeric then "number"
+        when true, false then "boolean"
+        when nil then "null"
+        else value.class.name.downcase
+        end
+      end
+
+      def join(path, segment) = path.empty? ? segment.to_s : "#{path}.#{segment}"
+      def key(path) = path.empty? ? "(root)" : path
+    end
+  end
+end

data/lib/insika/workflow_registry.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Insika
+  # Workflow registry. A workflow is a Ruby callable with the signature
+  # `#call(input, context:, tools:)` that orchestrates RubyLLM Agents/Workflows FROM
+  # WITHIN (RubyLLM First): `context:` is the ContextPackage, `tools:` are
+  # instances already filtered by the Resolution. Execution = one logical turn;
+  # checkpoint at the end. Nothing is validated at registration (the callable may come
+  # via a factory block). Consumed by the TriggerWorkflow handler.
+  #
+  # Item 22 / §4.4 — the EXPOSED surface: a registration may carry `input_schema:` /
+  # `output_schema:` (a JSON Schema Hash or any dry-schema-compatible validator) and a
+  # `description:` in its metadata. `definition` bundles them with the factory into a
+  # Workflow::Definition (schemas resolved, factory left lazy); `catalog` is the
+  # discovery view (GET /v1/workflows).
+  class WorkflowRegistry < Registry
+    # -> Workflow::Definition (does NOT resolve the factory — the Executor resolves
+    # inside the fiber). Raises NotFoundError for an unregistered name.
+    def definition(name)
+      e = entry(name)
+      Insika::Workflow::Definition.new(
+        name: e.name,
+        description: e.metadata[:description],
+        input_schema: Insika::Workflow::Schema.coerce(e.metadata[:input_schema]),
+        output_schema: Insika::Workflow::Schema.coerce(e.metadata[:output_schema]),
+        factory: e.factory
+      )
+    end
+
+    # Discovery: [{ "name", "description", "input_schema", "output_schema" }, …].
+    def catalog = entries.map { |e| definition(e.name).catalog_entry }
+  end
+end

data/lib/insika.rb

@@ -1,7 +1,206 @@
 # frozen_string_literal: true
 
 require_relative "insika/version"
-
-# Insika — name reserved. Project under active development.
-module Insika
-end
+require_relative "insika/errors"
+require_relative "insika/coercion"
+require_relative "insika/message_origin"
+require_relative "insika/env_schema"
+require_relative "insika/allowlist"
+require_relative "insika/event"
+require_relative "insika/agent_profile"
+require_relative "insika/subagent_graph"
+require_relative "insika/model_policy"
+require_relative "insika/model_selection"
+require_relative "insika/model_resolver"
+require_relative "insika/tool_definition"
+require_relative "insika/tool_manifest"
+require_relative "insika/frontmatter"
+require_relative "insika/token_estimator"
+require_relative "insika/checkpoint"
+require_relative "insika/command"
+require_relative "insika/hooks"
+require_relative "insika/middleware"
+# Production edge (item 33 / §12 G7): windowed counters + the rate-limit/cost
+# Middleware. Both inert until configured (nil/0 = off).
+require_relative "insika/usage_ledger"
+require_relative "insika/edge_limiter"
+# Content safety / guardrails (RFC-0009). detectors.rb is self-contained (the eval
+# requires it directly, D4); the rest hang off Middleware/hooks seams. No ruby_llm
+# at load-time — Factory requires the gem lazily, like the Executor's create_chat.
+require_relative "insika/safety/detectors"
+require_relative "insika/safety/safe_responses"
+require_relative "insika/safety/config"
+require_relative "insika/safety/moderator"
+require_relative "insika/safety/output_filter"
+require_relative "insika/safety/input_guardrail"
+require_relative "insika/safety/output_validator"
+require_relative "insika/safety/factory"
+require_relative "insika/context/fragment"
+require_relative "insika/context/priority"
+require_relative "insika/context/provider"
+require_relative "insika/context/catalog_provider"
+require_relative "insika/context/builder"
+require_relative "insika/context/providers/request"
+require_relative "insika/context/providers/prompt"
+require_relative "insika/context/providers/skill"
+require_relative "insika/context/providers/tool_search"
+require_relative "insika/context/providers/memory"
+require_relative "insika/context/providers/session"
+require_relative "insika/policy/policy"
+require_relative "insika/policy/engine"
+require_relative "insika/registry"
+require_relative "insika/tool_registry"
+require_relative "insika/workflow"
+require_relative "insika/workflow_registry"
+require_relative "insika/policy_registry"
+require_relative "insika/capability_registry"
+require_relative "insika/prompt_catalog"
+require_relative "insika/plugin"
+require_relative "insika/plugin/loader"
+require_relative "insika/store"
+require_relative "insika/stores/memory"
+require_relative "insika/stores/sqlite"
+require_relative "insika/session_store"
+require_relative "insika/task_store"
+require_relative "insika/checkpoint_store"
+require_relative "insika/pending_action_store"
+require_relative "insika/delegation_store"
+# Channels (RFC-0011): the outbound record + the inbound retry window. Both are
+# plain stores; the channel objects themselves come after the HTTP client.
+require_relative "insika/outbox_store"
+require_relative "insika/inbound_log"
+require_relative "insika/memory_store"
+require_relative "insika/config_store"
+require_relative "insika/profile_source"
+require_relative "insika/agent_file_store"
+require_relative "insika/skill_store"
+require_relative "insika/secret_masking"
+require_relative "insika/tool_store"
+require_relative "insika/tool_trace_store"
+# Refinement (RFC-0013 phase A): the run record + the evidence half of the loop.
+# Reads sessions/tasks/traces above; requires Safety::Detectors (loaded earlier) for
+# the PII redaction of the snippets it puts in a report.
+require_relative "insika/refinement_store"
+require_relative "insika/refinement/evidence_collector"
+# The candidate format is pure data + validation, so it loads with the collector;
+# the GATE needs the evals module and the stores, so it waits for them below.
+require_relative "insika/refinement/candidate"
+# The proposer only needs the candidate format and an injected `ask` — the provider
+# gem is required lazily, inside the factory, so requiring Insika still loads nothing.
+require_relative "insika/refinement/proposer"
+require_relative "insika/egress_guard"
+require_relative "insika/schema_guard"
+require_relative "insika/sandbox"
+require_relative "insika/http_client"
+# Channels (RFC-0011 §4/§6): the registry, the bundled relay adapter and the
+# out-of-band dispatcher. After http_client and egress_guard — the relay POSTs
+# through both — and after registry.rb, which ChannelRegistry extends.
+require_relative "insika/channel_registry"
+require_relative "insika/channels/relay"
+require_relative "insika/channels/web"
+require_relative "insika/channel_delivery"
+require_relative "insika/overlay_tool_registry"
+require_relative "insika/settings_store"
+require_relative "insika/llm_provider_store"
+require_relative "insika/llm_configurator"
+# LLM-first onboarding surface (item 20 / §5.6): serves start.md + models.json + the
+# public docs. Reads the settings/provider stores above at call-time (order is free).
+require_relative "insika/onboarding"
+# Evals (RFC-0008) — the quality harness, moved under lib/ so the engine can call it
+# (the RFC-0013 refinement gate scores a candidate agent with the SAME judge the CLI
+# uses; a second copy would be the worst outcome). It stays a CLIENT of the engine:
+# HttpTransport talks to a running deployment, nothing here reads a store. Pure Ruby +
+# stdlib; the judge's provider call is injected, so no ruby_llm at load time.
+require_relative "insika/evals/golden"
+require_relative "insika/evals/assertions"
+require_relative "insika/evals/judge"
+require_relative "insika/evals/pairwise"
+require_relative "insika/evals/runner"
+require_relative "insika/evals/report"
+require_relative "insika/evals/baseline"
+require_relative "insika/evals/transport"
+# Authored eval cases (RFC-0013 §3.7): the corpus becomes editable without a
+# checkout. Requires the loader above (it is the one validator).
+require_relative "insika/golden_store"
+require_relative "insika/baseline_store"
+# RFC-0013 §3.5: scores a candidate by REPLAYING it. After evals (the runner and
+# the baseline comparison) and after the stores it clones an agent through.
+require_relative "insika/refinement/gate"
+# RFC-0013 §3.9 (phase D): the proposer PANEL and the run's token budget. Needs the
+# candidate format and the gate's Report shape, so it loads after both.
+require_relative "insika/refinement/panel"
+require_relative "insika/mcp_store"
+require_relative "insika/mcp_http_client"
+require_relative "insika/mcp_tool_ingestor"
+require_relative "insika/system_file_store"
+require_relative "insika/recovery"
+require_relative "insika/command_bus"
+require_relative "insika/commands/create_session"
+require_relative "insika/commands/cancel_task"
+require_relative "insika/commands/pause_task"
+require_relative "insika/commands/approve_action"
+require_relative "insika/commands/send_message"
+require_relative "insika/commands/resume_task"
+require_relative "insika/commands/trigger_workflow"
+require_relative "insika/commands/agent_payload"
+require_relative "insika/commands/create_agent"
+require_relative "insika/commands/update_agent"
+require_relative "insika/commands/delete_agent"
+require_relative "insika/commands/set_agent_tools"
+require_relative "insika/commands/write_agent_file"
+require_relative "insika/commands/delete_agent_file"
+require_relative "insika/commands/restore_agent_file"
+require_relative "insika/commands/write_skill"
+require_relative "insika/commands/set_skill_agents"
+require_relative "insika/commands/memory_put_fact"
+require_relative "insika/commands/memory_forget_fact"
+require_relative "insika/commands/memory_add_note"
+require_relative "insika/commands/run_refinement"
+require_relative "insika/commands/gate_refinement"
+require_relative "insika/commands/resolve_refinement"
+require_relative "insika/commands/write_golden"
+require_relative "insika/commands/update_settings"
+require_relative "insika/commands/upsert_llm_provider"
+require_relative "insika/commands/delete_llm_provider"
+require_relative "insika/commands/upsert_mcp"
+require_relative "insika/commands/delete_mcp"
+require_relative "insika/commands/write_system_file"
+require_relative "insika/commands/delete_system_file"
+require_relative "insika/commands/restore_system_file"
+require_relative "insika/commands/write_data_tool"
+require_relative "insika/commands/delete_data_tool"
+require_relative "insika/commands/restore_data_tool"
+require_relative "insika/commands/import_tools"
+require_relative "insika/commands/import_mcp_tools"
+require_relative "insika/event_stream"
+require_relative "insika/task_actor"
+require_relative "insika/queue_policy"
+require_relative "insika/session_actor"
+require_relative "insika/skill_catalog"
+require_relative "insika/tool_catalog"
+require_relative "insika/steer_injector"
+require_relative "insika/turn_output"
+require_relative "insika/turn_state"
+require_relative "insika/turn_timing"
+require_relative "insika/capability/resolved_tool"
+require_relative "insika/tool_envelope"
+require_relative "insika/tool_assembly"
+require_relative "insika/chat_builder"
+require_relative "insika/executor"
+require_relative "insika/shutdown"
+require_relative "insika/pack"
+require_relative "insika/pack_importer"
+require_relative "insika/telemetry"
+# Strict config + diagnosis (item 23 / §8.1). Doctor reads the config stores above;
+# EnvSchema (required at the top) is its env layer.
+require_relative "insika/doctor"
+# Shared composition core for both roots (config/wiring.rb + config/deployment.rb).
+# Only references the classes above at call-time, so require order is unconstrained.
+require_relative "insika/wiring/graph"
+# Public Ruby DSL (item 36): Insika.agent { … }. The Builder is gem-free (it only
+# generates a Pack); the runtime (chat/serve) is required lazily by Definition, so
+# `require "insika"` stays free of ruby_llm and the HTTP server.
+require_relative "insika/dsl"
+# Do NOT require "insika/tools/load_skill" here: it does `require "ruby_llm"` at
+# the top (inherits from RubyLLM::Tool) and would pull the gem in at load-time. The
+# Executor loads it lazily inside create_chat (D9).