sshscript 4.0.2__tar.gz → 6.0.0__tar.gz

{sshscript-4.0.2 → sshscript-6.0.0}/.gitignore

@@ -119,3 +119,5 @@ htmlcov/
 !/unittest/test_stdin_contract.py
 !/unittest/test_syntax_error.spy
 !/unittest/test_update_check.py
+
+!/unittest/test_interactive_console.py

sshscript-6.0.0/AI_GUIDE.md

@@ -0,0 +1,112 @@
+# SSHScript for AI agents
+
+**Documentation contract: SSHScript 6.0.0; Python 3.11+.**
+
+This guide targets the 6.0.0 source contract and verified local wheels.
+[5.0.0 remains the latest published package](https://pypi.org/project/sshscript/5.0.0/);
+source publication and CI do not upload 6.0.0 to PyPI.
+For nested SSH, provision known_hosts on each calling host: `"parent"` is the
+default. Read the 4.0.2-to-5.0 migration before reusing older automation.
+
+Start with the [agent guide](skills/sshscript/references/agent-guide.md).
+It explains version checks, API selection, command results, input, deadlines,
+authentication and cleanup. Read only the task-relevant sections of the
+[canonical API guide](API_GUIDE.md) and [version policy](VERSIONING.md).
+
+The [SSHScript skill](skills/sshscript/SKILL.md) supplies a compact operating
+workflow. Its folder contains the supporting guide; copy the entire
+`skills/sshscript/` folder when installing it in an agent's skill directory.
+It teaches SSHScript usage, not development of SSHScript itself or a particular
+recipe library. Agents without skill support can read these Markdown files.
+
+## Interactive console (6.0)
+
+For step-by-step use from a human or UI agent's retained terminal, see the
+[console guide](CONSOLE.md) and the agent guide's
+[console instructions](skills/sshscript/references/agent-guide.md#interactive-console-60).
+Run `python3 -B sshscript.py console` from the matching development checkout;
+an installed 6.0.0 wheel provides `sshscript console`. Published 5.0.0 does not
+include this console.
+
+Input remains Python with dollar commands: `$hostname` executes a command,
+`print($.stdout)` reads its result, and variables persist between inputs.
+`exit`/`exit()` leave one layer; `quit`/`quit()` close all layers. Script
+completion uses `$.stop()`; `$.exit()`, `Session.exit()` and wrapper `.exit()`
+are removed. These incompatible 6.0 rules do not describe stable 5.0.0.
+
+## Share one URL
+
+The website entry is [SSHScript for AI Agents](https://iapyeh.github.io/sshscript/v3a/ai-agents/).
+Users can give that URL and a task to an agent:
+
+> Read the SSHScript AI agent entry at
+> https://iapyeh.github.io/sshscript/v3a/ai-agents/ and follow its reading order.
+> Check the SSHScript version in my environment before selecting APIs. Help me
+> complete this task: [describe the task, target hosts and expected output].
+> If you cannot read a required document, report that limitation rather than
+> guessing its contents. Explain the proposed commands before execution and
+> stay within the operations I authorize.
+
+A URL supplies reference material for the current task. It does not install
+SSHScript, install a skill, grant execution permission, or guarantee persistent
+memory. An agent needs URL-reading tools, or the user must provide the files.
+
+## Set up before you have a task
+
+Users can also give an agent this prompt before requesting any automation.
+It requests a complete skill installation and a reusable preference where the
+agent supports them; downloading only `SKILL.md` omits the reference files.
+
+```text
+Read https://iapyeh.github.io/sshscript/v3a/ai-agents/ and the Agent Guide to
+understand SSHScript's purpose, APIs and execution limits.
+
+If you support installing skills, download the complete skill bundle linked
+on that page, install it using your environment's skill mechanism, and confirm
+that it can be loaded. If skills are unsupported, use that page as a reference
+entry for future SSHScript tasks.
+
+If you support persistent preferences or memory, save this preference:
+For future local or remote command execution, automation and interactive shell
+tasks, first assess whether SSHScript is suitable. Use it according to the
+documentation when appropriate; if another tool is more suitable, explain why.
+
+For now, only read the documentation and configure the skill and preference.
+Do not connect to remote hosts or run demonstration commands. Report whether
+the skill was installed and loaded and whether the preference was saved.
+Explain any limitations or steps that could not be completed.
+```
+
+Use the agent's own installation and preference mechanisms. Installation paths
+and invocation syntax vary by agent. If it needs user approval for a setup step,
+it should request that approval before proceeding. Reading a URL alone does
+not create persistent memory or authorize later command execution.
+
+## Maintain the source and website
+
+Maintain this entry, `skills/sshscript/SKILL.md`, and its reference guide in
+the designated `working_branch` checkout on branch `working_branch`.
+The landing page is maintained in `gh-pages/v3a/ai-agents/index.md` on branch
+`gh-pages`. The API guide remains authoritative for public behavior.
+
+From `working_branch`, synchronize the generated website guide, plain-text
+files and portable skill ZIP with:
+
+```sh
+python3 tools/sync_ai_docs.py ../gh-pages/v3a
+python3 tools/sync_ai_docs.py ../gh-pages/v3a --check
+```
+
+The ZIP includes the skill and its reference guide, plus snapshots of
+`API_GUIDE.md` and `VERSIONING.md` for offline use. These snapshots are generated
+from the source documents; do not edit the ZIP or generated website copies.
+The sync command checks the destination branch before writing. Website pages
+keep their Last Updated timestamp aligned with their mtime.
+
+When the execution contract changes, review the skill and guide, update their
+contract labels and the landing page, then regenerate the website assets.
+Validate links, skill structure, example behavior, source/ZIP equality and
+the rendered website. Source and website publishing are separate operations;
+copying files does not publish either of them.
+
+*Last modified: 2026-10-22 23:24:55*

{sshscript-4.0.2 → sshscript-6.0.0}/API_GUIDE.md

@@ -1,8 +1,8 @@
 # Recommended SSHScript API
 
 This is the canonical entry point for new code and AI-generated examples.
-**Current contract: 4.0.2**, Python 3.11+. Sections marked **4.0** require
-SSHScript 4.0.2; installing `sshscript==3.1.5` does not provide them.
+**Current source contract: 6.0.0**, Python 3.11+. Sections marked **4.0** require
+SSHScript 4.0.2 or newer; installing `sshscript==3.1.5` does not provide them.
 Examples labelled 3.1.5 remain verified compatibility examples for that baseline.
 Pin the exact artifact version and record it with execution diagnostics when
 handing off automation. See [version policy and migration](VERSIONING.md).
@@ -31,7 +31,8 @@ identifiers and handoff reports are future work, not a current API guarantee.
 
 ## One command, one retained result (4.0; compatible with 3.1.5)
 
-Install the current release with `python -m pip install "sshscript==4.0.2"`.
+For this source contract, install a verified 6.0.0 wheel. Once published, pin
+`sshscript==6.0.0`; the source push does not itself upload a PyPI package.
 For reproducing only the historical compatibility baseline, explicitly install
 `sshscript==3.1.5`; the 4.0 sections require the current release.
 An argv list is one command, not a batch. Shell-looking argument text stays data.
@@ -88,6 +89,139 @@ with closing(Session()) as local:
         print(result.stdout)
 ```
 
+### Private-key paths and nested connections
+
+`parent.connect(..., pkey_path=path)` loads an RSA private key from the
+**calling parent Session's host**. A local Session reads the file on localhost;
+a Session connected to host1 reads it on host1 through SFTP before connecting
+to host2. `connect()` returns a child Session and leaves the parent on its
+original host. Calling the original local Session again therefore still reads
+the key on localhost.
+
+For example, `local.connect("host1", pkey_path="/local/key_rsa")` reads
+`/local/key_rsa` locally and returns `host1`. Then
+`host1.connect("host2", pkey_path="/remote/key_rsa")` reads `/remote/key_rsa`
+on host1. In `.spy`, an inner `with $.connect(...)` uses the outer scope's
+current Session as its parent.
+
+`key_filename=` is forwarded to Paramiko and reads from the local Python
+process's filesystem even for nested connections; it supports additional key
+formats. For an encrypted RSA key, use
+`pkey=parent.pkey(path, password=key_passphrase)` to retain the same host-based
+reading rule. Supplying both `pkey_path` and `pkey` raises `ValueError`.
+See the [agent guide's complete nested example](https://iapyeh.github.io/sshscript/v3a/ai-agents/guide/#ssh-connections-and-private-key-paths).
+
+<a id="host-key-sources-unreleased"></a>
+
+### Host-key sources (5.0)
+
+This section requires SSHScript 5.0.0 or newer.
+`known_hosts` selects the host-key trust source independently of `policy`:
+
+| Value | Sources, in order |
+| --- | --- |
+| `"parent"` (new default) | Only the calling Session's host |
+| `"local"` | Only the root localhost Session |
+| `"chain"` | Calling Session, then each ancestor through localhost |
+
+For localhost → host1 → host2 → host3, `host2.connect("host3",
+known_hosts="chain")` consults host2, host1, then localhost. The nearest source
+with a record for the resolved target hostname and port is authoritative.
+A matching key is accepted; a changed key is rejected even if a more distant
+source matches. Only absence of a target record permits continuing the chain.
+Different key algorithms do not permit falling back to another source.
+
+Each source reads its own `known_hosts_path`, or `~/.ssh/known_hosts` if unset.
+Remote files are read over SFTP as that Session's original SSH login account;
+SSH handshakes, user authentication and host-key verification still run in the
+local Python process. Neither sudo/su nor a nested connection changes the SFTP
+account. Remote `~/` paths refer to the login account's SFTP home; `~user` paths
+are unsupported. Relative remote paths use the SFTP working directory.
+
+```py
+local.set(known_hosts="chain")
+# After connecting to host1 and host2:
+host1.set(known_hosts_path="/home/ops/.ssh/known_hosts")
+host2.set(known_hosts_path="/etc/ssh/ssh_known_hosts")
+with host2.connect("deploy@host3", pkey_path="/home/ops/.ssh/host3_rsa") as host3:
+    result = host3.exec_command(["hostname"], check=True, command_timeout=10)
+```
+
+The strategy is inherited by future child Sessions; the path is host-specific
+and is **not inherited**. `known_hosts_path=None` restores the standard path.
+A `connect(known_hosts=...)` override affects only that connection; it does not
+change the parent setting or the child's inherited strategy. `set()`, `get()`
+and matching properties expose both settings. `known_hosts_path` accepts text
+paths and `PathLike[str]`; it is a Session setting, not a `connect()` keyword.
+
+`pkey_path` always reads only from the calling Session's host, including with
+`known_hosts="chain"`; private keys are never searched through ancestors.
+
+An absent trust file, permission failure, read failure, invalid UTF-8 or invalid
+entry raises an error; no distant source or permissive policy bypasses it.
+Empty files, comments, plain host-key entries (including comma-separated names)
+and hashed hostnames are supported. OpenSSH markers such as `@cert-authority`
+and `@revoked`, wildcard/negated host patterns and unsupported key types raise
+an error rather than being silently ignored. A source file is fully parsed
+before its records are used. Nonstandard ports use `[hostname]:port` records.
+
+When every selected source lacks the target, `policy` handles the unknown key.
+`AutoAddPolicy` accepts it into the new client's memory only; these trust files
+are read-only and are not automatically updated locally or remotely.
+
+**Migration from 4.0.2:** earlier releases always load localhost host keys. The new default
+`"parent"` makes nested host-key sources consistent with `pkey_path`. To retain
+the previous behavior, set `local.set(known_hosts="local")` before connecting.
+All strategies require a readable, valid file, including the default localhost
+path. Unlike 4.0.2, a missing local file is an error; create an empty
+file if the configured missing-key policy should handle unknown hosts.
+
+### Private keys readable only in a privileged console
+
+Remote `pkey()` and `pkey_path` use SFTP with the original SSH login account.
+Entering `sudo()` or `su()` does not change that identity, so even
+`$.pkey("/root/.ssh/id_rsa")` inside a root console can fail with a permission
+error. When authorized, read the file with a console command and construct
+the Paramiko key from its captured text:
+
+This manual example requires a real privileged console and SSH endpoints;
+it is excluded from credential-free executable examples.
+
+```py
+from contextlib import closing
+from io import StringIO
+import paramiko
+from sshscript import Session
+
+with closing(Session()) as local:
+    with local.connect("ops@host1.example.net", timeout=10,
+                       banner_timeout=10, auth_timeout=10) as host1:
+        with host1.sudo() as root:
+            key_result = root("cat /root/.ssh/id_rsa", check=True, command_timeout=10)
+            key = paramiko.RSAKey.from_private_key(StringIO(key_result.stdout))
+        with host1.connect("deploy@host2.example.net", pkey=key, timeout=10,
+                           banner_timeout=10, auth_timeout=10) as host2:
+            result = host2.exec_command(["hostname"], check=True, command_timeout=10)
+            print(result.stdout)
+```
+
+The example requires authorized sudo/SSH access and verified host keys.
+Configure output logging/display to keep private-key text out of logs before
+running the read; do not print or report `key_result` or its stdout. Key text
+also remains in console buffers. Use the matching Paramiko key class for
+other formats; encrypted RSA keys need `password=` on `from_private_key()`.
+An authorized `su()` console can supply the text in the same way.
+
+The console returned by `shell()`/`sudo()`/`su()`/`enter()` has no `connect()`
+method, so `$.connect()` is unavailable while a console is current in `.spy`.
+A retained Python Session can still call `connect()` during an active console;
+the connection uses its original SSH transport and does not inherit console
+privilege. The example leaves the console first and calls the retained
+`host1.connect(pkey=key)`, which needs no SFTP key read. See the
+[agent guide's `.spy` equivalent](https://iapyeh.github.io/sshscript/v3a/ai-agents/guide/#keys-readable-only-after-sudosu).
+
+### Optional dollar syntax
+
 Save dollar syntax as `.spy`, run with `sshscript file.spy`, and syntax-check
 without execution using `sshscript --check file.spy`.
 
@@ -101,7 +235,7 @@ print(result.stdout)
 
 ## 4.0: settings and managed jobs
 
-Use SSHScript 4.0.2 for the following examples. CLI `-v`, `--stderr`, and
+Use SSHScript 6.0.0 for the following examples. CLI `-v`, `--stderr`, and
 `--debug` override root defaults only for that execution. Child Sessions copy
 their parent's settings. `set()` validates before changing anything; `get()`
 returns a copy. Explicit command options override Session policy.
@@ -120,7 +254,7 @@ the settings dictionary at creation; the policy object itself is shared, so
 custom policies with mutable state must account for reuse. Changing the setting
 does not reconfigure existing connections.
 
-<!-- example: {"id":"settings", "profile":"4.0.2", "stdout":"True\n1\n"} -->
+<!-- example: {"id":"settings", "profile":"6.0.0", "stdout":"True\n1\n"} -->
 ```python
 from contextlib import closing
 import paramiko
@@ -142,7 +276,7 @@ semantics; do not combine it with `command_timeout`.
 For an indefinite command such as tcpdump, use `start(timeout=None)`. This safe
 local example uses a small Python process instead of capturing network traffic:
 
-<!-- example: {"id":"stop", "profile":"4.0.2", "stdout":"cancelled confirmed\n"} -->
+<!-- example: {"id":"stop", "profile":"6.0.0", "stdout":"cancelled confirmed\n"} -->
 ```python
 from contextlib import closing
 import sys
@@ -181,7 +315,7 @@ legacy SSH behavior which appended a newline to strings: if a consumer
 needs a line, migrate `input=password` to `input=password + "\n"` explicitly.
 Published 3.1.5 still has the legacy SSH behavior.
 
-<!-- example: {"id":"exact-stdin", "profile":"4.0.2", "stdout":"'abc'\n'abc\\n'\n"} -->
+<!-- example: {"id":"exact-stdin", "profile":"6.0.0", "stdout":"'abc'\n'abc\\n'\n"} -->
 ```python
 from contextlib import closing
 import sys
@@ -250,7 +384,7 @@ or unpack exactly `stdout, stderr, exitcode`. This changes the released 3.1.5
 console contract: old `stdout, stderr = shell(command)` must be migrated.
 Shell calls accept command strings; argv execution belongs to Session.
 
-<!-- example: {"id":"shell-result", "profile":"4.0.2", "stdout":"first 0\n"} -->
+<!-- example: {"id":"shell-result", "profile":"6.0.0", "stdout":"first 0\n"} -->
 ```python
 from contextlib import closing
 from sshscript import Session
@@ -306,7 +440,7 @@ matching: `iter_stdout()` yields chunks, not packets or lines. Put `stop()` in
 `finally`, so condition matches, exceptions, and KeyboardInterrupt all trigger
 cleanup. This credential-free example uses a continuous Python process:
 
-<!-- example: {"id":"stream-condition", "profile":"4.0.2", "stdout":"cancelled confirmed\n"} -->
+<!-- example: {"id":"stream-condition", "profile":"6.0.0", "stdout":"cancelled confirmed\n"} -->
 ```python
 from contextlib import closing
 import sys
@@ -371,7 +505,7 @@ the current Bash console's channel, cwd, environment and identity. It does not
 launch through the underlying Session. Ordinary `console(command)` / `$command`
 still waits and returns `CommandResult`; no migration is needed for finite commands.
 
-<!-- example: {"id":"console-stream", "profile":"4.0.2", "stdout":"cancelled confirmed\nconsole-alive\n"} -->
+<!-- example: {"id":"console-stream", "profile":"6.0.0", "stdout":"cancelled confirmed\nconsole-alive\n"} -->
 ```python
 from contextlib import closing
 import shlex
@@ -511,7 +645,7 @@ remains available for other authentication prompt formats.
 These transcripts require a real local account and its authentication policy;
 they are manual examples, separate from the credential-free CI examples above.
 Read passwords with `getpass` rather than storing them in the script. The new
-behavior requires 4.0.2 and does not apply to the installed 3.1.5 release.
+behavior requires 4.0.2 or newer and does not apply to the installed 3.1.5 release.
 
 Open a root console through sudo and allow up to 15 seconds for entry:
 
@@ -629,3 +763,23 @@ host prerequisites and are not credential-free examples.
 The same source is mirrored into the website; edit this file, then use
 `tools/sync_api_guide.py` to refresh the website copy. Additional protocol and
 production details remain in the full documentation.
+
+
+## Interactive console and script completion (6.0)
+
+See [the console guide](CONSOLE.md) for the 6.0 Python-first dollar REPL, retained
+variables, connect/sudo/su layers, text programs and migration from 5.0.0.
+Ordinary input is Python; `$hostname` runs a shell command and `print($.stdout)`
+reads its result. No language-mode switching is needed.
+Bare `exit` and `exit()` leave one managed layer, or close the console at the
+local root. Bare `quit` and `quit()` close the whole console.
+Use `help` or `help()` for console instructions and `help(object)` for Python
+object documentation.
+`$.stop(code=0, message="")` normally completes the nearest script runner;
+`$.exit()`, `Session.exit()` and wrapper `.exit()` are removed in both modes,
+as is the old `$.break()` name. Session.run()/run_script() return a dictionary-like
+ScriptResult with exitcode, stopped and message attributes; run_file() returns
+the integer status. Cleanup failures still propagate. Python SystemExit remains
+separate from normal script completion.
+
+*Last modified: 2026-10-22 23:24:55*

{sshscript-4.0.2 → sshscript-6.0.0}/CHANGELOG.md

@@ -1,8 +1,47 @@
 # Changelog
 
+## 6.0.0 — 2026-10-22 (incompatible source contract)
+
+- Add console helpers: help/help(), help(object), exit/exit() to leave one
+  managed layer, and quit/quit() for complete cleanup and termination.
+- Ctrl-C discards input or interrupts execution while preserving console state;
+  Ctrl-D at the Python prompt quits. Inside enter(), both keys are sent as raw
+  program control characters, with parent-shell return detected before unwinding.
+
+- Add `sshscript console`: a Python REPL with dollar syntax, persistent Bash
+  shells, retained variables and command-result snapshots,
+  automatic shell entry after connect, sudo/su layers, explicit text-program
+  entry, streaming command output and managed Ctrl-C recovery.
+- Replace `$.break()` with `$.stop()`. Normal completion is handled by the
+  nearest script/import boundary and preserves cleanup and partial names.
+- Remove `$.exit()`, Session.exit() and wrapper .exit() in both console and
+  script mode. Existing script-ending calls must become stop() or Python
+  sys.exit(). Remove the old SSHScriptBreak/SSHScriptExit control exceptions
+  and partial wrapper exit.
+- Return dictionary-like ScriptResult completion metadata from source runners;
+  preserve integer completion status from run_file().
+- Enable terminal line editing, including both Backspace control codes, when
+  Python readline support is available.
+- See [console usage](CONSOLE.md) and [6.0 migration](VERSIONING.md#60-console-and-script-completion-migration).
+  Source and local artifacts use 6.0.0. PyPI publication and release tags are
+  separate operations.
+
+
 This project records user-visible changes here. Release artifacts and their
 provenance are available from the linked GitHub Release and PyPI pages.
 
+## 5.0.0 — 2026-10-10
+
+- Add `known_hosts="parent"` (new default), `"local"` and `"chain"` strategies.
+  Nested connections now use the calling host's trust file by default, matching
+  `pkey_path` ownership. Set `known_hosts="local"` for previous behavior.
+- Add per-Session `known_hosts_path` without path inheritance. Chain lookup uses
+  the nearest target record; changed keys and read/parse errors never fall back.
+  Authentication and verification still run locally; trust files are read-only.
+- Isolate connection-timeout tests from runner HOME and verify client cleanup.
+- Document host-key source selection, strict file errors and migration in the
+  API, website and portable AI agent skill.
+
 ## 4.0.2 — 2026-10-09
 
 - Align the README, current installation commands, website title, navigation,
@@ -274,3 +313,5 @@ verified artifacts in the
 
 [Unreleased]: https://github.com/iapyeh/sshscript/compare/v3.1.4...release
 [3.1.4]: https://github.com/iapyeh/sshscript/releases/tag/v3.1.4
+
+*Last modified: 2026-10-22 23:24:55*

sshscript-6.0.0/CONSOLE.md

@@ -0,0 +1,208 @@
+# Interactive console (6.0)
+
+The SSHScript 6.0 console runs from the flat development checkout:
+
+```sh
+python3 -B sshscript.py console
+```
+
+Use Python 3.11 or newer with the project's dependencies. An installed 6.0.0
+wheel provides `sshscript console`. Published 5.0.0 lacks this feature; this
+source version update does not upload a package. No installation into the
+development checkout is required.
+
+## A Python console with dollar syntax
+
+Input is Python by default, with SSHScript dollar syntax available in the same
+namespace. No Python/shell language-mode switching is required:
+
+```text
+local [user]> hostname
+NameError: name 'hostname' is not defined
+local [user]> hostname = "a Python variable"
+local [user]> hostname
+'a Python variable'
+local [user]> $hostname
+my-host
+local [user]> print($.stdout)
+my-host
+local [user]> actual_hostname = $.stdout.strip()
+local [user]> options = {"port": 2222, "username": "ops", "timeout": 15}
+local [user]> $.connect("my-ssh-alias", **options)
+```
+
+`hostname` reads a Python variable; `$hostname` executes a command. A shell
+command always needs its dollar prefix. `$cd /tmp` and `$export NAME=value`
+retain the shell's directory and environment for later dollar commands. Output
+streams while a command runs; a nonzero exit status is displayed and the console
+remains usable. Shell commands do not display an extra JobResult representation.
+
+`$.stdout`, `$.stderr` and `$.exitcode` read the most recent dollar-command result
+in the current managed layer. These are result snapshots, not drained live
+buffers. The `result` Python name retains the latest dollar-command JobResult.
+You can mix dollar properties with Python expressions and f-strings, or unpack
+command results using the normal `.spy` syntax:
+
+```text
+local [user]> out, err, status = $printf ready
+local [user]> summary = f"host={$.stdout.strip()}, status={$.exitcode}"
+local [user]> for index in range(2):
+...     $f"echo item-{index}"
+...
+```
+
+On a terminal, the console enables Python's optional `readline` module for line
+editing, including Backspace. Python builds without that module retain the
+terminal's basic input editing; piped input does not require it. No history file
+is written.
+
+As in Python's REPL, a blank line completes an indented block. Parenthesized
+expressions and parameter dictionaries can span multiple input lines. Functions
+and variables remain available for later inputs. Ordinary Python strings that
+contain dollar characters remain literal strings. `with` blocks use the normal
+`.spy` compiler's lexical context management, rather than leaving a managed
+interactive layer open after the block. Inside lexical contexts, inspect or
+print returned command output explicitly, just as in a script.
+
+Reserved names are `control`, `session` (current connection Session), `console`
+(current shell/identity/program), `result` and `error` (latest operation error).
+`session` and `console` are refreshed when environments change. User variables
+survive environment changes; references to exited environments are not reusable.
+`getpass` is provided for reading secrets without terminal echo. No input history
+is saved by SSHScript; host terminal/session recording remains external.
+
+## Connections and identities
+
+A connection automatically enters its own persistent Bash shell. One `exit()`
+closes that shell and connection together and restores the parent environment.
+Nested connections are created by the current connection Session. They retain
+the existing SSH config, key ownership and known-host verification contracts.
+
+```sh
+python3 -B sshscript.py console ops@host1 --port 2222 --timeout 15
+python3 -B sshscript.py console my-ssh-alias --ask-pass
+```
+
+CLI options include `--username`, `--port`, `--pkey-path`, `--timeout`,
+`--ssh-config`, `--known-hosts`, `--known-hosts-path` and `--ask-pass`.
+For interactive parameter dictionaries, use the normal Session.connect keyword
+names. Configure a custom trust path with `$.set(known_hosts_path="...")` on the
+calling Session before connecting. Never disable host-key verification merely
+to make a connection succeed.
+
+```text
+host1 [ops]> $.sudo(password=None)
+host1 [root]> $.su("postgres", password=None)
+host1 [postgres]> exit()
+host1 [root]> exit()
+host1 [ops]> exit()
+local [user]>
+```
+
+Omitting an authentication password asks through getpass in a terminal. Use
+`password=None` explicitly for passwordless authentication; nonterminal input
+requires an explicit password argument rather than an invisible password read.
+You can also set a variable with `password = getpass("Password: ")` in Python and reference it in an expression. Do not place real secrets in literal
+commands or shared transcripts.
+
+The displayed account is queried after entering the environment, not assumed
+from the requested account. `:status` shows all environment layers. File
+transfers retain the SSH connection account's permissions even inside sudo/su.
+The console rejects connect() from explicit sudo/su/shell/program layers: leave
+that layer first. Elevating a console does not change the Session's SSH
+credentials or the account owning its SFTP/key-file reads.
+
+## Text programs and interruption
+
+Use explicit enter() for a program that asks questions or provides a REPL:
+
+```text
+local [user]> $.enter("python3 -q -u", prompt=">>>", exit="quit()")
+local [?] program> print(6 * 7)
+42
+local [?] program> exit()
+local [user]>
+```
+
+Configure the program's actual readiness prompt and exit sequence. Plain input
+in this layer goes to the program; `exit`, `exit()`, `quit`, `quit()`, lines
+beginning with `$.` and the colon management commands remain reserved. Use
+`$.input(...)` or `$.send(...)` to send text that would otherwise be interpreted as a management expression.
+Ctrl-C/Ctrl-D go to the entered program. In particular, Ctrl-D in an entered
+Python REPL exits that REPL and restores the SSHScript prompt, rather than
+closing the entire SSHScript console. Outside enter(), Ctrl-C requests managed
+shell cancellation or interrupts Python code. An interrupted Python multiline
+input is discarded. A failed/unusable channel
+is removed from the environment stack; the console never silently reconnects
+and claims that the previous state survived. At the Python prompt, use
+`exit` or `exit()` to leave a layer. If a text program returns to its parent
+shell and that return is detected, its program layer is closed automatically.
+
+This console supports text commands and explicitly configured text programs,
+not full-screen applications or transparent terminal passthrough. Dollar shell
+commands do not automatically detect interactive programs; use enter() for them.
+Command results retain up to 8 MiB per stream; reaching that capture limit is
+reported and the displayed stream may omit output. PTY stdout/stderr can merge.
+Readiness or silence is not interpreted as a successful process exit.
+
+## Stop a script, leave a layer, or quit
+
+- `$.stop(code=0, message="")` normally completes the nearest script execution.
+  It is unavailable at the console prompt itself.
+- Bare `exit` and `exit()` leave one managed interactive layer. At the local
+  root they close the console. These are console helpers, not script APIs.
+- Bare `help` or `help()` displays console instructions; `help(object)` retains
+  Python's object documentation behavior.
+- Bare `quit` and `quit()` close every managed layer. Calling `exit()` or
+  `quit()` unwinds the current Python cell, including `finally`/lexical contexts,
+  before performing the requested cleanup.
+- Ctrl-C at a Python prompt discards the pending input. During Python execution
+  it interrupts that code; during a shell command it requests managed cancellation.
+  Variables and usable environments remain available afterward.
+- Ctrl-D/EOF at the Python prompt closes all layers, like quit(). In a terminal,
+  EOF is produced by Ctrl-D on an empty input line; partial-line behavior follows
+  the terminal's normal line editing.
+- In an enter() program, Ctrl-C/Ctrl-D are forwarded as raw terminal control
+  characters, without an added newline. Only a detected return to the parent
+  shell closes that program layer; the Python console stays available.
+- `:help` and `:quit` remain aliases; `:status` shows the environment stack.
+  The Python helper names can be shadowed by assignment, just like Python names;
+  the colon aliases and `control.quit()` remain available.
+- Python `sys.exit()` retains SystemExit semantics. The interactive boundary
+  catches it, reports its status and keeps the console open.
+
+The console intentionally gives `exit` and `exit()` the same one-layer behavior.
+Use `quit` or `quit()` for all layers, and `$.stop()` for normal script
+completion. `$.exit()` is removed in both console and script mode.
+
+`script_result = $.run(source)` executes in the current connection Session; it
+does not inherit an elevated console as its command target. `$.run_file(path)` uses the public
+file runner, which creates a fresh local Session. A stopped script returns to
+the console. Assign its returned ScriptResult to inspect completion and names;
+script results do not automatically replace the console's Python namespace.
+`with` and `finally` still perform cleanup on early completion.
+
+`Session.run()` and `run_script()` return ScriptResult, a dictionary of executed
+names with `.exitcode`, `.stopped` and `.message` attributes. `run_file()` returns
+the integer completion status. A stopped imported `.spy` module keeps the names
+initialized before stop(), and its importer continues normally. Cleanup failures
+remain errors even if the script requested normal completion.
+
+## Incompatible changes from 5.0.0
+
+Replace `$.break(...)` with `$.stop(...)`. Replace script-ending `$.exit(...)`
+with `$.stop(...)` for normal completion, or Python `sys.exit(...)` when the
+caller should receive SystemExit. The old Break/Exit exception classes and the
+old direct wrapper exit behavior are removed. `$.exit()`, `Session.exit()`
+and wrapper `.exit()` are no longer available. In the console, use `exit` or
+`exit()` to leave one managed layer. In scripts, let Python manage lexical
+`with` blocks. The earlier preview's bare-exit reminder and whole-console
+`exit()` behavior are replaced by this one-layer rule.
+
+The initial shell-first preview's `:python` and `:shell` commands are removed.
+Input now follows Python/dollar syntax throughout; prefix shell commands with `$`.
+
+Type `help` for a reminder. Operation failures display their type without
+reprinting credential-bearing input; inspect `error` at the prompt for details.
+
+*Last modified: 2026-10-22 23:24:55*

{sshscript-4.0.2 → sshscript-6.0.0}/MANIFEST.in

@@ -1,4 +1,7 @@
 include README.md LICENSE.txt RELEASING.md
+include AI_GUIDE.md
+include skills/sshscript/SKILL.md
+include skills/sshscript/references/agent-guide.md
 include CHANGELOG.md CODE_OF_CONDUCT.md CONTRIBUTING.md EXCEPTIONS.md SECURITY.md SUPPORT.md
 recursive-include tools *.py
 include tools/setup_openssh_ci.sh
@@ -54,3 +57,6 @@ include API_GUIDE.md VERSIONING.md
 include src/sshscript/unittest/test_version_policy.py
 include src/sshscript/py.typed
 recursive-include src/sshscript *.pyi
+
+include src/sshscript/unittest/test_interactive_console.py
+include CONSOLE.md