veryfront 0.1.512 → 0.1.513

package/README.md

@@ -12,24 +12,34 @@ It gives you agents, tools, workflows, and a complete React rendering stack in a
 
 Purpose-built for TypeScript and React, Veryfront gives you everything you need to build agentic full-stack applications out-of-the-box.
 
-- [**Agents**](https://veryfront.com/docs/code/guides/agents) — Build autonomous agents with model routing, system prompts, hosted execution helpers, and tool calling. Agents reason about goals and iterate until they reach a final answer.
+- [**Agents**](https://veryfront.com/docs/code/guides/agents) — Build autonomous agents with model routing, system prompts, hosted execution, and tool calling. Agents reason about goals and iterate until they reach a final answer. Supports AG-UI streaming, multi-agent composition, and hosted child-run orchestration.
 
 - [**Tools**](https://veryfront.com/docs/code/guides/tools) — Define Zod-validated functions that agents can call. Tools are auto-discovered from the file system with no registration needed.
 
-- [**Workflows**](https://veryfront.com/docs/code/guides/workflows) — Orchestrate multi-step AI pipelines with branching, parallelism, and human-in-the-loop approval gates.
+- [**Workflows**](https://veryfront.com/docs/code/guides/workflows) — Orchestrate multi-step AI pipelines with branching, parallelism, human-in-the-loop approval gates, and durable crash recovery via Redis checkpoints.
+
+- [**Skills**](https://veryfront.com/docs/code/guides/skills) — Project-level agent capabilities defined as `SKILL.md` files following the agentskills.io specification. Skills provide prompt augmentation, tool allowlists, and script execution.
 
 - [**Jobs & Cron Jobs**](https://veryfront.com/docs/code/guides/jobs) — Run durable project-scoped background work now or on a schedule through the Veryfront platform.
 
-- [**Multi-Agent**](https://veryfront.com/docs/code/guides/multi-agent) — Compose agents that delegate to each other as tools for complex, coordinated tasks.
+- [**Tasks**](https://veryfront.com/docs/code/guides/tasks) — File-based background task definitions discovered automatically and executable via the jobs system.
+
+- [**Multi-Agent**](https://veryfront.com/docs/code/guides/multi-agent) — Compose agents that delegate to each other as tools for complex, coordinated tasks. AG-UI control-plane for hosted agent orchestration.
+
+- [**Memory & Streaming**](https://veryfront.com/docs/code/guides/memory-and-streaming) — Give agents conversation history and streaming responses. Built-in chat UI components for React with AG-UI protocol support.
 
-- [**Memory & Streaming**](https://veryfront.com/docs/code/guides/memory-and-streaming) — Give agents conversation history and streaming responses. Built-in chat UI components for React.
+- [**MCP Server**](https://veryfront.com/docs/code/guides/mcp-server) — Expose tools, prompts, and resources via the Model Context Protocol. Includes SSE transport, session management, and elicitation support.
 
-- [**MCP Server**](https://veryfront.com/docs/code/guides/mcp-server) — Expose tools, prompts, and resources via the Model Context Protocol.
+- [**Sandbox**](https://veryfront.com/docs/code/guides/sandbox) — Ephemeral compute environments for isolated code execution with shell tools and agent service integration.
+
+- [**Integrations**](https://veryfront.com/docs/code/guides/integrations) — Pre-built connectors with OAuth flows, remote tools, and metadata for third-party services.
 
 - [**Pages & Routing**](https://veryfront.com/docs/code/guides/pages-and-routing) — File-based routing with React Server Components, layouts, and server-side rendering.
 
 - [**Data Fetching & API Routes**](https://veryfront.com/docs/code/guides/data-fetching) — Server-side data loading, API route handlers, and [middleware](https://veryfront.com/docs/code/guides/middleware) with built-in [OAuth](https://veryfront.com/docs/code/guides/oauth) support.
 
+- [**Extensions**](./docs/guides/extensions.md) — Contract-based plugin system with 12 first-party packages for LLM providers, bundling, CSS, tracing, caching, and more.
+
 ## Get Started
 
 The **recommended** way to get started with Veryfront:
@@ -60,6 +70,37 @@ brew install veryfront/tap/veryfront
 
 Follow the [Quickstart guide](https://veryfront.com/docs/code/guides/quickstart) for step-by-step setup, or explore our [templates](https://veryfront.com/docs/code/guides/quickstart#templates) to start building your first application with Veryfront. For the full documentation, visit [veryfront.com/docs/code](https://veryfront.com/docs/code).
 
+## Project Structure
+
+```
+veryfront/
+├── src/                  # Framework core modules
+│   ├── agent/           # Agent runtime, AG-UI, hosted execution
+│   ├── tool/            # Tool definitions and registry
+│   ├── workflow/        # Durable DAG workflows with crash recovery
+│   ├── mcp/             # Model Context Protocol server
+│   ├── skill/           # Agent skills system (SKILL.md)
+│   ├── chat/            # Chat UI components and streaming
+│   ├── discovery/       # Auto-discovery of tools, agents, workflows
+│   ├── sandbox/         # Ephemeral compute environments
+│   ├── jobs/            # Background jobs client
+│   ├── task/            # Task definitions and runner
+│   ├── channels/        # Control-plane agent routing
+│   ├── integrations/    # Third-party connector metadata
+│   ├── provider/        # AI model provider adapters
+│   ├── rendering/       # SSR/RSC engine
+│   ├── server/          # HTTP servers (dev + production)
+│   ├── routing/         # File-based routing
+│   ├── security/        # Rate limiting, CORS, CSP, validation
+│   └── ...              # See src/README.md for full list
+├── cli/                  # CLI and TUI dashboard
+├── extensions/           # First-party extension packages
+├── docs/                 # Architecture diagrams and guides
+├── tests/                # Integration and E2E tests
+├── benchmarks/           # Performance benchmarks
+└── scripts/              # Development and build scripts
+```
+
 ## Examples
 
 You can find standalone, runnable examples in the [veryfront-examples](https://github.com/veryfront/veryfront-examples) repo.

package/esm/deno.d.ts

@@ -259,12 +259,8 @@ declare namespace _default {
         "@opentelemetry/sdk-node": string;
         "@opentelemetry/sdk-trace-base": string;
         "@mdx-js/mdx": string;
-        "@babel/parser": string;
         "gray-matter": string;
         zod: string;
-        mdast: string;
-        hast: string;
-        unist: string;
         unified: string;
         "class-variance-authority": string;
         "tailwind-merge": string;

package/esm/deno.js

@@ -1,6 +1,6 @@
 export default {
     "name": "veryfront",
-    "version": "0.1.512",
+    "version": "0.1.513",
     "license": "Apache-2.0",
     "nodeModulesDir": "auto",
     "workspace": [
@@ -284,12 +284,8 @@ export default {
         "@opentelemetry/sdk-node": "npm:@opentelemetry/sdk-node@0.217.0",
         "@opentelemetry/sdk-trace-base": "npm:@opentelemetry/sdk-trace-base@2.7.1",
         "@mdx-js/mdx": "npm:@mdx-js/mdx@3.1.1",
-        "@babel/parser": "npm:@babel/parser@7.29.2",
         "gray-matter": "npm:gray-matter@4.0.3",
         "zod": "npm:zod@4.3.6",
-        "mdast": "npm:@types/mdast@4.0.3",
-        "hast": "npm:@types/hast@3.0.3",
-        "unist": "npm:@types/unist@3.0.2",
         "unified": "npm:unified@11.0.5",
         "class-variance-authority": "npm:class-variance-authority@0.7.1",
         "tailwind-merge": "npm:tailwind-merge@3.5.0",

package/esm/src/agent/agent-service-config.d.ts

@@ -1,6 +1,19 @@
 import { z } from "zod";
 export declare const agentServiceConfigSchema: z.ZodPipe<z.ZodObject<{
     VERYFRONT_API_URL: z.ZodDefault<z.ZodString>;
+    VERYFRONT_API_TOKEN: z.ZodOptional<z.ZodString>;
+    VERYFRONT_PROJECT_ID: z.ZodOptional<z.ZodString>;
+    VERYFRONT_AGENT_SERVICE_URL: z.ZodOptional<z.ZodString>;
+    VERYFRONT_AGENT_SERVICE_KEY: z.ZodOptional<z.ZodString>;
+    VERYFRONT_AGENT_SERVICE_REGISTRATION: z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+        true: "true";
+        false: "false";
+        auto: "auto";
+        enabled: "enabled";
+        disabled: "disabled";
+    }>>, z.ZodTransform<"auto" | "enabled" | "disabled", "true" | "false" | "auto" | "enabled" | "disabled">>;
+    VERYFRONT_AGENT_SERVICE_HEARTBEAT_INTERVAL_MS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    VERYFRONT_AGENT_SERVICE_REGION: z.ZodOptional<z.ZodString>;
     NODE_ENV: z.ZodDefault<z.ZodEnum<{
         development: "development";
         production: "production";
@@ -17,6 +30,13 @@ export declare const agentServiceConfigSchema: z.ZodPipe<z.ZodObject<{
 }, z.core.$strip>, z.ZodTransform<{
     VERYFRONT_API_URL: string;
     VERYFRONT_MCP_URL: string;
+    VERYFRONT_API_TOKEN: string | undefined;
+    VERYFRONT_PROJECT_ID: string | undefined;
+    VERYFRONT_AGENT_SERVICE_URL: string | undefined;
+    VERYFRONT_AGENT_SERVICE_KEY: string | undefined;
+    VERYFRONT_AGENT_SERVICE_REGISTRATION: "auto" | "enabled" | "disabled";
+    VERYFRONT_AGENT_SERVICE_HEARTBEAT_INTERVAL_MS: number;
+    VERYFRONT_AGENT_SERVICE_REGION: string | undefined;
     VERYFRONT_STUDIO_MCP_URL: string;
     VERYFRONT_ENABLE_DURABLE_INVOKE_AGENT: boolean;
     VERYFRONT_ENABLE_DURABLE_TASK: boolean;
@@ -28,6 +48,8 @@ export declare const agentServiceConfigSchema: z.ZodPipe<z.ZodObject<{
     OTEL_EXPORTER_OTLP_ENDPOINT: string | undefined;
 }, {
     VERYFRONT_API_URL: string;
+    VERYFRONT_AGENT_SERVICE_REGISTRATION: "auto" | "enabled" | "disabled";
+    VERYFRONT_AGENT_SERVICE_HEARTBEAT_INTERVAL_MS: number;
     NODE_ENV: "development" | "production" | "test";
     PORT: number;
     VERYFRONT_STUDIO_MCP_URL: string;
@@ -35,6 +57,11 @@ export declare const agentServiceConfigSchema: z.ZodPipe<z.ZodObject<{
     VERYFRONT_ENABLE_DURABLE_TASK: boolean;
     ALLOWED_ORIGINS: string;
     OTEL_ENABLED: boolean;
+    VERYFRONT_API_TOKEN?: string | undefined;
+    VERYFRONT_PROJECT_ID?: string | undefined;
+    VERYFRONT_AGENT_SERVICE_URL?: string | undefined;
+    VERYFRONT_AGENT_SERVICE_KEY?: string | undefined;
+    VERYFRONT_AGENT_SERVICE_REGION?: string | undefined;
     OAUTH_PUBLIC_KEY?: string | undefined;
     OTEL_EXPORTER_OTLP_ENDPOINT?: string | undefined;
 }>>;
@@ -42,6 +69,19 @@ export type AgentServiceConfig = z.infer<typeof agentServiceConfigSchema>;
 export type AgentServiceConfigInput = z.input<typeof agentServiceConfigSchema>;
 export declare const hostedAgentServiceConfigSchema: z.ZodPipe<z.ZodObject<{
     VERYFRONT_API_URL: z.ZodDefault<z.ZodString>;
+    VERYFRONT_API_TOKEN: z.ZodOptional<z.ZodString>;
+    VERYFRONT_PROJECT_ID: z.ZodOptional<z.ZodString>;
+    VERYFRONT_AGENT_SERVICE_URL: z.ZodOptional<z.ZodString>;
+    VERYFRONT_AGENT_SERVICE_KEY: z.ZodOptional<z.ZodString>;
+    VERYFRONT_AGENT_SERVICE_REGISTRATION: z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+        true: "true";
+        false: "false";
+        auto: "auto";
+        enabled: "enabled";
+        disabled: "disabled";
+    }>>, z.ZodTransform<"auto" | "enabled" | "disabled", "true" | "false" | "auto" | "enabled" | "disabled">>;
+    VERYFRONT_AGENT_SERVICE_HEARTBEAT_INTERVAL_MS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    VERYFRONT_AGENT_SERVICE_REGION: z.ZodOptional<z.ZodString>;
     NODE_ENV: z.ZodDefault<z.ZodEnum<{
         development: "development";
         production: "production";
@@ -58,6 +98,13 @@ export declare const hostedAgentServiceConfigSchema: z.ZodPipe<z.ZodObject<{
 }, z.core.$strip>, z.ZodTransform<{
     VERYFRONT_API_URL: string;
     VERYFRONT_MCP_URL: string;
+    VERYFRONT_API_TOKEN: string | undefined;
+    VERYFRONT_PROJECT_ID: string | undefined;
+    VERYFRONT_AGENT_SERVICE_URL: string | undefined;
+    VERYFRONT_AGENT_SERVICE_KEY: string | undefined;
+    VERYFRONT_AGENT_SERVICE_REGISTRATION: "auto" | "enabled" | "disabled";
+    VERYFRONT_AGENT_SERVICE_HEARTBEAT_INTERVAL_MS: number;
+    VERYFRONT_AGENT_SERVICE_REGION: string | undefined;
     VERYFRONT_STUDIO_MCP_URL: string;
     VERYFRONT_ENABLE_DURABLE_INVOKE_AGENT: boolean;
     VERYFRONT_ENABLE_DURABLE_TASK: boolean;
@@ -69,6 +116,8 @@ export declare const hostedAgentServiceConfigSchema: z.ZodPipe<z.ZodObject<{
     OTEL_EXPORTER_OTLP_ENDPOINT: string | undefined;
 }, {
     VERYFRONT_API_URL: string;
+    VERYFRONT_AGENT_SERVICE_REGISTRATION: "auto" | "enabled" | "disabled";
+    VERYFRONT_AGENT_SERVICE_HEARTBEAT_INTERVAL_MS: number;
     NODE_ENV: "development" | "production" | "test";
     PORT: number;
     VERYFRONT_STUDIO_MCP_URL: string;
@@ -76,6 +125,11 @@ export declare const hostedAgentServiceConfigSchema: z.ZodPipe<z.ZodObject<{
     VERYFRONT_ENABLE_DURABLE_TASK: boolean;
     ALLOWED_ORIGINS: string;
     OTEL_ENABLED: boolean;
+    VERYFRONT_API_TOKEN?: string | undefined;
+    VERYFRONT_PROJECT_ID?: string | undefined;
+    VERYFRONT_AGENT_SERVICE_URL?: string | undefined;
+    VERYFRONT_AGENT_SERVICE_KEY?: string | undefined;
+    VERYFRONT_AGENT_SERVICE_REGION?: string | undefined;
     OAUTH_PUBLIC_KEY?: string | undefined;
     OTEL_EXPORTER_OTLP_ENDPOINT?: string | undefined;
 }>>;

package/esm/src/agent/agent-service-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-service-config.d.ts","sourceRoot":"","sources":["../../../src/src/agent/agent-service-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuBlC,CAAC;AAEJ,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC1E,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE/E,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAA2B,CAAC;AACvE,MAAM,MAAM,wBAAwB,GAAG,kBAAkB,CAAC;AAC1D,MAAM,MAAM,6BAA6B,GAAG,uBAAuB,CAAC;AAEpE,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,uBAAuB,GAC7B,kBAAkB,CAEpB;AAED,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,6BAA6B,GACnC,wBAAwB,CAE1B"}
+{"version":3,"file":"agent-service-config.d.ts","sourceRoot":"","sources":["../../../src/src/agent/agent-service-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAqBxB,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqClC,CAAC;AAEJ,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC1E,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE/E,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAA2B,CAAC;AACvE,MAAM,MAAM,wBAAwB,GAAG,kBAAkB,CAAC;AAC1D,MAAM,MAAM,6BAA6B,GAAG,uBAAuB,CAAC;AAEpE,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,uBAAuB,GAC7B,kBAAkB,CAEpB;AAED,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,6BAA6B,GACnC,wBAAwB,CAE1B"}

package/esm/src/agent/agent-service-config.js

@@ -6,8 +6,25 @@ function splitAllowedOrigins(value) {
     return value.split(",").map((origin) => origin.trim());
 }
 const booleanFlagSchema = z.string().default("false").transform(parseBooleanFlag);
+const agentServiceRegistrationModeInputSchema = z
+    .enum(["auto", "enabled", "disabled", "true", "false"])
+    .default("auto")
+    .transform((value) => {
+    if (value === "true")
+        return "enabled";
+    if (value === "false")
+        return "disabled";
+    return value;
+});
 export const agentServiceConfigSchema = z.object({
     VERYFRONT_API_URL: z.string().url().default("https://api.veryfront.com"),
+    VERYFRONT_API_TOKEN: z.string().min(1).optional(),
+    VERYFRONT_PROJECT_ID: z.string().min(1).optional(),
+    VERYFRONT_AGENT_SERVICE_URL: z.string().url().optional(),
+    VERYFRONT_AGENT_SERVICE_KEY: z.string().min(1).max(128).optional(),
+    VERYFRONT_AGENT_SERVICE_REGISTRATION: agentServiceRegistrationModeInputSchema,
+    VERYFRONT_AGENT_SERVICE_HEARTBEAT_INTERVAL_MS: z.coerce.number().positive().default(30_000),
+    VERYFRONT_AGENT_SERVICE_REGION: z.string().min(1).max(128).optional(),
     NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
     PORT: z.coerce.number().default(3001),
     OAUTH_PUBLIC_KEY: z.string().optional(),
@@ -20,6 +37,13 @@ export const agentServiceConfigSchema = z.object({
 }).transform((env) => ({
     VERYFRONT_API_URL: env.VERYFRONT_API_URL,
     VERYFRONT_MCP_URL: `${env.VERYFRONT_API_URL}/mcp`,
+    VERYFRONT_API_TOKEN: env.VERYFRONT_API_TOKEN,
+    VERYFRONT_PROJECT_ID: env.VERYFRONT_PROJECT_ID,
+    VERYFRONT_AGENT_SERVICE_URL: env.VERYFRONT_AGENT_SERVICE_URL,
+    VERYFRONT_AGENT_SERVICE_KEY: env.VERYFRONT_AGENT_SERVICE_KEY,
+    VERYFRONT_AGENT_SERVICE_REGISTRATION: env.VERYFRONT_AGENT_SERVICE_REGISTRATION,
+    VERYFRONT_AGENT_SERVICE_HEARTBEAT_INTERVAL_MS: env.VERYFRONT_AGENT_SERVICE_HEARTBEAT_INTERVAL_MS,
+    VERYFRONT_AGENT_SERVICE_REGION: env.VERYFRONT_AGENT_SERVICE_REGION,
     VERYFRONT_STUDIO_MCP_URL: env.VERYFRONT_STUDIO_MCP_URL,
     VERYFRONT_ENABLE_DURABLE_INVOKE_AGENT: env.VERYFRONT_ENABLE_DURABLE_INVOKE_AGENT,
     VERYFRONT_ENABLE_DURABLE_TASK: env.VERYFRONT_ENABLE_DURABLE_TASK,

package/esm/src/agent/agent-service-registration.d.ts

@@ -0,0 +1,110 @@
+import { z } from "zod";
+export declare const agentServiceRegistrationModeSchema: z.ZodEnum<{
+    auto: "auto";
+    enabled: "enabled";
+    disabled: "disabled";
+}>;
+export declare const agentServiceRegistrationConfigSchema: z.ZodObject<{
+    VERYFRONT_API_URL: z.ZodString;
+    VERYFRONT_API_TOKEN: z.ZodOptional<z.ZodString>;
+    VERYFRONT_PROJECT_ID: z.ZodOptional<z.ZodString>;
+    VERYFRONT_AGENT_SERVICE_URL: z.ZodOptional<z.ZodString>;
+    VERYFRONT_AGENT_SERVICE_KEY: z.ZodOptional<z.ZodString>;
+    VERYFRONT_AGENT_SERVICE_REGISTRATION: z.ZodEnum<{
+        auto: "auto";
+        enabled: "enabled";
+        disabled: "disabled";
+    }>;
+    VERYFRONT_AGENT_SERVICE_HEARTBEAT_INTERVAL_MS: z.ZodNumber;
+    VERYFRONT_AGENT_SERVICE_REGION: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const resolvedAgentServiceRegistrationInputSchema: z.ZodObject<{
+    apiUrl: z.ZodString;
+    authToken: z.ZodString;
+    serviceName: z.ZodString;
+    serviceKey: z.ZodString;
+    scopeKind: z.ZodEnum<{
+        global: "global";
+        project: "project";
+    }>;
+    projectId: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodString>;
+    baseUrl: z.ZodString;
+    invokeUrl: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    runtime: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+    heartbeatIntervalMs: z.ZodNumber;
+}, z.core.$strip>;
+declare const agentPushRuntimeServiceRestSchema: z.ZodObject<{
+    id: z.ZodString;
+    service_name: z.ZodString;
+    service_key: z.ZodString;
+    scope_kind: z.ZodEnum<{
+        global: "global";
+        project: "project";
+    }>;
+    scope_key: z.ZodString;
+    project_id: z.ZodNullable<z.ZodString>;
+    agent_id: z.ZodNullable<z.ZodString>;
+    base_url: z.ZodString;
+    invoke_url: z.ZodString;
+    status: z.ZodEnum<{
+        disabled: "disabled";
+        active: "active";
+    }>;
+    capabilities: z.ZodNullable<z.ZodUnknown>;
+    metadata: z.ZodNullable<z.ZodUnknown>;
+    version: z.ZodNullable<z.ZodString>;
+    runtime: z.ZodNullable<z.ZodString>;
+    region: z.ZodNullable<z.ZodString>;
+    last_heartbeat_at: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+declare const registerAgentPushRuntimeServiceRequestSchema: z.ZodObject<{
+    service_name: z.ZodString;
+    service_key: z.ZodString;
+    scope_kind: z.ZodEnum<{
+        global: "global";
+        project: "project";
+    }>;
+    project_id: z.ZodOptional<z.ZodString>;
+    agent_id: z.ZodOptional<z.ZodString>;
+    base_url: z.ZodString;
+    invoke_url: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    runtime: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AgentServiceRegistrationMode = z.infer<typeof agentServiceRegistrationModeSchema>;
+export type AgentServiceRegistrationConfig = z.infer<typeof agentServiceRegistrationConfigSchema>;
+export type ResolvedAgentServiceRegistrationInput = z.infer<typeof resolvedAgentServiceRegistrationInputSchema>;
+export type AgentPushRuntimeServiceRest = z.infer<typeof agentPushRuntimeServiceRestSchema>;
+export type RegisterAgentPushRuntimeServiceRequest = z.infer<typeof registerAgentPushRuntimeServiceRequestSchema>;
+export type AgentServiceRegistrationLogger = {
+    info?: (message: string, metadata?: Record<string, unknown>) => void;
+    warn?: (message: string, metadata?: Record<string, unknown>) => void;
+    error?: (message: string, metadata?: Record<string, unknown>) => void;
+};
+export type ResolveAgentServiceRegistrationInputOptions = {
+    config: AgentServiceRegistrationConfig;
+    serviceName: string;
+    agentId?: string;
+    version?: string;
+    runtime?: string;
+};
+export type AgentServiceRegistrationLifecycle = {
+    serviceId: string;
+    service: AgentPushRuntimeServiceRest;
+    heartbeat: () => Promise<void>;
+    stop: () => void;
+};
+export type CreateAgentServiceRegistrationLifecycleOptions = ResolvedAgentServiceRegistrationInput & {
+    fetch?: typeof globalThis.fetch;
+    logger?: AgentServiceRegistrationLogger;
+};
+export declare function resolveAgentServiceRegistrationInput(options: ResolveAgentServiceRegistrationInputOptions): Promise<ResolvedAgentServiceRegistrationInput | null>;
+export declare function createAgentServiceRegistrationLifecycle(options: CreateAgentServiceRegistrationLifecycleOptions): Promise<AgentServiceRegistrationLifecycle>;
+export {};
+//# sourceMappingURL=agent-service-registration.d.ts.map

package/esm/src/agent/agent-service-registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-service-registration.d.ts","sourceRoot":"","sources":["../../../src/src/agent/agent-service-registration.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,kCAAkC;;;;EAI7C,CAAC;AAEH,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;iBAS/C,CAAC;AAEH,eAAO,MAAM,2CAA2C;;;;;;;;;;;;;;;;;iBActD,CAAC;AAEH,QAAA,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;;iBAmBrC,CAAC;AAMH,QAAA,MAAM,4CAA4C;;;;;;;;;;;;;;iBAWhD,CAAC;AAEH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAC9F,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oCAAoC,CAAC,CAAC;AAClG,MAAM,MAAM,qCAAqC,GAAG,CAAC,CAAC,KAAK,CACzD,OAAO,2CAA2C,CACnD,CAAC;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAC5F,MAAM,MAAM,sCAAsC,GAAG,CAAC,CAAC,KAAK,CAC1D,OAAO,4CAA4C,CACpD,CAAC;AAEF,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACrE,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACrE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CACvE,CAAC;AAEF,MAAM,MAAM,2CAA2C,GAAG;IACxD,MAAM,EAAE,8BAA8B,CAAC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,iCAAiC,GAAG;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,2BAA2B,CAAC;IACrC,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,8CAA8C,GACtD,qCAAqC,GACrC;IACA,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,MAAM,CAAC,EAAE,8BAA8B,CAAC;CACzC,CAAC;AA0DJ,wBAAsB,oCAAoC,CACxD,OAAO,EAAE,2CAA2C,GACnD,OAAO,CAAC,qCAAqC,GAAG,IAAI,CAAC,CA6CvD;AA4DD,wBAAsB,uCAAuC,CAC3D,OAAO,EAAE,8CAA8C,GACtD,OAAO,CAAC,iCAAiC,CAAC,CA0C5C"}

package/esm/src/agent/agent-service-registration.js

@@ -0,0 +1,228 @@
+import * as dntShim from "../../_dnt.shims.js";
+import { z } from "zod";
+export const agentServiceRegistrationModeSchema = z.enum([
+    "auto",
+    "enabled",
+    "disabled",
+]);
+export const agentServiceRegistrationConfigSchema = z.object({
+    VERYFRONT_API_URL: z.string().url(),
+    VERYFRONT_API_TOKEN: z.string().min(1).optional(),
+    VERYFRONT_PROJECT_ID: z.string().min(1).optional(),
+    VERYFRONT_AGENT_SERVICE_URL: z.string().url().optional(),
+    VERYFRONT_AGENT_SERVICE_KEY: z.string().min(1).max(128).optional(),
+    VERYFRONT_AGENT_SERVICE_REGISTRATION: agentServiceRegistrationModeSchema,
+    VERYFRONT_AGENT_SERVICE_HEARTBEAT_INTERVAL_MS: z.number().positive(),
+    VERYFRONT_AGENT_SERVICE_REGION: z.string().min(1).max(128).optional(),
+});
+export const resolvedAgentServiceRegistrationInputSchema = z.object({
+    apiUrl: z.string().url(),
+    authToken: z.string().min(1),
+    serviceName: z.string().min(1).max(128),
+    serviceKey: z.string().min(1).max(128),
+    scopeKind: z.enum(["global", "project"]),
+    projectId: z.string().min(1).optional(),
+    agentId: z.string().min(1).max(128).optional(),
+    baseUrl: z.string().url(),
+    invokeUrl: z.string().url(),
+    version: z.string().min(1).max(128).optional(),
+    runtime: z.string().min(1).max(128).optional(),
+    region: z.string().min(1).max(128).optional(),
+    heartbeatIntervalMs: z.number().positive(),
+});
+const agentPushRuntimeServiceRestSchema = z.object({
+    id: z.string().uuid(),
+    service_name: z.string(),
+    service_key: z.string(),
+    scope_kind: z.enum(["global", "project"]),
+    scope_key: z.string(),
+    project_id: z.string().nullable(),
+    agent_id: z.string().nullable(),
+    base_url: z.string().url(),
+    invoke_url: z.string().url(),
+    status: z.enum(["active", "disabled"]),
+    capabilities: z.unknown().nullable(),
+    metadata: z.unknown().nullable(),
+    version: z.string().nullable(),
+    runtime: z.string().nullable(),
+    region: z.string().nullable(),
+    last_heartbeat_at: z.string().nullable(),
+    created_at: z.string(),
+    updated_at: z.string(),
+});
+const agentPushRuntimeServiceResponseSchema = z.object({
+    service: agentPushRuntimeServiceRestSchema,
+});
+const registerAgentPushRuntimeServiceRequestSchema = z.object({
+    service_name: z.string().min(1).max(128),
+    service_key: z.string().min(1).max(128),
+    scope_kind: z.enum(["global", "project"]),
+    project_id: z.string().optional(),
+    agent_id: z.string().optional(),
+    base_url: z.string().url(),
+    invoke_url: z.string().url(),
+    version: z.string().optional(),
+    runtime: z.string().optional(),
+    region: z.string().optional(),
+});
+function normalizeBaseUrl(value) {
+    const url = new URL(value);
+    url.pathname = url.pathname.replace(/\/+$/, "");
+    url.search = "";
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+}
+function defaultInvokeUrl(baseUrl) {
+    return new URL("/api/runs", baseUrl).toString();
+}
+function getRegistrationEndpoint(apiUrl) {
+    return new URL("/agent-runtimes/push-services", apiUrl).toString();
+}
+function getHeartbeatEndpoint(apiUrl, serviceId) {
+    return new URL(`/agent-runtimes/push-services/${serviceId}/heartbeat`, apiUrl).toString();
+}
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function stableServiceKey(input) {
+    const keySource = [
+        input.serviceName,
+        input.agentId ?? "default",
+        input.scopeKind,
+        input.projectId ?? "global",
+        input.baseUrl,
+    ].join("|");
+    const digest = await dntShim.crypto.subtle.digest("SHA-256", new TextEncoder().encode(keySource));
+    const hash = Array.from(new Uint8Array(digest))
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("")
+        .slice(0, 32);
+    return `${input.serviceName}:${hash}`.slice(0, 128);
+}
+function requireExplicitRegistrationValue(value, envName) {
+    if (!value) {
+        throw new Error(`${envName} is required when VERYFRONT_AGENT_SERVICE_REGISTRATION=enabled`);
+    }
+    return value;
+}
+export async function resolveAgentServiceRegistrationInput(options) {
+    const config = agentServiceRegistrationConfigSchema.parse(options.config);
+    const enabled = config.VERYFRONT_AGENT_SERVICE_REGISTRATION === "enabled";
+    const token = enabled
+        ? requireExplicitRegistrationValue(config.VERYFRONT_API_TOKEN, "VERYFRONT_API_TOKEN")
+        : config.VERYFRONT_API_TOKEN;
+    const serviceUrl = enabled
+        ? requireExplicitRegistrationValue(config.VERYFRONT_AGENT_SERVICE_URL, "VERYFRONT_AGENT_SERVICE_URL")
+        : config.VERYFRONT_AGENT_SERVICE_URL;
+    if (config.VERYFRONT_AGENT_SERVICE_REGISTRATION === "disabled") {
+        return null;
+    }
+    if (!token || !serviceUrl) {
+        return null;
+    }
+    const scopeKind = config.VERYFRONT_PROJECT_ID ? "project" : "global";
+    const baseUrl = normalizeBaseUrl(serviceUrl);
+    const serviceKey = config.VERYFRONT_AGENT_SERVICE_KEY ?? await stableServiceKey({
+        serviceName: options.serviceName,
+        agentId: options.agentId,
+        baseUrl,
+        scopeKind,
+        projectId: config.VERYFRONT_PROJECT_ID,
+    });
+    return resolvedAgentServiceRegistrationInputSchema.parse({
+        apiUrl: config.VERYFRONT_API_URL,
+        authToken: token,
+        serviceName: options.serviceName,
+        serviceKey,
+        scopeKind,
+        projectId: config.VERYFRONT_PROJECT_ID,
+        agentId: options.agentId,
+        baseUrl,
+        invokeUrl: defaultInvokeUrl(baseUrl),
+        version: options.version,
+        runtime: options.runtime,
+        region: config.VERYFRONT_AGENT_SERVICE_REGION,
+        heartbeatIntervalMs: config.VERYFRONT_AGENT_SERVICE_HEARTBEAT_INTERVAL_MS,
+    });
+}
+async function readAgentPushRuntimeServiceResponse(response) {
+    if (!response.ok) {
+        throw new Error(`Agent runtime registration request failed with HTTP ${response.status}`);
+    }
+    const parsed = agentPushRuntimeServiceResponseSchema.parse(await response.json());
+    return parsed.service;
+}
+function createHeaders(authToken) {
+    const headers = new Headers();
+    headers.set("Authorization", `Bearer ${authToken}`);
+    headers.set("Content-Type", "application/json");
+    return headers;
+}
+function buildRegistrationRequest(input) {
+    return registerAgentPushRuntimeServiceRequestSchema.parse({
+        service_name: input.serviceName,
+        service_key: input.serviceKey,
+        scope_kind: input.scopeKind,
+        project_id: input.projectId,
+        agent_id: input.agentId,
+        base_url: input.baseUrl,
+        invoke_url: input.invokeUrl,
+        version: input.version,
+        runtime: input.runtime,
+        region: input.region,
+    });
+}
+async function registerAgentPushRuntimeService(input, fetchImpl) {
+    const response = await fetchImpl(getRegistrationEndpoint(input.apiUrl), {
+        method: "POST",
+        headers: createHeaders(input.authToken),
+        body: JSON.stringify(buildRegistrationRequest(input)),
+    });
+    return await readAgentPushRuntimeServiceResponse(response);
+}
+async function heartbeatAgentPushRuntimeService(input, fetchImpl) {
+    const response = await fetchImpl(getHeartbeatEndpoint(input.apiUrl, input.serviceId), {
+        method: "POST",
+        headers: createHeaders(input.authToken),
+    });
+    return await readAgentPushRuntimeServiceResponse(response);
+}
+export async function createAgentServiceRegistrationLifecycle(options) {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const input = resolvedAgentServiceRegistrationInputSchema.parse(options);
+    const service = await registerAgentPushRuntimeService(input, fetchImpl);
+    let stopped = false;
+    const heartbeat = async () => {
+        if (stopped) {
+            return;
+        }
+        await heartbeatAgentPushRuntimeService({
+            apiUrl: input.apiUrl,
+            authToken: input.authToken,
+            serviceId: service.id,
+        }, fetchImpl);
+    };
+    const interval = dntShim.setInterval(() => {
+        void heartbeat().catch((error) => {
+            options.logger?.warn?.("Agent service heartbeat failed", {
+                serviceId: service.id,
+                error: getErrorMessage(error),
+            });
+        });
+    }, input.heartbeatIntervalMs);
+    options.logger?.info?.("Agent service registered with control plane", {
+        serviceId: service.id,
+        serviceName: service.service_name,
+        scopeKind: service.scope_kind,
+        projectId: service.project_id,
+    });
+    return {
+        serviceId: service.id,
+        service,
+        heartbeat,
+        stop: () => {
+            stopped = true;
+            clearInterval(interval);
+        },
+    };
+}

package/esm/src/agent/agent-service-runtime.d.ts

@@ -5,7 +5,7 @@ import { type AgentServiceAuth, type AgentServiceAuthConfig } from "./agent-serv
 import type { ParsedHostedChatRequest } from "./hosted-chat-request-parser.js";
 import type { AgUiResumeValue } from "./ag-ui-tool-shared.js";
 import type { RuntimeAgentMarkdownDefinition } from "./runtime-agent-definition.js";
-import { type AgentServiceServer, type NodeAgentServiceServer } from "./agent-service-server.js";
+import { type AgentServiceServer, type AgentServiceServerLifecycle, type NodeAgentServiceServer } from "./agent-service-server.js";
 import type { VeryfrontServiceServerLogger } from "../server/service-server.js";
 export type HostedAgentServiceRuntimeConfig = AgentServiceAuthConfig & {
     PORT: number;
@@ -49,12 +49,14 @@ export type StartNodeHostedAgentServiceOptions<TExecution extends object, TConfi
     bindAddress?: string;
     hardShutdownTimeoutMs?: number;
     signals?: readonly NodeJS.Signals[];
+    lifecycle?: AgentServiceServerLifecycle;
 };
 export type StartNodeAgentServiceOptions<TExecution extends object, TConfig extends AgentServiceRuntimeConfig = AgentServiceRuntimeConfig> = StartNodeHostedAgentServiceOptions<TExecution, TConfig>;
 export type StartAgentServiceRuntimeOptions<TExecution extends object, TConfig extends AgentServiceRuntimeConfig = AgentServiceRuntimeConfig> = CreateAgentServiceRuntimeOptions<TExecution, TConfig> & {
     bindAddress?: string;
     hardShutdownTimeoutMs?: number;
     signals?: readonly NodeJS.Signals[];
+    lifecycle?: AgentServiceServerLifecycle;
 };
 export type StartNodeHostedAgentServiceResult<TExecution extends object, TConfig extends HostedAgentServiceRuntimeConfig = HostedAgentServiceRuntimeConfig> = HostedAgentServiceRuntimeBundle<TExecution, TConfig> & {
     nodeServer: NodeAgentServiceServer;