Open a TN3270 connection to the configured host. Idempotent.

Does NOT log in; call login(userid) afterwards.

Log in to TSO as userid. Password is fetched from the OS keychain.

Set the password once via scripts/set_password.py before calling this.

Args: userid: RACF userid.

Close the TN3270 session cleanly.

Return a one-line status: host, connected flag, userid, mode.

Force a disconnect + reconnect. Re-logs in if a userid was previously set.

Force-reset the host-side session for the configured userid.

Use when a prior dirty disconnect (or external session) is holding the userid as "IN USE" and blocking new logons. Steps:

1. Drive the current TN3270 session through the robust logoff protocol (navigate to READY then LOGOFF).

2. If still dirty, surface a one-line operator instruction for the Hercules console MODIFY command which always works: /F TSO,USER=<userid>,LOGOFF.

Returns a single-line status that the AI can echo verbatim.

Return the current 3270 screen, row-numbered (24 rows x 80 cols).

Return all (row, col) coordinates where the literal pattern appears on the current screen.

Args: pattern: Exact text to search for. Case-sensitive.

Return text at a specific screen position.

Args: row: 1-based row index (1-24). col: 1-based column index (1-80). length: Number of characters to read.

Return a per-row inventory of non-blank content on the current screen.

Heuristic only: returns each non-empty stripped line with its row number so the AI can locate input fields by neighboring labels.

Identify the current screen against known signatures.

Returns a screen_id like TSO_READY, ISPF_PRIMARY, ISPF_DSLIST, ISPF_EDIT, SDSF_HOME, or UNKNOWN.

Scan the current screen for abend codes or error markers. Trips lockout if abend found.

Send the ENTER AID key. Returns the resulting screen.

Send a PF key (1-24). Returns the resulting screen.

Args: number: PF key number (1-24).

Send a PA key (1-3). Returns the resulting screen.

Args: number: PA key number (1-3).

Send the CLEAR AID key. Returns the resulting screen.

Type text into the current input field at the cursor position. Does NOT submit.

Use send_enter / send_pf afterwards to submit. Do NOT use for passwords; the login tool fetches them from the OS keychain.

Args: text: Characters to type.

Block until pattern appears anywhere on screen or timeout elapses.

Args: pattern: Literal text to wait for (case-insensitive). timeout: Seconds to wait. Default 10.

Block until the screen changes from its last observed state, or timeout elapses.

Args: timeout: Seconds to wait. Default 10.

List MVS datasets whose name matches pattern (e.g. ADCDC.*).

Uses ISPF 3.4 or z/OS FTP depending on config.dataset.transport. With the ISPF transport, the TN3270 session must already be logged in.

Args: pattern: Fully-qualified dataset name with wildcards (* matches any qualifier).

List members of a PDS (e.g. ADCDC.SOURCE.COBOL).

Args: pds: PDS dataset name without trailing (*).

Read a PDS member as text.

Args: pds_member: PDS.NAME(MEMBER) form.

Return DCB attributes (RECFM, LRECL, BLKSIZE, DSORG, volume) for a dataset.

Args: dataset: Fully-qualified dataset name.

Return the current JES state of a job.

States: ON INPUT QUEUE | EXECUTING | ON HOLD QUEUE | ON OUTPUT QUEUE | NOT FOUND | UNKNOWN.

Args: job_id: JES job id (e.g. JOB01234). The literal "last" resolves to the most-recently-submitted id this session.

Fetch a job's SYSOUT and surface RC + abend if present.

Detects abends inside the returned spool body and trips the abend lockout the same way a screen-side check_for_errors would. The spool is purged after fetch so the JES output queue stays clean.

Args: job_id: JES job id, or "last" for the most recent. ddname: Reserved for future per-DD filtering (requires SDSF; TSO OUTPUT returns the union). Currently informational only.

List jobs owned by the current userid (TSO STATUS with no jobid).