@pyai/sdk 0.3.1 → 0.5.0

package/src/cli-config.ts

@@ -0,0 +1,283 @@
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, rename, unlink, type FileHandle } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export const DEFAULT_BASE_URL = "https://api.pyai.com";
+
+export class CliConfigError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "CliConfigError";
+    this.code = code;
+  }
+}
+
+export interface CliProfile {
+  api_key?: string;
+  base_url?: string;
+}
+
+export interface CliConfig {
+  version: 1;
+  active_profile: string | null;
+  profiles: Record<string, CliProfile>;
+}
+
+export interface ResolvedConfig {
+  apiKey?: string;
+  baseURL: string;
+  profile: string;
+  /** Provenance of the API key. The base URL is resolved independently. */
+  source: "explicit" | "environment" | "profile" | "none";
+}
+
+export interface ProfileSummary {
+  name: string;
+  active: boolean;
+  base_url: string;
+  has_api_key: boolean;
+}
+
+/** Keys are opaque: validation only ensures a bounded, header-safe value. */
+export function validateApiKey(input: string): string {
+  if (typeof input !== "string" || input.length === 0 || input.length > 512 || /[\s\p{Cc}]/u.test(input)) {
+    throw new CliConfigError("invalid_api_key", "API keys must contain 1–512 characters without whitespace or control characters.");
+  }
+  return input;
+}
+
+/** The SDK adds /v1, so accept both documented API base URL forms. */
+export function normalizeBaseURL(input: string): string {
+  const invalid = () => new CliConfigError("invalid_base_url", "Base URL must use HTTPS (or HTTP on localhost), without credentials, a query, or a fragment.");
+  if (typeof input !== "string" || !/^https?:\/\//i.test(input) || /[\s\p{Cc}?#]/u.test(input)) throw invalid();
+  let url: URL;
+  try {
+    url = new URL(input);
+  } catch {
+    throw invalid();
+  }
+  const authority = input.slice(input.indexOf("://") + 3).split("/")[0]!;
+  if (url.username || url.password || authority.includes("@")) throw invalid();
+  const hostname = url.hostname.toLowerCase();
+  const loopback = hostname === "localhost" || hostname === "localhost." || hostname === "[::1]" || /^127\.\d+\.\d+\.\d+$/.test(hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) throw invalid();
+  const path = url.pathname.replace(/\/+$/, "").replace(/\/v1$/, "").replace(/\/+$/, "");
+  return `${url.origin}${path}`;
+}
+
+export function validateProfileName(name: string): string {
+  if (typeof name !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(name)) {
+    throw new CliConfigError("invalid_profile", "Profile names must be 1–64 letters, numbers, dots, underscores, or hyphens, starting with a letter or number.");
+  }
+  return name;
+}
+
+function configDirectory(): string {
+  if (process.env.PYAI_CONFIG_DIR) return resolve(process.env.PYAI_CONFIG_DIR);
+  return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "pyai");
+}
+
+function emptyConfig(): CliConfig {
+  return { version: 1, active_profile: null, profiles: {} };
+}
+
+function hasCode(error: unknown, code: string): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function invalidConfig(): CliConfigError {
+  return new CliConfigError("config_invalid", "PyAI config.json is invalid or uses an unsupported version. Fix it or move it aside before retrying.");
+}
+
+function parseConfig(text: string): CliConfig {
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (!isRecord(parsed) || parsed.version !== 1 || !isRecord(parsed.profiles)) throw invalidConfig();
+    if (parsed.active_profile !== null && typeof parsed.active_profile !== "string") throw invalidConfig();
+    const profiles: Record<string, CliProfile> = {};
+    for (const [name, value] of Object.entries(parsed.profiles)) {
+      validateProfileName(name);
+      if (!isRecord(value) || Object.keys(value).some((key) => key !== "api_key" && key !== "base_url")) throw invalidConfig();
+      const profile: CliProfile = {};
+      if ("api_key" in value) profile.api_key = validateApiKey(value.api_key as string);
+      if ("base_url" in value) profile.base_url = normalizeBaseURL(value.base_url as string);
+      profiles[name] = profile;
+    }
+    if (parsed.active_profile !== null) {
+      validateProfileName(parsed.active_profile);
+      if (!Object.hasOwn(profiles, parsed.active_profile)) throw invalidConfig();
+    }
+    return { version: 1, active_profile: parsed.active_profile, profiles };
+  } catch {
+    // Never include JSON parser errors: they can contain the credential itself.
+    throw invalidConfig();
+  }
+}
+
+function verifyOwner(uid: number): void {
+  if (typeof process.getuid === "function" && uid !== process.getuid()) {
+    throw new CliConfigError("config_unsafe", "PyAI configuration must be owned by the current user.");
+  }
+}
+
+async function inspectDirectory(directory: string): Promise<boolean> {
+  try {
+    const stat = await lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+      throw new CliConfigError("config_unsafe", "PyAI configuration directory must be a real directory, not a symbolic link.");
+    }
+    verifyOwner(stat.uid);
+    return true;
+  } catch (error) {
+    if (hasCode(error, "ENOENT")) return false;
+    throw error;
+  }
+}
+
+async function readConfigAt(directory: string): Promise<CliConfig> {
+  let file: FileHandle | undefined;
+  try {
+    if (!(await inspectDirectory(directory))) return emptyConfig();
+    const path = join(directory, "config.json");
+    const stat = await lstat(path);
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+      throw new CliConfigError("config_unsafe", "PyAI config.json must be a regular file, not a symbolic link.");
+    }
+    file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const openedStat = await file.stat();
+    verifyOwner(openedStat.uid);
+    if (!openedStat.isFile() || openedStat.size > 1024 * 1024) throw invalidConfig();
+    return parseConfig(await file.readFile("utf8"));
+  } catch (error) {
+    if (hasCode(error, "ENOENT")) return emptyConfig();
+    if (error instanceof CliConfigError) throw error;
+    throw new CliConfigError("config_read_failed", "Unable to read PyAI config.json. Check the configuration directory and file permissions.");
+  } finally {
+    await file?.close();
+  }
+}
+
+/** Raw configuration is for internal use; use listProfiles for display. */
+export async function readConfig(): Promise<CliConfig> {
+  return readConfigAt(configDirectory());
+}
+
+async function writeConfigAt(directory: string, config: CliConfig): Promise<void> {
+  const temporary = join(directory, `.config-${randomUUID()}.tmp`);
+  let file: FileHandle | undefined;
+  try {
+    file = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+    await file.writeFile(`${JSON.stringify(config, null, 2)}\n`, "utf8");
+    await file.sync();
+    await file.close();
+    file = undefined;
+    await rename(temporary, join(directory, "config.json"));
+  } finally {
+    await file?.close();
+    await unlink(temporary).catch((error: unknown) => {
+      if (!hasCode(error, "ENOENT")) throw error;
+    });
+  }
+}
+
+async function updateConfig(update: (config: CliConfig) => void): Promise<void> {
+  const directory = configDirectory();
+  const lockPath = join(directory, "config.json.lock");
+  let lock: FileHandle | undefined;
+  try {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await inspectDirectory(directory);
+    await chmod(directory, 0o700);
+    // Every writer holds an exclusive lock across read, modification, and rename.
+    // A crashed writer leaves a visible lock instead of risking lost updates.
+    const deadline = Date.now() + 5000;
+    while (!lock) {
+      try {
+        lock = await open(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+      } catch (error) {
+        if (!hasCode(error, "EEXIST")) throw error;
+        if (Date.now() >= deadline) {
+          throw new CliConfigError("config_busy", "PyAI configuration is locked by another process. Retry shortly; remove config.json.lock only if no PyAI configuration command is running.");
+        }
+        await new Promise((resolve) => setTimeout(resolve, 25));
+      }
+    }
+    const config = await readConfigAt(directory);
+    update(config);
+    await writeConfigAt(directory, config);
+  } catch (error) {
+    if (error instanceof CliConfigError) throw error;
+    throw new CliConfigError("config_write_failed", "Unable to save PyAI configuration. Check the configuration directory and file permissions.");
+  } finally {
+    if (lock) {
+      await lock.close();
+      await unlink(lockPath);
+    }
+  }
+}
+
+/** Merge supplied fields and make this the active profile. */
+export async function saveProfile(name: string, fields: CliProfile): Promise<void> {
+  validateProfileName(name);
+  const normalized: CliProfile = {};
+  if (fields.api_key !== undefined) normalized.api_key = validateApiKey(fields.api_key);
+  if (fields.base_url !== undefined) normalized.base_url = normalizeBaseURL(fields.base_url);
+  await updateConfig((config) => {
+    const previous = Object.hasOwn(config.profiles, name) ? config.profiles[name] : undefined;
+    config.profiles[name] = { ...previous, ...normalized };
+    config.active_profile = name;
+  });
+}
+
+export async function removeProfile(name: string): Promise<void> {
+  validateProfileName(name);
+  await updateConfig((config) => {
+    if (!Object.hasOwn(config.profiles, name)) throw new CliConfigError("profile_not_found", "The selected PyAI profile does not exist. Use auth login to create it.");
+    delete config.profiles[name];
+    if (config.active_profile === name) {
+      config.active_profile = Object.hasOwn(config.profiles, "default") ? "default" : Object.keys(config.profiles).sort()[0] ?? null;
+    }
+  });
+}
+
+export async function useProfile(name: string): Promise<void> {
+  validateProfileName(name);
+  await updateConfig((config) => {
+    if (!Object.hasOwn(config.profiles, name)) throw new CliConfigError("profile_not_found", "The selected PyAI profile does not exist. Use auth login to create it.");
+    config.active_profile = name;
+  });
+}
+
+export async function resolveConfig(options: { apiKey?: string; baseURL?: string; profile?: string; allowMissingProfile?: boolean; ignoreApiKey?: boolean } = {}): Promise<ResolvedConfig> {
+  const config = await readConfig();
+  const selected = options.profile ?? (process.env.PYAI_PROFILE || undefined);
+  const profile = validateProfileName(selected ?? config.active_profile ?? "default");
+  const stored = Object.hasOwn(config.profiles, profile) ? config.profiles[profile] : undefined;
+  if (selected !== undefined && !stored && !options.allowMissingProfile) {
+    throw new CliConfigError("profile_not_found", "The selected PyAI profile does not exist. Use auth login to create it.");
+  }
+  const environmentKey = process.env.PYAI_API_KEY || undefined;
+  const apiKey = options.ignoreApiKey ? undefined : options.apiKey ?? environmentKey ?? stored?.api_key;
+  const baseURL = normalizeBaseURL(options.baseURL ?? (process.env.PYAI_BASE_URL || undefined) ?? stored?.base_url ?? DEFAULT_BASE_URL);
+  const source = options.ignoreApiKey ? "none" : options.apiKey !== undefined ? "explicit" : environmentKey !== undefined ? "environment" : stored?.api_key !== undefined ? "profile" : "none";
+  return { ...(apiKey !== undefined ? { apiKey: validateApiKey(apiKey) } : {}), baseURL, profile, source };
+}
+
+/** Never reveal a key, including its prefix or suffix, in profile listings. */
+export async function listProfiles(): Promise<ProfileSummary[]> {
+  const config = await readConfig();
+  return Object.keys(config.profiles).sort().map((name) => ({
+    name,
+    active: config.active_profile === name,
+    base_url: config.profiles[name]!.base_url ?? DEFAULT_BASE_URL,
+    has_api_key: config.profiles[name]!.api_key !== undefined,
+  }));
+}

package/src/cli-dx.ts

@@ -0,0 +1,33 @@
+/** Offline discovery and copyable workflows; recipes never execute commands. */
+export const aliases: Record<string, string> = Object.assign(Object.create(null), {
+  login: "auth login", logout: "auth logout", whoami: "auth status", use: "profiles use",
+  say: "speak", hear: "transcribe",
+});
+export const shortFlags: Record<string, string> = Object.assign(Object.create(null), {
+  "-h": "--help", "-v": "--version", "-o": "--out", "-f": "--file",
+  "-t": "--text", "-p": "--profile", "-j": "--json",
+});
+export interface Recipe { name: string; title: string; description: string; commands: string[]; notes: string[] }
+export const recipes: Recipe[] = [
+  { name: "auth", title: "Sign in and check access", description: "Save a named profile and inspect the current credential.",
+    commands: ["pyai login --profile work", "pyai whoami --profile work --json", "pyai use work"],
+    notes: ["Browser login requires the CLI login API and console deployment. Use --no-browser on remote terminals.", "For unattended runs, supply PYAI_API_KEY through the environment. Environment values override saved profiles."] },
+  { name: "speak", title: "Turn text into audio", description: "Speak a line, narrate a text file, or pipe text from another command.",
+    commands: ['pyai speak "Hello from PyAI" -o hello.wav', "pyai speak --text-file script.txt -o narration.wav", 'printf "Build complete.\\n" | pyai speak -o build.wav'],
+    notes: ["Files must have a new output name unless you pass --force. Default output is pyai-speak.wav.", "Use pyai voices --json to choose a current voice; add --voice ID."] },
+  { name: "transcribe", title: "Get a transcript", description: "Print just the words or retain structured output for automation.",
+    commands: ["pyai hear call.wav --text-only > transcript.txt", "pyai transcribe call.wav --json > transcript.json", 'pyai transcribe "https://example.com/call.wav" --wait --text-only'],
+    notes: ["Replace the example URL with a reachable audio URL. Hosted audio uses an asynchronous job.", "--text-only requires --wait for URLs; large offloaded results retain a job reference instead of following an external URL with credentials."] },
+  { name: "dub", title: "Dub audio in one command", description: "Submit a Dub job, wait for completion, and download the audio.",
+    commands: ["pyai request GET /healthz/dub --json", "pyai dub original.wav --from en --to hi -o dubbed.wav --wait-timeout 600"],
+    notes: ["Check the live health response for available input and output languages before choosing them. Requires dub:render.", "On a timeout, resume with pyai dub wait JOB_ID and pyai dub audio JOB_ID -o dubbed.wav; do not resubmit the source."] },
+  { name: "agent", title: "Start a project for a coding agent", description: "Create local context and request examples without a network call.",
+    commands: ["pyai init voice-demo --template agent", "pyai schema agents create --json", "pyai agents create --data @voice-demo/agent.json --dry-run --json"],
+    notes: ["The destination directory must be new. The starter writes no credentials and installs no dependencies.", "Read the generated PYAI.md first. Fetch live OpenAPI before adding fields or endpoints; remove --dry-run only when ready to create the profile."] },
+  { name: "inspect", title: "Discover before you call", description: "Inspect commands offline and fetch the current API contract.",
+    commands: ["pyai schema speak --json", "pyai schema agents --json", "pyai schema --openapi --json > openapi.json", "pyai request GET /v1/me --json"],
+    notes: ["Local schema and recipes work without credentials. Live OpenAPI needs a network connection but no API key.", "The CLI manages Agent profiles; use the SDK or WebSocket API for a live Omni audio session."] },
+  { name: "ci", title: "Use PyAI in a build", description: "Check access and produce an audio artifact with machine-readable output.",
+    commands: ["pyai whoami --json", 'pyai speak "Your build is ready" -o build.wav --json', "pyai doctor --json"],
+    notes: ["Set PYAI_API_KEY through the CI secret store; do not put it in source or shell arguments.", "doctor synthesizes and transcribes a sample, which consumes usage. Use whoami for an authentication-only check.", "Install the CLI with npm install -g @pyai/sdk@0.5.0 and pin that version in repeatable builds."] },
+];

package/src/cli-http.ts

@@ -0,0 +1,273 @@
+/** HTTP transport for the CLI. SDK request behavior remains independent. */
+
+export class CliError extends Error {
+  readonly code: string;
+  readonly exitCode: number;
+  readonly details?: Record<string, unknown>;
+
+  constructor(code: string, message: string, exitCode = 1, details?: Record<string, unknown>) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+    this.exitCode = exitCode;
+    this.details = details;
+  }
+}
+
+export interface CliHttpOptions {
+  baseURL: string;
+  apiKey?: string;
+  timeoutMs?: number;
+  maxRetries?: number;
+}
+
+export interface CliRequestOptions {
+  json?: unknown;
+  body?: BodyInit;
+  headers?: Record<string, string>;
+  auth?: boolean;
+  timeoutMs?: number;
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown> : {};
+}
+
+function string(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function timeout(value: number): number {
+  if (!Number.isFinite(value) || value <= 0 || value > 2_147_483_647) {
+    throw new CliError("invalid_timeout", "Request timeout must be a positive number of milliseconds (at most 2147483647).", 2);
+  }
+  return value;
+}
+
+function retryDelay(header: string | null, attempt: number): number {
+  if (header !== null) {
+    const seconds = Number(header);
+    if (header.trim() !== "" && Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+    const date = Date.parse(header);
+    if (Number.isFinite(date)) return Math.max(0, date - Date.now());
+  }
+  return Math.min(200 * 2 ** attempt, 2000);
+}
+
+function pause(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) { reject(signal.reason); return; }
+    const finish = () => { signal.removeEventListener("abort", abort); resolve(); };
+    const timer = setTimeout(finish, ms);
+    const abort = () => { clearTimeout(timer); signal.removeEventListener("abort", abort); reject(signal.reason); };
+    signal.addEventListener("abort", abort, { once: true });
+  });
+}
+
+export class CliHttp {
+  private readonly baseURL: URL;
+  private readonly apiKey?: string;
+  private readonly timeoutMs: number;
+  private readonly maxRetries: number;
+
+  constructor(options: CliHttpOptions) {
+    try { this.baseURL = new URL(options.baseURL); }
+    catch { throw new CliError("invalid_base_url", "API base URL must be an absolute HTTP or HTTPS URL.", 2); }
+    if (!["http:", "https:"].includes(this.baseURL.protocol) || this.baseURL.username || this.baseURL.password
+      || this.baseURL.search || this.baseURL.hash) {
+      throw new CliError("invalid_base_url", "API base URL must use HTTP or HTTPS without credentials, a query, or a fragment.", 2);
+    }
+    this.apiKey = options.apiKey;
+    this.timeoutMs = timeout(options.timeoutMs ?? 30_000);
+    this.maxRetries = options.maxRetries ?? 2;
+    if (!Number.isSafeInteger(this.maxRetries) || this.maxRetries < 0) {
+      throw new CliError("invalid_retries", "Maximum retries must be a non-negative integer.", 2);
+    }
+  }
+
+  request(method: string, path: string, options: CliRequestOptions = {}): Promise<Response> {
+    return this.execute(method, path, options, false) as Promise<Response>;
+  }
+
+  json(method: string, path: string, options: CliRequestOptions = {}): Promise<any> {
+    return this.execute(method, path, options, true);
+  }
+
+  /** Validate previews through the same URL rules used by live requests. */
+  validatePath(path: string): string {
+    return this.url(path).toString();
+  }
+
+  private redact(value: string): string {
+    let result = value;
+    if (this.apiKey) {
+      result = result.split(this.apiKey).join("[REDACTED]");
+      result = result.split(encodeURIComponent(this.apiKey)).join("[REDACTED]");
+    }
+    return result.replace(/\bBearer\s+[^\s"',;<>]+/gi, "Bearer [REDACTED]")
+      .replace(/\bpyai_(?:test|live)_[A-Za-z0-9._~-]+/g, "[REDACTED]");
+  }
+
+  private url(path: string): URL {
+    if (!/^\/(?![\/\\])/.test(path) || /[\\\u0000-\u0020\u007f#]/.test(path)) {
+      throw new CliError("invalid_path", "API path must begin with a single / and contain no backslashes, whitespace, or fragment.", 2);
+    }
+    if (path.split("?", 1)[0]!.split("/").some((segment) => [".", ".."].includes(segment.replace(/%2e/gi, ".")))) {
+      throw new CliError("invalid_path", "API path must not contain . or .. traversal segments.", 2);
+    }
+    const url = new URL(this.baseURL.toString().replace(/\/+$/, "") + path);
+    if (url.origin !== this.baseURL.origin || url.username || url.password) {
+      throw new CliError("invalid_path", "API path must remain on the configured API origin.", 2);
+    }
+    for (const name of url.searchParams.keys()) {
+      if (name.toLowerCase() === "api_key") {
+        throw new CliError("unsafe_query", "Pass API keys through authentication, never through a URL query.", 2);
+      }
+    }
+    return url;
+  }
+
+  private transportError(error: unknown, signal: AbortSignal): CliError {
+    if (signal.aborted && signal.reason instanceof CliError) return signal.reason;
+    if (error instanceof CliError) return error;
+    const message = error instanceof Error ? error.message : "Connection failed.";
+    return new CliError("network_error", this.redact(`Network request failed: ${message}`), 4);
+  }
+
+  private async apiError(response: Response): Promise<CliError> {
+    const text = await response.text();
+    let payload: Record<string, unknown> = {};
+    try { payload = record(JSON.parse(text)); } catch { /* Non-JSON gateways still expose their HTTP status. */ }
+    const nested = record(payload.error);
+    const problemType = string(payload.type);
+    const problemCode = problemType?.match(/^https?:\/\/[^/]+\/problems\/([^/?#]+)$/)?.[1];
+    const fallbackCode = response.status === 401 ? "unauthorized" : response.status === 403 ? "forbidden" : `http_${response.status}`;
+    const code = this.redact(string(nested.code) ?? string(payload.code) ?? problemCode ?? fallbackCode);
+    const message = this.redact(string(nested.message) ?? string(payload.detail) ?? string(payload.message)
+      ?? string(payload.title) ?? `API request failed (HTTP ${response.status}).`);
+    const details: Record<string, unknown> = { status: response.status };
+    const requestId = response.headers.get("x-request-id") ?? response.headers.get("request-id")
+      ?? string(payload.request_id) ?? string(nested.request_id);
+    const retryAfter = response.headers.get("retry-after") ?? string(payload.retry_after);
+    if (requestId) details.request_id = this.redact(requestId);
+    if (retryAfter !== undefined && retryAfter !== null) details.retry_after = this.redact(retryAfter);
+    if (string(nested.type)) details.type = this.redact(nested.type as string);
+    if (typeof nested.param === "string") details.param = this.redact(nested.param);
+    return new CliError(code, message, response.status === 401 || response.status === 403 ? 3 : 1, details);
+  }
+
+  /** Preserve the request deadline after headers, including paused or stalled downloads. */
+  private stream(response: Response, abort: AbortController, cleanup: () => void): Response {
+    if (!response.body) { cleanup(); return response; }
+    const reader = response.body.getReader();
+    let finished = false;
+    let stop: () => void;
+    const finish = () => {
+      finished = true;
+      abort.signal.removeEventListener("abort", stop);
+      cleanup();
+    };
+    const body = new ReadableStream<Uint8Array>({
+      start: (controller) => {
+        stop = () => {
+          if (finished) return;
+          finish();
+          controller.error(this.transportError(abort.signal.reason, abort.signal));
+          void reader.cancel().catch(() => {});
+        };
+        abort.signal.addEventListener("abort", stop, { once: true });
+        if (abort.signal.aborted) stop();
+      },
+      pull: async (controller) => {
+        try {
+          const result = await reader.read();
+          if (finished) return;
+          if (result.done) { finish(); controller.close(); }
+          else controller.enqueue(result.value);
+        } catch (error) {
+          if (finished) return;
+          finish();
+          controller.error(this.transportError(error, abort.signal));
+        }
+      },
+      cancel: async (reason) => {
+        finish();
+        abort.abort();
+        await reader.cancel(reason).catch(() => {});
+      },
+    });
+    const result = new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+    Object.defineProperties(result, {
+      url: { value: response.url }, redirected: { value: response.redirected }, type: { value: response.type },
+    });
+    return result;
+  }
+
+  private async execute(method: string, path: string, options: CliRequestOptions, readJson: boolean): Promise<unknown> {
+    const url = this.url(path);
+    method = method.toUpperCase();
+    if (!/^[A-Z]+$/.test(method) || ["CONNECT", "TRACE", "TRACK"].includes(method)) {
+      throw new CliError("invalid_method", "Unsupported HTTP method.", 2);
+    }
+    if (options.auth !== false && !this.apiKey) {
+      throw new CliError("missing_api_key", "No API key. Set PYAI_API_KEY, configure a profile, or pass --api-key.", 3);
+    }
+    if (options.json !== undefined && options.body !== undefined) {
+      throw new CliError("invalid_body", "Provide either a JSON body or a raw body, not both.", 2);
+    }
+    let headers: Headers;
+    let body: BodyInit | undefined;
+    try {
+      headers = new Headers(options.headers);
+      headers.delete("authorization");
+      headers.delete("x-api-key");
+      if (options.auth !== false) headers.set("authorization", `Bearer ${this.apiKey}`);
+      body = options.json === undefined ? options.body : JSON.stringify(options.json);
+      if (options.json !== undefined) headers.set("content-type", "application/json");
+    } catch { throw new CliError("invalid_request", "Request headers or JSON body are invalid.", 2); }
+    if ((method === "GET" || method === "HEAD") && body !== undefined) {
+      throw new CliError("invalid_body", `${method} requests cannot have a body.`, 2);
+    }
+    const duration = timeout(options.timeoutMs ?? this.timeoutMs);
+    const deadline = Date.now() + duration;
+    const abort = new AbortController();
+    const timer = setTimeout(() => abort.abort(new CliError("timeout", `Request timed out after ${duration} ms.`, 4)), duration);
+    const cleanup = () => clearTimeout(timer);
+    const retries = method === "GET" || method === "HEAD" ? this.maxRetries : 0;
+    let streaming = false;
+    try {
+      for (let attempt = 0; ; attempt++) {
+        let delay = retryDelay(null, attempt);
+        try {
+          const response = await fetch(url, { method, headers, body, signal: abort.signal, redirect: "manual" });
+          if (response.status >= 300 && response.status < 400) {
+            await response.body?.cancel();
+            throw new CliError("redirect_refused", "API redirects are refused. Configure the final API base URL directly.", 1, { status: response.status });
+          }
+          if ((response.status === 429 || response.status >= 500) && attempt < retries) {
+            delay = retryDelay(response.headers.get("retry-after"), attempt);
+            await response.body?.cancel();
+          } else {
+            if (!response.ok) throw await this.apiError(response);
+            if (readJson) {
+              const text = await response.text();
+              if (!text.trim()) return null;
+              try { return JSON.parse(text); }
+              catch { throw new CliError("invalid_response", "API returned an invalid JSON response.", 1, { status: response.status }); }
+            }
+            const result = this.stream(response, abort, cleanup);
+            streaming = response.body !== null;
+            return result;
+          }
+        } catch (error) {
+          const failure = this.transportError(error, abort.signal);
+          if (abort.signal.aborted || failure.code !== "network_error" || failure.exitCode !== 4 || attempt >= retries) throw failure;
+        }
+        await pause(Math.min(delay, Math.max(0, deadline - Date.now())), abort.signal);
+      }
+    } finally {
+      if (!streaming) cleanup();
+    }
+  }
+}