@foldspace_npm/harness 0.1.27 → 0.1.29

package/src/lint/rules.mjs

@@ -57,7 +57,7 @@ const IMPERATIVE_PATTERNS = [
 const EMOJI_PATTERN = /\p{Extended_Pictographic}/u;
 
 const PROMPT_FIX =
-  "Put the wording in the action or agent instructions via MCP or Agent Studio; return data only.";
+  "Put the wording in the action's instructions (with the Foldspace tools or in Agent Studio) or in the agent's instructions (Agent Studio only); return data only.";
 
 function mergeBindings(fn, sourceFile) {
   return new Map([
@@ -98,7 +98,7 @@ function inspectReturnedObject(obj, bindings, sourceFile, relative, findings, or
           sourceFile,
           node: at,
           file: relative,
-          message: `${origin} sends the copilot operating instructions ('${text.slice(0, 80)}').`,
+          message: `${origin} sends the agent operating instructions ('${text.slice(0, 80)}').`,
           fix: PROMPT_FIX,
         }),
       );
@@ -128,19 +128,29 @@ export function ruleNoStaticAgentPrompt(sourceFile, relative, findings) {
     }
 
     if (name === "render") {
-      const cbName = callbackParamName(fn);
-      forEachCallNamed(fn, cbName, (call) => {
-        const arg = call.arguments[0];
-        if (!arg) return;
-        inspectReturnedObject(
-          resolveNode(arg, bindings),
-          bindings,
-          sourceFile,
-          relative,
-          findings,
-          "callback",
-        );
-      });
+      // What a card hands to callback, and to readyState (render's 6th
+      // parameter), reaches the agent as the card's result - check both.
+      const params = fn.parameters || [];
+      const readyName =
+        params.length >= 6 && ts.isIdentifier(params[5].name) ? params[5].name.text : null;
+      for (const [paramName, origin] of [
+        [callbackParamName(fn), "callback"],
+        [readyName, "readyState"],
+      ]) {
+        if (!paramName) continue;
+        forEachCallNamed(fn, paramName, (call) => {
+          const arg = call.arguments[0];
+          if (!arg) return;
+          inspectReturnedObject(
+            resolveNode(arg, bindings),
+            bindings,
+            sourceFile,
+            relative,
+            findings,
+            origin,
+          );
+        });
+      }
     }
   });
 }
@@ -208,8 +218,8 @@ function reportEmoji(node, sourceFile, relative, findings) {
       sourceFile,
       node,
       file: relative,
-      message: "Emoji in handler or widget copy reads as off-brand in a product UI that has none.",
-      fix: "Strip the glyph from handler/render copy. Put “no emoji” in the agent's Behavior instructions; the MCP cannot write that field, so each new action's Studio instructions must carry the line too.",
+      message: "Emoji in handler or card copy reads as off-brand in a product UI that has none.",
+      fix: "Strip the glyph from handler/render copy. Put “no emoji” in the agent's Behavior instructions; the Foldspace tools cannot write that field, so each new action's Studio instructions must carry the line too.",
     }),
   );
 }
@@ -450,30 +460,357 @@ export function ruleRegistryIntegrity({ indexFile, indexSource, actionFiles, pro
   }
 }
 
-// The panel saves every rendered card to the conversation history as an image
-// drawn with html2canvas, which cannot parse modern colour functions: one such
-// value and the saved card is blank ("data:," where the card was - seen on a
-// CRM, 2026-09-22). Hex and rgba survive.
-const UNSNAPSHOTTABLE_COLOR = /\b(oklch|oklab|lch|lab|color-mix|light-dark)\s*\(/i;
-
-export function ruleNoUnsnapshottableColor(sourceFile, relative, findings) {
-  forEachStringLiteral(sourceFile, (node) => {
-    if (ts.isImportDeclaration(node.parent) || ts.isExportDeclaration(node.parent)) return;
-    const text = node.getText(sourceFile);
-    const match = UNSNAPSHOTTABLE_COLOR.exec(text);
-    if (!match) return;
+// The card contract of the page SDK. A card is a view card or an input card.
+// An input card's render uses one of its 4th to 6th parameters - callback,
+// cancel, readyState - and the agent waits until callback or cancel runs, or
+// until readyState reports. A view card uses none of them: as soon as render
+// returns, the agent is told it was shown, with everything execute returned.
+// awaitUserInput is never needed. The chat panel ignores it; in headless mode
+// awaitUserInput: true forces the wait, so on a view card the agent waits for
+// a callback that never comes.
+//
+// "Uses" is read the way the SDK reads render in the built bundle, where
+// parameters are renamed and types are erased: the parameter's name anywhere
+// in the body, nested functions included, but not as a property name
+// (`host.callback`, `{ callback: 1 }`) and not inside a type. A destructured
+// parameter, a `...rest` parameter or `arguments` count as used. A TypeScript
+// `this` parameter is erased, so it takes no position.
+const CARD_PARAMS = ["callback", "cancel", "readyState"];
+
+function mentions(fn, test) {
+  let found = false;
+  function walk(node) {
+    if (found) return;
+    if (ts.isIdentifier(node) && test(node.text)) {
+      const parent = node.parent;
+      const isName =
+        parent &&
+        (ts.isPropertyAccessExpression(parent) ||
+          ts.isPropertyAssignment(parent) ||
+          ts.isMethodDeclaration(parent) ||
+          ts.isPropertyDeclaration(parent) ||
+          ts.isGetAccessorDeclaration(parent) ||
+          ts.isSetAccessorDeclaration(parent)) &&
+        parent.name === node;
+      const isKey = parent && ts.isBindingElement(parent) && parent.propertyName === node;
+      let inType = false;
+      for (let up = parent; up && up !== fn; up = up.parent) {
+        if (ts.isTypeNode(up) && !ts.isExpressionWithTypeArguments(up)) {
+          inType = true;
+          break;
+        }
+      }
+      if (!isName && !isKey && !inType) {
+        found = true;
+        return;
+      }
+    }
+    ts.forEachChild(node, walk);
+  }
+  if (fn.body) walk(fn.body);
+  return found;
+}
+
+/** What the SDK concludes about a render function: does the agent wait, and which card parameters are declared but unused. */
+function readRender(fn) {
+  const params = fn.parameters.filter((param) => !(ts.isIdentifier(param.name) && param.name.text === "this"));
+  const cardParams = params.slice(3, 3 + CARD_PARAMS.length);
+  const restOrArguments = params.some((param) => param.dotDotDotToken) || mentions(fn, (name) => name === "arguments");
+  const destructured = cardParams.some((param) => !ts.isIdentifier(param.name));
+  const names = cardParams.filter((param) => ts.isIdentifier(param.name)).map((param) => param.name.text);
+  const used = names.filter((name) => mentions(fn, (text) => text === name));
+  const waits = restOrArguments || destructured || used.length > 0;
+  return { waits, declaredUnused: !waits && names.length > 0 ? names : [] };
+}
+
+// The function `render` names: inline, a method, or - for `render` and
+// `render: renderCard` - a `function` or `const` of that name in the same file.
+function declaredFunction(sourceFile, name) {
+  let found = null;
+  function walk(node) {
+    if (found) return;
+    if (ts.isFunctionDeclaration(node) && node.name?.text === name) {
+      found = node;
+      return;
+    }
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === name && isFunctionLike(node.initializer)) {
+      found = node.initializer;
+      return;
+    }
+    ts.forEachChild(node, walk);
+  }
+  walk(sourceFile);
+  return found;
+}
+
+function renderFunction(sourceFile, member) {
+  if (ts.isMethodDeclaration(member)) return member;
+  if (ts.isShorthandPropertyAssignment(member)) return declaredFunction(sourceFile, member.name.text);
+  let value = member.initializer;
+  while (
+    value &&
+    (ts.isParenthesizedExpression(value) ||
+      ts.isAsExpression(value) ||
+      ts.isSatisfiesExpression(value) ||
+      ts.isNonNullExpression(value) ||
+      ts.isTypeAssertionExpression(value))
+  )
+    value = value.expression;
+  if (isFunctionLike(value)) return value;
+  if (value && ts.isIdentifier(value)) return declaredFunction(sourceFile, value.text);
+  return null;
+}
+
+export function ruleCardContract(sourceFile, relative, findings) {
+  function walk(node) {
+    if (ts.isObjectLiteralExpression(node)) {
+      const members = node.properties;
+      const render = members.find(
+        (member) =>
+          propertyName(member) === "render" &&
+          (ts.isPropertyAssignment(member) || ts.isMethodDeclaration(member) || ts.isShorthandPropertyAssignment(member)),
+      );
+      const fn = render ? renderFunction(sourceFile, render) : null;
+      if (fn) {
+        const { waits, declaredUnused } = readRender(fn);
+        const flag = members.find((member) => propertyName(member) === "awaitUserInput");
+        const flagTrue = flag && ts.isPropertyAssignment(flag) && flag.initializer.kind === ts.SyntaxKind.TrueKeyword;
+        if (flagTrue && !waits) {
+          findings.push(
+            finding({
+              rule: "card-contract",
+              severity: "error",
+              sourceFile,
+              node: flag.name,
+              file: relative,
+              message:
+                "A view card (render uses neither callback nor cancel) sets awaitUserInput: true. The chat panel ignores it, but in headless mode the agent then waits for a callback that never comes.",
+              fix: "Remove awaitUserInput. A view card is reported to the agent as shown, with what execute returned.",
+            }),
+          );
+        }
+        if (flag && !waits && !flagTrue) {
+          findings.push(
+            finding({
+              rule: "card-contract",
+              severity: "warning",
+              sourceFile,
+              node: flag.name,
+              file: relative,
+              message:
+                "A view card does not need awaitUserInput: render uses neither callback nor cancel, so the agent is told the card was shown, with what execute returned.",
+              fix: "Remove awaitUserInput.",
+            }),
+          );
+        }
+        if (flag && waits) {
+          findings.push(
+            finding({
+              rule: "card-contract",
+              severity: "warning",
+              sourceFile,
+              node: flag.name,
+              file: relative,
+              message:
+                "An input card does not need awaitUserInput: render uses callback, cancel or readyState, and that is what makes the agent wait.",
+              fix: 'Remove awaitUserInput. Then check that every path calls callback or cancel - choosing, "none of these", closing the card, failing. When the conversation should go on while the user decides, call readyState(value) once the card is drawn.',
+            }),
+          );
+        }
+        if (declaredUnused.length > 0) {
+          const list =
+            declaredUnused.length === 1
+              ? declaredUnused[0]
+              : `${declaredUnused.slice(0, -1).join(", ")} and ${declaredUnused.at(-1)}`;
+          const unused = declaredUnused.length === 1 ? "never uses it" : "uses none of them";
+          findings.push(
+            finding({
+              rule: "card-contract",
+              severity: "warning",
+              sourceFile,
+              node: render.name,
+              file: relative,
+              message: `render declares ${list} but ${unused} - the SDK treats the card as a view card: the agent is told it was shown, with what execute returned.`,
+              fix: `For a view card, remove ${list} from render. For an input card, call callback or cancel on every path, or readyState(value) once the card is drawn.`,
+            }),
+          );
+        }
+      }
+    }
+    ts.forEachChild(node, walk);
+  }
+  walk(sourceFile);
+}
+
+// Test mode belongs to `attach --test-mode`, which never touches the bundle.
+// A call in agent code that turns it on can ship to production and mark real
+// users' conversations as test traffic.
+//
+// `setTestMode` is refused unless it is called with the literal `false` - and
+// also when it is reached any other way (handed on, `.call`, `.bind`).
+// `armAllInstances` is refused however it is used, whatever its argument:
+// called (by name, under the name it was imported as, by element access),
+// handed on (a timer, a listener, an object, a default value) or exported
+// under another name. Even with `false` it sends a partial `setConfiguration`
+// to every instance. Importing it, re-exporting it under its own name and
+// types are not uses. Names are matched within the file, not by binding, so
+// the rule errs on the side of refusing.
+//
+// One call is not refused. A code project carries its own copy of the runtime,
+// and that copy's `agent/runtime/agent.ts` defines `function
+// armAllInstances(testMode)`, which calls `setTestMode(testMode)`. That call -
+// with the helper's own first parameter, in that function, in that file - runs
+// only when something uses `armAllInstances`, and every use is refused. The
+// build also checks the bundle itself (`bundleTurnsOnTestMode`), which catches
+// what reading the source cannot.
+export function ruleNoTestModeInBundle(sourceFile, relative, findings) {
+  // path.sep, so a POSIX file whose name holds a backslash is not read as a folder.
+  const inRuntimeHelperFile = relative.split(path.sep).join("/") === "agent/runtime/agent.ts";
+
+  const ARM = "armAllInstances";
+  const armNames = new Set([ARM]);
+  const keyText = (key) => {
+    if (!key) return undefined;
+    if (ts.isIdentifier(key) || ts.isStringLiteralLike(key)) return key.text;
+    if (ts.isComputedPropertyName(key) && ts.isStringLiteralLike(key.expression)) return key.expression.text;
+    return undefined;
+  };
+  const collectImportedNames = (node) => {
+    if (ts.isImportSpecifier(node) && keyText(node.propertyName ?? node.name) === ARM) armNames.add(node.name.text);
+    if (ts.isBindingElement(node) && ts.isIdentifier(node.name) && keyText(node.propertyName ?? node.name) === ARM) {
+      armNames.add(node.name.text);
+    }
+    ts.forEachChild(node, collectImportedNames);
+  };
+  collectImportedNames(sourceFile);
+
+  const memberName = (node) => {
+    if (ts.isPropertyAccessExpression(node)) return node.name.text;
+    if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression)) {
+      return node.argumentExpression.text;
+    }
+    return "";
+  };
+  const unwrap = (node) => {
+    while (
+      node &&
+      (ts.isParenthesizedExpression(node) ||
+        ts.isNonNullExpression(node) ||
+        ts.isAsExpression(node) ||
+        ts.isSatisfiesExpression(node) ||
+        ts.isTypeAssertionExpression(node))
+    ) {
+      node = node.expression;
+    }
+    return node;
+  };
+  const isArm = (node) => (ts.isIdentifier(node) && armNames.has(node.text)) || memberName(node) === ARM;
+  const isSetTestMode = (node) =>
+    (ts.isIdentifier(node) && node.text === "setTestMode") || memberName(node) === "setTestMode";
+  const isCallee = (node) => {
+    let parent = node.parent;
+    while (parent && (ts.isParenthesizedExpression(parent) || ts.isNonNullExpression(parent) || ts.isAsExpression(parent))) {
+      parent = parent.parent;
+    }
+    return parent !== undefined && ts.isCallExpression(parent) && unwrap(parent.expression) === node;
+  };
+
+  const inImportEquals = (node) => {
+    let n = node;
+    while (n.parent && ts.isQualifiedName(n.parent)) n = n.parent;
+    return n.parent !== undefined && ts.isImportEqualsDeclaration(n.parent);
+  };
+  // Positions where the name is declared, imported, a key or a type - not a
+  // value that can be called later.
+  const isNamedNotUsed = (node) => {
+    const parent = node.parent;
+    if (!parent) return true;
+    if (ts.isPropertyAccessExpression(parent) && parent.name === node) return true;
+    if (ts.isQualifiedName(parent)) return !inImportEquals(node);
+    if (ts.isExportSpecifier(parent)) return true; // the export itself is judged below, once
+    if (ts.isBindingElement(parent)) return parent.name === node || parent.propertyName === node;
+    if (
+      ts.isImportSpecifier(parent) ||
+      ts.isImportClause(parent) ||
+      ts.isNamespaceImport(parent) ||
+      ts.isTypeQueryNode(parent) ||
+      ts.isImportTypeNode(parent)
+    ) {
+      return true;
+    }
+    if (ts.isFunctionDeclaration(parent) && parent.name === node) {
+      return !parent.modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword);
+    }
+    return (
+      (ts.isFunctionExpression(parent) ||
+        ts.isVariableDeclaration(parent) ||
+        ts.isParameter(parent) ||
+        ts.isPropertyAssignment(parent) ||
+        ts.isMethodDeclaration(parent) ||
+        ts.isMethodSignature(parent) ||
+        ts.isGetAccessorDeclaration(parent) ||
+        ts.isSetAccessorDeclaration(parent) ||
+        ts.isPropertyDeclaration(parent) ||
+        ts.isPropertySignature(parent) ||
+        ts.isEnumMember(parent)) &&
+      parent.name === node
+    );
+  };
+
+  // The helper's first parameter, when node is the runtime copy's own
+  // `function armAllInstances(testMode)` in agent/runtime/agent.ts.
+  const helperParam = (node) => {
+    if (!inRuntimeHelperFile || !ts.isFunctionDeclaration(node) || node.name?.text !== ARM) return undefined;
+    if (node.modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)) return undefined;
+    const first = node.parameters[0];
+    return first && ts.isIdentifier(first.name) ? first.name.text : undefined;
+  };
+
+  const refuse = (node, name) => {
     findings.push(
       finding({
-        rule: "no-unsnapshottable-color",
+        rule: "no-test-mode-in-bundle",
         severity: "error",
         sourceFile,
         node,
         file: relative,
-        message: `${match[1]}() in a card: the panel saves cards to history as an image drawn with html2canvas, which cannot read it - the saved card comes out blank.`,
-        fix: "Use plain hex or rgba. Do not read the app's CSS variables either: on modern apps they resolve to oklch.",
+        message: `\`${name}\` does not belong in agent code: any file in \`agent/\` can ship to production, where test mode would stop real users' conversations being tracked.`,
+        fix: "Remove it. Test mode is only for an agent that already has real users, and only through `npx foldspace attach --test-mode`, which never touches the bundle. For an agent with no real users yet, leave test mode off.",
       }),
     );
-  });
+  };
+
+  const walk = (node, exemptParam) => {
+    if (ts.isCallExpression(node) && isSetTestMode(unwrap(node.expression))) {
+      const [first] = node.arguments;
+      const off = first !== undefined && first.kind === ts.SyntaxKind.FalseKeyword;
+      const helperOwnCall =
+        exemptParam !== undefined && node.arguments.length === 1 && ts.isIdentifier(first) && first.text === exemptParam;
+      if (!off && !helperOwnCall) refuse(node, "setTestMode");
+    } else if (isSetTestMode(node) && !isCallee(node) && !(ts.isIdentifier(node) && isNamedNotUsed(node))) {
+      refuse(node, "setTestMode");
+    }
+    if (ts.isCallExpression(node) && isArm(unwrap(node.expression))) {
+      refuse(node, ARM);
+    } else if (isArm(node)) {
+      if (!isCallee(node) && !(ts.isIdentifier(node) && isNamedNotUsed(node))) refuse(node, ARM);
+    } else if (ts.isExportSpecifier(node)) {
+      const local = keyText(node.propertyName ?? node.name);
+      if (local !== undefined && armNames.has(local) && keyText(node.name) !== ARM) refuse(node, ARM);
+    }
+    const param = exemptParam ?? helperParam(node);
+    ts.forEachChild(node, (child) => walk(child, param));
+  };
+  walk(sourceFile, undefined);
+}
+
+// What the build checks in the bundle it wrote: minify keeps property names,
+// so a bundle that can turn test mode on still says `setTestMode`. Calls with
+// `false` (`!1` once minified) are allowed; any other mention is not - the
+// net under the lint rule above, for code it cannot read (a computed name, a
+// file lint does not walk).
+export function bundleTurnsOnTestMode(js) {
+  return /setTestMode/.test(js.replace(/\??\.setTestMode(\?\.)?\(\s*(!1|false)\s*\)/g, ""));
 }
 
 export function lintActionFile(filePath, relative, findings) {
@@ -482,11 +819,10 @@ export function lintActionFile(filePath, relative, findings) {
   ruleNoStaticAgentPrompt(sourceFile, relative, findings);
   ruleNoRunTaskPrompt(sourceFile, relative, findings);
   ruleNoEmoji(sourceFile, relative, findings);
-  ruleNoUnsnapshottableColor(sourceFile, relative, findings);
+  ruleCardContract(sourceFile, relative, findings);
 }
 
 export function lintViewsFile(filePath, relative, findings) {
   const sourceFile = parseFile(filePath);
   ruleNoEmoji(sourceFile, relative, findings, { wholeFile: true });
-  ruleNoUnsnapshottableColor(sourceFile, relative, findings);
 }