feat(studio): create Fabric agents by uploading their directory [ASTD-448]

web/packages/common/src/api/common/utils.ts

@@ -49,6 +49,12 @@ export const isValidationErrorArray = (detail: unknown): detail is ValidationErr
 export const isVersionConflictError = (error: unknown): boolean =>
   error instanceof AxiosError && error.response?.status === 409;
 
+/** A 404 from the platform API. */
+export const isNotFoundError = (error: unknown): boolean => {
+  const candidate = error as { response?: { status?: number }; status?: number };
+  return candidate?.response?.status === 404 || candidate?.status === 404;
+};
+
 /**
  * Extracts a user-friendly error message from an error object.
  * Handles both ValidationError arrays and simple string errors from the backend.

web/packages/studio/src/api/agents/useCreateAgentFromUpload.test.ts

@@ -0,0 +1,185 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { agentsCreateAgent, agentsGetAgent } from '@nemo/sdk/generated/agents/api';
+import {
+  filesCreateFileset,
+  filesDeleteFileset,
+  filesRetrieveFileset,
+  filesUploadFile,
+} from '@nemo/sdk/generated/platform/api';
+import {
+  AgentSpecFilesetConflictError,
+  AgentSpecFilesetOrphanError,
+  createAgentFromUpload,
+} from '@studio/api/agents/useCreateAgentFromUpload';
+import type { UploadAgentEntry } from '@studio/routes/agents/AgentsListRoute/UploadAgentModal/type';
+
+vi.mock('@nemo/sdk/generated/agents/api', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@nemo/sdk/generated/agents/api')>()),
+  agentsCreateAgent: vi.fn(),
+  agentsGetAgent: vi.fn(),
+}));
+
+vi.mock('@nemo/sdk/generated/platform/api', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@nemo/sdk/generated/platform/api')>()),
+  filesRetrieveFileset: vi.fn(),
+  filesCreateFileset: vi.fn(),
+  filesUploadFile: vi.fn(),
+  filesDeleteFileset: vi.fn(),
+}));
+
+const FABRIC_YAML = 'config_format: nemo-agents-spec-v1\nname: calc\ndescription: Adds numbers\n';
+
+const entryFor = (path: string, contents: string): UploadAgentEntry => ({
+  path,
+  file: new File([contents], path.split('/').pop() ?? path),
+});
+
+const entries = (): UploadAgentEntry[] => [
+  entryFor('agent.yaml', FABRIC_YAML),
+  entryFor('mcps/calculator.py', 'print(1)\n'),
+];
+
+const params = () => ({ workspace: 'ws', name: 'calc', entries: entries() });
+
+const httpError = (status: number): Error =>
+  Object.assign(new Error(`HTTP ${status}`), { response: { status } });
+
+const filesetMissing = () => vi.mocked(filesRetrieveFileset).mockRejectedValue(httpError(404));
+const filesetExists = () =>
+  vi.mocked(filesRetrieveFileset).mockResolvedValue({ name: 'calc-spec' } as never);
+const agentMissing = () => vi.mocked(agentsGetAgent).mockRejectedValue(httpError(404));
+const agentExists = () => vi.mocked(agentsGetAgent).mockResolvedValue({ name: 'calc' } as never);
+
+beforeEach(() => {
+  filesetMissing();
+  agentMissing();
+  vi.mocked(filesCreateFileset).mockResolvedValue({ name: 'calc-spec' } as never);
+  vi.mocked(filesUploadFile).mockResolvedValue({ path: 'agent.yaml' } as never);
+  vi.mocked(filesDeleteFileset).mockResolvedValue(undefined as never);
+  vi.mocked(agentsCreateAgent).mockResolvedValue({ name: 'calc' } as never);
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('createAgentFromUpload', () => {
+  it('uploads every file before creating the agent', async () => {
+    const order: string[] = [];
+    vi.mocked(filesUploadFile).mockImplementation(async (_ws, _fs, path) => {
+      order.push(`upload:${path}`);
+      return { path } as never;
+    });
+    vi.mocked(agentsCreateAgent).mockImplementation(async () => {
+      order.push('createAgent');
+      return { name: 'calc' } as never;
+    });
+
+    await createAgentFromUpload(params());
+
+    // Uploads run concurrently, so only their completion before the create is guaranteed.
+    expect(order.at(-1)).toBe('createAgent');
+    expect(order.slice(0, -1).sort()).toEqual(['upload:agent.yaml', 'upload:mcps/calculator.py']);
+    expect(agentsCreateAgent).toHaveBeenCalledWith('ws', {
+      name: 'calc',
+      description: 'Adds numbers',
+      config: expect.objectContaining({ config_format: 'nemo-agents-spec-v1' }),
+      config_format: 'nemo-agents-spec-v1',
+    });
+  });
+
+  it('refuses a fileset that an existing agent owns', async () => {
+    filesetExists();
+    agentExists();
+
+    await expect(createAgentFromUpload(params())).rejects.toThrow(AgentSpecFilesetConflictError);
+    expect(filesCreateFileset).not.toHaveBeenCalled();
+    expect(filesDeleteFileset).not.toHaveBeenCalled();
+  });
+
+  it('asks before replacing a fileset that no agent owns', async () => {
+    filesetExists();
+
+    await expect(createAgentFromUpload(params())).rejects.toThrow(AgentSpecFilesetOrphanError);
+    expect(filesDeleteFileset).not.toHaveBeenCalled();
+    expect(agentsCreateAgent).not.toHaveBeenCalled();
+  });
+
+  it('replaces an orphaned fileset once confirmed', async () => {
+    filesetExists();
+
+    await createAgentFromUpload({ ...params(), replaceOrphanedFileset: true });
+
+    expect(filesDeleteFileset).toHaveBeenCalledWith('ws', 'calc-spec');
+    expect(filesCreateFileset).toHaveBeenCalledWith(
+      'ws',
+      expect.objectContaining({ name: 'calc-spec' })
+    );
+    expect(agentsCreateAgent).toHaveBeenCalled();
+  });
+
+  it('does not replace an owned fileset even when confirmed', async () => {
+    filesetExists();
+    agentExists();
+
+    await expect(
+      createAgentFromUpload({ ...params(), replaceOrphanedFileset: true })
+    ).rejects.toThrow(AgentSpecFilesetConflictError);
+    expect(filesDeleteFileset).not.toHaveBeenCalled();
+  });
+
+  it('deletes the fileset when an upload fails', async () => {
+    vi.mocked(filesUploadFile)
+      .mockResolvedValueOnce({ path: 'agent.yaml' } as never)
+      .mockRejectedValueOnce(new Error('network down'));
+
+    await expect(createAgentFromUpload(params())).rejects.toThrow('network down');
+    expect(filesDeleteFileset).toHaveBeenCalledWith('ws', 'calc-spec');
+  });
+
+  it('deletes the fileset when creating the agent fails', async () => {
+    vi.mocked(agentsCreateAgent).mockRejectedValue(new Error('409 conflict'));
+
+    await expect(createAgentFromUpload(params())).rejects.toThrow('409 conflict');
+    expect(filesDeleteFileset).toHaveBeenCalledWith('ws', 'calc-spec');
+  });
+
+  it('does not delete a fileset it failed to create', async () => {
+    vi.mocked(filesCreateFileset).mockRejectedValue(httpError(409));
+
+    await expect(createAgentFromUpload(params())).rejects.toThrow('HTTP 409');
+    expect(filesDeleteFileset).not.toHaveBeenCalled();
+  });
+
+  it('does not claim the name when the fileset lookup fails for any reason but absence', async () => {
+    vi.mocked(filesRetrieveFileset).mockRejectedValue(httpError(503));
+
+    await expect(createAgentFromUpload(params())).rejects.toThrow('HTTP 503');
+    expect(filesCreateFileset).not.toHaveBeenCalled();
+    expect(filesDeleteFileset).not.toHaveBeenCalled();
+  });
+
+  it('does not replace a fileset when the agent lookup fails for any reason but absence', async () => {
+    filesetExists();
+    vi.mocked(agentsGetAgent).mockRejectedValue(httpError(503));
+
+    await expect(
+      createAgentFromUpload({ ...params(), replaceOrphanedFileset: true })
+    ).rejects.toThrow('HTTP 503');
+    expect(filesDeleteFileset).not.toHaveBeenCalled();
+    expect(agentsCreateAgent).not.toHaveBeenCalled();
+  });
+
+  it('rejects a non-Fabric config before touching anything', async () => {
+    const natEntries = [entryFor('agent.yaml', 'config_format: nat-workflow-v1\n')];
+
+    await expect(
+      createAgentFromUpload({ workspace: 'ws', name: 'calc', entries: natEntries })
+    ).rejects.toThrow(/config_format/);
+    expect(filesRetrieveFileset).not.toHaveBeenCalled();
+    expect(filesCreateFileset).not.toHaveBeenCalled();
+    expect(agentsCreateAgent).not.toHaveBeenCalled();
+  });
+});

web/packages/studio/src/api/agents/useCreateAgentFromUpload.ts

@@ -0,0 +1,153 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { isNotFoundError } from '@nemo/common/src/api/common/utils';
+import { agentsCreateAgent, agentsGetAgent } from '@nemo/sdk/generated/agents/api';
+import type { Agent } from '@nemo/sdk/generated/agents/schema/Agent';
+import {
+  filesCreateFileset,
+  filesDeleteFileset,
+  filesRetrieveFileset,
+  filesUploadFile,
+} from '@nemo/sdk/generated/platform/api';
+import {
+  AGENT_CONFIG_FILENAME,
+  FABRIC_CONFIG_FORMAT,
+} from '@studio/routes/agents/AgentsListRoute/UploadAgentModal/const';
+import type { UploadAgentEntry } from '@studio/routes/agents/AgentsListRoute/UploadAgentModal/type';
+import {
+  agentSpecFilesetName,
+  parseAgentConfig,
+} from '@studio/routes/agents/AgentsListRoute/UploadAgentModal/utils';
+import { UseMutationOptions, useMutation } from '@tanstack/react-query';
+
+export interface CreateAgentFromUploadParams {
+  workspace: string;
+  name: string;
+  entries: UploadAgentEntry[];
+  replaceOrphanedFileset?: boolean;
+}
+
+/** An agent of this name already exists; its spec fileset is not ours to take. */
+export class AgentSpecFilesetConflictError extends Error {
+  constructor(public readonly filesetName: string) {
+    super(
+      `An agent named "${filesetName.replace(/-spec$/, '')}" already owns the fileset "${filesetName}". Choose a different name.`
+    );
+  }
+}
+
+/** A spec fileset with no agent behind it — an abandoned upload, or an agent since deleted. */
+export class AgentSpecFilesetOrphanError extends Error {
+  constructor(public readonly filesetName: string) {
+    super(
+      `A fileset named "${filesetName}" already exists, but no agent owns it — an upload that did not finish, or an agent that was deleted, since deleting an agent leaves its fileset behind. Replacing it discards its current contents.`
+    );
+  }
+}
+
+// Files first: the fileset reserves the name, and a create-time validation that needs a
+// base_dir can only see files that are already uploaded. Creating it outside the try keeps
+// rollback to what this call created.
+export const createAgentFromUpload = async ({
+  workspace,
+  name,
+  entries,
+  replaceOrphanedFileset = false,
+}: CreateAgentFromUploadParams): Promise<Agent> => {
+  const filesetName = agentSpecFilesetName(name);
+
+  const configEntry = entries.find((entry) => entry.path === AGENT_CONFIG_FILENAME);
+  if (!configEntry) throw new Error(`No ${AGENT_CONFIG_FILENAME} in the selected directory.`);
+  const config = parseAgentConfig(await configEntry.file.text());
+
+  await claimFileset(workspace, name, filesetName, replaceOrphanedFileset);
+
+  await filesCreateFileset(workspace, {
+    name: filesetName,
+    description: `Agent spec for ${name}`,
+  });
+
+  try {
+    await uploadEntries(workspace, filesetName, entries);
+
+    return await agentsCreateAgent(workspace, {
+      name,
+      description: typeof config.description === 'string' ? config.description : '',
+      config,
+      config_format: FABRIC_CONFIG_FORMAT,
+    });
+  } catch (error) {
+    await rollback(workspace, filesetName);
+    throw error;
+  }
+};
+
+const claimFileset = async (
+  workspace: string,
+  agentName: string,
+  filesetName: string,
+  replaceOrphanedFileset: boolean
+): Promise<void> => {
+  try {
+    await filesRetrieveFileset(workspace, filesetName);
+  } catch (error) {
+    // Only a 404 means the name is free; anything else leaves ownership unknown.
+    if (!isNotFoundError(error)) throw error;
+    return;
+  }
+
+  if (await agentExists(workspace, agentName)) {
+    throw new AgentSpecFilesetConflictError(filesetName);
+  }
+  if (!replaceOrphanedFileset) {
+    throw new AgentSpecFilesetOrphanError(filesetName);
+  }
+
+  await filesDeleteFileset(workspace, filesetName);
+};
+
+const agentExists = async (workspace: string, agentName: string): Promise<boolean> => {
+  try {
+    await agentsGetAgent(workspace, agentName);
+    return true;
+  } catch (error) {
+    if (!isNotFoundError(error)) throw error;
+    return false;
+  }
+};
+
+// One request per file, so a 500-file agent is 500 round trips. Run a bounded number at
+// once: unbounded Promise.all would queue them all against the browser's per-host limit
+// and lose the first error behind hundreds of in-flight requests.
+const UPLOAD_CONCURRENCY = 6;
+
+const uploadEntries = async (
+  workspace: string,
+  filesetName: string,
+  entries: UploadAgentEntry[]
+): Promise<void> => {
+  const queue = [...entries];
+  const worker = async (): Promise<void> => {
+    for (let entry = queue.shift(); entry; entry = queue.shift()) {
+      const blob = new Blob([await entry.file.arrayBuffer()], { type: 'application/octet-stream' });
+      await filesUploadFile(workspace, filesetName, entry.path, blob);
+    }
+  };
+
+  await Promise.all(
+    Array.from({ length: Math.min(UPLOAD_CONCURRENCY, entries.length) }, () => worker())
+  );
+};
+
+const rollback = async (workspace: string, filesetName: string): Promise<void> => {
+  await filesDeleteFileset(workspace, filesetName).catch(() => undefined);
+};
+
+export type UseCreateAgentFromUploadOptions = Omit<
+  UseMutationOptions<Agent, Error, CreateAgentFromUploadParams>,
+  'mutationFn'
+>;
+
+export const useCreateAgentFromUpload = (options?: UseCreateAgentFromUploadOptions) =>
+  useMutation({ ...options, mutationFn: createAgentFromUpload });

web/packages/studio/src/routes/agents/AgentsListRoute/UploadAgentModal/const.ts

@@ -0,0 +1,45 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { z } from 'zod';
+
+export const AGENT_CONFIG_FILENAME = 'agent.yaml';
+
+export const FABRIC_CONFIG_FORMAT = 'nemo-agents-spec-v1';
+
+// Container staging skips this file, so its bytes never reach a deployment.
+export const AGENT_SPEC_FILENAME = 'AGENT-SPEC.md';
+
+// Mirrors MAX_AGENT_SPEC_STAGED_BYTES / _FILES; the platform only enforces them at deploy.
+export const MAX_AGENT_SPEC_BYTES = 900_000;
+export const MAX_AGENT_SPEC_FILES = 500;
+
+// A directory picker hands over every descendant, so a mistaken pick can arrive with
+// hundreds of thousands of entries. Reject on the raw count before mapping, filtering or
+// sorting any of them — the ignore list cannot be applied without touching every entry.
+export const MAX_PICKED_FILES = 1_000;
+
+export const IGNORED_DIRECTORIES = new Set([
+  '__pycache__',
+  '.git',
+  '.venv',
+  'venv',
+  'node_modules',
+  '.mypy_cache',
+  '.pytest_cache',
+  '.ruff_cache',
+  '.idea',
+  '.vscode',
+]);
+
+export const IGNORED_FILENAMES = new Set(['.DS_Store', 'Thumbs.db']);
+
+export const IGNORED_EXTENSIONS = ['.pyc', '.pyo', '.pyd', '.so', '.dylib', '.dll'];
+
+export const uploadAgentFormSchema = z.object({
+  name: z
+    .string()
+    .trim()
+    .min(1, 'Name is required')
+    .regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, 'Use lowercase letters, numbers, and hyphens'),
+});