veryfront 0.1.218 → 0.1.220

package/esm/src/integrations/schema.js

@@ -140,6 +140,14 @@ export const IntegrationConfigSchema = z.object({
     description: z.string(),
     auth: OAuthConfigSchema,
     envVars: z.array(EnvVarSchema).optional(),
+    /**
+     * Optional map of npm packages to semver ranges. When this integration is
+     * selected during `veryfront init`, these deps are merged into the
+     * generated project's `package.json#dependencies`. Use this for templates
+     * that import packages beyond the init scaffold's defaults (react,
+     * react-dom, veryfront, zod).
+     */
+    npmDependencies: z.record(z.string(), z.string()).optional(),
     tools: z.array(IntegrationToolSchema),
     prompts: z.array(IntegrationPromptSchema).optional(),
     suggestedWith: z.array(z.string()).optional(),

package/esm/src/server/runtime-handler/request-tracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request-tracker.d.ts","sourceRoot":"","sources":["../../../../src/src/server/runtime-handler/request-tracker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,OAAO,MAAM,wBAAwB,CAAC;AASlD,UAAU,cAAc;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,UAAU,CAAC,OAAO,OAAO,CAAC,UAAU,CAAC,CAAC;IAClD,aAAa,CAAC,EAAE,UAAU,CAAC,OAAO,OAAO,CAAC,UAAU,CAAC,CAAC;CACvD;AAiBD,cAAM,cAAc;IAClB,OAAO,CAAC,QAAQ,CAAqC;IACrD,OAAO,CAAC,cAAc,CAAqD;IAC3E,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,aAAa,CAAK;;IAM1B,OAAO,CAAC,kBAAkB;IA4B1B,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,GACjB,IAAI;IAsDP,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,UAAQ,GAAG,IAAI;IAmCvE,gBAAgB,IAAI,MAAM;IAI1B,mBAAmB,IAAI,cAAc,EAAE;IAIvC,QAAQ,IAAI;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IAS9E,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,SAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAsD7E,QAAQ,IAAI,IAAI;CAUjB;AAED,eAAO,MAAM,cAAc,gBAAuB,CAAC"}
+{"version":3,"file":"request-tracker.d.ts","sourceRoot":"","sources":["../../../../src/src/server/runtime-handler/request-tracker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,OAAO,MAAM,wBAAwB,CAAC;AASlD,UAAU,cAAc;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,UAAU,CAAC,OAAO,OAAO,CAAC,UAAU,CAAC,CAAC;IAClD,aAAa,CAAC,EAAE,UAAU,CAAC,OAAO,OAAO,CAAC,UAAU,CAAC,CAAC;CACvD;AAiBD,cAAM,cAAc;IAClB,OAAO,CAAC,QAAQ,CAAqC;IACrD,OAAO,CAAC,cAAc,CAAqD;IAC3E,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,aAAa,CAAK;;IAM1B,OAAO,CAAC,kBAAkB;IA4B1B,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,GACjB,IAAI;IAuDP,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,UAAQ,GAAG,IAAI;IAgCvE,gBAAgB,IAAI,MAAM;IAI1B,mBAAmB,IAAI,cAAc,EAAE;IAIvC,QAAQ,IAAI;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IAS9E,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,SAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAsD7E,QAAQ,IAAI,IAAI;CAUjB;AAED,eAAO,MAAM,cAAc,gBAAuB,CAAC"}

package/esm/src/server/runtime-handler/request-tracker.js

@@ -7,7 +7,7 @@
 import * as dntShim from "../../../_dnt.shims.js";
 import { serverLogger } from "../../utils/index.js";
 import { unrefTimer } from "../../platform/compat/process.js";
-import { isWebSocketPath } from "./request-utils.js";
+import { isLightweightPath, isWebSocketPath } from "./request-utils.js";
 const logger = serverLogger.component("request-tracker");
 /** Threshold in ms before logging a warning about a slow request */
 const SLOW_REQUEST_THRESHOLD_MS = 10_000; // 10 seconds
@@ -66,8 +66,9 @@ class RequestTracker {
             env,
             releaseId,
         };
-        // WebSocket connections are long-lived by design — don't flag them as stuck.
-        if (!isWebSocketPath(path)) {
+        // WebSocket connections are long-lived by design and lightweight internal
+        // asset/module requests can be noisy under CI jitter — don't flag them as stuck.
+        if (!isWebSocketPath(path) && !isLightweightPath(path)) {
             tracked.slowTimer = dntShim.setTimeout(() => {
                 const elapsedMs = Math.round(performance.now() - startTime);
                 logger.warn("Slow request detected", {
@@ -118,9 +119,7 @@ class RequestTracker {
             this.totalTimedOut++;
         else
             this.totalCompleted++;
-        const isModuleRequest = tracked.path.startsWith("/_vf_modules/") ||
-            tracked.path.startsWith("/_veryfront/");
-        if (isModuleRequest) {
+        if (isLightweightPath(tracked.path)) {
             if (durationMs > MODULE_REQUEST_LOG_THRESHOLD_MS) {
                 logger.debug(`${tracked.method} ${tracked.path} ${statusCode} ${durationMs}ms`);
             }

package/esm/src/server/runtime-handler/request-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request-utils.d.ts","sourceRoot":"","sources":["../../../../src/src/server/runtime-handler/request-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAErE,qDAAqD;AACrD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAkBpD;AAED,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,aAA+C,CAAC;AAK7E,yFAAyF;AACzF,wBAAgB,iBAAiB,IAAI,MAAM,CAK1C;AAED,OAAO,EAAE,oBAAoB,EAAE,CAAC;AAEhC,sEAAsE;AACtE,eAAO,MAAM,gBAAgB,eAA4B,CAAC;AAE1D,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,uFAAuF;AACvF,eAAO,MAAM,yBAAyB,UAQrC,CAAC;AAEF,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEnE"}
+{"version":3,"file":"request-utils.d.ts","sourceRoot":"","sources":["../../../../src/src/server/runtime-handler/request-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAErE,qDAAqD;AACrD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAkBpD;AAED,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,aAA+C,CAAC;AAK7E,yFAAyF;AACzF,wBAAgB,iBAAiB,IAAI,MAAM,CAK1C;AAED,OAAO,EAAE,oBAAoB,EAAE,CAAC;AAEhC,sEAAsE;AACtE,eAAO,MAAM,gBAAgB,eAA4B,CAAC;AAE1D,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,uFAAuF;AACvF,eAAO,MAAM,yBAAyB,UASrC,CAAC;AAEF,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEnE"}

package/esm/src/server/runtime-handler/request-utils.js

@@ -48,6 +48,7 @@ export function isMonitoringPath(pathname) {
 /** Lightweight paths that should skip concurrency limiting (modules, static assets) */
 export const LIGHTWEIGHT_PATH_PREFIXES = [
     "/_vf_modules/",
+    "/_vf_styles/",
     "/_veryfront/modules/",
     "/_veryfront/hydration-runtime.js",
     "/_veryfront/preview-hmr.js",

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

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.218";
+export declare const VERSION = "0.1.220";
 //# 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.218";
+export const VERSION = "0.1.220";

package/package.json

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

package/src/cli/commands/init/config-generator.ts

@@ -5,9 +5,23 @@ import { createFileSystem } from "../../../src/platform/index.js";
 // Keep init scaffold aligned with current framework default React major/minor.
 const DEFAULT_INIT_REACT_VERSION = "19.1.1";
 
+export interface CreatePackageJsonOptions {
+  /**
+   * Selected integrations whose `connector.json#npmDependencies` should be
+   * merged into the generated project's `package.json#dependencies`.
+   * First declaration wins on version collisions; framework pins
+   * (react, react-dom, veryfront, zod) always take precedence.
+   */
+  integrations?: Array<{
+    name: string;
+    npmDependencies?: Record<string, string>;
+  }>;
+}
+
 export async function createPackageJson(
   projectDir: string,
   projectName?: string,
+  options: CreatePackageJsonOptions = {},
 ): Promise<void> {
   const fs = createFileSystem();
 
@@ -19,6 +33,24 @@ export async function createPackageJson(
     templateDeps = existing.dependencies ?? {};
   }
 
+  // Merge per-integration deps. First declaration wins; collisions are logged.
+  const integrationDeps: Record<string, string> = {};
+  for (const integration of options.integrations ?? []) {
+    for (const [pkg, range] of Object.entries(integration.npmDependencies ?? {})) {
+      if (pkg in integrationDeps) {
+        if (integrationDeps[pkg] !== range) {
+          logger.warn(
+            `[init] ${integration.name} requested ${pkg}@${range} but ${pkg}@${
+              integrationDeps[pkg]
+            } is already pinned by an earlier integration - keeping the earlier pin`,
+          );
+        }
+        continue;
+      }
+      integrationDeps[pkg] = range;
+    }
+  }
+
   const dirName = projectDir.split(/[/\\]/).pop();
   const packageJson = {
     name: projectName ?? dirName ?? "veryfront-project",
@@ -34,6 +66,7 @@ export async function createPackageJson(
     },
     dependencies: {
       ...templateDeps,
+      ...integrationDeps,
       react: `^${DEFAULT_INIT_REACT_VERSION}`,
       "react-dom": `^${DEFAULT_INIT_REACT_VERSION}`,
       veryfront: `^${VERSION}`,

package/src/cli/commands/init/init-command.ts

@@ -269,6 +269,7 @@ export async function initCommand(options: InitOptions): Promise<void> {
 
   const allEnvVars: EnvVarConfig[] = templateConfig?.envVars ? [...templateConfig.envVars] : [];
   const featureTips: string[] = [];
+  let loadedIntegrations: ResolvedIntegration[] = [];
 
   if (features.length) {
     const { ordered, errors } = await resolveFeatures(features);
@@ -309,10 +310,11 @@ export async function initCommand(options: InitOptions): Promise<void> {
     if (baseConfig?.envVars) allEnvVars.push(...baseConfig.envVars);
 
     const {
-      integrations: loadedIntegrations,
+      integrations: resolvedIntegrations,
       files: integrationFiles,
       errors: integrationErrors,
     } = await loadIntegrations(integrations);
+    loadedIntegrations = resolvedIntegrations;
 
     if (integrationErrors.length) {
       for (const error of integrationErrors) logger.warn(error);
@@ -359,7 +361,12 @@ export async function initCommand(options: InitOptions): Promise<void> {
 
     // Skip in quiet/TUI mode since local dev uses CDN and package.json can cause hydration issues
     if (!options.quiet) {
-      await createPackageJson(projectDir, projectName);
+      await createPackageJson(projectDir, projectName, {
+        integrations: loadedIntegrations.map((integration) => ({
+          name: integration.config.name,
+          npmDependencies: integration.config.npmDependencies,
+        })),
+      });
     }
 
     if (allEnvVars.length) {

package/src/deno.js

@@ -1,6 +1,6 @@
 export default {
   "name": "veryfront",
-  "version": "0.1.218",
+  "version": "0.1.220",
   "license": "Apache-2.0",
   "nodeModulesDir": "auto",
   "workspace": [
@@ -264,7 +264,6 @@ export default {
     "tailwindcss/plugin": "https://esm.sh/tailwindcss@4.2.2/plugin",
     "tailwindcss/defaultTheme": "https://esm.sh/tailwindcss@4.2.2/defaultTheme",
     "tailwindcss/colors": "https://esm.sh/tailwindcss@4.2.2/colors",
-    "pg": "npm:pg@8.13.1",
     "@opentelemetry/api": "npm:@opentelemetry/api@1.9.0",
     "@opentelemetry/core": "npm:@opentelemetry/core@2.6.0",
     "@opentelemetry/context-async-hooks": "npm:@opentelemetry/context-async-hooks@2.6.0",

package/src/src/agent/ag-ui-detached-start.ts

@@ -0,0 +1,453 @@
+import { z } from "zod";
+import { INVALID_ARGUMENT } from "../errors/index.js";
+import { SKILL_TOOL_IDS } from "../skill/types.js";
+import { type Tool, toolRegistry } from "../tool/index.js";
+import { streamDataStreamEvents } from "./data-stream.js";
+import { type AgUiInjectedTool, type AgUiRequest, AgUiRequestSchema } from "./ag-ui-handler.js";
+import {
+  AgentRuntime,
+  RunAlreadyExistsError,
+  type RunResumeSessionManager,
+} from "./runtime/index.js";
+import type { Agent, Message } from "./types.js";
+
+const AGENT_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
+const AG_UI_DETACHED_RUN_ID_SCHEMA = z.string().min(1).max(128).regex(AGENT_ID_PATTERN);
+const MAX_TEXT_PART_LENGTH = 10_000;
+
+type AgUiResumeValue = {
+  result: unknown;
+  isError: boolean;
+};
+
+type AgUiContextValue =
+  | Record<string, unknown>
+  | ((request: Request) => Record<string, unknown> | Promise<Record<string, unknown>>);
+
+type AgUiRuntimePart = Record<string, unknown> & { type: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeToolArgs(part: Record<string, unknown>): Record<string, unknown> {
+  if (isRecord(part.args)) return part.args;
+  if (isRecord(part.input)) return part.input;
+  return {};
+}
+
+function normalizeMessagePart(part: Record<string, unknown>): Message["parts"][number] | null {
+  if (
+    part.type === "text" && typeof part.text === "string" &&
+    part.text.length <= MAX_TEXT_PART_LENGTH
+  ) {
+    return { type: "text", text: part.text };
+  }
+
+  if (part.type === "tool_call" && typeof part.id === "string" && typeof part.name === "string") {
+    return {
+      type: "tool-call",
+      toolCallId: part.id,
+      toolName: part.name,
+      args: normalizeToolArgs(part),
+    };
+  }
+
+  if (
+    part.type === "tool-call" &&
+    typeof part.toolCallId === "string" &&
+    typeof part.toolName === "string"
+  ) {
+    return {
+      type: "tool-call",
+      toolCallId: part.toolCallId,
+      toolName: part.toolName,
+      args: normalizeToolArgs(part),
+    };
+  }
+
+  if (
+    typeof part.type === "string" &&
+    part.type.startsWith("tool-") &&
+    part.type !== "tool-result" &&
+    typeof part.toolCallId === "string" &&
+    typeof part.toolName === "string"
+  ) {
+    return {
+      type: part.type,
+      toolCallId: part.toolCallId,
+      toolName: part.toolName,
+      args: normalizeToolArgs(part),
+    };
+  }
+
+  if (part.type === "tool_result" && typeof part.tool_call_id === "string") {
+    return {
+      type: "tool-result",
+      toolCallId: part.tool_call_id,
+      toolName: typeof part.tool_name === "string" ? part.tool_name : "unknown",
+      result: "output" in part ? part.output : undefined,
+    };
+  }
+
+  if (part.type === "tool-result" && typeof part.toolCallId === "string") {
+    return {
+      type: "tool-result",
+      toolCallId: part.toolCallId,
+      toolName: typeof part.toolName === "string" ? part.toolName : "unknown",
+      result: "result" in part ? part.result : undefined,
+    };
+  }
+
+  return null;
+}
+
+function normalizeMessages(messages: AgUiRequest["messages"]): Message[] {
+  return messages.map((message) => ({
+    id: message.id,
+    role: message.role,
+    parts: message.parts
+      .map((part) => normalizeMessagePart(part))
+      .filter((part): part is Message["parts"][number] => part !== null),
+    ...(message.createdAt ? { timestamp: Date.parse(message.createdAt) || undefined } : {}),
+    ...(message.metadata ? { metadata: message.metadata } : {}),
+  }));
+}
+
+function isRequest(obj: unknown): obj is Request {
+  return (
+    typeof obj === "object" &&
+    obj !== null &&
+    "json" in obj &&
+    typeof obj.json === "function" &&
+    "url" in obj &&
+    typeof obj.url === "string" &&
+    "method" in obj &&
+    typeof obj.method === "string"
+  );
+}
+
+function extractRequest(requestOrCtx: unknown): Request {
+  if (isRequest(requestOrCtx)) return requestOrCtx;
+
+  if (typeof requestOrCtx === "object" && requestOrCtx !== null && "request" in requestOrCtx) {
+    const candidate = (requestOrCtx as Record<string, unknown>).request;
+    if (isRequest(candidate)) return candidate;
+  }
+
+  throw INVALID_ARGUMENT.create({
+    detail: "Invalid handler argument: expected Request or APIContext",
+  });
+}
+
+function buildStreamContext(
+  request: AgUiDetachedStartRequest,
+  baseContext: Record<string, unknown>,
+  threadId: string,
+  runId: string,
+): Record<string, unknown> {
+  return {
+    ...baseContext,
+    threadId,
+    runId,
+    agUi: {
+      context: request.context,
+      forwardedProps: request.forwardedProps,
+    },
+  };
+}
+
+function createInjectedAgUiTool(
+  runId: string,
+  tool: AgUiInjectedTool,
+  sessionManager: RunResumeSessionManager<AgUiResumeValue>,
+): Tool {
+  return {
+    id: tool.name,
+    type: "function",
+    description: tool.description ?? tool.name,
+    inputSchema: z.record(z.string(), z.unknown()),
+    inputSchemaJson: (tool.parameters ??
+      { type: "object", properties: {}, additionalProperties: true }) as Tool["inputSchemaJson"],
+    execute: async (_input, context) => {
+      const toolCallId = typeof context?.toolCallId === "string" ? context.toolCallId : null;
+      if (!toolCallId) {
+        throw new Error(`Missing toolCallId for injected tool "${tool.name}"`);
+      }
+
+      sessionManager.prepareForSignal(runId, toolCallId);
+      const submitted = await sessionManager.waitForSignal(runId, toolCallId);
+      if (submitted.isError) {
+        throw new Error(
+          typeof submitted.result === "string"
+            ? submitted.result
+            : JSON.stringify(submitted.result),
+        );
+      }
+      return submitted.result;
+    },
+  };
+}
+
+function buildMergedTools(
+  agent: Agent,
+  request: AgUiDetachedStartRequest,
+  sessionManager: RunResumeSessionManager<AgUiResumeValue>,
+): Agent["config"]["tools"] {
+  const injectedTools = Object.fromEntries(
+    request.tools.map((tool) => [
+      tool.name,
+      createInjectedAgUiTool(request.runId, tool, sessionManager),
+    ]),
+  );
+
+  if (!agent.config.tools) {
+    return Object.keys(injectedTools).length > 0 ? injectedTools : undefined;
+  }
+
+  if (agent.config.tools === true) {
+    const merged: Record<string, Tool | boolean> = {};
+    for (const [toolId] of toolRegistry.getAll()) {
+      if (!agent.config.skills && SKILL_TOOL_IDS.has(toolId)) {
+        continue;
+      }
+      merged[toolId] = true;
+    }
+    return { ...merged, ...injectedTools };
+  }
+
+  return { ...agent.config.tools, ...injectedTools };
+}
+
+async function resolveContextValue(
+  value: AgUiContextValue | undefined,
+  request: Request,
+): Promise<Record<string, unknown>> {
+  if (typeof value === "function") {
+    return await value(request);
+  }
+
+  return value ?? {};
+}
+
+function scheduleDetachedTask(requestOrCtx: unknown, task: Promise<void>): void {
+  if (
+    typeof requestOrCtx === "object" &&
+    requestOrCtx !== null &&
+    "waitUntil" in requestOrCtx &&
+    typeof (requestOrCtx as Record<string, unknown>).waitUntil === "function"
+  ) {
+    ((requestOrCtx as { waitUntil: (promise: Promise<void>) => void }).waitUntil)(task);
+    return;
+  }
+
+  void task;
+}
+
+async function drainRuntimeStream(
+  stream: ReadableStream<Uint8Array>,
+): Promise<void> {
+  for await (const _event of streamDataStreamEvents(stream) as AsyncIterable<AgUiRuntimePart>) {
+    continue;
+  }
+}
+
+export const AgUiDetachedStartRequestSchema = AgUiRequestSchema.extend({
+  threadId: z.string().uuid(),
+  runId: AG_UI_DETACHED_RUN_ID_SCHEMA,
+});
+
+export const AgUiDetachedStartAcceptedSchema = z.object({
+  accepted: z.literal(true),
+  duplicate: z.boolean(),
+  runId: AG_UI_DETACHED_RUN_ID_SCHEMA,
+  threadId: z.string().uuid(),
+});
+
+export type AgUiDetachedStartRequest = z.infer<typeof AgUiDetachedStartRequestSchema>;
+export type AgUiDetachedStartAccepted = z.infer<typeof AgUiDetachedStartAcceptedSchema>;
+
+interface AgUiDetachedStartExecutionInput {
+  request: AgUiDetachedStartRequest;
+  requestOrCtx: unknown;
+  rawRequest: Request;
+  context: Record<string, unknown>;
+  abortSignal: AbortSignal;
+}
+
+type AgUiDetachedExecutionStarter = (
+  input: AgUiDetachedStartExecutionInput,
+) => Promise<void> | void;
+
+interface AgUiDetachedStartHandlerOptionsBase {
+  sessionManager: RunResumeSessionManager<AgUiResumeValue>;
+  context?: AgUiContextValue;
+  startDetachedExecution?: AgUiDetachedExecutionStarter;
+  onAccepted?: (input: {
+    request: AgUiDetachedStartRequest;
+    runId: string;
+    threadId: string;
+  }) => Promise<void> | void;
+  onDuplicate?: (input: {
+    request: AgUiDetachedStartRequest;
+    runId: string;
+    threadId: string;
+  }) => Promise<void> | void;
+  onFinish?: (input: { runId: string; threadId: string }) => Promise<void> | void;
+  onError?: (input: { runId: string; threadId: string; error: unknown }) => Promise<void> | void;
+}
+
+export type AgUiDetachedStartHandlerOptions =
+  | (AgUiDetachedStartHandlerOptionsBase & { agent: Agent })
+  | (AgUiDetachedStartHandlerOptionsBase & {
+    agent?: undefined;
+    startDetachedExecution: AgUiDetachedExecutionStarter;
+  });
+
+async function startDefaultDetachedExecution(input: {
+  agent: Agent;
+  request: AgUiDetachedStartRequest;
+  context: Record<string, unknown>;
+  abortSignal: AbortSignal;
+  sessionManager: RunResumeSessionManager<AgUiResumeValue>;
+}): Promise<void> {
+  const runtime = new AgentRuntime(input.agent.id, {
+    ...input.agent.config,
+    tools: buildMergedTools(input.agent, input.request, input.sessionManager),
+  });
+
+  const runtimeStream = await runtime.stream(
+    normalizeMessages(input.request.messages),
+    buildStreamContext(input.request, input.context, input.request.threadId, input.request.runId),
+    undefined,
+    input.request.model,
+    input.request.maxOutputTokens,
+    input.abortSignal,
+  );
+
+  await drainRuntimeStream(runtimeStream);
+}
+
+export function createAgUiDetachedStartHandler(
+  options: AgUiDetachedStartHandlerOptions,
+): (requestOrCtx: unknown) => Promise<Response> {
+  if (!options.agent && !options.startDetachedExecution) {
+    throw new Error(
+      "Detached AG-UI start requires either an agent or startDetachedExecution handler.",
+    );
+  }
+
+  return async function POST(requestOrCtx: unknown): Promise<Response> {
+    const request = extractRequest(requestOrCtx);
+
+    try {
+      const parsed = AgUiDetachedStartRequestSchema.parse(await request.json());
+      const context = await resolveContextValue(options.context, request);
+
+      try {
+        const abortSignal = options.sessionManager.startRun({
+          runId: parsed.runId,
+          threadId: parsed.threadId,
+        });
+
+        await options.onAccepted?.({
+          request: parsed,
+          runId: parsed.runId,
+          threadId: parsed.threadId,
+        });
+
+        const detachedTask = (async () => {
+          try {
+            if (options.startDetachedExecution) {
+              await options.startDetachedExecution({
+                request: parsed,
+                requestOrCtx,
+                rawRequest: request,
+                context,
+                abortSignal,
+              });
+            } else if (options.agent) {
+              await startDefaultDetachedExecution({
+                agent: options.agent,
+                request: parsed,
+                context,
+                abortSignal,
+                sessionManager: options.sessionManager,
+              });
+            } else {
+              throw new Error(
+                "Detached AG-UI start configuration became invalid during execution.",
+              );
+            }
+
+            options.sessionManager.completeRun(parsed.runId);
+            await options.onFinish?.({
+              runId: parsed.runId,
+              threadId: parsed.threadId,
+            });
+          } catch (error) {
+            options.sessionManager.failRun(parsed.runId);
+            await options.onError?.({
+              runId: parsed.runId,
+              threadId: parsed.threadId,
+              error,
+            });
+          }
+        })().catch(() => undefined);
+
+        scheduleDetachedTask(requestOrCtx, detachedTask);
+
+        return Response.json(
+          {
+            accepted: true,
+            duplicate: false,
+            runId: parsed.runId,
+            threadId: parsed.threadId,
+          } satisfies AgUiDetachedStartAccepted,
+          { status: 202 },
+        );
+      } catch (error) {
+        if (error instanceof RunAlreadyExistsError) {
+          await options.onDuplicate?.({
+            request: parsed,
+            runId: parsed.runId,
+            threadId: parsed.threadId,
+          });
+
+          return Response.json(
+            {
+              accepted: true,
+              duplicate: true,
+              runId: parsed.runId,
+              threadId: parsed.threadId,
+            } satisfies AgUiDetachedStartAccepted,
+            { status: 202 },
+          );
+        }
+
+        options.sessionManager.failRun(parsed.runId);
+        throw error;
+      }
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        return Response.json(
+          {
+            error: "Invalid AG-UI detached start request",
+            details: error.issues.map((issue) => ({
+              path: issue.path,
+              message: issue.message,
+            })),
+          },
+          { status: 400 },
+        );
+      }
+
+      return Response.json(
+        {
+          error: error instanceof Error ? error.message : "Internal detached start failed",
+        },
+        { status: 500 },
+      );
+    }
+  };
+}

package/src/src/agent/index.ts

@@ -173,6 +173,14 @@ export {
   getProviderNativeToolNames,
   type ProviderNativeToolInventoryOptions,
 } from "./provider-native-tool-inventory.js";
+export {
+  type AgUiDetachedStartAccepted,
+  AgUiDetachedStartAcceptedSchema,
+  type AgUiDetachedStartHandlerOptions,
+  type AgUiDetachedStartRequest,
+  AgUiDetachedStartRequestSchema,
+  createAgUiDetachedStartHandler,
+} from "./ag-ui-detached-start.js";
 export {
   type AgUiCancelHandlerOptions,
   type AgUiResumeHandlerOptions,