kward 0.84.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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +164 -0
- data/CONTRIBUTING.md +1 -1
- data/Gemfile.lock +6 -2
- data/README.md +5 -5
- data/Rakefile +3 -0
- data/doc/agent-tools.md +24 -1
- data/doc/api.md +20 -2
- data/doc/composer.md +5 -4
- data/doc/configuration.md +86 -14
- data/doc/extensibility.md +4 -1
- data/doc/getting-started.md +3 -3
- data/doc/git.md +4 -2
- data/doc/memory.md +1 -1
- data/doc/pan.md +6 -0
- data/doc/permissions.md +4 -4
- data/doc/plugins.md +504 -20
- data/doc/providers.md +10 -4
- data/doc/rpc.md +279 -23
- data/doc/sandboxing.md +11 -5
- data/doc/security.md +7 -1
- data/doc/session-management.md +41 -5
- data/doc/shell.md +643 -27
- data/doc/tabs.md +8 -3
- data/doc/transports.md +15 -0
- data/doc/troubleshooting.md +1 -1
- data/doc/usage.md +25 -12
- data/doc/workspace-tools.md +9 -0
- data/examples/plugins/openrouter_proxy/README.md +103 -0
- data/examples/plugins/openrouter_proxy/fake_embeddings.rb +85 -0
- data/examples/plugins/openrouter_proxy/plugin.rb +7 -0
- data/examples/plugins/openrouter_proxy/protocol.rb +202 -0
- data/examples/plugins/openrouter_proxy/server.rb +186 -0
- data/examples/plugins/space_invaders.rb +1 -2
- data/examples/plugins/stardate_footer.rb +2 -2
- data/examples/plugins/telegram/plugin.rb +1 -1
- data/exe/kward +2 -2
- data/exe/kwsh +7 -0
- data/kward.gemspec +3 -1
- data/lib/kward/agent.rb +66 -19
- data/lib/kward/cli/commands.rb +41 -11
- data/lib/kward/cli/compaction.rb +9 -3
- data/lib/kward/cli/interactive_turn.rb +10 -0
- data/lib/kward/cli/plugins.rb +85 -12
- data/lib/kward/cli/prompt_interface.rb +29 -6
- data/lib/kward/cli/rendering.rb +24 -28
- data/lib/kward/cli/runtime_helpers.rb +168 -56
- data/lib/kward/cli/sessions.rb +9 -5
- data/lib/kward/cli/settings/menus.rb +745 -0
- data/lib/kward/cli/settings/model.rb +316 -0
- data/lib/kward/cli/settings.rb +6 -1055
- data/lib/kward/cli/slash_commands.rb +45 -4
- data/lib/kward/cli/tabs.rb +257 -44
- data/lib/kward/cli/tool_summaries.rb +2 -0
- data/lib/kward/{cli_transcript_formatter.rb → cli/transcript_formatter.rb} +6 -13
- data/lib/kward/cli/worktrees.rb +66 -2
- data/lib/kward/cli.rb +82 -31
- data/lib/kward/compactor.rb +18 -7
- data/lib/kward/config/core.rb +400 -0
- data/lib/kward/config/extensions.rb +99 -0
- data/lib/kward/config/paths.rb +11 -0
- data/lib/kward/config/prompts.rb +313 -0
- data/lib/kward/config/settings.rb +257 -0
- data/lib/kward/config_files.rb +14 -1008
- data/lib/kward/conversation.rb +41 -2
- data/lib/kward/entrypoint.rb +14 -0
- data/lib/kward/events.rb +2 -0
- data/lib/kward/generated_images.rb +237 -0
- data/lib/kward/image_attachments.rb +1 -1
- data/lib/kward/model/catalog.rb +6 -3
- data/lib/kward/model/client.rb +107 -38
- data/lib/kward/model/codex_images.rb +83 -0
- data/lib/kward/model/copilot_models.rb +10 -6
- data/lib/kward/model/model_info.rb +42 -7
- data/lib/kward/{openrouter_model_cache.rb → model/openrouter_model_cache.rb} +7 -5
- data/lib/kward/model/payloads.rb +18 -8
- data/lib/kward/model/sources.rb +3 -1
- data/lib/kward/model/stream_parser.rb +4 -7
- data/lib/kward/model/typesafe_client.rb +78 -0
- data/lib/kward/pan/index.html.erb +8 -1
- data/lib/kward/pan/server.rb +23 -8
- data/lib/kward/permissions/policy.rb +6 -2
- data/lib/kward/plugin_registry.rb +2 -659
- data/lib/kward/plugins/actions.rb +453 -0
- data/lib/kward/plugins/chat_contract.rb +121 -0
- data/lib/kward/{plugin_chat_runtime.rb → plugins/chat_runtime.rb} +62 -18
- data/lib/kward/plugins/codex_responses.rb +73 -0
- data/lib/kward/plugins/host.rb +248 -0
- data/lib/kward/plugins/http_server.rb +83 -0
- data/lib/kward/plugins/registry.rb +1229 -0
- data/lib/kward/plugins/resources.rb +206 -0
- data/lib/kward/plugins/turn_request.rb +36 -0
- data/lib/kward/plugins/ui.rb +219 -0
- data/lib/kward/prompt_interface/composer_controller.rb +0 -1
- data/lib/kward/prompt_interface/composer_renderer.rb +160 -73
- data/lib/kward/prompt_interface/composer_state.rb +1 -1
- data/lib/kward/prompt_interface/editor/controller.rb +2 -2
- data/lib/kward/prompt_interface/editor/renderer.rb +10 -7
- data/lib/kward/prompt_interface/editor/runner.rb +1 -1
- data/lib/kward/prompt_interface/editor/state.rb +1 -1
- data/lib/kward/prompt_interface/file_overlay.rb +3 -3
- data/lib/kward/prompt_interface/generated_image_preview.rb +162 -0
- data/lib/kward/prompt_interface/git_prompt.rb +18 -11
- data/lib/kward/prompt_interface/interactive/renderer.rb +1 -1
- data/lib/kward/prompt_interface/interactive/state.rb +18 -20
- data/lib/kward/prompt_interface/key_handler.rb +108 -25
- data/lib/kward/prompt_interface/layout.rb +11 -1
- data/lib/kward/prompt_interface/overlay_renderer.rb +26 -9
- data/lib/kward/prompt_interface/plugin_ui_requests.rb +82 -0
- data/lib/kward/prompt_interface/project_browser.rb +27 -54
- data/lib/kward/prompt_interface/prompt_renderer.rb +27 -35
- data/lib/kward/prompt_interface/question_prompt.rb +19 -28
- data/lib/kward/prompt_interface/runtime_state.rb +37 -10
- data/lib/kward/prompt_interface/screen.rb +30 -20
- data/lib/kward/prompt_interface/selection_prompt.rb +8 -8
- data/lib/kward/prompt_interface/slash_overlay.rb +1 -1
- data/lib/kward/prompt_interface/transcript_renderer.rb +7 -6
- data/lib/kward/prompt_interface.rb +149 -30
- data/lib/kward/prompts/commands.rb +2 -1
- data/lib/kward/prompts.rb +7 -1
- data/lib/kward/{adaptive_pty_output_sink.rb → pty/adaptive_output_sink.rb} +39 -5
- data/lib/kward/{interactive_pty_runner.rb → pty/interactive_runner.rb} +22 -30
- data/lib/kward/{local_command_runner.rb → pty/local_command_runner.rb} +1 -1
- data/lib/kward/{local_pty_command_runner.rb → pty/local_pty_runner.rb} +3 -9
- data/lib/kward/{pty_output_sink.rb → pty/output_sink.rb} +9 -4
- data/lib/kward/pty/transcript_normalizer.rb +137 -0
- data/lib/kward/rpc/config_manager.rb +3 -0
- data/lib/kward/rpc/plugin_chat_manager.rb +30 -10
- data/lib/kward/rpc/prompt_bridge.rb +25 -0
- data/lib/kward/rpc/server.rb +118 -17
- data/lib/kward/rpc/session_manager.rb +208 -60
- data/lib/kward/rpc/session_tree_rows.rb +2 -2
- data/lib/kward/rpc/tool_metadata.rb +1 -1
- data/lib/kward/rpc/transcript_normalizer.rb +11 -7
- data/lib/kward/sandbox/command_runner.rb +1 -1
- data/lib/kward/{session_catalog.rb → sessions/catalog.rb} +1 -1
- data/lib/kward/{session_store.rb → sessions/store.rb} +39 -12
- data/lib/kward/{session_tree_nodes.rb → sessions/tree_nodes.rb} +3 -3
- data/lib/kward/{session_tree_renderer.rb → sessions/tree_renderer.rb} +4 -4
- data/lib/kward/{session_tree_tool_display.rb → sessions/tree_tool_display.rb} +1 -1
- data/lib/kward/{kwsh.rb → shell/kwsh.rb} +30 -10
- data/lib/kward/{kwshrc.rb → shell/kwshrc.rb} +11 -2
- data/lib/kward/shell/native_arithmetic.rb +255 -0
- data/lib/kward/shell/native_arrays.rb +102 -0
- data/lib/kward/shell/native_braces.rb +96 -0
- data/lib/kward/shell/native_builtins.rb +476 -0
- data/lib/kward/shell/native_completion.rb +169 -0
- data/lib/kward/shell/native_condition.rb +75 -0
- data/lib/kward/shell/native_directory.rb +116 -0
- data/lib/kward/shell/native_exec_state.rb +73 -0
- data/lib/kward/shell/native_expansion.rb +252 -0
- data/lib/kward/shell/native_fields.rb +62 -0
- data/lib/kward/shell/native_glob.rb +96 -0
- data/lib/kward/shell/native_history.rb +242 -0
- data/lib/kward/shell/native_interactive.rb +164 -0
- data/lib/kward/shell/native_invocation.rb +42 -0
- data/lib/kward/shell/native_jobs.rb +250 -0
- data/lib/kward/shell/native_line_editor.rb +382 -0
- data/lib/kward/shell/native_line_terminal.rb +286 -0
- data/lib/kward/shell/native_locale.rb +109 -0
- data/lib/kward/shell/native_locals.rb +57 -0
- data/lib/kward/shell/native_pattern.rb +200 -0
- data/lib/kward/shell/native_process.rb +279 -0
- data/lib/kward/shell/native_program.rb +40 -0
- data/lib/kward/shell/native_programmable_completion.rb +115 -0
- data/lib/kward/shell/native_prompt_format.rb +89 -0
- data/lib/kward/shell/native_runtime.rb +964 -0
- data/lib/kward/shell/native_substitution.rb +110 -0
- data/lib/kward/shell/native_syntax.rb +946 -0
- data/lib/kward/shell/native_traps.rb +196 -0
- data/lib/kward/shell/native_vi.rb +407 -0
- data/lib/kward/shell/native_vi_terminal.rb +19 -0
- data/lib/kward/shell/native_worker.rb +82 -0
- data/lib/kward/{persistent_shell_session.rb → shell/persistent_session.rb} +187 -193
- data/lib/kward/shell/prompt.rb +66 -0
- data/lib/kward/shell/prompt_agent.rb +17 -0
- data/lib/kward/{shell_prompt_session.rb → shell/prompt_session.rb} +1 -1
- data/lib/kward/shell/script_runner.rb +244 -0
- data/lib/kward/shell/standalone_agent.rb +31 -0
- data/lib/kward/shell/standalone_link.rb +78 -0
- data/lib/kward/shell/standalone_terminal.rb +287 -0
- data/lib/kward/skills/trust_store.rb +1 -1
- data/lib/kward/tabs/driver.rb +194 -0
- data/lib/kward/{tab_store.rb → tabs/store.rb} +2 -2
- data/lib/kward/{clipboard.rb → terminal/clipboard.rb} +1 -1
- data/lib/kward/{terminal_image_support.rb → terminal/image_support.rb} +1 -1
- data/lib/kward/{terminal_keys.rb → terminal/keys.rb} +22 -1
- data/lib/kward/terminal/locale_text.rb +29 -0
- data/lib/kward/{terminal_sequences.rb → terminal/sequences.rb} +45 -4
- data/lib/kward/tools/base.rb +18 -0
- data/lib/kward/tools/context_for_task.rb +15 -6
- data/lib/kward/tools/datetime.rb +85 -0
- data/lib/kward/tools/edit_file.rb +9 -6
- data/lib/kward/tools/generate_image.rb +36 -0
- data/lib/kward/tools/git_commit.rb +13 -7
- data/lib/kward/tools/list_directory.rb +4 -4
- data/lib/kward/tools/plugin_tool.rb +41 -0
- data/lib/kward/tools/prepare_shell_command.rb +1 -1
- data/lib/kward/tools/read_file.rb +7 -6
- data/lib/kward/tools/registry.rb +130 -21
- data/lib/kward/tools/run_shell_command.rb +10 -8
- data/lib/kward/tools/search/code.rb +1 -1
- data/lib/kward/tools/summarize_file_structure.rb +5 -5
- data/lib/kward/tools/tool_call.rb +4 -1
- data/lib/kward/tools/typesafe_evaluate.rb +81 -0
- data/lib/kward/tools/workspace_targets.rb +58 -0
- data/lib/kward/tools/write_file.rb +9 -6
- data/lib/kward/{export_path.rb → transcripts/export_path.rb} +1 -1
- data/lib/kward/{markdown_transcript.rb → transcripts/markdown_transcript.rb} +10 -2
- data/lib/kward/transcripts/turn_summary_formatter.rb +93 -0
- data/lib/kward/transport/contracts.rb +200 -0
- data/lib/kward/transport/gateway.rb +81 -36
- data/lib/kward/transport/plugin_chat_gateway.rb +3 -2
- data/lib/kward/transport.rb +1 -200
- data/lib/kward/turn_summary.rb +68 -0
- data/lib/kward/version.rb +1 -1
- data/lib/kward/{workspace_factory.rb → workspace/factory.rb} +2 -2
- data/lib/kward/{git_worktree_manager.rb → workspace/git_worktree_manager.rb} +28 -0
- data/lib/kward/{workspace.rb → workspace/workspace.rb} +3 -3
- data/lib/main.rb +6 -3
- data/templates/default/fulldoc/html/css/kward.css +125 -0
- data/templates/default/fulldoc/html/images/kward_screen_1.png +0 -0
- data/templates/default/fulldoc/html/setup.rb +1 -1
- data/templates/default/layout/html/layout.erb +16 -4
- metadata +150 -48
- data/lib/kward/pty_transcript_normalizer.rb +0 -93
- data/lib/kward/shell_prompt.rb +0 -52
- data/lib/kward/tab_driver.rb +0 -90
- data/templates/default/fulldoc/html/images/kward_workflow.svg +0 -52
- /data/lib/kward/{editor_prompt.rb → cli/editor_prompt.rb} +0 -0
- /data/lib/kward/{editor_prompt_session.rb → cli/editor_prompt_session.rb} +0 -0
- /data/lib/kward/{diff_view_mode.rb → prompt_interface/editor/diff_view_mode.rb} +0 -0
- /data/lib/kward/{editor_mode.rb → prompt_interface/editor/editor_mode.rb} +0 -0
- /data/lib/kward/{markdown_code_block.rb → prompt_interface/editor/markdown_code_block.rb} +0 -0
- /data/lib/kward/{scratchpad_languages.rb → prompt_interface/editor/scratchpad_languages.rb} +0 -0
- /data/lib/kward/{scratchpad_runner.rb → prompt_interface/editor/scratchpad_runner.rb} +0 -0
- /data/lib/kward/{detached_run.rb → pty/detached_run.rb} +0 -0
- /data/lib/kward/{session_diff.rb → sessions/diff.rb} +0 -0
- /data/lib/kward/{session_naming.rb → sessions/naming.rb} +0 -0
- /data/lib/kward/{session_trash.rb → sessions/trash.rb} +0 -0
- /data/lib/kward/{ansi.rb → terminal/ansi.rb} +0 -0
- /data/lib/kward/{terminal_text.rb → terminal/text.rb} +0 -0
- /data/lib/kward/{transcript_export.rb → transcripts/transcript_export.rb} +0 -0
- /data/lib/kward/{project_files.rb → workspace/files.rb} +0 -0
- /data/lib/kward/{path_guard.rb → workspace/path_guard.rb} +0 -0
data/doc/tabs.md
CHANGED
|
@@ -59,11 +59,13 @@ Inspect, merge, or remove the binding explicitly:
|
|
|
59
59
|
/tab worktree remove
|
|
60
60
|
```
|
|
61
61
|
|
|
62
|
-
`/tab worktree merge` merges the active worktree's clean, committed branch directly into the branch currently checked out in its original workspace. Kward shows the source and target revisions and requires confirmation. Both worktrees must be clean. If Git reports conflicts, Kward leaves the original workspace in its normal merge state
|
|
62
|
+
`/tab worktree merge` merges the active worktree's clean, committed branch directly into the branch currently checked out in its original workspace. Kward shows the source and target revisions and requires confirmation. Both worktrees must be clean. If Git reports conflicts, Kward leaves the original workspace in its normal merge state while keeping the current tab on the linked branch. The composer shows the target branch and conflict count. Run `/tab worktree merge resolve` (or `/worktree merge resolve`) to start an agent turn that inspects and edits the verified original workspace with `target: "origin"`; the turn leaves committing for review. After the conflicts are resolved, run `/tab worktree merge continue` to stage the resolutions and complete the merge, or use `/tab worktree merge abort` to cancel it.
|
|
63
63
|
|
|
64
64
|
Removal refuses a dirty worktree and keeps its branch. A worktree that is missing or no longer points at the recorded branch is restored as unavailable rather than silently falling back to the original workspace.
|
|
65
65
|
|
|
66
|
-
Worktree tabs are available for normal session tabs, not plugin-owned tabs. Kward's file tools, `@`/`$` completion, `/files` browser, integrated editor, and model-requested shell workers use the active worktree root
|
|
66
|
+
Worktree tabs are available for normal session tabs, not plugin-owned tabs. Kward's file tools, `@`/`$` completion, `/files` browser, integrated editor, and model-requested shell workers use the active worktree root by default. Core model workspace tools advertise an optional `target` selector in an active worktree tab: `active` keeps the normal linked-worktree root, while `origin` selects only that tab's verified original repository worktree. Selecting `origin` does not add a separate approval prompt; the normal configured tool-permission policy applies equally to both targets. Paths remain relative to the selected root, and arbitrary filesystem targets are never accepted.
|
|
67
|
+
|
|
68
|
+
Both targets retain strict workspace guardrails and separate command sandboxes. The user-directed `/shell`, `!command`, `/capture`, and `/pty` features remain host-process operations and are not contained by the model command sandbox; use them only when that is intentional. Generic shell Git writes remain protected. When explicitly asked to commit, the agent can use `git_commit` for the active worktree or set `target: "origin"` for the original worktree; use the interactive `/git` flow when you want to review and commit changes yourself.
|
|
67
69
|
|
|
68
70
|
## Common workflow
|
|
69
71
|
|
|
@@ -98,6 +100,8 @@ Tabs keep the conversations separate, so context from one tab does not automatic
|
|
|
98
100
|
| `/tab worktree detach` | Return to the original workspace while keeping the linked worktree and branch |
|
|
99
101
|
| `/tab worktree status` | Show the current tab's worktree binding and Git status |
|
|
100
102
|
| `/tab worktree merge` | Merge the current worktree branch into the branch checked out in its original workspace |
|
|
103
|
+
| `/tab worktree merge resolve` | Ask the agent to resolve an in-progress merge in the original workspace from the same tab |
|
|
104
|
+
| `/tab worktree merge continue` | Stage resolutions and complete an in-progress merge after confirmation |
|
|
101
105
|
| `/tab worktree merge abort` | Abort a conflicted worktree merge in the original workspace |
|
|
102
106
|
| `/tab worktree remove` | Remove a clean linked worktree and keep its branch |
|
|
103
107
|
| `/worktree …` | Alias for `/tab worktree …` on the active tab |
|
|
@@ -122,7 +126,8 @@ When `composer.tab_keybindings` is `ctrl`:
|
|
|
122
126
|
|
|
123
127
|
| Key | Action |
|
|
124
128
|
| --- | ------ |
|
|
125
|
-
| `Ctrl+T` |
|
|
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 |
|
|
126
131
|
| `Ctrl+W` | Close tab |
|
|
127
132
|
| `Ctrl+1` through `Ctrl+9` | Switch to a numbered tab, if your terminal reports modified number keys |
|
|
128
133
|
|
data/doc/transports.md
CHANGED
|
@@ -104,6 +104,13 @@ Plugin-chat drivers may accept a `context:` keyword on `submit`. Transport turns
|
|
|
104
104
|
provide the authenticated actor there. Existing drivers that do not accept the
|
|
105
105
|
keyword continue to work, but cannot use actor-specific context.
|
|
106
106
|
|
|
107
|
+
The plugin-chat factory host reports `surface: :transport`, the stable chat type
|
|
108
|
+
ID and scope key, immutable plugin configuration, scoped durable storage, secret
|
|
109
|
+
lookup, logging, declared chat capabilities, and managed cleanup. Storage is
|
|
110
|
+
isolated by plugin, chat type, and external conversation scope. Versioned chat
|
|
111
|
+
contracts also reject attachments not declared by that chat type before calling
|
|
112
|
+
the driver.
|
|
113
|
+
|
|
107
114
|
Plugin-chat transport IDs, turn events, transcript storage, and authorization
|
|
108
115
|
remain separate from normal workspace sessions. A plugin's `singleton: :global`
|
|
109
116
|
setting also means that all transport conversations share that one plugin
|
|
@@ -119,6 +126,14 @@ API.
|
|
|
119
126
|
Transports that cannot support interactive approvals must use an explicit
|
|
120
127
|
configured fallback policy; they must not leave an agent turn waiting forever.
|
|
121
128
|
|
|
129
|
+
Structured plugin UI requests use the same transport-neutral interaction path.
|
|
130
|
+
Plugin `question`, `select`, `confirm`, and `input` calls arrive with matching
|
|
131
|
+
interaction kinds, prompts, choices, and metadata, and answers are routed back to the
|
|
132
|
+
waiting plugin handler. An adapter may support only a subset, but it must cancel
|
|
133
|
+
or answer unsupported requests rather than leaving the turn blocked. Plugin
|
|
134
|
+
notifications and progress remain local to the RPC/TUI UI bridge for now and
|
|
135
|
+
are not transport interaction requests.
|
|
136
|
+
|
|
122
137
|
## Storage and routing
|
|
123
138
|
|
|
124
139
|
Transport plugins receive namespaced durable storage for state such as:
|
data/doc/troubleshooting.md
CHANGED
|
@@ -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:
|
|
@@ -136,11 +136,14 @@ Slash commands run local actions in the current session. Most do not send a prom
|
|
|
136
136
|
| `/tab close` | close the active tab. |
|
|
137
137
|
| `/tab new` | open a new tab. |
|
|
138
138
|
| `/tab name <label>` | rename the active tab label. |
|
|
139
|
+
| `/name <name>` | rename the active session and tab together; available while the tab's agent is running. |
|
|
139
140
|
| `/tab worktree` | create or activate the active session tab's linked Git worktree. |
|
|
140
141
|
| `/tab worktree activate` | explicitly create or activate the active session tab's linked Git worktree. |
|
|
141
142
|
| `/tab worktree detach` | return to the original workspace while keeping the linked worktree and branch. |
|
|
142
143
|
| `/tab worktree status` | inspect the active tab's worktree binding and changes. |
|
|
143
144
|
| `/tab worktree merge` | merge a clean worktree branch into the branch checked out in its original workspace. |
|
|
145
|
+
| `/tab worktree merge resolve` | ask the agent to resolve an in-progress merge in the original workspace from the same tab. |
|
|
146
|
+
| `/tab worktree merge continue` | stage resolutions and complete an in-progress merge after confirmation. |
|
|
144
147
|
| `/tab worktree merge abort` | abort a conflicted worktree merge in the original workspace. |
|
|
145
148
|
| `/tab worktree remove` | remove a clean linked worktree while keeping its branch. |
|
|
146
149
|
| `/worktree …` | alias for `/tab worktree …` on the active tab. |
|
|
@@ -191,7 +194,7 @@ Use sessions when work spans more than one terminal sitting, or when you want to
|
|
|
191
194
|
Typical flow:
|
|
192
195
|
|
|
193
196
|
```text
|
|
194
|
-
/
|
|
197
|
+
/name oauth cleanup
|
|
195
198
|
# work with Kward
|
|
196
199
|
/export oauth-notes.md
|
|
197
200
|
/exit
|
|
@@ -212,24 +215,26 @@ For the full guide to context management, cloning, forking, rewinding, `/tree`,
|
|
|
212
215
|
One-shot prompts are best for short tasks that do not need session history:
|
|
213
216
|
|
|
214
217
|
```bash
|
|
215
|
-
kward "What does this repository do?"
|
|
216
|
-
cat error.log | kward
|
|
218
|
+
kward prompt "What does this repository do?"
|
|
219
|
+
cat error.log | kward prompt "Explain the errors in this log"
|
|
217
220
|
```
|
|
218
221
|
|
|
219
|
-
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.
|
|
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.
|
|
220
223
|
|
|
221
224
|
```bash
|
|
222
|
-
git diff | kward "Review this diff"
|
|
223
|
-
echo "Hello" | kward
|
|
224
|
-
kward
|
|
225
|
+
git diff | kward prompt "Review this diff"
|
|
226
|
+
echo "Hello" | kward filter "Translate to German"
|
|
227
|
+
kward filter "Indent this JSON" < unindented.json
|
|
225
228
|
```
|
|
226
229
|
|
|
227
|
-
Use `--mode chat
|
|
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:
|
|
228
231
|
|
|
229
232
|
```bash
|
|
230
|
-
kward --
|
|
233
|
+
kward prompt -- --working-directory is part of the prompt
|
|
231
234
|
```
|
|
232
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
|
+
|
|
233
238
|
One-shot prompts do not use Kward memory.
|
|
234
239
|
|
|
235
240
|
## Workspace tools
|
|
@@ -261,6 +266,14 @@ Use this for tasks such as:
|
|
|
261
266
|
This screenshot shows the broken layout. Find the likely CSS issue.
|
|
262
267
|
```
|
|
263
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
|
+
|
|
264
277
|
## Pan mode
|
|
265
278
|
|
|
266
279
|
Pan mode starts a mobile-friendly local web UI:
|
data/doc/workspace-tools.md
CHANGED
|
@@ -21,6 +21,15 @@ Important behavior:
|
|
|
21
21
|
- Edits use exact text replacement, so accidental partial or fuzzy changes fail instead of guessing.
|
|
22
22
|
- With sandboxing off (the default), shell commands run as your operating-system user from the workspace. Enable [command sandboxing](sandboxing.md) to apply an OS boundary to model-requested `run_shell_command` workers. Command output is capped at 128 KB.
|
|
23
23
|
|
|
24
|
+
### Worktree targets
|
|
25
|
+
|
|
26
|
+
In an active linked-worktree tab, `list_directory`, `read_file`, `write_file`, `edit_file`, `run_shell_command`, `summarize_file_structure`, and `context_for_task` also advertise an optional `target` argument:
|
|
27
|
+
|
|
28
|
+
- `active` is the default linked worktree.
|
|
29
|
+
- `origin` is the tab's verified original repository worktree.
|
|
30
|
+
|
|
31
|
+
Kward supplies this fixed role map from the tab binding; the model cannot provide an arbitrary filesystem root. Selecting `origin` does not add a separate approval prompt, so the agent can complete a requested inspect/edit/test/commit workflow without interruption. The normal configured tool-permission policy still applies equally to both targets. Each target keeps its own path guard and strict shell sandbox.
|
|
32
|
+
|
|
24
33
|
## Reading the workspace
|
|
25
34
|
|
|
26
35
|
### `list_directory`
|
|
@@ -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
|