sshscript 6.0.0__tar.gz → 6.1.0__tar.gz

{sshscript-6.0.0 → sshscript-6.1.0}/.github/workflows/ci.yml

@@ -4,7 +4,7 @@ permissions:
   contents: read
 jobs:
   verify:
-    timeout-minutes: 20
+    timeout-minutes: 30
     strategy:
       fail-fast: false
       matrix:
@@ -48,7 +48,7 @@ jobs:
   openssh-integration:
     name: OpenSSH integration (Python ${{ matrix.python-version }}, ${{ matrix.dependency-label }})
     runs-on: ubuntu-latest
-    timeout-minutes: 25
+    timeout-minutes: 35
     strategy:
       fail-fast: false
       matrix:

{sshscript-6.0.0 → sshscript-6.1.0}/.github/workflows/release.yml

@@ -12,7 +12,7 @@ jobs:
   build:
     name: Verify and attest release artifacts
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    timeout-minutes: 30
     permissions:
       contents: read
       id-token: write

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

@@ -121,3 +121,5 @@ htmlcov/
 !/unittest/test_update_check.py
 
 !/unittest/test_interactive_console.py
+
+!/unittest/test_embedded_console.py

{sshscript-6.0.0 → sshscript-6.1.0}/AI_GUIDE.md

@@ -1,10 +1,9 @@
 # SSHScript for AI agents
 
-**Documentation contract: SSHScript 6.0.0; Python 3.11+.**
+**Documentation contract: SSHScript 6.1.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.
+This guide targets SSHScript 6.1.0 and its public Console integration API.
+Install `sshscript==6.1.0` and verify the imported package version.
 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.
 
@@ -19,14 +18,22 @@ workflow. Its folder contains the supporting guide; copy the entire
 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)
+## Borrowed Session integration (unified Console API)
+
+Use `from sshscript import Console` and `with Console(existing_session)` for an
+existing authorized connection. Read [the full host contract](EMBEDDED_CONSOLE.md)
+before driving it. Require structured completion/exit status and confirmed reuse;
+keep host account policy and credentials in the resolver. A prompt/silence is not
+a success signal. See the bundled skill for the matching agent guidance.
+
+## Interactive console (6.1)
 
 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).
+[console instructions](skills/sshscript/references/agent-guide.md#interactive-console-61).
 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.
+an installed 6.1.0 wheel provides `sshscript console`. Use public
+Console(session) for host integration; older 6.0 console internals are removed.
 
 Input remains Python with dollar commands: `$hostname` executes a command,
 `print($.stdout)` reads its result, and variables persist between inputs.
@@ -109,4 +116,4 @@ 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*
+*Last modified: 2026-10-23 18:39:31*

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

@@ -1,7 +1,7 @@
 # Recommended SSHScript API
 
 This is the canonical entry point for new code and AI-generated examples.
-**Current source contract: 6.0.0**, Python 3.11+. Sections marked **4.0** require
+**Current release contract: 6.1.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
@@ -31,8 +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)
 
-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.
+Install `sshscript==6.1.0` for this contract. Verify the installed version and
+artifact before operational use; source publication alone does not install it.
 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.
@@ -235,7 +235,7 @@ print(result.stdout)
 
 ## 4.0: settings and managed jobs
 
-Use SSHScript 6.0.0 for the following examples. CLI `-v`, `--stderr`, and
+Use SSHScript 6.1.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.
@@ -254,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":"6.0.0", "stdout":"True\n1\n"} -->
+<!-- example: {"id":"settings", "profile":"6.1.0", "stdout":"True\n1\n"} -->
 ```python
 from contextlib import closing
 import paramiko
@@ -276,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":"6.0.0", "stdout":"cancelled confirmed\n"} -->
+<!-- example: {"id":"stop", "profile":"6.1.0", "stdout":"cancelled confirmed\n"} -->
 ```python
 from contextlib import closing
 import sys
@@ -315,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":"6.0.0", "stdout":"'abc'\n'abc\\n'\n"} -->
+<!-- example: {"id":"exact-stdin", "profile":"6.1.0", "stdout":"'abc'\n'abc\\n'\n"} -->
 ```python
 from contextlib import closing
 import sys
@@ -384,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":"6.0.0", "stdout":"first 0\n"} -->
+<!-- example: {"id":"shell-result", "profile":"6.1.0", "stdout":"first 0\n"} -->
 ```python
 from contextlib import closing
 from sshscript import Session
@@ -440,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":"6.0.0", "stdout":"cancelled confirmed\n"} -->
+<!-- example: {"id":"stream-condition", "profile":"6.1.0", "stdout":"cancelled confirmed\n"} -->
 ```python
 from contextlib import closing
 import sys
@@ -505,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":"6.0.0", "stdout":"cancelled confirmed\nconsole-alive\n"} -->
+<!-- example: {"id":"console-stream", "profile":"6.1.0", "stdout":"cancelled confirmed\nconsole-alive\n"} -->
 ```python
 from contextlib import closing
 import shlex
@@ -765,6 +765,14 @@ The same source is mirrored into the website; edit this file, then use
 production details remain in the full documentation.
 
 
+## Embed an existing Session (unified Console API)
+
+`from sshscript import Console` provides a supported integration surface without
+editing reserved variables. `Console(session)` borrows the connection, while
+`ownership="owned"` explicitly transfers ownership. Read the complete
+[API and lifecycle contract](EMBEDDED_CONSOLE.md) for structured updates,
+credentials, identity, PTY limits, exceptions and runnable examples.
+
 ## Interactive console and script completion (6.0)
 
 See [the console guide](CONSOLE.md) for the 6.0 Python-first dollar REPL, retained
@@ -782,4 +790,4 @@ 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*
+*Last modified: 2026-10-23 18:39:31*

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

@@ -1,5 +1,28 @@
 # Changelog
 
+## 6.1.0 — 2026-10-23
+
+- Add public `Console(existing_session)` for terminal and host/AI-agent interaction
+  over an existing Session, including target Sessions reached through jumps,
+  without reconnecting or changing authentication/host-key sources.
+- Retain Python variables, shell cwd/environment and interactive program state.
+  Expose structured submit/poll/input/interrupt/EOF and completion results.
+- Add account credential/policy and switch-result hooks, separate connection login
+  identity from effective shell identity, and expose the environment stack.
+- Borrow Sessions by default. Unwind console-owned layers and confirm Session
+  reuse; initialization/restoration/cleanup failures report unknown explicitly.
+- Fix lost prompt readiness after program Ctrl-C. Keep waiting_input after a
+  protocol match, running for ignored/unfinished interrupts, and real exit status
+  for exiting programs; support delayed prompt recovery through poll.
+- Use one Console implementation for CLI and embedding. Remove old internal
+  InteractiveConsole/open()/execute() entry points and :help/:quit aliases; use
+  Console(session), submit(), help/quit and structured status instead.
+- Add complete terminal/agent examples and the matching AI skill. OpsFeast reports
+  local/simulated and browser UI revalidation passed. This is distinct from real
+  SSH/jump/PAM/su/sudo validation; release CI records its own disposable native tests.
+- Development-stage releases do not guarantee backward compatibility unless
+  explicitly requested. Minor releases may include the differences listed above.
+
 ## 6.0.0 — 2026-10-22 (incompatible source contract)
 
 - Add console helpers: help/help(), help(object), exit/exit() to leave one
@@ -314,4 +337,4 @@ 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*
+*Last modified: 2026-10-23 18:39:31*

{sshscript-6.0.0 → sshscript-6.1.0}/CONSOLE.md

@@ -1,16 +1,24 @@
-# Interactive console (6.0)
+# Interactive console (6.1)
 
-The SSHScript 6.0 console runs from the flat development checkout:
+The SSHScript 6.1 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
+Use Python 3.11 or newer with the project's dependencies. Install
+`sshscript==6.1.0` for `sshscript console`. No installation into the flat
 development checkout is required.
 
+## Embed an existing Session (new API)
+
+Use the public `sshscript.Console` API for borrowed Sessions, host-driven updates,
+credential hooks and explicit cleanup/reuse reporting. Read
+[the embedded console contract](EMBEDDED_CONSOLE.md) and its executable examples.
+The CLI uses the same Console core and ownership contract. Earlier 6.0 CLI
+compatibility is not maintained; see the linked contract for removed entry points
+and aliases. This guide describes the 6.1.0 release contract.
+
 ## A Python console with dollar syntax
 
 Input is Python by default, with SSHScript dollar syntax available in the same
@@ -18,7 +26,7 @@ namespace. No Python/shell language-mode switching is required:
 
 ```text
 local [user]> hostname
-NameError: name 'hostname' is not defined
+NameError: operation failed; inspect error for details.
 local [user]> hostname = "a Python variable"
 local [user]> hostname
 'a Python variable'
@@ -165,7 +173,8 @@ Readiness or silence is not interpreted as a successful process exit.
 - 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.
+- Use `help`/`help()` and `quit`/`quit()`. The former `:help` and `:quit` aliases
+  are removed; `: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
@@ -205,4 +214,4 @@ 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*
+*Last modified: 2026-10-23 18:39:31*

sshscript-6.1.0/EMBEDDED_CONSOLE.md

@@ -0,0 +1,200 @@
+# Unified Console API
+
+**Contract: SSHScript 6.1.0; Python 3.11+.**
+
+Design and lifecycle contract, written before implementation.
+
+`from sshscript import Console` exposes the shared Python/dollar console
+on an existing `Session`. `Console(session, ownership="borrowed")` opens only a
+new Bash channel, without connect(), authentication or Session settings changes.
+Jump connections and SSH/SFTP login identity remain owned by the caller.
+`ownership="owned"` explicitly transfers the supplied Session (and its children,
+not its ancestors) to the console. Ownership begins at construction, including
+initialization failure. A local Session is also supported.
+
+All calls run on the constructing thread. The caller must serialize console and
+Session use until close. Python evaluation and lexical with blocks are synchronous;
+arbitrary Python cannot be safely preempted. `submit(line)` retains the existing
+compiler and namespace. `start_command(command, timeout=60)` starts the existing
+persistent-shell foreground job; `poll()` reads incremental output without waiting.
+`send_input(text, timeout=...)` replies to an enter() program, appending one newline.
+`send_input(text, newline=False)` sends raw text to an enter() program.
+Shell jobs reject stdin writes: a late write could reach the parent shell after
+the process exits. Use enter() for interactive applications.
+`interrupt()` stops a job with bounded recovery, or sends Ctrl-C to a program;
+otherwise it discards unfinished Python input. After program Ctrl-C, a matched
+program prompt returns `waiting_input` and remains ready across polls, even when
+the protocol has consumed the prompt text. A control-read timeout stays `running`;
+a later prompt can restore readiness through `poll()`. `error_type=KeyboardInterrupt`
+records the interruption attempt, not program completion or failure. If the program
+exits, its restored exit status determines `completed` or `failed`. `eof()` leaves program EOF behavior
+unchanged; at the Python prompt it closes the console. `leave()` exits one layer,
+including the root shell; `close()` unwinds everything. `quit` closes everything.
+Python SystemExit is reported as failed input and leaves the console open.
+A host exception in `with Console(...)` runs cleanup; cleanup failure is never
+suppressed. Initialization failure cleans up the acquired channel.
+
+Immutable `ConsoleUpdate` records carry state, incremental stdout/stderr, a command result,
+safe error type, and Session reuse status. States are `ready`, `incomplete`,
+`running`, `waiting_input`, `completed`, `failed`, `closed`. A nonzero exit status,
+Python/syntax error, deadline expiry or unconfirmed recovery is failure. `completed`
+requires a real job completion record or a restored program exit status, never silence. `waiting_input` means an
+enter() prompt matched the configured program protocol; it is not proof of command
+success. Silent or timed-out interactive reads remain `running`. A generic process
+cannot reveal whether it is waiting for stdin: shell jobs remain `running` until
+completion. Polling does not infer readiness from text.
+For an ordinary Python cell, completed means evaluation returned without an
+uncaught exception. It does not certify side effects or results of arbitrary
+Python calls. The exit-status classification applies to managed dollar jobs,
+start_command() and restored enter() program results; inspect other returned
+Python API results explicitly. Configure enter() prompts
+for text programs; full-screen terminal emulation is unsupported.
+
+`connection` returns the current Session, without changing its login account.
+`environments` returns immutable snapshots with kind, host, connection username,
+effective username and identity verification. Effective names come from `id -un`
+on entry; program layers inherit the last verified name with verification false.
+They are observations, not authorization evidence for subsequent arbitrary Python.
+Leaving a nested layer restores its parent channel; closing the root channel does
+not attempt to preserve that shell's cwd/environment in the Session's later new
+commands. A successful borrowed close additionally probes Session command execution
+with a finite budget; `session_reuse="confirmed"` means cleanup and that probe
+succeeded. `unknown` means the caller must reconcile or discard the connection;
+`closed` means an owned Session was closed. No API can guarantee future network
+availability or remote child-process termination from a channel close alone.
+
+`credential_resolver(SwitchRequest)` runs before every managed su/sudo switch,
+including explicit credentials. It may reject by raising or return
+`SwitchCredentials(password=...)`; None keeps explicit credentials. Request metadata
+contains no password. `switch_observer(SwitchOutcome)` receives success/failure,
+request, resulting environment and safe error type, never credential/error text.
+The resolver implements host configuration, candidate ordering and policy outside
+SSHScript. It is called once per attempted switch; there is no automatic retry.
+A missing password in non-terminal mode raises `CredentialsRequiredError`;
+explicit None requests passwordless authentication. Observer failure propagates;
+a successful switch remains active and is visible for cleanup. Explicit password
+arguments and arbitrary Python error objects are sensitive application memory.
+Do not log input source, namespace/error objects, JobResult.command or arbitrary
+program output containing secrets. Use the resolver rather than literals in input.
+Hooks cover managed Console.su/sudo and prompt-level dollar calls; arbitrary Python,
+raw Session access and lexical script with blocks are trusted code, not a policy
+sandbox. Hosts must restrict supplied code if they need enforced authorization.
+
+`terminal=False` needs no terminal on the Python process. The new shell still uses
+a PTY by default for su/sudo and reliable job interruption. `get_pty=False` supports
+pipe jobs but cannot safely interrupt a running job; recovery can be unknown.
+Programs/password readers may require a PTY. No hidden getpass prompt is used in
+non-terminal mode. `terminal=True` enables the terminal frontend of the same Console core
+and getpass fallback. Captured event streams and terminal streams are separate;
+headless capture is consumed by each returned update. When a custom stdout or
+stderr stream is supplied (or terminal=True selects terminal streams), that
+stream receives the output and the corresponding update output field is empty. Only one console/redirected
+Python execution may run in a process at a time because Python stdout redirection
+is process-global. This API does not provide a Python sandbox or an async Python
+executor.
+
+## One core for CLI and host integration
+
+The CLI and embedding applications use the same public `Console` implementation
+in `interactive.py`. There is no legacy InteractiveConsole class, separate embedded
+subclass, or compatibility module. The CLI creates an explicit owned local Session;
+embedding callers normally borrow the Session they already hold. Both frontends
+use submit(), poll(), interrupt(), eof() and the same cleanup and failure policy.
+The CLI drains foreground $.start() jobs through poll() before reading another line.
+
+Earlier 6.0 CLI behavior is not a compatibility target. Internal open()/execute()
+entry points are removed: construct Console(session) and call submit(line).
+`:help` and `:quit` aliases are removed; use help/help() and quit/quit(). `:status`
+remains the environment-stack command. Diagnostics always omit source and arbitrary
+exception text, including NameError and SystemExit values. A failed channel remains
+owned until cleanup and is reported as unknown; it is not silently popped to an
+apparently healthy parent layer. SSH/SFTP authentication and Session command APIs
+keep their existing responsibilities.
+
+This public API is released in SSHScript 6.1.0. During development, minor releases
+may include incompatible changes; compatibility is required only when explicitly
+requested. Pin the released artifact or record the exact source revision/hash.
+
+## Executable examples
+
+Run from the flat source checkout with `PYTHONPATH=. python3 -B` followed by
+[examples/embedded_agent.py](examples/embedded_agent.py) or
+[examples/embedded_terminal.py](examples/embedded_terminal.py). With the matching
+installed wheel the PYTHONPATH setting is unnecessary. Both examples create only
+local Sessions; `handover(existing_target)` and `drive(existing_target)` also
+accept a host's already-connected target Session, including a jump target.
+
+Terminal handover, followed by reuse:
+
+```python
+from sshscript import Console
+
+def handover(existing_target):
+    with Console(existing_target, terminal=True) as console:
+        console.interact()
+    assert console.session_reuse == "confirmed"
+    return existing_target.exec_command("hostname", check=True)
+```
+
+Non-terminal Python/dollar cells and asynchronous shell output:
+
+```python
+import time
+from sshscript import Console
+
+def drive(existing_target):
+    with Console(existing_target) as console:
+        assert console.submit("value = 42").state == "completed"
+        assert console.submit("$export TASK=value; cd /tmp").state == "completed"
+        update = console.start_command('printf "%s" "$TASK"', timeout=3)
+        while True:
+            consume(update.stdout, update.stderr)  # host callback
+            if update.state != "running":
+                break
+            time.sleep(.03)
+            update = console.poll()
+        if update.state != "completed":
+            raise RuntimeError("command failed: " + str(update.error_type))
+        assert update.result.exitcode == 0
+    return existing_target.exec_command("printf reusable", check=True)
+```
+
+For a text program, call `console.enter("python3 -q -u", prompt=">>>", exit="quit()")`,
+then `console.send_input("print(42)", timeout=2)`. A prompt response produces
+`waiting_input`; program exit restores the parent and supplies `result.exitcode`.
+`poll()` can observe a program's later prompt/exit after a timed-out read or raw
+send. Program results snapshot the final input buffers; retain incremental events
+for the full conversation. Job results snapshot the bounded whole command output.
+`poll()` may perform bounded shell recovery when an enter() program has exited;
+it does not block on a running shell job. Program restoration uses the existing
+console exit budget (up to 60 seconds), unlike immediate job polling.
+
+Credential and policy integration (no host configuration parser in SSHScript):
+
+```python
+from sshscript import Console, SwitchCredentials
+
+def resolve(request):
+    host_policy.require_switch(request.environment.host, request.kind, request.username)
+    # Return None only when keeping an explicit password argument. Returning a
+    # SwitchCredentials object with password=None deliberately tries passwordless.
+    return SwitchCredentials(secret_store.password_for(request.username))
+
+with Console(existing_target, credential_resolver=resolve,
+             switch_observer=audit_switch_metadata) as console:
+    console.su("operator")
+    print(console.environments[-1])
+    console.leave()
+```
+
+The host supplies `consume`, `host_policy`, `secret_store` and
+`audit_switch_metadata`; the linked executable examples need none of these.
+Resolver/observer exceptions from direct method calls propagate. `submit()` reports
+safe error types instead. Cleanup errors always raise `ConsoleCleanupError` with
+`session_reuse="unknown"`; repeated close reports the same failure. Initialization
+raises `ConsoleInitializationError` with unknown reuse, even if channel cleanup
+appeared successful. If the host body and cleanup both fail, both errors are
+preserved in a BaseExceptionGroup. Do not reuse an unknown Session on the strength
+of a prompt or a successful command from an unrelated shell.
+
+*Last modified: 2026-10-23 18:39:31*

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

@@ -60,3 +60,8 @@ recursive-include src/sshscript *.pyi
 
 include src/sshscript/unittest/test_interactive_console.py
 include CONSOLE.md
+
+include src/sshscript/unittest/test_embedded_console.py
+include EMBEDDED_CONSOLE.md
+include examples/embedded_terminal.py
+include examples/embedded_agent.py

{sshscript-6.0.0/src/sshscript.egg-info → sshscript-6.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sshscript
-Version: 6.0.0
+Version: 6.1.0
 Summary: Python automation for local processes, SSH, and SSHScript .spy files
 Author-email: "Yeh, Hsin-Yuan" <iapyeh@gmail.com>
 License-Expression: MIT
@@ -13,7 +13,7 @@ Project-URL: Issues, https://github.com/iapyeh/sshscript/issues
 Project-URL: Security, https://github.com/iapyeh/sshscript/security/policy
 Project-URL: Support, https://github.com/iapyeh/sshscript/discussions
 Keywords: automation,paramiko,remote-execution,sftp,ssh,subprocess,system-administration
-Classifier: Development Status :: 5 - Production/Stable
+Classifier: Development Status :: 4 - Beta
 Classifier: Operating System :: MacOS
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
@@ -31,7 +31,12 @@ Dynamic: license-file
 
 # SSHScript
 
-SSHScript 6.0.0: [interactive console and script completion](CONSOLE.md).
+**Development status:** SSHScript is still under active development. Backward
+compatibility is not maintained at this stage. APIs, CLI behavior, configuration
+and data formats may change; we provide only brief notes on major differences.
+Compatibility work is done only when explicitly requested by the maintainer.
+
+SSHScript 6.1.0: [borrow an existing Session for interactive operation](EMBEDDED_CONSOLE.md).
 Run `python3 -B sshscript.py console` from the development checkout.
 
 
@@ -54,10 +59,9 @@ output and status, distinguish failure from timeout, and make cleanup and
 unknown termination explicit. A successful command exit is evidence about
 that command; verify the deployment or other application outcome separately.
 
-**Source contract: 6.0.0.** The release branch and local artifacts target this
-version; this source update does not publish a package or create a release tag.
-**Latest published release:** [5.0.0](https://github.com/iapyeh/sshscript/releases/tag/v5.0.0)
-(Production/Stable) · **Python:** 3.11 or newer · **Tested:** Python
+**Release contract: 6.1.0.** Install the matching distribution and verify its version.
+[Release notes](https://github.com/iapyeh/sshscript/releases/tag/v6.1.0)
+(development-stage project) · **Python:** 3.11 or newer · **Tested:** Python
 3.11–3.14 on Linux and macOS
 
 [Documentation](https://iapyeh.github.io/sshscript/v3a/) ·
@@ -66,13 +70,14 @@ version; this source update does not publish a package or create a release tag.
 [Security](https://github.com/iapyeh/sshscript/security/policy) ·
 [Support](https://github.com/iapyeh/sshscript/blob/release/SUPPORT.md)
 
-**Version 6.0.0** adds a Python-first interactive console and normal script
-completion through `$.stop()`. It removes `$.exit()`, `$.break()` and their old
-control exceptions; review the [6.0 migration](VERSIONING.md#60-console-and-script-completion-migration).
-It retains the 5.0 calling-host default for host-key sources. Provision its known_hosts file or
-select `known_hosts="local"` when migrating existing nested connections.
-Upgrade 3.1.5 automation using the migration guide and application regressions.
-See [version policy and migration](VERSIONING.md) before upgrading automation.
+**Version 6.1.0** adds public `Console(existing_session)` integration for terminals,
+host applications and AI agents. Python variables, shell state and text programs
+persist; structured updates distinguish readiness, execution, failure and cleanup.
+Borrowed Sessions remain owned by the host. Credential/policy hooks and verified
+Session reuse keep integration explicit. Read the [integration contract](EMBEDDED_CONSOLE.md).
+Earlier 6.0 console internals, open()/execute() entry points and :help/:quit aliases
+are removed; use Console(session), submit(), help/quit and structured updates.
+The 5.0 host-key source and SSH/SFTP login identity contracts remain unchanged.
 
 ## AI agent ready
 
@@ -161,7 +166,7 @@ pin SSHScript and all transitive dependencies in your application's lock file.
 To install this release explicitly:
 
 ```sh
-python3 -m pip install /path/to/sshscript-6.0.0-py3-none-any.whl
+python3 -m pip install "sshscript==6.1.0"
 ```
 
 Use `python3 -m pip install --upgrade sshscript` to upgrade. The optional
@@ -170,11 +175,9 @@ it never installs an update by itself.
 
 ## 60-second local quickstart
 
-For 6.0.0, install a verified local wheel as shown above until package publication.
-After publication, pin `sshscript==6.0.0` instead. The latest published 5.0.0
-package does not contain the new console.
+Install `sshscript==6.1.0` for the Console integration documented here.
 
-This example runs on 6.0.0 and retains compatibility with the 3.1.5 command API.
+This example runs on 6.1.0 and retains compatibility with the 3.1.5 command API.
 The metadata below records that older compatibility baseline.
 
 <!-- example: {"id":"readme-quickstart", "profile":"3.1.5", "stdout":"sshscript is ready\nexit code: 0\n"} -->
@@ -620,4 +623,8 @@ for maintainer-only release steps.
 SSHScript is released under the
 [MIT License](https://github.com/iapyeh/sshscript/blob/release/LICENSE.txt).
 
-*Last modified: 2026-10-22 23:24:55*
+For embedding an existing connected Session, see the new public
+[Console integration API](EMBEDDED_CONSOLE.md). CLI and embedding applications
+share one implementation; earlier 6.0 CLI compatibility is not maintained.
+
+*Last modified: 2026-10-23 18:39:31*