@melaya/runner 1.1.80 → 1.1.81

package/dist/assistantHost.py

@@ -282,6 +282,7 @@ _DELTA_FLUSH_MS = 35
 
 # Sentinel returned by a turn's coroutine when the user pressed STOP.
 _CANCELLED = object()
+_DEFERRED = object()  # EXCOM: the turn ended on an approval request
 
 
 class _RedactingStdout:
@@ -567,7 +568,8 @@ def _apply_turn_update(req) -> None:
     if not tid or tid != _stream.get("turnId"):
         return
     changed = False
-    if "hitl_mode" in req:
+    # An EXCOM turn keeps the server gate: a mode change never re-arms the card.
+    if "hitl_mode" in req and not _EXCOM_GATE.get("on"):
         _apply_hitl_mode(req.get("hitl_mode"))
         _log(f"autonomy changed mid-turn -> {os.environ.get('MEL_ASSISTANT_HITL_MODE')}")
         changed = True
@@ -650,6 +652,15 @@ def _autonomy_block() -> str:
     approval_required result and only THEN pauses. Refreshed every turn so a
     safe<->autonomous flip takes effect on the next message (the tool gate env is
     flipped in the same turn by _apply_hitl_mode)."""
+    if _EXCOM_GATE.get("on"):
+        # EXCOM executive: its autonomy is the server's gate, not this mode.
+        return (
+            "\n\n## AUTONOMY: decided by the executive gate\n"
+            "Every tool call is checked by the server against your autonomy, grants and rules "
+            "before it runs. A refused call returns the reason: do not retry it, adjust or propose "
+            "it as a task for the humans. A call that needs a human returns approval_pending: "
+            "stop there, the turn ends and resumes once a human decides.\n"
+        )
     mode = (os.environ.get("MEL_ASSISTANT_HITL_MODE", "safe") or "safe").lower()
     if mode == "autonomous":
         return (
@@ -735,6 +746,184 @@ def _emit(turn_id: str, kind: str, **fields) -> None:
         pass
 
 
+# ── EXCOM gate (server-authoritative tool gate) ─────────────────────────────
+# An EXCOM executive whose model runs here gets exactly the gate it has on a
+# cloud model: before EVERY tool call of its turn this host asks the server
+# (stdout frame `excom_gate` {gateId, tool, args} -> runner -> server, which
+# evaluates the turn's own constraint) and waits for the answer on stdin
+# (`excom_gate_reply` {gateId, decision, message, requestId, cached, report}):
+#   allow -> run the tool, then report its metadata (`excom_gate_result`
+#            {gateId, ok, chars, uncertain}; plus `content` when the server
+#            asked for it: vault reads, for the internal-excerpt guard);
+#            `cached` -> answer with that text, nothing runs;
+#   deny  -> the tool does not run; the model sees the server's reason;
+#   ask   -> the approval card is staged server side; the model sees
+#            approval_pending and the turn ends (the job parks on it).
+# Fail closed: no answer within MEL_EXCOM_GATE_TIMEOUT_S (default 30 s), a
+# malformed answer, or a gate that cannot be installed => nothing runs. The
+# runner's own Safe-mode card is not part of it: the server decides.
+_EXCOM_GATE: dict = {
+    "on": False, "turnId": "", "installed": False, "deferred": None,
+    "lock": threading.Lock(), "waiters": {},
+}
+_EXCOM_GATE_CONTENT_MAX = 64_000
+
+
+def _excom_gate_timeout() -> float:
+    try:
+        return max(2.0, min(120.0, float(os.environ.get("MEL_EXCOM_GATE_TIMEOUT_S", "30") or 30)))
+    except Exception:
+        return 30.0
+
+
+def _excom_gate_deny(gate_id: str, message: str) -> dict:
+    return {"gateId": gate_id, "decision": "deny", "message": message}
+
+
+def _excom_gate_ask(tool: str, args) -> dict:
+    """Blocking: ask the server for a decision on one tool call (worker thread)."""
+    gid = _uuid.uuid4().hex
+    ev = threading.Event()
+    slot = {"ev": ev, "reply": None}
+    with _EXCOM_GATE["lock"]:
+        _EXCOM_GATE["waiters"][gid] = slot
+    try:
+        _emit(str(_EXCOM_GATE.get("turnId") or ""), "excom_gate", gateId=gid, tool=str(tool or ""),
+              args=args if isinstance(args, dict) else {})
+        if not ev.wait(_excom_gate_timeout()):
+            return _excom_gate_deny(gid, "The executive gate did not answer in time, so nothing ran. Try again later or propose it as a task for the humans.")
+        reply = slot["reply"]
+    finally:
+        with _EXCOM_GATE["lock"]:
+            _EXCOM_GATE["waiters"].pop(gid, None)
+    if not isinstance(reply, dict) or reply.get("gateId") != gid or reply.get("decision") not in ("allow", "deny", "ask"):
+        return _excom_gate_deny(gid, "The executive gate answered something unreadable, so nothing ran.")
+    return reply
+
+
+def _excom_gate_deliver(reply) -> bool:
+    """stdin-reader thread: hand a server answer to the waiting call."""
+    if not isinstance(reply, dict):
+        return False
+    gid = str(reply.get("gateId") or "")
+    with _EXCOM_GATE["lock"]:
+        slot = _EXCOM_GATE["waiters"].get(gid)
+    if not slot:
+        return False
+    slot["reply"] = reply
+    slot["ev"].set()
+    return True
+
+
+def _excom_gate_release_all() -> None:
+    """Turn end / channel loss: every waiting call is denied (fail closed)."""
+    with _EXCOM_GATE["lock"]:
+        slots = list(_EXCOM_GATE["waiters"].items())
+    for gid, slot in slots:
+        slot["reply"] = _excom_gate_deny(gid, "The executive gate is gone, so nothing ran.")
+        slot["ev"].set()
+
+
+def _excom_gate_report(gate_id: str, ok: bool, text: str, uncertain: bool, with_content: bool) -> None:
+    fields = {"gateId": gate_id, "ok": bool(ok), "chars": len(text or ""), "uncertain": bool(uncertain)}
+    if with_content and ok:
+        fields["content"] = (text or "")[:_EXCOM_GATE_CONTENT_MAX]
+    _emit(str(_EXCOM_GATE.get("turnId") or ""), "excom_gate_result", **fields)
+
+
+def _excom_text_response(text: str):
+    from agentscope.tool import ToolResponse
+    from agentscope.message import TextBlock
+    return ToolResponse(content=[TextBlock(type="text", text=str(text))])
+
+
+def _excom_response_text(resp) -> str:
+    try:
+        content = getattr(resp, "content", None) or []
+        parts = []
+        for b in content:
+            t = b.get("text") if isinstance(b, dict) else getattr(b, "text", None)
+            if isinstance(t, str):
+                parts.append(t)
+        return "\n".join(parts)
+    except Exception:
+        return ""
+
+
+def _excom_looks_failed(text: str) -> bool:
+    head = (text or "").lstrip()[:80].lower()
+    return head.startswith(("error", "could not", "failed", "functionnotfounderror", "tool error"))
+
+
+async def _excom_gate_middleware(kwargs, next_handler):
+    """agentscope Toolkit middleware: the gate around every tool call."""
+    if not _EXCOM_GATE.get("on"):
+        async for chunk in next_handler(**kwargs):
+            yield chunk
+        return
+    import asyncio
+    tc = kwargs.get("tool_call") or {}
+    name = str((tc.get("name") if isinstance(tc, dict) else getattr(tc, "name", "")) or "")
+    args = (tc.get("input") if isinstance(tc, dict) else getattr(tc, "input", None)) or {}
+    if _EXCOM_GATE.get("deferred"):
+        yield _excom_text_response("Not run: this turn is waiting for a human approval and ends now.")
+        return
+    reply = await asyncio.to_thread(_excom_gate_ask, name, args)
+    decision = reply.get("decision")
+    if decision == "ask":
+        yield _excom_text_response(str(reply.get("message") or json.dumps({"status": "approval_pending", "requestId": reply.get("requestId"), "tool": name})))
+        # The turn ends after this round, like the cloud loop (the job parks).
+        _EXCOM_GATE["deferred"] = {"requestId": str(reply.get("requestId") or ""), "tool": name}
+        return
+    if decision != "allow":
+        yield _excom_text_response(str(reply.get("message") or "Outside this executive's autonomy. Nothing ran."))
+        return
+    if isinstance(reply.get("cached"), str):
+        yield _excom_text_response(reply["cached"])
+        return
+    gid = str(reply.get("gateId") or "")
+    is_write = reply.get("isWrite") is True
+    last = None
+    try:
+        async for chunk in next_handler(**kwargs):
+            last = chunk
+            yield chunk
+    except BaseException:
+        # Cancelled, timed out or raised: a write may have happened.
+        _excom_gate_report(gid, False, "", is_write, False)
+        raise
+    text = _excom_response_text(last)
+    failed = _excom_looks_failed(text)
+    _excom_gate_report(gid, not failed, text, failed and is_write and "timeout" in text.lower(), reply.get("report") == "content")
+
+
+def _install_excom_gate(toolkit) -> bool:
+    try:
+        if toolkit is None or not hasattr(toolkit, "register_middleware"):
+            return False
+        toolkit.register_middleware(_excom_gate_middleware)
+        return True
+    except Exception as exc:
+        _log(f"excom gate middleware unavailable: {type(exc).__name__}")
+        return False
+
+
+def _excom_gate_begin(turn_id: str) -> None:
+    _EXCOM_GATE["on"] = True
+    _EXCOM_GATE["turnId"] = turn_id
+    _EXCOM_GATE["deferred"] = None
+    # The server decides every call: the host's own Safe-mode card stays out
+    # (lazy_registry reads the mode at call time).
+    _apply_hitl_mode("autonomous")
+
+
+def _excom_gate_end() -> None:
+    _EXCOM_GATE["on"] = False
+    _EXCOM_GATE["turnId"] = ""
+    _EXCOM_GATE["deferred"] = None
+    _excom_gate_release_all()
+
+
 # ── Output files (assistant protocol 4) ──────────────────────────────────────
 # A turn frame may carry `output_dir`: a fresh folder the runner made for THIS
 # turn. It becomes MELAYA_OUTPUT_DIR for the turn, so every file-producing tool
@@ -1096,6 +1285,11 @@ def _build_agent():
         except Exception:
             toolkit = build_toolkit(names=[])
 
+    # EXCOM gate: the server decides every tool of an executive's turn. The
+    # middleware is a no-op on every other turn; without it an EXCOM turn is
+    # refused (fail closed, see the turn loop in main()).
+    _EXCOM_GATE["installed"] = _install_excom_gate(toolkit)
+
     phone_rule = (
         "- If the user asks you to DO something on their phone (open an app, browse, "
         "tap, type, comment, post), use the phone_* tools. ALWAYS call "
@@ -1704,6 +1898,15 @@ def _run_turn(agent, turn_id: str, message: str, browser_turn: bool = False, ima
                 except BaseException:  # CancelledError + any teardown error
                     pass
                 return _CANCELLED
+            # EXCOM: a call went to a human approval; the turn ends after
+            # this round (the job parks), like the cloud loop.
+            if _EXCOM_GATE.get("on") and _EXCOM_GATE.get("deferred"):
+                task.cancel()
+                try:
+                    await task
+                except BaseException:
+                    pass
+                return _DEFERRED
             if wallclock_s and time.time() - started_at > wallclock_s:
                 task.cancel()
                 try:
@@ -1742,6 +1945,16 @@ def _run_turn(agent, turn_id: str, message: str, browser_turn: bool = False, ima
         _emit(turn_id, "done")
         return
 
+    if result is _DEFERRED:
+        _flush_delta(turn_id)
+        _stream["turnId"] = ""
+        pend = _EXCOM_GATE.get("deferred") or {}
+        _log("turn ends on an EXCOM approval request")
+        _emit(turn_id, "text", content=f"Waiting for a human approval of {pend.get('tool') or 'an action'}. The work continues once it is decided.")
+        _emit_turn_files(turn_id)
+        _emit(turn_id, "done")
+        return
+
     if result is _WALLCLOCK:
         _stream["turnId"] = ""
         _log("browser turn wall-clock budget exceeded")
@@ -1789,6 +2002,11 @@ def _stdin_reader(q: "queue.Queue[str]") -> None:
                     if not tid or tid == _stream.get("turnId"):
                         _stream["cancel"] = True
                     continue  # consumed — do not queue as a turn
+                # EXCOM gate answer: wakes the tool call waiting on it, WHILE
+                # the turn runs. Never queued as a turn.
+                if isinstance(req, dict) and req.get("kind") == "excom_gate_reply":
+                    _excom_gate_deliver(req)
+                    continue
                 # Live mid-turn update (autonomy mode / connectors): applied HERE,
                 # while the turn runs, like STOP. Never queued as a turn.
                 if isinstance(req, dict) and req.get("kind") == "turn_update":
@@ -1801,6 +2019,7 @@ def _stdin_reader(q: "queue.Queue[str]") -> None:
     except Exception:
         pass
     finally:
+        _excom_gate_release_all()  # no answer can come any more: deny (fail closed)
         q.put("")  # sentinel: stdin closed
 
 
@@ -1958,6 +2177,20 @@ def main() -> int:
         # it here (before _run_turn) is enough — no agent rebuild needed.
         if "hitl_mode" in req:
             _apply_hitl_mode(req.get("hitl_mode"))
+        # EXCOM gate: the server decides every tool of this turn. A host that
+        # cannot install the gate refuses the turn (fail closed).
+        excom_gate = bool(req.get("excom_gate"))
+        if excom_gate and not _EXCOM_GATE.get("installed"):
+            _log("excom gate requested but unavailable: turn refused")
+            _emit(turn_id, "error", code="runner_constraint_unsupported", message=(
+                "This runner cannot enforce the executive's autonomy gate, so nothing ran. "
+                "Update the runner, or pick a cloud model for this executive."))
+            _emit(turn_id, "done")
+            continue
+        if excom_gate:
+            _excom_gate_begin(turn_id)
+        else:
+            _EXCOM_GATE["on"] = False
         # Product usage attribution is per turn. This must be applied before the
         # AgentScope spans are created; _emit_usage force-flushes them before the
         # next turn can replace the value.
@@ -1974,6 +2207,8 @@ def main() -> int:
         _apply_static_context(agent, base_sys_prompt, req.get("static_context"))
         if not message and not images:
             _purge_connector_env()
+            if excom_gate:
+                _excom_gate_end()
             _emit(turn_id, "done")
             continue
         # P2-6: nudge the live memory budget down if a prior turn's OOM downgraded
@@ -1989,6 +2224,8 @@ def main() -> int:
         try:
             _run_turn(agent, turn_id, message, browser_turn=browser_turn, images=images)
         finally:
+            if excom_gate:
+                _excom_gate_end()
             _clear_turn_output_dir()
             _purge_browser_turn_grant()
             # Connector credentials live for the turn only; the selection (ids,

package/dist/connection.js

@@ -57,6 +57,7 @@ import { reportHostFile, reportOutputsSince } from "./hostFiles.js";
 // Computer control: computer:command / computer:stop relayed to the desktop app
 // executor (or the CLI computer host); capabilities reported on connect.
 import { attachComputerRelay } from "./computerRelay.js";
+import { EXCOM_GATE_VERSION, relayExcomGate, relayExcomGateResult } from "./excomGate.js";
 // Model rediscovery while connected (audit P2.3): every 15 min, and skipped
 // when the provider fingerprint (credential/cache file mtimes + local server
 // ports) is unchanged since the last scan, unless that scan is older than
@@ -613,6 +614,11 @@ export async function connect(opts) {
             package: "@melaya/runner",
             version: RUNNER_VERSION,
             assistantProtocol: ASSISTANT_PROTOCOL_VERSION,
+            // EXCOM gate (excomGate.ts): this runner's host asks the server before
+            // every tool of an EXCOM executive's turn and fails closed without an
+            // answer. The server allows Prepare, Run and vault writes on a runner
+            // model only when this is advertised.
+            excomGate: EXCOM_GATE_VERSION,
             // Browser control capability report (plan Section 4).
             browserControl: {
                 version: BROWSER_CONTROL_VERSION,
@@ -1848,6 +1854,21 @@ export async function connect(opts) {
                             }
                             continue;
                         }
+                        // EXCOM gate frames (excomGate.ts): answered here, never forwarded
+                        // as assistant events. A host frame from a spare (no session) is denied.
+                        if (parsed?.kind === "excom_gate") {
+                            const write = (l) => { proc.stdin?.write(l); };
+                            if (session.forward)
+                                void relayExcomGate(parsed, { sessionId: session.sid, socket, write });
+                            else
+                                write(JSON.stringify({ kind: "excom_gate_reply", gateId: String(parsed.gateId || ""), decision: "deny", message: "No executive session on this host, so nothing ran." }) + "\n");
+                            continue;
+                        }
+                        if (parsed?.kind === "excom_gate_result") {
+                            if (session.forward)
+                                relayExcomGateResult(parsed, { sessionId: session.sid, socket });
+                            continue;
+                        }
                         if (parsed?.kind === "done" && typeof parsed.turnId === "string")
                             session.turnFiles?.delete(parsed.turnId);
                         if (typeof parsed?.memoryWatermark === "number")
@@ -2574,6 +2595,8 @@ export async function connect(opts) {
                 // v4: the turn's output dir (absent: the host keeps its boot-time dir
                 // and reports no files).
                 ...(turnOutDir ? { output_dir: turnOutDir } : {}),
+                // EXCOM gate: the host asks before every tool and fails closed.
+                ...(Number(payload.excomGate) >= 1 ? { excom_gate: 1 } : {}),
             }) + "\n");
         }
         catch (e) {

package/dist/excomGate.d.ts

@@ -0,0 +1,32 @@
+/** Advertised as `excomGate` in runner:hello (server EXCOM_GATE_VERSION). */
+export declare const EXCOM_GATE_VERSION = 1;
+/** Below the host's own wait (MEL_EXCOM_GATE_TIMEOUT_S, 30 s), so the host gets an explicit deny. */
+export declare const EXCOM_GATE_ACK_MS = 25000;
+export interface GateSocketLike {
+    connected?: boolean;
+    emit(event: string, payload: unknown, ack?: (reply: unknown) => void): unknown;
+}
+export interface GateRelayCtx {
+    sessionId: string;
+    socket: GateSocketLike;
+    /** Writes one line to the host's stdin. */
+    write: (line: string) => void;
+    timeoutMs?: number;
+}
+export type GateDecision = "allow" | "deny" | "ask";
+export interface GateReplyFrame {
+    kind: "excom_gate_reply";
+    gateId: string;
+    decision: GateDecision;
+    message?: string;
+    requestId?: string;
+    cached?: string;
+    report?: "meta" | "content";
+    isWrite?: boolean;
+}
+/** The reply the host gets: only known fields, any doubt is a deny. */
+export declare function sanitizeGateReply(gateId: string, raw: unknown): GateReplyFrame;
+/** One `excom_gate` frame from the host: ask the server, answer the host once. */
+export declare function relayExcomGate(frame: Record<string, unknown>, ctx: GateRelayCtx): Promise<GateReplyFrame>;
+/** One `excom_gate_result` frame from the host: metadata to the server (best-effort). */
+export declare function relayExcomGateResult(frame: Record<string, unknown>, ctx: Pick<GateRelayCtx, "sessionId" | "socket">): boolean;

package/dist/excomGate.js

@@ -0,0 +1,100 @@
+// excomGate.ts — the runner half of the EXCOM gate (server:
+// services/excom/excomRunnerGate.ts, host: assistantHost.py "EXCOM gate").
+//
+// An EXCOM executive's turn runs on this computer only when the server can
+// decide every tool call. The host writes `excom_gate` {gateId, tool, args} on
+// stdout and blocks that call; this relay asks the server
+// (`runner:excom_gate`, answered on the ack) and writes the answer back on the
+// host's stdin (`excom_gate_reply`). After an allowed call the host writes
+// `excom_gate_result` (metadata, plus the text of a vault read), relayed as
+// `runner:excom_gate_result`.
+//
+// Fail closed: a malformed frame, a disconnected socket, an error, no answer
+// within EXCOM_GATE_ACK_MS or a malformed answer all become `deny`. Gate
+// frames are never forwarded as assistant events and argument values are
+// never logged.
+/** Advertised as `excomGate` in runner:hello (server EXCOM_GATE_VERSION). */
+export const EXCOM_GATE_VERSION = 1;
+/** Below the host's own wait (MEL_EXCOM_GATE_TIMEOUT_S, 30 s), so the host gets an explicit deny. */
+export const EXCOM_GATE_ACK_MS = 25_000;
+const CONTENT_MAX = 64_000;
+const str = (v, max) => (typeof v === "string" ? v.slice(0, max) : "");
+/** The reply the host gets: only known fields, any doubt is a deny. */
+export function sanitizeGateReply(gateId, raw) {
+    const r = (raw && typeof raw === "object" ? raw : {});
+    const decision = r.decision;
+    if (r.gateId !== gateId || (decision !== "allow" && decision !== "deny" && decision !== "ask")) {
+        return { kind: "excom_gate_reply", gateId, decision: "deny", message: "The executive gate answered something unreadable, so nothing ran." };
+    }
+    const out = { kind: "excom_gate_reply", gateId, decision };
+    if (typeof r.message === "string")
+        out.message = r.message.slice(0, 4_000);
+    if (typeof r.requestId === "string")
+        out.requestId = r.requestId.slice(0, 120);
+    if (decision === "allow" && typeof r.cached === "string")
+        out.cached = r.cached;
+    if (r.report === "content" || r.report === "meta")
+        out.report = r.report;
+    if (typeof r.isWrite === "boolean")
+        out.isWrite = r.isWrite;
+    return out;
+}
+const denyFrame = (gateId, message) => ({ kind: "excom_gate_reply", gateId, decision: "deny", message });
+/** One `excom_gate` frame from the host: ask the server, answer the host once. */
+export function relayExcomGate(frame, ctx) {
+    const gateId = str(frame?.gateId, 80);
+    const turnId = str(frame?.turnId, 200);
+    const tool = str(frame?.tool, 200);
+    const args = frame?.args && typeof frame.args === "object" && !Array.isArray(frame.args) ? frame.args : {};
+    return new Promise((resolve) => {
+        let done = false;
+        let timer;
+        const answer = (reply) => {
+            if (done)
+                return;
+            done = true;
+            if (timer)
+                clearTimeout(timer);
+            try {
+                ctx.write(JSON.stringify(reply) + "\n");
+            }
+            catch { /* the host is gone: its own wait denies */ }
+            resolve(reply);
+        };
+        if (!gateId || !tool || !turnId) {
+            answer(denyFrame(gateId, "The executive gate refused a malformed call. Nothing ran."));
+            return;
+        }
+        if (ctx.socket.connected === false) {
+            answer(denyFrame(gateId, "The executive gate is not reachable (the runner is offline), so nothing ran."));
+            return;
+        }
+        timer = setTimeout(() => answer(denyFrame(gateId, "The executive gate did not answer in time, so nothing ran.")), ctx.timeoutMs ?? EXCOM_GATE_ACK_MS);
+        try {
+            ctx.socket.emit("runner:excom_gate", { sessionId: ctx.sessionId, turnId, gateId, tool, args }, (reply) => answer(sanitizeGateReply(gateId, reply)));
+        }
+        catch {
+            answer(denyFrame(gateId, "The executive gate failed on this call, so nothing ran."));
+        }
+    });
+}
+/** One `excom_gate_result` frame from the host: metadata to the server (best-effort). */
+export function relayExcomGateResult(frame, ctx) {
+    const gateId = str(frame?.gateId, 80);
+    const turnId = str(frame?.turnId, 200);
+    if (!gateId || !turnId || ctx.socket.connected === false)
+        return false;
+    const payload = {
+        sessionId: ctx.sessionId, turnId, gateId, ok: frame.ok === true,
+        chars: Math.max(0, Math.trunc(Number(frame.chars) || 0)), uncertain: frame.uncertain === true,
+    };
+    if (typeof frame.content === "string")
+        payload.content = frame.content.slice(0, CONTENT_MAX);
+    try {
+        ctx.socket.emit("runner:excom_gate_result", payload);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melaya/runner",
-  "version": "1.1.80",
+  "version": "1.1.81",
   "description": "Run Melaya AI pipelines locally with your own LM Studio or Ollama models",
   "license": "Apache-2.0",
   "author": "Melaya Labs LLC",