@comma-agents/core 2.0.0-rc.0

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

@@ -0,0 +1,55 @@
+import type { Agent } from "../../agents/agent/agent.types";
+import type { LoadFlowOptions } from "./loader.types";
+/**
+ * Load a single flow from a JSON or YAML description file.
+ *
+ * Auto-detects format by file extension (`.json`, `.yaml`, `.yml`).
+ * Validates the structure, resolves agent references from the provided
+ * registry, and returns a live `Agent` (flow) ready to call.
+ *
+ * @param filePath - Absolute or relative path to the flow description file.
+ * @param options  - Agent registry and optional hooks.
+ * @returns A live Agent implementing the flow.
+ * @throws {StrategyValidationError} If the file is invalid or missing required fields.
+ *
+ * @example
+ * ```ts
+ * import { loadAgent, loadFlow } from "@comma-agents/core";
+ *
+ * const writer = await loadAgent("./agents/writer.yaml");
+ * const reviewer = await loadAgent("./agents/reviewer.yaml");
+ *
+ * const flow = await loadFlow("./flows/review-pipeline.yaml", {
+ *   agents: { writer, reviewer },
+ * });
+ * const result = await flow.call("Write a function that adds two numbers");
+ * ```
+ */
+export declare function loadFlow(filePath: string, options: LoadFlowOptions): Promise<Agent>;
+/**
+ * Load a single flow from a raw JSON or YAML string.
+ *
+ * Useful when the content is already in memory (e.g., received over
+ * a WebSocket, from a database, or from a test fixture).
+ *
+ * @param content - The raw flow description string.
+ * @param format  - "json" or "yaml".
+ * @param options - Agent registry and optional hooks.
+ * @returns A live Agent implementing the flow.
+ * @throws {StrategyValidationError} If parsing or validation fails.
+ *
+ * @example
+ * ```ts
+ * const yaml = `
+ * name: review-pipeline
+ * type: sequential
+ * steps:
+ *   - agent: writer
+ *   - agent: reviewer
+ * `;
+ * const flow = loadFlowFromString(yaml, "yaml", {
+ *   agents: { writer, reviewer },
+ * });
+ * ```
+ */
+export declare function loadFlowFromString(content: string, format: "json" | "yaml", options: LoadFlowOptions): Agent;

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

@@ -0,0 +1,195 @@
+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>;

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

@@ -0,0 +1,27 @@
+import type { Agent } from "../../agents/agent/agent.types";
+import type { FlowHooks } from "../flow/flow.types";
+/**
+ * Options for loading a flow from a description file.
+ *
+ * The `agents` registry is required — it maps agent names referenced in
+ * the flow steps to live `Agent` instances. Agents can be created via
+ * `createAgent()`, `loadAgent()`, or any other factory.
+ *
+ * @example
+ * ```ts
+ * import { loadAgent, loadFlow } from "@comma-agents/core";
+ *
+ * const writer = await loadAgent("./agents/writer.yaml");
+ * const reviewer = await loadAgent("./agents/reviewer.yaml");
+ *
+ * const flow = await loadFlow("./flows/review-pipeline.yaml", {
+ *   agents: { writer, reviewer },
+ * });
+ * ```
+ */
+export interface LoadFlowOptions {
+    /** Registry of named agents that steps can reference. */
+    readonly agents: Readonly<Record<string, Agent>>;
+    /** Optional hooks to inject into the loaded flow. */
+    readonly flowHooks?: FlowHooks;
+}

package/dist/guard/guard.d.ts

@@ -0,0 +1,17 @@
+import type { SandboxTrashMetadata } from "../tools/io/trash";
+import type { Guard, GuardCallbacks, Policy } from "./guard.types";
+/**
+ * Create a per-tool Guard instance.
+ *
+ * The guard resolves paths, enforces the jail boundary, evaluates the
+ * policy chain, dispatches "ask" via the callbacks, and self-updates
+ * session memory when the user grants/denies access.
+ *
+ * @param toolName - The tool this guard enforces.
+ * @param cwd - Workspace root for path resolution.
+ * @param allowAbsolutePaths - Whether absolute input paths are allowed.
+ * @param jail - Whether to enforce the cwd boundary.
+ * @param policies - Initial policy chain.
+ * @param callbacks - onAsk / onPolicyChange handlers (shared across guards).
+ */
+export declare function createGuard(toolName: string, cwd: string, allowAbsolutePaths: boolean, jail: boolean, policies: readonly Policy[], callbacks?: GuardCallbacks, trashMetadata?: SandboxTrashMetadata): Guard;

package/dist/guard/guard.types.d.ts

@@ -0,0 +1,112 @@
+import type { PermissionDecision, PermissionOperation } from "../sandbox/sandbox.types";
+import type { SandboxTrashMetadata } from "../tools/io/trash";
+/** Closed set of access categories that a tool can request. */
+export type AccessType = "fs.read" | "fs.write" | "command.execute";
+/** Describes what a tool wants to do. Evaluated against the guard's policy chain. */
+export interface AccessRequest {
+    /** Category of access: file read, file write, or command execution. */
+    readonly type: AccessType;
+    /** The path, command, or other resource being accessed. */
+    readonly resource: string;
+}
+/** A policy's evaluation result. "pass" means "skip me, let the next policy decide." */
+export type PolicyDecision = "allow" | "deny" | "ask" | "pass";
+/**
+ * Pure evaluation function — stateless, composable, testable.
+ * Returns "pass" when the policy doesn't handle this request type.
+ */
+export interface Policy {
+    readonly name: string;
+    evaluate(request: AccessRequest): PolicyDecision | Promise<PolicyDecision>;
+}
+/**
+ * Context forwarded by a tool when it calls `guard.authorize()`.
+ */
+export interface AuthorizationContext {
+    readonly agentName: string;
+    readonly toolName: string;
+    readonly signal: AbortSignal;
+}
+/**
+ * Permission request dispatched to the guard's `onAsk` callback when a
+ * policy returns "ask".
+ */
+export interface GuardPermissionRequest {
+    readonly agentName: string;
+    readonly toolName: string;
+    readonly operation: PermissionOperation | AccessType;
+    readonly resource: string;
+    readonly reason: "policy-ask";
+    readonly signal?: AbortSignal;
+}
+/** Snapshot of the guard's current policy chain. */
+export interface GuardPolicySnapshot {
+    readonly toolName: string;
+    readonly policies: ReadonlyArray<{
+        readonly name: string;
+    }>;
+}
+/** Callbacks injected into every guard at creation time. */
+/** Callbacks injected into every guard at creation time. */
+/** Callbacks injected into every guard at creation time. */
+export interface GuardCallbacks {
+    /**
+     * Called when the policy chain returns "ask". Returns the user's decision.
+     * If absent and a policy returns "ask", the guard fails-closed.
+     */
+    readonly onAsk?: (request: GuardPermissionRequest) => Promise<PermissionDecision>;
+    /**
+     * Called whenever the guard's policy chain changes (addPolicy/removePolicy
+     * or session-memory self-update). The snapshot includes the tool name and
+     * the ordered policy chain.
+     */
+    readonly onPolicyChange?: (snapshot: GuardPolicySnapshot) => void;
+    /**
+     * Called when a tool requests direct user input/feedback.
+     */
+    readonly onQuestion?: (request: {
+        readonly agentName: string;
+        readonly toolName: string;
+        readonly question: string;
+    }) => Promise<string>;
+}
+/**
+ * Per-tool enforcement engine.
+ *
+ * Created lazily by the Sandbox for each tool. Handles path resolution,
+ * jail enforcement, policy chain evaluation, "ask" dispatch, and
+ * self-updating session memory.
+ */
+export interface Guard {
+    /** The tool this guard enforces. */
+    readonly toolName: string;
+    /** Workspace root for path resolution. */
+    readonly cwd: string;
+    /** Trash metadata for archive identification (runId, sessionId). */
+    readonly trashMetadata?: SandboxTrashMetadata;
+    /** Trash metadata for archive identification (runId, sessionId). */
+    readonly trashMetadata?: SandboxTrashMetadata;
+    /**
+     * Full authorization through the policy chain.
+     * Resolves the path, checks jail, evaluates policies, dispatches "ask"
+     * if needed. Returns the resolved absolute path on success.
+     *
+     * @throws {SandboxViolationError} on deny, jail escape, or forbidden glob.
+     */
+    authorize(request: AccessRequest, ctx: AuthorizationContext): Promise<string>;
+    /**
+     * Non-throwing inspection. Returns false when the policy chain would deny.
+     * Never dispatches "ask" — treats "ask" the same as "deny".
+     */
+    canAccess(request: AccessRequest): boolean;
+    /** Insert a policy into the chain, optionally before a named policy. */
+    addPolicy(policy: Policy, before?: string): void;
+    /** Remove a policy by name. Returns true if it was found and removed. */
+    removePolicy(name: string): boolean;
+    /** Snapshot of the current policy chain for broadcasting. */
+    getPolicies(): GuardPolicySnapshot;
+    /** Subscribe to policy chain changes. Returns an unsubscribe function. */
+    onPolicyChange(listener: (snapshot: GuardPolicySnapshot) => void): () => void;
+    /** Ask the user a question / prompt for interactive feedback. */
+    askQuestion(question: string, ctx: AuthorizationContext): Promise<string>;
+}

package/dist/guard/index.d.ts

@@ -0,0 +1,3 @@
+export { createGuard } from "./guard";
+export type { AccessRequest, AccessType, AuthorizationContext, Guard, GuardCallbacks, GuardPermissionRequest, GuardPolicySnapshot, Policy, PolicyDecision, } from "./guard.types";
+export { approveCommandsPolicy, buildDefaultPolicies, denyCommandsPolicy, forbiddenGlobsPolicy, pathPolicy, } from "./policies";

package/dist/guard/policies.d.ts

@@ -0,0 +1,28 @@
+import type { PathPolicy } from "../sandbox/sandbox.types";
+import type { Policy } from "./guard.types";
+/**
+ * Unconditionally deny paths matching secret/sensitive glob patterns.
+ * Runs before read/write policies; cannot be overridden.
+ */
+export declare function forbiddenGlobsPolicy(globs: readonly string[], cwd: string): Policy;
+/**
+ * deny > allow > default for a class of file-system operations.
+ * Respects the evaluation order: deny wins over allow, allow wins over default.
+ */
+export declare function pathPolicy(mode: "read" | "write", config: PathPolicy | undefined, cwd: string): Policy;
+/**
+ * Always-deny specific commands (regex patterns).
+ * Runs during the guard's policy chain for "command.execute" requests.
+ */
+export declare function denyCommandsPolicy(patterns: readonly string[]): Policy;
+/**
+ * Ask (prompt the user) for commands matching approval patterns.
+ * Returns "ask" when a command matches; the guard's onAsk callback handles the prompt.
+ */
+export declare function approveCommandsPolicy(patterns: readonly string[]): Policy;
+/**
+ * Build the default policy chain for a new guard.
+ * Order: forbiddenGlobs → readPath → writePath.
+ * Tool-specific policies should be added after these.
+ */
+export declare function buildDefaultPolicies(forbiddenGlobs: readonly string[], read: PathPolicy | undefined, write: PathPolicy | undefined, cwd: string): Policy[];

package/dist/hooks/built-in/token-tracking/index.d.ts

@@ -0,0 +1,2 @@
+export { createTokenTracker, useTokenTracking } from "./token-tracking";
+export type { ModelMetadata, TokenSnapshot, TokenTracker, TokenTrackerConfig, TokenUsageRecord, UseTokenTrackingConfig, } from "./token-tracking.types";

package/dist/hooks/built-in/token-tracking/token-tracking.constants.d.ts

@@ -0,0 +1,14 @@
+import type { ModelMetadata } from "./token-tracking.types";
+/**
+ * Built-in model catalog mapping model identifiers to context window metadata.
+ *
+ * TODO: Determine if this can be queried somehow to have a more generalized
+ * way of getting this data.
+ *
+ * Keys are `"providerID/modelID"` strings matching the strategy model format.
+ * Values are frozen ModelMetadata objects.
+ *
+ * This catalog covers widely-used models. For models not listed, pass
+ * `modelMetadata` explicitly to `createTokenTracker()`.
+ */
+export declare const MODEL_CATALOG: Readonly<Record<string, ModelMetadata>>;

package/dist/hooks/built-in/token-tracking/token-tracking.d.ts

@@ -0,0 +1,87 @@
+import type { Agent } from "../../../agents/agent/agent.types";
+import type { TokenTracker, TokenTrackerConfig, UseTokenTrackingConfig } from "./token-tracking.types";
+/**
+ * Create a new token usage tracker.
+ *
+ * The tracker accumulates real token counts from the AI SDK (not estimates).
+ * When model metadata is available (via the built-in catalog or explicit config),
+ * snapshots include context budget information.
+ *
+ * Typically you should use the higher-level `useTokenTracking()` hook, which
+ * creates a tracker, auto-detects the model, and installs the `afterCallResult`
+ * hook on the agent automatically. Use `createTokenTracker()` directly when you
+ * need a standalone tracker or want full control over hook wiring.
+ *
+ * @example
+ * ```ts
+ * import { useTokenTracking } from "@comma-agents/core";
+ *
+ * // Recommended: auto-detects model from agent config
+ * const tracker = useTokenTracking(agent);
+ *
+ * await agent.call("Hello");
+ * const snap = tracker.snapshot();
+ * console.log(`${snap.totalTokens} tokens used`);
+ * console.log(`Context ${(snap.contextUsagePercent! * 100).toFixed(1)}% full`);
+ * console.log(`${snap.contextRemaining} tokens remaining`);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With explicit metadata for a model not in the catalog
+ * const tracker = createTokenTracker({
+ *   modelMetadata: { contextWindow: 32_000, maxOutputTokens: 4_096 },
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Without model metadata — usage tracking only, no budget info
+ * const tracker = createTokenTracker({});
+ * ```
+ */
+export declare function createTokenTracker(config?: TokenTrackerConfig): TokenTracker;
+/**
+ * Hook token tracking into an agent.
+ *
+ * Creates a `TokenTracker`, installs an `afterCallResult` hook on the agent
+ * that records token usage after each call, and returns the tracker.
+ *
+ * The model's context window metadata is resolved in this order:
+ * 1. Explicit `config.modelMetadata` (if provided)
+ * 2. Explicit `config.model` string (catalog lookup)
+ * 3. Auto-detected from `agent.config.model` (already a "providerID/modelID" string)
+ *
+ * @param agent - An agent created by `createAgent()`.
+ * @param config - Optional configuration to override model detection.
+ * @returns A `TokenTracker` that accumulates usage from subsequent agent calls.
+ *
+ * @example
+ * ```ts
+ * import { createAgent, useTokenTracking } from "@comma-agents/core";
+ *
+ * const agent = createAgent({
+ *   name: "writer",
+ *   model: "openai/gpt-4o",
+ *   systemPrompt: "You are helpful.",
+ * });
+ *
+ * // Auto-detects model, looks up catalog for context window info
+ * const tracker = useTokenTracking(agent);
+ *
+ * await agent.call("Hello");
+ * const snap = tracker.snapshot();
+ * console.log(`Used ${snap.totalTokens} tokens`);
+ * console.log(`Context ${(snap.contextUsagePercent! * 100).toFixed(1)}% full`);
+ * console.log(`${snap.contextRemaining} tokens remaining`);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Explicit metadata for a model not in the catalog
+ * const tracker = useTokenTracking(agent, {
+ *   modelMetadata: { contextWindow: 32_000, maxOutputTokens: 4_096 },
+ * });
+ * ```
+ */
+export declare function useTokenTracking(agent: Agent, config?: UseTokenTrackingConfig): TokenTracker;