gea-program 0.88.0__tar.gz → 0.89.0__tar.gz

{gea_program-0.88.0/gea_program.egg-info → gea_program-0.89.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.88.0
+Version: 0.89.0
 Summary: GEA-Program: downhole gauge monitoring - canonical measurement records, quality rules, drift evaluation with a re-fit change log, well-test validation, alarm management, model cards, store-and-forward, monthly SLA measurement, FAT/SAT protocols and a dashboard, generated from live objects in the client's reporting outline.
 Author: Daniel T. Murphy
 License: MPL-2.0
@@ -847,7 +847,7 @@ unsigned, the key hand-overs - and shows the reports as they were signed. A
 reader made from the workspace knows the site's key fingerprints, so it
 says whether a dossier is the site's; it allows no network request, and it
 leaves the trusted time-stamp to `verify_dossier.py`. For a client who wants
-it installed, every release also carries `GEA-Reader-Setup-0.88.0.exe`: GEA
+it installed, every release also carries `GEA-Reader-Setup-0.89.0.exe`: GEA
 Reader as a Windows program of its own - its own icon and taskbar button,
 Check with GEA Reader on a dossier's right-click menu, fingerprints the client
 saves kept on that computer, nothing of GEA-Program. `gea help reader`.
@@ -1053,6 +1053,26 @@ followed. The thresholds are settings, each changed with its source. On a
 record still being written an event raises an alert once. The **Drilling
 alerts** tab, `gea dysfunction`, `gea help dysfunction`.
 
+### Assistant access (MCP)
+
+The site, readable by an assistant. `gea mcp` is a Model Context Protocol
+server: a chat program that speaks MCP - Claude Desktop, or any other
+client - starts it as its own child process and is given the program's
+pages as tools: the site and its wells, the rig time, the roadmap, the
+drilling alerts, torque and drag, hydraulics, the fluid balance, the plume,
+the front and their calibration, frac hits, the alerts, the audit log, the
+help. Each tool returns what the program itself computes, with its own
+labels - SIMULATION where it is one, "nothing declared" where nothing is -
+so the assistant's account of the site is the program's. It is local: no
+port is opened, the conversation is the child process's standard input and
+output. It is read-only: no tool declares, attaches, removes, writes a
+report or changes a setting. It is logged: every call is a line in the
+workspace. And the site chooses which pages are offered, because what a
+tool returns goes to whoever runs the model behind the assistant. Both
+eras of the protocol are spoken: the stateless revision 2026-07-28 and the
+`initialize` handshake of 2025-11-25 and earlier. The **Assistant access**
+tab (one button adds it to Claude Desktop), `gea mcp`, `gea help mcp`.
+
 ### Plan vs actual and the survey tools
 
 Each well against its directional plan: at every survey station, how far
@@ -1717,7 +1737,7 @@ attaches the zips to the GitHub release of that tag.
 
 ### The Windows installer
 
-Every release also carries `GEA-Program-Setup-0.88.0.exe` (for 0.88.0): the
+Every release also carries `GEA-Program-Setup-0.89.0.exe` (for 0.89.0): the
 same Windows kit installed like any Windows program, for the signed-in user
 alone and with no administrator rights (`%LOCALAPPDATA%\Programs\GEA-Program`).
 It asks for the site workspace (an existing one such as `C:\site` is used as
@@ -1736,7 +1756,7 @@ it, removes the program and leaves the workspace. Silent, for a site's
 software deployment:
 
 ```
-GEA-Program-Setup-0.88.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"
+GEA-Program-Setup-0.89.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"
 ```
 
 The setup is built by Inno Setup 6 from `tools/installer.iss` in the same

{gea_program-0.88.0 → gea_program-0.89.0}/README.md

@@ -808,7 +808,7 @@ unsigned, the key hand-overs - and shows the reports as they were signed. A
 reader made from the workspace knows the site's key fingerprints, so it
 says whether a dossier is the site's; it allows no network request, and it
 leaves the trusted time-stamp to `verify_dossier.py`. For a client who wants
-it installed, every release also carries `GEA-Reader-Setup-0.88.0.exe`: GEA
+it installed, every release also carries `GEA-Reader-Setup-0.89.0.exe`: GEA
 Reader as a Windows program of its own - its own icon and taskbar button,
 Check with GEA Reader on a dossier's right-click menu, fingerprints the client
 saves kept on that computer, nothing of GEA-Program. `gea help reader`.
@@ -1014,6 +1014,26 @@ followed. The thresholds are settings, each changed with its source. On a
 record still being written an event raises an alert once. The **Drilling
 alerts** tab, `gea dysfunction`, `gea help dysfunction`.
 
+### Assistant access (MCP)
+
+The site, readable by an assistant. `gea mcp` is a Model Context Protocol
+server: a chat program that speaks MCP - Claude Desktop, or any other
+client - starts it as its own child process and is given the program's
+pages as tools: the site and its wells, the rig time, the roadmap, the
+drilling alerts, torque and drag, hydraulics, the fluid balance, the plume,
+the front and their calibration, frac hits, the alerts, the audit log, the
+help. Each tool returns what the program itself computes, with its own
+labels - SIMULATION where it is one, "nothing declared" where nothing is -
+so the assistant's account of the site is the program's. It is local: no
+port is opened, the conversation is the child process's standard input and
+output. It is read-only: no tool declares, attaches, removes, writes a
+report or changes a setting. It is logged: every call is a line in the
+workspace. And the site chooses which pages are offered, because what a
+tool returns goes to whoever runs the model behind the assistant. Both
+eras of the protocol are spoken: the stateless revision 2026-07-28 and the
+`initialize` handshake of 2025-11-25 and earlier. The **Assistant access**
+tab (one button adds it to Claude Desktop), `gea mcp`, `gea help mcp`.
+
 ### Plan vs actual and the survey tools
 
 Each well against its directional plan: at every survey station, how far
@@ -1678,7 +1698,7 @@ attaches the zips to the GitHub release of that tag.
 
 ### The Windows installer
 
-Every release also carries `GEA-Program-Setup-0.88.0.exe` (for 0.88.0): the
+Every release also carries `GEA-Program-Setup-0.89.0.exe` (for 0.89.0): the
 same Windows kit installed like any Windows program, for the signed-in user
 alone and with no administrator rights (`%LOCALAPPDATA%\Programs\GEA-Program`).
 It asks for the site workspace (an existing one such as `C:\site` is used as
@@ -1697,7 +1717,7 @@ it, removes the program and leaves the workspace. Silent, for a site's
 software deployment:
 
 ```
-GEA-Program-Setup-0.88.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"
+GEA-Program-Setup-0.89.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"
 ```
 
 The setup is built by Inno Setup 6 from `tools/installer.iss` in the same

{gea_program-0.88.0 → gea_program-0.89.0}/gea/__init__.py

@@ -123,7 +123,7 @@ from .profile_catalog import (
     read_pangaea_txt,
 )
 
-__version__ = "0.88.0"
+__version__ = "0.89.0"
 __all__ = [
     "aging_rate", "rate_psi_yr", "accuracy_psi",
     "Sensor", "SimulatorConfig", "DownholeEngine",

{gea_program-0.88.0 → gea_program-0.89.0}/gea/__main__.py

@@ -677,6 +677,21 @@ def main(argv=None) -> int:
     p_os.add_argument("--actor", type=str, default="cli")
     p_os.add_argument("--json", action="store_true")
 
+    p_mc = sub.add_parser("mcp", help="the site, readable by an assistant: a Model Context Protocol server on standard input and output - local (no port), read-only (every tool reads one of the program's pages, none changes anything), logged; with --workspace alone it serves until its input closes")
+    p_mc.add_argument("--workspace", type=str, default=None, help="the workspace folder; without one the self-test runs (both eras of the protocol against a labelled site)")
+    p_mc.add_argument("--allow", type=str, default=None, help="serve only these tools this run, comma-separated (never more than the site offers)")
+    p_mc.add_argument("--status", action="store_true", help="print the tools offered, how to start the server and the last calls, and exit")
+    p_mc.add_argument("--config", action="store_true", help="print the entry an MCP client's configuration needs to start this site's server, and exit")
+    p_mc.add_argument("--call", type=str, default=None, help="call one tool and print its answer, as an assistant would get it")
+    p_mc.add_argument("--well", type=str, default=None, help="--call: the well, by name or id")
+    p_mc.add_argument("--topic", type=str, default=None, help="--call help: the topic")
+    p_mc.add_argument("--json", action="store_true", help="--call: the page as JSON instead of its text")
+    p_mc.add_argument("--offer", type=str, default=None, help="settings: the tools the site offers, comma-separated (all: every tool)")
+    p_mc.add_argument("--max-chars", type=int, default=None, help="settings: the most characters one answer carries (default 40000)")
+    p_mc.add_argument("--source", type=str, default="", help="settings: who decided, and on what grounds")
+    p_mc.add_argument("--add-to-claude-desktop", action="store_true", help="add this site's server to Claude Desktop's configuration on this computer, keeping every other entry and a dated copy of the file")
+    p_mc.add_argument("--remove-from-claude-desktop", action="store_true", help="take it out again")
+    p_mc.add_argument("--actor", type=str, default="cli")
     p_al = sub.add_parser("alerts", help="the program's alerts: earthquakes near operating wells and the protocol levels they reach, the earthquake watch going quiet, components due for service, penetrator checks outside their ratings, dossiers the workspace no longer matches")
     p_al.add_argument("--workspace", type=str, required=True)
     p_al.add_argument("--check", action="store_true", help="check the motors, penetrators and dossiers now, sending what began or cleared through the notification rules")
@@ -3560,6 +3575,50 @@ def main(argv=None) -> int:
             for v in f_["versions"][: (50 if a.family else 3)]:
                 print(f"      {v['utc']}  {v.get('report_id') or ''}  reports/{v['dir']}")
         return 0
+    elif a.cmd == "mcp":
+        import json as _json
+        from . import mcp_server as _MC
+        from .workspace import Workspace, WorkspaceError
+        allow_ = [t_.strip() for t_ in a.allow.split(",") if t_.strip()] if a.allow else None
+        if not a.workspace:
+            r = _MC.selftest()
+            print("\n".join(f"{'PASS' if c['pass'] else 'FAIL'}  {c['check']}: {c['value']}" for c in r["checks"]) + f"\n{'OK' if r['ok'] else 'FAILED'} - {r['label']}")
+            return 0 if r["ok"] else 1
+        try:
+            ws = Workspace(a.workspace)
+        except WorkspaceError as e:
+            print(f"mcp: {e}", file=sys.stderr)                 # the error stream: standard output is the protocol's
+            return 2
+        if not (a.status or a.config or a.call or a.offer or a.max_chars is not None or a.add_to_claude_desktop or a.remove_from_claude_desktop):
+            return _MC.serve(ws, allow=allow_)                  # the server: nothing but protocol messages on standard output
+        from .cli import _safe_stdout
+        _safe_stdout()
+        try:
+            if a.offer or a.max_chars is not None:
+                st_ = _MC.set_settings(ws, a.actor, (list(_MC.NAMES) if a.offer and a.offer.strip().lower() == "all" else a.offer), a.max_chars, a.source)
+                print(f"offered: {', '.join(_MC.offered(ws))}; an answer carries {st_['max_chars']:,} characters at most")
+            if a.add_to_claude_desktop or a.remove_from_claude_desktop:
+                r = _MC.install_claude_desktop(ws, a.actor, remove=a.remove_from_claude_desktop)
+                for d_ in r["done"]:
+                    print(f"{'taken out of' if r['removed'] else 'added to'} {d_['path']}" + (f" (as it was: {d_['backup']})" if d_["backup"] else "") + " - quit Claude Desktop and start it again")
+                for d_ in r["skipped"]:
+                    print(f"not changed: {d_['path']} - {d_['why']}")
+            if a.config:
+                print(_json.dumps(_MC.client_config(ws.path, allow_), indent=2))
+            if a.call:
+                if a.call not in _MC.offered(ws, allow_):
+                    raise SystemExit(f"mcp: no tool {a.call!r} is offered; offered: {', '.join(_MC.offered(ws, allow_))}")
+                args_ = {k: v for k, v in (("well", a.well), ("topic", a.topic)) if v is not None}
+                if a.json:
+                    args_["json"] = True
+                r = _MC.call_tool(ws, a.call, args_, _MC.settings(ws)["max_chars"])
+                print(r["text"])
+                return 1 if r["is_error"] else 0
+            if a.status:
+                print(_MC.text(_MC.page(ws)))
+        except (_MC.ToolError, WorkspaceError, OSError) as e:
+            raise SystemExit(f"mcp: {e.args[0] if e.args else e}")
+        return 0
     elif a.cmd == "alerts":
         import json as _json
         from . import alerts as _AL

{gea_program-0.88.0 → gea_program-0.89.0}/gea/acceptance_tests.py

@@ -18725,6 +18725,235 @@ def section_eg_dysfunction(tmp: str) -> None:
        "with its charts and the three alert names on the Alarms tab, the help pages, the README and lesson 13" + (f" [failed: {', '.join(failed3)}]" if failed3 else ""))
 
 
+def section_eh_mcp(tmp: str) -> None:
+    """Section EH - assistant access: the MCP server's self-test (a client of each era of the protocol against a
+    labelled site); the tool definitions; a workspace read through every tool with every file hashed before and after
+    and the network refused (read-only, local, and the same text as the page's own); the server as a real child process
+    on its standard streams in both eras, with a withheld tool, a run started with fewer tools, the access log; the
+    configuration entry and an assistant's configuration file; the routes, the tab, the command, the help, the IT
+    statement, the README and the lesson."""
+    import hashlib
+    import http.cookiejar
+    import socket as _socket
+    import subprocess as _sp
+    import urllib.error
+    import urllib.request
+    from . import __version__ as _ver
+    from . import dysfunction as DY
+    from . import helplib as H
+    from . import mcp_server as MC
+    from . import rig_state as RS
+    from . import roadmap as RM
+    from . import tutorial as TU
+    from .service import Service, Users
+    from .workspace import Workspace
+    pkg = Path(__file__).parent
+    d = Path(tmp, "eh"); d.mkdir()
+    env = {**os.environ, "PYTHONPATH": str(pkg.parent) + os.pathsep + os.environ.get("PYTHONPATH", "")}
+    # -- EH1 the protocol and the tools -----------------------------------------------------------------------------------
+    st = MC.selftest()
+    defs = [MC.tool_definition(n_) for n_ in MC.NAMES]
+    fake = d / "py"; fake.mkdir(); (fake / "pythonw.exe").write_text(""); (fake / "python.exe").write_text("")
+    real_exe = sys.executable
+    try:
+        sys.executable = str(fake / "pythonw.exe")
+        lc = MC.launch_command(str(d / "site"), ["site", "help"])
+    finally:
+        sys.executable = real_exe
+    plain = MC._plain({"a": np.float64(1.5), "_work": [1, 2], "b": [np.int64(3), float("nan")], "c": np.arange(4), "d": (1, "x")})
+    c1 = {
+        "selftest": st["ok"] and len(st["checks"]) >= 7,
+        "tools": len(defs) == 23 and defs[0]["name"] == "site" and all(d_["annotations"]["readOnlyHint"] is True and d_["annotations"]["destructiveHint"] is False and d_["annotations"]["openWorldHint"] is False
+                                                                        and d_["inputSchema"]["type"] == "object" and d_["inputSchema"]["additionalProperties"] is False and d_["title"] for d_ in defs)
+                 and "well" in defs[1]["inputSchema"]["properties"] and "json" in defs[2]["inputSchema"]["properties"] and "json" not in MC.tool_definition("help")["inputSchema"]["properties"]
+                 and not [n_ for n_ in MC.NAMES if any(w_ in n_ for w_ in ("write", "set", "declare", "attach", "remove", "delete", "run"))],
+        "versions": MC.SUPPORTED[0] == "2026-07-28" and set(MC.LEGACY) == {"2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"} and MC.E_VERSION == -32022,
+        "launch": lc["command"] == str(fake / "python.exe") and lc["args"][:4] == ["-m", "gea", "mcp", "--workspace"] and lc["args"][-2:] == ["--allow", "site,help"]
+                  and MC.launch_command(str(d / "site"))["command"] == sys.executable and isinstance(MC.claude_desktop_paths(), list) and MC.claude_desktop_paths()[0].endswith("claude_desktop_config.json"),
+        "plain": plain == {"a": 1.5, "b": [3, None], "c": "(an array of 4 values, left out)", "d": [1, "x"]},
+    }
+    failed1 = [k_ for k_, v in c1.items() if not v]
+    ok(not failed1,
+       "EH1 the MCP server: the self-test (a client of an earlier revision through its handshake and a client of revision 2026-07-28 statelessly, each listing and calling the tools; a line that is "
+       "not JSON, a tool, a well, an argument and a method that do not exist, a batch; a withheld tool; the access log; an assistant's configuration file added to and restored); twenty-three tools, "
+       "each read-only by its own declaration with its arguments closed, none named for a change; the revisions spoken; the command a client starts - the console interpreter, never the windowless "
+       "one; a page as plain JSON with the working arrays left out" + (f" [failed: {', '.join(failed1)}]" if failed1 else ""))
+
+    # -- EH2 a workspace read through every tool: read-only, local, the page's own text ------------------------------------
+    wsp = str(d / "ws"); ws = Workspace.create(wsp, "Pad EH", actor="tester")
+    DY.write_edr(DY.synthetic_record(True, stands=16), str(d / "rig.csv"))
+    wid = ws.add_well_file(str(d / "rig.csv"), display="RIG-1", actor="tester")["id"]
+    DY.write_edr(DY.synthetic_record(False, seed=5, stands=16), str(d / "rig2.csv"))
+    ws.add_well_file(str(d / "rig2.csv"), display="RIG-2", actor="tester")
+    MC.call_tool(ws, "rig_time", {})                               # the chart caches, as opening the tab would build them
+
+    def snapshot():
+        out = {}
+        for r_, _, fs in os.walk(wsp):
+            for f_ in fs:
+                p_ = os.path.join(r_, f_)
+                with open(p_, "rb") as fh:
+                    out[os.path.relpath(p_, wsp)] = hashlib.sha256(fh.read()).hexdigest()
+        return out
+    before = snapshot()
+    tried = []
+    real_connect = _socket.socket.connect
+
+    def no_network(self, *a_, **k_):
+        tried.append(a_)
+        raise OSError("no network in this check")
+    _socket.socket.connect = no_network
+    try:
+        answers = {n_: MC.call_tool(ws, n_, {}) for n_ in MC.NAMES}
+        as_json = {n_: MC.call_tool(ws, n_, {"json": True}, 400000) for n_ in MC.NAMES if n_ != "help"}
+        one = MC.call_tool(ws, "well", {"well": "rig-1"})
+        named = MC.call_tool(ws, "roadmap", {"well": "RIG-2"})
+    finally:
+        _socket.socket.connect = real_connect
+    after = snapshot()
+    changed = sorted(k_ for k_ in set(before) | set(after) if before.get(k_) != after.get(k_))
+    parsed = {}
+    for n_, r_ in as_json.items():
+        try:
+            parsed[n_] = json.loads(r_["text"])
+        except ValueError:
+            parsed[n_] = None
+    # the server as a child process, on its standard streams
+    def child(lines, extra=()):
+        pr = _sp.run([sys.executable, "-m", "gea", "mcp", "--workspace", wsp, *extra], input=b"".join(json.dumps(m_).encode() + b"\n" for m_ in lines), capture_output=True, env=env, cwd=str(d), timeout=300)
+        return pr.returncode, [json.loads(l_) for l_ in pr.stdout.split(b"\n") if l_], pr.stderr.decode("utf-8", "replace")
+    meta = {MC.K_VERSION: "2026-07-28", MC.K_CLIENT: {"name": "gate-modern", "version": "1"}, "io.modelcontextprotocol/clientCapabilities": {}}
+    rc_o, out_o, err_o = child([{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": {"name": "gate-legacy", "version": "1"}}},
+                                {"jsonrpc": "2.0", "method": "notifications/initialized"}, {"jsonrpc": "2.0", "id": 2, "method": "tools/list"},
+                                {"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "rig_time", "arguments": {}}},
+                                {"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "drilling_alerts", "arguments": {}}}])
+    rc_m, out_m, err_m = child([{"jsonrpc": "2.0", "id": "p", "method": "server/discover", "params": {"_meta": meta}}, {"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {"_meta": meta}},
+                                {"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "site", "arguments": {}, "_meta": meta}},
+                                {"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "site", "arguments": {}, "_meta": {**meta, MC.K_VERSION: "2099-01-01"}}}])
+    kept = MC.set_settings(ws, "tester", tools=[n_ for n_ in MC.NAMES if n_ != "audit"], max_chars=3000, source="site manager (gate): no audit log to assistants")
+    rc_w, out_w, _ = child([{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}, {"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "audit"}},
+                            {"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "help", "arguments": {"topic": "mcp"}}}])
+    rc_a, out_a, _ = child([{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}, {"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "rig_time"}}], ("--allow", "site,audit"))
+    rc_x = _sp.run([sys.executable, "-m", "gea", "mcp", "--workspace", str(d / "nowhere")], input=b"", capture_output=True, env=env, cwd=str(d), timeout=120)
+    log = MC.access_log(ws, 100)
+    errs = {}
+    for name, kw in (("tool", {"tools": ["site", "wipe"]}), ("chars", {"max_chars": 10}), ("number", {"max_chars": "lots"})):
+        try:
+            MC.set_settings(ws, "tester", **kw); errs[name] = ""
+        except MC.ToolError as e:
+            errs[name] = str(e)
+    MC.set_settings(ws, "tester", tools=list(MC.NAMES), max_chars=40000)
+    audit = Path(ws.audit_path).read_text(encoding="utf-8")
+    c2 = {
+        "read_only": changed == [] and len(before) > 20,
+        "local": tried == [],
+        "answers": all(not r_["is_error"] for n_, r_ in answers.items() if n_ != "well") and answers["well"]["is_error"] and "name the well" in answers["well"]["text"]
+                   and not one["is_error"] and json.loads(one["text"])["id"] == wid and not named["is_error"] and "RIG-2 at" in named["text"],
+        "same_text": answers["rig_time"]["text"] == RS.text(RS.page(ws)) and answers["roadmap"]["text"] == RM.text(RM.page(ws)) and answers["drilling_alerts"]["text"] == DY.text(DY.page(ws))
+                     and "SIMULATION" in answers["pressure_plume"]["text"].splitlines()[0] and "RIG-1" in answers["site"]["text"] and _ver in answers["site"]["text"],
+        "json": all(isinstance(v, (dict, list)) for n_, v in parsed.items() if n_ != "well") and parsed["well"] is None and as_json["well"]["is_error"] and parsed["roadmap"]["status"] == "OK" and not [k_ for k_ in parsed["rig_time"] if str(k_).startswith("_")]
+                and len(parsed["drilling_alerts"]["wells"]) == 2,
+        "child_legacy": rc_o == 0 and len(out_o) == 4 and out_o[0]["result"]["protocolVersion"] == "2025-11-25" and len(out_o[1]["result"]["tools"]) == 23 and "resultType" not in out_o[1]["result"]
+                        and out_o[2]["result"]["content"][0]["text"] == answers["rig_time"]["text"] and "motor stall" in out_o[3]["result"]["content"][0]["text"] and "Traceback" not in err_o,
+        "child_modern": rc_m == 0 and len(out_m) == 4 and out_m[0]["result"]["supportedVersions"] == list(MC.SUPPORTED) and out_m[1]["result"]["resultType"] == "complete"
+                        and out_m[1]["result"]["cacheScope"] == "private" and out_m[2]["result"]["_meta"][MC.K_SERVER] == {"name": "gea-program", "title": "GEA-Program", "version": _ver}
+                        and out_m[2]["result"]["isError"] is False and out_m[3]["error"]["code"] == -32022 and out_m[3]["error"]["data"]["requested"] == "2099-01-01" and "Traceback" not in err_m,
+        "withheld": kept["tools"] is not None and "audit" not in kept["tools"] and rc_w == 0 and "audit" not in [t_["name"] for t_ in out_w[0]["result"]["tools"]] and len(out_w[0]["result"]["tools"]) == 22
+                    and out_w[1]["error"]["code"] == -32602 and "[cut at 3,000 of" in out_w[2]["result"]["content"][0]["text"],
+        "narrowed": rc_a == 0 and [t_["name"] for t_ in out_a[0]["result"]["tools"]] == ["site"] and out_a[1]["error"]["code"] == -32602,
+        "no_workspace": rc_x.returncode == 2 and rc_x.stdout == b"" and b"not a workspace" in rc_x.stderr,
+        "log": [r_["tool"] for r_ in reversed(log)] == ["rig_time", "drilling_alerts", "site", "audit", "help", "rig_time"]
+               and sum(1 for r_ in log if r_.get("turned_away") == "withheld") == 2 and any((r_.get("client") or {}).get("name") == "gate-legacy" for r_ in log)
+               and any((r_.get("client") or {}).get("name") == "gate-modern" for r_ in log) and any(r_.get("truncated") for r_ in log) and all("utc" in r_ and "chars" in r_ for r_ in log),
+        "settings": "no tool named wipe" in errs["tool"] and "between" in errs["chars"] and "number" in errs["number"] and "mcp.settings" in audit and "no audit log to assistants" in audit
+                    and MC.settings(ws)["tools"] is None,
+    }
+    failed2 = [k_ for k_, v in c2.items() if not v]
+    ok(not failed2,
+       "EH2 a site read through every tool with every file in the workspace hashed before and after and the network refused: no file changed, nothing tried to connect; every tool answers (the one "
+       "that needs a well says so, and reads it by name in any case); the rig time, the roadmap and the drilling alerts return the very text their own pages print, the plume says SIMULATION in its "
+       "first line; every page also as JSON without the working arrays. The server as a child process on its standard streams: a client of 2025-11-25 through its handshake and a client of "
+       "2026-07-28 statelessly, nothing on standard output but one message a line, a clean exit when the input closes; a withheld tool not listed and not callable, a long answer cut and saying so; "
+       "a run started with fewer tools offering fewer and never one the site withholds; a folder that is no workspace an error on the error stream and nothing on the output; six lines in the "
+       "access log with who asked; the choice of tools in the audit log" + (f" [failed: {', '.join(failed2)}]" if failed2 else ""))
+
+    # -- EH3 the routes, the command, the tab, the help ---------------------------------------------------------------------
+    Users(str(Path(wsp, "users.json"))).add("v", "viewer-pass-1", "viewer"); Users(str(Path(wsp, "users.json"))).add("op", "op-pass-123", "operator"); Users(str(Path(wsp, "users.json"))).add("ad", "admin-pass-12", "admin")
+    cfgp = d / "Claude" / "claude_desktop_config.json"; cfgp.parent.mkdir()
+    cfgp.write_text(json.dumps({"mcpServers": {"files": {"command": "npx", "args": ["-y", "x"]}}, "globalShortcut": "Ctrl+Space"}), encoding="utf-8")
+    real_paths = MC.claude_desktop_paths
+    MC.claude_desktop_paths = lambda: [str(cfgp)]                 # never the real one: this check must not touch an assistant installed on the computer that runs it
+    svc = Service(wsp, port=0, scheduler=False).start()
+    base_url = svc.url.rstrip("/")
+
+    def opener(name, pw_):
+        o = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar()))
+        rq = urllib.request.Request(base_url + "/api/login", method="POST", data=json.dumps({"name": name, "password": pw_}).encode())
+        rq.add_header("Content-Type", "application/json"); rq.add_header("X-GEA-Action", "1"); o.open(rq, timeout=30)
+        return o
+
+    def call(o, method, path, body=None):
+        rq = urllib.request.Request(base_url + path, method=method, data=(json.dumps(body).encode() if body is not None else None))
+        if method == "POST":
+            rq.add_header("Content-Type", "application/json"); rq.add_header("X-GEA-Action", "1")
+        try:
+            with o.open(rq, timeout=300) as rr_:
+                return rr_.status, json.loads(rr_.read())
+        except urllib.error.HTTPError as e:
+            return e.code, json.loads(e.read())
+    try:
+        V, O, A = opener("v", "viewer-pass-1"), opener("op", "op-pass-123"), opener("ad", "admin-pass-12")
+        s_vg, vg = call(V, "GET", "/api/mcp")
+        s_vs, _ = call(V, "POST", "/api/mcp/settings", {"tools": ["site"]})
+        s_os, os_ = call(O, "POST", "/api/mcp/settings", {"tools": ["site", "roadmap", "help"], "max_chars": "20000", "source": "operator (api)"})
+        s_bs, _ = call(O, "POST", "/api/mcp/settings", {"tools": ["site", "format_disk"]})
+        s_oc, _ = call(O, "POST", "/api/mcp/claude-desktop", {})
+        s_ac, ac = call(A, "POST", "/api/mcp/claude-desktop", {})
+        cfg_added = json.loads(cfgp.read_text(encoding="utf-8"))
+        s_g2, g2 = call(V, "GET", "/api/mcp")
+        s_ar, ar = call(A, "POST", "/api/mcp/claude-desktop", {"remove": True})
+        cfg_removed = json.loads(cfgp.read_text(encoding="utf-8"))
+        s_oa, _ = call(O, "POST", "/api/mcp/settings", {"tools": list(MC.NAMES), "max_chars": "40000"})
+    finally:
+        svc.stop()
+        MC.claude_desktop_paths = real_paths
+    run = lambda *a_: _sp.run([sys.executable, "-m", "gea", "mcp", "--workspace", wsp, *a_], capture_output=True, text=True, env=env, cwd=str(d), timeout=300)
+    cli_s, cli_c, cli_k, cli_j = run("--status"), run("--config"), run("--call", "roadmap", "--well", "RIG-2"), run("--call", "site", "--json")
+    cli_u, cli_o, cli_b, cli_a = run("--call", "format_disk"), run("--offer", "site,rig_time,help", "--source", "cli (gate)"), run("--offer", "site,format_disk"), run("--offer", "all")
+    page_src = (pkg / "web" / "app.html").read_text(encoding="utf-8")
+    readme = (pkg.parent / "README.md").read_text(encoding="utf-8") if (pkg.parent / "README.md").is_file() else ""
+    lesson = (pkg / "help" / "tutorial" / "20-admin.md").read_text(encoding="utf-8")
+    its = (pkg / "help" / "IT_SECURITY.md").read_text(encoding="utf-8")
+    backups = sorted(p_.name for p_ in cfgp.parent.iterdir() if ".before-gea-" in p_.name)
+    c3 = {
+        "api": s_vg == 200 and len(vg["tools"]) == 23 and all(t_["offered"] for t_ in vg["tools"]) and vg["config"]["mcpServers"]["gea"]["args"][-1] == os.path.abspath(wsp) and len(vg["log"]) >= 6
+               and vg["claude_desktop"]["found"] and not vg["claude_desktop"]["installed"] and s_vs == 403 and s_os == 200 and os_["offered"] == ["site", "roadmap", "help"] and os_["max_chars"] == 20000
+               and s_bs == 400 and s_oa == 200,
+        "claude_desktop": s_oc == 403 and s_ac == 200 and len(ac["done"]) == 1 and cfg_added["globalShortcut"] == "Ctrl+Space" and cfg_added["mcpServers"]["files"] == {"command": "npx", "args": ["-y", "x"]}
+                          and cfg_added["mcpServers"]["gea"]["args"] == ["-m", "gea", "mcp", "--workspace", os.path.abspath(wsp)] and s_g2 == 200 and g2["claude_desktop"]["installed"]
+                          and s_ar == 200 and ar["removed"] and "gea" not in cfg_removed["mcpServers"] and "files" in cfg_removed["mcpServers"] and len(backups) >= 1 and "mcp.claude_desktop" in Path(ws.audit_path).read_text(encoding="utf-8"),
+        "cli": cli_s.returncode == 0 and "Assistant access (MCP)" in cli_s.stdout and "offered   site" in cli_s.stdout and cli_c.returncode == 0
+               and json.loads(cli_c.stdout)["mcpServers"]["gea"]["command"] == sys.executable and cli_k.returncode == 0 and "Drilling roadmap" in cli_k.stdout and "RIG-2 at" in cli_k.stdout
+               and cli_j.returncode == 0 and json.loads(cli_j.stdout)["site"] == "Pad EH" and cli_u.returncode != 0 and "no tool" in cli_u.stderr and cli_o.returncode == 0
+               and "offered: site, rig_time, help" in cli_o.stdout and cli_b.returncode != 0 and "no tool named format_disk" in cli_b.stderr and cli_a.returncode == 0 and "audit" in cli_a.stdout,
+        "page": all(x in page_src for x in ("VIEWS.mcp", "['#/mcp', 'Assistant access']", "/api/mcp/settings", "/api/mcp/claude-desktop", "help('mcp')", "Add to Claude Desktop",
+                                            "The server is on this computer; the assistant usually is not.")),
+        "help": not H.check("mcp") and H.VIEW_TOPIC.get("mcp") == "mcp" and any(t_ == "mcp" for t_, _, _ in H.INDEX)
+                and all(x in (H.page("mcp") or "") for x in ("gea mcp --workspace C:\\site --status", "2026-07-28", "server/discover", "records/mcp_access.jsonl", "may leave the site", "not verified"))
+                and all(f"`{n_}`" in (H.page("mcp") or "") for n_ in MC.NAMES),
+        "it_readme_lesson": "Assistant access (MCP)" in its and "opens no port" in its and "leaves the computer" in its
+                            and its == ((pkg.parent / "docs" / "IT_SECURITY.md").read_text(encoding="utf-8") if (pkg.parent / "docs" / "IT_SECURITY.md").is_file() else its)
+                            and (not readme or ("### Assistant access (MCP)" in readme and "`gea mcp`" in readme)) and "**Assistant access**" in lesson and "mcp" in lesson.split("Help:")[-1] and not TU.check("admin"),
+    }
+    failed3 = [k_ for k_, v in c3.items() if not v]
+    ok(not failed3,
+       "EH3 on the API (anyone reads what is offered, the entry and the log; only an operator changes the choice, and a tool that does not exist is 400), adding the site to an assistant's "
+       "configuration file - a stand-in for Claude Desktop's, never the real one - is an administrator's (an operator is 403): its other server and its own settings kept, a dated copy left, "
+       "the page then showing it set, and taken out again; the command (the status, the entry, one tool's answer for a named well and as JSON, a tool that does not exist stopped, the choice kept "
+       "and put back); the Assistant access tab with its warning; the help page naming every tool; the IT statement in both copies, the README and lesson 20"
+       + (f" [failed: {', '.join(failed3)}]" if failed3 else ""))
+
+
 def main() -> int:
     print("GEA-Program - ACCEPTANCE SUITE (the product gate)")
     # a handle a job subprocess still holds at the end must not turn a finished gate into a traceback on Windows:
@@ -18865,6 +19094,7 @@ def main() -> int:
         section_ee_calibration(tmp)
         section_ef_roadmap(tmp)
         section_eg_dysfunction(tmp)
+        section_eh_mcp(tmp)
     if _FAILS:
         print(f"[ACCEPTANCE] {len(_FAILS)} FAILURES ({_PASS} passed):")
         for f in _FAILS:

{gea_program-0.88.0 → gea_program-0.89.0}/gea/help/IT_SECURITY.md

@@ -199,6 +199,20 @@ declared extras.
   give them - a position, not a coordinate: the plan's azimuth and the
   heel are in the rig PC's config, no surface location is.
 
+- **Assistant access (MCP)**: off until a person turns it on, and then it
+  opens no port. `gea mcp` is a child process of the assistant program
+  that starts it, speaking JSON on its standard input and output; it has
+  the rights of the Windows user who runs that program and of nobody
+  else. Its tools read pages; none writes a record, a declaration, a
+  report or a setting, and each declares itself read-only. Which tools are
+  offered is the site's choice (`records\mcp.json`, changed by an operator,
+  in the audit log); a withheld tool is not listed and cannot be called.
+  Every call is a line in `records\mcp_access.jsonl`. **What a tool returns
+  leaves the computer**: it becomes part of the assistant's conversation
+  and goes to whoever runs the model. Adding the server to Claude Desktop
+  is an administrator's action; it writes one entry into that program's
+  configuration file and keeps a copy of the file as it was.
+
 ## What it records
 
 Every action - by a person through the page, by a scheduled job, by the

{gea_program-0.88.0 → gea_program-0.89.0}/gea/help/driller.md

@@ -2,7 +2,7 @@
 
 > A program on the rig PC that reads the rig's own feed and the pre-drill model, places the bit in the layer with a position filter, and, every 30 ft, recommends in the driller's units what to do next - a policy trained by reinforcement learning in a physics twin of the lateral - with the driller's answer, every command, and the records pulled into GEA.
 
-**The command**: on the rig PC, `GEA-Driller-0.88.0.tar.gz` from the release (or the kit's `installers` folder, fetched on the Audit / Update tab): unpack it and run `sudo sh install.sh` on Linux or `install.cmd` on Windows, once; edit its config - the EDR's WITS0 feed (`tcp`, the host and port; `serial`, the COM port), the pre-drill model (the target layer's top TVD at the heel, its thickness and dip, the gamma in, above and below, the deep-resistivity tool, the heel's MD and TVD), the tool's cap, the limits - and restart it. The driller's screen is at port 8790 of the rig PC: `http://192.168.1.60:8790/live`. It shows the section with the model's layer window, the hole drilled through it and - since 0.78.0 - the **position filter**'s band: where the layer is from the readings, as a geosteerer places it (a particle filter over the layer's offset from the model, its dip error and its thickness, moved every decision and kept to the guesses that explain the gamma and the deep-resistivity distance), with the probability the bit is in the layer, above or below it and the distance to the top and the base with its spread, sixty feet ahead; the agent reads the same estimate, and so does the textbook driller it is judged against. Then the recommendation in words - *Build +1.5°/100 ft (toolface up, 25% steering); 25 klb WOB, 120 rpm, 500 gpm* - with its reasons (what the deep-resistivity tool says, the gamma against the model's values, the model's bracket, the limits) and the confidence of each choice, the rig's numbers against the limits, and **Accept**, **Reject** or **Did something else…** with the operator's name. In GEA: the **Drill string** tab's card **GEA Driller** - the rig PC's address and the well, **Pull**: the records come in checked against their hashes, and the table says how many decisions, accepted, rejected, done otherwise, the hole under advice, the armed sections and the commands. **Open the driller's screen** opens the rig PC's screen from its address. Before there is a rig PC: **Start the twin as the rig** runs the driller's program on this computer with a scene drilling itself under the agent - **Open its screen** is the driller's screen with the twin behind it, labelled SIMULATION - and **Pull from it** brings its records in; **Stop it** closes them. **Shadow a drilled well** (since 0.79.0): a well of this workspace with a drilling-recorder export is replayed through the advisor - every 30 ft the agent sees what the rig had shown to that point and nothing past it, and its recommendation is set beside what the record did next: the build actually made over the following 90 ft, the weight, speed and flow used, and at each stretch the gamma marks as out of the layer, whether the advisor called the way back at the first reading. The report, **SHADOW MODE**, is under the well's reports with a drawing of the lateral against the layer; the layer model is read off the well's own gamma in hindsight and says so - and grades how well it fits the well (good, fair, poor: a well steered to a rock that is not the low gamma reads poor, and the agent's calls against a poor model mean little) - unless the site's pre-drill model is given: a file `wells\Well-30636033\driller\model.json` with the config's `model` block (the target layer's top TVD at the heel, its thickness and dip, the gamma in, above and below, the heel's MD and TVD) is used whenever it is there (`gea workspace --path C:\site --action driller-shadow --well Well-30636033`). The export is read on this computer and nothing of it leaves it. Agreement with the driller says the two would have done alike, not that either was right. **The third dimension** (since 0.80.0): the lateral has an azimuth. The config's model carries the plan's azimuth (`plan_azimuth_deg`; empty, the first survey's at the heel is taken), the layer's dip across the plan line (`cross_dip_deg`, positive deepening to the right), the corridor the hole may run in to the right and left of the plan line (`corridor_ft`, the lease line and the offset wells) and where the heel sits across it (`heel_offset_ft`); the feed's surveys and the continuous azimuth (WITS item 0832, or the config's mapping) place the bit by minimum curvature along the plan, right of its line and in depth, and the screen draws the plan view - the corridor as a band, the hole against the plan line - under the section. The recommendation gains the aim - where to point the azimuth, along the plan or 4° left or right of it, and the turn that asks from where the hole points: *Build +1.5°/100 ft and aim 4° right of the plan (azimuth 44.0°), turning right 2.0°/100 ft (toolface 53°, 42% steering)* - with the build and the turn held together inside the DLS limit, and **Did something else…** takes the aim, or the turn made instead; the position filter carries the cross dip and reads it only when the hole moves across the plan line, leaving the model's value standing until then. In the twin the layer is a surface, the faults have a strike, the tool walks, and a hole that leaves the corridor by 150 ft is lost; the agent is judged on the hole in the corridor as well as in the layer (`gea-driller evaluate` prints both). Shadow mode reads the record's `azimuth_deg` column when it has one and sets the turn the advisor would have asked beside the turn the record made; without it the record's turns are not judged, and the report says so. **The vibration index from the feed** (since 0.81.0): a rig without a downhole vibration tool left the agent blind to the stick-slip and the whirl it was trained to ease, and the closed loop's vibration limit could never trip. Now the rig PC reads an index off the surface channels every EDR sends: over the last minute (`rig.vibration_window_s`), the surface torque's RMS about its mean as a fraction of the mean - the measure the Drill string page calls the oscillation index - times root two for the amplitude, and the same of the weight on bit and the hook load; stick-slip is the torque amplitude over 0.4, lateral vibration the weight amplitude over 0.2 (the twin's scale, where 1.2 is the limit), and the index is the larger. The downhole tool's item (WITS 0830) is taken instead whenever it comes, and every decision records which it read: the tile on the screen says *downhole tool* or *from surface data, stick-slip*, the reasons say *vibration 1.35 derived from the surface data (stick-slip, the surface torque swinging ±54%) over the limit 1.2*, and the limit disarms the loop on either. A surface proxy, labelled; on the twin as the rig it tracks the twin's own index within a few hundredths. The lateral file GEA writes for shadow mode carries, per foot, the surface channels' mean and RMS over the seconds of that foot (`torque_mean`, `torque_rms`, `wob_mean`, `wob_rms`, `hkld_mean`, `hkld_rms`, `rpm_mean`, `rpm_rms`, `spp_mean`, `spp_rms`), the replay reads the index off them for every decision, and the report says how often it stood over the limit and how often the advisor asked for less weight or more speed there than the record used; a record without torque or weight statistics says so and the advisor sees none. **The bar and the ceiling** (since 0.82.0): the agent is judged between two drillers on the same held-out scenes. The textbook driller is the bar - what a careful directional driller and geosteerer do by the book from the same observation the agent gets and nothing more: aim at the middle of the layer as the filter places it, steer back hard when the filter says the bit is out, lean away from a boundary the gamma's trend is running at, the rated weight in a calm hole in the layer and not while the hole fills, over the vibration limit lighter and faster first and heavier and slower when that did not quiet it, circulate at 40% of a bed, ream a balled bit, hold the plan line; it has a driller's memory of its own last decisions and none of the twin's secret. The oracle is the ceiling - the same driller told the twin's own layer at the bit and 120 ft ahead of it, which no policy can beat because it sees what no tool measures. `gea-driller evaluate` prints the three rows and how far the agent stands from the bar toward the ceiling; the self-test refuses a policy that does not beat the textbook, and the gate holds it under the oracle. The figures are a simulation's, labelled; a stronger textbook lowers the agent's standing without changing the agent, and that is the point of it. Over a cellular modem the rig PC joins GEA-VPN as a member of kind `driller` and GEA pulls from `http://10.77.0.4:8790`. The closed loop: `closed_loop.allowed` in the rig PC's config puts the switch on its screen; an operator arms it by name for one section of at most 500 ft (**Arm for this section**), every decision then goes to the downlink as a command, and the loop disarms itself on a stale feed, a crossed limit, the section's end or **Disarm now** - and this version's only downlink is the null one, which keeps every command on record and sends none, because no vendor's downlink protocol ships with it. From a terminal: `gea workspace --path C:\site --action driller-pull --box http://192.168.1.60:8790 --well SWD-1`; on the rig PC `gea-driller sim --seed 7 --pace 3 --port 8790`, `gea-driller evaluate --scenes 20`, `gea-driller train --seconds 600 --out policy.json`, `gea-driller selftest`.
+**The command**: on the rig PC, `GEA-Driller-0.89.0.tar.gz` from the release (or the kit's `installers` folder, fetched on the Audit / Update tab): unpack it and run `sudo sh install.sh` on Linux or `install.cmd` on Windows, once; edit its config - the EDR's WITS0 feed (`tcp`, the host and port; `serial`, the COM port), the pre-drill model (the target layer's top TVD at the heel, its thickness and dip, the gamma in, above and below, the deep-resistivity tool, the heel's MD and TVD), the tool's cap, the limits - and restart it. The driller's screen is at port 8790 of the rig PC: `http://192.168.1.60:8790/live`. It shows the section with the model's layer window, the hole drilled through it and - since 0.78.0 - the **position filter**'s band: where the layer is from the readings, as a geosteerer places it (a particle filter over the layer's offset from the model, its dip error and its thickness, moved every decision and kept to the guesses that explain the gamma and the deep-resistivity distance), with the probability the bit is in the layer, above or below it and the distance to the top and the base with its spread, sixty feet ahead; the agent reads the same estimate, and so does the textbook driller it is judged against. Then the recommendation in words - *Build +1.5°/100 ft (toolface up, 25% steering); 25 klb WOB, 120 rpm, 500 gpm* - with its reasons (what the deep-resistivity tool says, the gamma against the model's values, the model's bracket, the limits) and the confidence of each choice, the rig's numbers against the limits, and **Accept**, **Reject** or **Did something else…** with the operator's name. In GEA: the **Drill string** tab's card **GEA Driller** - the rig PC's address and the well, **Pull**: the records come in checked against their hashes, and the table says how many decisions, accepted, rejected, done otherwise, the hole under advice, the armed sections and the commands. **Open the driller's screen** opens the rig PC's screen from its address. Before there is a rig PC: **Start the twin as the rig** runs the driller's program on this computer with a scene drilling itself under the agent - **Open its screen** is the driller's screen with the twin behind it, labelled SIMULATION - and **Pull from it** brings its records in; **Stop it** closes them. **Shadow a drilled well** (since 0.79.0): a well of this workspace with a drilling-recorder export is replayed through the advisor - every 30 ft the agent sees what the rig had shown to that point and nothing past it, and its recommendation is set beside what the record did next: the build actually made over the following 90 ft, the weight, speed and flow used, and at each stretch the gamma marks as out of the layer, whether the advisor called the way back at the first reading. The report, **SHADOW MODE**, is under the well's reports with a drawing of the lateral against the layer; the layer model is read off the well's own gamma in hindsight and says so - and grades how well it fits the well (good, fair, poor: a well steered to a rock that is not the low gamma reads poor, and the agent's calls against a poor model mean little) - unless the site's pre-drill model is given: a file `wells\Well-30636033\driller\model.json` with the config's `model` block (the target layer's top TVD at the heel, its thickness and dip, the gamma in, above and below, the heel's MD and TVD) is used whenever it is there (`gea workspace --path C:\site --action driller-shadow --well Well-30636033`). The export is read on this computer and nothing of it leaves it. Agreement with the driller says the two would have done alike, not that either was right. **The third dimension** (since 0.80.0): the lateral has an azimuth. The config's model carries the plan's azimuth (`plan_azimuth_deg`; empty, the first survey's at the heel is taken), the layer's dip across the plan line (`cross_dip_deg`, positive deepening to the right), the corridor the hole may run in to the right and left of the plan line (`corridor_ft`, the lease line and the offset wells) and where the heel sits across it (`heel_offset_ft`); the feed's surveys and the continuous azimuth (WITS item 0832, or the config's mapping) place the bit by minimum curvature along the plan, right of its line and in depth, and the screen draws the plan view - the corridor as a band, the hole against the plan line - under the section. The recommendation gains the aim - where to point the azimuth, along the plan or 4° left or right of it, and the turn that asks from where the hole points: *Build +1.5°/100 ft and aim 4° right of the plan (azimuth 44.0°), turning right 2.0°/100 ft (toolface 53°, 42% steering)* - with the build and the turn held together inside the DLS limit, and **Did something else…** takes the aim, or the turn made instead; the position filter carries the cross dip and reads it only when the hole moves across the plan line, leaving the model's value standing until then. In the twin the layer is a surface, the faults have a strike, the tool walks, and a hole that leaves the corridor by 150 ft is lost; the agent is judged on the hole in the corridor as well as in the layer (`gea-driller evaluate` prints both). Shadow mode reads the record's `azimuth_deg` column when it has one and sets the turn the advisor would have asked beside the turn the record made; without it the record's turns are not judged, and the report says so. **The vibration index from the feed** (since 0.81.0): a rig without a downhole vibration tool left the agent blind to the stick-slip and the whirl it was trained to ease, and the closed loop's vibration limit could never trip. Now the rig PC reads an index off the surface channels every EDR sends: over the last minute (`rig.vibration_window_s`), the surface torque's RMS about its mean as a fraction of the mean - the measure the Drill string page calls the oscillation index - times root two for the amplitude, and the same of the weight on bit and the hook load; stick-slip is the torque amplitude over 0.4, lateral vibration the weight amplitude over 0.2 (the twin's scale, where 1.2 is the limit), and the index is the larger. The downhole tool's item (WITS 0830) is taken instead whenever it comes, and every decision records which it read: the tile on the screen says *downhole tool* or *from surface data, stick-slip*, the reasons say *vibration 1.35 derived from the surface data (stick-slip, the surface torque swinging ±54%) over the limit 1.2*, and the limit disarms the loop on either. A surface proxy, labelled; on the twin as the rig it tracks the twin's own index within a few hundredths. The lateral file GEA writes for shadow mode carries, per foot, the surface channels' mean and RMS over the seconds of that foot (`torque_mean`, `torque_rms`, `wob_mean`, `wob_rms`, `hkld_mean`, `hkld_rms`, `rpm_mean`, `rpm_rms`, `spp_mean`, `spp_rms`), the replay reads the index off them for every decision, and the report says how often it stood over the limit and how often the advisor asked for less weight or more speed there than the record used; a record without torque or weight statistics says so and the advisor sees none. **The bar and the ceiling** (since 0.82.0): the agent is judged between two drillers on the same held-out scenes. The textbook driller is the bar - what a careful directional driller and geosteerer do by the book from the same observation the agent gets and nothing more: aim at the middle of the layer as the filter places it, steer back hard when the filter says the bit is out, lean away from a boundary the gamma's trend is running at, the rated weight in a calm hole in the layer and not while the hole fills, over the vibration limit lighter and faster first and heavier and slower when that did not quiet it, circulate at 40% of a bed, ream a balled bit, hold the plan line; it has a driller's memory of its own last decisions and none of the twin's secret. The oracle is the ceiling - the same driller told the twin's own layer at the bit and 120 ft ahead of it, which no policy can beat because it sees what no tool measures. `gea-driller evaluate` prints the three rows and how far the agent stands from the bar toward the ceiling; the self-test refuses a policy that does not beat the textbook, and the gate holds it under the oracle. The figures are a simulation's, labelled; a stronger textbook lowers the agent's standing without changing the agent, and that is the point of it. Over a cellular modem the rig PC joins GEA-VPN as a member of kind `driller` and GEA pulls from `http://10.77.0.4:8790`. The closed loop: `closed_loop.allowed` in the rig PC's config puts the switch on its screen; an operator arms it by name for one section of at most 500 ft (**Arm for this section**), every decision then goes to the downlink as a command, and the loop disarms itself on a stale feed, a crossed limit, the section's end or **Disarm now** - and this version's only downlink is the null one, which keeps every command on record and sends none, because no vendor's downlink protocol ships with it. From a terminal: `gea workspace --path C:\site --action driller-pull --box http://192.168.1.60:8790 --well SWD-1`; on the rig PC `gea-driller sim --seed 7 --pace 3 --port 8790`, `gea-driller evaluate --scenes 20`, `gea-driller train --seconds 600 --out policy.json`, `gea-driller selftest`.
 
 **What it writes**: on the rig PC, `decisions.jsonl` (every observation, recommendation, confidence, reasons and answer), `commands.jsonl` (every arming, command and disarming with its reason) and `surveys.csv`, each with a `.sha256` beside it, and `manifest.json`. In GEA, `wells\SWD-1\driller\` holds the same files as pulled, `manifest.json` and `last_pull.json` with the summary; the audit lines `driller.pull`, `driller.sim_start`, `driller.sim_stop`. The twin as the rig writes under `field\sim-driller\data`.
 

{gea_program-0.88.0 → gea_program-0.89.0}/gea/help/install.md

@@ -2,7 +2,7 @@
 
 > GEA-Program-Setup: the program installed for you like any Windows program - a window of its own, an icon in the notification area, Start-menu and desktop shortcuts, an Add/Remove Programs entry, upgrades in place - with no administrator rights and the site's data left where it is.
 
-**The command**: download the setup from the release on GitHub (`GEA-Program-Setup-0.88.0.exe` for this version) and run it. It installs for you alone, under `%LOCALAPPDATA%\Programs\GEA-Program`, and asks for the site workspace - the folder that holds the wells, reports, records, accounts and keys. An existing one such as `C:\site` is used exactly as it is, its name included; for a new one (by default `%LOCALAPPDATA%\GEA-Program\site`) it also asks the site's name, which heads every report, and makes the workspace with it (left empty, the workspace is named after its folder; an administrator renames the site in Administration's site settings). Then the Start menu's **GEA-Program** (and the desktop shortcut) starts the control panel when it is not running and opens it in a window of its own. A newer setup installs over the older one: it stops the control panel, replaces the program, keeps the workspace and the choices made before. For a site's software deployment: `GEA-Program-Setup-0.88.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"` (`/SITENAME` names a workspace the setup makes; one that exists keeps its own name). From a terminal: `gea launch` does what the shortcut does, `gea launch --selftest` says what it would do, `gea tray --selftest` checks the icon.
+**The command**: download the setup from the release on GitHub (`GEA-Program-Setup-0.89.0.exe` for this version) and run it. It installs for you alone, under `%LOCALAPPDATA%\Programs\GEA-Program`, and asks for the site workspace - the folder that holds the wells, reports, records, accounts and keys. An existing one such as `C:\site` is used exactly as it is, its name included; for a new one (by default `%LOCALAPPDATA%\GEA-Program\site`) it also asks the site's name, which heads every report, and makes the workspace with it (left empty, the workspace is named after its folder; an administrator renames the site in Administration's site settings). Then the Start menu's **GEA-Program** (and the desktop shortcut) starts the control panel when it is not running and opens it in a window of its own. A newer setup installs over the older one: it stops the control panel, replaces the program, keeps the workspace and the choices made before. For a site's software deployment: `GEA-Program-Setup-0.89.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"` (`/SITENAME` names a workspace the setup makes; one that exists keeps its own name). From a terminal: `gea launch` does what the shortcut does, `gea launch --selftest` says what it would do, `gea tray --selftest` checks the icon.
 
 **The window**: Microsoft Edge's app window (`msedge --app=`: the control panel with no tabs and no address bar, its own button on the taskbar, which shows the program's derrick and pins as GEA-Program, not as Edge), with a browser profile of its own (`%LOCALAPPDATA%\GEA-Program\window`, no extensions; the first time, Edge may say it signed that profile in to your Microsoft account - Got it), else Google Chrome's, else a tab in the default browser. Where the browser keeps no cookies (its settings or a policy block them), the sign-in page says so and the control panel holds the sign-in itself, in the window's address, until the window is closed. The control panel itself runs with no window of its own: `gea supervise` keeps it running in the background, starts it again when it asks for a restart, and writes everything it would have shown in a console - the start, the sign-ins, the jobs, a stop and why - to `records\console.log` in the workspace. No PowerShell or console window opens. The kit's `start-dashboard.cmd` still runs it in a console window, for a site that wants to watch it there.
 
@@ -18,7 +18,7 @@
 
 **The number to check**: Add/Remove Programs lists GEA-Program with the version you installed; `gea doctor --workspace C:\site` ends with `nothing blocks serving`; the Start menu's **Verify GEA-Program** runs the acceptance gate from the installation and ends with `[ACCEPTANCE] OK - N checks passed`. The release's build installs, upgrades and uninstalls the setup silently before it is published, with the control panel running, and checks the workspace untouched afterwards.
 
-**Signed**: when the publisher's code-signing certificate is configured for the build, the setup is signed with it (Authenticode, timestamped) and Windows names the publisher; until then it ships unsigned and Windows SmartScreen says "unknown publisher" (More info, then Run anyway). The build's provenance holds either way: `gh attestation verify GEA-Program-Setup-0.88.0.exe -R Daniel8Murphy0007/GEA-Program`. The uninstaller the setup leaves behind is Inno Setup's own and is not signed separately.
+**Signed**: when the publisher's code-signing certificate is configured for the build, the setup is signed with it (Authenticode, timestamped) and Windows names the publisher; until then it ships unsigned and Windows SmartScreen says "unknown publisher" (More info, then Run anyway). The build's provenance holds either way: `gh attestation verify GEA-Program-Setup-0.89.0.exe -R Daniel8Murphy0007/GEA-Program`. The uninstaller the setup leaves behind is Inno Setup's own and is not signed separately.
 
 **What this page will not call a measurement**: the icon's running or stopped is whether the control panel's port answers on this computer, read every three seconds - not whether every patch, job or report behind it is healthy (Home and the Verification page say that).
 

gea_program-0.89.0/gea/help/mcp.md

@@ -0,0 +1,15 @@
+# Assistant access (MCP)
+
+> The site, readable by an assistant. A chat program that speaks the Model Context Protocol can be given this program as a tool box: it starts `gea mcp` as its own child process, asks what tools there are, and calls them. Each tool is one of this program's pages - the rig time, the roadmap, the drilling alerts, the fluid balance - read out as the text the command line prints, so what the assistant says about the site is what the program says. It is local (it listens on no port), read-only (no tool declares, attaches, removes, writes or sets anything) and logged (every call is a line in the workspace). What a tool returns goes into the assistant's conversation, and so to whoever runs the model behind it: offering a tool is deciding that its page may leave the site.
+
+**The command**: the **Assistant access** tab. **Add to Claude Desktop** (an administrator) writes one entry, `gea`, into Claude Desktop's own configuration file on this computer, keeps every other entry and leaves a dated copy of the file as it was; then quit Claude Desktop completely and start it again, and the tools are under its connectors. **Take it out of Claude Desktop** removes the entry the same way. For any other MCP client, **Copy** the entry shown and paste it into that client's configuration. **The tools** table is the choice of what an assistant may read: untick a page that must not leave the site and **Keep** (an operator), with who decided and on what grounds; a tool not offered is not listed to the assistant and cannot be called. **The access log** shows the last calls. From a terminal: `gea mcp --workspace C:\site` is the server itself - it waits on its standard input and is what the assistant runs, not something to start by hand; `gea mcp --workspace C:\site --status` prints the tools offered, how to start it and the last calls; `gea mcp --workspace C:\site --config` prints the entry for a client's configuration; `gea mcp --workspace C:\site --call roadmap` prints one tool's answer as an assistant would get it (`--well` names a well, `--json` asks for the page as JSON); `gea mcp --workspace C:\site --offer site,rig_time,roadmap,drilling_alerts,help --source "site manager, 2026-11-13: drilling pages only"` keeps the choice (`--offer all` offers every tool again); `gea mcp --workspace C:\site --add-to-claude-desktop` and `--remove-from-claude-desktop` do what the buttons do; `gea mcp` alone runs the self-test.
+
+**What it writes**: `records/mcp_access.jsonl` - a line a call: the time, the tool, its arguments, the client as it names itself, whether it answered, how many characters and how long, and a call for a tool that is withheld or does not exist as turned away (the file is set aside as `.1` when it passes 5 MB). `records/mcp.json` when the choice of tools or the limit is changed (audit line `mcp.settings`). Claude Desktop's `claude_desktop_config.json` and a copy `claude_desktop_config.json.before-gea-<time>` beside it, only when the button or the command is used (audit line `mcp.claude_desktop`). Nothing else: no tool writes a record, a declaration, a report or a setting. Reading a page for the first time may build that well's chart cache, as opening its tab would.
+
+**The tools**: `site` (the wells), `well` (one well as declared), `rig_time`, `drill_string`, `roadmap`, `drilling_alerts`, `torque_drag`, `hydraulics`, `pore_pressure`, `casing`, `collision`, `plan_vs_actual`, `frac_hits`, `fluid_balance`, `pressure_plume`, `fluid_front`, `calibration` (the kept result; it runs nothing), `decline`, `invoice_check`, `seismicity`, `alerts`, `audit` and `help`. Those that read a well take `well`, by name or id; `alerts` and `audit` take `n`; `help` takes `topic`; every tool but `help` takes `json` for the page as the program's own structure instead of its text. An answer longer than the limit (40,000 characters unless changed) is cut and says so. Each tool declares itself read-only to the client, which is the client's cue not to ask for confirmation on every call - and is true.
+
+**The protocol**: JSON-RPC 2.0, one message a line, on the standard input and output of the process the client starts; anything the program would otherwise print goes to the error stream. Two eras are spoken, chosen by how the client opens. A client of revision 2026-07-28 sends each request with its protocol version in `_meta` and is answered statelessly, every result carrying `resultType`, with `server/discover` for the versions and capabilities; a version it does not speak is answered with error -32022 and the versions it does. A client of 2025-11-25, 2025-06-18, 2025-03-26 or 2024-11-05 opens with `initialize` and is answered with the handshake of the revision it names. Tools only: no resources, no prompts, and nothing is ever asked of the client. An unknown or withheld tool is error -32602; a well that does not exist or a page that cannot be computed is an ordinary answer marked as an error, with what to do about it.
+
+**The number to check**: one tool's answer against its tab - `gea mcp --workspace C:\site --call rig_time` beside the Rig time tab: the same figures, because it is the same function; and the access log's count of calls against what was asked of the assistant. On the self-test `gea mcp` runs, a client of each era opens against a labelled site, lists the tools and calls them; a line that is not JSON, a tool that does not exist, a well that does not and an argument a tool does not take are each answered as what they are; a withheld tool is not listed and cannot be called; and the entry is added to a configuration file with its other entries kept, and taken out again.
+
+**What this page will not call a measurement**: privacy - the server is local, the assistant is not, and nothing here controls what the assistant's maker does with what it is given; the assistant's answer - a tool returns the program's page, and what the assistant then writes about it is the assistant's, to be checked against the page; who is asking - a client names itself, and that name is logged as given, not verified; a SIMULATION - the plume, the front and the calibration are projections here exactly as they are on their tabs, and say so in their first line; silence - a page that says nothing is declared has no figures, and an assistant that supplies some did not get them from here.

{gea_program-0.88.0 → gea_program-0.89.0}/gea/help/reader.md

@@ -4,7 +4,7 @@
 
 **The command**: Reports tab -> Signed dossiers -> **Download GEA Reader for your clients**, or `gea reader --workspace C:\site --out C:\site\GEA-Reader.html`. Send the file once, by any channel (email, a USB stick, the client's portal); send the site's key fingerprint separately - by phone, email or in the contract - as for any dossier. The client opens GEA-Reader.html, drops a dossier on it (or chooses it), and reads the verdict: **Valid** (signed with the site's key, or with a newer key the site's key handed over to), **Valid, but signed by a key you were not given**, or **Not valid** with the reason. Below the verdict: each check, the signer's fingerprint, the key hand-overs, and every file the dossier holds - a report opens in the page as it was signed, a PDF in the browser's own viewer, a table or a log as text, and any file can be saved. A dossier that lists source records by hash without carrying them lets the client choose their copies and checks each against its hash.
 
-**The program**: for a client who wants it installed, **GEA-Reader-Setup-0.88.0.exe** on the release page installs GEA Reader as a Windows program of its own, for the signed-in user, with no administrator rights and nothing of GEA-Program: GEA Reader in the Start menu and on the desktop with its own icon (a white page with a green seal, on blue) and its own taskbar button, and **Check with GEA Reader** on the right-click menu of .zip files (on Windows 11, under Show more options), which opens the dossier at once. It opens the same page in Microsoft Edge's app window with a browser profile of its own (`%LOCALAPPDATA%\GEA-Reader\window`), so a fingerprint the client saves - **Remember this fingerprint**, with whose it is - stays on that computer, and every later dossier signed with that key reads **Valid** with the name the client gave it. `GEA-Reader-portable-0.88.0.zip` is the same program to unzip and run (`GEA-Reader.cmd`). `python\python.exe -m gea_reader --selftest`, in the installed folder, checks the page, the icon, the taskbar identity and the hand-over of a dossier without opening a window.
+**The program**: for a client who wants it installed, **GEA-Reader-Setup-0.89.0.exe** on the release page installs GEA Reader as a Windows program of its own, for the signed-in user, with no administrator rights and nothing of GEA-Program: GEA Reader in the Start menu and on the desktop with its own icon (a white page with a green seal, on blue) and its own taskbar button, and **Check with GEA Reader** on the right-click menu of .zip files (on Windows 11, under Show more options), which opens the dossier at once. It opens the same page in Microsoft Edge's app window with a browser profile of its own (`%LOCALAPPDATA%\GEA-Reader\window`), so a fingerprint the client saves - **Remember this fingerprint**, with whose it is - stays on that computer, and every later dossier signed with that key reads **Valid** with the name the client gave it. `GEA-Reader-portable-0.89.0.zip` is the same program to unzip and run (`GEA-Reader.cmd`). `python\python.exe -m gea_reader --selftest`, in the installed folder, checks the page, the icon, the taskbar identity and the hand-over of a dossier without opening a window.
 
 **What it writes**: the one file, GEA-Reader.html (about 40 KB): the checks, written in the page's own script - Ed25519 (RFC 8032) in its own arithmetic, SHA-256 from the browser - and, when made from a workspace, the site's name and the fingerprints of every key it has signed with (the current one and each retired one from the key history: public halves only; the signing key never leaves `keys\`). The audit log records each download (`reader.download`) and each `gea reader` (`reader.write`) with the fingerprints the reader carried. The reader page writes nothing on the client's computer but the fingerprints a client saves (in the browser's storage for the page): it reads the zip it is given, in memory, and a saved copy goes where the client's browser saves downloads. The installed program also writes the page it opens to `%LOCALAPPDATA%\GEA-Reader\page` (with the dossier inside it when one was right-clicked; removed ten minutes later) and its right-click entry under the user's own registry keys, removed with the program.