kward 0.85.0 → 0.86.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.
Files changed (151) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +130 -0
  3. data/CONTRIBUTING.md +1 -1
  4. data/Gemfile.lock +6 -2
  5. data/README.md +3 -3
  6. data/Rakefile +3 -0
  7. data/doc/agent-tools.md +11 -0
  8. data/doc/api.md +4 -1
  9. data/doc/composer.md +4 -3
  10. data/doc/configuration.md +60 -11
  11. data/doc/extensibility.md +2 -0
  12. data/doc/getting-started.md +3 -3
  13. data/doc/git.md +1 -1
  14. data/doc/memory.md +1 -1
  15. data/doc/plugins.md +40 -5
  16. data/doc/providers.md +10 -4
  17. data/doc/rpc.md +125 -7
  18. data/doc/session-management.md +36 -1
  19. data/doc/shell.md +643 -27
  20. data/doc/tabs.md +2 -1
  21. data/doc/troubleshooting.md +1 -1
  22. data/doc/usage.md +21 -11
  23. data/examples/plugins/openrouter_proxy/README.md +103 -0
  24. data/examples/plugins/openrouter_proxy/fake_embeddings.rb +85 -0
  25. data/examples/plugins/openrouter_proxy/plugin.rb +7 -0
  26. data/examples/plugins/openrouter_proxy/protocol.rb +202 -0
  27. data/examples/plugins/openrouter_proxy/server.rb +186 -0
  28. data/examples/plugins/space_invaders.rb +0 -1
  29. data/exe/kward +2 -2
  30. data/exe/kwsh +7 -0
  31. data/kward.gemspec +3 -1
  32. data/lib/kward/agent.rb +43 -9
  33. data/lib/kward/cli/commands.rb +41 -11
  34. data/lib/kward/cli/interactive_turn.rb +10 -0
  35. data/lib/kward/cli/plugins.rb +5 -1
  36. data/lib/kward/cli/prompt_interface.rb +4 -1
  37. data/lib/kward/cli/rendering.rb +21 -28
  38. data/lib/kward/cli/runtime_helpers.rb +52 -34
  39. data/lib/kward/cli/settings/model.rb +1 -12
  40. data/lib/kward/cli/tabs.rb +91 -18
  41. data/lib/kward/cli/tool_summaries.rb +2 -0
  42. data/lib/kward/cli/transcript_formatter.rb +3 -10
  43. data/lib/kward/cli/worktrees.rb +1 -0
  44. data/lib/kward/cli.rb +56 -7
  45. data/lib/kward/config/core.rb +16 -5
  46. data/lib/kward/config/extensions.rb +3 -0
  47. data/lib/kward/config/paths.rb +11 -0
  48. data/lib/kward/config/settings.rb +7 -0
  49. data/lib/kward/conversation.rb +11 -1
  50. data/lib/kward/entrypoint.rb +14 -0
  51. data/lib/kward/events.rb +2 -0
  52. data/lib/kward/generated_images.rb +237 -0
  53. data/lib/kward/model/catalog.rb +6 -3
  54. data/lib/kward/model/client.rb +105 -36
  55. data/lib/kward/model/codex_images.rb +83 -0
  56. data/lib/kward/model/copilot_models.rb +8 -4
  57. data/lib/kward/model/model_info.rb +27 -9
  58. data/lib/kward/model/openrouter_model_cache.rb +4 -2
  59. data/lib/kward/model/payloads.rb +6 -5
  60. data/lib/kward/model/sources.rb +3 -1
  61. data/lib/kward/model/stream_parser.rb +4 -7
  62. data/lib/kward/pan/index.html.erb +8 -1
  63. data/lib/kward/pan/server.rb +13 -1
  64. data/lib/kward/plugins/codex_responses.rb +73 -0
  65. data/lib/kward/plugins/host.rb +16 -0
  66. data/lib/kward/plugins/http_server.rb +83 -0
  67. data/lib/kward/plugins/registry.rb +39 -0
  68. data/lib/kward/prompt_interface/composer_controller.rb +0 -1
  69. data/lib/kward/prompt_interface/composer_renderer.rb +159 -72
  70. data/lib/kward/prompt_interface/editor/controller.rb +1 -1
  71. data/lib/kward/prompt_interface/editor/renderer.rb +10 -7
  72. data/lib/kward/prompt_interface/file_overlay.rb +3 -3
  73. data/lib/kward/prompt_interface/generated_image_preview.rb +162 -0
  74. data/lib/kward/prompt_interface/git_prompt.rb +18 -11
  75. data/lib/kward/prompt_interface/interactive/renderer.rb +1 -1
  76. data/lib/kward/prompt_interface/interactive/state.rb +18 -20
  77. data/lib/kward/prompt_interface/key_handler.rb +108 -25
  78. data/lib/kward/prompt_interface/layout.rb +11 -1
  79. data/lib/kward/prompt_interface/overlay_renderer.rb +25 -8
  80. data/lib/kward/prompt_interface/project_browser.rb +27 -54
  81. data/lib/kward/prompt_interface/prompt_renderer.rb +27 -35
  82. data/lib/kward/prompt_interface/question_prompt.rb +19 -28
  83. data/lib/kward/prompt_interface/runtime_state.rb +31 -9
  84. data/lib/kward/prompt_interface/screen.rb +24 -21
  85. data/lib/kward/prompt_interface/selection_prompt.rb +8 -8
  86. data/lib/kward/prompt_interface/slash_overlay.rb +1 -1
  87. data/lib/kward/prompt_interface/transcript_renderer.rb +7 -6
  88. data/lib/kward/prompt_interface.rb +109 -39
  89. data/lib/kward/prompts.rb +7 -1
  90. data/lib/kward/pty/adaptive_output_sink.rb +38 -4
  91. data/lib/kward/pty/interactive_runner.rb +20 -28
  92. data/lib/kward/pty/transcript_normalizer.rb +65 -21
  93. data/lib/kward/rpc/config_manager.rb +3 -0
  94. data/lib/kward/rpc/server.rb +27 -5
  95. data/lib/kward/rpc/session_manager.rb +62 -17
  96. data/lib/kward/rpc/transcript_normalizer.rb +11 -7
  97. data/lib/kward/sessions/store.rb +30 -3
  98. data/lib/kward/shell/kwsh.rb +27 -7
  99. data/lib/kward/shell/kwshrc.rb +11 -2
  100. data/lib/kward/shell/native_arithmetic.rb +255 -0
  101. data/lib/kward/shell/native_arrays.rb +102 -0
  102. data/lib/kward/shell/native_braces.rb +96 -0
  103. data/lib/kward/shell/native_builtins.rb +476 -0
  104. data/lib/kward/shell/native_completion.rb +169 -0
  105. data/lib/kward/shell/native_condition.rb +75 -0
  106. data/lib/kward/shell/native_directory.rb +116 -0
  107. data/lib/kward/shell/native_exec_state.rb +73 -0
  108. data/lib/kward/shell/native_expansion.rb +252 -0
  109. data/lib/kward/shell/native_fields.rb +62 -0
  110. data/lib/kward/shell/native_glob.rb +96 -0
  111. data/lib/kward/shell/native_history.rb +242 -0
  112. data/lib/kward/shell/native_interactive.rb +164 -0
  113. data/lib/kward/shell/native_invocation.rb +42 -0
  114. data/lib/kward/shell/native_jobs.rb +250 -0
  115. data/lib/kward/shell/native_line_editor.rb +382 -0
  116. data/lib/kward/shell/native_line_terminal.rb +286 -0
  117. data/lib/kward/shell/native_locale.rb +109 -0
  118. data/lib/kward/shell/native_locals.rb +57 -0
  119. data/lib/kward/shell/native_pattern.rb +200 -0
  120. data/lib/kward/shell/native_process.rb +279 -0
  121. data/lib/kward/shell/native_program.rb +40 -0
  122. data/lib/kward/shell/native_programmable_completion.rb +115 -0
  123. data/lib/kward/shell/native_prompt_format.rb +89 -0
  124. data/lib/kward/shell/native_runtime.rb +964 -0
  125. data/lib/kward/shell/native_substitution.rb +110 -0
  126. data/lib/kward/shell/native_syntax.rb +946 -0
  127. data/lib/kward/shell/native_traps.rb +196 -0
  128. data/lib/kward/shell/native_vi.rb +407 -0
  129. data/lib/kward/shell/native_vi_terminal.rb +19 -0
  130. data/lib/kward/shell/native_worker.rb +82 -0
  131. data/lib/kward/shell/persistent_session.rb +184 -190
  132. data/lib/kward/shell/prompt.rb +14 -0
  133. data/lib/kward/shell/prompt_agent.rb +17 -0
  134. data/lib/kward/shell/script_runner.rb +244 -0
  135. data/lib/kward/shell/standalone_agent.rb +31 -0
  136. data/lib/kward/shell/standalone_link.rb +78 -0
  137. data/lib/kward/shell/standalone_terminal.rb +287 -0
  138. data/lib/kward/terminal/keys.rb +22 -1
  139. data/lib/kward/terminal/locale_text.rb +29 -0
  140. data/lib/kward/terminal/sequences.rb +45 -4
  141. data/lib/kward/tools/datetime.rb +85 -0
  142. data/lib/kward/tools/generate_image.rb +36 -0
  143. data/lib/kward/tools/registry.rb +35 -9
  144. data/lib/kward/tools/tool_call.rb +3 -1
  145. data/lib/kward/transcripts/markdown_transcript.rb +8 -0
  146. data/lib/kward/transcripts/turn_summary_formatter.rb +93 -0
  147. data/lib/kward/transport/gateway.rb +2 -1
  148. data/lib/kward/turn_summary.rb +68 -0
  149. data/lib/kward/version.rb +1 -1
  150. data/lib/main.rb +6 -3
  151. metadata +84 -1
data/doc/tabs.md CHANGED
@@ -126,7 +126,8 @@ When `composer.tab_keybindings` is `ctrl`:
126
126
 
127
127
  | Key | Action |
128
128
  | --- | ------ |
129
- | `Ctrl+T` | New tab |
129
+ | `Ctrl+T` | Open a new tab at the end of the tab list |
130
+ | `Ctrl+Shift+T` | Open and focus a new tab immediately to the right of the current tab, if your terminal reports the shortcut |
130
131
  | `Ctrl+W` | Close tab |
131
132
  | `Ctrl+1` through `Ctrl+9` | Switch to a numbered tab, if your terminal reports modified number keys |
132
133
 
@@ -23,7 +23,7 @@ Use `kward auth status --all` when you also want to see every unconfigured provi
23
23
  Kward keeps normal command failures concise. To include a Ruby backtrace while diagnosing an unexpected failure, rerun the command with debug errors enabled:
24
24
 
25
25
  ```bash
26
- KWARD_DEBUG=1 kward "Repeat the failing task"
26
+ KWARD_DEBUG=1 kward prompt "Repeat the failing task"
27
27
  ```
28
28
 
29
29
  Backtraces can include local paths and implementation details. Review them before sharing them publicly.
data/doc/usage.md CHANGED
@@ -33,7 +33,7 @@ Summarize the test strategy.
33
33
  ### Review changes before committing
34
34
 
35
35
  ```bash
36
- git diff | kward "Review this diff for bugs, missing tests, and confusing naming"
36
+ git diff | kward prompt "Review this diff for bugs, missing tests, and confusing naming"
37
37
  ```
38
38
 
39
39
  For larger reviews, use interactive mode so Kward can inspect related files:
@@ -86,7 +86,7 @@ Useful shell commands:
86
86
 
87
87
  ```bash
88
88
  kward # start interactive chat
89
- kward "Explain this project" # ask one question and exit
89
+ kward prompt "Explain this project" # ask one question and exit
90
90
  kward help # show commands and examples
91
91
  kward version # show the installed version
92
92
  kward doctor # check local setup
@@ -101,7 +101,7 @@ Use another workspace without changing directories:
101
101
 
102
102
  ```bash
103
103
  kward --working-directory ~/code/project
104
- kward --working-directory ~/code/project "Summarize this repository"
104
+ kward --working-directory ~/code/project prompt "Summarize this repository"
105
105
  ```
106
106
 
107
107
  If your main config file is broken and prevents startup, use `--skip-config` to ignore it for one run:
@@ -215,24 +215,26 @@ For the full guide to context management, cloning, forking, rewinding, `/tree`,
215
215
  One-shot prompts are best for short tasks that do not need session history:
216
216
 
217
217
  ```bash
218
- kward "What does this repository do?"
219
- cat error.log | kward
218
+ kward prompt "What does this repository do?"
219
+ cat error.log | kward prompt "Explain the errors in this log"
220
220
  ```
221
221
 
222
- When stdin and a prompt are both present, Kward runs in filter mode: stdin is the input, the prompt is the instruction, and stdout contains only the transformed result. You can also force this with `--filter` or `--mode filter`.
222
+ When stdin and a prompt are both present, Kward runs in filter mode: stdin is the input, the prompt is the instruction, and stdout contains only the transformed result. Use the explicit `filter` command to make that intent clear; unknown commands are never treated as prompts.
223
223
 
224
224
  ```bash
225
- git diff | kward "Review this diff"
226
- echo "Hello" | kward --filter "Translate to German"
227
- kward --mode filter "Indent this JSON" < unindented.json
225
+ git diff | kward prompt "Review this diff"
226
+ echo "Hello" | kward filter "Translate to German"
227
+ kward filter "Indent this JSON" < unindented.json
228
228
  ```
229
229
 
230
- Use `--mode chat`, `--mode oneshot`, or `--mode filter` to override automatic mode detection. Use `--` when your prompt starts with something that could be parsed as a command or option:
230
+ Use `--mode chat` or `--mode oneshot` to override execution mode. Put `--` after `prompt` or `filter` when the text begins with an option-like value:
231
231
 
232
232
  ```bash
233
- kward -- explain --working-directory
233
+ kward prompt -- --working-directory is part of the prompt
234
234
  ```
235
235
 
236
+ Unknown command-line arguments are reported as errors rather than sent to the model. Start interactive chat with `kward` and no command.
237
+
236
238
  One-shot prompts do not use Kward memory.
237
239
 
238
240
  ## Workspace tools
@@ -264,6 +266,14 @@ Use this for tasks such as:
264
266
  This screenshot shows the broken layout. Find the likely CSS issue.
265
267
  ```
266
268
 
269
+ ### Generate an image with Codex
270
+
271
+ In an interactive Codex chat, ask normally: “Create a pixel-art lighthouse on a stormy coast.” Kward shows an animated indicator while Codex works. Generation uses your Codex account limits and does not fall back to API-key billing.
272
+
273
+ When the PNG is ready, Kward opens a preview. Press **D** to save to Downloads, or **P** to choose a folder inside the current project or worktree. Press **Tab** to complete a directory and **Enter** to save. Kward chooses an unused filename rather than overwriting anything. If your terminal can’t display the image, the save options still work.
274
+
275
+ Press **Esc** in the directory picker to return to the preview. Press **Esc** in the preview to discard it; saved copies are unaffected. Unsaved previews are temporary and do not survive closing the tab or quitting Kward. Generation is available in interactive terminal chat and in RPC clients that implement [generated image previews](rpc.md#generated-image-previews), not in one-shot, filter, or Pan mode.
276
+
267
277
  ## Pan mode
268
278
 
269
279
  Pan mode starts a mobile-friendly local web UI:
@@ -0,0 +1,103 @@
1
+ # OpenRouter-compatible Codex proxy
2
+
3
+ The example `openrouter_proxy` plugin lets a local application use Kward's configured Codex subscription for Chat Completions. It routes chat through Kward's normal Codex provider client and translates the resulting stream back to Chat Completions JSON or SSE. It can also serve deterministic, locally generated fake embeddings for app setup and inspection without contacting an embedding provider.
4
+
5
+ This is a deliberately limited compatibility layer, not a complete OpenRouter replacement.
6
+
7
+ ## Install and configure
8
+
9
+ Copy the example plugin into Kward's trusted plugin directory:
10
+
11
+ ```bash
12
+ mkdir -p ~/.kward/plugins/openrouter_proxy
13
+ cp examples/plugins/openrouter_proxy/*.rb ~/.kward/plugins/openrouter_proxy/
14
+ ```
15
+
16
+ The proxy uses the Codex subscription already configured in Kward. If you have not configured that account yet, sign in once with:
17
+
18
+ ```bash
19
+ kward login
20
+ ```
21
+
22
+ Configure at least one client-visible model ID to Codex model ID mapping in `~/.kward/config.json`:
23
+
24
+ ```json
25
+ {
26
+ "plugins": {
27
+ "com.kward.openrouter-proxy": {
28
+ "port": 4000,
29
+ "model_map": {
30
+ "openai/gpt-5-mini": "gpt-5-mini"
31
+ },
32
+ "fake_embedding_models": {
33
+ "kward/fake-embedding-1536": 1536
34
+ }
35
+ }
36
+ }
37
+ }
38
+ ```
39
+
40
+ Set a separate local bearer token in the environment. The plugin reads this secret without displaying it:
41
+
42
+ ```bash
43
+ export KWARD_PLUGIN_COM_KWARD_OPENROUTER_PROXY_API_KEY="$(openssl rand -hex 32)"
44
+ ```
45
+
46
+ Start the proxy in the foreground:
47
+
48
+ ```bash
49
+ kward --openrouter-proxy
50
+ ```
51
+
52
+ By default it listens only on `127.0.0.1:4000`. Configure another loopback port with the plugin's `port` setting. The local base URL is `http://127.0.0.1:4000/api/v1`; use the local bearer token as the client's API key.
53
+
54
+ ## Point an application at it
55
+
56
+ Configure the application's **chat-completions** endpoint/base URL to the local address and its key to the local proxy token. Its model value must match a key in `model_map` exactly. For example, `openai/gpt-5-mini` maps to Codex model `gpt-5-mini`.
57
+
58
+ Point both the application's chat-completions and embeddings endpoints at the local base URL. Configure the app to request the exact fake embedding model ID from `fake_embedding_models`, such as `kward/fake-embedding-1536`. Chat completions still use Codex; embedding requests are computed locally and never sent upstream. The same local bearer token authenticates both endpoints.
59
+
60
+ A minimal request looks like:
61
+
62
+ ```bash
63
+ curl http://127.0.0.1:4000/api/v1/chat/completions \
64
+ -H "Authorization: Bearer $KWARD_PLUGIN_COM_KWARD_OPENROUTER_PROXY_API_KEY" \
65
+ -H "Content-Type: application/json" \
66
+ -d '{
67
+ "model": "openai/gpt-5-mini",
68
+ "messages": [
69
+ {"role": "system", "content": "Reply concisely."},
70
+ {"role": "user", "content": "Say hello."}
71
+ ]
72
+ }'
73
+ ```
74
+
75
+ Add `"stream": true` to receive Chat Completions SSE chunks. Non-streaming chat requests also use Kward's normal streamed Codex request and are collected into one JSON completion.
76
+
77
+ A fake embedding request looks like:
78
+
79
+ ```bash
80
+ curl http://127.0.0.1:4000/api/v1/embeddings \
81
+ -H "Authorization: Bearer $KWARD_PLUGIN_COM_KWARD_OPENROUTER_PROXY_API_KEY" \
82
+ -H "Content-Type: application/json" \
83
+ -d '{"model":"kward/fake-embedding-1536","input":"A sample sentence."}'
84
+ ```
85
+
86
+ ## Supported API subset
87
+
88
+ - `POST /api/v1/chat/completions`.
89
+ - `POST /api/v1/embeddings` for configured fake models. This endpoint is deterministic, local, and does not contact Codex or another embedding provider.
90
+ - Streaming and non-streaming text responses.
91
+ - `system`, `user`, and `assistant` messages with string content.
92
+ - Strict `response_format.type: "json_schema"`.
93
+ - `max_tokens` is accepted for compatibility but is not enforced by Kward's Codex provider path.
94
+ - Explicit model mapping; unconfigured model IDs are rejected.
95
+ - OpenAI-compatible JSON errors before streaming starts; error chunks for failures after streaming begins.
96
+
97
+ Fake embeddings use stable token hashing, not a trained model: identical text produces identical vectors, but vectors do not capture semantic meaning and search quality will be poor. Configure each fake model ID with its output dimension. Text input, float encoding, and batches of up to 64 strings are supported; requested dimensions are bounded to 4096. Usage token counts are approximate. Unknown fake model IDs and unsupported fields are rejected. `GET /models`, image/audio content, model routing, and tool calls remain unsupported. This plugin does not advertise general OpenRouter compatibility.
98
+
99
+ ## Security and lifecycle
100
+
101
+ The listener is loopback-only, request sizes and timeouts are bounded, and the local bearer token is distinct from Kward's subscription credentials. Incoming client credentials are checked locally and are never forwarded upstream. Chat requests use Kward's existing Codex credential and account context; those credentials are not returned to the plugin client. Embedding inputs are processed locally and are not logged or sent upstream. Stop the foreground process to stop the listener; Kward also stops plugin-owned listeners during cleanup.
102
+
103
+ For parity with normal Kward Codex agent requests, chat uses Kward's existing `https://chatgpt.com/backend-api/codex/responses` route. This is an undocumented/private endpoint and may change without notice; the proxy is therefore coupled to Kward's internal Codex provider behavior. See the [Kward plugin guide](https://github.com/kaiwood/kward/blob/main/doc/plugins.md) for plugin installation and host APIs, and [OpenRouter's API reference](https://openrouter.ai/docs/api_reference/overview) for the broader API this subset resembles.
@@ -0,0 +1,85 @@
1
+ require "digest"
2
+ require_relative "protocol"
3
+
4
+ module Kward
5
+ module OpenRouterProxy
6
+ class FakeEmbeddings
7
+ REQUEST_KEYS = %w[model input dimensions encoding_format].freeze
8
+ MAX_DIMENSIONS = 4096
9
+ MAX_INPUTS = 64
10
+
11
+ def initialize(models:)
12
+ raise ArgumentError, "fake_embedding_models must be an object" unless models.is_a?(Hash)
13
+
14
+ @models = models.each_with_object({}) do |(model, dimensions), configured|
15
+ unless model.is_a?(String) && !model.empty? && dimensions.is_a?(Integer) && dimensions.between?(1, MAX_DIMENSIONS)
16
+ raise ArgumentError, "fake_embedding_models must map model IDs to dimensions between 1 and #{MAX_DIMENSIONS}"
17
+ end
18
+
19
+ configured[model] = dimensions
20
+ end.freeze
21
+ end
22
+
23
+ def create(value)
24
+ raise RequestError, "Request body must be an object" unless value.is_a?(Hash)
25
+
26
+ unsupported = value.keys.map(&:to_s) - REQUEST_KEYS
27
+ raise RequestError, "Unsupported request fields: #{unsupported.join(', ')}" unless unsupported.empty?
28
+
29
+ model = value["model"]
30
+ raise RequestError, "A model is required" unless model.is_a?(String) && !model.empty?
31
+
32
+ default_dimensions = @models[model]
33
+ raise RequestError, "Fake embedding model is not configured" unless default_dimensions
34
+
35
+ dimensions = value.fetch("dimensions", default_dimensions)
36
+ unless dimensions.is_a?(Integer) && dimensions.between?(1, MAX_DIMENSIONS)
37
+ raise RequestError, "dimensions must be an integer between 1 and #{MAX_DIMENSIONS}"
38
+ end
39
+
40
+ encoding_format = value.fetch("encoding_format", "float")
41
+ raise RequestError, "Only encoding_format float is supported" unless encoding_format == "float"
42
+
43
+ inputs = normalize_input(value["input"])
44
+ if inputs.length > MAX_INPUTS
45
+ raise RequestError, "input must contain no more than #{MAX_INPUTS} items"
46
+ end
47
+
48
+ token_count = inputs.sum { |input| input.scan(/\S+/).length }
49
+ {
50
+ object: "list",
51
+ data: inputs.each_with_index.map do |input, index|
52
+ { object: "embedding", embedding: embedding(input, dimensions), index: index }
53
+ end,
54
+ model: model,
55
+ usage: { prompt_tokens: token_count, total_tokens: token_count }
56
+ }
57
+ end
58
+
59
+ private
60
+
61
+ def normalize_input(input)
62
+ inputs = input.is_a?(Array) ? input : [input]
63
+ unless !inputs.empty? && inputs.all? { |item| item.is_a?(String) }
64
+ raise RequestError, "input must be a string or a non-empty array of strings"
65
+ end
66
+
67
+ inputs
68
+ end
69
+
70
+ def embedding(text, dimensions)
71
+ vector = Array.new(dimensions, 0.0)
72
+ text.downcase.scan(/[\p{Alnum}]+/u) do |token|
73
+ digest = Digest::SHA256.digest(token)
74
+ index = digest.unpack1("N") % dimensions
75
+ vector[index] += digest.getbyte(4).odd? ? 1.0 : -1.0
76
+ end
77
+
78
+ magnitude = Math.sqrt(vector.sum { |value| value * value })
79
+ return vector if magnitude.zero?
80
+
81
+ vector.map { |value| value / magnitude }
82
+ end
83
+ end
84
+ end
85
+ end
@@ -0,0 +1,7 @@
1
+ require_relative "server"
2
+
3
+ Kward.plugin(id: "com.kward.openrouter-proxy", version: "1.0.0", api: 1) do |plugin|
4
+ plugin.startup_option("--openrouter-proxy", description: "Run the local Codex-backed OpenRouter proxy") do |host|
5
+ Kward::OpenRouterProxy::Server.new(host: host).run
6
+ end
7
+ end
@@ -0,0 +1,202 @@
1
+ require "securerandom"
2
+
3
+ module Kward
4
+ module OpenRouterProxy
5
+ Request = Struct.new(:model_id, :model, :input, :instructions, :text, :max_output_tokens, :stream, keyword_init: true)
6
+
7
+ class RequestError < StandardError
8
+ attr_reader :status
9
+
10
+ def initialize(message, status: 400)
11
+ @status = status
12
+ super(message)
13
+ end
14
+ end
15
+
16
+ class Protocol
17
+ REQUEST_KEYS = %w[model messages stream response_format max_tokens].freeze
18
+ MESSAGE_ROLES = %w[system user assistant].freeze
19
+
20
+ def initialize(model_map:)
21
+ raise ArgumentError, "model_map must be an object" unless model_map.is_a?(Hash)
22
+
23
+ @model_map = model_map.each_with_object({}) do |(client_model, codex_model), mapped|
24
+ next unless client_model.is_a?(String) && !client_model.empty?
25
+ next unless codex_model.is_a?(String) && !codex_model.empty?
26
+
27
+ mapped[client_model] = codex_model
28
+ end.freeze
29
+ end
30
+
31
+ def parse_request(value)
32
+ raise RequestError, "Request body must be an object" unless value.is_a?(Hash)
33
+
34
+ unsupported = value.keys.map(&:to_s) - REQUEST_KEYS
35
+ raise RequestError, "Unsupported request fields: #{unsupported.join(', ')}" unless unsupported.empty?
36
+
37
+ model_id = value["model"]
38
+ raise RequestError, "A model is required" unless model_id.is_a?(String) && !model_id.empty?
39
+
40
+ model = @model_map[model_id]
41
+ raise RequestError, "Model is not configured" unless model
42
+
43
+ messages = value["messages"]
44
+ raise RequestError, "Messages must be a non-empty array" unless messages.is_a?(Array) && !messages.empty?
45
+
46
+ stream = value.fetch("stream", false)
47
+ raise RequestError, "stream must be a boolean" unless [true, false].include?(stream)
48
+
49
+ instructions, input = split_messages(messages)
50
+ raise RequestError, "At least one non-system message is required" if input.empty?
51
+
52
+ text = responses_text_format(value["response_format"])
53
+ max_output_tokens = positive_integer(value["max_tokens"], "max_tokens") if value.key?("max_tokens")
54
+
55
+ Request.new(
56
+ model_id: model_id,
57
+ model: model,
58
+ input: input,
59
+ instructions: instructions,
60
+ text: text,
61
+ max_output_tokens: max_output_tokens,
62
+ stream: stream
63
+ )
64
+ end
65
+
66
+ def responses_request(request)
67
+ result = { model: request.model, input: request.input }
68
+ result[:instructions] = request.instructions unless request.instructions.nil?
69
+ result[:text] = request.text unless request.text.nil?
70
+ result[:max_output_tokens] = request.max_output_tokens if request.max_output_tokens
71
+ result
72
+ end
73
+
74
+ def stream_state(request)
75
+ { id: "chatcmpl-#{SecureRandom.hex(12)}", created: Time.now.to_i, model: request.model_id, terminal: false }
76
+ end
77
+
78
+ def stream_start_chunk(state)
79
+ chat_chunk(state, delta: { role: "assistant" })
80
+ end
81
+
82
+ def stream_chunks(state, event)
83
+ return [] if state[:terminal]
84
+
85
+ case event["type"]
86
+ when "response.output_text.delta"
87
+ return [] unless event["delta"].is_a?(String)
88
+
89
+ [chat_chunk(state, delta: { content: event["delta"] })]
90
+ when "response.completed"
91
+ state[:terminal] = true
92
+ response = event["response"].is_a?(Hash) ? event["response"] : {}
93
+ chunks = [chat_chunk(state, delta: {}, finish_reason: "stop")]
94
+ chunks << chat_chunk(state, delta: {}, finish_reason: "stop", usage: chat_usage(response["usage"])) if response["usage"].is_a?(Hash)
95
+ chunks
96
+ when "response.failed", "response.incomplete"
97
+ state[:terminal] = true
98
+ state[:failed] = true
99
+ [chat_chunk(state, delta: {}, finish_reason: "error", error: { code: "server_error", message: "Codex response did not complete" })]
100
+ else
101
+ []
102
+ end
103
+ end
104
+
105
+ def chat_completion(request, events)
106
+ terminal = events.reverse.find { |event| %w[response.completed response.failed response.incomplete].include?(event["type"]) }
107
+ raise RequestError.new("Codex did not complete the response", status: 502) unless terminal&.fetch("type") == "response.completed"
108
+
109
+ response = terminal["response"].is_a?(Hash) ? terminal["response"] : {}
110
+ output_text = events.filter_map do |event|
111
+ event["delta"] if event["type"] == "response.output_text.delta" && event["delta"].is_a?(String)
112
+ end.join
113
+ output_text = response_output_text(response) if output_text.empty?
114
+
115
+ result = {
116
+ id: response["id"] ? "chatcmpl-#{response['id']}" : "chatcmpl-#{SecureRandom.hex(12)}",
117
+ object: "chat.completion",
118
+ created: Time.now.to_i,
119
+ model: request.model_id,
120
+ choices: [{ index: 0, message: { role: "assistant", content: output_text }, finish_reason: "stop" }]
121
+ }
122
+ result[:usage] = chat_usage(response["usage"]) if response["usage"].is_a?(Hash)
123
+ result
124
+ end
125
+
126
+ private
127
+
128
+ def split_messages(messages)
129
+ instructions = []
130
+ input = messages.map.with_index do |message, index|
131
+ unless message.is_a?(Hash) && MESSAGE_ROLES.include?(message["role"]) && message["content"].is_a?(String)
132
+ raise RequestError, "Message #{index} must have a supported role and string content"
133
+ end
134
+
135
+ if message["role"] == "system"
136
+ instructions << message["content"]
137
+ nil
138
+ else
139
+ { role: message["role"], content: message["content"] }
140
+ end
141
+ end.compact
142
+ [instructions.empty? ? nil : instructions.join("\n\n"), input]
143
+ end
144
+
145
+ def responses_text_format(value)
146
+ return nil if value.nil?
147
+ raise RequestError, "response_format must be an object" unless value.is_a?(Hash)
148
+ raise RequestError, "Only json_schema response_format is supported" unless value["type"] == "json_schema"
149
+
150
+ schema_format = value["json_schema"]
151
+ unless schema_format.is_a?(Hash) && schema_format["schema"].is_a?(Hash)
152
+ raise RequestError, "response_format.json_schema.schema must be an object"
153
+ end
154
+
155
+ format = {
156
+ type: "json_schema",
157
+ name: schema_format["name"].to_s.empty? ? "response" : schema_format["name"].to_s,
158
+ schema: schema_format["schema"],
159
+ strict: schema_format.fetch("strict", true)
160
+ }
161
+ raise RequestError, "response_format.json_schema.strict must be a boolean" unless [true, false].include?(format[:strict])
162
+
163
+ { format: format }
164
+ end
165
+
166
+ def positive_integer(value, name)
167
+ raise RequestError, "#{name} must be a positive integer" unless value.is_a?(Integer) && value.positive?
168
+
169
+ value
170
+ end
171
+
172
+ def chat_chunk(state, delta:, finish_reason: nil, usage: nil, error: nil)
173
+ chunk = {
174
+ id: state[:id],
175
+ object: "chat.completion.chunk",
176
+ created: state[:created],
177
+ model: state[:model],
178
+ choices: [{ index: 0, delta: delta, finish_reason: finish_reason }]
179
+ }
180
+ chunk[:usage] = usage if usage
181
+ chunk[:error] = error if error
182
+ chunk
183
+ end
184
+
185
+ def response_output_text(response)
186
+ Array(response["output"]).filter_map do |item|
187
+ next unless item.is_a?(Hash) && item["type"] == "message"
188
+
189
+ Array(item["content"]).filter_map do |part|
190
+ part["text"] if part.is_a?(Hash) && part["type"] == "output_text"
191
+ end.join
192
+ end.join
193
+ end
194
+
195
+ def chat_usage(usage)
196
+ input = usage["input_tokens"].to_i
197
+ output = usage["output_tokens"].to_i
198
+ { prompt_tokens: input, completion_tokens: output, total_tokens: usage["total_tokens"].to_i.positive? ? usage["total_tokens"].to_i : input + output }
199
+ end
200
+ end
201
+ end
202
+ end