@jussmor/sdk-ai 0.2.0

package/dist/streaming-BtD23BE0.d.ts

@@ -0,0 +1,372 @@
+import { g as ToolFuncParams, f as ToolDef, a as Conversation, L as LLMProvider, c as ChatResponse, C as ChatMessage, b as ChatRequest, T as ToolCallEntry } from './conversation-kIkMQdYK.js';
+import { b as MemoryProvider } from './memory-uBLqrQRY.js';
+import { b as ThreadProvider } from './thread-C2b9xRMJ.js';
+import { T as Tokenizer } from './tokenizer-BhG_RGUk.js';
+
+type ToolCategory = "workspace" | "compute" | "data" | "web" | "planning" | "communication" | "integrations" | "memory" | "custom";
+type ToolExecuteFunc = (ctx: AbortSignal | undefined, sandboxId: string, args: Record<string, unknown>) => Promise<string>;
+type ToolPredicate = (args: Record<string, unknown>) => boolean;
+type ToolValidator = (ctx: AbortSignal | undefined, args: Record<string, unknown>) => Promise<void>;
+type PermissionDecision = "allow" | "deny" | "ask_user";
+interface PermissionResult {
+    decision: PermissionDecision;
+    reason?: string;
+    updatedArgs?: Record<string, unknown>;
+}
+type ToolPermissionFn = (ctx: AbortSignal | undefined, args: Record<string, unknown>) => Promise<PermissionResult>;
+type ToolReminderFn = (ctx: AbortSignal | undefined) => Promise<string>;
+interface Tool {
+    name: string;
+    description: string;
+    category: ToolCategory;
+    parameters: ToolFuncParams;
+    execute: ToolExecuteFunc;
+    aliases?: string[];
+    searchHint?: string;
+    isReadOnly?: ToolPredicate;
+    isConcurrencySafe?: ToolPredicate;
+    isDestructive?: ToolPredicate;
+    validate?: ToolValidator;
+    checkPermissions?: ToolPermissionFn;
+    dynamicReminder?: ToolReminderFn;
+    hidden?: boolean;
+    deferred?: boolean;
+    alwaysLoad?: boolean;
+    maxResultSizeChars?: number;
+}
+interface ToolMatch {
+    tool: Tool;
+    score: number;
+}
+declare function toToolDef(t: Tool): ToolDef;
+declare class ToolRegistry {
+    private tools;
+    private aliases;
+    register(tool: Tool): void;
+    get(name: string): Tool | undefined;
+    list(): Tool[];
+    byCategory(category: ToolCategory): Tool[];
+    names(): string[];
+    describeAvailable(): string;
+    toolDefs(): ToolDef[];
+    collectDynamicReminders(signal?: AbortSignal): Promise<string[]>;
+    search(query: string): ToolMatch[];
+    reveal(name: string): void;
+    hide(name: string): void;
+}
+
+interface SandboxExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+interface SandboxDriver {
+    exec(sandboxId: string, command: string, args?: string[], signal?: AbortSignal): Promise<SandboxExecResult>;
+    readFile(sandboxId: string, path: string, signal?: AbortSignal): Promise<string>;
+    writeFile(sandboxId: string, path: string, content: string, signal?: AbortSignal): Promise<void>;
+}
+
+type InterruptKind = "approval" | "question" | "form_input";
+interface FormField {
+    name: string;
+    label: string;
+    type: "text" | "textarea" | "select" | "checkbox";
+    options?: string[];
+    required?: boolean;
+    defaultValue?: string;
+}
+interface InterruptRequest {
+    id: string;
+    kind: InterruptKind;
+    title: string;
+    description?: string;
+    toolName?: string;
+    toolArgs?: Record<string, unknown>;
+    fields?: FormField[];
+    createdAt: Date;
+}
+interface InterruptResponse {
+    id: string;
+    approved?: boolean;
+    answer?: unknown;
+    modifiedArgs?: string;
+}
+type InterruptRequester = (req: InterruptRequest, signal?: AbortSignal) => Promise<InterruptResponse>;
+declare class InterruptGate {
+    private requester;
+    private pending;
+    constructor(requester: InterruptRequester);
+    wait(req: InterruptRequest, signal?: AbortSignal): Promise<InterruptResponse>;
+    pendingRequests(): InterruptRequest[];
+}
+
+type PermissionBehavior = "allow" | "deny" | "ask";
+interface PermissionRule {
+    toolName?: string;
+    pathPrefix?: string;
+    behavior: PermissionBehavior;
+    reason?: string;
+}
+interface PermissionDecisionResult {
+    behavior: PermissionBehavior;
+    reason?: string;
+    updatedInput?: Record<string, unknown>;
+}
+interface PermissionApprover {
+    ask(tool: Tool, args: Record<string, unknown>, signal?: AbortSignal): Promise<PermissionDecisionResult>;
+}
+declare class InterruptApprover implements PermissionApprover {
+    private requester;
+    constructor(requester: InterruptRequester);
+    ask(tool: Tool, args: Record<string, unknown>, signal?: AbortSignal): Promise<PermissionDecisionResult>;
+}
+declare class PermissionEngine {
+    private rules;
+    private approver?;
+    withRules(rules: PermissionRule[]): this;
+    withApprover(approver: PermissionApprover): this;
+    decide(tool: Tool, args: Record<string, unknown>, signal?: AbortSignal): Promise<PermissionDecisionResult>;
+}
+
+type BaseMode = "balanced" | "analyst" | "deep_work";
+type ToolsMode = "allowlist" | "denylist";
+interface ModeMeta {
+    id: string;
+    name: string;
+    baseMode?: string;
+    toolsMode?: ToolsMode;
+    tools?: string[];
+    model?: string;
+    reasoningEffort?: string;
+    temperature?: string;
+    author?: string;
+    created?: string;
+}
+interface ModelSettings {
+    model?: string;
+    reasoningEffort?: string;
+    temperature?: number;
+}
+interface Mode {
+    meta: ModeMeta;
+    id: string;
+    name: string;
+    baseModeId?: BaseMode;
+    promptContent?: string;
+    modelSettings?: ModelSettings;
+    toolsMode?: ToolsMode;
+    toolsList?: string[];
+}
+declare function isToolAllowed(mode: Mode, toolName: string): boolean;
+interface ModeProvider {
+    get(modeId: string, signal?: AbortSignal): Promise<Mode>;
+    list(signal?: AbortSignal): Promise<Mode[]>;
+    create(mode: Mode, signal?: AbortSignal): Promise<Mode>;
+    builtinModes(): Mode[];
+}
+declare class StaticModeProvider implements ModeProvider {
+    private modes;
+    private modeList;
+    constructor(modes: Mode[]);
+    get(modeId: string): Promise<Mode>;
+    list(): Promise<Mode[]>;
+    create(): Promise<Mode>;
+    builtinModes(): Mode[];
+}
+
+interface ContextBudget {
+    windowSize: number;
+    skillsReserve: number;
+    memoryReserve: number;
+    historyReserve: number;
+    reserveBuffer: number;
+}
+interface EnforcementResult {
+    overflowTokens: number;
+    truncatedHistory: boolean;
+    historyDropped: number;
+    stillOverflow: boolean;
+}
+declare function defaultContextBudget(windowSize: number): ContextBudget;
+declare function enforceContextBudget(budget: ContextBudget, conv: Conversation, memoryTokens: number, tok: Tokenizer): EnforcementResult;
+
+type SystemPromptLayer = "core" | "behavior" | "memory" | "session" | "mode";
+declare class SystemPromptBuilder {
+    private layers;
+    private maxLayerTokens;
+    setMaxLayerTokens(layer: SystemPromptLayer, maxTokens: number): void;
+    build(): string;
+    buildWithBudget(tok?: Tokenizer): string;
+    get(layer: SystemPromptLayer): string;
+    has(layer: SystemPromptLayer): boolean;
+    set(layer: SystemPromptLayer, content: string): void;
+    append(layer: SystemPromptLayer, content: string): void;
+    clear(layer: SystemPromptLayer): void;
+}
+
+interface Engine {
+    memory?: MemoryProvider;
+    sandbox?: SandboxDriver;
+    tools?: ToolRegistry;
+    threads?: ThreadProvider;
+    modes?: ModeProvider;
+    llm?: LLMProvider;
+    prompt?: SystemPromptBuilder;
+    budget?: ContextBudget;
+}
+declare function newEngine(...opts: Array<(e: Engine) => void>): Engine;
+declare function newEngineWithDefaults(windowSize: number): Engine;
+declare const hasMemory: (e: Engine) => boolean;
+declare const hasSandbox: (e: Engine) => boolean;
+declare const hasTools: (e: Engine) => boolean;
+declare const hasThreads: (e: Engine) => boolean;
+declare const hasModes: (e: Engine) => boolean;
+declare const hasLLM: (e: Engine) => boolean;
+declare const hasPrompt: (e: Engine) => boolean;
+declare const hasBudget: (e: Engine) => boolean;
+declare const withMemory: (p: MemoryProvider) => (e: Engine) => void;
+declare const withSandbox: (p: SandboxDriver) => (e: Engine) => void;
+declare const withTools: (r: ToolRegistry) => (e: Engine) => void;
+declare const withThreads: (p: ThreadProvider) => (e: Engine) => void;
+declare const withModes: (p: ModeProvider) => (e: Engine) => void;
+declare const withLLM: (p: LLMProvider) => (e: Engine) => void;
+declare const withPrompt: (b: SystemPromptBuilder) => (e: Engine) => void;
+declare const withBudget: (b: ContextBudget) => (e: Engine) => void;
+
+interface ReasoningStep {
+    id: string;
+    type: "thinking" | "action" | "result";
+    title: string;
+    content?: string;
+    details?: string[];
+}
+
+interface AgentLoopConfig {
+    provider?: LLMProvider;
+    systemPrompt?: string;
+    model?: string;
+    tools?: ToolRegistry;
+    sandbox?: SandboxDriver;
+    sandboxId?: string;
+    permissions?: PermissionEngine;
+    maxTurns?: number;
+    maxRetries?: number;
+    onTurn?: (turn: number, resp: ChatResponse) => boolean;
+    onToolCall?: (call: {
+        id: string;
+        name: string;
+        arguments: string;
+    }) => boolean;
+    onToolResult?: (call: {
+        id: string;
+        name: string;
+        arguments: string;
+    }, result: {
+        toolCallId: string;
+        name: string;
+        content: string;
+        error?: Error;
+    }) => {
+        toolCallId: string;
+        name: string;
+        content: string;
+        error?: Error;
+    };
+    shouldStop?: (turn: number, resp: ChatResponse) => boolean;
+    onError?: (err: Error, attempt: number) => boolean;
+    buildRequest?: (systemPrompt: string, messages: ChatMessage[], tools?: ToolRegistry) => ChatRequest;
+}
+interface AgentLoopResult {
+    finalContent: string;
+    providerReasoning: string;
+    totalTurns: number;
+    totalUsage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    messages: ChatMessage[];
+    reasoningTrace: ReasoningStep[];
+    stopReason: "complete" | "max_turns" | "aborted" | "stopped" | "error";
+}
+declare function runAgentLoop(cfg: AgentLoopConfig, messages: ChatMessage[], signal?: AbortSignal): Promise<AgentLoopResult>;
+declare function runAgentLoopWithEngine(engine: Engine, modeId: string, cfg: AgentLoopConfig, messages: ChatMessage[], signal?: AbortSignal): Promise<AgentLoopResult>;
+
+type ArtifactType = "file" | "component" | "data";
+interface Artifact {
+    id: string;
+    type: ArtifactType;
+    title?: string;
+    content: string;
+    mediaType?: string;
+    props?: Record<string, unknown>;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+type ArtifactEmitter = (artifact: Artifact) => void;
+declare const ARTIFACT_EMITTER_KEY: unique symbol;
+interface ArtifactContext {
+    [ARTIFACT_EMITTER_KEY]?: ArtifactEmitter;
+}
+declare function withArtifactEmitter<T extends ArtifactContext>(ctx: T, emitter: ArtifactEmitter): T & ArtifactContext;
+declare function emitArtifact(ctx: ArtifactContext, artifact: Artifact): void;
+
+interface ToolResult {
+    toolCallId: string;
+    name: string;
+    content: string;
+    error?: Error;
+}
+declare class ToolDispatcher {
+    private tools;
+    private sandbox?;
+    private permissions?;
+    constructor(tools: ToolRegistry, sandbox?: SandboxDriver | undefined);
+    withPermissions(engine: PermissionEngine): this;
+    dispatch(call: ToolCallEntry, sandboxId: string, signal?: AbortSignal): Promise<ToolResult>;
+    dispatchAll(calls: ToolCallEntry[], sandboxId: string, signal?: AbortSignal): Promise<ToolResult[]>;
+    dispatchParallel(calls: ToolCallEntry[], sandboxId: string, signal?: AbortSignal): Promise<ToolResult[]>;
+}
+declare function toolResultsToMessages(assistantToolCalls: ToolCallEntry[], results: ToolResult[]): ChatMessage[];
+declare function areIndependent(calls: ToolCallEntry[]): boolean;
+
+type StreamEventType = "delta" | "thinking" | "tool_call" | "tool_result" | "turn_complete" | "agent_result" | "interrupt_required" | "interrupt_resolved" | "artifact_created" | "artifact_updated" | "compaction" | "plan_mode_changed" | "done" | "error";
+interface CompactionEvent {
+    messagesDropped: number;
+    overflowTokens: number;
+    summary?: string;
+}
+interface PlanModeEvent {
+    state: "entered" | "exited";
+    plan?: string;
+    reason?: string;
+}
+interface AgentResult {
+    agentId: string;
+    result: AgentLoopResult;
+}
+interface StreamEvent {
+    type: StreamEventType;
+    delta?: string;
+    thinking?: string;
+    toolCall?: ToolCallEntry;
+    toolResult?: ToolResult;
+    agentResult?: AgentResult;
+    interrupt?: InterruptRequest;
+    artifact?: Artifact;
+    final?: AgentLoopResult;
+    compaction?: CompactionEvent;
+    planMode?: PlanModeEvent;
+    error?: Error;
+}
+interface StreamingLLMProvider extends LLMProvider {
+    chatStream(req: ChatRequest, signal?: AbortSignal): AsyncGenerator<StreamEvent>;
+}
+declare function collectStream(events: AsyncGenerator<StreamEvent>): Promise<{
+    text: string;
+    final: AgentLoopResult | undefined;
+    error: Error | undefined;
+}>;
+declare function fanOutStream(source: AsyncGenerator<StreamEvent>, consumers: number): AsyncGenerator<StreamEvent>[];
+
+export { collectStream as $, type AgentLoopConfig as A, type BaseMode as B, type ContextBudget as C, type StreamEventType as D, type EnforcementResult as E, type FormField as F, type StreamingLLMProvider as G, SystemPromptBuilder as H, type InterruptRequest as I, type SystemPromptLayer as J, type ToolCategory as K, ToolDispatcher as L, type Mode as M, type ToolExecuteFunc as N, type ToolMatch as O, PermissionEngine as P, type ToolPermissionFn as Q, type ReasoningStep as R, type StreamEvent as S, type Tool as T, type ToolPredicate as U, ToolRegistry as V, type ToolReminderFn as W, type ToolResult as X, type ToolValidator as Y, type ToolsMode as Z, areIndependent as _, type Engine as a, defaultContextBudget as a0, emitArtifact as a1, enforceContextBudget as a2, fanOutStream as a3, hasBudget as a4, hasLLM as a5, hasMemory as a6, hasModes as a7, hasPrompt as a8, hasSandbox as a9, hasThreads as aa, hasTools as ab, isToolAllowed as ac, newEngine as ad, newEngineWithDefaults as ae, runAgentLoop as af, runAgentLoopWithEngine as ag, toToolDef as ah, toolResultsToMessages as ai, withArtifactEmitter as aj, withBudget as ak, withLLM as al, withMemory as am, withModes as an, withPrompt as ao, withSandbox as ap, withThreads as aq, withTools as ar, InterruptGate as b, type AgentLoopResult as c, type AgentResult as d, type Artifact as e, type ArtifactContext as f, type ArtifactEmitter as g, type ArtifactType as h, type CompactionEvent as i, InterruptApprover as j, type InterruptKind as k, type InterruptRequester as l, type InterruptResponse as m, type ModeMeta as n, type ModeProvider as o, type ModelSettings as p, type PermissionApprover as q, type PermissionBehavior as r, type PermissionDecision as s, type PermissionDecisionResult as t, type PermissionResult as u, type PermissionRule as v, type PlanModeEvent as w, type SandboxDriver as x, type SandboxExecResult as y, StaticModeProvider as z };

package/dist/thread-C2b9xRMJ.d.cts

@@ -0,0 +1,30 @@
+type ThreadStatus = "active" | "completed" | "failed" | "archived";
+interface Thread {
+    id: string;
+    userId?: string;
+    projectId?: string;
+    modeId?: string;
+    status: ThreadStatus;
+    parentId?: string;
+}
+interface Message {
+    id?: string;
+    fromThreadId: string;
+    toThreadId: string;
+    content: string;
+    sentAt?: Date;
+}
+interface ThreadProvider {
+    create(projectId: string, modeId: string, signal?: AbortSignal): Promise<Thread>;
+    get(threadId: string, signal?: AbortSignal): Promise<Thread>;
+    archive(threadId: string, signal?: AbortSignal): Promise<void>;
+    sendMessage(msg: Message, signal?: AbortSignal): Promise<void>;
+}
+interface MultiUserThreadProvider extends ThreadProvider {
+    createForUser(userId: string, projectId: string, modeId: string, signal?: AbortSignal): Promise<Thread>;
+    getForUser(userId: string, threadId: string, signal?: AbortSignal): Promise<Thread>;
+    listByUser(userId: string, status: ThreadStatus, signal?: AbortSignal): Promise<Thread[]>;
+}
+declare const ErrThreadAccessDenied: Error;
+
+export { ErrThreadAccessDenied as E, type Message as M, type Thread as T, type MultiUserThreadProvider as a, type ThreadProvider as b, type ThreadStatus as c };

package/dist/thread-C2b9xRMJ.d.ts

@@ -0,0 +1,30 @@
+type ThreadStatus = "active" | "completed" | "failed" | "archived";
+interface Thread {
+    id: string;
+    userId?: string;
+    projectId?: string;
+    modeId?: string;
+    status: ThreadStatus;
+    parentId?: string;
+}
+interface Message {
+    id?: string;
+    fromThreadId: string;
+    toThreadId: string;
+    content: string;
+    sentAt?: Date;
+}
+interface ThreadProvider {
+    create(projectId: string, modeId: string, signal?: AbortSignal): Promise<Thread>;
+    get(threadId: string, signal?: AbortSignal): Promise<Thread>;
+    archive(threadId: string, signal?: AbortSignal): Promise<void>;
+    sendMessage(msg: Message, signal?: AbortSignal): Promise<void>;
+}
+interface MultiUserThreadProvider extends ThreadProvider {
+    createForUser(userId: string, projectId: string, modeId: string, signal?: AbortSignal): Promise<Thread>;
+    getForUser(userId: string, threadId: string, signal?: AbortSignal): Promise<Thread>;
+    listByUser(userId: string, status: ThreadStatus, signal?: AbortSignal): Promise<Thread[]>;
+}
+declare const ErrThreadAccessDenied: Error;
+
+export { ErrThreadAccessDenied as E, type Message as M, type Thread as T, type MultiUserThreadProvider as a, type ThreadProvider as b, type ThreadStatus as c };

package/dist/tokenizer-BhG_RGUk.d.cts

@@ -0,0 +1,13 @@
+interface Tokenizer {
+    count(text: string): number;
+    encode(text: string): number[];
+    decode(tokens: number[]): string;
+}
+declare class HeuristicTokenizer implements Tokenizer {
+    count(text: string): number;
+    encode(_text: string): number[];
+    decode(_tokens: number[]): string;
+}
+declare function truncateToTokens(text: string, maxTokens: number, tok: Tokenizer): string;
+
+export { HeuristicTokenizer as H, type Tokenizer as T, truncateToTokens as t };

package/dist/tokenizer-BhG_RGUk.d.ts

@@ -0,0 +1,13 @@
+interface Tokenizer {
+    count(text: string): number;
+    encode(text: string): number[];
+    decode(tokens: number[]): string;
+}
+declare class HeuristicTokenizer implements Tokenizer {
+    count(text: string): number;
+    encode(_text: string): number[];
+    decode(_tokens: number[]): string;
+}
+declare function truncateToTokens(text: string, maxTokens: number, tok: Tokenizer): string;
+
+export { HeuristicTokenizer as H, type Tokenizer as T, truncateToTokens as t };

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@jussmor/sdk-ai",
+  "version": "0.2.0",
+  "description": "TypeScript server-side agent SDK — port of the Go harness-sdk.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./providers/llm/anthropic": {
+      "types": "./dist/providers/llm/anthropic.d.ts",
+      "import": "./dist/providers/llm/anthropic.js",
+      "require": "./dist/providers/llm/anthropic.cjs"
+    },
+    "./providers/llm/openai": {
+      "types": "./dist/providers/llm/openai.d.ts",
+      "import": "./dist/providers/llm/openai.js",
+      "require": "./dist/providers/llm/openai.cjs"
+    },
+    "./providers/llm/ollama": {
+      "types": "./dist/providers/llm/ollama.d.ts",
+      "import": "./dist/providers/llm/ollama.js",
+      "require": "./dist/providers/llm/ollama.cjs"
+    },
+    "./providers/thread/memory": {
+      "types": "./dist/providers/thread/memory.d.ts",
+      "import": "./dist/providers/thread/memory.js",
+      "require": "./dist/providers/thread/memory.cjs"
+    },
+    "./providers/thread/sqlite": {
+      "types": "./dist/providers/thread/sqlite.d.ts",
+      "import": "./dist/providers/thread/sqlite.js",
+      "require": "./dist/providers/thread/sqlite.cjs"
+    },
+    "./providers/memory/filesystem": {
+      "types": "./dist/providers/memory/filesystem.d.ts",
+      "import": "./dist/providers/memory/filesystem.js",
+      "require": "./dist/providers/memory/filesystem.cjs"
+    },
+    "./providers/store/filesystem": {
+      "types": "./dist/providers/store/filesystem.d.ts",
+      "import": "./dist/providers/store/filesystem.js",
+      "require": "./dist/providers/store/filesystem.cjs"
+    },
+    "./providers/tokenizers": {
+      "types": "./dist/providers/tokenizers/auto.d.ts",
+      "import": "./dist/providers/tokenizers/auto.js",
+      "require": "./dist/providers/tokenizers/auto.cjs"
+    }
+  },
+  "files": ["dist", "src"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "sync-check": "node --experimental-strip-types ../../scripts/check-ts-contract.ts"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.37.0",
+    "openai": "^4.77.0"
+  },
+  "optionalDependencies": {
+    "better-sqlite3": "^11.0.0",
+    "pg": "^8.13.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^22.0.0",
+    "@types/pg": "^8.11.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}