start-command 0.39.2 → 0.41.0

package/src/lib/formal-ai.js

@@ -0,0 +1,329 @@
+/**
+ * The task loop of the experimental `--use-formal-ai` mode (issue #255).
+ *
+ * The natural-language request goes to Formal AI verbatim. Formal AI decides
+ * what to observe and which tool calls to make; start checks every call
+ * against the effect policy, runs approved calls, reports each receipt back
+ * 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.
+ */
+
+const policy = require('./formal-ai-policy');
+const { formatToolResult, runTool } = require('./formal-ai-tool');
+
+const { EXIT } = policy;
+const PREVIEW_CHARS = 2000;
+const SIGNAL_EXIT = { SIGINT: 130, SIGTERM: 143, SIGHUP: 129 };
+
+function preview(text) {
+  return text.length > PREVIEW_CHARS
+    ? `${text.slice(0, PREVIEW_CHARS)}… [${text.length - PREVIEW_CHARS} more chars]`
+    : text;
+}
+
+/** Observed working-directory changes, in words. */
+function describeEffects(effects) {
+  const parts = ['added', 'removed', 'changed']
+    .filter((key) => effects[key].length)
+    .map((key) => {
+      const names = effects[key];
+      const more = names.length > 10 ? ` and ${names.length - 10} more` : '';
+      return `${key} ${names.slice(0, 10).join(', ')}${more}`;
+    });
+  const text = parts.length ? parts.join('; ') : 'no file changed';
+  return effects.complete ? text : `${text} (fingerprint incomplete)`;
+}
+
+/**
+ * Run one request to completion.
+ * @param {object} options
+ * @param {string} options.request - Natural-language request, never executed
+ * @param {string} options.cwd - Working directory of the tools
+ * @param {object} options.env - Tool environment
+ * @param {object} options.bounds - policy.resolveBounds() result
+ * @param {object} options.client - formal-ai-client createClient() result
+ * @param {object} [options.io] - {stdout, stderr, note(text)} mirrors
+ * @param {AbortSignal} [options.signal] - Cancellation
+ * @param {object} [options.evidence] - Evidence object to fill (for crash-safe writes)
+ * @returns {Promise<object>} Evidence with `outcome`
+ */
+async function runFormalAiTask(options) {
+  const { request, cwd, env, bounds, client, signal = null } = options;
+  const io = options.io || {};
+  const note = io.note || (() => {});
+  const deadline = options.deadline || Date.now() + bounds.timeoutMs;
+  const evidence = options.evidence || {};
+  Object.assign(evidence, {
+    request,
+    cwd,
+    effectsMode: bounds.effects,
+    bounds: { ...bounds },
+    steps: [],
+    effects: { added: [], removed: [], changed: [], complete: true },
+    outcome: null,
+  });
+  const context = {
+    cwd,
+    effects: bounds.effects,
+    observed: new Set(),
+    observedDirs: new Set(),
+  };
+  const finish = (status, exitCode, message, remaining = []) => {
+    evidence.outcome = {
+      status,
+      exitCode,
+      message,
+      remainingObligations: remaining,
+    };
+    return evidence;
+  };
+  const cancelled = () =>
+    finish(
+      'cancelled',
+      SIGNAL_EXIT[signal && signal.reason] || 130,
+      `cancelled by ${(signal && signal.reason) || 'SIGINT'}`,
+      ['the task was interrupted; later steps did not run']
+    );
+  if (signal) {
+    // Cancellation stops the running tool's whole process group.
+    signal.addEventListener('abort', () => {
+      if (evidence.activeKill) {
+        evidence.activeKill('SIGTERM');
+      }
+    });
+  }
+  const messages = [{ role: 'user', content: request }];
+  let lastExit = null;
+  let toolCalls = 0;
+
+  for (let turn = 1; turn <= bounds.maxSteps; turn++) {
+    if (signal && signal.aborted) {
+      return cancelled();
+    }
+    if (Date.now() >= deadline) {
+      return finish('budget-exhausted', EXIT.BUDGET, 'time budget exhausted', [
+        'the task did not finish within START_FORMAL_AI_TIMEOUT_MS',
+      ]);
+    }
+    let response;
+    try {
+      response = await client.complete(messages, { signal });
+    } catch (error) {
+      if (signal && signal.aborted) {
+        return cancelled();
+      }
+      const status =
+        error.exitCode === EXIT.BUDGET
+          ? 'budget-exhausted'
+          : error.exitCode === EXIT.UNAVAILABLE
+            ? 'unavailable'
+            : 'protocol-error';
+      return finish(status, error.exitCode || EXIT.PROTOCOL, error.message, [
+        'Formal AI did not complete the task',
+      ]);
+    }
+    evidence.steps.push({
+      kind: 'response',
+      turn,
+      finishReason: response.finishReason,
+      handler: response.handler,
+      content: preview(response.content),
+      toolCalls: response.toolCalls.map((c) => c.command),
+    });
+    if (!response.toolCalls.length) {
+      if (response.content) {
+        note(response.content);
+      }
+      if (response.handler === 'unknown' && toolCalls === 0) {
+        return finish(
+          'unsupported',
+          EXIT.UNSUPPORTED,
+          'Formal AI did not understand the request; no tool ran',
+          ['rephrase the request or perform it manually']
+        );
+      }
+      if (lastExit === null) {
+        return finish('answered', 0, 'Formal AI answered without tools');
+      }
+      // The status reports what the tools did, not what Formal AI claims:
+      // a run of reads is never presented as a completed change.
+      const status =
+        lastExit === 0
+          ? `finished after ${toolCalls} tool call(s)`
+          : `finished; the last tool call exited with ${lastExit}`;
+      return finish(
+        'completed',
+        lastExit,
+        `${status}; ${describeEffects(evidence.effects)}`,
+        lastExit === 0 ? [] : ['the last tool call failed']
+      );
+    }
+    messages.push({
+      role: 'assistant',
+      content: response.content,
+      tool_calls: response.toolCalls.map((call, index) => ({
+        id: call.id || `call_${turn}_${index}`,
+        type: 'function',
+        function: {
+          name: call.name,
+          arguments: JSON.stringify({ command: call.command }),
+        },
+      })),
+    });
+    for (const [index, call] of response.toolCalls.entries()) {
+      const callId = messages[messages.length - 1].tool_calls[index].id;
+      toolCalls++;
+      if (toolCalls > bounds.maxSteps) {
+        return finish(
+          'budget-exhausted',
+          EXIT.BUDGET,
+          `tool call budget of ${bounds.maxSteps} exhausted`,
+          ['the task did not finish within START_FORMAL_AI_MAX_STEPS']
+        );
+      }
+      const outcome = await runCall({
+        call,
+        context,
+        cwd,
+        env,
+        bounds,
+        deadline,
+        io,
+        note,
+        evidence,
+      });
+      if (signal && signal.aborted) {
+        return cancelled();
+      }
+      if (outcome.stop) {
+        return finish(...outcome.stop);
+      }
+      lastExit = outcome.exitCode;
+      messages.push({
+        role: 'tool',
+        tool_call_id: callId,
+        content: outcome.result,
+      });
+    }
+  }
+  return finish(
+    'budget-exhausted',
+    EXIT.BUDGET,
+    `step budget of ${bounds.maxSteps} exhausted`,
+    ['the task did not finish within START_FORMAL_AI_MAX_STEPS']
+  );
+}
+
+async function runCall({
+  call,
+  context,
+  cwd,
+  env,
+  bounds,
+  deadline,
+  io,
+  note,
+  evidence,
+}) {
+  const decision = policy.evaluateCommand(call.command, context);
+  const step = { kind: 'tool', command: call.command, argv: decision.tokens };
+  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'],
+      ],
+    };
+  }
+  step.decision = 'allowed';
+  step.effect = decision.kind;
+  note(`$ ${call.command}`);
+  const before = policy.fingerprint(cwd, bounds.maxFingerprintEntries);
+  const receipt = await runTool({
+    argv: decision.tokens,
+    cwd,
+    env,
+    timeoutMs: Math.max(
+      1,
+      Math.min(bounds.toolTimeoutMs, deadline - Date.now())
+    ),
+    maxOutputBytes: bounds.maxOutputBytes,
+    stdout: io.stdout,
+    stderr: io.stderr,
+    onSpawn: (kill) => {
+      evidence.activeKill = kill;
+    },
+  });
+  delete evidence.activeKill;
+  const diff = policy.diffFingerprints(
+    before,
+    policy.fingerprint(cwd, bounds.maxFingerprintEntries)
+  );
+  Object.assign(step, {
+    exitCode: receipt.exitCode,
+    signal: receipt.signal,
+    timedOut: receipt.timedOut,
+    durationMs: receipt.durationMs,
+    truncated: receipt.truncated,
+    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;
+  if (receipt.truncated) {
+    note(
+      `output truncated at START_FORMAL_AI_MAX_OUTPUT_BYTES=${bounds.maxOutputBytes}`
+    );
+  }
+  if (receipt.timedOut) {
+    return {
+      stop: [
+        'budget-exhausted',
+        EXIT.BUDGET,
+        `\`${call.command}\` exceeded the tool time limit and was stopped`,
+        ['the stopped call may have done part of its work'],
+      ],
+    };
+  }
+  if (decision.kind === 'read') {
+    policy.recordObservation(decision, context);
+    if (policy.hasEffects(diff)) {
+      step.unexpectedEffects = true;
+      note(
+        `warning: the working directory changed during a read-only call (${[...diff.added, ...diff.removed, ...diff.changed].slice(0, 5).join(', ')})`
+      );
+    }
+  } else if (receipt.exitCode === 0) {
+    step.verification = policy.verifyChange(decision.tokens, cwd);
+    if (!step.verification.verified) {
+      return {
+        stop: [
+          'unverified',
+          EXIT.PROTOCOL,
+          `\`${call.command}\` exited 0 but ${step.verification.detail}`,
+          ['the change could not be confirmed by readback'],
+        ],
+      };
+    }
+    for (const target of decision.targets) {
+      context.observed.add(target);
+    }
+  }
+  return {
+    exitCode: receipt.exitCode,
+    result: formatToolResult(receipt, call.command, cwd),
+  };
+}
+
+module.exports = { SIGNAL_EXIT, describeEffects, runFormalAiTask };

package/src/lib/log-sanitizer.js

@@ -8,11 +8,10 @@
  * local gh hosts.yml (--gh-config). It streams the log from stdin, keeps
  * invalid UTF-8 bytes and writes a new private file atomically (--output).
  *
- * One rule stays here: the library masks an unquoted or single-quoted
- * `Authorization: <scheme> <value>` to the end of the line, which drops the
- * rest of a logged one-line JSON prompt (issue #249). The pre-pass below masks
- * only the scheme and its token first; the library keeps values that already
- * start with [REDACTED]. Remove it with sensitive-data-sanitizer#45.
+ * Since 0.12.1 the library masks only the scheme and token of an
+ * `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).
  */
 
 const fs = require('fs');
@@ -27,89 +26,6 @@ const COMMAND = 'sensitive-data-sanitizer';
 const OVERRIDE = 'START_SENSITIVE_DATA_SANITIZER';
 const OPTIONS = ['--credentials-only', '--env-secrets', '--gh-config'];
 
-// The longest header and scheme prefix is 122 bytes.
-const HOLDBACK = 160;
-const HEADER =
-  /((?:Proxy-)?Authorization[ \t]{0,32}:[ \t]{0,32})(?:Bearer|Basic|Digest|token)[ \t]{1,32}/gi;
-// Shell expressions, placeholders and masked values are not credentials.
-const NOT_A_VALUE = '$<[{';
-
-function isValueByte(code) {
-  return (
-    code > 0x20 &&
-    code !== 0x22 &&
-    code !== 0x27 &&
-    code !== 0x2c &&
-    code !== 0x5c
-  );
-}
-
-function valueEnd(text, start) {
-  let end = start;
-  while (end < text.length && isValueByte(text.charCodeAt(end))) {
-    end++;
-  }
-  return end;
-}
-
-/**
- * Masks `Authorization: <scheme> <token>` as `Authorization: [REDACTED]`.
- * It works on bytes (latin1 maps each byte to one character), so invalid
- * UTF-8 passes through unchanged, and holds at most HOLDBACK pending bytes.
- */
-class AuthorizationHeaderMask {
-  constructor() {
-    this.pending = '';
-    this.inValue = false;
-    this.redactions = 0;
-  }
-
-  push(block, final = false) {
-    const text = this.pending + block.toString('latin1');
-    this.pending = '';
-    let output = '';
-    let offset = 0;
-    if (this.inValue) {
-      offset = valueEnd(text, 0);
-      if (offset === text.length && !final) {
-        return Buffer.alloc(0);
-      }
-      this.inValue = false;
-    }
-    HEADER.lastIndex = offset;
-    let match;
-    while ((match = HEADER.exec(text))) {
-      const valueStart = match.index + match[0].length;
-      if (valueStart === text.length && !final) {
-        output += text.slice(offset, match.index);
-        this.pending = text.slice(match.index);
-        return Buffer.from(output, 'latin1');
-      }
-      if (
-        valueStart === text.length ||
-        !isValueByte(text.charCodeAt(valueStart)) ||
-        NOT_A_VALUE.includes(text[valueStart])
-      ) {
-        continue;
-      }
-      output += text.slice(offset, match.index + match[1].length) + MARKER;
-      this.redactions++;
-      offset = valueEnd(text, valueStart);
-      if (offset === text.length && !final) {
-        this.inValue = true;
-        return Buffer.from(output, 'latin1');
-      }
-      HEADER.lastIndex = offset;
-    }
-    const safeEnd = final
-      ? text.length
-      : Math.max(offset, text.length - HOLDBACK);
-    output += text.slice(offset, safeEnd);
-    this.pending = text.slice(safeEnd);
-    return Buffer.from(output, 'latin1');
-  }
-}
-
 /** Value-free failure: `code` is a fixed ERR_* name, never log content. */
 class SanitizationError extends Error {
   constructor(code, subject = 'Log') {
@@ -195,10 +111,9 @@ function runSanitizer(args, options, subject) {
  * @returns {string}
  */
 function sanitizeText(text, options = {}) {
-  const input = new AuthorizationHeaderMask().push(Buffer.from(text), true);
   const result = runSanitizer(
     ['redact', '-', ...OPTIONS],
-    { ...options, input },
+    { ...options, input: text },
     'Text'
   );
   return result.stdout.toString();
@@ -230,46 +145,6 @@ function countMarkers(filePath) {
   }
 }
 
-function createPrivateFile(filePath) {
-  const descriptor = fs.openSync(filePath, 'wx', 0o600);
-  if (process.platform !== 'win32') {
-    fs.fchmodSync(descriptor, 0o600);
-  }
-  return descriptor;
-}
-
-function maskAuthorizationHeaders(sourcePath, stagePath) {
-  const source = fs.openSync(sourcePath, 'r');
-  let stage;
-  try {
-    if (!fs.fstatSync(source).isFile()) {
-      throw new SanitizationError('ERR_SOURCE');
-    }
-    stage = createPrivateFile(stagePath);
-    const mask = new AuthorizationHeaderMask();
-    const buffer = Buffer.alloc(BLOCK_SIZE);
-    let bytes = 0;
-    for (;;) {
-      const length = fs.readSync(source, buffer, 0, BLOCK_SIZE, null);
-      const output = mask.push(buffer.subarray(0, length), length === 0);
-      if (output.length) {
-        fs.writeSync(stage, output);
-      }
-      if (length === 0) {
-        break;
-      }
-      bytes += length;
-    }
-    fs.fsyncSync(stage);
-    return bytes;
-  } finally {
-    fs.closeSync(source);
-    if (stage !== undefined) {
-      fs.closeSync(stage);
-    }
-  }
-}
-
 /**
  * Create a private sanitized copy of a log. The source is never modified;
  * any failure removes the copy and throws a value-free SanitizationError.
@@ -288,19 +163,25 @@ function sanitizeLogToTemp(sourcePath, options = {}) {
     if (process.platform !== 'win32') {
       fs.chmodSync(directory, 0o700);
     }
-    const stagePath = path.join(directory, 'authorization-masked.log');
     const target = path.join(directory, 'execution.log');
     code = 'ERR_SOURCE';
-    const bytes = maskAuthorizationHeaders(sourcePath, stagePath);
-    code = 'ERR_PRIVATE_FILE';
-    const input = fs.openSync(stagePath, 'r');
+    const input = fs.openSync(sourcePath, 'r');
+    let bytes;
     try {
-      const size = Math.max(1, fs.fstatSync(input).size);
+      const source = fs.fstatSync(input);
+      if (!source.isFile()) {
+        throw new SanitizationError('ERR_SOURCE');
+      }
+      bytes = source.size;
+      const size = Math.max(1, bytes);
+      code = 'ERR_PRIVATE_FILE';
       runSanitizer(
         [
           'redact',
           '-',
           '--stream',
+          // A NUL byte in a terminal transcript must not block the upload.
+          '--allow-binary',
           ...OPTIONS,
           '--max-bytes',
           String(size),
@@ -326,7 +207,6 @@ function sanitizeLogToTemp(sourcePath, options = {}) {
         `Prepared private sanitized log: ${bytes} bytes scanned, ${Math.max(0, redactions)} redactions.`
       );
     }
-    fs.rmSync(stagePath, { force: true });
     return { path: target, cleanup };
   } catch (error) {
     cleanup();
@@ -341,7 +221,6 @@ function sanitizeLogToTemp(sourcePath, options = {}) {
 }
 
 module.exports = {
-  AuthorizationHeaderMask,
   BLOCK_SIZE,
   SanitizationError,
   resolveSanitizerCommand,

package/src/lib/usage.js

@@ -46,6 +46,7 @@ Options:
   --keep-container-on-fail  Remove successful docker containers, keep failed or OOM-killed ones
   --shell <shell>       Shell to use in isolation environments: auto, bash, zsh, sh (default: auto)
   --use-command-stream  Use command-stream library for execution (experimental)
+  --use-formal-ai       Perform a natural-language request through Formal AI (experimental)
   --status <id>         Show status of execution by UUID or session name (--output-format: links-notation|json|text)
   --list                List all tracked executions (--output-format: links-notation|json|text)
   --running             With --list, only report executions that are still running
@@ -103,7 +104,8 @@ Examples:
   $ --rename <uuid> nightly-build          # Address it as nightly-build from now on
   $ -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-command-stream echo "Hello"      # Use command-stream library
+  $ --use-formal-ai -- print list of files in current directory`);
   console.log('');
   console.log('Piping with $:');
   console.log('  echo "hi" | $ agent       # Preferred - pipe TO $ command');

package/test/ci-workflow-invariants.js

@@ -504,6 +504,24 @@ describe('CI workflow invariants', () => {
     assert.match(lint.body, /cargo metadata --locked/);
   });
 
+  it('gates pull requests on every dependency being its latest release', () => {
+    // Obsolete dependencies, sensitive-data-sanitizer among them, stayed in
+    // use unnoticed (issue #253).
+    const jsJobs = parseJobs(readWorkflow('js.yml'));
+    const freshness = jsJobs.find((job) => job.name === 'dependency-freshness');
+    assert.ok(freshness, 'js.yml has no dependency-freshness job');
+    assert.match(
+      freshness.body,
+      /scripts\/check-dependency-freshness\.mjs --lockfiles\n/
+    );
+    const status = jsJobs.find((job) => job.name === 'pipeline-status');
+    assert.ok(parseNeeds(status.body).includes('dependency-freshness'));
+    const lint = parseJobs(readWorkflow('rust.yml')).find(
+      (job) => job.name === 'lint'
+    );
+    assert.match(lint.body, /cargo update --dry-run/);
+  });
+
   it('reports a failed Rust test as a failed test, not low coverage', () => {
     // Without pipefail a failing test reached the threshold check as an empty
     // value: "Coverage % is below the 50% threshold" (issue #234).

package/test/command-stream-log.js

@@ -0,0 +1,85 @@
+/**
+ * Issue #253: command-stream 2.x returns completed `stdout` and `stderr` as
+ * readable stream snapshots instead of strings. `--use-command-stream` must
+ * still write the command's output to its log file.
+ */
+const { describe, it, expect } = require('bun:test');
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { pathToFileURL } = require('url');
+
+const CLI = path.join(__dirname, '../src/bin/cli.js');
+
+describe('--use-command-stream log (#253)', () => {
+  it('loads execution without compatibility and terminal modules', () => {
+    const wrapper = pathToFileURL(
+      path.join(__dirname, '../src/lib/command-stream.js')
+    ).href;
+    const result = spawnSync(
+      'node',
+      [
+        '--input-type=module',
+        '-e',
+        `import { registerHooks } from 'node:module';
+         import assert from 'node:assert/strict';
+         const extras = [];
+         registerHooks({ load(url, context, next) {
+           if (/command-stream\\/src\\/(shelljs|terminal|rust-repl)/.test(url)) extras.push(url);
+           return next(url, context);
+         }});
+         const { default: wrapper } = await import(${JSON.stringify(wrapper)});
+         const core = await wrapper.getCommandStream();
+         assert.equal(typeof core.$, 'function');
+         assert.equal(typeof core.ProcessRunner, 'function');
+         assert.deepEqual(extras, []);`,
+      ],
+      { encoding: 'utf8', timeout: 30000 }
+    );
+    expect(result.error).toBeUndefined();
+    expect(result.stderr).toBe('');
+    expect(result.status).toBe(0);
+  });
+
+  it.skipIf(process.platform === 'win32')(
+    'writes stdout and stderr to the log file',
+    () => {
+      const root = fs.mkdtempSync(path.join(os.tmpdir(), 'start-253-'));
+      try {
+        const result = spawnSync(
+          process.execPath,
+          [
+            CLI,
+            '--use-command-stream',
+            '--',
+            'sh',
+            '-c',
+            'echo out-253; echo err-253 >&2',
+          ],
+          {
+            env: {
+              ...process.env,
+              START_APP_FOLDER: path.join(root, 'app'),
+              START_LOG_DIR: path.join(root, 'logs'),
+              START_DISABLE_AUTO_ISSUE: '1',
+              START_DISABLE_LOG_UPLOAD: '1',
+            },
+            encoding: 'utf8',
+            timeout: 30000,
+          }
+        );
+        expect(result.status).toBe(0);
+        expect(result.stderr).not.toContain('Could not append log file');
+        const logDir = path.join(root, 'logs', 'direct');
+        const [logName] = fs.readdirSync(logDir);
+        const log = fs.readFileSync(path.join(logDir, logName), 'utf8');
+        expect(log).toContain('out-253\n');
+        expect(log).toContain('err-253\n');
+      } finally {
+        fs.rmSync(root, { recursive: true, force: true });
+      }
+    },
+    40000
+  );
+});