@agent-native/dispatch 0.24.5 → 0.25.0

package/src/lib/agent-pack.spec.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+
+import { agentPackRoot, normalizeAgentPack } from "./agent-pack.js";
+
+describe("agent packs", () => {
+  it("normalizes a folder into a profile, references, and skills", () => {
+    const pack = normalizeAgentPack([
+      {
+        path: "researcher/agent.md",
+        content:
+          "---\nname: Researcher\ndescription: Finds evidence\ntools: WebSearch, Bash\n---\n\n# Role\nFind evidence.",
+      },
+      {
+        path: "researcher/context/glossary.md",
+        content: "# Glossary\n\nUse citizens instead of users.",
+      },
+      {
+        path: "researcher/skills/interviews/SKILL.md",
+        content:
+          "---\nname: Interviews\ndescription: Run interviews\n---\n\n# Workflow\nAsk open questions.",
+      },
+    ]);
+
+    expect(pack.profile.name).toBe("Researcher");
+    expect(pack.files).toEqual([
+      expect.objectContaining({
+        path: "context/glossary.md",
+        kind: "agent-file",
+      }),
+      expect.objectContaining({
+        path: "skills/interviews/SKILL.md",
+        kind: "skill",
+        name: "Interviews",
+      }),
+    ]);
+    expect(agentPackRoot(pack.profile.slug)).toBe("agents/researcher");
+  });
+
+  it("rejects private paths and oversized packs", () => {
+    expect(() =>
+      normalizeAgentPack([
+        { path: "agent.md", content: "# Agent" },
+        { path: ".env", content: "SECRET=not-for-import" },
+      ]),
+    ).toThrow("ignored or private");
+  });
+});

package/src/lib/agent-pack.ts

@@ -0,0 +1,226 @@
+import {
+  parseFrontmatter,
+  parseSkillMetadata,
+} from "@agent-native/core/resources/metadata";
+
+import {
+  buildSimpleAgentContent,
+  normalizeImportedAgent,
+  slugifyAgentName,
+  type ImportedAgentProfile,
+} from "./simple-agent-profile.js";
+
+export const AGENT_PACK_MAX_FILES = 80;
+export const AGENT_PACK_MAX_FILE_BYTES = 200_000;
+export const AGENT_PACK_MAX_TOTAL_BYTES = 2_000_000;
+
+const IGNORED_PACK_FILES = new Set([
+  ".ds_store",
+  ".git",
+  ".gitignore",
+  ".env",
+  ".env.local",
+  "node_modules",
+]);
+
+export interface AgentPackFileInput {
+  path: string;
+  content: string;
+}
+
+export interface NormalizedAgentPackFile {
+  path: string;
+  content: string;
+  name: string;
+  description?: string;
+  kind: "agent-file" | "skill";
+}
+
+export interface NormalizedAgentPack {
+  profile: ImportedAgentProfile;
+  profileFile: AgentPackFileInput;
+  files: NormalizedAgentPackFile[];
+  warnings: string[];
+  totalBytes: number;
+}
+
+function normalizePackPath(value: string): string {
+  const normalized = value
+    .replaceAll("\\", "/")
+    .split("/")
+    .filter((part) => part && part !== ".")
+    .join("/")
+    .trim();
+  if (!normalized || normalized.startsWith("/") || normalized.includes("..")) {
+    throw new Error(`Invalid agent pack path: ${value}`);
+  }
+  if (normalized.length > 240) {
+    throw new Error(`Agent pack path is too long: ${value}`);
+  }
+  return normalized;
+}
+
+function shouldIgnorePackPath(path: string): boolean {
+  return path
+    .split("/")
+    .some((part) => IGNORED_PACK_FILES.has(part.toLowerCase()));
+}
+
+function commonRoot(paths: string[]): string {
+  const firstParts = paths.map((path) => path.split("/")[0]);
+  if (
+    firstParts.length < 2 ||
+    !firstParts.every((part) => part === firstParts[0])
+  ) {
+    return "";
+  }
+  const root = firstParts[0];
+  if (
+    !root ||
+    ["skills", "context", "references", "files", "scripts"].includes(root)
+  ) {
+    return "";
+  }
+  return root;
+}
+
+function stripCommonRoot(files: AgentPackFileInput[]): AgentPackFileInput[] {
+  const root = commonRoot(files.map((file) => normalizePackPath(file.path)));
+  if (!root) return files;
+  return files.map((file) => ({
+    ...file,
+    path: normalizePackPath(file.path).slice(root.length + 1),
+  }));
+}
+
+function profileScore(file: AgentPackFileInput): number {
+  const name = file.path.split("/").pop()?.toLowerCase() || "";
+  if (["agent.md", "agent.json", "profile.md"].includes(name)) return 100;
+  if (["agents.md", "claude.md", "instructions.md"].includes(name)) return 90;
+  if (name.endsWith(".md")) return 50;
+  if (name.endsWith(".json")) return 40;
+  return 0;
+}
+
+function fileDescription(file: AgentPackFileInput): string | undefined {
+  const frontmatter = parseFrontmatter(file.content);
+  const description = frontmatter?.fields.find(
+    (field) => field.key === "description",
+  )?.value;
+  if (description?.trim()) return description.trim();
+  const heading = file.content.match(/^#\s+(.+)$/m)?.[1]?.trim();
+  return heading || undefined;
+}
+
+function fileName(path: string): string {
+  return path.split("/").pop() || path;
+}
+
+function isSkillFile(path: string): boolean {
+  return (
+    path.startsWith("skills/") &&
+    path.endsWith(".md") &&
+    (path.endsWith("/SKILL.md") || !path.slice("skills/".length).includes("/"))
+  );
+}
+
+export function normalizeAgentPack(
+  inputFiles: AgentPackFileInput[],
+): NormalizedAgentPack {
+  if (inputFiles.length === 0) {
+    throw new Error("Choose an agent file or folder with at least one file.");
+  }
+  if (inputFiles.length > AGENT_PACK_MAX_FILES) {
+    throw new Error(
+      `Agent packs can contain at most ${AGENT_PACK_MAX_FILES} files.`,
+    );
+  }
+
+  const files = stripCommonRoot(
+    inputFiles.map((file) => {
+      const path = normalizePackPath(file.path);
+      if (shouldIgnorePackPath(path)) {
+        throw new Error(
+          `Remove ignored or private path from the pack: ${path}`,
+        );
+      }
+      if (typeof file.content !== "string") {
+        throw new Error(`Agent pack file is not text: ${path}`);
+      }
+      const size = Buffer.byteLength(file.content, "utf8");
+      if (size > AGENT_PACK_MAX_FILE_BYTES) {
+        throw new Error(
+          `${path} is too large. Keep text files under ${Math.round(AGENT_PACK_MAX_FILE_BYTES / 1024)} KB.`,
+        );
+      }
+      return { path, content: file.content };
+    }),
+  );
+
+  const totalBytes = files.reduce(
+    (total, file) => total + Buffer.byteLength(file.content, "utf8"),
+    0,
+  );
+  if (totalBytes > AGENT_PACK_MAX_TOTAL_BYTES) {
+    throw new Error(
+      `Agent packs can contain at most ${Math.round(AGENT_PACK_MAX_TOTAL_BYTES / 1_000_000)} MB of text.`,
+    );
+  }
+
+  const profileFile = [...files]
+    .filter((file) => profileScore(file) > 0)
+    .sort(
+      (a, b) =>
+        profileScore(b) - profileScore(a) || a.path.localeCompare(b.path),
+    )[0];
+  if (!profileFile) {
+    throw new Error(
+      "An agent pack needs an agent.md, CLAUDE.md, or Markdown profile file.",
+    );
+  }
+
+  const profile = normalizeImportedAgent(profileFile.content, profileFile.path);
+  const warnings: string[] = [...profile.warnings];
+  const packFiles = files
+    .filter((file) => file !== profileFile)
+    .map((file): NormalizedAgentPackFile => {
+      const skill = isSkillFile(file.path)
+        ? parseSkillMetadata(file.content, file.path)
+        : null;
+      return {
+        path: file.path,
+        content: file.content,
+        name: skill?.name || fileName(file.path),
+        description: skill?.description || fileDescription(file),
+        kind: skill ? "skill" : "agent-file",
+      };
+    });
+
+  if (packFiles.length === 0) {
+    warnings.push(
+      "This pack contains only the profile; add files under context/ or skills/ when needed.",
+    );
+  }
+
+  return { profile, profileFile, files: packFiles, warnings, totalBytes };
+}
+
+export function agentPackProfileContent(input: {
+  profile: ImportedAgentProfile;
+  tools?: string;
+  sourceHash?: string;
+  importedAt?: string;
+}): string {
+  return buildSimpleAgentContent({
+    ...input.profile,
+    tools: input.tools,
+    source: input.profile.source,
+    sourcePath: input.profile.sourcePath,
+    sourceHash: input.sourceHash,
+    importedAt: input.importedAt,
+  });
+}
+
+export function agentPackRoot(agentNameOrSlug: string): string {
+  return `agents/${slugifyAgentName(agentNameOrSlug)}`;
+}

package/src/lib/simple-agent-profile.spec.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  buildSimpleAgentContent,
+  normalizeImportedAgent,
+  slugifyAgentName,
+  validateImportedAgentTools,
+} from "./simple-agent-profile.js";
+
+describe("simple agent profiles", () => {
+  it("normalizes a Claude-style Markdown agent", () => {
+    const result = normalizeImportedAgent(
+      `---\nname: Research Partner\ndescription: Synthesizes research\nmodel: sonnet\ntools: Read, WebSearch\n---\n\n# Role\n\nResearch carefully.`,
+      ".claude/agents/research.md",
+    );
+
+    expect(result).toMatchObject({
+      name: "Research Partner",
+      description: "Synthesizes research",
+      model: "sonnet",
+      tools: "Read, WebSearch",
+      source: "claude",
+      sourcePath: ".claude/agents/research.md",
+    });
+    expect(result.instructions).toContain("Research carefully.");
+  });
+
+  it("normalizes a generic JSON agent and reports unsafe fields", () => {
+    const result = normalizeImportedAgent(
+      JSON.stringify({
+        name: "Launch Reviewer",
+        systemPrompt: "Review launch plans.",
+        tools: ["Read", "Search"],
+        hooks: { afterRun: "rm -rf ./tmp" },
+      }),
+      "agent.json",
+    );
+
+    expect(result).toMatchObject({
+      name: "Launch Reviewer",
+      tools: "Read, Search",
+      source: "json",
+    });
+    expect(result.warnings).toContain("Skipped unsafe capability: hooks");
+  });
+
+  it("builds the canonical runtime profile content", () => {
+    expect(
+      buildSimpleAgentContent({
+        name: "Research Partner",
+        description: "Synthesizes research",
+        instructions: "Ask for evidence before making claims.",
+        source: "claude",
+        sourcePath: ".claude/agents/research.md",
+        sourceHash: "abc123",
+      }),
+    ).toContain("source-hash: abc123");
+  });
+
+  it("keeps resolvable imported tools and warns for the rest", () => {
+    expect(
+      validateImportedAgentTools(
+        "Read, Bash, WebSearch",
+        new Set(["bash", "web-search"]),
+      ),
+    ).toEqual({
+      tools: "bash, web-search",
+      warnings: ["Skipped unmapped tool: Read"],
+    });
+  });
+
+  it("creates stable slugs for names", () => {
+    expect(slugifyAgentName("  User Research / KPMG  ")).toBe(
+      "user-research-kpmg",
+    );
+  });
+});

package/src/lib/simple-agent-profile.ts

@@ -0,0 +1,247 @@
+import {
+  frontmatterFieldsToObject,
+  parseFrontmatter,
+  serializeFrontmatter,
+} from "@agent-native/core/resources/metadata";
+
+export interface SimpleAgentProfileInput {
+  name: string;
+  description?: string;
+  model?: string;
+  tools?: string;
+  instructions: string;
+  source?: string;
+  sourcePath?: string;
+  sourceHash?: string;
+  importedAt?: string;
+}
+
+export interface ImportedAgentProfile {
+  name: string;
+  description?: string;
+  model?: string;
+  tools?: string;
+  instructions: string;
+  slug: string;
+  source: "markdown" | "claude" | "json";
+  sourcePath?: string;
+  warnings: string[];
+}
+
+export interface ImportedAgentToolValidation {
+  tools?: string;
+  warnings: string[];
+}
+
+const SUPPORTED_FIELDS = new Set([
+  "name",
+  "description",
+  "model",
+  "tools",
+  "color",
+  "delegate-default",
+  "source",
+  "source-path",
+  "source-hash",
+  "imported-at",
+]);
+
+export function slugifyAgentName(value: string): string {
+  return (
+    value
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "agent"
+  );
+}
+
+function deriveName(fileName?: string): string {
+  const baseName = fileName?.replaceAll("\\", "/").split("/").pop();
+  const name = baseName?.replace(/\.(md|markdown|json|txt)$/i, "");
+  return name?.trim() || "Imported agent";
+}
+
+function stringValue(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+function toolsValue(value: unknown): string | undefined {
+  if (Array.isArray(value)) {
+    const tools = value.filter(
+      (item): item is string => typeof item === "string",
+    );
+    return tools.length > 0 ? tools.join(", ") : undefined;
+  }
+  return stringValue(value);
+}
+
+function normalizeToolKey(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+
+function importedToolNames(value: string): string[] {
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.toLowerCase() === "inherit") return [];
+  const unwrapped = trimmed.replace(/^\[|\]$/g, "");
+  return unwrapped
+    .split(/[\n,]/)
+    .map((tool) => tool.trim().replace(/^['"]|['"]$/g, ""))
+    .filter(Boolean);
+}
+
+/**
+ * Imported tool names are descriptive input, not a permission grant. Keep only
+ * names the current Dispatch surface can resolve and make every omission
+ * visible to the caller instead of persisting a misleading tool list.
+ */
+export function validateImportedAgentTools(
+  tools: string | undefined,
+  availableToolNames: ReadonlySet<string>,
+): ImportedAgentToolValidation {
+  const names = importedToolNames(tools ?? "");
+  if (names.length === 0) return { warnings: [] };
+
+  const resolvable = new Map<string, string>();
+  for (const name of availableToolNames) {
+    resolvable.set(normalizeToolKey(name), name);
+  }
+
+  const mapped: string[] = [];
+  const warnings: string[] = [];
+  for (const name of names) {
+    const resolved = resolvable.get(normalizeToolKey(name));
+    if (resolved) {
+      if (!mapped.includes(resolved)) mapped.push(resolved);
+    } else {
+      warnings.push(`Skipped unmapped tool: ${name}`);
+    }
+  }
+
+  return {
+    tools: mapped.length > 0 ? mapped.join(", ") : undefined,
+    warnings,
+  };
+}
+
+function markdownProfile(
+  source: string,
+  fileName?: string,
+): Omit<ImportedAgentProfile, "source"> & {
+  source: "markdown" | "claude";
+} {
+  const frontmatter = parseFrontmatter(source);
+  const values = frontmatterFieldsToObject(frontmatter);
+  const body = (frontmatter?.body ?? source).trim();
+  const heading = body.match(/^#\s+(.+)$/m)?.[1]?.trim();
+  const name = stringValue(values.name) || heading || deriveName(fileName);
+  const warnings = Object.keys(values)
+    .filter((key) => !SUPPORTED_FIELDS.has(key))
+    .map((key) => `Ignored unsupported field: ${key}`);
+  if (!body) warnings.push("The imported agent has no instructions yet.");
+
+  return {
+    name,
+    description: stringValue(values.description),
+    model: stringValue(values.model),
+    tools: toolsValue(values.tools),
+    instructions: body,
+    slug: slugifyAgentName(name),
+    source: fileName?.includes(".claude/") ? "claude" : "markdown",
+    sourcePath: fileName,
+    warnings,
+  };
+}
+
+function jsonProfile(source: string, fileName?: string): ImportedAgentProfile {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(source);
+  } catch {
+    throw new Error("This file looks like JSON, but it is not valid JSON.");
+  }
+
+  const record =
+    parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  const candidate =
+    record?.agent &&
+    typeof record.agent === "object" &&
+    !Array.isArray(record.agent)
+      ? (record.agent as Record<string, unknown>)
+      : record;
+  if (!candidate) {
+    throw new Error("Import a single agent definition, not a JSON list.");
+  }
+
+  const name =
+    stringValue(candidate.name) ||
+    stringValue(candidate.title) ||
+    deriveName(fileName);
+  const instructions =
+    stringValue(candidate.instructions) ||
+    stringValue(candidate.systemPrompt) ||
+    stringValue(candidate.prompt) ||
+    stringValue(candidate.content) ||
+    "";
+  const warnings: string[] = [];
+  for (const key of ["hooks", "env", "environment", "command", "args", "cwd"]) {
+    if (candidate[key] !== undefined) {
+      warnings.push(`Skipped unsafe capability: ${key}`);
+    }
+  }
+  if (!instructions)
+    warnings.push("The imported agent has no instructions yet.");
+
+  return {
+    name,
+    description: stringValue(candidate.description),
+    model: stringValue(candidate.model),
+    tools: toolsValue(candidate.tools),
+    instructions,
+    slug: slugifyAgentName(name),
+    source: "json",
+    sourcePath: fileName,
+    warnings,
+  };
+}
+
+export function normalizeImportedAgent(
+  source: string,
+  fileName?: string,
+): ImportedAgentProfile {
+  const trimmed = source.trim();
+  if (!trimmed) throw new Error("Paste an agent definition or choose a file.");
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    return jsonProfile(trimmed, fileName);
+  }
+  return markdownProfile(trimmed, fileName);
+}
+
+export function buildSimpleAgentContent(
+  input: SimpleAgentProfileInput,
+): string {
+  const fields = [
+    { key: "name", value: input.name.trim() },
+    ...(input.description?.trim()
+      ? [{ key: "description", value: input.description.trim() }]
+      : []),
+    { key: "model", value: input.model?.trim() || "inherit" },
+    { key: "tools", value: input.tools?.trim() || "inherit" },
+    { key: "delegate-default", value: "false" },
+    ...(input.source ? [{ key: "source", value: input.source }] : []),
+    ...(input.sourcePath
+      ? [{ key: "source-path", value: input.sourcePath }]
+      : []),
+    ...(input.sourceHash
+      ? [{ key: "source-hash", value: input.sourceHash }]
+      : []),
+    ...(input.importedAt
+      ? [{ key: "imported-at", value: input.importedAt }]
+      : []),
+  ];
+  return `${serializeFrontmatter(fields)}${input.instructions.trim()}\n`;
+}

package/src/routes/index.spec.ts

@@ -18,6 +18,7 @@ describe("Dispatch route registration", () => {
     expect(paths).toContain("browser-connect");
     expect(paths).toContain("operations");
     expect(paths).toContain("admin");
+    expect(paths).toContain("agents");
     expect(paths.indexOf("chat")).toBeLessThan(paths.indexOf(":appId"));
     expect(paths.indexOf("chat/:threadId")).toBeLessThan(
       paths.indexOf(":appId"),

package/src/routes/pages/agents.tsx

@@ -5,6 +5,7 @@ import {
 import { useT } from "@agent-native/core/client/i18n";
 import { IconCheck, IconCopy, IconPlugConnected } from "@tabler/icons-react";
 import { useMemo, useState } from "react";
+import { useLocation } from "react-router";
 import { toast } from "sonner";
 
 import { ActionQueryError } from "../../components/action-query-error";
@@ -13,6 +14,7 @@ import {
   type ConnectedAgent,
 } from "../../components/agents-panel";
 import { DispatchShell } from "../../components/dispatch-shell";
+import { SimpleAgentsPanel } from "../../components/simple-agents-panel";
 import { Button } from "../../components/ui/button";
 import { Input } from "../../components/ui/input";
 import { Skeleton } from "../../components/ui/skeleton";
@@ -203,7 +205,7 @@ function DispatchMcpAccessPanel() {
   );
 }
 
-export default function AgentsRoute() {
+function ConnectedAgentsRoute() {
   const t = useT();
   const agentsQuery = useActionQuery("list-connected-agents", {});
 
@@ -229,3 +231,21 @@ export default function AgentsRoute() {
     </DispatchShell>
   );
 }
+
+export default function AgentsRoute() {
+  const t = useT();
+  const location = useLocation();
+
+  if (!location.pathname.startsWith("/admin/agents")) {
+    return (
+      <DispatchShell
+        title={t("dispatch.nav.agents")}
+        description={t("dispatch.pages.simpleAgentsDescription")}
+      >
+        <SimpleAgentsPanel />
+      </DispatchShell>
+    );
+  }
+
+  return <ConnectedAgentsRoute />;
+}