veryfront 0.1.157 → 0.1.161

package/esm/src/platform/adapters/fs/veryfront/stat-operations.js

@@ -255,7 +255,7 @@ export class StatOperations extends VeryfrontOperationsBase {
         this.cache.set(cacheKey, files);
         return files;
     }
-    buildResolveSearchPatterns(normalizedPath, options) {
+    buildResolveSearchPatterns(normalizedPath, options, knownExtensionFallback = "exact") {
         const patterns = new Set();
         const pathWithoutExt = stripKnownExtension(normalizedPath, EXTENSION_PRIORITY);
         const allowPagesPrefix = options?.allowPagesPrefix !== false;
@@ -264,7 +264,7 @@ export class StatOperations extends VeryfrontOperationsBase {
                 patterns.add(pattern);
         };
         if (EXTENSION_PRIORITY.some((ext) => normalizedPath.endsWith(ext))) {
-            addPattern(normalizedPath);
+            addPattern(knownExtensionFallback === "wildcard" ? `${pathWithoutExt}.*` : normalizedPath);
             return [...patterns];
         }
         addPattern(`${pathWithoutExt}.*`);
@@ -282,7 +282,7 @@ export class StatOperations extends VeryfrontOperationsBase {
             path: normalizeIndexedFilePath(match).normalizedPath,
         }));
     }
-    async tryResolveViaApiSearch(normalizedPath, options) {
+    async tryResolveViaApiSearch(normalizedPath, options, knownExtensionFallback = "exact") {
         if (isFrameworkSourcePath(normalizedPath)) {
             logger.debug("Skipping API search for framework path", { normalizedPath });
             return null;
@@ -291,7 +291,7 @@ export class StatOperations extends VeryfrontOperationsBase {
             logger.warn("API search circuit breaker open, skipping", { normalizedPath });
             return undefined;
         }
-        const patterns = this.buildResolveSearchPatterns(normalizedPath, options);
+        const patterns = this.buildResolveSearchPatterns(normalizedPath, options, knownExtensionFallback);
         let sawSuccessfulSearch = false;
         for (const pattern of patterns) {
             try {
@@ -459,49 +459,17 @@ export class StatOperations extends VeryfrontOperationsBase {
             logger.debug("Skipping API search for framework path", { normalizedPath });
             return null;
         }
-        // NOTE: Removed optimization that skipped API search for paths with extensions.
-        // This was causing layout files and other project files to not be found when
-        // they were missing from the file index (due to cache issues, incomplete fetch, etc.).
-        // The API pattern search is the fallback to ensure files can still be found.
-        if (!this.apiSearchCircuitBreaker.canSearch()) {
-            logger.warn("API search circuit breaker open, skipping", { normalizedPath });
-            return null;
-        }
-        const searchPattern = `${pathWithoutExt}.*`;
-        logger.debug("Searching for file via API", {
-            pattern: searchPattern,
-            normalizedPath,
-        });
-        try {
-            const matches = await this.client.searchFiles(searchPattern);
-            this.apiSearchCircuitBreaker.recordSuccess();
-            logger.debug("API search result", {
-                pattern: searchPattern,
-                matchCount: matches.length,
-                matches: matches.map((m) => m.path).slice(0, 5),
-            });
-            const sortedMatches = sortPathsByExtensionPriority(matches, EXTENSION_PRIORITY);
-            const first = sortedMatches[0];
-            if (first) {
-                logger.debug("resolveFile found via API search", { path: first.path });
-                this.cache.set(cacheKey, first.path);
-                return first.path;
-            }
+        // NOTE: Keep the post-index API fallback aligned with the pre-index helper for extensionless
+        // paths, while preserving the older wildcard sibling-extension lookup for known-extension
+        // paths. Incomplete file-list snapshots otherwise hide valid files until the cache refreshes.
+        const apiResolved = await this.tryResolveViaApiSearch(normalizedPath, options, "wildcard");
+        if (typeof apiResolved === "string") {
+            this.cache.set(cacheKey, apiResolved);
+            return apiResolved;
         }
-        catch (error) {
-            const result = this.apiSearchCircuitBreaker.recordFailure();
-            if (result.tripped) {
-                logger.warn("API search circuit breaker tripped", {
-                    failures: result.failures,
-                });
-            }
-            logger.error("API pattern search failed", { pattern: searchPattern, error });
+        if (apiResolved === null) {
+            this.cache.set(cacheKey, NOT_FOUND_SENTINEL);
         }
-        logger.debug("resolveFile not found after API search", {
-            normalizedPath,
-            pathWithoutExt,
-        });
-        this.cache.set(cacheKey, NOT_FOUND_SENTINEL);
         return null;
     }
 }

package/esm/src/routing/api/module-loader/loader.d.ts

@@ -1,4 +1,11 @@
 import type { APIRoute, LoadModuleOptions } from "./types.js";
+import type { FileSystem } from "../../../platform/compat/fs.js";
 export declare function toCjsDestructureBindings(bindings: string): string;
 export declare function loadHandlerModule(options: LoadModuleOptions): Promise<APIRoute | null>;
+export declare function getNodeExternalPackagesToResolve(userDeps: Map<string, string>): string[];
+export declare function resolveNodePackageToFileUrl(projectDir: string, packageName: string, fs: FileSystem, pathToFileURL: typeof import("node:url").pathToFileURL): Promise<string | null>;
+export declare function loadVeryfrontExportsMap(projectDir: string, fs: FileSystem): Promise<Record<string, {
+    import?: string;
+}>>;
+export declare function rewriteNodeExternalImports(code: string, projectDir: string, fs: FileSystem, userDeps: Map<string, string>): Promise<string>;
 //# sourceMappingURL=loader.d.ts.map

package/esm/src/routing/api/module-loader/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../../../src/src/routing/api/module-loader/loader.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAgL9D,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAejE;AAgBD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAyBtF"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../../../src/src/routing/api/module-loader/loader.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAI9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AA4KjE,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAejE;AAgBD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAyBtF;AAuaD,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,EAAE,CAUxF;AAED,wBAAsB,2BAA2B,CAC/C,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,UAAU,EACd,aAAa,EAAE,cAAc,UAAU,EAAE,aAAa,GACrD,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoBxB;AAED,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,UAAU,GACb,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAW9C;AAED,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,UAAU,EACd,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,OAAO,CAAC,MAAM,CAAC,CA6EjB"}

package/esm/src/routing/api/module-loader/loader.js

@@ -512,105 +512,115 @@ async function loadModuleFromCode(code, projectDir, fs, userDeps = new Map()) {
         await fs.remove(tempDir, { recursive: true });
     }
 }
-async function rewriteExternalImports(code, projectDir, fs, userDeps = new Map()) {
+export function getNodeExternalPackagesToResolve(userDeps) {
+    const externalPackagesToResolve = ["zod"];
+    for (const name of userDeps.keys()) {
+        if (!externalPackagesToResolve.includes(name)) {
+            externalPackagesToResolve.push(name);
+        }
+    }
+    return externalPackagesToResolve;
+}
+export async function resolveNodePackageToFileUrl(projectDir, packageName, fs, pathToFileURL) {
+    const packagePath = pathHelper.join(projectDir, "node_modules", packageName);
+    const packageJsonPath = pathHelper.join(packagePath, "package.json");
+    try {
+        const pkgJson = JSON.parse(await fs.readTextFile(packageJsonPath));
+        let entryPoint;
+        if (pkgJson.exports) {
+            entryPoint = resolveExportEntry(pkgJson.exports["."]);
+        }
+        entryPoint ||= pkgJson.module || pkgJson.main || "index.js";
+        if (!entryPoint)
+            return null;
+        return pathToFileURL(pathHelper.join(packagePath, entryPoint)).href;
+    }
+    catch (_) {
+        /* expected: package.json may not exist or be invalid */
+        return null;
+    }
+}
+export async function loadVeryfrontExportsMap(projectDir, fs) {
+    const vfPackagePath = pathHelper.join(projectDir, "node_modules", "veryfront");
+    const vfPackageJsonPath = pathHelper.join(vfPackagePath, "package.json");
+    try {
+        const pkgJson = JSON.parse(await fs.readTextFile(vfPackageJsonPath));
+        return pkgJson.exports || {};
+    }
+    catch (_error) {
+        logger.debug("Could not read veryfront package.json");
+        return {};
+    }
+}
+export async function rewriteNodeExternalImports(code, projectDir, fs, userDeps) {
+    const { pathToFileURL } = await import("node:url");
     let transformed = code;
-    if (isNode) {
-        try {
-            const { pathToFileURL } = await import("node:url");
-            logger.debug(`Rewriting external imports for Node.js, projectDir: ${projectDir}`);
-            const resolvePackageToFileUrl = async (packageName) => {
-                const packagePath = pathHelper.join(projectDir, "node_modules", packageName);
-                const packageJsonPath = pathHelper.join(packagePath, "package.json");
-                try {
-                    const pkgJson = JSON.parse(await fs.readTextFile(packageJsonPath));
-                    let entryPoint;
-                    if (pkgJson.exports) {
-                        entryPoint = resolveExportEntry(pkgJson.exports["."]);
-                    }
-                    entryPoint ||= pkgJson.module || pkgJson.main || "index.js";
-                    if (!entryPoint)
-                        return null;
-                    return pathToFileURL(pathHelper.join(packagePath, entryPoint)).href;
-                }
-                catch (_) {
-                    /* expected: package.json may not exist or be invalid */
-                    return null;
-                }
-            };
-            const externalPackagesToResolve = ["zod"];
-            for (const name of userDeps.keys()) {
-                if (!externalPackagesToResolve.includes(name)) {
-                    externalPackagesToResolve.push(name);
-                }
-            }
-            for (const pkg of externalPackagesToResolve) {
-                const escapedPkg = pkg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-                // Match both exact imports (from "pkg") and subpath imports (from "pkg/sub")
-                const staticImportRegex = new RegExp(`from\\s*["']${escapedPkg}(/[^"']*)?["']`, "g");
-                const dynamicImportRegex = new RegExp(`import\\s*\\(\\s*["']${escapedPkg}(/[^"']*)?["']\\s*\\)`, "g");
-                const needsStatic = staticImportRegex.test(transformed);
-                staticImportRegex.lastIndex = 0;
-                const needsDynamic = dynamicImportRegex.test(transformed);
-                dynamicImportRegex.lastIndex = 0;
-                if (!needsStatic && !needsDynamic)
-                    continue;
-                const packageDir = pathToFileURL(pathHelper.join(projectDir, "node_modules", pkg)).href;
-                const resolvedUrl = await resolvePackageToFileUrl(pkg);
-                if (needsStatic) {
-                    transformed = transformed.replace(staticImportRegex, (_, subpath) => {
-                        if (subpath) {
-                            const subUrl = `${packageDir}${subpath}`;
-                            logger.debug(`Resolved ${pkg}${subpath} -> ${subUrl}`);
-                            return `from "${subUrl}"`;
-                        }
-                        if (!resolvedUrl)
-                            return `from "${pkg}"`;
-                        logger.debug(`Resolved ${pkg} -> ${resolvedUrl}`);
-                        return `from "${resolvedUrl}"`;
-                    });
-                }
-                if (needsDynamic) {
-                    transformed = transformed.replace(dynamicImportRegex, (_, subpath) => {
-                        if (subpath) {
-                            const subUrl = `${packageDir}${subpath}`;
-                            return `import("${subUrl}")`;
-                        }
-                        if (!resolvedUrl)
-                            return `import("${pkg}")`;
-                        return `import("${resolvedUrl}")`;
-                    });
-                }
-            }
-            const vfPackagePath = pathHelper.join(projectDir, "node_modules", "veryfront");
-            const vfPackageJsonPath = pathHelper.join(vfPackagePath, "package.json");
-            let exportsMap = {};
-            try {
-                const pkgJson = JSON.parse(await fs.readTextFile(vfPackageJsonPath));
-                exportsMap = pkgJson.exports || {};
-            }
-            catch (_error) {
-                logger.debug(`Could not read veryfront package.json: `);
-            }
-            transformed = transformed.replace(/from\s+["'](veryfront\/[^"']+)["']/g, (match, fullSpecifier) => {
-                const subpath = "./" + fullSpecifier.replace("veryfront/", "");
-                const exportEntry = exportsMap[subpath];
-                if (!exportEntry?.import) {
-                    logger.warn(`No export found for ${subpath}`);
-                    return match;
+    logger.debug(`Rewriting external imports for Node.js, projectDir: ${projectDir}`);
+    for (const pkg of getNodeExternalPackagesToResolve(userDeps)) {
+        const escapedPkg = pkg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const staticImportRegex = new RegExp(`from\\s*["']${escapedPkg}(/[^"']*)?["']`, "g");
+        const dynamicImportRegex = new RegExp(`import\\s*\\(\\s*["']${escapedPkg}(/[^"']*)?["']\\s*\\)`, "g");
+        const needsStatic = staticImportRegex.test(transformed);
+        staticImportRegex.lastIndex = 0;
+        const needsDynamic = dynamicImportRegex.test(transformed);
+        dynamicImportRegex.lastIndex = 0;
+        if (!needsStatic && !needsDynamic)
+            continue;
+        const packageDir = pathToFileURL(pathHelper.join(projectDir, "node_modules", pkg)).href;
+        const resolvedUrl = await resolveNodePackageToFileUrl(projectDir, pkg, fs, pathToFileURL);
+        if (needsStatic) {
+            transformed = transformed.replace(staticImportRegex, (_, subpath) => {
+                if (subpath) {
+                    const subUrl = `${packageDir}${subpath}`;
+                    logger.debug(`Resolved ${pkg}${subpath} -> ${subUrl}`);
+                    return `from "${subUrl}"`;
                 }
-                const resolvedPath = pathHelper.join(vfPackagePath, exportEntry.import);
-                logger.debug(`Resolved ${fullSpecifier} -> ${resolvedPath}`);
-                return `from "${pathToFileURL(resolvedPath).href}"`;
+                if (!resolvedUrl)
+                    return `from "${pkg}"`;
+                logger.debug(`Resolved ${pkg} -> ${resolvedUrl}`);
+                return `from "${resolvedUrl}"`;
             });
-            transformed = transformed.replace(/from\s+["']veryfront["']/g, () => {
-                const exportEntry = exportsMap["."];
-                if (!exportEntry?.import)
-                    return 'from "veryfront"';
-                const resolvedPath = pathHelper.join(vfPackagePath, exportEntry.import);
-                logger.debug(`Resolved veryfront -> ${resolvedPath}`);
-                return `from "${pathToFileURL(resolvedPath).href}"`;
+        }
+        if (needsDynamic) {
+            transformed = transformed.replace(dynamicImportRegex, (_, subpath) => {
+                if (subpath) {
+                    return `import("${packageDir}${subpath}")`;
+                }
+                if (!resolvedUrl)
+                    return `import("${pkg}")`;
+                return `import("${resolvedUrl}")`;
             });
         }
+    }
+    const vfPackagePath = pathHelper.join(projectDir, "node_modules", "veryfront");
+    const exportsMap = await loadVeryfrontExportsMap(projectDir, fs);
+    transformed = transformed.replace(/from\s+["'](veryfront\/[^"']+)["']/g, (match, fullSpecifier) => {
+        const subpath = "./" + fullSpecifier.replace("veryfront/", "");
+        const exportEntry = exportsMap[subpath];
+        if (!exportEntry?.import) {
+            logger.warn(`No export found for ${subpath}`);
+            return match;
+        }
+        const resolvedPath = pathHelper.join(vfPackagePath, exportEntry.import);
+        logger.debug(`Resolved ${fullSpecifier} -> ${resolvedPath}`);
+        return `from "${pathToFileURL(resolvedPath).href}"`;
+    });
+    transformed = transformed.replace(/from\s+["']veryfront["']/g, () => {
+        const exportEntry = exportsMap["."];
+        if (!exportEntry?.import)
+            return 'from "veryfront"';
+        const resolvedPath = pathHelper.join(vfPackagePath, exportEntry.import);
+        logger.debug(`Resolved veryfront -> ${resolvedPath}`);
+        return `from "${pathToFileURL(resolvedPath).href}"`;
+    });
+    return transformed;
+}
+async function rewriteExternalImports(code, projectDir, fs, userDeps = new Map()) {
+    let transformed = code;
+    if (isNode) {
+        try {
+            transformed = await rewriteNodeExternalImports(transformed, projectDir, fs, userDeps);
+        }
         catch (e) {
             logger.warn(`Failed to import node:module: ${e}`);
         }

package/esm/src/utils/version-constant.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.157";
+export declare const VERSION = "0.1.161";
 //# sourceMappingURL=version-constant.d.ts.map

package/esm/src/utils/version-constant.js

@@ -1,3 +1,3 @@
 // Keep in sync with deno.json version.
 // scripts/release.ts updates this constant during releases.
-export const VERSION = "0.1.157";
+export const VERSION = "0.1.161";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "veryfront",
-  "version": "0.1.157",
+  "version": "0.1.161",
   "description": "The simplest way to build AI-powered apps",
   "keywords": [
     "react",

package/src/cli/mcp/remote-file-tools.ts

@@ -87,6 +87,15 @@ function getBranchParam(branch?: string): string {
   return branch ? `?branch_id=${branch}` : "";
 }
 
+function buildProjectApiPath(project: string, resource: string, branch?: string): string {
+  const normalizedResource = resource.startsWith("/") ? resource.slice(1) : resource;
+  return `/${project}${getBranchPath(branch)}/${normalizedResource}`;
+}
+
+function buildProjectFilePath(project: string, filePath: string, branch?: string): string {
+  return buildProjectApiPath(project, `files/${encodeFilePath(filePath)}`, branch);
+}
+
 interface RemoteFile {
   id?: string;
   path: string;
@@ -214,9 +223,9 @@ export const vfRemoteListFiles: MCPTool<RemoteListFilesInput, RemoteListFilesOut
         params.set("limit", String(input.limit));
         params.set("fields", "(path,type,size)");
 
-        const apiPath = `/${input.project}${
-          getBranchPath(input.branch)
-        }/files?${params.toString()}`;
+        const apiPath = `${
+          buildProjectApiPath(input.project, "files", input.branch)
+        }?${params.toString()}`;
         const result = await apiRequest<FileListResponse>("GET", apiPath);
         if (!result.ok) return { success: false, error: result.error };
 
@@ -260,9 +269,7 @@ export const vfRemoteGetFile: MCPTool<RemoteGetFileInput, RemoteGetFileOutput> =
     withSpan(
       "cli.mcp.tool.vf_remote_get_file",
       async () => {
-        const apiPath = `/${input.project}${getBranchPath(input.branch)}/files/${
-          encodeFilePath(input.path)
-        }`;
+        const apiPath = buildProjectFilePath(input.project, input.path, input.branch);
         const result = await apiRequest<RemoteFile>("GET", apiPath);
         if (!result.ok) return { success: false, error: result.error };
 
@@ -314,7 +321,7 @@ export const vfRemoteUpdateFile: MCPTool<RemoteUpdateFileInput, RemoteUpdateFile
     withSpan(
       "cli.mcp.tool.vf_remote_update_file",
       async () => {
-        const apiPath = `/${input.project}/files/${encodeFilePath(input.path)}${
+        const apiPath = `${buildProjectFilePath(input.project, input.path)}${
           getBranchParam(input.branch)
         }`;
         const result = await apiRequest<{ id: string; path: string }>("PUT", apiPath, {
@@ -362,7 +369,7 @@ export const vfRemoteDeleteFile: MCPTool<RemoteDeleteFileInput, RemoteDeleteFile
   description: "Delete a file from a remote Veryfront project.",
   inputSchema: remoteDeleteFileInput,
   execute: async (input) => {
-    const apiPath = `/${input.project}/files/${encodeFilePath(input.path)}${
+    const apiPath = `${buildProjectFilePath(input.project, input.path)}${
       getBranchParam(input.branch)
     }`;
     const result = await apiRequest<void>("DELETE", apiPath);
@@ -405,7 +412,7 @@ export const vfRemoteSearchFiles: MCPTool<RemoteSearchFilesInput, RemoteSearchFi
     withSpan(
       "cli.mcp.tool.vf_remote_search_files",
       async () => {
-        const apiPath = `/${input.project}${getBranchPath(input.branch)}/files/search`;
+        const apiPath = buildProjectApiPath(input.project, "files/search", input.branch);
         const result = await apiRequest<SearchResponse>("POST", apiPath, {
           body: {
             query: input.query,
@@ -455,7 +462,11 @@ export const vfRemoteMoveFile: MCPTool<RemoteMoveFileInput, RemoteMoveFileOutput
   description: "Move or rename a file in a remote Veryfront project.",
   inputSchema: remoteMoveFileInput,
   execute: async (input) => {
-    const apiPath = `/${input.project}/files/move${getBranchParam(input.branch)}`;
+    const apiPath = `${buildProjectApiPath(input.project, "files/move")}${
+      getBranchParam(
+        input.branch,
+      )
+    }`;
     const result = await apiRequest<{ source_path: string; destination_path: string }>(
       "POST",
       apiPath,
@@ -732,7 +743,7 @@ export const vfRemoteCloneProject: MCPTool<RemoteCloneProjectInput, RemoteCloneP
 
         const listResult = await apiRequest<FileListResponse>(
           "GET",
-          `/${input.source_project}/files?${params.toString()}`,
+          `${buildProjectApiPath(input.source_project, "files")}?${params.toString()}`,
         );
 
         if (!listResult.ok) {
@@ -750,7 +761,7 @@ export const vfRemoteCloneProject: MCPTool<RemoteCloneProjectInput, RemoteCloneP
         for (const file of sourceFiles) {
           const getResult = await apiRequest<RemoteFile>(
             "GET",
-            `/${input.source_project}/files/${encodeFilePath(file.path)}`,
+            buildProjectFilePath(input.source_project, file.path),
           );
 
           if (!getResult.ok || !getResult.data) {
@@ -760,7 +771,7 @@ export const vfRemoteCloneProject: MCPTool<RemoteCloneProjectInput, RemoteCloneP
 
           const createFileResult = await apiRequest<{ id: string; path: string }>(
             "PUT",
-            `/${createResult.slug}/files/${encodeFilePath(file.path)}`,
+            buildProjectFilePath(createResult.slug, file.path),
             { body: { content: getResult.data.content } },
           );
 

package/src/deno.js

@@ -1,6 +1,6 @@
 export default {
   "name": "veryfront",
-  "version": "0.1.157",
+  "version": "0.1.161",
   "license": "Apache-2.0",
   "nodeModulesDir": "auto",
   "exclude": [

package/src/src/agent/human-input.ts

@@ -0,0 +1,152 @@
+import { z } from "zod";
+import { AgUiRuntimeRunIdSchema } from "./runtime-ag-ui-contract.js";
+import { RunResumeSessionManager } from "./runtime/index.js";
+
+const TOOL_CALL_ID_SCHEMA = z.string().min(1).max(128);
+
+export const HumanInputOptionSchema = z.object({
+  value: z.string(),
+  label: z.string(),
+  description: z.string().optional(),
+  recommended: z.boolean().optional(),
+});
+
+const BaseHumanInputFieldSchema = z.object({
+  name: z.string().min(1).max(128),
+  label: z.string().min(1).max(256),
+  description: z.string().max(1024).optional(),
+  required: z.boolean().optional().default(false),
+  secret: z.boolean().optional().default(false),
+});
+
+export const HumanInputFieldSchema = z.discriminatedUnion("type", [
+  BaseHumanInputFieldSchema.extend({
+    type: z.enum(["text", "email", "url", "password", "number"]),
+    placeholder: z.string().max(512).optional(),
+    defaultValue: z.string().optional(),
+    pattern: z.string().max(512).optional(),
+    minLength: z.number().int().nonnegative().optional(),
+    maxLength: z.number().int().positive().optional(),
+    min: z.number().optional(),
+    max: z.number().optional(),
+  }),
+  BaseHumanInputFieldSchema.extend({
+    type: z.literal("textarea"),
+    placeholder: z.string().max(512).optional(),
+    defaultValue: z.string().optional(),
+    minLength: z.number().int().nonnegative().optional(),
+    maxLength: z.number().int().positive().optional(),
+    rows: z.number().int().positive().optional().default(3),
+  }),
+  BaseHumanInputFieldSchema.extend({
+    type: z.literal("select"),
+    options: z.array(HumanInputOptionSchema).min(1),
+    defaultValue: z.string().optional(),
+    placeholder: z.string().max(512).optional(),
+  }),
+  BaseHumanInputFieldSchema.extend({
+    type: z.literal("checkbox"),
+    defaultValue: z.boolean().optional().default(false),
+  }),
+  BaseHumanInputFieldSchema.extend({
+    type: z.literal("radio"),
+    options: z.array(HumanInputOptionSchema).min(1),
+    defaultValue: z.string().optional(),
+  }),
+  BaseHumanInputFieldSchema.extend({
+    type: z.literal("confirm"),
+    confirmLabel: z.string().max(64).optional().default("Yes"),
+    denyLabel: z.string().max(64).optional().default("No"),
+  }),
+]);
+
+export const HumanInputRequestSchema = z.object({
+  title: z.string().min(1).max(256),
+  description: z.string().max(2048).optional(),
+  fields: z.array(HumanInputFieldSchema).min(1),
+  submitLabel: z.string().max(64).optional().default("Submit"),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+export const HumanInputResponseValuesSchema = z.record(
+  z.string(),
+  z.union([z.string(), z.boolean(), z.number(), z.null()]),
+);
+
+export const HumanInputResultSchema = z.discriminatedUnion("submitted", [
+  z.object({
+    submitted: z.literal(true),
+    values: HumanInputResponseValuesSchema,
+  }),
+  z.object({
+    submitted: z.literal(false),
+    values: HumanInputResponseValuesSchema.default({}),
+  }),
+]);
+
+export const HumanInputPendingRequestSchema = z.object({
+  runId: AgUiRuntimeRunIdSchema,
+  toolCallId: TOOL_CALL_ID_SCHEMA,
+  request: HumanInputRequestSchema,
+});
+
+export type HumanInputOption = z.infer<typeof HumanInputOptionSchema>;
+export type HumanInputField = z.infer<typeof HumanInputFieldSchema>;
+export type HumanInputFieldInput = z.input<typeof HumanInputFieldSchema>;
+export type HumanInputRequest = z.infer<typeof HumanInputRequestSchema>;
+export type HumanInputRequestInput = z.input<typeof HumanInputRequestSchema>;
+export type HumanInputResult = z.infer<typeof HumanInputResultSchema>;
+export type HumanInputPendingRequest = z.infer<typeof HumanInputPendingRequestSchema>;
+
+type HumanInputResumeValue = {
+  result: unknown;
+  isError: boolean;
+};
+
+export interface WaitForHumanInputOptions {
+  sessionManager: RunResumeSessionManager<HumanInputResumeValue>;
+  runId: string;
+  toolCallId: string;
+  request: HumanInputRequestInput;
+  onRequest?: ((request: HumanInputPendingRequest) => void | Promise<void>) | undefined;
+}
+
+export class HumanInputResumeError extends Error {
+  constructor(readonly detail: unknown) {
+    super(
+      typeof detail === "string" ? detail : "Human input resume failed",
+    );
+    this.name = "HumanInputResumeError";
+  }
+}
+
+export class InvalidHumanInputResultError extends Error {
+  constructor(readonly detail: z.ZodIssue[]) {
+    super("Invalid human input resume payload");
+    this.name = "InvalidHumanInputResultError";
+  }
+}
+
+export async function waitForHumanInput(
+  options: WaitForHumanInputOptions,
+): Promise<HumanInputResult> {
+  const pendingRequest = HumanInputPendingRequestSchema.parse({
+    runId: options.runId,
+    toolCallId: options.toolCallId,
+    request: options.request,
+  });
+
+  await options.onRequest?.(pendingRequest);
+
+  const resumed = await options.sessionManager.waitForSignal(options.runId, options.toolCallId);
+  if (resumed.isError) {
+    throw new HumanInputResumeError(resumed.result);
+  }
+
+  const parsed = HumanInputResultSchema.safeParse(resumed.result);
+  if (!parsed.success) {
+    throw new InvalidHumanInputResultError(parsed.error.issues);
+  }
+
+  return parsed.data;
+}

package/src/src/agent/index.ts

@@ -97,7 +97,13 @@ export type {
   MessagePart,
   ModelProvider,
   ModelString,
+  ModelTransportRequest,
+  ModelTransportResolver,
   ResolvedAgentConfig,
+  ResolvedModelTransport,
+  ResolvedRuntimeState,
+  RuntimeStateRequest,
+  RuntimeStateResolver,
   StreamToolCall,
   ToolCall,
   ToolCallPart,
@@ -162,6 +168,24 @@ export {
   AgUiRequestSchema,
   createAgUiHandler,
 } from "./ag-ui-handler.js";
+export {
+  type HumanInputField,
+  type HumanInputFieldInput,
+  HumanInputFieldSchema,
+  type HumanInputOption,
+  HumanInputOptionSchema,
+  type HumanInputPendingRequest,
+  HumanInputPendingRequestSchema,
+  type HumanInputRequest,
+  type HumanInputRequestInput,
+  HumanInputRequestSchema,
+  type HumanInputResult,
+  HumanInputResultSchema,
+  HumanInputResumeError,
+  InvalidHumanInputResultError,
+  waitForHumanInput,
+  type WaitForHumanInputOptions,
+} from "./human-input.js";
 export {
   type ChatHandlerBeforeStream,
   type ChatHandlerBeforeStreamContext,