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

package/dist/flows/loader/loader.schema.d.ts

@@ -1,195 +1,2 @@
-import { z } from "zod";
-/**
- * A step that references a named agent from the caller-provided registry.
- *
- * @example
- * ```yaml
- * steps:
- *   - agent: researcher
- *   - agent: writer
- * ```
- */
-export declare const AgentStepDescriptionSchema: z.ZodObject<{
-    /** Name of the agent in the caller-provided registry. */
-    agent: z.ZodString;
-    /** Optional human-readable description of this step. */
-    description: z.ZodOptional<z.ZodString>;
-}, "strict", z.ZodTypeAny, {
-    agent: string;
-    description?: string | undefined;
-}, {
-    agent: string;
-    description?: string | undefined;
-}>;
-/**
- * A step that is a nested flow definition (recursive).
- * Uses `z.lazy()` to support arbitrarily deep nesting.
- */
-export declare const FlowStepDescriptionSchema: z.ZodType;
-/** Sequential flow — pipeline where each step receives the previous step's output. */
-export declare const SequentialFlowDescriptionSchema: z.ZodObject<{
-    type: z.ZodLiteral<"sequential">;
-    /** Unique name for this flow. */
-    name: z.ZodString;
-    /** Optional human-readable description. */
-    description: z.ZodOptional<z.ZodString>;
-    /** Steps to execute — agent references or nested flow definitions. */
-    steps: z.ZodArray<z.ZodType<any, z.ZodTypeDef, any>, "many">;
-}, "strict", z.ZodTypeAny, {
-    type: "sequential";
-    name: string;
-    steps: any[];
-    description?: string | undefined;
-}, {
-    type: "sequential";
-    name: string;
-    steps: any[];
-    description?: string | undefined;
-}>;
-/** Cycle flow — repeating pipeline with optional observer and cycle count. */
-export declare const CycleFlowDescriptionSchema: z.ZodObject<{
-    type: z.ZodLiteral<"cycle">;
-    /**
-     * Number of cycle iterations. Use `"Infinity"` for infinite loops.
-     * @default 1
-     */
-    cycles: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodLiteral<"Infinity">]>>;
-    /** Name of an observer agent that runs after each cycle. */
-    observer: z.ZodOptional<z.ZodString>;
-    /** Unique name for this flow. */
-    name: z.ZodString;
-    /** Optional human-readable description. */
-    description: z.ZodOptional<z.ZodString>;
-    /** Steps to execute — agent references or nested flow definitions. */
-    steps: z.ZodArray<z.ZodType<any, z.ZodTypeDef, any>, "many">;
-}, "strict", z.ZodTypeAny, {
-    type: "cycle";
-    name: string;
-    steps: any[];
-    description?: string | undefined;
-    cycles?: number | "Infinity" | undefined;
-    observer?: string | undefined;
-}, {
-    type: "cycle";
-    name: string;
-    steps: any[];
-    description?: string | undefined;
-    cycles?: number | "Infinity" | undefined;
-    observer?: string | undefined;
-}>;
-/** Broadcast flow — fan-out where all steps receive the same message. */
-export declare const BroadcastFlowDescriptionSchema: z.ZodObject<{
-    type: z.ZodLiteral<"broadcast">;
-    /**
-     * Separator used to join step responses.
-     * @default "\n\n"
-     */
-    separator: z.ZodOptional<z.ZodString>;
-    /** Unique name for this flow. */
-    name: z.ZodString;
-    /** Optional human-readable description. */
-    description: z.ZodOptional<z.ZodString>;
-    /** Steps to execute — agent references or nested flow definitions. */
-    steps: z.ZodArray<z.ZodType<any, z.ZodTypeDef, any>, "many">;
-}, "strict", z.ZodTypeAny, {
-    type: "broadcast";
-    name: string;
-    steps: any[];
-    description?: string | undefined;
-    separator?: string | undefined;
-}, {
-    type: "broadcast";
-    name: string;
-    steps: any[];
-    description?: string | undefined;
-    separator?: string | undefined;
-}>;
-/**
- * Flow description schema — validates a standalone flow description file.
- *
- * Discriminated union on `type` supporting sequential, cycle, and broadcast flows.
- *
- * @example
- * ```yaml
- * name: code-review
- * type: sequential
- * steps:
- *   - agent: writer
- *   - agent: reviewer
- *   - agent: editor
- * ```
- */
-export declare const FlowDescriptionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
-    type: z.ZodLiteral<"sequential">;
-    /** Unique name for this flow. */
-    name: z.ZodString;
-    /** Optional human-readable description. */
-    description: z.ZodOptional<z.ZodString>;
-    /** Steps to execute — agent references or nested flow definitions. */
-    steps: z.ZodArray<z.ZodType<any, z.ZodTypeDef, any>, "many">;
-}, "strict", z.ZodTypeAny, {
-    type: "sequential";
-    name: string;
-    steps: any[];
-    description?: string | undefined;
-}, {
-    type: "sequential";
-    name: string;
-    steps: any[];
-    description?: string | undefined;
-}>, z.ZodObject<{
-    type: z.ZodLiteral<"cycle">;
-    /**
-     * Number of cycle iterations. Use `"Infinity"` for infinite loops.
-     * @default 1
-     */
-    cycles: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodLiteral<"Infinity">]>>;
-    /** Name of an observer agent that runs after each cycle. */
-    observer: z.ZodOptional<z.ZodString>;
-    /** Unique name for this flow. */
-    name: z.ZodString;
-    /** Optional human-readable description. */
-    description: z.ZodOptional<z.ZodString>;
-    /** Steps to execute — agent references or nested flow definitions. */
-    steps: z.ZodArray<z.ZodType<any, z.ZodTypeDef, any>, "many">;
-}, "strict", z.ZodTypeAny, {
-    type: "cycle";
-    name: string;
-    steps: any[];
-    description?: string | undefined;
-    cycles?: number | "Infinity" | undefined;
-    observer?: string | undefined;
-}, {
-    type: "cycle";
-    name: string;
-    steps: any[];
-    description?: string | undefined;
-    cycles?: number | "Infinity" | undefined;
-    observer?: string | undefined;
-}>, z.ZodObject<{
-    type: z.ZodLiteral<"broadcast">;
-    /**
-     * Separator used to join step responses.
-     * @default "\n\n"
-     */
-    separator: z.ZodOptional<z.ZodString>;
-    /** Unique name for this flow. */
-    name: z.ZodString;
-    /** Optional human-readable description. */
-    description: z.ZodOptional<z.ZodString>;
-    /** Steps to execute — agent references or nested flow definitions. */
-    steps: z.ZodArray<z.ZodType<any, z.ZodTypeDef, any>, "many">;
-}, "strict", z.ZodTypeAny, {
-    type: "broadcast";
-    name: string;
-    steps: any[];
-    description?: string | undefined;
-    separator?: string | undefined;
-}, {
-    type: "broadcast";
-    name: string;
-    steps: any[];
-    description?: string | undefined;
-    separator?: string | undefined;
-}>]>;
-export type FlowDescription = z.infer<typeof FlowDescriptionSchema>;
+export type { FlowDef as FlowDescription } from "../../strategy/schema";
+export { AgentStepSchema as AgentStepDescriptionSchema, BroadcastFlowDefSchema as BroadcastFlowDescriptionSchema, CustomFlowDefSchema as CustomFlowDescriptionSchema, CycleFlowDefSchema as CycleFlowDescriptionSchema, FlowDefSchema as FlowDescriptionSchema, FlowStepSchema as FlowStepDescriptionSchema, SequentialFlowDefSchema as SequentialFlowDescriptionSchema, } from "../../strategy/schema";

package/dist/flows/loader/loader.utils.d.ts

@@ -0,0 +1,5 @@
+import type { Agent } from "../../agents/agent/agent.types";
+import type { FlowDef } from "../../strategy/schema";
+import type { LoadFlowOptions } from "./loader.types";
+/** Build a validated declarative flow tree into a runnable agent. */
+export declare function buildFlowFromDescription(description: FlowDef, options: LoadFlowOptions): Agent;

package/dist/flows/registry/flow-registry.constants.d.ts

@@ -0,0 +1 @@
+export declare const BUILT_IN_FLOW_NAMES: readonly ["sequential", "cycle", "broadcast"];

package/dist/flows/registry/flow-registry.d.ts

@@ -0,0 +1,45 @@
+import type { z } from "zod";
+import type { FlowTypeDefinition, RegisteredFlowFactory } from "./flow-registry.types";
+/**
+ * Preserve schema inference when declaring a reusable custom flow type.
+ *
+ * @param definition - Configuration schema and factory for the custom flow.
+ * @returns The unchanged flow definition, with inferred configuration types.
+ * @example
+ * ```ts
+ * const firstMatchFlow = defineFlowType({
+ *   configSchema: z.object({ marker: z.string() }),
+ *   create: ({ name, steps, config }) => createFlow({
+ *     name,
+ *     steps,
+ *     execute: async (availableSteps, message, flowContext) => {
+ *       for (const step of availableSteps) {
+ *         const result = await flowContext.runStep(step, message);
+ *         if (result.text.includes(config.marker)) return result.text;
+ *       }
+ *       return message;
+ *     },
+ *   }),
+ * });
+ * ```
+ */
+export declare function defineFlowType<ConfigSchema extends z.ZodTypeAny>(definition: FlowTypeDefinition<ConfigSchema>): FlowTypeDefinition<ConfigSchema>;
+/**
+ * Register a custom flow type for use in strategy and standalone flow files.
+ *
+ * @param name - Value referenced by a declarative flow's `type` field.
+ * @param definition - Configuration schema and factory for the custom flow.
+ * @example
+ * ```ts
+ * registerFlow("first-match", firstMatchFlow);
+ * ```
+ */
+export declare function registerFlow<ConfigSchema extends z.ZodTypeAny>(name: string, definition: FlowTypeDefinition<ConfigSchema>): void;
+/** Remove a custom flow registration. Built-in flow types remain available. */
+export declare function unregisterFlow(name: string): boolean;
+/** Return the currently registered custom flow type names. */
+export declare function getRegisteredFlowNames(): readonly string[];
+/** @internal Resolve a custom flow factory by type name. */
+export declare function resolveRegisteredFlow(name: string): RegisteredFlowFactory | undefined;
+/** Reset custom flow registrations. Primarily intended for test isolation. */
+export declare function resetFlowRegistry(): void;

package/dist/flows/registry/flow-registry.types.d.ts

@@ -0,0 +1,31 @@
+import type { z } from "zod";
+import type { Agent } from "../../agents/agent/agent.types";
+/** Context passed to a registered custom flow factory. */
+export interface FlowTypeContext<Config> {
+    /** Name declared for this flow instance. */
+    readonly name: string;
+    /** Agent and nested-flow steps declared for this flow instance. */
+    readonly steps: ReadonlyArray<Agent>;
+    /** Custom configuration validated by the flow type's schema. */
+    readonly config: Config;
+    /** Resolve another named agent from the strategy or standalone loader registry. */
+    readonly resolveAgent: (name: string) => Agent;
+}
+/** Definition used to validate and construct a reusable declarative flow type. */
+export interface FlowTypeDefinition<ConfigSchema extends z.ZodTypeAny> {
+    /** Schema for the flow definition's `config` object. */
+    readonly configSchema: ConfigSchema;
+    /** Create a runnable flow from resolved steps and validated configuration. */
+    readonly create: (context: FlowTypeContext<z.output<ConfigSchema>>) => Agent;
+}
+/** @internal Unvalidated context used by the declarative flow loader. */
+export interface RegisteredFlowContext {
+    readonly name: string;
+    readonly steps: ReadonlyArray<Agent>;
+    readonly config: unknown;
+    readonly resolveAgent: (name: string) => Agent;
+}
+/** @internal Type-erased registered factory used after registration. */
+export interface RegisteredFlowFactory {
+    readonly create: (context: RegisteredFlowContext) => Agent;
+}

package/dist/flows/registry/index.d.ts

@@ -0,0 +1,2 @@
+export { defineFlowType, getRegisteredFlowNames, registerFlow, resetFlowRegistry, unregisterFlow, } from "./flow-registry";
+export type { FlowTypeContext, FlowTypeDefinition, } from "./flow-registry.types";

package/dist/hub/archive/archive.d.ts

@@ -0,0 +1,2 @@
+/** Extract one Hub package from a compressed repository archive. */
+export declare function extractHubPackageArchive(compressedArchive: Uint8Array, packageName: string, destination: string): Promise<void>;

package/dist/hub/archive/index.d.ts

@@ -0,0 +1 @@
+export { extractHubPackageArchive } from "./archive";

package/dist/hub/comma-project.schema.json

@@ -0,0 +1,171 @@
+{
+  "$ref": "#/definitions/CommaProjectManifest",
+  "definitions": {
+    "CommaProjectManifest": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^@[a-z0-9][a-z0-9-]*\\/[a-z0-9][a-z0-9-]*$"
+        },
+        "version": {
+          "type": "string",
+          "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-]+)*)?$"
+        },
+        "description": {
+          "type": "string"
+        },
+        "license": {
+          "type": "string"
+        },
+        "author": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string",
+              "minLength": 1
+            },
+            "email": {
+              "type": "string",
+              "format": "email"
+            },
+            "url": {
+              "type": "string",
+              "format": "uri"
+            }
+          },
+          "required": [
+            "name"
+          ],
+          "additionalProperties": false
+        },
+        "contributors": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/CommaProjectManifest/properties/author"
+          }
+        },
+        "keywords": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "strategies": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string",
+                "minLength": 1
+              },
+              "expose": {
+                "type": "boolean"
+              },
+              "description": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "path"
+            ],
+            "additionalProperties": false
+          },
+          "propertyNames": {
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          }
+        },
+        "agents": {
+          "$ref": "#/definitions/CommaProjectManifest/properties/strategies"
+        },
+        "flows": {
+          "$ref": "#/definitions/CommaProjectManifest/properties/strategies"
+        },
+        "tools": {
+          "$ref": "#/definitions/CommaProjectManifest/properties/strategies"
+        },
+        "entry": {
+          "type": "string",
+          "minLength": 1
+        },
+        "dependencies": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "environment": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "description": {
+                "type": "string"
+              },
+              "required": {
+                "type": "boolean"
+              },
+              "default": {
+                "type": "string"
+              },
+              "example": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          },
+          "propertyNames": {
+            "pattern": "^[A-Z_][A-Z0-9_]*$"
+          }
+        },
+        "permissions": {
+          "type": "object",
+          "properties": {
+            "network": {
+              "type": "boolean"
+            },
+            "filesystem": {
+              "type": "boolean"
+            },
+            "shell": {
+              "type": "boolean"
+            },
+            "executesCode": {
+              "type": "boolean"
+            }
+          },
+          "additionalProperties": false
+        },
+        "links": {
+          "type": "object",
+          "properties": {
+            "homepage": {
+              "type": "string",
+              "format": "uri"
+            },
+            "repository": {
+              "type": "string",
+              "format": "uri"
+            },
+            "docs": {
+              "type": "string",
+              "format": "uri"
+            },
+            "issues": {
+              "type": "string",
+              "format": "uri"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "name",
+        "version"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/dist/hub/hub.constants.d.ts

@@ -0,0 +1,5 @@
+import type { HubRepositoryConfig } from "./hub.types";
+export declare const DEFAULT_HUB_REPOSITORY: HubRepositoryConfig;
+export declare const HUB_MAX_FILES = 2000;
+export declare const HUB_MAX_UNCOMPRESSED_BYTES: number;
+export declare const HUB_INSTALLED_STATE_FILENAME = "installed-packages.json";

package/dist/hub/hub.d.ts

@@ -0,0 +1,13 @@
+import type { CreateHubManagerOptions, HubManager } from "./hub.types";
+/**
+ * Create a manager for discovering, installing, updating, and removing Hub packages.
+ *
+ * @param options - Optional data directory, repository, and fetch implementation.
+ * @example
+ * ```ts
+ * const hub = createHubManager();
+ * const packages = await hub.listAvailable();
+ * await hub.install(packages[0].name);
+ * ```
+ */
+export declare function createHubManager(options?: CreateHubManagerOptions): HubManager;