agent-led-growth 0.6.4 → 0.8.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-led-growth",
-  "version": "0.6.4",
+  "version": "0.8.0",
   "description": "Score: evals for agents as customers. Runs a real agent through signup, key and first call on your product, before you ship. Track, the analytics half, measures which agents convert after.",
   "author": {
     "name": "Kat Laszlo",

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.8.0 (2026-10-23)
+
+- `alg connect`: sets up Track's key without copying a secret by hand. It prints a code and opens the browser; once approved it writes `AGENT_TRAFFIC_KEY` (and `AGENT_TRAFFIC_PROJECT_ID`, not a secret) to `.env` or `--env-file`, replacing existing lines for those names and keeping the rest, and creates a new file with mode 0600. It warns when the file is not gitignored in a git repo and offers to add it. In a folder linked to Vercel, or with `--vercel`, it offers to run `vercel env add AGENT_TRAFFIC_KEY production` with the key on stdin. The key is never printed, logged or put on a command line. `--endpoint` or `AGENT_TRAFFIC_ENDPOINT` points it at another Track server, which is then written as `AGENT_TRAFFIC_ENDPOINT`.
+
+## 0.7.0 (2026-10-23)
+
+- `test` no longer stops when `alg.yml` has no `verify_call` and the product has no OpenAPI document. At a terminal it asks for a GET that needs a key (and the header that carries it, default `Authorization: Bearer {key}`), checks the answer, saves it to `alg.yml` and continues the run; Enter with nothing skips the check for that run. Answering "n" to an inferred call asks the same way instead of cancelling. Before, it printed `verify_call_invalid` and left the person to edit the file and start over.
+- `test --skip-verify`: the signup runs and the agent's key is not checked, for CI and products with no API call to prove a key. The result passes when the agent saved a key, and says the key was not checked; `--json` carries `checker.skipped: true`. Without a terminal, `verify_call_invalid` names the flag.
+
 ## 0.6.0 (2026-10-22)
 
 - One name. The command is `alg` (`npx agent-led-growth` still runs it); the config file is `alg.yml` and the run folder `.alg/`. The skills are `alg` and `alg-test`, the plugin `agent-led-growth`. `agent-ready`, `agent-ready.yml` and `.agent-ready/` are gone.

package/README.md

@@ -104,6 +104,14 @@ Add agent traffic to this API: read https://alg.katrinalaszlo.com/SKILL.md and f
 Add agent traffic to this API: read https://alg.katrinalaszlo.com/SKILL.md and follow it.
 ```
 
+To set up the key yourself, run this in your API's folder:
+
+```bash
+npx agent-led-growth connect
+```
+
+It prints a code and opens your browser; approve there, and it writes `AGENT_TRAFFIC_KEY` to `.env` (plus `AGENT_TRAFFIC_PROJECT_ID`, which is not a secret and is optional). Nothing to copy: the key is never printed, logged or put on a command line. If `.env` is not in `.gitignore` it says so and offers to add it. In a folder linked to Vercel (`.vercel/project.json`) it asks whether to also save the key in Vercel production, and passes it to `vercel env add` on stdin. Then restart your server and open `https://alg.katrinalaszlo.com/install` to watch the first event.
+
 ## Full command reference
 
 ### The three steps
@@ -142,7 +150,7 @@ Commit `alg.yml` so CI reuses your answers. `test` needs Claude Code installed a
 
 ### Installed
 
-`npm i -g agent-led-growth`, then `alg check …` and `alg test …`.
+`npm i -g agent-led-growth`, then `alg check …`, `alg test …` and `alg connect`.
 
 ### Flags
 
@@ -163,11 +171,23 @@ Commit `alg.yml` so CI reuses your answers. `test` needs Claude Code installed a
 | --- | --- |
 | `--check` | Show the plan, run nothing. Free. |
 | `--yes` | Skip the confirmation; save an inferred `verify_call` to `alg.yml`. |
+| `--skip-verify` | Test the signup only. The agent's key is not checked, so no `verify_call` is needed. |
 | `--max-budget-usd <n>` | Model-use cap, default 5. Checked after each turn, so a run can end slightly above it. |
 | `--max-turns <n>` | Agent turn budget, default 40. |
 | `--inbox <address>` | An inbox you relay mail from, for products that email a code. Or set `AGENTMAIL_API_KEY` and each run gets its own. |
 | `--json` | `agent-ready/verify@1` (or `verify-plan@1` with `--check`) to stdout. |
 
+`connect`
+
+| Flag | Does |
+| --- | --- |
+| `--endpoint <url>` | Track server. Default `AGENT_TRAFFIC_ENDPOINT`, else `https://alg.katrinalaszlo.com`. |
+| `--env-file <path>` | File to write the key to. Default `.env`. Existing lines for the same names are replaced; the rest of the file is kept. A new file is created readable only by you. |
+| `--vercel` | Also save the key in Vercel production. Asked by default when `.vercel/project.json` exists; without a terminal, only this flag does it. |
+| `--no-vercel` | Do not offer Vercel. |
+
+`connect` exits `0` when the key is saved and `1` when the sign-in is denied or expires.
+
 Exit codes, both commands: `0` done or passed, `1` fixes found or test failed, `2` usage or setup, `3` the site did not answer or the run was inconclusive, `130` cancelled.
 
 ### Cost, accounts and data
@@ -201,7 +221,7 @@ The headline and the seven steps are the same whatever the answers; the answers
 
 ### alg.yml
 
-`check` writes it. `test` reads it, and infers a `verify_call` from your OpenAPI document when there is none: a GET that needs a key and no parameters, preferring `/me`, `/account`, `/user`, `/whoami`. A complete file:
+`check` writes it. `test` reads it, and infers a `verify_call` from your OpenAPI document when there is none: a GET that needs a key and no parameters, preferring `/me`, `/account`, `/user`, `/whoami`. With no OpenAPI document, `test` asks you at the prompt for a GET that needs a key (and the header that carries it), saves it to `alg.yml` and goes on; press Enter with nothing to skip the check for that run. Without a terminal, pass `--skip-verify`. A complete file:
 
 ```yaml
 url: yourproduct.com
@@ -253,4 +273,4 @@ npx agent-led-growth test --json --yes     # creates a real account; ask the dev
 
 Each fix prompt is written for a coding agent: read `files.prompts[0]`, make the change, run its acceptance tests, deploy, run `check` again.
 
-Source and issues: https://github.com/katrinalaszlo/agent-led-growth-cli. MIT.
+Source: https://github.com/katrinalaszlo/score (development) and https://github.com/katrinalaszlo/agent-led-growth-cli (the published build, where issues go). MIT.

package/bin/cli.js

@@ -32,8 +32,10 @@ import { runStandards } from "../src/audit/standards.js";
 import { parseVerifySpec, buildVerifyTask, classify, failedStep, networkFor, describeSpec } from "../src/verify/index.js";
 import { renderVerify, renderPlan, duration } from "../src/verify/render.js";
 import { inferVerifyCall, latestInterface, latestAnswers } from "../src/verify/infer.js";
+import { askVerifyCall } from "../src/verify/wizard.js";
 import { renderPrompt } from "../src/audit/prompts.js";
 import { patternInfo } from "../src/audit/index.js";
+import { connect, resolveEndpoint } from "../src/connect/index.js";
 import { createInterface } from "node:readline/promises";
 import { spawnSync } from "node:child_process";
 
@@ -276,6 +278,7 @@ program
   .alias("verify")
   .description("A real agent (your Claude Code) signs up for and uses your product; a separate checker proves its key. Creates a real account, spends up to $5 of model use, asks first.")
   .option("-y, --yes", "skip the confirmation and save an inferred verify_call to alg.yml")
+  .option("--skip-verify", "test the signup only: the agent's key is not checked, so no verify_call is needed")
   .option("--inbox <address>", "an inbox you will relay mail from into the run's work/inbox/, for products that email a code")
   .option("--max-turns <n>", "agent turn budget", (v) => parseInt(v, 10), 40)
   .option("--max-budget-usd <usd>", "stop the agent once model use passes this many dollars (checked after each turn)", parseBudget, 5)
@@ -289,7 +292,9 @@ program
 Examples:
   alg test --check          check Claude Code and alg.yml, print the plan, run nothing
   alg test                  use url, task and verify_call from alg.yml
-                                    (no verify_call: one is taken from the product's OpenAPI document)
+                                    (no verify_call: one is taken from the product's OpenAPI document,
+                                    or you are asked for one at the prompt)
+  alg test --skip-verify    signup only; the key is not checked
   alg test --yes --json     no confirmation, JSON result (CI)`)
   .exitOverride(usageExit)
   .action(async (input, opts) => {
@@ -311,47 +316,77 @@ Examples:
       const shown = configPath.startsWith(home + sep) ? `~${configPath.slice(home.length)}` : CONFIG_FILE;
       console.error(`  ${style.dim(`Not using ${shown}: it is for ${savedFor || "no product"}.`)}`);
     }
-    const addCallHint = `Add the call that proves an agent's key works to ${CONFIG_FILE}, for example: verify_call: GET https://api.example.com/v1/me`;
+    const addCallHint = `Add the call that proves an agent's key works to ${CONFIG_FILE}, for example: verify_call: GET https://api.example.com/v1/me, or pass --skip-verify to test the signup without checking the key`;
+    const interactive = process.stdin.isTTY && !opts.json;
+    const askOnce = async (question) => {
+      const rl = createInterface({ input: process.stdin, output: process.stderr });
+      const reply = await rl.question(question).catch((err) => {
+        if (err.code === "ABORT_ERR") return "";
+        throw err;
+      });
+      rl.close();
+      return reply;
+    };
     // No verify_call: take one from the product's own OpenAPI document. It is saved only once accepted, by a
-    // person at the prompt or by --yes; otherwise it is used for this run alone.
-    let inferred = null;
-    if (!(config.verify_call || "").trim()) {
+    // person at the prompt or by --yes; otherwise it is used for this run alone. When the docs give none, a person
+    // at the terminal is asked for the call, or can skip the check; without a terminal, --skip-verify does that.
+    let chosen = null;
+    let skipped = Boolean(opts.skipVerify);
+    if (!skipped && !(config.verify_call || "").trim()) {
       const live = !opts.json && Boolean(process.stderr.isTTY);
       if (live) process.stderr.write(`  ${style.dim("Finding a call that proves the agent's key works…")}`);
-      inferred = await inferVerifyCall({ url, version: pkg.version, cwd: process.cwd() });
+      const inferred = await inferVerifyCall({ url, version: pkg.version, cwd: process.cwd() });
       if (live) process.stderr.write("\r\x1b[2K");
-      // For another product's file, the call goes in a file of this product's own, never in that one.
-      if (inferred.error && !useSaved) fail(opts, 2, "verify_call_invalid", `No verify_call for ${host}, and none could be taken from the product's docs: ${inferred.error}.`, `Run "alg check ${host}" in a folder of its own, then add the call that proves an agent's key works to the ${CONFIG_FILE} it writes, for example: verify_call: GET https://api.example.com/v1/me`);
-      if (inferred.error) fail(opts, 2, "verify_call_invalid", `${CONFIG_FILE} has no verify_call, and none could be taken from the product's docs: ${inferred.error}.`, addCallHint);
-      const from = `(from ${inferred.specUrl}${inferred.specVia ? `, linked from ${inferred.specVia}` : ""})`;
-      const willCheck = `Will check with ${inferred.call} on ${inferred.apiHost} (${inferred.headerName}) ${from}.`;
-      const offSiteNote = inferred.offSite ? `\n  This API host is on a different site than ${host}; the key the agent gets is sent there.` : "";
+      if (inferred.error && !interactive) {
+        // For another product's file, the call goes in a file of this product's own, never in that one.
+        if (!useSaved) fail(opts, 2, "verify_call_invalid", `No verify_call for ${host}, and none could be taken from the product's docs: ${inferred.error}.`, `Run "alg check ${host}" in a folder of its own, then add the call that proves an agent's key works to the ${CONFIG_FILE} it writes, for example: verify_call: GET https://api.example.com/v1/me, or pass --skip-verify to test the signup without checking the key`);
+        fail(opts, 2, "verify_call_invalid", `${CONFIG_FILE} has no verify_call, and none could be taken from the product's docs: ${inferred.error}.`, addCallHint);
+      }
       let accepted = Boolean(opts.yes);
-      if (!accepted && process.stdin.isTTY && !opts.json) {
-        const rl = createInterface({ input: process.stdin, output: process.stderr });
-        // A person reads the call and where it came from; the "Will check with" line stays for logs and agents.
-        const ask = `\n  To prove the agent's key works, we'll call your API with it after signup:\n    ${style.bold(inferred.call)}   ${style.dim(`(from ${inferred.specUrl.replace(/^https?:\/\//, "")})`)}${offSiteNote}\n  Use this call? [Y/n] `;
-        const reply = await rl.question(ask).catch((err) => {
-          if (err.code === "ABORT_ERR") return "n";
-          throw err;
-        });
-        rl.close();
-        if (!/^(y(es)?)?$/i.test(reply.trim())) {
-          console.error(`  Cancelled. Nothing saved. To use a different call, add it to ${CONFIG_FILE}, for example: verify_call: GET https://api.example.com/v1/me`);
-          process.exit(130);
+      let typed = false;
+      if (inferred.error) {
+        const answer = await askVerifyCall({ ask: askOnce, say: (l) => console.error(l), url, reason: inferred.error, style });
+        if (answer.skip) skipped = true;
+        else {
+          chosen = { ...answer, source: "typed" };
+          accepted = true;
+          typed = true;
         }
-        accepted = true;
-      } else if (!opts.json) console.error(`\n  ${willCheck}${offSiteNote}`);
-      if (!useSaved) {
+      } else {
+        chosen = { ...inferred, source: "inferred" };
+        const offSiteNote = inferred.offSite ? `\n  This API host is on a different site than ${host}; the key the agent gets is sent there.` : "";
+        if (!accepted && interactive) {
+          // A person reads the call and where it came from; the "Will check with" line stays for logs and agents.
+          const ask = `\n  To prove the agent's key works, we'll call your API with it after signup:\n    ${style.bold(inferred.call)}   ${style.dim(`(from ${inferred.specUrl.replace(/^https?:\/\//, "")})`)}${offSiteNote}\n  Use this call? [Y/n] `;
+          const reply = await askOnce(ask);
+          if (/^(y(es)?)?$/i.test(reply.trim())) accepted = true;
+          else {
+            // Not that one: the person names the call instead, or skips the check.
+            const answer = await askVerifyCall({ ask: askOnce, say: (l) => console.error(l), url, reason: null, style });
+            if (answer.skip) {
+              chosen = null;
+              skipped = true;
+            } else {
+              chosen = { ...answer, source: "typed" };
+              accepted = true;
+              typed = true;
+            }
+          }
+        } else if (!opts.json) console.error(`\n  Will check with ${inferred.call} on ${inferred.apiHost} (${inferred.headerName}) (from ${inferred.specUrl}${inferred.specVia ? `, linked from ${inferred.specVia}` : ""}).${offSiteNote}`);
+      }
+      if (skipped) {
+        if (!opts.json) console.error(`  ${style.dim("Verification skipped: the agent signs up, and its key is not checked.")}`);
+      } else if (!useSaved) {
         if (!opts.json) console.error(`  ${style.dim(`Used for this run only: ${CONFIG_FILE} here is not for ${host}.`)}`);
       } else if (accepted) {
-        writeVerifyCall(configPath, inferred);
-        if (!opts.json) console.error(`  ${style.dim(`Saved to ${CONFIG_FILE}.`)}`);
+        writeVerifyCall(configPath, chosen);
+        if (!opts.json) console.error(`  ${style.dim(`Saved to ${CONFIG_FILE}${typed ? ": the next test uses it without asking" : ""}.`)}`);
       } else if (!opts.json) console.error(`  ${style.dim(`Not saved to ${CONFIG_FILE}; pass --yes or run in a terminal to save it.`)}`);
     }
-    const spec = parseVerifySpec(inferred ? { ...config, verify_call: inferred.call, verify_header: inferred.header } : config);
-    if (spec.error) fail(opts, 2, "verify_call_invalid", spec.error, addCallHint);
-    const checker = { inferred: Boolean(inferred), inferredFrom: inferred ? inferred.specUrl : null, ...(inferred?.specVia ? { inferredVia: inferred.specVia } : {}), ...(inferred ? { apiHost: inferred.apiHost, apiHostOffSite: inferred.offSite } : {}) };
+    if (skipped && !opts.json && opts.skipVerify) console.error(`\n  ${style.dim("Verification skipped (--skip-verify): the agent signs up, and its key is not checked.")}`);
+    const spec = skipped ? null : parseVerifySpec(chosen ? { ...config, verify_call: chosen.call, verify_header: chosen.header } : config);
+    if (spec?.error) fail(opts, 2, "verify_call_invalid", spec.error, addCallHint);
+    const checker = { inferred: chosen?.source === "inferred", inferredFrom: chosen?.source === "inferred" ? chosen.specUrl : null, ...(chosen?.specVia ? { inferredVia: chosen.specVia } : {}), ...(chosen ? { apiHost: chosen.apiHost, apiHostOffSite: chosen.offSite } : {}), ...(skipped ? { skipped: true } : {}) };
     if (opts.check) {
       const claude = opts.executor === "claude-print" ? claudeStatus() : { ok: true, detail: `executor ${opts.executor}` };
       const inbox = process.env.AGENTMAIL_API_KEY ? "AgentMail: a fresh inbox for this run, deleted after" : opts.inbox ? `you relay mail from ${opts.inbox} into work/inbox/` : "none (set AGENTMAIL_API_KEY if the product emails a code or link)";
@@ -361,8 +396,8 @@ Examples:
         target: { url, host },
         task,
         claudeCode: claude,
-        agent: { hosts: networkFor(url, spec), inbox, maxTurns: opts.maxTurns, maxBudgetUsd: opts.maxBudgetUsd, saves: ["AGENT_READY_KEY", ...spec.fields] },
-        checker: { call: describeSpec(spec), calls: ["with the agent's key: must answer " + spec.expect, "with no key: must be refused (400, 401 or 403)", "with a wrong key: must be refused"], ...checker },
+        agent: { hosts: networkFor(url, spec), inbox, maxTurns: opts.maxTurns, maxBudgetUsd: opts.maxBudgetUsd, saves: ["AGENT_READY_KEY", ...(spec ? spec.fields : [])] },
+        checker: { call: describeSpec(spec), calls: spec ? ["with the agent's key: must answer " + spec.expect, "with no key: must be refused (400, 401 or 403)", "with a wrong key: must be refused"] : ["none: a key the agent saves counts, unchecked"], ...checker },
       };
       // The onboarding pattern chosen in alg.yml, as the last check's interface.json describes it.
       const onboarding = latestInterface(process.cwd(), url)?.doc.onboarding;
@@ -435,6 +470,46 @@ Examples:
     process.exitCode = verdict.exitCode;
   });
 
+program
+  .command("connect")
+  .description("Connect this app to Track: approve in the browser, and the key is written to .env for you (and to Vercel if you say yes). The key is never printed.")
+  .option("--endpoint <url>", "Track server (default: AGENT_TRAFFIC_ENDPOINT, else https://alg.katrinalaszlo.com)")
+  .option("--env-file <path>", "env file to write the key to", ".env")
+  .option("--vercel", "also save the key in Vercel production (asked by default when .vercel/project.json exists)")
+  .option("--no-vercel", "do not offer to save the key in Vercel")
+  .option("--no-color", "plain output")
+  .addHelpText("after", `
+Examples:
+  alg connect                         sign in, write AGENT_TRAFFIC_KEY to .env
+  alg connect --env-file .env.local   write it to another file
+  alg connect --no-vercel             skip the Vercel question`)
+  .exitOverride(usageExit)
+  .action(async (opts) => {
+    const endpoint = resolveEndpoint(opts.endpoint, process.env);
+    if (!/^https?:\/\/[^/]+/.test(endpoint)) fail(opts, 2, "invalid_address", `"${endpoint}" is not a web address.`, "Try: alg connect --endpoint https://alg.katrinalaszlo.com");
+    const style = makeStyle(Boolean(process.stderr.isTTY) && opts.color && !process.env.NO_COLOR);
+    const ask = async (question) => {
+      const rl = createInterface({ input: process.stdin, output: process.stderr });
+      const reply = await rl.question(question).catch((err) => {
+        if (err.code === "ABORT_ERR") return "n";
+        throw err;
+      });
+      rl.close();
+      return reply;
+    };
+    process.exitCode = await connect({
+      endpoint,
+      envFile: resolve(opts.envFile),
+      vercel: opts.vercel,
+      cwd: process.cwd(),
+      interactive: Boolean(process.stdin.isTTY),
+      sleep: (ms) => new Promise((done) => setTimeout(done, ms)),
+      ask,
+      say: (line) => console.error(line),
+      style,
+    });
+  });
+
 // 0.3 kept a Tanso workspace for verify runs. check and test need no Tanso account now; these
 // commands stay so scripts written for 0.3 get a clear answer instead of "unknown command".
 for (const name of ["account", "login", "logout"]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-led-growth",
-  "version": "0.6.4",
+  "version": "0.8.0",
   "description": "Score: evals for agents as customers. Runs a real agent through signup, key and first call on your product, before you ship. Track, the analytics half, measures which agents convert after.",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
     "bin/cli.js",
     "src/index.js",
     "src/audit/",
+    "src/connect/",
     "src/dashboard/strip.js",
     "src/crash/",
     "src/harness/",

package/skills/alg-test/SKILL.md

@@ -14,7 +14,7 @@ A run creates a real account on the product and uses the developer's Claude Code
 
 `test` reads `alg.yml` in the current directory. If it is missing, run `npx agent-led-growth check <url> --json --yes` first, which writes it.
 
-With no `verify_call`, `test` infers one from the product's OpenAPI document: a GET that needs a key (bearer, or an API key header) and has no required parameters, preferring `/me`, `/account`, `/user` or `/whoami`, on the document's first server. An API key in the `Authorization` header gets the prefix the document gives (`Authorization: Token {key}` when it says "Prefix your key with 'Token '"); with no documented prefix that call is skipped. The plan shows the call's API host (`checker.apiHost`) and, when it is on a different site than the product (`checker.apiHostOffSite`), says the key the agent gets is sent there. Tell the developer which host the key goes to. When the product's own OpenAPI document has none, it tries the OpenAPI documents its `llms.txt`, `auth.md` and other agent files link to on the same registrable domain (such as `app.` or `api.` hosts). It reuses the latest `.alg/<host>/*/interface.json` from `check`, or reads the public pages again. `--yes` accepts the call and saves it to `alg.yml`; without `--yes` and without a terminal it is used for that run and not saved. With `--json`, the plan and the result carry `checker.inferred: true` and `checker.inferredFrom`, and `checker.inferredVia` (the page that linked the document) when it came from a link. Show the developer the inferred call before a real run. When nothing fits, `test` exits `2` with `verify_call_invalid`; then add the call yourself.
+With no `verify_call`, `test` infers one from the product's OpenAPI document: a GET that needs a key (bearer, or an API key header) and has no required parameters, preferring `/me`, `/account`, `/user` or `/whoami`, on the document's first server. An API key in the `Authorization` header gets the prefix the document gives (`Authorization: Token {key}` when it says "Prefix your key with 'Token '"); with no documented prefix that call is skipped. The plan shows the call's API host (`checker.apiHost`) and, when it is on a different site than the product (`checker.apiHostOffSite`), says the key the agent gets is sent there. Tell the developer which host the key goes to. When the product's own OpenAPI document has none, it tries the OpenAPI documents its `llms.txt`, `auth.md` and other agent files link to on the same registrable domain (such as `app.` or `api.` hosts). It reuses the latest `.alg/<host>/*/interface.json` from `check`, or reads the public pages again. `--yes` accepts the call and saves it to `alg.yml`; without `--yes` and without a terminal it is used for that run and not saved. With `--json`, the plan and the result carry `checker.inferred: true` and `checker.inferredFrom`, and `checker.inferredVia` (the page that linked the document) when it came from a link. Show the developer the inferred call before a real run. When nothing fits and a person is at the terminal, `test` asks for the call (a GET that needs a key, then the header that carries it), saves it to `alg.yml` and goes on; Enter with nothing skips the check for that run, and the result says the key was not checked (`checker.skipped: true`). Without a terminal, or with `--json`, it exits `2` with `verify_call_invalid`; pass `--skip-verify` to run the signup without checking the key, or add the call to `alg.yml`.
 
 To choose the call, add it. Pick an authenticated read from the product's own API docs that refuses a request without a key:
 
@@ -63,7 +63,7 @@ The JSON is `agent-ready/verify@1`. Report `outcome`, `reason`, each entry in `c
 | --- | --- | --- |
 | `0` | `passed` or `handoff` | The key works and no key and a wrong key were refused; or the agent correctly stopped where the onboarding model says a person sets access up first. |
 | `1` | `failed` | The agent got no key, or the checker's calls did not pass. `prompt` names a fix prompt in the run folder. |
-| `2` | | Usage or setup: no `verify_call` and none could be inferred, or Claude Code missing or signed out. |
+| `2` | | Usage or setup: no `verify_call` and none could be inferred (without a terminal; `--skip-verify` runs the signup anyway), or Claude Code missing or signed out. |
 | `3` | `inconclusive` | Not a result about the product: server errors, a call that answers without a key, the agent could not connect, the spending cap, or a run that did not finish. Say why and suggest what to change. |
 | `130` | | Cancelled. |
 

package/src/connect/index.js

@@ -0,0 +1,209 @@
+import { existsSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+import { spawnSync } from "node:child_process";
+
+// `alg connect`: a device login against Track. The person approves in the browser, and the key Track returns is
+// written to the env file (and, if they say yes, to Vercel) without ever being printed, logged or put on a command
+// line. Everything that touches the outside (fetch, child processes, the clock, the prompt) is passed in, so tests
+// run it against a fake server.
+
+export const DEFAULT_ENDPOINT = "https://alg.katrinalaszlo.com";
+
+export function resolveEndpoint(flag, env) {
+  return (flag || env.AGENT_TRAFFIC_ENDPOINT || DEFAULT_ENDPOINT).replace(/\/+$/, "");
+}
+
+const defaultRun = (cmd, args, options = {}) => spawnSync(cmd, args, { encoding: "utf8", ...options });
+
+async function postJson(fetchImpl, url, body) {
+  let res;
+  try {
+    res = await fetchImpl(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+  } catch (err) {
+    throw new Error(`Could not reach ${url}: ${err.cause?.message || err.message}`);
+  }
+  // A proxy or a 5xx page can answer in HTML: only a JSON answer is read, and the status alone says what happened.
+  const isJson = (res.headers.get("content-type") || "").includes("json");
+  return { status: res.status, body: isJson ? await res.json() : null };
+}
+
+export async function startDeviceLogin({ endpoint, fetchImpl }) {
+  const res = await postJson(fetchImpl, `${endpoint}/v1/connect/start`, { client: "agent-led-growth" });
+  if (res.status !== 201 || !res.body?.device_code || !res.body?.user_code || !res.body?.verification_url) {
+    throw new Error(`${endpoint} did not start a sign-in (${res.status}${res.body?.error ? ` ${res.body.error}` : ""}).`);
+  }
+  return res.body;
+}
+
+// Polls until the person approves, denies, or the code expires. Returns { ok: true, result } or
+// { ok: false, reason, message }.
+export async function pollForKey({ endpoint, start, fetchImpl, sleep, now }) {
+  let intervalSeconds = Number(start.interval) || 5;
+  const deadline = now() + (Number(start.expires_in) || 600) * 1000;
+  const expired = { ok: false, reason: "expired", message: "The sign-in code expired before it was approved. Run alg connect again." };
+  for (;;) {
+    await sleep(intervalSeconds * 1000);
+    if (now() >= deadline) return expired;
+    const res = await postJson(fetchImpl, `${endpoint}/v1/connect/poll`, { device_code: start.device_code });
+    if (res.status === 202) continue;
+    if (res.status === 429) {
+      intervalSeconds += 2;
+      continue;
+    }
+    if (res.status === 200 && res.body?.key) return { ok: true, result: res.body };
+    if (res.status === 403) return { ok: false, reason: "denied", message: "The sign-in was denied in the browser. Nothing was saved." };
+    if (res.status === 410) return expired;
+    return { ok: false, reason: "unexpected", message: `${endpoint} answered ${res.status}${res.body?.error ? ` ${res.body.error}` : ""} while waiting for approval. Nothing was saved.` };
+  }
+}
+
+// Sets each name in values in the env file: an existing line for that name is replaced in place (a second one is
+// dropped), every other line is kept as it is, and a missing name is added at the end. A new file is created
+// readable only by its owner. Returns { created }.
+export function writeEnvFile(path, values) {
+  const created = !existsSync(path);
+  const lines = created ? [] : readFileSync(path, "utf8").split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  const written = new Set();
+  const out = [];
+  for (const line of lines) {
+    const name = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line)?.[1];
+    if (name && name in values) {
+      if (written.has(name)) continue;
+      out.push(`${name}=${values[name]}`);
+      written.add(name);
+      continue;
+    }
+    out.push(line);
+  }
+  for (const [name, value] of Object.entries(values)) if (!written.has(name)) out.push(`${name}=${value}`);
+  const text = out.join("\n") + "\n";
+  if (created) writeFileSync(path, text, { mode: 0o600 });
+  else writeFileSync(path, text);
+  return { created };
+}
+
+// "ignored", "not_ignored", "no_repo" (not inside a git work tree) or "no_git" (git is not installed).
+export function gitIgnoreStatus(path, run = defaultRun) {
+  const cwd = dirname(path);
+  const inside = run("git", ["rev-parse", "--is-inside-work-tree"], { cwd });
+  if (inside.error) return "no_git";
+  if (inside.status !== 0 || inside.stdout.trim() !== "true") return "no_repo";
+  const check = run("git", ["check-ignore", "-q", basename(path)], { cwd });
+  return check.status === 0 ? "ignored" : "not_ignored";
+}
+
+// Adds the file's name to the .gitignore next to it, creating that .gitignore if there is none.
+export function addToGitignore(path) {
+  const gitignore = join(dirname(path), ".gitignore");
+  const before = existsSync(gitignore) ? readFileSync(gitignore, "utf8") : "";
+  appendFileSync(gitignore, `${before === "" || before.endsWith("\n") ? "" : "\n"}${basename(path)}\n`);
+  return gitignore;
+}
+
+export function openBrowser(url, run = defaultRun, platform = process.platform) {
+  if (platform === "darwin") return run("open", [url]);
+  if (platform === "win32") return run("cmd", ["/c", "start", '""', url.replace(/&/g, "^&")], { windowsVerbatimArguments: true });
+  return run("xdg-open", [url]);
+}
+
+const vercelByHand = "To add it yourself: run vercel env add AGENT_TRAFFIC_KEY production and paste the AGENT_TRAFFIC_KEY value from your env file when asked, or add it in the Vercel dashboard under Settings, Environment Variables.";
+
+// The key goes to the child on stdin only. Child output is shown only on failure, with the key cut out.
+export async function saveKeyInVercel({ key, ask, say, run = defaultRun, cwd }) {
+  const hide = (text) => String(text || "").split(key).join("[key]").trim();
+  const version = run("vercel", ["--version"], { cwd });
+  if (version.error) {
+    say("  The vercel command was not found, so the key was not saved in Vercel.");
+    say(`  ${vercelByHand}`);
+    return "vercel_missing";
+  }
+  const list = run("vercel", ["env", "ls", "production"], { cwd });
+  if (list.status !== 0) {
+    say(`  vercel env ls failed, so the key was not saved in Vercel: ${hide(list.stderr) || `exit ${list.status}`}`);
+    say(`  ${vercelByHand}`);
+    return "failed";
+  }
+  if (/(^|\s)AGENT_TRAFFIC_KEY(\s|$)/m.test(list.stdout)) {
+    const reply = await ask("  AGENT_TRAFFIC_KEY is already set in Vercel production. Replace it? (Y/n) ");
+    if (!/^(y(es)?)?$/i.test(reply.trim())) {
+      say("  Kept the existing AGENT_TRAFFIC_KEY in Vercel production.");
+      return "kept";
+    }
+    const removed = run("vercel", ["env", "rm", "AGENT_TRAFFIC_KEY", "production", "--yes"], { cwd });
+    if (removed.status !== 0) {
+      say(`  vercel env rm failed, so the key was not replaced in Vercel: ${hide(removed.stderr) || `exit ${removed.status}`}`);
+      say(`  ${vercelByHand}`);
+      return "failed";
+    }
+  }
+  const added = run("vercel", ["env", "add", "AGENT_TRAFFIC_KEY", "production"], { cwd, input: key });
+  if (added.status !== 0) {
+    say(`  vercel env add failed, so the key was not saved in Vercel: ${hide(added.stderr) || `exit ${added.status}`}`);
+    say(`  ${vercelByHand}`);
+    return "failed";
+  }
+  say("  Saved AGENT_TRAFFIC_KEY in Vercel production. It takes effect on the next deploy.");
+  return "saved";
+}
+
+// Runs the whole flow and returns the exit code: 0 connected, 1 denied, expired or failed.
+export async function connect({ endpoint, envFile, vercel, cwd, interactive, fetchImpl = fetch, sleep, now = Date.now, run = defaultRun, ask, say, style }) {
+  const bold = style?.bold || ((s) => s);
+  const dim = style?.dim || ((s) => s);
+  say("");
+  say(`  ${bold("alg connect")} · ${new URL(endpoint).host}`);
+  const start = await startDeviceLogin({ endpoint, fetchImpl });
+  say("");
+  say(`  Your code: ${bold(start.user_code)}`);
+  const opened = openBrowser(start.verification_url, run);
+  if (opened.error || opened.status) say(`  Open ${start.verification_url} in your browser.`);
+  else say(`  Opened ${start.verification_url} in your browser.`);
+  say(`  Check the code there matches, then approve. ${dim("Waiting…")}`);
+
+  const polled = await pollForKey({ endpoint, start, fetchImpl, sleep, now });
+  if (!polled.ok) {
+    say("");
+    say(`  ${polled.message}`);
+    return 1;
+  }
+  const { key, project_id: projectId, project_name: projectName } = polled.result;
+  const trackEndpoint = (polled.result.endpoint || endpoint).replace(/\/+$/, "");
+
+  const values = { AGENT_TRAFFIC_KEY: key };
+  if (projectId) values.AGENT_TRAFFIC_PROJECT_ID = projectId;
+  // The middleware sends to the default host unless told otherwise.
+  if (trackEndpoint !== DEFAULT_ENDPOINT) values.AGENT_TRAFFIC_ENDPOINT = trackEndpoint;
+  const { created } = writeEnvFile(envFile, values);
+  const shown = relative(cwd, envFile).startsWith("..") ? envFile : relative(cwd, envFile);
+  say("");
+  say(`  Connected to ${bold(projectName || projectId || "your Track project")}.`);
+  say(`  Saved ${Object.keys(values).join(", ")} to ${shown}${created ? " (new file, readable only by you)" : ""}.`);
+
+  const ignored = gitIgnoreStatus(envFile, run);
+  if (ignored === "not_ignored") {
+    say(`  ${shown} is not in .gitignore, so git would commit the key.`);
+    const reply = interactive ? await ask(`  Add ${basename(envFile)} to .gitignore? (Y/n) `) : "n";
+    if (/^(y(es)?)?$/i.test(reply.trim())) {
+      const gitignore = addToGitignore(envFile);
+      say(`  Added ${basename(envFile)} to ${relative(cwd, gitignore).startsWith("..") ? gitignore : relative(cwd, gitignore)}.`);
+    } else say(`  Add ${basename(envFile)} to .gitignore before you commit.`);
+  } else if (ignored === "no_git") say(`  ${dim("git was not found, so .gitignore was not checked.")}`);
+
+  const linked = existsSync(join(cwd, ".vercel", "project.json"));
+  if (vercel === true || (vercel !== false && linked)) {
+    say("");
+    if (interactive) {
+      const reply = await ask("  Also save the key in Vercel production? (Y/n) ");
+      if (/^(y(es)?)?$/i.test(reply.trim())) await saveKeyInVercel({ key, ask, say, run, cwd });
+      else say("  Not saved in Vercel.");
+    } else if (vercel === true) {
+      await saveKeyInVercel({ key, ask: async () => "y", say, run, cwd });
+    } else say(`  ${dim("This folder is linked to Vercel. Run alg connect --vercel to save the key there too.")}`);
+  }
+
+  say("");
+  say(`  Next: restart your server, then open ${trackEndpoint}/install to watch the first event.`);
+  say("");
+  return 0;
+}

package/src/verify/index.js

@@ -54,7 +54,9 @@ export function parseVerifySpec(config) {
   return { method: (match[1] || "GET").toUpperCase(), url: match[2], body: config.verify_body || null, header: { name: header.slice(0, colon).trim(), template: header.slice(colon + 1).trim() }, expect, assert, fields, exchange, hosts, cli: registries };
 }
 
+// spec is null when verification was skipped: the agent signs up, and its key is not checked.
 export function describeSpec(spec) {
+  if (!spec) return "none: verification skipped, the agent's key is not checked";
   const assertion = spec.assert ? (spec.assert.equals === null ? `, ${spec.assert.path} present` : `, ${spec.assert.path} = ${spec.assert.equals}`) : "";
   const first = spec.exchange ? `${spec.exchange.method} ${spec.exchange.url} for a token (${spec.exchange.tokenPath}), then ` : "";
   return `${first}${spec.method} ${spec.url} with ${spec.header.name}: ${spec.header.template}; expect ${spec.expect}${assertion}`;
@@ -155,23 +157,30 @@ export async function checkKey(spec, key, { fetchImpl = fetch, fields = {} } = {
 export function networkFor(targetUrl, spec) {
   const host = new URL(targetUrl).hostname;
   const apex = registrableDomain(host);
-  const hosts = [host, apex, ...PRODUCT_SUBDOMAINS.map((s) => `${s}.${apex}`), new URL(spec.url.replace(/\{[^}]+\}/g, "x")).hostname, ...(spec.exchange ? [new URL(spec.exchange.url.replace(/\{[^}]+\}/g, "x")).hostname] : []), ...(spec.hosts || [])];
+  const hosts = [host, apex, ...PRODUCT_SUBDOMAINS.map((s) => `${s}.${apex}`)];
+  if (spec) hosts.push(new URL(spec.url.replace(/\{[^}]+\}/g, "x")).hostname, ...(spec.exchange ? [new URL(spec.exchange.url.replace(/\{[^}]+\}/g, "x")).hostname] : []), ...(spec.hosts || []));
   return [...new Set(hosts)];
 }
 
+// With no spec the check is skipped: a key the agent saved counts, and the result says it was not checked.
+async function skippedCheck() {
+  const checks = [{ id: "key_works", label: "Key works", pass: null, detail: "not checked: verification skipped (no verify_call)" }];
+  return { ok: true, status: 0, detail: checks[0].detail, objects: { checks, checkerInvalid: false, skipped: true } };
+}
+
 export function buildVerifyTask({ url, task, spec, fetchImpl = fetch }) {
   const host = new URL(url).hostname;
   return defineSignupTask({
     id: "verify",
     name: host,
     url,
-    apiHost: new URL(spec.url.replace(/\{[^}]+\}/g, "x")).hostname,
+    apiHost: spec ? new URL(spec.url.replace(/\{[^}]+\}/g, "x")).hostname : host,
     network: networkFor(url, spec),
     credentialEnvName: KEY_ENV,
-    extraFields: spec.fields,
+    extraFields: spec ? spec.fields : [],
     keyPattern: /^\S{8,}$/,
     taskText: `${task}. The product is ${host}.`,
-    verify: { describe: describeSpec(spec), call: (key, runId, fields) => checkKey(spec, key, { fetchImpl, fields }) },
+    verify: { describe: describeSpec(spec), call: spec ? (key, runId, fields) => checkKey(spec, key, { fetchImpl, fields }) : skippedCheck },
   });
 }
 
@@ -184,6 +193,7 @@ const REPORTED_5XX = /\b(?:HTTP\s*(?:status)?|status(?:\s*code)?)\W{0,4}5\d\d\b|
 export function classify(result, onboarding, resultMd = "") {
   const evaluation = result.evaluation || {};
   const stages = result.reconciled?.stages || [];
+  if (evaluation.success && evaluation.objects?.skipped) return { outcome: "passed", exitCode: 0, reason: "A real agent got its own key. The key was not checked: verification was skipped. Add verify_call to alg.yml to prove it works." };
   if (evaluation.success) return { outcome: "passed", exitCode: 0, reason: "A real agent got its own key and the checker confirmed it works." };
   if (evaluation.objects?.checkerInvalid) return { outcome: "inconclusive", exitCode: 3, reason: "The verify call answers without a key, so it cannot prove the agent's key works. Pick a call that needs authentication." };
   if (stages.some((s) => s.agent?.outcome === "product_unavailable")) return { outcome: "inconclusive", exitCode: 3, reason: "The product returned server errors during the run. Try again later." };

package/src/verify/wizard.js

@@ -0,0 +1,41 @@
+import { parseVerifySpec } from "./index.js";
+import { sameSite } from "../interface/sources.js";
+
+// `test` found no verify_call in alg.yml and none in the product's docs. Instead of stopping, it asks the person
+// at the terminal for the call, or lets them skip the check. ask(question) returns the typed line; say(line)
+// prints one. Returns { call, header, apiHost, offSite } for a call, or { skip: true }.
+
+export const EXAMPLE_CALL = "GET https://api.example.com/v1/me";
+export const DEFAULT_HEADER = "Authorization: Bearer {key}";
+
+export async function askVerifyCall({ ask, say, url, reason, style }) {
+  const dim = style?.dim || ((s) => s);
+  const bold = style?.bold || ((s) => s);
+  say("");
+  say(`  We couldn't find an OpenAPI spec to figure out how to test your API key${reason ? ` ${dim(`(${reason})`)}` : ""}.`);
+  say("  What's a simple GET endpoint we can use to verify the key works?");
+  say(`  ${dim(`e.g. ${EXAMPLE_CALL}. Press Enter with nothing to skip verification: the agent signs up, and its key is not checked.`)}`);
+  let spec;
+  for (;;) {
+    const reply = (await ask("  Call: ")).trim();
+    if (!reply || /^skip$/i.test(reply)) return { skip: true };
+    spec = parseVerifySpec({ verify_call: reply });
+    if (!spec.error) break;
+    say(`  ${spec.error.replace(/^alg\.yml has no verify_call\. /, "")}`);
+  }
+  const call = `${spec.method} ${spec.url}`;
+  let header;
+  for (;;) {
+    const reply = (await ask(`  Header that carries the key ${dim(`[${DEFAULT_HEADER}]`)}: `)).trim() || DEFAULT_HEADER;
+    const withHeader = parseVerifySpec({ verify_call: call, verify_header: reply });
+    if (!withHeader.error) {
+      header = reply;
+      break;
+    }
+    say(`  ${withHeader.error}`);
+  }
+  const apiHost = new URL(spec.url.replace(/\{[^}]+\}/g, "x")).hostname;
+  const offSite = !sameSite(spec.url, url);
+  say(`  ${dim("Will check with")} ${bold(call)} ${dim(`(${header})`)}`);
+  return { call, header, apiHost, offSite };
+}