@kooka/agent-sdk 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,251 @@
+import type { AgentHistoryMessage } from '@kooka/core';
+export interface ToolParameterSchema {
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+    description?: string;
+    enum?: (string | number)[];
+    items?: ToolParameterSchema;
+    properties?: Record<string, ToolParameterSchema>;
+    required?: string[];
+    default?: unknown;
+}
+export type ToolExecution = {
+    type: 'function';
+    handler: string;
+} | {
+    type: 'command';
+    command: string;
+} | {
+    type: 'shell';
+    script: string;
+    shell?: string;
+    cwd?: string;
+} | {
+    type: 'http';
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+} | {
+    type: 'inline';
+    code: string;
+};
+export interface ToolDefinition {
+    id: string;
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, ToolParameterSchema>;
+        required?: string[];
+    };
+    execution: ToolExecution;
+    when?: string;
+    metadata?: {
+        category?: string;
+        icon?: string;
+        requiresApproval?: boolean;
+        timeout?: number;
+        tags?: string[];
+        /**
+         * Whether this tool can operate on file paths outside the current workspace.
+         * If true, external paths should be blocked when allowExternalPaths=false.
+         */
+        supportsExternalPaths?: boolean;
+        /**
+         * Permission category used for allow/ask/deny evaluation.
+         * If omitted, defaults to the tool id (with common edit tools mapped to "edit").
+         */
+        permission?: string;
+        /**
+         * Whether the tool is read-only (safe to run in Plan mode without prompting).
+         * Non-read-only tools are blocked/confirmed in Plan mode.
+         */
+        readOnly?: boolean;
+        /**
+         * Extract patterns from tool args for permission evaluation (e.g. file paths or commands).
+         */
+        permissionPatterns?: Array<{
+            arg: string;
+            kind?: 'path' | 'command' | 'raw';
+        }>;
+    };
+}
+export interface ToolContext {
+    /**
+     * Workspace root for path resolution / boundary enforcement.
+     * If absent, tools must treat all paths as external.
+     */
+    workspaceRoot?: string;
+    /**
+     * Whether tools are allowed to access paths outside the workspaceRoot.
+     * Even when true, tools may still require approval via permissions.
+     */
+    allowExternalPaths?: boolean;
+    /**
+     * Optional session identifier used by stateful tools.
+     */
+    sessionId?: string;
+    /**
+     * Abort signal for cancellation/timeouts.
+     */
+    signal: AbortSignal;
+    /**
+     * Optional host logger for tool-level diagnostics (must be redacted by the host if needed).
+     */
+    log: (message: string) => void;
+}
+export interface ToolResult {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+    metadata?: Record<string, unknown> & {
+        duration?: number;
+        truncated?: boolean;
+        errorType?: string;
+        stack?: string;
+        /**
+         * Optional user-facing tool output text; if absent, the agent formats `data`/`error`.
+         */
+        outputText?: string;
+        /**
+         * Optional display title for tool output.
+         */
+        title?: string;
+    };
+}
+export type ToolHandler = (args: Record<string, unknown>, context: ToolContext) => Promise<ToolResult>;
+export interface ToolProvider {
+    readonly id: string;
+    readonly name: string;
+    getTools(): ToolDefinition[] | Promise<ToolDefinition[]>;
+    executeTool(toolId: string, args: Record<string, unknown>, context: ToolContext): Promise<ToolResult>;
+    dispose?(): void;
+}
+export interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface LLMProvider {
+    readonly id: string;
+    readonly name: string;
+    getModel(modelId: string): Promise<unknown>;
+    dispose?(): void;
+}
+export interface AgentConfig {
+    model?: string;
+    systemPrompt?: string;
+    mode?: 'build' | 'plan';
+    temperature?: number;
+    /**
+     * Retry count for transient provider failures.
+     * Note: retries are only attempted when no tool call has started and no output was streamed.
+     */
+    maxRetries?: number;
+    /**
+     * Maximum tokens for generated output (provider-dependent).
+     */
+    maxOutputTokens?: number;
+    toolFilter?: string[];
+    autoApprove?: boolean;
+    /**
+     * Optional session identifier (provided by the host).
+     */
+    sessionId?: string;
+}
+export interface AgentCallbacks {
+    onIterationStart?: (iteration: number) => void | Promise<void>;
+    onIterationEnd?: (iteration: number) => void | Promise<void>;
+    onThinking?: () => void;
+    onCompactionStart?: (event: {
+        auto: boolean;
+        markerMessageId: string;
+    }) => void | Promise<void>;
+    onCompactionEnd?: (event: {
+        auto: boolean;
+        markerMessageId: string;
+        summaryMessageId?: string;
+        status: 'done' | 'error' | 'canceled';
+        error?: string;
+    }) => void | Promise<void>;
+    /**
+     * Debug logging hook (no prompts/URLs). Intended for host diagnostics.
+     */
+    onDebug?: (message: string) => void;
+    /**
+     * Raw token stream as emitted by the provider (may include <think> or tool-call markers).
+     */
+    onToken?: (token: string) => void;
+    /**
+     * Token stream for user-facing assistant text with <think>/<tool_call> sections removed.
+     */
+    onAssistantToken?: (token: string) => void;
+    /**
+     * Token stream for model reasoning (<think> sections) with tool-call blocks removed.
+     */
+    onThoughtToken?: (token: string) => void;
+    onToolCall?: (tool: ToolCall, definition: ToolDefinition) => void;
+    onToolBlocked?: (tool: ToolCall, definition: ToolDefinition, reason: string) => void;
+    onToolResult?: (tool: ToolCall, result: ToolResult) => void;
+    onRequestApproval?: (tool: ToolCall, definition: ToolDefinition) => Promise<boolean>;
+    onComplete?: (response: string) => void;
+    onError?: (error: Error) => void;
+    onStatusChange?: (status: {
+        type: 'running' | 'retry' | 'done' | 'error';
+        attempt?: number;
+        nextRetryTime?: number;
+        message?: string;
+    }) => void;
+}
+export type LingyunEvent = {
+    type: 'debug';
+    message: string;
+} | {
+    type: 'status';
+    status: NonNullable<AgentCallbacks['onStatusChange']> extends (s: infer S) => any ? S : never;
+} | {
+    type: 'assistant_token';
+    token: string;
+} | {
+    type: 'thought_token';
+    token: string;
+} | {
+    type: 'tool_call';
+    tool: ToolCall;
+    definition: ToolDefinition;
+} | {
+    type: 'tool_blocked';
+    tool: ToolCall;
+    definition: ToolDefinition;
+    reason: string;
+} | {
+    type: 'tool_result';
+    tool: ToolCall;
+    result: ToolResult;
+} | {
+    type: 'compaction_start';
+    auto: boolean;
+    markerMessageId: string;
+} | {
+    type: 'compaction_end';
+    auto: boolean;
+    markerMessageId: string;
+    summaryMessageId?: string;
+    status: 'done' | 'error' | 'canceled';
+    error?: string;
+};
+export interface LingyunRunResult {
+    text: string;
+    session: {
+        history: AgentHistoryMessage[];
+        pendingPlan?: string;
+        sessionId?: string;
+    };
+}
+export interface LingyunRun {
+    events: AsyncIterable<LingyunEvent>;
+    done: Promise<LingyunRunResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kooka/agent-sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Headless LingYun agent runtime for Node.js (tools + skills + plugins).",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@ai-sdk/openai-compatible": "^2.0.2",
+    "ai": "^6.0.6",
+    "glob": "^13.0.0",
+    "undici": "^7.18.2",
+    "zod": "^4.1.8",
+    "@kooka/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@ai-sdk/provider": "^3.0.2",
+    "@ai-sdk/provider-utils": "^4.0.5",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^20.11.16",
+    "mocha": "^11.7.5",
+    "typescript": "^5.3.3"
+  },
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true }); require('fs').rmSync('dist-test', { recursive: true, force: true })\"",
+    "build": "pnpm run clean && pnpm --filter @kooka/core build && tsc -p tsconfig.json",
+    "typecheck": "pnpm --filter @kooka/core build && tsc -p tsconfig.json --noEmit",
+    "build:test": "tsc -p tsconfig.test.json",
+    "test": "pnpm run build && pnpm run build:test && mocha --ui tdd ./dist-test/suite/*.test.js",
+    "test:e2e": "pnpm run build && pnpm run build:test && mocha --ui tdd --timeout 300000 ./dist-test/e2e/*.test.js"
+  }
+}