@psnext/slingcli 3.0.20260820-2 → 3.1.20260904-1

package/skills/s-help/resources/s-filechanges.md

@@ -0,0 +1,38 @@
+# /s:filechanges
+
+**Source:** `slingshot/src/filechanges/index.ts`
+
+## What it does
+
+Tracks and visualizes **files modified by the agent** (via `write`/`edit` tool calls) during the current session/branch, then lets you inspect diffs and either:
+
+- **accept** the changes (keep current files, clear the log)
+- **decline** the changes (revert files back to baseline, clear the log)
+
+It also adds a small UI widget/status indicator in the footer.
+
+## Usage
+
+- `/s:filechanges`
+
+### Interactive mode (UI)
+
+Shows a picker list:
+
+- “Accept changes (clear log)”
+- “Undo changes (revert)”
+- Individual files (pick one to view a `diff`)
+
+### Non-interactive mode (no UI)
+
+Prints a summary of changed files to stdout.
+
+## Related commands
+
+- `/s:filechanges-accept`
+- `/s:filechanges-decline`
+
+## Notes / Safety
+
+- Declining changes can **overwrite** files and delete created files.
+- In non-UI mode, accept/decline require `force` confirmation flags (see the specific commands).

package/skills/s-help/resources/s-footer.md

@@ -0,0 +1,38 @@
+# /s:footer
+
+**Source:** `slingshot/src/footer/index.ts`
+
+## What it does
+
+Enables/configures the Slingshot **powerline-style footer** (status line) experience.
+
+The footer implementation is large and featureful; it includes (non-exhaustive):
+
+- Powerline segments (model, cwd, git, token usage, etc.)
+- Presets (`default`, etc.)
+- Optional secondary row for overflow segments
+- Fixed-editor layout integration (required for certain jump/scroll behaviors)
+- Keyboard shortcuts (stash/copy/cut/jump/scroll)
+- “Welcome” overlay/header on startup
+- Bash-mode integration (shell session + transcript)
+
+## Usage
+
+In pi, run:
+
+- `/s:footer` — opens an interactive configuration UI (if UI is available) or toggles/configures behavior depending on how the command handler is implemented.
+
+## Key settings & files
+
+- Global settings: `~/.sling/agent/settings.json`
+- Project settings: `<project>/.sling/settings.json`
+- Stash history persistence: `~/.sling/agent/sling-footer/stash-history.json`
+- Session prompt history storage: `~/.sling/agent/sling-footer/sessions/**`
+
+## Notes
+
+- Some chat-jump features explicitly require fixed-editor mode:
+  - “Chat message jumps require /s:footer fixed-editor on”
+  - “Chat bottom jump requires /s:footer fixed-editor on”
+
+If you see those warnings, enable fixed-editor within the footer config.

package/skills/s-help/resources/s-promptlib.md

@@ -0,0 +1,28 @@
+# /s:promptlib
+
+**Source:** `slingshot/src/promptlib/index.ts`
+
+## What it does
+
+Opens a **Slingshot Prompt Library** browser.
+
+Implementation details:
+
+- Temporarily registers an MCP server config named `Slingshot-PromptLibrary`
+- Calls the MCP tool `list_prompts`
+- Presents a multi-step picker UI:
+  1. Select Account
+  2. Select Project
+  3. Select Prompt
+- Sends the selected prompt text back into chat as a follow-up message
+
+## Usage
+
+- `/s:promptlib`
+
+## Requirements / Notes
+
+- Requires a valid provider API key (resolved from `ctx.modelRegistry.getApiKeyForProvider(...)`).
+- Uses Slingshot OAuth credentials (projectId/workspaceId) for MCP headers.
+- On shutdown it removes the MCP server config.
+- Writes debug output to `tmp/prompts.json` in the current working directory.

package/skills/s-help/resources/s-skills-manager.md

@@ -0,0 +1,31 @@
+# /s:skills-manager
+
+**Source:** `slingshot/src/skillmanager/index.ts`
+
+## What it does
+
+Interactive UI to **enable/disable skills** by updating pi settings (similar to `pi config`).
+
+Features:
+
+- grouped by source (top-level vs package, user vs project)
+- search/filter
+  - plain text: matches skill name
+  - `/query`: matches full skill path
+  - `@query`: matches package/source
+- view modes (Tab cycles): By source / A–Z / Active first
+- writes `+pattern` / `-pattern` entries to settings
+- optionally prompts to `/reload` to apply changes
+
+## Usage
+
+- `/s:skills-manager`
+
+Non-interactive listing:
+
+- `/s:skills-manager list`
+
+## Notes
+
+- Uses `SettingsManager` + `DefaultPackageManager` to resolve skills.
+- In headless/no-UI mode, it will fall back to listing output.

package/skills/s-help/resources/s-stash-history.md

@@ -0,0 +1,26 @@
+# /s:stash-history
+
+**Source:** `slingshot/src/footer/index.ts`
+
+## What it does
+
+Provides a quick way to **stash** the current editor text into a small history list, and then later browse/insert those stashed prompts.
+
+This is designed for prompt iteration: you can save a prompt before trying a variant, then quickly restore earlier versions.
+
+## Usage
+
+- `/s:stash-history`
+
+Typically used via the footer shortcut (default shown in the footer code as `ctrl+alt+h`), but the command is also registered.
+
+## Persistence
+
+Stash history is persisted at:
+
+- `~/.sling/agent/sling-footer/stash-history.json`
+
+## Notes
+
+- History is capped (see `STASH_HISTORY_LIMIT` in the footer implementation).
+- Entries are compacted/deduped (no consecutive duplicates; whitespace-only entries skipped).

package/skills/screenshot/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: "screenshot"
+description: "Use when the user explicitly asks for a desktop or system screenshot (full screen, specific app or window, or a pixel region), or when tool-specific capture capabilities are unavailable and an OS-level capture is needed."
+---
+
+
+# Screenshot Capture
+
+Follow these save-location rules every time:
+
+1) If the user specifies a path, save there.
+2) If the user asks for a screenshot without a path, save to the OS default screenshot location.
+3) If Codex needs a screenshot for its own inspection, save to the temp directory.
+
+## Tool priority
+
+- Prefer tool-specific screenshot capabilities when available (for example: a Figma MCP/skill for Figma files, or Playwright/agent-browser tools for browsers and Electron apps).
+- Use this skill when explicitly asked, for whole-system desktop captures, or when a tool-specific capture cannot get what you need.
+- Otherwise, treat this skill as the default for desktop apps without a better-integrated capture tool.
+
+## macOS permission preflight (reduce repeated prompts)
+
+On macOS, run the preflight helper once before window/app capture. It checks
+Screen Recording permission, explains why it is needed, and requests it in one
+place.
+
+The helpers route Swift's module cache to `$TMPDIR/codex-swift-module-cache`
+to avoid extra sandbox module-cache prompts.
+
+```bash
+bash <path-to-skill>/scripts/ensure_macos_permissions.sh
+```
+
+To avoid multiple sandbox approval prompts, combine preflight + capture in one
+command when possible:
+
+```bash
+bash <path-to-skill>/scripts/ensure_macos_permissions.sh && \
+python3 <path-to-skill>/scripts/take_screenshot.py --app "Codex"
+```
+
+For Codex inspection runs, keep the output in temp:
+
+```bash
+bash <path-to-skill>/scripts/ensure_macos_permissions.sh && \
+python3 <path-to-skill>/scripts/take_screenshot.py --app "<App>" --mode temp
+```
+
+Use the bundled scripts to avoid re-deriving OS-specific commands.
+
+## macOS and Linux (Python helper)
+
+Run the helper from the repo root:
+
+```bash
+python3 <path-to-skill>/scripts/take_screenshot.py
+```
+
+Common patterns:
+
+- Default location (user asked for "a screenshot"):
+
+```bash
+python3 <path-to-skill>/scripts/take_screenshot.py
+```
+
+- Temp location (Codex visual check):
+
+```bash
+python3 <path-to-skill>/scripts/take_screenshot.py --mode temp
+```
+
+- Explicit location (user provided a path or filename):
+
+```bash
+python3 <path-to-skill>/scripts/take_screenshot.py --path output/screen.png
+```
+
+- App/window capture by app name (macOS only; substring match is OK; captures all matching windows):
+
+```bash
+python3 <path-to-skill>/scripts/take_screenshot.py --app "Codex"
+```
+
+- Specific window title within an app (macOS only):
+
+```bash
+python3 <path-to-skill>/scripts/take_screenshot.py --app "Codex" --window-name "Settings"
+```
+
+- List matching window ids before capturing (macOS only):
+
+```bash
+python3 <path-to-skill>/scripts/take_screenshot.py --list-windows --app "Codex"
+```
+
+- Pixel region (x,y,w,h):
+
+```bash
+python3 <path-to-skill>/scripts/take_screenshot.py --mode temp --region 100,200,800,600
+```
+
+- Focused/active window (captures only the frontmost window; use `--app` to capture all windows):
+
+```bash
+python3 <path-to-skill>/scripts/take_screenshot.py --mode temp --active-window
+```
+
+- Specific window id (use --list-windows on macOS to discover ids):
+
+```bash
+python3 <path-to-skill>/scripts/take_screenshot.py --window-id 12345
+```
+
+The script prints one path per capture. When multiple windows or displays match, it prints multiple paths (one per line) and adds suffixes like `-w<windowId>` or `-d<display>`. View each path sequentially with the image viewer tool, and only manipulate images if needed or requested.
+
+### Workflow examples
+
+- "Take a look at <App> and tell me what you see": capture to temp, then view each printed path in order.
+
+```bash
+bash <path-to-skill>/scripts/ensure_macos_permissions.sh && \
+python3 <path-to-skill>/scripts/take_screenshot.py --app "<App>" --mode temp
+```
+
+- "The design from Figma is not matching what is implemented": use a Figma MCP/skill to capture the design first, then capture the running app with this skill (typically to temp) and compare the raw screenshots before any manipulation.
+
+### Multi-display behavior
+
+- On macOS, full-screen captures save one file per display when multiple monitors are connected.
+- On Linux and Windows, full-screen captures use the virtual desktop (all monitors in one image); use `--region` to isolate a single display when needed.
+
+### Linux prerequisites and selection logic
+
+The helper automatically selects the first available tool:
+
+1) `scrot`
+2) `gnome-screenshot`
+3) ImageMagick `import`
+
+If none are available, ask the user to install one of them and retry.
+
+Coordinate regions require `scrot` or ImageMagick `import`.
+
+`--app`, `--window-name`, and `--list-windows` are macOS-only. On Linux, use
+`--active-window` or provide `--window-id` when available.
+
+## Windows (PowerShell helper)
+
+Run the PowerShell helper:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1
+```
+
+Common patterns:
+
+- Default location:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1
+```
+
+- Temp location (Codex visual check):
+
+```powershell
+powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Mode temp
+```
+
+- Explicit path:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Path "C:\Temp\screen.png"
+```
+
+- Pixel region (x,y,w,h):
+
+```powershell
+powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Mode temp -Region 100,200,800,600
+```
+
+- Active window (ask the user to focus it first):
+
+```powershell
+powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Mode temp -ActiveWindow
+```
+
+- Specific window handle (only when provided):
+
+```powershell
+powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -WindowHandle 123456
+```
+
+## Direct OS commands (fallbacks)
+
+Use these when you cannot run the helpers.
+
+### macOS
+
+- Full screen to a specific path:
+
+```bash
+screencapture -x output/screen.png
+```
+
+- Pixel region:
+
+```bash
+screencapture -x -R100,200,800,600 output/region.png
+```
+
+- Specific window id:
+
+```bash
+screencapture -x -l12345 output/window.png
+```
+
+- Interactive selection or window pick:
+
+```bash
+screencapture -x -i output/interactive.png
+```
+
+### Linux
+
+- Full screen:
+
+```bash
+scrot output/screen.png
+```
+
+```bash
+gnome-screenshot -f output/screen.png
+```
+
+```bash
+import -window root output/screen.png
+```
+
+- Pixel region:
+
+```bash
+scrot -a 100,200,800,600 output/region.png
+```
+
+```bash
+import -window root -crop 800x600+100+200 output/region.png
+```
+
+- Active window:
+
+```bash
+scrot -u output/window.png
+```
+
+```bash
+gnome-screenshot -w -f output/window.png
+```
+
+## Error handling
+
+- On macOS, run `bash <path-to-skill>/scripts/ensure_macos_permissions.sh` first to request Screen Recording in one place.
+- If you see "screen capture checks are blocked in the sandbox", "could not create image from display", or Swift `ModuleCache` permission errors in a sandboxed run, rerun the command with escalated permissions.
+- If macOS app/window capture returns no matches, run `--list-windows --app "AppName"` and retry with `--window-id`, and make sure the app is visible on screen.
+- If Linux region/window capture fails, check tool availability with `command -v scrot`, `command -v gnome-screenshot`, and `command -v import`.
+- If saving to the OS default location fails with permission errors in a sandbox, rerun the command with escalated permissions.
+- Always report the saved file path in the response.

package/skills/screenshot/scripts/ensure_macos_permissions.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "$(uname)" != "Darwin" ]]; then
+  echo "ensure_macos_permissions.sh only supports macOS" >&2
+  exit 1
+fi
+
+if ! command -v swift >/dev/null 2>&1; then
+  echo "swift is required to check macOS screen capture permissions" >&2
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PERM_SWIFT="$SCRIPT_DIR/macos_permissions.swift"
+MODULE_CACHE="${TMPDIR:-/tmp}/codex-swift-module-cache"
+mkdir -p "$MODULE_CACHE"
+
+screen_capture_status() {
+  local json
+  json="$(swift -module-cache-path "$MODULE_CACHE" "$PERM_SWIFT" "$@")"
+  python3 -c 'import json, sys; data=json.loads(sys.argv[1]); print("1" if data.get("screenCapture") else "0")' "$json"
+}
+
+if [[ -n "${CODEX_SANDBOX:-}" ]]; then
+  echo "Screen capture checks are blocked in the sandbox; rerun with escalated permissions." >&2
+  exit 3
+fi
+
+if [[ "$(screen_capture_status)" == "1" ]]; then
+  echo "Screen Recording permission already granted."
+  exit 0
+fi
+
+cat <<'MSG'
+This workflow needs macOS Screen Recording permission to capture screenshots.
+macOS will show a single system prompt for Screen Recording. Approve it, then
+return here. If macOS opens System Settings instead of prompting, enable Screen
+Recording for your terminal and rerun the command.
+MSG
+
+# Request permission once after explaining why it is needed.
+screen_capture_status --request >/dev/null || true
+
+if [[ "$(screen_capture_status)" != "1" ]]; then
+  cat <<'MSG'
+Screen Recording is still not granted.
+Open System Settings > Privacy & Security > Screen Recording and enable it for
+your terminal (and Codex if needed), then rerun your screenshot command.
+MSG
+  exit 2
+fi
+
+echo "Screen Recording permission granted."

package/skills/screenshot/scripts/macos_display_info.swift

@@ -0,0 +1,22 @@
+import AppKit
+import Foundation
+
+struct Response: Encodable {
+  let count: Int
+  let displays: [Int]
+}
+
+let count = max(NSScreen.screens.count, 1)
+let displays = Array(1...count)
+
+let response = Response(count: count, displays: displays)
+let encoder = JSONEncoder()
+encoder.outputFormatting = [.sortedKeys]
+
+if let data = try? encoder.encode(response),
+   let json = String(data: data, encoding: .utf8) {
+  print(json)
+} else {
+  fputs("{\"count\":\(count)}\n", stderr)
+  exit(1)
+}

package/skills/screenshot/scripts/macos_permissions.swift

@@ -0,0 +1,40 @@
+import CoreGraphics
+import Foundation
+
+struct Status: Encodable {
+  let screenCapture: Bool
+  let requested: Bool
+}
+
+let shouldRequest = CommandLine.arguments.contains("--request")
+
+@available(macOS 10.15, *)
+func screenCaptureGranted(request: Bool) -> Bool {
+  if CGPreflightScreenCaptureAccess() {
+    return true
+  }
+  if request {
+    _ = CGRequestScreenCaptureAccess()
+    return CGPreflightScreenCaptureAccess()
+  }
+  return false
+}
+
+let granted: Bool
+if #available(macOS 10.15, *) {
+  granted = screenCaptureGranted(request: shouldRequest)
+} else {
+  granted = true
+}
+
+let status = Status(screenCapture: granted, requested: shouldRequest)
+let encoder = JSONEncoder()
+encoder.outputFormatting = [.sortedKeys]
+
+if let data = try? encoder.encode(status),
+   let json = String(data: data, encoding: .utf8) {
+  print(json)
+} else {
+  fputs("{\"requested\":\(shouldRequest),\"screenCapture\":\(granted)}\n", stderr)
+  exit(1)
+}

package/skills/screenshot/scripts/macos_window_info.swift

@@ -0,0 +1,126 @@
+import AppKit
+import CoreGraphics
+import Foundation
+
+struct Bounds: Encodable {
+  let x: Int
+  let y: Int
+  let width: Int
+  let height: Int
+}
+
+struct WindowInfo: Encodable {
+  let id: Int
+  let owner: String
+  let name: String
+  let layer: Int
+  let bounds: Bounds
+  let area: Int
+}
+
+struct Response: Encodable {
+  let count: Int
+  let selected: WindowInfo?
+  let windows: [WindowInfo]?
+}
+
+func value(for flag: String) -> String? {
+  guard let idx = CommandLine.arguments.firstIndex(of: flag) else {
+    return nil
+  }
+  let next = CommandLine.arguments.index(after: idx)
+  guard next < CommandLine.arguments.endIndex else {
+    return nil
+  }
+  return CommandLine.arguments[next]
+}
+
+let frontmostFlag = CommandLine.arguments.contains("--frontmost")
+let explicitApp = value(for: "--app")
+let frontmostName = frontmostFlag ? NSWorkspace.shared.frontmostApplication?.localizedName : nil
+if frontmostFlag && frontmostName == nil {
+  fputs("{\"count\":0}\n", stderr)
+  exit(1)
+}
+let appFilter = (explicitApp ?? frontmostName)?.lowercased()
+let nameFilter = value(for: "--window-name")?.lowercased()
+let includeList = CommandLine.arguments.contains("--list")
+
+let options: CGWindowListOption = [.optionOnScreenOnly, .excludeDesktopElements]
+guard let raw = CGWindowListCopyWindowInfo(options, kCGNullWindowID) as? [[String: Any]] else {
+  fputs("{\"count\":0}\n", stderr)
+  exit(1)
+}
+
+var exactMatches: [WindowInfo] = []
+var partialMatches: [WindowInfo] = []
+exactMatches.reserveCapacity(raw.count)
+partialMatches.reserveCapacity(raw.count)
+
+for entry in raw {
+  guard let owner = entry[kCGWindowOwnerName as String] as? String else { continue }
+  let ownerLower = owner.lowercased()
+  if let appFilter, !ownerLower.contains(appFilter) { continue }
+
+  let name = (entry[kCGWindowName as String] as? String) ?? ""
+  if let nameFilter, !name.lowercased().contains(nameFilter) { continue }
+
+  guard let number = entry[kCGWindowNumber as String] as? Int else { continue }
+  let layer = (entry[kCGWindowLayer as String] as? Int) ?? 0
+
+  guard let boundsDict = entry[kCGWindowBounds as String] as? [String: Any] else { continue }
+  let x = Int((boundsDict["X"] as? Double) ?? 0)
+  let y = Int((boundsDict["Y"] as? Double) ?? 0)
+  let width = Int((boundsDict["Width"] as? Double) ?? 0)
+  let height = Int((boundsDict["Height"] as? Double) ?? 0)
+  if width <= 0 || height <= 0 { continue }
+
+  let bounds = Bounds(x: x, y: y, width: width, height: height)
+  let area = width * height
+  let info = WindowInfo(id: number, owner: owner, name: name, layer: layer, bounds: bounds, area: area)
+  if let appFilter, ownerLower == appFilter {
+    exactMatches.append(info)
+  } else {
+    partialMatches.append(info)
+  }
+}
+
+let windows: [WindowInfo]
+if appFilter != nil && !exactMatches.isEmpty {
+  windows = exactMatches
+} else {
+  windows = partialMatches
+}
+
+func rank(_ window: WindowInfo) -> (Int, Int) {
+  // Prefer normal-layer windows, then larger area.
+  let layerScore = window.layer == 0 ? 0 : 1
+  return (layerScore, -window.area)
+}
+
+let ordered: [WindowInfo]
+if frontmostFlag {
+  ordered = windows
+} else {
+  ordered = windows.sorted { rank($0) < rank($1) }
+}
+let selected = ordered.first
+
+let list: [WindowInfo]?
+if includeList {
+  list = ordered
+} else {
+  list = nil
+}
+
+let response = Response(count: windows.count, selected: selected, windows: list)
+let encoder = JSONEncoder()
+encoder.outputFormatting = [.sortedKeys]
+
+if let data = try? encoder.encode(response),
+   let json = String(data: data, encoding: .utf8) {
+  print(json)
+} else {
+  fputs("{\"count\":\(windows.count)}\n", stderr)
+  exit(1)
+}