@friskai/frisk-js 0.1.5 → 0.2.0

package/README.md

@@ -13,7 +13,7 @@ import { createAgent } from 'langchain'
 const frisk = await Frisk.connect({ /* apiKey: process.env.FRISK_API_KEY (default) */ })
 const agent = createAgent({
     stateSchema: yourStateSchema,
-    // Collect LLM reasoning for every tool call
+    // Optional: Collect LLM reasoning for every tool call
     tools: frisk.wrapTools(yourTools),
     // Block unwanted tool calls using middleware
     middleware: [frisk.guard({ stateSchema: yourSchema })]
@@ -32,4 +32,41 @@ await agent.invoke(
         context: session.context 
     },
 )
+```
+
+### Claude Agent SDK
+
+```typescript
+import { Frisk } from '@friskai/frisk-js/claude'
+import { query, createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk'
+
+/*
+ One-time setup
+ */
+const frisk = await Frisk.connect({ /* apiKey: process.env.FRISK_API_KEY (default) */})
+
+/*
+ Optional: Collect LLM reasoning for every tool call. 
+ MCP Servers created with `createSdkMcpServer` are currently supported.
+*/
+const friskWrappedTools = createSdkMcpServer({
+    name: 'your-tools',
+    version: '1.0.0',
+    tools: frisk.wrapTools(yourTools)
+})
+
+/*
+ Per-request setup
+ */
+const session = frisk.session({ /* Optional: application state, e.g. userId, organizationId, etc. */ })
+await query({
+    prompt,
+    options: {
+        // Collect telemetry for this agent invocation.
+        hooks: session.hooks(),
+        // Wrapping a tool does not alter the name of the tool or its MCP server
+        mcpServers: { 'your-tools': friskWrappedTools },
+        allowedTools: ['mcp__your-tools__*'], 
+    }
+})
 ```

package/dist/adapters/claude/claude-framework-adapter/claude-framework-adapter.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @friskai/frisk-js Claude Framework Adapter
+ *
+ * Framework adapter for Claude integration.
+ * Handles Claude-specific tool calls, serialization, and tool wrapping.
+ */
+import { SdkMcpToolDefinition } from '@anthropic-ai/claude-agent-sdk';
+import { ZodRawShape } from 'zod';
+import { FrameworkAdapter, ToolCallInfo, WrapToolOptions } from '../../../framework-adapter/framework-adapter';
+import type { RedactedDictionary, RedactedSerializedObject, RedactOption } from '../../../utils/redact';
+/**
+ * Claude ToolCall type
+ * Represents a tool call from Claude messages
+ */
+export interface ClaudeToolCall {
+    id?: string;
+    name: string;
+    args: Record<string, unknown>;
+    type?: string;
+}
+/** Placeholder type for Claude tool objects accepted by this adapter. */
+export interface ClaudeTool {
+}
+/**
+ * Claude framework adapter
+ *
+ * Provides Claude-specific implementation of the FrameworkAdapter interface.
+ * Handles ToolCall objects, message serialization, and tool wrapping.
+ *
+ */
+export declare class ClaudeFrameworkAdapter implements FrameworkAdapter<ClaudeToolCall, ClaudeTool> {
+    /**
+     * Serialize tool arguments to JSON with optional redaction
+     */
+    serializeToolArgs(toolArgs: Record<string, unknown> | null | undefined, options?: {
+        redact?: RedactOption;
+    }): RedactedSerializedObject;
+    /**
+     * Serialize agent state to JSON with optional redaction.
+     *
+     * This implementation delegates to {@link agentStateToDict} to apply any
+     * provided redaction options before serializing the result.
+     */
+    serializeAgentState(agentState: Record<string, unknown> | null | undefined, options?: {
+        redact?: RedactOption;
+    }): RedactedSerializedObject;
+    /**
+     * Convert tool arguments to dictionary with optional redaction
+     */
+    toolArgsToDict(toolArgs: Record<string, unknown>, options?: {
+        redact?: RedactOption;
+    }): RedactedDictionary;
+    /**
+     * Convert agent state to dictionary with optional redaction.
+     *
+     * Applies the provided redact option directly to the agent state object.
+     */
+    agentStateToDict(agentState: Record<string, unknown>, options?: {
+        redact?: RedactOption;
+    }): RedactedDictionary;
+    /**
+     * Extract tool call information from a Claude ToolCall
+     */
+    normalizeToolCall(toolCall: ClaudeToolCall): ToolCallInfo;
+    /**
+     * Get the tool call ID or generate one if not present
+     */
+    private getOrCreateToolCallId;
+    /**
+     * Get the tool name from a ToolCall
+     */
+    private getToolName;
+    /**
+     * Extract the user query from agent state
+     *
+     * Looks for the last human message in the messages array
+     */
+    extractPrompt(input: {
+        prompt: string;
+    }): string | null;
+    /**
+     * Wrap tools with additional functionality
+     *
+     * Note: For Frisk policy enforcement, use session.hooks instead.
+     * This method provides basic tool wrapping without policy checks.
+     */
+    wrapTools(tools: Iterable<SdkMcpToolDefinition<ZodRawShape>>, options?: WrapToolOptions): SdkMcpToolDefinition<ZodRawShape>[];
+    /**
+     * Wrap tools with additional functionality.
+     *
+     * This is a passthrough by default. Override in subclasses for custom wrapping.
+     */
+    wrapTool(tool: SdkMcpToolDefinition<ZodRawShape>, options?: WrapToolOptions): SdkMcpToolDefinition<ZodRawShape>;
+}
+//# sourceMappingURL=claude-framework-adapter.d.ts.map

package/dist/adapters/claude/claude-framework-adapter/claude-framework-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-framework-adapter.d.ts","sourceRoot":"","sources":["../../../../src/adapters/claude/claude-framework-adapter/claude-framework-adapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAA;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,KAAK,CAAA;AACjC,OAAO,EAEL,gBAAgB,EAChB,YAAY,EACZ,eAAe,EAChB,MAAM,8CAA8C,CAAA;AAErD,OAAO,KAAK,EACV,kBAAkB,EAClB,wBAAwB,EACxB,YAAY,EACb,MAAM,uBAAuB,CAAA;AAI9B;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,yEAAyE;AACzE,MAAM,WAAW,UAAU;CAE1B;AAED;;;;;;GAMG;AACH,qBAAa,sBACX,YAAW,gBAAgB,CAAC,cAAc,EAAE,UAAU,CAAC;IAEvD;;OAEG;IACH,iBAAiB,CACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EACpD,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,YAAY,CAAA;KAAE,GAClC,wBAAwB;IAY3B;;;;;OAKG;IACH,mBAAmB,CACjB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EACtD,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,YAAY,CAAA;KAAE,GAClC,wBAAwB;IAY3B;;OAEG;IACH,cAAc,CACZ,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,YAAY,CAAA;KAAE,GAClC,kBAAkB;IAIrB;;;;OAIG;IACH,gBAAgB,CACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,YAAY,CAAA;KAAE,GAClC,kBAAkB;IAIrB;;OAEG;IACH,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,YAAY;IAQzD;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAQ7B;;OAEG;IACH,OAAO,CAAC,WAAW;IAQnB;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,GAAG,IAAI;IAIvD;;;;;OAKG;IACH,SAAS,CACP,KAAK,EAAE,QAAQ,CAAC,oBAAoB,CAAC,WAAW,CAAC,CAAC,EAClD,OAAO,GAAE,eAAwC,GAChD,oBAAoB,CAAC,WAAW,CAAC,EAAE;IAItC;;;;OAIG;IACI,QAAQ,CACb,IAAI,EAAE,oBAAoB,CAAC,WAAW,CAAC,EACvC,OAAO,GAAE,eAAwC,GAChD,oBAAoB,CAAC,WAAW,CAAC;CAOrC"}

package/dist/adapters/claude/claude-framework-adapter/wrap-tool-with-llm-reasoning.d.ts

@@ -0,0 +1,4 @@
+import { SdkMcpToolDefinition } from '@anthropic-ai/claude-agent-sdk';
+import { ZodRawShape } from 'zod';
+export declare function wrapToolWithLlmReasoning(originalTool: SdkMcpToolDefinition<ZodRawShape>): SdkMcpToolDefinition<ZodRawShape>;
+//# sourceMappingURL=wrap-tool-with-llm-reasoning.d.ts.map

package/dist/adapters/claude/claude-framework-adapter/wrap-tool-with-llm-reasoning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-tool-with-llm-reasoning.d.ts","sourceRoot":"","sources":["../../../../src/adapters/claude/claude-framework-adapter/wrap-tool-with-llm-reasoning.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAQ,MAAM,gCAAgC,CAAA;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,KAAK,CAAA;AAKjC,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,oBAAoB,CAAC,WAAW,CAAC,GAC9C,oBAAoB,CAAC,WAAW,CAAC,CAsBnC"}

package/dist/adapters/claude/frisk-claude-session.d.ts

@@ -0,0 +1,29 @@
+import { type HookCallback, type HookCallbackMatcher, type HookEvent } from '@anthropic-ai/claude-agent-sdk';
+import type { Tracer } from '@opentelemetry/api';
+import { FriskSession, type FriskSessionOptions } from '../../core/frisk-session';
+import type { ResolvedRedactionOptions } from '../../core/redaction-options';
+import { type FriskSDKLoggingOptions } from '../../logging';
+import { FriskClaude, type FriskClaudeAgentState } from './frisk-claude';
+export interface FriskClaudeSessionOptions extends FriskSessionOptions<FriskClaude> {
+    frisk: FriskClaude;
+    agentState: FriskClaudeAgentState;
+    redact: ResolvedRedactionOptions;
+    tracer: Tracer;
+    logging?: FriskSDKLoggingOptions;
+}
+export interface FriskClaudeHooksOptions {
+    controls?: {
+        toolPolicies?: boolean;
+    };
+}
+export type ClaudeAgentHooks = Partial<Record<HookEvent, HookCallbackMatcher[]>>;
+/** Claude-specific session object exposing context and callback helpers. */
+export declare class FriskClaudeSession extends FriskSession<FriskClaude> {
+    private agentState;
+    constructor(options: FriskClaudeSessionOptions);
+    hooks(options?: FriskClaudeHooksOptions): ClaudeAgentHooks;
+    sessionStopHook(): HookCallback;
+    userPromptSubmitHook(): HookCallback;
+    preToolUseHook(): HookCallback;
+}
+//# sourceMappingURL=frisk-claude-session.d.ts.map

package/dist/adapters/claude/frisk-claude-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frisk-claude-session.d.ts","sourceRoot":"","sources":["../../../src/adapters/claude/frisk-claude-session.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,SAAS,EAIf,MAAM,gCAAgC,CAAA;AACvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EACL,YAAY,EACZ,KAAK,mBAAmB,EACzB,MAAM,0BAA0B,CAAA;AAEjC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAA;AAE5E,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,eAAe,CAAA;AAC3D,OAAO,EAAE,WAAW,EAAE,KAAK,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAGxE,MAAM,WAAW,yBACf,SAAQ,mBAAmB,CAAC,WAAW,CAAC;IACxC,KAAK,EAAE,WAAW,CAAA;IAClB,UAAU,EAAE,qBAAqB,CAAA;IACjC,MAAM,EAAE,wBAAwB,CAAA;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,sBAAsB,CAAA;CACjC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE;QACT,YAAY,CAAC,EAAE,OAAO,CAAA;KACvB,CAAA;CACF;AAED,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,mBAAmB,EAAE,CAAC,CAAC,CAAA;AAEhF,4EAA4E;AAC5E,qBAAa,kBAAmB,SAAQ,YAAY,CAAC,WAAW,CAAC;IAC/D,OAAO,CAAC,UAAU,CAAuB;gBAEtB,OAAO,EAAE,yBAAyB;IAU9C,KAAK,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,gBAAgB;IAa1D,eAAe,IAAI,YAAY;IAQ/B,oBAAoB,IAAI,YAAY;IAYpC,cAAc,IAAI,YAAY;CA+BtC"}

package/dist/adapters/claude/frisk-claude.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @friskai/frisk-js Claude Integration
+ *
+ * FriskClaude class that extends Frisk with Claude-specific functionality.
+ */
+import { SdkMcpToolDefinition } from '@anthropic-ai/claude-agent-sdk';
+import { ZodRawShape } from 'zod';
+import { Frisk } from '../../core/frisk';
+import type { FriskOptions } from '../../core/types';
+import { WrapToolOptions } from '../../framework-adapter/framework-adapter';
+import { ClaudeFrameworkAdapter, type ClaudeTool, type ClaudeToolCall } from './claude-framework-adapter/claude-framework-adapter';
+import { FriskClaudeSession } from './frisk-claude-session';
+/**
+ * Claude-specific Frisk init params (without frameworkAdapter since it's preset)
+ */
+export type FriskClaudeOptions = Omit<FriskOptions<ClaudeToolCall, ClaudeTool>, 'adapter'>;
+export type FriskClaudeAgentState = Record<string, unknown>;
+/**
+ * FriskClaude - Frisk SDK configured for Claude integration
+ *
+ * Extends the base Frisk class with Claude-specific functionality.
+ * Automatically configures the ClaudeFrameworkAdapter.
+ *
+ * @example
+ * ```typescript
+ * import { Frisk } from '@friskai/frisk-js/claude';
+ *
+ * const frisk = await Frisk.connect({
+ *   apiKey: process.env.FRISK_API_KEY,
+ *   redact: {
+ *     redactToolArgs: ['password'],
+ *   },
+ * });
+ *
+ * // Collect LLM reasoning from tools
+ * const wrappedTools = frisk.wrapTools(myTools);
+ *
+ * // Evaluate a tool call against Frisk policies
+ * const result = frisk.decideToolCall({
+ *   toolCall: { name: 'send_email', id: 'tool-call-1', args: { recipient: 'user@example.com' } },
+ *   agentState: { userId: 123 }
+ * })
+ * ```
+ */
+export declare class FriskClaude extends Frisk<ClaudeToolCall, ClaudeTool, ClaudeFrameworkAdapter, FriskClaudeAgentState> {
+    constructor(params?: FriskClaudeOptions);
+    session(agentState?: FriskClaudeAgentState): FriskClaudeSession;
+    /**
+     * Wrap many Claude tools with Frisk policy enforcement.
+     *
+     * This wrapper requires the LLM to provide a **reasoning / justification** before calling a tool.
+     * Frisk captures that reasoning and makes it available for review in the Frisk dashboard.
+     *
+     * ## Accepted tool types
+     * Accepts an instance of Claude's SdkMcpToolDefinition.
+     * This includes tools created via the `tool()` function, whose arguments are object-shaped.
+     */
+    wrapTools(tools: Iterable<SdkMcpToolDefinition<ZodRawShape>>, options?: WrapToolOptions): SdkMcpToolDefinition<ZodRawShape>[];
+    /**
+     * Wrap a single Claude tool with Frisk policy enforcement.
+     *
+     * This wrapper requires the LLM to provide a **reasoning / justification** before calling a tool.
+     * Frisk captures that reasoning and makes it available for review in the Frisk dashboard.
+     *
+     * ## Accepted tool types
+     * Accepts an instance of Claude's SdkMcpToolDefinition.
+     * This includes tools created via the `tool()` function, whose arguments are object-shaped.
+     */
+    wrapTool(tool: SdkMcpToolDefinition<ZodRawShape>, options?: WrapToolOptions): SdkMcpToolDefinition<ZodRawShape>;
+}
+//# sourceMappingURL=frisk-claude.d.ts.map

package/dist/adapters/claude/frisk-claude.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frisk-claude.d.ts","sourceRoot":"","sources":["../../../src/adapters/claude/frisk-claude.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAA;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,KAAK,CAAA;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAExC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAEL,eAAe,EAChB,MAAM,2CAA2C,CAAA;AAClD,OAAO,EACL,sBAAsB,EACtB,KAAK,UAAU,EACf,KAAK,cAAc,EACpB,MAAM,qDAAqD,CAAA;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAE3D;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,CACnC,YAAY,CAAC,cAAc,EAAE,UAAU,CAAC,EACxC,SAAS,CACV,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,WAAY,SAAQ,KAAK,CACpC,cAAc,EACd,UAAU,EACV,sBAAsB,EACtB,qBAAqB,CACtB;gBACa,MAAM,CAAC,EAAE,kBAAkB;IAOhC,OAAO,CAAC,UAAU,CAAC,EAAE,qBAAqB,GAAG,kBAAkB;IAkBtE;;;;;;;;;OASG;IACI,SAAS,CACd,KAAK,EAAE,QAAQ,CAAC,oBAAoB,CAAC,WAAW,CAAC,CAAC,EAClD,OAAO,GAAE,eAAwC,GAChD,oBAAoB,CAAC,WAAW,CAAC,EAAE;IAItC;;;;;;;;;OASG;IACI,QAAQ,CACb,IAAI,EAAE,oBAAoB,CAAC,WAAW,CAAC,EACvC,OAAO,GAAE,eAAwC,GAChD,oBAAoB,CAAC,WAAW,CAAC;CAGrC"}

package/dist/adapters/claude/index.d.ts

@@ -0,0 +1,3 @@
+export { FriskClaude, FriskClaude as Frisk, type FriskClaudeOptions, type FriskClaudeOptions as FriskOptions, } from './frisk-claude';
+export { FriskClaudeSession, FriskClaudeSession as FriskSession, } from './frisk-claude-session';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/claude/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/claude/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,WAAW,IAAI,KAAK,EACpB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,IAAI,YAAY,GACxC,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EACL,kBAAkB,EAClB,kBAAkB,IAAI,YAAY,GACnC,MAAM,wBAAwB,CAAA"}