@shareai-lab/kode-sdk 1.0.0-beta.0

package/dist/core/types.d.ts

@@ -0,0 +1,192 @@
+export type ContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: any;
+} | {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: any;
+    is_error?: boolean;
+};
+export type MessageRole = 'user' | 'assistant' | 'system';
+export interface Message {
+    role: MessageRole;
+    content: ContentBlock[];
+}
+export type AgentState = 'READY' | 'PAUSED' | 'BUSY';
+export type ErrorKind = 'ProviderError' | 'ToolTimeout' | 'ToolDenied' | 'PermissionPending' | 'PolicyViolation' | 'StoreError' | 'MCPError';
+export type AgentEventKind = 'text_chunk' | 'text' | 'tool_use' | 'tool_result' | 'usage' | 'error' | 'messages_update' | 'permission_ask' | 'permission_decision' | 'commit' | 'state' | 'resume' | 'forked';
+export type AgentEvent = {
+    type: 'text_chunk';
+    cursor: number;
+    eventId: string;
+    timestamp: number;
+    delta: string;
+} | {
+    type: 'text';
+    cursor: number;
+    eventId: string;
+    timestamp: number;
+    text: string;
+} | {
+    type: 'tool_use';
+    cursor: number;
+    eventId: string;
+    timestamp: number;
+    id: string;
+    name: string;
+    input: any;
+} | {
+    type: 'tool_result';
+    cursor: number;
+    eventId: string;
+    timestamp: number;
+    id: string;
+    name: string;
+    ok: boolean;
+    content: any;
+    duration_ms?: number;
+} | {
+    type: 'usage';
+    cursor: number;
+    eventId: string;
+    timestamp: number;
+    data: {
+        input_tokens: number;
+        output_tokens: number;
+        total_tokens: number;
+        cost_usd?: number;
+        latency_ms?: number;
+    };
+} | {
+    type: 'error';
+    cursor: number;
+    eventId: string;
+    timestamp: number;
+    kind: ErrorKind;
+    message: string;
+    hint?: string;
+} | {
+    type: 'messages_update';
+    cursor: number;
+    eventId: string;
+    timestamp: number;
+    messageCount: number;
+    lastSfpIndex: number;
+    added?: number;
+} | {
+    type: 'permission_ask';
+    cursor: number;
+    eventId: string;
+    timestamp: number;
+    id: string;
+    tool: string;
+    args: any;
+    meta?: any;
+    respond: (decision: 'allow' | 'deny', note?: string) => Promise<void>;
+} | {
+    type: 'permission_decision';
+    cursor: number;
+    eventId: string;
+    timestamp: number;
+    id: string;
+    decision: 'allow' | 'deny';
+    by: 'api' | 'respond';
+} | {
+    type: 'commit';
+    cursor: number;
+    eventId: string;
+    timestamp: number;
+    sfpIndex: number;
+} | {
+    type: 'state';
+    cursor: number;
+    eventId: string;
+    timestamp: number;
+    state: AgentState;
+} | {
+    type: 'resume';
+    cursor: number;
+    eventId: string;
+    timestamp: number;
+    from: 'crash' | 'manual';
+    sealed: Array<{
+        tool_use_id: string;
+        note: string;
+    }>;
+} | {
+    type: 'forked';
+    cursor: number;
+    eventId: string;
+    timestamp: number;
+    childSessionId: string;
+    from: SnapshotId;
+};
+export declare const MINIMAL_EVENT_KINDS: AgentEventKind[];
+export interface Timeline {
+    cursor: number;
+    event: AgentEvent;
+}
+export type SnapshotId = string;
+export interface Snapshot {
+    id: SnapshotId;
+    messages: Message[];
+    lastSfpIndex: number;
+    createdAt: string;
+}
+export interface SubscribeOptions {
+    since?: number;
+    kinds?: AgentEventKind[];
+}
+export interface AgentStatus {
+    state: AgentState;
+    sessionId: string;
+    messageCount: number;
+    lastSfpIndex: number;
+    cursor: number;
+}
+export interface AgentInfo {
+    sessionId: string;
+    templateId: string;
+    createdAt: string;
+    lineage: string[];
+    messageCount: number;
+    lastSfpIndex: number;
+}
+export interface ToolCall {
+    id: string;
+    name: string;
+    args: any;
+    sessionId: string;
+}
+export interface ToolOutcome {
+    id: string;
+    name: string;
+    ok: boolean;
+    content: any;
+    duration_ms?: number;
+}
+export type HookDecision = {
+    decision: 'ask';
+    meta?: any;
+} | {
+    decision: 'deny';
+    reason?: string;
+    toolResult?: any;
+} | {
+    result: any;
+} | void;
+export type PostHookResult = void | {
+    update: Partial<ToolOutcome>;
+} | {
+    replace: ToolOutcome;
+};
+export interface ToolContext {
+    sessionId: string;
+    sandbox: import('../infra/sandbox').Sandbox;
+    agent: any;
+}

package/dist/core/types.js

@@ -0,0 +1,13 @@
+"use strict";
+// Core data structures for Agent Model Client SDK
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MINIMAL_EVENT_KINDS = void 0;
+exports.MINIMAL_EVENT_KINDS = [
+    'text_chunk',
+    'text',
+    'tool_use',
+    'tool_result',
+    'usage',
+    'error',
+    'messages_update',
+];

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { Agent, AgentOptions } from './core/agent';
+export { AgentPool } from './core/pool';
+export { Room } from './core/room';
+export { Scheduler, AgentSchedulerHandle } from './core/scheduler';
+export { EventBus } from './core/events';
+export { HookManager, Hooks } from './core/hooks';
+export * from './core/types';
+export { Store, JSONStore } from './infra/store';
+export { Sandbox, LocalSandbox } from './infra/sandbox';
+export { Provider, AnthropicProvider } from './infra/provider';
+export { Tool, FsRead, FsWrite, FsEdit, toolTune } from './tools/fs';
+export { BashRun, BashLogs, BashKill } from './tools/bash';
+export { TaskRun, AgentTemplate } from './tools/task';
+export { builtin } from './tools/builtin';
+export { SessionId } from './utils/session-id';

package/dist/index.js

@@ -0,0 +1,57 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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.SessionId = exports.builtin = exports.TaskRun = exports.BashKill = exports.BashLogs = exports.BashRun = exports.toolTune = exports.FsEdit = exports.FsWrite = exports.FsRead = exports.AnthropicProvider = exports.LocalSandbox = exports.JSONStore = exports.HookManager = exports.EventBus = exports.AgentSchedulerHandle = exports.Scheduler = exports.Room = exports.AgentPool = exports.Agent = void 0;
+// Core
+var agent_1 = require("./core/agent");
+Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return agent_1.Agent; } });
+var pool_1 = require("./core/pool");
+Object.defineProperty(exports, "AgentPool", { enumerable: true, get: function () { return pool_1.AgentPool; } });
+var room_1 = require("./core/room");
+Object.defineProperty(exports, "Room", { enumerable: true, get: function () { return room_1.Room; } });
+var scheduler_1 = require("./core/scheduler");
+Object.defineProperty(exports, "Scheduler", { enumerable: true, get: function () { return scheduler_1.Scheduler; } });
+Object.defineProperty(exports, "AgentSchedulerHandle", { enumerable: true, get: function () { return scheduler_1.AgentSchedulerHandle; } });
+var events_1 = require("./core/events");
+Object.defineProperty(exports, "EventBus", { enumerable: true, get: function () { return events_1.EventBus; } });
+var hooks_1 = require("./core/hooks");
+Object.defineProperty(exports, "HookManager", { enumerable: true, get: function () { return hooks_1.HookManager; } });
+// Types
+__exportStar(require("./core/types"), exports);
+// Infrastructure
+var store_1 = require("./infra/store");
+Object.defineProperty(exports, "JSONStore", { enumerable: true, get: function () { return store_1.JSONStore; } });
+var sandbox_1 = require("./infra/sandbox");
+Object.defineProperty(exports, "LocalSandbox", { enumerable: true, get: function () { return sandbox_1.LocalSandbox; } });
+var provider_1 = require("./infra/provider");
+Object.defineProperty(exports, "AnthropicProvider", { enumerable: true, get: function () { return provider_1.AnthropicProvider; } });
+// Tools
+var fs_1 = require("./tools/fs");
+Object.defineProperty(exports, "FsRead", { enumerable: true, get: function () { return fs_1.FsRead; } });
+Object.defineProperty(exports, "FsWrite", { enumerable: true, get: function () { return fs_1.FsWrite; } });
+Object.defineProperty(exports, "FsEdit", { enumerable: true, get: function () { return fs_1.FsEdit; } });
+Object.defineProperty(exports, "toolTune", { enumerable: true, get: function () { return fs_1.toolTune; } });
+var bash_1 = require("./tools/bash");
+Object.defineProperty(exports, "BashRun", { enumerable: true, get: function () { return bash_1.BashRun; } });
+Object.defineProperty(exports, "BashLogs", { enumerable: true, get: function () { return bash_1.BashLogs; } });
+Object.defineProperty(exports, "BashKill", { enumerable: true, get: function () { return bash_1.BashKill; } });
+var task_1 = require("./tools/task");
+Object.defineProperty(exports, "TaskRun", { enumerable: true, get: function () { return task_1.TaskRun; } });
+var builtin_1 = require("./tools/builtin");
+Object.defineProperty(exports, "builtin", { enumerable: true, get: function () { return builtin_1.builtin; } });
+// Utils
+var session_id_1 = require("./utils/session-id");
+Object.defineProperty(exports, "SessionId", { enumerable: true, get: function () { return session_id_1.SessionId; } });

package/dist/infra/provider.d.ts

@@ -0,0 +1,58 @@
+import { Message, ContentBlock } from '../core/types';
+export interface ProviderResponse {
+    role: 'assistant';
+    content: ContentBlock[];
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+    stop_reason?: string;
+}
+export interface ProviderStreamChunk {
+    type: 'content_block_start' | 'content_block_delta' | 'content_block_stop' | 'message_delta' | 'message_stop';
+    index?: number;
+    content_block?: ContentBlock;
+    delta?: {
+        type: 'text_delta' | 'input_json_delta';
+        text?: string;
+        partial_json?: string;
+    };
+    usage?: {
+        output_tokens: number;
+    };
+}
+export interface Provider {
+    complete(messages: Message[], opts?: {
+        tools?: any[];
+        maxTokens?: number;
+        temperature?: number;
+        system?: string;
+        stream?: boolean;
+    }): Promise<ProviderResponse>;
+    stream(messages: Message[], opts?: {
+        tools?: any[];
+        maxTokens?: number;
+        temperature?: number;
+        system?: string;
+    }): AsyncIterable<ProviderStreamChunk>;
+}
+export declare class AnthropicProvider implements Provider {
+    private apiKey;
+    private model;
+    private baseUrl;
+    constructor(apiKey: string, model?: string, baseUrl?: string);
+    complete(messages: Message[], opts?: {
+        tools?: any[];
+        maxTokens?: number;
+        temperature?: number;
+        system?: string;
+        stream?: boolean;
+    }): Promise<ProviderResponse>;
+    stream(messages: Message[], opts?: {
+        tools?: any[];
+        maxTokens?: number;
+        temperature?: number;
+        system?: string;
+    }): AsyncIterable<ProviderStreamChunk>;
+    private formatMessages;
+}

package/dist/infra/provider.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnthropicProvider = void 0;
+class AnthropicProvider {
+    constructor(apiKey, model = 'claude-3-5-sonnet-20241022', baseUrl = 'https://api.anthropic.com') {
+        this.apiKey = apiKey;
+        this.model = model;
+        this.baseUrl = baseUrl;
+    }
+    async complete(messages, opts) {
+        const body = {
+            model: this.model,
+            messages: this.formatMessages(messages),
+            max_tokens: opts?.maxTokens || 4096,
+        };
+        if (opts?.temperature !== undefined)
+            body.temperature = opts.temperature;
+        if (opts?.system)
+            body.system = opts.system;
+        if (opts?.tools && opts.tools.length > 0)
+            body.tools = opts.tools;
+        const response = await fetch(`${this.baseUrl}/v1/messages`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey,
+                'anthropic-version': '2023-06-01',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Anthropic API error: ${response.status} ${error}`);
+        }
+        const data = await response.json();
+        return {
+            role: 'assistant',
+            content: data.content,
+            usage: data.usage,
+            stop_reason: data.stop_reason,
+        };
+    }
+    async *stream(messages, opts) {
+        const body = {
+            model: this.model,
+            messages: this.formatMessages(messages),
+            max_tokens: opts?.maxTokens || 4096,
+            stream: true,
+        };
+        if (opts?.temperature !== undefined)
+            body.temperature = opts.temperature;
+        if (opts?.system)
+            body.system = opts.system;
+        if (opts?.tools && opts.tools.length > 0)
+            body.tools = opts.tools;
+        const response = await fetch(`${this.baseUrl}/v1/messages`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey,
+                'anthropic-version': '2023-06-01',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Anthropic API error: ${response.status} ${error}`);
+        }
+        const reader = response.body?.getReader();
+        if (!reader)
+            throw new Error('No response body');
+        const decoder = new TextDecoder();
+        let buffer = '';
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop() || '';
+            for (const line of lines) {
+                if (!line.trim() || !line.startsWith('data: '))
+                    continue;
+                const data = line.slice(6);
+                if (data === '[DONE]')
+                    continue;
+                try {
+                    const event = JSON.parse(data);
+                    if (event.type === 'content_block_start') {
+                        yield { type: 'content_block_start', index: event.index, content_block: event.content_block };
+                    }
+                    else if (event.type === 'content_block_delta') {
+                        yield { type: 'content_block_delta', index: event.index, delta: event.delta };
+                    }
+                    else if (event.type === 'content_block_stop') {
+                        yield { type: 'content_block_stop', index: event.index };
+                    }
+                    else if (event.type === 'message_delta') {
+                        yield { type: 'message_delta', delta: event.delta, usage: event.usage };
+                    }
+                    else if (event.type === 'message_stop') {
+                        yield { type: 'message_stop' };
+                    }
+                }
+                catch (e) {
+                    // Skip invalid JSON
+                }
+            }
+        }
+    }
+    formatMessages(messages) {
+        return messages.map((msg) => ({
+            role: msg.role === 'system' ? 'user' : msg.role,
+            content: msg.content,
+        }));
+    }
+}
+exports.AnthropicProvider = AnthropicProvider;

package/dist/infra/sandbox.d.ts

@@ -0,0 +1,39 @@
+export type SandboxKind = 'local' | 'docker' | 'k8s' | 'remote' | 'vfs';
+export interface SandboxFS {
+    resolve(path: string): string;
+    isInside(path: string): boolean;
+    read(path: string): Promise<string>;
+    write(path: string, content: string): Promise<void>;
+    temp(name?: string): string;
+}
+export interface SandboxExecResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export interface Sandbox {
+    kind: SandboxKind;
+    workDir?: string;
+    fs: SandboxFS;
+    exec(cmd: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<SandboxExecResult>;
+}
+export declare class LocalSandbox implements Sandbox {
+    kind: SandboxKind;
+    workDir: string;
+    fs: SandboxFS;
+    constructor(opts: {
+        workDir?: string;
+        baseDir?: string;
+        pwd?: string;
+    });
+    exec(cmd: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<SandboxExecResult>;
+    static local(opts: {
+        workDir?: string;
+        baseDir?: string;
+        pwd?: string;
+    }): LocalSandbox;
+}

package/dist/infra/sandbox.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalSandbox = void 0;
+class LocalSandbox {
+    constructor(opts) {
+        this.kind = 'local';
+        // Support workDir, baseDir (deprecated), and pwd (alias) for backward compatibility
+        this.workDir = require('path').resolve(opts.workDir || opts.baseDir || opts.pwd || process.cwd());
+        this.fs = new LocalFS(this.workDir);
+    }
+    async exec(cmd, opts) {
+        const { exec } = require('child_process');
+        const util = require('util');
+        const execPromise = util.promisify(exec);
+        const timeout = opts?.timeoutMs || 120000;
+        try {
+            const { stdout, stderr } = await execPromise(cmd, {
+                cwd: this.workDir,
+                timeout,
+                maxBuffer: 10 * 1024 * 1024,
+            });
+            return { code: 0, stdout: stdout || '', stderr: stderr || '' };
+        }
+        catch (error) {
+            return {
+                code: error.code || 1,
+                stdout: error.stdout || '',
+                stderr: error.stderr || error.message || '',
+            };
+        }
+    }
+    static local(opts) {
+        return new LocalSandbox(opts);
+    }
+}
+exports.LocalSandbox = LocalSandbox;
+class LocalFS {
+    constructor(workDir) {
+        this.workDir = workDir;
+    }
+    resolve(p) {
+        const path = require('path');
+        if (path.isAbsolute(p))
+            return p;
+        return path.resolve(this.workDir, p);
+    }
+    isInside(p) {
+        const path = require('path');
+        const resolved = this.resolve(p);
+        const relative = path.relative(this.workDir, resolved);
+        return !relative.startsWith('..') && !path.isAbsolute(relative);
+    }
+    async read(p) {
+        const fs = require('fs').promises;
+        const resolved = this.resolve(p);
+        if (!this.isInside(resolved)) {
+            throw new Error(`Path outside sandbox: ${p}`);
+        }
+        return await fs.readFile(resolved, 'utf-8');
+    }
+    async write(p, content) {
+        const fs = require('fs').promises;
+        const path = require('path');
+        const resolved = this.resolve(p);
+        if (!this.isInside(resolved)) {
+            throw new Error(`Path outside sandbox: ${p}`);
+        }
+        const dir = path.dirname(resolved);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(resolved, content, 'utf-8');
+    }
+    temp(name) {
+        const path = require('path');
+        const tempName = name || `temp-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+        return path.relative(this.workDir, path.join(this.workDir, '.temp', tempName));
+    }
+}

package/dist/infra/store.d.ts

@@ -0,0 +1,32 @@
+import { Message, Timeline, Snapshot, AgentInfo } from '../core/types';
+export interface Store {
+    saveMessages(sessionId: string, messages: Message[]): Promise<void>;
+    loadMessages(sessionId: string): Promise<Message[]>;
+    appendEvent(sessionId: string, timeline: Timeline): Promise<void>;
+    readEvents(sessionId: string, since?: number): AsyncIterable<Timeline>;
+    saveSnapshot(sessionId: string, snapshot: Snapshot): Promise<void>;
+    loadSnapshot(sessionId: string, snapshotId: string): Promise<Snapshot | undefined>;
+    listSnapshots(sessionId: string): Promise<Snapshot[]>;
+    saveInfo(sessionId: string, info: AgentInfo): Promise<void>;
+    loadInfo(sessionId: string): Promise<AgentInfo | undefined>;
+    exists(sessionId: string): Promise<boolean>;
+    delete(sessionId: string): Promise<void>;
+    list(prefix?: string): Promise<string[]>;
+}
+export declare class JSONStore implements Store {
+    private baseDir;
+    constructor(baseDir: string);
+    private getPath;
+    saveMessages(sessionId: string, messages: Message[]): Promise<void>;
+    loadMessages(sessionId: string): Promise<Message[]>;
+    appendEvent(sessionId: string, timeline: Timeline): Promise<void>;
+    readEvents(sessionId: string, since?: number): AsyncIterable<Timeline>;
+    saveSnapshot(sessionId: string, snapshot: Snapshot): Promise<void>;
+    loadSnapshot(sessionId: string, snapshotId: string): Promise<Snapshot | undefined>;
+    listSnapshots(sessionId: string): Promise<Snapshot[]>;
+    saveInfo(sessionId: string, info: AgentInfo): Promise<void>;
+    loadInfo(sessionId: string): Promise<AgentInfo | undefined>;
+    exists(sessionId: string): Promise<boolean>;
+    delete(sessionId: string): Promise<void>;
+    list(prefix?: string): Promise<string[]>;
+}