agent-framework-js 0.1.1

package/dist/workflows/index.d.cts

@@ -0,0 +1,182 @@
+import { A as Agent } from '../index-DdYZeNIu.cjs';
+import '../types-Cn1g9Tg4.cjs';
+import '../errors-CjVz4W_5.cjs';
+import '../provider-CMAymr1b.cjs';
+import '../tool-BZg_znMZ.cjs';
+import '../skill-DfNChtJN.cjs';
+import '../thread-Dfo9LLf7.cjs';
+import '../registry-D4fThGiN.cjs';
+
+/**
+ * Bounded-concurrency execution with a configurable failure policy for concurrent
+ * workflows. Fail-soft (default) aggregates partial results; fail-fast cancels
+ * remaining work on the first failure. (FR-019b, FR-019c)
+ *
+ * @packageDocumentation
+ */
+/** How concurrent branches react to a failure. */
+type FailurePolicy = "fail-soft" | "fail-fast";
+/** Per-branch outcome under fail-soft. */
+interface BranchResult<T> {
+    index: number;
+    value?: T;
+    error?: Error;
+}
+/**
+ * Run `tasks` with at most `maxConcurrency` in flight (-1 = unlimited).
+ *
+ * - `fail-soft`: every branch runs; failures are captured per-branch.
+ * - `fail-fast`: the first failure rejects and remaining branches are abandoned.
+ *
+ * @returns Per-branch results (always, including under fail-fast where the failing
+ *   branch carries the error). Under fail-fast this throws on first failure.
+ */
+declare function runBounded<T>(tasks: Array<() => Promise<T>>, maxConcurrency: number, policy: FailurePolicy): Promise<Array<BranchResult<T>>>;
+
+/**
+ * Orchestration patterns: sequential, concurrent, handoff, and group collaboration.
+ * Each pattern advances a {@link WorkflowContext} by one round and reports whether
+ * the workflow is complete. (FR-019)
+ *
+ * @packageDocumentation
+ */
+
+/** Supported orchestration patterns. */
+type WorkflowPattern = "sequential" | "concurrent" | "handoff" | "group";
+/** Mutable state threaded through pattern execution. */
+interface WorkflowContext {
+    /** Latest combined output. */
+    output: string;
+    /** Per-agent latest outputs (by agent name). */
+    outputs: Record<string, string>;
+    /** Current round (0-based). */
+    round: number;
+    /** Index of the next agent (handoff/sequential). */
+    cursor: number;
+    /** Names of agents that errored this run (fail-soft). */
+    errors: Record<string, string>;
+}
+/** Hooks customizing pattern behavior. */
+interface PatternHooks {
+    /** Returns true when an output signals the workflow is complete. (FR-019a) */
+    isComplete?: (output: string, ctx: WorkflowContext) => boolean;
+    /** For handoff: choose the next agent name from the latest output (or null to stop). */
+    selectNext?: (output: string, ctx: WorkflowContext) => string | null;
+    maxConcurrency?: number;
+    failurePolicy?: FailurePolicy;
+}
+/** One step's result. */
+interface StepResult {
+    complete: boolean;
+}
+/** Advance a sequential workflow by one agent. */
+declare function stepSequential(agents: Agent[], ctx: WorkflowContext, input: string, hooks: PatternHooks): Promise<StepResult>;
+/** Run all agents concurrently on the same input and aggregate outputs. */
+declare function stepConcurrent(agents: Agent[], ctx: WorkflowContext, input: string, hooks: PatternHooks): Promise<StepResult>;
+/** Advance a handoff workflow: the current agent may delegate to another. */
+declare function stepHandoff(agents: Agent[], ctx: WorkflowContext, input: string, hooks: PatternHooks): Promise<StepResult>;
+/** Group collaboration: every agent contributes each round until complete. */
+declare function stepGroup(agents: Agent[], ctx: WorkflowContext, input: string, hooks: PatternHooks): Promise<StepResult>;
+
+/**
+ * Workflow checkpointing. A checkpoint is a serializable snapshot enabling resume.
+ * Restore fails closed: corrupt or version-mismatched data yields a typed
+ * {@link CheckpointError} with no partial restore. (FR-022, FR-022a)
+ *
+ * @packageDocumentation
+ */
+/** Current checkpoint schema version. */
+declare const CHECKPOINT_VERSION = "1";
+/** A serializable workflow snapshot. */
+interface Checkpoint {
+    version: string;
+    id: string;
+    /** Opaque workflow state (round, messages, pending node, etc.). */
+    state: Record<string, unknown>;
+}
+/** Create a checkpoint with the current schema version. */
+declare function createCheckpoint(id: string, state: Record<string, unknown>): Checkpoint;
+/** Serialize a checkpoint to a string. */
+declare function serializeCheckpoint(cp: Checkpoint): string;
+/**
+ * Restore a checkpoint from its serialized form or object. Fails closed.
+ *
+ * @throws {CheckpointError} `corrupt` if the data cannot be parsed/validated.
+ * @throws {CheckpointError} `version-mismatch` if the schema version differs.
+ */
+declare function restoreCheckpoint(input: string | Checkpoint): Checkpoint;
+
+/**
+ * The workflow engine: composes agents under an orchestration pattern with a
+ * completion signal and a configurable max-rounds safety cap, bounded concurrency,
+ * a failure policy, streaming, human-in-the-loop yield/resume, and checkpointing.
+ * (FR-018, FR-019, FR-019a, FR-019b, FR-019c, FR-020, FR-021, FR-021a, FR-021b, FR-022)
+ *
+ * @packageDocumentation
+ */
+
+/** Lifecycle status of a workflow run, observable by the host. (FR-021b) */
+type WorkflowStatus = "running" | "awaiting-input" | "completed" | "failed";
+/** Configuration for {@link createWorkflow}. */
+interface WorkflowConfig {
+    pattern: WorkflowPattern;
+    agents: Agent[];
+    /** Max rounds; -1 = unlimited. Default 16. (FR-019a) */
+    maxRounds?: number;
+    /** Concurrent failure policy. Default fail-soft. (FR-019b) */
+    failurePolicy?: FailurePolicy;
+    /** Max parallel agent calls; -1 = unlimited. Default 4. (FR-019c) */
+    maxConcurrency?: number;
+    /** Completion signal: end the workflow when this returns true. (FR-019a) */
+    isComplete?: (output: string, ctx: WorkflowContext) => boolean;
+    /** Handoff target selector. */
+    selectNext?: (output: string, ctx: WorkflowContext) => string | null;
+    /** Human-in-the-loop gate: when it returns a prompt, the workflow yields. (FR-021) */
+    humanInputGate?: (ctx: WorkflowContext) => string | null;
+}
+/** Serializable result/handle of a workflow run. (FR-021a, FR-022) */
+interface WorkflowState {
+    status: WorkflowStatus;
+    output: string;
+    /** Present when status is `awaiting-input`. */
+    awaiting?: {
+        prompt: string;
+    };
+    /** Error message when status is `failed`. */
+    error?: string;
+    /** Snapshot enabling resume. */
+    checkpoint: Checkpoint;
+}
+/** Streamed workflow event. (FR-020) */
+type WorkflowEvent = {
+    type: "round";
+    round: number;
+    output: string;
+} | {
+    type: "awaiting-input";
+    prompt: string;
+    state: WorkflowState;
+} | {
+    type: "done";
+    state: WorkflowState;
+};
+/** A runnable multi-agent workflow. */
+interface Workflow {
+    run(input: string): Promise<WorkflowState>;
+    runStream(input: string): AsyncIterable<WorkflowEvent>;
+    resume(state: WorkflowState, humanInput?: string): Promise<WorkflowState>;
+    status(): WorkflowStatus;
+}
+/**
+ * Create a workflow.
+ *
+ * @example
+ * ```ts
+ * const wf = createWorkflow({ pattern: "sequential", agents: [researcher, summarizer] });
+ * let state = await wf.run("Summarize the notes.");
+ * if (state.status === "awaiting-input") state = await wf.resume(state, "approved");
+ * ```
+ */
+declare function createWorkflow(config: WorkflowConfig): Workflow;
+
+export { type BranchResult, CHECKPOINT_VERSION, type Checkpoint, type FailurePolicy, type PatternHooks, type StepResult, type Workflow, type WorkflowConfig, type WorkflowContext, type WorkflowEvent, type WorkflowPattern, type WorkflowState, type WorkflowStatus, createCheckpoint, createWorkflow, restoreCheckpoint, runBounded, serializeCheckpoint, stepConcurrent, stepGroup, stepHandoff, stepSequential };

package/dist/workflows/index.d.ts

@@ -0,0 +1,182 @@
+import { A as Agent } from '../index-D7-znzrc.js';
+import '../types-Cn1g9Tg4.js';
+import '../errors-CjVz4W_5.js';
+import '../provider-osAtfZ7x.js';
+import '../tool-CSCC87OD.js';
+import '../skill-DfNChtJN.js';
+import '../thread-CWVzTyti.js';
+import '../registry-CpO0yH5v.js';
+
+/**
+ * Bounded-concurrency execution with a configurable failure policy for concurrent
+ * workflows. Fail-soft (default) aggregates partial results; fail-fast cancels
+ * remaining work on the first failure. (FR-019b, FR-019c)
+ *
+ * @packageDocumentation
+ */
+/** How concurrent branches react to a failure. */
+type FailurePolicy = "fail-soft" | "fail-fast";
+/** Per-branch outcome under fail-soft. */
+interface BranchResult<T> {
+    index: number;
+    value?: T;
+    error?: Error;
+}
+/**
+ * Run `tasks` with at most `maxConcurrency` in flight (-1 = unlimited).
+ *
+ * - `fail-soft`: every branch runs; failures are captured per-branch.
+ * - `fail-fast`: the first failure rejects and remaining branches are abandoned.
+ *
+ * @returns Per-branch results (always, including under fail-fast where the failing
+ *   branch carries the error). Under fail-fast this throws on first failure.
+ */
+declare function runBounded<T>(tasks: Array<() => Promise<T>>, maxConcurrency: number, policy: FailurePolicy): Promise<Array<BranchResult<T>>>;
+
+/**
+ * Orchestration patterns: sequential, concurrent, handoff, and group collaboration.
+ * Each pattern advances a {@link WorkflowContext} by one round and reports whether
+ * the workflow is complete. (FR-019)
+ *
+ * @packageDocumentation
+ */
+
+/** Supported orchestration patterns. */
+type WorkflowPattern = "sequential" | "concurrent" | "handoff" | "group";
+/** Mutable state threaded through pattern execution. */
+interface WorkflowContext {
+    /** Latest combined output. */
+    output: string;
+    /** Per-agent latest outputs (by agent name). */
+    outputs: Record<string, string>;
+    /** Current round (0-based). */
+    round: number;
+    /** Index of the next agent (handoff/sequential). */
+    cursor: number;
+    /** Names of agents that errored this run (fail-soft). */
+    errors: Record<string, string>;
+}
+/** Hooks customizing pattern behavior. */
+interface PatternHooks {
+    /** Returns true when an output signals the workflow is complete. (FR-019a) */
+    isComplete?: (output: string, ctx: WorkflowContext) => boolean;
+    /** For handoff: choose the next agent name from the latest output (or null to stop). */
+    selectNext?: (output: string, ctx: WorkflowContext) => string | null;
+    maxConcurrency?: number;
+    failurePolicy?: FailurePolicy;
+}
+/** One step's result. */
+interface StepResult {
+    complete: boolean;
+}
+/** Advance a sequential workflow by one agent. */
+declare function stepSequential(agents: Agent[], ctx: WorkflowContext, input: string, hooks: PatternHooks): Promise<StepResult>;
+/** Run all agents concurrently on the same input and aggregate outputs. */
+declare function stepConcurrent(agents: Agent[], ctx: WorkflowContext, input: string, hooks: PatternHooks): Promise<StepResult>;
+/** Advance a handoff workflow: the current agent may delegate to another. */
+declare function stepHandoff(agents: Agent[], ctx: WorkflowContext, input: string, hooks: PatternHooks): Promise<StepResult>;
+/** Group collaboration: every agent contributes each round until complete. */
+declare function stepGroup(agents: Agent[], ctx: WorkflowContext, input: string, hooks: PatternHooks): Promise<StepResult>;
+
+/**
+ * Workflow checkpointing. A checkpoint is a serializable snapshot enabling resume.
+ * Restore fails closed: corrupt or version-mismatched data yields a typed
+ * {@link CheckpointError} with no partial restore. (FR-022, FR-022a)
+ *
+ * @packageDocumentation
+ */
+/** Current checkpoint schema version. */
+declare const CHECKPOINT_VERSION = "1";
+/** A serializable workflow snapshot. */
+interface Checkpoint {
+    version: string;
+    id: string;
+    /** Opaque workflow state (round, messages, pending node, etc.). */
+    state: Record<string, unknown>;
+}
+/** Create a checkpoint with the current schema version. */
+declare function createCheckpoint(id: string, state: Record<string, unknown>): Checkpoint;
+/** Serialize a checkpoint to a string. */
+declare function serializeCheckpoint(cp: Checkpoint): string;
+/**
+ * Restore a checkpoint from its serialized form or object. Fails closed.
+ *
+ * @throws {CheckpointError} `corrupt` if the data cannot be parsed/validated.
+ * @throws {CheckpointError} `version-mismatch` if the schema version differs.
+ */
+declare function restoreCheckpoint(input: string | Checkpoint): Checkpoint;
+
+/**
+ * The workflow engine: composes agents under an orchestration pattern with a
+ * completion signal and a configurable max-rounds safety cap, bounded concurrency,
+ * a failure policy, streaming, human-in-the-loop yield/resume, and checkpointing.
+ * (FR-018, FR-019, FR-019a, FR-019b, FR-019c, FR-020, FR-021, FR-021a, FR-021b, FR-022)
+ *
+ * @packageDocumentation
+ */
+
+/** Lifecycle status of a workflow run, observable by the host. (FR-021b) */
+type WorkflowStatus = "running" | "awaiting-input" | "completed" | "failed";
+/** Configuration for {@link createWorkflow}. */
+interface WorkflowConfig {
+    pattern: WorkflowPattern;
+    agents: Agent[];
+    /** Max rounds; -1 = unlimited. Default 16. (FR-019a) */
+    maxRounds?: number;
+    /** Concurrent failure policy. Default fail-soft. (FR-019b) */
+    failurePolicy?: FailurePolicy;
+    /** Max parallel agent calls; -1 = unlimited. Default 4. (FR-019c) */
+    maxConcurrency?: number;
+    /** Completion signal: end the workflow when this returns true. (FR-019a) */
+    isComplete?: (output: string, ctx: WorkflowContext) => boolean;
+    /** Handoff target selector. */
+    selectNext?: (output: string, ctx: WorkflowContext) => string | null;
+    /** Human-in-the-loop gate: when it returns a prompt, the workflow yields. (FR-021) */
+    humanInputGate?: (ctx: WorkflowContext) => string | null;
+}
+/** Serializable result/handle of a workflow run. (FR-021a, FR-022) */
+interface WorkflowState {
+    status: WorkflowStatus;
+    output: string;
+    /** Present when status is `awaiting-input`. */
+    awaiting?: {
+        prompt: string;
+    };
+    /** Error message when status is `failed`. */
+    error?: string;
+    /** Snapshot enabling resume. */
+    checkpoint: Checkpoint;
+}
+/** Streamed workflow event. (FR-020) */
+type WorkflowEvent = {
+    type: "round";
+    round: number;
+    output: string;
+} | {
+    type: "awaiting-input";
+    prompt: string;
+    state: WorkflowState;
+} | {
+    type: "done";
+    state: WorkflowState;
+};
+/** A runnable multi-agent workflow. */
+interface Workflow {
+    run(input: string): Promise<WorkflowState>;
+    runStream(input: string): AsyncIterable<WorkflowEvent>;
+    resume(state: WorkflowState, humanInput?: string): Promise<WorkflowState>;
+    status(): WorkflowStatus;
+}
+/**
+ * Create a workflow.
+ *
+ * @example
+ * ```ts
+ * const wf = createWorkflow({ pattern: "sequential", agents: [researcher, summarizer] });
+ * let state = await wf.run("Summarize the notes.");
+ * if (state.status === "awaiting-input") state = await wf.resume(state, "approved");
+ * ```
+ */
+declare function createWorkflow(config: WorkflowConfig): Workflow;
+
+export { type BranchResult, CHECKPOINT_VERSION, type Checkpoint, type FailurePolicy, type PatternHooks, type StepResult, type Workflow, type WorkflowConfig, type WorkflowContext, type WorkflowEvent, type WorkflowPattern, type WorkflowState, type WorkflowStatus, createCheckpoint, createWorkflow, restoreCheckpoint, runBounded, serializeCheckpoint, stepConcurrent, stepGroup, stepHandoff, stepSequential };

package/dist/workflows/index.js

@@ -0,0 +1,5 @@
+export { CHECKPOINT_VERSION, createCheckpoint, createWorkflow, restoreCheckpoint, runBounded, serializeCheckpoint, stepConcurrent, stepGroup, stepHandoff, stepSequential } from '../chunk-T2GHJ5R4.js';
+import '../chunk-IXV4UIF5.js';
+import '../chunk-DEABART4.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/workflows/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/package.json

@@ -0,0 +1,145 @@
+{
+  "name": "agent-framework-js",
+  "version": "0.1.1",
+  "description": "Modular, tree-shakeable JavaScript/TypeScript agent framework for no-backend deployments (browser, edge, Node). Agents, tools, MCP, skills, multi-agent workflows, middleware, persistence, and OpenTelemetry observability.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Varun Anand Patkar",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Varun-Patkar/agent-framework-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Varun-Patkar/agent-framework-js/issues"
+  },
+  "homepage": "https://github.com/Varun-Patkar/agent-framework-js#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./agents": {
+      "types": "./dist/agents/index.d.ts",
+      "import": "./dist/agents/index.js",
+      "require": "./dist/agents/index.cjs"
+    },
+    "./providers": {
+      "types": "./dist/providers/index.d.ts",
+      "import": "./dist/providers/index.js",
+      "require": "./dist/providers/index.cjs"
+    },
+    "./tools": {
+      "types": "./dist/tools/index.d.ts",
+      "import": "./dist/tools/index.js",
+      "require": "./dist/tools/index.cjs"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "import": "./dist/mcp/index.js",
+      "require": "./dist/mcp/index.cjs"
+    },
+    "./skills": {
+      "types": "./dist/skills/index.d.ts",
+      "import": "./dist/skills/index.js",
+      "require": "./dist/skills/index.cjs"
+    },
+    "./workflows": {
+      "types": "./dist/workflows/index.d.ts",
+      "import": "./dist/workflows/index.js",
+      "require": "./dist/workflows/index.cjs"
+    },
+    "./middleware": {
+      "types": "./dist/middleware/index.d.ts",
+      "import": "./dist/middleware/index.js",
+      "require": "./dist/middleware/index.cjs"
+    },
+    "./persistence": {
+      "types": "./dist/persistence/index.d.ts",
+      "import": "./dist/persistence/index.js",
+      "require": "./dist/persistence/index.cjs"
+    },
+    "./observability": {
+      "types": "./dist/observability/index.d.ts",
+      "import": "./dist/observability/index.js",
+      "require": "./dist/observability/index.cjs"
+    },
+    "./declarative": {
+      "types": "./dist/declarative/index.d.ts",
+      "import": "./dist/declarative/index.js",
+      "require": "./dist/declarative/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "AGENT_USAGE.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "audit": "npm audit --audit-level=high",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm test && npm run build"
+  },
+  "keywords": [
+    "agent",
+    "agents",
+    "ai",
+    "llm",
+    "mcp",
+    "orchestration",
+    "workflows",
+    "openai",
+    "copilot",
+    "no-backend",
+    "edge"
+  ],
+  "dependencies": {
+    "ajv": "^8.17.1"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@opentelemetry/api": "^1.9.0",
+    "yaml": "^2.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
+    "@opentelemetry/api": {
+      "optional": true
+    },
+    "yaml": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@types/node": "^20.14.0",
+    "@typescript-eslint/eslint-plugin": "^7.16.0",
+    "@typescript-eslint/parser": "^7.16.0",
+    "eslint": "^8.57.0",
+    "prettier": "^3.3.0",
+    "tsup": "^8.2.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0",
+    "yaml": "^2.5.0"
+  }
+}