@shareai-lab/kode-sdk 1.0.0-beta.9 → 2.7.0

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.string(), 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/logger.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 日志工具模块
+ *
+ * 仅在 NODE_ENV=local 时输出日志，生产环境静默
+ */
+/**
+ * 日志输出（仅在 NODE_ENV=local 时输出）
+ */
+export declare const logger: {
+    log: (...args: any[]) => void;
+    info: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+    debug: (...args: any[]) => void;
+};

package/dist/utils/logger.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * 日志工具模块
+ *
+ * 仅在 NODE_ENV=local 时输出日志，生产环境静默
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+/**
+ * 检查是否启用日志（仅在本地开发环境）
+ */
+function isLoggingEnabled() {
+    return process.env.NODE_ENV === 'local';
+}
+/**
+ * 日志输出（仅在 NODE_ENV=local 时输出）
+ */
+exports.logger = {
+    log: (...args) => {
+        if (isLoggingEnabled()) {
+            console.log(...args);
+        }
+    },
+    info: (...args) => {
+        if (isLoggingEnabled()) {
+            console.info(...args);
+        }
+    },
+    warn: (...args) => {
+        if (isLoggingEnabled()) {
+            console.warn(...args);
+        }
+    },
+    error: (...args) => {
+        if (isLoggingEnabled()) {
+            console.error(...args);
+        }
+    },
+    debug: (...args) => {
+        if (isLoggingEnabled()) {
+            console.debug(...args);
+        }
+    },
+};

package/dist/utils/session-id.js

@@ -10,22 +10,22 @@ class SessionId {
             forkIds: [],
         };
         for (const part of parts) {
-            if (part.startsWith('org:')) {
+            if (part.startsWith('org-')) {
                 components.orgId = part.slice(4);
             }
-            else if (part.startsWith('team:')) {
+            else if (part.startsWith('team-')) {
                 components.teamId = part.slice(5);
             }
-            else if (part.startsWith('user:')) {
+            else if (part.startsWith('user-')) {
                 components.userId = part.slice(5);
             }
-            else if (part.startsWith('agent:')) {
+            else if (part.startsWith('agent-')) {
                 components.agentTemplate = part.slice(6);
             }
-            else if (part.startsWith('session:')) {
+            else if (part.startsWith('session-')) {
                 components.rootId = part.slice(8);
             }
-            else if (part.startsWith('fork:')) {
+            else if (part.startsWith('fork-')) {
                 components.forkIds.push(part.slice(5));
             }
         }
@@ -34,28 +34,28 @@ class SessionId {
     static generate(opts) {
         const parts = [];
         if (opts.orgId)
-            parts.push(`org:${opts.orgId}`);
+            parts.push(`org-${opts.orgId}`);
         if (opts.teamId)
-            parts.push(`team:${opts.teamId}`);
+            parts.push(`team-${opts.teamId}`);
         if (opts.userId)
-            parts.push(`user:${opts.userId}`);
-        parts.push(`agent:${opts.agentTemplate}`);
+            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()}`);
+            parts.push(`session-${parent.rootId}`);
+            parts.push(...parent.forkIds.map((id) => `fork-${id}`));
+            parts.push(`fork-${this.randomId()}`);
         }
         else {
-            parts.push(`session:${this.randomId()}`);
+            parts.push(`session-${this.randomId()}`);
         }
         return parts.join('/');
     }
     static snapshot(sessionId, sfpIndex) {
-        return `${sessionId}@sfp:${sfpIndex}`;
+        return `${sessionId}@sfp-${sfpIndex}`;
     }
     static label(sessionId, label) {
-        return `${sessionId}@label:${label}`;
+        return `${sessionId}@label-${label}`;
     }
     static randomId() {
         return Math.random().toString(36).slice(2, 8);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shareai-lab/kode-sdk",
-  "version": "1.0.0-beta.9",
-  "description": "Event-driven Agent Model Client SDK for building long-running, collaborative AI agents",
+  "version": "2.7.0",
+  "description": "Event-driven, long-running AI Agent development framework with enterprise-grade persistence and context management",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
@@ -9,14 +9,24 @@
     "dev": "tsc --watch",
     "clean": "rm -rf dist",
     "prepare": "npm run build",
-    "test:cli": "ts-node test-cli.ts",
-    "example:u1": "ts-node examples/u1-nextjs-backend.ts",
-    "example:u2": "ts-node examples/u2-permission-approval.ts",
-    "example:u3": "ts-node examples/u3-hook-guard.ts",
-    "example:u4": "ts-node examples/u4-scheduler.ts",
-    "example:u5": "ts-node examples/u5-sub-agent.ts",
-    "example:u6": "ts-node examples/u6-room-chat.ts",
-    "example:u7": "ts-node examples/u7-chatdev-team.ts"
+    "test": "npm run test:unit",
+    "test:unit": "ts-node --project tsconfig.json ./tests/run-unit.ts",
+    "test:integration": "ts-node --project tsconfig.json ./tests/run-integration.ts",
+    "test:e2e": "ts-node --project tsconfig.json ./tests/run-e2e.ts",
+    "test:all": "ts-node --project tsconfig.json ./tests/run-all.ts",
+    "example:getting-started": "ts-node examples/getting-started.ts",
+    "example:openai": "ts-node examples/openai-usage.ts",
+    "example:gemini": "ts-node examples/gemini-usage.ts",
+    "example:agent-inbox": "ts-node examples/01-agent-inbox.ts",
+    "example:approval": "ts-node examples/02-approval-control.ts",
+    "example:room": "ts-node examples/03-room-collab.ts",
+    "example:scheduler": "ts-node examples/04-scheduler-watch.ts",
+    "example:nextjs": "ts-node examples/nextjs-api-route.ts",
+    "example:openrouter": "ts-node examples/05-openrouter-complete.ts",
+    "example:openrouter-stream": "ts-node examples/06-openrouter-stream.ts",
+    "example:openrouter-agent": "ts-node examples/07-openrouter-agent.ts",
+    "example:db-sqlite": "ts-node examples/db-sqlite.ts",
+    "example:db-postgres": "ts-node examples/db-postgres.ts"
   },
   "keywords": [
     "agent",
@@ -31,9 +41,23 @@
   ],
   "author": "",
   "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "~1.22.0",
+    "ajv": "^8.17.1",
+    "better-sqlite3": "^12.6.2",
+    "dotenv": "^16.4.5",
+    "e2b": "^2.10.3",
+    "fast-glob": "^3.3.2",
+    "pg": "^8.17.2",
+    "undici": "^7.18.2",
+    "zod": "~3.23.8",
+    "zod-to-json-schema": "~3.23.0"
+  },
   "devDependencies": {
-    "@shareai-lab/kode-sdk": "^1.0.0-beta.9",
+    "@shareai-lab/kode-sdk": "file:.",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^20.0.0",
+    "@types/pg": "^8.16.0",
     "ts-node": "^10.9.0",
     "typescript": "^5.3.0"
   },

package/dist/tools/bash.d.ts

@@ -1,63 +0,0 @@
-import { ToolContext } from '../core/types';
-import { Tool } from './fs';
-export declare class BashRun implements Tool {
-    name: string;
-    description: string;
-    input_schema: {
-        type: string;
-        properties: {
-            cmd: {
-                type: string;
-                description: string;
-            };
-            timeout_ms: {
-                type: string;
-                description: string;
-            };
-            background: {
-                type: string;
-                description: string;
-            };
-        };
-        required: string[];
-    };
-    exec(args: {
-        cmd: string;
-        timeout_ms?: number;
-        background?: boolean;
-    }, ctx: ToolContext): Promise<any>;
-}
-export declare class BashLogs implements Tool {
-    name: string;
-    description: string;
-    input_schema: {
-        type: string;
-        properties: {
-            shell_id: {
-                type: string;
-                description: string;
-            };
-        };
-        required: string[];
-    };
-    exec(args: {
-        shell_id: string;
-    }, ctx: ToolContext): Promise<any>;
-}
-export declare class BashKill implements Tool {
-    name: string;
-    description: string;
-    input_schema: {
-        type: string;
-        properties: {
-            shell_id: {
-                type: string;
-                description: string;
-            };
-        };
-        required: string[];
-    };
-    exec(args: {
-        shell_id: string;
-    }, ctx: ToolContext): Promise<any>;
-}