|
| 1 | +--- |
| 2 | +id: code-run-shell |
| 3 | +name: Code run shell |
| 4 | +aliases: ["shell","cli","powershell","pwsh","process-run"] |
| 5 | +icon: code-run-shell |
| 6 | +kind: playbook |
| 7 | +description: Run programs and shell commands through process_run on Windows, Linux or macOS, including PowerShell; may change files or external data only within the user's authorized scope, with risk, duration and encoding checks. |
| 8 | +parameters: {"type":"object","properties":{"task":{"type":"string","description":"The command or automation goal"},"shell":{"type":"string","description":"Shell explicitly chosen by the user"},"workingDirectory":{"type":"string","description":"Working directory provided by the user"}},"additionalProperties":false} |
| 9 | +tools: ["tool_search","process_run","read_text_file","get_file_info","list_directory","write_file","create_directory","ask_user"] |
| 10 | +--- |
| 11 | + |
| 12 | +The user's instructions take precedence. Follow repository instructions and use ordinary |
| 13 | +permission-checked tools; this playbook grants no access. Report in the user's language. |
| 14 | +Prefer a direct executable and argv array. Use a shell for its built-ins, pipelines, redirection |
| 15 | +or scripts, and a dedicated tool when it better serves the task. |
| 16 | + |
| 17 | +1. Establish the goal, inputs and authorized side effects. Check `process_run` availability, |
| 18 | + discovering it through `tool_search` if needed, and read its current description/schema. |
| 19 | + If unavailable, briefly explain and use another available executor; do not install/connect |
| 20 | + tools automatically. Identify the server OS, not the client's OS, and verify executable paths, |
| 21 | + shell availability/version and working directory with permitted read-only checks. |
| 22 | +2. Use `executable`, string-array `arguments`, verified `workingDirectory` and supported |
| 23 | + `timeoutMs`. In the known contract, a bare executable name is resolved through PATH even with |
| 24 | + a working directory; use an absolute path or `./name` for a file in that directory. Each array |
| 25 | + element is one argv entry: do not wrap a path in extra quotes just because it contains spaces. |
| 26 | + There is no implicit shell, glob or variable expansion; `*`, `~`, `$VAR`, `%VAR%`, pipes and |
| 27 | + redirects are literal arguments unless a shell explicitly parses them. Stdin is closed at |
| 28 | + launch: use noninteractive modes and supported input files, not interactive prompts. Known |
| 29 | + parameters do not include stdin, environment, encoding, background mode or session polling; |
| 30 | + do not invent them. The actual schema wins. |
| 31 | +3. Choose the shell explicitly when required: |
| 32 | + - Windows PowerShell 7: `pwsh` with `-NoLogo`, `-NoProfile`, `-NonInteractive`, `-Command`, |
| 33 | + then one string of PowerShell code; or use `-File` for a verified .ps1 file. |
| 34 | + - Windows PowerShell 5.1: `powershell.exe` with the same switches, but use syntax and encoding |
| 35 | + supported by that version. PowerShell 7 is not guaranteed to be installed. |
| 36 | + - Windows cmd: `cmd.exe` with `/d`, `/s`, `/c`, then cmd code for cmd built-ins or .cmd/.bat |
| 37 | + files. Respect cmd-specific quoting and percent expansion. |
| 38 | + - Linux/macOS POSIX shell: verified `/bin/sh` with `-c`, then POSIX code; avoid Bash extensions. |
| 39 | + For Bash-specific code use verified `bash` with `--noprofile`, `--norc`, `-c`, then Bash code. |
| 40 | + Do not assume a particular Bash version, especially on macOS. Use zsh only when appropriate |
| 41 | + and verified. `pwsh` also works on Linux/macOS when actually installed. |
| 42 | + Respect host path syntax, case sensitivity, executable extensions and line endings. Avoid |
| 43 | + interactive profiles unless required. On Windows keep recursive filesystem operations in one |
| 44 | + shell, using PowerShell -LiteralPath where applicable; do not enumerate there and delete via cmd. |
| 45 | +4. For complex PowerShell use a .ps1 with `param(...)`, `-File` and values as separate arguments. |
| 46 | + Example argv: `["-NoLogo","-NoProfile","-NonInteractive","-File","C:\\work\\job.ps1", |
| 47 | + "-InputPath","C:\\work\\данные.json"]`; first verify those actual paths or use the host's paths. |
| 48 | + `-Command` receives code to be parsed: an argv array does not protect interpolated data inside |
| 49 | + that code. For POSIX shell pass data as positional arguments: `sh -c '<code using "$1">' |
| 50 | + task '<value>'`. Use `--` for values beginning with '-' only when the program supports it. |
| 51 | + JSON escaping is not shell escaping. PowerShell -EncodedCommand is Base64 of UTF-16LE code, |
| 52 | + not protection against injection or an output-encoding setting. Do not automatically bypass |
| 53 | + ExecutionPolicy. For scripts requiring stop-on-error set `$ErrorActionPreference = 'Stop'`; |
| 54 | + check `$LASTEXITCODE` immediately after important native programs and propagate an appropriate |
| 55 | + `exit` code. Nonterminating PowerShell errors and native program failures need separate checks. |
| 56 | +5. Assess deletion, overwrite, moves, database/network changes and disk exhaustion before launch. |
| 57 | + The working directory is not a sandbox. Verify full targets, empty inputs, source/destination |
| 58 | + overlap, existing outputs and symlinks/junctions. Before recursive deletion/moves confirm the |
| 59 | + final path is within the intended authorized area, not an accidental root, home or entire |
| 60 | + working tree. Preview targets or use dry-run/-WhatIf where supported; preserve important |
| 61 | + originals or write and verify a new output before replacement. Inspect the entire command: |
| 62 | + redirection can truncate a file before the program succeeds. Do not add blanket approval for |
| 63 | + ordinary reads or already authorized changes. Prepare concrete targets and ask only for missing |
| 64 | + authorization for irreversible actions outside the request. Declined stops that action; |
| 65 | + unresolved approval does not authorize it. Process termination does not undo partial changes. |
| 66 | +6. Estimate duration: builds, data processing and automation may take hours. Check tool/client |
| 67 | + limits and whether a genuine managed long-running execution mechanism exists. The known |
| 68 | + `timeoutMs` range is 1–120000, default 120000; timeout/cancellation terminates the process tree. |
| 69 | + Do not exceed the schema. If insufficient, use safely separable batches/stages with checkpoints, |
| 70 | + or an available managed job/session/queue with identifier, status, logs, cancellation and final |
| 71 | + result. Do not split atomic operations in ways that damage integrity. Change a timeout setting |
| 72 | + only when actually supported and authorized. If no suitable mechanism exists, explain the |
| 73 | + limit and prepare a reproducible script without claiming completion. Do not bypass limits with |
| 74 | + nohup, &, detached processes or Start-Process: children may be terminated and launch does not |
| 75 | + prove completion. When a supported workflow needs Start-Process on Windows, use -WindowStyle |
| 76 | + Hidden unless a visible interactive window is explicitly needed. After timeout inspect actual |
| 77 | + status, partial artifacts and logs before retrying safely resumable work. |
| 78 | +7. Agree encodings for input files, stdout/stderr and artifacts. JSON argv is Unicode, but child |
| 79 | + byte streams and files may use UTF-8, OEM/ANSI or UTF-16. Prefer explicit UTF-8 modes when the |
| 80 | + program supports them; agree with the tool's decoder rather than assuming UTF-8. If the decoder |
| 81 | + cannot be configured, capture raw output to a file using byte-preserving means and read it |
| 82 | + with a known encoding through an available file tool or controlled decoder. Do not repair text |
| 83 | + after replacement characters have lost information. Check a short Cyrillic/non-ASCII example |
| 84 | + when important. Preserve existing encoding, BOM and line endings; default new text to UTF-8 |
| 85 | + without BOM unless the consumer needs another format. Do not expose secrets in argv or logs. |
| 86 | + - PowerShell 7 usually writes UTF-8 without BOM; Windows PowerShell 5.1 defaults vary by cmdlet, |
| 87 | + and Out-File/> commonly write UTF-16LE. Specify -Encoding with a value supported by the version. |
| 88 | + For .ps1 with non-ASCII under 5.1 use UTF-8 with BOM or another correctly readable encoding. |
| 89 | + Use .NET file APIs when an exact byte format is needed. |
| 90 | + - `[Console]::OutputEncoding` governs console output; `$OutputEncoding` governs text sent to |
| 91 | + native programs through pipelines. Set them locally only as needed and agree with decoding. |
| 92 | + Neither `chcp 65001` nor a PowerShell encoding assignment forces every native program to |
| 93 | + emit UTF-8. Avoid `cmd /u` unless UTF-16 output from cmd built-ins matches the decoder. |
| 94 | + - On Linux/macOS verify an available UTF-8 locale rather than assuming C.UTF-8 exists. The known |
| 95 | + runner restricts inherited environment variables; do not assume LANG or arbitrary credentials |
| 96 | + survive. Use a supported program/wrapper mechanism for required environment, without changing |
| 97 | + the server globally. Locale also affects dates, decimal separators and sorting; use explicit |
| 98 | + machine formats when needed. |
| 99 | +8. Inspect `exitCode`, `error`, `timedOut`, `truncated`, stdout and stderr. A nonzero code depends on |
| 100 | + the program's contract (for example a search with no matches); absence of stderr is not proof of |
| 101 | + success. Known capture is limited to 32768 characters per stream; save complete authorized logs |
| 102 | + through program options or an explicit shell redirect with a correct encoding. Verify the final |
| 103 | + artifacts and intended postconditions. Before retrying failures inspect partial side effects. |
| 104 | + The final answer contains the requested command result or accessible artifacts, actual checks |
| 105 | + and any unresolved duration, encoding or completeness limits. A running job is not a passed run. |
0 commit comments