@shareai-lab/kode-sdk 2.7.3 → 2.7.4

package/README.md

@@ -10,7 +10,7 @@
 - **Long-Running & Resumable** - Seven-stage checkpoints with Safe-Fork-Point for crash recovery
 - **Multi-Agent Collaboration** - AgentPool, Room messaging, and task delegation
 - **Enterprise Persistence** - SQLite/PostgreSQL support with unified WAL
-- **Cloud Sandbox** - [E2B](https://e2b.dev) integration for isolated remote code execution
+- **Cloud Sandbox** - [E2B](https://e2b.dev) and OpenSandbox integration for isolated remote code execution
 - **Extensible Ecosystem** - MCP tools, custom Providers, Skills system
 
 ## Quick Start
@@ -79,6 +79,15 @@ npm run example:getting-started    # Minimal chat
 npm run example:agent-inbox        # Event-driven inbox
 npm run example:approval           # Tool approval workflow
 npm run example:room               # Multi-agent collaboration
+npm run example:opensandbox        # OpenSandbox basic usage
+```
+
+OpenSandbox quick config:
+
+```bash
+export OPEN_SANDBOX_API_KEY=...                      # optional (required only when auth is enabled)
+export OPEN_SANDBOX_ENDPOINT=http://127.0.0.1:8080  # optional
+export OPEN_SANDBOX_IMAGE=ubuntu                     # optional
 ```
 
 ## Architecture for Scale
@@ -142,6 +151,8 @@ See [docs/en/guides/architecture.md](./docs/en/guides/architecture.md) for detai
 | **Guides** | |
 | [Events](./docs/en/guides/events.md) | Three-channel event system |
 | [Tools](./docs/en/guides/tools.md) | Built-in tools & custom tools |
+| [E2B Sandbox](./docs/en/guides/e2b-sandbox.md) | E2B cloud sandbox integration |
+| [OpenSandbox](./docs/en/guides/opensandbox-sandbox.md) | OpenSandbox self-hosted sandbox integration |
 | [Skills](./docs/en/guides/skills.md) | Skills system for reusable prompts |
 | [Providers](./docs/en/guides/providers.md) | Model provider configuration |
 | [Database](./docs/en/guides/database.md) | SQLite/PostgreSQL persistence |

package/README.zh-CN.md

@@ -10,7 +10,7 @@
 - **长时运行与恢复** - 七段断点机制，支持 Safe-Fork-Point 崩溃恢复
 - **多 Agent 协作** - AgentPool、Room 消息、任务委派
 - **企业级持久化** - 支持 SQLite/PostgreSQL，统一 WAL 日志
-- **云端沙箱** - 集成 [E2B](https://e2b.dev)，提供隔离的远程代码执行环境
+- **云端沙箱** - 集成 [E2B](https://e2b.dev) 与 OpenSandbox，提供隔离的远程代码执行环境
 - **可扩展生态** - MCP 工具、自定义 Provider、Skills 系统
 
 ## 快速开始
@@ -79,6 +79,15 @@ npm run example:getting-started    # 最简对话
 npm run example:agent-inbox        # 事件驱动收件箱
 npm run example:approval           # 工具审批流程
 npm run example:room               # 多Agent协作
+npm run example:opensandbox        # OpenSandbox 基础使用
+```
+
+OpenSandbox 快速配置：
+
+```bash
+export OPEN_SANDBOX_API_KEY=...                      # 可选（仅在服务开启鉴权时需要）
+export OPEN_SANDBOX_ENDPOINT=http://127.0.0.1:8080  # 可选
+export OPEN_SANDBOX_IMAGE=ubuntu                     # 可选
 ```
 
 ## 支持的 Provider
@@ -102,6 +111,8 @@ npm run example:room               # 多Agent协作
 | **使用指南** | |
 | [事件系统](./docs/zh-CN/guides/events.md) | 三通道事件系统 |
 | [工具系统](./docs/zh-CN/guides/tools.md) | 内置工具与自定义工具 |
+| [E2B 沙箱](./docs/zh-CN/guides/e2b-sandbox.md) | E2B 云端沙箱接入 |
+| [OpenSandbox 沙箱](./docs/zh-CN/guides/opensandbox-sandbox.md) | OpenSandbox 自托管沙箱接入 |
 | [Skills 系统](./docs/zh-CN/guides/skills.md) | Skills 可复用提示词系统 |
 | [Provider 配置](./docs/zh-CN/guides/providers.md) | 模型 Provider 配置 |
 | [数据库存储](./docs/zh-CN/guides/database.md) | SQLite/PostgreSQL 持久化 |

package/dist/core/agent.js

@@ -195,12 +195,22 @@ class Agent {
             config.agentId = Agent.generateAgentId();
         }
         const template = deps.templateRegistry.get(config.templateId);
-        const sandboxConfig = config.sandbox && 'kind' in config.sandbox
+        const sandboxConfigSource = config.sandbox && 'kind' in config.sandbox
             ? config.sandbox
             : template.sandbox;
+        const sandboxConfig = sandboxConfigSource
+            ? { ...sandboxConfigSource }
+            : undefined;
         const sandbox = typeof config.sandbox === 'object' && 'exec' in config.sandbox
             ? config.sandbox
             : await deps.sandboxFactory.createAsync(sandboxConfig || { kind: 'local', workDir: process.cwd() });
+        // OpenSandbox creates sandbox id at runtime; persist it for strict resume.
+        if (sandboxConfig?.kind === 'opensandbox' && typeof sandbox.getSandboxId === 'function') {
+            const sandboxId = sandbox.getSandboxId();
+            if (sandboxId) {
+                sandboxConfig.sandboxId = sandboxId;
+            }
+        }
         const model = config.model
             ? config.model
             : config.modelConfig

package/dist/index.d.ts

@@ -27,6 +27,8 @@ export { PostgresStore } from './infra/db/postgres/postgres-store';
 export { Sandbox, LocalSandbox, SandboxKind } from './infra/sandbox';
 export { E2BSandbox, E2BFS, E2BTemplateBuilder } from './infra/e2b';
 export type { E2BSandboxOptions, E2BTemplateConfig } from './infra/e2b';
+export { OpenSandbox, OpenSandboxFS } from './infra/opensandbox';
+export type { OpenSandboxOptions, OpenSandboxWatchMode } from './infra/opensandbox';
 export { ModelProvider, ModelConfig, ModelResponse, ModelStreamChunk, AnthropicProvider, OpenAIProvider, GeminiProvider, } from './infra/provider';
 export { SandboxFactory } from './infra/sandbox-factory';
 export { FsRead } from './tools/fs_read';

package/dist/index.js

@@ -14,8 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BashLogs = exports.BashRun = exports.FsMultiEdit = exports.FsGrep = exports.FsGlob = exports.FsEdit = exports.FsWrite = exports.FsRead = exports.SandboxFactory = exports.GeminiProvider = exports.OpenAIProvider = exports.AnthropicProvider = exports.E2BTemplateBuilder = exports.E2BFS = exports.E2BSandbox = exports.LocalSandbox = exports.PostgresStore = exports.SqliteStore = exports.createExtendedStore = exports.createStore = exports.JSONStore = exports.ProviderCapabilityError = exports.UnsupportedProviderError = exports.UnsupportedContentBlockError = exports.MultimodalValidationError = exports.ResumeError = exports.PermissionModeRegistry = exports.permissionModes = exports.ToolRunner = exports.TodoManager = exports.MessageQueue = exports.PermissionManager = exports.BreakpointManager = exports.SandboxFileManager = exports.OperationStatus = exports.OperationType = exports.OperationQueue = exports.SkillsManagementManager = exports.SkillsManager = exports.TimeBridge = exports.TodoService = exports.AgentTemplateRegistry = exports.FilePool = exports.ContextManager = exports.HookManager = exports.EventBus = exports.Scheduler = exports.Room = exports.AgentPool = exports.Agent = void 0;
-exports.generateAgentId = exports.extendSchema = exports.mergeSchemas = exports.SchemaBuilder = exports.patterns = exports.schema = exports.inferFromExample = exports.createScriptsTool = exports.createSkillsTool = exports.toolMethod = exports.ToolKit = exports.disconnectAllMCP = exports.disconnectMCP = exports.getMCPTools = exports.tools = exports.tool = exports.extractTools = exports.defineTools = exports.defineTool = exports.globalToolRegistry = exports.ToolRegistry = exports.builtin = exports.TodoWrite = exports.TodoRead = exports.createTaskRunTool = exports.BashKill = void 0;
+exports.FsMultiEdit = exports.FsGrep = exports.FsGlob = exports.FsEdit = exports.FsWrite = exports.FsRead = exports.SandboxFactory = exports.GeminiProvider = exports.OpenAIProvider = exports.AnthropicProvider = exports.OpenSandboxFS = exports.OpenSandbox = exports.E2BTemplateBuilder = exports.E2BFS = exports.E2BSandbox = exports.LocalSandbox = exports.PostgresStore = exports.SqliteStore = exports.createExtendedStore = exports.createStore = exports.JSONStore = exports.ProviderCapabilityError = exports.UnsupportedProviderError = exports.UnsupportedContentBlockError = exports.MultimodalValidationError = exports.ResumeError = exports.PermissionModeRegistry = exports.permissionModes = exports.ToolRunner = exports.TodoManager = exports.MessageQueue = exports.PermissionManager = exports.BreakpointManager = exports.SandboxFileManager = exports.OperationStatus = exports.OperationType = exports.OperationQueue = exports.SkillsManagementManager = exports.SkillsManager = exports.TimeBridge = exports.TodoService = exports.AgentTemplateRegistry = exports.FilePool = exports.ContextManager = exports.HookManager = exports.EventBus = exports.Scheduler = exports.Room = exports.AgentPool = exports.Agent = void 0;
+exports.generateAgentId = exports.extendSchema = exports.mergeSchemas = exports.SchemaBuilder = exports.patterns = exports.schema = exports.inferFromExample = exports.createScriptsTool = exports.createSkillsTool = exports.toolMethod = exports.ToolKit = exports.disconnectAllMCP = exports.disconnectMCP = exports.getMCPTools = exports.tools = exports.tool = exports.extractTools = exports.defineTools = exports.defineTool = exports.globalToolRegistry = exports.ToolRegistry = exports.builtin = exports.TodoWrite = exports.TodoRead = exports.createTaskRunTool = exports.BashKill = exports.BashLogs = exports.BashRun = void 0;
 // Core
 var agent_1 = require("./core/agent");
 Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return agent_1.Agent; } });
@@ -84,6 +84,9 @@ var e2b_1 = require("./infra/e2b");
 Object.defineProperty(exports, "E2BSandbox", { enumerable: true, get: function () { return e2b_1.E2BSandbox; } });
 Object.defineProperty(exports, "E2BFS", { enumerable: true, get: function () { return e2b_1.E2BFS; } });
 Object.defineProperty(exports, "E2BTemplateBuilder", { enumerable: true, get: function () { return e2b_1.E2BTemplateBuilder; } });
+var opensandbox_1 = require("./infra/opensandbox");
+Object.defineProperty(exports, "OpenSandbox", { enumerable: true, get: function () { return opensandbox_1.OpenSandbox; } });
+Object.defineProperty(exports, "OpenSandboxFS", { enumerable: true, get: function () { return opensandbox_1.OpenSandboxFS; } });
 var provider_1 = require("./infra/provider");
 Object.defineProperty(exports, "AnthropicProvider", { enumerable: true, get: function () { return provider_1.AnthropicProvider; } });
 Object.defineProperty(exports, "OpenAIProvider", { enumerable: true, get: function () { return provider_1.OpenAIProvider; } });

package/dist/infra/opensandbox/index.d.ts

@@ -0,0 +1,3 @@
+export { OpenSandbox } from './opensandbox-sandbox';
+export { OpenSandboxFS } from './opensandbox-fs';
+export type { OpenSandboxOptions, OpenSandboxWatchMode } from './types';

package/dist/infra/opensandbox/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenSandboxFS = exports.OpenSandbox = void 0;
+var opensandbox_sandbox_1 = require("./opensandbox-sandbox");
+Object.defineProperty(exports, "OpenSandbox", { enumerable: true, get: function () { return opensandbox_sandbox_1.OpenSandbox; } });
+var opensandbox_fs_1 = require("./opensandbox-fs");
+Object.defineProperty(exports, "OpenSandboxFS", { enumerable: true, get: function () { return opensandbox_fs_1.OpenSandboxFS; } });

package/dist/infra/opensandbox/opensandbox-fs.d.ts

@@ -0,0 +1,27 @@
+import type { Sandbox as OpenSandboxClient } from '@alibaba-group/opensandbox';
+import { SandboxFS } from '../sandbox';
+export interface OpenSandboxFSHost {
+    workDir: string;
+    getOpenSandbox(): OpenSandboxClient;
+}
+export declare class OpenSandboxFS implements SandboxFS {
+    private readonly host;
+    constructor(host: OpenSandboxFSHost);
+    resolve(p: string): string;
+    isInside(_p: string): boolean;
+    read(p: string): Promise<string>;
+    write(p: string, content: string): Promise<void>;
+    temp(name?: string): string;
+    stat(p: string): Promise<{
+        mtimeMs: number;
+    }>;
+    glob(pattern: string, opts?: {
+        cwd?: string;
+        ignore?: string[];
+        dot?: boolean;
+        absolute?: boolean;
+    }): Promise<string[]>;
+    private hasDotPath;
+    private toTimestamp;
+    private matchGlob;
+}

package/dist/infra/opensandbox/opensandbox-fs.js

@@ -0,0 +1,113 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenSandboxFS = void 0;
+const path_1 = __importDefault(require("path"));
+const minimatch_1 = require("minimatch");
+class OpenSandboxFS {
+    constructor(host) {
+        this.host = host;
+    }
+    resolve(p) {
+        if (path_1.default.posix.isAbsolute(p))
+            return path_1.default.posix.normalize(p);
+        return path_1.default.posix.normalize(path_1.default.posix.join(this.host.workDir, p));
+    }
+    isInside(_p) {
+        // OpenSandbox runtime is already isolated at container/sandbox level.
+        return true;
+    }
+    async read(p) {
+        const sandbox = this.host.getOpenSandbox();
+        const resolved = this.resolve(p);
+        return await sandbox.files.readFile(resolved);
+    }
+    async write(p, content) {
+        const sandbox = this.host.getOpenSandbox();
+        const resolved = this.resolve(p);
+        const dir = path_1.default.posix.dirname(resolved);
+        if (dir && dir !== '/') {
+            await sandbox.files.createDirectories([{ path: dir, mode: 0o755 }]).catch(() => undefined);
+        }
+        await sandbox.files.writeFiles([{ path: resolved, data: content }]);
+    }
+    temp(name) {
+        const tempName = name || `temp-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+        return path_1.default.posix.join('/tmp', tempName);
+    }
+    async stat(p) {
+        const sandbox = this.host.getOpenSandbox();
+        const resolved = this.resolve(p);
+        const info = await sandbox.files.getFileInfo([resolved]);
+        const fileInfo = info[resolved] || Object.values(info)[0];
+        if (!fileInfo) {
+            throw new Error(`File not found: ${resolved}`);
+        }
+        const mtime = this.toTimestamp(fileInfo.modifiedAt ??
+            fileInfo.modified_at ??
+            fileInfo.mtime ??
+            fileInfo.updatedAt);
+        return { mtimeMs: mtime ?? Date.now() };
+    }
+    async glob(pattern, opts) {
+        const sandbox = this.host.getOpenSandbox();
+        const searchRoot = opts?.cwd ? this.resolve(opts.cwd) : this.host.workDir;
+        const items = await sandbox.files.search({
+            path: searchRoot,
+            pattern,
+        });
+        const includeDot = opts?.dot ?? false;
+        const ignore = opts?.ignore || [];
+        const matched = items
+            .map((item) => this.resolve(String(item.path || '')))
+            .filter((entry) => {
+            if (!entry)
+                return false;
+            if (!includeDot && this.hasDotPath(entry))
+                return false;
+            if (ignore.length === 0)
+                return true;
+            const relToRoot = path_1.default.posix.relative(searchRoot, entry);
+            const relToWorkDir = path_1.default.posix.relative(this.host.workDir, entry);
+            return !ignore.some((rule) => {
+                return (this.matchGlob(rule, relToRoot) ||
+                    this.matchGlob(rule, relToWorkDir) ||
+                    this.matchGlob(rule, entry));
+            });
+        });
+        if (opts?.absolute) {
+            return matched;
+        }
+        return matched.map((entry) => path_1.default.posix.relative(this.host.workDir, entry));
+    }
+    hasDotPath(entry) {
+        const normalized = entry.replace(/\\/g, '/');
+        return normalized.split('/').some((seg) => seg.startsWith('.') && seg.length > 1);
+    }
+    toTimestamp(value) {
+        if (value == null)
+            return undefined;
+        if (typeof value === 'number' && Number.isFinite(value))
+            return value;
+        if (value instanceof Date)
+            return value.getTime();
+        if (typeof value === 'string') {
+            const parsed = Date.parse(value);
+            if (Number.isFinite(parsed))
+                return parsed;
+        }
+        return undefined;
+    }
+    matchGlob(pattern, target) {
+        const normalizedPattern = pattern.replace(/\\/g, '/');
+        const normalizedTarget = target.replace(/\\/g, '/');
+        return (0, minimatch_1.minimatch)(normalizedTarget, normalizedPattern, {
+            dot: true,
+            nocase: false,
+            matchBase: false,
+        });
+    }
+}
+exports.OpenSandboxFS = OpenSandboxFS;

package/dist/infra/opensandbox/opensandbox-sandbox.d.ts

@@ -0,0 +1,35 @@
+import { Sandbox as OpenSandboxClient } from '@alibaba-group/opensandbox';
+import { Sandbox, SandboxExecResult, SandboxKind } from '../sandbox';
+import { OpenSandboxFS } from './opensandbox-fs';
+import { OpenSandboxOptions } from './types';
+export declare class OpenSandbox implements Sandbox {
+    kind: SandboxKind;
+    workDir: string;
+    fs: OpenSandboxFS;
+    private sandbox;
+    private readonly options;
+    private readonly watchers;
+    private readonly watchMode;
+    private readonly pollIntervalMs;
+    private readonly disposeAction;
+    constructor(options: OpenSandboxOptions);
+    init(): Promise<void>;
+    getOpenSandbox(): OpenSandboxClient;
+    getSandboxId(): string | undefined;
+    isRunning(): Promise<boolean>;
+    exec(cmd: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<SandboxExecResult>;
+    watchFiles(paths: string[], listener: (event: {
+        path: string;
+        mtimeMs: number;
+    }) => void): Promise<string>;
+    unwatchFiles(id: string): void;
+    dispose(): Promise<void>;
+    private buildConnectionConfig;
+    private pollWatcher;
+    private safeMtime;
+    private resolveExecTimeoutMs;
+    private startPollingWatcher;
+    private startNativeWatcher;
+}

package/dist/infra/opensandbox/opensandbox-sandbox.js

@@ -0,0 +1,325 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenSandbox = void 0;
+const opensandbox_1 = require("@alibaba-group/opensandbox");
+const logger_1 = require("../../utils/logger");
+const opensandbox_fs_1 = require("./opensandbox-fs");
+class OpenSandbox {
+    constructor(options) {
+        this.kind = 'opensandbox';
+        this.sandbox = null;
+        this.watchers = new Map();
+        this.options = { ...options };
+        this.workDir = options.workDir || '/workspace';
+        this.fs = new opensandbox_fs_1.OpenSandboxFS(this);
+        this.watchMode = options.watch?.mode || 'polling';
+        this.pollIntervalMs = Math.max(100, options.watch?.pollIntervalMs ?? 1000);
+        this.disposeAction = options.lifecycle?.disposeAction || 'kill';
+    }
+    async init() {
+        if (this.sandbox)
+            return;
+        const connectionConfig = this.buildConnectionConfig();
+        if (this.options.sandboxId) {
+            const connectOptions = {
+                sandboxId: this.options.sandboxId,
+                connectionConfig,
+                skipHealthCheck: this.options.skipHealthCheck,
+                readyTimeoutSeconds: this.options.readyTimeoutSeconds,
+                healthCheckPollingInterval: this.options.healthCheckPollingInterval,
+            };
+            this.sandbox = await opensandbox_1.Sandbox.connect(connectOptions);
+        }
+        else {
+            const createOptions = {
+                connectionConfig,
+                image: this.options.image || this.options.template || 'ubuntu',
+                timeoutSeconds: Math.max(1, Math.ceil((this.options.timeoutMs ?? 10 * 60 * 1000) / 1000)),
+                env: this.options.env,
+                metadata: this.options.metadata,
+                resource: this.options.resource,
+                networkPolicy: this.options.networkPolicy,
+                skipHealthCheck: this.options.skipHealthCheck,
+                readyTimeoutSeconds: this.options.readyTimeoutSeconds,
+                healthCheckPollingInterval: this.options.healthCheckPollingInterval,
+            };
+            this.sandbox = await opensandbox_1.Sandbox.create(createOptions);
+        }
+        // Persist resolved sandbox id for Agent resume metadata.
+        this.options.sandboxId = this.sandbox.id;
+        // Best-effort workdir bootstrap.
+        if (this.workDir && this.workDir !== '/') {
+            await this.sandbox.commands
+                .run(`mkdir -p ${quoteShell(this.workDir)}`, {
+                workingDirectory: '/',
+                timeoutSeconds: 10,
+            })
+                .catch(() => undefined);
+        }
+    }
+    getOpenSandbox() {
+        if (!this.sandbox) {
+            throw new Error('OpenSandbox not initialized. Call init() first.');
+        }
+        return this.sandbox;
+    }
+    getSandboxId() {
+        return this.sandbox?.id || this.options.sandboxId;
+    }
+    async isRunning() {
+        try {
+            const info = await this.getOpenSandbox().getInfo();
+            const state = String(info?.status?.state || '').toLowerCase();
+            return state === 'running';
+        }
+        catch {
+            return false;
+        }
+    }
+    async exec(cmd, opts) {
+        const sandbox = this.getOpenSandbox();
+        const timeoutMs = this.resolveExecTimeoutMs(opts);
+        const timeoutSeconds = Math.max(1, Math.ceil(timeoutMs / 1000));
+        try {
+            const execution = await sandbox.commands.run(cmd, {
+                workingDirectory: this.workDir,
+                timeoutSeconds,
+            });
+            const stdout = execution.logs.stdout.map((m) => m.text).join('');
+            let stderr = execution.logs.stderr.map((m) => m.text).join('');
+            let code = execution.error ? 1 : 0;
+            if (execution.id) {
+                try {
+                    const status = await sandbox.commands.getCommandStatus(execution.id);
+                    if (typeof status.exitCode === 'number') {
+                        code = status.exitCode;
+                    }
+                    else if (status.running === false && status.error) {
+                        code = 1;
+                    }
+                }
+                catch {
+                    // keep fallback code when status API is unavailable
+                }
+            }
+            if (execution.error && !stderr) {
+                const traces = Array.isArray(execution.error.traceback) ? execution.error.traceback.join('\n') : '';
+                stderr = [execution.error.name, execution.error.value, traces].filter(Boolean).join('\n');
+            }
+            return { code, stdout, stderr };
+        }
+        catch (error) {
+            return {
+                code: 1,
+                stdout: '',
+                stderr: error?.message || String(error),
+            };
+        }
+    }
+    async watchFiles(paths, listener) {
+        if (this.watchMode === 'off') {
+            return `watch-disabled-${Date.now()}`;
+        }
+        const id = `opensandbox-watch-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+        const resolved = Array.from(new Set(paths.map((p) => this.fs.resolve(p))));
+        if (this.watchMode === 'native') {
+            const nativeStarted = await this.startNativeWatcher(id, resolved, listener);
+            if (nativeStarted) {
+                return id;
+            }
+            logger_1.logger.warn('[OpenSandbox] native watch unavailable, falling back to polling mode.');
+        }
+        await this.startPollingWatcher(id, resolved, listener);
+        return id;
+    }
+    unwatchFiles(id) {
+        const watcher = this.watchers.get(id);
+        if (!watcher)
+            return;
+        if (watcher.kind === 'polling') {
+            clearInterval(watcher.timer);
+        }
+        else {
+            watcher.abortController.abort();
+        }
+        this.watchers.delete(id);
+    }
+    async dispose() {
+        for (const id of Array.from(this.watchers.keys())) {
+            this.unwatchFiles(id);
+        }
+        if (!this.sandbox)
+            return;
+        let disposeError;
+        const sandbox = this.sandbox;
+        this.sandbox = null;
+        if (this.disposeAction === 'kill') {
+            try {
+                await sandbox.kill();
+            }
+            catch (error) {
+                disposeError = error;
+            }
+        }
+        try {
+            await sandbox.close();
+        }
+        catch (error) {
+            disposeError = disposeError || error;
+        }
+        if (disposeError) {
+            throw disposeError;
+        }
+    }
+    buildConnectionConfig() {
+        const config = {
+            apiKey: this.options.apiKey,
+            domain: this.options.endpoint || this.options.domain,
+            protocol: this.options.protocol,
+            requestTimeoutSeconds: this.options.requestTimeoutSeconds,
+            useServerProxy: this.options.useServerProxy ?? false,
+        };
+        return new opensandbox_1.ConnectionConfig(config);
+    }
+    async pollWatcher(id, listener) {
+        const watcher = this.watchers.get(id);
+        if (!watcher || watcher.kind !== 'polling' || watcher.polling)
+            return;
+        watcher.polling = true;
+        try {
+            do {
+                watcher.pending = false;
+                for (const path of watcher.paths) {
+                    if (!this.watchers.has(id)) {
+                        return;
+                    }
+                    const current = await this.safeMtime(path);
+                    const previous = watcher.lastMtimes.get(path);
+                    watcher.lastMtimes.set(path, current);
+                    if (previous === undefined && current === undefined)
+                        continue;
+                    if (previous === current)
+                        continue;
+                    listener({ path, mtimeMs: current ?? Date.now() });
+                }
+            } while (this.watchers.has(id) && watcher.pending);
+        }
+        finally {
+            if (this.watchers.get(id) === watcher) {
+                watcher.polling = false;
+            }
+        }
+    }
+    async safeMtime(path) {
+        try {
+            const stat = await this.fs.stat(path);
+            return stat.mtimeMs;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    resolveExecTimeoutMs(opts) {
+        return opts?.timeoutMs ?? this.options.execTimeoutMs ?? this.options.timeoutMs ?? 120000;
+    }
+    async startPollingWatcher(id, paths, listener) {
+        const lastMtimes = new Map();
+        for (const p of paths) {
+            lastMtimes.set(p, await this.safeMtime(p));
+        }
+        const watcher = {
+            kind: 'polling',
+            timer: setInterval(() => {
+                const current = this.watchers.get(id);
+                if (!current || current.kind !== 'polling')
+                    return;
+                current.pending = true;
+                if (!current.polling) {
+                    void this.pollWatcher(id, listener);
+                }
+            }, this.pollIntervalMs),
+            paths,
+            lastMtimes,
+            polling: false,
+            pending: true,
+        };
+        this.watchers.set(id, watcher);
+        void this.pollWatcher(id, listener);
+    }
+    async startNativeWatcher(id, paths, listener) {
+        const probe = await this.exec('command -v inotifywait >/dev/null 2>&1 && echo __KODE_INOTIFY_READY__', {
+            timeoutMs: 5000,
+        });
+        if (probe.code !== 0 || !probe.stdout.includes('__KODE_INOTIFY_READY__')) {
+            return false;
+        }
+        const sandbox = this.getOpenSandbox();
+        const abortController = new AbortController();
+        const nativeWatchCommand = buildNativeWatchCommand(paths);
+        let stdoutBuffer = '';
+        const streamTask = (async () => {
+            try {
+                for await (const event of sandbox.commands.runStream(nativeWatchCommand, { workingDirectory: this.workDir }, abortController.signal)) {
+                    if (abortController.signal.aborted) {
+                        break;
+                    }
+                    if (event.type !== 'stdout' || typeof event.text !== 'string') {
+                        continue;
+                    }
+                    stdoutBuffer += event.text;
+                    let lineBreak = stdoutBuffer.indexOf('\n');
+                    while (lineBreak >= 0) {
+                        const line = stdoutBuffer.slice(0, lineBreak).trim();
+                        stdoutBuffer = stdoutBuffer.slice(lineBreak + 1);
+                        if (line) {
+                            listener({ path: line, mtimeMs: Date.now() });
+                        }
+                        lineBreak = stdoutBuffer.indexOf('\n');
+                    }
+                }
+                const tail = stdoutBuffer.trim();
+                if (tail) {
+                    listener({ path: tail, mtimeMs: Date.now() });
+                }
+            }
+            catch (error) {
+                if (!abortController.signal.aborted) {
+                    logger_1.logger.warn('[OpenSandbox] native watch stream failed, fallback to polling.', error);
+                }
+            }
+            finally {
+                const current = this.watchers.get(id);
+                if (!current || current.kind !== 'native' || current.abortController !== abortController) {
+                    return;
+                }
+                this.watchers.delete(id);
+                if (!abortController.signal.aborted) {
+                    try {
+                        await this.startPollingWatcher(id, paths, listener);
+                        logger_1.logger.warn('[OpenSandbox] native watch stopped, switched to polling mode.');
+                    }
+                    catch (error) {
+                        logger_1.logger.warn('[OpenSandbox] failed to start polling fallback after native watch exit.', error);
+                    }
+                }
+            }
+        })();
+        const watcher = {
+            kind: 'native',
+            paths,
+            abortController,
+            streamTask,
+        };
+        this.watchers.set(id, watcher);
+        return true;
+    }
+}
+exports.OpenSandbox = OpenSandbox;
+function quoteShell(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function buildNativeWatchCommand(paths) {
+    const targets = paths.map((p) => quoteShell(p)).join(' ');
+    const script = `exec inotifywait -m -e modify,create,delete,move --format '%w%f' -- ${targets}`;
+    return `sh -lc ${quoteShell(script)}`;
+}

package/dist/infra/opensandbox/types.d.ts

@@ -0,0 +1,30 @@
+export type OpenSandboxWatchMode = 'native' | 'polling' | 'off';
+export interface OpenSandboxOptions {
+    kind: 'opensandbox';
+    apiKey?: string;
+    endpoint?: string;
+    domain?: string;
+    protocol?: 'http' | 'https';
+    sandboxId?: string;
+    image?: string;
+    template?: string;
+    workDir?: string;
+    timeoutMs?: number;
+    execTimeoutMs?: number;
+    requestTimeoutSeconds?: number;
+    useServerProxy?: boolean;
+    env?: Record<string, string>;
+    metadata?: Record<string, string>;
+    resource?: Record<string, string>;
+    networkPolicy?: Record<string, any>;
+    skipHealthCheck?: boolean;
+    readyTimeoutSeconds?: number;
+    healthCheckPollingInterval?: number;
+    watch?: {
+        mode?: OpenSandboxWatchMode;
+        pollIntervalMs?: number;
+    };
+    lifecycle?: {
+        disposeAction?: 'close' | 'kill';
+    };
+}

package/dist/infra/opensandbox/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/infra/providers/utils.js

@@ -82,8 +82,8 @@ function normalizeBaseUrl(url) {
 }
 function normalizeOpenAIBaseUrl(url) {
     let normalized = url.replace(/\/+$/, '');
-    // Auto-append /v1 if not present (for OpenAI-compatible APIs)
-    if (!normalized.endsWith('/v1')) {
+    // Auto-append /v1 if no version path detected (e.g., /v1, /v2, /v4)
+    if (!/\/v\d+$/.test(normalized)) {
         normalized += '/v1';
     }
     return normalized;

package/dist/infra/sandbox-factory.js

@@ -3,11 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SandboxFactory = void 0;
 const sandbox_1 = require("./sandbox");
 const e2b_sandbox_1 = require("./e2b/e2b-sandbox");
+const opensandbox_1 = require("./opensandbox");
 class SandboxFactory {
     constructor() {
         this.factories = new Map();
         this.factories.set('local', (config) => new sandbox_1.LocalSandbox(config));
         this.factories.set('e2b', (config) => new e2b_sandbox_1.E2BSandbox(config));
+        this.factories.set('opensandbox', (config) => new opensandbox_1.OpenSandbox(config));
     }
     register(kind, factory) {
         this.factories.set(kind, factory);
@@ -24,6 +26,9 @@ class SandboxFactory {
         if (config.kind === 'e2b' && sandbox instanceof e2b_sandbox_1.E2BSandbox) {
             await sandbox.init();
         }
+        if (config.kind === 'opensandbox' && sandbox instanceof opensandbox_1.OpenSandbox) {
+            await sandbox.init();
+        }
         return sandbox;
     }
 }

package/dist/infra/sandbox.d.ts

@@ -1,4 +1,4 @@
-export type SandboxKind = 'local' | 'docker' | 'k8s' | 'remote' | 'vfs' | 'e2b';
+export type SandboxKind = 'local' | 'docker' | 'k8s' | 'remote' | 'vfs' | 'e2b' | 'opensandbox';
 export interface SandboxFS {
     resolve(path: string): string;
     isInside(path: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shareai-lab/kode-sdk",
-  "version": "2.7.3",
+  "version": "2.7.4",
   "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",
@@ -22,6 +22,7 @@
     "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:opensandbox": "ts-node examples/opensandbox-usage.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",
@@ -42,12 +43,14 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
+    "@alibaba-group/opensandbox": "~0.1.4",
     "@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",
+    "minimatch": "^10.2.4",
     "pg": "^8.17.2",
     "undici": "^7.18.2",
     "zod": "^4.3.5",