@agent-native/core 0.176.3 → 0.176.4-nightly-20260901193441

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 8819
+- template files: 8820

package/corpus/templates/calendar/changelog/2026-09-01-calendar-keeps-the-learn-more-link-clear-of-the-language-con.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-09-01
+---
+
+Calendar keeps the learn-more link clear of the language control on every screen size.

package/corpus/templates/calendar/server/plugins/auth.ts

@@ -14,6 +14,7 @@ export default createAuthPlugin({
     screenshotWidth: 914,
     screenshotHeight: 818,
     learnMoreUrl: "https://agent-native.com/apps/calendar",
+    learnMorePlacement: "bottom-right",
     tagline:
       "Your AI agent schedules, reschedules, and manages your calendar so you never have to.",
     features: [

package/dist/client/auth/AuthPage.d.ts

@@ -10,6 +10,7 @@ export interface AuthMarketingProps {
     screenshotWidth?: number;
     screenshotHeight?: number;
     learnMoreUrl?: string;
+    learnMorePlacement?: "top-right" | "bottom-right";
 }
 export interface AuthLocaleOption {
     value: string;

package/dist/client/auth/AuthPage.js

@@ -1831,9 +1831,15 @@ export function AuthPage(props) {
             React.createElement("span", { "aria-hidden": "true" }, " - "),
             React.createElement("span", { className: "auth-marketing-learn-more-link" }, t("learnMore")))) : null, auth: React.createElement(React.Fragment, null,
             authCard,
-            localNote), className: marketingCopy.screenshotSrc
-            ? "auth-marketing-home has-product-screenshot"
-            : "auth-marketing-home" }, marketingCopy.screenshotSrc ? (React.createElement("div", { className: "auth-marketing-screenshot-wrap" },
+            localNote), className: [
+            "auth-marketing-home",
+            marketingCopy.screenshotSrc ? "has-product-screenshot" : "",
+            marketingCopy.learnMorePlacement === "bottom-right"
+                ? "has-bottom-right-learn-more"
+                : "",
+        ]
+            .filter(Boolean)
+            .join(" ") }, marketingCopy.screenshotSrc ? (React.createElement("div", { className: "auth-marketing-screenshot-wrap" },
         React.createElement("img", { className: "auth-marketing-screenshot", src: marketingCopy.screenshotSrc, alt: `${marketingCopy.appName} preview`, width: marketingCopy.screenshotWidth, height: marketingCopy.screenshotHeight, fetchPriority: "high", decoding: "async" }))) : (React.createElement("div", { className: "marketing-content" },
         React.createElement("h2", { className: "app-name" },
             React.createElement("img", { className: "brand-mark", src: brandMarkSrc, alt: "", "aria-hidden": "true" }),

package/dist/client/terminal/AgentTerminal.d.ts

@@ -22,6 +22,8 @@ export interface AgentTerminalProps {
     theme?: Record<string, string>;
     /** Font size. Default: 12 */
     fontSize?: number;
+    /** Focus the terminal on mount and when it becomes active. Default: true */
+    autoFocus?: boolean;
     /** CSS class for the container */
     className?: string;
     /** Inline styles for the container */
@@ -40,4 +42,4 @@ export interface AgentTerminalSubmitRequest {
     text: string;
 }
 export declare function formatWebSocketHostname(hostname: string): string;
-export declare function AgentTerminal({ command, flags, wsUrl: wsUrlProp, hideInFrame, theme, fontSize, className, style, onConnectionChange, onAgentRunningChange, submitRequest, onPromptSubmitted, }: AgentTerminalProps): import("react").JSX.Element | null;
+export declare function AgentTerminal({ command, flags, wsUrl: wsUrlProp, hideInFrame, theme, fontSize, autoFocus, className, style, onConnectionChange, onAgentRunningChange, submitRequest, onPromptSubmitted, }: AgentTerminalProps): import("react").JSX.Element | null;

package/dist/client/terminal/AgentTerminal.js

@@ -33,9 +33,20 @@ function injectXtermCss() {
     .xterm .composition-view { display: none; position: absolute; white-space: nowrap; z-index: 1; }
     .xterm .composition-view.active { display: block; }
     .xterm .xterm-viewport {
-      background-color: var(--agent-terminal-background); overflow-y: scroll;
+      background-color: var(--agent-terminal-background); overflow-y: auto;
+      scrollbar-width: thin;
+      scrollbar-color: hsl(var(--muted-foreground) / 0.22) transparent;
       cursor: default; position: absolute; right: 0; left: 0; top: 0; bottom: 0;
     }
+    .xterm .xterm-viewport::-webkit-scrollbar { width: 8px; height: 8px; }
+    .xterm .xterm-viewport::-webkit-scrollbar-track { background: transparent; }
+    .xterm .xterm-viewport::-webkit-scrollbar-thumb {
+      background: hsl(var(--muted-foreground) / 0.22);
+      border-radius: 999px;
+    }
+    .xterm .xterm-viewport::-webkit-scrollbar-thumb:hover {
+      background: hsl(var(--muted-foreground) / 0.36);
+    }
     .xterm .xterm-screen { position: relative; }
     .xterm .xterm-screen canvas { position: absolute; left: 0; top: 0; }
     .xterm .xterm-scroll-area { visibility: hidden; }
@@ -85,10 +96,13 @@ export function formatWebSocketHostname(hostname) {
         ? `[${hostname}]`
         : hostname;
 }
-export function AgentTerminal({ command, flags, wsUrl: wsUrlProp, hideInFrame = true, theme, fontSize = 12, className, style, onConnectionChange, onAgentRunningChange, submitRequest, onPromptSubmitted, }) {
+export function AgentTerminal({ command, flags, wsUrl: wsUrlProp, hideInFrame = true, theme, fontSize = 12, autoFocus = true, className, style, onConnectionChange, onAgentRunningChange, submitRequest, onPromptSubmitted, }) {
     const termRef = useRef(null);
     const submitPromptRef = useRef(null);
     const pendingSubmitRequestRef = useRef(null);
+    const autoFocusRef = useRef(autoFocus);
+    autoFocusRef.current = autoFocus;
+    const focusTerminalRef = useRef(null);
     const onPromptSubmittedRef = useRef(onPromptSubmitted);
     onPromptSubmittedRef.current = onPromptSubmitted;
     const [connected, setConnected] = useState(false);
@@ -111,6 +125,17 @@ export function AgentTerminal({ command, flags, wsUrl: wsUrlProp, hideInFrame =
     useEffect(() => {
         onConnectionChange?.(connected);
     }, [connected, onConnectionChange]);
+    useEffect(() => {
+        if (autoFocus) {
+            focusTerminalRef.current?.();
+            return;
+        }
+        const activeElement = document.activeElement;
+        if (activeElement instanceof HTMLElement &&
+            termRef.current?.contains(activeElement)) {
+            activeElement.blur();
+        }
+    }, [autoFocus]);
     // Main terminal setup
     useEffect(() => {
         if (typeof window === "undefined")
@@ -148,6 +173,10 @@ export function AgentTerminal({ command, flags, wsUrl: wsUrlProp, hideInFrame =
             term.loadAddon(fitAddon);
             term.loadAddon(webLinksAddon);
             term.open(container);
+            const focusTerminal = () => term.focus();
+            focusTerminalRef.current = focusTerminal;
+            if (autoFocusRef.current)
+                focusTerminal();
             let fitPending = false;
             function fitAndResize() {
                 if (fitPending)
@@ -190,6 +219,9 @@ export function AgentTerminal({ command, flags, wsUrl: wsUrlProp, hideInFrame =
                 window.removeEventListener("focus", handleVisibilityOrFocus);
                 document.removeEventListener("visibilitychange", handleVisibilityOrFocus);
                 resizeObserver.disconnect();
+                if (focusTerminalRef.current === focusTerminal) {
+                    focusTerminalRef.current = null;
+                }
                 term.dispose();
             }
             function disposeIfCancelled() {
@@ -236,7 +268,6 @@ export function AgentTerminal({ command, flags, wsUrl: wsUrlProp, hideInFrame =
             }
             if (flags)
                 fullWsUrl.searchParams.set("flags", flags);
-            term.write(`\x1b[2m[terminal] Starting ${resolvedCommand || "CLI"}...\x1b[0m\r\n`);
             // Connect WebSocket
             let agentRunning = false;
             let idleTimer = null;
@@ -284,6 +315,8 @@ export function AgentTerminal({ command, flags, wsUrl: wsUrlProp, hideInFrame =
                 socket.onopen = () => {
                     setConnected(true);
                     setError(null);
+                    if (autoFocusRef.current)
+                        focusTerminal();
                     socket.send(JSON.stringify({
                         type: "resize",
                         cols: term.cols,
@@ -333,7 +366,6 @@ export function AgentTerminal({ command, flags, wsUrl: wsUrlProp, hideInFrame =
                 socket.onclose = () => {
                     setConnected(false);
                     if (connectionId === thisId && !disposed) {
-                        term.write("\r\n\x1b[31m[terminal] Connection closed. Reconnecting in 3s...\x1b[0m\r\n");
                         setTimeout(() => {
                             if (connectionId === thisId && !disposed) {
                                 connect(url);

package/dist/collab/routes.d.ts

@@ -26,8 +26,8 @@ export declare const getCollabState: import("h3").EventHandlerWithFetch<import("
  * Body: { update: string (base64), requestSource?: string }
  */
 export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/collab/struct-routes.d.ts

@@ -13,8 +13,8 @@
  * Body: { json: any, fieldName?: string, type?: "map"|"array", requestSource?: string }
  */
 export declare const postCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/file-upload/actions/upload-image.d.ts

@@ -3,25 +3,25 @@ declare const _default: import("../../action.js").ActionDefinition<{
     url?: string;
     filename?: string;
 }, {
-    id?: undefined;
     error: string;
     configured?: undefined;
     connectPath?: undefined;
     url?: undefined;
+    id?: undefined;
     provider?: undefined;
 } | {
-    id?: undefined;
     error: string;
     configured: boolean;
     connectPath: string;
     url?: undefined;
+    id?: undefined;
     provider?: undefined;
 } | {
+    error?: undefined;
     configured?: undefined;
     connectPath?: undefined;
     url: string;
     id: string;
     provider: string;
-    error?: undefined;
 }>;
 export default _default;

package/dist/observability/routes.d.ts

@@ -41,27 +41,27 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
+    error?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
-    id?: undefined;
-    error?: undefined;
     ok?: undefined;
+    id?: undefined;
 } | {
+    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id: string;
-    error?: undefined;
     ok?: undefined;
 } | {
     summary?: undefined;
     spans?: undefined;
-    id?: undefined;
     error: any;
     ok?: undefined;
+    id?: undefined;
 } | {
+    error?: undefined;
     summary?: undefined;
     spans?: undefined;
-    id?: undefined;
     ok: boolean;
-    error?: undefined;
+    id?: undefined;
 }>>;

package/dist/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;

package/dist/secrets/routes.d.ts

@@ -37,17 +37,17 @@ export declare function createWriteSecretHandler(): import("h3").EventHandlerWit
     ok?: undefined;
     status?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     status: string;
-    error?: undefined;
 } | {
     ok?: undefined;
     error: string;
     removed?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     removed: boolean;
-    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
@@ -58,13 +58,13 @@ export declare function createTestSecretHandler(): import("h3").EventHandlerWith
     error: string;
     note?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     note?: undefined;
-    error?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     note: string;
-    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,11 +95,11 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
+    error?: undefined;
     ok: boolean;
     key: string;
-    error?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     removed: boolean;
-    error?: undefined;
 }>>;

package/dist/server/agent-engine-api-key-route.d.ts

@@ -34,10 +34,10 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
+    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
-    error?: undefined;
 }>>;
 export {};

package/dist/server/auth-marketing.d.ts

@@ -7,6 +7,7 @@ export interface AuthMarketingContent {
     screenshotWidth?: number;
     screenshotHeight?: number;
     learnMoreUrl?: string;
+    learnMorePlacement?: "top-right" | "bottom-right";
     /** @deprecated Local execution is no longer offered from auth pages. */
     runLocalCommand?: string;
     signupLocalModeNote?: {

package/dist/server/auth-marketing.js

@@ -32,6 +32,7 @@ export const BUILT_IN_AUTH_MARKETING = {
             "Manages availability and booking links automatically",
             "Answers schedule questions and resolves conflicts instantly",
         ],
+        learnMorePlacement: "bottom-right",
     },
     clips: {
         appName: "Agent-Native Clips",

package/dist/server/auth.d.ts

@@ -132,6 +132,7 @@ export interface AuthOptions {
         screenshotWidth?: number;
         screenshotHeight?: number;
         learnMoreUrl?: string;
+        learnMorePlacement?: "top-right" | "bottom-right";
         /** @deprecated Local execution is no longer offered from auth pages. */
         runLocalCommand?: string;
     };

package/dist/server/onboarding-html.d.ts

@@ -33,6 +33,7 @@ export interface OnboardingHtmlOptions {
         screenshotWidth?: number;
         screenshotHeight?: number;
         learnMoreUrl?: string;
+        learnMorePlacement?: "top-right" | "bottom-right";
         /** @deprecated Local execution is no longer offered from auth pages. */
         runLocalCommand?: string;
     };

package/dist/server/onboarding-html.js

@@ -1281,6 +1281,7 @@ export function getOnboardingHtml(opts = {}) {
                     : undefined,
                 screenshotWidth: marketing.screenshotWidth,
                 screenshotHeight: marketing.screenshotHeight,
+                learnMorePlacement: marketing.learnMorePlacement,
                 learnMoreUrl: marketing.learnMoreUrl ??
                     (marketingSlug
                         ? `https://agent-native.com/apps/${marketingSlug}`
@@ -1350,13 +1351,11 @@ export function getOnboardingHtml(opts = {}) {
     width: 2rem;
     height: 2rem;
     padding: 0;
-    background: rgba(20,20,20,0.82);
+    background: transparent;
     color: #e5e5e5;
-    border: 1px solid rgba(255,255,255,0.12);
-    border-radius: 8px;
+    border: 0;
     cursor: pointer;
     outline: none;
-    backdrop-filter: blur(12px);
   }
   .locale-trigger svg {
     width: 1rem;
@@ -1369,11 +1368,10 @@ export function getOnboardingHtml(opts = {}) {
   }
   .locale-trigger:hover,
   .locale-trigger[aria-expanded="true"] {
-    border-color: rgba(255,255,255,0.22);
-    background: rgba(28,28,28,0.92);
+    border-color: transparent;
+    background: transparent;
   }
   .locale-trigger:focus {
-    border-color: rgba(255,255,255,0.42);
     box-shadow: 0 0 0 3px rgba(255,255,255,0.08);
   }
   .locale-menu {
@@ -1940,13 +1938,17 @@ ${embeddedAuthCss}
     justify-content: flex-end;
     align-items: center;
     position: absolute;
-    height: 2rem;
     padding: 0;
     top: max(1rem, env(safe-area-inset-top));
     inset-inline-end: calc(max(1rem, env(safe-area-inset-right)) + 2.5rem);
     z-index: 2;
   }
-  .auth-marketing-learn-more { font-size: 0.9rem; }
+  .auth-marketing-learn-more { font-size: 0.8rem; }
+  .auth-marketing-home.has-bottom-right-learn-more .auth-marketing-top-right {
+    top: auto;
+    bottom: max(1rem, env(safe-area-inset-bottom));
+    inset-inline-end: max(1rem, env(safe-area-inset-right));
+  }
   .auth-marketing-home .auth-marketing-layout {
     min-height: 100vh;
     display: flex;
@@ -1981,9 +1983,17 @@ ${embeddedAuthCss}
     }
     .auth-marketing-home .auth-marketing-top-right {
       top: max(1rem, env(safe-area-inset-top));
+      bottom: auto;
       inset-inline-start: max(1rem, env(safe-area-inset-left));
       inset-inline-end: auto;
     }
+    .auth-marketing-home.has-bottom-right-learn-more .auth-marketing-top-right {
+      top: auto;
+      bottom: max(1rem, env(safe-area-inset-bottom));
+      inset-inline-start: 50%;
+      inset-inline-end: auto;
+      transform: translateX(-50%);
+    }
     .auth-marketing-home .auth-marketing-layout { min-height: auto; }
     .auth-marketing-home .auth-marketing-shell { display: block; }
     .auth-marketing-home .auth-marketing-shell-with-top-right { display: flex; }

package/dist/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
-    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
+    error?: undefined;
 }>>;

package/dist/server/transcribe-voice.d.ts

@@ -20,6 +20,6 @@ export declare function createTranscribeVoiceHandler(): import("h3").EventHandle
     error: string;
     text?: undefined;
 } | {
-    text: string;
     error?: undefined;
+    text: string;
 }>>;

package/dist/terminal/cli-registry.d.ts

@@ -10,8 +10,11 @@ export interface CliEntry {
     /** Env vars to strip when spawning (prevents nesting) */
     stripEnv: string[];
 }
+export declare function terminalPath(environment?: NodeJS.ProcessEnv): Promise<string>;
 export declare const CLI_REGISTRY: Record<string, CliEntry>;
 /** Check if a command name is in the CLI_REGISTRY allowlist */
 export declare function isAllowedCommand(cmd: string): boolean;
+/** Resolve a CLI from the user's shell locations, including GUI launch paths. */
+export declare function resolveCommandPath(cmd: string, environment?: NodeJS.ProcessEnv): Promise<string | null>;
 /** Check if a CLI command exists on PATH (safe — no shell interpolation) */
 export declare function commandExists(cmd: string): Promise<boolean>;

package/dist/terminal/cli-registry.js

@@ -2,6 +2,45 @@
  * CLI Registry — known AI coding CLIs and their metadata.
  * Used by the embedded terminal in the agent panel.
  */
+export async function terminalPath(environment = process.env) {
+    const [fs, os, path] = await Promise.all([
+        import("node:fs"),
+        import("node:os"),
+        import("node:path"),
+    ]);
+    const home = environment.HOME || os.homedir();
+    const nvmDirectories = home
+        ? (() => {
+            try {
+                return fs
+                    .readdirSync(path.join(home, ".nvm", "versions", "node"))
+                    .map((version) => path.join(home, ".nvm", "versions", "node", version, "bin"));
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return [];
+                throw error;
+            }
+        })()
+        : [];
+    const entries = [
+        ...(environment.PATH ?? environment.Path ?? "")
+            .split(path.delimiter)
+            .filter(Boolean),
+        environment.PNPM_HOME,
+        home ? path.join(home, ".local", "bin") : undefined,
+        home ? path.join(home, ".local", "share", "pnpm") : undefined,
+        home ? path.join(home, "Library", "pnpm") : undefined,
+        home ? path.join(home, ".opencode", "bin") : undefined,
+        home ? path.join(home, ".cargo", "bin") : undefined,
+        ...nvmDirectories,
+        "/opt/homebrew/bin",
+        "/usr/local/bin",
+        "/usr/bin",
+        "/bin",
+    ].filter((entry) => Boolean(entry));
+    return [...new Set(entries)].join(path.delimiter);
+}
 export const CLI_REGISTRY = {
     claude: {
         label: "Claude Code",
@@ -38,14 +77,21 @@ export const CLI_REGISTRY = {
 export function isAllowedCommand(cmd) {
     return Object.prototype.hasOwnProperty.call(CLI_REGISTRY, cmd);
 }
+/** Resolve a CLI from the user's shell locations, including GUI launch paths. */
+export async function resolveCommandPath(cmd, environment = process.env) {
+    const { spawnSync } = await import("node:child_process");
+    const resolver = process.platform === "win32" ? "where.exe" : "which";
+    const result = spawnSync(resolver, [cmd], {
+        encoding: "utf8",
+        env: { ...environment, PATH: await terminalPath(environment) },
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (result.status !== 0)
+        return null;
+    const resolved = result.stdout?.trim().split(/\r?\n/)[0];
+    return resolved || cmd;
+}
 /** Check if a CLI command exists on PATH (safe — no shell interpolation) */
 export async function commandExists(cmd) {
-    try {
-        const { spawnSync } = await import("node:child_process");
-        const result = spawnSync("which", [cmd], { stdio: "ignore" });
-        return result.status === 0;
-    }
-    catch {
-        return false;
-    }
+    return (await resolveCommandPath(cmd)) !== null;
 }

package/dist/terminal/pty-server.d.ts

@@ -21,9 +21,26 @@ export interface PtyServerOptions {
     authCheck?: (req: IncomingMessage) => boolean | Promise<boolean>;
     /** Trusted host arguments appended to each validated CLI command. */
     getCommandArgs?: (command: string) => string[] | Promise<string[]>;
+    /** Trusted environment additions for the validated CLI command. */
+    getEnvironment?: (command: string) => NodeJS.ProcessEnv | Promise<NodeJS.ProcessEnv>;
+    /** Per-connection setup for trusted host capabilities and cleanup. */
+    getSessionSetup?: (command: string, context: PtySessionContext | null) => PtySessionSetup | Promise<PtySessionSetup>;
     /** Log prefix for console output. Defaults to '[terminal]' */
     logPrefix?: string;
 }
+export interface PtySessionContext {
+    appId: string;
+    path?: string;
+    view?: string;
+}
+export interface PtySessionSetup {
+    /** Trusted arguments appended to the selected CLI command. */
+    commandArgs?: string[];
+    /** Trusted environment additions for the selected CLI command. */
+    environment?: NodeJS.ProcessEnv;
+    /** Releases per-connection resources such as scoped MCP relays. */
+    onClose?: () => void | Promise<void>;
+}
 export interface PtyServerResult {
     /** The underlying HTTP server */
     server: HttpServer;
@@ -33,3 +50,8 @@ export interface PtyServerResult {
     close: () => void;
 }
 export declare function createPtyWebSocketServer(options?: PtyServerOptions): Promise<PtyServerResult>;
+export declare function preparePtySpawn(commandPath: string, args: string[], platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+};
+export declare function parseTerminalArguments(value: string, platform?: NodeJS.Platform): string[];

package/dist/terminal/pty-server.js

@@ -11,7 +11,7 @@ import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import os from "os";
 import path from "path";
-import { CLI_REGISTRY, commandExists, isAllowedCommand, } from "./cli-registry.js";
+import { CLI_REGISTRY, isAllowedCommand, resolveCommandPath, terminalPath, } from "./cli-registry.js";
 // Lazy singletons for Node-only modules (only available in Node.js)
 let _cp;
 async function getChildProcess() {
@@ -50,24 +50,6 @@ export function ensurePtySpawnHelperPermissions() {
         console.warn("[terminal] Could not verify node-pty spawn-helper permissions:", err.message);
     }
 }
-function resolveTerminalShell() {
-    if (os.platform() === "win32") {
-        // config-ok: COMSPEC is an inherited host shell fact, not application configuration.
-        return process.env["COMSPEC"] || "cmd.exe";
-    }
-    // config-ok: SHELL is the user's inherited host shell, not application configuration.
-    const configuredShell = process.env.SHELL;
-    if (configuredShell && path.isAbsolute(configuredShell)) {
-        try {
-            if (fs.statSync(configuredShell).isFile())
-                return configuredShell;
-        }
-        catch {
-            // coercion-ok: an invalid SHELL falls through to known system shells.
-        }
-    }
-    return (["/bin/zsh", "/bin/bash", "/bin/sh"].find((candidate) => fs.existsSync(candidate)) ?? "/bin/sh");
-}
 /**
  * Kill a process and all its descendants.
  * node-pty's kill() only sends a signal to the shell, but child processes
@@ -146,13 +128,12 @@ async function killProcessTree(pid, _logPrefix, killParent, isParentExited = ()
     }, 500);
 }
 export async function createPtyWebSocketServer(options = {}) {
-    const { appDir = process.cwd(), command: defaultCommand = "claude", port = 0, authCheck, getCommandArgs, logPrefix = "[terminal]", } = options;
+    const { appDir = process.cwd(), command: defaultCommand = "claude", port = 0, authCheck, getCommandArgs, getEnvironment, getSessionSetup, logPrefix = "[terminal]", } = options;
     ensurePtySpawnHelperPermissions();
     // Dynamic imports for optional native dependencies
     const { WebSocketServer, WebSocket } = await import("ws");
     const pty = await import("node-pty");
     const resolvedAppDir = path.resolve(appDir);
-    const shell = resolveTerminalShell();
     const server = createHttpServer((req, res) => {
         // CORS headers
         res.setHeader("Access-Control-Allow-Origin", "*");
@@ -225,6 +206,7 @@ export async function createPtyWebSocketServer(options = {}) {
         const url = new URL(req.url || "", `http://${req.headers.host}`);
         const command = url.searchParams.get("command") || defaultCommand;
         const extraFlags = url.searchParams.get("flags") || "";
+        const context = readPtySessionContext(url);
         console.log(`${logPrefix} WebSocket connected for command: ${command}`);
         const sendStatus = (status, message) => {
             if (ws.readyState === WebSocket.OPEN) {
@@ -245,32 +227,42 @@ export async function createPtyWebSocketServer(options = {}) {
                 ws.close();
             return;
         }
-        // Check if CLI is installed; if not, use npx to run it
-        let useNpx = false;
-        const commandInstalled = await commandExists(command);
-        if (closed) {
-            ws.close();
-            return;
-        }
-        if (!commandInstalled) {
-            const registry = CLI_REGISTRY[command];
-            if (registry?.installPackage) {
-                console.log(`${logPrefix} ${command} CLI not found, will use npx`);
-                useNpx = true;
-            }
-            else {
-                sendStatus("not-found", `"${command}" not found on PATH. Please install it manually.`);
-                if (ws.readyState === WebSocket.OPEN)
-                    ws.close();
+        let connectionClosed = false;
+        const markConnectionClosed = () => {
+            connectionClosed = true;
+        };
+        ws.once("close", markConnectionClosed);
+        let sessionSetup;
+        let sessionSetupClosed = false;
+        const closeSessionSetup = () => {
+            if (!sessionSetup || sessionSetupClosed)
                 return;
-            }
-        }
+            sessionSetupClosed = true;
+            void Promise.resolve(sessionSetup.onClose?.()).catch((error) => {
+                console.warn(`${logPrefix} Session cleanup failed:`, error);
+            });
+        };
         let commandArgs = [];
+        let commandEnvironment = {};
         try {
-            if (getCommandArgs)
-                commandArgs = await getCommandArgs(command);
+            if (getSessionSetup) {
+                sessionSetup = await getSessionSetup(command, context);
+                commandArgs = sessionSetup.commandArgs ?? [];
+                commandEnvironment = sessionSetup.environment ?? {};
+            }
+            if (getCommandArgs) {
+                const additionalArgs = await getCommandArgs(command);
+                commandArgs = [...commandArgs, ...additionalArgs];
+            }
+            if (getEnvironment) {
+                commandEnvironment = {
+                    ...commandEnvironment,
+                    ...(await getEnvironment(command)),
+                };
+            }
         }
         catch (error) {
+            closeSessionSetup();
             if (closed) {
                 ws.close();
                 return;
@@ -282,32 +274,93 @@ export async function createPtyWebSocketServer(options = {}) {
                 ws.close();
             return;
         }
-        if (closed) {
+        if (connectionClosed || ws.readyState !== WebSocket.OPEN || closed) {
+            closeSessionSetup();
+            ws.close();
+            return;
+        }
+        let extraArgumentList = [];
+        try {
+            extraArgumentList = parseTerminalArguments(extraFlags);
+        }
+        catch (error) {
+            closeSessionSetup();
+            sendStatus("failed", error instanceof Error ? error.message : "Invalid terminal flags.");
+            if (ws.readyState === WebSocket.OPEN)
+                ws.close();
+            return;
+        }
+        if (connectionClosed || ws.readyState !== WebSocket.OPEN || closed) {
+            closeSessionSetup();
             ws.close();
             return;
         }
-        // Build the command — use npx if CLI not found locally
-        const baseCommand = useNpx
-            ? `npx --yes ${CLI_REGISTRY[command].installPackage}`
-            : command;
-        const generatedFlags = commandArgs.map(shellQuote).join(" ");
-        const fullCommand = [baseCommand, generatedFlags, extraFlags]
-            .filter(Boolean)
-            .join(" ");
-        console.log(`${logPrefix} Spawning PTY for ${command}`);
         // Build env, stripping CLI-specific nesting vars
         const registry = CLI_REGISTRY[command];
         const env = {
             ...process.env,
+            ...commandEnvironment,
             TERM: "xterm-256color",
         };
         if (registry) {
             for (const v of registry.stripEnv)
                 delete env[v];
         }
+        let commandPath;
+        try {
+            env.PATH = await terminalPath(env);
+            commandPath = await resolveCommandPath(command, env);
+        }
+        catch (error) {
+            closeSessionSetup();
+            if (closed) {
+                ws.close();
+                return;
+            }
+            sendStatus("failed", error instanceof Error
+                ? error.message
+                : "The terminal command could not be resolved.");
+            if (ws.readyState === WebSocket.OPEN)
+                ws.close();
+            return;
+        }
+        if (connectionClosed || ws.readyState !== WebSocket.OPEN || closed) {
+            closeSessionSetup();
+            ws.close();
+            return;
+        }
+        let spawnCommand = commandPath;
+        let spawnArgs = [...commandArgs, ...extraArgumentList];
+        if (!spawnCommand) {
+            if (!registry?.installPackage) {
+                closeSessionSetup();
+                sendStatus("not-found", `"${command}" not found on PATH. Please install it manually.`);
+                if (ws.readyState === WebSocket.OPEN)
+                    ws.close();
+                return;
+            }
+            const npxPath = await resolveCommandPath("npx", env);
+            if (connectionClosed || ws.readyState !== WebSocket.OPEN || closed) {
+                closeSessionSetup();
+                ws.close();
+                return;
+            }
+            if (!npxPath) {
+                closeSessionSetup();
+                sendStatus("not-found", `"${command}" not found on PATH and npx is unavailable.`);
+                if (ws.readyState === WebSocket.OPEN)
+                    ws.close();
+                return;
+            }
+            console.log(`${logPrefix} ${command} CLI not found, will use npx`);
+            spawnCommand = npxPath;
+            spawnArgs = ["--yes", registry.installPackage, ...spawnArgs];
+        }
+        console.log(`${logPrefix} Spawning PTY for ${command}`);
+        const preparedSpawn = preparePtySpawn(spawnCommand, spawnArgs);
         let ptyProcess;
         try {
-            ptyProcess = pty.spawn(shell, ["-l", "-c", fullCommand], {
+            ptyProcess = pty.spawn(preparedSpawn.command, preparedSpawn.args, {
                 name: "xterm-256color",
                 cols: 120,
                 rows: 40,
@@ -321,6 +374,7 @@ export async function createPtyWebSocketServer(options = {}) {
                 sendStatus("failed", `Failed to spawn PTY: ${err instanceof Error ? err.message : String(err)}`);
                 ws.close();
             }
+            closeSessionSetup();
             return;
         }
         let disposed = false;
@@ -330,6 +384,7 @@ export async function createPtyWebSocketServer(options = {}) {
                 return;
             disposed = true;
             activeDisposers.delete(dispose);
+            closeSessionSetup();
             const killPty = () => {
                 try {
                     ptyProcess.kill();
@@ -435,6 +490,78 @@ export async function createPtyWebSocketServer(options = {}) {
         });
     });
 }
-function shellQuote(value) {
-    return `'${value.replaceAll("'", `'"'"'`)}'`;
+function readPtySessionContext(url) {
+    const appId = url.searchParams.get("appId")?.trim();
+    if (!appId)
+        return null;
+    const pathValue = url.searchParams.get("path")?.trim();
+    const view = url.searchParams.get("view")?.trim();
+    return {
+        appId,
+        ...(pathValue ? { path: pathValue } : {}),
+        ...(view ? { view } : {}),
+    };
+}
+export function preparePtySpawn(commandPath, args, platform = process.platform) {
+    if (platform !== "win32")
+        return { command: commandPath, args };
+    const extension = path.extname(commandPath).toLowerCase();
+    if (extension !== ".cmd" && extension !== ".bat") {
+        return { command: commandPath, args };
+    }
+    return {
+        command: "cmd.exe",
+        args: ["/d", "/s", "/c", `"${commandPath}"`, ...args],
+    };
+}
+export function parseTerminalArguments(value, platform = process.platform) {
+    if (!value)
+        return [];
+    const args = [];
+    let current = "";
+    let quote = null;
+    let escaped = false;
+    const preserveBackslashes = platform === "win32";
+    const pushCurrent = () => {
+        if (current)
+            args.push(current);
+        current = "";
+    };
+    for (let index = 0; index < value.length; index++) {
+        const character = value[index];
+        if (escaped) {
+            current += character;
+            escaped = false;
+            continue;
+        }
+        if (character === "\\" && quote !== "'") {
+            if (!preserveBackslashes || value[index + 1] === '"') {
+                escaped = true;
+                continue;
+            }
+            current += character;
+            continue;
+        }
+        if (quote) {
+            if (character === quote)
+                quote = null;
+            else
+                current += character;
+            continue;
+        }
+        if (character === '"' || character === "'") {
+            quote = character;
+        }
+        else if (/\s/.test(character)) {
+            pushCurrent();
+        }
+        else {
+            current += character;
+        }
+    }
+    if (escaped || quote) {
+        throw new Error("Invalid flags: unterminated terminal argument");
+    }
+    pushCurrent();
+    return args;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.176.3",
+  "version": "0.176.4-nightly-20260901193441",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {