veryfront 0.1.516 → 0.1.518

package/src/src/agent/runtime/load-skill-tool.ts

@@ -0,0 +1,239 @@
+import { defineSchema } from "../../schemas/index.js";
+import type { InferSchema } from "../../extensions/schema/index.js";
+import { tool } from "../../tool/index.js";
+import type { Tool } from "../../tool/types.js";
+import {
+  LOAD_SKILL_CONTINUE_SAME_TURN,
+  LOAD_SKILL_DELEGATION_THRESHOLD,
+  LOAD_SKILL_OVERRIDE_FORWARDING,
+  LOAD_SKILL_ROOT_OWNERSHIP,
+  LOAD_SKILL_TOOL_INTERSECTION,
+  LOAD_SKILL_USE_ALLOWED_TOOLS,
+} from "../conversation/delegation-policy.js";
+import {
+  listRuntimeBuiltinSkillReferences,
+  readRuntimeBuiltinSkill,
+  readRuntimeBuiltinSkillReferenceFile,
+} from "./builtin-skill-files.js";
+import type {
+  RuntimeLoadedProjectSkill,
+  RuntimeProjectSkillContext,
+  RuntimeProjectSkillLoader,
+} from "./project-skill-loader.js";
+import {
+  buildRuntimeLoadedSkillResponse,
+  normalizeRuntimeSkillReferencePath,
+  type RuntimeLoadedSkillResponse,
+  type RuntimeLoadedSkillResponseMessages,
+  type RuntimeSkillMetadataLogger,
+} from "./skill-metadata.js";
+
+export const RUNTIME_LOAD_SKILL_CONTINUATION_NOTE =
+  `IMPORTANT: load_skill only loads instructions. It does not perform the task or finish the turn. ${LOAD_SKILL_CONTINUE_SAME_TURN} ${LOAD_SKILL_ROOT_OWNERSHIP} ${LOAD_SKILL_USE_ALLOWED_TOOLS} ${LOAD_SKILL_DELEGATION_THRESHOLD} ${LOAD_SKILL_OVERRIDE_FORWARDING} ${LOAD_SKILL_TOOL_INTERSECTION}`;
+
+export const RUNTIME_LOAD_SKILL_DESCRIPTION =
+  `Load the full instructions for a skill. Use this when you need detailed guidance for a specific task type. If the skill specifies allowed-tools, you MUST only use those tools while following this skill. load_skill does not perform the task by itself. ${LOAD_SKILL_CONTINUE_SAME_TURN} ${LOAD_SKILL_ROOT_OWNERSHIP} ${LOAD_SKILL_USE_ALLOWED_TOOLS} ${LOAD_SKILL_DELEGATION_THRESHOLD} Use the optional \`file\` parameter to load a specific reference file from the skill.`;
+
+const DEFAULT_RUNTIME_LOAD_SKILL_RESPONSE_MESSAGES: RuntimeLoadedSkillResponseMessages = {
+  allowedToolsNote:
+    "IMPORTANT: While following this skill, you MUST only use the tools listed in allowedTools.",
+  noCurrentRunToolsNote:
+    "IMPORTANT: While following this skill, no direct-execution tools from this skill are available in the current run. allowedTools is intentionally empty; do not attempt direct tool execution in this run.",
+  unavailableCurrentRunToolsDelegationNote:
+    "IMPORTANT: Some tools required by this skill are not available in the current run. Use invoke_agent for the isolated work and pass delegationTools as the child tools allowlist.",
+  overrideNote: LOAD_SKILL_OVERRIDE_FORWARDING,
+  referenceNote: "Use load_skill with the `file` parameter to load any of these reference files.",
+};
+
+export type RuntimeLoadSkillToolContext = RuntimeProjectSkillContext & {
+  availableSkillIds?: readonly string[];
+  availableToolNames?: readonly string[];
+};
+
+export type RuntimeLoadSkillBuiltinStore = {
+  readSkill: (skillsDir: string, skillId: string) => string | null;
+  readReferenceFile: (skillsDir: string, skillId: string, normalizedFile: string) => string | null;
+  listReferences: (skillsDir: string, skillId: string) => string[];
+};
+
+export type RuntimeLoadSkillToolMessages = Partial<RuntimeLoadedSkillResponseMessages>;
+
+export type RuntimeLoadSkillToolOptions = {
+  context: RuntimeLoadSkillToolContext;
+  skillsDir: string;
+  projectSkillLoader: RuntimeProjectSkillLoader;
+  builtinSkillIds?: readonly string[];
+  builtinStore?: RuntimeLoadSkillBuiltinStore;
+  description?: string;
+  nextStep?: string;
+  messages?: RuntimeLoadSkillToolMessages;
+  logger?: RuntimeSkillMetadataLogger;
+};
+
+export const getRuntimeLoadSkillToolInputSchema = defineSchema((v) =>
+  v.object({
+    skillId: v.string()
+      .regex(/^[a-zA-Z0-9_-]+$/, 'skillId must contain only letters, numbers, "_" or "-"')
+      .describe('The skill ID to load (e.g., "react-components", "api-design")'),
+    file: v.string().optional().describe(
+      'Optional reference file to load (e.g. "references/quickstart.md")',
+    ),
+  })
+);
+
+/** @deprecated Use getRuntimeLoadSkillToolInputSchema() */
+const runtimeLoadSkillToolInputSchema = getRuntimeLoadSkillToolInputSchema();
+
+export type RuntimeLoadSkillToolInput = InferSchema<
+  ReturnType<typeof getRuntimeLoadSkillToolInputSchema>
+>;
+
+export type RuntimeLoadSkillReferenceFileOutput = {
+  skillId: string;
+  file: string;
+  content: string;
+};
+
+export type RuntimeLoadSkillErrorOutput = {
+  error: string;
+};
+
+export type RuntimeLoadSkillToolOutput =
+  | RuntimeLoadedSkillResponse
+  | RuntimeLoadSkillReferenceFileOutput
+  | RuntimeLoadSkillErrorOutput;
+
+function getBuiltinStore(options: RuntimeLoadSkillToolOptions): RuntimeLoadSkillBuiltinStore {
+  return {
+    readSkill: options.builtinStore?.readSkill ?? readRuntimeBuiltinSkill,
+    readReferenceFile: options.builtinStore?.readReferenceFile ??
+      readRuntimeBuiltinSkillReferenceFile,
+    listReferences: options.builtinStore?.listReferences ?? listRuntimeBuiltinSkillReferences,
+  };
+}
+
+function getResponseMessages(
+  options: RuntimeLoadSkillToolOptions,
+): RuntimeLoadedSkillResponseMessages {
+  return {
+    allowedToolsNote: options.messages?.allowedToolsNote ??
+      DEFAULT_RUNTIME_LOAD_SKILL_RESPONSE_MESSAGES.allowedToolsNote,
+    noCurrentRunToolsNote: options.messages?.noCurrentRunToolsNote ??
+      DEFAULT_RUNTIME_LOAD_SKILL_RESPONSE_MESSAGES.noCurrentRunToolsNote,
+    unavailableCurrentRunToolsDelegationNote:
+      options.messages?.unavailableCurrentRunToolsDelegationNote ??
+        DEFAULT_RUNTIME_LOAD_SKILL_RESPONSE_MESSAGES.unavailableCurrentRunToolsDelegationNote,
+    overrideNote: options.messages?.overrideNote ??
+      DEFAULT_RUNTIME_LOAD_SKILL_RESPONSE_MESSAGES.overrideNote,
+    referenceNote: options.messages?.referenceNote ??
+      DEFAULT_RUNTIME_LOAD_SKILL_RESPONSE_MESSAGES.referenceNote,
+  };
+}
+
+function buildLoadedSkillResponse(input: {
+  options: RuntimeLoadSkillToolOptions;
+  skillId: string;
+  instructions: string;
+  references?: readonly string[];
+}): RuntimeLoadedSkillResponse {
+  return buildRuntimeLoadedSkillResponse({
+    skillId: input.skillId,
+    instructions: input.instructions,
+    nextStep: input.options.nextStep ?? RUNTIME_LOAD_SKILL_CONTINUATION_NOTE,
+    messages: getResponseMessages(input.options),
+    references: input.references,
+    availableToolNames: input.options.context.availableToolNames,
+    logger: input.options.logger,
+  });
+}
+
+function buildMissingSkillError(
+  options: RuntimeLoadSkillToolOptions,
+  skillId: string,
+): RuntimeLoadSkillErrorOutput {
+  const knownIds = new Set([
+    ...(options.context.availableSkillIds ?? []),
+    ...(options.builtinSkillIds ?? []),
+  ]);
+  const available = [...knownIds].sort().join(", ");
+  return {
+    error: `Skill not found: ${skillId}. Available skills: ${available}`,
+  };
+}
+
+async function loadRuntimeSkillReferenceFile(
+  options: RuntimeLoadSkillToolOptions,
+  skillId: string,
+  file: string,
+): Promise<RuntimeLoadSkillReferenceFileOutput | RuntimeLoadSkillErrorOutput> {
+  const normalizedFile = normalizeRuntimeSkillReferencePath(file);
+  if (!normalizedFile) {
+    return { error: `Invalid reference file path: ${file}` };
+  }
+
+  const projectFileContent = await options.projectSkillLoader.loadProjectSkillReference(
+    options.context,
+    skillId,
+    normalizedFile,
+  );
+  if (projectFileContent) {
+    return { skillId, file: normalizedFile, content: projectFileContent };
+  }
+
+  const localContent = getBuiltinStore(options).readReferenceFile(
+    options.skillsDir,
+    skillId,
+    normalizedFile,
+  );
+  if (localContent) {
+    return { skillId, file: normalizedFile, content: localContent };
+  }
+
+  return { error: `Reference file not found: ${skillId}/${normalizedFile}` };
+}
+
+async function loadRuntimeSkillBody(
+  options: RuntimeLoadSkillToolOptions,
+  skillId: string,
+): Promise<RuntimeLoadedProjectSkill | null> {
+  return await options.projectSkillLoader.loadProjectSkill(options.context, skillId);
+}
+
+export function createRuntimeLoadSkillTool(
+  options: RuntimeLoadSkillToolOptions,
+): Tool<RuntimeLoadSkillToolInput, RuntimeLoadSkillToolOutput> {
+  const builtinStore = getBuiltinStore(options);
+
+  return tool({
+    id: "load_skill",
+    description: options.description ?? RUNTIME_LOAD_SKILL_DESCRIPTION,
+    inputSchema: runtimeLoadSkillToolInputSchema,
+    execute: async ({ skillId, file }) => {
+      if (file) {
+        return await loadRuntimeSkillReferenceFile(options, skillId, file);
+      }
+
+      const projectSkill = await loadRuntimeSkillBody(options, skillId);
+      if (projectSkill) {
+        return buildLoadedSkillResponse({
+          options,
+          skillId,
+          instructions: projectSkill.instructions,
+          references: projectSkill.references,
+        });
+      }
+
+      const localContent = builtinStore.readSkill(options.skillsDir, skillId);
+      if (localContent) {
+        return buildLoadedSkillResponse({
+          options,
+          skillId,
+          instructions: localContent,
+          references: builtinStore.listReferences(options.skillsDir, skillId),
+        });
+      }
+
+      return buildMissingSkillError(options, skillId);
+    },
+  });
+}

package/src/src/agent/runtime/message-file-url-refresh.ts

@@ -0,0 +1,120 @@
+import type { ChatUiMessage, FileUIPartWithUpload } from "../../chat/types.js";
+
+export type RuntimeFileUrlResolverInput = {
+  uploadId: string;
+  part: FileUIPartWithUpload;
+  message: ChatUiMessage;
+};
+
+export type RuntimeFileUrlResolver = (
+  input: RuntimeFileUrlResolverInput,
+) => Promise<string | undefined>;
+
+export async function resolveRuntimeMessageFileUrls(
+  messages: readonly ChatUiMessage[],
+  resolveFileUrl: RuntimeFileUrlResolver,
+): Promise<ChatUiMessage[]> {
+  const urlByUploadId = new Map<string, Promise<string | undefined>>();
+
+  return Promise.all(
+    messages.map(async (message) => {
+      if (!message.parts.some((part) => getUploadId(part))) {
+        return message;
+      }
+
+      const parts = await Promise.all(
+        message.parts.map(async (part) => {
+          const uploadId = getUploadId(part);
+          if (!uploadId) return part;
+
+          let urlPromise = urlByUploadId.get(uploadId);
+          if (!urlPromise) {
+            urlPromise = resolveFileUrl({
+              uploadId,
+              part: toResolverPart(part, uploadId),
+              message,
+            });
+            urlByUploadId.set(uploadId, urlPromise);
+          }
+
+          const signedUrl = await urlPromise;
+          if (!signedUrl) return normalizeUploadedFilePart(part, uploadId);
+
+          return {
+            ...normalizeUploadedFilePart(part, uploadId),
+            url: signedUrl,
+          };
+        }),
+      );
+
+      return { ...message, parts };
+    }),
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function getStringField(part: unknown, key: string): string | undefined {
+  if (!isRecord(part)) return undefined;
+
+  const value = part[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function getUploadId(part: unknown): string | undefined {
+  if (!isRecord(part) || (part.type !== "file" && part.type !== "image")) {
+    return undefined;
+  }
+
+  return getStringField(part, "uploadId") ?? getStringField(part, "upload_id");
+}
+
+function getMediaType(part: unknown): string | undefined {
+  return getStringField(part, "mediaType") ?? getStringField(part, "media_type");
+}
+
+function normalizeUploadedFilePart(
+  part: ChatUiMessage["parts"][number],
+  uploadId: string,
+): ChatUiMessage["parts"][number] {
+  if (!isRecord(part)) return part;
+
+  const partRecord: Record<string, unknown> = part;
+  const partType = partRecord.type;
+  if (partType !== "file" && partType !== "image") return part;
+
+  const mediaType = getMediaType(part);
+  const url = getStringField(part, "url");
+  if (!mediaType || !url) return part;
+
+  const filename = getStringField(part, "filename");
+  const uploadPath = getStringField(part, "uploadPath") ?? getStringField(part, "upload_path");
+
+  return {
+    type: partType === "image" ? "image" : "file",
+    mediaType,
+    url,
+    ...(filename ? { filename } : {}),
+    uploadId,
+    ...(uploadPath ? { uploadPath } : {}),
+  } as ChatUiMessage["parts"][number];
+}
+
+function toResolverPart(
+  part: ChatUiMessage["parts"][number],
+  uploadId: string,
+): FileUIPartWithUpload {
+  const normalized = normalizeUploadedFilePart(part, uploadId);
+  if (isRecord(normalized) && normalized.type === "file") {
+    return normalized as FileUIPartWithUpload;
+  }
+
+  return {
+    type: "file",
+    mediaType: getMediaType(part) ?? "application/octet-stream",
+    url: getStringField(part, "url") ?? "",
+    uploadId,
+  };
+}

package/src/src/agent/runtime/message-preparation.ts

@@ -0,0 +1,58 @@
+import { prepareProviderModelMessagesFromUiMessages } from "../../chat/message-prep.js";
+import type { ChatUiMessage } from "../../chat/types.js";
+import {
+  type AgentRuntimeMessage,
+  convertProviderMessagesToAgentRuntimeMessages,
+} from "../agent-runtime-message-adapter.js";
+import {
+  resolveRuntimeMessageFileUrls,
+  type RuntimeFileUrlResolver,
+} from "./message-file-url-refresh.js";
+
+const DEFAULT_EMPTY_CONVERSATION_PROMPT =
+  "Please provide 3-4 specific suggestions for what I could build or improve based on the current project context.";
+
+export type PrepareAgentRuntimeMessagesFromUiMessagesOptions = {
+  messages: readonly ChatUiMessage[];
+  emptyConversationPrompt?: string;
+  resolveFileUrl?: RuntimeFileUrlResolver;
+};
+
+export async function prepareAgentRuntimeMessagesFromUiMessages(
+  options: PrepareAgentRuntimeMessagesFromUiMessagesOptions,
+): Promise<AgentRuntimeMessage[]> {
+  if (isEmptyConversation(options.messages)) {
+    return convertProviderMessagesToAgentRuntimeMessages([
+      {
+        role: "user",
+        content: options.emptyConversationPrompt ?? DEFAULT_EMPTY_CONVERSATION_PROMPT,
+      },
+    ]);
+  }
+
+  const refreshedMessages = options.resolveFileUrl
+    ? await resolveRuntimeMessageFileUrls(options.messages, options.resolveFileUrl)
+    : [...options.messages];
+
+  return convertProviderMessagesToAgentRuntimeMessages(
+    prepareProviderModelMessagesFromUiMessages(refreshedMessages),
+  );
+}
+
+function isEmptyConversation(messages: readonly ChatUiMessage[]): boolean {
+  if (messages.length === 0) return true;
+
+  if (messages.length === 1 && messages[0]?.role === "user") {
+    const parts = messages[0].parts;
+    if (parts.length === 0) return true;
+
+    return parts.every((part) => {
+      if (part.type === "text") {
+        return !part.text || part.text.trim() === "";
+      }
+      return false;
+    });
+  }
+
+  return false;
+}

package/src/src/agent/runtime/project-files-client.ts

@@ -0,0 +1,256 @@
+import { defineSchema } from "../../schemas/index.js";
+import type { InferSchema } from "../../extensions/schema/index.js";
+
+const DEFAULT_PROJECT_FILES_TIMEOUT_MS = 15_000;
+const DEFAULT_PROJECT_FILES_PAGE_LIMIT = 100;
+
+export const getRuntimeProjectFileSchema = defineSchema((v) =>
+  v.object({
+    path: v.string(),
+    content: v.string(),
+  })
+);
+
+export const getRuntimeProjectFileListItemSchema = defineSchema((v) =>
+  v.object({
+    path: v.string(),
+  })
+);
+
+const getRuntimeProjectFileListRestResponseSchema = defineSchema((v) =>
+  v.object({
+    data: v.array(getRuntimeProjectFileListItemSchema()),
+    page_info: v.object({
+      next: v.string().nullable(),
+    }),
+  })
+);
+
+const getApiErrorBodySchema = defineSchema((v) =>
+  v.object({
+    detail: v.string().optional(),
+    message: v.string().optional(),
+    error: v.string().optional(),
+  }).passthrough()
+);
+
+/** @deprecated Use getRuntimeProjectFileSchema() */
+export const runtimeProjectFileSchema = getRuntimeProjectFileSchema();
+/** @deprecated Use getRuntimeProjectFileListItemSchema() */
+export const runtimeProjectFileListItemSchema = getRuntimeProjectFileListItemSchema();
+
+export type RuntimeProjectFile = InferSchema<ReturnType<typeof getRuntimeProjectFileSchema>>;
+export type RuntimeProjectFileListItem = InferSchema<
+  ReturnType<typeof getRuntimeProjectFileListItemSchema>
+>;
+
+export type RuntimeProjectFilesApiOptions = {
+  projectId: string;
+  authToken: string;
+  branchId?: string | null;
+};
+
+export type RuntimeGetProjectFileOptions = RuntimeProjectFilesApiOptions & {
+  path: string;
+};
+
+export type RuntimeProjectFilesFetch = (url: string, init: RequestInit) => Promise<Response>;
+
+export type RuntimeProjectFilesTrace = <T>(name: string, fn: () => Promise<T>) => Promise<T>;
+
+export type RuntimeProjectFilesClientOptions = {
+  apiUrl: string | URL;
+  fetch?: RuntimeProjectFilesFetch;
+  timeoutMs?: number;
+  pageLimit?: number;
+  trace?: RuntimeProjectFilesTrace;
+  createAccessDeniedError?: (statusCode: number, message: string) => Error;
+};
+
+export type RuntimeProjectFilesClient = {
+  getProjectFile: (options: RuntimeGetProjectFileOptions) => Promise<RuntimeProjectFile | null>;
+  getProjectFiles: (
+    options: RuntimeProjectFilesApiOptions,
+  ) => Promise<RuntimeProjectFileListItem[]>;
+};
+
+export class RuntimeProjectFilesApiAuthError extends Error {
+  readonly statusCode: number;
+  readonly errorCode: string;
+
+  constructor(statusCode: number, message: string) {
+    super(message);
+    this.name = "RuntimeProjectFilesApiAuthError";
+    this.statusCode = statusCode;
+    this.errorCode = statusCode === 401 ? "UNAUTHENTICATED" : "FORBIDDEN";
+  }
+}
+
+export function createRuntimeProjectFilesClient(
+  options: RuntimeProjectFilesClientOptions,
+): RuntimeProjectFilesClient {
+  return {
+    getProjectFile: (input) => getRuntimeProjectFile({ ...options, ...input }),
+    getProjectFiles: (input) => getRuntimeProjectFiles({ ...options, ...input }),
+  };
+}
+
+export async function getRuntimeProjectFile(
+  options: RuntimeProjectFilesClientOptions & RuntimeGetProjectFileOptions,
+): Promise<RuntimeProjectFile | null> {
+  return traceProjectFilesRequest(options, "runtimeProjectFiles.getProjectFile", async () => {
+    const url = createRuntimeProjectFileUrl({
+      ...options,
+      fields: "(path,content)",
+    });
+    const response = await fetchRuntimeProjectFilesRestResponse(url, options);
+
+    if (response.status === 404) {
+      return null;
+    }
+
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch file ${options.path} for project ${options.projectId}: ${await readApiErrorMessage(
+          response,
+        )}`,
+      );
+    }
+
+    const parsed = getRuntimeProjectFileSchema().safeParse(await response.json());
+    if (!parsed.success) {
+      throw new Error(
+        `Failed to fetch file ${options.path} for project ${options.projectId}: invalid API response`,
+      );
+    }
+
+    return parsed.data;
+  });
+}
+
+export async function getRuntimeProjectFiles(
+  options: RuntimeProjectFilesClientOptions & RuntimeProjectFilesApiOptions,
+): Promise<RuntimeProjectFileListItem[]> {
+  return traceProjectFilesRequest(options, "runtimeProjectFiles.getProjectFiles", async () => {
+    const files: RuntimeProjectFileListItem[] = [];
+    let cursor: string | null = null;
+
+    do {
+      const url = createRuntimeProjectFileUrl({
+        ...options,
+        fields: "(path)",
+        cursor,
+      });
+      const response = await fetchRuntimeProjectFilesRestResponse(url, options);
+
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch files for project ${options.projectId}: ${await readApiErrorMessage(
+            response,
+          )}`,
+        );
+      }
+
+      const parsed = getRuntimeProjectFileListRestResponseSchema().safeParse(await response.json());
+      if (!parsed.success) {
+        throw new Error(
+          `Failed to fetch files for project ${options.projectId}: invalid API response`,
+        );
+      }
+
+      files.push(...parsed.data.data);
+      cursor = parsed.data.page_info.next;
+    } while (cursor);
+
+    return files;
+  });
+}
+
+function createRuntimeProjectFileUrl(input: {
+  apiUrl: string | URL;
+  projectId: string;
+  path?: string;
+  branchId?: string | null;
+  fields: string;
+  cursor?: string | null;
+  pageLimit?: number;
+}): URL {
+  const apiUrl = new URL(input.apiUrl);
+  const encodedProjectId = encodeURIComponent(input.projectId);
+  const pathname = input.path
+    ? `/projects/${encodedProjectId}/files/${encodeURIComponent(input.path)}`
+    : `/projects/${encodedProjectId}/files`;
+  const url = new URL(pathname, apiUrl.origin);
+
+  url.searchParams.set("fields", input.fields);
+  if (input.branchId) {
+    url.searchParams.set("branch", input.branchId);
+  }
+  if (input.cursor) {
+    url.searchParams.set("cursor", input.cursor);
+  }
+  if (!input.path) {
+    url.searchParams.set("limit", String(input.pageLimit ?? DEFAULT_PROJECT_FILES_PAGE_LIMIT));
+  }
+
+  return url;
+}
+
+async function fetchRuntimeProjectFilesRestResponse(
+  url: URL,
+  options: RuntimeProjectFilesClientOptions & { authToken: string },
+): Promise<Response> {
+  const response = await (options.fetch ?? fetch)(url.toString(), {
+    headers: {
+      Authorization: `Bearer ${options.authToken}`,
+    },
+    signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_PROJECT_FILES_TIMEOUT_MS),
+  });
+
+  if (response.status === 401 || response.status === 403) {
+    throw createProjectFilesAccessDeniedError(options, response.status);
+  }
+
+  return response;
+}
+
+function createProjectFilesAccessDeniedError(
+  options: RuntimeProjectFilesClientOptions,
+  statusCode: number,
+): Error {
+  const message = "Access denied to project files API";
+  return options.createAccessDeniedError?.(statusCode, message) ??
+    new RuntimeProjectFilesApiAuthError(statusCode, message);
+}
+
+async function readApiErrorMessage(response: Response): Promise<string> {
+  const body = await response.text().catch(() => "");
+  if (!body.trim()) {
+    return response.statusText || `HTTP ${response.status}`;
+  }
+
+  let parsedJson: { success: true; data: { detail?: string; message?: string; error?: string } } | {
+    success: false;
+  };
+  try {
+    const jsonValue = JSON.parse(body);
+    const result = getApiErrorBodySchema().safeParse(jsonValue);
+    parsedJson = result.success ? { success: true, data: result.data } : { success: false };
+  } catch {
+    parsedJson = { success: false };
+  }
+
+  if (parsedJson.success) {
+    return parsedJson.data.detail ?? parsedJson.data.message ?? parsedJson.data.error ?? body;
+  }
+
+  return body;
+}
+
+function traceProjectFilesRequest<T>(
+  options: RuntimeProjectFilesClientOptions,
+  name: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return options.trace ? options.trace(name, fn) : fn();
+}