veryfront 0.1.511 → 0.1.513

package/esm/src/oauth/providers/base.d.ts

@@ -40,6 +40,16 @@ export declare class OAuthService extends OAuthProvider {
      * tokens. See VULN-AUTH-2.
      */
     getAccessToken(userId: string): Promise<string | null>;
+    /**
+     * Resolve `endpoint` against `apiBaseUrl`, validating that absolute URLs
+     * share the configured origin.
+     *
+     * Without this check, a caller that forwards user-controlled data as
+     * `endpoint` could cause `fetch()` to issue requests to arbitrary hosts
+     * (including cloud metadata services and internal infrastructure). See
+     * SEC-003 in the security audit.
+     */
+    private resolveEndpointUrl;
     fetch<T>(userId: string, endpoint: string, options?: RequestInit): Promise<T>;
 }
 //# sourceMappingURL=base.d.ts.map

package/esm/src/oauth/providers/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../../src/src/oauth/providers/base.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,uBAAuB,EACvB,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,EAEV,oBAAoB,EACpB,mBAAmB,EACnB,UAAU,EACX,MAAM,aAAa,CAAC;AAUrB,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;AAuB5D,qBAAa,aAAa;IACxB,SAAS,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACtC,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC;gBAEnB,MAAM,EAAE,mBAAmB,EAAE,SAAS,GAAE,SAAkB;IAKtE,WAAW,IAAI,MAAM,GAAG,IAAI;IAI5B,eAAe,IAAI,MAAM,GAAG,IAAI;IAIhC,YAAY,IAAI,OAAO;IAIjB,sBAAsB,CAC1B,OAAO,GAAE,uBAAuB,GAAG;QAAE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;KAAO,GACnE,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,UAAU,CAAA;KAAE,CAAC;IA0C9C,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,kBAAkB;YAyCZ,gBAAgB;IAe9B,OAAO,CAAC,4BAA4B;YAQtB,aAAa;IA+BrB,YAAY,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA+BzE,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAwBjE,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAiBnD;AAED,qBAAa,YAAa,SAAQ,aAAa;IAC7C,SAAS,CAAC,aAAa,EAAE,kBAAkB,CAAC;IAC5C,SAAS,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;gBAEtB,MAAM,EAAE,kBAAkB,EAAE,UAAU,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,SAAS;IAMtF,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAEQ,sBAAsB,CAC7B,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,UAAU,CAAA;KAAE,CAAC;IAO9C;;;;;;OAMG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAmBtD,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;CA4BxF"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../../src/src/oauth/providers/base.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,uBAAuB,EACvB,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,EAEV,oBAAoB,EACpB,mBAAmB,EACnB,UAAU,EACX,MAAM,aAAa,CAAC;AAUrB,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;AAuB5D,qBAAa,aAAa;IACxB,SAAS,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACtC,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC;gBAEnB,MAAM,EAAE,mBAAmB,EAAE,SAAS,GAAE,SAAkB;IAKtE,WAAW,IAAI,MAAM,GAAG,IAAI;IAI5B,eAAe,IAAI,MAAM,GAAG,IAAI;IAIhC,YAAY,IAAI,OAAO;IAIjB,sBAAsB,CAC1B,OAAO,GAAE,uBAAuB,GAAG;QAAE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;KAAO,GACnE,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,UAAU,CAAA;KAAE,CAAC;IA0C9C,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,kBAAkB;YAyCZ,gBAAgB;IAe9B,OAAO,CAAC,4BAA4B;YAQtB,aAAa;IA+BrB,YAAY,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA+BzE,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAwBjE,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAiBnD;AAED,qBAAa,YAAa,SAAQ,aAAa;IAC7C,SAAS,CAAC,aAAa,EAAE,kBAAkB,CAAC;IAC5C,SAAS,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;gBAEtB,MAAM,EAAE,kBAAkB,EAAE,UAAU,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,SAAS;IAMtF,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAEQ,sBAAsB,CAC7B,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,UAAU,CAAA;KAAE,CAAC;IAO9C;;;;;;OAMG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAmB5D;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAuBpB,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;CA4BxF"}

package/esm/src/oauth/providers/base.js

@@ -249,6 +249,37 @@ export class OAuthService extends OAuthProvider {
         await this.tokenStore.setTokens(this.serviceId, userId, result.tokens);
         return result.tokens.accessToken;
     }
+    /**
+     * Resolve `endpoint` against `apiBaseUrl`, validating that absolute URLs
+     * share the configured origin.
+     *
+     * Without this check, a caller that forwards user-controlled data as
+     * `endpoint` could cause `fetch()` to issue requests to arbitrary hosts
+     * (including cloud metadata services and internal infrastructure). See
+     * SEC-003 in the security audit.
+     */
+    resolveEndpointUrl(endpoint) {
+        if (!endpoint.startsWith("http")) {
+            return `${this.apiBaseUrl}${endpoint}`;
+        }
+        let target;
+        let allowed;
+        try {
+            target = new URL(endpoint);
+            allowed = new URL(this.apiBaseUrl);
+        }
+        catch {
+            throw INVALID_ARGUMENT.create({
+                detail: `Invalid OAuth endpoint URL`,
+            });
+        }
+        if (target.origin !== allowed.origin) {
+            throw INVALID_ARGUMENT.create({
+                detail: `OAuth endpoint origin ${target.origin} does not match configured ${allowed.origin}`,
+            });
+        }
+        return endpoint;
+    }
     async fetch(userId, endpoint, options = {}) {
         const token = await this.getAccessToken(userId);
         if (!token) {
@@ -256,7 +287,7 @@ export class OAuthService extends OAuthProvider {
                 detail: `Not authenticated with ${this.serviceConfig.displayName}`,
             });
         }
-        const url = endpoint.startsWith("http") ? endpoint : `${this.apiBaseUrl}${endpoint}`;
+        const url = this.resolveEndpointUrl(endpoint);
         const response = await fetch(url, {
             ...options,
             headers: {

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

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.511";
+export declare const VERSION = "0.1.513";
 //# 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.511";
+export const VERSION = "0.1.513";

package/package.json

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

package/src/deno.js

@@ -1,6 +1,6 @@
 export default {
   "name": "veryfront",
-  "version": "0.1.511",
+  "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/src/src/agent/agent-service-config.ts

@@ -10,8 +10,24 @@ function splitAllowedOrigins(value: string): string[] {
 
 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(),
@@ -24,6 +40,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/src/src/agent/agent-service-registration.ts

@@ -0,0 +1,320 @@
+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(),
+});
+
+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;
+  };
+
+function normalizeBaseUrl(value: string): string {
+  const url = new URL(value);
+  url.pathname = url.pathname.replace(/\/+$/, "");
+  url.search = "";
+  url.hash = "";
+  return url.toString().replace(/\/$/, "");
+}
+
+function defaultInvokeUrl(baseUrl: string): string {
+  return new URL("/api/runs", baseUrl).toString();
+}
+
+function getRegistrationEndpoint(apiUrl: string): string {
+  return new URL("/agent-runtimes/push-services", apiUrl).toString();
+}
+
+function getHeartbeatEndpoint(apiUrl: string, serviceId: string): string {
+  return new URL(`/agent-runtimes/push-services/${serviceId}/heartbeat`, apiUrl).toString();
+}
+
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+async function stableServiceKey(input: {
+  serviceName: string;
+  agentId?: string;
+  baseUrl: string;
+  scopeKind: "global" | "project";
+  projectId?: string;
+}): Promise<string> {
+  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: string | undefined,
+  envName: string,
+): string {
+  if (!value) {
+    throw new Error(`${envName} is required when VERYFRONT_AGENT_SERVICE_REGISTRATION=enabled`);
+  }
+  return value;
+}
+
+export async function resolveAgentServiceRegistrationInput(
+  options: ResolveAgentServiceRegistrationInputOptions,
+): Promise<ResolvedAgentServiceRegistrationInput | null> {
+  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: Response,
+): Promise<AgentPushRuntimeServiceRest> {
+  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: string): Headers {
+  const headers = new Headers();
+  headers.set("Authorization", `Bearer ${authToken}`);
+  headers.set("Content-Type", "application/json");
+  return headers;
+}
+
+function buildRegistrationRequest(
+  input: ResolvedAgentServiceRegistrationInput,
+): RegisterAgentPushRuntimeServiceRequest {
+  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: ResolvedAgentServiceRegistrationInput,
+  fetchImpl: typeof globalThis.fetch,
+): Promise<AgentPushRuntimeServiceRest> {
+  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: { apiUrl: string; authToken: string; serviceId: string },
+  fetchImpl: typeof globalThis.fetch,
+): Promise<AgentPushRuntimeServiceRest> {
+  const response = await fetchImpl(getHeartbeatEndpoint(input.apiUrl, input.serviceId), {
+    method: "POST",
+    headers: createHeaders(input.authToken),
+  });
+  return await readAgentPushRuntimeServiceResponse(response);
+}
+
+export async function createAgentServiceRegistrationLifecycle(
+  options: CreateAgentServiceRegistrationLifecycleOptions,
+): Promise<AgentServiceRegistrationLifecycle> {
+  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: unknown) => {
+      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/src/src/agent/agent-service-runtime.ts

@@ -28,6 +28,7 @@ import type { AgUiResumeValue } from "./ag-ui-tool-shared.js";
 import type { RuntimeAgentMarkdownDefinition } from "./runtime-agent-definition.js";
 import {
   type AgentServiceServer,
+  type AgentServiceServerLifecycle,
   type NodeAgentServiceServer,
   startAgentServiceServer,
   startNodeAgentServiceServer,
@@ -110,6 +111,7 @@ export type StartNodeHostedAgentServiceOptions<
   bindAddress?: string;
   hardShutdownTimeoutMs?: number;
   signals?: readonly NodeJS.Signals[];
+  lifecycle?: AgentServiceServerLifecycle;
 };
 
 export type StartNodeAgentServiceOptions<
@@ -124,6 +126,7 @@ export type StartAgentServiceRuntimeOptions<
   bindAddress?: string;
   hardShutdownTimeoutMs?: number;
   signals?: readonly NodeJS.Signals[];
+  lifecycle?: AgentServiceServerLifecycle;
 };
 
 export type StartNodeHostedAgentServiceResult<
@@ -152,6 +155,26 @@ function defaultTrace<TResult>(
   return operation();
 }
 
+function combineAgentServiceLifecycle(
+  primary: AgentServiceServerLifecycle,
+  secondary: AgentServiceServerLifecycle | undefined,
+): AgentServiceServerLifecycle {
+  if (!secondary) {
+    return primary;
+  }
+
+  return {
+    setShuttingDown: () => {
+      primary.setShuttingDown?.();
+      secondary.setShuttingDown?.();
+    },
+    stop: async () => {
+      await primary.stop?.();
+      await secondary.stop?.();
+    },
+  };
+}
+
 export function createAgentServiceRuntime<
   TExecution extends object,
   TConfig extends AgentServiceRuntimeConfig = AgentServiceRuntimeConfig,
@@ -232,7 +255,7 @@ export async function startNodeAgentService<
   const nodeServer = await startNodeAgentServiceServer({
     runtime: bundle.runtime,
     serviceName: options.serviceName,
-    lifecycle: bundle.lifecycle,
+    lifecycle: combineAgentServiceLifecycle(bundle.lifecycle, options.lifecycle),
     port: bundle.config.PORT,
     bindAddress: options.bindAddress,
     signals: options.signals,
@@ -265,7 +288,7 @@ export async function startAgentServiceRuntime<
   const server = await startAgentServiceServer({
     runtime: bundle.runtime,
     serviceName: options.serviceName,
-    lifecycle: bundle.lifecycle,
+    lifecycle: combineAgentServiceLifecycle(bundle.lifecycle, options.lifecycle),
     port: bundle.config.PORT,
     bindAddress: options.bindAddress,
     signals: options.signals,

package/src/src/agent/index.ts

@@ -347,6 +347,21 @@ export {
   veryfrontMcpServer,
   type VeryfrontMcpServerKind,
 } from "./veryfront-cloud-agent-service.js";
+export {
+  type AgentPushRuntimeServiceRest,
+  type AgentServiceRegistrationConfig,
+  agentServiceRegistrationConfigSchema,
+  type AgentServiceRegistrationLifecycle,
+  type AgentServiceRegistrationLogger,
+  type AgentServiceRegistrationMode,
+  createAgentServiceRegistrationLifecycle,
+  type CreateAgentServiceRegistrationLifecycleOptions,
+  type RegisterAgentPushRuntimeServiceRequest,
+  resolveAgentServiceRegistrationInput,
+  type ResolveAgentServiceRegistrationInputOptions,
+  type ResolvedAgentServiceRegistrationInput,
+  resolvedAgentServiceRegistrationInputSchema,
+} from "./agent-service-registration.js";
 export {
   type AgentServiceConfig,
   type AgentServiceConfigInput,

package/src/src/agent/runtime-agent-definition-files.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { z } from "zod";
 import {
@@ -19,6 +19,14 @@ export type ResolveRuntimeAgentDefinitionsDirInput = z.infer<
   typeof resolveRuntimeAgentDefinitionsDirInputSchema
 >;
 
+export const listRuntimeAgentMarkdownDefinitionIdsInputSchema = z.object({
+  baseDir: z.string().min(1),
+});
+
+export type ListRuntimeAgentMarkdownDefinitionIdsInput = z.infer<
+  typeof listRuntimeAgentMarkdownDefinitionIdsInputSchema
+>;
+
 export const loadRuntimeAgentMarkdownDefinitionFromFileInputSchema = z.object({
   agentsDir: z.string().min(1),
   id: runtimeAgentDefinitionFileIdSchema,
@@ -40,27 +48,62 @@ function hasRuntimeAgentDefinitionFile(path: string, fileName: string): boolean
   return existsSync(resolve(path, fileName));
 }
 
+function getRuntimeAgentDefinitionsDirCandidates(baseDir: string): string[] {
+  const firstCandidate = resolve(baseDir, "agents");
+  const sourceLayoutCandidate = resolve(baseDir, "../agents");
+  const candidates = [
+    firstCandidate,
+    sourceLayoutCandidate,
+    resolve(baseDir, "../../agents"),
+    resolve(baseDir, "../../../agents"),
+  ];
+
+  return [...new Set(candidates)];
+}
+
 export function resolveRuntimeAgentDefinitionsDir(
   input: ResolveRuntimeAgentDefinitionsDirInput,
 ): string {
   const parsedInput = resolveRuntimeAgentDefinitionsDirInputSchema.parse(input);
   const fileName = getRuntimeAgentDefinitionFileName(parsedInput);
-  const firstCandidate = resolve(parsedInput.baseDir, "agents");
+  const candidates = getRuntimeAgentDefinitionsDirCandidates(parsedInput.baseDir);
   const sourceLayoutCandidate = resolve(parsedInput.baseDir, "../agents");
-  const candidates = [
-    firstCandidate,
-    sourceLayoutCandidate,
-    resolve(parsedInput.baseDir, "../../agents"),
-    resolve(parsedInput.baseDir, "../../../agents"),
-  ];
   const fallbackCandidate = basename(parsedInput.baseDir) === "src"
     ? sourceLayoutCandidate
-    : firstCandidate;
+    : resolve(parsedInput.baseDir, "agents");
 
   return candidates.find((candidate) => hasRuntimeAgentDefinitionFile(candidate, fileName)) ??
     fallbackCandidate;
 }
 
+export function listRuntimeAgentMarkdownDefinitionIds(
+  input: ListRuntimeAgentMarkdownDefinitionIdsInput,
+): string[] {
+  const parsedInput = listRuntimeAgentMarkdownDefinitionIdsInputSchema.parse(input);
+  const ids = new Set<string>();
+
+  for (const dir of getRuntimeAgentDefinitionsDirCandidates(parsedInput.baseDir)) {
+    if (!existsSync(dir)) {
+      continue;
+    }
+
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isFile()) {
+        continue;
+      }
+
+      const parseResult = runtimeAgentDefinitionFileNameSchema.safeParse(entry.name);
+      if (!parseResult.success) {
+        continue;
+      }
+
+      ids.add(parseResult.data.slice(0, -".md".length));
+    }
+  }
+
+  return [...ids].sort((left, right) => left.localeCompare(right));
+}
+
 export function resolveRuntimeAgentMarkdownDefinitionFilePath(
   input: LoadRuntimeAgentMarkdownDefinitionFromFileInput,
 ): string {