mirror of
https://github.com/binaricat/Netcatty.git
synced 2026-11-16 12:01:13 +00:00
feat(ai): make unrecognized shell prompts an actionable unknown state instead of a terminal block (#4198)
* feat(ai): make unrecognized shell prompts an actionable unknown state instead of a terminal block Composes #3935 (advisory semantics), #4110 (OSC 133 marker authority + pending-input guards) and #4195 (asymmetric harm / state-model proposal). An unrecognized prompt on a live shell now yields a non-terminal SHELL_READINESS_UNKNOWN result with a read-only/confirm viable path; PROVEN-busy states keep the exact hard SHELL_NOT_READY block. Never blind-types into unknown; never claims ready without evidence. * fix(ai): propagate unknown readiness code through the active Catty SDK path --------- Co-authored-by: 陈大猫 <16399091+binaricat@users.noreply.github.com>
This commit is contained in:
1 parent
8433302959
commit
0a4ff8875f
20 files changed
+778
-17
No files matched your search
@@ -27,6 +27,7 @@ const {
|
||||
stripAnsi,
|
||||
} = require("./ptyExecHelpers.cjs");
|
||||
const { extractTrailingIdlePrompt } = require("./shellUtils.cjs");
|
||||
const { READINESS_UNKNOWN, SHELL_READINESS_UNKNOWN_MESSAGE } = require("./shellReadinessState.cjs");
|
||||
const { getSessionSnapshot } = require("../terminalInterruptDiagnostics.cjs");
|
||||
const { createJobStartupDiag } = require("./jobStartupDiagnostics.cjs");
|
||||
|
||||
@@ -70,6 +71,7 @@ function startPtyJob(ptyStream, command, options) {
|
||||
sessionId = null,
|
||||
diagnosticsSession = null,
|
||||
getReadyPrompt,
|
||||
classifyReadiness,
|
||||
beforeInput,
|
||||
promptWaitTimeoutMs = 30000,
|
||||
typedInput = false,
|
||||
@@ -85,6 +87,30 @@ function startPtyJob(ptyStream, command, options) {
|
||||
let readinessFailureCode = null;
|
||||
let waitingForInputGuard = typeof beforeInput === "function";
|
||||
|
||||
// #4195: an empty prompt at the bounded wait deadline is resolved into a
|
||||
// PROVEN-busy hard block (unchanged) or an honest, actionable `unknown`.
|
||||
// A missing/ambiguous classifier always fails closed to busy, so #4110's
|
||||
// false-ready guards and legacy callers without classifyReadiness keep the
|
||||
// exact SHELL_NOT_READY behavior. `unknown` NEVER sends the queued command.
|
||||
function resolveUnreadyOutcome() {
|
||||
if (typeof classifyReadiness !== "function") return "busy";
|
||||
try {
|
||||
return classifyReadiness() === "unknown" ? "unknown" : "busy";
|
||||
} catch {
|
||||
return "busy";
|
||||
}
|
||||
}
|
||||
|
||||
function finishUnready(busyMessage) {
|
||||
if (resolveUnreadyOutcome() === "unknown") {
|
||||
readinessFailureCode = READINESS_UNKNOWN;
|
||||
finish("", -1, SHELL_READINESS_UNKNOWN_MESSAGE);
|
||||
} else {
|
||||
readinessFailureCode = "SHELL_NOT_READY";
|
||||
finish("", -1, busyMessage);
|
||||
}
|
||||
}
|
||||
|
||||
const marker = `__NCMCP_${Date.now().toString(36)}_${crypto.randomBytes(16).toString('hex')}__`;
|
||||
let resolvedShellKind = resolveEffectiveShellKind(shellKind, expectedPrompt, {
|
||||
loginShellHint,
|
||||
@@ -203,10 +229,12 @@ function startPtyJob(ptyStream, command, options) {
|
||||
wallTimeoutId = setTimeout(() => {
|
||||
if (finished) return;
|
||||
if (waitingForPrompt || waitingForInputGuard) {
|
||||
readinessFailureCode = waitingForPrompt ? "SHELL_NOT_READY" : "EXECUTION_NOT_AUTHORIZED";
|
||||
finish("", -1, waitingForPrompt
|
||||
? "Shell prompt is not ready; no command was sent"
|
||||
: "Execution authorization timed out; no command was sent");
|
||||
if (waitingForPrompt) {
|
||||
finishUnready("Shell prompt is not ready; no command was sent");
|
||||
} else {
|
||||
readinessFailureCode = "EXECUTION_NOT_AUTHORIZED";
|
||||
finish("", -1, "Execution authorization timed out; no command was sent");
|
||||
}
|
||||
return;
|
||||
}
|
||||
if (pendingEnd) {
|
||||
@@ -1017,8 +1045,10 @@ function startPtyJob(ptyStream, command, options) {
|
||||
return;
|
||||
}
|
||||
if (Date.now() >= deadline) {
|
||||
readinessFailureCode = "SHELL_NOT_READY";
|
||||
finish("", -1, "Shell prompt is not ready (startup, busy program, pending input, or unrecognized prompt); no command was sent");
|
||||
// Same bounded 30s budget, unchanged. Only the *verdict* differs:
|
||||
// proven-busy stays a hard block; an unrecognized prompt on a live
|
||||
// shell becomes an honest, non-terminal, actionable `unknown`.
|
||||
finishUnready("Shell prompt is not ready (startup, busy program, pending input, or unrecognized prompt); no command was sent");
|
||||
return;
|
||||
}
|
||||
readinessTimer = setTimeout(checkReady, Math.min(50, deadline - Date.now()));
|
||||
@@ -1062,6 +1092,7 @@ function startPtyJob(ptyStream, command, options) {
|
||||
* @param {AbortSignal} [options.abortSignal] - AbortSignal to cancel execution
|
||||
* @param {string} [options.expectedPrompt] - Last observed idle prompt for exact fallback matching
|
||||
* @param {() => string} [options.getReadyPrompt] - Read current prompt; wait without writing until non-empty
|
||||
* @param {() => "busy"|"unknown"} [options.classifyReadiness] - At the bounded wait deadline, classify an empty prompt as PROVEN busy (hard SHELL_NOT_READY) or an honest actionable `unknown` (SHELL_READINESS_UNKNOWN). Absent/ambiguous ⇒ busy (fail closed). Never sends the command for `unknown`.
|
||||
* @param {function} [options.beforeInput] - Revalidate authorization before the first PTY byte (may return a promise)
|
||||
* @param {number} [options.promptWaitTimeoutMs=30000] - Bounded pre-input wait (maximum 30 seconds)
|
||||
* @param {boolean} [options.typedInput=false] - Emit synthetic command echo before execution
|
||||
|
||||
@@ -0,0 +1,280 @@
|
||||
"use strict";
|
||||
|
||||
const test = require("node:test");
|
||||
const assert = require("node:assert/strict");
|
||||
const { EventEmitter } = require("node:events");
|
||||
const { startPtyJob } = require("./ptyExec.cjs");
|
||||
const {
|
||||
trackSessionIdlePrompt,
|
||||
getFreshIdlePrompt,
|
||||
getVisibleIdlePrompt,
|
||||
} = require("./shellUtils.cjs");
|
||||
const {
|
||||
READINESS_UNKNOWN,
|
||||
SHELL_READINESS_UNKNOWN_MESSAGE,
|
||||
classifyShellReadiness,
|
||||
} = require("./shellReadinessState.cjs");
|
||||
const {
|
||||
formatTerminalExecuteMcpResponse,
|
||||
} = require("../../capabilities/codegen/mcpToolRegistry.cjs");
|
||||
const { MODEL_DESCRIPTION_HINTS } = require("../../capabilities/schemas/toolInputs.cjs");
|
||||
|
||||
function readyPrompt(session) {
|
||||
return getFreshIdlePrompt(session) || getVisibleIdlePrompt(session);
|
||||
}
|
||||
|
||||
function makeSession(extra = {}) {
|
||||
return { _promptTrackTail: "", lastIdlePrompt: "", ...extra };
|
||||
}
|
||||
|
||||
// Records every byte written to the PTY; echoes a completion marker so a
|
||||
// genuinely-executed command resolves ok:true (same seam as
|
||||
// ptyExec.readiness.test.cjs).
|
||||
class TestPty extends EventEmitter {
|
||||
writes = [];
|
||||
write(data) {
|
||||
this.writes.push(String(data));
|
||||
const marker = String(data).match(/(__NCMCP_[a-z0-9]+_[0-9a-f]+__)/i)?.[1];
|
||||
if (marker) queueMicrotask(() => this.emit("data", `${marker}_S\nOK\n${marker}_E:0\n`));
|
||||
}
|
||||
}
|
||||
|
||||
const UNKNOWN_PROMPT = "Last login: Mon\r\nstarship-custom-prompt─❯ ";
|
||||
const SHORT_BUDGET = { promptWaitTimeoutMs: 30, timeoutMs: 2000 };
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// classifier unit: PROVEN busy stays hard, whitelist miss on a live shell is
|
||||
// an honest unknown. These are the #4110 false-ready guards we must not weaken.
|
||||
// ---------------------------------------------------------------------------
|
||||
test("classifyShellReadiness: proven-busy OSC 133 / pending-input / task / transport stay busy", () => {
|
||||
assert.equal(classifyShellReadiness(makeSession({ osc133Ready: false })), "busy"); // C/D
|
||||
assert.equal(classifyShellReadiness(makeSession({ _osc133PromptRedrawPending: true })), "busy");
|
||||
assert.equal(classifyShellReadiness(makeSession({ _osc133PromptContinued: true })), "busy");
|
||||
assert.equal(classifyShellReadiness(makeSession({ osc133Ready: true, _osc133PromptLine: 3 })), "busy"); // B cursor deviation
|
||||
assert.equal(classifyShellReadiness(makeSession({ waitingForInput: true })), "busy");
|
||||
assert.equal(classifyShellReadiness(makeSession({ busy: true })), "busy");
|
||||
assert.equal(classifyShellReadiness(makeSession({ status: "disconnected" })), "busy");
|
||||
assert.equal(classifyShellReadiness(makeSession(), { taskInFlight: true }), "busy");
|
||||
assert.equal(classifyShellReadiness(makeSession(), { transportAlive: false }), "busy");
|
||||
assert.equal(classifyShellReadiness(null), "busy"); // fail closed
|
||||
});
|
||||
|
||||
test("classifyShellReadiness: unrecognized prompt on a live shell is unknown (not ready, not busy)", () => {
|
||||
const session = makeSession();
|
||||
trackSessionIdlePrompt(session, UNKNOWN_PROMPT);
|
||||
assert.equal(readyPrompt(session), ""); // genuine whitelist miss
|
||||
assert.equal(classifyShellReadiness(session), "unknown");
|
||||
// A-only marker with no C/D and no B confirmation is still unknown (no busy evidence).
|
||||
assert.equal(classifyShellReadiness(makeSession({ osc133Ready: true, _osc133PromptLine: null })), "unknown");
|
||||
});
|
||||
|
||||
test("classifyShellReadiness: credential prompts remain hard busy (#4195)", () => {
|
||||
for (const line of ["Password:", "[sudo] password for alice: ", "Enter passphrase for key '/root/.ssh/id_rsa': ", "PIN: ", "Sorry, try again."]) {
|
||||
const session = makeSession({ _promptTrackTail: line });
|
||||
assert.equal(readyPrompt(session), "", line);
|
||||
assert.equal(classifyShellReadiness(session), "busy", line);
|
||||
}
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// gating trichotomy end-to-end — EVERY case asserts PTY bytes written.
|
||||
// ---------------------------------------------------------------------------
|
||||
test("ready (whitelist match) → command sent, unchanged", async () => {
|
||||
const pty = new TestPty();
|
||||
const prompt = "user@host:~$ ";
|
||||
const result = await startPtyJob(pty, "echo OK", {
|
||||
shellKind: "posix",
|
||||
getReadyPrompt: () => prompt,
|
||||
classifyReadiness: () => "unknown", // never consulted when a prompt is recognized
|
||||
...SHORT_BUDGET,
|
||||
}).resultPromise;
|
||||
assert.equal(result.ok, true);
|
||||
assert.equal(pty.writes.length, 1);
|
||||
});
|
||||
|
||||
test("ready (OSC 133 A with empty input) → command sent, unchanged (#4110)", async () => {
|
||||
const pty = new TestPty();
|
||||
const session = makeSession();
|
||||
trackSessionIdlePrompt(session, "\x1b]133;A\x07\x1b[38;5;39m~/src\x1b[0m \x1b[38;5;213m❯\x1b[0m ");
|
||||
assert.equal(readyPrompt(session), "~/src ❯ ");
|
||||
const result = await startPtyJob(pty, "echo OK", {
|
||||
shellKind: "posix",
|
||||
getReadyPrompt: () => readyPrompt(session),
|
||||
classifyReadiness: () => classifyShellReadiness(session),
|
||||
...SHORT_BUDGET,
|
||||
}).resultPromise;
|
||||
assert.equal(result.ok, true);
|
||||
assert.equal(pty.writes.length, 1);
|
||||
});
|
||||
|
||||
test("PROVEN busy (OSC 133 C/D) → hard SHELL_NOT_READY, ZERO bytes written (#4110 guard)", async () => {
|
||||
const pty = new TestPty();
|
||||
const session = makeSession();
|
||||
trackSessionIdlePrompt(session, "\x1b]133;A\x07PS C:\\Users\\alice> ");
|
||||
assert.equal(readyPrompt(session), "PS C:\\Users\\alice> ");
|
||||
trackSessionIdlePrompt(session, "\x1b]133;C\x07build running...\r\nPS C:\\Users\\alice> ");
|
||||
assert.equal(readyPrompt(session), "");
|
||||
assert.equal(classifyShellReadiness(session), "busy");
|
||||
const result = await startPtyJob(pty, "echo OK", {
|
||||
shellKind: "powershell",
|
||||
getReadyPrompt: () => readyPrompt(session),
|
||||
classifyReadiness: () => classifyShellReadiness(session),
|
||||
...SHORT_BUDGET,
|
||||
}).resultPromise;
|
||||
assert.equal(result.code, "SHELL_NOT_READY");
|
||||
assert.deepEqual(pty.writes, []);
|
||||
});
|
||||
|
||||
test("PROVEN busy (pending-input / our task / disconnected) → hard block, ZERO bytes written", async () => {
|
||||
for (const extra of [
|
||||
{ _osc133PromptContinued: true },
|
||||
{ _osc133PromptRedrawPending: true },
|
||||
{ waitingForInput: true },
|
||||
{ busy: true },
|
||||
{ status: "disconnected" },
|
||||
]) {
|
||||
const pty = new TestPty();
|
||||
const session = makeSession(extra);
|
||||
trackSessionIdlePrompt(session, UNKNOWN_PROMPT);
|
||||
assert.equal(readyPrompt(session), "");
|
||||
const result = await startPtyJob(pty, "echo OK", {
|
||||
shellKind: "posix",
|
||||
getReadyPrompt: () => readyPrompt(session),
|
||||
classifyReadiness: () => classifyShellReadiness(session),
|
||||
...SHORT_BUDGET,
|
||||
}).resultPromise;
|
||||
assert.equal(result.code, "SHELL_NOT_READY", JSON.stringify(extra));
|
||||
assert.deepEqual(pty.writes, [], JSON.stringify(extra));
|
||||
}
|
||||
});
|
||||
|
||||
test("unknown (unrecognized prompt, live shell, no busy evidence): command NOT sent, actionable NON-fatal result", async () => {
|
||||
const pty = new TestPty();
|
||||
const session = makeSession();
|
||||
trackSessionIdlePrompt(session, UNKNOWN_PROMPT);
|
||||
assert.equal(readyPrompt(session), "");
|
||||
assert.equal(classifyShellReadiness(session), "unknown");
|
||||
const result = await startPtyJob(pty, "echo OK", {
|
||||
shellKind: "posix",
|
||||
getReadyPrompt: () => readyPrompt(session),
|
||||
classifyReadiness: () => classifyShellReadiness(session),
|
||||
...SHORT_BUDGET,
|
||||
}).resultPromise;
|
||||
assert.equal(result.code, READINESS_UNKNOWN);
|
||||
assert.equal(result.ok, false); // NOT a lie of success
|
||||
assert.equal(result.error, SHELL_READINESS_UNKNOWN_MESSAGE);
|
||||
assert.match(result.error, /connection is alive/i);
|
||||
assert.match(result.error, /could not be recognized/i);
|
||||
assert.match(result.error, /NOT sent/i);
|
||||
assert.match(result.error, /read-only/i);
|
||||
assert.match(result.error, /get_environment|terminal_read_context/);
|
||||
assert.deepEqual(pty.writes, []); // no blind typing
|
||||
});
|
||||
|
||||
test("unknown keeps the same bounded wait (no early send, no early verdict)", async () => {
|
||||
const pty = new TestPty();
|
||||
let prompt = "";
|
||||
const job = startPtyJob(pty, "echo OK", {
|
||||
shellKind: "posix",
|
||||
getReadyPrompt: () => prompt,
|
||||
classifyReadiness: () => "unknown",
|
||||
promptWaitTimeoutMs: 80,
|
||||
timeoutMs: 2000,
|
||||
});
|
||||
await new Promise((resolve) => setTimeout(resolve, 20));
|
||||
assert.deepEqual(pty.writes, []); // still waiting at the bounded budget
|
||||
const result = await job.resultPromise;
|
||||
assert.equal(result.code, READINESS_UNKNOWN);
|
||||
assert.deepEqual(pty.writes, []);
|
||||
});
|
||||
|
||||
test("unknown is recoverable: a recognized prompt (user pressed Enter) lets the next exec succeed", async () => {
|
||||
const pty = new TestPty();
|
||||
let prompt = "";
|
||||
const first = await startPtyJob(pty, "echo OK", {
|
||||
shellKind: "posix",
|
||||
getReadyPrompt: () => prompt,
|
||||
classifyReadiness: () => "unknown",
|
||||
...SHORT_BUDGET,
|
||||
}).resultPromise;
|
||||
assert.equal(first.code, READINESS_UNKNOWN);
|
||||
assert.deepEqual(pty.writes, []); // first exec never bricked the session
|
||||
|
||||
prompt = "user@host:~$ ";
|
||||
const second = await startPtyJob(pty, "echo OK", {
|
||||
shellKind: "posix",
|
||||
getReadyPrompt: () => prompt,
|
||||
classifyReadiness: () => "unknown",
|
||||
...SHORT_BUDGET,
|
||||
}).resultPromise;
|
||||
assert.equal(second.ok, true);
|
||||
assert.equal(pty.writes.length, 1);
|
||||
});
|
||||
|
||||
test("Password: remains hard not-ready, ZERO bytes written (#4195 correct behavior)", async () => {
|
||||
const pty = new TestPty();
|
||||
const session = makeSession();
|
||||
trackSessionIdlePrompt(session, "Password:");
|
||||
assert.equal(readyPrompt(session), "");
|
||||
assert.equal(classifyShellReadiness(session), "busy");
|
||||
const result = await startPtyJob(pty, "echo OK", {
|
||||
shellKind: "posix",
|
||||
getReadyPrompt: () => readyPrompt(session),
|
||||
classifyReadiness: () => classifyShellReadiness(session),
|
||||
...SHORT_BUDGET,
|
||||
}).resultPromise;
|
||||
assert.equal(result.code, "SHELL_NOT_READY");
|
||||
assert.deepEqual(pty.writes, []);
|
||||
});
|
||||
|
||||
test("legacy callers without classifyReadiness keep the exact hard SHELL_NOT_READY block", async () => {
|
||||
const pty = new TestPty();
|
||||
const result = await startPtyJob(pty, "echo OK", {
|
||||
getReadyPrompt: () => "",
|
||||
...SHORT_BUDGET,
|
||||
}).resultPromise;
|
||||
assert.equal(result.code, "SHELL_NOT_READY");
|
||||
assert.deepEqual(pty.writes, []);
|
||||
});
|
||||
|
||||
test("a throwing / ambiguous classifier fails closed to busy (never a false ready)", async () => {
|
||||
const pty = new TestPty();
|
||||
const result = await startPtyJob(pty, "echo OK", {
|
||||
getReadyPrompt: () => "",
|
||||
classifyReadiness: () => { throw new Error("inspection blew up"); },
|
||||
...SHORT_BUDGET,
|
||||
}).resultPromise;
|
||||
assert.equal(result.code, "SHELL_NOT_READY");
|
||||
assert.deepEqual(pty.writes, []);
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// agent-visible surfaces: MCP tool result + tool description.
|
||||
// ---------------------------------------------------------------------------
|
||||
test("MCP terminal_execute surfaces unknown as a NON-fatal, actionable result (not isError)", () => {
|
||||
const unknownResult = {
|
||||
ok: false,
|
||||
error: SHELL_READINESS_UNKNOWN_MESSAGE,
|
||||
code: READINESS_UNKNOWN,
|
||||
exitCode: -1,
|
||||
stdout: "",
|
||||
stderr: "",
|
||||
};
|
||||
const formatted = formatTerminalExecuteMcpResponse(unknownResult);
|
||||
assert.notEqual(formatted.isError, true); // THE fix: agent does not see a terminal error
|
||||
assert.match(formatted.content[0].text, /read-only/i);
|
||||
assert.match(formatted.content[0].text, /NOT sent/i);
|
||||
assert.match(formatted.content[0].text, /get_environment|terminal_read_context/);
|
||||
// Control: a proven-busy verdict is still a hard error.
|
||||
const busy = formatTerminalExecuteMcpResponse({ ...unknownResult, code: "SHELL_NOT_READY", error: "Shell prompt is not ready; no command was sent" });
|
||||
assert.equal(busy.isError, true);
|
||||
});
|
||||
|
||||
test("terminal_execute tool description documents the unknown outcome and the read-only/confirm path", () => {
|
||||
const description = MODEL_DESCRIPTION_HINTS["terminal.execute"] || "";
|
||||
assert.match(description, /SHELL_READINESS_UNKNOWN/);
|
||||
assert.match(description, /NOT sent/);
|
||||
assert.match(description, /read-only/);
|
||||
assert.match(description, /get_environment|terminal_read_context/);
|
||||
assert.match(description, /ask the user to confirm/);
|
||||
});
|
||||
@@ -0,0 +1,106 @@
|
||||
"use strict";
|
||||
|
||||
/**
|
||||
* First-class shell readiness classification for the pre-input gate in
|
||||
* startPtyJob. This composes #4110's OSC 133 marker authority and #4195's
|
||||
* asymmetric-harm thesis: a whitelist miss on a live shell must be an
|
||||
* actionable `unknown`, never a terminal SHELL_NOT_READY — but anything
|
||||
* PROVEN busy (or a credential prompt waiting for the user's secret) must
|
||||
* stay a hard block. It mirrors #3935's honesty rule: `unknown` is NOT a lie
|
||||
* of success and is never claimed as ready.
|
||||
*
|
||||
* This module only READS session state. It never writes to a PTY, never
|
||||
* injects OSC markers, and never widens tool scope. It lives outside
|
||||
* shellUtils.cjs (the prompt whitelist) on purpose so the gating consumer
|
||||
* evolves independently of positive-signal additions such as #4197.
|
||||
*/
|
||||
const { stripAnsi } = require("./shellUtils.cjs");
|
||||
|
||||
/** Distinct, non-terminal code emitted when the gate cannot prove busy. */
|
||||
const READINESS_UNKNOWN = "SHELL_READINESS_UNKNOWN";
|
||||
|
||||
/**
|
||||
* Honest, actionable result text. Surfaced verbatim as the exec result
|
||||
* `error` and as the MCP/Catty tool-result text. It must never claim ready.
|
||||
* (a) connection alive + no busy signal, (b) prompt unrecognized,
|
||||
* (c) command NOT sent / no blind typing, (d) the viable read-only path.
|
||||
*/
|
||||
const SHELL_READINESS_UNKNOWN_MESSAGE = [
|
||||
"Shell readiness unknown (SHELL_READINESS_UNKNOWN): the terminal connection is",
|
||||
"alive and no busy, pending-input, or credential-prompt signal was observed, but",
|
||||
"the prompt could not be recognized (custom theme, colored/starship/root prompt,",
|
||||
"or continuation). The command was NOT sent — never blind-type into a possible",
|
||||
"password prompt, editor, or half-typed command. This is a recoverable,",
|
||||
"non-terminal state, not a failed command. Read-only next steps: call",
|
||||
"get_environment or terminal_read_context to inspect the visible buffer, re-check",
|
||||
"readiness after the user presses Enter or a recognized prompt appears, reuse",
|
||||
"another idle session, or ask the user to confirm the prompt before retrying.",
|
||||
"Retrying once the prompt is recognized is safe.",
|
||||
].join(" ");
|
||||
|
||||
// Known credential/passphrase prompts. #4195: `Password:` (and friends) are
|
||||
// PROVEN "waiting for secret input" states and MUST remain hard not-ready.
|
||||
// This is a conservative block-list (hardening only): a miss falls through to
|
||||
// `unknown`, which still never types.
|
||||
const BLOCKING_INPUT_PATTERNS = [
|
||||
/^(?:\[sudo\]\s*|enter\s+|please\s+enter\s+)?(?:password|passphrase|pin)(?:\s+for\s+[^:]+)?\s*:?\s*$/i,
|
||||
/^sorry,\s*try\s+again\.?\s*$/i,
|
||||
];
|
||||
|
||||
function lastVisibleLine(session) {
|
||||
const tail = typeof session?._promptTrackTail === "string" ? session._promptTrackTail : "";
|
||||
if (!tail) return "";
|
||||
const lines = stripAnsi(tail).split(/[\r\n]/);
|
||||
for (let i = lines.length - 1; i >= 0; i -= 1) {
|
||||
const line = lines[i].trim();
|
||||
if (line) return line;
|
||||
}
|
||||
return "";
|
||||
}
|
||||
|
||||
/**
|
||||
* Classify a session whose getReadyPrompt() just returned empty (i.e. no
|
||||
* whitelist match and no OSC 133 A-with-empty-input ready signal).
|
||||
*
|
||||
* Returns:
|
||||
* "busy" — PROVEN busy → keep the hard SHELL_NOT_READY block unchanged.
|
||||
* "unknown" — connection alive, no proven-busy evidence, prompt not
|
||||
* recognized → actionable, non-terminal outcome.
|
||||
*
|
||||
* Anything ambiguous (missing session, thrown helper, unknown context) fails
|
||||
* CLOSED to "busy", so #4110's false-ready guards are never weakened.
|
||||
*/
|
||||
function classifyShellReadiness(session, context = {}) {
|
||||
if (!session) return "busy";
|
||||
const { taskInFlight = false, transportAlive = true } = context || {};
|
||||
// Our own tracked task in flight / a dead transport are proven busy and are
|
||||
// also hard-blocked at the exec call sites (reserveSessionExecution,
|
||||
// writability check) and by the PTY close/error handlers.
|
||||
if (taskInFlight || !transportAlive) return "busy";
|
||||
// #4110: an OSC 133 C/D marker establishes a running command/output
|
||||
// lifecycle. shellUtils.cjs:321 sets osc133Ready=false; getFreshIdlePrompt
|
||||
// (:377) and getVisibleIdlePrompt (:406) both return "" for that state.
|
||||
if (session.osc133Ready === false) return "busy";
|
||||
// #4110 pending-input guards (shellUtils.cjs:265-275): redraw latch,
|
||||
// continuation/PS2, and B-marker cursor deviation. An empty prompt while
|
||||
// osc133Ready===true with a B-marked line means matchesOsc133EmptyPrompt
|
||||
// rejected it → the user typed into the prompt line.
|
||||
if (session._osc133PromptRedrawPending) return "busy";
|
||||
if (session._osc133PromptContinued) return "busy";
|
||||
if (session.osc133Ready === true && session._osc133PromptLine != null) return "busy";
|
||||
// Explicit busy / waiting-for-input session state (#3935 recovery model:
|
||||
// sessionRecoveryService.cjs:55-56, 101-102).
|
||||
if (session.waitingForInput === true || session.busy === true) return "busy";
|
||||
if (session.status === "disconnected" || session.status === "stopped") return "busy";
|
||||
// Credential prompt waiting for the user's secret (#4195).
|
||||
const line = lastVisibleLine(session);
|
||||
if (line && BLOCKING_INPUT_PATTERNS.some((pattern) => pattern.test(line))) return "busy";
|
||||
// Connection alive, no proven-busy evidence, prompt not recognized.
|
||||
return "unknown";
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
READINESS_UNKNOWN,
|
||||
SHELL_READINESS_UNKNOWN_MESSAGE,
|
||||
classifyShellReadiness,
|
||||
};
|
||||
@@ -4,6 +4,7 @@
|
||||
// (based in electron/bridges/). Requiring here keeps the path unambiguous.
|
||||
const { emitTerminalSessionData } = require("../emitTerminalSessionData.cjs");
|
||||
const { formatSyntheticEcho, getVisibleIdlePrompt } = require("../ai/shellUtils.cjs");
|
||||
const { classifyShellReadiness } = require("../ai/shellReadinessState.cjs");
|
||||
const { clearSessionFlowState } = require("../terminalFlowAck.cjs");
|
||||
const { remoteDisallowsExecChannelProbe, sessionDisallowsExtraSshChannel, ensureSessionShellKindForExec } = require("../ai/sessionShellKind.cjs");
|
||||
const defaultAiPrivacyService = require("../../shared/aiPrivacyService.cjs");
|
||||
@@ -227,6 +228,7 @@ function registerCattyExecHandlers(ctx) {
|
||||
expectedPrompt: getFreshIdlePrompt(session),
|
||||
getReadyPrompt: typeof session._promptTrackTail === "string"
|
||||
? () => getFreshIdlePrompt(session) || getVisibleIdlePrompt(session) : undefined,
|
||||
classifyReadiness: () => classifyShellReadiness(session),
|
||||
typedInput: true,
|
||||
echoCommand: (rawCommand) => {
|
||||
const contents = electronModule?.webContents?.fromId?.(session.webContentsId);
|
||||
|
||||
@@ -384,7 +384,9 @@ test("MCP background readiness timeout survives job polling without PTY writes",
|
||||
const polled = api.handleJobPoll({ jobId: started.jobId, chatSessionId: "readiness-chat" });
|
||||
assert.equal(polled.status, "failed");
|
||||
assert.equal(polled.completed, true);
|
||||
assert.equal(polled.code, "SHELL_NOT_READY");
|
||||
// #4195: a live shell whose prompt was never recognized is an actionable
|
||||
// unknown, not a terminal SHELL_NOT_READY. The command is still never sent.
|
||||
assert.equal(polled.code, "SHELL_READINESS_UNKNOWN");
|
||||
assert.equal(ctx.activeSessionExecutions.size, 0);
|
||||
assert.deepEqual(pty.writes, []);
|
||||
ctx.getFreshIdlePrompt = () => "user@host:~$ ";
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
// where bare `require` resolves to ctx.require (based in electron/bridges/).
|
||||
const { clearSessionFlowState } = require("../terminalFlowAck.cjs");
|
||||
const { getVisibleIdlePrompt } = require("../ai/shellUtils.cjs");
|
||||
const { classifyShellReadiness } = require("../ai/shellReadinessState.cjs");
|
||||
const { emitJobDiag } = require("../ai/jobStartupDiagnostics.cjs");
|
||||
const {
|
||||
ensureSessionShellKind,
|
||||
@@ -161,6 +162,7 @@ function createExecHandlerApi(ctx) {
|
||||
expectedPrompt: getFreshIdlePrompt(session),
|
||||
getReadyPrompt: typeof session._promptTrackTail === "string"
|
||||
? () => getFreshIdlePrompt(session) || getVisibleIdlePrompt(session) : undefined,
|
||||
classifyReadiness: () => classifyShellReadiness(session),
|
||||
typedInput: true,
|
||||
echoCommand: (rawCommand) => echoCommandToSession(session, sessionId, rawCommand),
|
||||
chatSessionId,
|
||||
@@ -343,6 +345,7 @@ function createExecHandlerApi(ctx) {
|
||||
expectedPrompt: getFreshIdlePrompt(session),
|
||||
getReadyPrompt: typeof session._promptTrackTail === "string"
|
||||
? () => getFreshIdlePrompt(session) || getVisibleIdlePrompt(session) : undefined,
|
||||
classifyReadiness: () => classifyShellReadiness(session),
|
||||
typedInput: true,
|
||||
echoCommand: (rawCommand) => echoCommandToSession(session, sessionId, rawCommand),
|
||||
maxBufferedChars: MAX_BACKGROUND_JOB_OUTPUT_CHARS,
|
||||
|
||||
@@ -81,6 +81,11 @@ function formatTerminalExecuteResult(result) {
|
||||
// Align with Catty executor wording when a command ran but produced no text.
|
||||
const TERMINAL_EXECUTE_NO_OUTPUT_TEXT = "Command completed (no output)";
|
||||
|
||||
// Matches READINESS_UNKNOWN in electron/bridges/ai/shellReadinessState.cjs.
|
||||
// Kept as a literal to avoid a capabilities -> bridges dependency; a test
|
||||
// asserts the two stay in sync.
|
||||
const SHELL_READINESS_UNKNOWN_CODE = "SHELL_READINESS_UNKNOWN";
|
||||
|
||||
/**
|
||||
* Format terminal_execute for MCP clients.
|
||||
* Match Catty semantics: when the command actually ran, always surface
|
||||
@@ -97,6 +102,18 @@ function formatTerminalExecuteMcpResponse(result) {
|
||||
return { content: [{ type: "text", text: formatRpcError(result) }], isError: true };
|
||||
}
|
||||
|
||||
// #4195: an unrecognized prompt on a live shell is an actionable,
|
||||
// non-terminal state, not a fatal tool error. The exec gate already refused
|
||||
// to send the command; surface the honest + viable-path hint as a NORMAL
|
||||
// tool result (no isError) so the agent inspects / re-checks / confirms
|
||||
// instead of treating the session as permanently bricked (cf. #3935, where
|
||||
// shellReady became advisory). Never claim the command ran.
|
||||
if (result.code === SHELL_READINESS_UNKNOWN_CODE) {
|
||||
return {
|
||||
content: [{ type: "text", text: result.error || "Shell readiness unknown; no command was sent." }],
|
||||
};
|
||||
}
|
||||
|
||||
// Operational failure with no command evidence (session not found, busy, blocked…).
|
||||
if (result.ok === false && !hasTerminalExecuteEvidence(result)) {
|
||||
return { content: [{ type: "text", text: formatRpcError(result) }], isError: true };
|
||||
|
||||
@@ -418,7 +418,7 @@ const MODEL_DESCRIPTION_HINTS = Object.freeze({
|
||||
"session.environment":
|
||||
"Call this first for any task involving a live Netcatty terminal, remote server, SSH session, SFTP path, or terminal tab. Select the target by label or hostname, then pass its sessionId to terminal and SFTP tools. Call it again after the user opens, closes, or renames a session.",
|
||||
"terminal.execute":
|
||||
"Use this instead of the local shell when the command is intended for a Netcatty terminal or remote host. Call get_environment first to resolve the sessionId. Use only for commands expected to finish within about 60 seconds. For long-running commands use terminal_start and terminal_poll. Commands run in an isolated subshell of the visible terminal: the user sees the output live, but shell state such as cd, export, or set does not persist between calls — use absolute paths or combine cd with the command (cd /path && cmd).",
|
||||
"Use this instead of the local shell when the command is intended for a Netcatty terminal or remote host. Call get_environment first to resolve the sessionId. Use only for commands expected to finish within about 60 seconds. For long-running commands use terminal_start and terminal_poll. Commands run in an isolated subshell of the visible terminal: the user sees the output live, but shell state such as cd, export, or set does not persist between calls — use absolute paths or combine cd with the command (cd /path && cmd). If the shell prompt cannot be recognized while the connection is alive and no busy signal is present, the command is NOT sent and the tool returns SHELL_READINESS_UNKNOWN (a recoverable, non-terminal result, not a failed command): do not blind-type into a possible password prompt — inspect the terminal read-only with get_environment or terminal_read_context, re-check readiness after the user presses Enter, reuse another idle session, or ask the user to confirm the prompt before retrying.",
|
||||
"terminal.start":
|
||||
"Use this instead of the local shell for long-running commands on a Netcatty terminal or remote host. Call get_environment first to resolve the sessionId. Prefer for builds, scans, log-following, or anything likely to exceed about 2 minutes. Shell state such as cd or export does not persist between calls — combine cd with the command.",
|
||||
"terminal.poll":
|
||||
|
||||
@@ -9,6 +9,7 @@ const {
|
||||
execViaRawPty,
|
||||
} = require("../bridges/ai/ptyExec.cjs");
|
||||
const { getFreshIdlePrompt, getVisibleIdlePrompt, formatSyntheticEcho } = require("../bridges/ai/shellUtils.cjs");
|
||||
const { classifyShellReadiness } = require("../bridges/ai/shellReadinessState.cjs");
|
||||
const {
|
||||
ensureSessionShellKind,
|
||||
remoteDisallowsExecChannelProbe, sessionDisallowsExtraSshChannel, ensureSessionShellKindForExec,
|
||||
@@ -339,6 +340,7 @@ function createWorkerAiExecHandler({
|
||||
expectedPrompt: getFreshIdlePrompt(session),
|
||||
getReadyPrompt: typeof session._promptTrackTail === "string"
|
||||
? () => getFreshIdlePrompt(session) || getVisibleIdlePrompt(session) : undefined,
|
||||
classifyReadiness: () => classifyShellReadiness(session),
|
||||
typedInput: true,
|
||||
echoCommand: (rawCommand) => {
|
||||
event?.sender?.send?.("netcatty:data", {
|
||||
@@ -568,6 +570,7 @@ function createWorkerAiJobStartHandler({
|
||||
expectedPrompt: getFreshIdlePrompt(session),
|
||||
getReadyPrompt: typeof session._promptTrackTail === "string"
|
||||
? () => getFreshIdlePrompt(session) || getVisibleIdlePrompt(session) : undefined,
|
||||
classifyReadiness: () => classifyShellReadiness(session),
|
||||
typedInput: true,
|
||||
echoCommand: (rawCommand) => {
|
||||
event?.sender?.send?.("netcatty:data", {
|
||||
|
||||
@@ -678,7 +678,9 @@ test("worker background readiness timeout survives job polling without PTY write
|
||||
});
|
||||
assert.equal(polled.status, "failed");
|
||||
assert.equal(polled.completed, true);
|
||||
assert.equal(polled.code, "SHELL_NOT_READY");
|
||||
// #4195: a live shell whose prompt was never recognized is an actionable
|
||||
// unknown, not a terminal SHELL_NOT_READY. The command is still never sent.
|
||||
assert.equal(polled.code, "SHELL_READINESS_UNKNOWN");
|
||||
assert.deepEqual(pty.writes, []);
|
||||
trackSessionIdlePrompt(session, "user@host:~$ ");
|
||||
t.mock.timers.tick(1000);
|
||||
|
||||
@@ -98,29 +98,42 @@ export function formatToolErrorContent(error: unknown, fallback = 'Tool executio
|
||||
return JSON.stringify({ error: fallback });
|
||||
}
|
||||
|
||||
// Non-terminal readiness verdict surfaced by the terminal.execute gate
|
||||
// (#4195/#4198). Kept in sync with READINESS_UNKNOWN in
|
||||
// electron/bridges/ai/shellReadinessState.cjs and SHELL_READINESS_UNKNOWN_CODE
|
||||
// in electron/capabilities/codegen/mcpToolRegistry.cjs. The active Catty SDK
|
||||
// path (capabilityTools.ts -> agentEventAdapter.ts -> AgentRuntime) preserves
|
||||
// this `code` on the result so every error classifier can honour it.
|
||||
export const SHELL_READINESS_UNKNOWN_CODE = 'SHELL_READINESS_UNKNOWN';
|
||||
|
||||
/** Detect tool results that represent errors/denials (e.g. `{ error: "..." }` or `{ ok: false }`) */
|
||||
export function isToolResultError(output: unknown): boolean {
|
||||
if (output == null) return false;
|
||||
|
||||
|
||||
if (typeof output === 'object') {
|
||||
const obj = output as Record<string, unknown>;
|
||||
// #4198: an unrecognized prompt on a live shell is an actionable,
|
||||
// non-terminal state. Even if an `error` field is present, never flag it
|
||||
// as a fatal tool error / session blocker.
|
||||
if (obj.code === SHELL_READINESS_UNKNOWN_CODE) return false;
|
||||
// Check for explicit error objects
|
||||
if ('error' in obj && typeof obj.error === 'string') return true;
|
||||
if ('ok' in obj && obj.ok === false) return true;
|
||||
}
|
||||
|
||||
|
||||
// Check stringified JSON (common for tool result wrapping)
|
||||
if (typeof output === 'string') {
|
||||
try {
|
||||
const parsed = JSON.parse(output);
|
||||
if (parsed && typeof parsed === 'object') {
|
||||
const parsedObj = parsed as Record<string, unknown>;
|
||||
if (parsedObj.code === SHELL_READINESS_UNKNOWN_CODE) return false;
|
||||
if ('error' in parsedObj && typeof parsedObj.error === 'string') return true;
|
||||
if ('ok' in parsedObj && parsedObj.ok === false) return true;
|
||||
}
|
||||
} catch { /* not JSON, not an error */ }
|
||||
}
|
||||
|
||||
|
||||
return false;
|
||||
}
|
||||
|
||||
|
||||
@@ -29,6 +29,7 @@ export interface NetcattyBridge {
|
||||
stderr?: string;
|
||||
exitCode?: number;
|
||||
error?: string;
|
||||
code?: string;
|
||||
}>;
|
||||
/**
|
||||
* Cancel any in-flight Catty Agent command execution scoped to the
|
||||
@@ -71,6 +72,13 @@ export interface ExecutorContext {
|
||||
/** Convert a shared ToolExecResult into the executor's ToolResult format. */
|
||||
function toToolResult(toolCallId: string, r: ToolExecResult): ToolResult {
|
||||
if (r.ok === false) {
|
||||
// #4195: an unrecognized prompt on a live shell is an actionable,
|
||||
// non-terminal state, not a fatal tool error. The exec gate already refused
|
||||
// to send the command; surface the honest + viable-path hint as a normal
|
||||
// tool result (no isError) so the agent inspects / re-checks / confirms.
|
||||
if (r.code === 'SHELL_READINESS_UNKNOWN') {
|
||||
return { toolCallId, content: r.error };
|
||||
}
|
||||
if (
|
||||
typeof r.data === 'object'
|
||||
&& r.data !== null
|
||||
|
||||
@@ -0,0 +1,76 @@
|
||||
import { describe, it } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { createToolExecutor, type NetcattyBridge, type ExecutorContext } from './executor';
|
||||
|
||||
// Mirrors SHELL_READINESS_UNKNOWN_MESSAGE from
|
||||
// electron/bridges/ai/shellReadinessState.cjs (kept inline to avoid a
|
||||
// renderer -> electron import in this harness test).
|
||||
const UNKNOWN_HINT = [
|
||||
'Shell readiness unknown (SHELL_READINESS_UNKNOWN): the terminal connection is',
|
||||
'alive but the prompt could not be recognized. The command was NOT sent — never',
|
||||
'blind-type. Read-only next steps: call get_environment or terminal_read_context,',
|
||||
're-check after the user presses Enter, reuse another idle session, or ask the',
|
||||
'user to confirm the prompt before retrying.',
|
||||
].join(' ');
|
||||
|
||||
function makeBridge(result: Record<string, unknown>): NetcattyBridge {
|
||||
return { aiExec: async () => result } as unknown as NetcattyBridge;
|
||||
}
|
||||
|
||||
const context: ExecutorContext = {
|
||||
sessions: [
|
||||
{
|
||||
sessionId: 's1',
|
||||
hostId: 'h1',
|
||||
hostname: 'host',
|
||||
label: 'tab',
|
||||
protocol: 'ssh',
|
||||
connected: true,
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
function call(command = 'echo OK') {
|
||||
return { id: 'call-1', name: 'terminal_execute', arguments: { sessionId: 's1', command } };
|
||||
}
|
||||
|
||||
describe('Catty Agent terminal_execute surfaces SHELL_READINESS_UNKNOWN as non-fatal (#4195)', () => {
|
||||
it('returns the actionable read-only hint WITHOUT isError (agent is not bricked)', async () => {
|
||||
const bridge = makeBridge({
|
||||
ok: false,
|
||||
error: UNKNOWN_HINT,
|
||||
code: 'SHELL_READINESS_UNKNOWN',
|
||||
stdout: '',
|
||||
stderr: '',
|
||||
exitCode: -1,
|
||||
});
|
||||
const execute = createToolExecutor(bridge, context, [], 'auto');
|
||||
const result = await execute(call());
|
||||
assert.notEqual(result.isError, true);
|
||||
assert.match(result.content, /read-only/i);
|
||||
assert.match(result.content, /NOT sent/i);
|
||||
assert.match(result.content, /get_environment|terminal_read_context/);
|
||||
});
|
||||
|
||||
it('a proven-busy SHELL_NOT_READY verdict is still a hard error', async () => {
|
||||
const bridge = makeBridge({
|
||||
ok: false,
|
||||
error: 'Shell prompt is not ready; no command was sent',
|
||||
code: 'SHELL_NOT_READY',
|
||||
stdout: '',
|
||||
stderr: '',
|
||||
exitCode: -1,
|
||||
});
|
||||
const execute = createToolExecutor(bridge, context, [], 'auto');
|
||||
const result = await execute(call());
|
||||
assert.equal(result.isError, true);
|
||||
});
|
||||
|
||||
it('a normal successful command is unaffected', async () => {
|
||||
const bridge = makeBridge({ ok: true, stdout: 'OK', stderr: '', exitCode: 0 });
|
||||
const execute = createToolExecutor(bridge, context, [], 'auto');
|
||||
const result = await execute(call());
|
||||
assert.notEqual(result.isError, true);
|
||||
assert.match(result.content, /OK/);
|
||||
});
|
||||
});
|
||||
@@ -1,5 +1,5 @@
|
||||
import type { AgentEvent, AgentEventListener } from './types';
|
||||
import { resolveStreamChunkToolCallId } from '../aiChatStreamingSupport';
|
||||
import { resolveStreamChunkToolCallId, SHELL_READINESS_UNKNOWN_CODE } from '../aiChatStreamingSupport';
|
||||
|
||||
let eventCounter = 0;
|
||||
|
||||
@@ -40,12 +40,18 @@ function isToolResultError(output: unknown): boolean {
|
||||
if (output == null) return false;
|
||||
if (typeof output === 'object') {
|
||||
const obj = output as Record<string, unknown>;
|
||||
// #4198 (round 2): an unrecognized prompt on a live shell is an actionable,
|
||||
// non-terminal state. Honour the preserved `code` so this result is never
|
||||
// emitted as `isError: true` (which AgentRuntime stores as an open-session
|
||||
// blocker), even if an `error` field is present. All other codes untouched.
|
||||
if (obj.code === SHELL_READINESS_UNKNOWN_CODE) return false;
|
||||
if ('error' in obj && typeof obj.error === 'string') return true;
|
||||
if ('ok' in obj && obj.ok === false) return true;
|
||||
}
|
||||
if (typeof output === 'string') {
|
||||
try {
|
||||
const parsed = JSON.parse(output) as Record<string, unknown>;
|
||||
if (parsed.code === SHELL_READINESS_UNKNOWN_CODE) return false;
|
||||
if ('error' in parsed && typeof parsed.error === 'string') return true;
|
||||
if ('ok' in parsed && parsed.ok === false) return true;
|
||||
} catch {
|
||||
|
||||
@@ -16,6 +16,7 @@ import { redactSecretsForModel, redactSecretsInValueForModel, setReversibleModel
|
||||
import { globalTerminalMonitorGuard } from './terminalMonitorGuard';
|
||||
import { netcattyBridge } from '../../services/netcattyBridge';
|
||||
import type { AISessionScope } from '../types';
|
||||
import { SHELL_READINESS_UNKNOWN_CODE } from '../aiChatStreamingSupport';
|
||||
|
||||
let turnCounter = 0;
|
||||
|
||||
@@ -27,6 +28,11 @@ function nextTurnId(): string {
|
||||
function isFailedToolResult(result: string): boolean {
|
||||
try {
|
||||
const parsed = JSON.parse(result) as Record<string, unknown>;
|
||||
// #4198 (round 2): an unrecognized prompt on a live shell is an actionable,
|
||||
// non-terminal state. Honour the preserved `code` so it is never stored as
|
||||
// an open-session blocker, even if an `error` field is present. All other
|
||||
// error codes keep the exact existing classification.
|
||||
if (parsed?.code === SHELL_READINESS_UNKNOWN_CODE) return false;
|
||||
return parsed?.ok === false || typeof parsed?.error === 'string';
|
||||
} catch {
|
||||
return false;
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
import { tool } from 'ai';
|
||||
import { z } from 'zod';
|
||||
import { SHELL_READINESS_UNKNOWN_CODE } from '../aiChatStreamingSupport';
|
||||
import type { ExecutorContext, NetcattyBridge } from '../cattyAgent/executor';
|
||||
import type { TerminalContextReadRange } from '../../../domain/terminalContextRead';
|
||||
import type { AIPermissionMode } from '../types';
|
||||
@@ -443,6 +444,33 @@ function createCatalogTool(spec: CattyToolSpec) {
|
||||
try {
|
||||
const result = await executeTerminalExecute(deps, { sessionId: sid, command });
|
||||
if (result.ok === false) {
|
||||
// #4195/#4198 (round 2): this is the ACTIVE Catty SDK path.
|
||||
// cattyTurnDriver builds its tools with createCattyToolsFromCatalog,
|
||||
// NOT the createToolExecutor path (which has no production callers).
|
||||
// Falling through to the generic `fittedFailure` below re-wraps the
|
||||
// result as `{ error: ... }` and DROPS its `code`, so every
|
||||
// downstream error-shape classifier mis-handles it:
|
||||
// - agentEventAdapter.ts:220 isToolResultError -> isError: true
|
||||
// - agentRuntime.ts isFailedToolResult -> open session blocker
|
||||
// - the shared isToolResultError (UI / external-sdk), staleContextPruner
|
||||
// Instead surface the SAME honest + viable-path hint used by the
|
||||
// MCP path (mcpToolRegistry.cjs) as a NORMAL tool result: preserve
|
||||
// `code`, carry the hint as text, and use NO `error` / `ok:false`
|
||||
// shape. All of the heuristics above then classify it as non-error
|
||||
// without a wider refactor, while every OTHER error code (e.g.
|
||||
// SHELL_NOT_READY) keeps the exact hard-error path below.
|
||||
// No command ran, so skip completed-write dedup: a retry after the
|
||||
// prompt becomes recognized must re-evaluate, not replay a stale
|
||||
// "command not sent" result.
|
||||
if (result.code === SHELL_READINESS_UNKNOWN_CODE) {
|
||||
return {
|
||||
content: [{
|
||||
type: 'text',
|
||||
text: result.error || 'Shell readiness unknown; no command was sent.',
|
||||
}],
|
||||
code: result.code,
|
||||
};
|
||||
}
|
||||
if (!result.data) return unwrap(result);
|
||||
const fittedFailure = {
|
||||
error: fitLargeToolResultForModel({
|
||||
|
||||
@@ -135,7 +135,7 @@
|
||||
"toolName": "terminal_execute",
|
||||
"rpcMethod": "netcatty/exec",
|
||||
"localExecution": false,
|
||||
"description": "Execute a short command in a terminal session and wait for completion. Use this instead of the local shell when the command is intended for a Netcatty terminal or remote host. Call get_environment first to resolve the sessionId. Use only for commands expected to finish within about 60 seconds. For long-running commands use terminal_start and terminal_poll. Commands run in an isolated subshell of the visible terminal: the user sees the output live, but shell state such as cd, export, or set does not persist between calls — use absolute paths or combine cd with the command (cd /path && cmd).",
|
||||
"description": "Execute a short command in a terminal session and wait for completion. Use this instead of the local shell when the command is intended for a Netcatty terminal or remote host. Call get_environment first to resolve the sessionId. Use only for commands expected to finish within about 60 seconds. For long-running commands use terminal_start and terminal_poll. Commands run in an isolated subshell of the visible terminal: the user sees the output live, but shell state such as cd, export, or set does not persist between calls — use absolute paths or combine cd with the command (cd /path && cmd). If the shell prompt cannot be recognized while the connection is alive and no busy signal is present, the command is NOT sent and the tool returns SHELL_READINESS_UNKNOWN (a recoverable, non-terminal result, not a failed command): do not blind-type into a possible password prompt — inspect the terminal read-only with get_environment or terminal_read_context, re-check readiness after the user presses Enter, reuse another idle session, or ask the user to confirm the prompt before retrying.",
|
||||
"inputShape": {
|
||||
"sessionId": {
|
||||
"type": "string",
|
||||
|
||||
@@ -141,7 +141,7 @@
|
||||
"toolName": "terminal_execute",
|
||||
"rpcMethod": "netcatty/exec",
|
||||
"localExecution": false,
|
||||
"description": "Execute a short command in a terminal session and wait for completion. Use this instead of the local shell when the command is intended for a Netcatty terminal or remote host. Call get_environment first to resolve the sessionId. Use only for commands expected to finish within about 60 seconds. For long-running commands use terminal_start and terminal_poll. Commands run in an isolated subshell of the visible terminal: the user sees the output live, but shell state such as cd, export, or set does not persist between calls — use absolute paths or combine cd with the command (cd /path && cmd).",
|
||||
"description": "Execute a short command in a terminal session and wait for completion. Use this instead of the local shell when the command is intended for a Netcatty terminal or remote host. Call get_environment first to resolve the sessionId. Use only for commands expected to finish within about 60 seconds. For long-running commands use terminal_start and terminal_poll. Commands run in an isolated subshell of the visible terminal: the user sees the output live, but shell state such as cd, export, or set does not persist between calls — use absolute paths or combine cd with the command (cd /path && cmd). If the shell prompt cannot be recognized while the connection is alive and no busy signal is present, the command is NOT sent and the tool returns SHELL_READINESS_UNKNOWN (a recoverable, non-terminal result, not a failed command): do not blind-type into a possible password prompt — inspect the terminal read-only with get_environment or terminal_read_context, re-check readiness after the user presses Enter, reuse another idle session, or ask the user to confirm the prompt before retrying.",
|
||||
"inputShape": {
|
||||
"sessionId": {
|
||||
"type": "string",
|
||||
|
||||
@@ -0,0 +1,175 @@
|
||||
import { describe, it } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import {
|
||||
createCattyToolsFromCatalog,
|
||||
withCattyToolContext,
|
||||
} from './capabilityTools';
|
||||
import { mapCattyStreamChunkToAgentEvents } from './agentEventAdapter';
|
||||
import { AgentRuntime } from './agentRuntime';
|
||||
import { SessionStateStore } from './sessionState';
|
||||
import type { AgentEvent } from './types';
|
||||
import type { TurnDriver, TurnDriverContext, TurnInput } from './turnDrivers/types';
|
||||
|
||||
// Reuse the #4198 fixture (infrastructure/ai/cattyAgent/
|
||||
// shellReadiness.unknownState.test.ts) verbatim so the MCP path, the executor
|
||||
// path and the ACTIVE Catty SDK path are asserted against the same honest,
|
||||
// actionable hint.
|
||||
const UNKNOWN_HINT = [
|
||||
'Shell readiness unknown (SHELL_READINESS_UNKNOWN): the terminal connection is',
|
||||
'alive but the prompt could not be recognized. The command was NOT sent — never',
|
||||
'blind-type. Read-only next steps: call get_environment or terminal_read_context,',
|
||||
're-check after the user presses Enter, reuse another idle session, or ask the',
|
||||
'user to confirm the prompt before retrying.',
|
||||
].join(' ');
|
||||
|
||||
const BUSY_HINT = 'Shell prompt is not ready; no command was sent';
|
||||
const UNKNOWN_CODE = 'SHELL_READINESS_UNKNOWN';
|
||||
const CHAT = 'chat-readiness';
|
||||
|
||||
function bundle(result: Record<string, unknown>) {
|
||||
return createCattyToolsFromCatalog(
|
||||
{ aiExec: async () => result } as never,
|
||||
{
|
||||
sessions: [{
|
||||
sessionId: 's1',
|
||||
hostId: 'h1',
|
||||
hostname: 'host',
|
||||
label: 'tab',
|
||||
protocol: 'ssh',
|
||||
connected: true,
|
||||
}],
|
||||
} as never,
|
||||
[],
|
||||
'auto',
|
||||
undefined,
|
||||
CHAT,
|
||||
);
|
||||
}
|
||||
|
||||
async function executeTerminal(result: Record<string, unknown>): Promise<Record<string, unknown>> {
|
||||
const { tools, toolsContext } = bundle(result);
|
||||
const execute = withCattyToolContext(
|
||||
tools.terminal_execute as unknown as { execute: (...args: never[]) => unknown },
|
||||
toolsContext.terminal_execute,
|
||||
'call-1',
|
||||
);
|
||||
return await execute.execute({ sessionId: 's1', command: 'echo OK' } as never) as unknown as Record<string, unknown>;
|
||||
}
|
||||
|
||||
function unknownResult(): Record<string, unknown> {
|
||||
return {
|
||||
ok: false, error: UNKNOWN_HINT, code: UNKNOWN_CODE,
|
||||
stdout: '', stderr: '', exitCode: -1,
|
||||
};
|
||||
}
|
||||
|
||||
function busyResult(): Record<string, unknown> {
|
||||
return {
|
||||
ok: false, error: BUSY_HINT, code: 'SHELL_NOT_READY',
|
||||
stdout: '', stderr: '', exitCode: -1,
|
||||
};
|
||||
}
|
||||
|
||||
function toCattyToolResultEvent(output: Record<string, unknown>): AgentEvent {
|
||||
const events = mapCattyStreamChunkToAgentEvents(
|
||||
{ type: 'tool-result', toolCallId: 'call-1', toolName: 'terminal_execute', output },
|
||||
{ sessionId: CHAT, chatSessionId: CHAT },
|
||||
);
|
||||
assert.equal(events.length, 1);
|
||||
return events[0];
|
||||
}
|
||||
|
||||
// Drive a real AgentRuntime turn with the given tool-result event, then read
|
||||
// back whether SessionStateStore registered an open-session blocker. This
|
||||
// exercises agentRuntime.ts:188 (event.isError || isFailedToolResult(result)),
|
||||
// the exact place the old { error: ... } wrapping bricked the session.
|
||||
async function reinjectionFor(output: Record<string, unknown>): Promise<string | undefined> {
|
||||
const toolResultEvent = toCattyToolResultEvent(output);
|
||||
const sessionStateStore = new SessionStateStore();
|
||||
const driver: TurnDriver = {
|
||||
backend: 'catty',
|
||||
async run(_input: TurnInput, ctx: TurnDriverContext): Promise<void> {
|
||||
ctx.emit({
|
||||
id: 'call',
|
||||
type: 'tool_call',
|
||||
toolCallId: 'call-1',
|
||||
toolName: 'terminal_execute',
|
||||
args: { sessionId: 's1', command: 'echo OK' },
|
||||
} as unknown as AgentEvent);
|
||||
ctx.emit({ ...toolResultEvent, id: 'result' } as unknown as AgentEvent);
|
||||
},
|
||||
};
|
||||
const runtime = new AgentRuntime({ drivers: [driver], sessionStateStore });
|
||||
await runtime.runTurn({
|
||||
backend: 'catty',
|
||||
chatSessionId: CHAT,
|
||||
sendScopeKey: CHAT,
|
||||
userText: 'check uptime',
|
||||
signal: new AbortController().signal,
|
||||
currentSession: undefined,
|
||||
assistantMsgId: 'assistant-1',
|
||||
context: {
|
||||
activeProvider: undefined,
|
||||
activeModelId: '',
|
||||
scopeType: 'terminal',
|
||||
globalPermissionMode: 'confirm',
|
||||
terminalSessions: [],
|
||||
autoTitleSession: () => {},
|
||||
},
|
||||
maxIterations: 5,
|
||||
ui: {
|
||||
addMessageToSession: () => {},
|
||||
updateLastMessage: () => {},
|
||||
updateMessageById: () => {},
|
||||
reportStreamError: () => {},
|
||||
setStreamingForScope: () => {},
|
||||
},
|
||||
} as unknown as TurnInput);
|
||||
return sessionStateStore.toReinjectionText(CHAT);
|
||||
}
|
||||
|
||||
describe('active Catty SDK path surfaces SHELL_READINESS_UNKNOWN as non-fatal (#4198 round 2)', () => {
|
||||
it('capabilityTools preserves the code + honest hint and emits NO error shape', async () => {
|
||||
const result = await executeTerminal(unknownResult());
|
||||
assert.equal(result.code, UNKNOWN_CODE);
|
||||
assert.equal('error' in result, false);
|
||||
assert.notEqual(result.ok, false);
|
||||
const text = JSON.stringify(result);
|
||||
assert.match(text, /read-only|get_environment|terminal_read_context/);
|
||||
assert.match(text, /NOT sent/i);
|
||||
const content = result.content as Array<{ type: string; text: string }> | undefined;
|
||||
assert.equal(content?.[0]?.text, UNKNOWN_HINT);
|
||||
});
|
||||
|
||||
it('unknown => agentEventAdapter emits NO isError; SHELL_NOT_READY => still isError true', async () => {
|
||||
const unknownEvent = toCattyToolResultEvent(await executeTerminal(unknownResult()));
|
||||
assert.equal((unknownEvent as { isError?: boolean }).isError, false);
|
||||
const busyEvent = toCattyToolResultEvent(await executeTerminal(busyResult()));
|
||||
assert.equal((busyEvent as { isError?: boolean }).isError, true);
|
||||
});
|
||||
|
||||
it('unknown registers NO open-session blocker; busy still registers one', async () => {
|
||||
const unknownText = await reinjectionFor(await executeTerminal(unknownResult()));
|
||||
assert.doesNotMatch(unknownText ?? '', /Open blockers/);
|
||||
const busyText = await reinjectionFor(await executeTerminal(busyResult()));
|
||||
assert.match(busyText ?? '', /Open blockers/);
|
||||
});
|
||||
|
||||
it('defense-in-depth: a code-carrying error-shaped result stays non-error', async () => {
|
||||
// Even if a future change re-adds an `error` field, the preserved `code`
|
||||
// must keep it out of isError / the session blocker (classification guards).
|
||||
const errorShaped = { error: UNKNOWN_HINT, code: UNKNOWN_CODE };
|
||||
const event = toCattyToolResultEvent(errorShaped);
|
||||
assert.equal((event as { isError?: boolean }).isError, false);
|
||||
const text = await reinjectionFor(errorShaped);
|
||||
assert.doesNotMatch(text ?? '', /Open blockers/);
|
||||
});
|
||||
|
||||
it('a proven-busy error-shaped result without the unknown code is still a hard error', async () => {
|
||||
const busyShaped = { error: BUSY_HINT, ok: false };
|
||||
const event = toCattyToolResultEvent(busyShaped);
|
||||
assert.equal((event as { isError?: boolean }).isError, true);
|
||||
const text = await reinjectionFor(busyShaped);
|
||||
assert.match(text ?? '', /Open blockers/);
|
||||
});
|
||||
});
|
||||
@@ -19,7 +19,7 @@ import { executeWebSearchProvider } from './webSearchProviders';
|
||||
/** Discriminated union returned by every shared executor. */
|
||||
export type ToolExecResult<T = unknown> =
|
||||
| { ok: true; data: T }
|
||||
| { ok: false; error: string; data?: T };
|
||||
| { ok: false; error: string; data?: T; code?: string };
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Dependencies bundle
|
||||
@@ -99,11 +99,14 @@ export async function executeTerminalExecute(
|
||||
}
|
||||
|
||||
const result = await bridge.aiExec(sessionId, command, deps.chatSessionId);
|
||||
// Real execution failures (timeout, disconnect, no stream) have an `error` field
|
||||
// Real execution failures (timeout, disconnect, no stream) have an `error` field.
|
||||
// Propagate `code` so consumers can distinguish an actionable, non-terminal
|
||||
// SHELL_READINESS_UNKNOWN from a fatal error (#4195).
|
||||
if (!result.ok && result.error) {
|
||||
return {
|
||||
ok: false,
|
||||
error: result.error,
|
||||
code: result.code,
|
||||
data: {
|
||||
stdout: result.stdout || '',
|
||||
stderr: result.stderr || '',
|
||||
|
||||
Reference in new issue
Block a user