shell-manual

# Shell manual — router Use the schema for a short, deterministic command. Read one focused route before long-lived/coding-CLI work, scheduling, an unfamiliar workflow, or recovery. The selected dialect, policy, and working-directory sandbox remain boundaries. ## Route by task | Task | Read one direct reference | |---|---| | Long command/CLI; `job_id`, `poll`, `cancel`, reminder, completion, relaunch, or async recovery | [async jobs](reference/async-jobs/SKILL.md) | | Recurring or time-triggered work | [scheduled work](reference/scheduled-work/SKILL.md) | | One future self-wakeup | [notification reminders](reference/notification-reminders/SKILL.md) | | Silent, duplicated, failed, or retired scheduler | [debugging and cleanup](reference/debugging-cleanup/SKILL.md) | | Reading, creating, or editing durable files; large or non-UTF-8 content | Durable filesystem changes below | | Unfamiliar dialect, working directory, timeout, or policy boundary | First success and Settings inventory below | | Backend-specific CLI flags, environment, or parser behavior | `daemon-manual` → `reference/cli-backends/SKILL.md` | ## First success 1. For a bounded command, call `shell(action="run", input={"command": "..."}, reasoning="...")` synchronously. Keep `working_dir` inside the sandbox; for an external checkout, leave it at the granted root and use `cd /absolute/path && ...` in the command. Dialect is fixed and policy still applies. 2. For work that may take minutes, set `input.async=true` and keep the returned `job_id`. On completion or a genuine health-check trigger, poll once for exact output; do not poll to stay active. Follow up with `shell(action="poll", input={"job_id": "..."}, reasoning="...")`; cancel only within authority with `shell(action="cancel", input={"job_id": "..."}, reasoning="...")`. A reminder means “may still be running,” not completion; cancellation is not cleanup. 3. Judge `exit_code`, `ok`, `command_status`, and `warning`; top-level `status` only records spawn/terminal handling, not inner command success. `status: "error"` means Shell could not run it. Prefer bounded `rg --files` and parse JSONL line by line. Unknown or late async state stays unknown: never invent an exit code, completion, or cancellation before durable terminal truth. Keep the job ID pollable after lease/return failure. Completion is authoritative; a reminder is fallback. Retain artifacts unless the human authorizes cleanup. Optional progress is channel-neutral; use `task_card(action="manual", input={})`. Shell creates no watcher. ## Durable filesystem changes Shell is the one filesystem tool: there is no separate file family. The same sandbox, policy, and authority boundaries apply to every read and write. 1. **Anchor the target.** Work under the authorized working directory, or `cd /absolute/path && ...` inside the command for an approved external checkout. Never let a relative path or `..` decide where a write lands. 2. **Bound every read.** Inspect metadata first (`wc -lc`, `file`, `ls -l`), then read a window: `sed -n '120,200p' path`, `head -c 20000 path`, `rg -n 'pattern' path`. A capped window is not the whole file; page by line range until you reach the end you measured. 3. **Precondition an exact replacement.** Before editing, prove the old text exists exactly once: `rg -c -F 'old text' path` must print `1`. Then replace with a tool that does not reinterpret the text (for example a short `python - <<'PY'` block using `str.replace(old, new, 1)` on the UTF-8 content), never an unescaped `sed -i` over user data. 4. **Create or overwrite deliberately.** Read the target before a full rewrite; write with a heredoc (`cat > path <<'EOF' ... EOF`) or a Python block, and create parent directories explicitly (`mkdir -p`). 5. **Verify the mutation.** Re-read the changed lines (`sed -n`/`rg -n`) or compare (`diff`) before reporting success; the write receipt is the re-read, not the exit code alone. 6. **Handle binary and non-UTF-8 honestly.** Check `file path` first. Convert known encodings explicitly (`iconv -f gbk -t utf-8`) and treat lossy `errors='replace'` output as review material, not as the durable copy. Do not describe binary, image, or audio content you did not decode. 7. **Rebuild when the owner requires it.** Editing a durable prompt source (`system/pad.md`, `system/lingtai.md`, pinned references, knowledge, skills) changes disk only; it takes effect after `context(action="rebuild", input={})` or a passive refresh/molt. The owning `psyche` domain manual and `context(action="manual", input={})` own that procedure. Keep private local paths out of human-facing results, and retain artifacts unless the human authorizes cleanup. ## Settings inventory Call `shell(action="settings", input={}, reasoning="inspect applied Shell settings")` for read-only rows. The live schema/settings response owns values and configurability; this section owns only procedures. SHOW has no set/reset authority and an unavailable value fails the whole action without partial rows. | Row | Meaning, source and authorized change | |---|---| | `shell_kind` | Setup-selected `posix`, `powershell`, `cmd`, `gitbash` or `wsl`; valid capability value wins, then case-insensitive `LINGTAI_SHELL`, then platform discovery. Invalid values fall through; default is null because discovery has no universal shell. Change the capability/launcher or `setup(shell_kind=...)`, rebuild/relaunch the owning Agent, recheck SHOW. | | `sync_timeout_default_seconds` | Built-in 30, immutable; nullable call timeout uses it. A finite non-negative per-call timeout does not reconfigure it. | | `sync_timeout_max_seconds` | `LINGTAI_TOOL_TIMEOUT_MAX_SECONDS` read each call/SHOW: positive finite values win over 120, invalid/missing values use 120, and values below 30 are floored at 30. Change only the authorized process/launcher environment; relaunch if snapshotted. Work above the ceiling uses async. | | `result_max_chars` | Per-stream stdout/stderr capture limit, default 50000. Only an authorized embedding owner can pass positive `ShellManager(max_output=...)` before rebuilding the manager. Normal capability setup exposes no key or environment override. | | `async_default` | Built-in false, immutable; `input.async` selects one call. | | `async_reminder_default_seconds` | Built-in 1800, immutable. For one async run, `input.reminder` must be finite/non-negative within the platform timer bound; it is fallback, not completion. | | `command_policy` | Both values stay redacted. Default (omitted config or `shell: {}`) is yolo. Authorized setup selects explicit `yolo=true`, then `policy_file`, then packaged policy for explicit `yolo=false`; rebuild/relaunch and verify SHOW. No rules/paths are disclosed. | SHOW is strict-empty and read-only; there is no Shell settings file or mutation verb. Verify an authorized change through its owning construction procedure and SHOW. Result limits affect disclosure, not authority; no setting permits a working-directory escape.