veryfront 0.1.64 → 0.1.67

package/esm/src/server/handlers/request/agent-stream.handler.js

@@ -0,0 +1,86 @@
+import * as dntShim from "../../../../_dnt.shims.js";
+import { defaultChannelInvokeDeps } from "../../../channels/invoke.js";
+import { createRuntimeAgentStreamResponse, } from "../../../internal-agents/run-stream.js";
+import { ControlPlaneRequestError, verifyControlPlaneRequest, } from "../../../internal-agents/control-plane-auth.js";
+import { INTERNAL_AGENT_STREAM_MAX_BODY_BYTES, InternalAgentRequestBodyTooLargeError, readInternalAgentRequestBody, } from "../../../internal-agents/request-body.js";
+import { AgentRunAlreadyExistsError, agentRunSessionManager, } from "../../../internal-agents/session-manager.js";
+import { RuntimeRunAgentInputSchema } from "../../../internal-agents/schema.js";
+import { BaseHandler } from "../response/base.js";
+import { PRIORITY_MEDIUM_API } from "../../../utils/constants/index.js";
+const defaultDeps = {
+    ...defaultChannelInvokeDeps,
+    sessionManager: agentRunSessionManager,
+};
+function applyBuilderHeaders(target, source) {
+    const headers = new dntShim.Headers(target.headers);
+    for (const [key, value] of source.entries()) {
+        if (!headers.has(key)) {
+            headers.set(key, value);
+        }
+    }
+    return new dntShim.Response(target.body, {
+        status: target.status,
+        statusText: target.statusText,
+        headers,
+    });
+}
+export class AgentStreamHandler extends BaseHandler {
+    deps;
+    metadata = {
+        name: "AgentStreamHandler",
+        priority: PRIORITY_MEDIUM_API,
+        patterns: [{ pattern: "/internal/agents/stream", exact: true, method: "POST" }],
+    };
+    constructor(deps = defaultDeps) {
+        super();
+        this.deps = deps;
+    }
+    async handle(req, ctx) {
+        if (!this.shouldHandle(req, ctx)) {
+            return this.continue();
+        }
+        return this.withProxyContext(ctx, async () => {
+            const builder = this.createResponseBuilder(ctx)
+                .withCORS(req, ctx.securityConfig?.cors)
+                .withSecurity(ctx.securityConfig ?? undefined, req);
+            try {
+                const rawBody = await readInternalAgentRequestBody(req, INTERNAL_AGENT_STREAM_MAX_BODY_BYTES);
+                const payload = RuntimeRunAgentInputSchema.parse(JSON.parse(rawBody));
+                await verifyControlPlaneRequest(req, ctx, rawBody, {
+                    expectedSubject: payload.runId,
+                    expectedSurface: "studio",
+                });
+                await this.deps.ensureProjectDiscovery(ctx);
+                const agent = this.deps.getAgent(payload.agentId);
+                if (!agent) {
+                    return this.respond(builder.json({ error: "Agent not found" }, 404));
+                }
+                const response = await createRuntimeAgentStreamResponse(payload, agent, this.deps);
+                return this.respond(applyBuilderHeaders(response, builder.headers));
+            }
+            catch (error) {
+                if (error instanceof InternalAgentRequestBodyTooLargeError) {
+                    return this.respond(builder.json({ error: error.message }, error.status));
+                }
+                if (error instanceof ControlPlaneRequestError) {
+                    return this.respond(builder.json({ error: error.message }, error.status));
+                }
+                if (error instanceof SyntaxError) {
+                    return this.respond(builder.json({ error: "Invalid internal agent stream request" }, 400));
+                }
+                if (error instanceof AgentRunAlreadyExistsError) {
+                    return this.respond(builder.json({ error: error.message }, 409));
+                }
+                if (error instanceof Error && error.name === "ZodError") {
+                    return this.respond(builder.json({ error: "Invalid internal agent stream request" }, 400));
+                }
+                this.logWarn("Internal agent stream request failed", {
+                    error: error instanceof Error ? error.message : String(error),
+                    projectId: ctx.projectId,
+                    projectSlug: ctx.projectSlug,
+                });
+                return this.respond(builder.json({ error: "Internal agent stream failed" }, 500));
+            }
+        });
+    }
+}

package/esm/src/server/handlers/request/{channel-assistants.handler.d.ts → internal-agents-list.handler.d.ts}

@@ -1,11 +1,11 @@
 import * as dntShim from "../../../../_dnt.shims.js";
 import { BaseHandler } from "../response/base.js";
 import type { HandlerContext, HandlerMetadata, HandlerResult } from "../types.js";
-import { type ChannelInvokeDeps } from "../../../channels/invoke.js";
-export declare class ChannelAssistantsHandler extends BaseHandler {
+import { type RuntimeAgentDiscoveryDeps } from "../../../channels/control-plane.js";
+export declare class InternalAgentsListHandler extends BaseHandler {
     private readonly deps;
     metadata: HandlerMetadata;
-    constructor(deps?: ChannelInvokeDeps);
+    constructor(deps?: RuntimeAgentDiscoveryDeps);
     handle(req: dntShim.Request, ctx: HandlerContext): Promise<HandlerResult>;
 }
-//# sourceMappingURL=channel-assistants.handler.d.ts.map
+//# sourceMappingURL=internal-agents-list.handler.d.ts.map

package/esm/src/server/handlers/request/internal-agents-list.handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-agents-list.handler.d.ts","sourceRoot":"","sources":["../../../../../src/src/server/handlers/request/internal-agents-list.handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,2BAA2B,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AACnG,OAAO,EAIL,KAAK,yBAAyB,EAC/B,MAAM,oCAAoC,CAAC;AAc5C,qBAAa,yBAA0B,SAAQ,WAAW;IAO5C,OAAO,CAAC,QAAQ,CAAC,IAAI;IANjC,QAAQ,EAAE,eAAe,CAIvB;gBAE2B,IAAI,GAAE,yBAAoD;IAIjF,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;CAkEhF"}

package/esm/src/server/handlers/request/internal-agents-list.handler.js

@@ -0,0 +1,73 @@
+import { BaseHandler } from "../response/base.js";
+import { ControlPlaneAgentsListRequestSchema, listRuntimeAgents, } from "../../../channels/control-plane.js";
+import { defaultChannelInvokeDeps } from "../../../channels/invoke.js";
+import { ControlPlaneRequestError, verifyControlPlaneRequest, } from "../../../internal-agents/control-plane-auth.js";
+import { INTERNAL_AGENT_CONTROL_PLANE_MAX_BODY_BYTES, InternalAgentRequestBodyTooLargeError, readInternalAgentRequestBody, } from "../../../internal-agents/request-body.js";
+import { PRIORITY_MEDIUM_API } from "../../../utils/constants/index.js";
+import { ZodError } from "zod";
+export class InternalAgentsListHandler extends BaseHandler {
+    deps;
+    metadata = {
+        name: "InternalAgentsListHandler",
+        priority: PRIORITY_MEDIUM_API,
+        patterns: [{ pattern: "/internal/agents/list", exact: true, method: "POST" }],
+    };
+    constructor(deps = defaultChannelInvokeDeps) {
+        super();
+        this.deps = deps;
+    }
+    async handle(req, ctx) {
+        if (!this.shouldHandle(req, ctx)) {
+            return this.continue();
+        }
+        return this.withProxyContext(ctx, async () => {
+            const builder = this.createResponseBuilder(ctx)
+                .withCORS(req, ctx.securityConfig?.cors)
+                .withSecurity(ctx.securityConfig ?? undefined, req);
+            try {
+                const rawBody = await readInternalAgentRequestBody(req, INTERNAL_AGENT_CONTROL_PLANE_MAX_BODY_BYTES);
+                const payload = ControlPlaneAgentsListRequestSchema.parse(JSON.parse(rawBody));
+                const claims = await verifyControlPlaneRequest(req, ctx, rawBody, {
+                    expectedSubject: payload.requestId,
+                    expectedSurface: payload.surface,
+                });
+                if (payload.projectId !== claims.project_id ||
+                    (ctx.projectId !== undefined && payload.projectId !== ctx.projectId)) {
+                    this.logWarn("Internal agents list request body did not match signed claims", {
+                        projectSlug: ctx.projectSlug,
+                        projectId: ctx.projectId,
+                        requestId: payload.requestId,
+                        signedRequestId: claims.sub,
+                        surface: payload.surface,
+                        signedSurface: claims.surface,
+                    });
+                    return this.respond(builder.json({ error: "Invalid control-plane signature" }, 401));
+                }
+                const response = await listRuntimeAgents(ctx, this.deps);
+                return this.respond(builder.json(response, 200));
+            }
+            catch (error) {
+                if (error instanceof InternalAgentRequestBodyTooLargeError) {
+                    return this.respond(builder.json({ error: error.message }, error.status));
+                }
+                if (error instanceof ControlPlaneRequestError) {
+                    this.logWarn("Internal agents list signature verification failed", {
+                        error: error.message,
+                        projectSlug: ctx.projectSlug,
+                        projectId: ctx.projectId,
+                    });
+                    return this.respond(builder.json({ error: error.message }, error.status));
+                }
+                if (error instanceof SyntaxError || error instanceof ZodError) {
+                    this.logWarn("Internal agents list request validation failed", {
+                        error: error instanceof Error ? error.message : String(error),
+                        projectSlug: ctx.projectSlug,
+                        projectId: ctx.projectId,
+                    });
+                    return this.respond(builder.json({ error: "Invalid internal agents request" }, 400));
+                }
+                throw error;
+            }
+        });
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/src/server/runtime-handler/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,OAAO,MAAM,wBAAwB,CAAC;AAQlD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AA0F7D,OAAO,EAAE,qBAAqB,EAAE,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAMtF,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,oFAAoF;IACpF,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,sFAAsF;IACtF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oFAAoF;IACpF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uGAAuG;IACvG,kBAAkB,CAAC,EAAE,SAAS,GAAG,YAAY,CAAC;CAC/C;AAED,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,cAAc,EACvB,IAAI,GAAE,qBAAsC,GAC3C,CAAC,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAyanF;AAGD,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/src/server/runtime-handler/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,OAAO,MAAM,wBAAwB,CAAC;AAQlD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AA6F7D,OAAO,EAAE,qBAAqB,EAAE,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAMtF,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,oFAAoF;IACpF,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,sFAAsF;IACtF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oFAAoF;IACpF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uGAAuG;IACvG,kBAAkB,CAAC,EAAE,SAAS,GAAG,YAAY,CAAC;CAC/C;AAED,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,cAAc,EACvB,IAAI,GAAE,qBAAsC,GAC3C,CAAC,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CA4anF;AAGD,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC"}

package/esm/src/server/runtime-handler/index.js

@@ -42,7 +42,10 @@ import { HMRHandler } from "../handlers/preview/hmr.handler.js";
 import { MarkdownPreviewHandler } from "../handlers/preview/markdown-preview.handler.js";
 import { OpenAPIHandler } from "../handlers/request/openapi.handler.js";
 import { OpenAPIDocsHandler } from "../handlers/request/openapi-docs.handler.js";
-import { ChannelAssistantsHandler } from "../handlers/request/channel-assistants.handler.js";
+import { InternalAgentsListHandler } from "../handlers/request/internal-agents-list.handler.js";
+import { AgentStreamHandler } from "../handlers/request/agent-stream.handler.js";
+import { AgentRunResumeHandler } from "../handlers/request/agent-run-resume.handler.js";
+import { AgentRunCancelHandler } from "../handlers/request/agent-run-cancel.handler.js";
 import { ChannelInvokeHandler } from "../handlers/request/channel-invoke.handler.js";
 import { DevDashboardHandler } from "../handlers/dev/dashboard/index.js";
 import { ProjectsHandler } from "../handlers/dev/projects/index.js";
@@ -125,7 +128,10 @@ export function createVeryfrontHandler(projectDir, adapter, opts = { projectDir
         new DebugContextHandler(),
         new OpenAPIHandler(),
         new OpenAPIDocsHandler(),
-        new ChannelAssistantsHandler(),
+        new InternalAgentsListHandler(),
+        new AgentStreamHandler(),
+        new AgentRunResumeHandler(),
+        new AgentRunCancelHandler(),
         new ChannelInvokeHandler(),
         new DevDashboardHandler(),
         new ProjectsHandler(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "veryfront",
-  "version": "0.1.64",
+  "version": "0.1.67",
   "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.64",
+  "version": "0.1.67",
   "license": "Apache-2.0",
   "nodeModulesDir": "auto",
   "exclude": [

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

@@ -243,6 +243,7 @@ export class AgentRuntime {
     callbacks?: {
       onToolCall?: (toolCall: ToolCall) => void;
       onChunk?: (chunk: string) => void;
+      onFinish?: (response: AgentResponse) => void;
     },
     modelOverride?: string,
     maxOutputTokensOverride?: number,
@@ -298,7 +299,7 @@ export class AgentRuntime {
           });
           sendSSE(controller, encoder, { type: "text-start", id: textPartId });
 
-          await this.executeAgentLoopStreaming(
+          const response = await this.executeAgentLoopStreaming(
             systemPrompt,
             memoryMessages,
             controller,
@@ -310,6 +311,7 @@ export class AgentRuntime {
             languageModel,
             maxOutputTokensOverride,
           );
+          callbacks?.onFinish?.(response);
 
           sendSSE(controller, encoder, { type: "text-end", id: textPartId });
           sendSSE(controller, encoder, { type: "message-finish" });
@@ -479,7 +481,10 @@ export class AgentRuntime {
               toolCall.status = "executing";
               const startTime = Date.now();
 
-              const result = await executeTool(tc.toolName, toolCall.args, { agentId: this.id });
+              const result = await executeTool(tc.toolName, toolCall.args, {
+                agentId: this.id,
+                toolCallId: tc.toolCallId,
+              });
 
               toolCall.status = "completed";
               toolCall.result = result;
@@ -561,6 +566,7 @@ export class AgentRuntime {
     callbacks?: {
       onToolCall?: (toolCall: ToolCall) => void;
       onChunk?: (chunk: string) => void;
+      onFinish?: (response: AgentResponse) => void;
     },
     textPartId?: string,
     toolContext?: Record<string, unknown>,
@@ -590,6 +596,7 @@ export class AgentRuntime {
 
     // Request-scoped skill policy (not class-level mutable state)
     let activeSkillPolicy: string[] | undefined;
+    let finalFinishReason: string | undefined;
 
     for (let step = 0; step < maxSteps; step++) {
       sendSSE(controller, encoder, { type: "step-start" });
@@ -617,6 +624,7 @@ export class AgentRuntime {
         onChunk: callbacks?.onChunk,
         onUsage: (usage) => accumulateUsage(totalUsage, usage),
       });
+      finalFinishReason = state.finishReason ?? finalFinishReason;
 
       const streamParts: MessagePart[] = [];
       if (state.accumulatedText) streamParts.push({ type: "text", text: state.accumulatedText });
@@ -707,6 +715,7 @@ export class AgentRuntime {
 
           const result = await executeTool(tc.name, toolCall.args, {
             agentId: this.id,
+            toolCallId: tc.id,
             ...toolContext,
           });
 
@@ -768,6 +777,7 @@ export class AgentRuntime {
       toolCalls,
       status: "completed",
       usage: totalUsage,
+      metadata: finalFinishReason ? { finishReason: finalFinishReason } : undefined,
     };
   }
 

package/src/src/channels/control-plane.ts

@@ -0,0 +1,332 @@
+import * as dntShim from "../../_dnt.shims.js";
+import type { Agent } from "../agent/index.js";
+import type { HandlerContext } from "../types/index.js";
+import { skillRegistry } from "../skill/registry.js";
+import { base64urlEncodeBytes } from "../utils/base64url.js";
+import { z } from "zod";
+
+const SIGNATURE_SKEW_SECONDS = 5;
+
+const compactJwsHeaderSchema = z.object({
+  alg: z.literal("EdDSA"),
+  typ: z.string().optional(),
+  kid: z.string().optional(),
+});
+
+export const ControlPlaneSurfaceSchema = z.enum(["studio", "channels", "a2a", "mcp"]);
+
+export const ControlPlaneAgentsListRequestSchema = z.object({
+  requestId: z.string().min(1),
+  projectId: z.string().min(1),
+  surface: ControlPlaneSurfaceSchema,
+});
+
+export const RuntimeAgentSkillSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+  examples: z.array(z.string()).optional(),
+});
+
+export const RuntimeAgentSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string().nullable().optional(),
+  model: z.string().nullable().optional(),
+  version: z.string().nullable().optional(),
+  skills: z.array(RuntimeAgentSkillSchema).optional(),
+});
+
+export const RuntimeAgentListResponseSchema = z.object({
+  agents: z.array(RuntimeAgentSchema),
+});
+
+const dispatchClaimsSchema = z.object({
+  iss: z.string(),
+  aud: z.string(),
+  sub: z.string(),
+  project_id: z.string(),
+  platform: z.string(),
+  body_sha256: z.string(),
+  iat: z.number().int(),
+  exp: z.number().int(),
+});
+
+const controlPlaneClaimsSchema = z.object({
+  iss: z.string(),
+  aud: z.string(),
+  sub: z.string(),
+  surface: ControlPlaneSurfaceSchema,
+  project_id: z.string(),
+  request_hash: z.string(),
+  iat: z.number().int(),
+  exp: z.number().int(),
+});
+
+export type ControlPlaneSurface = z.infer<typeof ControlPlaneSurfaceSchema>;
+export type ControlPlaneAgentsListRequest = z.infer<typeof ControlPlaneAgentsListRequestSchema>;
+export type RuntimeAgentSkill = z.infer<typeof RuntimeAgentSkillSchema>;
+export type RuntimeAgent = z.infer<typeof RuntimeAgentSchema>;
+export type RuntimeAgentListResponse = z.infer<typeof RuntimeAgentListResponseSchema>;
+export type DispatchClaims = z.infer<typeof dispatchClaimsSchema>;
+export type ControlPlaneClaims = z.infer<typeof controlPlaneClaimsSchema>;
+
+export interface RuntimeAgentDiscoveryDeps {
+  ensureProjectDiscovery: (ctx: HandlerContext) => Promise<void>;
+  getAgent: (id: string) => Agent | undefined;
+  getAllAgentIds: () => string[];
+}
+
+type SignedRequestClaims = {
+  aud: string;
+  exp: number;
+  iat: number;
+  project_id: string;
+  sub: string;
+} & Record<string, unknown>;
+
+function base64urlDecodeToBytes(input: string): ArrayBuffer {
+  const normalized = input
+    .replaceAll("-", "+")
+    .replaceAll("_", "/")
+    .padEnd(Math.ceil(input.length / 4) * 4, "=");
+
+  return toArrayBuffer(Uint8Array.from(atob(normalized), (char) => char.charCodeAt(0)));
+}
+
+function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  const buffer = new ArrayBuffer(bytes.byteLength);
+  new Uint8Array(buffer).set(bytes);
+  return buffer;
+}
+
+function pemToDer(pem: string, label: string): ArrayBuffer {
+  const body = pem
+    .replace(`-----BEGIN ${label}-----`, "")
+    .replace(`-----END ${label}-----`, "")
+    .replace(/\s/g, "");
+
+  return toArrayBuffer(Uint8Array.from(atob(body), (char) => char.charCodeAt(0)));
+}
+
+async function importEd25519PublicKey(pem: string): Promise<dntShim.CryptoKey> {
+  return dntShim.crypto.subtle.importKey(
+    "spki",
+    pemToDer(pem, "PUBLIC KEY"),
+    "Ed25519",
+    false,
+    ["verify"],
+  );
+}
+
+async function sha256Base64url(body: string): Promise<string> {
+  const hash = await dntShim.crypto.subtle.digest("SHA-256", new TextEncoder().encode(body));
+  return base64urlEncodeBytes(new Uint8Array(hash));
+}
+
+async function verifySignedRequestJws<TClaims extends SignedRequestClaims>(
+  jws: string,
+  body: string,
+  options: {
+    audience: string;
+    claimsSchema: z.ZodType<TClaims>;
+    expectedProjectId?: string;
+    expectedSubject?: string;
+    hashClaimKey: keyof TClaims & string;
+    maxAgeSeconds: number;
+    publicKeyPem: string;
+    scopedClaim?: {
+      key: keyof TClaims & string;
+      label: string;
+      value: string;
+    };
+  },
+): Promise<TClaims> {
+  const parts = jws.split(".");
+  if (parts.length !== 3) {
+    throw new Error("Control-plane signature must be a compact JWS");
+  }
+
+  const encodedHeader = parts[0];
+  const encodedPayload = parts[1];
+  const encodedSignature = parts[2];
+  if (!encodedHeader || !encodedPayload || !encodedSignature) {
+    throw new Error("Control-plane signature must include header, payload, and signature");
+  }
+
+  const header = compactJwsHeaderSchema.parse(
+    JSON.parse(new TextDecoder().decode(base64urlDecodeToBytes(encodedHeader))),
+  );
+  const claims = options.claimsSchema.parse(
+    JSON.parse(new TextDecoder().decode(base64urlDecodeToBytes(encodedPayload))),
+  );
+
+  if (header.alg !== "EdDSA") {
+    throw new Error("Unsupported control-plane JWS algorithm");
+  }
+
+  const signingInput = new TextEncoder().encode(`${encodedHeader}.${encodedPayload}`);
+  const signature = base64urlDecodeToBytes(encodedSignature);
+  const publicKey = await importEd25519PublicKey(options.publicKeyPem);
+  const verified = await dntShim.crypto.subtle.verify("Ed25519", publicKey, signature, signingInput);
+
+  if (!verified) {
+    throw new Error("Control-plane signature verification failed");
+  }
+
+  if (claims.iss !== "veryfront-api") {
+    throw new Error("Control-plane issuer mismatch");
+  }
+
+  if (claims.aud !== options.audience) {
+    throw new Error("Control-plane audience mismatch");
+  }
+
+  if (options.expectedProjectId && claims.project_id !== options.expectedProjectId) {
+    throw new Error("Control-plane project mismatch");
+  }
+
+  if (options.expectedSubject && claims.sub !== options.expectedSubject) {
+    throw new Error("Control-plane subject mismatch");
+  }
+
+  if (options.scopedClaim && claims[options.scopedClaim.key] !== options.scopedClaim.value) {
+    throw new Error(`Control-plane ${options.scopedClaim.label} mismatch`);
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  if (claims.exp <= now) {
+    throw new Error("Control-plane signature expired");
+  }
+
+  if (claims.iat > now + SIGNATURE_SKEW_SECONDS) {
+    throw new Error("Control-plane signature issued in the future");
+  }
+
+  if (now - claims.iat > options.maxAgeSeconds) {
+    throw new Error("Control-plane signature is too old");
+  }
+
+  const requestHash = claims[options.hashClaimKey];
+  if (typeof requestHash !== "string") {
+    throw new Error("Control-plane request hash is missing");
+  }
+
+  const bodyHash = await sha256Base64url(body);
+  if (requestHash !== bodyHash) {
+    throw new Error("Control-plane body hash mismatch");
+  }
+
+  return claims;
+}
+
+function resolveAgentSkills(agent: Agent): RuntimeAgentSkill[] {
+  if (!agent.config.skills) {
+    return [];
+  }
+
+  return Array.from(skillRegistry.resolveForAgent(agent.config.skills).values())
+    .map((skill) =>
+      RuntimeAgentSkillSchema.parse({
+        id: skill.id,
+        name: skill.metadata.name || skill.id,
+        ...(skill.metadata.description ? { description: skill.metadata.description } : {}),
+      })
+    )
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function getRuntimeAgentMetadata(agent: Agent): RuntimeAgent {
+  const rawConfig = agent.config as unknown as Record<string, unknown>;
+
+  return RuntimeAgentSchema.parse({
+    id: agent.id,
+    name: typeof rawConfig.name === "string" && rawConfig.name.trim().length > 0
+      ? rawConfig.name
+      : agent.id,
+    description: typeof rawConfig.description === "string" ? rawConfig.description : null,
+    model: agent.config.model ?? null,
+    version: typeof rawConfig.version === "string" ? rawConfig.version : null,
+    skills: resolveAgentSkills(agent),
+  });
+}
+
+export async function listRuntimeAgents(
+  ctx: HandlerContext,
+  deps: RuntimeAgentDiscoveryDeps,
+): Promise<RuntimeAgentListResponse> {
+  await deps.ensureProjectDiscovery(ctx);
+
+  const agents = deps.getAllAgentIds()
+    .map((id) => deps.getAgent(id))
+    .filter((agent): agent is Agent => Boolean(agent))
+    .map(getRuntimeAgentMetadata)
+    .sort((left, right) => left.name.localeCompare(right.name));
+
+  return RuntimeAgentListResponseSchema.parse({ agents });
+}
+
+export async function verifyDispatchJws(
+  jws: string,
+  body: string,
+  options: {
+    audience: string;
+    expectedPlatform?: string;
+    expectedProjectId?: string;
+    expectedSubject?: string;
+    maxAgeSeconds: number;
+    publicKeyPem: string;
+  },
+): Promise<DispatchClaims> {
+  return verifySignedRequestJws(jws, body, {
+    audience: options.audience,
+    claimsSchema: dispatchClaimsSchema,
+    expectedProjectId: options.expectedProjectId,
+    ...(options.expectedSubject ? { expectedSubject: options.expectedSubject } : {}),
+    hashClaimKey: "body_sha256",
+    maxAgeSeconds: options.maxAgeSeconds,
+    publicKeyPem: options.publicKeyPem,
+    ...(options.expectedPlatform
+      ? {
+        scopedClaim: {
+          key: "platform" as const,
+          label: "platform",
+          value: options.expectedPlatform,
+        },
+      }
+      : {}),
+  });
+}
+
+export async function verifyControlPlaneJws(
+  jws: string,
+  body: string,
+  options: {
+    audience: string;
+    expectedProjectId?: string;
+    expectedSubject?: string;
+    expectedSurface?: ControlPlaneSurface;
+    maxAgeSeconds: number;
+    publicKeyPem: string;
+  },
+): Promise<ControlPlaneClaims> {
+  return verifySignedRequestJws(jws, body, {
+    audience: options.audience,
+    claimsSchema: controlPlaneClaimsSchema,
+    expectedProjectId: options.expectedProjectId,
+    ...(options.expectedSubject ? { expectedSubject: options.expectedSubject } : {}),
+    hashClaimKey: "request_hash",
+    maxAgeSeconds: options.maxAgeSeconds,
+    publicKeyPem: options.publicKeyPem,
+    ...(options.expectedSurface
+      ? {
+        scopedClaim: {
+          key: "surface" as const,
+          label: "surface",
+          value: options.expectedSurface,
+        },
+      }
+      : {}),
+  });
+}