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 |
| Recurring or time-triggered work |
scheduled work |
| One future self-wakeup |
notification reminders |
| Silent, duplicated, failed, or retired scheduler |
debugging and cleanup |
| 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
- 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.
- 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.
- 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.
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.
1---2name: shell-manual3description: **Read before running a long-lived agent/coding CLI as a shell subprocess**, or before setting up cron/launchd/systemd timers or scheduled reminders. Routes shell-side async+poll supervision, host-scheduler setup, LingTai wake-by-mailbox-drop, one-shot reminders, and safe cleanup. Per-backend CLI operational detail (command shapes, flags, env contracts) for daemon-backed CLIs lives in `daemon-manual` → `reference/cli-backends/SKILL.md`.4---56# Shell manual — router78Use the schema for a short, deterministic command. Read one focused route before9long-lived/coding-CLI work, scheduling, an unfamiliar workflow, or recovery.10The selected dialect, policy, and working-directory sandbox remain boundaries.1112## Route by task1314| Task | Read one direct reference |15|---|---|16| Long command/CLI; `job_id`, `poll`, `cancel`, reminder, completion, relaunch, or async recovery | [async jobs](reference/async-jobs/SKILL.md) |17| Recurring or time-triggered work | [scheduled work](reference/scheduled-work/SKILL.md) |18| One future self-wakeup | [notification reminders](reference/notification-reminders/SKILL.md) |19| Silent, duplicated, failed, or retired scheduler | [debugging and cleanup](reference/debugging-cleanup/SKILL.md) |20| Unfamiliar dialect, working directory, timeout, or policy boundary | First success and Settings inventory below |21| Backend-specific CLI flags, environment, or parser behavior | `daemon-manual` → `reference/cli-backends/SKILL.md` |2223## First success24251. For a bounded command, call `shell(action="run", input={"command": "..."},26 reasoning="...")` synchronously. Keep `working_dir` inside the sandbox; for27 an external checkout, leave it at the granted root and use28 `cd /absolute/path && ...` in the command. Dialect is fixed and policy still29 applies.302. For work that may take minutes, set `input.async=true` and keep the returned31 `job_id`. On completion or a genuine health-check trigger, poll once for32 exact output; do not poll to stay active. Follow up with33 `shell(action="poll", input={"job_id": "..."}, reasoning="...")`; cancel only34 within authority with `shell(action="cancel", input={"job_id": "..."}, reasoning="...")`.35 A reminder means “may still be running,” not completion; cancellation is not cleanup.363. Judge `exit_code`, `ok`, `command_status`, and `warning`; top-level `status`37 only records spawn/terminal handling, not inner command success. `status:38 "error"` means Shell could not run it. Prefer bounded `rg --files` and parse39 JSONL line by line.4041Unknown or late async state stays unknown: never invent an exit code,42completion, or cancellation before durable terminal truth. Keep the job ID43pollable after lease/return failure. Completion is authoritative; a reminder is44fallback. Retain artifacts unless the human authorizes cleanup. Optional45progress is channel-neutral; use `task_card(action="manual", input={})`.46Shell creates no watcher.4748## Settings inventory4950Call `shell(action="settings", input={}, reasoning="inspect applied Shell51settings")` for read-only rows. The live schema/settings response owns values and52configurability; this section owns only procedures. SHOW has no set/reset53authority and an unavailable value fails the whole action without partial rows.5455| Row | Meaning, source and authorized change |56|---|---|57| `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. |58| `sync_timeout_default_seconds` | Built-in 30, immutable; nullable call timeout uses it. A finite non-negative per-call timeout does not reconfigure it. |59| `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. |60| `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. |61| `async_default` | Built-in false, immutable; `input.async` selects one call. |62| `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. |63| `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. |6465SHOW is strict-empty and read-only; there is no Shell settings file or mutation66verb. Verify an authorized change through its owning construction procedure and67SHOW. Result limits affect disclosure, not authority; no setting permits a68working-directory escape.
lingtai-ai