@primitivedotdev/cli 0.25.2 → 0.26.1

package/bin/run.js

@@ -1,5 +1,11 @@
 #!/usr/bin/env node
 
 import { execute } from "@oclif/core";
+import { applyProxyAutoDetect } from "../dist/oclif/proxy-auto-detect.js";
+
+// Auto-set NODE_USE_ENV_PROXY=1 when HTTP(S)_PROXY is in the env.
+// Must run before any network init (e.g. before oclif loads commands
+// that touch fetch). See proxy-auto-detect.ts for the full rationale.
+applyProxyAutoDetect();
 
 await execute({ dir: import.meta.url });

package/dist/oclif/api-command.js

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { Command, Errors, Flags } from "@oclif/core";
 import { operations, PrimitiveApiClient } from "@primitivedotdev/sdk/api";
 import { deleteCliCredentials, resolveCliAuth, } from "./auth.js";
+import { maybeWriteFunctionEndpointRedirect, } from "./endpoints-test-redirect.js";
 export const API_ERROR_CODES = {
     accessDenied: "access_denied",
     authorizationPending: "authorization_pending",
@@ -722,6 +723,29 @@ export function createOperationCommand(operation) {
                         configDir: this.config.configDir,
                         payload: errorPayload,
                     });
+                    // Function-endpoint redirect. POST /endpoints/{id}/test on a
+                    // function-kind endpoint returns `not_found` even though the
+                    // same id IS visible in `endpoints:list-endpoints`. The hook
+                    // looks the id up via listEndpoints; if it matches a
+                    // function-kind row, it prints a redirect to
+                    // `functions:test-function` (with the function id) so the
+                    // caller does not have to translate the id themselves.
+                    // No-op for any other operation, any other error code, or
+                    // when the lookup misses or fails.
+                    const listClient = apiClient.client;
+                    const listEndpointsFn = () => operations.listEndpoints({
+                        client: listClient,
+                        responseStyle: "fields",
+                    });
+                    await maybeWriteFunctionEndpointRedirect({
+                        sdkName: operation.sdkName,
+                        errorCode: extractErrorCode(errorPayload),
+                        endpointId: typeof parsedFlags.id === "string" ? parsedFlags.id : undefined,
+                        listEndpoints: listEndpointsFn,
+                        writeStderr: (chunk) => {
+                            process.stderr.write(chunk);
+                        },
+                    });
                     process.exitCode = 1;
                     return;
                 }

package/dist/oclif/commands/functions-init.js

@@ -29,7 +29,7 @@ const SDK_VERSION_RANGE = "^0.25.0";
 // resolves at least v1.2.3, so the user does not silently downgrade
 // the bin under themselves. The lockstep test in functions-init.test.ts
 // enforces that invariant.
-const CLI_VERSION_RANGE = "^0.25.0";
+const CLI_VERSION_RANGE = "^0.26.0";
 // esbuild version range. Pinned to the latest stable major used
 // elsewhere in the Primitive codebase for bundling Workers-style
 // handlers. Caret range so patch fixes flow in automatically.
@@ -52,9 +52,11 @@ export function renderHandler() {
 import { createPrimitiveClient } from "@primitivedotdev/sdk/api";
 
 // TODO: replace with your verified sender address. Must be a domain
-// you own or your managed *.primitive.email subdomain. The
-// self-reply guard below compares incoming mail against this value
-// to avoid the handler replying to its own outbound traffic.
+// you own or your managed *.primitive.email subdomain. The isLoop
+// guard below compares incoming mail against this value (in addition
+// to the *.primitive.email suffix) so the handler does not reply to
+// its own outbound traffic when REPLY_FROM is on a non-managed
+// domain.
 const REPLY_FROM = "you@your-domain.primitive.email";
 
 interface EmailReceivedEvent {
@@ -64,6 +66,45 @@ interface EmailReceivedEvent {
   };
 }
 
+// Loop protection. A deployed Function receives catch-all inbound for
+// the managed *.primitive.email subdomain, which includes bounces and
+// auto-replies generated by its own outbound traffic. Without this
+// guard the handler can respond to its own bounces and create a
+// fan-out loop.
+//
+// The default check returns true when From is on any *.primitive.email
+// address (covers the managed subdomain catch-all, the simple
+// self-reply case, and bounces from mailer-daemon@*.primitive.email)
+// or when From contains REPLY_FROM as a case-insensitive substring.
+// Substring matching is deliberate so display-name forms like
+// "Support <support@example.com>" match a bare-address REPLY_FROM,
+// but it also accepts false positives where REPLY_FROM is a suffix
+// of another address (e.g. REPLY_FROM="info@x.com" matches
+// "mr.info@x.com"). For strict equality, parse the address out of the
+// header and exact-match against REPLY_FROM.
+//
+// Extend this helper if you need stricter detection. Common additions:
+//   - Match the org's signup / account-owner email (not auto-injected
+//     into env today; either bake it into a SIGNUP_EMAIL const or read
+//     it from a secret you set via \`primitive functions:set-secret\`).
+//   - Honor RFC 3834 auto-response headers: skip when
+//     \`event.email.headers["auto-submitted"]\` is anything other than
+//     "no", or when a \`List-Unsubscribe\` / \`Precedence: bulk\` header
+//     is present.
+//   - Track Message-ID / In-Reply-To chains to break ping-pong loops
+//     between two cooperating handlers on different domains.
+export function isLoop(event: EmailReceivedEvent): boolean {
+  // event.email.headers.from is the raw RFC 2822 header value, so it
+  // may be a bare address ("alice@example.com") or a display-name form
+  // ("Alice <alice@example.com>"). Lowercase substring checks match
+  // both shapes without needing to parse the bracketed address.
+  const from = event.email.headers.from?.toLowerCase() ?? "";
+  if (!from) return false;
+  if (from.includes(".primitive.email")) return true;
+  if (from.includes(REPLY_FROM.toLowerCase())) return true;
+  return false;
+}
+
 export default {
   async fetch(
     req: Request,
@@ -80,18 +121,12 @@ export default {
         return Response.json({ ok: true, skipped: event.event });
       }
 
-      // Self-reply guard: do not act on mail that this function itself
-      // sent. Without this, an outbound reply that gets forwarded back
-      // into the inbox would trigger another reply, and so on.
-      //
-      // event.email.headers.from is the raw RFC 2822 header value, so
-      // it may be either a bare address ("alice@example.com") or a
-      // display-name form ("Alice <alice@example.com>"). A substring
-      // check matches both. Tighten this predicate (e.g. parse the
-      // bracketed address) if you legitimately want to act on mail
-      // from your own domain.
-      if (event.email.headers.from?.includes(REPLY_FROM)) {
-        return Response.json({ ok: true, skipped: "self-reply" });
+      // Loop protection runs immediately after the event-type check
+      // (the gateway has already HMAC-verified the request before it
+      // reaches this handler). See isLoop above for what's covered and
+      // how to extend it.
+      if (isLoop(event)) {
+        return Response.json({ ok: true, skipped: "loop" });
       }
 
       const client = createPrimitiveClient({ apiKey: env.PRIMITIVE_API_KEY });

package/dist/oclif/commands/functions-test-function.js

@@ -0,0 +1,238 @@
+import { Command, Flags } from "@oclif/core";
+import { getEmail, PrimitiveApiClient, testFunction, } from "@primitivedotdev/sdk/api";
+import { API_BASE_URL_1_FLAG_DESCRIPTION, API_BASE_URL_2_FLAG_DESCRIPTION, baseUrlOverriddenFromFlags, extractErrorPayload, removeStaleSavedCredentialOnUnauthorized, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
+import { resolveCliAuth } from "../auth.js";
+import { DEFAULT_EMAIL_POLL_INTERVAL_SECONDS, fetchEmailSearchPage, sleep, } from "./emails-poll.js";
+// `primitive functions:test-function` is the agent-grade shortcut for
+// triggering a real round-trip and (optionally) waiting for the
+// function to actually run before exiting. The underlying
+// `POST /functions/{id}/test` operation only kicks off a synthetic
+// inbound through MX and returns the queued send id; AGX walkthroughs
+// flagged the missing wait-and-show-sends step as the single biggest
+// time-sink in the verification loop.
+//
+// Shapes:
+//   primitive functions:test-function --id <fn-id>
+//       Fire-and-forget. Returns the TestInvocationResult JSON
+//       (recipient, poll_since, watch_url). Same behavior as the
+//       auto-generated functions:test-function it replaces.
+//
+//   primitive functions:test-function --id <fn-id> --wait
+//       Blocks until the test inbound has arrived AND the function's
+//       webhook has fired (or --timeout elapses). Exits non-zero on
+//       timeout or on exhausted retries.
+//
+//   primitive functions:test-function --id <fn-id> --wait --show-sends
+//       Same as --wait, plus prints the inbound's `replies` array
+//       (every outbound the function emitted while processing the
+//       test inbound), with each send's id, status, recipient,
+//       subject, and queue id.
+//
+// The auto-generated functions:test-function entry is filtered out
+// of the generated-command set in oclif/index.ts so this hand-rolled
+// version owns the id.
+const DEFAULT_WAIT_TIMEOUT_SECONDS = 60;
+// Terminal states from the EmailWebhookStatus enum. `fired` means the
+// function returned 2xx; `exhausted` means all retries are spent and
+// the delivery is permanently failed. `pending` / `in_flight` /
+// `failed` are intermediate (`failed` is a temporary failure that may
+// retry into `fired` or eventually `exhausted`), so we keep polling.
+const TERMINAL_WEBHOOK_STATUSES = new Set(["fired", "exhausted"]);
+class FunctionsTestFunctionCommand extends Command {
+    static description = "Send a real test email through MX to trigger this function. With --wait, blocks until the function has processed the inbound; with --show-sends, also prints any outbound sends the function emitted in response.";
+    static summary = "Trigger a test invocation; with --wait, watch it land";
+    static examples = [
+        "<%= config.bin %> functions:test-function --id <fn-id>",
+        "<%= config.bin %> functions:test-function --id <fn-id> --local-part summarize",
+        "<%= config.bin %> functions:test-function --id <fn-id> --wait --show-sends",
+        "<%= config.bin %> functions:test-function --id <fn-id> --local-part summarize --wait --timeout 120",
+    ];
+    static flags = {
+        "api-key": Flags.string({
+            description: "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
+            env: "PRIMITIVE_API_KEY",
+        }),
+        "api-base-url-1": Flags.string({
+            description: API_BASE_URL_1_FLAG_DESCRIPTION,
+            env: "PRIMITIVE_API_BASE_URL_1",
+            hidden: true,
+        }),
+        "api-base-url-2": Flags.string({
+            description: API_BASE_URL_2_FLAG_DESCRIPTION,
+            env: "PRIMITIVE_API_BASE_URL_2",
+            hidden: true,
+        }),
+        id: Flags.string({
+            description: "Function id (UUID).",
+            required: true,
+        }),
+        "local-part": Flags.string({
+            description: "Override the synthetic local-part the test inbound is addressed to. Otherwise the runtime picks `__primitive_function_test+<random>`.",
+        }),
+        wait: Flags.boolean({
+            description: "Block until the function has processed the test inbound (webhook status is `fired` or `exhausted`) or --timeout elapses. Exits non-zero on timeout or on exhausted retries.",
+        }),
+        "show-sends": Flags.boolean({
+            description: "When the wait resolves, also print the outbound emails the function emitted while processing the test inbound (id, status, to, subject). Implies --wait.",
+        }),
+        timeout: Flags.integer({
+            default: DEFAULT_WAIT_TIMEOUT_SECONDS,
+            description: "Seconds to wait before exiting non-zero when --wait is set; 0 waits forever.",
+            min: 0,
+        }),
+        "poll-interval": Flags.integer({
+            default: DEFAULT_EMAIL_POLL_INTERVAL_SECONDS,
+            description: "Seconds between polls while waiting.",
+            min: 1,
+        }),
+        time: Flags.boolean({
+            description: TIME_FLAG_DESCRIPTION,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(FunctionsTestFunctionCommand);
+        // --show-sends implies --wait. You can't print what was sent
+        // until the function has actually run.
+        const shouldWait = flags.wait || flags["show-sends"];
+        const shouldShowSends = flags["show-sends"];
+        const baseUrlOverridden = baseUrlOverriddenFromFlags(flags);
+        const auth = resolveCliAuth({
+            apiKey: flags["api-key"],
+            apiBaseUrl1: flags["api-base-url-1"],
+            apiBaseUrl2: flags["api-base-url-2"],
+            configDir: this.config.configDir,
+        });
+        const apiClient = new PrimitiveApiClient({
+            apiKey: auth.apiKey,
+            apiBaseUrl1: auth.apiBaseUrl1,
+            apiBaseUrl2: auth.apiBaseUrl2,
+        });
+        await runWithTiming(flags.time, async () => {
+            // 1. Trigger the test send.
+            const triggerResult = await testFunction({
+                client: apiClient.client,
+                path: { id: flags.id },
+                body: flags["local-part"]
+                    ? { local_part: flags["local-part"] }
+                    : undefined,
+                responseStyle: "fields",
+            });
+            if (triggerResult.error) {
+                const payload = extractErrorPayload(triggerResult.error);
+                writeErrorWithHints(payload);
+                removeStaleSavedCredentialOnUnauthorized({
+                    auth,
+                    baseUrlOverridden,
+                    configDir: this.config.configDir,
+                    payload,
+                });
+                process.exitCode = 1;
+                return;
+            }
+            const invocation = triggerResult.data
+                .data;
+            if (!shouldWait) {
+                // Fire-and-forget path: print the TestInvocationResult JSON
+                // unchanged. Same shape the auto-generated command emitted.
+                this.log(JSON.stringify(invocation, null, 2));
+                return;
+            }
+            const startedAt = Date.now();
+            const timeoutMs = flags.timeout * 1000;
+            const pollIntervalMs = flags["poll-interval"] * 1000;
+            const isExpired = () => flags.timeout > 0 && Date.now() - startedAt > timeoutMs;
+            // 2. Wait for the test inbound to arrive. The synthetic
+            // recipient is unique per call (random suffix in the local-part
+            // unless --local-part overrides), so `to` + `since` uniquely
+            // identifies the test inbound row.
+            this.log(`Waiting for test inbound to arrive at ${invocation.to}...`);
+            let inboundId;
+            while (!isExpired()) {
+                const page = await fetchEmailSearchPage({
+                    apiClient,
+                    filters: { to: invocation.to },
+                    pageSize: 25,
+                    since: invocation.poll_since,
+                });
+                if (!page.ok) {
+                    const payload = extractErrorPayload(page.error);
+                    writeErrorWithHints(payload);
+                    removeStaleSavedCredentialOnUnauthorized({
+                        auth,
+                        baseUrlOverridden,
+                        configDir: this.config.configDir,
+                        payload,
+                    });
+                    process.exitCode = 1;
+                    return;
+                }
+                const found = page.rows[0];
+                if (found) {
+                    inboundId = found.id;
+                    break;
+                }
+                await sleep(pollIntervalMs);
+            }
+            if (!inboundId) {
+                this.error(`Timed out after ${flags.timeout}s waiting for test inbound ${invocation.to} to land. Browse ${invocation.watch_url} for the live view.`, { exit: 2 });
+            }
+            // 3. Wait for the function (webhook) to actually run. We poll
+            // the email-detail endpoint because it already carries both the
+            // webhook_status terminal state and the `replies` array we'll
+            // print under --show-sends. No second endpoint needed.
+            this.log(`Inbound landed (${inboundId}). Waiting for function to run...`);
+            let detail;
+            while (!isExpired()) {
+                const result = await getEmail({
+                    client: apiClient.client,
+                    path: { id: inboundId },
+                    responseStyle: "fields",
+                });
+                if (result.error) {
+                    const payload = extractErrorPayload(result.error);
+                    writeErrorWithHints(payload);
+                    removeStaleSavedCredentialOnUnauthorized({
+                        auth,
+                        baseUrlOverridden,
+                        configDir: this.config.configDir,
+                        payload,
+                    });
+                    process.exitCode = 1;
+                    return;
+                }
+                const fetched = result.data.data;
+                if (fetched.webhook_status &&
+                    TERMINAL_WEBHOOK_STATUSES.has(fetched.webhook_status)) {
+                    detail = fetched;
+                    break;
+                }
+                await sleep(pollIntervalMs);
+            }
+            if (!detail) {
+                this.error(`Timed out after ${flags.timeout}s waiting for function webhook to fire for inbound ${inboundId}. Browse ${invocation.watch_url} for the live view.`, { exit: 2 });
+            }
+            // 4. Emit the outcome.
+            const elapsedSeconds = Math.round((Date.now() - startedAt) / 1000);
+            const outcome = {
+                function_id: flags.id,
+                inbound_id: inboundId,
+                inbound_to: invocation.to,
+                webhook_status: detail.webhook_status,
+                webhook_attempt_count: detail.webhook_attempt_count,
+                webhook_last_status_code: detail.webhook_last_status_code,
+                webhook_last_error: detail.webhook_last_error,
+                elapsed_seconds: elapsedSeconds,
+            };
+            if (shouldShowSends) {
+                outcome.sent_emails = detail.replies;
+            }
+            this.log(JSON.stringify(outcome, null, 2));
+            // Exit non-zero when the function failed permanently so CI
+            // scripts can gate on the exit code.
+            if (detail.webhook_status === "exhausted") {
+                process.exitCode = 1;
+            }
+        });
+    }
+}
+export default FunctionsTestFunctionCommand;

package/dist/oclif/endpoints-test-redirect.js

@@ -0,0 +1,94 @@
+// `endpoints:test-endpoint` calls POST /endpoints/{id}/test. The server
+// implementation only resolves http-kind endpoints by url and returns
+// `not_found` for function-kind endpoints (where url is null). The same
+// function-endpoint id IS returned by `endpoints:list-endpoints`, so a
+// caller naturally tries it against test-endpoint and is greeted with
+// "Endpoint not found." Confusing.
+//
+// This helper closes the loop on the CLI side. After test-endpoint
+// returns `not_found`, the dispatcher in `api-command.ts` calls
+// `detectFunctionEndpoint` to see whether the id actually belongs to a
+// function-kind endpoint owned by the caller. If yes, we replace the
+// generic envelope with a redirect to `functions:test-function`,
+// surfacing both the endpoint id and the function id so the caller
+// does not have to look the function id up themselves.
+//
+// `kind` and `function_id` are not currently declared on the OpenAPI
+// `Endpoint` schema (so they are absent from the generated TS types),
+// but they are present in the JSON the server returns. We read them
+// off a loose Record<string, unknown> rather than relying on the
+// generated type, then sanity-check both fields before treating an
+// endpoint as a function endpoint.
+// Returns a `FunctionEndpointMatch` if and only if `endpointId` matches
+// an endpoint in the caller's `listEndpoints` response whose `kind` is
+// `function` and whose `function_id` is a non-empty string. Any other
+// outcome (no match, http-kind match, list call failure, missing
+// fields) returns `null` so the dispatcher falls back to surfacing the
+// original error envelope unchanged.
+export async function detectFunctionEndpoint(endpointId, listEndpoints) {
+    let response;
+    try {
+        response = await listEndpoints();
+    }
+    catch {
+        return null;
+    }
+    if (response.error)
+        return null;
+    const rows = response.data?.data;
+    if (!Array.isArray(rows))
+        return null;
+    // Relies on `listEndpoints` returning every endpoint in a single response.
+    // True today: the operation has `query?: never` in the generated types and
+    // the server returns all rows. If pagination is ever added, an endpoint on
+    // a later page would silently miss the redirect and reduce this to the
+    // original "Endpoint not found" UX. Update this call (filter-by-id or
+    // exhaust-pages) at the same time pagination lands on listEndpoints.
+    for (const row of rows) {
+        if (!row || typeof row !== "object")
+            continue;
+        if (row.id !== endpointId)
+            continue;
+        if (row.kind !== "function")
+            return null;
+        const functionId = row.function_id;
+        if (typeof functionId !== "string" || functionId.length === 0)
+            return null;
+        return { endpointId, functionId };
+    }
+    return null;
+}
+// Stderr copy printed when the dispatcher detects the
+// `endpoints:test-endpoint` `not_found` was really a function-kind
+// endpoint. Surfaces both ids so the caller does not have to run
+// `endpoints:list-endpoints` again to find the function_id. Returned
+// as a string rather than written here so the call site controls the
+// stream (stderr, in practice) and the tests can assert on the value.
+export function formatFunctionEndpointRedirect(match) {
+    return [
+        "This is a function endpoint. Function endpoints are tested differently. Run:",
+        "",
+        `    primitive functions:test-function --id ${match.functionId}`,
+        "",
+        `(pass the function id, not the endpoint id. endpoint_id=${match.endpointId} function_id=${match.functionId})`,
+    ].join("\n");
+}
+// Post-error hook: if the operation that just failed is
+// `endpoints:test-endpoint`, the failure is a `not_found`, and the
+// caller's id matches a function-kind endpoint they own, print a
+// redirect to `functions:test-function`. Returns the resolved match
+// so the caller (and the test) can assert the branch taken without
+// scraping stderr.
+export async function maybeWriteFunctionEndpointRedirect(inputs) {
+    if (inputs.sdkName !== "testEndpoint")
+        return null;
+    if (inputs.errorCode !== "not_found")
+        return null;
+    if (!inputs.endpointId)
+        return null;
+    const match = await detectFunctionEndpoint(inputs.endpointId, inputs.listEndpoints);
+    if (!match)
+        return null;
+    inputs.writeStderr(`${formatFunctionEndpointRedirect(match)}\n`);
+    return match;
+}

package/dist/oclif/index.js

@@ -9,6 +9,7 @@ import FunctionsDeployCommand from "./commands/functions-deploy.js";
 import FunctionsInitCommand from "./commands/functions-init.js";
 import FunctionsRedeployCommand from "./commands/functions-redeploy.js";
 import FunctionsSetSecretCommand from "./commands/functions-set-secret.js";
+import FunctionsTestFunctionCommand from "./commands/functions-test-function.js";
 import LoginCommand from "./commands/login.js";
 import LogoutCommand from "./commands/logout.js";
 import SendCommand from "./commands/send.js";
@@ -108,7 +109,17 @@ class CompletionCommand extends Command {
 function commandId(operation) {
     return `${operation.tagCommand}:${operation.command}`;
 }
-const generatedCommands = Object.fromEntries(operationManifest.map((operation) => [
+// Operation ids whose surface is owned by a hand-rolled command in
+// COMMANDS below. The auto-generated wrapper is filtered out so the
+// hand-rolled command owns the id without a name collision.
+const OVERRIDDEN_OPERATION_IDS = new Set([
+    // `functions:test-function` is hand-rolled to add --wait, --show-sends,
+    // and --timeout flags on top of the auto-generated POST /functions/{id}/test.
+    "functions:test-function",
+]);
+const generatedCommands = Object.fromEntries(operationManifest
+    .filter((operation) => !OVERRIDDEN_OPERATION_IDS.has(commandId(operation)))
+    .map((operation) => [
     commandId(operation),
     createOperationCommand(operation),
 ]));
@@ -171,5 +182,12 @@ export const COMMANDS = {
     // visible to the running handler requires a separate redeploy,
     // which this shortcut folds in via --redeploy.
     "functions:set-secret": FunctionsSetSecretCommand,
+    // `functions:test-function` is hand-rolled to add --wait, --show-sends,
+    // and --timeout on top of POST /functions/{id}/test. Without those
+    // flags, agents had to manually thread queued-send + emails:wait +
+    // emails:get-email + sending:list-sent-emails to verify a function
+    // ran and see what it emitted; AGX walkthroughs flagged that loop as
+    // the single biggest verification time-sink.
+    "functions:test-function": FunctionsTestFunctionCommand,
     ...generatedCommands,
 };

package/dist/oclif/proxy-auto-detect.js

@@ -0,0 +1,64 @@
+// Auto-detect proxy environment variables at CLI startup so users
+// behind a corporate proxy don't have to prefix every command with
+// `NODE_USE_ENV_PROXY=1`.
+//
+// Node 22+ ignores `HTTP_PROXY` / `HTTPS_PROXY` for the built-in
+// `fetch` / undici client unless `NODE_USE_ENV_PROXY=1` is set. That
+// turns a one-line proxy export into per-command friction: every CLI
+// invocation either inherits the prefix or fails with `ENETUNREACH`.
+//
+// This module is called once from `bin/run.js` before any network
+// initialization. If any of the standard proxy env vars are set AND
+// `NODE_USE_ENV_PROXY` is not already set explicitly, it sets it to
+// `1` for the current process and prints a one-time stderr hint so
+// the user knows what changed.
+//
+// An explicit `NODE_USE_ENV_PROXY` value (including `0`, `""`, etc.)
+// is always respected: if the user has chosen to disable proxy use
+// for this invocation, we don't override that choice.
+const PROXY_ENV_VARS = [
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "http_proxy",
+    "https_proxy",
+];
+// Module-level latch so the hint is printed at most once per process
+// even if `applyProxyAutoDetect` is called more than once (e.g. from
+// tests, or if a future entry point routes through it twice).
+let hintPrinted = false;
+// Test-only: reset the one-shot hint latch so each test case can
+// observe the first-call behavior independently.
+export function _resetHintLatchForTest() {
+    hintPrinted = false;
+}
+function detectProxyVars(env) {
+    return PROXY_ENV_VARS.filter((name) => {
+        const value = env[name];
+        return typeof value === "string" && value.length > 0;
+    });
+}
+export function applyProxyAutoDetect(options = {}) {
+    const env = options.env ?? process.env;
+    const stderr = options.stderr ?? process.stderr;
+    const detectedVars = detectProxyVars(env);
+    if (detectedVars.length === 0) {
+        return { applied: false, detectedVars: [], reason: "no_proxy_env" };
+    }
+    // Respect any explicit `NODE_USE_ENV_PROXY` value, including `0`
+    // or an empty string. The user has made a deliberate choice and
+    // auto-detection must not silently override it.
+    if (Object.hasOwn(env, "NODE_USE_ENV_PROXY")) {
+        return {
+            applied: false,
+            detectedVars,
+            reason: "node_use_env_proxy_already_set",
+        };
+    }
+    env.NODE_USE_ENV_PROXY = "1";
+    if (!hintPrinted) {
+        hintPrinted = true;
+        const names = detectedVars.join("/");
+        stderr.write(`primitive: proxy detected via ${names}, NODE_USE_ENV_PROXY=1 set automatically\n`);
+    }
+    return { applied: true, detectedVars, reason: "applied" };
+}

package/oclif.manifest.json

@@ -1036,6 +1036,103 @@
       "summary": "Write a function secret (optionally redeploying to push it live)",
       "enableJsonFlag": false
     },
+    "functions:test-function": {
+      "aliases": [],
+      "args": {},
+      "description": "Send a real test email through MX to trigger this function. With --wait, blocks until the function has processed the inbound; with --show-sends, also prints any outbound sends the function emitted in response.",
+      "examples": [
+        "<%= config.bin %> functions:test-function --id <fn-id>",
+        "<%= config.bin %> functions:test-function --id <fn-id> --local-part summarize",
+        "<%= config.bin %> functions:test-function --id <fn-id> --wait --show-sends",
+        "<%= config.bin %> functions:test-function --id <fn-id> --local-part summarize --wait --timeout 120"
+      ],
+      "flags": {
+        "api-key": {
+          "description": "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
+          "env": "PRIMITIVE_API_KEY",
+          "name": "api-key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-base-url-1": {
+          "description": "Override the primary API base URL. Internal testing only; not documented to customers.",
+          "env": "PRIMITIVE_API_BASE_URL_1",
+          "hidden": true,
+          "name": "api-base-url-1",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-base-url-2": {
+          "description": "Override the attachments-supporting send host base URL. Internal testing only; not documented to customers.",
+          "env": "PRIMITIVE_API_BASE_URL_2",
+          "hidden": true,
+          "name": "api-base-url-2",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "id": {
+          "description": "Function id (UUID).",
+          "name": "id",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "local-part": {
+          "description": "Override the synthetic local-part the test inbound is addressed to. Otherwise the runtime picks `__primitive_function_test+<random>`.",
+          "name": "local-part",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "wait": {
+          "description": "Block until the function has processed the test inbound (webhook status is `fired` or `exhausted`) or --timeout elapses. Exits non-zero on timeout or on exhausted retries.",
+          "name": "wait",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "show-sends": {
+          "description": "When the wait resolves, also print the outbound emails the function emitted while processing the test inbound (id, status, to, subject). Implies --wait.",
+          "name": "show-sends",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "timeout": {
+          "description": "Seconds to wait before exiting non-zero when --wait is set; 0 waits forever.",
+          "name": "timeout",
+          "default": 60,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "poll-interval": {
+          "description": "Seconds between polls while waiting.",
+          "name": "poll-interval",
+          "default": 2,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "functions:test-function",
+      "pluginAlias": "@primitivedotdev/cli",
+      "pluginName": "@primitivedotdev/cli",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Trigger a test invocation; with --wait, watch it land",
+      "enableJsonFlag": false
+    },
     "account:get-account": {
       "aliases": [],
       "args": {},
@@ -3624,83 +3721,6 @@
       "summary": "Set a secret by key",
       "enableJsonFlag": false
     },
-    "functions:test-function": {
-      "aliases": [],
-      "args": {},
-      "description": "Sends a real test email from a Primitive-controlled sender to a\nlocal-part on one of the org's verified inbound domains. By\ndefault the recipient is a synthetic\n`__primitive_function_test+<random>@<domain>` address that\nevery handler's catch-all routing receives identically; pass\n`local_part` to override and exercise routing logic that\nbranches on a specific recipient (the common pattern when one\nfunction handles multiple inboxes like `summarize@` and\n`action@`). The function fires through the normal MX delivery\npath, so reply / send-mail calls from inside the handler\nagainst the inbound's `email.id` work the same as in\nproduction. Returns immediately after the send is queued; the\ninvocation appears on the function's invocations list within a\nfew seconds.\n\nRequires that the function is currently `deployed`. Returns 422\nif the function is in `pending` or `failed` state, or if the\norg has no verified inbound domain to receive the test mail.\nReturns 400 if `local_part` is set to a value that does not\nmatch the local-part character set.\n",
-      "flags": {
-        "api-key": {
-          "description": "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
-          "env": "PRIMITIVE_API_KEY",
-          "name": "api-key",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "api-base-url-1": {
-          "description": "Override the primary API base URL. Internal testing only; not documented to customers.",
-          "env": "PRIMITIVE_API_BASE_URL_1",
-          "hidden": true,
-          "name": "api-base-url-1",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "api-base-url-2": {
-          "description": "Override the attachments-supporting send host base URL. Internal testing only; not documented to customers.",
-          "env": "PRIMITIVE_API_BASE_URL_2",
-          "hidden": true,
-          "name": "api-base-url-2",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "time": {
-          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
-          "name": "time",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "id": {
-          "description": "Resource UUID",
-          "name": "id",
-          "required": true,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "raw-body": {
-          "description": "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available.",
-          "name": "raw-body",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "body-file": {
-          "description": "Path to a JSON file used as the request body. Same role as --raw-body for callers passing a saved payload.",
-          "name": "body-file",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "local-part": {
-          "description": "Override the synthetic local-part. When set, the test email is sent to `<local_part>@<picked-domain>` instead of the default `__primitive_function_test+<random>@<picked-domain>`. Must start with an alphanumeric and contain only letters, digits, dots, plus signs, hyphens, or underscores; 1-64 characters total.",
-          "name": "local-part",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "functions:test-function",
-      "pluginAlias": "@primitivedotdev/cli",
-      "pluginName": "@primitivedotdev/cli",
-      "pluginType": "core",
-      "strict": true,
-      "summary": "Send a test invocation",
-      "enableJsonFlag": false
-    },
     "functions:update-function": {
       "aliases": [],
       "args": {},
@@ -4366,5 +4386,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.25.2"
+  "version": "0.26.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/cli",
-  "version": "0.25.2",
+  "version": "0.26.1",
   "description": "Official Primitive CLI: deploy Primitive Functions, send and inspect mail, manage endpoints, all from the terminal. Wraps the @primitivedotdev/sdk runtime client with one-shot commands.",
   "type": "module",
   "sideEffects": false,
@@ -35,7 +35,7 @@
         "description": "Claim, verify, and manage email domains"
       },
       "emails": {
-        "description": "List, inspect, and manage received emails. Use `primitive emails:latest` for a one-line-per-email summary of recent inbound mail."
+        "description": "List, inspect, and wait for received emails. `primitive emails:latest` lists the most recent inbound, `primitive emails:wait` blocks until matching inbound arrives (filter with --to/--from/--subject/--q; bounded by --timeout and --number; ideal for agents and CI), and `primitive emails:watch` streams new matches indefinitely for long-running terminals."
       },
       "sending": {
         "description": "Send outbound emails. For replies to inbound mail, use `sending:reply-to-email --id <inbound-id>` (threading and Re: subject derived server-side); for fresh sends, use `sending:send-email` or the `primitive send` shortcut."