premanmcp 0.5.0 → 0.7.0

package/bin/integrations.js

@@ -0,0 +1,367 @@
+/**
+ * Connect AWS, GitHub and Slack from the terminal.
+ *
+ * Each of these already had a backend that hands back a URL and a way to ask
+ * whether the customer finished. What was missing was anywhere to drive them
+ * except the dashboard, which meant a terminal-first user had to stop, find the
+ * web app, and hunt for three different settings screens before PreMan could
+ * show them anything.
+ *
+ * The shape is the same for all three because the constraint is the same: the
+ * customer's session with AWS, GitHub or Slack lives in their browser, not in
+ * this process. So we ask the backend for a URL, open it, and poll our own API
+ * until the other side reports the connection exists. Nothing is copied back by
+ * hand, and no third-party credential ever touches the terminal.
+ */
+
+import { spawn } from "node:child_process";
+
+import {
+  assertOk,
+  callBackendJson,
+  frontendUrl,
+  promptText,
+  resolveApiKey,
+} from "./shared.js";
+
+const POLL_INTERVAL_MS = 3000;
+const POLL_TIMEOUT_MS = 300000;
+
+/**
+ * Colour only when someone is actually watching.
+ *
+ * Escape codes in piped output end up in log files and CI transcripts as
+ * literal noise, and NO_COLOR is the standard way to ask us not to. The mark
+ * itself still prints in both cases -- it carries the meaning, the colour only
+ * makes it quicker to find.
+ */
+const USE_COLOR = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+
+function paint(code, text) {
+  return USE_COLOR ? `[${code}m${text}` : text;
+}
+
+export const MARK = {
+  ok: () => paint("32", "✓"),
+  skip: () => paint("90", "○"),
+  fail: () => paint("31", "✗"),
+};
+
+/** A finished step, marked so it can be found at a glance. */
+export function connected(message) {
+  process.stdout.write(`${MARK.ok()} ${message}\n`);
+}
+
+/** Open a URL in the customer's default browser, best effort. */
+export function openUrl(url) {
+  const command =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  try {
+    const child = spawn(command, [url], {
+      stdio: "ignore",
+      detached: true,
+      shell: process.platform === "win32",
+    });
+    child.unref();
+    return true;
+  } catch {
+    // Headless boxes and locked-down shells are normal. The URL is printed
+    // either way, so this is a convenience, never the only path.
+    return false;
+  }
+}
+
+function present(url, what) {
+  process.stdout.write(`\n  ${url}\n\n`);
+  if (openUrl(url)) process.stdout.write(`Opened ${what} in your browser.\n`);
+  else process.stdout.write(`Open the link above to ${what}.\n`);
+}
+
+/**
+ * Raised by a poll that will never succeed, however long we wait.
+ *
+ * Distinct from an ordinary failed poll because the two need opposite
+ * handling: a network blip while the customer is in another tab should be
+ * ignored, but a stack deployed into the wrong AWS account will report the
+ * same answer forever, and waiting five minutes to say so is five minutes of
+ * the customer believing it might still work.
+ */
+export class Unrecoverable extends Error {}
+
+/**
+ * Poll ``check`` until it reports done.
+ *
+ * Returns the truthy value from ``check``, or null on timeout. Ordinary
+ * exceptions are swallowed and retried; :class:`Unrecoverable` stops the wait.
+ */
+async function waitFor(label, check) {
+  const deadline = Date.now() + POLL_TIMEOUT_MS;
+  process.stdout.write(`Waiting for ${label}`);
+  while (Date.now() < deadline) {
+    try {
+      const done = await check();
+      if (done) {
+        process.stdout.write(" done.\n");
+        return done;
+      }
+    } catch (err) {
+      if (err instanceof Unrecoverable) {
+        process.stdout.write("\n");
+        throw err;
+      }
+      /* keep waiting; the customer is elsewhere */
+    }
+    process.stdout.write(".");
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+  }
+  process.stdout.write("\n");
+  return null;
+}
+
+function requireKey(args) {
+  const apiKey = resolveApiKey(args);
+  if (!apiKey) {
+    throw new Error("Not signed in. Run 'preman login' first.");
+  }
+  return apiKey;
+}
+
+// ---------------------------------------------------------------------------
+// AWS
+// ---------------------------------------------------------------------------
+
+export async function awsCommand(args) {
+  const token = requireKey(args);
+
+  const accountId = (
+    args.value("--account", "") || (await promptText("AWS account ID (12 digits): "))
+  ).trim();
+  const region = args.value("--region", "us-east-1");
+
+  const created = await callBackendJson(args, "POST", "/aws-links", {
+    token,
+    json: { aws_account_id: accountId, console_region: region },
+  });
+  assertOk(created, "create AWS connection");
+
+  const setup = created.setup || {};
+  process.stdout.write("\nThis grants PreMan read-only access to:\n");
+  for (const grant of setup.grants || []) process.stdout.write(`  - ${grant}\n`);
+
+  if (setup.quick_create_url) {
+    present(setup.quick_create_url, "create the CloudFormation stack");
+    process.stdout.write("Tick the IAM acknowledgement, then click Create stack.\n");
+  } else {
+    // No hosted template in this deployment: the CLI path still works.
+    process.stdout.write(`\nRun this to create the role:\n\n  ${setup.cli_command}\n\n`);
+  }
+
+  const linkId = created.link?.id;
+  let verified;
+  try {
+    verified = await waitFor("the stack", async () => {
+      const result = await callBackendJson(args, "POST", `/aws-links/${linkId}/verify`, {
+        token,
+        query: { region },
+      });
+      // Waiting cannot fix a stack built in the wrong account: it will report
+      // this same answer until the customer redeploys somewhere else.
+      if (result.reason === "wrong_account") throw new Unrecoverable(result.remediation);
+      return result.verified ? result : null;
+    });
+  } catch (err) {
+    if (!(err instanceof Unrecoverable)) throw err;
+    process.stdout.write(`${err.message}\n`);
+    return;
+  }
+
+  if (!verified) {
+    process.stdout.write("Timed out. Re-run 'preman aws' once the stack finishes.\n");
+    return;
+  }
+  connected(`AWS connected: ${verified.role_arn}`);
+
+  const groups = await callBackendJson(args, "GET", `/aws-links/${linkId}/log-groups`, {
+    token,
+    query: { region },
+  });
+  const names = (groups.log_groups || []).map((g) => g.name);
+  if (!names.length) {
+    process.stdout.write(`No log groups found in ${region}.\n`);
+    return;
+  }
+
+  process.stdout.write("\nLog groups PreMan can read:\n");
+  names.slice(0, 10).forEach((name, i) => process.stdout.write(`  ${i + 1}. ${name}\n`));
+
+  const projectId = args.value("--project-id", "");
+  if (!projectId) {
+    process.stdout.write("\nPass --project-id to start streaming one of these.\n");
+    return;
+  }
+
+  const pick = args.value("--log-group", "") || (await promptText("Stream which one? [1]: "));
+  const chosen = names.includes(pick) ? pick : names[Math.max(0, Number(pick || 1) - 1)];
+
+  const connector = await callBackendJson(args, "POST", `/projects/${projectId}/log-connectors`, {
+    token,
+    json: {
+      name: chosen,
+      connector_type: "cloudwatch",
+      stream: "backend",
+      interval_seconds: 15,
+      config: { account_link_id: linkId, region, log_group: chosen },
+    },
+  });
+  assertOk(connector, "create log connector");
+  connected(`Streaming ${chosen}. Logs appear in PreMan within about a minute.`);
+}
+
+// ---------------------------------------------------------------------------
+// GitHub
+// ---------------------------------------------------------------------------
+
+export async function githubCommand(args) {
+  const token = requireKey(args);
+
+  const before = await callBackendJson(args, "GET", "/integrations/github", { token });
+  const seen = new Set((before.integrations || before.repos || []).map((r) => r.id));
+
+  const started = await callBackendJson(args, "POST", "/integrations/github/app/install", {
+    token,
+    json: {},
+  });
+  assertOk(started, "start GitHub install");
+
+  const url = started.install_url || started.url;
+  if (!url) throw new Error("Backend returned no GitHub install URL.");
+  present(url, "install the PreMan GitHub App");
+  process.stdout.write("Pick the repositories PreMan may read.\n");
+
+  const done = await waitFor("the installation", async () => {
+    const now = await callBackendJson(args, "GET", "/integrations/github", { token });
+    const rows = now.integrations || now.repos || [];
+    // Compare against what existed before, so a user who already had repos
+    // connected is not told they are done the moment polling starts.
+    const fresh = rows.filter((r) => !seen.has(r.id));
+    return fresh.length ? fresh : null;
+  });
+
+  if (!done) {
+    process.stdout.write("Timed out. Re-run 'preman github' if the install finished.\n");
+    return;
+  }
+  connected(`GitHub connected: ${done.length} repository(ies).`);
+  for (const repo of done.slice(0, 5)) process.stdout.write(`  - ${repo.repo_url}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// Slack
+// ---------------------------------------------------------------------------
+
+export async function slackCommand(args) {
+  const token = requireKey(args);
+
+  const before = await callBackendJson(args, "GET", "/slack/connections", { token });
+  const seen = new Set((before.connections || []).map((c) => c.id));
+
+  const started = await callBackendJson(args, "POST", "/slack/install", { token, json: {} });
+  assertOk(started, "start Slack install");
+
+  const url = started.install_url || started.url;
+  if (!url) throw new Error("Backend returned no Slack install URL.");
+  present(url, "add PreMan to your Slack workspace");
+
+  const done = await waitFor("the Slack install", async () => {
+    const now = await callBackendJson(args, "GET", "/slack/connections", { token });
+    const fresh = (now.connections || []).filter((c) => !seen.has(c.id));
+    return fresh.length ? fresh : null;
+  });
+
+  if (!done) {
+    process.stdout.write("Timed out. Re-run 'preman slack' if the install finished.\n");
+    return;
+  }
+  connected(`Slack connected: ${done[0].team_name || done[0].id}`);
+}
+
+// ---------------------------------------------------------------------------
+// The guided run
+// ---------------------------------------------------------------------------
+
+async function askYes(question, { assumeYes }) {
+  if (assumeYes) return true;
+  const answer = (await promptText(`${question} [Y/n]: `)).trim().toLowerCase();
+  return answer === "" || answer === "y" || answer === "yes";
+}
+
+/**
+ * Everything a new account needs, in one pass.
+ *
+ * Each step is optional and each failure is survivable: a customer who cannot
+ * finish Slack today should still leave with AWS streaming, so a step that
+ * throws is reported and the run continues rather than unwinding the ones that
+ * already worked.
+ */
+export async function onboardCommand(commandArgs, { makeArgs, authenticateTerminal, connectCommand }) {
+  const args = makeArgs(commandArgs);
+  const assumeYes = args.has("--yes");
+
+  process.stdout.write("PreMan setup\n\n");
+
+  const creds = await authenticateTerminal(args);
+  connected(`Signed in as ${creds.user_email || "your account"}.`);
+
+  const steps = [
+    {
+      name: "coding agent",
+      question: "Connect your coding agent?",
+      run: () => connectCommand([...commandArgs, "--skip-login"]),
+    },
+    { name: "GitHub", question: "Connect GitHub?", run: () => githubCommand(args) },
+    { name: "AWS logs", question: "Connect AWS?", run: () => awsCommand(args) },
+    { name: "Slack", question: "Connect Slack?", run: () => slackCommand(args) },
+  ];
+
+  const done = [];
+  const skipped = [];
+  const failed = [];
+
+  for (const step of steps) {
+    process.stdout.write(`\n── ${step.name} ──\n`);
+    if (!(await askYes(step.question, { assumeYes }))) {
+      skipped.push(step.name);
+      continue;
+    }
+    try {
+      await step.run();
+      done.push(step.name);
+    } catch (err) {
+      // Report and carry on: a failed Slack install must not cost the customer
+      // the AWS connection they just finished.
+      failed.push(`${step.name}: ${err.message}`);
+      process.stdout.write(`Could not finish ${step.name}: ${err.message}\n`);
+    }
+  }
+
+  process.stdout.write("\n── done ──\n");
+  // One line per step, marked, so the outcome is scannable rather than prose.
+  for (const name of done) process.stdout.write(`${MARK.ok()} ${name}\n`);
+  for (const name of skipped) process.stdout.write(`${MARK.skip()} ${name} (skipped)\n`);
+  for (const failure of failed) process.stdout.write(`${MARK.fail()} ${failure}\n`);
+  process.stdout.write(`\nOpen ${frontendUrl(args)} to see your logs and endpoints.\n`);
+}
+
+export const INTEGRATIONS_HELP = `
+Setup options:
+  preman onboard              Sign in, then connect agent, GitHub, AWS and Slack
+  preman aws                  Connect an AWS account and stream a log group
+  preman github               Install the PreMan GitHub App
+  preman slack                Add PreMan to a Slack workspace
+
+  --yes                       Accept every step without prompting (onboard)
+  --account <id>              AWS account id, skips the prompt
+  --region <region>           AWS region for log groups. Defaults to us-east-1
+  --project-id <id>           PreMan project to attach the log connector to
+  --log-group <name>          Log group to stream, skips the picker
+`;

package/bin/shared.js

@@ -341,8 +341,11 @@ export function buildServerConfig(args, { pairCode = "" } = {}) {
   if (pairCode) env.PREMAN_PAIR_CODE = pairCode;
 
   return {
-    command: "npx",
-    args: ["-y", "premanmcp@latest"],
+    // npm exec rather than npx: same resolution, but it is the command every
+    // install of npm ships, and it is what the rest of our instructions use.
+    // The trailing "--" stops npm from claiming flags meant for the server.
+    command: "npm",
+    args: ["exec", "-y", "premanmcp@latest", "--"],
     env,
   };
 }

package/dist/server.js

@@ -62,6 +62,7 @@ async function heartbeatWorkbenchLink() {
     try {
         const resp = await fetch(`${BACKEND_URL}/workbench/coding-agent/heartbeat`, {
             method: "POST",
+            signal: AbortSignal.timeout(5000),
             headers: {
                 Authorization: `Bearer ${API_KEY}`,
                 "Content-Type": "application/json",
@@ -360,7 +361,7 @@ export function createServer() {
             "",
             "## Tool taxonomy",
             "- **Read tools** (no side effects): get_endpoints, get_coverage, detect_drift, preman_status, list_collections, get_collection, list_runs",
-            "- **Action tools** (execute tests / mutate state): test_api, generate_tests, import_collection, test_endpoint_by_id, run_tests, delete_collection",
+            "- **Action tools** (execute tests / mutate state): test_api, generate_tests, generate_endpoint_tests, run_stress_test, import_collection, test_endpoint_by_id, register_discovered_endpoints, run_tests, delete_collection",
             "- **MCP conversion tools**: discover_endpoints_from_codebase, verify_endpoints_live, mcp_preview (returns inline two-pane panel), mcp_deploy, mcp_list_deployed, mcp_mint_consumer_token, mcp_revoke_consumer_token",
             "- **Auth (API key / PreMan)**: preman_create_api_key (JWT -> saved pm_live_ key), preman_login, preman_login_complete, preman_logout",
             "- **Auth (app JWT — email/OTP/password on your API)**: user_auth_start_signup, user_auth_signup, user_auth_verify_otp, user_auth_login, user_auth_needs_password, user_auth_resend_otp, user_auth_forgot_password, user_auth_set_password, user_auth_me, user_auth_change_password, user_auth_delete_account (HTTP to PREMAN_BACKEND /auth/*; no pm_live_ key required)",
@@ -372,6 +373,9 @@ export function createServer() {
             "- 'preview my MCP before deploying': mcp_preview (read-only). 'actually deploy': mcp_deploy.",
             "- 'test the login endpoint' / 'hit POST /auth/login with body': test_api with the full URL. Use test_endpoint_by_id ONLY when the user references a saved endpoint by id/uuid.",
             "- 'import my Postman/OpenAPI/Bruno/curl collection': import_collection.",
+            "- 'generate tests for endpoint X' / 'write unit tests for X and run them': generate_endpoint_tests (set include_code=true and write the returned code_artifacts to disk when the user wants test files).",
+            "- 'stress / load test X': run_stress_test. Read-only unless the user explicitly authorises writes — never set allow_writes yourself.",
+            "- After discover_endpoints_from_codebase, call register_discovered_endpoints with the JSON array it asked for, then verify_endpoints_live to confirm they respond.",
             "- App-auth flows (signup, OTP, login, change_password) live under the user_auth_* tools and do not need an pm_live_ key.",
             "- PREMAN_BACKEND / backend_url is the PreMan control plane. It is NOT the target API upstream for a generated MCP unless the user's own API is PreMan. Prefer base_url from verify_endpoints_live results.",
             "",
@@ -469,6 +473,70 @@ export function createServer() {
             });
         }
     });
+    // ── generate_endpoint_tests ───────────────────────────────────────
+    server.tool("generate_endpoint_tests", "Generate scenario tests for one endpoint (happy path, auth, validation, boundaries, plus user-described scenarios) and run them by default. Pass a workbench request_id, a registry endpoint_id, or target to let PreMan resolve either. Set include_code=true for ready-to-write pytest/jest files in code_artifacts.", {
+        request_id: z.string().optional().describe("Saved workbench request id"),
+        endpoint_id: z.string().optional().describe("Registry endpoint UUID from get_endpoints"),
+        target: z.string().optional().describe("Either kind of id; PreMan resolves it"),
+        scenarios: z.array(z.string()).optional().describe("The user's scenario descriptions, one per entry"),
+        run: z.boolean().optional().default(true).describe("Execute the generated cases now (read-only by default)"),
+        allow_writes: z.boolean().optional().default(false).describe("Permit mutating cases — only when the user authorised it"),
+        persist_suite: z.boolean().optional().default(false).describe("Also save as a recurring auto-test suite (paid feature)"),
+        max_cases: z.number().optional().default(10).describe("Max generated cases (1-25)"),
+        include_code: z.boolean().optional().default(false).describe("Return unit-test files in code_artifacts"),
+        test_framework: z.enum(["pytest", "jest"]).optional().default("pytest").describe("Framework for code_artifacts"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("generate_endpoint_tests", args);
+            return withFrontendUrl(result, "/endpoints");
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Call get_endpoints (include_workbench=true) to find a valid request or endpoint id."],
+                related_tools: ["get_endpoints", "run_stress_test"],
+            });
+        }
+    });
+    // ── run_stress_test ───────────────────────────────────────────────
+    server.tool("run_stress_test", "Bounded load test against one endpoint: paced requests for a fixed duration, reporting p50/p95/p99 latency, error rate, throughput, and a failure-classification mix. Read-only endpoints unless the user explicitly authorised writes; destructive endpoints always refused. Paid feature; server-side caps apply.", {
+        request_id: z.string().optional().describe("Saved workbench request id"),
+        endpoint_id: z.string().optional().describe("Registry endpoint UUID from get_endpoints"),
+        target: z.string().optional().describe("Either kind of id; PreMan resolves it"),
+        duration_seconds: z.number().optional().default(15).describe("Run length (server caps apply)"),
+        rps: z.number().optional().default(5).describe("Target requests per second (server caps apply)"),
+        concurrency: z.number().optional().default(5).describe("Max in-flight requests (server caps apply)"),
+        allow_writes: z.boolean().optional().default(false).describe("Only when the user authorised stressing a write endpoint"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("run_stress_test", args);
+            return withFrontendUrl(result, "/endpoints");
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Call get_endpoints (include_workbench=true) to find a valid request or endpoint id."],
+                related_tools: ["get_endpoints", "generate_endpoint_tests"],
+            });
+        }
+    });
+    // ── register_discovered_endpoints ─────────────────────────────────
+    server.tool("register_discovered_endpoints", "Save discovered endpoints into PreMan and set them up as runnable requests. Use after discover_endpoints_from_codebase with the JSON array its brief asked you to build; then call verify_endpoints_live to confirm they respond.", {
+        endpoints: z.array(z.record(z.any())).optional().describe("Discovery-shaped endpoint objects (method, path_template, schemas, confidence, …); max 100"),
+        endpoint_ids: z.array(z.string()).optional().describe("Alternatively, existing registry ids to set up as runnable requests"),
+        project_id: z.string().optional().describe("Scope registration to a project"),
+        base_url: z.string().optional().describe("Applied to endpoints that carry none"),
+        setup_workbench: z.boolean().optional().default(true).describe("Also create saved workbench requests (default true)"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("register_discovered_endpoints", args);
+            return withFrontendUrl(result, "/endpoints");
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Run discover_endpoints_from_codebase first and pass its endpoints array here."],
+                related_tools: ["discover_endpoints_from_codebase", "verify_endpoints_live"],
+            });
+        }
+    });
     // ── get_endpoints ─────────────────────────────────────────────────
     server.tool("get_endpoints", "Return endpoint inventory (registry, optionally MCP sessions and collections). Default: structured JSON for agents. Pass format='text' for deprecated human-friendly output, or open_ui=true for the visual dashboard. Schemas stripped by default to save tokens; set include_schemas=true when needed.", {
         status: z.string().optional().describe("Filter: tested, needed, draft"),
@@ -476,6 +544,7 @@ export function createServer() {
         include_sessions: z.boolean().optional().default(false).describe("Include recent MCP session test results"),
         include_collections: z.boolean().optional().default(false).describe("Include imported collection endpoints"),
         include_schemas: z.boolean().optional().default(false).describe("Include request/response schemas per endpoint (default false to save tokens)"),
+        include_workbench: z.boolean().optional().default(false).describe("Also list the default workspace's saved runnable requests"),
         limit: z.number().optional().default(50).describe("Max endpoints per page (default 50)"),
         offset: z.number().optional().default(0).describe("Pagination offset"),
         project_id: z.string().optional().describe("Scope to a specific project"),
@@ -1068,6 +1137,42 @@ export function createServer() {
     // ── Hosted MCP platform tools ──────────────────────────────────────
     // Thin stdio proxies; all real logic lives in flowtest/mcp/hosted_mcp_tools.py
     // and is reached via the /mcp/call-tool HTTP bridge.
+    server.tool("connect_logs", "Front door for connecting a customer's production logs to PreMan. Call with NO arguments first: it returns the projects you can use, the supported sources, and the questions to ask. Then call again with action='connect' (CloudWatch/S3/PostHog), action='push' (logs that live anywhere else — Kubernetes, a PaaS drain, a self-hosted collector), and finally action='verify'. NEVER ask the user for AWS access keys: AWS access is a read-only role the customer creates from the CloudFormation template this tool returns, and your job is to run the deploy command it gives you. For action='push', reference $PREMAN_API_KEY by name in any config you write — never print the key itself.", {
+        action: z
+            .enum(["brief", "connect", "push", "verify"])
+            .optional()
+            .describe("Omit for the guided brief; then connect | push | verify"),
+        project_id: z.string().optional().describe("PreMan project the logs belong to"),
+        source: z
+            .enum(["cloudwatch", "s3", "posthog"])
+            .optional()
+            .describe("Where the logs already land; required for action='connect'"),
+        config: z
+            .record(z.any())
+            .optional()
+            .describe("Source config: cloudwatch {region, log_group}, s3 {region, bucket, prefix?}, posthog {project_id, host?, event_names?}"),
+        aws_account_id: z
+            .string()
+            .optional()
+            .describe("Customer's 12-digit AWS account id; used to predict the role ARN the template creates"),
+        posthog_api_key: z.string().optional().describe("PostHog personal API key, read scope (posthog only)"),
+        name: z.string().optional().describe("Display name for the connector"),
+        env_name: z.string().optional().describe("Environment the logs belong to, e.g. production"),
+        stream: z.enum(["frontend", "backend", "unknown"]).optional().describe("Which log rail these lines land on"),
+        interval_seconds: z.number().optional().describe("Poll interval; defaults per source type"),
+        connector_id: z.string().optional().describe("Connector to check; required for action='verify'"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("connect_logs", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Call connect_logs with no arguments to see the supported actions."],
+                related_tools: ["connect_logs"],
+            });
+        }
+    });
     server.tool("discover_endpoints_from_codebase", "Return a brief the coding agent follows to extract HTTP endpoints from the user's codebase. Call this first when the user asks to turn their API into an MCP — the returned instructions tell your agent how to walk the repo and what shape to produce. Then pass the findings to verify_endpoints_live.", {
         base_path: z.string().optional().describe("Directory to scan (defaults to CWD)"),
         framework_hint: z.string().optional().describe("fastapi | express | nestjs | rails | django | nextjs"),
@@ -1323,6 +1428,21 @@ async function main() {
     const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    // Starting the configured MCP server is itself proof that the coding agent
+    // is live.  Previously the workbench remained in `connecting` until someone
+    // explicitly asked the agent to call `preman_status`, even when this process
+    // already had valid stored credentials and the pairing code in its env.
+    // Keep startup non-blocking so a slow control plane cannot delay MCP setup.
+    if (API_KEY) {
+        void heartbeatWorkbenchLink().then((link) => {
+            if (link?.ok) {
+                console.error("[PreMan] Coding-agent connection heartbeat sent");
+            }
+            else if (link) {
+                console.error(`[PreMan] Coding-agent heartbeat not accepted: ${String(link.detail || link.status || "unknown error")}`);
+            }
+        });
+    }
 }
 main().catch(console.error);
 process.on("SIGINT", () => { process.exit(0); });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Turn APIs into agent-callable MCP tools with auth, testing, and audit logs",
   "type": "module",
   "bin": {
@@ -12,7 +12,8 @@
     "build": "tsc -p tsconfig.server.json",
     "dev": "tsx src/server.ts",
     "open-mcp-preview": "node scripts/emit-mcp-preview.mjs",
-    "open-mcp-preview-in-cursor": "node scripts/open-cursor-preview.mjs"
+    "open-mcp-preview-in-cursor": "node scripts/open-cursor-preview.mjs",
+    "test": "node --test scripts/smoke-onboard.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^0.1.0",