veryfront 0.1.146 → 0.1.147

package/src/src/internal-agents/schema.ts

@@ -79,21 +79,105 @@ export const RuntimeAgentSourceContextSchema = z.discriminatedUnion("type", [
   }),
 ]);
 
+const RuntimeMessageExtensionFieldsSchema = {
+  name: z.string().max(256).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  createdAt: z.string().optional(),
+} as const;
+
+export const RuntimeToolFunctionCallSchema = z.object({
+  name: ClientToolNameSchema,
+  arguments: z.string().max(MAX_TOOL_PARAMETERS_BYTES),
+}).strict();
+
+export const RuntimeToolCallSchema = z.object({
+  id: z.string().min(1).max(128),
+  type: z.literal("function"),
+  function: RuntimeToolFunctionCallSchema,
+}).strict();
+
+export const RuntimeSystemMessageSchema = z.object({
+  id: z.string().min(1),
+  role: z.literal("system"),
+  content: z.string(),
+  ...RuntimeMessageExtensionFieldsSchema,
+}).strict();
+
+export const RuntimeUserMessageSchema = z.object({
+  id: z.string().min(1),
+  role: z.literal("user"),
+  content: z.string(),
+  ...RuntimeMessageExtensionFieldsSchema,
+}).strict();
+
+export const RuntimeAssistantMessageSchema = z.object({
+  id: z.string().min(1),
+  role: z.literal("assistant"),
+  content: z.string().optional(),
+  toolCalls: z.array(RuntimeToolCallSchema).optional(),
+  ...RuntimeMessageExtensionFieldsSchema,
+}).strict();
+
+export const RuntimeToolMessageSchema = z.object({
+  id: z.string().min(1),
+  role: z.literal("tool"),
+  toolCallId: z.string().min(1).max(128),
+  content: z.string(),
+  error: z.string().optional(),
+  ...RuntimeMessageExtensionFieldsSchema,
+}).strict();
+
+export const RuntimeMessageSchema = z.discriminatedUnion("role", [
+  RuntimeSystemMessageSchema,
+  RuntimeUserMessageSchema,
+  RuntimeAssistantMessageSchema,
+  RuntimeToolMessageSchema,
+]);
+
+export const RuntimeContextSchema = z.union([
+  z.object({
+    description: z.string().max(1024),
+    value: z.string().max(MAX_CONTEXT_ITEM_BYTES),
+  }),
+  RuntimeContextItemSchema,
+]);
+
 export const RuntimeRunAgentInputSchema = z.object({
+  threadId: z.string().uuid(),
+  runId: RunIdSchema,
+  parentRunId: RunIdSchema.optional(),
+  state: z.unknown().optional(),
+  messages: z.array(RuntimeMessageSchema).max(MAX_RUNTIME_MESSAGES),
+  tools: z.array(RuntimeInjectedToolSchema).max(50).default([]),
+  context: z.array(RuntimeContextSchema).max(10).default([]).refine(
+    (value) => isWithinJsonSizeLimit(value, MAX_CONTEXT_TOTAL_BYTES),
+    { message: "context must be less than 64 KB total" },
+  ),
+  forwardedProps: z.record(z.string(), z.unknown()).optional().refine(
+    (value) => value === undefined || isWithinJsonSizeLimit(value, MAX_FORWARDED_PROPS_BYTES),
+    { message: "forwardedProps must be less than 64 KB" },
+  ),
+});
+
+export const InternalAgentCompatibilityMessageSchema = z.object({
+  id: z.string().min(1),
+  role: z.enum(["user", "assistant", "system", "tool"]),
+  parts: z.array(z.object({ type: z.string().min(1) }).passthrough()).default([]),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  createdAt: z.string().optional(),
+});
+
+export const InternalAgentStreamRequestSchema = z.object({
   agentId: AgentIdSchema,
   threadId: z.string().uuid(),
   runId: RunIdSchema,
-  messages: z.array(
-    z.object({
-      id: z.string().min(1),
-      role: z.enum(["user", "assistant", "system", "tool"]),
-      parts: z.array(z.object({ type: z.string().min(1) }).passthrough()).default([]),
-      metadata: z.record(z.string(), z.unknown()).optional(),
-      createdAt: z.string().optional(),
-    }),
-  ).max(MAX_RUNTIME_MESSAGES),
+  parentRunId: RunIdSchema.optional(),
+  state: z.unknown().optional(),
+  messages: z.array(z.union([RuntimeMessageSchema, InternalAgentCompatibilityMessageSchema])).max(
+    MAX_RUNTIME_MESSAGES,
+  ),
   tools: z.array(RuntimeInjectedToolSchema).max(50).default([]),
-  context: z.array(RuntimeContextItemSchema).max(10).default([]).refine(
+  context: z.array(RuntimeContextSchema).max(10).default([]).refine(
     (value) => isWithinJsonSizeLimit(value, MAX_CONTEXT_TOTAL_BYTES),
     { message: "context must be less than 64 KB total" },
   ),
@@ -104,6 +188,188 @@ export const RuntimeRunAgentInputSchema = z.object({
   ),
 });
 
+type RuntimeMessage = z.infer<typeof RuntimeMessageSchema>;
+type InternalAgentCompatibilityMessage = z.infer<typeof InternalAgentCompatibilityMessageSchema>;
+
+function extractToolArgs(
+  part: Record<string, unknown>,
+): Record<string, unknown> {
+  const args = part.args;
+  if (args && typeof args === "object" && !Array.isArray(args)) {
+    return args as Record<string, unknown>;
+  }
+
+  const input = part.input;
+  if (input && typeof input === "object" && !Array.isArray(input)) {
+    return input as Record<string, unknown>;
+  }
+
+  return {};
+}
+
+function serializeToolArguments(args: Record<string, unknown>): string {
+  try {
+    return JSON.stringify(args);
+  } catch {
+    return "{}";
+  }
+}
+
+function getPartString(
+  part: Record<string, unknown>,
+  ...keys: string[]
+): string | null {
+  for (const key of keys) {
+    const value = part[key];
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+  }
+
+  return null;
+}
+
+function isLegacyToolCallPart(part: Record<string, unknown>): boolean {
+  return getPartString(part, "type") === "tool_call";
+}
+
+function isCanonicalToolCallPart(part: Record<string, unknown>): boolean {
+  const type = getPartString(part, "type");
+
+  return type === "tool-call" ||
+    (typeof type === "string" && type.startsWith("tool-") && type !== "tool-result" &&
+      type !== "tool_result");
+}
+
+function getToolCallShape(
+  part: Record<string, unknown>,
+): z.infer<typeof RuntimeToolCallSchema> | null {
+  const id = getPartString(part, "toolCallId", "tool_call_id", "id");
+  const name = getPartString(part, "toolName", "tool_name", "name");
+
+  if (!id || !name) {
+    return null;
+  }
+
+  return {
+    id,
+    type: "function",
+    function: {
+      name,
+      arguments: serializeToolArguments(extractToolArgs(part)),
+    },
+  };
+}
+
+function isToolResultPart(part: Record<string, unknown>): boolean {
+  const type = getPartString(part, "type");
+  return type === "tool-result" || type === "tool_result";
+}
+
+function stringifyToolResult(result: unknown): string {
+  if (typeof result === "string") {
+    return result;
+  }
+
+  try {
+    return JSON.stringify(result);
+  } catch {
+    return String(result);
+  }
+}
+
+function toRuntimeMessage(
+  message: RuntimeMessage | InternalAgentCompatibilityMessage,
+): RuntimeMessage {
+  if (!("parts" in message)) {
+    return message;
+  }
+
+  const textContent = message.parts
+    .filter((part) => part.type === "text" && typeof part.text === "string")
+    .map((part) => part.text)
+    .join("\n");
+
+  const sharedFields = {
+    ...(message.metadata ? { metadata: message.metadata } : {}),
+    ...(message.createdAt ? { createdAt: message.createdAt } : {}),
+  };
+
+  switch (message.role) {
+    case "system":
+      return {
+        id: message.id,
+        role: "system",
+        content: textContent,
+        ...sharedFields,
+      };
+    case "user":
+      return {
+        id: message.id,
+        role: "user",
+        content: textContent,
+        ...sharedFields,
+      };
+    case "assistant": {
+      const toolCalls = message.parts.flatMap((part) => {
+        if (!isCanonicalToolCallPart(part) && !isLegacyToolCallPart(part)) {
+          return [];
+        }
+
+        const toolCall = getToolCallShape(part);
+        return toolCall ? [toolCall] : [];
+      });
+
+      return {
+        id: message.id,
+        role: "assistant",
+        ...(textContent ? { content: textContent } : {}),
+        ...(toolCalls.length ? { toolCalls } : {}),
+        ...sharedFields,
+      };
+    }
+    case "tool": {
+      const toolResultPart = message.parts.find(
+        (part) =>
+          isToolResultPart(part) && getPartString(part, "toolCallId", "tool_call_id") !== null,
+      );
+      const toolCallId = toolResultPart
+        ? getPartString(toolResultPart, "toolCallId", "tool_call_id")
+        : null;
+      const toolResult = toolResultPart && "result" in toolResultPart
+        ? toolResultPart.result
+        : toolResultPart && "output" in toolResultPart
+        ? toolResultPart.output
+        : undefined;
+      const toolError = toolResultPart ? getPartString(toolResultPart, "error") : null;
+
+      return {
+        id: message.id,
+        role: "tool",
+        toolCallId: toolCallId ?? message.id,
+        content: toolResult !== undefined ? stringifyToolResult(toolResult) : textContent,
+        ...(toolError ? { error: toolError } : {}),
+        ...sharedFields,
+      };
+    }
+  }
+}
+
+export function toRuntimeRunAgentInput(
+  input: z.infer<typeof InternalAgentStreamRequestSchema>,
+): z.infer<typeof RuntimeRunAgentInputSchema> {
+  return {
+    threadId: input.threadId,
+    runId: input.runId,
+    ...(input.parentRunId ? { parentRunId: input.parentRunId } : {}),
+    ...(input.state !== undefined ? { state: input.state } : {}),
+    messages: input.messages.map(toRuntimeMessage),
+    tools: input.tools,
+    context: input.context,
+    ...(input.forwardedProps ? { forwardedProps: input.forwardedProps } : {}),
+  };
+}
+
 export const ResumeSignalSchema = z.discriminatedUnion("type", [
   z.object({
     type: z.literal("tool_result"),
@@ -120,4 +386,5 @@ export type RuntimeInjectedTool = z.infer<typeof RuntimeInjectedToolSchema>;
 export type RuntimeContextItem = z.infer<typeof RuntimeContextItemSchema>;
 export type RuntimeAgentSourceContext = z.infer<typeof RuntimeAgentSourceContextSchema>;
 export type RuntimeRunAgentInput = z.infer<typeof RuntimeRunAgentInputSchema>;
+export type InternalAgentStreamRequest = z.infer<typeof InternalAgentStreamRequestSchema>;
 export type ResumeSignal = z.infer<typeof ResumeSignalSchema>;

package/src/src/mcp/elicitation.ts

@@ -0,0 +1,42 @@
+export interface FormElicitationOptions {
+  message: string;
+  schema: Record<string, unknown>;
+}
+
+export interface UrlElicitationOptions {
+  message: string;
+  url: string;
+  elicitationId: string;
+}
+
+export interface ElicitationRequest {
+  method: "elicitation/create";
+  params: Record<string, unknown>;
+}
+
+export function buildFormElicitation(
+  options: FormElicitationOptions,
+): ElicitationRequest {
+  return {
+    method: "elicitation/create",
+    params: {
+      mode: "form",
+      message: options.message,
+      requestedSchema: options.schema,
+    },
+  };
+}
+
+export function buildUrlElicitation(
+  options: UrlElicitationOptions,
+): ElicitationRequest {
+  return {
+    method: "elicitation/create",
+    params: {
+      mode: "url",
+      message: options.message,
+      url: options.url,
+      elicitationId: options.elicitationId,
+    },
+  };
+}

package/src/src/mcp/index.ts

@@ -43,5 +43,14 @@ export {
 
 export { createMCPServer, type IntegrationLoaderConfig, MCPServer } from "./server.js";
 
+export {
+  buildFormElicitation,
+  buildUrlElicitation,
+  type ElicitationRequest,
+  type FormElicitationOptions,
+  type UrlElicitationOptions,
+} from "./elicitation.js";
 export { formatSSEEvent, formatSSEPrimingEvent, formatSSERetry } from "./sse.js";
 export { SessionManager } from "./session.js";
+export { TaskStore } from "./task-store.js";
+export type { Task } from "./task-store.js";

package/src/src/mcp/server.ts

@@ -14,6 +14,7 @@ import { VeryfrontError } from "../security/input-validation/errors.js";
 import type { IntegrationRuntimeConfig } from "../integrations/types.js";
 import { logger as baseLogger } from "../utils/index.js";
 import { SessionManager } from "./session.js";
+import { TaskStore } from "./task-store.js";
 
 const logger = baseLogger.component("mcp-server");
 
@@ -110,10 +111,29 @@ export interface IntegrationLoaderConfig {
 const MCP_SUPPORTED_VERSIONS = ["2025-11-25", "2024-11-05"];
 
 export class MCPServer {
+  private static LOG_LEVELS = [
+    "debug",
+    "info",
+    "notice",
+    "warning",
+    "error",
+    "critical",
+    "alert",
+    "emergency",
+  ] as const;
+  private logLevel: typeof MCPServer.LOG_LEVELS[number] = "warning";
   private config: MCPServerConfig;
   private integrationLoader?: IntegrationLoaderConfig;
   private integrationsLoaded = false;
   private sessionManager = new SessionManager();
+  private taskStore = new TaskStore();
+  private pendingTasks = new Map<string, Promise<void>>();
+  // TODO(#842): capabilities should be stored per-session (keyed by MCP-Session-Id)
+  // so concurrent clients don't overwrite each other's capability flags.
+  private clientCapabilities: Record<string, unknown> = {};
+
+  /** Callback for server-initiated notifications. Set by transport layer. */
+  onNotification?: (notification: { jsonrpc: "2.0"; method: string; params?: unknown }) => void;
 
   constructor(config: MCPServerConfig) {
     this.config = config;
@@ -123,6 +143,18 @@ export class MCPServer {
     }
   }
 
+  notifyToolsChanged(): void {
+    this.onNotification?.({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
+  }
+
+  notifyResourcesChanged(): void {
+    this.onNotification?.({ jsonrpc: "2.0", method: "notifications/resources/list_changed" });
+  }
+
+  notifyPromptsChanged(): void {
+    this.onNotification?.({ jsonrpc: "2.0", method: "notifications/prompts/list_changed" });
+  }
+
   /**
    * Configure integration tools to be loaded from the API.
    *
@@ -135,6 +167,15 @@ export class MCPServer {
     this.integrationsLoaded = false;
   }
 
+  clientSupportsElicitation(mode: "form" | "url"): boolean {
+    const raw = this.clientCapabilities.elicitation;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return false;
+    const elicitation = raw as Record<string, unknown>;
+    // Per MCP spec: empty elicitation object implies basic form support (backwards compat)
+    if (mode === "form" && Object.keys(elicitation).length === 0) return true;
+    return mode in elicitation;
+  }
+
   handleRequest(request: JSONRPCRequest, context?: ToolExecutionContext): Promise<JSONRPCResponse> {
     return withSpan(
       "mcp.handleRequest",
@@ -178,8 +219,21 @@ export class MCPServer {
         return this.initialize(params);
       case "notifications/initialized":
         return Promise.resolve({});
+      case "notifications/cancelled":
+        // TODO(#841): propagate cancellation to in-flight tool executions via AbortController
+        return Promise.resolve({});
       case "completion/complete":
         return this.complete(params);
+      case "logging/setLevel":
+        return this.setLogLevel(params);
+      case "tasks/get":
+        return this.getTask(params);
+      case "tasks/result":
+        return this.getTaskResult(params);
+      case "tasks/cancel":
+        return this.cancelTask(params);
+      case "tasks/list":
+        return this.listTasks();
       default:
         throw toError(
           createError({
@@ -197,6 +251,9 @@ export class MCPServer {
       ? requested
       : MCP_SUPPORTED_VERSIONS[0];
 
+    const clientCaps = (p.capabilities ?? {}) as Record<string, unknown>;
+    this.clientCapabilities = clientCaps;
+
     return Promise.resolve({
       protocolVersion: negotiated,
       serverInfo: {
@@ -211,6 +268,8 @@ export class MCPServer {
         resources: { subscribe: true, listChanged: true },
         prompts: { listChanged: true },
         completions: {},
+        logging: {},
+        tasks: { list: {}, cancel: {}, requests: { tools: { call: {} } } },
       },
       instructions:
         "Veryfront MCP server provides development tools. Use vf_get_errors to check for code errors, vf_get_logs for server logs, vf_scaffold for code generation, and vf_get_project_context for project structure.",
@@ -250,7 +309,13 @@ export class MCPServer {
     params: JSONRPCParams | undefined,
     context?: ToolExecutionContext,
   ): Promise<Record<string, unknown>> {
-    const { name, arguments: args } = toParamsRecord(params);
+    const p = toParamsRecord(params);
+    const { name, arguments: args } = p;
+    const meta = (p._meta ?? {}) as Record<string, unknown>;
+    const rawToken = meta.progressToken;
+    const progressToken = (typeof rawToken === "string" || typeof rawToken === "number")
+      ? rawToken
+      : undefined;
 
     if (!name) {
       throw toError(createError({ type: "agent", message: "Tool name is required" }));
@@ -273,11 +338,55 @@ export class MCPServer {
       }
     }
 
+    const toolContext: ToolExecutionContext | undefined = progressToken !== undefined
+      ? { ...context, progressToken }
+      : context;
+
+    // Async task mode: if the caller provides a `task` field, create a task
+    // and run the tool in the background, returning the task immediately.
+    const taskParam = p.task as { ttl?: number } | undefined;
+    if (taskParam) {
+      const MIN_TTL = 1000;
+      const MAX_TTL = 3_600_000; // 1 hour
+      const rawTtl = typeof taskParam.ttl === "number" ? taskParam.ttl : 60000;
+      const ttl = Math.max(MIN_TTL, Math.min(MAX_TTL, rawTtl));
+      const task = this.taskStore.create(ttl);
+
+      // Run tool in background, update task on completion
+      // TODO(#842): wire AbortController so that tasks/cancel actually aborts the running tool execution
+      const pending = withSpan(
+        "mcp.callTool.async",
+        async () => {
+          try {
+            const result = await executeTool(toolName, args, toolContext);
+            this.taskStore.complete(task.taskId, {
+              content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+              isError: false,
+            });
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.warn("Async tool execution failed", {
+              tool: toolName,
+              taskId: task.taskId,
+              error: message,
+            });
+            this.taskStore.fail(task.taskId, message);
+          }
+        },
+        { "mcp.tool.name": toolName, "mcp.task.id": task.taskId },
+      ).then(() => {
+        this.pendingTasks.delete(task.taskId);
+      });
+      this.pendingTasks.set(task.taskId, pending);
+
+      return Promise.resolve({ task });
+    }
+
     return withSpan(
       "mcp.callTool",
       async () => {
         try {
-          const result = await executeTool(toolName, args, context);
+          const result = await executeTool(toolName, args, toolContext);
           return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
             isError: false,
@@ -447,6 +556,75 @@ export class MCPServer {
     });
   }
 
+  private setLogLevel(
+    params: JSONRPCParams | undefined,
+  ): Promise<Record<string, unknown>> {
+    const p = toParamsRecord(params);
+    const level = p.level as string;
+    if (
+      !MCPServer.LOG_LEVELS.includes(
+        level as typeof MCPServer.LOG_LEVELS[number],
+      )
+    ) {
+      return Promise.reject({
+        code: -32602,
+        message: `Invalid log level: ${level}. Valid levels: ${MCPServer.LOG_LEVELS.join(", ")}`,
+      });
+    }
+    this.logLevel = level as typeof MCPServer.LOG_LEVELS[number];
+    return Promise.resolve({});
+  }
+
+  private getTask(params: JSONRPCParams | undefined): Promise<Record<string, unknown>> {
+    const { taskId } = toParamsRecord(params);
+    if (!taskId) {
+      throw new JsonRpcError(-32602, "taskId is required");
+    }
+    const task = this.taskStore.get(String(taskId));
+    if (!task) {
+      throw new JsonRpcError(-32602, `Task not found: ${taskId}`);
+    }
+    return Promise.resolve({ ...task });
+  }
+
+  private getTaskResult(params: JSONRPCParams | undefined): Promise<Record<string, unknown>> {
+    const { taskId } = toParamsRecord(params);
+    if (!taskId) {
+      throw new JsonRpcError(-32602, "taskId is required");
+    }
+    const task = this.taskStore.get(String(taskId));
+    if (!task) {
+      throw new JsonRpcError(-32602, `Task not found: ${taskId}`);
+    }
+    const result = this.taskStore.getResult(String(taskId));
+    if (result === undefined) {
+      throw new JsonRpcError(-32002, "Task result is not yet available");
+    }
+    return Promise.resolve(result as Record<string, unknown>);
+  }
+
+  private cancelTask(params: JSONRPCParams | undefined): Promise<Record<string, unknown>> {
+    const { taskId } = toParamsRecord(params);
+    if (!taskId) {
+      throw new JsonRpcError(-32602, "taskId is required");
+    }
+    const cancelled = this.taskStore.cancel(String(taskId));
+    if (!cancelled) {
+      throw new JsonRpcError(-32002, `Cannot cancel task: ${taskId}`);
+    }
+    const task = this.taskStore.get(String(taskId));
+    return Promise.resolve({ ...task });
+  }
+
+  private listTasks(): Promise<Record<string, unknown>> {
+    return Promise.resolve({ tasks: this.taskStore.list() });
+  }
+
+  /** Wait for all background task executions to settle. Useful in tests. */
+  waitForPendingTasks(): Promise<void> {
+    return Promise.all(this.pendingTasks.values()).then(() => {});
+  }
+
   createHTTPHandler(): (request: dntShim.Request) => Promise<dntShim.Response> {
     return async (request: dntShim.Request) => {
       const requestOrigin = request.headers.get("Origin");
@@ -623,6 +801,11 @@ export class MCPServer {
       };
     }
     await syncIntegrationConfig(apiBaseUrl, apiToken, integrationConfigs);
+    try {
+      this.notifyToolsChanged();
+    } catch (_) {
+      // Notification delivery failure is non-fatal — sync already succeeded
+    }
     return true;
   }
 }