@comma-agents/core 2.0.0-rc.0 → 2.0.0-rc.1

package/dist/hub/hub.types.d.ts

@@ -0,0 +1,50 @@
+import type { z } from "zod";
+import type { CommaProjectManifestSchema, HubEnvironmentVariableSchema, HubPackageSchema, HubPermissionsSchema, HubPersonSchema, HubRegistryArtifactSchema, HubRegistrySchema, ProjectArtifactEntrySchema } from "./hub.schema";
+/** Public metadata for a person associated with a Hub project. */
+export type HubPerson = z.infer<typeof HubPersonSchema>;
+/** A declared environment variable used by a project. */
+export type HubEnvironmentVariable = z.infer<typeof HubEnvironmentVariableSchema>;
+/** Runtime capabilities required by a project. */
+export type HubPermissions = z.infer<typeof HubPermissionsSchema>;
+/** One artifact declared by a project manifest. */
+export type ProjectArtifactEntry = z.infer<typeof ProjectArtifactEntrySchema>;
+/** Canonical `comma-project.json` contract inferred from the public schema. */
+export type CommaProjectManifest = z.infer<typeof CommaProjectManifestSchema>;
+export type HubArtifactKind = "strategies" | "agents" | "flows" | "tools";
+export type HubRegistryArtifact = z.infer<typeof HubRegistryArtifactSchema>;
+export type HubPackage = z.infer<typeof HubPackageSchema>;
+export type HubRegistry = z.infer<typeof HubRegistrySchema>;
+export interface HubRegistrySnapshot {
+    readonly commit: string;
+    readonly registry: HubRegistry;
+}
+export interface InstalledHubPackage {
+    readonly name: string;
+    readonly version: string;
+    readonly commit: string;
+    readonly path: string;
+    readonly executableCodeApproved: boolean;
+}
+export interface HubInstallOptions {
+    readonly allowCode?: boolean;
+}
+export interface HubRepositoryConfig {
+    readonly owner: string;
+    readonly repository: string;
+    readonly branch: string;
+}
+export interface CreateHubManagerOptions {
+    readonly dataDir?: string;
+    readonly repository?: HubRepositoryConfig;
+    readonly fetch?: typeof globalThis.fetch;
+}
+export interface HubManager {
+    refreshRegistry(): Promise<HubRegistrySnapshot>;
+    listAvailable(): Promise<readonly HubPackage[]>;
+    listInstalled(): Promise<readonly InstalledHubPackage[]>;
+    install(name: string, options?: HubInstallOptions): Promise<InstalledHubPackage>;
+    update(name: string, options?: HubInstallOptions): Promise<InstalledHubPackage>;
+    remove(name: string): Promise<boolean>;
+    getInstalled(name: string): Promise<InstalledHubPackage | undefined>;
+    isExecutableCodeApproved(manifestPath: string): Promise<boolean>;
+}

package/dist/hub/hub.utils.d.ts

@@ -0,0 +1,3 @@
+import type { HubPackage, HubRegistrySnapshot } from "./hub.types";
+/** Find a named package in a registry snapshot or throw when unavailable. */
+export declare function findAvailableHubPackage(snapshot: HubRegistrySnapshot, name: string): HubPackage;

package/dist/hub/index.d.ts

@@ -0,0 +1,3 @@
+export { createHubManager } from "./hub";
+export { CommaProjectManifestSchema, HubPackageSchema, HubRegistryArtifactSchema, HubRegistrySchema, ProjectArtifactEntrySchema, } from "./hub.schema";
+export type { CommaProjectManifest, CreateHubManagerOptions, HubArtifactKind, HubEnvironmentVariable, HubInstallOptions, HubManager, HubPackage, HubPermissions, HubPerson, HubRegistry, HubRegistryArtifact, HubRegistrySnapshot, HubRepositoryConfig, InstalledHubPackage, ProjectArtifactEntry, } from "./hub.types";

package/dist/hub/index.js

@@ -0,0 +1,404 @@
+// @bun
+var __require = import.meta.require;
+
+// src/hub/hub.ts
+import { join as join3 } from "path";
+
+// src/data-directory/data-directory.ts
+import { homedir } from "os";
+import { join } from "path";
+function resolveDataDir() {
+  return join(homedir(), ".comma");
+}
+// src/hub/hub.constants.ts
+var DEFAULT_HUB_REPOSITORY = {
+  owner: "CloAI",
+  repository: "CommaAgentsHub",
+  branch: "main"
+};
+var HUB_MAX_FILES = 2000;
+var HUB_MAX_UNCOMPRESSED_BYTES = 50 * 1024 * 1024;
+var HUB_INSTALLED_STATE_FILENAME = "installed-packages.json";
+
+// src/hub/hub.utils.ts
+function findAvailableHubPackage(snapshot, name) {
+  const project = snapshot.registry.packages.find((availablePackage) => availablePackage.name === name);
+  if (!project)
+    throw new Error(`Hub package not found: ${name}`);
+  return project;
+}
+
+// src/hub/installed-packages/installed-packages.ts
+import { mkdir, readFile, rename, rm, writeFile } from "fs/promises";
+import { dirname, resolve } from "path";
+function createInstalledPackageStore({
+  statePath
+}) {
+  async function readState() {
+    try {
+      const parsed = JSON.parse(await readFile(statePath, "utf8"));
+      return {
+        packages: Array.isArray(parsed.packages) ? parsed.packages : []
+      };
+    } catch (error) {
+      if (error.code === "ENOENT")
+        return { packages: [] };
+      throw error;
+    }
+  }
+  async function writeState(packages) {
+    await mkdir(dirname(statePath), { recursive: true });
+    const temporaryPath = `${statePath}.${crypto.randomUUID()}.tmp`;
+    await writeFile(temporaryPath, `${JSON.stringify({ packages: [...packages].sort((firstPackage, secondPackage) => firstPackage.name.localeCompare(secondPackage.name)) }, null, 2)}
+`);
+    await rename(temporaryPath, statePath);
+  }
+  async function list() {
+    return (await readState()).packages;
+  }
+  async function get(name) {
+    return (await list()).find((installedPackage) => installedPackage.name === name);
+  }
+  return {
+    list,
+    get,
+    async replace(installedPackage) {
+      const state = await readState();
+      await writeState([
+        ...state.packages.filter((statePackage) => statePackage.name !== installedPackage.name),
+        installedPackage
+      ]);
+    },
+    async remove(name) {
+      const installedPackage = await get(name);
+      if (!installedPackage)
+        return false;
+      const backupPath = `${installedPackage.path}.${crypto.randomUUID()}.removing`;
+      const state = await readState();
+      await rename(installedPackage.path, backupPath);
+      try {
+        await writeState(state.packages.filter((statePackage) => statePackage.name !== name));
+        await rm(backupPath, { recursive: true, force: true });
+        return true;
+      } catch (error) {
+        await rename(backupPath, installedPackage.path);
+        throw error;
+      }
+    },
+    async isExecutableCodeApproved(manifestPath) {
+      const installedPackage = (await list()).find((statePackage) => resolve(statePackage.path, "comma-project.json") === resolve(manifestPath));
+      return installedPackage?.executableCodeApproved ?? false;
+    }
+  };
+}
+// src/hub/package-installer/package-installer.ts
+import { mkdir as mkdir3, mkdtemp, readFile as readFile2, rename as rename2, rm as rm2, stat } from "fs/promises";
+import { tmpdir } from "os";
+import { dirname as dirname3, join as join2 } from "path";
+
+// src/hub/archive/archive.ts
+import { createWriteStream } from "fs";
+import { mkdir as mkdir2 } from "fs/promises";
+import { dirname as dirname2, relative, resolve as resolve2, sep } from "path";
+import { extract } from "tar-stream";
+async function extractHubPackageArchive(compressedArchive, packageName, destination) {
+  const unpackedArchive = Bun.gunzipSync(compressedArchive.buffer);
+  const archive = extract();
+  const packageMarker = `/packages/${packageName}/`;
+  let fileCount = 0;
+  let byteCount = 0;
+  let foundManifest = false;
+  await new Promise((resolveExtraction, rejectExtraction) => {
+    archive.on("entry", (header, stream, next) => {
+      const markerIndex = header.name.indexOf(packageMarker);
+      if (markerIndex === -1) {
+        stream.resume();
+        stream.once("end", next);
+        return;
+      }
+      const relativePath = header.name.slice(markerIndex + packageMarker.length);
+      if (relativePath.length === 0 || header.type === "directory") {
+        stream.resume();
+        stream.once("end", next);
+        return;
+      }
+      if (header.type !== "file") {
+        rejectExtraction(new Error(`Hub archive contains unsupported ${header.type} entry: ${relativePath}`));
+        stream.resume();
+        return;
+      }
+      const outputPath = resolve2(destination, relativePath);
+      const relativeOutputPath = relative(resolve2(destination), resolve2(outputPath));
+      if (relativeOutputPath === "" || relativeOutputPath === ".." || relativeOutputPath.startsWith(`..${sep}`)) {
+        rejectExtraction(new Error(`Hub archive path escapes package root: ${relativePath}`));
+        stream.resume();
+        return;
+      }
+      fileCount += 1;
+      byteCount += header.size ?? 0;
+      if (fileCount > HUB_MAX_FILES || byteCount > HUB_MAX_UNCOMPRESSED_BYTES) {
+        rejectExtraction(new Error("Hub package exceeds extraction limits"));
+        stream.resume();
+        return;
+      }
+      mkdir2(dirname2(outputPath), { recursive: true }).then(() => {
+        if (relativePath === "comma-project.json")
+          foundManifest = true;
+        const output = createWriteStream(outputPath, { flags: "wx" });
+        output.once("error", rejectExtraction);
+        output.once("finish", next);
+        stream.once("error", rejectExtraction);
+        stream.pipe(output);
+      }).catch(rejectExtraction);
+    });
+    archive.once("finish", () => {
+      if (!foundManifest) {
+        rejectExtraction(new Error(`Package ${packageName} was not found in the Hub archive`));
+        return;
+      }
+      resolveExtraction();
+    });
+    archive.once("error", rejectExtraction);
+    archive.end(unpackedArchive);
+  });
+}
+// src/hub/hub.schema.ts
+import { z } from "zod";
+var PACKAGE_NAME_PATTERN = /^@[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/;
+var ARTIFACT_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+var SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+var HubPersonSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email().optional(),
+  url: z.string().url().optional()
+}).strict();
+var HubEnvironmentVariableSchema = z.object({
+  description: z.string().optional(),
+  required: z.boolean().optional(),
+  default: z.string().optional(),
+  example: z.string().optional()
+}).strict();
+var HubPermissionsSchema = z.object({
+  network: z.boolean().optional(),
+  filesystem: z.boolean().optional(),
+  shell: z.boolean().optional(),
+  executesCode: z.boolean().optional()
+}).strict();
+var ProjectArtifactEntrySchema = z.object({
+  path: z.string().min(1),
+  expose: z.boolean().optional(),
+  description: z.string().optional()
+}).strict();
+var ArtifactMapSchema = z.record(z.string().regex(ARTIFACT_NAME_PATTERN), ProjectArtifactEntrySchema);
+var CommaProjectManifestSchema = z.object({
+  name: z.string().regex(PACKAGE_NAME_PATTERN),
+  version: z.string().regex(SEMVER_PATTERN, "Expected semantic version x.y.z"),
+  description: z.string().optional(),
+  license: z.string().optional(),
+  author: HubPersonSchema.optional(),
+  contributors: z.array(HubPersonSchema).optional(),
+  keywords: z.array(z.string()).optional(),
+  strategies: ArtifactMapSchema.optional(),
+  agents: ArtifactMapSchema.optional(),
+  flows: ArtifactMapSchema.optional(),
+  tools: ArtifactMapSchema.optional(),
+  entry: z.string().min(1).optional(),
+  dependencies: z.record(z.string(), z.string()).optional(),
+  environment: z.record(z.string().regex(/^[A-Z_][A-Z0-9_]*$/), HubEnvironmentVariableSchema).optional(),
+  permissions: HubPermissionsSchema.optional(),
+  links: z.object({
+    homepage: z.string().url().optional(),
+    repository: z.string().url().optional(),
+    docs: z.string().url().optional(),
+    issues: z.string().url().optional()
+  }).strict().optional()
+}).strict();
+var HubRegistryArtifactSchema = z.object({
+  id: z.string().regex(ARTIFACT_NAME_PATTERN),
+  ref: z.string().min(1),
+  path: z.string().min(1),
+  description: z.string().optional()
+}).strict();
+var RegistryArtifactListSchema = z.array(HubRegistryArtifactSchema);
+var HubPackageSchema = z.object({
+  name: z.string().regex(PACKAGE_NAME_PATTERN),
+  version: z.string().regex(SEMVER_PATTERN),
+  description: z.string().optional(),
+  license: z.string().optional(),
+  path: z.string().min(1),
+  author: HubPersonSchema.optional(),
+  contributors: z.array(HubPersonSchema).optional(),
+  keywords: z.array(z.string()).optional(),
+  exports: z.object({
+    strategies: RegistryArtifactListSchema,
+    agents: RegistryArtifactListSchema,
+    flows: RegistryArtifactListSchema,
+    tools: RegistryArtifactListSchema
+  }).strict(),
+  environment: z.record(HubEnvironmentVariableSchema).optional(),
+  permissions: HubPermissionsSchema.optional(),
+  links: z.object({
+    homepage: z.string().url().optional(),
+    repository: z.string().url().optional(),
+    docs: z.string().url().optional(),
+    issues: z.string().url().optional()
+  }).strict().optional()
+}).strict();
+var HubRegistrySchema = z.object({
+  version: z.literal(1),
+  packages: z.array(HubPackageSchema)
+}).strict();
+
+// src/hub/package-installer/package-installer.ts
+function createHubPackageInstaller({
+  packagesRoot,
+  installedPackages,
+  registryClient
+}) {
+  return {
+    async install(project, snapshot, options, replace) {
+      if (project.permissions?.executesCode === true && options.allowCode !== true) {
+        throw new Error(`Package ${project.name} contains executable code; pass allowCode: true to install it`);
+      }
+      const existingPackage = await installedPackages.get(project.name);
+      if (existingPackage && !replace)
+        throw new Error(`Package ${project.name} is already installed`);
+      const stagingRoot = await mkdtemp(join2(tmpdir(), "comma-hub-"));
+      const stagedPackagePath = join2(stagingRoot, "package");
+      const destinationPath = join2(packagesRoot, ...project.name.split("/"));
+      const backupPath = `${destinationPath}.${crypto.randomUUID()}.backup`;
+      let destinationReplaced = false;
+      try {
+        await mkdir3(stagedPackagePath, { recursive: true });
+        await extractHubPackageArchive(await registryClient.fetchArchive(snapshot.commit), project.name, stagedPackagePath);
+        const manifest = CommaProjectManifestSchema.safeParse(JSON.parse(await readFile2(join2(stagedPackagePath, "comma-project.json"), "utf8")));
+        if (!manifest.success || manifest.data.name !== project.name || manifest.data.version !== project.version) {
+          throw new Error(`Installed manifest does not match registry entry for ${project.name}`);
+        }
+        if (manifest.data.permissions?.executesCode !== project.permissions?.executesCode) {
+          throw new Error(`Installed manifest permissions do not match registry entry for ${project.name}`);
+        }
+        if (manifest.data.dependencies && Object.keys(manifest.data.dependencies).length > 0) {
+          throw new Error(`Package dependencies are not supported in v1: ${project.name}`);
+        }
+        await mkdir3(dirname3(destinationPath), { recursive: true });
+        if (existingPackage)
+          await rename2(destinationPath, backupPath);
+        await rename2(stagedPackagePath, destinationPath);
+        destinationReplaced = true;
+        const installedPackage = {
+          name: project.name,
+          version: project.version,
+          commit: snapshot.commit,
+          path: destinationPath,
+          executableCodeApproved: project.permissions?.executesCode === true
+        };
+        await installedPackages.replace(installedPackage);
+        await rm2(backupPath, { recursive: true, force: true });
+        return installedPackage;
+      } catch (error) {
+        try {
+          if (destinationReplaced) {
+            await rm2(destinationPath, { recursive: true, force: true });
+          }
+          if (existingPackage && (await stat(backupPath)).isDirectory()) {
+            await rename2(backupPath, destinationPath);
+          }
+        } catch {}
+        throw error;
+      } finally {
+        await rm2(stagingRoot, { recursive: true, force: true });
+        await rm2(backupPath, { recursive: true, force: true });
+      }
+    }
+  };
+}
+// src/hub/registry-client/registry-client.ts
+function createHubRegistryClient({
+  repository,
+  fetch
+}) {
+  let registrySnapshot;
+  async function fetchRequired(url) {
+    const response = await fetch(url, {
+      headers: { Accept: "application/vnd.github+json" }
+    });
+    if (!response.ok)
+      throw new Error(`Hub request failed (${response.status}): ${url}`);
+    return response;
+  }
+  async function refresh() {
+    const repositoryUrl = `https://api.github.com/repos/${repository.owner}/${repository.repository}`;
+    const commitResponse = await fetchRequired(`${repositoryUrl}/commits/${repository.branch}`);
+    const commitJson = await commitResponse.json();
+    if (typeof commitJson.sha !== "string")
+      throw new Error("Hub commit response did not contain a SHA");
+    const registryResponse = await fetchRequired(`https://raw.githubusercontent.com/${repository.owner}/${repository.repository}/${commitJson.sha}/registry.json`);
+    const parsedRegistry = HubRegistrySchema.safeParse(await registryResponse.json());
+    if (!parsedRegistry.success) {
+      throw new Error(`Hub registry validation failed: ${parsedRegistry.error.message}`);
+    }
+    registrySnapshot = {
+      commit: commitJson.sha,
+      registry: parsedRegistry.data
+    };
+    return registrySnapshot;
+  }
+  return {
+    refresh,
+    async getSnapshot() {
+      return registrySnapshot ?? refresh();
+    },
+    async fetchArchive(commit) {
+      const archiveResponse = await fetchRequired(`https://codeload.github.com/${repository.owner}/${repository.repository}/tar.gz/${commit}`);
+      return new Uint8Array(await archiveResponse.arrayBuffer());
+    }
+  };
+}
+// src/hub/hub.ts
+function createHubManager(options = {}) {
+  const dataDirectory = options.dataDir ?? resolveDataDir();
+  const repository = options.repository ?? DEFAULT_HUB_REPOSITORY;
+  const registryClient = createHubRegistryClient({
+    repository,
+    fetch: options.fetch ?? globalThis.fetch
+  });
+  const installedPackages = createInstalledPackageStore({
+    statePath: join3(dataDirectory, "hub", HUB_INSTALLED_STATE_FILENAME)
+  });
+  const packageInstaller = createHubPackageInstaller({
+    packagesRoot: join3(dataDirectory, "packages"),
+    installedPackages,
+    registryClient
+  });
+  return {
+    refreshRegistry: registryClient.refresh,
+    async listAvailable() {
+      return (await registryClient.getSnapshot()).registry.packages;
+    },
+    listInstalled: installedPackages.list,
+    async install(name, installOptions = {}) {
+      const snapshot = await registryClient.getSnapshot();
+      const project = findAvailableHubPackage(snapshot, name);
+      return packageInstaller.install(project, snapshot, installOptions, false);
+    },
+    async update(name, installOptions = {}) {
+      if (!await installedPackages.get(name))
+        throw new Error(`Package ${name} is not installed`);
+      const snapshot = await registryClient.refresh();
+      const project = findAvailableHubPackage(snapshot, name);
+      return packageInstaller.install(project, snapshot, installOptions, true);
+    },
+    remove: installedPackages.remove,
+    getInstalled: installedPackages.get,
+    isExecutableCodeApproved: installedPackages.isExecutableCodeApproved
+  };
+}
+export {
+  createHubManager,
+  ProjectArtifactEntrySchema,
+  HubRegistrySchema,
+  HubRegistryArtifactSchema,
+  HubPackageSchema,
+  CommaProjectManifestSchema
+};

package/dist/hub/installed-packages/index.d.ts

@@ -0,0 +1,2 @@
+export { createInstalledPackageStore } from "./installed-packages";
+export type { InstalledPackageStore } from "./installed-packages.types";

package/dist/hub/installed-packages/installed-packages.d.ts

@@ -0,0 +1,3 @@
+import type { CreateInstalledPackageStoreOptions, InstalledPackageStore } from "./installed-packages.types";
+/** Create the persistent store used to track installed Hub packages. */
+export declare function createInstalledPackageStore({ statePath, }: CreateInstalledPackageStoreOptions): InstalledPackageStore;

package/dist/hub/installed-packages/installed-packages.types.d.ts

@@ -0,0 +1,14 @@
+import type { InstalledHubPackage } from "../hub.types";
+export interface InstalledPackageStore {
+    list(): Promise<readonly InstalledHubPackage[]>;
+    get(name: string): Promise<InstalledHubPackage | undefined>;
+    replace(installedPackage: InstalledHubPackage): Promise<void>;
+    remove(name: string): Promise<boolean>;
+    isExecutableCodeApproved(manifestPath: string): Promise<boolean>;
+}
+export interface CreateInstalledPackageStoreOptions {
+    readonly statePath: string;
+}
+export interface InstalledPackageState {
+    readonly packages: readonly InstalledHubPackage[];
+}

package/dist/hub/package-installer/index.d.ts

@@ -0,0 +1,2 @@
+export { createHubPackageInstaller } from "./package-installer";
+export type { HubPackageInstaller } from "./package-installer.types";

package/dist/hub/package-installer/package-installer.d.ts

@@ -0,0 +1,3 @@
+import type { CreateHubPackageInstallerOptions, HubPackageInstaller } from "./package-installer.types";
+/** Create the transaction that validates and installs Hub packages. */
+export declare function createHubPackageInstaller({ packagesRoot, installedPackages, registryClient, }: CreateHubPackageInstallerOptions): HubPackageInstaller;

package/dist/hub/package-installer/package-installer.types.d.ts

@@ -0,0 +1,11 @@
+import type { HubInstallOptions, HubPackage, HubRegistrySnapshot, InstalledHubPackage } from "../hub.types";
+import type { InstalledPackageStore } from "../installed-packages";
+import type { HubRegistryClient } from "../registry-client";
+export interface CreateHubPackageInstallerOptions {
+    readonly packagesRoot: string;
+    readonly installedPackages: InstalledPackageStore;
+    readonly registryClient: HubRegistryClient;
+}
+export interface HubPackageInstaller {
+    install(project: HubPackage, snapshot: HubRegistrySnapshot, options: HubInstallOptions, replace: boolean): Promise<InstalledHubPackage>;
+}

package/dist/hub/registry-client/index.d.ts

@@ -0,0 +1,2 @@
+export { createHubRegistryClient } from "./registry-client";
+export type { HubRegistryClient } from "./registry-client.types";

package/dist/hub/registry-client/registry-client.d.ts

@@ -0,0 +1,3 @@
+import type { CreateHubRegistryClientOptions, HubRegistryClient } from "./registry-client.types";
+/** Create a client for fetching a Hub registry and its repository archive. */
+export declare function createHubRegistryClient({ repository, fetch, }: CreateHubRegistryClientOptions): HubRegistryClient;

package/dist/hub/registry-client/registry-client.types.d.ts

@@ -0,0 +1,10 @@
+import type { HubRegistrySnapshot, HubRepositoryConfig } from "../hub.types";
+export interface HubRegistryClient {
+    refresh(): Promise<HubRegistrySnapshot>;
+    getSnapshot(): Promise<HubRegistrySnapshot>;
+    fetchArchive(commit: string): Promise<Uint8Array>;
+}
+export interface CreateHubRegistryClientOptions {
+    readonly repository: HubRepositoryConfig;
+    readonly fetch: typeof globalThis.fetch;
+}

package/dist/index.d.ts

@@ -6,18 +6,21 @@ export { createUserAgent } from "./agents/built-in/user/user-agent";
 export type { InputCollector, InputRequest, UserAgentConfig, } from "./agents/built-in/user/user-agent.types";
 export { hookIntoAgent } from "./agents/hook-into-agent/hook-into-agent";
 export type { AgentHooks, ToolHooks } from "./agents/hooks/hooks.types";
-export type { AgentDescription, LoadAgentOptions } from "./agents/loader/index";
-export { AgentDescriptionSchema, loadAgent, loadAgentFromString, } from "./agents/loader/index";
-export type { AssistantModelMessage, CompactionOptions, ContextPrepareInput, ContextUsage, ContextRecordTransform, ContextRetentionOptions, ContextTransformInput, ConversationHistory, ConversationRecord, ConversationRecordStatus, ConversationRetentionEvent, ConversationUsage, CreateConversationRecordInput, ModelMessage, ResponseMessage, RollingWindowOptions, SummarizeRecords, ToolModelMessage, UserModelMessage, } from "./conversation-context";
+export type { AgentDescription, CustomAgentDescription, LLMAgentDescription, LoadAgentOptions, } from "./agents/loader/index";
+export { AgentDescriptionSchema, CustomAgentDescriptionSchema, LLMAgentDescriptionSchema, loadAgent, loadAgentFromString, } from "./agents/loader/index";
+export type { AgentTypeContext, AgentTypeDefinition, AgentTypeRuntime, } from "./agents/registry";
+export { defineAgentType, getRegisteredAgentNames, registerAgent, resetAgentRegistry, unregisterAgent, } from "./agents/registry";
+export type { AssistantModelMessage, CompactionOptions, ContextPrepareInput, ContextRecordTransform, ContextRetentionOptions, ContextTransformInput, ContextUsage, ConversationHistory, ConversationRecord, ConversationRecordStatus, ConversationRetentionEvent, ConversationUsage, CreateConversationRecordInput, ModelMessage, ResponseMessage, RollingWindowOptions, SummarizeRecords, ToolModelMessage, UserModelMessage, } from "./conversation-context";
 export type { ConversationContext, ConversationContextOptions, } from "./conversation-context/index";
-export { applyCompaction, applyRollingWindow, contextUsageFromSteps, createConversationContext, createConversationRecord, parseConversationJson, parseConversationJsonl, parseConversationYaml, prepareContextRecords, recordsToMessages, recordToJsonlLine, serializeConversationRecordsJson, serializeConversationRecords, serializeConversationRecordsYaml, } from "./conversation-context/index";
+export { applyCompaction, applyRollingWindow, contextUsageFromSteps, createConversationContext, createConversationRecord, parseConversationJson, parseConversationJsonl, parseConversationYaml, prepareContextRecords, recordsToMessages, recordToJsonlLine, serializeConversationRecords, serializeConversationRecordsJson, serializeConversationRecordsYaml, } from "./conversation-context/index";
 export type { ApiCredential, AuthStatus, CreateCredentialStoreOptions, Credential, CredentialBackend, CredentialStore, CredentialStoreData, CustomCredential, EnvVarMap, OAuthCredential, } from "./credentials/index";
-export { ApiCredentialSchema, CredentialSchema, CustomCredentialSchema, createCredentialStore, createJsonFileBackend, OAuthCredentialSchema, resolveCredentialsPath, resolveDataDir, } from "./credentials/index";
+export { ApiCredentialSchema, CredentialSchema, CustomCredentialSchema, createCredentialStore, createJsonFileBackend, OAuthCredentialSchema, resolveCredentialsPath, } from "./credentials/index";
+export { resolveDataDir } from "./data-directory";
 export type { GlobalDefaults, ProviderRegistration } from "./defaults/index";
 export { getGlobalCredentialStore, getGlobalDefaults, getGlobalProviderResolver, registerProvider, resetGlobalDefaults, setGlobalCredentialStore, setProviderCacheDir, unregisterProvider, } from "./defaults/index";
 export { AgentCallError, CommaAgentsError, FlowExecutionError, HookExecutionError, ModelResolutionError, SandboxViolationError, StrategyValidationError, ToolExecutionError, } from "./errors/index";
-export type { BroadcastFlowConfig, CustomFlowConfig, CycleFlowConfig, CycleHooks, FlowConfig, FlowContext, FlowExecutor, FlowHooks, FlowResult, } from "./flows/index";
-export { buildFlowAgent, createBroadcastFlow, createCycleFlow, createFlow, createSequentialFlow, hookIntoFlow, } from "./flows/index";
+export type { BroadcastFlowConfig, CustomFlowConfig, CycleFlowConfig, CycleHooks, FlowConfig, FlowContext, FlowExecutor, FlowHooks, FlowResult, FlowTypeContext, FlowTypeDefinition, } from "./flows/index";
+export { buildFlowAgent, createBroadcastFlow, createCycleFlow, createFlow, createSequentialFlow, defineFlowType, getRegisteredFlowNames, hookIntoFlow, registerFlow, resetFlowRegistry, unregisterFlow, } from "./flows/index";
 export type { FlowDescription, LoadFlowOptions } from "./flows/loader/index";
 export { FlowDescriptionSchema, loadFlow, loadFlowFromString, } from "./flows/loader/index";
 export type { AccessRequest, AccessType, Guard, GuardCallbacks, GuardPermissionRequest, GuardPolicySnapshot, Policy, PolicyDecision, } from "./guard/index";
@@ -28,15 +31,15 @@ export type { ModelMetadata, TokenSnapshot, TokenTracker, TokenTrackerConfig, To
 export { createTokenTracker, useTokenTracking, } from "./hooks/built-in/token-tracking/index";
 export type { LanguageDiagnostic, LanguageDiagnosticSeverity, LanguageHoverResult, LanguageLocation, LanguagePosition, LanguageRange, LanguageService, LanguageSymbol, LspMethod, LspRequest, LspResponse, } from "./language/index";
 export type { CatalogData, CatalogModel, CatalogProvider, ListModelsContext, ListModelsFn, ListModelsResult, Modality, ModelCapabilities, ModelCost, ModelInfo, ModelModalities, ModelStatus, ModelsSource, ParsedModel, ProviderDefinition, ProviderFactory, ProviderInfo, ProviderResolver, ProviderWithModels, } from "./model/index";
-export { extractProviderIds, getCatalogModels, getCatalogProvider, getCatalogProviderSync, getCatalogSnapshot, getModelCapabilities, getModelMetadata, getQualifiedModelMetadata, getProviderDefinition, getProviderInfo, getProviderPackage, getProvidersForModel, getReverseModelIndex, isKnownProvider, listAllProviderModels, listCatalogProviders, listProviderDefinitions, listProviderModels, listProviders, loadCatalog, parseModel, refreshCatalog, registerModel, registerProviderDefinition, resetCatalog, resetModelRegistry, resetProviderRegistry, resolveCatalogCachePath, resolveModel, toModelInfo, unregisterModel, unregisterProviderDefinition, } from "./model/index";
+export { extractProviderIds, getCatalogModels, getCatalogProvider, getCatalogProviderSync, getCatalogSnapshot, getModelCapabilities, getModelMetadata, getProviderDefinition, getProviderInfo, getProviderPackage, getProvidersForModel, getQualifiedModelMetadata, getReverseModelIndex, isKnownProvider, listAllProviderModels, listCatalogProviders, listProviderDefinitions, listProviderModels, listProviders, loadCatalog, parseModel, refreshCatalog, registerModel, registerProviderDefinition, resetCatalog, resetModelRegistry, resetProviderRegistry, resolveCatalogCachePath, resolveModel, toModelInfo, unregisterModel, unregisterProviderDefinition, } from "./model/index";
 export type { BuildMessagesOptions, PromptTemplate, PromptTemplateConfig, SystemPromptOptions, TemplateValue, TemplateVariables, } from "./prompts/index";
 export { buildMessages, createPromptTemplate, resolveSystemPrompt, } from "./prompts/index";
 export type { AccessMode, PathPolicy, PermissionDecision, PermissionOperation, PermissionRequest, PermissionRequester, PolicyPatch, Sandbox, SandboxConfig, } from "./sandbox/index";
 export { createSandbox, DEFAULT_DAEMON_SANDBOX_CONFIG, DEFAULT_FORBIDDEN_GLOBS, DEFAULT_SANDBOX_CONFIG, getSandbox, inSandbox, PERMISSIVE_SANDBOX_CONFIG, } from "./sandbox/index";
 export type { LoadSkillsOptions, Skill, SkillLoadResult, SkillLoadWarning, SkillMetadata, SkillRegistry, } from "./skills/index";
 export { buildSkillsPromptHeader, createSkillRegistry, loadSkills, } from "./skills/index";
-export type { AgentDef, AgentStep, BroadcastFlowDef, BuiltInToolName, CommaProjectManifest, CycleFlowDef, DiscoveredStrategy, DiscoveredStrategyOrigin, DiscoverStrategiesOptions, DiscoverStrategiesResult, DiscoveryWarning, ExportStrategyOptions, FlowDef, LLMAgentDef, LoadedProject, LoadedStrategy, LoadStrategyOptions, SequentialFlowDef, Strategy, UserAgentDef, } from "./strategy/index";
-export { CommaProjectManifestSchema, discoverStrategies, exportStrategy, isAgentStep, isFlowDef, isLLMAgentDef, isUserAgentDef, loadProject, loadStrategy, loadStrategyFromString, readStrategyFile, StrategySchema, } from "./strategy/index";
+export type { AgentDef, AgentStep, BroadcastFlowDef, BuiltInToolName, CustomAgentDef, CustomFlowDef, CycleFlowDef, DiscoveredStrategy, DiscoveredStrategyOrigin, DiscoverStrategiesOptions, DiscoverStrategiesResult, DiscoveryWarning, ExportStrategyOptions, FlowDef, LLMAgentDef, LoadedProject, LoadedStrategy, LoadStrategyOptions, SequentialFlowDef, Strategy, UserAgentDef, } from "./strategy/index";
+export { CustomAgentDefSchema, CustomFlowDefSchema, discoverStrategies, exportStrategy, isAgentStep, isCustomAgentDef, isFlowDef, isLLMAgentDef, isUserAgentDef, loadProject, loadStrategy, loadStrategyFromString, readStrategyFile, StrategySchema, } from "./strategy/index";
 export type { ProjectedConversationContext, Timeline, TimelineEvent, TimelineFilter, } from "./timeline/index";
 export { createTimeline, projectConversationContext, projectFileState, } from "./timeline/index";
 export { buildToolSystemPrompt, mergeSystemPrompts, } from "./tools/build-tool-system-prompt";