testronaut 1.3.6 → 1.4.0

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

package/.github/workflows/periapsis-vulnerability-daily.yml

@@ -0,0 +1,58 @@
+name: Periapsis Vulnerability Daily Check
+
+on:
+  schedule:
+    - cron: "0 14 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  security-events: read
+  pull-requests: read
+
+jobs:
+  periapsis-vulnerability:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install periapsis
+        run: npm install -g periapsis
+      - name: Run vulnerability governance check
+        run: periapsis vulnerability check --report
+        env:
+          GITHUB_TOKEN: ${{ secrets.PERIAPSIS_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
+      - name: Upload vulnerability report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: vulnerability-report
+          path: policy/reports/
+          retention-days: 90
+      - name: Send vulnerability notifications
+        run: periapsis vulnerability notify
+        env:
+          GITHUB_TOKEN: ${{ secrets.PERIAPSIS_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
+          PERIAPSIS_SLACK_WEBHOOK: ${{ secrets.PERIAPSIS_SLACK_WEBHOOK }}
+      - name: Read breach count from report
+        id: report
+        run: |
+          REPORT=$(ls policy/reports/vulnerability-report-*.json 2>/dev/null | sort | tail -n1)
+          if [ -z "$REPORT" ]; then
+            echo "breached=0" >> $GITHUB_OUTPUT
+          else
+            BREACHED=$(node -e "const r=JSON.parse(require('fs').readFileSync('$REPORT','utf8')); process.stdout.write(String(r.summary.breached))")
+            echo "breached=$BREACHED" >> $GITHUB_OUTPUT
+            echo "md=${REPORT%.json}.md" >> $GITHUB_OUTPUT
+          fi
+      - name: Send breach notification email
+        if: steps.report.outputs.breached != '0'
+        uses: dawidd6/action-send-mail@v3
+        with:
+          server_address: ${{ secrets.PERIAPSIS_SMTP_HOST }}
+          server_port: ${{ secrets.PERIAPSIS_SMTP_PORT || 587 }}
+          username: ${{ secrets.PERIAPSIS_SMTP_USER }}
+          password: ${{ secrets.PERIAPSIS_SMTP_PASSWORD }}
+          subject: "[${{ github.repository }}] ${{ steps.report.outputs.breached }} vulnerability SLA breach(es) detected"
+          to: ${{ secrets.PERIAPSIS_EMAIL_TO }}
+          from: ${{ secrets.PERIAPSIS_EMAIL_FROM || secrets.PERIAPSIS_SMTP_USER }}
+          body: file://${{ steps.report.outputs.md }}

package/.github/workflows/periapsis-vulnerability-exception-request.yml

@@ -0,0 +1,86 @@
+name: Periapsis Vulnerability Exception Request
+
+on:
+  workflow_dispatch:
+    inputs:
+      repo:
+        description: "Repository, e.g. owner/repo"
+        required: true
+      alertNumber:
+        description: "Dependabot alert number"
+        required: false
+      exceptionType:
+        description: "alert, package, repo_severity, ecosystem"
+        required: true
+      package:
+        description: "Package name"
+        required: false
+      ecosystem:
+        description: "Package ecosystem"
+        required: false
+      dependencyScope:
+        description: "prod, dev, unknown"
+        required: false
+      severities:
+        description: "Comma-separated severities"
+        required: true
+      reason:
+        description: "Reason for exception"
+        required: true
+      acceptedUntil:
+        description: "Expiry date YYYY-MM-DD or ISO datetime"
+        required: true
+      approvedBy:
+        description: "Approver"
+        required: true
+      evidenceRef:
+        description: "Evidence reference"
+        required: true
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  exception-request:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install periapsis
+        run: npm install -g periapsis
+      - name: Add vulnerability exception
+        env:
+          INPUT_REPO: ${{ inputs.repo }}
+          INPUT_ALERT_NUMBER: ${{ inputs.alertNumber }}
+          INPUT_TYPE: ${{ inputs.exceptionType }}
+          INPUT_PACKAGE: ${{ inputs.package }}
+          INPUT_ECOSYSTEM: ${{ inputs.ecosystem }}
+          INPUT_SCOPE: ${{ inputs.dependencyScope }}
+          INPUT_SEVERITIES: ${{ inputs.severities }}
+          INPUT_REASON: ${{ inputs.reason }}
+          INPUT_UNTIL: ${{ inputs.acceptedUntil }}
+          INPUT_APPROVED_BY: ${{ inputs.approvedBy }}
+          INPUT_EVIDENCE: ${{ inputs.evidenceRef }}
+        run: |
+          periapsis vulnerability exceptions add \
+            --non-interactive \
+            --repo "$INPUT_REPO" \
+            --alert-number "$INPUT_ALERT_NUMBER" \
+            --type "$INPUT_TYPE" \
+            ${INPUT_PACKAGE:+--package "$INPUT_PACKAGE"} \
+            ${INPUT_ECOSYSTEM:+--ecosystem "$INPUT_ECOSYSTEM"} \
+            ${INPUT_SCOPE:+--dependency-scope "$INPUT_SCOPE"} \
+            --severities "$INPUT_SEVERITIES" \
+            --reason "$INPUT_REASON" \
+            --accepted-until "$INPUT_UNTIL" \
+            --approved-by "$INPUT_APPROVED_BY" \
+            --evidence-ref "$INPUT_EVIDENCE"
+      - name: Validate vulnerability policy
+        run: periapsis vulnerability validate
+      - name: Create pull request
+        uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: "Add vulnerability SLA exception"
+          title: "Add vulnerability SLA exception"
+          body: "Adds a structured Periapsis vulnerability exception. Review required before merge."
+          branch: "periapsis/vulnerability-exception-request"

package/.github/workflows/periapsis-vulnerability-pr-check.yml

@@ -0,0 +1,23 @@
+name: Periapsis Vulnerability PR Check
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+  security-events: read
+  pull-requests: read
+  checks: write
+
+jobs:
+  periapsis-vulnerability-pr-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install periapsis
+        run: npm install -g periapsis
+      - name: Run vulnerability PR check
+        run: periapsis vulnerability pr-check
+        env:
+          GITHUB_TOKEN: ${{ secrets.PERIAPSIS_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}

package/README.md

@@ -44,6 +44,7 @@ Includes:
 
 ## 📦 Installation
 
+**Global install** (recommended — use `testronaut` directly):
 ```bash
 npm install -g testronaut
 ```
@@ -51,11 +52,17 @@ npm install -g testronaut
 Then initialize your project:
 
 ```bash
-npx testronaut --init
+testronaut --init
 ```
 
 Run the sample mission:
 ```bash
+testronaut welcome.mission.js
+```
+
+**One-off / no install** (use `npx` to run without installing):
+```bash
+npx testronaut --init
 npx testronaut welcome.mission.js
 ```
 
@@ -117,10 +124,10 @@ Choose your preferred LLM at init or via environment variables.
 
 ```bash
 # During init
-npx testronaut --init
+testronaut --init
 
 # Or override anytime
-TESTRONAUT_PROVIDER=gemini TESTRONAUT_MODEL=gemini-2.5-pro npx testronaut
+TESTRONAUT_PROVIDER=gemini TESTRONAUT_MODEL=gemini-2.5-pro testronaut
 ```
 
 Current supported providers:
@@ -138,12 +145,12 @@ More providers coming soon (Anthropic, Mistral, etc.).
 
 Run all missions:
 ```bash
-npx testronaut
+testronaut
 ```
 
 Run a specific mission:
 ```bash
-npx testronaut login.mission.js
+testronaut login.mission.js
 ```
 
 Chain missions together:
@@ -161,12 +168,12 @@ await runMissions({
 
 Use the staging API base URL:
 ```bash
-npx testronaut --dev
+testronaut --dev
 ```
 
 If the staging deployment is protected by Vercel, pass the bypass secret:
 ```bash
-npx testronaut --dev --vercel-bypass=YOUR_SECRET login
+testronaut --dev --vercel-bypass=YOUR_SECRET login
 ```
 
 You can also set the bypass secret via environment variables:
@@ -175,6 +182,63 @@ export VERCEL_AUTOMATION_BYPASS_SECRET=YOUR_SECRET
 # or
 export TESTRONAUT_VERCEL_BYPASS=YOUR_SECRET
 ```
+
+---
+
+## 🔐 Automated MFA Codes
+
+Testronaut can retrieve a stored TOTP MFA code from the Testronaut API during a mission. This uses the `sessionToken` saved by `testronaut login` in the project root `testronaut-config.json`.
+
+The agent will prefer the automated `get_mfa_code` tool when an MFA nickname is known, then fall back to the manual human input tool if the code is unavailable, the entry is missing, the feature is disabled, or the API session cannot access it.
+
+If the nickname is missing or does not match exactly, the tool can call the MFA list endpoint to see available nicknames. It will retry simple case, spacing, or punctuation mismatches, such as `rudy poo` matching `rudy-poo`.
+
+Add a default MFA nickname to `testronaut-config.json`:
+
+```json
+{
+  "sessionToken": "eyJ...",
+  "mfaName": "github-test-mfa"
+}
+```
+
+Or pass the nickname for a single run:
+
+```bash
+testronaut login.mission.js -o mfa=github-test-mfa
+```
+
+Mission text can also name the MFA entry:
+
+```js
+export const loginMission = `
+Log in to GitHub.
+When prompted for MFA, use the MFA nickname github-test-mfa.
+`;
+```
+
+Use staging API endpoints with the same developer flag:
+
+```bash
+testronaut --dev login.mission.js -o mfa=github-test-mfa
+```
+
+To inspect MFA API traffic during a run, enable debug logging:
+
+```bash
+testronaut --debug --dev login.mission.js -o mfa=github-test-mfa
+# or
+TESTRONAUT_API_DEBUG=1 testronaut --dev login.mission.js -o mfa=github-test-mfa
+```
+
+This writes sanitized request and response details to `missions/mission_reports/api-debug.log`, including the resolved endpoint URL, status, content type, response keys, body preview, parsed response shape, and list endpoint nicknames. Session tokens, bypass secrets, and MFA code values are redacted.
+
+Notes:
+- Run `testronaut login` first so `sessionToken` exists.
+- The CLI calls the API host, not the app host.
+- The MFA API feature flag must be enabled.
+- Paid access is required by the API for paid-gated MFA operations. If the API returns a payment or access error, the mission can still ask for a manual code when human input is enabled.
+
 ---
 
 ## 📋 Reports

package/TODO.md

@@ -0,0 +1,15 @@
+# TODO
+
+## Automated MFA Follow-Ups
+
+- [ ] Add an integration smoke test against a local or staging API fixture for `get_mfa_code`.
+- [ ] Add a staging smoke-test checklist that covers `--dev`, `--vercel-bypass`, paid access, free-user fallback, missing nickname, and expired session token behavior.
+- [ ] Consider a dedicated `testronaut mfa list` command to verify session token access and available MFA nicknames before running missions.
+- [ ] Consider a lightweight MFA preflight warning when `--dev` is used without `VERCEL_AUTOMATION_BYPASS_SECRET`, `TESTRONAUT_VERCEL_BYPASS`, or `--vercel-bypass`.
+- [ ] Consider allowing `testronaut mfa list/get` to accept `--api-base` for quick diagnostics against staging, preview, or local API hosts.
+- [ ] Track automated MFA outcomes in reports without storing raw codes.
+- [ ] Add explicit report/log redaction assertions for MFA codes, session tokens, and Vercel bypass secrets.
+- [ ] Decide how long `missions/mission_reports/api-debug.log` should be retained and whether it should rotate, append per run, or be copied into each run report bundle.
+- [ ] Decide whether `-o/--options` should support more structured formats once more run options exist.
+- [ ] Revisit whether `request_human_input` should return the code to the model or fill fields through a dedicated browser action.
+- [ ] Document a troubleshooting matrix for MFA failures: premium required, feature disabled, invalid session, missing nickname, non-JSON/app-shell response, not found, rate limited, and network error.

package/bin/cli.js

@@ -63,6 +63,27 @@ const DEV_API_BASE = 'https://staging.api.testronaut.app';
 
 let args = process.argv.slice(2);
 
+// Detect how the CLI was invoked so help text matches the actual command
+function detectCliName(npmCommand = process.env.npm_command, argv1 = process.argv[1]) {
+  // npx sets npm_command to 'exec'
+  if (npmCommand === 'exec') return 'npx testronaut';
+  // global install: argv[1] is the bin symlink named 'testronaut'
+  if (path.basename(argv1 || '') === 'testronaut') return 'testronaut';
+  return 'npx testronaut';
+}
+
+function isDirectInvocation(argv1 = process.argv[1], moduleUrl = import.meta.url) {
+  if (!argv1) return false;
+  const modulePath = fileURLToPath(moduleUrl);
+  try {
+    return fs.realpathSync(argv1) === fs.realpathSync(modulePath);
+  } catch {
+    return path.resolve(argv1) === path.resolve(modulePath);
+  }
+}
+
+const cliName = detectCliName();
+
 // Look for --dev / --developer / --developer-mode / --staging
 const devFlagIndex = args.findIndex(a =>
   a === '--dev' ||
@@ -76,6 +97,7 @@ if (devFlagIndex >= 0) {
   console.log(`🧪 Developer mode: using ${apiBase}`);
   args.splice(devFlagIndex, 1);
 }
+process.env.TESTRONAUT_API_BASE_EFFECTIVE = apiBase;
 
 function parseVercelBypassArgs(argsList) {
   const nextArgs = [...argsList];
@@ -138,6 +160,56 @@ function parseProviderArgs(argsList) {
   return { provider, args: nextArgs, invalid };
 }
 
+function parseRunOptionsArgs(argsList) {
+  const nextArgs = [...argsList];
+  const options = {};
+  let invalid = false;
+
+  for (let idx = 0; idx < nextArgs.length;) {
+    const rawArg = nextArgs[idx];
+    const isInline =
+      rawArg.startsWith('--options=') ||
+      rawArg.startsWith('--option=') ||
+      rawArg.startsWith('-o=');
+    const isSeparate =
+      rawArg === '--options' ||
+      rawArg === '--option' ||
+      rawArg === '-o';
+
+    if (!isInline && !isSeparate) {
+      idx += 1;
+      continue;
+    }
+
+    const rawValue = isInline
+      ? rawArg.slice(rawArg.indexOf('=') + 1)
+      : nextArgs[idx + 1] && !nextArgs[idx + 1].startsWith('-')
+        ? nextArgs[idx + 1]
+        : '';
+
+    if (!rawValue) {
+      invalid = true;
+      nextArgs.splice(idx, 1);
+      continue;
+    }
+
+    for (const part of rawValue.split(',')) {
+      const [keyRaw, ...valueParts] = part.split('=');
+      const key = String(keyRaw || '').trim();
+      const value = valueParts.join('=').trim();
+      if (!key || !value) {
+        invalid = true;
+        continue;
+      }
+      options[key] = value;
+    }
+
+    nextArgs.splice(idx, isInline ? 1 : 2);
+  }
+
+  return { options, args: nextArgs, invalid };
+}
+
 
 const vercelBypassResult = parseVercelBypassArgs(args);
 if (vercelBypassResult.invalid) {
@@ -234,6 +306,9 @@ export const __test__ = {
   parseVercelBypassArgs,
   createVercelBypassHeader,
   parseProviderArgs,
+  parseRunOptionsArgs,
+  detectCliName,
+  isDirectInvocation,
 };
 
 // Look for --model=<id> or --model <id>
@@ -267,6 +342,20 @@ if (providerOverride) {
   console.log(`🧩 Provider override: ${process.env.TESTRONAUT_PROVIDER}`);
 }
 
+const runOptionsResult = parseRunOptionsArgs(args);
+if (runOptionsResult.invalid) {
+  console.warn('⚠️ Invalid --options value. Use key=value pairs, for example: -o mfa=github-test-mfa');
+}
+args = runOptionsResult.args;
+const cliMfaName =
+  runOptionsResult.options.mfa ||
+  runOptionsResult.options.mfaName ||
+  runOptionsResult.options['mfa-name'];
+if (cliMfaName) {
+  process.env.TESTRONAUT_MFA_NAME = String(cliMfaName).trim();
+  console.log(`🔐 MFA nickname override: ${process.env.TESTRONAUT_MFA_NAME}`);
+}
+
 // Look for --debug / --debug=<bool> / --no-debug
 // Normalize CLI boolean strings into true/false/null for optional flags.
 const parseBool = (v) => {
@@ -436,18 +525,19 @@ const HELP_TEXT = `
 🧑‍🚀 testronaut - Autonomous Agent Mission Runner
 
 Usage:
-  npx testronaut                 Run all missions in the ./missions directory
-  npx testronaut <file>         Run a specific mission file (e.g., login.mission.js)
-  npx testronaut login          Log in and store session token
-  npx testronaut upload         Upload the most recent report JSON
-  npx testronaut serve        Serve & open the most recent HTML report (read-only)
-  npx testronaut view         Alias of 'serve'
+  ${cliName}                 Run all missions in the ./missions directory
+  ${cliName} <file>         Run a specific mission file (e.g., login.mission.js)
+  ${cliName} login          Log in and store session token
+  ${cliName} upload         Upload the most recent report JSON
+  ${cliName} serve        Serve & open the most recent HTML report (read-only)
+  ${cliName} view         Alias of 'serve'
 
 Options:
   --init                    Scaffold project folders and a welcome mission
   --turns=<n>               Override max turns for this run (e.g., --turns=30)
   --debug[=<bool>]          Enable verbose debug logs (or set TESTRONAUT_DEBUG=1)
   --provider=<id>           Override LLM provider for this run (e.g., --provider=openai)
+  -o, --options key=value   Set run options, such as mfa=github-test-mfa
   --dev                     Use the staging API base URL
   --vercel-bypass=<secret>  Send Vercel protection bypass header for protected deployments
   --human-input[=<bool>]    Allow the agent to pause for short verification codes (default: true)
@@ -457,13 +547,14 @@ Options:
   --retry_limit=<n>         Override agent turn retry limits (minimum 1, maximum 10)
 
 Examples:
-  npx testronaut
-  npx testronaut login
-  npx testronaut upload
-  npx testronaut serve
-  npx testronaut --init
+  ${cliName}
+  ${cliName} login
+  ${cliName} upload
+  ${cliName} serve
+  ${cliName} --init
 `;
 
+async function main() {
 if (args.includes('--init')) {
   await initializeTestronautProject();
   await createWelcomeMission();
@@ -494,7 +585,7 @@ Next steps:
   1. Get an API key from your AI provider
   2. Add it to your .env file
   3. Run your first mission:
-       npx testronaut
+       ${cliName}
 
 📚 Docs: https://docs.testronaut.app/docs/guides/cli-auth
   `);
@@ -611,6 +702,18 @@ fs.mkdirSync(outputDir, { recursive: true });
 fs.writeFileSync(`${outputDir}/${runId}.json`, JSON.stringify(report, null, 2));
 generateHtmlReport(report, `${outputDir}/${runId}.html`);
 
+  try {
+    if (!process.env.TN_KEEP_TMP && fs.existsSync(TMP_DIR)) {
+      fs.rmSync(TMP_DIR, { recursive: true, force: true });
+      console.log('🧹 Cleaned up temporary files.');
+    } else {
+      console.log('⚠️ Skipped tmp cleanup (TN_KEEP_TMP set).');
+    }
+  } catch (err) {
+    console.warn(`⚠️ Could not remove tmp folder: ${err.message}`);
+  }
+}
+
 /**
  * Parse a fetch Response safely and return JSON or throw a rich error.
  * @param {Response} res
@@ -1113,13 +1216,6 @@ async function serveLatestReport() {
   await openInBrowser(reportUrl).catch(() => {});
 }
 
-try {
-  if (!process.env.TN_KEEP_TMP && fs.existsSync(TMP_DIR)) {
-    fs.rmSync(TMP_DIR, { recursive: true, force: true });
-    console.log('🧹 Cleaned up temporary files.');
-  } else {
-    console.log('⚠️ Skipped tmp cleanup (TN_KEEP_TMP set).');
-  }
-} catch (err) {
-  console.warn(`⚠️ Could not remove tmp folder: ${err.message}`);
+if (isDirectInvocation()) {
+  await main();
 }

package/core/agent.js

@@ -135,15 +135,28 @@ Use Ground Control as your persistent mission memory about:
 - Any constraints about staying on the correct site.
       `.trim();
 
+      systemContent +=
+        '\n\n' +
+        `
+Verification codes:
+- If the app requires a TOTP/MFA code, first try get_mfa_code when an MFA nickname is known from the mission text, config, or CLI options.
+- Use the returned value promptly. If the app rejects it as expired or invalid, call get_mfa_code once more for a fresh code and retry carefully.
+- Never invent, guess, or reuse placeholder MFA digits. Only enter an MFA value that came from get_mfa_code or request_human_input.
+        `.trim();
+
       if (opts.humanInput?.enabled !== false) {
         systemContent +=
-          '\n\n' +
+          '\n' +
           `
-Human-in-the-loop verification:
-- If the app requires a TOTP, SMS, email, or similar short verification code that you cannot retrieve yourself, call request_human_input.
-- Do not ask for passwords, API keys, or long free-form text with this tool.
-- After receiving the code from the tool result, enter it into the appropriate field and continue the mission.
+- If get_mfa_code returns that MFA is unavailable, not configured, not found, not enabled, or the account lacks access, gracefully fall back to request_human_input when human input is enabled.
+- Use request_human_input for SMS, email, or other short verification codes that cannot be retrieved automatically.
+- Do not ask for passwords, API keys, or long free-form text with request_human_input.
+- After receiving a code from either tool, enter it into the appropriate field and continue the mission.
           `.trim();
+      } else {
+        systemContent +=
+          '\n' +
+          'Human input is disabled for this run. If get_mfa_code cannot provide a usable MFA code, report a graceful FAILURE with the reason.';
       }
 
       if (groundSummary) {