mech.app
AI Agents

Agentic COBOL: How Hypercubic Wraps Mainframes in Natural Language

Protocol translation between LLM agents and CICS/IMS. Session state, EBCDIC serialization, transactional integrity, and the security boundary for production data.

Source: hypercubic.ai
Agentic COBOL: How Hypercubic Wraps Mainframes in Natural Language

Hypercubic’s Hopper is an agent wrapper for z/OS mainframes. It translates natural language into TN3270 screen navigation, JCL submission, VSAM queries, and CICS program calls. The interesting part is not the LLM. The interesting part is the protocol translation layer that sits between an agent’s tool calls and a 1970s-era transactional system with strict data integrity requirements.

The Protocol Stack

Hopper runs as a desktop application (macOS, Windows, Linux) that maintains a persistent TN3270 session to your LPAR. The agent does not get raw terminal access. Instead, it operates through a curated set of tools that abstract ISPF panels, JES spool files, and VSAM datasets into structured JSON.

Key components:

  • TN3270 driver: Handles 3270 data stream encoding, attention keys (PF/PA), and EBCDIC conversion.
  • Panel parser: Extracts field positions, labels, and input masks from ISPF screens to build a navigable graph.
  • JCL compiler: Generates column-strict JCL from agent instructions, validates syntax before submission.
  • Spool decoder: Parses JESMSGLG, JESYSMSG, and SYSUDUMP into structured diagnostics (abend code, failing step, source line).
  • VSAM adapter: Translates SQL-like queries into IDCAMS commands or CICS file control calls.

The agent sees a tool catalog that looks like this:

tools = [
    {
        "name": "navigate_ispf",
        "description": "Navigate to an ISPF panel by ID (e.g., ISRPRIM, ISREDDE2)",
        "parameters": {"panel_id": "string", "option": "string"}
    },
    {
        "name": "submit_jcl",
        "description": "Submit JCL and return job ID. Does not execute until user approves.",
        "parameters": {"jcl": "string", "wait_for_completion": "boolean"}
    },
    {
        "name": "query_vsam",
        "description": "Query a VSAM file using SQL-like syntax",
        "parameters": {"file": "string", "query": "string"}
    },
    {
        "name": "decode_abend",
        "description": "Parse spool output for a failed job and return structured diagnostics",
        "parameters": {"job_id": "string"}
    }
]

Each tool call triggers a state machine that drives the TN3270 session, waits for screen updates, and extracts results.

State Management and Session Lifecycle

Hopper maintains one TN3270 session per conversation. The session persists across multiple agent turns, which means the agent can navigate through ISPF menus, submit a job, wait for completion, and inspect the spool without re-authenticating.

Session lifecycle:

  1. User connects to LPAR via TN3270 credentials (stored locally, not sent to LLM).
  2. Hopper establishes session, logs into TSO, and enters ISPF.
  3. Agent receives session handle and current panel state.
  4. Each tool call advances the session state (navigate, submit, query).
  5. Session remains open until user disconnects or timeout.

State risks:

  • If the agent issues a destructive operation (e.g., delete dataset), the session has already authenticated. The only gate is user approval before execution.
  • If the session times out mid-conversation, the agent must re-authenticate. The tool layer handles this transparently, but it breaks the conversational flow.
  • If the agent navigates into a modal dialog or error screen, the state machine must detect and recover. Otherwise, the session hangs.

Data Serialization and Token Budget

COBOL data structures are hostile to LLM context windows. A single PICTURE clause can define packed decimals, EBCDIC strings, and nested OCCURS clauses that expand into thousands of bytes. Hopper solves this by serializing only the logical schema, not the raw bytes.

Example COBOL record:

01  CUSTOMER-RECORD.
    05  CUST-ID            PIC 9(8) COMP.
    05  CUST-NAME          PIC X(40).
    05  CUST-BALANCE       PIC S9(9)V99 COMP-3.
    05  CUST-TRANSACTIONS  OCCURS 100 TIMES.
        10  TXN-DATE       PIC 9(8).
        10  TXN-AMOUNT     PIC S9(7)V99 COMP-3.

Serialized for agent context:

{
  "schema": {
    "CUST-ID": "integer(8)",
    "CUST-NAME": "string(40)",
    "CUST-BALANCE": "decimal(9,2)",
    "CUST-TRANSACTIONS": "array(100, {TXN-DATE: date, TXN-AMOUNT: decimal(7,2)})"
  },
  "sample": {
    "CUST-ID": 12345678,
    "CUST-NAME": "ACME CORP",
    "CUST-BALANCE": 1234.56,
    "CUST-TRANSACTIONS": [{"TXN-DATE": "20260515", "TXN-AMOUNT": 100.00}]
  }
}

The agent never sees EBCDIC bytes or packed decimal encoding. It operates on JSON. The adapter handles conversion.

Transactional Integrity and Rollback

Mainframes are ACID-compliant transactional systems. CICS and IMS enforce strict two-phase commit protocols. Hopper does not bypass these. Instead, it wraps them in a human-in-the-loop approval gate.

Approval flow:

  1. Agent generates a change (e.g., update VSAM record, submit JCL that modifies production data).
  2. Hopper pauses execution and displays the proposed change to the user.
  3. User approves or rejects.
  4. If approved, Hopper executes the change within a CICS or IMS transaction.
  5. If the transaction fails, the mainframe rolls back automatically. Hopper surfaces the error to the agent.

Audit trail:

  • Every tool call is logged with timestamp, user ID, and session ID.
  • Approved changes are logged with before/after snapshots (where feasible).
  • Failed transactions are logged with abend codes and diagnostic output.

Failure modes:

Failure TypeDetectionRecovery
Session timeoutTN3270 keepalive failureRe-authenticate, resume from last known panel
CICS abendEXEC CICS HANDLE ABENDSurface abend code to agent, do not retry
VSAM I/O errorFile status code ≠ 00Surface error to agent, suggest corrective action
JCL syntax errorJES return code ≠ 0Parse JESMSGLG, return line number and error text
Agent hallucinationInvalid panel ID or dataset nameReturn error, do not attempt navigation

Security Boundary

The agent never sees mainframe credentials. Credentials are stored in the local Hopper application and used only to establish the TN3270 session. The LLM receives session state (current panel, available options) but not authentication tokens.

Boundary enforcement:

  • Agent cannot execute arbitrary 3270 commands. It must use the tool catalog.
  • Agent cannot bypass the approval gate for destructive operations.
  • Agent cannot access datasets outside the user’s RACF authorization.
  • Agent cannot exfiltrate data by encoding it in tool call parameters (parameters are validated against schema).

Enterprise controls (Enterprise tier):

  • SAML SSO for user authentication (mainframe credentials still stored locally).
  • Admin-defined tool allowlists (e.g., disable submit_jcl for junior developers).
  • Org-wide privacy controls (e.g., mask PII in agent context).
  • No model training on customer data (enforced by contract, not technical control).

Deployment Shape

Hopper is a desktop application, not a cloud service. The TN3270 session runs locally. The LLM calls are proxied through Hypercubic’s API, but the mainframe connection never leaves the user’s network.

On-prem option (Enterprise tier):

  • Deploy Hopper as a containerized service inside the customer VPC.
  • LLM inference runs on customer-managed GPUs or via private API endpoint.
  • No data leaves the customer network.

Observability:

  • Hopper logs all tool calls, session state transitions, and approval decisions.
  • Logs can be exported to SIEM (Splunk, ELK) for compliance auditing.
  • No built-in tracing for LLM inference (that’s handled by the model provider).

Technical Verdict

Use Hopper if:

  • You have experienced mainframe operators who spend hours in SDSF triaging abends and need to compress that workflow into minutes.
  • You need to onboard developers to z/OS without a six-month ISPF training program, and you’re willing to trade approval latency for faster ramp-up.
  • You require an audit trail for every mainframe operation but lack the budget to instrument CICS transactions at the application layer.
  • Your team already knows what they want to do (query VSAM, debug JCL, inspect datasets) but the TN3270 interface is the bottleneck.

Avoid Hopper if:

  • You need real-time, high-throughput mainframe access where the human approval gate adds unacceptable latency (e.g., production incident response with SLA pressure).
  • You operate under strict air-gap requirements and cannot route LLM calls to an external API, and you lack the infrastructure to deploy the on-prem option.
  • You want the agent to learn patterns from your production COBOL and improve over time (the no-training policy prevents model fine-tuning on customer data).
  • Your mainframe operations are already fully automated via scripting or orchestration tools, and you don’t need natural language as an interface layer.

The core value is not automation. It’s protocol translation. Hopper makes mainframes legible to LLMs without rewriting COBOL or replacing CICS. That’s useful if you have 40 years of production code and no budget for a greenfield rewrite.