@testchimp/cli 0.1.84 → 0.1.85

package/dist/agentwatch/credentialsFile.js

@@ -0,0 +1,76 @@
+/**
+ * Local AgentWatch credentials in `~/.testchimp/agentwatch/credentials.json` (TESTCHIMP_HOME honoured).
+ *
+ * Written by `testchimp bot connect`, read by headless AgentWatch (desktop
+ * `src/main/auth/agentwatchCredentials.ts`) so it runs without TestChimp Studio sign-in. Keyed by
+ * project because the API key is per project. Holds the user's PAT: directory 0700, file 0600.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { getTestchimpHome } from "../workspace/projectsRegistry.js";
+export const AgentwatchProjectCredentialsSchema = z.looseObject({
+    userId: z.string().min(1),
+    email: z.string().optional(),
+    userAuthKey: z.string().min(8),
+    projectApiKey: z.string().min(8),
+    botId: z.string().optional(),
+    backendUrl: z.string().url(),
+    ingressUrl: z.string().url().optional(),
+    savedAtMillis: z.number().int().nonnegative(),
+});
+export const AgentwatchCredentialsFileSchema = z.looseObject({
+    schemaVersion: z.literal(1),
+    projects: z.record(z.string(), AgentwatchProjectCredentialsSchema),
+});
+export function agentwatchCredentialsPath(env = {}) {
+    return join(getTestchimpHome(env), "agentwatch", "credentials.json");
+}
+/** Parsed file, or null when missing / unreadable / another schema. */
+export function readAgentwatchCredentials(env = {}) {
+    const path = agentwatchCredentialsPath(env);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = AgentwatchCredentialsFileSchema.safeParse(JSON.parse(readFileSync(path, "utf8")));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeAtomic(file, env) {
+    const path = agentwatchCredentialsPath(env);
+    const dir = join(getTestchimpHome(env), "agentwatch");
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, path);
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // Windows ignores POSIX modes.
+    }
+}
+export function saveProjectCredentials(projectId, creds, env = {}) {
+    const entry = AgentwatchProjectCredentialsSchema.parse(creds);
+    const file = readAgentwatchCredentials(env) ?? { schemaVersion: 1, projects: {} };
+    file.projects[projectId] = entry;
+    writeAtomic(file, env);
+    return agentwatchCredentialsPath(env);
+}
+/** True when an entry was removed. Deletes the file once no project is left. */
+export function removeProjectCredentials(projectId, env = {}) {
+    const file = readAgentwatchCredentials(env);
+    if (!file || !(projectId in file.projects))
+        return false;
+    delete file.projects[projectId];
+    if (Object.keys(file.projects).length === 0) {
+        unlinkSync(agentwatchCredentialsPath(env));
+    }
+    else {
+        writeAtomic(file, env);
+    }
+    return true;
+}

package/dist/cli/program.d.ts

@@ -1,4 +1,6 @@
 import { Command } from "commander";
 import { PACKAGE_VERSION } from "../core/version.js";
 export { PACKAGE_VERSION };
+/** Numeric x.y.z comparison; prerelease / build suffixes are ignored. */
+export declare function compareSemver(a: string, b: string): number;
 export declare function buildCliProgram(): Command;

package/dist/cli/program.js

@@ -1,7 +1,7 @@
 import { Command, Option } from "commander";
 import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { DEFAULT_BACKEND, postMcp } from "../core/client.js";
+import { DEFAULT_BACKEND, DEFAULT_INGRESS, postIngress, postMcp } from "../core/client.js";
 import { deepMerge } from "../core/merge.js";
 import { runTool } from "../core/tools.js";
 import { TOOL_DEFINITIONS } from "../core/tools.js";
@@ -15,6 +15,24 @@ function isPerfComparisonRegressed(parsed) {
     const body = parsed;
     return body.regressed === true || body.comparison?.regressed === true;
 }
+/** Ack statuses that mean the id or bot identity is wrong (exit non-zero). */
+const BOT_ACK_FAILURE_STATUSES = new Set([
+    "BOT_ACK_UNKNOWN_EVENT",
+    "BOT_ACK_NOT_A_TARGET",
+    "BOT_ACK_MISSING_BOT_ID",
+]);
+/** Numeric x.y.z comparison; prerelease / build suffixes are ignored. */
+export function compareSemver(a, b) {
+    const parts = (v) => v.trim().replace(/^v/, "").split(/[-+]/)[0].split(".").map((p) => parseInt(p, 10) || 0);
+    const pa = parts(a);
+    const pb = parts(b);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d < 0 ? -1 : 1;
+    }
+    return 0;
+}
 function parseRecordTypesCsv(raw) {
     return String(raw)
         .split(",")
@@ -102,8 +120,19 @@ export function buildCliProgram() {
     program.name("testchimp").description("TestChimp CLI — call project MCP HTTP APIs").version(PACKAGE_VERSION);
     program
         .command("mcp")
-        .description("Start the TestChimp MCP server (stdio transport)")
-        .action(async () => {
+        .description("Start the TestChimp MCP server (stdio transport; --http for remote Streamable HTTP with OAuth bearer auth)")
+        .option("--http", "Serve MCP over Streamable HTTP (stateless) at /mcp instead of stdio")
+        .option("--port <n>", "HTTP port (default: PORT env or 8080)", (v) => parseInt(v, 10))
+        .option("--host <h>", "HTTP bind host", "0.0.0.0")
+        .action(async (opts) => {
+        if (opts.http) {
+            const port = opts.port ?? (process.env.PORT ? parseInt(process.env.PORT, 10) : 8080);
+            if (!Number.isInteger(port) || port < 0 || port > 65535)
+                throw new Error(`Invalid port: ${port}`);
+            const { runMcpHttpServer } = await import("../mcp/httpServer.js");
+            await runMcpHttpServer({ port, host: String(opts.host) });
+            return;
+        }
         const { runMcpServer } = await import("../mcp/server.js");
         await runMcpServer();
     });
@@ -1728,6 +1757,261 @@ export function buildCliProgram() {
             body.limit = opts.limit;
         console.log(await runTool("list-api-operation-interactions", mergeBodies(body, opts.jsonInput), { postMcp }));
     });
+    for (const kebab of ["get-qa-posture", "get-bot-compat"]) {
+        program
+            .command(kebab)
+            .description(TOOL_DEFINITIONS.find((t) => t.kebab === kebab).description)
+            .addOption(jsonInputOption())
+            .action(async (opts) => {
+            console.log(await runTool(kebab, mergeBodies({}, opts.jsonInput), { postMcp }));
+        });
+    }
+    program
+        .command("get-my-tasks")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-my-tasks").description)
+        .addOption(jsonInputOption())
+        .option("--user-id <id>", "Team member user id (required with an API key; OAuth tokens imply the user)")
+        .action(async (opts) => {
+        const body = {};
+        if (opts.userId)
+            body.userId = String(opts.userId);
+        console.log(await runTool("get-my-tasks", mergeBodies(body, opts.jsonInput), { postMcp }));
+    });
+    program
+        .command("list-tests-awaiting-verification")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "list-tests-awaiting-verification").description)
+        .addOption(jsonInputOption())
+        .option("--user-id <id>", "Team member user id")
+        .option("--limit <n>", "Maximum results", (v) => parseInt(v, 10))
+        .action(async (opts) => {
+        const body = {};
+        if (opts.userId)
+            body.userId = String(opts.userId);
+        if (opts.limit != null && !Number.isNaN(opts.limit))
+            body.limit = opts.limit;
+        console.log(await runTool("list-tests-awaiting-verification", mergeBodies(body, opts.jsonInput), { postMcp }));
+    });
+    program
+        .command("get-bot-profile")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-bot-profile").description)
+        .addOption(jsonInputOption())
+        .option("--bot-id <id>", "Bot id (defaults to TESTCHIMP_BOT_ID / OAuth token)")
+        .action(async (opts) => {
+        const body = {};
+        if (opts.botId)
+            body.botId = String(opts.botId);
+        console.log(await runTool("get-bot-profile", mergeBodies(body, opts.jsonInput), { postMcp }));
+    });
+    const bot = program.command("bot").description("TestChimp QA-bot helpers (profile, event acks, compatibility)");
+    bot
+        .command("ack")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "ack-bot-events").description)
+        .argument("<eventIds...>", "Event ids from the webhook delivery (max 100)")
+        .option("--ack-url <url>", "Delivery ackUrl (default: TESTCHIMP_INGRESS_URL + /bot/events/ack)")
+        .action(async (eventIds, opts) => {
+        const body = { eventIds };
+        if (opts.ackUrl)
+            body.ackUrl = String(opts.ackUrl);
+        const out = await runTool("ack-bot-events", body, { postMcp, postIngress });
+        let results = [];
+        try {
+            const parsed = JSON.parse(out);
+            results = Array.isArray(parsed.results) ? parsed.results : [];
+        }
+        catch {
+            console.log(out);
+            process.exitCode = 1;
+            return;
+        }
+        let failed = results.length === 0;
+        for (const r of results) {
+            const status = String(r.status ?? "UNKNOWN");
+            console.log(`${r.eventId ?? "?"}\t${status}`);
+            if (BOT_ACK_FAILURE_STATUSES.has(status))
+                failed = true;
+        }
+        if (failed)
+            process.exitCode = 1;
+    });
+    bot
+        .command("register-profile")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "register-bot-profile").description)
+        .addOption(jsonInputOption())
+        .option("--bot-id <id>", "Bot id (defaults to TESTCHIMP_BOT_ID / OAuth token)")
+        .option("--role <role>", "QA_LEAD | PM | QA_ENGINEER | DEVELOPER")
+        .option("--responsibilities <text>", "Free-text responsibilities in the user's words")
+        .option("--capability <name>", "Capability (repeatable): REQUIREMENTS_UPDATE, E2E_AUTHORING, ISSUE_FIX, MANUAL_TEST_COORDINATION, TEST_BATCH_FIX, QA_POSTURE", (v, prev = []) => [...prev, ...v.split(",").map((s) => s.trim()).filter(Boolean)])
+        .option("--subscriptions-json <json>", "Subscriptions array JSON or @file: [{eventType, filters:[{field, op, value}]}]")
+        .action(async (opts) => {
+        const body = {};
+        if (opts.botId)
+            body.botId = String(opts.botId);
+        if (opts.role)
+            body.role = String(opts.role).trim().toUpperCase();
+        if (opts.responsibilities != null)
+            body.responsibilities = String(opts.responsibilities);
+        if (opts.capability?.length)
+            body.capabilities = opts.capability.map((c) => c.toUpperCase());
+        if (opts.subscriptionsJson) {
+            const raw = String(opts.subscriptionsJson).trim();
+            const text = raw.startsWith("@") ? readFileSync(raw.slice(1), "utf8") : raw;
+            const parsed = JSON.parse(text);
+            body.subscriptions = Array.isArray(parsed)
+                ? parsed
+                : parsed.subscriptions ?? parsed;
+        }
+        console.log(await runTool("register-bot-profile", mergeBodies(body, opts.jsonInput), { postMcp }));
+    });
+    bot
+        .command("get-profile")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-bot-profile").description)
+        .addOption(jsonInputOption())
+        .option("--bot-id <id>", "Bot id (defaults to TESTCHIMP_BOT_ID / OAuth token)")
+        .action(async (opts) => {
+        const body = {};
+        if (opts.botId)
+            body.botId = String(opts.botId);
+        console.log(await runTool("get-bot-profile", mergeBodies(body, opts.jsonInput), { postMcp }));
+    });
+    bot
+        .command("compat")
+        .description("Check this CLI (and optionally the testchimp skill) against the deployment's minimum bot versions")
+        .option("--skill-version <semver>", "Installed testchimp skill version (SKILL.md frontmatter) to check too")
+        .action(async (opts) => {
+        const out = await runTool("get-bot-compat", {}, { postMcp });
+        const compat = JSON.parse(out);
+        const cliUpgradeRequired = !!compat.minCliVersion && compareSemver(PACKAGE_VERSION, compat.minCliVersion) < 0;
+        const skillVersion = opts.skillVersion ? String(opts.skillVersion).trim() : undefined;
+        const skillUpgradeRequired = skillVersion != null && !!compat.minSkillVersion && compareSemver(skillVersion, compat.minSkillVersion) < 0;
+        console.log(JSON.stringify({
+            ...compat,
+            cliVersion: PACKAGE_VERSION,
+            cliUpgradeRequired,
+            ...(skillVersion != null ? { skillVersion, skillUpgradeRequired } : {}),
+        }, null, 2));
+        if (cliUpgradeRequired) {
+            console.error(`[testchimp] CLI ${PACKAGE_VERSION} is older than required ${compat.minCliVersion}; run: npm i -g @testchimp/cli@latest`);
+        }
+        else {
+            console.error(`[testchimp] CLI ${PACKAGE_VERSION} meets minimum ${compat.minCliVersion ?? "(none)"}; no upgrade required.`);
+        }
+        if (skillUpgradeRequired) {
+            console.error(`[testchimp] testchimp skill ${skillVersion} is older than required ${compat.minSkillVersion}; reinstall the skill.`);
+        }
+    });
+    bot
+        .command("connect")
+        .description("Sign in through the browser (OAuth) and store this user's id, PAT and the project API key for headless AgentWatch (no TestChimp Studio needed)")
+        .option("--project-id <id>", "Fail unless the project approved on the consent page is this one")
+        .option("--port <n>", "Loopback port for the OAuth redirect (default: a free port)")
+        .option("--no-browser", "Only print the approval URL")
+        .option("--timeout-ms <n>", "How long to wait for approval (default 300000)")
+        .action(async (opts) => {
+        const { connectAgentWatch, ingressUrlForBackend } = await import("../agentwatch/connect.js");
+        const { getBackendUrl, getIngressUrl } = await import("../core/client.js");
+        try {
+            const backendUrl = getBackendUrl();
+            const result = await connectAgentWatch({
+                backendUrl,
+                ingressUrl: process.env.TESTCHIMP_INGRESS_URL?.trim() ? getIngressUrl() : ingressUrlForBackend(backendUrl),
+                expectedProjectId: opts.projectId ? String(opts.projectId).trim() : undefined,
+                port: opts.port != null ? Number(opts.port) : undefined,
+                timeoutMs: opts.timeoutMs != null ? Number(opts.timeoutMs) : undefined,
+                openUrl: opts.browser === false ? () => undefined : undefined,
+                log: stderrProgress,
+            });
+            stderrProgress(`Saved AgentWatch credentials for project ${result.projectId} in ${result.credentialsPath}` +
+                (result.botId ? `; set TESTCHIMP_BOT_ID=${result.botId} for this bot` : ""));
+            console.log(JSON.stringify(result, null, 2));
+        }
+        catch (e) {
+            console.error(`[testchimp bot connect] ${e instanceof Error ? e.message : String(e)}`);
+            process.exitCode = 1;
+        }
+    });
+    bot
+        .command("disconnect")
+        .description("Remove the stored AgentWatch credentials for a project")
+        .requiredOption("--project-id <id>", "TestChimp project id")
+        .action(async (opts) => {
+        const { removeProjectCredentials, agentwatchCredentialsPath } = await import("../agentwatch/credentialsFile.js");
+        const projectId = String(opts.projectId).trim();
+        const removed = removeProjectCredentials(projectId);
+        console.log(JSON.stringify({ projectId, removed, credentialsPath: agentwatchCredentialsPath() }));
+    });
+    const workspace = program
+        .command("workspace")
+        .description("Per-user local folder ↔ TestChimp project mapping (~/.testchimp/projects.json, shared with TestChimp Studio)");
+    workspace
+        .command("map")
+        .description("Map a local git repo folder to a TestChimp project (same rules as Studio folder mapping)")
+        .requiredOption("--project-id <id>", "TestChimp project id")
+        .requiredOption("--folder <path>", "Local repository folder (must be a git repo)")
+        .option("--project-name <name>", "Project display name stored with the mapping")
+        .option("--reassign", "Move the folder from another project's mapping to this project")
+        .option("--skip-repo-check", "Do not compare the git remote with the project's connected repository")
+        .action(async (opts) => {
+        const { upsertWorkspaceFolder, projectsRegistryPath } = await import("../workspace/projectsRegistry.js");
+        const { assertFolderMatchesRepo, inspectLocalGitRepo } = await import("../workspace/gitRepo.js");
+        const projectId = String(opts.projectId).trim();
+        try {
+            if (!projectId)
+                throw new Error("INVALID_PAYLOAD: --project-id");
+            const inspection = inspectLocalGitRepo(String(opts.folder));
+            let expectedRepo = null;
+            if (opts.skipRepoCheck) {
+                stderrProgress("Skipping connected-repository check (--skip-repo-check).");
+            }
+            else if (!process.env.TESTCHIMP_API_KEY?.trim() && !process.env.TESTCHIMP_OAUTH_TOKEN?.trim()) {
+                stderrProgress("No TESTCHIMP_API_KEY / TESTCHIMP_OAUTH_TOKEN set; skipping connected-repository check.");
+            }
+            else {
+                try {
+                    const out = await runTool("get-git-folder-mapping", {}, { postMcp });
+                    const parsed = JSON.parse(out);
+                    expectedRepo = parsed.repositoryFullName?.trim() || null;
+                    if (!expectedRepo)
+                        stderrProgress("Project has no connected repository; skipping remote check.");
+                }
+                catch (e) {
+                    stderrProgress(`Could not load the project's connected repository (${e instanceof Error ? e.message : String(e)}); skipping remote check.`);
+                }
+            }
+            assertFolderMatchesRepo(inspection, expectedRepo);
+            const mapping = upsertWorkspaceFolder({
+                projectId,
+                projectName: opts.projectName != null ? String(opts.projectName).trim() || undefined : undefined,
+                rootPath: inspection.selectedPath,
+                reassign: opts.reassign === true,
+            });
+            stderrProgress(`Mapped ${inspection.selectedPath} → project ${projectId} in ${projectsRegistryPath()}`);
+            console.log(JSON.stringify(mapping, null, 2));
+        }
+        catch (e) {
+            console.error(`[testchimp workspace map] ${e instanceof Error ? e.message : String(e)}`);
+            process.exitCode = 1;
+        }
+    });
+    workspace
+        .command("get")
+        .description("Print the folder mapping JSON for a project (exit 1 when unmapped)")
+        .requiredOption("--project-id <id>", "TestChimp project id")
+        .action(async (opts) => {
+        const { findWorkspaceMapping } = await import("../workspace/projectsRegistry.js");
+        try {
+            const mapping = findWorkspaceMapping(String(opts.projectId).trim());
+            if (!mapping) {
+                console.error(`[testchimp workspace get] project ${opts.projectId} is not mapped to a local folder; run: testchimp workspace map --project-id ${opts.projectId} --folder <path>`);
+                process.exitCode = 1;
+                return;
+            }
+            console.log(JSON.stringify(mapping, null, 2));
+        }
+        catch (e) {
+            console.error(`[testchimp workspace get] ${e instanceof Error ? e.message : String(e)}`);
+            process.exitCode = 1;
+        }
+    });
     const chimphands = program.command("chimphands").description("ChimpHands GitHub Actions agent bridge");
     chimphands
         .command("report-branch")
@@ -1811,6 +2095,6 @@ export function buildCliProgram() {
     program.on("--help", () => {
         /* default */
     });
-    program.addHelpText("after", `\nEnvironment:\n  TESTCHIMP_API_KEY          required\n  TESTCHIMP_BACKEND_URL      optional (default ${DEFAULT_BACKEND})\n\nOutput:\n  Response JSON on stdout.\n  provision-ephemeral-environment-and-wait progress on stderr.\n\nAdvanced:\n  --json-input merges a JSON object over flags (JSON wins on key conflicts). Use @file.json to read from disk.\n`);
+    program.addHelpText("after", `\nEnvironment:\n  TESTCHIMP_API_KEY          required unless TESTCHIMP_OAUTH_TOKEN is set\n  TESTCHIMP_OAUTH_TOKEN      optional OAuth access token (sent as Authorization: Bearer)\n  TESTCHIMP_BOT_ID           optional QA bot id (sent as bot-id header)\n  TESTCHIMP_BACKEND_URL      optional (default ${DEFAULT_BACKEND})\n  TESTCHIMP_INGRESS_URL      optional (default ${DEFAULT_INGRESS})\n  TESTCHIMP_HOME             optional Studio/CLI home for workspace mappings (default ~/.testchimp)\n\nOutput:\n  Response JSON on stdout.\n  provision-ephemeral-environment-and-wait progress on stderr.\n\nAdvanced:\n  --json-input merges a JSON object over flags (JSON wins on key conflicts). Use @file.json to read from disk.\n`);
     return program;
 }

package/dist/core/client.d.ts

@@ -1,6 +1,38 @@
 /** HTTP client for TestChimp MCP proxy APIs. */
 export declare const DEFAULT_BACKEND = "https://featureservice.testchimp.io";
+export declare const DEFAULT_INGRESS = "https://ingress.testchimp.io";
 export declare function getBackendUrl(): string;
+export declare function getIngressUrl(): string;
+/**
+ * Validate an explicit absolute ingress URL (e.g. webhook `ackUrl`). Credentials are attached, so only
+ * https (or http on loopback) to the configured ingress host or a TestChimp SaaS host is allowed.
+ */
+export declare function resolveIngressTargetUrl(absoluteUrl: string): string;
 export declare function requireApiKey(): string;
+/**
+ * Per-request caller credentials (remote MCP over HTTP). When `isolated` is true the process env
+ * credentials (TESTCHIMP_API_KEY / TESTCHIMP_OAUTH_TOKEN / TESTCHIMP_BOT_ID) are never used.
+ */
+export interface RequestAuth {
+    bearerToken?: string;
+    botId?: string;
+    isolated: boolean;
+}
+export declare function runWithRequestAuth<T>(auth: RequestAuth, fn: () => T): T;
+/** 1..64 printable ASCII characters, no spaces or control characters. */
+export declare function isValidBotId(value: string): boolean;
+/** Test hook: allow the once-per-process TESTCHIMP_BOT_ID warning to fire again. */
+export declare function resetClientWarningsForTests(): void;
+/** Headers for featureservice / ingress calls. API-key-only callers get exactly the legacy header set. */
+export declare function buildRequestHeaders(): Record<string, string>;
+/** Non-2xx TestChimp API response (message format matches the historical client errors). */
+export declare class TestChimpHttpError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, statusText: string, body: string);
+}
 export declare function postMcp(path: string, body: unknown): Promise<string>;
+/** POST to TestChimp ingress: a path under TESTCHIMP_INGRESS_URL, or an explicit absolute URL (e.g. ackUrl). */
+export declare function postIngress(pathOrUrl: string, body: unknown): Promise<string>;
 export type PostMcpFn = (path: string, body: unknown) => Promise<string>;
+export type PostIngressFn = (pathOrUrl: string, body: unknown) => Promise<string>;

package/dist/core/client.js

@@ -1,9 +1,18 @@
 /** HTTP client for TestChimp MCP proxy APIs. */
+import { AsyncLocalStorage } from "node:async_hooks";
 export const DEFAULT_BACKEND = "https://featureservice.testchimp.io";
+export const DEFAULT_INGRESS = "https://ingress.testchimp.io";
 function isTestChimpSaasFeatureservice(hostname) {
     return hostname === "featureservice.testchimp.io"
         || /^featureservice-[a-z0-9-]+\.testchimp\.io$/i.test(hostname);
 }
+function isTestChimpSaasIngress(hostname) {
+    return hostname === "ingress.testchimp.io"
+        || /^ingress-[a-z0-9-]+\.testchimp\.io$/i.test(hostname);
+}
+function isLoopbackHost(hostname) {
+    return hostname === "localhost" || hostname === "127.0.0.1";
+}
 export function getBackendUrl() {
     const raw = process.env.TESTCHIMP_BACKEND_URL?.trim();
     if (!raw)
@@ -23,6 +32,51 @@ export function getBackendUrl() {
     }
     return raw.replace(/\/+$/, "");
 }
+export function getIngressUrl() {
+    const raw = process.env.TESTCHIMP_INGRESS_URL?.trim();
+    if (!raw)
+        return DEFAULT_INGRESS;
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new Error(`TESTCHIMP_INGRESS_URL must be an absolute http(s) URL; received ${JSON.stringify(raw)}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error(`TESTCHIMP_INGRESS_URL must use http or https; received ${parsed.protocol}`);
+    }
+    if (parsed.protocol === "http:" && isTestChimpSaasIngress(parsed.hostname)) {
+        throw new Error(`TESTCHIMP_INGRESS_URL must use https for TestChimp SaaS; change it to https://${parsed.host}`);
+    }
+    return raw.replace(/\/+$/, "");
+}
+/**
+ * Validate an explicit absolute ingress URL (e.g. webhook `ackUrl`). Credentials are attached, so only
+ * https (or http on loopback) to the configured ingress host or a TestChimp SaaS host is allowed.
+ */
+export function resolveIngressTargetUrl(absoluteUrl) {
+    let parsed;
+    try {
+        parsed = new URL(absoluteUrl.trim());
+    }
+    catch {
+        throw new Error(`Invalid ingress URL ${JSON.stringify(absoluteUrl)}; expected an absolute https URL`);
+    }
+    const loopback = isLoopbackHost(parsed.hostname);
+    if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && loopback)) {
+        throw new Error(`Ingress URL must use https (http is only allowed for localhost / 127.0.0.1); received ${parsed.protocol}//${parsed.host}`);
+    }
+    const configuredHost = new URL(getIngressUrl()).hostname;
+    const trustedHost = loopback
+        || parsed.hostname === configuredHost
+        || parsed.hostname === "testchimp.io"
+        || parsed.hostname.endsWith(".testchimp.io");
+    if (!trustedHost) {
+        throw new Error(`Refusing to send credentials to untrusted ingress host ${parsed.hostname}; set TESTCHIMP_INGRESS_URL to your TestChimp ingress URL`);
+    }
+    return parsed.toString();
+}
 export function requireApiKey() {
     const k = process.env.TESTCHIMP_API_KEY?.trim();
     if (!k) {
@@ -30,26 +84,96 @@ export function requireApiKey() {
     }
     return k;
 }
-export async function postMcp(path, body) {
-    const apiKey = requireApiKey();
-    const url = `${getBackendUrl()}${path}`;
+const requestAuthStorage = new AsyncLocalStorage();
+export function runWithRequestAuth(auth, fn) {
+    return requestAuthStorage.run(auth, fn);
+}
+const BOT_ID_PATTERN = /^[\x21-\x7e]{1,64}$/;
+/** 1..64 printable ASCII characters, no spaces or control characters. */
+export function isValidBotId(value) {
+    return BOT_ID_PATTERN.test(value);
+}
+let warnedInvalidBotId = false;
+/** Test hook: allow the once-per-process TESTCHIMP_BOT_ID warning to fire again. */
+export function resetClientWarningsForTests() {
+    warnedInvalidBotId = false;
+}
+function envBotId() {
+    const raw = process.env.TESTCHIMP_BOT_ID;
+    if (raw == null || raw === "")
+        return undefined;
+    if (isValidBotId(raw))
+        return raw;
+    if (!warnedInvalidBotId) {
+        warnedInvalidBotId = true;
+        console.error("[testchimp] Ignoring TESTCHIMP_BOT_ID: must be 1-64 printable ASCII characters without spaces; bot-id header not sent.");
+    }
+    return undefined;
+}
+/** Headers for featureservice / ingress calls. API-key-only callers get exactly the legacy header set. */
+export function buildRequestHeaders() {
+    const headers = { "Content-Type": "application/json" };
+    const requestAuth = requestAuthStorage.getStore();
+    if (requestAuth?.isolated) {
+        if (!requestAuth.bearerToken) {
+            throw new Error("Authorization: Bearer token is required for remote TestChimp MCP requests.");
+        }
+        headers.Authorization = `Bearer ${requestAuth.bearerToken}`;
+        if (requestAuth.botId && isValidBotId(requestAuth.botId))
+            headers["bot-id"] = requestAuth.botId;
+        return headers;
+    }
+    const bearer = requestAuth?.bearerToken || process.env.TESTCHIMP_OAUTH_TOKEN?.trim();
+    const apiKey = process.env.TESTCHIMP_API_KEY?.trim();
+    if (!bearer) {
+        headers["TestChimp-Api-Key"] = requireApiKey();
+    }
+    else {
+        if (apiKey)
+            headers["TestChimp-Api-Key"] = apiKey;
+        headers.Authorization = `Bearer ${bearer}`;
+    }
+    const botId = requestAuth?.botId && isValidBotId(requestAuth.botId) ? requestAuth.botId : envBotId();
+    if (botId)
+        headers["bot-id"] = botId;
+    return headers;
+}
+/** Non-2xx TestChimp API response (message format matches the historical client errors). */
+export class TestChimpHttpError extends Error {
+    status;
+    body;
+    constructor(status, statusText, body) {
+        super(`TestChimp API ${status} ${statusText}: ${body}`);
+        this.status = status;
+        this.body = body;
+        this.name = "TestChimpHttpError";
+    }
+}
+async function postJson(url, body, redirectHint) {
     const res = await fetch(url, {
         method: "POST",
         redirect: "manual",
-        headers: {
-            "Content-Type": "application/json",
-            "TestChimp-Api-Key": apiKey,
-        },
+        headers: buildRequestHeaders(),
         body: JSON.stringify(body ?? {}),
     });
     if (res.status >= 300 && res.status < 400) {
         const location = res.headers.get("location");
         const destination = location ? ` to ${location}` : "";
-        throw new Error(`TestChimp API redirected ${res.status}${destination}. Refusing to follow because an HTTP redirect may rewrite POST to GET; set TESTCHIMP_BACKEND_URL to the final HTTPS featureservice URL.`);
+        throw new Error(`TestChimp API redirected ${res.status}${destination}. Refusing to follow because an HTTP redirect may rewrite POST to GET; ${redirectHint}`);
     }
     const text = await res.text();
     if (!res.ok) {
-        throw new Error(`TestChimp API ${res.status} ${res.statusText}: ${text}`);
+        throw new TestChimpHttpError(res.status, res.statusText, text);
     }
     return text;
 }
+export async function postMcp(path, body) {
+    return postJson(`${getBackendUrl()}${path}`, body, "set TESTCHIMP_BACKEND_URL to the final HTTPS featureservice URL.");
+}
+/** POST to TestChimp ingress: a path under TESTCHIMP_INGRESS_URL, or an explicit absolute URL (e.g. ackUrl). */
+export async function postIngress(pathOrUrl, body) {
+    const url = /^[a-z][a-z0-9+.-]*:\/\//i.test(pathOrUrl.trim())
+        ? resolveIngressTargetUrl(pathOrUrl)
+        : `${getIngressUrl()}${pathOrUrl}`;
+    return postJson(url, body, "set TESTCHIMP_INGRESS_URL to the final HTTPS ingress URL.");
+}