@jussmor/sdk-ai 0.2.0

package/src/providers/llm/openai.ts

@@ -0,0 +1,215 @@
+import OpenAI from "openai";
+import type {
+  LLMProvider,
+  ChatRequest,
+  ChatResponse,
+  ChatMessage,
+} from "../../llm.js";
+import type { StreamingLLMProvider, StreamEvent } from "../../streaming.js";
+
+function toOpenAIMessages(
+  messages: ChatMessage[],
+): OpenAI.ChatCompletionMessageParam[] {
+  return messages.map((msg): OpenAI.ChatCompletionMessageParam => {
+    if (msg.role === "system") {
+      return { role: "system", content: msg.content };
+    }
+    if (msg.role === "tool") {
+      return {
+        role: "tool",
+        tool_call_id: msg.toolCallId ?? "",
+        content: msg.content,
+      };
+    }
+    if (msg.role === "assistant") {
+      const out: OpenAI.ChatCompletionAssistantMessageParam = {
+        role: "assistant",
+        content: msg.content || null,
+      };
+      if (msg.toolCalls?.length) {
+        out.tool_calls = msg.toolCalls.map((tc) => ({
+          id: tc.id,
+          type: "function" as const,
+          function: { name: tc.name, arguments: tc.arguments },
+        }));
+      }
+      return out;
+    }
+    if (msg.images?.length) {
+      const content: OpenAI.ChatCompletionContentPart[] = msg.images.map(
+        (img) =>
+          img.url
+            ? ({ type: "image_url", image_url: { url: img.url } } as const)
+            : ({
+                type: "image_url",
+                image_url: {
+                  url: `data:${img.mediaType};base64,${img.source}`,
+                },
+              } as const),
+      );
+      if (msg.content) content.push({ type: "text", text: msg.content });
+      return { role: "user", content };
+    }
+    return { role: "user", content: msg.content };
+  });
+}
+
+export interface OpenAIProviderOptions {
+  apiKey?: string;
+  baseURL?: string;
+  defaultModel?: string;
+  defaultMaxTokens?: number;
+}
+
+export class OpenAIProvider implements StreamingLLMProvider {
+  private client: OpenAI;
+  private defaultModel: string;
+  private defaultMaxTokens: number;
+
+  constructor(opts: OpenAIProviderOptions = {}) {
+    this.client = new OpenAI({
+      apiKey: opts.apiKey ?? process.env["OPENAI_API_KEY"],
+      baseURL: opts.baseURL ?? process.env["OPENAI_BASE_URL"],
+    });
+    this.defaultModel = opts.defaultModel ?? "gpt-4o";
+    this.defaultMaxTokens = opts.defaultMaxTokens ?? 4096;
+  }
+
+  async chat(req: ChatRequest, signal?: AbortSignal): Promise<ChatResponse> {
+    const messages = toOpenAIMessages(req.messages);
+    const tools = req.tools?.map((t) => ({
+      type: "function" as const,
+      function: {
+        name: t.function.name,
+        description: t.function.description,
+        parameters: t.function.parameters as unknown as Record<string, unknown>,
+      },
+    }));
+
+    const resp = await this.client.chat.completions.create(
+      {
+        model: req.model ?? this.defaultModel,
+        messages,
+        max_tokens: req.maxTokens ?? this.defaultMaxTokens,
+        ...(tools?.length ? { tools } : {}),
+        ...(req.temperature != null ? { temperature: req.temperature } : {}),
+        ...(req.topP != null ? { top_p: req.topP } : {}),
+        ...(req.stop?.length ? { stop: req.stop } : {}),
+      },
+      { signal },
+    );
+
+    const choice = resp.choices[0];
+    const msg = choice?.message;
+
+    return {
+      content: msg?.content ?? "",
+      toolCalls: msg?.tool_calls?.map((tc) => ({
+        id: tc.id,
+        name: tc.function.name,
+        arguments: tc.function.arguments,
+      })),
+      finishReason: choice?.finish_reason ?? "stop",
+      usage: {
+        promptTokens: resp.usage?.prompt_tokens ?? 0,
+        completionTokens: resp.usage?.completion_tokens ?? 0,
+        totalTokens: resp.usage?.total_tokens ?? 0,
+      },
+      model: resp.model,
+    };
+  }
+
+  async *chatStream(
+    req: ChatRequest,
+    signal?: AbortSignal,
+  ): AsyncGenerator<StreamEvent> {
+    const messages = toOpenAIMessages(req.messages);
+    const tools = req.tools?.map((t) => ({
+      type: "function" as const,
+      function: {
+        name: t.function.name,
+        description: t.function.description,
+        parameters: t.function.parameters as unknown as Record<string, unknown>,
+      },
+    }));
+
+    const stream = await this.client.chat.completions.create(
+      {
+        model: req.model ?? this.defaultModel,
+        messages,
+        max_tokens: req.maxTokens ?? this.defaultMaxTokens,
+        stream: true,
+        stream_options: { include_usage: true },
+        ...(tools?.length ? { tools } : {}),
+        ...(req.temperature != null ? { temperature: req.temperature } : {}),
+        ...(req.topP != null ? { top_p: req.topP } : {}),
+        ...(req.stop?.length ? { stop: req.stop } : {}),
+      },
+      { signal },
+    );
+
+    const toolCallBufs = new Map<
+      number,
+      { id: string; name: string; argsBuf: string }
+    >();
+    let promptTokens = 0;
+    let completionTokens = 0;
+
+    for await (const chunk of stream) {
+      if (signal?.aborted) break;
+
+      if (chunk.usage) {
+        promptTokens = chunk.usage.prompt_tokens;
+        completionTokens = chunk.usage.completion_tokens;
+      }
+
+      const delta = chunk.choices[0]?.delta;
+      if (!delta) continue;
+
+      if (delta.content) {
+        yield { type: "delta", delta: delta.content };
+      }
+
+      if (delta.tool_calls) {
+        for (const tc of delta.tool_calls) {
+          const idx = tc.index;
+          if (!toolCallBufs.has(idx)) {
+            toolCallBufs.set(idx, { id: tc.id ?? "", name: tc.function?.name ?? "", argsBuf: "" });
+          }
+          const buf = toolCallBufs.get(idx)!;
+          if (tc.id) buf.id = tc.id;
+          if (tc.function?.name) buf.name = tc.function.name;
+          if (tc.function?.arguments) buf.argsBuf += tc.function.arguments;
+        }
+      }
+
+      const finishReason = chunk.choices[0]?.finish_reason;
+      if (finishReason) {
+        for (const [, tc] of toolCallBufs) {
+          yield {
+            type: "tool_call",
+            toolCall: { id: tc.id, name: tc.name, arguments: tc.argsBuf },
+          };
+        }
+        toolCallBufs.clear();
+
+        yield {
+          type: "done",
+          final: {
+            finalContent: "",
+            providerReasoning: "",
+            totalTurns: 1,
+            totalUsage: {
+              promptTokens,
+              completionTokens,
+              totalTokens: promptTokens + completionTokens,
+            },
+            messages: [],
+            reasoningTrace: [],
+            stopReason: "complete",
+          },
+        };
+      }
+    }
+  }
+}

package/src/providers/memory/filesystem.ts

@@ -0,0 +1,99 @@
+import { readFile, writeFile, mkdir, rm, rename, readdir } from "node:fs/promises";
+import { join, dirname, normalize, relative } from "node:path";
+import { existsSync } from "node:fs";
+import type { MemoryProvider, MemoryEntry, Scope } from "../../memory.js";
+
+export class FilesystemMemoryProvider implements MemoryProvider {
+  constructor(private root: string) {}
+
+  private scopeDir(scope: Scope): string {
+    return join(this.root, scope);
+  }
+
+  private resolvePath(scope: Scope, path: string): string {
+    const base = this.scopeDir(scope);
+    const resolved = normalize(join(base, path));
+    if (!resolved.startsWith(base)) {
+      throw new Error(`path traversal attempt: ${path}`);
+    }
+    return resolved;
+  }
+
+  async view(scope: Scope, path: string): Promise<string> {
+    const full = this.resolvePath(scope, path);
+    try {
+      return await readFile(full, "utf-8");
+    } catch (e) {
+      const err = e as NodeJS.ErrnoException;
+      if (err.code === "ENOENT") throw new Error(`not found: ${path}`);
+      throw e;
+    }
+  }
+
+  async create(scope: Scope, path: string, content: string): Promise<void> {
+    const full = this.resolvePath(scope, path);
+    if (existsSync(full)) {
+      throw new Error(`file already exists: ${path}`);
+    }
+    await mkdir(dirname(full), { recursive: true });
+    await writeFile(full, content, "utf-8");
+  }
+
+  async strReplace(
+    scope: Scope,
+    path: string,
+    oldStr: string,
+    newStr: string,
+  ): Promise<void> {
+    const full = this.resolvePath(scope, path);
+    const content = await readFile(full, "utf-8");
+    const count = (content.split(oldStr).length - 1);
+    if (count === 0) throw new Error(`string not found in ${path}`);
+    if (count > 1) throw new Error(`string appears ${count} times in ${path}, must appear exactly once`);
+    await writeFile(full, content.replace(oldStr, newStr), "utf-8");
+  }
+
+  async delete(scope: Scope, path: string): Promise<void> {
+    const full = this.resolvePath(scope, path);
+    await rm(full, { recursive: true, force: true });
+  }
+
+  async rename(scope: Scope, oldPath: string, newPath: string): Promise<void> {
+    const oldFull = this.resolvePath(scope, oldPath);
+    const newFull = this.resolvePath(scope, newPath);
+    await mkdir(dirname(newFull), { recursive: true });
+    await rename(oldFull, newFull);
+  }
+
+  async list(scope: Scope, path: string): Promise<string[]> {
+    const full = this.resolvePath(scope, path);
+    const base = this.scopeDir(scope);
+    try {
+      const entries = await readdir(full, { recursive: true });
+      return (entries as string[])
+        .map((e) => relative(base, join(full, e)))
+        .sort();
+    } catch {
+      return [];
+    }
+  }
+
+  async search(scope: Scope, query: string): Promise<MemoryEntry[]> {
+    const files = await this.list(scope, "/");
+    const results: MemoryEntry[] = [];
+    const q = query.toLowerCase();
+
+    for (const file of files) {
+      if (!file.endsWith(".md")) continue;
+      try {
+        const content = await this.view(scope, file);
+        if (content.toLowerCase().includes(q)) {
+          results.push({ path: file, scope, content: content.slice(0, 500) });
+        }
+      } catch {
+        // skip unreadable files
+      }
+    }
+    return results;
+  }
+}

package/src/providers/store/filesystem.ts

@@ -0,0 +1,64 @@
+import { readFile, writeFile, mkdir, rm, readdir } from "node:fs/promises";
+import { join, normalize } from "node:path";
+import type { ConversationStore } from "../../conversation-store.js";
+import type { Conversation } from "../../conversation.js";
+
+export class FilesystemConversationStore implements ConversationStore {
+  constructor(private root: string) {}
+
+  private filePath(id: string): string {
+    const safe = id.replace(/[^a-zA-Z0-9_-]/g, "_");
+    const full = normalize(join(this.root, `${safe}.json`));
+    if (!full.startsWith(normalize(this.root))) {
+      throw new Error(`invalid conversation id: ${id}`);
+    }
+    return full;
+  }
+
+  async save(conv: Conversation): Promise<void> {
+    await mkdir(this.root, { recursive: true });
+    const path = this.filePath(conv.id);
+    await writeFile(path, JSON.stringify(conv, null, 2), "utf-8");
+  }
+
+  async load(id: string): Promise<Conversation | undefined> {
+    try {
+      const raw = await readFile(this.filePath(id), "utf-8");
+      const parsed = JSON.parse(raw) as Conversation;
+      parsed.createdAt = new Date(parsed.createdAt);
+      if (parsed.lastTurnAt) parsed.lastTurnAt = new Date(parsed.lastTurnAt);
+      return parsed;
+    } catch {
+      return undefined;
+    }
+  }
+
+  async list(threadId?: string): Promise<Conversation[]> {
+    try {
+      const files = await readdir(this.root);
+      const convs: Conversation[] = [];
+      for (const f of files) {
+        if (!f.endsWith(".json")) continue;
+        const id = f.slice(0, -5);
+        const conv = await this.load(id);
+        if (conv && (!threadId || conv.threadId === threadId)) {
+          convs.push(conv);
+        }
+      }
+      return convs.sort(
+        (a, b) =>
+          new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime(),
+      );
+    } catch {
+      return [];
+    }
+  }
+
+  async delete(id: string): Promise<void> {
+    try {
+      await rm(this.filePath(id));
+    } catch {
+      // already gone
+    }
+  }
+}

package/src/providers/thread/memory.ts

@@ -0,0 +1,67 @@
+import { randomUUID } from "node:crypto";
+import type {
+  ThreadProvider,
+  MultiUserThreadProvider,
+  Thread,
+  ThreadStatus,
+  Message,
+} from "../../thread.js";
+import { ErrThreadAccessDenied } from "../../thread.js";
+
+export class InMemoryThreadProvider implements MultiUserThreadProvider {
+  private threads = new Map<string, Thread>();
+
+  async create(projectId: string, modeId: string): Promise<Thread> {
+    const t: Thread = {
+      id: randomUUID(),
+      projectId,
+      modeId,
+      status: "active",
+    };
+    this.threads.set(t.id, t);
+    return t;
+  }
+
+  async createForUser(
+    userId: string,
+    projectId: string,
+    modeId: string,
+  ): Promise<Thread> {
+    const t: Thread = {
+      id: randomUUID(),
+      userId,
+      projectId,
+      modeId,
+      status: "active",
+    };
+    this.threads.set(t.id, t);
+    return t;
+  }
+
+  async get(threadId: string): Promise<Thread> {
+    const t = this.threads.get(threadId);
+    if (!t) throw new Error(`thread not found: ${threadId}`);
+    return t;
+  }
+
+  async getForUser(userId: string, threadId: string): Promise<Thread> {
+    const t = await this.get(threadId);
+    if (t.userId && t.userId !== userId) throw ErrThreadAccessDenied;
+    return t;
+  }
+
+  async listByUser(userId: string, status: ThreadStatus): Promise<Thread[]> {
+    return Array.from(this.threads.values()).filter(
+      (t) => t.userId === userId && (!status || t.status === status),
+    );
+  }
+
+  async archive(threadId: string): Promise<void> {
+    const t = await this.get(threadId);
+    t.status = "archived";
+  }
+
+  async sendMessage(_msg: Message): Promise<void> {
+    // in-memory: drop messages
+  }
+}

package/src/providers/thread/sqlite.ts

@@ -0,0 +1,147 @@
+import { randomUUID } from "node:crypto";
+import type {
+  MultiUserThreadProvider,
+  Thread,
+  ThreadStatus,
+  Message,
+} from "../../thread.js";
+import { ErrThreadAccessDenied } from "../../thread.js";
+
+interface BetterSqlite3Database {
+  prepare(sql: string): BetterSqlite3Statement;
+  exec(sql: string): void;
+  pragma(pragma: string): unknown;
+}
+
+interface BetterSqlite3Statement {
+  run(...params: unknown[]): { changes: number };
+  get(...params: unknown[]): unknown;
+  all(...params: unknown[]): unknown[];
+}
+
+// Import dynamically to allow the package to be optional
+async function openDatabase(path: string): Promise<BetterSqlite3Database> {
+  const { default: Database } = await import("better-sqlite3") as { default: new (path: string) => BetterSqlite3Database };
+  const db = new Database(path);
+  db.pragma("journal_mode = WAL");
+  db.pragma("foreign_keys = ON");
+  return db;
+}
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS threads (
+  id TEXT PRIMARY KEY,
+  user_id TEXT,
+  project_id TEXT NOT NULL,
+  mode_id TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'active',
+  parent_id TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS thread_messages (
+  id TEXT PRIMARY KEY,
+  from_thread_id TEXT NOT NULL,
+  to_thread_id TEXT NOT NULL,
+  content TEXT NOT NULL,
+  sent_at TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (to_thread_id) REFERENCES threads(id) ON DELETE CASCADE
+);
+`;
+
+interface ThreadRow {
+  id: string;
+  user_id: string | null;
+  project_id: string;
+  mode_id: string;
+  status: string;
+  parent_id: string | null;
+}
+
+function rowToThread(row: ThreadRow): Thread {
+  return {
+    id: row.id,
+    userId: row.user_id ?? undefined,
+    projectId: row.project_id,
+    modeId: row.mode_id,
+    status: row.status as ThreadStatus,
+    parentId: row.parent_id ?? undefined,
+  };
+}
+
+export class SqliteThreadProvider implements MultiUserThreadProvider {
+  private db!: BetterSqlite3Database;
+  private ready: Promise<void>;
+
+  constructor(dbPath: string) {
+    this.ready = openDatabase(dbPath).then((db) => {
+      this.db = db;
+      db.exec(SCHEMA);
+    });
+  }
+
+  private async ensureReady(): Promise<void> {
+    await this.ready;
+  }
+
+  async create(projectId: string, modeId: string): Promise<Thread> {
+    await this.ensureReady();
+    const id = randomUUID();
+    this.db.prepare(
+      `INSERT INTO threads (id, project_id, mode_id) VALUES (?, ?, ?)`,
+    ).run(id, projectId, modeId);
+    return this.get(id);
+  }
+
+  async createForUser(
+    userId: string,
+    projectId: string,
+    modeId: string,
+  ): Promise<Thread> {
+    await this.ensureReady();
+    const id = randomUUID();
+    this.db.prepare(
+      `INSERT INTO threads (id, user_id, project_id, mode_id) VALUES (?, ?, ?, ?)`,
+    ).run(id, userId, projectId, modeId);
+    return this.get(id);
+  }
+
+  async get(threadId: string): Promise<Thread> {
+    await this.ensureReady();
+    const row = this.db
+      .prepare(`SELECT * FROM threads WHERE id = ?`)
+      .get(threadId) as ThreadRow | undefined;
+    if (!row) throw new Error(`thread not found: ${threadId}`);
+    return rowToThread(row);
+  }
+
+  async getForUser(userId: string, threadId: string): Promise<Thread> {
+    const t = await this.get(threadId);
+    if (t.userId && t.userId !== userId) throw ErrThreadAccessDenied;
+    return t;
+  }
+
+  async listByUser(userId: string, status: ThreadStatus): Promise<Thread[]> {
+    await this.ensureReady();
+    const rows = this.db
+      .prepare(
+        `SELECT * FROM threads WHERE user_id = ? ${status ? "AND status = ?" : ""} ORDER BY created_at DESC`,
+      )
+      .all(...(status ? [userId, status] : [userId])) as ThreadRow[];
+    return rows.map(rowToThread);
+  }
+
+  async archive(threadId: string): Promise<void> {
+    await this.ensureReady();
+    this.db
+      .prepare(`UPDATE threads SET status = 'archived' WHERE id = ?`)
+      .run(threadId);
+  }
+
+  async sendMessage(msg: Message): Promise<void> {
+    await this.ensureReady();
+    this.db.prepare(
+      `INSERT INTO thread_messages (id, from_thread_id, to_thread_id, content) VALUES (?, ?, ?, ?)`,
+    ).run(msg.id ?? randomUUID(), msg.fromThreadId, msg.toThreadId, msg.content);
+  }
+}

package/src/providers/tokenizers/auto.ts

@@ -0,0 +1,26 @@
+import type { Tokenizer } from "../../tokenizer.js";
+import { ClaudeTokenizer } from "./byte.js";
+import { TiktokenTokenizer } from "./tiktoken.js";
+
+const cache = new Map<string, Tokenizer>();
+
+export function autoTokenizer(model: string): Tokenizer {
+  const cached = cache.get(model);
+  if (cached) return cached;
+
+  const lower = model.toLowerCase();
+  let tok: Tokenizer;
+
+  if (lower.includes("gpt-4o") || lower.startsWith("o1") || lower.startsWith("o3") || lower.startsWith("gpt-5")) {
+    tok = new TiktokenTokenizer("o200k_base");
+  } else if (lower.includes("gpt-4") || lower.includes("gpt-3.5")) {
+    tok = new TiktokenTokenizer("cl100k_base");
+  } else {
+    tok = new ClaudeTokenizer();
+  }
+
+  cache.set(model, tok);
+  return tok;
+}
+
+export { ClaudeTokenizer, TiktokenTokenizer };

package/src/providers/tokenizers/byte.ts

@@ -0,0 +1,27 @@
+import type { Tokenizer } from "../../tokenizer.js";
+
+export class ByteTokenizer implements Tokenizer {
+  private charsPerToken: number;
+
+  constructor(charsPerToken = 4.0) {
+    this.charsPerToken = charsPerToken;
+  }
+
+  count(text: string): number {
+    return Math.ceil([...text].length / this.charsPerToken);
+  }
+
+  encode(_text: string): number[] { return []; }
+  decode(_tokens: number[]): string { return ""; }
+}
+
+export class ClaudeTokenizer implements Tokenizer {
+  count(text: string): number {
+    const words = text.split(/\s+/).filter(Boolean).length;
+    const specials = (text.match(/[{}\[\]<>()]/g) ?? []).length;
+    return Math.ceil(words * 1.3 + specials * 0.5);
+  }
+
+  encode(_text: string): number[] { return []; }
+  decode(_tokens: number[]): string { return ""; }
+}