@sema-agent/server 1.196.0 → 1.197.0

package/skills/keybindings-help.md

@@ -0,0 +1,294 @@
+---
+name: keybindings-help
+description: Use when the user wants to customize the interactive shell's keyboard shortcuts, rebind keys, add chord bindings, or modify the shell's keybindings.json. Examples: "rebind ctrl+s", "add a chord shortcut", "change the submit key", "customize keybindings".
+---
+
+# Keybindings Skill
+
+Create or modify the shell's user `keybindings.json` to customize keyboard shortcuts. By convention the file lives in the shell's user config directory; the exact location is shell/deployment-configurable - check your shell's docs or an existing file before writing.
+
+## CRITICAL: Read Before Write
+
+**Always read the existing `keybindings.json` first** (it may not exist yet). Merge changes with existing bindings — never replace the entire file.
+
+- Use **Edit** tool for modifications to existing files
+- Use **Write** tool only if the file does not exist yet
+
+## File Format
+
+```json
+{
+  "bindings": [
+    {
+      "context": "Chat",
+      "bindings": {
+        "ctrl+e": "chat:externalEditor"
+      }
+    }
+  ]
+}
+```
+
+If your shell distribution publishes a JSON schema for this file, include a `$schema` reference to it.
+
+## Keystroke Syntax
+
+**Modifiers** (combine with `+`):
+- `ctrl` (alias: `control`)
+- `alt` (aliases: `opt`, `option`) — note: `alt` and `meta` are identical in terminals
+- `shift`
+- `meta` (aliases: `cmd`, `command`)
+
+**Special keys**: `escape`/`esc`, `enter`/`return`, `tab`, `space`, `backspace`, `delete`, `up`, `down`, `left`, `right`
+
+**Chords**: Space-separated keystrokes, e.g. `ctrl+k ctrl+s` (1-second timeout between keystrokes)
+
+**Examples**: `ctrl+shift+p`, `alt+enter`, `ctrl+k ctrl+n`
+
+## Unbinding Default Shortcuts
+
+Set a key to `null` to remove its default binding:
+
+```json
+{
+  "context": "Chat",
+  "bindings": {
+    "ctrl+s": null
+  }
+}
+```
+
+## How User Bindings Interact with Defaults
+
+- User bindings are **additive** — they are appended after the default bindings
+- To **move** a binding to a different key: unbind the old key (`null`) AND add the new binding
+- A context only needs to appear in the user's file if they want to change something in that context
+
+## Common Patterns
+
+### Rebind a key
+To change the external editor shortcut from `ctrl+g` to `ctrl+e`:
+```json
+{
+  "context": "Chat",
+  "bindings": {
+    "ctrl+g": null,
+    "ctrl+e": "chat:externalEditor"
+  }
+}
+```
+
+### Add a chord binding
+```json
+{
+  "context": "Global",
+  "bindings": {
+    "ctrl+k ctrl+t": "app:toggleTodos"
+  }
+}
+```
+
+## Behavioral Rules
+
+1. Only include contexts the user wants to change (minimal overrides)
+2. Validate that actions and contexts are from the known lists below
+3. Warn the user proactively if they choose a key that conflicts with reserved shortcuts or common tools like tmux (`ctrl+b`) and screen (`ctrl+a`)
+4. When adding a new binding for an existing action, the new binding is additive (existing default still works unless explicitly unbound)
+5. To fully replace a default binding, unbind the old key AND add the new one
+
+## Validation
+
+The shell validates `keybindings.json` when it loads; warnings go to the debug log. After editing the file, re-check it against the rules below and fix anything that matches.
+
+### Common Issues and Fixes
+
+| Issue | Cause | Fix |
+| --- | --- | --- |
+| `keybindings.json must have a "bindings" array` | Missing wrapper object | Wrap bindings in `{ "bindings": [...] }` |
+| `"bindings" must be an array` | `bindings` is not an array | Set `"bindings"` to an array: `[{ context: ..., bindings: ... }]` |
+| `Unknown context "X"` | Typo or invalid context name | Use exact context names from the Available Contexts table |
+| `Duplicate key "X" in Y bindings` | Same key defined twice in one context | Remove the duplicate; JSON uses only the last value |
+| `"X" may not work: ...` | Key conflicts with terminal/OS reserved shortcut | Choose a different key (see Reserved Shortcuts section) |
+| `Could not parse keystroke "X"` | Invalid key syntax | Check syntax: use `+` between modifiers, valid key names |
+| `Invalid action for "X"` | Action value is not a string or null | Actions must be strings like `"app:help"` or `null` to unbind |
+
+### Example validation warnings (debug log)
+
+```
+[keybindings] Found 2 validation issue(s)
+[keybindings] [error] Unknown context "chat" — Valid contexts: Global, Chat, Autocomplete, ...
+[keybindings] [warning] "ctrl+c" may not work: Terminal interrupt (SIGINT)
+```
+
+**Errors** prevent bindings from working and must be fixed. **Warnings** indicate potential conflicts but the binding may still work.
+
+## Reserved Shortcuts
+
+### Non-rebindable (errors)
+- `ctrl+c` — Cannot be rebound - used for interrupt/exit (hardcoded)
+- `ctrl+d` — Cannot be rebound - used for exit (hardcoded)
+- `ctrl+m` — Cannot be rebound - identical to Enter in terminals (both send CR)
+- `capslock` — Caps Lock is not delivered to terminal applications
+
+### Terminal reserved (errors/warnings)
+- `ctrl+z` — Unix process suspend (SIGTSTP) (may conflict)
+- `ctrl+\` — Terminal quit signal (SIGQUIT) (will not work)
+
+### macOS reserved (errors)
+- `cmd+c` — macOS system copy
+- `cmd+v` — macOS system paste
+- `cmd+x` — macOS system cut
+- `cmd+q` — macOS quit application
+- `cmd+w` — macOS close window/tab
+- `cmd+tab` — macOS app switcher
+- `cmd+space` — macOS Spotlight
+
+## Available Contexts
+
+| Context | Description |
+| --- | --- |
+| `Global` | Active everywhere, regardless of focus |
+| `Chat` | When the chat input is focused |
+| `Autocomplete` | When autocomplete menu is visible |
+| `Confirmation` | When a confirmation/permission dialog is shown |
+| `Help` | When the help overlay is open |
+| `Transcript` | When viewing the transcript |
+| `HistorySearch` | When searching command history (ctrl+r) |
+| `Task` | When a task/agent is running in the foreground |
+| `ThemePicker` | When the theme picker is open |
+| `Settings` | When the settings menu is open |
+| `Tabs` | When tab navigation is active |
+| `Attachments` | When navigating image attachments in a select dialog |
+| `Footer` | When footer indicators are focused |
+| `MessageSelector` | When the message selector (rewind) is open |
+| `DiffDialog` | When the diff dialog is open |
+| `DiffPanel` | When the diff sidebar panel is open |
+| `ModelPicker` | When the model picker is open |
+| `Select` | When a select/list component is focused |
+| `Plugin` | When the plugin dialog is open |
+| `Scroll` | When a scrollable view is focused (fullscreen layout) |
+
+## Available Actions
+
+| Action | Default Key(s) | Context |
+| --- | --- | --- |
+| `app:interrupt` | `ctrl+c` | Global |
+| `app:exit` | `ctrl+d` | Global |
+| `app:toggleTodos` | `ctrl+t` | Global |
+| `app:toggleTranscript` | `ctrl+o` | Global |
+| `app:toggleBrief` | `ctrl+shift+b` | Global |
+| `app:toggleReplTab` | (none) | Global |
+| `app:toggleDiffNoiseFilter` | (none) | Global |
+| `app:diffFileListUp` | `ctrl+up`, `meta+up` | Global |
+| `app:diffFileListDown` | `ctrl+down`, `meta+down` | Global |
+| `app:toggleDiffPreSession` | (none) | Global |
+| `app:cycleDiffBase` | (none) | Global |
+| `app:toggleTerminal` | (none) | Global |
+| `app:redraw` | (none) | Global |
+| `app:openArtifact` | `ctrl+]` | Global |
+| `history:search` | `ctrl+r` | Global |
+| `history:previous` | `up` | Chat |
+| `history:next` | `down` | Chat |
+| `chat:cancel` | `escape` | Chat |
+| `chat:killAgents` | `ctrl+x ctrl+k` | Chat |
+| `chat:cycleMode` | `shift+tab` | Chat |
+| `chat:modelPicker` | `meta+p` | Chat |
+| `chat:fastMode` | `meta+o` | Chat |
+| `chat:thinkingToggle` | `meta+t` | Chat |
+| `chat:workflowKeywordToggle` | `meta+w` | Chat |
+| `chat:submit` | `enter` | Chat |
+| `chat:newline` | `ctrl+j` | Chat |
+| `chat:undo` | `ctrl+_`, `ctrl+-`, `ctrl+shift+-`, `ctrl+shift+_` | Chat |
+| `chat:externalEditor` | `ctrl+x ctrl+e`, `ctrl+g` | Chat |
+| `chat:stash` | `ctrl+s` | Chat |
+| `chat:imagePaste` | `ctrl+v` | Chat |
+| `chat:clearInput` | `ctrl+l` | Chat |
+| `chat:clearScreen` | `cmd+k` | Chat |
+| `autocomplete:accept` | `tab` | Autocomplete |
+| `autocomplete:dismiss` | `escape` | Autocomplete |
+| `autocomplete:previous` | `up` | Autocomplete |
+| `autocomplete:next` | `down` | Autocomplete |
+| `confirm:yes` | `y`, `enter` | Confirmation |
+| `confirm:no` | `escape`, `n`, `escape` | Settings |
+| `confirm:previous` | `up` | Confirmation |
+| `confirm:next` | `down` | Confirmation |
+| `confirm:nextField` | `tab` | Confirmation |
+| `confirm:previousField` | (none) | Confirmation |
+| `confirm:cycleMode` | `shift+tab` | Confirmation |
+| `confirm:toggle` | `space` | Confirmation |
+| `confirm:toggleExplanation` | `ctrl+e` | Confirmation |
+| `tabs:next` | `tab`, `right` | Tabs |
+| `tabs:previous` | `shift+tab`, `left` | Tabs |
+| `transcript:toggleShowAll` | `ctrl+e` | Transcript |
+| `transcript:exit` | `ctrl+c`, `escape`, `q` | Transcript |
+| `historySearch:next` | `ctrl+r` | HistorySearch |
+| `historySearch:accept` | `escape`, `tab` | HistorySearch |
+| `historySearch:cancel` | `ctrl+c` | HistorySearch |
+| `historySearch:execute` | `enter` | HistorySearch |
+| `historySearch:cycleScope` | `ctrl+s` | HistorySearch |
+| `task:background` | `ctrl+x ctrl+b`, `ctrl+b` | Task |
+| `theme:toggleSyntaxHighlighting` | `ctrl+t` | ThemePicker |
+| `theme:editCustom` | `ctrl+e` | ThemePicker |
+| `help:dismiss` | `escape` | Help |
+| `attachments:next` | `right` | Attachments |
+| `attachments:previous` | `left` | Attachments |
+| `attachments:remove` | `backspace`, `delete` | Attachments |
+| `attachments:exit` | `down`, `escape` | Attachments |
+| `footer:up` | `up`, `ctrl+p` | Footer |
+| `footer:down` | `down`, `ctrl+n` | Footer |
+| `footer:next` | `right` | Footer |
+| `footer:previous` | `left` | Footer |
+| `footer:openSelected` | `enter` | Footer |
+| `footer:clearSelection` | `escape` | Footer |
+| `footer:close` | `x` | Footer |
+| `messageSelector:up` | `up`, `k`, `ctrl+p` | MessageSelector |
+| `messageSelector:down` | `down`, `j`, `ctrl+n` | MessageSelector |
+| `messageSelector:top` | `ctrl+up`, `shift+up`, `meta+up`, `shift+k` | MessageSelector |
+| `messageSelector:bottom` | `ctrl+down`, `shift+down`, `meta+down`, `shift+j` | MessageSelector |
+| `messageSelector:select` | `enter` | MessageSelector |
+| `diff:dismiss` | `escape` | DiffDialog |
+| `diff:previousSource` | `left` | DiffDialog |
+| `diff:nextSource` | `right` | DiffDialog |
+| `diff:back` | (none) | DiffDialog |
+| `diff:viewDetails` | `enter` | DiffDialog |
+| `diff:previousFile` | `up`, `k` | DiffDialog |
+| `diff:nextFile` | `down`, `j` | DiffDialog |
+| `modelPicker:decreaseEffort` | `left` | ModelPicker |
+| `modelPicker:increaseEffort` | `right` | ModelPicker |
+| `modelPicker:thisSessionOnly` | `s` | ModelPicker |
+| `select:next` | `down`, `j`, `ctrl+n`, `down`, `j`, `ctrl+n` | Settings |
+| `select:previous` | `up`, `k`, `ctrl+p`, `up`, `k`, `ctrl+p` | Settings |
+| `select:pageUp` | `pageup` | Select |
+| `select:pageDown` | `pagedown` | Select |
+| `select:first` | `home` | Select |
+| `select:last` | `end` | Select |
+| `select:accept` | `space`, `enter`, `enter` | Settings |
+| `select:cancel` | `escape` | Select |
+| `plugin:toggle` | `space` | Plugin |
+| `plugin:install` | `i` | Plugin |
+| `plugin:favorite` | `f` | Plugin |
+| `permission:toggleDebug` | (none) | Confirmation |
+| `settings:search` | `/` | Settings |
+| `settings:retry` | `r` | Settings |
+| `settings:periodDay` | `d` | Settings |
+| `settings:periodWeek` | `w` | Settings |
+| `settings:sortByTokens` | `t` | Settings |
+| `voice:pushToTalk` | `space` | Chat |
+| `scroll:pageUp` | `pageup`, `pageup` | Scroll |
+| `scroll:pageDown` | `pagedown`, `pagedown` | Scroll |
+| `scroll:lineUp` | `ctrl+p`, `k`, `up`, `wheelup` | Transcript |
+| `scroll:lineDown` | `ctrl+n`, `j`, `down`, `wheeldown` | Transcript |
+| `scroll:top` | `g`, `home`, `ctrl+home`, `g`, `home` | Transcript |
+| `scroll:bottom` | `shift+g`, `end`, `ctrl+end`, `shift+g`, `end` | Transcript |
+| `scroll:halfPageUp` | `ctrl+u`, `ctrl+u` | Settings |
+| `scroll:halfPageDown` | `ctrl+d`, `ctrl+d` | Settings |
+| `scroll:fullPageUp` | `ctrl+b`, `b`, `shift+space`, `b` | Transcript |
+| `scroll:fullPageDown` | `ctrl+f`, `space`, `space` | Transcript |
+| `selection:copy` | `ctrl+shift+c`, `cmd+c` | Scroll |
+| `selection:clear` | (none) | Unknown |
+| `selection:extendLeft` | `shift+left` | Scroll |
+| `selection:extendRight` | `shift+right` | Scroll |
+| `selection:extendUp` | `shift+up` | Scroll |
+| `selection:extendDown` | `shift+down` | Scroll |
+| `selection:extendLineStart` | `shift+home` | Scroll |
+| `selection:extendLineEnd` | `shift+end` | Scroll |

package/skills/loop.md

@@ -0,0 +1,50 @@
+---
+name: loop
+description: Run a prompt or slash command on a recurring interval (e.g. /loop 5m /foo). Omit the interval to let the model self-pace. - When the user wants to set up a recurring task, poll for status, or run something repeatedly on an interval (e.g. "check the deploy every 5 minutes", "keep running /babysit-prs"). Do NOT invoke for one-off tasks.
+---
+
+# /loop — run a prompt on a recurring cadence
+
+Parse the input as `[interval] <prompt…>` and schedule it. sema has TWO loop mechanisms — pick by whether an interval was given:
+
+- **Interval given** → fixed cadence: schedule with `CronCreate` (fires as a scheduled task via the sema scheduler).
+- **No interval** → dynamic mode: YOU self-pace the loop with `ScheduleWakeup`, choosing each delay from what you are actually waiting for.
+
+## Parsing (in priority order)
+
+1. **Leading token**: if the first whitespace-delimited token matches `^\d+[smhd]$` (e.g. `5m`, `2h`), that's the interval; the rest is the prompt.
+2. **Trailing "every" clause**: if the input ends with `every <N><unit>` or `every <N> <unit-word>` (e.g. `every 20m`, `every 5 minutes`), extract it as the interval and strip it from the prompt. Only match when what follows "every" is a time expression — `check every PR` has no interval.
+3. **Otherwise**: no interval → dynamic mode; the entire input is the prompt.
+
+If the resulting prompt is empty AND no interval was given, show usage `/loop [interval] <prompt>` and stop. An empty prompt WITH intent to run autonomously is the autonomous-loop case (see sentinels below).
+
+## Fixed cadence: CronCreate
+
+Convert the interval to a 5-field local-time cron expression (`Nm` → `*/N * * * *`; `Nh` → `0 */N * * *`; `Nd` → `0 0 */N * *`; `Ns` → round up to whole minutes — 1 minute is the floor). If the interval doesn't divide its unit cleanly (e.g. `7m`, `90m`), pick the nearest clean interval and tell the user what you rounded to.
+
+Call `CronCreate` with:
+
+- `prompt`: the parsed prompt, verbatim (slash commands pass through unchanged). The task fires UNATTENDED and will not see this conversation, so if the prompt relies on conversational context, rewrite it self-contained first.
+- `schedule`: `{ "kind": "cron", "expr": "<the expression>" }`
+- `label`: a short name for the loop (also the dedup key — re-creating with the same schedule+label upserts instead of duplicating).
+
+Then briefly confirm what's scheduled (id, human cadence, how to cancel with `CronDelete`), and **immediately execute the parsed prompt once now** — don't wait for the first fire.
+
+## Dynamic mode: ScheduleWakeup
+
+With no interval, run one iteration of the task now, then call `ScheduleWakeup` to schedule when you resume:
+
+- `delaySeconds`: how long to sleep (runtime clamps to [60, 3600]).
+- `reason`: one short, specific sentence ("watching CI run #123" beats "waiting") — shown to the user and telemetry.
+- `prompt`: the same /loop input verbatim, so the next firing re-enters this skill and continues the loop. For an autonomous loop with no user prompt, pass the literal sentinel `<<autonomous-loop-dynamic>>` (never the CronCreate-mode `<<autonomous-loop>>` sentinel — ScheduleWakeup always uses the `-dynamic` variant).
+- To END the loop: call `ScheduleWakeup` with `stop: true` and omit every other field — the loop ends immediately and no further wakeups fire.
+
+### Picking delaySeconds
+
+Do NOT schedule short wakeups to poll harness-tracked background work — when tracked work finishes you are re-invoked automatically, so polling is wasted; schedule a long fallback (1200s+) so the loop survives if the work hangs. Only poll external state the harness cannot track (a CI run, a deploy, a remote queue), and pick the delay from how fast that state actually changes.
+
+Wake-up cost is driven by the provider prompt cache: anthropic-messages routes default to a ~5-minute cache TTL (waking under ~300s stays warm; prefer 270s over 300s when actively polling, and commit to 1200s+ rather than repeated ~300s waits). Routes with hours-long cache retention (e.g. DeepSeek) re-read your context cached at any delay in the clamp range — there, pick purely from the signal you're waiting for. Never schedule extra wakeups just to keep the cache warm. For idle ticks with no specific signal, default to 1200–1800s.
+
+## Which mechanism backs this
+
+Both tools are engine tools mounted only when the runtime exposes a scheduler capability; in the sema TOC shell that backend is the shell scheduler daemon, which persists tasks and fires them on time. Dynamic wakeups resume THIS session (`mode: session-wakeup`, label `loop-wakeup`); CronCreate tasks run unattended. If `CronCreate`/`ScheduleWakeup` are not in your tool list, the scheduler capability is not wired in this session — say so instead of simulating a loop with sleeps.