kode-sdk 2.7.0

package/dist/tools/toolkit.d.ts

@@ -0,0 +1,69 @@
+import { ZodType } from 'zod';
+import type { ToolInstance } from '../index';
+/**
+ * ToolKit 装饰器元数据
+ */
+interface ToolMethodMetadata {
+    description?: string;
+    parameters?: ZodType;
+    metadata?: any;
+}
+/**
+ * 工具方法装饰器
+ *
+ * @example
+ * ```ts
+ * class WeatherKit extends ToolKit {
+ *   @toolMethod({ description: 'Get current weather' })
+ *   async getWeather(args: { city: string }, ctx: ToolContext) {
+ *     return { temperature: 25, city: args.city };
+ *   }
+ * }
+ * ```
+ */
+export declare function toolMethod(metadata?: ToolMethodMetadata): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * ToolKit 基类
+ *
+ * 提供组织化的工具定义方式
+ *
+ * @example
+ * ```ts
+ * class DatabaseKit extends ToolKit {
+ *   constructor(private db: Database) {
+ *     super('db');
+ *   }
+ *
+ *   @toolMethod({
+ *     description: 'Query database',
+ *     parameters: z.object({ query: z.string() })
+ *   })
+ *   async query(args: { query: string }, ctx: ToolContext) {
+ *     return await this.db.query(args.query);
+ *   }
+ *
+ *   @toolMethod({ description: 'Insert record' })
+ *   async insert(args: { table: string; data: any }, ctx: ToolContext) {
+ *     return await this.db.insert(args.table, args.data);
+ *   }
+ * }
+ *
+ * // 使用
+ * const dbKit = new DatabaseKit(myDatabase);
+ * const tools = dbKit.getTools();
+ * // 返回: [db__query, db__insert]
+ * ```
+ */
+export declare class ToolKit {
+    private readonly namespace?;
+    constructor(namespace?: string | undefined);
+    /**
+     * 获取所有工具实例
+     */
+    getTools(): ToolInstance[];
+    /**
+     * 获取工具名称列表
+     */
+    getToolNames(): string[];
+}
+export {};

package/dist/tools/toolkit.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolKit = void 0;
+exports.toolMethod = toolMethod;
+const zod_1 = require("zod");
+const tool_1 = require("./tool");
+/**
+ * 工具方法装饰器
+ *
+ * @example
+ * ```ts
+ * class WeatherKit extends ToolKit {
+ *   @toolMethod({ description: 'Get current weather' })
+ *   async getWeather(args: { city: string }, ctx: ToolContext) {
+ *     return { temperature: 25, city: args.city };
+ *   }
+ * }
+ * ```
+ */
+function toolMethod(metadata = {}) {
+    return function (target, propertyKey, descriptor) {
+        // 存储元数据到类的原型
+        if (!target.constructor._toolMethods) {
+            target.constructor._toolMethods = new Map();
+        }
+        target.constructor._toolMethods.set(propertyKey, {
+            ...metadata,
+            method: descriptor.value,
+        });
+    };
+}
+/**
+ * ToolKit 基类
+ *
+ * 提供组织化的工具定义方式
+ *
+ * @example
+ * ```ts
+ * class DatabaseKit extends ToolKit {
+ *   constructor(private db: Database) {
+ *     super('db');
+ *   }
+ *
+ *   @toolMethod({
+ *     description: 'Query database',
+ *     parameters: z.object({ query: z.string() })
+ *   })
+ *   async query(args: { query: string }, ctx: ToolContext) {
+ *     return await this.db.query(args.query);
+ *   }
+ *
+ *   @toolMethod({ description: 'Insert record' })
+ *   async insert(args: { table: string; data: any }, ctx: ToolContext) {
+ *     return await this.db.insert(args.table, args.data);
+ *   }
+ * }
+ *
+ * // 使用
+ * const dbKit = new DatabaseKit(myDatabase);
+ * const tools = dbKit.getTools();
+ * // 返回: [db__query, db__insert]
+ * ```
+ */
+class ToolKit {
+    constructor(namespace) {
+        this.namespace = namespace;
+    }
+    /**
+     * 获取所有工具实例
+     */
+    getTools() {
+        const constructor = this.constructor;
+        const toolMethods = constructor._toolMethods;
+        if (!toolMethods) {
+            return [];
+        }
+        const tools = [];
+        for (const [methodName, metadata] of toolMethods) {
+            const toolName = this.namespace ? `${this.namespace}__${methodName}` : methodName;
+            const def = {
+                name: toolName,
+                description: metadata.description || `Execute ${methodName}`,
+                parameters: metadata.parameters || zod_1.z.any(),
+                execute: metadata.method.bind(this),
+                metadata: metadata.metadata,
+            };
+            tools.push((0, tool_1.tool)(def));
+        }
+        return tools;
+    }
+    /**
+     * 获取工具名称列表
+     */
+    getToolNames() {
+        return this.getTools().map((t) => t.name);
+    }
+}
+exports.ToolKit = ToolKit;

package/dist/tools/type-inference.d.ts

@@ -0,0 +1,127 @@
+import { z, ZodType, ZodTypeAny } from 'zod';
+/**
+ * TypeScript 类型到 Zod schema 的自动推断
+ *
+ * 注意：由于 TypeScript 类型在运行时被擦除，我们无法直接从类型生成 schema。
+ * 这个模块提供了一些辅助函数来简化 schema 定义。
+ */
+/**
+ * 从示例对象推断 Zod schema
+ *
+ * @example
+ * ```ts
+ * const schema = inferFromExample({
+ *   name: 'string',
+ *   age: 0,
+ *   active: true,
+ *   tags: ['string']
+ * });
+ * // 等价于:
+ * z.object({
+ *   name: z.string(),
+ *   age: z.number(),
+ *   active: z.boolean(),
+ *   tags: z.array(z.string())
+ * })
+ * ```
+ */
+export declare function inferFromExample<T extends Record<string, any>>(example: T): ZodType<any>;
+/**
+ * Schema 构建器 - 提供流畅的 API
+ *
+ * @example
+ * ```ts
+ * const schema = schema()
+ *   .string('name', 'User name')
+ *   .number('age', 'User age').optional()
+ *   .boolean('active').default(true)
+ *   .array('tags', z.string())
+ *   .build();
+ * ```
+ */
+export declare class SchemaBuilder {
+    private fields;
+    string(name: string, description?: string): this;
+    number(name: string, description?: string): this;
+    boolean(name: string, description?: string): this;
+    array(name: string, itemSchema: ZodTypeAny, description?: string): this;
+    object(name: string, shape: Record<string, ZodTypeAny>, description?: string): this;
+    enum(name: string, values: readonly [string, ...string[]], description?: string): this;
+    optional(name: string): this;
+    default(name: string, defaultValue: any): this;
+    custom(name: string, schema: ZodTypeAny): this;
+    build(): ZodType<any>;
+}
+/**
+ * 创建 schema 构建器
+ */
+export declare function schema(): SchemaBuilder;
+/**
+ * 快速定义常用的 schema 模式
+ */
+export declare const patterns: {
+    /**
+     * 文件路径
+     */
+    filePath: (description?: string) => z.ZodString;
+    /**
+     * 目录路径
+     */
+    dirPath: (description?: string) => z.ZodString;
+    /**
+     * URL
+     */
+    url: (description?: string) => z.ZodString;
+    /**
+     * Email
+     */
+    email: (description?: string) => z.ZodString;
+    /**
+     * 正整数
+     */
+    positiveInt: (description?: string) => z.ZodNumber;
+    /**
+     * 非负整数
+     */
+    nonNegativeInt: (description?: string) => z.ZodNumber;
+    /**
+     * 字符串数组
+     */
+    stringArray: (description?: string) => z.ZodArray<z.ZodString, "many">;
+    /**
+     * 可选字符串
+     */
+    optionalString: (description?: string) => z.ZodOptional<z.ZodString>;
+    /**
+     * 可选数字
+     */
+    optionalNumber: (description?: string) => z.ZodOptional<z.ZodNumber>;
+    /**
+     * JSON 对象
+     */
+    json: (description?: string) => z.ZodRecord<z.ZodString, z.ZodAny>;
+};
+/**
+ * 从 JSDoc 注释推断 schema（实验性）
+ *
+ * 这需要在构建时使用 TypeScript Compiler API 解析
+ * 当前仅提供接口，实际实现需要编译时支持
+ */
+export interface JSDocSchema {
+    /**
+     * @param name - Parameter name
+     * @param type - TypeScript type string (e.g., 'string', 'number', 'Array<string>')
+     * @param description - Parameter description
+     * @param optional - Whether parameter is optional
+     */
+    param(name: string, type: string, description?: string, optional?: boolean): this;
+    build(): ZodType<any>;
+}
+/**
+ * 辅助函数：合并多个 schema
+ */
+export declare function mergeSchemas(...schemas: ZodType<any>[]): ZodType<any>;
+/**
+ * 辅助函数：扩展 schema
+ */
+export declare function extendSchema<T extends ZodType<any>>(base: T, extension: Record<string, ZodTypeAny>): ZodType<any>;

package/dist/tools/type-inference.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.patterns = exports.SchemaBuilder = void 0;
+exports.inferFromExample = inferFromExample;
+exports.schema = schema;
+exports.mergeSchemas = mergeSchemas;
+exports.extendSchema = extendSchema;
+const zod_1 = require("zod");
+/**
+ * TypeScript 类型到 Zod schema 的自动推断
+ *
+ * 注意：由于 TypeScript 类型在运行时被擦除，我们无法直接从类型生成 schema。
+ * 这个模块提供了一些辅助函数来简化 schema 定义。
+ */
+/**
+ * 从示例对象推断 Zod schema
+ *
+ * @example
+ * ```ts
+ * const schema = inferFromExample({
+ *   name: 'string',
+ *   age: 0,
+ *   active: true,
+ *   tags: ['string']
+ * });
+ * // 等价于:
+ * z.object({
+ *   name: z.string(),
+ *   age: z.number(),
+ *   active: z.boolean(),
+ *   tags: z.array(z.string())
+ * })
+ * ```
+ */
+function inferFromExample(example) {
+    const shape = {};
+    for (const [key, value] of Object.entries(example)) {
+        shape[key] = inferValueType(value);
+    }
+    return zod_1.z.object(shape);
+}
+/**
+ * 推断单个值的类型
+ */
+function inferValueType(value) {
+    if (value === null || value === undefined) {
+        return zod_1.z.any();
+    }
+    const type = typeof value;
+    switch (type) {
+        case 'string':
+            return zod_1.z.string();
+        case 'number':
+            return zod_1.z.number();
+        case 'boolean':
+            return zod_1.z.boolean();
+        case 'object':
+            if (Array.isArray(value)) {
+                if (value.length === 0) {
+                    return zod_1.z.array(zod_1.z.any());
+                }
+                return zod_1.z.array(inferValueType(value[0]));
+            }
+            return inferFromExample(value);
+        default:
+            return zod_1.z.any();
+    }
+}
+/**
+ * Schema 构建器 - 提供流畅的 API
+ *
+ * @example
+ * ```ts
+ * const schema = schema()
+ *   .string('name', 'User name')
+ *   .number('age', 'User age').optional()
+ *   .boolean('active').default(true)
+ *   .array('tags', z.string())
+ *   .build();
+ * ```
+ */
+class SchemaBuilder {
+    constructor() {
+        this.fields = {};
+    }
+    string(name, description) {
+        this.fields[name] = description ? zod_1.z.string().describe(description) : zod_1.z.string();
+        return this;
+    }
+    number(name, description) {
+        this.fields[name] = description ? zod_1.z.number().describe(description) : zod_1.z.number();
+        return this;
+    }
+    boolean(name, description) {
+        this.fields[name] = description ? zod_1.z.boolean().describe(description) : zod_1.z.boolean();
+        return this;
+    }
+    array(name, itemSchema, description) {
+        const schema = zod_1.z.array(itemSchema);
+        this.fields[name] = description ? schema.describe(description) : schema;
+        return this;
+    }
+    object(name, shape, description) {
+        const schema = zod_1.z.object(shape);
+        this.fields[name] = description ? schema.describe(description) : schema;
+        return this;
+    }
+    enum(name, values, description) {
+        const schema = zod_1.z.enum(values);
+        this.fields[name] = description ? schema.describe(description) : schema;
+        return this;
+    }
+    optional(name) {
+        if (this.fields[name]) {
+            this.fields[name] = this.fields[name].optional();
+        }
+        return this;
+    }
+    default(name, defaultValue) {
+        if (this.fields[name]) {
+            this.fields[name] = this.fields[name].default(defaultValue);
+        }
+        return this;
+    }
+    custom(name, schema) {
+        this.fields[name] = schema;
+        return this;
+    }
+    build() {
+        return zod_1.z.object(this.fields);
+    }
+}
+exports.SchemaBuilder = SchemaBuilder;
+/**
+ * 创建 schema 构建器
+ */
+function schema() {
+    return new SchemaBuilder();
+}
+/**
+ * 快速定义常用的 schema 模式
+ */
+exports.patterns = {
+    /**
+     * 文件路径
+     */
+    filePath: (description = 'File path') => zod_1.z.string().describe(description),
+    /**
+     * 目录路径
+     */
+    dirPath: (description = 'Directory path') => zod_1.z.string().describe(description),
+    /**
+     * URL
+     */
+    url: (description = 'URL') => zod_1.z.string().url().describe(description),
+    /**
+     * Email
+     */
+    email: (description = 'Email address') => zod_1.z.string().email().describe(description),
+    /**
+     * 正整数
+     */
+    positiveInt: (description = 'Positive integer') => zod_1.z.number().int().positive().describe(description),
+    /**
+     * 非负整数
+     */
+    nonNegativeInt: (description = 'Non-negative integer') => zod_1.z.number().int().nonnegative().describe(description),
+    /**
+     * 字符串数组
+     */
+    stringArray: (description = 'Array of strings') => zod_1.z.array(zod_1.z.string()).describe(description),
+    /**
+     * 可选字符串
+     */
+    optionalString: (description) => zod_1.z.string().optional().describe(description || 'Optional string'),
+    /**
+     * 可选数字
+     */
+    optionalNumber: (description) => zod_1.z.number().optional().describe(description || 'Optional number'),
+    /**
+     * JSON 对象
+     */
+    json: (description = 'JSON object') => zod_1.z.record(zod_1.z.any()).describe(description),
+};
+/**
+ * 辅助函数：合并多个 schema
+ */
+function mergeSchemas(...schemas) {
+    if (schemas.length === 0) {
+        return zod_1.z.object({});
+    }
+    if (schemas.length === 1) {
+        return schemas[0];
+    }
+    // 使用 z.intersection 合并
+    return schemas.reduce((acc, schema) => acc.and(schema));
+}
+/**
+ * 辅助函数：扩展 schema
+ */
+function extendSchema(base, extension) {
+    if (base instanceof zod_1.z.ZodObject) {
+        return base.extend(extension);
+    }
+    // 如果不是 object schema，创建新的 object schema
+    return zod_1.z.object(extension);
+}

package/dist/utils/agent-id.d.ts

@@ -0,0 +1 @@
+export declare function generateAgentId(): string;

package/dist/utils/agent-id.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateAgentId = generateAgentId;
+const CROCKFORD32 = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+function encodeTime(time, length) {
+    let remaining = time;
+    const chars = Array(length);
+    for (let i = length - 1; i >= 0; i--) {
+        const mod = remaining % 32;
+        chars[i] = CROCKFORD32.charAt(mod);
+        remaining = Math.floor(remaining / 32);
+    }
+    return chars.join('');
+}
+function encodeRandom(length) {
+    const chars = Array(length);
+    for (let i = 0; i < length; i++) {
+        const rand = Math.floor(Math.random() * 32);
+        chars[i] = CROCKFORD32.charAt(rand);
+    }
+    return chars.join('');
+}
+function generateAgentId() {
+    const time = Date.now();
+    const timePart = encodeTime(time, 10);
+    const randomPart = encodeRandom(16);
+    return `agt:${timePart}${randomPart}`;
+}

package/dist/utils/session-id.d.ts

@@ -0,0 +1,21 @@
+export interface SessionIdComponents {
+    orgId?: string;
+    teamId?: string;
+    userId?: string;
+    agentTemplate: string;
+    rootId: string;
+    forkIds: string[];
+}
+export declare class SessionId {
+    static parse(id: string): SessionIdComponents;
+    static generate(opts: {
+        orgId?: string;
+        teamId?: string;
+        userId?: string;
+        agentTemplate: string;
+        parentSessionId?: string;
+    }): string;
+    static snapshot(sessionId: string, sfpIndex: number): string;
+    static label(sessionId: string, label: string): string;
+    private static randomId;
+}

package/dist/utils/session-id.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionId = void 0;
+class SessionId {
+    static parse(id) {
+        const parts = id.split('/');
+        const components = {
+            agentTemplate: '',
+            rootId: '',
+            forkIds: [],
+        };
+        for (const part of parts) {
+            if (part.startsWith('org:')) {
+                components.orgId = part.slice(4);
+            }
+            else if (part.startsWith('team:')) {
+                components.teamId = part.slice(5);
+            }
+            else if (part.startsWith('user:')) {
+                components.userId = part.slice(5);
+            }
+            else if (part.startsWith('agent:')) {
+                components.agentTemplate = part.slice(6);
+            }
+            else if (part.startsWith('session:')) {
+                components.rootId = part.slice(8);
+            }
+            else if (part.startsWith('fork:')) {
+                components.forkIds.push(part.slice(5));
+            }
+        }
+        return components;
+    }
+    static generate(opts) {
+        const parts = [];
+        if (opts.orgId)
+            parts.push(`org:${opts.orgId}`);
+        if (opts.teamId)
+            parts.push(`team:${opts.teamId}`);
+        if (opts.userId)
+            parts.push(`user:${opts.userId}`);
+        parts.push(`agent:${opts.agentTemplate}`);
+        if (opts.parentSessionId) {
+            const parent = SessionId.parse(opts.parentSessionId);
+            parts.push(`session:${parent.rootId}`);
+            parts.push(...parent.forkIds.map((id) => `fork:${id}`));
+            parts.push(`fork:${this.randomId()}`);
+        }
+        else {
+            parts.push(`session:${this.randomId()}`);
+        }
+        return parts.join('/');
+    }
+    static snapshot(sessionId, sfpIndex) {
+        return `${sessionId}@sfp:${sfpIndex}`;
+    }
+    static label(sessionId, label) {
+        return `${sessionId}@label:${label}`;
+    }
+    static randomId() {
+        return Math.random().toString(36).slice(2, 8);
+    }
+}
+exports.SessionId = SessionId;

package/dist/utils/unicode.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Unicode helpers
+ *
+ * JavaScript strings are UTF-16. If we truncate with `slice()` we can split a surrogate pair
+ * (common with emoji), producing an invalid lone surrogate such as `\uD83D`.
+ *
+ * Some downstream JSON/UTF-8 encoders (notably server-side Python) reject lone surrogates with:
+ * "surrogates not allowed".
+ */
+export declare function stripInvalidSurrogates(input: string, replacement?: string): string;
+/**
+ * Truncate a UTF-16 JS string without splitting surrogate pairs.
+ *
+ * NOTE: `maxCodeUnits` is the same unit as `string.length` (UTF-16 code units), so this is a
+ * drop-in safer alternative to `slice(0, maxCodeUnits)`.
+ */
+export declare function safeTruncateUtf16(input: string, maxCodeUnits: number): string;

package/dist/utils/unicode.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripInvalidSurrogates = stripInvalidSurrogates;
+exports.safeTruncateUtf16 = safeTruncateUtf16;
+/**
+ * Unicode helpers
+ *
+ * JavaScript strings are UTF-16. If we truncate with `slice()` we can split a surrogate pair
+ * (common with emoji), producing an invalid lone surrogate such as `\uD83D`.
+ *
+ * Some downstream JSON/UTF-8 encoders (notably server-side Python) reject lone surrogates with:
+ * "surrogates not allowed".
+ */
+function stripInvalidSurrogates(input, replacement = '\uFFFD') {
+    if (!input)
+        return '';
+    let out = '';
+    for (let i = 0; i < input.length; i++) {
+        const code = input.charCodeAt(i);
+        // High surrogate
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = i + 1 < input.length ? input.charCodeAt(i + 1) : 0;
+            // Valid pair
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                out += input[i] + input[i + 1];
+                i++;
+                continue;
+            }
+            // Lone high surrogate
+            out += replacement;
+            continue;
+        }
+        // Lone low surrogate
+        if (code >= 0xdc00 && code <= 0xdfff) {
+            out += replacement;
+            continue;
+        }
+        out += input[i];
+    }
+    return out;
+}
+/**
+ * Truncate a UTF-16 JS string without splitting surrogate pairs.
+ *
+ * NOTE: `maxCodeUnits` is the same unit as `string.length` (UTF-16 code units), so this is a
+ * drop-in safer alternative to `slice(0, maxCodeUnits)`.
+ */
+function safeTruncateUtf16(input, maxCodeUnits) {
+    const text = stripInvalidSurrogates(String(input ?? ''));
+    const limit = Number.isFinite(maxCodeUnits) ? Math.max(0, Math.floor(maxCodeUnits)) : 0;
+    if (limit <= 0)
+        return '';
+    if (text.length <= limit)
+        return text;
+    let sliced = text.slice(0, limit);
+    // If we ended on a high surrogate, drop it to avoid creating a lone surrogate.
+    const last = sliced.charCodeAt(sliced.length - 1);
+    if (last >= 0xd800 && last <= 0xdbff) {
+        sliced = sliced.slice(0, -1);
+    }
+    return stripInvalidSurrogates(sliced);
+}