veryfront 0.1.282 → 0.1.284

package/src/src/agent/agent-service.ts

@@ -26,21 +26,70 @@ export interface AgentServiceServerConfig {
   cors?: boolean;
 }
 
-/**
- * Phase-0 contract draft for the future framework-owned hosted agent service.
- */
-export interface AgentContract<
+export type AgentRegistry = Record<string, Agent>;
+
+export interface AgentServiceContractBase<
   TStartInput = void,
   TRun = unknown,
   TEvent = unknown,
   TTerminalState = unknown,
 > {
   serviceName: string;
-  agent: Agent;
   server?: AgentServiceServerConfig;
   durableRunSink?: DurableRunSink<TStartInput, TRun, TEvent, TTerminalState>;
 }
 
+/**
+ * Multi-agent hosted-service contract. Framework services route to
+ * `defaultAgentId` unless the host chooses another registered agent.
+ */
+export interface AgentServiceRegistryContract<
+  TStartInput = void,
+  TRun = unknown,
+  TEvent = unknown,
+  TTerminalState = unknown,
+> extends AgentServiceContractBase<TStartInput, TRun, TEvent, TTerminalState> {
+  agents: AgentRegistry;
+  defaultAgentId: string;
+}
+
+/**
+ * Single-agent convenience accepted by `defineAgentService()`. Implementations
+ * must normalize this shape into the same registry path used by multi-agent
+ * services so framework users are not boxed into one-agent-per-process.
+ */
+export interface AgentServiceSingleAgentContract<
+  TStartInput = void,
+  TRun = unknown,
+  TEvent = unknown,
+  TTerminalState = unknown,
+> extends AgentServiceContractBase<TStartInput, TRun, TEvent, TTerminalState> {
+  agent: Agent;
+  defaultAgentId?: string;
+}
+
+/**
+ * Phase-0 contract draft for the future framework-owned hosted agent service.
+ */
+export type AgentContract<
+  TStartInput = void,
+  TRun = unknown,
+  TEvent = unknown,
+  TTerminalState = unknown,
+> =
+  | AgentServiceRegistryContract<TStartInput, TRun, TEvent, TTerminalState>
+  | AgentServiceSingleAgentContract<TStartInput, TRun, TEvent, TTerminalState>;
+
+export interface NormalizedAgentServiceContract<
+  TStartInput = void,
+  TRun = unknown,
+  TEvent = unknown,
+  TTerminalState = unknown,
+> extends AgentServiceContractBase<TStartInput, TRun, TEvent, TTerminalState> {
+  agents: AgentRegistry;
+  defaultAgentId: string;
+}
+
 /**
  * Type-preserving service definition reserved ahead of the runtime
  * implementation landing in a later migration phase.
@@ -51,12 +100,47 @@ export interface AgentServiceDefinition<
   TEvent = unknown,
   TTerminalState = unknown,
 > {
-  contract: AgentContract<TStartInput, TRun, TEvent, TTerminalState>;
+  contract: NormalizedAgentServiceContract<TStartInput, TRun, TEvent, TTerminalState>;
 }
 
 const DEFINE_AGENT_SERVICE_STUB_ERROR =
   "defineAgentService() is a Phase 0 stub. The framework contract is reserved, but the hosted runtime implementation has not landed yet.";
 
+function getSingleAgentDefaultId(contract: {
+  agent: Agent;
+  defaultAgentId?: string;
+}): string {
+  return contract.defaultAgentId ?? contract.agent.id ?? "default";
+}
+
+function normalizeAgentServiceContract<
+  TStartInput = void,
+  TRun = unknown,
+  TEvent = unknown,
+  TTerminalState = unknown,
+>(
+  contract: AgentContract<TStartInput, TRun, TEvent, TTerminalState>,
+): NormalizedAgentServiceContract<TStartInput, TRun, TEvent, TTerminalState> {
+  if ("agents" in contract) {
+    return {
+      serviceName: contract.serviceName,
+      agents: contract.agents,
+      defaultAgentId: contract.defaultAgentId,
+      server: contract.server,
+      durableRunSink: contract.durableRunSink,
+    };
+  }
+
+  const defaultAgentId = getSingleAgentDefaultId(contract);
+  return {
+    serviceName: contract.serviceName,
+    agents: { [defaultAgentId]: contract.agent },
+    defaultAgentId,
+    server: contract.server,
+    durableRunSink: contract.durableRunSink,
+  };
+}
+
 /**
  * Reserve the public hosted agent-service signature before the runtime
  * implementation lands.
@@ -69,6 +153,6 @@ export function defineAgentService<
 >(
   contract: AgentContract<TStartInput, TRun, TEvent, TTerminalState>,
 ): AgentServiceDefinition<TStartInput, TRun, TEvent, TTerminalState> {
-  void contract;
+  void normalizeAgentServiceContract(contract);
   throw new Error(DEFINE_AGENT_SERVICE_STUB_ERROR);
 }

package/src/src/agent/index.ts

@@ -143,10 +143,14 @@ export {
 export { agent } from "./factory.js";
 export {
   type AgentContract,
+  type AgentRegistry,
   type AgentServiceDefinition,
+  type AgentServiceRegistryContract,
   type AgentServiceServerConfig,
+  type AgentServiceSingleAgentContract,
   defineAgentService,
   type DurableRunSink,
+  type NormalizedAgentServiceContract,
 } from "./agent-service.js";
 export {
   type AgUiRuntimeHandlerConfig,

package/src/src/agent/runtime/index.ts

@@ -47,7 +47,7 @@ import { repairToolCall } from "./repair-tool-call.js";
 import { MiddlewareChain } from "../middleware/chain.js";
 import { AGENT_DEFAULTS } from "../defaults.js";
 import { tryGetCacheKeyContext } from "../../cache/cache-key-builder.js";
-import type { ToolExecutionContext } from "../../tool/index.js";
+import type { ToolDefinition, ToolExecutionContext } from "../../tool/index.js";
 import { isLocalModelRuntime } from "../../provider/runtime-inspection.js";
 import { generateText, streamText } from "../../runtime/runtime-bridge.js";
 
@@ -110,6 +110,9 @@ const LOAD_SKILL_TOOL_ID = "load-skill";
 
 type RuntimeToolFilterConfig = AgentConfig & {
   __vfAllowedRemoteTools?: string[];
+  __vfForwardedIntegrationToolDefs?: Array<
+    { name: string; description: string; parameters: Record<string, unknown> }
+  >;
 };
 
 function isAbortError(error: unknown, abortSignal?: AbortSignal): boolean {
@@ -418,6 +421,30 @@ function getRuntimeAllowedRemoteTools(config: AgentConfig): string[] | undefined
   return raw.every((toolName) => typeof toolName === "string") ? raw : [];
 }
 
+function getRuntimeForwardedIntegrationToolDefs(
+  config: AgentConfig,
+): ToolDefinition[] | undefined {
+  const configWithFilters = config as RuntimeToolFilterConfig;
+  const raw = configWithFilters.__vfForwardedIntegrationToolDefs;
+  if (!Array.isArray(raw) || raw.length === 0) return undefined;
+  return raw
+    .filter(
+      (def): def is { name: string; description: string; parameters: Record<string, unknown> } =>
+        typeof def === "object" &&
+        def !== null &&
+        typeof def.name === "string" &&
+        typeof def.description === "string",
+    )
+    .map((def) => ({
+      name: def.name,
+      description: def.description,
+      parameters: typeof def.parameters === "object" && def.parameters !== null &&
+          !Array.isArray(def.parameters)
+        ? def.parameters
+        : { type: "object", properties: {} },
+    }));
+}
+
 type ResolvedModelTransport = {
   requestedModel: string;
   resolvedModelString: string;
@@ -722,6 +749,7 @@ export class AgentRuntime {
       // Request-scoped skill policy (not class-level mutable state)
       let activeSkillPolicy: string[] | undefined;
       const allowedRemoteToolNames = getRuntimeAllowedRemoteTools(this.config);
+      const forwardedRemoteToolDefinitions = getRuntimeForwardedIntegrationToolDefs(this.config);
       let currentSystemPrompt = systemPrompt;
       let currentRuntimeContext = runtimeContext;
 
@@ -743,6 +771,7 @@ export class AgentRuntime {
         let tools = isLocal ? [] : await getAvailableTools(this.config.tools, {
           includeSkillTools: Boolean(this.config.skills),
           allowedRemoteToolNames,
+          forwardedRemoteToolDefinitions,
           remoteToolSources: this.config.remoteTools,
           remoteToolContext: toolContext,
         });
@@ -1004,6 +1033,7 @@ export class AgentRuntime {
     let finalFinishReason: string | undefined;
     let latestAssistantText = "";
     const allowedRemoteToolNames = getRuntimeAllowedRemoteTools(this.config);
+    const forwardedRemoteToolDefinitions = getRuntimeForwardedIntegrationToolDefs(this.config);
     let currentSystemPrompt = systemPrompt;
     let currentRuntimeContext = runtimeContext;
 
@@ -1026,6 +1056,7 @@ export class AgentRuntime {
       let tools = isLocalStreaming ? [] : await getAvailableTools(this.config.tools, {
         includeSkillTools: Boolean(this.config.skills),
         allowedRemoteToolNames,
+        forwardedRemoteToolDefinitions,
         remoteToolSources: this.config.remoteTools,
         remoteToolContext: toolContext,
       });

package/src/src/agent/runtime/tool-helpers.ts

@@ -297,6 +297,27 @@ function addToolDefinition(
   tools.push(def);
 }
 
+/**
+ * Merge forwarded integration tool definitions into the remote defs array.
+ * Forwarded definitions are provided by the API when the runtime cannot
+ * fetch them directly (e.g., the runtime token lacks user auth).
+ * Only appends definitions not already present in the array.
+ */
+function appendForwardedToolDefinitions(
+  remoteDefs: ToolDefinition[],
+  forwarded: ToolDefinition[] | undefined,
+  allowedNames: string[] | undefined,
+): void {
+  if (!forwarded?.length) return;
+  const existing = new Set(remoteDefs.map((def) => def.name));
+  for (const def of forwarded) {
+    if (existing.has(def.name)) continue;
+    if (allowedNames && !allowedNames.includes(def.name)) continue;
+    remoteDefs.push(def);
+    existing.add(def.name);
+  }
+}
+
 /**
  * Get available tools based on agent configuration.
  * When tools === true, loads all tools from registry.
@@ -311,6 +332,7 @@ export async function getAvailableTools(
     includeSkillTools?: boolean;
     includeIntegrationTools?: boolean;
     allowedRemoteToolNames?: string[];
+    forwardedRemoteToolDefinitions?: ToolDefinition[];
     remoteToolSources?: RemoteToolSource[];
     remoteToolContext?: ToolExecutionContext;
   },
@@ -333,6 +355,11 @@ export async function getAvailableTools(
 
     // Append remote integration tools (per-request, project-scoped)
     const remoteDefs = await getRemoteToolDefinitions(options);
+    appendForwardedToolDefinitions(
+      remoteDefs,
+      options?.forwardedRemoteToolDefinitions,
+      options?.allowedRemoteToolNames,
+    );
     for (const def of remoteDefs) {
       logToolDefinition(def.name, def);
     }
@@ -343,6 +370,11 @@ export async function getAvailableTools(
 
   const tools: ToolDefinition[] = [];
   const remoteDefs = await getRemoteToolDefinitions(options);
+  appendForwardedToolDefinitions(
+    remoteDefs,
+    options?.forwardedRemoteToolDefinitions,
+    options?.allowedRemoteToolNames,
+  );
   const remoteToolNames = new Set(remoteDefs.map((def) => def.name));
   const explicitlyRequestedRemoteToolNames = new Set<string>();
   const unresolvedConfiguredToolNames: string[] = [];

package/src/src/embedding/resolve.ts

@@ -1,11 +1,11 @@
 import { createError, toError } from "../errors/veryfront-error.js";
 import { getGoogleGenAIEnvConfig, getOpenAIEnvConfig } from "../config/env.js";
 import { createLocalEmbeddingModel } from "../provider/local/embedding-runtime-adapter.js";
-import {
-  createGoogleEmbeddingRuntime,
-  createOpenAIEmbeddingRuntime,
-} from "../provider/runtime-loader.js";
+import { createGoogleEmbeddingRuntime } from "../provider/runtime-loader.js";
 import type { EmbeddingRuntime } from "../provider/types.js";
+import { tryResolve } from "../extensions/contracts.js";
+import type { AIProviderRegistry } from "../extensions/interfaces/index.js";
+import { AIProviderRegistryName } from "../extensions/interfaces/index.js";
 import { createVeryfrontCloudEmbeddingModel } from "./veryfront-cloud/provider.js";
 
 type EmbeddingProviderFactory = (modelId: string) => EmbeddingRuntime;
@@ -44,9 +44,20 @@ function autoInitializeFromEnv(): void {
           }),
         );
       }
-      return createOpenAIEmbeddingRuntime(
-        { apiKey: config.apiKey, baseURL: config.baseURL },
-        id,
+      const registry = tryResolve<AIProviderRegistry>(AIProviderRegistryName);
+      const provider = registry?.get("openai");
+      if (provider?.createEmbedding) {
+        return provider.createEmbedding(id, {
+          credential: config.apiKey,
+          baseURL: config.baseURL,
+        });
+      }
+      throw toError(
+        createError({
+          type: "config",
+          message:
+            "OpenAI provider not installed. Add @veryfront/ext-openai to use openai/* embedding models.",
+        }),
       );
     });
   }

package/src/src/embedding/veryfront-cloud/provider.ts

@@ -1,8 +1,5 @@
 import { createError, toError } from "../../errors/veryfront-error.js";
-import {
-  createGoogleEmbeddingRuntime,
-  createOpenAIEmbeddingRuntime,
-} from "../../provider/runtime-loader.js";
+import { createGoogleEmbeddingRuntime } from "../../provider/runtime-loader.js";
 import type { EmbeddingRuntime } from "../../provider/types.js";
 import {
   createVeryfrontCloudFetch,
@@ -19,12 +16,9 @@ export function createVeryfrontCloudEmbeddingModel(modelId: string): EmbeddingRu
 
   switch (provider) {
     case "openai":
-      return createOpenAIEmbeddingRuntime({
-        apiKey: apiToken,
-        baseURL,
-        name: "veryfront-cloud",
-        fetch,
-      }, upstreamModelId);
+      throw new Error(
+        "OpenAI provider not installed. Add @veryfront/ext-openai to use openai embedding models via veryfront-cloud.",
+      );
 
     case "google":
       return createGoogleEmbeddingRuntime({

package/src/src/extensions/contracts.ts

@@ -14,9 +14,9 @@ export function resolve<T>(name: string): T {
   if (impl === undefined) {
     const recommendation = getRecommendation(name);
     throw MISSING_EXTENSION_ERROR.create({
-      message: `Missing extension for contract "${name}"${
-        recommendation ? `. Recommended: ${recommendation}` : ""
-      }`,
+      message: recommendation
+        ? `Missing extension for contract "${name}". Install it with: deno add ${recommendation}`
+        : `Missing extension for contract "${name}"`,
       detail: recommendation ? `Install it with: deno add ${recommendation}` : undefined,
     });
   }

package/src/src/extensions/interfaces/ai-provider.ts

@@ -0,0 +1,54 @@
+/**
+ * Contract interface for LLM provider extensions.
+ *
+ * A single `AIProviderRegistry` impl lives in the contract registry under
+ * {@link AIProviderRegistryName}. Each provider extension resolves the
+ * registry in its `setup()` and calls `registry.register(provider)`.
+ * Core consumers (model-registry, veryfront-cloud) resolve the registry
+ * and dispatch on provider id parsed from `"provider/model"` strings.
+ *
+ * @module extensions/interfaces/ai-provider
+ */
+
+import type { EmbeddingRuntime, ModelRuntime } from "../../provider/types.js";
+
+/** Config passed to any provider's create* method. */
+export interface AIProviderConfig {
+  /** API credential — maps to OpenAI `apiKey`, Anthropic `authToken`, Google `apiKey` internally. */
+  credential: string;
+  /** Override the provider's base URL (e.g. Azure OpenAI, self-hosted gateway). */
+  baseURL?: string;
+  /** Override fetch (veryfront-cloud uses this to inject project auth headers). */
+  fetch?: typeof fetch;
+  /** Display name shown in errors + telemetry. Defaults to provider id. */
+  name?: string;
+  /** Provider-specific extras. */
+  [key: string]: unknown;
+}
+
+/**
+ * An LLM provider implementation. Extensions register one of these with the
+ * {@link AIProviderRegistry} during setup(). `createModel` is required;
+ * `createEmbedding` and `createResponses` are optional and absent on
+ * providers that don't support them.
+ */
+export interface AIProvider {
+  /** Stable id used in model strings: "openai" / "anthropic" / "google". */
+  readonly id: string;
+  createModel(modelId: string, config: AIProviderConfig): ModelRuntime;
+  createEmbedding?(modelId: string, config: AIProviderConfig): EmbeddingRuntime;
+  createResponses?(modelId: string, config: AIProviderConfig): ModelRuntime;
+}
+
+/** Registry contract. Single impl created at bootstrap. */
+export interface AIProviderRegistry {
+  register(provider: AIProvider): void;
+  unregister(id: string): void;
+  get(id: string): AIProvider | undefined;
+  require(id: string): AIProvider;
+  list(): AIProvider[];
+  has(id: string): boolean;
+}
+
+/** Contract name used for `resolve()` / `provide()`. */
+export const AIProviderRegistryName = "AIProviderRegistry" as const;

package/src/src/extensions/interfaces/code-parser.ts

@@ -74,6 +74,12 @@ export interface GenerateResult {
  * Implementations parse source code into ASTs, traverse/transform
  * nodes, and generate code back from modified trees.
  */
+/** Options for {@link CodeParser.injectJsxNodePositions}. */
+export interface InjectJsxNodePositionsOptions {
+  /** Source file path — emitted into `data-node-file` attributes. */
+  filePath: string;
+}
+
 export interface CodeParser {
   /** Parse source code into an abstract syntax tree. */
   parse(options: ParseOptions): Promise<ASTNode>;
@@ -81,4 +87,10 @@ export interface CodeParser {
   traverse(ast: ASTNode, visitor: TraverseVisitor): void;
   /** Generate source code from an AST. */
   generate(ast: ASTNode, options?: GenerateOptions): Promise<GenerateResult>;
+  /**
+   * Inject `data-node-*` attributes into every JSX element in the source,
+   * enabling Studio Navigator to map rendered elements back to their
+   * source positions. Parsing failures return the input unchanged.
+   */
+  injectJsxNodePositions(source: string, options: InjectJsxNodePositionsOptions): string;
 }

package/src/src/extensions/interfaces/css-processor.ts

@@ -1,40 +1,61 @@
 /**
- * Contract interface for CSS processing engines.
+ * Contract interface for CSS processing engines (Tailwind-style compile
+ * pipelines).
  *
  * Default implementation: `@veryfront/ext-tailwind`
  *
+ * The contract mirrors the Tailwind v4 `compile()` surface: a stateful
+ * compiler is constructed once per stylesheet and emits CSS output for the
+ * set of class-name candidates discovered at render time. Core scans the
+ * rendered HTML for candidates and calls `CSSCompiler.build(candidates)`
+ * on each request; the compiler accumulates state across calls, so per-
+ * project isolation is the caller's responsibility (see
+ * `tailwind-compiler-cache.ts`).
+ *
  * @module extensions/interfaces/css-processor
  */
 
-/** Options passed to {@link CSSProcessor.process}. */
-export interface CSSProcessOptions {
-  /** Raw CSS or utility-class input. */
+/** A loaded stylesheet body with the base path used to resolve relative imports. */
+export interface CSSStylesheetSource {
   content: string;
-  /** Paths to source files used for scanning class usage. */
-  sources?: string[];
-  /** Enable minification of the output. */
-  minify?: boolean;
-  /** Extra implementation-specific options. */
-  [key: string]: unknown;
+  base: string;
+  path: string;
+}
+
+/** A loaded module (Tailwind plugin). `module` is the plugin's default export. */
+export interface CSSModuleSource {
+  module: unknown;
+  base: string;
+  path: string;
+}
+
+/** Options passed to {@link CSSProcessor.compile}. */
+export interface CSSCompileOptions {
+  /** Base path used to resolve relative `@import` specifiers. */
+  base: string;
+  /** Resolver invoked when the compiler encounters an `@import` it doesn't recognize. */
+  loadStylesheet(id: string): Promise<CSSStylesheetSource>;
+  /** Resolver invoked for `@plugin` directives. */
+  loadModule(id: string): Promise<CSSModuleSource>;
 }
 
-/** Result returned from {@link CSSProcessor.process}. */
-export interface CSSProcessResult {
-  /** Processed CSS output. */
-  css: string;
-  /** Source map, if generated. */
-  map?: string;
+/** Stateful compiler returned by {@link CSSProcessor.compile}. */
+export interface CSSCompiler {
+  /**
+   * Emit CSS for the supplied list of class-name candidates. Stateful — the
+   * compiler accumulates candidates across calls for the lifetime of the
+   * underlying compile session.
+   */
+  build(candidates: string[]): string;
 }
 
 /**
  * CSSProcessor contract interface.
  *
- * Implementations compile utility classes or raw CSS into optimized
- * stylesheets ready for the browser.
+ * Implementations wire a utility-class compiler (Tailwind, UnoCSS, etc.) so
+ * core's styles-builder can emit per-request CSS without importing the
+ * underlying engine directly.
  */
 export interface CSSProcessor {
-  /** Process CSS input and return the compiled result. */
-  process(options: CSSProcessOptions): Promise<CSSProcessResult>;
-  /** Merge class names using the processor's conflict-resolution strategy. */
-  mergeClasses?(...classes: string[]): string;
+  compile(stylesheet: string, options: CSSCompileOptions): Promise<CSSCompiler>;
 }

package/src/src/extensions/interfaces/index.ts

@@ -27,7 +27,13 @@ export type { CacheStore } from "./cache-store.js";
 export type { TokenCacheEntry, TokenCacheStats, TokenCacheStore } from "./token-cache-store.js";
 
 // CSS processor
-export type { CSSProcessOptions, CSSProcessor, CSSProcessResult } from "./css-processor.js";
+export type {
+  CSSCompileOptions,
+  CSSCompiler,
+  CSSModuleSource,
+  CSSProcessor,
+  CSSStylesheetSource,
+} from "./css-processor.js";
 
 // Content transformer
 export type {
@@ -51,16 +57,9 @@ export type {
 // Tracing exporter
 export type { SpanData, TracerProvider, TracingExporter } from "./tracing-exporter.js";
 
-// AI model provider
-export type {
-  AIModelProvider,
-  ChatMessage,
-  CompletionOptions,
-  CompletionResult,
-  ContentPart,
-  StreamChunk,
-  ToolDefinition,
-} from "./ai-model-provider.js";
+// AI provider (registry + per-provider contract)
+export type { AIProvider, AIProviderConfig, AIProviderRegistry } from "./ai-provider.js";
+export { AIProviderRegistryName } from "./ai-provider.js";
 
 // Embedding provider
 export type { EmbeddingOptions, EmbeddingProvider, EmbeddingResult } from "./embedding-provider.js";
@@ -71,6 +70,7 @@ export type {
   CodeParser,
   GenerateOptions,
   GenerateResult,
+  InjectJsxNodePositionsOptions,
   NodePath,
   ParseOptions,
   TraverseVisitor,
@@ -78,8 +78,12 @@ export type {
 
 // Schema validator
 export type {
+  InferSchema,
+  InferShape,
   Schema,
+  SchemaFactory,
   SchemaValidator,
+  SchemaValidatorCoerce,
   ValidationFailure,
   ValidationIssue,
   ValidationResult,