samagotchi 0.2.0

data/lib/samagotchi/worker_idle_exit.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # When a background session worker nobody uses should exit. The session is
+  # saved after every turn, so the next send wakes a new worker with the
+  # conversation intact; what lives only in memory (metrics, the Bridge's
+  # event ring, the last recap) is lost.
+  #
+  # The worker stays up while any of these holds:
+  # * a turn runs, or input is queued for one;
+  # * a client holds the Bridge's stream (an attached TUI, even an idle one,
+  #   or a web tab);
+  # * a reminder is registered. Reminders live only in the Engine and repeat
+  #   until the agent cancels them, so an exit would drop them for good;
+  # * a continue offer waits for an answer; it too lives only in memory;
+  # * less than the timeout has passed since the worker started, the Engine's
+  #   last activity, or the last client request or disconnect.
+  #
+  # A client can also ask the worker to exit now (`/exit` in the attached
+  # TUI, Bridge POST /exit): #hold_for_request applies the same rules without
+  # the timeout and leaves out the asking client's own stream.
+  class WorkerIdleExit
+    # @param engine [Engine] #turn_running?, #last_activity_at, #reminder_store
+    # @param bridge [Bridge, nil] #open_streams, #last_client_activity_at; nil
+    #   when the worker's Bridge failed to start
+    # @param timeout_minutes [Numeric, nil] 0 or nil: never exit
+    # @param input_pending [#call] true while input files wait
+    # @param awaiting_continue [#call] true while a continue offer waits
+    # @param clock [#call] monotonic seconds, the Engine's and Bridge's clock
+    def initialize(engine:, bridge:, timeout_minutes:, input_pending:, awaiting_continue: -> { false },
+                   clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      @engine = engine
+      @bridge = bridge
+      @timeout = timeout_minutes.to_f * 60
+      @input_pending = input_pending
+      @awaiting_continue = awaiting_continue
+      @clock = clock
+      @started_at = clock.call
+    end
+
+    # @return [Boolean] whether the worker should exit now
+    def due?
+      hold.nil?
+    end
+
+    # What keeps the worker up, or nil when nothing does.
+    # @return [Symbol, nil] :disabled, :turn_running, :input_queued,
+    #   :continue_offered, :client_connected, :reminders or :recent_activity
+    def hold
+      return :disabled unless @timeout.positive?
+      return :turn_running if @engine.turn_running?
+      return :input_queued if @input_pending.call
+      return :continue_offered if @awaiting_continue.call
+      return :client_connected if @bridge && @bridge.open_streams.positive?
+      return :reminders if @engine.reminder_store&.any?
+      return :recent_activity if idle_seconds < @timeout
+
+      nil
+    end
+
+    # What keeps the worker up when a client asks it to exit now, or nil
+    # when nothing does. The timeout doesn't apply, even 0 ("never idle
+    # out"): the request is explicit.
+    # @param requester [String, nil] the asking client's id; its own streams
+    #   don't hold
+    # @param streams [Boolean] false: other clients' streams don't hold
+    #   either (the last check before leaving, when the asker's stream may
+    #   still be open, untagged)
+    # @return [Symbol, nil] :turn_running, :input_queued, :continue_offered,
+    #   :client_connected or :reminders
+    def hold_for_request(requester:, streams: true)
+      return :turn_running if @engine.turn_running?
+      return :input_queued if @input_pending.call
+      return :continue_offered if @awaiting_continue.call
+      return :client_connected if streams && @bridge && @bridge.open_streams_except(requester).positive?
+      return :reminders if @engine.reminder_store&.any?
+
+      nil
+    end
+
+    # @return [Float] seconds since the latest activity of any kind
+    def idle_seconds
+      last = [@started_at, @engine.last_activity_at, @bridge&.last_client_activity_at].compact.max
+      @clock.call - last
+    end
+  end
+end

data/lib/samagotchi.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "samagotchi/config"
+require_relative "samagotchi/context_usage"
+require_relative "samagotchi/model_profile"
+require_relative "samagotchi/prompt"
+require_relative "samagotchi/client"
+require_relative "samagotchi/debug_log"
+require_relative "samagotchi/pending_input_queue"
+require_relative "samagotchi/kernel_loop"
+require_relative "samagotchi/session"
+require_relative "samagotchi/terminal_ui"

metadata

@@ -0,0 +1,374 @@
+--- !ruby/object:Gem::Specification
+name: samagotchi
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Dmitry Dedov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: reline
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.3
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.9'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rackup
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: chi is an agent harness for local and OpenAI-compatible models (llama.cpp,
+  mlx, oMLX, hosted APIs). It runs sessions in a terminal REPL or in background workers
+  you can attach to from the terminal and a web UI, keeps memories in plain files
+  shared as bundles, and extends through hooks, guardrails, plugins and MCP servers.
+email:
+- me@dmitry.it
+executables:
+- chi
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- bin/chi
+- docs/architecture.md
+- docs/cli.md
+- docs/configuration.md
+- docs/desktop.md
+- docs/guardrails.md
+- docs/hooks.md
+- docs/internals/background-tasks.md
+- docs/internals/context-telemetry.md
+- docs/internals/gemma4-contract.md
+- docs/internals/tool-guardrails.md
+- docs/memory.md
+- docs/plugins.md
+- docs/releasing.md
+- docs/sessions.md
+- lib/samagotchi.rb
+- lib/samagotchi/bridge.rb
+- lib/samagotchi/bridge/bounded_queue.rb
+- lib/samagotchi/bridge/card_store.rb
+- lib/samagotchi/bridge/event_id.rb
+- lib/samagotchi/bridge/ring_buffer.rb
+- lib/samagotchi/bridge/sse_writer.rb
+- lib/samagotchi/bridge/turn_accumulator.rb
+- lib/samagotchi/bridge_client.rb
+- lib/samagotchi/bridge_client/event_stream.rb
+- lib/samagotchi/bridge_client/sse_parser.rb
+- lib/samagotchi/bundle_needs.rb
+- lib/samagotchi/bundles/btw/manifest.yml
+- lib/samagotchi/bundles/btw/plugin.rb
+- lib/samagotchi/bundles/guardrails/guardrails.md
+- lib/samagotchi/bundles/guardrails/guardrails/rules.yml
+- lib/samagotchi/bundles/guardrails/manifest.yml
+- lib/samagotchi/bundles/known-names/hooks/known_names.rb
+- lib/samagotchi/bundles/known-names/known_names.md
+- lib/samagotchi/bundles/known-names/manifest.yml
+- lib/samagotchi/bundles/loop-guard/manifest.yml
+- lib/samagotchi/bundles/loop-guard/plugin.rb
+- lib/samagotchi/bundles/mcp/manifest.yml
+- lib/samagotchi/bundles/mcp/plugin.rb
+- lib/samagotchi/bundles/system/config_modification_protocol.md
+- lib/samagotchi/bundles/system/delegated.md
+- lib/samagotchi/bundles/system/identity.md
+- lib/samagotchi/bundles/system/manifest.yml
+- lib/samagotchi/bundles/system/memory_guide.md
+- lib/samagotchi/bundles/system/self_map.md
+- lib/samagotchi/cancellation_controller.rb
+- lib/samagotchi/client.rb
+- lib/samagotchi/commands/registry.rb
+- lib/samagotchi/config.rb
+- lib/samagotchi/context_note.rb
+- lib/samagotchi/context_quote.rb
+- lib/samagotchi/context_usage.rb
+- lib/samagotchi/context_window.rb
+- lib/samagotchi/debug_log.rb
+- lib/samagotchi/desktop.rb
+- lib/samagotchi/desktop/macos.rb
+- lib/samagotchi/desktop/macos/App.swift
+- lib/samagotchi/desktop/macos/ChiRunner.swift
+- lib/samagotchi/desktop/macos/Hotkey.swift
+- lib/samagotchi/desktop/macos/Info.plist.erb
+- lib/samagotchi/desktop/macos/Panel.swift
+- lib/samagotchi/desktop_command.rb
+- lib/samagotchi/engine.rb
+- lib/samagotchi/guardrails.rb
+- lib/samagotchi/guardrails/approval.rb
+- lib/samagotchi/guardrails/approvals.rb
+- lib/samagotchi/guardrails/context.rb
+- lib/samagotchi/guardrails/gate.rb
+- lib/samagotchi/guardrails/load_failures.rb
+- lib/samagotchi/guardrails/protected_paths.rb
+- lib/samagotchi/guardrails/rules.rb
+- lib/samagotchi/guardrails/targets.rb
+- lib/samagotchi/guardrails/verdict.rb
+- lib/samagotchi/hooks.rb
+- lib/samagotchi/hooks/bundle_loader.rb
+- lib/samagotchi/hooks/loader.rb
+- lib/samagotchi/hooks/registry.rb
+- lib/samagotchi/host_registry.rb
+- lib/samagotchi/idle_client.rb
+- lib/samagotchi/idle_recap.rb
+- lib/samagotchi/idle_reminders.rb
+- lib/samagotchi/idle_scheduler.rb
+- lib/samagotchi/image_store.rb
+- lib/samagotchi/installed_gem.rb
+- lib/samagotchi/kernel_loop.rb
+- lib/samagotchi/launch_mode.rb
+- lib/samagotchi/llm/backend.rb
+- lib/samagotchi/llm/chat_loop.rb
+- lib/samagotchi/llm/errors.rb
+- lib/samagotchi/llm/http.rb
+- lib/samagotchi/llm/model_result.rb
+- lib/samagotchi/llm/native_backend.rb
+- lib/samagotchi/llm/native_tool_normalizer.rb
+- lib/samagotchi/llm/openai_chat.rb
+- lib/samagotchi/llm/usage.rb
+- lib/samagotchi/log.rb
+- lib/samagotchi/log_line.rb
+- lib/samagotchi/log_path.rb
+- lib/samagotchi/log_subscriber.rb
+- lib/samagotchi/memory_bundle.rb
+- lib/samagotchi/memory_bundle/builder.rb
+- lib/samagotchi/memory_bundle/index_updater.rb
+- lib/samagotchi/memory_bundle/installer.rb
+- lib/samagotchi/memory_bundle/listing.rb
+- lib/samagotchi/memory_bundle/manifest.rb
+- lib/samagotchi/memory_bundle/merger.rb
+- lib/samagotchi/memory_bundle/placeholder.rb
+- lib/samagotchi/memory_bundle/provenance.rb
+- lib/samagotchi/memory_bundle/source.rb
+- lib/samagotchi/memory_bundle/status.rb
+- lib/samagotchi/memory_bundle/system_bundle.rb
+- lib/samagotchi/memory_bundle/uninstaller.rb
+- lib/samagotchi/memory_paths.rb
+- lib/samagotchi/model_overlay.rb
+- lib/samagotchi/model_profile.rb
+- lib/samagotchi/muted_memories.rb
+- lib/samagotchi/note_command.rb
+- lib/samagotchi/output_formatter.rb
+- lib/samagotchi/owner_lock.rb
+- lib/samagotchi/pending_input_queue.rb
+- lib/samagotchi/plugin/api.rb
+- lib/samagotchi/plugin/context.rb
+- lib/samagotchi/plugin/loader.rb
+- lib/samagotchi/plugin/service.rb
+- lib/samagotchi/plugin/sessions.rb
+- lib/samagotchi/plugin/side_question.rb
+- lib/samagotchi/plugin/tool_result.rb
+- lib/samagotchi/project_scope.rb
+- lib/samagotchi/prompt.rb
+- lib/samagotchi/prompt_literal_guard.rb
+- lib/samagotchi/recap_store.rb
+- lib/samagotchi/reminder_store.rb
+- lib/samagotchi/self_report.rb
+- lib/samagotchi/send_command.rb
+- lib/samagotchi/served_model.rb
+- lib/samagotchi/session.rb
+- lib/samagotchi/session_commands.rb
+- lib/samagotchi/session_delete_command.rb
+- lib/samagotchi/session_manager.rb
+- lib/samagotchi/session_metrics.rb
+- lib/samagotchi/session_observer.rb
+- lib/samagotchi/terminal_ui.rb
+- lib/samagotchi/terminal_ui/attach_launcher.rb
+- lib/samagotchi/terminal_ui/attached_loop.rb
+- lib/samagotchi/terminal_ui/attached_view.rb
+- lib/samagotchi/terminal_ui/event_renderer.rb
+- lib/samagotchi/terminal_ui/formatting.rb
+- lib/samagotchi/terminal_ui/image_input.rb
+- lib/samagotchi/terminal_ui/input_support.rb
+- lib/samagotchi/terminal_ui/legacy_surface.rb
+- lib/samagotchi/terminal_ui/line_reader.rb
+- lib/samagotchi/terminal_ui/live_region.rb
+- lib/samagotchi/terminal_ui/plain_surface.rb
+- lib/samagotchi/terminal_ui/question_prompt.rb
+- lib/samagotchi/terminal_ui/question_slot.rb
+- lib/samagotchi/terminal_ui/reline_seam.rb
+- lib/samagotchi/terminal_ui/repl_input.rb
+- lib/samagotchi/terminal_ui/screen.rb
+- lib/samagotchi/terminal_ui/surface.rb
+- lib/samagotchi/terminal_ui/thinking_line.rb
+- lib/samagotchi/thinking_ticker.rb
+- lib/samagotchi/thought_stream_splitter.rb
+- lib/samagotchi/token_usage.rb
+- lib/samagotchi/tool_activity.rb
+- lib/samagotchi/tool_call_parser.rb
+- lib/samagotchi/tool_declarations.rb
+- lib/samagotchi/tool_runner.rb
+- lib/samagotchi/tools/args.rb
+- lib/samagotchi/tools/ask_user_question.rb
+- lib/samagotchi/tools/builtins.rb
+- lib/samagotchi/tools/cancel_reminder.rb
+- lib/samagotchi/tools/delegate.rb
+- lib/samagotchi/tools/delegate_result.rb
+- lib/samagotchi/tools/delegate_wait.rb
+- lib/samagotchi/tools/edit.rb
+- lib/samagotchi/tools/execute.rb
+- lib/samagotchi/tools/list_reminders.rb
+- lib/samagotchi/tools/list_sessions.rb
+- lib/samagotchi/tools/memory.rb
+- lib/samagotchi/tools/output_guardrails.rb
+- lib/samagotchi/tools/peers.rb
+- lib/samagotchi/tools/read.rb
+- lib/samagotchi/tools/register_reminder.rb
+- lib/samagotchi/tools/registry.rb
+- lib/samagotchi/tools/send_note.rb
+- lib/samagotchi/tools/task_create.rb
+- lib/samagotchi/tools/task_get.rb
+- lib/samagotchi/tools/task_list.rb
+- lib/samagotchi/tools/task_runtime.rb
+- lib/samagotchi/tools/task_stop.rb
+- lib/samagotchi/tools/task_wait.rb
+- lib/samagotchi/tools/tool_path.rb
+- lib/samagotchi/tools/web_fetch.rb
+- lib/samagotchi/tools/write.rb
+- lib/samagotchi/turn_flow.rb
+- lib/samagotchi/turn_note.rb
+- lib/samagotchi/turn_tally.rb
+- lib/samagotchi/version.rb
+- lib/samagotchi/vision_context.rb
+- lib/samagotchi/vision_support.rb
+- lib/samagotchi/web/app.rb
+- lib/samagotchi/web/markdown_renderer.rb
+- lib/samagotchi/web/message_parts.rb
+- lib/samagotchi/web/public/activity.js
+- lib/samagotchi/web/public/annotations.js
+- lib/samagotchi/web/public/app.js
+- lib/samagotchi/web/public/card.js
+- lib/samagotchi/web/public/chat_view.js
+- lib/samagotchi/web/public/chunk_router.js
+- lib/samagotchi/web/public/command_complete.js
+- lib/samagotchi/web/public/composer_size.js
+- lib/samagotchi/web/public/copy.js
+- lib/samagotchi/web/public/ctx.js
+- lib/samagotchi/web/public/data.js
+- lib/samagotchi/web/public/format.js
+- lib/samagotchi/web/public/hold.js
+- lib/samagotchi/web/public/images.js
+- lib/samagotchi/web/public/index.html
+- lib/samagotchi/web/public/init_row.js
+- lib/samagotchi/web/public/model_pick.js
+- lib/samagotchi/web/public/question_card.js
+- lib/samagotchi/web/public/route.js
+- lib/samagotchi/web/public/scope.js
+- lib/samagotchi/web/public/scroll.js
+- lib/samagotchi/web/public/sentences.js
+- lib/samagotchi/web/public/sessions_list.js
+- lib/samagotchi/web/public/strip.js
+- lib/samagotchi/web/public/tally.js
+- lib/samagotchi/web/public/thinking_ticker.js
+- lib/samagotchi/web/public/timing.js
+- lib/samagotchi/web/public/turn_events.js
+- lib/samagotchi/web/public/turn_model.js
+- lib/samagotchi/web/public/turn_view.js
+- lib/samagotchi/web/server.rb
+- lib/samagotchi/web/session_hub.rb
+- lib/samagotchi/web/session_summary.rb
+- lib/samagotchi/worker.rb
+- lib/samagotchi/worker_idle_exit.rb
+homepage: https://github.com/dm1try/samagotchi
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/dm1try/samagotchi
+  changelog_uri: https://github.com/dm1try/samagotchi/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/dm1try/samagotchi/issues
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'chi: a local-first coding agent with memory, sessions and a web UI'
+test_files: []