wtagent 0.3.0 → 1.0.0

package/src/protocol/envelope.js

@@ -0,0 +1,74 @@
+// Locate transport tags without mistaking quoted attributes, comments, or
+// CDATA payloads for markup. This is a boundary scanner, not an XML validator.
+// Malformed markup is still passed to the strict protocol parser.
+export function* xmlTags(value) {
+  const text = String(value ?? "");
+  let index = 0;
+  while ((index = text.indexOf("<", index)) >= 0) {
+    const start = index;
+    const special = text.startsWith("<![CDATA[", index)
+      ? [9, "]]>"]
+      : text.startsWith("<!--", index)
+        ? [4, "-->"]
+        : text.startsWith("<?", index) ? [2, "?>"] : null;
+    if (special) {
+      const end = text.indexOf(special[1], index + special[0]);
+      if (end < 0) return;
+      index = end + special[1].length;
+      continue;
+    }
+    const match = /^<(\/)?([A-Za-z_][\w:.-]*)(?=[\s/>])/.exec(text.slice(index));
+    if (!match) {
+      index += 1;
+      continue;
+    }
+    index += match[0].length;
+    let quote = null;
+    for (; index < text.length; index += 1) {
+      const character = text[index];
+      if (quote) {
+        if (character === quote) quote = null;
+      } else if (character === '"' || character === "'") {
+        quote = character;
+      } else if (character === "<" || character === ">") {
+        break;
+      }
+    }
+    // Keep an unfinished opening tag visible to the boundary finder; otherwise
+    // a tool inside a malformed outer root could be mistaken for a bare call.
+    if (index >= text.length || text[index] === "<") {
+      yield { name: match[2], closing: Boolean(match[1]), selfClosing: false, start, end: null };
+      if (index >= text.length) return;
+      continue;
+    }
+    index += 1;
+    yield {
+      name: match[2],
+      closing: Boolean(match[1]),
+      selfClosing: /\/\s*>$/.test(text.slice(start, index)),
+      start,
+      end: index,
+    };
+  }
+}
+
+export function findXmlElement(text, name = "agent_response") {
+  let start = null;
+  let depth = 0;
+  for (const tag of xmlTags(text)) {
+    if (tag.name !== name) continue;
+    if (start == null) {
+      if (tag.closing) continue;
+      start = tag.start;
+    }
+    if (tag.end == null) return { start, end: null };
+    if (tag.closing) depth -= 1;
+    else if (!tag.selfClosing) depth += 1;
+    if (depth === 0) return { start, end: tag.end };
+  }
+  return start == null ? null : { start, end: null };
+}
+
+export function hasCompleteAgentEnvelope(text) {
+  return findXmlElement(text)?.end != null;
+}

package/src/protocol/markers.js

@@ -21,6 +21,22 @@ export const DEFAULT_SYSTEM_REMINDER = [
   "Write large code or file payloads as CDATA (<![CDATA[...]]>) inside <content>, <new_text>, or <message> — never raw code directly inside the envelope — and never include the sequence ]]> inside CDATA content.",
 ].join(" ");
 
+// A native image is an assistant response, never a local XML tool call.
+export const NATIVE_IMAGE_CONTRACT = [
+  "When the task needs generated artwork, generate and output the image directly using your native image-generation capability.",
+  "Image responses are exempt from the XML format: output the image itself, without an XML wrapper or drawing code.",
+  "The Runtime automatically downloads images from your completed reply and returns verified local paths; then continue the user's task using those paths.",
+  "There is no local image-generation tool. This replaces any image-tool instructions from earlier in this conversation.",
+  "If generation returns only text, that text will be returned as the provider result so you can explain the limitation or ask the user; do not claim an image was saved.",
+].join(" ");
+
+export const NATIVE_IMAGE_SYSTEM_REMINDER = [
+  NATIVE_IMAGE_CONTRACT,
+  "For text answers and local operations, use exactly one complete <agent_response> XML envelope in one xml code fence.",
+  "Use done=true for a deliverable answer or a question that requires user input; use done=false with one local tool request when needed.",
+  "Use CDATA for code or long payloads. Local tools execute only after the Runtime returns their results.",
+].join(" ");
+
 export function wrapSystemPrompt(text) {
   return `<${SYSTEM_PROMPT_TAG}>\n${String(text ?? "")}\n</${SYSTEM_PROMPT_TAG}>`;
 }

package/src/protocol/prompt-builder.js

@@ -1,4 +1,4 @@
-import { wrapSystemPrompt } from "./markers.js";
+import { NATIVE_IMAGE_CONTRACT, wrapSystemPrompt } from "./markers.js";
 
 function formatTool(tool) {
   // Flat, so multi-line descriptions (arrays) keep their line breaks instead
@@ -19,19 +19,19 @@ const DONE_SEMANTICS = `Current-run completion semantics:
 - Set done=true only when the current user request has a complete, deliverable answer, or when you have a specific question that must be answered by the user before useful work can continue.
 - For informational or conversational tasks (e.g. answering a question, summarizing text, brainstorming), you can reply with done=true and your answer directly — no tool call is required.
 - For tasks that require reading, creating, or modifying files on the user's machine, use the local tools and verify the result before done=true.
-- The Runtime validates completion against successful local tool evidence. Never claim that you created, changed, read, tested, or verified local state unless the corresponding tool results were returned in this run.
+- Base claims about creating, changing, reading, testing, or verifying local state on tool results returned in this run. The Runtime validates the protocol and tracks tool execution; you are responsible for assessing whether the user's request is satisfied.
 - Use done=false only when you are about to call a local tool and need its result before you can continue.
 - Tool count, elapsed turns, or lack of an immediately obvious next action never proves completion.`;
 
 // The protocol + tool catalog are WTAgent-specific transport scaffolding.
 // They are wrapped for the web message and never persisted into the portable
 // Codex rollout.
-function buildBootstrapScaffold({ projectRoot, tools }) {
+function buildBootstrapScaffold({ projectRoot, tools, nativeImages }) {
   const toolDocs = tools.map(formatTool).join("\n\n");
 
   return `The user is running WTAgent, a local application that uses this web AI conversation for reasoning. The following is the user's requested application-level response format and collaboration contract; it is not a claim that this web chat has native filesystem or function-call tools.
 
-You do not need direct filesystem access or provider-native tool buttons. Return local operation requests as XML text. After your reply is complete, the user's local Node.js Runtime will parse the XML, validate the arguments, apply local policy, and may execute the requested operation. Its result will arrive in the next user message as <tool_result>. XML by itself never guarantees execution.
+You do not need direct filesystem access for local operations. Return local operation requests as XML text. After your reply is complete, the user's local Node.js Runtime will parse the XML, validate the arguments, apply local policy, and may execute the requested operation. Its result will arrive in the next user message as <tool_result>. XML by itself never guarantees execution.
 
 You are not limited to coding tasks. You can answer questions, write text, brainstorm, analyze, summarize, and — when the task requires it — request that the user's Runtime read, create, or modify files or run commands.
 
@@ -40,8 +40,8 @@ The project filesystem described below is a logical, virtual filesystem namespac
 
 Do not inspect /workspace, /mnt/data, or any ambient, cloud, or sandbox filesystem. Those locations are unrelated to the user's project. Request all project reads, listings, writes, edits, and commands only through the XML operations declared below.
 
-## Output protocol
-Every reply must contain exactly one complete XML root node inside a single \`xml\` code fence, with no text outside the fence. The code fence guarantees that JavaScript backticks and other source characters are not swallowed by the web Markdown renderer:
+${nativeImages ? `## Native images\n${NATIVE_IMAGE_CONTRACT}\n\n` : ""}## Output protocol
+${nativeImages ? "Every text reply" : "Every reply"} must contain exactly one complete XML root node inside a single \`xml\` code fence, with no text outside the fence. The code fence guarantees that JavaScript backticks and other source characters are not swallowed by the web Markdown renderer:
 
 \`\`\`xml
 <agent_response>
@@ -106,18 +106,19 @@ export function buildBootstrapPrompt({
   task,
   projectRoot,
   tools,
+  nativeImages = false,
 }) {
-  const developer = buildBootstrapScaffold({ projectRoot, tools });
+  const developer = buildBootstrapScaffold({ projectRoot, tools, nativeImages });
   const web = `${wrapSystemPrompt(developer)}\n\n## User task\n${task}`;
   return { web, developer, user: task };
 }
 
-function buildResumeScaffold({ tools, followUpRule, state, nextInstruction }) {
+function buildResumeScaffold({ tools, followUpRule, state, nextInstruction, nativeImages }) {
   const toolDocs = tools.map(formatTool).join("\n\n");
 
   return `Continue the same WTAgent session using the user's requested XML application protocol. You do not need native tool access: write a <tool_call> request as text, and the user's local Runtime will validate it, may execute it, and will return <tool_result> in the next user message.
 
-Still place your single <agent_response> XML inside one \`xml\` code fence with no text outside it and call at most one tool per turn. This preserves JavaScript backticks inside file contents.
+${nativeImages ? `${NATIVE_IMAGE_CONTRACT}\n\nFor text replies: ` : ""}Still place your single <agent_response> XML inside one \`xml\` code fence with no text outside it and call at most one tool per turn. This preserves JavaScript backticks inside file contents.
 
 ${DONE_SEMANTICS}
 
@@ -138,6 +139,7 @@ export function buildResumePrompt({
   instruction,
   state,
   tools,
+  nativeImages = false,
 }) {
   const nextInstruction = instruction?.trim()
     || "Continue the interrupted run based on the current project state and return a deliverable result.";
@@ -150,6 +152,7 @@ export function buildResumePrompt({
     followUpRule,
     state,
     nextInstruction,
+    nativeImages,
   });
   return {
     web: wrapSystemPrompt(developer),

package/src/protocol/xml-protocol.js

@@ -1,5 +1,6 @@
 import { XMLParser, XMLValidator } from "fast-xml-parser";
 import { ProtocolError } from "../shared/errors.js";
+import { findXmlElement, xmlTags } from "./envelope.js";
 import {
   truncateUtf8HeadTail,
   utf8ByteLength,
@@ -64,8 +65,9 @@ function escapeBareAmpersands(text) {
 }
 
 function closeDanglingToolCall(envelope) {
-  const open = (envelope.match(/<tool_call(?:\s|>)/gi) ?? []).length;
-  const close = (envelope.match(/<\/tool_call>/gi) ?? []).length;
+  const tags = [...xmlTags(envelope)].filter((tag) => tag.name === "tool_call");
+  const open = tags.filter((tag) => !tag.closing && !tag.selfClosing).length;
+  const close = tags.filter((tag) => tag.closing).length;
   if (open !== close + 1) {
     return envelope;
   }
@@ -76,11 +78,9 @@ function closeDanglingToolCall(envelope) {
 }
 
 function wrapBareToolCall(text) {
-  const start = text.search(/<tool_call(?:\s|>)/i);
-  const endTag = "</tool_call>";
-  const end = start < 0 ? -1 : text.indexOf(endTag, start);
-  if (start >= 0 && end >= start) {
-    const toolCall = text.slice(start, end + endTag.length);
+  const bounds = findXmlElement(text, "tool_call");
+  if (bounds?.end != null) {
+    const toolCall = text.slice(bounds.start, bounds.end);
     if (/<args[\s>/]/i.test(toolCall)) {
       return [
         "<agent_response>",
@@ -134,12 +134,11 @@ function wrapClaudeStyleInvoke(text) {
 
 function extractEnvelope(text) {
   const cleaned = stripSingleCodeFence(text);
-  const start = cleaned.indexOf("<agent_response");
-  const endTag = "</agent_response>";
-  const end = start < 0 ? -1 : cleaned.indexOf(endTag, start);
+  const bounds = findXmlElement(cleaned);
 
-  if (start < 0 || end < 0) {
-    const wrapped = wrapBareToolCall(cleaned);
+  if (bounds?.end == null) {
+    // Never salvage an operation out of an unfinished outer response.
+    const wrapped = bounds == null ? wrapBareToolCall(cleaned) : null;
     if (wrapped) {
       return wrapped;
     }
@@ -154,7 +153,7 @@ function extractEnvelope(text) {
   // — so first-open + last-close would glue two envelopes together and fail
   // with "Extra text at the end". Trailing chatter after that first envelope
   // is ignored the same way a preamble before it is.
-  return cleaned.slice(start, end + endTag.length);
+  return cleaned.slice(bounds.start, bounds.end);
 }
 
 // Web-UIs render provider chrome into the assistant text: thinking-block
@@ -231,12 +230,11 @@ export function stripUiNoiseLines(text) {
 // and let the caller keep the envelope's own message.
 export function extractTrailingProse(rawText) {
   const text = String(rawText ?? "");
-  const endTag = "</agent_response>";
-  const end = text.indexOf(endTag);
-  if (end < 0) {
+  const bounds = findXmlElement(text);
+  if (bounds?.end == null) {
     return null;
   }
-  const trailing = text.slice(end + endTag.length);
+  const trailing = text.slice(bounds.end);
   if (trailing.includes("<agent_response")) {
     return null;
   }
@@ -332,9 +330,21 @@ function looseTagText(xml, tag) {
 // guessing the arguments of a side-effecting operation from broken XML is
 // unsafe, so those still fall through to a format retry.
 function recoverMessageOnlyResponse(envelope) {
-  if (/<tool_call[\s>]/i.test(envelope)) {
+  const tags = [...xmlTags(envelope)];
+  if (
+    tags.some((tag) => /^(tool_call|tool_calls|invoke|action|parameter)$/.test(tag.name))
+    || tags.filter((tag) => tag.name === "agent_response" && !tag.closing).length !== 1
+  ) {
     return null;
   }
+  // Tolerate malformed display markup only inside <message>. Unknown sibling
+  // fields must not disappear when a damaged operation is mistaken for prose.
+  const root = tags.find((tag) => tag.name === "agent_response" && !tag.closing);
+  const closing = tags.findLast((tag) => tag.name === "agent_response" && tag.closing);
+  const siblings = envelope.slice(root.end, closing.start)
+    .replace(/<done(?:\s[^>]*)?>[\s\S]*?<\/done>/g, "")
+    .replace(/<message(?:\s[^>]*)?>[\s\S]*?<\/message>/g, "");
+  if (siblings.trim()) return null;
   const doneText = looseTagText(envelope, "done");
   const message = looseTagText(envelope, "message");
   if (doneText == null || message == null) {
@@ -366,6 +376,11 @@ export function parseAgentResponse(rawText) {
   if (/<!DOCTYPE|<!ENTITY/i.test(structuralXml)) {
     throw new ProtocolError("DTD and XML entities are not allowed.");
   }
+  if ([...xmlTags(rawEnvelope)].filter((tag) => (
+    tag.name === "agent_response" && !tag.closing
+  )).length !== 1) {
+    throw new ProtocolError("Nested <agent_response> envelopes are not allowed.");
+  }
 
   // Repair the most common, meaning-preserving corruptions before validation:
   // 1. bare ampersands the model wrote outside CDATA
@@ -402,6 +417,9 @@ export function parseAgentResponse(rawText) {
   if (!response || typeof response !== "object" || Array.isArray(response)) {
     throw new ProtocolError("Missing <agent_response> root.");
   }
+  if (["action", "invoke", "tool_calls"].some((name) => response[name] != null)) {
+    throw new ProtocolError("Operations must use one <tool_call> element with <args>.");
+  }
 
   const done = parseDone(response.done);
   const message = scalarText(response.message);