@directive-run/ai 0.1.1

package/dist/types-BKCdgKC-.d.cts

@@ -0,0 +1,300 @@
+import { Requirement } from '@directive-run/core';
+
+/** Simplified Agent interface */
+interface AgentLike {
+    name: string;
+    instructions?: string;
+    model?: string;
+    tools?: unknown[];
+}
+/** Agent run result */
+interface RunResult<T = unknown> {
+    output: T;
+    messages: Message[];
+    toolCalls: ToolCall[];
+    totalTokens: number;
+    /** Breakdown of input vs output tokens, when available from the provider */
+    tokenUsage?: TokenUsage;
+    /** True when result was served from semantic cache */
+    isCached?: boolean;
+}
+/** Breakdown of token usage by input/output */
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+/** Message from agent run */
+interface Message {
+    role: "user" | "assistant" | "tool" | "system";
+    content: string;
+    toolCallId?: string;
+}
+/** Tool call record */
+interface ToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+    result?: string;
+}
+/** Run function type */
+type AgentRunner = <T = unknown>(agent: AgentLike, input: string, options?: RunOptions) => Promise<RunResult<T>>;
+/** Run options */
+interface RunOptions {
+    maxTurns?: number;
+    signal?: AbortSignal;
+    onMessage?: (message: Message) => void;
+    onToolCall?: (toolCall: ToolCall) => void;
+}
+/**
+ * Lifecycle hooks for adapter-level observability.
+ *
+ * Attach to any adapter (runner or streaming runner) to trace, log,
+ * or measure individual LLM calls without modifying application code.
+ *
+ * @example
+ * ```typescript
+ * const runner = createOpenAIRunner({
+ *   apiKey: process.env.OPENAI_API_KEY!,
+ *   hooks: {
+ *     onBeforeCall: ({ agent, input }) => console.log(`→ ${agent.name}`, input.slice(0, 50)),
+ *     onAfterCall: ({ durationMs, tokenUsage }) => {
+ *       metrics.track('llm_call', { durationMs, ...tokenUsage });
+ *     },
+ *     onError: ({ error }) => Sentry.captureException(error),
+ *   },
+ * });
+ * ```
+ */
+interface AdapterHooks {
+    /** Fires before each LLM API call. */
+    onBeforeCall?: (event: {
+        agent: AgentLike;
+        input: string;
+        timestamp: number;
+    }) => void;
+    /** Fires after a successful LLM API call. */
+    onAfterCall?: (event: {
+        agent: AgentLike;
+        input: string;
+        output: string;
+        totalTokens: number;
+        tokenUsage: TokenUsage;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    /** Fires when an LLM API call fails. */
+    onError?: (event: {
+        agent: AgentLike;
+        input: string;
+        error: Error;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+}
+/** Guardrail function */
+type GuardrailFn<T = unknown> = (data: T, context: GuardrailContext) => GuardrailResult | Promise<GuardrailResult>;
+/** Guardrail context */
+interface GuardrailContext {
+    agentName: string;
+    input: string;
+    facts: Record<string, unknown>;
+}
+/** Guardrail result */
+interface GuardrailResult {
+    passed: boolean;
+    reason?: string;
+    transformed?: unknown;
+}
+/** Input guardrail data */
+interface InputGuardrailData {
+    input: string;
+    agentName: string;
+}
+/** Output guardrail data */
+interface OutputGuardrailData {
+    output: unknown;
+    agentName: string;
+    input: string;
+    messages: Message[];
+}
+/** Tool call guardrail data */
+interface ToolCallGuardrailData {
+    toolCall: ToolCall;
+    agentName: string;
+    input: string;
+}
+/** Retry configuration for guardrails */
+interface GuardrailRetryConfig {
+    /** @default 1 */
+    attempts?: number;
+    /** @default "exponential" */
+    backoff?: "exponential" | "linear" | "fixed";
+    /** @default 100 */
+    baseDelayMs?: number;
+    /** @default 5000 */
+    maxDelayMs?: number;
+}
+/** Named guardrail for better debugging */
+interface NamedGuardrail<T = unknown> {
+    name: string;
+    fn: GuardrailFn<T>;
+    /** @default true */
+    critical?: boolean;
+    retry?: GuardrailRetryConfig;
+}
+/** Guardrails configuration */
+interface GuardrailsConfig {
+    input?: Array<GuardrailFn<InputGuardrailData> | NamedGuardrail<InputGuardrailData>>;
+    output?: Array<GuardrailFn<OutputGuardrailData> | NamedGuardrail<OutputGuardrailData>>;
+    toolCall?: Array<GuardrailFn<ToolCallGuardrailData> | NamedGuardrail<ToolCallGuardrailData>>;
+}
+/** Retry configuration for agent runs */
+interface AgentRetryConfig {
+    /** @default 1 */
+    attempts?: number;
+    /** @default "exponential" */
+    backoff?: "exponential" | "linear" | "fixed";
+    /** @default 1000 */
+    baseDelayMs?: number;
+    /** @default 30000 */
+    maxDelayMs?: number;
+    isRetryable?: (error: Error) => boolean;
+    onRetry?: (attempt: number, error: Error, delayMs: number) => void;
+}
+/** Agent state in facts */
+interface AgentState {
+    status: "idle" | "running" | "paused" | "completed" | "error";
+    currentAgent: string | null;
+    input: string | null;
+    output: unknown | null;
+    error: string | null;
+    tokenUsage: number;
+    turnCount: number;
+    startedAt: number | null;
+    completedAt: number | null;
+}
+/** Approval state */
+interface ApprovalState {
+    pending: ApprovalRequest[];
+    approved: string[];
+    rejected: RejectedRequest[];
+}
+/** Rejected request with tracking information */
+interface RejectedRequest {
+    id: string;
+    reason?: string;
+    rejectedAt: number;
+}
+/** Approval request */
+interface ApprovalRequest {
+    id: string;
+    type: "tool_call" | "output" | "handoff";
+    agentName: string;
+    description: string;
+    data: unknown;
+    requestedAt: number;
+}
+/** Combined orchestrator state */
+interface OrchestratorState {
+    agent: AgentState;
+    approval: ApprovalState;
+    conversation: Message[];
+    toolCalls: ToolCall[];
+}
+/** Constraint for orchestrator */
+interface OrchestratorConstraint<F extends Record<string, unknown>> {
+    when: (facts: F & OrchestratorState) => boolean | Promise<boolean>;
+    require: Requirement | ((facts: F & OrchestratorState) => Requirement);
+    priority?: number;
+}
+/** Resolver context for orchestrator */
+interface OrchestratorResolverContext<F extends Record<string, unknown>> {
+    facts: F & OrchestratorState;
+    runAgent: <T>(agent: AgentLike, input: string, options?: RunOptions) => Promise<RunResult<T>>;
+    signal: AbortSignal;
+}
+/** Resolver for orchestrator */
+interface OrchestratorResolver<F extends Record<string, unknown>, R extends Requirement = Requirement> {
+    requirement: (req: Requirement) => req is R;
+    key?: (req: R) => string;
+    resolve: (req: R, ctx: OrchestratorResolverContext<F>) => void | Promise<void>;
+}
+/** Lifecycle hooks for observability */
+interface OrchestratorLifecycleHooks {
+    onAgentStart?: (event: {
+        agentName: string;
+        input: string;
+        timestamp: number;
+    }) => void;
+    onAgentComplete?: (event: {
+        agentName: string;
+        input: string;
+        output: unknown;
+        tokenUsage: number;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    onAgentError?: (event: {
+        agentName: string;
+        input: string;
+        error: Error;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    onGuardrailCheck?: (event: {
+        guardrailName: string;
+        guardrailType: "input" | "output" | "toolCall";
+        passed: boolean;
+        reason?: string;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    onAgentRetry?: (event: {
+        agentName: string;
+        input: string;
+        attempt: number;
+        error: Error;
+        delayMs: number;
+        timestamp: number;
+    }) => void;
+}
+/** Error codes for guardrail errors */
+type GuardrailErrorCode = "INPUT_GUARDRAIL_FAILED" | "OUTPUT_GUARDRAIL_FAILED" | "TOOL_CALL_GUARDRAIL_FAILED" | "APPROVAL_REJECTED" | "BUDGET_EXCEEDED" | "RATE_LIMIT_EXCEEDED" | "AGENT_ERROR";
+/**
+ * Structured error for guardrail failures.
+ *
+ * **Security:** The `input` and `data` properties are non-enumerable to prevent
+ * accidental leakage of sensitive data via JSON.stringify or console.log.
+ */
+declare class GuardrailError extends Error {
+    readonly code: GuardrailErrorCode;
+    readonly guardrailName: string;
+    readonly guardrailType: "input" | "output" | "toolCall";
+    readonly userMessage: string;
+    readonly data: unknown;
+    readonly agentName: string;
+    readonly input: string;
+    constructor(options: {
+        code: GuardrailErrorCode;
+        message: string;
+        guardrailName: string;
+        guardrailType: "input" | "output" | "toolCall";
+        userMessage?: string;
+        data?: unknown;
+        agentName: string;
+        input: string;
+        cause?: Error;
+    });
+    toJSON(): Record<string, unknown>;
+}
+/** Check if an error is a GuardrailError. */
+declare function isGuardrailError(error: unknown): error is GuardrailError;
+/** Schema validation result */
+interface SchemaValidationResult {
+    valid: boolean;
+    errors?: string[];
+}
+/** Schema validator function type */
+type SchemaValidator<_T = unknown> = (value: unknown) => SchemaValidationResult | boolean;
+
+export { type ApprovalRequest as A, type GuardrailResult as G, type InputGuardrailData as I, type Message as M, type NamedGuardrail as N, type OutputGuardrailData as O, type RunOptions as R, type SchemaValidator as S, type ToolCallGuardrailData as T, type ToolCall as a, type AgentLike as b, type AgentRunner as c, type GuardrailFn as d, type GuardrailContext as e, type AdapterHooks as f, type RunResult as g, type ApprovalState as h, type AgentState as i, type OrchestratorState as j, type OrchestratorConstraint as k, type OrchestratorResolver as l, type AgentRetryConfig as m, type OrchestratorLifecycleHooks as n, type GuardrailsConfig as o, GuardrailError as p, type GuardrailErrorCode as q, type GuardrailRetryConfig as r, type OrchestratorResolverContext as s, type RejectedRequest as t, type SchemaValidationResult as u, type TokenUsage as v, isGuardrailError as w };

package/dist/types-BKCdgKC-.d.ts

@@ -0,0 +1,300 @@
+import { Requirement } from '@directive-run/core';
+
+/** Simplified Agent interface */
+interface AgentLike {
+    name: string;
+    instructions?: string;
+    model?: string;
+    tools?: unknown[];
+}
+/** Agent run result */
+interface RunResult<T = unknown> {
+    output: T;
+    messages: Message[];
+    toolCalls: ToolCall[];
+    totalTokens: number;
+    /** Breakdown of input vs output tokens, when available from the provider */
+    tokenUsage?: TokenUsage;
+    /** True when result was served from semantic cache */
+    isCached?: boolean;
+}
+/** Breakdown of token usage by input/output */
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+/** Message from agent run */
+interface Message {
+    role: "user" | "assistant" | "tool" | "system";
+    content: string;
+    toolCallId?: string;
+}
+/** Tool call record */
+interface ToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+    result?: string;
+}
+/** Run function type */
+type AgentRunner = <T = unknown>(agent: AgentLike, input: string, options?: RunOptions) => Promise<RunResult<T>>;
+/** Run options */
+interface RunOptions {
+    maxTurns?: number;
+    signal?: AbortSignal;
+    onMessage?: (message: Message) => void;
+    onToolCall?: (toolCall: ToolCall) => void;
+}
+/**
+ * Lifecycle hooks for adapter-level observability.
+ *
+ * Attach to any adapter (runner or streaming runner) to trace, log,
+ * or measure individual LLM calls without modifying application code.
+ *
+ * @example
+ * ```typescript
+ * const runner = createOpenAIRunner({
+ *   apiKey: process.env.OPENAI_API_KEY!,
+ *   hooks: {
+ *     onBeforeCall: ({ agent, input }) => console.log(`→ ${agent.name}`, input.slice(0, 50)),
+ *     onAfterCall: ({ durationMs, tokenUsage }) => {
+ *       metrics.track('llm_call', { durationMs, ...tokenUsage });
+ *     },
+ *     onError: ({ error }) => Sentry.captureException(error),
+ *   },
+ * });
+ * ```
+ */
+interface AdapterHooks {
+    /** Fires before each LLM API call. */
+    onBeforeCall?: (event: {
+        agent: AgentLike;
+        input: string;
+        timestamp: number;
+    }) => void;
+    /** Fires after a successful LLM API call. */
+    onAfterCall?: (event: {
+        agent: AgentLike;
+        input: string;
+        output: string;
+        totalTokens: number;
+        tokenUsage: TokenUsage;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    /** Fires when an LLM API call fails. */
+    onError?: (event: {
+        agent: AgentLike;
+        input: string;
+        error: Error;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+}
+/** Guardrail function */
+type GuardrailFn<T = unknown> = (data: T, context: GuardrailContext) => GuardrailResult | Promise<GuardrailResult>;
+/** Guardrail context */
+interface GuardrailContext {
+    agentName: string;
+    input: string;
+    facts: Record<string, unknown>;
+}
+/** Guardrail result */
+interface GuardrailResult {
+    passed: boolean;
+    reason?: string;
+    transformed?: unknown;
+}
+/** Input guardrail data */
+interface InputGuardrailData {
+    input: string;
+    agentName: string;
+}
+/** Output guardrail data */
+interface OutputGuardrailData {
+    output: unknown;
+    agentName: string;
+    input: string;
+    messages: Message[];
+}
+/** Tool call guardrail data */
+interface ToolCallGuardrailData {
+    toolCall: ToolCall;
+    agentName: string;
+    input: string;
+}
+/** Retry configuration for guardrails */
+interface GuardrailRetryConfig {
+    /** @default 1 */
+    attempts?: number;
+    /** @default "exponential" */
+    backoff?: "exponential" | "linear" | "fixed";
+    /** @default 100 */
+    baseDelayMs?: number;
+    /** @default 5000 */
+    maxDelayMs?: number;
+}
+/** Named guardrail for better debugging */
+interface NamedGuardrail<T = unknown> {
+    name: string;
+    fn: GuardrailFn<T>;
+    /** @default true */
+    critical?: boolean;
+    retry?: GuardrailRetryConfig;
+}
+/** Guardrails configuration */
+interface GuardrailsConfig {
+    input?: Array<GuardrailFn<InputGuardrailData> | NamedGuardrail<InputGuardrailData>>;
+    output?: Array<GuardrailFn<OutputGuardrailData> | NamedGuardrail<OutputGuardrailData>>;
+    toolCall?: Array<GuardrailFn<ToolCallGuardrailData> | NamedGuardrail<ToolCallGuardrailData>>;
+}
+/** Retry configuration for agent runs */
+interface AgentRetryConfig {
+    /** @default 1 */
+    attempts?: number;
+    /** @default "exponential" */
+    backoff?: "exponential" | "linear" | "fixed";
+    /** @default 1000 */
+    baseDelayMs?: number;
+    /** @default 30000 */
+    maxDelayMs?: number;
+    isRetryable?: (error: Error) => boolean;
+    onRetry?: (attempt: number, error: Error, delayMs: number) => void;
+}
+/** Agent state in facts */
+interface AgentState {
+    status: "idle" | "running" | "paused" | "completed" | "error";
+    currentAgent: string | null;
+    input: string | null;
+    output: unknown | null;
+    error: string | null;
+    tokenUsage: number;
+    turnCount: number;
+    startedAt: number | null;
+    completedAt: number | null;
+}
+/** Approval state */
+interface ApprovalState {
+    pending: ApprovalRequest[];
+    approved: string[];
+    rejected: RejectedRequest[];
+}
+/** Rejected request with tracking information */
+interface RejectedRequest {
+    id: string;
+    reason?: string;
+    rejectedAt: number;
+}
+/** Approval request */
+interface ApprovalRequest {
+    id: string;
+    type: "tool_call" | "output" | "handoff";
+    agentName: string;
+    description: string;
+    data: unknown;
+    requestedAt: number;
+}
+/** Combined orchestrator state */
+interface OrchestratorState {
+    agent: AgentState;
+    approval: ApprovalState;
+    conversation: Message[];
+    toolCalls: ToolCall[];
+}
+/** Constraint for orchestrator */
+interface OrchestratorConstraint<F extends Record<string, unknown>> {
+    when: (facts: F & OrchestratorState) => boolean | Promise<boolean>;
+    require: Requirement | ((facts: F & OrchestratorState) => Requirement);
+    priority?: number;
+}
+/** Resolver context for orchestrator */
+interface OrchestratorResolverContext<F extends Record<string, unknown>> {
+    facts: F & OrchestratorState;
+    runAgent: <T>(agent: AgentLike, input: string, options?: RunOptions) => Promise<RunResult<T>>;
+    signal: AbortSignal;
+}
+/** Resolver for orchestrator */
+interface OrchestratorResolver<F extends Record<string, unknown>, R extends Requirement = Requirement> {
+    requirement: (req: Requirement) => req is R;
+    key?: (req: R) => string;
+    resolve: (req: R, ctx: OrchestratorResolverContext<F>) => void | Promise<void>;
+}
+/** Lifecycle hooks for observability */
+interface OrchestratorLifecycleHooks {
+    onAgentStart?: (event: {
+        agentName: string;
+        input: string;
+        timestamp: number;
+    }) => void;
+    onAgentComplete?: (event: {
+        agentName: string;
+        input: string;
+        output: unknown;
+        tokenUsage: number;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    onAgentError?: (event: {
+        agentName: string;
+        input: string;
+        error: Error;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    onGuardrailCheck?: (event: {
+        guardrailName: string;
+        guardrailType: "input" | "output" | "toolCall";
+        passed: boolean;
+        reason?: string;
+        durationMs: number;
+        timestamp: number;
+    }) => void;
+    onAgentRetry?: (event: {
+        agentName: string;
+        input: string;
+        attempt: number;
+        error: Error;
+        delayMs: number;
+        timestamp: number;
+    }) => void;
+}
+/** Error codes for guardrail errors */
+type GuardrailErrorCode = "INPUT_GUARDRAIL_FAILED" | "OUTPUT_GUARDRAIL_FAILED" | "TOOL_CALL_GUARDRAIL_FAILED" | "APPROVAL_REJECTED" | "BUDGET_EXCEEDED" | "RATE_LIMIT_EXCEEDED" | "AGENT_ERROR";
+/**
+ * Structured error for guardrail failures.
+ *
+ * **Security:** The `input` and `data` properties are non-enumerable to prevent
+ * accidental leakage of sensitive data via JSON.stringify or console.log.
+ */
+declare class GuardrailError extends Error {
+    readonly code: GuardrailErrorCode;
+    readonly guardrailName: string;
+    readonly guardrailType: "input" | "output" | "toolCall";
+    readonly userMessage: string;
+    readonly data: unknown;
+    readonly agentName: string;
+    readonly input: string;
+    constructor(options: {
+        code: GuardrailErrorCode;
+        message: string;
+        guardrailName: string;
+        guardrailType: "input" | "output" | "toolCall";
+        userMessage?: string;
+        data?: unknown;
+        agentName: string;
+        input: string;
+        cause?: Error;
+    });
+    toJSON(): Record<string, unknown>;
+}
+/** Check if an error is a GuardrailError. */
+declare function isGuardrailError(error: unknown): error is GuardrailError;
+/** Schema validation result */
+interface SchemaValidationResult {
+    valid: boolean;
+    errors?: string[];
+}
+/** Schema validator function type */
+type SchemaValidator<_T = unknown> = (value: unknown) => SchemaValidationResult | boolean;
+
+export { type ApprovalRequest as A, type GuardrailResult as G, type InputGuardrailData as I, type Message as M, type NamedGuardrail as N, type OutputGuardrailData as O, type RunOptions as R, type SchemaValidator as S, type ToolCallGuardrailData as T, type ToolCall as a, type AgentLike as b, type AgentRunner as c, type GuardrailFn as d, type GuardrailContext as e, type AdapterHooks as f, type RunResult as g, type ApprovalState as h, type AgentState as i, type OrchestratorState as j, type OrchestratorConstraint as k, type OrchestratorResolver as l, type AgentRetryConfig as m, type OrchestratorLifecycleHooks as n, type GuardrailsConfig as o, GuardrailError as p, type GuardrailErrorCode as q, type GuardrailRetryConfig as r, type OrchestratorResolverContext as s, type RejectedRequest as t, type SchemaValidationResult as u, type TokenUsage as v, isGuardrailError as w };

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@directive-run/ai",
+  "version": "0.1.1",
+  "description": "AI agent orchestration, guardrails, and multi-agent coordination for Directive.",
+  "license": "MIT",
+  "author": "Jason Comes",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/directive-run/directive",
+    "directory": "packages/ai"
+  },
+  "homepage": "https://directive.run",
+  "bugs": {
+    "url": "https://github.com/directive-run/directive/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "directive",
+    "ai",
+    "agents",
+    "guardrails",
+    "orchestration",
+    "llm",
+    "constraint-driven"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "require": "./dist/testing.cjs",
+      "import": "./dist/testing.js"
+    },
+    "./anthropic": {
+      "types": "./dist/anthropic.d.ts",
+      "require": "./dist/anthropic.cjs",
+      "import": "./dist/anthropic.js"
+    },
+    "./openai": {
+      "types": "./dist/openai.d.ts",
+      "require": "./dist/openai.cjs",
+      "import": "./dist/openai.js"
+    },
+    "./ollama": {
+      "types": "./dist/ollama.d.ts",
+      "require": "./dist/ollama.cjs",
+      "import": "./dist/ollama.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@directive-run/core": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "@directive-run/core": "0.1.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}