nox-qwen-agent-cli 1.1.5 → 1.1.7

package/README.md

@@ -22,10 +22,10 @@ PowerShell can also run `.\install.ps1` directly.
 
 ## Configure
 
-Interactive mode asks for a masked API key on every launch. The key remains in
-memory for that process only and is never stored in source code, settings, or
-chat history. Non-interactive `-p` runs read `NOX_API_KEY`,
-`OPENAI_COMPAT_API_KEY`, or `OPENAI_API_KEY`.
+Interactive runs always ask for a masked API key, including `qwen -p` when a
+terminal is attached. Non-interactive runs read `NOX_API_KEY`,
+`OPENAI_COMPAT_API_KEY`, or `OPENAI_API_KEY`. The key remains in memory for that
+process only and is never stored in source code, settings, or chat history.
 
 Linux, macOS, and Termux:
 
@@ -45,6 +45,7 @@ $env:NOX_API_KEY = "your-key"
 qwen
 qwen -m qwen3.7-plus
 qwen -m gpt-5.5 -p "Inspect and test this project."
+qwen --clarify -p "Add authentication."
 qwen --yes --no-stream
 ```
 
@@ -56,8 +57,13 @@ The interactive composer is multiline:
 - Arrow keys, Home, End, Backspace, and Delete edit the message.
 - Multiline clipboard paste is preserved.
 
-Commands: `/plan TASK`, `/image PATH PROMPT`, `/file PATH PROMPT`, `/new`, `/sessions`,
-`/resume SESSION`, `/approval ask|auto`, `/model`, and `/exit`.
+Commands: `/plan TASK`, `/clarify TASK`, `/image PATH PROMPT`, `/file PATH PROMPT`,
+`/new`, `/sessions`, `/resume SESSION`, `/approval ask|auto`, `/model`, and `/exit`.
+
+Use `/clarify TASK` or `--clarify -p "TASK"` when you want the agent to ask
+precise requirements questions first. In clarification mode the agent should
+not edit files or run side-effecting commands; it returns focused questions and
+safe assumptions before implementation.
 
 Images and files are sent as structured OpenAI attachment parts. Their bytes
 are uploaded through the selected provider's file endpoint and are never
@@ -67,8 +73,9 @@ Streaming is enabled by default. Reasoning is shown in a separate Thinking
 section when the provider returns it, and is never mixed into the final answer.
 
 The agent includes bounded file reads, batch reads and writes, tree and text
-search, path metadata, file operations, Git status/diff, and cross-platform
-shell execution. Mutating actions require approval unless `--yes` is used.
+search, path metadata, file operations, Git status/diff, cross-platform shell
+execution, and background terminals for dev servers and long-running commands.
+Mutating actions require approval unless `--yes` is used.
 For substantial tasks the model can call `update_plan`; plan steps and their
 live status are rendered separately from chat and tool output.
 
@@ -77,12 +84,18 @@ live status are rendered separately from chat and tool output.
 The Agent prompt and file tools are maintained centrally. Available workspace
 tools include `file_info`, `list_files`, `search_files`, `find_in_file`,
 `read_file`, `read_lines`, `update_file`, `apply_patch`, `create_file`,
-`delete_file`, `move_file`, `copy_file`, and `make_directory`.
-
-Every Agent run sends fresh runtime context in the system prompt: OS/version,
-processor, Node.js version, workspace root, top-level workspace entries,
-available tools, and approval mode. The prompt includes an explicit Agent
-reminder at startup.
+`delete_file`, `move_file`, `copy_file`, `make_directory`,
+`start_background_terminal`, `read_background_terminal`, and
+`stop_background_terminal`.
+
+Every Agent run sends fresh runtime context in the first user message:
+OS/version, processor, Node.js version, workspace root, top-level workspace
+entries, available tools, and approval mode. The CLI and VS Code extension
+intentionally transport the full Agent instructions by prefixing the first user
+message with `<agent_instructions>`. Every fourth user turn is prefixed with
+`<agent_reminder>` so the model keeps the active workspace and agent role in
+context. This avoids gateways that drop or weaken `system` messages while still
+sending a SHA-256 prompt proof in request metadata.
 
 The file tools enforce workspace-only paths, reject traversal and symlink
 escapes, deny protected secret-looking files by default, detect binary files,

package/agent-system-prompt.js

@@ -28,9 +28,13 @@ Tool-selection rules:
 - Use create_file only when a new file is genuinely required.
 - Use delete_file only when deletion is explicitly required and safe.
 - Use run_shell_command only for commands relevant to the user's task.
+- Use start_background_terminal for long-running commands such as dev servers, watchers, and commands that need later polling.
+- Use read_background_terminal to inspect background output before claiming a server, watcher, or long task is ready.
+- Use stop_background_terminal when a background process is no longer needed or is producing failures.
 - Run focused tests first, followed by the broader suite when appropriate.
 
 File-access rules:
+- A file may be available through an uploaded file id, an attachment in the current request, a client-provided excerpt, workspace tools, a line-range read, or a search result followed by a targeted read.
 - Do not ask the user to upload a file when it is already available in the workspace.
 - Do not read an entire large file when a targeted range is sufficient.
 - Do not invent missing file contents.
@@ -56,6 +60,7 @@ Clarification rules:
 
 Progress rules:
 For longer operations, provide brief progress updates after meaningful milestones. Do not narrate every low-level command.
+When a background terminal is running, summarize only meaningful state changes such as started, ready, failed, or stopped.
 
 Safety rules:
 - Stay inside the configured workspace root.
@@ -64,6 +69,7 @@ Safety rules:
 - Do not read protected secret files unless explicitly authorised.
 - Do not execute destructive commands without explicit permission.
 - Do not install untrusted packages or extensions silently.
+- Do not leave background terminals running after they are no longer needed unless the user asked to keep them running.
 - Do not bypass tests merely to produce a successful-looking result.
 
 Completion rules:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nox-qwen-agent-cli",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "Cross-platform OpenAI-compatible Qwen coding agent CLI",
   "type": "module",
   "license": "UNLICENSED",

package/qwen.js

@@ -19,6 +19,8 @@ const MAX_FILE_BYTES = 20 * 1024 * 1024;
 const MAX_COMMAND_OUTPUT = 128 * 1024;
 const MAX_API_RETRIES = 2;
 const MAX_SHELL_TIMEOUT_MS = 10 * 60 * 1000;
+const MAX_BACKGROUND_OUTPUT = 256 * 1024;
+const MAX_BACKGROUND_TERMINALS = 8;
 const CLARIFY_REQUEST_PROMPT = `Clarify this request before execution.
 Do not modify files, run commands with side effects, or implement the task yet.
 Ask the minimum set of precise questions needed to remove ambiguity, identify acceptance criteria, and confirm risky choices.
@@ -40,6 +42,7 @@ When a tool is required, output exactly one block and no other text:
 <NOX_TOOL_CALL>{"id":"short-stable-id","tool":"exact_tool_name","args":{}}</NOX_TOOL_CALL>
 Arguments must match the selected tool schema. Never emit more than one tool call per response.
 After receiving a <tool_result> block, continue the same objective with the next tool call or the final answer.`;
+const AGENT_REMINDER_PROMPT = `Agent reminder: continue following the initial Agent instructions, use the available tools when needed, keep workspace operations inside the active workspace, and finish only after the requested task is handled.`;
 
 const TOOL_DEFINITIONS = [
   tool("update_plan", "Create or update the visible execution plan.", {
@@ -152,6 +155,19 @@ const TOOL_DEFINITIONS = [
     cwd: stringProperty("Relative working directory; defaults to ."),
     timeout_ms: integerProperty("Timeout from 1 to 600000 ms"),
   }, ["command"]),
+  tool("start_background_terminal", "Start a long-running shell command in the background and return a terminal id for later polling.", {
+    command: stringProperty("Shell command"),
+    cwd: stringProperty("Relative working directory; defaults to ."),
+  }, ["command"]),
+  tool("read_background_terminal", "Read buffered output and status from a background terminal.", {
+    terminal_id: stringProperty("Background terminal id returned by start_background_terminal"),
+    max_bytes: integerProperty("Maximum stdout/stderr bytes to return; defaults to 12000"),
+    wait_ms: integerProperty("Optional polling wait from 0 to 10000 ms for new output or process exit"),
+  }, ["terminal_id"]),
+  tool("stop_background_terminal", "Stop a running background terminal.", {
+    terminal_id: stringProperty("Background terminal id returned by start_background_terminal"),
+    signal: stringProperty("Signal name; defaults to SIGTERM"),
+  }, ["terminal_id"]),
 ];
 
 const EFFECTIVE_TOOL_DEFINITIONS = [
@@ -199,6 +215,57 @@ function refreshSystemPrompt(state) {
   else state.messages.unshift({ role: "system", content: prompt });
 }
 
+function prefixTextContent(content, prompt, kind) {
+  const firstTurn = kind === "instructions";
+  return [
+    firstTurn ? "<agent_instructions>" : "<agent_reminder>",
+    prompt,
+    firstTurn ? "</agent_instructions>" : "</agent_reminder>",
+    "<user_message>",
+    String(content ?? ""),
+    "</user_message>",
+  ].join("\n");
+}
+
+function promptForUserTurn(userTurn, prompt) {
+  if (userTurn === 1) return { kind: "instructions", prompt };
+  if (userTurn > 1 && userTurn % 4 === 0) return { kind: "reminder", prompt: AGENT_REMINDER_PROMPT };
+  return null;
+}
+
+function prefixUserContent(content, transport) {
+  if (!transport) return content;
+  if (Array.isArray(content)) {
+    let inserted = false;
+    const parts = content.map((part) => {
+      if (!inserted && part?.type === "text") {
+        inserted = true;
+        return { ...part, text: prefixTextContent(part.text, transport.prompt, transport.kind) };
+      }
+      return part;
+    });
+    if (inserted) return parts;
+    return [{ type: "text", text: prefixTextContent("", transport.prompt, transport.kind) }, ...parts];
+  }
+  return prefixTextContent(content, transport.prompt, transport.kind);
+}
+
+function outboundMessages(state) {
+  const prompt = systemPrompt(state.workspace, state.options);
+  let userTurn = 1;
+  return state.messages
+    .filter((message) => message?.role !== "system" && message?.role !== "developer")
+    .map((message) => {
+      if (message?.role !== "user") return message;
+      const transport = promptForUserTurn(userTurn, prompt);
+      userTurn += 1;
+      return {
+        ...message,
+        content: prefixUserContent(message.content, transport),
+      };
+    });
+}
+
 function tool(name, description, properties, required = []) {
   return {
     type: "function",
@@ -685,6 +752,9 @@ async function executeToolCall(call, context) {
       }
       return await runShell(String(args.command), cwd, args.timeout_ms);
     }
+    if (name === "start_background_terminal") return await startBackgroundTerminal(context, args);
+    if (name === "read_background_terminal") return await readBackgroundTerminal(context, args);
+    if (name === "stop_background_terminal") return await stopBackgroundTerminal(context, args);
     return { ok: false, error: `Unknown tool: ${name}` };
   } catch (error) {
     return { ok: false, error: String(error?.message || error) };
@@ -853,6 +923,125 @@ async function runShell(command, cwd, timeoutValue) {
   });
 }
 
+function ensureBackgroundTerminals(context) {
+  if (!context.backgroundTerminals) context.backgroundTerminals = new Map();
+  return context.backgroundTerminals;
+}
+
+function backgroundSnapshot(entry, maxBytes = 12000) {
+  const limit = Math.max(1, Math.min(MAX_BACKGROUND_OUTPUT, Number(maxBytes || 12000)));
+  const stdout = entry.stdout.slice(-limit);
+  const stderr = entry.stderr.slice(-limit);
+  return {
+    ok: true,
+    terminal_id: entry.id,
+    command: entry.command,
+    cwd: entry.relativeCwd,
+    running: entry.exit === null,
+    pid: entry.child.pid,
+    started_at: entry.startedAt,
+    exited_at: entry.exitedAt,
+    exit_code: entry.exit?.code ?? null,
+    signal: entry.exit?.signal ?? null,
+    stdout,
+    stderr,
+    truncated: entry.stdout.length > stdout.length || entry.stderr.length > stderr.length || entry.truncated,
+  };
+}
+
+function appendBackgroundOutput(entry, target, chunk) {
+  const text = chunk.toString("utf8");
+  entry[target] += text;
+  if (entry.stdout.length + entry.stderr.length <= MAX_BACKGROUND_OUTPUT) return;
+  const overflow = entry.stdout.length + entry.stderr.length - MAX_BACKGROUND_OUTPUT;
+  if (entry[target].length >= overflow) entry[target] = entry[target].slice(overflow);
+  else {
+    const remaining = overflow - entry[target].length;
+    entry[target] = "";
+    const other = target === "stdout" ? "stderr" : "stdout";
+    entry[other] = entry[other].slice(Math.min(remaining, entry[other].length));
+  }
+  entry.truncated = true;
+}
+
+async function startBackgroundTerminal(context, args) {
+  const terminals = ensureBackgroundTerminals(context);
+  for (const [id, entry] of terminals) {
+    if (entry.exit !== null) terminals.delete(id);
+  }
+  if (terminals.size >= MAX_BACKGROUND_TERMINALS) {
+    throw new Error(`At most ${MAX_BACKGROUND_TERMINALS} background terminals can run at once.`);
+  }
+  const cwd = safeWorkspacePath(context.workspace, args.cwd || ".");
+  const command = String(args.command || "");
+  if (!command.trim()) throw new Error("command must not be empty.");
+  if (!await confirm(context.terminal, context.options, "start background terminal", `$ ${command}\n  cwd: ${path.relative(context.workspace, cwd) || "."}`)) {
+    return { ok: false, error: "User denied background terminal." };
+  }
+  const windows = process.platform === "win32";
+  const executable = windows ? (process.env.ComSpec || "cmd.exe") : "/bin/sh";
+  const shellArgs = windows ? ["/d", "/s", "/c", command] : ["-lc", command];
+  const child = spawn(executable, shellArgs, { cwd, env: process.env, windowsHide: true });
+  const id = `bg_${crypto.randomUUID().slice(0, 8)}`;
+  const entry = {
+    id,
+    command,
+    relativeCwd: path.relative(context.workspace, cwd) || ".",
+    child,
+    stdout: "",
+    stderr: "",
+    truncated: false,
+    startedAt: new Date().toISOString(),
+    exitedAt: null,
+    exit: null,
+  };
+  child.stdout.on("data", (chunk) => appendBackgroundOutput(entry, "stdout", chunk));
+  child.stderr.on("data", (chunk) => appendBackgroundOutput(entry, "stderr", chunk));
+  child.on("error", (error) => {
+    entry.stderr += error.message;
+    entry.exit = { code: null, signal: "ERROR" };
+    entry.exitedAt = new Date().toISOString();
+  });
+  child.on("close", (code, signal) => {
+    entry.exit = { code, signal };
+    entry.exitedAt = new Date().toISOString();
+  });
+  terminals.set(id, entry);
+  return backgroundSnapshot(entry, args.max_bytes);
+}
+
+async function readBackgroundTerminal(context, args) {
+  const terminals = ensureBackgroundTerminals(context);
+  const id = String(args.terminal_id || "");
+  const entry = terminals.get(id);
+  if (!entry) return { ok: false, error: `Unknown background terminal: ${id}` };
+  const waitMs = Math.max(0, Math.min(10000, Number(args.wait_ms || 0)));
+  if (waitMs > 0 && entry.exit === null) {
+    const stdoutLength = entry.stdout.length;
+    const stderrLength = entry.stderr.length;
+    const deadline = Date.now() + waitMs;
+    while (Date.now() < deadline && entry.exit === null && entry.stdout.length === stdoutLength && entry.stderr.length === stderrLength) {
+      await new Promise((resolve) => setTimeout(resolve, Math.min(50, deadline - Date.now())));
+    }
+  }
+  const snapshot = backgroundSnapshot(entry, args.max_bytes);
+  if (!snapshot.running) terminals.delete(id);
+  return snapshot;
+}
+
+async function stopBackgroundTerminal(context, args) {
+  const terminals = ensureBackgroundTerminals(context);
+  const id = String(args.terminal_id || "");
+  const entry = terminals.get(id);
+  if (!entry) return { ok: false, error: `Unknown background terminal: ${id}` };
+  const signal = String(args.signal || "SIGTERM");
+  if (entry.exit === null) entry.child.kill(signal);
+  await new Promise((resolve) => setTimeout(resolve, 25));
+  const snapshot = backgroundSnapshot(entry, args.max_bytes);
+  if (entry.exit !== null) terminals.delete(id);
+  return snapshot;
+}
+
 async function requestCompletion(state) {
   for (let attempt = 0; attempt <= MAX_API_RETRIES; attempt += 1) {
     try {
@@ -872,9 +1061,10 @@ async function requestCompletion(state) {
 
 async function requestCompletionOnce(state) {
   const providerSession = state.providerSessions?.[state.model] || null;
+  const prompt = systemPrompt(state.workspace, state.options);
   const body = {
     model: state.model,
-    messages: state.messages,
+    messages: outboundMessages(state),
     tools: EFFECTIVE_TOOL_DEFINITIONS,
     tool_choice: "auto",
     parallel_tool_calls: false,
@@ -886,6 +1076,8 @@ async function requestCompletionOnce(state) {
       nox_new_provider_chat: !providerSession,
       ...(providerSession ? { nox_provider_session: providerSession } : {}),
       qwen_cli_session_id: state.sessionId,
+      nox_prompt_transport: "user-prefix",
+      nox_system_prompt_sha256: crypto.createHash("sha256").update(prompt).digest("hex"),
       nox_thinking_level: "medium",
     },
   };
@@ -929,9 +1121,26 @@ async function collectChatStream(body, { onText, onThinking }) {
   let buffer = "";
   let content = "";
   let reasoning = "";
+  let pendingText = "";
+  let streamingText = false;
   const toolCalls = [];
   let providerSession = null;
   let completed = false;
+  const maybeTextToolPrefix = (value) => {
+    const trimmed = String(value || "").trimStart();
+    return "<NOX_TOOL_CALL>".startsWith(trimmed) || trimmed.startsWith("<NOX_TOOL_CALL>");
+  };
+  const handleText = (chunk) => {
+    if (streamingText) {
+      onText(chunk);
+      return;
+    }
+    pendingText += chunk;
+    if (maybeTextToolPrefix(pendingText)) return;
+    streamingText = true;
+    onText(pendingText);
+    pendingText = "";
+  };
   while (true) {
     const { value, done } = await reader.read();
     if (done) break;
@@ -966,7 +1175,7 @@ async function collectChatStream(body, { onText, onThinking }) {
       }
       if (typeof delta.content === "string" && delta.content) {
         content += delta.content;
-        onText(delta.content);
+        handleText(delta.content);
       }
       for (const part of delta.tool_calls || []) {
         const index = Number(part.index || 0);
@@ -988,6 +1197,17 @@ async function collectChatStream(body, { onText, onThinking }) {
     error.partialResponse = Boolean(content || toolCalls.length);
     throw error;
   }
+  const textToolCall = parseTextToolCall(content);
+  if (textToolCall && !toolCalls.length) {
+    return {
+      role: "assistant",
+      content: null,
+      ...(reasoning ? { reasoning_content: reasoning } : {}),
+      ...(providerSession ? { provider_session: providerSession } : {}),
+      tool_calls: [textToolCall],
+    };
+  }
+  if (!streamingText && pendingText) onText(pendingText);
   if (content && !onText) process.stdout.write("\n");
   return {
     role: "assistant",
@@ -1004,7 +1224,7 @@ async function runAgentTurn(state, userMessage) {
   await persistSession(state);
   for (let step = 0; step < MAX_TOOL_STEPS; step += 1) {
     state.ui?.working(step + 1);
-    const assistant = await requestCompletion(state);
+    const assistant = normalizeAssistantToolTransport(await requestCompletion(state));
     if (assistant.provider_session && typeof assistant.provider_session === "object") {
       state.providerSessions[state.model] = assistant.provider_session;
     }
@@ -1123,6 +1343,7 @@ async function main() {
     workspace,
     sessionId: "",
     providerSessions: {},
+    backgroundTerminals: new Map(),
     messages: [],
     ui,
     historyErrorShown: false,
@@ -1153,7 +1374,7 @@ async function main() {
 
   try {
     if (options.prompt) {
-      await runAgentTurn(state, { role: "user", content: options.prompt });
+      await runAgentTurn(state, { role: "user", content: options.clarify ? clarifyPrompt(options.prompt) : options.prompt });
       return;
     }
     if (!ui) throw new Error("Interactive mode requires a terminal or --prompt.");
@@ -1203,13 +1424,16 @@ async function main() {
       const image = parseImageCommand(input);
       const file = parseFileCommand(input);
       const planTask = input.startsWith("/plan ") ? input.slice(6).trim() : "";
+      const clarifyTask = input.startsWith("/clarify ") ? input.slice(9).trim() : "";
       try {
         await runAgentTurn(state,
           image ? await imageMessage(image.filePath, image.prompt)
             : file ? await fileMessage(file.filePath, file.prompt)
               : {
                   role: "user",
-                  content: planTask
+                  content: clarifyTask
+                    ? clarifyPrompt(clarifyTask)
+                    : planTask
                     ? `Create and show a concrete plan with update_plan before executing this task, then keep it updated:\n\n${planTask}`
                     : input,
                 });

package/terminal-ui.js

@@ -218,7 +218,7 @@ export class TerminalUI {
     if (approvalMode === "auto") {
       this.write(`${this.yellow("  Auto approval is active: model-requested changes and commands run without prompts.")}\n`);
     }
-    this.write(`${this.dim("  /plan   /image   /file   /model   /sessions   /approval   /exit")}\n`);
+    this.write(`${this.dim("  /plan   /clarify   /image   /file   /model   /sessions   /approval   /exit")}\n`);
   }
 
   async readMessage() {