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/shell.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Standalone and embedded shell
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Use `kward shell` to run Kward’s native shell in your terminal. The shell starts without the agent or composer; use `?` when you want the agent. If you’re already in Kward’s interactive TUI, choose the workflow that matches what you are doing:
|
|
4
4
|
|
|
5
5
|
- **For one quick command, use `!command`.** It runs from the active workspace and returns you to the normal composer when it finishes.
|
|
6
6
|
- **For a longer stretch of shell work, use `/shell`.** It keeps its directory, environment, aliases, and history between commands.
|
|
@@ -9,6 +9,91 @@ Kward lets you run your own shell commands without leaving the interactive TUI.
|
|
|
9
9
|
|
|
10
10
|
Ordinary `!command` input and external commands inside `/shell` receive an interactive PTY. Pagers, Vim, SSH, REPLs, password prompts, and other interactive tools therefore work without a `pty` prefix.
|
|
11
11
|
|
|
12
|
+
## Start a standalone shell
|
|
13
|
+
|
|
14
|
+
Run this from the directory you want to work in. No Kward login or agent configuration is needed:
|
|
15
|
+
|
|
16
|
+
```sh
|
|
17
|
+
kward shell
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Output scrolls normally, and foreground programs such as `less` and Vim own the shell’s terminal while they run. After a program exits, the shell prints its next prompt. Use **Up/Down** to recall history, **Left/Right** or **Home/End** to move, and **Backspace/Delete** to edit. Press **Tab** to complete a command, alias, function, or path. Tab extends a common prefix. Press it again to open the completion menu: **Tab / Shift+Tab** cycle through matches, **Esc** restores the draft as it was before the menu opened, and **Enter** accepts the choice without running it. Press Enter again to submit. After `cd`, it suggests directories only. In a terminal that supports bracketed paste, pasted commands stay in the draft until you press **Enter**, even if they span several lines. In a multiline draft, **Up/Down** move between lines and **Home/End** move within the current line. Terminals that send a distinct Shift+Enter key sequence can use it to insert a newline. **Ctrl+C** cancels the draft, and **Ctrl+D** on an empty prompt (or `exit`) leaves the shell.
|
|
21
|
+
|
|
22
|
+
Use `kward shell -o vi` or `set -o vi` to switch to native vi editing. `set +o vi` returns to the default editor. `TERM=dumb` falls back to plain input. Piping input runs the shell non-interactively unless you pass `-i`. History is in memory by default; see [standalone history](#standalone-command-history) for persistence and replay.
|
|
23
|
+
|
|
24
|
+
You can also run the same native language non-interactively:
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
kward shell -c 'printf "%s\n" "$PWD"'
|
|
28
|
+
kward shell scripts/check.kwsh README.md
|
|
29
|
+
printf 'printf "hello\\n"\n' | kward shell
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Interactive `kward shell` executes `~/.kward/kwshrc` and then `~/.kwshrc` in the current shell. Put aliases, exports, functions, and other native shell code there. Ordinary `-c` commands, scripts, and piped input skip startup files unless you explicitly pass `-i`. The hosted `/shell` only reads declarative settings from these files. See [Configuration](configuration.md) for the difference.
|
|
33
|
+
|
|
34
|
+
From a checkout, use `ruby exe/kward shell`. This is a traditional terminal frontend for **kwsh**, not Bash or Zsh; their startup files and extensions don’t generally carry over. A small Bash-style completion subset supports rbenv. The hosted composer and `/shell` shortcuts are not part of this mode. It isn’t an RPC or Pan session capability: it needs a local terminal for interactive editing and job control.
|
|
35
|
+
|
|
36
|
+
`kward edit <file>` restores the previous shell screen when you quit. The standalone shell defaults `LESS` to `FR` when unset on a capable terminal, so long Git logs restore the screen on quit and short logs still print normally. Your own `LESS` and pager settings take precedence; use `LESS=FRX` if you prefer to leave the log on screen.
|
|
37
|
+
|
|
38
|
+
### Edit commands and search history
|
|
39
|
+
|
|
40
|
+
In the default editor, use **Option+Left/Right** (**Alt+Left/Right** on other keyboards) or **Alt+B/F** to jump between words. **Option+Backspace** or **Ctrl+W** cuts backward by one word, and **Alt+D** cuts forward by one word.
|
|
41
|
+
|
|
42
|
+
**Ctrl+K** cuts to the end of the current line. **Ctrl+U** clears the whole draft. Use **Ctrl+Y** to insert the most recent cut at the cursor, even at the next prompt. Consecutive word cuts can be yanked together; nothing runs until you press **Enter**.
|
|
43
|
+
|
|
44
|
+
Type a prefix and press **Up/Down** to browse matching commands. With an empty draft, the arrows browse all commands; **Ctrl+P/N** always browse without a prefix.
|
|
45
|
+
|
|
46
|
+
While you type at the end of a fresh, single-line draft, the shell can suggest the rest of a command from history in dim text. For example, if you previously ran `brew outdated`, typing `brew` followed by a space may show `outdated` in grey. Press **Right Arrow** to insert it. If you press **Enter** without accepting it, the shell runs only `brew`. Suggestions run locally, require terminal styling, and can be disabled with `export KWSH_AUTOSUGGEST=0` in `~/.kwshrc`.
|
|
47
|
+
|
|
48
|
+
Press **Ctrl+R** and type part of a command to find it in history. Press **Ctrl+R** again for older matches, or **Ctrl+S** to move toward newer matches. **Enter** runs a match, **Left/Right** returns to editing it, and **Ctrl+G** or **Esc** restores your original draft. If the search fails, use **Backspace** to shorten the query; Enter won’t run an earlier match by mistake.
|
|
49
|
+
|
|
50
|
+
- **Ctrl+L** clears the visible screen and redraws the draft without clearing scrollback.
|
|
51
|
+
- **Ctrl+T** swaps adjacent characters. **Ctrl+_** undoes the last edit in the draft.
|
|
52
|
+
- **Alt+.** inserts the final shell word from the previous history entry, preserving quotes.
|
|
53
|
+
- **Alt+Y**, immediately after **Ctrl+Y**, cycles through older cuts. The cut ring is local to the shell and is not written to disk.
|
|
54
|
+
|
|
55
|
+
If your Mac types special characters instead of sending the shortcuts, try **Terminal → Settings → Profiles → Keyboard → Use Option as Meta key**. **Ctrl+W** works without Option/Meta setup.
|
|
56
|
+
|
|
57
|
+
### Pause history for a sensitive command
|
|
58
|
+
|
|
59
|
+
At a `kward shell` prompt, enter `history pause` on its own line. The prompt starts with `[private]` until you enter `history resume`. `history status` reports whether recording is paused. These controls are local to the current terminal session and are not saved to history.
|
|
60
|
+
|
|
61
|
+
While paused, commands are not added to in-memory or on-disk history, inline suggestions are hidden, and the shell does not collect command context for `?`. Resume before using the shell agent. Previously saved history stays intact. This does not hide commands from the terminal or clear scrollback, and it cannot prevent programs from logging their own input.
|
|
62
|
+
|
|
63
|
+
### Customize the prompt
|
|
64
|
+
|
|
65
|
+
Try this at a `kward shell` prompt, or add the same line to `~/.kwshrc` to keep it:
|
|
66
|
+
|
|
67
|
+
```sh
|
|
68
|
+
export PROMPT='%F{cyan}%~%f %F{yellow}[%?]%f %# '
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
The prompt shows your current directory in cyan, the last exit status in yellow, and a `%` (`#` for root). `cd` and command results update it automatically. On narrow terminals, use `%1~` instead of `%~` to show just the final directory name.
|
|
72
|
+
|
|
73
|
+
- **Directory:** `%~` abbreviates `$HOME` as `~`; `%d` or `%/` shows the full directory; `%1~` shows the last component (or `~` at home).
|
|
74
|
+
- **Other details:** `%n` is your username, `%m` is the short hostname, `%?` is the last exit status, `%#` is the prompt character, and `%%` is a literal `%`.
|
|
75
|
+
- **Styles:** `%F{cyan}` sets the text color and `%f` resets it. `%K{blue}` and `%k` do the same for the background; `%B` and `%b` toggle bold. Colors accept the eight standard names, a palette index from `0` to `255`, or `#RRGGBB`. `NO_COLOR=1`, `KWARD_COLOR=never`, and `TERM=dumb` can disable styling.
|
|
76
|
+
|
|
77
|
+
This is a single-line subset of Zsh’s prompt syntax, not a shell expression. The shell does not expand variables or run commands when drawing it. `unset PROMPT` returns to `PS1`; `PROMPT=''` requests a blank prompt. Continuation lines still use `PS2`. The separate `kwsh` executable and hosted `/shell` keep their existing prompts; RPC and Pan do not render this prompt.
|
|
78
|
+
|
|
79
|
+
### Ask the standalone shell agent
|
|
80
|
+
|
|
81
|
+
At an interactive `kward shell` prompt, ask about the last command just as you would in `/shell`:
|
|
82
|
+
|
|
83
|
+
```text
|
|
84
|
+
$ ls ./missing-directory
|
|
85
|
+
ls: ./missing-directory: No such file or directory
|
|
86
|
+
$ ? what was the last error message?
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
The first question loads your configured Kward model and credentials. The agent sees the last command, its exit status, the current directory, and a bounded portion of plain terminal output from before you supplied interactive input. Full-screen output is not sent. Ordinary shell use does not send output to a model.
|
|
90
|
+
|
|
91
|
+
Ask explicitly to run a command or change shell state and the agent works in the same live shell. For example, `? run brew install glow` prints `brew install glow` after your normal shell prompt and passes Homebrew's output directly to your terminal, including live progress and cursor updates. Only the copy sent to the model is bounded and filtered; output that redraws the screen can be visible in your terminal without being available to the agent.
|
|
92
|
+
|
|
93
|
+
Ask the agent to **prepare** commands that need keyboard input or full-screen terminal access. It puts an editable draft in the native prompt without running it; press **Enter** to run it yourself. With `TERM=dumb` the suggestion is printed instead. **Ctrl+C** cancels a question or a running agent command.
|
|
94
|
+
|
|
95
|
+
This uses a local PTY supervised by `kward`; the interpreter owns the PTY and its foreground jobs. The `?` prompt is not available with redirected standard streams, in scripts, in `kwsh` itself, or over RPC or Pan.
|
|
96
|
+
|
|
12
97
|
## Run a one-off command
|
|
13
98
|
|
|
14
99
|
Prefix a command with `!` in the normal composer:
|
|
@@ -19,11 +104,13 @@ Prefix a command with `!` in the normal composer:
|
|
|
19
104
|
!less README.md
|
|
20
105
|
```
|
|
21
106
|
|
|
22
|
-
The command runs from the active workspace root and begins in an inline PTY region above a frozen composer. Line-oriented output, single-line carriage-return progress, and synchronized-output update brackets scroll the transcript area naturally while keyboard input belongs to the child process. If the child emits alternate-screen, clear-screen,
|
|
107
|
+
The command runs from the active workspace root and begins in an inline PTY region above a frozen composer. Line-oriented output, single-line carriage-return progress, and synchronized-output update brackets scroll the transcript area naturally while keyboard input belongs to the child process. If the child emits alternate-screen, clear-screen, arbitrary row positioning, or unknown terminal controls, Kward conservatively hides the composer and switches permanently to full-terminal passthrough for the rest of that command. Pagers and full-screen applications therefore retain the complete terminal without relying on a command-name allowlist.
|
|
23
108
|
|
|
24
|
-
When an inline command exits without reading input, safe output is mirrored into the transient transcript view so a repaint cannot hide it. Carriage-return and horizontal-cursor progress redraws are reduced to their final visible lines, while an unterminated synchronized-output update is closed before Kward redraws. If the child
|
|
109
|
+
When an inline command exits without reading input, safe output is mirrored into the transient transcript view so a repaint cannot hide it. Carriage-return and horizontal-cursor progress redraws are reduced to their final visible lines, while an unterminated synchronized-output update is closed before Kward redraws. If the child receives input (including terminal replies), Kward retains only output captured before the first forwarded byte; this prevents echoed passwords, OTPs, or other input from entering tab state. Output from one-off commands is never added to the AI conversation or sent to the model.
|
|
25
110
|
|
|
26
|
-
|
|
111
|
+
[Kitty graphics](https://sw.kovidgoyal.net/kitty/graphics-protocol/) and their capability probes can pass through the inline region. If the rest of the command stays inline, Kward returns to the composer without clearing that screen, so images remain visible. Images are live terminal output: Kward does not save or replay them after a tab switch, resize, or full redraw. Use `/files` for an image preview managed by Kward.
|
|
112
|
+
|
|
113
|
+
Shell output can leave transient text in the transcript area. **After the command finishes, press Ctrl+L to redraw the durable conversation and clear that transient `!command` output.** While an interactive command owns the terminal, the composer remains frozen and ordinary keyboard input belongs to the child process. Kward's tab shortcuts are intercepted separately; switching tabs detaches the command and lets it continue in the originating tab's bounded background state. When you return to that tab, complete lines appear as they arrive; the last partial line appears when the command ends.
|
|
27
114
|
|
|
28
115
|
Configured `kwshrc` aliases also work after `!`:
|
|
29
116
|
|
|
@@ -89,7 +176,494 @@ Leave shell mode with `exit`, `logout`, or Ctrl+D on an empty prompt.
|
|
|
89
176
|
|
|
90
177
|
`cd` changes only the embedded shell's directory. It does not change Kward's workspace root or the directory used by the model's other tools.
|
|
91
178
|
|
|
92
|
-
##
|
|
179
|
+
## Write native kwsh scripts
|
|
180
|
+
|
|
181
|
+
`/shell` now interprets a small POSIX-style language in kwsh itself. It does not send your program to Bash or `/bin/sh`, and it is **not a fully POSIX-conforming shell**. The one-off `!command`, `/capture`, and ordinary model shell tools keep their existing execution paths.
|
|
182
|
+
|
|
183
|
+
Define a function, then use it in later commands:
|
|
184
|
+
|
|
185
|
+
```sh
|
|
186
|
+
check_files() {
|
|
187
|
+
for file in "$@"; do
|
|
188
|
+
if [ -f "$file" ]; then
|
|
189
|
+
printf 'Found: %s\n' "$file"
|
|
190
|
+
else
|
|
191
|
+
printf 'Missing: %s\n' "$file" >&2
|
|
192
|
+
return 1
|
|
193
|
+
fi
|
|
194
|
+
done
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
check_files README.md Gemfile || printf '%s\n' 'Some files are missing'
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
When a block or quote is incomplete, the prompt changes to `Shell ... >` and collects more lines. No part of that submission runs until it parses successfully. Ctrl+D leaves shell mode; normal execution cancellation and tab detachment still apply once a program is running.
|
|
201
|
+
|
|
202
|
+
Save a program in a file and run it **inside `/shell`**:
|
|
203
|
+
|
|
204
|
+
```sh
|
|
205
|
+
kwsh scripts/check.kwsh README.md Gemfile
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
The script receives `$0`, `$1`, `${10}`, `$#`, and `"$@"`. It runs in a separate native interpreter process, inheriting exported variables and the current directory without changing the caller's variables, functions, or directory. The gem also installs a standalone `kwsh` executable using the same native interpreter, without loading the coding agent:
|
|
209
|
+
|
|
210
|
+
```sh
|
|
211
|
+
kwsh scripts/check.kwsh README.md
|
|
212
|
+
kwsh -c 'printf "%s\n" "$1"' example argument
|
|
213
|
+
kwsh -n scripts/check.kwsh # syntax check without execution
|
|
214
|
+
printf 'printf hello\n' | kwsh -s
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
Standalone kwsh accepts inherited file descriptors 3–9 as well as standard input, output, and error. For example, from a parent shell:
|
|
218
|
+
|
|
219
|
+
```sh
|
|
220
|
+
kwsh -c 'cat <&3; printf "done\n" >&9' 3<input.txt 9>status.txt
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
Inherited descriptors support duplication, persistent `exec` redirection, and explicit closing. They reach child commands, native scripts, and executable-text fallback. The maximum supported shell redirection descriptor is 9. Discovery happens only at the standalone executable boundary; embedded runtimes and hosted `/shell` never discover Kward's private sockets or other open handles. Caller-supplied runtime descriptors remain borrowed unless ownership is explicitly transferred. This does not change RPC/Pan shell capabilities or sandbox policy.
|
|
224
|
+
|
|
225
|
+
From a checkout, use `ruby exe/kwsh`. Standalone stdin processing leaves each command's input available to `read` and external programs; it does not read the entire input stream ahead of execution. The rich interactive composer remains a Kward `/shell` feature. The `kwsh` executable keeps its plain line-oriented prompt by default (`-i`, or automatically when reading from a terminal with stderr also attached). Use `kward shell` for the default non-modal editor.
|
|
226
|
+
|
|
227
|
+
Startup sets `PPID` to the shell's parent process ID and `OPTIND` to `1`, even if those variables were inherited with different values. Subshells and command substitutions retain the current values instead of reinitializing them. `OPTIND` is not exported by default.
|
|
228
|
+
|
|
229
|
+
Standalone startup preserves an inherited `PWD` when it names the current directory with an absolute pathname and has no `.` or `..` components, including valid symlink-based logical paths. Otherwise it uses the physical pathname (`pwd -P`). Valid inherited paths beyond `PATH_MAX` are also retained when the filesystem can resolve them; if permissions prevent determining the physical pathname, POSIX leaves the value unspecified. Hosted `/shell` continues to use its explicit workspace root rather than adopting inherited `PWD`.
|
|
230
|
+
|
|
231
|
+
For file execution, `$0` is the command-file operand. With `-c`, an explicit command name becomes `$0`; otherwise, and when reading stdin, `$0` comes from the executable invocation (for example, `exe/kwsh` when launched with `ruby exe/kwsh`), not a fixed `kwsh` string. A leading single `-` ends option processing and is ignored before selecting operands:
|
|
232
|
+
|
|
233
|
+
```sh
|
|
234
|
+
kwsh - scripts/check.kwsh README.md # read the file, not stdin
|
|
235
|
+
kwsh -c - 'printf "%s:%s\n" "$0" "$1"' check README.md
|
|
236
|
+
printf '%s\n' 'printf "%s\n" "$1"' | kwsh -s - README.md
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
A lone `kwsh -` still reads commands from stdin. Do not combine this leading `-` with `--`; POSIX leaves that combination undefined.
|
|
240
|
+
|
|
241
|
+
For a standalone interactive session:
|
|
242
|
+
|
|
243
|
+
```sh
|
|
244
|
+
kwsh -i
|
|
245
|
+
ENV="$HOME/.kwsh-env" kwsh -i
|
|
246
|
+
kwsh -ec 'printf "%s\n" "$1"' example argument
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
Interactive startup parameter-expands `ENV` and executes the named native file when it exists. Non-interactive invocations ignore `ENV`; startup loading is also disabled when real and effective user or group IDs differ. The separate `kwsh` executable uses `ENV` but does not automatically load `kwshrc`. `PS1` and `PS2` support parameter expansion; `PS1` then replaces `!` with the next history number and `!!` with a literal `!`. Trace prefixes parameter-expand `PS4` (default `+ `); command substitutions in startup path or prompt text are rejected. Errors leave the prompt usable, and input is read without consuming a following command's stdin. Shell options may be grouped and may follow `-c` or `-s`. Standalone command history, `fc`, and `set -o vi` line editing are available. Emacs editing is not implemented.
|
|
250
|
+
|
|
251
|
+
Executable text files without a shebang also run natively when invoked from kwsh:
|
|
252
|
+
|
|
253
|
+
```sh
|
|
254
|
+
cat >hello <<'EOF'
|
|
255
|
+
printf 'Hello, %s\n' "$1"
|
|
256
|
+
EOF
|
|
257
|
+
chmod +x hello
|
|
258
|
+
./hello captain
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
After the operating system reports an executable-format error (`ENOEXEC`), kwsh interprets the file in a fresh native shell environment. This also works through `PATH`, `command`, and `exec`; arguments, exported variables, the working directory, redirections, and umask are preserved. The command name is retained as `$0`. Files without executable permission still fail, and a bounded prefix check rejects NUL-containing or ELF-looking binaries. Unsupported syntax remains an error, never a reason to try Bash or `/bin/sh`. An explicit shebang continues to select its named interpreter.
|
|
262
|
+
|
|
263
|
+
### Supported syntax
|
|
264
|
+
|
|
265
|
+
- Comments, newlines, `;`, single/double quotes, dollar-single-quotes (`$'line\n'`), and backslash escaping.
|
|
266
|
+
- Assignments, `$name`, `${name}`, `$?`, `$$`, positional parameters, `set --`, and `shift`. Parameter operators support defaults, assignment, error checks, alternate values, lengths, and prefix/suffix pattern removal.
|
|
267
|
+
- `export` and `unset`; ordinary assignments stay private to kwsh unless exported. `NAME=value command` supplies a temporary environment.
|
|
268
|
+
- `&&`, `||`, `!`, concurrent pipelines, brace groups and `( commands )` subshells. Pipeline stages and subshells isolate state. Pipeline status comes from the last stage unless `set -o pipefail` is enabled.
|
|
269
|
+
- `if` / `elif` / `else`, `case`, `for`, `while`, `until`, functions, `return`, `exit`, and multilevel `break` / `continue` (for example, `break 2`).
|
|
270
|
+
- `<`, `>`, `>>`, `<>`, `>|`, here-documents (`<<` / `<<-`), descriptor duplication, and closing on descriptors 0–9. Redirections apply left to right. Their operands do not undergo field splitting or pathname expansion, so `file="two words"; printf hello >$file` writes one file. Unquoted here-documents remove backslash-newline continuations before recognizing the delimiter.
|
|
271
|
+
- Ordinary `*`, `?`, and bracket filename patterns, `~` / `~user/...` (also after assignment colons), and field splitting with default, custom, or empty `IFS`. Quote variables and use `"$@"` to preserve argument boundaries. `"$*"` joins arguments with the first character of `IFS` (a space when unset).
|
|
272
|
+
- `read [-r] [-d delimiter] variable...`, including EOF status, backslash continuation, and multiple destination variables.
|
|
273
|
+
- Persistent `cd`, `pwd`, aliases, and direct executable lookup through `PATH`. Utilities such as `printf`, `test` / `[`, `grep`, and `cat` come from the operating system.
|
|
274
|
+
|
|
275
|
+
### Handle defaults and process input
|
|
276
|
+
|
|
277
|
+
Use parameter operators to avoid repetitive tests:
|
|
278
|
+
|
|
279
|
+
```sh
|
|
280
|
+
output=${OUTPUT_DIR:-./build} # use a default when unset or empty
|
|
281
|
+
: "${MODE:=development}" # also assign the default
|
|
282
|
+
: "${PROJECT:?set PROJECT}" # stop this submission if PROJECT is missing
|
|
283
|
+
printf '%s\n' "${#PROJECT}" # character count
|
|
284
|
+
file=src/example.rb
|
|
285
|
+
printf '%s\n' "${file##*/}" # example.rb
|
|
286
|
+
printf '%s\n' "${file%.rb}" # src/example
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
The `-`, `=`, `?`, and `+` operators test whether a parameter is unset. Adding `:` also tests for an empty value. `${name:+word}` substitutes `word` only when the parameter is set and nonempty. Defaults and alternate values may contain nested parameter or arithmetic expansions; unused operands are not evaluated. `:=` can assign ordinary variables, not special or positional parameters. A `:?` error stops the current submission before its command runs, but leaves the interactive session usable.
|
|
290
|
+
|
|
291
|
+
For pattern removal, `#` / `%` remove the shortest matching prefix / suffix; `##` / `%%` remove the longest. Quote a wildcard **inside** the operator's operand to make it literal: `${file#'*/'}` does not remove a path component. Double-quoting the whole expansion preserves its result without disabling the pattern.
|
|
292
|
+
|
|
293
|
+
Read a file without losing spaces, backslashes, or its final unterminated line:
|
|
294
|
+
|
|
295
|
+
```sh
|
|
296
|
+
while IFS= read -r file || [ -n "$file" ]; do
|
|
297
|
+
case "$file" in
|
|
298
|
+
*.rb|*.rake) printf 'Ruby: %s\n' "$file" ;;
|
|
299
|
+
'') continue ;;
|
|
300
|
+
*) printf 'Other: %s\n' "$file" ;;
|
|
301
|
+
esac
|
|
302
|
+
done < files.txt
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
`case` takes the first matching clause. Patterns support `*`, `?`, bracket ranges, negation, and character classes such as `[[:digit:]]`; unlike filename expansion, these patterns can match slashes and leading dots. Quoted pattern characters are literal. An optional `(` before each pattern list and an empty clause body are accepted. POSIX.1-2024 `;&` executes the next clause without testing or expanding its patterns; `;;` stops the case. Bash `;;&` re-testing remains unsupported.
|
|
306
|
+
|
|
307
|
+
`read -r` preserves backslashes. Without `-r`, backslashes escape the next character and backslash-newline continues a logical line; on an interactive terminal, continuation lines are prompted with parameter-expanded `PS2`. `read` returns 0 after a newline, 1 at EOF (still assigning any partial line), and greater than 1 for an error. With several variables, the final variable gets the remaining unsplit text, with surrounding IFS whitespace removed, following POSIX.1-2024. `read -d delimiter` uses the first byte as the delimiter; an empty delimiter reads NUL-separated records. `-r` and `-d` may be combined. `read -a array` stores split fields in an indexed array; prompt and timeout read options remain unsupported.
|
|
308
|
+
|
|
309
|
+
New shell invocations initialize `IFS` to space, tab, and newline, ignoring an inherited value. Unset `IFS` uses the same defaults. Empty `IFS` disables splitting. Non-whitespace separators such as `:` preserve empty fields between adjacent separators. A prefix assignment such as `IFS= read -r line` applies only to that command; it does not replace the session's `IFS`. `read` consumes only its own logical line, leaving input for the next command. Use redirection or a pipe when asking the shell agent to run it; terminal-input commands should be prepared for you instead.
|
|
310
|
+
|
|
311
|
+
### Calculate with integer arithmetic
|
|
312
|
+
|
|
313
|
+
Use `$((expression))` to substitute a calculated integer:
|
|
314
|
+
|
|
315
|
+
```sh
|
|
316
|
+
echo $((5 + 2)) # 7
|
|
317
|
+
value=5
|
|
318
|
+
echo "Result: $((value + 2))" # Result: 7
|
|
319
|
+
value=$((value + 1)) # update a counter
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
Arithmetic supports arithmetic, comparison, logical and bitwise operators, shifts, the conditional `?:`, assignments and compound assignments, comma expressions, prefix/postfix `++` / `--`, and right-associative `**`. Decimal, octal (`010`), and hexadecimal (`0x10`) integers work. Variables can hold arithmetic expressions; cycles are errors, and those values are parsed only as arithmetic, never shell commands. Unset or empty variables count as zero unless `set -u` applies. Division truncates toward zero. Logical operators and conditionals evaluate only the selected operand.
|
|
323
|
+
|
|
324
|
+
Use `((expression))` as a command (zero means failure, nonzero means success), or `for ((init; condition; update)); do …; done` for a counter loop.
|
|
325
|
+
|
|
326
|
+
Prefer adjacent `))` for portable syntax. As a kwsh convenience, spaces or tabs may separate the final closing parentheses: `echo $((5 + 2) )` also prints `7`. This extension applies only to arithmetic delimiters; it does not rewrite literal text or allow other tokens or newlines between the closers. Single quotes and an escaped `$` keep the expression literal. Incomplete expressions can continue on the next input line.
|
|
327
|
+
|
|
328
|
+
Arithmetic has no fixed expression-byte limit. Long left-associative chains are evaluated iteratively, preserving operand order and short-circuiting. Leading zeros in integer spellings do not consume precision. Parser/evaluator recursion remains limited to 100 internal levels. Values are checked using Ruby `Integer#bit_length <= 4096`, corresponding to the range `-2**4096` through `2**4096 - 1`; intermediate operands/results must fit too. Division truncates toward zero, and overflow reports an error rather than wrapping. Shift counts must be between 0 and 4096; negative exponents are errors. This exceeds the POSIX signed-long minimum but is not Bash machine-integer behavior. The remaining depth quota is a separate non-conforming safety policy, not an arithmetic precision allowance. Arithmetic expansion accepts parameter operators, command substitutions, backticks, and nested arithmetic, for example `$(( $(printf 2) + $((3 + 1)) ))`. Shell substitutions expand once before integer evaluation; expanded values are never parsed as shell commands. Static expressions are syntax-checked without evaluation; expressions containing substitutions are validated after expansion at execution time. Arithmetic array references and substitutions in the Bash-style `((...))` command/loop forms remain unsupported. Evaluation never invokes Ruby `eval` or another shell.
|
|
329
|
+
|
|
330
|
+
### Capture output and connect programs
|
|
331
|
+
|
|
332
|
+
```sh
|
|
333
|
+
revision=$(git rev-parse --short HEAD)
|
|
334
|
+
summary="$(printf '%s' "$revision")"
|
|
335
|
+
cat <(printf 'generated input\n')
|
|
336
|
+
printf 'generated output\n' > >(cat)
|
|
337
|
+
|
|
338
|
+
cat <<EOF
|
|
339
|
+
Revision: $revision
|
|
340
|
+
EOF
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
Command substitutions (`$(...)` and legacy backticks) run native parsed programs in an isolated process. They remove trailing newlines, retain interior newlines, and respect surrounding quotes. Assignment-only commands report the last substitution's status. Capture is limited to 16 MiB; oversize output and NUL bytes are explicit errors, not silently truncated values. Substitution children are cleaned up on cancellation.
|
|
344
|
+
|
|
345
|
+
Process substitutions use inherited `/dev/fd` pipes, owned by the current simple command. Both `<(program)` and `>(program)` work on the supported Unix hosts. Endpoints are closed and children reaped at command completion. kwsh waits for these children before reporting completion, unlike Bash's often-asynchronous process-substitution completion. Do not store these descriptor paths for later commands. Process substitution outside simple commands is not yet supported.
|
|
346
|
+
|
|
347
|
+
Here-documents expand parameters, command substitutions and arithmetic unless the delimiter is quoted (`<<'EOF'`). `<<-` strips leading tabs, not spaces. Input is stored in an immediately unlinked temporary file, avoiding pipe-buffer deadlocks and persistent temporary content.
|
|
348
|
+
|
|
349
|
+
### Use arrays, conditions, and generated arguments
|
|
350
|
+
|
|
351
|
+
```sh
|
|
352
|
+
files=(README.md "notes with spaces.md")
|
|
353
|
+
files[4]=CHANGELOG.md
|
|
354
|
+
printf '%s\n' "${files[@]}" # retain each element's boundaries
|
|
355
|
+
printf 'Count: %s\n' "${#files[@]}"
|
|
356
|
+
|
|
357
|
+
declare -A metadata
|
|
358
|
+
metadata=([language]=Ruby [owner]="Kai Wood")
|
|
359
|
+
printf '%s\n' "${metadata[owner]}"
|
|
360
|
+
|
|
361
|
+
for ((i=0; i<2; i++)); do
|
|
362
|
+
[[ ${files[i]} == *.md ]] && printf '%s\n' "${files[i]}"
|
|
363
|
+
done
|
|
364
|
+
|
|
365
|
+
printf '%s\n' report-{draft,final}.{md,txt} item-{01..03}
|
|
366
|
+
shopt -s globstar
|
|
367
|
+
printf '%s\n' **/*.rb
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
Indexed arrays are sparse, accept arithmetic indices and negative indices relative to the greatest index, and expand in index order. Associative arrays require `declare -A`. Use `"${array[@]}"` for separate arguments, `"${array[*]}"` to join with IFS, and `${!array[@]}` for keys. `unset 'array[index]'` removes an element. Arrays remain private shell state, not environment strings. Declarations accept `declare -a/-A name=(...)` or separate declaration and assignment. `array+=(...)` appends elements, `array[index]+=text` appends to one value, and `read -a array` reads split fields. Functions can use `local words=(...)` for a local indexed array. Local associative arrays, namerefs, alternate associative key/value-list syntax, and array prefix environments are not implemented.
|
|
371
|
+
|
|
372
|
+
`[[ … ]]` avoids splitting and filesystem globbing. It supports string and numeric comparisons, common file tests, pattern matching with `==` / `!=`, parentheses, negation, and lazy `&&` / `||`. Quoting the pattern makes it literal. `=~` accepts regular expressions and sets indexed `BASH_REMATCH` captures. It uses Ruby's engine with a 100 ms timeout, so it is not an exact Bash/POSIX ERE implementation. Put Boolean operator boundaries around a regex operand in separate words.
|
|
373
|
+
|
|
374
|
+
Brace expansion runs before substitutions and only on unquoted source text. It supports nested choices and numeric/letter sequences, with a 4,096-word and 32-level bound. A variable containing `{a,b}` stays literal. Recursive globbing is opt-in with `shopt -s globstar`, as in Bash; `shopt -u globstar` disables it. Other `shopt` options are not implemented.
|
|
375
|
+
|
|
376
|
+
### Manage script state
|
|
377
|
+
|
|
378
|
+
- `. ./library.kwsh [args...]` (or `source ./library.kwsh [args...]`) executes a native library in the current shell. Supplied arguments temporarily replace the shell’s positional parameters. Paths with a slash resolve from the shell’s current directory if relative; bare names are searched on `PATH`. At the hosted `/shell` prompt, use `.` to execute code: top-level `source` there is a declarative config loader.
|
|
379
|
+
- Inside a function, `local name` or `local name=value` shadows a variable until the function returns. Called functions can see the local value; variables not declared local can still change in the enclosing shell. `local name=(...)` does the same for an indexed array. Other Bash `local` flags are not supported.
|
|
380
|
+
- `LINENO` reports the current source line, including commands in functions and sourced files. Explicitly assigning or unsetting it disables automatic tracking for that interpreter.
|
|
381
|
+
- `readonly name=value`, `unset -f function`, `command [-p] [-v|-V]`, and `getopts` operate on interpreter state.
|
|
382
|
+
- `which name` reports what kwsh would use. For example, if `kward` is an alias, `which kward` prints `kward: aliased to ...` instead of the shadowed executable. Options such as `-a` are passed to the external `which` utility, which looks up executables on `PATH`.
|
|
383
|
+
- Explicit `eval` uses the native parser, not Ruby evaluation or a system shell. Treat its argument as executable source, not data.
|
|
384
|
+
- `umask [-S] [--] [mask]` accepts octal and symbolic permissions, including copies (`g=u`) and sequential operations (`g=u-w`). Setting a mask prints nothing, even with `-S`; querying with `-S` prints reusable `u=...,g=...,o=...` permissions. `X` uses the original allowed execute bits; non-permission `s`/`t` bits are ignored. It affects redirected files and external children without changing the host process's lasting mask.
|
|
385
|
+
- `cd` and `pwd` support grouped `-L` / `-P` flags and `--` (the last `-L` or `-P` wins). `cd -P -e` returns 1 if the directory changes but its physical pathname cannot be determined; without `-e`, that reporting failure still returns 0. Other `cd -P -e` errors return greater than 1 and leave the directory unchanged; `cd` searches `CDPATH` for eligible relative directory operands. `command -pv` and `command -pV` use the system default utility path without changing the caller's `PATH`. `hash [utility...]` remembers locations, `hash -r` clears them, `type name...` describes command resolution (at least one name is required), and `times` reports shell/child CPU usage.
|
|
386
|
+
- `set` supports `-a`, `-b`, `-e`, `-f`, `-h`, `-m`, `-n`, `-u`, `-v`, `-x`, `-C`, their `+` inverses, named `-o` options, and `pipefail`. `set -n` checks standalone scripts without execution and is ignored by interactive `/shell`. `set -x` deliberately writes expanded commands and assignments (including assignment-only commands) to stderr after expansion and before execution; command stderr redirections also capture these traces. Do not enable it around secrets. Command substitution inherits `errexit`, following POSIX rather than Bash's default mode. `-v` echoes source as it is read; `-b` enables interactive job-completion notifications while waiting for input; `-h` remembers literal external commands when functions are defined. `set -` disables verbose and execution tracing.
|
|
387
|
+
|
|
388
|
+
Assignment and expansion errors, and errors from directly invoked special builtins, stop non-interactive scripts even without `set -e`. Their EXIT trap still runs. In interactive `/shell`, these errors stop the current submission but leave the session usable. Ordinary utility and compound-command redirection failures return a nonzero status without terminating the shell; `command` also suppresses a special builtin's special error-exit behavior. `set -e` adds exit-on-failure behavior while respecting conditional tests, negated pipelines, and non-final AND-OR commands.
|
|
389
|
+
|
|
390
|
+
### Limit a command's resource use
|
|
391
|
+
|
|
392
|
+
Use `ulimit` to inspect the current process limits or constrain a command and its descendants. Put temporary changes in a subshell so they do not affect later commands in the session:
|
|
393
|
+
|
|
394
|
+
```sh
|
|
395
|
+
ulimit -a # list soft limits, with resource names and units
|
|
396
|
+
ulimit -H -f # query the hard file-size limit
|
|
397
|
+
(ulimit -S -f 2048 && ./build-report) # cap each written file at 1 MiB
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
`ulimit [-H|-S] -a` lists all supported resources. `ulimit [-H|-S] [-c|-d|-f|-n|-s|-t|-v] [newlimit]` queries or sets one resource:
|
|
401
|
+
|
|
402
|
+
| Option | Resource | Unit |
|
|
403
|
+
| --- | --- | --- |
|
|
404
|
+
| `-c` | Core file size | 512 bytes |
|
|
405
|
+
| `-d` | Data segment size | 1024 bytes |
|
|
406
|
+
| `-f` (default) | File size | 512 bytes |
|
|
407
|
+
| `-n` | Open file descriptors | One greater than the maximum newly assigned descriptor number |
|
|
408
|
+
| `-s` | Stack size | 1024 bytes |
|
|
409
|
+
| `-t` | Per-process CPU time | Seconds |
|
|
410
|
+
| `-v` | Address space size | 1024 bytes |
|
|
411
|
+
|
|
412
|
+
Queries default to the soft limit and print a number or `unlimited`; `-H` selects the hard limit. Setting without `-H` or `-S` changes **both** limits. Use a nonnegative decimal number or `unlimited`; leading zeros are decimal. `--` and grouped flags are accepted. Invalid input, unsupported options, out-of-range numbers, and OS-rejected changes return nonzero with a diagnostic. Mutually exclusive selectors are rejected rather than applied in sequence. A failed `ulimit` is an ordinary utility failure, subject to the usual `set -e` rules.
|
|
413
|
+
|
|
414
|
+
**Lowering a hard limit can be irreversible.** Soft limits can only be raised up to the hard limit, and raising a hard limit requires OS permission. Limits apply immediately to the shell itself and are inherited across forks, external commands, native scripts, and `exec`, including native executable-text fallback. Existing children keep their previous limits. File-size limits constrain writing, not reading existing files. OS/platform policies determine enforcement; these are not wall-clock timeouts or substitutes for a sandbox. Very low memory, stack, or descriptor limits can prevent the interpreter or child programs from running; native exec also needs private backup descriptors at 32 or above.
|
|
415
|
+
|
|
416
|
+
In `/shell`, only its dedicated worker and subsequent descendants are affected—not the Kward agent or other tabs. Limits persist between submissions in that session. Embedded Ruby `Runtime`/`ScriptRunner` callers can query limits, but changing them requires an explicitly owned process (`process_owned: true`) or a forked shell environment. Never opt a shared application process into that contract. Standalone entrypoints and workers opt in automatically. There is no new RPC session API; sandboxed command tools may run standalone `kwsh` as before.
|
|
417
|
+
|
|
418
|
+
[POSIX.1-2024 `ulimit`](https://pubs.opengroup.org/onlinepubs/9799919799/utilities/ulimit.html) specifies all these options: only `-t` is XSI, while the rest moved into Base in Issue 8. Bash's additional resource options are not implemented. This OS interface does not remove the interpreter safety quotas listed below.
|
|
419
|
+
|
|
420
|
+
### Keep working after a directory rename
|
|
421
|
+
|
|
422
|
+
The active directory is retained by identity, not just its pathname. A rename does not redirect subsequent commands into a replacement directory at the old name:
|
|
423
|
+
|
|
424
|
+
```sh
|
|
425
|
+
cd build/staging
|
|
426
|
+
mv ../staging ../ready
|
|
427
|
+
printf 'done\n' >status.txt # writes in build/ready
|
|
428
|
+
pwd -P # reports the current physical pathname
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
External commands, subshells, native scripts, `. ./library`, relative redirections and globs continue using that directory. `$PWD` retains the shell's logical spelling until a later directory change; `pwd -L` falls back to physical reporting when that spelling no longer identifies the directory. Logical `cd missing/..` fails rather than silently cancelling the missing component, and non-directory or dangling-symlink components fail too.
|
|
432
|
+
|
|
433
|
+
If the current directory is removed, pathname reporting can fail, while external execution and `cd -P ..` can still work according to the filesystem's rules. Relative file opens and child directory entry use retained descriptors, without changing Kward's host-process directory. Physical name discovery uses macOS `F_GETPATH` or Linux `/proc/self/fd`; Linux needs `/proc` mounted for name-based operations. These changes do not bypass command sandboxing or expose private handles as shell descriptors.
|
|
434
|
+
|
|
435
|
+
### Run and control background work
|
|
436
|
+
|
|
437
|
+
```sh
|
|
438
|
+
sleep 2 & first=$!
|
|
439
|
+
sleep 1 & second=$!
|
|
440
|
+
jobs -l
|
|
441
|
+
wait "$second"
|
|
442
|
+
wait "$first"
|
|
443
|
+
printf 'Last status: %s\n' "$?"
|
|
444
|
+
```
|
|
445
|
+
|
|
446
|
+
`&` starts an isolated asynchronous AND-OR list, including pipelines. `$!` is its waitable leader PID. `wait` with no arguments collects all known jobs and returns zero; with operands it returns the last requested job's status. An unknown or already-collected PID returns 127. Termination by a signal returns `128 + signal number`. Completed statuses are retained until collected; there is a 1,024-job bound.
|
|
447
|
+
|
|
448
|
+
`jobs` accepts `-l`, `-p`, `-r`, and `-s`. Job selectors include `%1`, `%+` / `%%` (current), `%-` (previous), `%prefix`, and `%?substring`; ambiguous selectors error. `kill [-s signal | -SIGNAL] pid-or-job...` signals a process or an entire job group. Signal names are case-independent; numeric short forms such as `-15` are also accepted. `kill -l` lists signal names and translates numbers.
|
|
449
|
+
|
|
450
|
+
Job control is on by default in interactive sessions (`/shell`, `kward shell`, and `kwsh -i`); standalone scripts can enable it with `set -m`. Ctrl-Z stops a foreground job and returns terminal ownership to kwsh. Terminal modes are saved with the stopped job and restored on `fg`, including for programs that suspend themselves after entering raw mode. Use `bg %1` to continue it in the background, or `fg %1` to return it to the terminal. Without job control, asynchronous input defaults to `/dev/null` unless explicitly redirected.
|
|
451
|
+
|
|
452
|
+
Hosted jobs remain tab-owned: closing the shell kills its owned groups, including stopped jobs. A forked hosted scope waits for its own background work before reporting completion, keeping descendants owned; standalone scripts do not impose that host-lifecycle rule. In `/shell`, background terminal output is drained and discarded while the prompt is idle so logging cannot block a server after `bg`. Output written during another command can still mix with that command's output. Redirect long-running jobs to files when you need to retain logs, for example `rake docs:serve >docs-server.log 2>&1 &`. Script jobs are separate from Kward's tab-detached foreground-command feature.
|
|
453
|
+
|
|
454
|
+
### Handle signals and replace a script
|
|
455
|
+
|
|
456
|
+
```sh
|
|
457
|
+
trap 'printf "Finished with status %s\n" "$?"' EXIT
|
|
458
|
+
trap 'printf "Received a notification\n"' USR1
|
|
459
|
+
kill -USR1 $$
|
|
460
|
+
trap - USR1 # restore the original disposition
|
|
461
|
+
|
|
462
|
+
exec 3>report.log # retain a descriptor in shell state
|
|
463
|
+
printf '%s\n' ready >&3
|
|
464
|
+
exec 3>&-
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
`trap` accepts signal names (with or without `SIG`), numbers, and `EXIT` / `0`. An empty action ignores a signal; `-` resets it to the shell's default. Bare `trap` lists non-default actions, including inherited ignores. `trap -p [--] [signals...]` also reports defaults, so saved output can undo traps added later:
|
|
468
|
+
|
|
469
|
+
```sh
|
|
470
|
+
saved=$(trap -p)
|
|
471
|
+
trap 'printf "Interrupted\n"' INT
|
|
472
|
+
# Run native commands with the temporary action.
|
|
473
|
+
eval "$saved"
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
Subshells and command substitutions reset caught execution actions immediately, but retain the parent's actions for trap inspection until a `trap` command supplies operands. This keeps `saved=$(trap -p)` useful without running the parent's handlers in the child. Non-interactive shells cannot catch or reset signals ignored on entry; interactive shells can override them. Invalid signal names return a nonzero status with a diagnostic, without aborting the rest of a script.
|
|
477
|
+
|
|
478
|
+
Actions execute as native source at interpreter safe points, preserving the interrupted `$?` unless they explicitly exit. Trapped signals interrupt the `wait` builtin; the action sees `128 + signal number` and runs before an `errexit` exit. When waiting for an ordinary foreground command, actions run after that command finishes. `EXIT` runs once on normal completion, explicit exit, or `errexit`. `KILL` and `STOP` cannot be caught or ignored; default resets are harmless. Ruby reserves `ILL`, `FPE`, `BUS`, `SEGV`, and `VTALRM`: kwsh can report their default dispositions but cannot install actions for them. This remains a conformance limitation.
|
|
479
|
+
|
|
480
|
+
Standalone interactive kwsh ignores `TERM` and `QUIT` by default. It also ignores `TTIN`, `TTOU`, and `TSTP` while monitoring jobs (and chooses to keep ignoring them with monitoring disabled). `INT` discards unfinished prompt input; while executing a command, an `INT` sent only to the shell does not interrupt that command. Terminal-generated Ctrl+C normally targets the foreground job, whose signal status is returned to the prompt. These shell-only defaults are reset for child commands, native scripts, and executable-text fallback. Interactive kwsh does not pass a launcher’s ignored `TTIN`, `TTOU`, or `TSTP` dispositions on to jobs, so Ctrl+Z can still suspend them. An explicit `trap` to ignore a signal still applies to child commands.
|
|
481
|
+
|
|
482
|
+
In standalone `kwsh`, `exec program args...` uses direct `execve`: it preserves the PID, does not run an EXIT trap on success, and never falls back to `/bin/sh`. `exec -c` clears the child's environment; `-a name` selects `argv[0]`, `-l` prefixes it with `-`, and `--` ends options. Without a program, redirections persist.
|
|
483
|
+
|
|
484
|
+
A failed `exec` in standalone interactive kwsh reports status 127 (not found) or 126 (other execution failure) and accepts a fresh submission. The failed submission may be abandoned. Successful redirections on that `exec` remain in effect, including input for the next submission; save descriptors first if you intend to restore them:
|
|
485
|
+
|
|
486
|
+
```sh
|
|
487
|
+
exec 8>&1 9>&2
|
|
488
|
+
exec ./missing >attempt.log 2>attempt.err
|
|
489
|
+
printf 'status=%s\n' "$?" # still writes to attempt.log
|
|
490
|
+
exec 1>&8 2>&9 # restore output and diagnostics
|
|
491
|
+
```
|
|
492
|
+
|
|
493
|
+
The interpreter restores its internal descriptors, directory, signal handlers, and process mask after failed replacement. Closed standard descriptors may be backed by `/dev/null`, as POSIX permits, so a closed stderr does not break prompt rendering. Non-interactive exec failures still exit. Successful exec still replaces the process with the same PID, including native executable-text fallback.
|
|
494
|
+
|
|
495
|
+
Standalone startup performs one same-PID re-exec of the trusted Ruby binary to reserve descriptor slots 3–9 away from Ruby's private wake-up handles. The reservation handles are close-on-exec and are not shell descriptors; inherited user descriptors remain available through the explicit shell map. Ruby startup hooks are not rerun by this internal bootstrap. This is not used by hosted workers and does not change RPC/Pan capabilities or sandbox boundaries.
|
|
496
|
+
|
|
497
|
+
The TUI worker must retain its private control channel. Its hosted `exec` therefore runs the replacement program, reports final state, and ends the logical shell session rather than replacing the protocol process. Hosted child scopes also retain their supervisors so that `exec` cannot abandon background descendants. `USR2` is reserved for hosted shutdown, omitted from that worker's trap listings, and cannot be trapped there; standalone scripts may trap it normally. Closing a tab is forced host cleanup, not a normal EXIT-trap invocation.
|
|
498
|
+
|
|
499
|
+
### Read aliases and scripts in order
|
|
500
|
+
|
|
501
|
+
```sh
|
|
502
|
+
alias say='printf "%s\n"'
|
|
503
|
+
say ready
|
|
504
|
+
alias dispatch='say ' # trailing blank enables alias expansion of the next word
|
|
505
|
+
alias greeting=hello
|
|
506
|
+
dispatch greeting
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
Native aliases expand unquoted command tokens while parsing, before parameter expansion. They may contain operators, refer to other aliases, or shadow builtins; cycles stop at the already-expanded name. Quoted names and names obtained from variables are not expanded. Define aliases in a separate complete input unit before using them: an alias change does not alter commands already parsed on the same line or in a function body. Replacement text shares the input lexer, so quotes and here-document bodies can cross alias boundaries. Expansion is bounded to 100 nested aliases, 65,536 replacement tokens, and 1 MiB of replacement source per parsed input unit.
|
|
510
|
+
|
|
511
|
+
Alias names accept letters, digits, and `!`, `%`, `,`, `-`, `@`, `_`, including numeric names such as `1`. Use `alias -- '-name=value'` for a name beginning with `-`. `alias` and `alias name` list quoted `name=value` entries, without an `alias ` prefix; prepend `alias -- ` when restoring a listed entry. `command -v` and `type` retain their separate command-description output.
|
|
512
|
+
|
|
513
|
+
Files, stdin, and explicit native source execute one complete input unit at a time. An error on a later line does not undo earlier commands. Stdin execution does not read ahead of a command that consumes its own input. Executable startup files and native `source` follow the same rules. The hosted `/shell` prompt’s declarative `source` command is separate.
|
|
514
|
+
|
|
515
|
+
### Select character and sorting rules
|
|
516
|
+
|
|
517
|
+
`LC_ALL` overrides category settings; otherwise `LC_CTYPE` and `LC_COLLATE` override `LANG`, defaulting to `C`. Installed libc locales control character counts, bracket classes/ranges, single- and multi-character collating symbols (`[[.a.]]`, `[[.ch.]]` where installed) and equivalence classes (`[[=a=]]`), string ordering, and filename sorting. For example:
|
|
518
|
+
|
|
519
|
+
```sh
|
|
520
|
+
value=é
|
|
521
|
+
LC_ALL=C
|
|
522
|
+
printf '%s\n' "${#value}" # 2 bytes
|
|
523
|
+
LC_ALL=C.UTF-8
|
|
524
|
+
printf '%s\n' "${#value}" # 1 character, if this locale is installed
|
|
525
|
+
```
|
|
526
|
+
|
|
527
|
+
Unavailable locales and unsupported encodings produce explicit errors. Locale changes use thread-local locale objects, not process-global `setlocale`. Path matching shares the bounded native string matcher; globstar does not descend through symlinked directories or hidden entries. A pathname expansion may visit at most 100,000 directory entries and 100 directory levels. These locale bindings target macOS and Linux.
|
|
528
|
+
|
|
529
|
+
Multi-character elements are shared by `case`, parameter trimming, and pathname expansion. For example, in an installed Czech locale, `[[.ch.]]` can match the two characters `ch`, and `[c[.ch.]]h` can match either `ch` or `chh`. Matching retains both paths rather than committing to the shorter element. Outside the POSIX locale, range behavior is unspecified by POSIX; kwsh uses the installed collation order. Available elements and primary equivalence classes depend on host libc/locale data. Multi-character symbol names containing glob metacharacters are rejected rather than passed to an unbounded libc wildcard matcher.
|
|
530
|
+
|
|
531
|
+
Collating-pattern matching uses an iterative, non-recursive search, capped at 1,000,000 transitions/prefix probes and 16 MiB of cumulative candidate bytes per match. Exceeding a bound is an error, not a partial match or silent omission. Ordinary C/POSIX patterns keep the single-character fast path.
|
|
532
|
+
|
|
533
|
+
### Resource limits and conformance
|
|
534
|
+
|
|
535
|
+
There is **no unrestricted/conforming standalone mode** yet. The native interpreter deliberately retains the safety policies below in both standalone kwsh and hosted `/shell`. Documenting a policy does not make it POSIX-conforming. In particular, passing the long-arithmetic regression does not close the remaining parser, expansion, or job-limit gaps. These are not configurable via an environment variable or a shell option.
|
|
536
|
+
|
|
537
|
+
The classification distinguishes **permitted choices** from **system constraints**, **extension policies**, and **additional safety policies affecting POSIX-required behavior**. Sources below are under `lib/kward/shell/`. The inventory covers native interpreter limits and the adjacent shell-host limits; external utilities and the OS can impose further constraints.
|
|
538
|
+
|
|
539
|
+
| Area / source | Enforced bound | Classification and disposition |
|
|
540
|
+
| --- | --- | --- |
|
|
541
|
+
| Arithmetic precision (`native_arithmetic.rb`) | `Integer#bit_length <= 4096`; every evaluated intermediate is checked | Permitted precision choice: SCL 2.6.4 allows a signed type larger than signed long. Overflow errors, no implicit wrap or floats. Significant-digit prechecks reject only values already too large for this precision. |
|
|
542
|
+
| Arithmetic domains (`native_arithmetic.rb`) | Shift count 0–4096; nonnegative exponent; exponentiation checked before allocating oversized results | Precision/domain choice and extension policy (`**`); preserves integer-only evaluation. |
|
|
543
|
+
| Arithmetic parser/evaluator depth (`native_arithmetic.rb`) | 100 internal recursive levels, including recursive variable-value evaluation; cycles rejected | Additional safety policy. Long flat binary chains no longer consume one recursive level per term. Deep otherwise-valid standard arithmetic still can fail. |
|
|
544
|
+
| Lexical expansion depth (`native_syntax.rb`) | 100 levels each for arithmetic, parameter, and command/backtick substitution paths | Additional safety policy affecting SCL 2.6; not justified by integer precision or OS limits. |
|
|
545
|
+
| Shell grammar depth (`native_syntax.rb`) | 100 internal parsing levels | Additional safety policy affecting standard nested compound commands. |
|
|
546
|
+
| Conditional-expression parsing (`native_syntax.rb`) | 100 recursive levels in the `[[ … ]]` parsers | Extension policy; not a portable POSIX conditional syntax. |
|
|
547
|
+
| Alias expansion (`native_syntax.rb`) | 100 expansion-provenance levels, 65,536 alias-derived tokens, 1,048,576 cumulative replacement bytes per parser instance | Additional safety policies. Same-name recursion suppression is a separate standard alias rule, not justification for these quotas. |
|
|
548
|
+
| Function, dot-source, and eval execution (`native_runtime.rb`, `native_builtins.rb`) | 100 levels each | Additional safety policies affecting otherwise-valid standard programs. |
|
|
549
|
+
| Command substitution (`native_substitution.rb`) | 16 MiB captured bytes before removing trailing newlines | Additional safety policy affecting SCL 2.6.3 in both modes. Output is rejected, not silently truncated; child cleanup remains mandatory. Process-substitution pipes do not use this capture buffer. |
|
|
550
|
+
| Multi-character collating matches (`native_pattern.rb`) | 1,000,000 accounted steps and 16 MiB cumulative candidate-byte work per match | Additional safety policies affecting SCL 2.14. These are work accounts, not a promise of a 16 MiB live-memory maximum. The matcher remains iterative; ordinary matching has no new fixed input-byte limit. |
|
|
551
|
+
| Pathname traversal (`native_glob.rb`) | 100,000 visited directory entries and 100 traversal levels | Additional safety policies for ordinary globs; also extension policies for `**`. Visited entries include nonmatches, so these are not merely result-count limits. |
|
|
552
|
+
| Job records (`native_jobs.rb`) | 1,024 active or retained jobs; new jobs fail until records are collected | Additional safety policy. This is not derived from `{CHILD_MAX}` and is not justified merely by POSIX's permission to forget old statuses. |
|
|
553
|
+
| PID operands (`native_jobs.rb`) | Absolute numeric value at most 2,147,483,647; at most 10 digits, plus optional minus | Numeric range follows the supported systems' signed `pid_t` ABI. The spelling-length restriction can reject excessive leading zeros and remains an additional policy. |
|
|
554
|
+
| Shell descriptors (`native_syntax.rb`, `native_runtime.rb`) | User redirections and duplication use descriptors 0–9 | Permitted implementation maximum: SCL 2.7 requires at least 0–9. Private backup descriptor floors (32) and startup reservations are allocation mechanics, not extra user descriptors. |
|
|
555
|
+
| Brace expansion (`native_braces.rb`) | 4,096 generated words, 32 recursive levels, 128 characters per numeric endpoint/step | Extension policies, not restrictions on a required POSIX expansion. |
|
|
556
|
+
| Indexed arrays (`native_arrays.rb`) | Index at most `2**31 - 1` | Extension policy; sparse storage does not make this a standard shell limit. |
|
|
557
|
+
| Regex condition (`native_condition.rb`) | 0.1-second Ruby regexp timeout for `[[ … =~ … ]]` | Extension policy. This is not a timeout on POSIX `case` patterns. |
|
|
558
|
+
| Executable-text detection (`native_process.rb`) | Inspect at most 4,096 bytes for binary-looking content before native ENOEXEC fallback | Permitted heuristic under SCL 2.9.1.6; **not** a script/line-length limit. |
|
|
559
|
+
| Physical directory reporting (`native_directory.rb`) | macOS F_GETPATH's 1,024-byte buffer; Linux procfs name discovery | System/API constraints; the retained directory descriptor is separate from successful pathname reporting. |
|
|
560
|
+
| Standalone prompt paste (`native_line_terminal.rb`) | 1 MiB per bracketed paste | Oversized pastes are discarded in full. This does not limit scripts or ordinary typed input. |
|
|
561
|
+
| Standalone vi alias macros (`native_vi.rb`) | 100 nested replacements and 1 MiB cumulative replacement bytes per edit line | Additional UP safety policy, not an OS limit. Does not impose a typed-line length ceiling; profile closure must account for this retained restriction. |
|
|
562
|
+
| Programmable completion (`native_programmable_completion.rb`) | 2 seconds, 256 candidates, 64 KiB of replies | Bounds an interactive Tab callback, not script execution. |
|
|
563
|
+
| Native process and file resources (`ulimit` in `native_builtins.rb`) | Inherited or explicitly set OS resource limits, argument/environment size, filesystem limits, available memory/storage, Ruby stack/runtime constraints | Underlying system constraints, not promises that every source fitting a kwsh quota can execute. No Ruby/system-shell eval fallback is introduced. |
|
|
564
|
+
| Hosted capture (`kwsh.rb`, `persistent_session.rb`) | Defaults: 1 MiB output and 300-second captured-command timeout; configurable through the existing shell configuration | Host policy only, unchanged. User-owned interactive commands do not get these capture/time limits. Normal model/RPC shell tools keep their own existing sandbox and cancellation policies. |
|
|
565
|
+
| Hosted context/preparation/history (`kwsh.rb`, `prompt_session.rb`) | 32,000-byte last-output context and prepared-command bound; default 1,000 history entries | Host/UI policies, not standalone shell-language limits. History remains configurable as documented below. |
|
|
566
|
+
| Hosted startup/cancellation (`persistent_session.rb`) | 5-second startup wait, 1-second interrupt/escalation waits, 0.2-second PTY draining window | Host lifecycle policies, unchanged; not standalone execution quotas. |
|
|
567
|
+
|
|
568
|
+
Fixed IO read chunks (4 KiB for hosted PTY reads, 16 KiB for substitution capture), polling intervals, the sigaction ABI buffer, `read`'s variable-count splitting, and escape widths are **not** cumulative program-size quotas. Dollar-single-quote hex escapes consume up to two digits and octal escapes up to three; longer hex forms are unspecified by POSIX, while `\u`/`\U` consume up to four/eight hex digits as extensions. Input files, here-documents, and ordinary source lines have no newly introduced byte ceiling; removing the arithmetic ceiling does not remove the explicitly listed nesting/work limits.
|
|
569
|
+
|
|
570
|
+
Authority: [POSIX shell language](https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html), especially 2.3, 2.6.3/2.6.4, 2.7, 2.9 and 2.14, and [sh input files](https://pubs.opengroup.org/onlinepubs/9799919799/utilities/sh.html). The open safety-policy gaps remain tracked separately from Base/UP/XSI feature coverage in `plan/POSIX_REQUIREMENTS.md`.
|
|
571
|
+
|
|
572
|
+
### Remaining compatibility limits
|
|
573
|
+
|
|
574
|
+
This is **not yet a fully POSIX- or Bash-conforming shell**. Additional builtin options, arithmetic array references, advanced array forms, and exact Bash/POSIX regular-expression semantics remain outside the implemented subset. `wait -n`, Bash pseudo-traps (`DEBUG`, `ERR`, `RETURN`), and emacs editing are not implemented. The XSI profile remains incomplete: `echo` delegates to the host utility (whose `-n` and backslash handling is not guaranteed to be XSI-conforming), and native diagnostics do not implement message-catalog lookup through `NLSPATH`. Use `printf` for portable output.
|
|
575
|
+
|
|
576
|
+
`capture`, `pty`, `clear`, and `kward edit` remain hosted prompt conveniences rather than scripting builtins. The hosted prompt also handles top-level `source` as a config loader; native programs treat `source` like `.`. Native aliases use read-time token expansion; the separate one-off `!` path retains its existing single command-prefix replacement.
|
|
577
|
+
|
|
578
|
+
The persistent shell and shell-agent API remain TUI-only. RPC/Pan still report that session capability unsupported. The standalone executable can be invoked as an ordinary external program through existing sandboxed command tools; it does not bypass their permission, cancellation, or sandbox boundaries.
|
|
579
|
+
|
|
580
|
+
### Compatibility roadmap
|
|
581
|
+
|
|
582
|
+
Native scripting is being extended in tested stages, targeting POSIX.1-2024 plus Bash-compatible behavior for the requested extensions. This is a roadmap, **not a claim that the remaining features already work**:
|
|
583
|
+
|
|
584
|
+
- [x] Parameter operators, `case`, `read -r/-d`, and custom `IFS`.
|
|
585
|
+
- [x] Subshells, nested command substitution, and bounded output capture.
|
|
586
|
+
- [x] Here-documents, `<>` / `>|`, and descriptors 0–9.
|
|
587
|
+
- [x] Native dot-sourcing, `getopts`, `readonly`, `command`, `eval`, and `umask`.
|
|
588
|
+
- [x] POSIX.1-2024 `ulimit` resource queries/settings, soft/hard limits, and owned-process inheritance/isolation.
|
|
589
|
+
- [x] Arithmetic operators, increment/decrement, exponentiation, and arithmetic loops, within documented bounds.
|
|
590
|
+
- [x] Initial indexed/associative arrays, `[[ … ]]`, process substitution, brace expansion, and opt-in globstar.
|
|
591
|
+
- [x] Standalone file/command/stdin modes, dollar-single-quotes, and the documented `set` options.
|
|
592
|
+
- [x] Signal/EXIT traps, asynchronous jobs, `wait`, terminal job control, and standalone/hosted `exec` lifecycle integration.
|
|
593
|
+
- [x] Named-user/assignment-context tildes, `$!`, read-time aliases, and incremental script-file execution.
|
|
594
|
+
- [x] Installed-locale character counts, single-character bracket classes/collation, native pathname matching, and locale sorting.
|
|
595
|
+
- [x] Native interpretation of executable text after `ENOEXEC`, including standalone `exec` and hosted job ownership.
|
|
596
|
+
- [x] Arithmetic-expansion substitutions, POSIX case fall-through, initial IFS, LINENO, and command-reporting precedence.
|
|
597
|
+
- [x] Shared-stream aliases, core builtin option combinations, command hashing, CDPATH, times, standalone interactive invocation, and guarded ENV startup.
|
|
598
|
+
- [x] Startup PPID/OPTIND, inherited logical PWD validation, invocation-derived `$0`, and leading `-` operand handling.
|
|
599
|
+
- [x] Bounded multi-character collation, including mixed brackets, ranges, trimming, and pathname matching.
|
|
600
|
+
- [x] Requirement-linked regression cases for quoting, splitting, redirections, continuations, errors, special builtins, invocation, jobs, and locale integration.
|
|
601
|
+
|
|
602
|
+
The remaining tracks are separate:
|
|
603
|
+
|
|
604
|
+
- **POSIX verification:** broader independent clause-by-clause audits and platform/locale matrices. The tests below are regression coverage, not certification of every POSIX requirement.
|
|
605
|
+
- **Optional utility/editing profiles:** XSI `echo` semantics and message catalogs remain open, alongside cross-platform verification of `ulimit -t`, `type`, numeric traps, and short-form `kill`. UP retains the vi macro-policy and platform gates. Emacs editing is neither implemented nor required for the UP milestone.
|
|
606
|
+
- **Bash extensions:** remaining array/conditional forms, arithmetic array references, `wait -n`, pseudo-traps, and exact Bash regex/machine-integer behavior.
|
|
607
|
+
- **Remaining shared safety policies:** the resource inventory above includes limits that also affect standalone POSIX behavior; these are open conformance gaps, not just hosted differences.
|
|
608
|
+
- **Intentional hosted differences:** reserved shutdown signals, supervised `exec`, tab-owned descendants, and host capture/time limits. Standalone interactive execution does not adopt hosted cleanup or reserve its shutdown signal.
|
|
609
|
+
|
|
610
|
+
### Verify native shell behavior
|
|
611
|
+
|
|
612
|
+
Run the focused shell suite without network services:
|
|
613
|
+
|
|
614
|
+
```sh
|
|
615
|
+
ruby -Itest -e '(Dir["test/test_native_shell*.rb"] + %w[test/test_persistent_shell_session.rb test/test_kwsh.rb test/test_shell_prompt.rb]).sort.each { |file| require_relative file }'
|
|
616
|
+
```
|
|
617
|
+
|
|
618
|
+
| Coverage | Tests |
|
|
619
|
+
| --- | --- |
|
|
620
|
+
| POSIX clause-linked behavior and cross-feature regressions | `test/test_native_shell_posix.rb` |
|
|
621
|
+
| Aliases, builtin options, startup identity checks, terminal invocation | `test/test_native_shell_invocation.rb` |
|
|
622
|
+
| Deterministic collation paths and work bounds | `test/test_native_shell_pattern.rb` |
|
|
623
|
+
| Installed-locale matching, trimming, globbing, and locale restoration | `test/test_native_shell_locale.rb` |
|
|
624
|
+
| Script modes, native execution, traps, descriptors, and process ownership | `test/test_native_shell.rb`, `test/test_native_shell_runner.rb`, `test/test_native_shell_descriptors.rb`, `test/test_native_shell_signals.rb`, `test/test_persistent_shell_session.rb` |
|
|
625
|
+
|
|
626
|
+
Installed multi-character collation tests require Czech or Slovak UTF-8 locale data and explicitly skip when unavailable. Deterministic matcher tests still run everywhere. Use POSIX.1-2024 as the authority when adding cases; Bash and the host `/bin/sh` can help investigate differences but are not conformance oracles. Do not turn implementation-defined or unspecified behavior into a purported universal requirement.
|
|
627
|
+
|
|
628
|
+
Language and state transitions remain native; implementing these features must not introduce a Bash or `/bin/sh` fallback. Hosted declarative `kwshrc` loading and ordinary model/RPC command isolation remain separate from executable standalone startup.
|
|
629
|
+
|
|
630
|
+
References: [POSIX Shell Command Language](https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html), [POSIX read](https://pubs.opengroup.org/onlinepubs/9799919799/utilities/read.html), [Bash parameter expansion](https://www.gnu.org/software/bash/manual/html_node/Shell-Parameter-Expansion.html), and [Bash arrays](https://www.gnu.org/software/bash/manual/html_node/Arrays.html), [POSIX wait](https://pubs.opengroup.org/onlinepubs/9799919799.2024edition/utilities/wait.html), and [POSIX job control](https://pubs.opengroup.org/onlinepubs/9799919799.2024edition/utilities/fg.html), and [Apple newlocale](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/newlocale.3.html).
|
|
631
|
+
|
|
632
|
+
### Edit a standalone command line with vi keys
|
|
633
|
+
|
|
634
|
+
Start `kward shell -o vi` or `kwsh -i -o vi`, or enter `set -o vi` at an existing standalone prompt. Each new line starts in insert mode. Press **Escape** for command mode, **i** to insert again, and **Enter** to execute. `set +o vi` returns to the default editor in `kward shell` and to plain terminal input in `kwsh`. The vi editor requires an ANSI-compatible terminal (`TERM=dumb` is rejected); non-terminal input remains line-oriented. Kward's hosted `/shell` composer has separate ownership and rejects native vi activation.
|
|
635
|
+
|
|
636
|
+
- Move with `h`, `l`, `0`, `^`, `$`, `|`, word motions `w/W`, `b/B`, `e/E`, and character searches `f/F`, `t/T`, `;`, `,`.
|
|
637
|
+
- Change with `a/A`, `i/I`, `R`, `c` plus a motion, `C`, `S`, `r`, or `~`. Delete with `d` plus a motion, `D`, `x`, or `X`; yank with `y` plus a motion or `Y`; put with `p/P`. Counts apply to the commands that accept them.
|
|
638
|
+
- `u` undoes the last change, `U` restores the edit line, and `.` repeats a change, including across submissions. A recalled history entry is copied before editing; the stored entry is not modified.
|
|
639
|
+
- `k`/`-` and `j`/`+` browse history; `[number]G` selects an entry. `/pattern` searches backward and `?pattern` forward using shell patterns; leading `^` anchors the pattern. Use `n/N` to repeat/reverse a search. `_` inserts the previous command's last bigword; a count selects another bigword.
|
|
640
|
+
- `\` completes the current bigword to its common pathname prefix, `*` inserts all pathname matches, and `=` lists shell-word expansions. Inserted pathnames are shell-escaped. **`=` is an explicit expansion action and can run command substitutions in the selected word**; ordinary redraw and pathname completion do not evaluate commands.
|
|
641
|
+
- `@a` plays editing keystrokes from alias `_a`. `#` comments and accepts the line. `v` edits the current line in external `vi`; `[number]v` selects a history entry. The same private temporary-file and failed-editor rules as `fc` apply.
|
|
642
|
+
|
|
643
|
+
Insert mode honors the terminal's configured erase, kill, interrupt, and EOF characters. Ctrl+W erases a word; Ctrl+V quotes the next character. Ctrl+C abandons the draft without adding it to history. Ctrl+L redraws in command mode. Long lines scroll horizontally rather than being truncated; control characters are displayed safely rather than emitted as terminal instructions. Raw mode is restored before execution, external editing, and cancellation, and input is not read ahead of the submitted command. Locale selection controls characters, case changes, and terminal cell widths. If editor setup fails (for example, an unavailable locale), kwsh reports the error and returns to plain input.
|
|
644
|
+
|
|
645
|
+
This is the native shell's vi command subset, not the full-screen Kward editor, an emacs mode, or a promise of every Vim/readline extension. Remaining resource policies and Linux verification are still tracked separately from POSIX conformance.
|
|
646
|
+
|
|
647
|
+
### Prompt options and mail
|
|
648
|
+
|
|
649
|
+
`set -o ignoreeof` prevents accidental terminal Ctrl+D exits; use `exit` explicitly, or disable it with `set +o ignoreeof`. With `-i` and `ignoreeof`, non-terminal EOF also waits for more input or an explicit exit (including an exit trap), without repeatedly printing prompts. Disable the option or issue `exit` when feeding a finite script to an interactive shell. `set -o nolog` is accepted and listed but intentionally has no effect, as permitted for this obsolete option.
|
|
650
|
+
|
|
651
|
+
Set `MAIL` to a mailbox pathname, or `MAILPATH` to colon-separated `path%message` entries. `MAILPATH` takes precedence even when empty; `\%` represents a literal percent in a pathname. Before primary prompts, kwsh checks for creation or modification since the previous check. `MAILCHECK` defaults to 600 seconds; `0` checks at every primary prompt. Invalid intervals use the default. The first check establishes a baseline. Optional messages are parameter-expanded, never evaluated as commands; the default is `you have mail`. These notifications belong to standalone prompts, not the hosted composer.
|
|
652
|
+
|
|
653
|
+
<a id="standalone-command-history"></a>
|
|
654
|
+
### Standalone command history
|
|
655
|
+
|
|
656
|
+
In `kwsh -i`, use `fc -l` to list recent commands, `fc -s old=new` to run the previous command with one replacement, or `fc -e vi` to edit and execute it. Numbers, negative offsets and command prefixes select entries; `fc -lnr 1 10` lists a reversed range without numbers. Replayed commands use the native interpreter, with the same assignments and redirections as `fc`.
|
|
657
|
+
|
|
658
|
+
History defaults to **512 entries in memory**. For persistence, set `HISTFILE` to a private file before the first prompt (for example `export HISTFILE="$HOME/.kwsh_history"` in `~/.kwshrc` for `kward shell`). `HISTSIZE` is a decimal entry count. Both are read once when history is first used; later changes do not reconfigure it. No file is created implicitly under `HOME`. History can contain secrets: do not enable persistence for sensitive sessions.
|
|
659
|
+
|
|
660
|
+
History files use private JSONL records with stable, increasing numbers and lossless storage of non-UTF-8 command bytes. The byte encoding is not encryption. New files are mode 0600; existing files must be regular, owned by the current user, mode 0600, and have one hard link. Symlinks and unsafe or inaccessible files fall back to memory without modifying their permissions. If a history update would exceed the current `ulimit -f`, that session keeps recording in memory and leaves the history file unchanged. Shells using the same file merge each new entry under a separate `.lock` file and replace the history file atomically. The default `kward shell` editor refreshes when you start browsing or searching from a fresh draft. Use separate files for independent history, and use the same `HISTSIZE` across shells sharing a file. Forked environments do not write their parent's history.
|
|
661
|
+
|
|
662
|
+
`FCEDIT` is parameter-expanded and names one executable (default `ed`), not shell source or a command plus arguments. Explicit `fc -e editor` overrides it. Edited commands live in a mode-0600 file inside a private temporary directory, removed on completion, failure, or cancellation. A failed/cancelled editor never executes its buffer or adds it to history. As with other temporary files, an uncatchable process kill can leave a private directory behind.
|
|
663
|
+
|
|
664
|
+
Native `fc` is standalone-only. Kward's hosted `/shell` retains its existing workspace history and composer ownership; RPC does not acquire a terminal editor or history-file API.
|
|
665
|
+
|
|
666
|
+
## Ask the hosted shell agent
|
|
93
667
|
|
|
94
668
|
While `/shell` is active, start a submitted line with `?` to ask the transient shell assistant:
|
|
95
669
|
|
|
@@ -112,7 +686,7 @@ For a suggestion or prepared command, the assistant uses `prepare_shell_command`
|
|
|
112
686
|
|
|
113
687
|
If you explicitly ask it to open an existing workspace file, the assistant uses `open_editor` to open Kward's integrated editor. Opening the editor does not modify or save the file.
|
|
114
688
|
|
|
115
|
-
The shell assistant cannot safely run commands that require terminal input. Ask it to prepare those commands instead. The local `/shell` session keeps one
|
|
689
|
+
The shell assistant cannot safely run commands that require terminal input. Ask it to prepare those commands instead. The local `/shell` session keeps one native kwsh interpreter process alive, so directory changes, variables, functions, aliases, and other shell state persist between commands. The one-off `!command` and `/capture` workflows remain separate. SSH remains available through the normal interactive PTY handoff, but shell-agent prompting resumes after that SSH session exits.
|
|
116
690
|
|
|
117
691
|
## Interactive and captured commands
|
|
118
692
|
|
|
@@ -167,6 +741,14 @@ Shell commands use a separate, workspace-scoped history rather than the normal c
|
|
|
167
741
|
|
|
168
742
|
Kward's tab shortcuts work at the shell prompt and while a shell command is running. Switching tabs detaches the running command instead of interrupting it; bounded output and completion state remain owned by the originating tab and are restored when you return. While detached, the command no longer receives terminal input. Explicit cancellation or shutdown still terminates detached work. Bounded output from shell-agent `?` turns is also retained in the tab's transient runtime view, so it is restored when you switch away and back without being added to session history. Ctrl+L clears this transient shell and shell-agent output.
|
|
169
743
|
|
|
744
|
+
### Protecting terminal shortcuts
|
|
745
|
+
|
|
746
|
+
With Ctrl tab bindings, Ctrl+1 through Ctrl+9 stay reserved for Kward, including while a command owns the screen. Kward keeps ownership of keyboard encoding: child Kitty keyboard push/pop/set and xterm `modifyOtherKeys` changes are filtered, and screen switches or terminal resets reassert Kward's encoding. Ordinary child input still uses the existing legacy-key translation; applications requiring their own enhanced keyboard protocol should run outside Kward.
|
|
747
|
+
|
|
748
|
+
On completion, cancellation, or tab detachment, Kward cancels unfinished terminal controls, leaves the alternate screen, and restores its keyboard, paste, mouse, focus, cursor-key, and rendering modes before redrawing. Fragmented key sequences are buffered within a fixed limit, and shortcuts inside bracketed paste are forwarded as pasted data rather than acted on.
|
|
749
|
+
|
|
750
|
+
This is best-effort protection, not a terminal sandbox. Ctrl+number still depends on your terminal sending distinguishable modified keys; Kward cannot recover modifiers that the terminal or a multiplexer discards. If your terminal cannot send these combinations, use the configurable Alt tab bindings instead. Interactive output remains trusted terminal access, including terminal-specific passthrough controls. These protections apply to local TUI handoffs (`/shell` and `!command`); RPC shell workers remain captured and noninteractive.
|
|
751
|
+
|
|
170
752
|
## Completion
|
|
171
753
|
|
|
172
754
|
Press Tab in `/shell` to complete:
|
|
@@ -210,7 +792,8 @@ The persistent `/shell` process handles these commands in-session so their state
|
|
|
210
792
|
| `cd [dir]` | Change the shell directory. Supports `cd`, `cd -`, and relative paths. |
|
|
211
793
|
| `pwd` | Print the shell directory. |
|
|
212
794
|
| `export KEY[=value]` | Set an environment variable. `export` and `export -p` list variables. |
|
|
213
|
-
| `source <file>`
|
|
795
|
+
| `source <file>` | Parse and apply aliases and exports from an rc file immediately. |
|
|
796
|
+
| `. <file> [args...]` | Execute a native script in the current shell. |
|
|
214
797
|
| `unset KEY` | Remove an environment variable. |
|
|
215
798
|
| `alias [name]` | List, inspect, or create aliases. |
|
|
216
799
|
| `unalias name` / `unalias -a` | Remove aliases. |
|
|
@@ -219,30 +802,59 @@ The persistent `/shell` process handles these commands in-session so their state
|
|
|
219
802
|
| `clear` | Clear the visible transcript. |
|
|
220
803
|
| `exit` / `logout` | Leave shell mode. |
|
|
221
804
|
|
|
222
|
-
|
|
805
|
+
Native aliases expand before builtin lookup. Prompt-only conveniences remain host-routed.
|
|
223
806
|
|
|
224
807
|
## Configure kwsh
|
|
225
808
|
|
|
226
|
-
|
|
809
|
+
The hosted `/shell` and interactive `kward shell` load these optional rc files in order:
|
|
227
810
|
|
|
228
811
|
```text
|
|
229
812
|
~/.kward/kwshrc
|
|
230
813
|
~/.kwshrc
|
|
231
814
|
```
|
|
232
815
|
|
|
233
|
-
When `KWARD_CONFIG_PATH` selects another main config file, Kward
|
|
816
|
+
When `KWARD_CONFIG_PATH` selects another main config file, Kward looks for the first `kwshrc` beside that file instead. The second file sees the first file’s changes and can override them. The separate `kwsh` executable does not automatically load either file.
|
|
817
|
+
|
|
818
|
+
### Standalone startup scripts
|
|
819
|
+
|
|
820
|
+
Interactive `kward shell` sources both files in the live native shell, including with `-i`. For example, put this in `~/.kwshrc`:
|
|
234
821
|
|
|
235
822
|
```sh
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
823
|
+
if [ -d "$HOME/bin" ]; then
|
|
824
|
+
export PATH="$HOME/bin:$PATH"
|
|
825
|
+
fi
|
|
826
|
+
|
|
827
|
+
work() { cd "$HOME/work"; }
|
|
828
|
+
alias gs='git status --short'
|
|
241
829
|
```
|
|
242
830
|
|
|
243
|
-
`
|
|
831
|
+
You can use functions, `if`, `eval`, and other supported native syntax, but not arbitrary Bash or Zsh configuration. Only put trusted code in these files: commands run with your privileges and can change files or exit the shell. A syntax error stops that startup file, not the interactive shell; earlier commands are not undone. Startup files are skipped when the real and effective user or group IDs differ. Kward’s main JSON config is not parsed until you ask the shell agent a `?` question.
|
|
244
832
|
|
|
245
|
-
|
|
833
|
+
To include a file, use `source "$HOME/.kward/kwsh-aliases"` or the POSIX spelling `. "$HOME/.kward/kwsh-aliases"`. If you used `source extra.rc` to load a file beside your rc, update it to an explicit path: native `source` searches `PATH` for a bare filename, and `source ./extra.rc` uses the current directory, not the rc file’s directory.
|
|
834
|
+
|
|
835
|
+
If you set `ENV` before launching `kward shell`, it selects a separate startup file that runs after both rc files. Assigning `ENV` inside `kwshrc` does not select that file. Non-interactive invocations load neither `kwshrc` nor `ENV`.
|
|
836
|
+
|
|
837
|
+
### Initialize rbenv
|
|
838
|
+
|
|
839
|
+
If `rbenv` is already on the launch `PATH`, add this to `~/.kwshrc`:
|
|
840
|
+
|
|
841
|
+
```sh
|
|
842
|
+
if command -v rbenv >/dev/null 2>&1; then
|
|
843
|
+
eval "$(rbenv init - bash)"
|
|
844
|
+
fi
|
|
845
|
+
```
|
|
846
|
+
|
|
847
|
+
If you launch from a GUI and the command is missing, add your Homebrew `bin` directory (typically `/opt/homebrew/bin` on Apple Silicon) to `PATH` before this block. With rbenv 1.3.2, `rbenv shell` and `rbenv rehash` work through the generated wrapper. In the default editor, try `rbenv shell ` and press **Tab** to complete installed versions. If you only want the shims, put `export PATH="${RBENV_ROOT:-$HOME/.rbenv}/shims:$PATH"` in your rc file instead.
|
|
848
|
+
|
|
849
|
+
This is not general support for `bash-completion`. Native `complete -F function command` registers a function, and `compgen -W wordlist -- prefix` filters a quote-aware list without evaluating it as shell source. The callback receives literal command words through the cursor in `COMP_WORDS`, the current index in `COMP_CWORD`, and returns candidates in `COMPREPLY`. Only the default standalone editor invokes these callbacks. A callback runs with your privileges in a separate process without terminal input; shell-state changes don’t persist, but filesystem or network effects can. Register only trusted functions. **Ctrl+C** cancels a running callback without clearing the draft, and `history pause` disables callbacks entirely. Tab never evaluates the draft itself.
|
|
850
|
+
|
|
851
|
+
### Hosted shell configuration
|
|
852
|
+
|
|
853
|
+
The hosted `/shell` and leading-`!` commands still read only declarative `alias`, `export`, and `source` (or `.`) directives from rc files. The loader does not execute code or follow shell conditionals. In these declarative files, an include is relative to the file containing it. At the `/shell` prompt, top-level `source <file>` applies declarative settings using the shell’s working directory; use `. ./file` when you want to execute a script instead. If you share rc files with the hosted shell, keep them declarative and use an inherited `ENV` for standalone-only code.
|
|
854
|
+
|
|
855
|
+
### Shell-agent model
|
|
856
|
+
|
|
857
|
+
By default, the hosted `/shell` agent uses the active conversation's provider, model, and reasoning effort. The standalone `kward shell` agent starts from Kward's configured selection. To override either default, set `shell.agent` in the main JSON file:
|
|
246
858
|
|
|
247
859
|
```json
|
|
248
860
|
{
|
|
@@ -256,9 +868,9 @@ The transient shell assistant normally follows the active conversation's model a
|
|
|
256
868
|
}
|
|
257
869
|
```
|
|
258
870
|
|
|
259
|
-
The optional `provider` uses the lowercase configuration IDs listed in [Model providers](providers.md).
|
|
871
|
+
The optional `provider` uses the lowercase configuration IDs listed in [Model providers](providers.md). If you set an explicit provider but omit the model or reasoning effort, Kward uses that provider's defaults for the omitted settings.
|
|
260
872
|
|
|
261
|
-
|
|
873
|
+
To override those settings, export the following variables before launching Kward:
|
|
262
874
|
|
|
263
875
|
```sh
|
|
264
876
|
export KWSH_PROVIDER="openrouter"
|
|
@@ -270,22 +882,24 @@ Environment variables take precedence over the JSON settings, and empty values a
|
|
|
270
882
|
|
|
271
883
|
### Runtime defaults
|
|
272
884
|
|
|
273
|
-
These
|
|
885
|
+
These defaults apply to the hosted shell and its one-off command path. They are built into kwsh and are not configurable through rc files:
|
|
274
886
|
|
|
275
887
|
| Setting | Default | What it does |
|
|
276
888
|
| --- | --- | --- |
|
|
277
|
-
| `shell` | `/bin/sh` |
|
|
889
|
+
| `shell` | `/bin/sh` | Executable for the separate one-off command path; persistent `/shell` now uses the native kwsh interpreter. |
|
|
278
890
|
| `timeout_seconds` | `300` | Maximum runtime for one captured or shell-agent command. |
|
|
279
891
|
| `max_output_bytes` | `1048576` | Maximum output retained for one captured or shell-agent command. |
|
|
280
892
|
| `history_limit` | `1000` | Maximum shell-history entries per workspace. |
|
|
281
893
|
|
|
282
|
-
Invalid or relative `shell` paths fall back to `/bin/sh`.
|
|
894
|
+
Invalid or relative `shell` paths fall back to `/bin/sh`. The hosted timeout and output limit apply to `capture` inside `/shell` and commands run by the hosted shell agent, not user-owned interactive commands or the separate `/capture` slash command.
|
|
895
|
+
|
|
896
|
+
In standalone `kward shell`, agent-run commands also default to a 300-second timeout. Their live terminal output has no byte cap; only the separate, filtered copy sent to the model is capped at 32,000 bytes.
|
|
283
897
|
|
|
284
898
|
### Environment
|
|
285
899
|
|
|
286
900
|
`export` values from rc files are applied when `/shell` starts and are also available to leading-`!` commands. Keys must be valid environment-variable names; invalid keys are ignored. Values support shell quoting and simple `$VAR`/`${VAR}` expansion.
|
|
287
901
|
|
|
288
|
-
Kward
|
|
902
|
+
For `/shell` and leading-`!` commands, Kward supplies these terminal defaults:
|
|
289
903
|
|
|
290
904
|
```sh
|
|
291
905
|
export CLICOLOR=1
|
|
@@ -293,13 +907,15 @@ export COLORTERM=truecolor
|
|
|
293
907
|
export TERM=xterm-256color # only when TERM is missing or dumb
|
|
294
908
|
```
|
|
295
909
|
|
|
296
|
-
|
|
910
|
+
On a real terminal, interactive `kward shell` also defaults to `CLICOLOR=1` and `COLORTERM=truecolor` when color isn't disabled, and uses `TERM=xterm-256color` if `TERM` is unset or empty. It preserves `TERM=dumb` for plain input. Startup scripts can override these defaults. Noninteractive invocations and the separate `kwsh` executable don't add them.
|
|
911
|
+
|
|
912
|
+
These defaults don't force color. Set `FORCE_COLOR`, `CLICOLOR_FORCE`, or a command-specific option such as `--color=always` when needed.
|
|
297
913
|
|
|
298
914
|
When rbenv is available, Kward adds its shims and bin directories to `PATH` and supplies `RBENV_ROOT` if it was missing before starting `/shell`. The configured interactive shell may also load its normal startup files.
|
|
299
915
|
|
|
300
916
|
### Aliases
|
|
301
917
|
|
|
302
|
-
|
|
918
|
+
Native aliases replace unquoted command tokens at read time:
|
|
303
919
|
|
|
304
920
|
```sh
|
|
305
921
|
alias ll='ls -la'
|
|
@@ -318,7 +934,7 @@ Configured aliases work inside `/shell` and after `!`. Aliases created with the
|
|
|
318
934
|
|
|
319
935
|
For compatibility with older configs, Kward removes a leading `pty` or `capture` mode marker when a configured alias is invoked through `!`, because `!command` is always interactive.
|
|
320
936
|
|
|
321
|
-
|
|
937
|
+
Native aliases may expand other aliases, with cycle detection; they are not shell functions. The separate `!command` path still performs only one command-prefix replacement. Use `alias` to list aliases, `alias name=value` to create one for subsequent complete input units, and `unalias` to remove one.
|
|
322
938
|
|
|
323
939
|
## Terminal output and safety
|
|
324
940
|
|