elelem-daemon 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 8f832021dd675364898d1326a2131038463a4ace53d2c9363c5e89a2430e942b
4
+ data.tar.gz: 93314a381146fcc0cf1cf72eb10e7e1e5b5e9849fcd877f34c556055ea945d0f
5
+ SHA512:
6
+ metadata.gz: 35b031b8cf60826fb4dfdc3fa487d8bc10ecc7e5e1819c20828cd5e3c5331ae29235d0f22cceb217da9d6f1c42e571e71a0ed1327ca032110887cac039c12236
7
+ data.tar.gz: f8e4970c986ffecafb24679e9d05280df31d19dbe226c877a6132954e0e599ffcbd9071cb0c2e8da1a546a866f7f6bfaae84e1b9b63ee7c1304e4c85d43491fc
@@ -0,0 +1,19 @@
1
+ As a `developer`, I `want a session that outlives its connection`, so
2
+ that `I can detach from a long task and reattach later, as with screen`.
3
+
4
+ # SYNOPSIS
5
+
6
+ `{"session":"deploy"}` attaches to a long-lived worker by name.
7
+
8
+ # DESCRIPTION
9
+
10
+ Today a connection is a session: closing it ends the worker. A named
11
+ session is a worker with its own socket, `sessions/NAME.sock`, next to
12
+ `elelemd.sock`, which is how screen does it.
13
+
14
+ - Every attached client gets each event. A prompt stays open until some
15
+ client answers it.
16
+ - The worker exits after an idle timeout with no client attached.
17
+ - `elelemd attach NAME` and `elelemd ls`.
18
+ - A sidecar `sessions/NAME.json` records the folder, the provider and
19
+ whether a turn is running, so `ls` needs no connection.
@@ -0,0 +1,23 @@
1
+ As an `agent working in one repo`, I `want to ask an agent in another
2
+ repo`, so that `agents can share what they know about their own code`.
3
+
4
+ # SYNOPSIS
5
+
6
+ A one-file plugin adds the tools `agents` and `ask_agent(name, prompt)`.
7
+
8
+ # DESCRIPTION
9
+
10
+ Depends on 001. The sessions directory is the registry: `agents` lists
11
+ the sidecar files, and `ask_agent` connects to that session's socket
12
+ and returns its `done` reply. Asking with `cwd` instead of a name
13
+ starts a fresh agent in that folder through `elelemd.sock`, which works
14
+ today.
15
+
16
+ - Approvals: the peer's `prompt` events go to the person at the top of
17
+ the chain. The asking agent never answers them itself.
18
+ - Loops: each request carries `from` and `via`. The daemon refuses a
19
+ request whose `via` already names the target, or holds more than 3
20
+ hops.
21
+ - Trust: the peer's reply reaches the model as data, framed as "reply
22
+ from agent NAME in PATH", not as instructions.
23
+ - Cost: cap the turns per request.
@@ -0,0 +1,63 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ workflow_dispatch:
7
+
8
+ permissions: {}
9
+
10
+ concurrency:
11
+ group: release
12
+ cancel-in-progress: false
13
+
14
+ jobs:
15
+ test:
16
+ runs-on: ubuntu-latest
17
+ permissions:
18
+ contents: read
19
+ steps:
20
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
21
+ with:
22
+ persist-credentials: false
23
+ - uses: ruby/setup-ruby@3ff19f5e2baf30647122352b96108b1fbe250c64 # v1.299.0
24
+ with:
25
+ ruby-version: "4.0"
26
+ bundler-cache: true
27
+ - run: bin/test
28
+ - run: bin/lint
29
+
30
+ release-please:
31
+ needs: test
32
+ runs-on: ubuntu-latest
33
+ permissions:
34
+ contents: write
35
+ issues: write
36
+ pull-requests: write
37
+ outputs:
38
+ release_created: ${{ steps.release.outputs.release_created }}
39
+ steps:
40
+ - id: release
41
+ uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
42
+ with:
43
+ config-file: release-please-config.json
44
+ manifest-file: .release-please-manifest.json
45
+
46
+ publish:
47
+ needs: release-please
48
+ if: needs.release-please.outputs.release_created == 'true'
49
+ runs-on: ubuntu-latest
50
+ permissions:
51
+ contents: write
52
+ id-token: write
53
+ steps:
54
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
55
+ with:
56
+ persist-credentials: false
57
+ - uses: ruby/setup-ruby@3ff19f5e2baf30647122352b96108b1fbe250c64 # v1.299.0
58
+ with:
59
+ ruby-version: "4.0"
60
+ bundler-cache: true
61
+ - uses: rubygems/release-gem@7f9650160c1a4e7989fdc9855807bdbd421d8b6b # v1.4.1
62
+ with:
63
+ await-release: false
@@ -0,0 +1,3 @@
1
+ {
2
+ ".": "0.1.0"
3
+ }
data/.rspec ADDED
@@ -0,0 +1 @@
1
+ --require spec_helper
data/.rubocop.yml ADDED
@@ -0,0 +1,62 @@
1
+ AllCops:
2
+ NewCops: enable
3
+ TargetRubyVersion: 4.0
4
+ SuggestExtensions: false
5
+ Exclude:
6
+ - "pkg/**/*"
7
+ - "bin/**/*"
8
+ - "vendor/**/*"
9
+ - "fixtures/**/*"
10
+
11
+ Metrics:
12
+ Enabled: false
13
+
14
+ Naming/PredicateMethod:
15
+ AllowedMethods:
16
+ - call
17
+ - run
18
+ - summarize
19
+ - prompt
20
+
21
+ Naming/MethodParameterName:
22
+ AllowedNames:
23
+ - me
24
+ - id
25
+ - as
26
+ - io
27
+
28
+ Style/GlobalVars:
29
+ Exclude:
30
+ - "spec/**/*"
31
+
32
+ Lint/EmptyBlock:
33
+ Exclude:
34
+ - "spec/**/*"
35
+
36
+ Lint/UselessDefaultValueArgument:
37
+ Enabled: false
38
+
39
+ Lint/RedundantRequireStatement:
40
+ Enabled: false
41
+
42
+ Lint/UnusedBlockArgument:
43
+ IgnoreEmptyBlocks: true
44
+ AllowUnusedKeywordArguments: true
45
+
46
+ Style/Documentation:
47
+ Enabled: false
48
+
49
+ Style/FormatStringToken:
50
+ Enabled: false
51
+
52
+ Style/FrozenStringLiteralComment:
53
+ Enabled: true
54
+
55
+ Style/StringLiterals:
56
+ EnforcedStyle: double_quotes
57
+
58
+ Style/StringLiteralsInInterpolation:
59
+ EnforcedStyle: double_quotes
60
+
61
+ Layout/LineLength:
62
+ Max: 120
data/CHANGELOG.md ADDED
@@ -0,0 +1,10 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 (2026-11-21)
4
+
5
+
6
+ ### Features
7
+
8
+ * serve elelem sessions over a unix socket, one worker per connection ([1493fdd](https://github.com/elelem-sh/daemon/commit/1493fdddf94c44e7eb9a47d8c93571360debf027))
9
+
10
+ ## Changelog
data/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2026 mo khan
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,106 @@
1
+ # elelem-daemon
2
+
3
+ An always-on [elelem](https://elelem.sh) that you talk to over a Unix socket.
4
+
5
+ `elelemd` runs once per user. Each connection gets its own worker process. The
6
+ worker moves into the folder the client names, so that folder's plugins,
7
+ permissions and `AGENTS.md` apply. A crash in one folder doesn't affect another.
8
+
9
+ ```sh
10
+ gem install elelem-daemon
11
+ elelemd serve -p ollama # in a terminal, or as a service (below)
12
+
13
+ elelemd ask "why does the build fail?" # a prompt for this folder
14
+ elelemd chat # a conversation from this folder
15
+ ```
16
+
17
+ The socket is `$XDG_RUNTIME_DIR/elelem/elelemd.sock`, or
18
+ `~/.local/state/elelem/elelemd.sock` when that variable isn't set. Set
19
+ `ELELEM_SOCKET` or pass `--socket` to use another path. Only your user can
20
+ connect.
21
+
22
+ ## Protocol
23
+
24
+ Each line is one JSON object, in both directions. The daemon speaks first.
25
+
26
+ ```
27
+ < {"type":"hello","protocol":1}
28
+ > {"cwd":"/src/app","prompt":"run the specs","interactive":false}
29
+ < {"type":"tool","name":"execute","args":{"command":"bin/test"},"state":"+"}
30
+ < {"type":"content","text":"..."}
31
+ < {"type":"done","reply":"...","interrupted":false}
32
+ ```
33
+
34
+ The first request must include `cwd`, an absolute folder. It may also include:
35
+ - `provider` and `model`;
36
+ - `env`, which the worker adds to its environment;
37
+ - `interactive`, which says whether a person will answer prompts.
38
+
39
+ After the first request you can send any of these:
40
+ - `{"prompt":"..."}` starts another turn in the same conversation. Prompts sent
41
+ while a turn is running wait their turn.
42
+ - `{"id":1,"answer":"y"}` answers a `prompt` event. `null` refuses.
43
+ - `{"interrupt":true}` stops the running turn and the command it is running.
44
+
45
+ Instead of a request, `{"status":true}` gets the daemon's pid, worker count and
46
+ version.
47
+
48
+ The daemon sends `content`, `thinking`, `tool`, `prompt` and `error` events,
49
+ and exactly one `done` for each prompt. Closing your sending side means you are
50
+ done sending: the queued turns still finish and reply. Closing the connection
51
+ stops the worker.
52
+
53
+ The simplest client is `nc` (OpenBSD `nc` needs `-N` to close its side when its
54
+ input ends):
55
+
56
+ ```sh
57
+ printf '%s\n' "{\"cwd\":\"$PWD\",\"prompt\":\"hi\"}" | nc -N -U "$XDG_RUNTIME_DIR/elelem/elelemd.sock"
58
+ ```
59
+
60
+ ## Approvals
61
+
62
+ A tool that needs approval (`"ask"` in `permissions.json`) asks the client with
63
+ a `prompt` event. If the client isn't interactive, such as a script or
64
+ `elelemd ask` without a terminal, the daemon denies the tool. It never approves
65
+ on its own.
66
+
67
+ ## As a service
68
+
69
+ systemd, as `~/.config/systemd/user/elelemd.service`:
70
+
71
+ ```ini
72
+ [Unit]
73
+ Description=elelem daemon
74
+
75
+ [Service]
76
+ ExecStart=%h/.local/share/gem/ruby/4.0.0/bin/elelemd serve -p anthropic
77
+ EnvironmentFile=-%h/.config/elelem/env
78
+ Restart=on-failure
79
+
80
+ [Install]
81
+ WantedBy=default.target
82
+ ```
83
+
84
+ Then run `systemctl --user enable --now elelemd`.
85
+
86
+ launchd, as `~/Library/LaunchAgents/sh.elelem.elelemd.plist`:
87
+
88
+ ```xml
89
+ <plist version="1.0"><dict>
90
+ <key>Label</key><string>sh.elelem.elelemd</string>
91
+ <key>ProgramArguments</key><array><string>/usr/local/bin/elelemd</string><string>serve</string></array>
92
+ <key>RunAtLoad</key><true/>
93
+ <key>KeepAlive</key><true/>
94
+ </dict></plist>
95
+ ```
96
+
97
+ Then run `launchctl load ~/Library/LaunchAgents/sh.elelem.elelemd.plist`.
98
+
99
+ `elelemd ask` and `elelemd chat` send your shell's environment with each
100
+ request, so commands run with your `PATH` and keys, not only the service's.
101
+
102
+ ## Limits
103
+
104
+ - Each connection starts its own MCP servers, so a single `ask` is about as
105
+ fast as `elelem ask`. Long conversations are where the daemon pays off.
106
+ - Not available on Windows, which has no `fork`.
data/Rakefile ADDED
@@ -0,0 +1,8 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "bundler/gem_tasks"
4
+ require "rspec/core/rake_task"
5
+
6
+ RSpec::Core::RakeTask.new(:spec)
7
+
8
+ task default: %i[spec]
data/exe/elelemd ADDED
@@ -0,0 +1,54 @@
1
+ #!/usr/bin/env ruby
2
+ # frozen_string_literal: true
3
+
4
+ require "elelem/daemon"
5
+ require "optparse"
6
+
7
+ options = {}
8
+ max_workers = Elelem::Daemon::MAX_WORKERS
9
+ socket = Elelem::Daemon.socket_path
10
+
11
+ parser = OptionParser.new do |o|
12
+ o.banner = <<~TEXT
13
+ Usage: elelemd [command] [options]
14
+
15
+ Commands:
16
+ serve Run the daemon (default)
17
+ ask <prompt> Send one prompt for this folder; reads stdin if piped
18
+ chat Talk to the daemon from this folder
19
+
20
+ Options:
21
+ TEXT
22
+ o.on("-s", "--socket PATH", "Socket (default: #{socket})") { |v| socket = v }
23
+ o.on("-p", "--provider NAME", "Provider to use") { |v| options[:provider] = v }
24
+ o.on("--model NAME", "Model to use, passed to the provider") { |v| options[:model] = v }
25
+ o.on("--max-workers N", Integer, "Connections served at once (default: #{max_workers})") { |v| max_workers = v }
26
+ o.on("-h", "--help", "Show this help") do
27
+ puts o
28
+ exit
29
+ end
30
+ end
31
+ args = parser.parse!(ARGV)
32
+
33
+ begin
34
+ case args.shift || "serve"
35
+ when "serve"
36
+ provider = options.fetch(:provider) { ENV.fetch("ELELEM_PROVIDER", "demo") }
37
+ Elelem::Daemon.new(path: socket, provider: provider, max_workers: max_workers).start
38
+ when "ask"
39
+ abort "Usage: elelemd ask <prompt>" if args.empty?
40
+ prompt = args.join(" ")
41
+ prompt = "#{prompt}\n\n```\n#{$stdin.read}\n```" if $stdin.stat.pipe? || $stdin.stat.file?
42
+ piped = !$stdout.tty?
43
+ output = piped ? Elelem::Output.new(stream: $stderr) : Elelem::Terminal.new
44
+ input = $stdin.tty? ? Elelem::Input.new : Elelem::NullInput.new
45
+ reply = Elelem::Daemon::Client.new(path: socket, input: input, output: output).ask(prompt, **options)
46
+ puts reply if piped
47
+ when "chat"
48
+ Elelem::Daemon::Client.new(path: socket).chat(**options)
49
+ else
50
+ abort parser.help
51
+ end
52
+ rescue RuntimeError => e
53
+ abort "elelemd: #{e.message}"
54
+ end
@@ -0,0 +1,76 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Elelem
4
+ class Daemon
5
+ # Talks to elelemd: sends prompts for the current folder, draws the
6
+ # events, and answers approval prompts when a person is there to.
7
+ class Client
8
+ def initialize(path: Daemon.socket_path, input: Input.new, output: Terminal.new)
9
+ @path = path
10
+ @input = input
11
+ @output = output
12
+ end
13
+
14
+ # One prompt; returns the reply.
15
+ def ask(prompt, **)
16
+ connect(prompt: prompt, **)
17
+ wait
18
+ ensure
19
+ @socket&.close
20
+ end
21
+
22
+ # A conversation: one prompt per line until end of input.
23
+ def chat(**)
24
+ connect(**)
25
+ while (line = @input.ask("> "))
26
+ next if line.empty?
27
+
28
+ @input.remember(line)
29
+ @connection.write(prompt: line)
30
+ wait
31
+ end
32
+ ensure
33
+ @socket&.close
34
+ end
35
+
36
+ private
37
+
38
+ def connect(**)
39
+ @socket = UNIXSocket.new(@path)
40
+ @connection = Connection.new(@socket, on_hang_up: -> { raise "elelemd closed the connection" })
41
+ protocol = @connection.read&.dig("protocol")
42
+ raise "elelemd speaks protocol #{protocol.inspect}, not #{PROTOCOL}" unless protocol == PROTOCOL
43
+
44
+ @connection.write(request(**))
45
+ rescue Errno::ENOENT, Errno::ECONNREFUSED
46
+ raise "elelemd is not running (no socket at #{@path})"
47
+ end
48
+
49
+ def request(provider: nil, model: nil, **rest)
50
+ { cwd: Dir.pwd, env: ENV.to_h, interactive: @input.interactive?, provider:, model:, **rest }.compact
51
+ end
52
+
53
+ # Draws events until the turn is done. Ctrl-C asks elelemd to stop it.
54
+ def wait
55
+ loop do
56
+ event = @connection.read or raise(@error || "elelemd closed the connection")
57
+ return event["reply"] if event["type"] == "done"
58
+
59
+ draw(event)
60
+ rescue Interrupt
61
+ @connection.write(interrupt: true)
62
+ end
63
+ end
64
+
65
+ def draw(event)
66
+ case event["type"]
67
+ when "content" then @output.say(event["text"], as: event["as"]&.to_sym)
68
+ when "thinking" then @output.thinking(event["text"])
69
+ when "tool" then @output.doing(event["name"], event["args"], state: event["state"] || "+")
70
+ when "prompt" then @connection.write(id: event["id"], answer: @input.ask(event["text"]))
71
+ when "error" then @output.say(@error = event["text"], as: :error)
72
+ end
73
+ end
74
+ end
75
+ end
76
+ end
@@ -0,0 +1,34 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Elelem
4
+ class Daemon
5
+ # One JSON object per line, in both directions.
6
+ class Connection
7
+ LINE_LIMIT = 1 << 20
8
+ HUNG_UP = [IOError, Errno::EPIPE, Errno::ECONNRESET].freeze
9
+
10
+ def initialize(socket, on_hang_up: -> {})
11
+ @socket = socket
12
+ @on_hang_up = on_hang_up
13
+ @lock = Mutex.new
14
+ end
15
+
16
+ # The next object, or nil at the end. A line that is not a JSON object,
17
+ # or is too long, raises.
18
+ def read
19
+ line = @socket.gets("\n", LINE_LIMIT) or return
20
+ raise ArgumentError, "a line is longer than #{LINE_LIMIT} bytes" if line.bytesize >= LINE_LIMIT
21
+
22
+ JSON.parse(line).tap { |message| raise ArgumentError, "expected a JSON object" unless message.is_a?(Hash) }
23
+ rescue JSON::ParserError
24
+ raise ArgumentError, "expected a JSON object"
25
+ end
26
+
27
+ def write(event)
28
+ @lock.synchronize { @socket.write("#{JSON.generate(event)}\n") }
29
+ rescue *HUNG_UP
30
+ @on_hang_up.call
31
+ end
32
+ end
33
+ end
34
+ end
@@ -0,0 +1,72 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Elelem
4
+ class Daemon
5
+ # A session's input and output, sent over the connection as events.
6
+ #
7
+ # It always reports itself interactive, so a tool that needs approval
8
+ # asks instead of being approved unseen. A client that cannot answer,
9
+ # such as a script, gets no prompt: the request is denied.
10
+ class Terminal
11
+ ANSI = /\e\[[0-9;]*[a-zA-Z]/
12
+
13
+ def initialize(connection, interactive:)
14
+ @connection = connection
15
+ @interactive = interactive
16
+ @prompts = {}
17
+ @next_id = 0
18
+ @lock = Mutex.new
19
+ end
20
+
21
+ def interactive? = true
22
+
23
+ def ask(prompt, **)
24
+ return unless @interactive
25
+
26
+ queue = Queue.new
27
+ id = @lock.synchronize { (@next_id += 1).tap { @prompts[it] = queue } }
28
+ @connection.write(type: "prompt", id: id, text: plain(prompt))
29
+ queue.pop
30
+ ensure
31
+ @lock.synchronize { @prompts.delete(id) } if id
32
+ end
33
+
34
+ def answer(id, text)
35
+ @lock.synchronize { @prompts[id] }&.push(text)
36
+ end
37
+
38
+ def say(text, as: nil)
39
+ emit("content", text, as: as&.to_s)
40
+ end
41
+
42
+ def print(text)
43
+ emit("content", text)
44
+ end
45
+
46
+ def thinking(text)
47
+ emit("thinking", text)
48
+ end
49
+
50
+ def doing(name, args, state: "+")
51
+ @connection.write(type: "tool", name: name.to_s, args: args, state: state)
52
+ end
53
+
54
+ def waiting; end
55
+
56
+ def display_file(path, fallback: nil)
57
+ say(fallback || path)
58
+ end
59
+
60
+ private
61
+
62
+ def emit(type, text, **extra)
63
+ text = plain(text)
64
+ @connection.write({ type: type, text: text, **extra.compact }) unless text.strip.empty?
65
+ end
66
+
67
+ def plain(text)
68
+ text.to_s.gsub(ANSI, "")
69
+ end
70
+ end
71
+ end
72
+ end
@@ -0,0 +1,7 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Elelem
4
+ class Daemon
5
+ VERSION = "0.1.0"
6
+ end
7
+ end