@arizeai/phoenix-cli 1.5.2 → 1.6.0

package/build/pxi/inkMarkdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inkMarkdown.d.ts","sourceRoot":"","sources":["../../src/pxi/inkMarkdown.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,EACvB,QAAQ,EACR,cAAc,GACf,EAAE;IACD,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,qBAMA"}

package/build/pxi/inkMarkdown.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Text } from "ink";
+import { formatMarkdownForTerminal } from "./markdown.js";
+/**
+ * Renders markdown text as styled terminal output inside an Ink `<Text>`.
+ *
+ * Modeled on the `ink-markdown` component
+ * (https://github.com/cameronhunter/ink-markdown, MIT). That package is
+ * published as CommonJS and `require()`s Ink internally, which is incompatible
+ * with Ink 6 (pure ESM with top-level await — `require()` throws
+ * `ERR_REQUIRE_ASYNC_MODULE`). We keep its API — `<Markdown>{text}</Markdown>` —
+ * but render through {@link formatMarkdownForTerminal}, which uses the current
+ * `marked` + `marked-terminal` API and preserves our width-aware table layout.
+ */
+export function Markdown({ children, phoenixBaseUrl, }) {
+    const rendered = formatMarkdownForTerminal({
+        text: children,
+        phoenixBaseUrl,
+    });
+    return _jsx(Text, { children: rendered || " " });
+}
+//# sourceMappingURL=inkMarkdown.js.map

package/build/pxi/inkMarkdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inkMarkdown.js","sourceRoot":"","sources":["../../src/pxi/inkMarkdown.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,KAAK,CAAC;AAG3B,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,QAAQ,CAAC,EACvB,QAAQ,EACR,cAAc,GAIf;IACC,MAAM,QAAQ,GAAG,yBAAyB,CAAC;QACzC,IAAI,EAAE,QAAQ;QACd,cAAc;KACf,CAAC,CAAC;IACH,OAAO,KAAC,IAAI,cAAE,QAAQ,IAAI,GAAG,GAAQ,CAAC;AACxC,CAAC"}

package/build/pxi/markdown.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Resolve a markdown link/image href against the Phoenix base URL.
+ *
+ * Absolute, fragment, and protocol-relative hrefs pass through unchanged, as
+ * does any href when no (valid) base URL is configured. Root-relative paths
+ * (`/foo`) are joined onto the base URL's path prefix so a Phoenix deployed
+ * under a sub-path still produces correct links; other relative paths resolve
+ * against the base path as usual.
+ */
+export declare function resolvePhoenixMarkdownHref({ href, phoenixBaseUrl, }: {
+    href: string;
+    phoenixBaseUrl?: string;
+}): string;
+/**
+ * Render markdown to terminal-styled text. The main entry point for callers:
+ * defaults `maxWidth` to the current terminal column count and absolutizes
+ * relative links against `phoenixBaseUrl` when provided.
+ */
+export declare function formatMarkdownForTerminal({ text, maxWidth, phoenixBaseUrl, }: {
+    text: string;
+    maxWidth?: number;
+    phoenixBaseUrl?: string;
+}): string;
+//# sourceMappingURL=markdown.d.ts.map

package/build/pxi/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/pxi/markdown.ts"],"names":[],"mappings":"AAmDA;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,IAAI,EACJ,cAAc,GACf,EAAE;IACD,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,MAAM,CAkBT;AA2DD;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,IAAI,EACJ,QAA6C,EAC7C,cAAc,GACf,EAAE;IACD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,MAAM,CAET"}

package/build/pxi/markdown.js

@@ -0,0 +1,115 @@
+import { Marked } from "marked";
+import { markedTerminal } from "marked-terminal";
+/**
+ * Render assistant markdown for the terminal.
+ *
+ * Wraps `marked` + `marked-terminal` to turn markdown into ANSI-styled text
+ * that fits the current terminal width. It also rewrites relative links against
+ * the Phoenix base URL so links the agent emits (e.g. `/projects/123`) become
+ * clickable absolute URLs pointing at the right Phoenix instance.
+ */
+// There is only ever one terminal width in play at a time, so a single cached
+// renderer is enough to avoid re-registering the marked-terminal extension on
+// every render. Rebuild it only when the width actually changes (e.g. resize),
+// which keeps this bounded instead of accumulating an entry per resize.
+let cachedRenderer = null;
+/**
+ * Whether an href should be left untouched: fragment (`#`), protocol-relative
+ * (`//`), or already carrying a scheme (`https:`, `mailto:`, …). Only truly
+ * relative paths get resolved against the Phoenix base URL.
+ */
+function isAbsoluteOrSpecialHref(href) {
+    return (href.startsWith("#") ||
+        href.startsWith("//") ||
+        /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(href));
+}
+function getPhoenixBaseUrl(phoenixBaseUrl) {
+    const trimmedBaseUrl = phoenixBaseUrl?.trim();
+    if (!trimmedBaseUrl) {
+        return null;
+    }
+    try {
+        return new URL(trimmedBaseUrl);
+    }
+    catch {
+        return null;
+    }
+}
+function getOrigin(url) {
+    return `${url.protocol}//${url.host}`;
+}
+function getNormalizedBasePath(url) {
+    return url.pathname === "/" ? "" : url.pathname.replace(/\/+$/, "");
+}
+/**
+ * Resolve a markdown link/image href against the Phoenix base URL.
+ *
+ * Absolute, fragment, and protocol-relative hrefs pass through unchanged, as
+ * does any href when no (valid) base URL is configured. Root-relative paths
+ * (`/foo`) are joined onto the base URL's path prefix so a Phoenix deployed
+ * under a sub-path still produces correct links; other relative paths resolve
+ * against the base path as usual.
+ */
+export function resolvePhoenixMarkdownHref({ href, phoenixBaseUrl, }) {
+    const trimmedHref = href.trim();
+    if (!trimmedHref || isAbsoluteOrSpecialHref(trimmedHref)) {
+        return href;
+    }
+    const baseUrl = getPhoenixBaseUrl(phoenixBaseUrl);
+    if (!baseUrl) {
+        return href;
+    }
+    const origin = getOrigin(baseUrl);
+    const basePath = getNormalizedBasePath(baseUrl);
+    if (trimmedHref.startsWith("/")) {
+        return new URL(`${basePath}${trimmedHref}`, origin).toString();
+    }
+    return new URL(trimmedHref, `${origin}${basePath}/`).toString();
+}
+function absolutizeMarkdownLinkToken({ token, phoenixBaseUrl, }) {
+    if (token.type !== "link" && token.type !== "image") {
+        return;
+    }
+    token.href = resolvePhoenixMarkdownHref({
+        href: token.href,
+        phoenixBaseUrl,
+    });
+}
+/**
+ * Get a `marked` renderer configured for the given terminal width, reusing the
+ * cached one when the width is unchanged (see {@link cachedRenderer}). Text
+ * reflow is disabled so the agent's own line breaks are preserved.
+ */
+function getMarkedRenderer(width) {
+    if (cachedRenderer?.width === width) {
+        return cachedRenderer.renderer;
+    }
+    const renderer = new Marked();
+    renderer.use(markedTerminal(Number.isFinite(width) ? { width, reflowText: false } : {}));
+    cachedRenderer = { width, renderer };
+    return renderer;
+}
+function renderMarkdownBlock({ text, maxWidth, phoenixBaseUrl, }) {
+    if (text.trim() === "") {
+        return "";
+    }
+    const renderer = getMarkedRenderer(maxWidth);
+    // The marked-terminal extension renders synchronously, so `parse` returns a
+    // string (marked's types don't narrow this from the `async: false` option).
+    const rendered = renderer.parse(text, {
+        async: false,
+        walkTokens: (token) => {
+            absolutizeMarkdownLinkToken({ token, phoenixBaseUrl });
+        },
+    });
+    return rendered.replace(/\n+$/, "");
+}
+/**
+ * Render markdown to terminal-styled text. The main entry point for callers:
+ * defaults `maxWidth` to the current terminal column count and absolutizes
+ * relative links against `phoenixBaseUrl` when provided.
+ */
+export function formatMarkdownForTerminal({ text, maxWidth = process.stdout.columns ?? Infinity, phoenixBaseUrl, }) {
+    return renderMarkdownBlock({ text, maxWidth, phoenixBaseUrl });
+}
+//# sourceMappingURL=markdown.js.map

package/build/pxi/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../../src/pxi/markdown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAc,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;GAOG;AAEH,8EAA8E;AAC9E,8EAA8E;AAC9E,+EAA+E;AAC/E,wEAAwE;AACxE,IAAI,cAAc,GAA+C,IAAI,CAAC;AAEtE;;;;GAIG;AACH,SAAS,uBAAuB,CAAC,IAAY;IAC3C,OAAO,CACL,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QACpB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QACrB,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC,CACtC,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,cAAuB;IAChD,MAAM,cAAc,GAAG,cAAc,EAAE,IAAI,EAAE,CAAC;IAC9C,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,cAAc,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAAC,GAAQ;IACzB,OAAO,GAAG,GAAG,CAAC,QAAQ,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC;AACxC,CAAC;AAED,SAAS,qBAAqB,CAAC,GAAQ;IACrC,OAAO,GAAG,CAAC,QAAQ,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CAAC,EACzC,IAAI,EACJ,cAAc,GAIf;IACC,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAChC,IAAI,CAAC,WAAW,IAAI,uBAAuB,CAAC,WAAW,CAAC,EAAE,CAAC;QACzD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,OAAO,GAAG,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAClD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,QAAQ,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAChD,IAAI,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAChC,OAAO,IAAI,GAAG,CAAC,GAAG,QAAQ,GAAG,WAAW,EAAE,EAAE,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC;IACjE,CAAC;IAED,OAAO,IAAI,GAAG,CAAC,WAAW,EAAE,GAAG,MAAM,GAAG,QAAQ,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;AAClE,CAAC;AAED,SAAS,2BAA2B,CAAC,EACnC,KAAK,EACL,cAAc,GAIf;IACC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QACpD,OAAO;IACT,CAAC;IACD,KAAK,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACtC,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,cAAc;KACf,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,KAAa;IACtC,IAAI,cAAc,EAAE,KAAK,KAAK,KAAK,EAAE,CAAC;QACpC,OAAO,cAAc,CAAC,QAAQ,CAAC;IACjC,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,MAAM,EAAE,CAAC;IAC9B,QAAQ,CAAC,GAAG,CACV,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAC3E,CAAC;IACF,cAAc,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;IACrC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,mBAAmB,CAAC,EAC3B,IAAI,EACJ,QAAQ,EACR,cAAc,GAKf;IACC,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACvB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC7C,4EAA4E;IAC5E,4EAA4E;IAC5E,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE;QACpC,KAAK,EAAE,KAAK;QACZ,UAAU,EAAE,CAAC,KAAK,EAAE,EAAE;YACpB,2BAA2B,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;QACzD,CAAC;KACF,CAAW,CAAC;IACb,OAAO,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,EACxC,IAAI,EACJ,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,IAAI,QAAQ,EAC7C,cAAc,GAKf;IACC,OAAO,mBAAmB,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC,CAAC;AACjE,CAAC"}

package/build/pxi/options.d.ts

@@ -0,0 +1,64 @@
+import { Command } from "commander";
+import type { BuiltInProvider, ModelSelection, PxiRuntimeOptions } from "./types.js";
+export declare const DEFAULT_PXI_PROVIDER: BuiltInProvider;
+export declare const DEFAULT_PXI_MODEL = "claude-opus-4-8";
+export declare const BUILT_IN_PROVIDERS: readonly ["ANTHROPIC", "AWS", "AZURE_OPENAI", "CEREBRAS", "DEEPSEEK", "FIREWORKS", "GOOGLE", "GROQ", "MOONSHOT", "OLLAMA", "OPENAI", "PERPLEXITY", "TOGETHER", "XAI"];
+type RawPxiOptions = {
+    endpoint?: string;
+    apiKey?: string;
+    profile?: string;
+    provider?: string;
+    model?: string;
+    customProviderId?: string;
+    skipModelPreflight?: boolean;
+    enableWebAccess?: boolean;
+    enableSubagents?: boolean;
+    enableGraphqlMutations?: boolean;
+    bypassEdits?: boolean;
+    ingestTraces?: boolean;
+    exportRemoteTraces?: boolean;
+    attachUserId?: boolean;
+};
+export type ResolvePxiRuntimeOptionsInput = {
+    cliOptions: RawPxiOptions;
+    sessionId?: string;
+};
+/**
+ * Turn the raw `--provider` / `--model` / `--custom-provider-id` flags into a
+ * normalized {@link ModelSelection}.
+ *
+ * Passing `--custom-provider-id` selects a custom provider and requires an
+ * explicit `--model`. Otherwise a built-in provider is used: its name is
+ * upper-cased and validated against {@link BUILT_IN_PROVIDERS}, and the model
+ * falls back to {@link DEFAULT_PXI_MODEL}. Throws {@link InvalidArgumentError}
+ * for an unknown provider or a custom provider missing its model.
+ */
+export declare function resolveModelSelection({ provider, model, customProviderId, }: {
+    provider?: string;
+    model?: string;
+    customProviderId?: string;
+}): ModelSelection;
+/**
+ * Build the fully-resolved {@link PxiRuntimeOptions} for a session from parsed
+ * CLI flags. This layers the endpoint/api-key/profile through
+ * {@link resolveConfig}, resolves the model selection, and coerces the boolean
+ * feature flags into their final shape. A fresh `sessionId` is generated unless
+ * one is supplied (tests pass a fixed id for determinism).
+ */
+export declare function resolvePxiRuntimeOptions({ cliOptions, sessionId, }: ResolvePxiRuntimeOptionsInput): PxiRuntimeOptions;
+/**
+ * Define the `pxi` Commander program: its flags, defaults, and help text.
+ * Kept separate from parsing so tests can introspect the command definition
+ * without executing it.
+ */
+export declare function createPxiProgram(): Command;
+/**
+ * Parse `argv` with the `pxi` program and resolve it into runtime options. This
+ * is the one-call path used by the entry point; `createPxiProgram` and
+ * `resolvePxiRuntimeOptions` are exposed separately for finer-grained testing.
+ */
+export declare function parsePxiRuntimeOptions({ argv, }?: {
+    argv?: string[];
+}): Promise<PxiRuntimeOptions>;
+export {};
+//# sourceMappingURL=options.d.ts.map

package/build/pxi/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/pxi/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EAEd,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB,eAAO,MAAM,oBAAoB,EAAE,eAA6B,CAAC;AACjE,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AAEnD,eAAO,MAAM,kBAAkB,uKAegB,CAAC;AAEhD,KAAK,aAAa,GAAG;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,UAAU,EAAE,aAAa,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAcF;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,QAAQ,EACR,KAAK,EACL,gBAAgB,GACjB,EAAE;IACD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,cAAc,CAgCjB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,EACvC,UAAU,EACV,SAA+B,GAChC,EAAE,6BAA6B,GAAG,iBAAiB,CA8BnD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CA+C1C;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,EAC3C,IAAmB,GACpB,GAAE;IACD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACZ,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAMlC"}

package/build/pxi/options.js

@@ -0,0 +1,148 @@
+import { Command } from "commander";
+import { resolveConfig } from "../config.js";
+import { InvalidArgumentError } from "../exitCodes.js";
+export const DEFAULT_PXI_PROVIDER = "ANTHROPIC";
+export const DEFAULT_PXI_MODEL = "claude-opus-4-8";
+export const BUILT_IN_PROVIDERS = [
+    "ANTHROPIC",
+    "AWS",
+    "AZURE_OPENAI",
+    "CEREBRAS",
+    "DEEPSEEK",
+    "FIREWORKS",
+    "GOOGLE",
+    "GROQ",
+    "MOONSHOT",
+    "OLLAMA",
+    "OPENAI",
+    "PERPLEXITY",
+    "TOGETHER",
+    "XAI",
+];
+function getExpectedProviderMessage() {
+    return `Expected one of: ${BUILT_IN_PROVIDERS.join(", ")}.`;
+}
+function isBuiltInProvider(provider) {
+    return BUILT_IN_PROVIDERS.includes(provider);
+}
+function normalizeBuiltInProvider({ provider }) {
+    return provider.toUpperCase();
+}
+/**
+ * Turn the raw `--provider` / `--model` / `--custom-provider-id` flags into a
+ * normalized {@link ModelSelection}.
+ *
+ * Passing `--custom-provider-id` selects a custom provider and requires an
+ * explicit `--model`. Otherwise a built-in provider is used: its name is
+ * upper-cased and validated against {@link BUILT_IN_PROVIDERS}, and the model
+ * falls back to {@link DEFAULT_PXI_MODEL}. Throws {@link InvalidArgumentError}
+ * for an unknown provider or a custom provider missing its model.
+ */
+export function resolveModelSelection({ provider, model, customProviderId, }) {
+    const trimmedModel = model?.trim();
+    const trimmedCustomProviderId = customProviderId?.trim();
+    if (trimmedCustomProviderId) {
+        if (!trimmedModel) {
+            throw new InvalidArgumentError("Missing required flag --model when --custom-provider-id is provided. Expected a non-empty model name.");
+        }
+        return {
+            providerType: "custom",
+            providerId: trimmedCustomProviderId,
+            modelName: trimmedModel,
+        };
+    }
+    const rawSelectedProvider = (provider ?? DEFAULT_PXI_PROVIDER).trim();
+    const selectedProvider = normalizeBuiltInProvider({
+        provider: rawSelectedProvider,
+    });
+    if (!isBuiltInProvider(selectedProvider)) {
+        throw new InvalidArgumentError(`Invalid value for --provider: ${rawSelectedProvider}. ${getExpectedProviderMessage()}`);
+    }
+    return {
+        providerType: "builtin",
+        provider: selectedProvider,
+        modelName: trimmedModel || DEFAULT_PXI_MODEL,
+    };
+}
+/**
+ * Build the fully-resolved {@link PxiRuntimeOptions} for a session from parsed
+ * CLI flags. This layers the endpoint/api-key/profile through
+ * {@link resolveConfig}, resolves the model selection, and coerces the boolean
+ * feature flags into their final shape. A fresh `sessionId` is generated unless
+ * one is supplied (tests pass a fixed id for determinism).
+ */
+export function resolvePxiRuntimeOptions({ cliOptions, sessionId = crypto.randomUUID(), }) {
+    const config = resolveConfig({
+        cliOptions: {
+            endpoint: cliOptions.endpoint,
+            apiKey: cliOptions.apiKey,
+        },
+        profileName: cliOptions.profile,
+    });
+    const modelSelection = resolveModelSelection({
+        provider: cliOptions.provider,
+        model: cliOptions.model,
+        customProviderId: cliOptions.customProviderId,
+    });
+    const editPermission = cliOptions.bypassEdits
+        ? "bypass"
+        : "manual";
+    return {
+        sessionId,
+        config,
+        modelSelection,
+        skipModelPreflight: Boolean(cliOptions.skipModelPreflight),
+        enableWebAccess: Boolean(cliOptions.enableWebAccess),
+        enableSubagents: Boolean(cliOptions.enableSubagents),
+        enableGraphqlMutations: Boolean(cliOptions.enableGraphqlMutations),
+        editPermission,
+        ingestTraces: Boolean(cliOptions.ingestTraces),
+        exportRemoteTraces: Boolean(cliOptions.exportRemoteTraces),
+        attachUserId: Boolean(cliOptions.attachUserId),
+    };
+}
+/**
+ * Define the `pxi` Commander program: its flags, defaults, and help text.
+ * Kept separate from parsing so tests can introspect the command definition
+ * without executing it.
+ */
+export function createPxiProgram() {
+    const program = new Command();
+    program
+        .name("pxi")
+        .description("Open an interactive Phoenix PXI terminal chat.")
+        .option("--endpoint <url>", "Phoenix endpoint URL")
+        .option("--api-key <key>", "Phoenix API key")
+        .option("--profile <name>", "Phoenix CLI profile name")
+        .option("--provider <provider>", `Built-in model provider (${BUILT_IN_PROVIDERS.join("|")})`, DEFAULT_PXI_PROVIDER)
+        .option("--model <model>", `Model name (defaults to ${DEFAULT_PXI_MODEL} for built-in providers)`)
+        .option("--custom-provider-id <id>", "Custom provider ID")
+        .option("--skip-model-preflight", "Skip Phoenix model catalog and credential checks before launch")
+        .option("--enable-web-access", "Enable PXI web access context")
+        .option("--enable-subagents", "Enable PXI subagent context")
+        .option("--enable-graphql-mutations", "Allow server-agent GraphQL mutation tools")
+        .option("--bypass-edits", "Bypass manual edit approvals when supported")
+        .option("--ingest-traces", "Persist local PXI traces in Phoenix")
+        .option("--export-remote-traces", "Export PXI traces remotely")
+        .option("--attach-user-id", "Attach the authenticated Phoenix user to PXI traces")
+        .addHelpText("after", `
+Examples:
+  pxi
+  pxi --endpoint http://localhost:6006 --provider OPENAI --model gpt-5.4
+  pxi --custom-provider-id provider-id --model custom-agent-model
+`);
+    return program;
+}
+/**
+ * Parse `argv` with the `pxi` program and resolve it into runtime options. This
+ * is the one-call path used by the entry point; `createPxiProgram` and
+ * `resolvePxiRuntimeOptions` are exposed separately for finer-grained testing.
+ */
+export async function parsePxiRuntimeOptions({ argv = process.argv, } = {}) {
+    const program = createPxiProgram();
+    await program.parseAsync(argv);
+    return resolvePxiRuntimeOptions({
+        cliOptions: program.opts(),
+    });
+}
+//# sourceMappingURL=options.js.map

package/build/pxi/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/pxi/options.ts"],"names":[],"mappings":"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"}

package/build/pxi/preflight.d.ts

@@ -0,0 +1,88 @@
+import type { PhoenixConfig } from "../config.js";
+import type { ModelSelection, PxiRuntimeOptions } from "./types.js";
+/**
+ * Pre-launch validation of the selected model.
+ *
+ * Before the chat UI opens, PXI asks the Phoenix server which providers and
+ * models are actually installed and credentialed, then checks the user's
+ * `--provider`/`--model` selection against that catalog. Catching a bad or
+ * unconfigured model here turns what would be a cryptic mid-stream failure into
+ * a clear, actionable startup error. The whole check can be skipped with
+ * `--skip-model-preflight`.
+ */
+/** GraphQL query fetching the server's provider catalog, credential state, and known models. */
+export declare const PXI_MODEL_PREFLIGHT_QUERY = "\n  query PxiModelPreflightQuery {\n    modelProviders {\n      key\n      name\n      dependenciesInstalled\n      credentialsSet\n      credentialRequirements {\n        envVarName\n        isRequired\n      }\n    }\n    playgroundModels {\n      providerKey\n      name\n    }\n    generativeModelCustomProviders(first: 50) {\n      edges {\n        node {\n          id\n          name\n          sdk\n          modelNames\n        }\n      }\n    }\n  }\n";
+type PxiModelProvider = {
+    key: string;
+    name: string;
+    dependenciesInstalled: boolean;
+    credentialsSet: boolean;
+    credentialRequirements: Array<{
+        envVarName: string;
+        isRequired: boolean;
+    }>;
+};
+type PxiPlaygroundModel = {
+    providerKey: string;
+    name: string;
+};
+type PxiCustomProvider = {
+    id: string;
+    name: string;
+    sdk: string;
+    modelNames: string[];
+};
+type PxiModelPreflightData = {
+    modelProviders: PxiModelProvider[];
+    playgroundModels: PxiPlaygroundModel[];
+    generativeModelCustomProviders: {
+        edges: Array<{
+            node: PxiCustomProvider;
+        }>;
+    };
+};
+/**
+ * Fetch the provider/model catalog from Phoenix via GraphQL. Requires a
+ * configured endpoint and turns non-2xx responses into errors that include the
+ * HTTP status and any response body. `fetchImpl` is injectable for testing.
+ */
+export declare function fetchPxiModelPreflight({ config, fetchImpl, }: {
+    config: PhoenixConfig;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<PxiModelPreflightData>;
+/**
+ * Check a model selection against the fetched catalog, throwing
+ * {@link InvalidArgumentError} with a helpful message on the first problem.
+ *
+ * For custom providers: the provider id must exist, and the model must be one of
+ * its configured names (when it advertises any). For built-in providers: the
+ * provider must be available, have its dependencies installed and credentials
+ * set, and — if the server publishes a model catalog for it — the model must be
+ * in that catalog. A provider with no published catalog accepts any model name.
+ */
+export declare function validatePxiModelSelection({ data, modelSelection, }: {
+    data: PxiModelPreflightData;
+    modelSelection: ModelSelection;
+}): void;
+/**
+ * Run the full preflight for a session: fetch the catalog and validate the
+ * selected model, unless `--skip-model-preflight` was passed. This is the single
+ * call the entry point makes before rendering the UI.
+ */
+export declare function runPxiModelPreflight({ options, fetchImpl, }: {
+    options: PxiRuntimeOptions;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<void>;
+/**
+ * Wrap an error thrown while talking to PXI into a single message that names the
+ * model and appends a tailored next step — pointing custom providers at their
+ * Phoenix settings and built-in providers at credential configuration or
+ * choosing a different model. Used for failures that surface after the preflight
+ * has already passed.
+ */
+export declare function formatPxiRuntimeError({ error, modelSelection, }: {
+    error: unknown;
+    modelSelection: ModelSelection;
+}): Error;
+export {};
+//# sourceMappingURL=preflight.d.ts.map

package/build/pxi/preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../src/pxi/preflight.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjE;;;;;;;;;GASG;AAEH,gGAAgG;AAChG,eAAO,MAAM,yBAAyB,kdA2BrC,CAAC;AAEF,KAAK,gBAAgB,GAAG;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB,EAAE,OAAO,CAAC;IAC/B,cAAc,EAAE,OAAO,CAAC;IACxB,sBAAsB,EAAE,KAAK,CAAC;QAC5B,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,OAAO,CAAC;KACrB,CAAC,CAAC;CACJ,CAAC;AAEF,KAAK,kBAAkB,GAAG;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,KAAK,iBAAiB,GAAG;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF,KAAK,qBAAqB,GAAG;IAC3B,cAAc,EAAE,gBAAgB,EAAE,CAAC;IACnC,gBAAgB,EAAE,kBAAkB,EAAE,CAAC;IACvC,8BAA8B,EAAE;QAC9B,KAAK,EAAE,KAAK,CAAC;YACX,IAAI,EAAE,iBAAiB,CAAC;SACzB,CAAC,CAAC;KACJ,CAAC;CACH,CAAC;AA2HF;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,EAC3C,MAAM,EACN,SAA4B,GAC7B,EAAE;IACD,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACrC,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAyBjC;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,IAAI,EACJ,cAAc,GACf,EAAE;IACD,IAAI,EAAE,qBAAqB,CAAC;IAC5B,cAAc,EAAE,cAAc,CAAC;CAChC,GAAG,IAAI,CA4DP;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,EACzC,OAAO,EACP,SAA4B,GAC7B,EAAE;IACD,OAAO,EAAE,iBAAiB,CAAC;IAC3B,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACrC,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,KAAK,EACL,cAAc,GACf,EAAE;IACD,KAAK,EAAE,OAAO,CAAC;IACf,cAAc,EAAE,cAAc,CAAC;CAChC,GAAG,KAAK,CASR"}