@cuylabs/agent-core 0.4.0 → 0.6.0

package/dist/index-ipP3_ztp.d.ts

@@ -0,0 +1,198 @@
+import { h as AgentMiddleware } from './runner-G1wxEgac.js';
+import { TelemetrySettings } from 'ai';
+
+/**
+ * Risk level for operations.
+ */
+type RiskLevel = "safe" | "moderate" | "dangerous";
+/**
+ * User response to an approval request.
+ */
+type ApprovalAction = "allow" | "deny" | "remember";
+/**
+ * Approval request sent to the UI/handler.
+ */
+interface ApprovalRequest {
+    /** Unique request ID */
+    id: string;
+    /** Session ID */
+    sessionId: string;
+    /** Tool name */
+    tool: string;
+    /** Tool arguments */
+    args: unknown;
+    /** Human-readable description */
+    description: string;
+    /** Risk level */
+    risk: RiskLevel;
+    /** Patterns that would be remembered if "remember" is chosen */
+    patterns: string[];
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * Rule for auto-approving/denying operations.
+ */
+interface ApprovalRule {
+    /** Pattern to match (glob-style) */
+    pattern: string;
+    /** Tool to match (`*` for all) */
+    tool: string;
+    /** Action to take */
+    action: "allow" | "deny";
+}
+/**
+ * Configuration for the approval handler.
+ */
+interface ApprovalConfig {
+    /** Default action when no rule matches (default: "ask") */
+    defaultAction?: "allow" | "deny" | "ask";
+    /** Pre-configured rules */
+    rules?: ApprovalRule[];
+    /** Handler for approval requests */
+    onRequest?: (request: ApprovalRequest) => Promise<ApprovalAction>;
+    /** Timeout for approval requests in ms (default: 5 minutes) */
+    timeout?: number;
+}
+
+/**
+ * Approval Middleware
+ *
+ * Wraps the existing approval system as an AgentMiddleware.
+ * This is how approval finally gets wired into the tool execution
+ * pipeline — no more dead code.
+ *
+ * @example
+ * ```typescript
+ * import { createAgent, approvalMiddleware } from "@cuylabs/agent-core";
+ *
+ * const agent = createAgent({
+ *   model: anthropic("claude-sonnet-4-20250514"),
+ *   tools: [read, write, bash],
+ *   middleware: [
+ *     approvalMiddleware({
+ *       rules: [
+ *         { pattern: "src/*", tool: "read_file", action: "allow" },
+ *       ],
+ *       onRequest: async (req) => {
+ *         // Prompt user in your UI
+ *         return await askUser(req);
+ *       },
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+
+/**
+ * Configuration for the approval middleware.
+ *
+ * Extends the existing ApprovalConfig with middleware-specific options.
+ */
+interface ApprovalMiddlewareConfig extends ApprovalConfig {
+    /**
+     * Custom risk classification for tools.
+     *
+     * Overrides the built-in risk map. Tools not listed here
+     * fall back to the default classification.
+     *
+     * @example
+     * ```typescript
+     * customRisks: {
+     *   "my_deploy_tool": "dangerous",
+     *   "my_lint_tool": "safe",
+     * }
+     * ```
+     */
+    customRisks?: Record<string, RiskLevel>;
+}
+/**
+ * Create an approval middleware from an ApprovalConfig.
+ *
+ * This bridges the existing `createApprovalHandler` into the middleware
+ * system. The `beforeToolCall` hook checks rules, classifies risk,
+ * and calls the approval handler when needed.
+ *
+ * @param config - Approval configuration (rules, handler, timeout, etc.)
+ * @returns An AgentMiddleware that gates tool execution
+ */
+declare function approvalMiddleware(config?: ApprovalMiddlewareConfig): AgentMiddleware;
+
+/**
+ * Configuration for the OpenTelemetry middleware.
+ */
+interface OtelMiddlewareConfig {
+    /**
+     * Whether to record tool call arguments as span attributes.
+     * Defaults to `true`.
+     */
+    recordInputs?: boolean;
+    /**
+     * Whether to record tool results as span attributes.
+     * Defaults to `true`.
+     */
+    recordOutputs?: boolean;
+    /**
+     * Agent name — used in the root span name and attributes.
+     * Falls back to `"agent"`.
+     */
+    agentName?: string;
+    /** Agent description — recorded as `gen_ai.agent.description`. */
+    agentDescription?: string;
+    /**
+     * Whether to emit `execute_tool` spans for tool calls.
+     * Defaults to `true`.
+     */
+    emitToolSpans?: boolean;
+    /**
+     * TTL in milliseconds for orphaned spans.
+     * Defaults to 5 minutes.
+     */
+    spanTimeoutMs?: number;
+}
+/**
+ * Configuration for `createTelemetryConfig()`.
+ */
+interface TelemetryConfig {
+    /** Agent name — used in span names and `gen_ai.agent.name`. */
+    agentName: string;
+    /** Agent description — recorded as `gen_ai.agent.description`. */
+    agentDescription?: string;
+    /** Record tool arguments and LLM prompts in spans. Defaults to `true`. */
+    recordInputs?: boolean;
+    /** Record tool results and LLM responses in spans. Defaults to `true`. */
+    recordOutputs?: boolean;
+    /** Emit `execute_tool` spans from our middleware. Defaults to `true`. */
+    emitToolSpans?: boolean;
+    /** TTL in ms for orphaned spans. Defaults to 5 minutes. */
+    spanTimeoutMs?: number;
+    /**
+     * An OTel `SpanProcessor` to auto-create and register a `NodeTracerProvider`.
+     */
+    spanProcessor?: unknown;
+    /**
+     * OTel service name for the `NodeTracerProvider` resource.
+     * Defaults to `agentName`.
+     */
+    serviceName?: string;
+}
+/**
+ * Result of `createTelemetryConfig()`.
+ */
+interface TelemetryConfigResult {
+    /** Agent-core middleware. */
+    middleware: AgentMiddleware;
+    /** AI SDK telemetry settings. */
+    telemetry: TelemetrySettings;
+    /**
+     * Flush and shut down the auto-created tracer provider.
+     * No-op when no provider was auto-created.
+     */
+    shutdown: () => Promise<void>;
+}
+
+declare function otelMiddleware(config?: OtelMiddlewareConfig): AgentMiddleware;
+
+declare function createTelemetryConfig(config: TelemetryConfig): TelemetryConfigResult;
+
+export { type ApprovalConfig as A, type OtelMiddlewareConfig as O, type RiskLevel as R, type TelemetryConfig as T, type ApprovalRule as a, type ApprovalAction as b, type ApprovalMiddlewareConfig as c, type ApprovalRequest as d, type TelemetryConfigResult as e, approvalMiddleware as f, createTelemetryConfig as g, otelMiddleware as o };