start-command 0.41.0 → 0.43.0

package/src/lib/formal-ai-policy.js

@@ -15,9 +15,9 @@ const path = require('path');
 /** Exit statuses of the mode; a finished task keeps its last tool's status. */
 const EXIT = Object.freeze({
   USAGE: 64, // request text or option combination rejected
-  UNSUPPORTED: 65, // Formal AI reported that it did not understand the task
+  UNSUPPORTED: 65, // Formal AI did not understand the task or reported a capability gap
   UNAVAILABLE: 69, // no qualified Formal AI runtime could be resolved
-  PROTOCOL: 70, // malformed response, unknown tool or unverified effect
+  PROTOCOL: 70, // malformed or 5xx response, unknown tool or unverified effect
   REFUSED: 77, // a tool call was refused by the effect policy
   CONFIG: 78, // invalid START_FORMAL_AI_* bound
   BUDGET: 124, // step, tool, time or retry budget exhausted
@@ -39,6 +39,11 @@ const BOUND_DEFAULTS = Object.freeze({
     value: 64 * 1024,
     max: 16 * 1024 * 1024,
   },
+  maxFileBytes: {
+    env: 'START_FORMAL_AI_MAX_FILE_BYTES',
+    value: 1024 * 1024,
+    max: 16 * 1024 * 1024,
+  },
   maxRequestChars: { env: 'START_FORMAL_AI_MAX_REQUEST_CHARS', value: 4096 },
   maxMemoryMb: { env: 'START_FORMAL_AI_MAX_MEMORY_MB', value: 1024 },
   maxFingerprintEntries: {
@@ -265,6 +270,8 @@ function operands(tokens) {
 
 /**
  * Normalized workspace-relative path of an operand, or null outside it.
+ * It uses `/` on every platform, like the fingerprint, so observations,
+ * messages and evidence are the same on Windows.
  * @param {string} cwd - Working directory
  * @param {string} operand - Operand text
  * @returns {string|null}
@@ -275,7 +282,7 @@ function workspacePath(cwd, operand) {
   if (!isInside(root, resolved)) {
     return null;
   }
-  return path.relative(root, resolved) || '.';
+  return path.relative(root, resolved).split(path.sep).join('/') || '.';
 }
 
 /**

package/src/lib/formal-ai.js

@@ -7,10 +7,19 @@
  * and keeps evidence of what actually happened. The run ends when Formal AI
  * gives its final answer, says it did not understand, or a bound, refusal,
  * protocol error or cancellation stops it, and the exit status says which.
+ * A final answer that is a known capability gap (issue #258) is reported as
+ * incomplete with its obligations, never as an answer.
+ *
+ * A failed change stays unresolved until the same typed tool changes the same
+ * target and its readback is verified (issue #261): a later read, a copy over
+ * the file or Formal AI's final answer does not resolve it, and the run then
+ * ends `incomplete` with the original failure and its exit status.
  */
 
 const policy = require('./formal-ai-policy');
 const { formatToolResult, runTool } = require('./formal-ai-tool');
+const files = require('./formal-ai-files');
+const { recognizeCapabilityGap } = require('./formal-ai-client');
 
 const { EXIT } = policy;
 const PREVIEW_CHARS = 2000;
@@ -68,13 +77,24 @@ async function runFormalAiTask(options) {
     effects: bounds.effects,
     observed: new Set(),
     observedDirs: new Set(),
+    contents: new Map(),
   };
-  const finish = (status, exitCode, message, remaining = []) => {
+  // Failed calls whose obligation no later verified call met (#261).
+  const unresolved = [];
+  const finish = (status, exitCode, message, remaining = [], extra = {}) => {
+    const open = unresolved.map(failureObligation);
     evidence.outcome = {
       status,
       exitCode,
       message,
-      remainingObligations: remaining,
+      remainingObligations: [
+        ...remaining,
+        ...open.filter((item) => !remaining.includes(item)),
+      ],
+      ...(unresolved.length
+        ? { failures: unresolved.map((f) => ({ ...f })) }
+        : {}),
+      ...extra,
     };
     return evidence;
   };
@@ -119,9 +139,15 @@ async function runFormalAiTask(options) {
           : error.exitCode === EXIT.UNAVAILABLE
             ? 'unavailable'
             : 'protocol-error';
-      return finish(status, error.exitCode || EXIT.PROTOCOL, error.message, [
-        'Formal AI did not complete the task',
-      ]);
+      // The cause and attempt count of a runtime failure stay in the
+      // evidence (issue #257); they are sanitized and bounded by the client.
+      return finish(
+        status,
+        error.exitCode || EXIT.PROTOCOL,
+        error.message,
+        ['Formal AI did not complete the task'],
+        error.details ? { diagnostics: { ...error.details } } : {}
+      );
     }
     evidence.steps.push({
       kind: 'response',
@@ -135,6 +161,34 @@ async function runFormalAiTask(options) {
       if (response.content) {
         note(response.content);
       }
+      const gap = recognizeCapabilityGap(response.content, messages);
+      if (gap) {
+        return finish(
+          'capability-gap',
+          EXIT.UNSUPPORTED,
+          describeGap(gap, evidence.effects),
+          gapObligations(gap, bounds.effects),
+          { gap }
+        );
+      }
+      if (unresolved.length) {
+        const [first] = unresolved;
+        return finish(
+          'incomplete',
+          first.exitCode || 1,
+          `\`${first.command}\` failed (${first.error}) and no later call resolved it; ${describeEffects(evidence.effects)}`
+        );
+      }
+      const record = unrecognizedGapRecord(response.content, messages);
+      if (record) {
+        return finish(
+          'incomplete',
+          EXIT.UNSUPPORTED,
+          `Formal AI reported ${record.schema}${record.reason ? ` (${record.reason})` : ''}${record.target ? ` for ${record.target}` : ''}${record.clause ? ` for the clause ${JSON.stringify(record.clause)}` : ''}; nothing was verified as done by Formal AI; ${describeEffects(evidence.effects)}`,
+          ['Formal AI did not confirm the requested change'],
+          { gapRecord: record }
+        );
+      }
       if (response.handler === 'unknown' && toolCalls === 0) {
         return finish(
           'unsupported',
@@ -167,7 +221,10 @@ async function runFormalAiTask(options) {
         type: 'function',
         function: {
           name: call.name,
-          arguments: JSON.stringify({ command: call.command }),
+          arguments:
+            call.tool === 'bash'
+              ? JSON.stringify({ command: call.command })
+              : call.arguments,
         },
       })),
     });
@@ -193,6 +250,7 @@ async function runFormalAiTask(options) {
         note,
         evidence,
       });
+      trackFailures(unresolved, evidence.steps[evidence.steps.length - 1]);
       if (signal && signal.aborted) {
         return cancelled();
       }
@@ -215,7 +273,269 @@ async function runFormalAiTask(options) {
   );
 }
 
-async function runCall({
+/**
+ * Keep the failed calls of a run until a later call meets their obligation
+ * (issue #261). A failed edit or write is resolved only by a verified edit or
+ * write of the same target (a write also resolves a failed read of the file
+ * it created); a failed read by a read of the same target; a failed write
+ * command only by the same command succeeding. A copy or move over the target
+ * never counts as the edit.
+ */
+function trackFailures(unresolved, step) {
+  if (!step || step.kind !== 'tool' || step.decision !== 'allowed') {
+    return;
+  }
+  const typed = step.tool !== undefined;
+  const changed = typed && step.tool !== 'read';
+  if (step.exitCode !== 0 && (typed || step.effect === 'write')) {
+    unresolved.push({
+      command: step.command,
+      ...(typed ? { tool: step.tool, target: step.target } : {}),
+      exitCode: step.exitCode ?? 1,
+      error:
+        step.error ||
+        (step.signal
+          ? `stopped by ${step.signal}`
+          : `exited with ${step.exitCode}`),
+    });
+    return;
+  }
+  if (step.exitCode !== 0) {
+    return;
+  }
+  const verified = changed && step.verification && step.verification.verified;
+  for (let index = unresolved.length - 1; index >= 0; index--) {
+    const failure = unresolved[index];
+    const resolved = typed
+      ? failure.target === step.target &&
+        (failure.tool === 'read'
+          ? step.tool === 'read' || verified
+          : verified && (failure.tool === step.tool || step.tool === 'edit'))
+      : failure.tool === undefined && failure.command === step.command;
+    if (resolved) {
+      unresolved.splice(index, 1);
+    }
+  }
+}
+
+function failureObligation(failure) {
+  return `\`${failure.command}\` failed: ${failure.error}`;
+}
+
+/**
+ * A final answer that is exactly one Links Notation record whose record_type
+ * names a gap, as Formal AI's task obligations answer (`obligation_gap`, e.g.
+ * reason `no_artifact_in_clause`): an id line, then `  key "value"` lines.
+ * Returned in the JSON gap shape (schema = record_type, never complete), so
+ * a gap Formal AI states in its own notation is never taken as success, even
+ * when start verified every change it made (#261).
+ * @param {string} text - Trimmed final answer
+ * @returns {object|null} {schema, reason?, clause?, complete: false}
+ */
+function linoGapRecord(text) {
+  const [id, ...lines] = text.split('\n');
+  if (!/^[A-Za-z0-9_]+$/.test(id) || !lines.length) {
+    return null;
+  }
+  const fields = {};
+  for (const line of lines) {
+    const match = /^ {2}([a-z_]+) (?:"([^"]*)"|'([^']*)'|(\S+))$/.exec(line);
+    if (!match || Object.hasOwn(fields, match[1])) {
+      return null;
+    }
+    fields[match[1]] = match[2] ?? match[3] ?? match[4];
+  }
+  if (typeof fields.record_type !== 'string') {
+    return null;
+  }
+  return {
+    schema: fields.record_type,
+    ...(fields.reason ? { reason: fields.reason } : {}),
+    ...(fields.clause ? { clause: fields.clause } : {}),
+    complete: false,
+  };
+}
+
+/**
+ * A final answer that is a JSON record of a gap start does not know: it is
+ * never taken as success, though its schema grants no recognized gap.
+ */
+function unrecognizedGapRecord(content, messages) {
+  let value;
+  try {
+    value = JSON.parse(String(content || '').trim());
+  } catch {
+    value = linoGapRecord(String(content || '').trim());
+  }
+  if (
+    !value ||
+    typeof value !== 'object' ||
+    Array.isArray(value) ||
+    typeof value.schema !== 'string' ||
+    !/gap/i.test(value.schema) ||
+    !(
+      value.verified === false ||
+      value.complete === false ||
+      value.completed === false
+    )
+  ) {
+    return null;
+  }
+  if (files.echoedByTool(String(content).trim(), messages)) {
+    return null;
+  }
+  return {
+    schema: value.schema,
+    ...(typeof value.target === 'string' ? { target: value.target } : {}),
+    ...(typeof value.reason === 'string' ? { reason: value.reason } : {}),
+    ...(typeof value.clause === 'string' ? { clause: value.clause } : {}),
+  };
+}
+
+/**
+ * Capability gap, in words. When tools changed the working directory, the
+ * message keeps what start observed: Formal AI's gap still means the task is
+ * not confirmed, whatever start verified on its own (#261).
+ */
+function describeGap(gap, effects) {
+  const missing = gap.missingCapabilities.length
+    ? `; missing ${gap.missingCapabilities.join(', ')}`
+    : '';
+  const head = `Formal AI reported a capability gap for ${gap.target} (${gap.reason}${missing})`;
+  return effects && policy.hasEffects(effects)
+    ? `${head}; Formal AI did not confirm the task as done; start observed: ${describeEffects(effects)}`
+    : `${head}; nothing was verified as done`;
+}
+
+function gapObligations(gap, effects) {
+  const obligations = [
+    `the requested change to ${gap.target} was not made or not verified`,
+  ];
+  const changes = ['edit', 'write', 'multi_edit'];
+  if (
+    effects !== 'workspace-write' &&
+    gap.missingCapabilities.some((c) => changes.includes(c))
+  ) {
+    obligations.push(
+      'set START_FORMAL_AI_EFFECTS=workspace-write to offer the edit and write tools'
+    );
+  }
+  return obligations;
+}
+
+function runCall(options) {
+  return options.call.tool === 'bash'
+    ? runBashCall(options)
+    : runFileToolCall(options);
+}
+
+/** Record a call's working-directory diff in its step and the run. */
+function recordEffects(step, diff, evidence) {
+  step.effects = diff;
+  for (const key of ['added', 'removed', 'changed']) {
+    evidence.effects[key].push(...diff[key]);
+  }
+  evidence.effects.complete = evidence.effects.complete && diff.complete;
+}
+
+/** A structured read, edit or write call (issue #258). */
+function runFileToolCall({ call, context, cwd, bounds, io, note, evidence }) {
+  const decision = files.evaluateFileCall(call.tool, call.args, context);
+  const step = {
+    kind: 'tool',
+    tool: call.tool,
+    command: call.command,
+    path: call.args.path,
+  };
+  evidence.steps.push(step);
+  if (!decision.allowed) {
+    step.decision = 'refused';
+    step.reason = decision.reason;
+    note(`refused \`${call.command}\`: ${decision.reason}`);
+    return {
+      stop: [
+        'refused',
+        EXIT.REFUSED,
+        `refused \`${call.command}\`: ${decision.reason}`,
+        ['the refused call did not run; nothing after it ran either'],
+      ],
+    };
+  }
+  Object.assign(step, {
+    decision: 'allowed',
+    effect: decision.kind,
+    target: decision.target,
+  });
+  note(call.command);
+  const started = Date.now();
+  const before = policy.fingerprint(cwd, bounds.maxFingerprintEntries);
+  const receipt = files.runFileCall(
+    call.tool,
+    call.args,
+    decision,
+    context,
+    bounds
+  );
+  const diff = policy.diffFingerprints(
+    before,
+    policy.fingerprint(cwd, bounds.maxFingerprintEntries)
+  );
+  Object.assign(step, {
+    exitCode: receipt.exitCode,
+    durationMs: Date.now() - started,
+    ...(receipt.error ? { error: receipt.error } : {}),
+    ...(receipt.bytes !== undefined ? { bytes: receipt.bytes } : {}),
+    ...(receipt.sha256 ? { sha256: receipt.sha256 } : {}),
+    ...(receipt.previousSha256
+      ? { previousSha256: receipt.previousSha256 }
+      : {}),
+    ...(receipt.replacements ? { replacements: receipt.replacements } : {}),
+    ...(receipt.mutation ? { mutation: receipt.mutation } : {}),
+  });
+  recordEffects(step, diff, evidence);
+  if (receipt.error) {
+    note(`${call.tool} failed: ${receipt.error}`);
+  } else if (call.tool === 'read') {
+    mirrorRead(receipt.text, bounds, io, note);
+    if (policy.hasEffects(diff)) {
+      step.unexpectedEffects = true;
+    }
+  } else {
+    step.verification = receipt.verification;
+    if (!receipt.verification.verified) {
+      return {
+        stop: [
+          'unverified',
+          EXIT.PROTOCOL,
+          `\`${call.command}\` ran but ${receipt.verification.detail}`,
+          ['the change could not be confirmed by readback'],
+        ],
+      };
+    }
+    note(receipt.verification.detail);
+  }
+  return {
+    exitCode: receipt.exitCode,
+    result: receipt.result,
+  };
+}
+
+/** Show what a read returned, like the stdout of `cat`, within the output cap. */
+function mirrorRead(text, bounds, io, note) {
+  if (!io.stdout || !text) {
+    return;
+  }
+  const bytes = Buffer.from(text, 'utf8');
+  const shown = bytes.subarray(0, bounds.maxOutputBytes).toString('utf8');
+  io.stdout.write(shown.endsWith('\n') ? shown : `${shown}\n`);
+  if (bytes.length > bounds.maxOutputBytes) {
+    note(
+      `output truncated at START_FORMAL_AI_MAX_OUTPUT_BYTES=${bounds.maxOutputBytes}`
+    );
+  }
+}
+
+async function runBashCall({
   call,
   context,
   cwd,
@@ -275,12 +595,8 @@ async function runCall({
     spawnError: receipt.spawnError,
     stdout: preview(receipt.stdout),
     stderr: preview(receipt.stderr),
-    effects: diff,
   });
-  for (const key of ['added', 'removed', 'changed']) {
-    evidence.effects[key].push(...diff[key]);
-  }
-  evidence.effects.complete = evidence.effects.complete && diff.complete;
+  recordEffects(step, diff, evidence);
   if (receipt.truncated) {
     note(
       `output truncated at START_FORMAL_AI_MAX_OUTPUT_BYTES=${bounds.maxOutputBytes}`

package/src/lib/log-sanitizer.js

@@ -12,6 +12,10 @@
  * `Authorization: <scheme> <value>` header, so a logged one-line JSON prompt
  * keeps the rest of its line (issue #249, sensitive-data-sanitizer#45); the
  * pre-pass that did this here is gone (issue #253).
+ *
+ * The package depends on ^0.14.0, the current release flagged by the
+ * dependency freshness check; the Rust installer and its version check
+ * require the same release (rust/src/lib/log_sanitizer.rs).
  */
 
 const fs = require('fs');

package/src/lib/usage.js

@@ -105,7 +105,9 @@ Examples:
   $ -i docker -d --on-kill-resume 3 --recovery-command 'solve --resume' -- solve
   $ -i docker -d --on-kill-resume 3 --on-kill-resume-delay 30-90 -- cargo test
   $ --use-command-stream echo "Hello"      # Use command-stream library
-  $ --use-formal-ai -- print list of files in current directory`);
+  $ --use-formal-ai -- print list of files in current directory
+  $ --use-formal-ai -- show contents of README.md
+  START_FORMAL_AI_EFFECTS=workspace-write $ --use-formal-ai -- "In a.js, replace «x» with «y»."`);
   console.log('');
   console.log('Piping with $:');
   console.log('  echo "hi" | $ agent       # Preferred - pipe TO $ command');