kernl 0.1.1

package/dist/tools.js

@@ -0,0 +1,220 @@
+import logger from "./logger";
+import { getCurrentSpan } from "./tracing";
+// --- utils ---
+import { safeExecute } from "./utils/safeExecute";
+import { toFunctionToolName } from "./utils/tools";
+import { getSchemaAndParserFromInputType } from "./utils/tools";
+import { isZodObject } from "./utils/typeGuards";
+/**
+ * Creates a hosted MCP tool definition.
+ *
+ * @param options - Configuration for the hosted MCP tool, including server connection details
+ * and approval requirements.
+ */
+export function hostedMcpTool(options) {
+    if ("serverUrl" in options) {
+        // the MCP servers comaptible with the specification
+        const providerData = typeof options.requireApproval === "undefined" ||
+            options.requireApproval === "never"
+            ? {
+                type: "mcp",
+                server_label: options.serverLabel,
+                server_url: options.serverUrl,
+                authorization: options.authorization,
+                require_approval: "never",
+                allowed_tools: toMcpAllowedToolsFilter(options.allowedTools),
+                headers: options.headers,
+            }
+            : {
+                type: "mcp",
+                server_label: options.serverLabel,
+                server_url: options.serverUrl,
+                authorization: options.authorization,
+                allowed_tools: toMcpAllowedToolsFilter(options.allowedTools),
+                headers: options.headers,
+                require_approval: typeof options.requireApproval === "string"
+                    ? "always"
+                    : buildRequireApproval(options.requireApproval),
+                on_approval: options.onApproval,
+            };
+        return {
+            type: "hosted_tool",
+            name: "hosted_mcp",
+            providerData,
+        };
+    }
+    else if ("connectorId" in options) {
+        // OpenAI's connectors
+        const providerData = typeof options.requireApproval === "undefined" ||
+            options.requireApproval === "never"
+            ? {
+                type: "mcp",
+                server_label: options.serverLabel,
+                connector_id: options.connectorId,
+                authorization: options.authorization,
+                require_approval: "never",
+                allowed_tools: toMcpAllowedToolsFilter(options.allowedTools),
+                headers: options.headers,
+            }
+            : {
+                type: "mcp",
+                server_label: options.serverLabel,
+                connector_id: options.connectorId,
+                authorization: options.authorization,
+                allowed_tools: toMcpAllowedToolsFilter(options.allowedTools),
+                headers: options.headers,
+                require_approval: typeof options.requireApproval === "string"
+                    ? "always"
+                    : buildRequireApproval(options.requireApproval),
+                on_approval: options.onApproval,
+            };
+        return {
+            type: "hosted_tool",
+            name: "hosted_mcp",
+            providerData,
+        };
+    }
+    else {
+        // the MCP servers comaptible with the specification
+        const providerData = typeof options.requireApproval === "undefined" ||
+            options.requireApproval === "never"
+            ? {
+                type: "mcp",
+                server_label: options.serverLabel,
+                require_approval: "never",
+                allowed_tools: toMcpAllowedToolsFilter(options.allowedTools),
+            }
+            : {
+                type: "mcp",
+                server_label: options.serverLabel,
+                allowed_tools: toMcpAllowedToolsFilter(options.allowedTools),
+                require_approval: typeof options.requireApproval === "string"
+                    ? "always"
+                    : buildRequireApproval(options.requireApproval),
+                on_approval: options.onApproval,
+            };
+        return {
+            type: "hosted_tool",
+            name: "hosted_mcp",
+            providerData,
+        };
+    }
+}
+/**
+ * The default function to invoke when an error occurs while running the tool.
+ *
+ * Always returns `An error occurred while running the tool. Please try again. Error: <error details>`
+ *
+ * @param context An instance of the current RunContext
+ * @param error The error that occurred
+ */
+function defaultToolErrorFunction(context, error) {
+    const details = error instanceof Error ? error.toString() : String(error);
+    return `An error occurred while running the tool. Please try again. Error: ${details}`;
+}
+/**
+ * Exposes a function to the agent as a tool to be called
+ *
+ * @param options The options for the tool
+ * @returns A new tool
+ */
+export function tool(options) {
+    const name = options.name
+        ? toFunctionToolName(options.name)
+        : toFunctionToolName(options.execute.name);
+    const toolErrorFunction = typeof options.errorFunction === "undefined"
+        ? defaultToolErrorFunction
+        : options.errorFunction;
+    if (!name) {
+        throw new Error("Tool name cannot be empty. Either name your function or provide a name in the options.");
+    }
+    const strictMode = options.strict ?? true;
+    if (!strictMode && isZodObject(options.parameters)) {
+        throw new UserError("Strict mode is required for Zod parameters");
+    }
+    const { parser, schema: parameters } = getSchemaAndParserFromInputType(options.parameters, name);
+    async function _invoke(context, input, details) {
+        const [error, parsed] = await safeExecute(() => parser(input));
+        if (error !== null) {
+            if (logger.dontLogToolData) {
+                logger.debug(`Invalid JSON input for tool ${name}`);
+            }
+            else {
+                logger.debug(`Invalid JSON input for tool ${name}: ${input}`);
+            }
+            throw new ModelBehaviorError("Invalid JSON input for tool");
+        }
+        if (logger.dontLogToolData) {
+            logger.debug(`Invoking tool ${name}`);
+        }
+        else {
+            logger.debug(`Invoking tool ${name} with input ${input}`);
+        }
+        const result = await options.execute(parsed, context, details);
+        const stringResult = toSmartString(result);
+        if (logger.dontLogToolData) {
+            logger.debug(`Tool ${name} completed`);
+        }
+        else {
+            logger.debug(`Tool ${name} returned: ${stringResult}`);
+        }
+        return result;
+    }
+    async function invoke(context, input, details) {
+        return _invoke(context, input, details).catch((error) => {
+            if (toolErrorFunction) {
+                const currentSpan = getCurrentSpan();
+                currentSpan?.setError({
+                    message: "Error running tool (non-fatal)",
+                    data: {
+                        tool_name: name,
+                        error: error.toString(),
+                    },
+                });
+                return toolErrorFunction(context, error);
+            }
+            throw error;
+        });
+    }
+    const needsApproval = typeof options.needsApproval === "function"
+        ? options.needsApproval
+        : async () => typeof options.needsApproval === "boolean"
+            ? options.needsApproval
+            : false;
+    const isEnabled = typeof options.isEnabled === "function"
+        ? async (context, agent) => {
+            const predicate = options.isEnabled;
+            const result = await predicate({ context, agent });
+            return Boolean(result);
+        }
+        : async () => typeof options.isEnabled === "boolean" ? options.isEnabled : true;
+    return {
+        type: "function",
+        name,
+        description: options.description,
+        parameters,
+        strict: strictMode,
+        invoke,
+        needsApproval,
+        isEnabled,
+    };
+}
+function buildRequireApproval(requireApproval) {
+    const result = {};
+    if (requireApproval.always) {
+        result.always = { tool_names: requireApproval.always.toolNames };
+    }
+    if (requireApproval.never) {
+        result.never = { tool_names: requireApproval.never.toolNames };
+    }
+    return result;
+}
+function toMcpAllowedToolsFilter(allowedTools) {
+    if (typeof allowedTools === "undefined") {
+        return undefined;
+    }
+    if (Array.isArray(allowedTools)) {
+        return { tool_names: allowedTools };
+    }
+    return { tool_names: allowedTools?.toolNames ?? [] };
+}

package/dist/trace/processor.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=processor.d.ts.map

package/dist/trace/processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processor.d.ts","sourceRoot":"","sources":["../../src/trace/processor.ts"],"names":[],"mappings":""}

package/dist/trace/processor.js

@@ -0,0 +1 @@
+"use strict";

package/dist/trace/traces.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=traces.d.ts.map

package/dist/trace/traces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traces.d.ts","sourceRoot":"","sources":["../../src/trace/traces.ts"],"names":[],"mappings":""}

package/dist/trace/traces.js

@@ -0,0 +1,73 @@
+"use strict";
+// import { defaultProcessor, TracingProcessor } from "./processor";
+// import { generateTraceId } from "./utils";
+// export type TraceOptions = {
+//   traceId?: string;
+//   name?: string;
+//   groupId?: string;
+//   metadata?: Record<string, any>;
+//   started?: boolean;
+// };
+// export class Trace {
+//   public type = "trace" as const;
+//   public traceId: string;
+//   public name: string;
+//   public groupId: string | null = null;
+//   public metadata?: Record<string, any>;
+//   #processor: TracingProcessor;
+//   #started: boolean;
+//   constructor(options: TraceOptions, processor?: TracingProcessor) {
+//     this.traceId = options.traceId ?? generateTraceId();
+//     this.name = options.name ?? "Agent workflow";
+//     this.groupId = options.groupId ?? null;
+//     this.metadata = options.metadata ?? {};
+//     this.#processor = processor ?? defaultProcessor();
+//     this.#started = options.started ?? false;
+//   }
+//   async start() {
+//     if (this.#started) {
+//       return;
+//     }
+//     this.#started = true;
+//     await this.#processor.onTraceStart(this);
+//   }
+//   async end() {
+//     if (!this.#started) {
+//       return;
+//     }
+//     this.#started = false;
+//     await this.#processor.onTraceEnd(this);
+//   }
+//   clone(): Trace {
+//     return new Trace({
+//       traceId: this.traceId,
+//       name: this.name,
+//       groupId: this.groupId ?? undefined,
+//       metadata: this.metadata,
+//       started: this.#started,
+//     });
+//   }
+//   toJSON(): object | null {
+//     return {
+//       object: this.type,
+//       id: this.traceId,
+//       workflow_name: this.name, // (TODO): why workflow?
+//       group_id: this.groupId,
+//       metadata: this.metadata,
+//     };
+//   }
+// }
+// export class NoopTrace extends Trace {
+//   constructor() {
+//     super({});
+//   }
+//   async start(): Promise<void> {
+//     return;
+//   }
+//   async end(): Promise<void> {
+//     return;
+//   }
+//   toJSON(): object | null {
+//     return null;
+//   }
+// }

package/dist/trace/utils.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Generate a trace ID using 16 random bytes (128-bit, 32 hex chars).
+ * @returns A trace ID prefixed with `trace_`.
+ */
+export declare function generateTraceId(): string;
+/**
+ * Generate a span ID using 12 random bytes (96-bit, 24 hex chars).
+ * @returns A span ID prefixed with `span_`.
+ */
+export declare function generateSpanId(): string;
+/**
+ * Generate a group ID using 12 random bytes (96-bit, 24 hex chars).
+ * @returns A group ID prefixed with `group_`.
+ */
+export declare function generateGroupId(): string;
+/**
+ * Remove fields that start with an underscore from an object.
+ * @param obj - The object to remove private fields from.
+ * @returns A new object with private fields removed.
+ */
+export declare function removePrivateFields(obj: Record<string, any>): Record<string, any>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/trace/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/trace/utils.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACvB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAIrB"}

package/dist/trace/utils.js

@@ -0,0 +1,30 @@
+import { randomID } from "@kernl/shared/lib";
+/**
+ * Generate a trace ID using 16 random bytes (128-bit, 32 hex chars).
+ * @returns A trace ID prefixed with `trace_`.
+ */
+export function generateTraceId() {
+    return `trace_${randomID(16)}`;
+}
+/**
+ * Generate a span ID using 12 random bytes (96-bit, 24 hex chars).
+ * @returns A span ID prefixed with `span_`.
+ */
+export function generateSpanId() {
+    return `span_${randomID(12)}`;
+}
+/**
+ * Generate a group ID using 12 random bytes (96-bit, 24 hex chars).
+ * @returns A group ID prefixed with `group_`.
+ */
+export function generateGroupId() {
+    return `group_${randomID(12)}`;
+}
+/**
+ * Remove fields that start with an underscore from an object.
+ * @param obj - The object to remove private fields from.
+ * @returns A new object with private fields removed.
+ */
+export function removePrivateFields(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([key]) => !key.startsWith("_")));
+}

package/dist/types/agent.d.ts

@@ -0,0 +1,91 @@
+import { type ZodType } from "zod";
+import { Context, UnknownContext } from "../context";
+import { LanguageModel, LanguageModelRequestSettings } from "@kernl/protocol";
+import { InputGuardrail, OutputGuardrail } from "../guardrail";
+import { Toolkit } from "../tool";
+import { TextResponse } from "./thread";
+/**
+ * Configuration for an agent.
+ */
+export interface AgentConfig<TContext = UnknownContext, TResponse extends AgentResponseType = TextResponse> {
+    id: string;
+    name: string;
+    /**
+     * The instructions for the agent. Will be used as the "system prompt" when this agent is
+     * invoked. Describes what the agent should do, and how it responds.
+     *
+     * Can either be a string, or a function that dynamically generates instructions for the agent.
+     * If you provide a function, it will be called with the context and the agent instance. It
+     * must return a string.
+     */
+    instructions: string | ((context: Context<TContext>) => Promise<string> | string);
+    /**
+     * The model implementation to use when invoking the LLM.
+     *
+     * By default, if not set, the agent will use a default model that throws an error when called.
+     */
+    model?: LanguageModel;
+    /**
+     * Configures model-specific tuning parameters (e.g. temperature, top_p, etc.)
+     */
+    modelSettings?: LanguageModelRequestSettings;
+    /**
+     * A list of toolkits the agent can use. Toolkits are collections of related tools
+     * that can be static (FunctionToolkit) or dynamic (MCPToolkit).
+     *
+     * @example
+     * ```typescript
+     * const myTools = new FunctionToolkit({
+     *   id: "custom",
+     *   tools: [tool1, tool2]
+     * });
+     *
+     * const github = new MCPToolkit({
+     *   id: "github",
+     *   server: githubServer
+     * });
+     *
+     * const agent = new Agent({
+     *   name: "Assistant",
+     *   instructions: "...",
+     *   toolkits: [myTools, github]
+     * });
+     * ```
+     */
+    toolkits?: Toolkit<TContext>[];
+    /**
+     * A list of checks that run in parallel to the agent's execution on the input + output for the agent,
+     * depending on the configuration.
+     */
+    guardrails?: AgentGuardrails<TResponse>;
+    /**
+     * The type of the response that the agent will return. If not provided, response will be a string.
+     */
+    responseType?: TResponse;
+    /**
+     * Whether to reset the tool choice to the default value after a tool has been called. Defaults
+     * to `true`. This ensures that the agent doesn't enter an infinite loop of tool usage.
+     */
+    resetToolChoice?: boolean;
+}
+/**
+ * Guardrails for an agent.
+ */
+export interface AgentGuardrails<TResponse extends AgentResponseType = TextResponse> {
+    /**
+     * A list of checks that run in parallel to the agent's execution, before generating a response.
+     * Runs only if the agent is the first agent in the chain.
+     */
+    input: InputGuardrail[];
+    /**
+     * A list of checks that run on the final output of the agent, after generating a response. Runs
+     * only if the agent produces a final output.
+     */
+    output: OutputGuardrail<TResponse>[];
+}
+/**
+ * The type of the output object. If not provided, the output will be a string.
+ * 'text' is a special type that indicates the output will be a string.
+ */
+export type AgentResponseType = TextResponse | ZodType;
+//# sourceMappingURL=agent.d.ts.map

package/dist/types/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/types/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEjC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,WAAW,CAC1B,QAAQ,GAAG,cAAc,EACzB,SAAS,SAAS,iBAAiB,GAAG,YAAY;IAGlD,EAAE,EAAE,MAAM,CAAC;IAGX,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;OAOG;IACH,YAAY,EACR,MAAM,GACN,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;IAe/D;;;;OAIG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IAEtB;;OAEG;IACH,aAAa,CAAC,EAAE,4BAA4B,CAAC;IAE7C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;IAE/B;;;OAGG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAExC;;OAEG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;IAsBzB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAC9B,SAAS,SAAS,iBAAiB,GAAG,YAAY;IAElD;;;OAGG;IACH,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB;;;OAGG;IACH,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,EAAE,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,OAAO,CAAC"}

package/dist/types/agent.js

@@ -0,0 +1 @@
+export {};