[Init] Initial commit - NetMesh terminal manager

skills/netcatty-tool-cli/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: netcatty-tool-cli
+description: Use this skill when an external agent needs to operate on Netcatty sessions through Skills + CLI instead of the netcatty-remote-hosts MCP server.
+---
+
+# Netcatty Tool CLI
+
+Use this skill for external ACP agents when Netcatty is configured for `Skills + CLI` mode.
+
+For routine tasks, the host prompt is usually enough. Read only the reference that matches the task type.
+
+## Router
+
+1. Use the exact Netcatty CLI prefix provided by the host prompt.
+2. Keep `--chat-session <chat-session-id>` on every Netcatty CLI call. Do not omit it.
+3. Treat `--chat-session <chat-session-id>` as required for `env`, `session`, real `exec`, and every `sftp` operation. Treat `--session <session-id>` as required for `session`, `exec`, and every `sftp` operation.
+4. Classify the task before choosing a command path:
+   - Remote command execution tasks go through the exec reference.
+   - Remote file or directory tasks go through the sftp reference.
+   - If the user explicitly says to avoid shell or `exec`, do not use `exec`.
+   - Treat `exec` as the short-command path only. If the command may exceed about 60 seconds, or streams output for an extended period, use the long-running job commands instead of plain `exec`.
+5. If the host prompt already names a connected default target session, use that session directly for routine requests that do not mention another session or host, but still start with `session --session <id> --json --chat-session <chat-session-id>` instead of jumping straight to `exec` or `sftp`.
+6. Only fall back to `env` lookup when the task is ambiguous, the user points to another session, or that direct `session` lookup fails.
+
+## Core Rules
+
+- Treat the host-provided CLI prefix as the only supported entrypoint for this session.
+- If a command launcher is needed, prefer the operating system's built-in launcher for the current environment; do not require optional shells that may not be installed.
+- Run Netcatty CLI commands strictly serially.
+- Treat Netcatty CLI errors as authoritative.
+- Never ask the user for SSH credentials, key paths, proxy settings, or jump-host details when Netcatty session access already exists.
+- Do not pause to explain the plan, re-read this skill, or design scripts before trying that shortest path.
+- When presenting structured results, prefer a concise table if it fits clearly.
+
+Examples:
+
+- On Windows, if a literal shell command line is required, use the host-provided prefix with the system launcher available in the environment, such as `cmd.exe` or Windows PowerShell; do not assume PowerShell 7 `pwsh.exe` exists.
+- On macOS or Linux, use the host-provided prefix directly, or the system shell already available in that environment when a shell command line is unavoidable.
+- When the execution surface accepts argv-style calls, use the Netcatty launcher path as the executable and pass subcommands and flags as separate arguments instead of wrapping it in another shell.
+
+## References
+
+- Exec and session workflow: `references/exec.md`
+- SFTP file workflow: `references/sftp.md`
+- Session and device-type handling: `references/session-types.md`
+- Cancel, resume, and runtime diagnostics: `references/control-commands.md`
+- Error handling and authoritative failures: `references/errors.md`

skills/netcatty-tool-cli/references/control-commands.md

@@ -0,0 +1,17 @@
+# Control Commands
+
+Read this when you need diagnostics, cancellation, or to re-enable a cancelled chat scope.
+
+## Useful Commands
+
+- Runtime diagnostics:
+  - `<netcatty-cli-prefix> status --json`
+- Cancel outstanding Netcatty work for this chat scope:
+  - `<netcatty-cli-prefix> cancel --chat-session <chat-session-id> --json`
+- Re-enable execution for that same chat scope:
+  - `<netcatty-cli-prefix> resume --chat-session <chat-session-id> --json`
+
+## Rules
+
+- `cancel` affects the current chat scope; it requests cancellation for in-flight `exec`, session-backed SFTP transfers, and running `job-start` work in that scope. Later `exec` calls in that scope stay blocked until `resume`.
+- Do not issue control commands concurrently with other Netcatty CLI commands for the same chat session.

skills/netcatty-tool-cli/references/errors.md

@@ -0,0 +1,10 @@
+# Error Handling
+
+Read this when a Netcatty CLI call fails or returns a blocked state.
+
+## Rules
+
+- Treat Netcatty CLI errors as authoritative. Do not argue with them or try alternate launch methods.
+- If Netcatty returns `COMMAND_ALREADY_RUNNING`, wait for the in-flight command to finish instead of retrying in parallel.
+- Netcatty enforces scope, approvals, blocklists, and timeouts. Do not try to bypass those checks with wrappers or alternate shells.
+- If a direct command fails and the failure suggests the task genuinely needs branching or parsing logic, then consider a small script. Otherwise keep commands simple.

skills/netcatty-tool-cli/references/exec.md

@@ -0,0 +1,31 @@
+# Exec Reference
+
+Use this reference for remote command execution tasks.
+
+## Shortest Path
+
+`exec` calls are internal agent transport calls. Always include both `--session <session-id>` and `--chat-session <chat-session-id>`.
+After `--`, pass exactly one shell-ready command string. Preserve any quoting inside that one argument instead of splitting it into multiple tokens.
+
+1. If the host prompt already gives a connected default target session, prefer it directly:
+   - `<netcatty-cli-prefix> session --session <default-session-id> --json --chat-session <chat-session-id>`
+   - `<netcatty-cli-prefix> exec --session <default-session-id> --json --chat-session <chat-session-id> -- <command>`
+2. Otherwise:
+   - `<netcatty-cli-prefix> env --json --chat-session <chat-session-id>`
+   - Choose a `connected` session.
+   - `<netcatty-cli-prefix> session --session <session-id> --json --chat-session <chat-session-id>`
+   - `<netcatty-cli-prefix> exec --session <session-id> --json --chat-session <chat-session-id> -- <command>`
+
+## Rules
+
+- Use `exec` only for command-style tasks expected to finish within about 60 seconds, such as hostname, IP address, CPU info, memory info, disk usage, pwd, whoami, uname, or process checks.
+- Use long-running jobs for builds, scans, migrations, watch mode, `tail -f`, `ping`, log-following, or anything likely to exceed that budget or stream output for an extended period.
+- Long-running flow:
+  - `<netcatty-cli-prefix> job-start --session <session-id> --chat-session <chat-session-id> --json -- <command>`
+  - wait before polling unless the output clearly justifies checking sooner
+  - `<netcatty-cli-prefix> job-poll --job <job-id> --chat-session <chat-session-id> --offset <offset> --json`
+  - if the user asks to stop it: `<netcatty-cli-prefix> job-stop --job <job-id> --chat-session <chat-session-id> --json`
+- Prefer one straightforward command over temporary scripts or multi-step shell orchestration.
+- Avoid shell command substitution such as `$()` and backticks, because Netcatty safety policy may block them.
+- Avoid wrapping simple commands in `sh -c`, `bash -c`, or similar shell launchers unless truly necessary.
+- Only write a script when the task genuinely needs branching, loops, or structured parsing that cannot fit cleanly in one direct command.

skills/netcatty-tool-cli/references/session-types.md

@@ -0,0 +1,17 @@
+# Session Types
+
+Read this only when the target session is not a routine shell session or when you are unsure how to execute the command safely.
+
+## Rules
+
+- Always call `session --session <id> --json --chat-session <chat-session-id>` before any `exec`.
+- Do not guess protocol, shell type, device type, or connection state from the `env` payload alone.
+- For normal shell sessions, pass the command after `--` so Netcatty can return `stdout`, `stderr`, and `exitCode`.
+- For serial/raw sessions and sessions with `deviceType: network`, commands are sent as-is without shell wrapping.
+- For serial/raw and network-device sessions, use vendor CLI commands directly and avoid pipes, redirects, subshells, and shell-only syntax.
+
+## Decision Guide
+
+- If the session metadata shows a normal shell: use one direct shell command.
+- If the session metadata shows `protocol: serial`, `shellType: raw`, or `deviceType: network`: use device-native commands only.
+- If the session is not connected: do not execute commands in it.

skills/netcatty-tool-cli/references/sftp.md

@@ -0,0 +1,42 @@
+# SFTP Reference
+
+Use this reference for remote file or directory tasks.
+
+## Default Path
+
+- Treat file and directory tasks as SFTP tasks by default, not shell tasks.
+- If the user explicitly says to use only `sftp`, do not call `exec`.
+- Every `sftp` command must include both `--session <session-id>` and `--chat-session <chat-session-id>`.
+- Do not use reusable SFTP handles or `--sftp <id>`.
+- After choosing a target session, first run `session --session <id> --json --chat-session <chat-session-id>` and inspect the returned metadata.
+- Use SFTP only when that `session` result shows a connected SSH-backed session. For local, Mosh, Telnet, serial/raw, or network-device sessions, do not use SFTP.
+- Keep path semantics strict:
+  - `--remote-path` always means a path on the remote host.
+  - `--local-path` always means a path on the local machine running Netcatty.
+- If the user says "download" to a local destination such as `/tmp`, `~/Downloads`, or Desktop, use `sftp download`.
+- If the user says to create or modify a file on the remote host, use `sftp write`, `sftp upload`, or another remote SFTP operation. Do not reinterpret that as a local download.
+
+## One-Off Commands
+
+- List a directory:
+  - `<netcatty-cli-prefix> sftp list --session <session-id> --remote-path <remote-path> --json --chat-session <chat-session-id>`
+- Read a file:
+  - `<netcatty-cli-prefix> sftp read --session <session-id> --remote-path <remote-path> --json --chat-session <chat-session-id>`
+- Write a small text file with known content:
+  - `<netcatty-cli-prefix> sftp write --session <session-id> --remote-path <remote-path> --content <text> --json --chat-session <chat-session-id>`
+- Download a remote file to an existing local path:
+  - `<netcatty-cli-prefix> sftp download --session <session-id> --remote-path <remote-path> --local-path <local-path> --json --chat-session <chat-session-id>`
+- Upload an existing local file:
+  - `<netcatty-cli-prefix> sftp upload --session <session-id> --local-path <local-path> --remote-path <remote-path> --json --chat-session <chat-session-id>`
+- Delete a remote path:
+  - `<netcatty-cli-prefix> sftp delete --session <session-id> --remote-path <remote-path> --json --chat-session <chat-session-id>`
+
+## Rules
+
+- Use `sftp write` directly for creating or updating a small text file with known content.
+- Use `sftp upload` only when a real local file already exists and must be transferred.
+- Use `sftp download` when the result must be saved to the local filesystem.
+- Do not create temporary local files just to upload text that could be sent with `sftp write`.
+- Do not use `sftp read` as a substitute for `sftp download` when the user asked for a local saved file.
+- Do not use `sftp write` as a substitute for `sftp download`; writing to `/tmp/foo` with `sftp write` writes to the remote host's `/tmp`, not the local machine.
+- Do not use shell commands like `cat`, `touch`, redirection, or ad hoc SCP/SSH usage for remote file tasks.