@jussmor/sdk-ai 0.2.0

package/src/dispatch.ts

@@ -0,0 +1,207 @@
+import type { ToolCallEntry } from "./llm.js";
+import type { ToolRegistry } from "./tool.js";
+import type { SandboxDriver } from "./sandbox.js";
+import type { PermissionEngine } from "./permissions.js";
+import type { ChatMessage } from "./llm.js";
+
+export type { ToolCallEntry };
+
+export interface ToolResult {
+  toolCallId: string;
+  name: string;
+  content: string;
+  error?: Error;
+}
+
+export class ToolDispatcher {
+  private permissions?: PermissionEngine;
+
+  constructor(
+    private tools: ToolRegistry,
+    private sandbox?: SandboxDriver,
+  ) {}
+
+  withPermissions(engine: PermissionEngine): this {
+    this.permissions = engine;
+    return this;
+  }
+
+  async dispatch(
+    call: ToolCallEntry,
+    sandboxId: string,
+    signal?: AbortSignal,
+  ): Promise<ToolResult> {
+    const tool = this.tools.get(call.name);
+    if (!tool) {
+      const err = new Error(`tool "${call.name}" not found`);
+      return {
+        toolCallId: call.id,
+        name: call.name,
+        content: `error: tool "${call.name}" not found in registry`,
+        error: err,
+      };
+    }
+
+    let args: Record<string, unknown> = {};
+    if (call.arguments && call.arguments !== "{}") {
+      try {
+        args = JSON.parse(call.arguments) as Record<string, unknown>;
+      } catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        return {
+          toolCallId: call.id,
+          name: call.name,
+          content: `error: invalid JSON arguments: ${err.message}`,
+          error: err,
+        };
+      }
+    }
+
+    if (tool.validate) {
+      try {
+        await tool.validate(signal, args);
+      } catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        return {
+          toolCallId: call.id,
+          name: call.name,
+          content: `error: ${err.message}`,
+          error: err,
+        };
+      }
+    }
+
+    if (this.permissions) {
+      const dec = await this.permissions.decide(tool, args, signal);
+      if (dec.behavior === "deny" || dec.behavior === "ask") {
+        const reason = dec.reason?.trim() || "permission denied";
+        const content = `<tool_use_error>The user did not approve this ${tool.name} call. Reason: ${reason}.\n\nThe tool was NOT executed. Do NOT claim success. Do NOT retry the same call. Acknowledge the rejection and ask the user how to proceed (or stop).</tool_use_error>`;
+        return {
+          toolCallId: call.id,
+          name: call.name,
+          content,
+          error: new Error(reason),
+        };
+      }
+      if (dec.updatedInput) args = dec.updatedInput;
+    } else if (tool.checkPermissions) {
+      try {
+        const result = await tool.checkPermissions(signal, args);
+        if (result.decision === "deny" || result.decision === "ask_user") {
+          const reason = result.reason?.trim() || "permission denied";
+          return {
+            toolCallId: call.id,
+            name: call.name,
+            content: `error: ${reason}`,
+            error: new Error(reason),
+          };
+        }
+        if (result.updatedArgs) args = result.updatedArgs as Record<string, unknown>;
+      } catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        return {
+          toolCallId: call.id,
+          name: call.name,
+          content: `error: permission check failed: ${err.message}`,
+          error: err,
+        };
+      }
+    }
+
+    try {
+      const content = await tool.execute(signal, sandboxId, args);
+      return { toolCallId: call.id, name: call.name, content };
+    } catch (e) {
+      const err = e instanceof Error ? e : new Error(String(e));
+      return {
+        toolCallId: call.id,
+        name: call.name,
+        content: `error: ${err.message}`,
+        error: err,
+      };
+    }
+  }
+
+  async dispatchAll(
+    calls: ToolCallEntry[],
+    sandboxId: string,
+    signal?: AbortSignal,
+  ): Promise<ToolResult[]> {
+    const results: ToolResult[] = [];
+    for (const call of calls) {
+      results.push(await this.dispatch(call, sandboxId, signal));
+    }
+    return results;
+  }
+
+  async dispatchParallel(
+    calls: ToolCallEntry[],
+    sandboxId: string,
+    signal?: AbortSignal,
+  ): Promise<ToolResult[]> {
+    if (calls.length === 0) return [];
+    if (calls.length === 1) return [await this.dispatch(calls[0]!, sandboxId, signal)];
+
+    const results = new Array<ToolResult>(calls.length);
+
+    const safe: Array<{ idx: number; call: ToolCallEntry }> = [];
+    const unsafe: Array<{ idx: number; call: ToolCallEntry }> = [];
+
+    for (let i = 0; i < calls.length; i++) {
+      const call = calls[i]!;
+      const tool = this.tools.get(call.name);
+      let isSafe = false;
+      if (tool?.isConcurrencySafe) {
+        let args: Record<string, unknown> = {};
+        try {
+          if (call.arguments && call.arguments !== "{}") {
+            args = JSON.parse(call.arguments) as Record<string, unknown>;
+          }
+        } catch {}
+        isSafe = tool.isConcurrencySafe(args);
+      }
+      if (isSafe) {
+        safe.push({ idx: i, call });
+      } else {
+        unsafe.push({ idx: i, call });
+      }
+    }
+
+    await Promise.all(
+      safe.map(async ({ idx, call }) => {
+        results[idx] = await this.dispatch(call, sandboxId, signal);
+      }),
+    );
+
+    for (const { idx, call } of unsafe) {
+      results[idx] = await this.dispatch(call, sandboxId, signal);
+    }
+
+    return results as ToolResult[];
+  }
+}
+
+export function toolResultsToMessages(
+  assistantToolCalls: ToolCallEntry[],
+  results: ToolResult[],
+): ChatMessage[] {
+  const msgs: ChatMessage[] = [
+    { role: "assistant", content: "", toolCalls: assistantToolCalls },
+  ];
+  for (const r of results) {
+    msgs.push({
+      role: "tool",
+      name: r.name,
+      toolCallId: r.toolCallId,
+      content: r.content,
+    });
+  }
+  return msgs;
+}
+
+export function areIndependent(calls: ToolCallEntry[]): boolean {
+  if (calls.length <= 1) return true;
+  return !calls.some(
+    (c) => c.arguments.includes("${") || c.arguments.includes("{{"),
+  );
+}

package/src/engine.ts

@@ -0,0 +1,53 @@
+import type { LLMProvider } from "./llm.js";
+import type { MemoryProvider } from "./memory.js";
+import type { SandboxDriver } from "./sandbox.js";
+import type { ThreadProvider } from "./thread.js";
+import type { ModeProvider } from "./mode.js";
+import type { ContextBudget } from "./context-budget.js";
+import { defaultContextBudget } from "./context-budget.js";
+import { SystemPromptBuilder } from "./system-prompt.js";
+import { ToolRegistry } from "./tool.js";
+
+export interface Engine {
+  memory?: MemoryProvider;
+  sandbox?: SandboxDriver;
+  tools?: ToolRegistry;
+  threads?: ThreadProvider;
+  modes?: ModeProvider;
+  llm?: LLMProvider;
+  prompt?: SystemPromptBuilder;
+  budget?: ContextBudget;
+}
+
+export function newEngine(...opts: Array<(e: Engine) => void>): Engine {
+  const e: Engine = {};
+  for (const opt of opts) opt(e);
+  return e;
+}
+
+export function newEngineWithDefaults(windowSize: number): Engine {
+  const budget = defaultContextBudget(windowSize);
+  return {
+    prompt: new SystemPromptBuilder(),
+    budget,
+  };
+}
+
+export const hasMemory  = (e: Engine) => e.memory != null;
+export const hasSandbox = (e: Engine) => e.sandbox != null;
+export const hasTools   = (e: Engine) => e.tools != null;
+export const hasThreads = (e: Engine) => e.threads != null;
+export const hasModes   = (e: Engine) => e.modes != null;
+export const hasLLM     = (e: Engine) => e.llm != null;
+export const hasPrompt  = (e: Engine) => e.prompt != null;
+export const hasBudget  = (e: Engine) => e.budget != null;
+
+// Functional options
+export const withMemory  = (p: MemoryProvider)  => (e: Engine) => { e.memory  = p; };
+export const withSandbox = (p: SandboxDriver)   => (e: Engine) => { e.sandbox = p; };
+export const withTools   = (r: ToolRegistry)    => (e: Engine) => { e.tools   = r; };
+export const withThreads = (p: ThreadProvider)  => (e: Engine) => { e.threads = p; };
+export const withModes   = (p: ModeProvider)    => (e: Engine) => { e.modes   = p; };
+export const withLLM     = (p: LLMProvider)     => (e: Engine) => { e.llm     = p; };
+export const withPrompt  = (b: SystemPromptBuilder) => (e: Engine) => { e.prompt = b; };
+export const withBudget  = (b: ContextBudget)   => (e: Engine) => { e.budget  = b; };

package/src/execution-context.ts

@@ -0,0 +1,31 @@
+export type TodoStatus = "pending" | "in_progress" | "completed";
+
+export interface Todo {
+  id: string;
+  content: string;
+  activeForm?: string;
+  status: TodoStatus;
+}
+
+export interface ExecutionContext {
+  todos(): Todo[];
+  setTodos(todos: Todo[]): void;
+  markDone(id: string): void;
+}
+
+export class InMemoryExecutionContext implements ExecutionContext {
+  private _todos: Todo[] = [];
+
+  todos(): Todo[] {
+    return this._todos.slice();
+  }
+
+  setTodos(todos: Todo[]): void {
+    this._todos = todos.slice();
+  }
+
+  markDone(id: string): void {
+    const todo = this._todos.find((t) => t.id === id);
+    if (todo) todo.status = "completed";
+  }
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+// Core types
+export * from "./protocol.js";
+export * from "./llm.js";
+export * from "./tool.js";
+export * from "./streaming.js";
+export * from "./conversation.js";
+export * from "./conversation-store.js";
+export * from "./mode.js";
+export * from "./memory.js";
+export * from "./thread.js";
+export * from "./sandbox.js";
+export * from "./artifact.js";
+export * from "./interrupt.js";
+export * from "./safety.js";
+export * from "./tracing.js";
+export * from "./reasoning.js";
+export * from "./tokenizer.js";
+export * from "./system-prompt.js";
+export * from "./system-reminder.js";
+export * from "./context-budget.js";
+export * from "./compaction.js";
+export * from "./permissions.js";
+export * from "./session-context.js";
+
+export * from "./execution-context.js";
+export * from "./interrupt-store.js";
+export * from "./agent-source.js";
+export * from "./memory-selector.js";
+export * from "./rule-matcher.js";
+export * from "./skill-source.js";
+
+// Core components
+export * from "./engine.js";
+export * from "./dispatch.js";
+export * from "./agent-loop.js";
+export * from "./llm-router.js";
+export * from "./runtime.js";

package/src/interrupt-store.ts

@@ -0,0 +1,25 @@
+import type { InterruptRequest } from "./interrupt.js";
+
+export interface InterruptStore {
+  put(req: InterruptRequest, signal?: AbortSignal): Promise<void>;
+  get(id: string, signal?: AbortSignal): Promise<{ req: InterruptRequest; ok: true } | { ok: false }>;
+  delete(id: string, signal?: AbortSignal): Promise<void>;
+}
+
+export class InMemoryInterruptStore implements InterruptStore {
+  private store = new Map<string, InterruptRequest>();
+
+  async put(req: InterruptRequest): Promise<void> {
+    this.store.set(req.id, req);
+  }
+
+  async get(id: string): Promise<{ req: InterruptRequest; ok: true } | { ok: false }> {
+    const req = this.store.get(id);
+    if (!req) return { ok: false };
+    return { req, ok: true };
+  }
+
+  async delete(id: string): Promise<void> {
+    this.store.delete(id);
+  }
+}

package/src/interrupt.ts

@@ -0,0 +1,55 @@
+export type InterruptKind = "approval" | "question" | "form_input";
+
+export interface FormField {
+  name: string;
+  label: string;
+  type: "text" | "textarea" | "select" | "checkbox";
+  options?: string[];
+  required?: boolean;
+  defaultValue?: string;
+}
+
+export interface InterruptRequest {
+  id: string;
+  kind: InterruptKind;
+  title: string;
+  description?: string;
+  toolName?: string;
+  toolArgs?: Record<string, unknown>;
+  fields?: FormField[];
+  createdAt: Date;
+}
+
+export interface InterruptResponse {
+  id: string;
+  approved?: boolean;
+  answer?: unknown;
+  modifiedArgs?: string;
+}
+
+export type InterruptRequester = (
+  req: InterruptRequest,
+  signal?: AbortSignal,
+) => Promise<InterruptResponse>;
+
+export class InterruptGate {
+  private requester: InterruptRequester;
+  private pending = new Map<string, InterruptRequest>();
+
+  constructor(requester: InterruptRequester) {
+    this.requester = requester;
+  }
+
+  async wait(req: InterruptRequest, signal?: AbortSignal): Promise<InterruptResponse> {
+    this.pending.set(req.id, req);
+    try {
+      return await this.requester(req, signal);
+    } finally {
+      this.pending.delete(req.id);
+    }
+  }
+
+  pendingRequests(): InterruptRequest[] {
+    return Array.from(this.pending.values());
+  }
+}

package/src/llm-router.ts

@@ -0,0 +1,34 @@
+import type { LLMProvider, ChatRequest, ChatResponse } from "./llm.js";
+
+export function parseModelRef(ref: string): [string, string] {
+  const slash = ref.indexOf("/");
+  if (slash === -1) return ["", ref];
+  return [ref.slice(0, slash), ref.slice(slash + 1)];
+}
+
+export class RoutedLLMProvider implements LLMProvider {
+  private routes = new Map<string, LLMProvider>();
+  private fallback?: LLMProvider;
+
+  register(provider: string, llm: LLMProvider): this {
+    this.routes.set(provider, llm);
+    return this;
+  }
+
+  withFallback(llm: LLMProvider): this {
+    this.fallback = llm;
+    return this;
+  }
+
+  route(model: string): LLMProvider {
+    const [provider] = parseModelRef(model);
+    const resolved = provider ? this.routes.get(provider) : undefined;
+    if (resolved) return resolved;
+    if (this.fallback) return this.fallback;
+    throw new Error(`no provider registered for model: ${model}`);
+  }
+
+  async chat(req: ChatRequest, signal?: AbortSignal): Promise<ChatResponse> {
+    return this.route(req.model ?? "").chat(req, signal);
+  }
+}

package/src/llm.ts

@@ -0,0 +1,100 @@
+export type Role = "system" | "user" | "assistant" | "tool";
+
+export interface ImageContent {
+  source?: string;
+  mediaType?: string;
+  url?: string;
+}
+
+export interface DocumentContent {
+  source?: string;
+  mediaType?: string;
+  url?: string;
+  title?: string;
+  cacheControl?: string;
+}
+
+export interface ToolCallEntry {
+  id: string;
+  name: string;
+  arguments: string;
+}
+
+export interface ToolChoice {
+  type: "auto" | "any" | "tool";
+  name?: string;
+  disableParallelToolUse?: boolean;
+}
+
+export interface ChatMessage {
+  role: Role;
+  content: string;
+  name?: string;
+  toolCallId?: string;
+  toolCalls?: ToolCallEntry[];
+  images?: ImageContent[];
+  documents?: DocumentContent[];
+}
+
+export interface ToolFuncParams {
+  type: "object";
+  properties?: Record<string, ToolParam>;
+  required?: string[];
+}
+
+export interface ToolParam {
+  type: string;
+  description?: string;
+  enum?: string[];
+  items?: ToolParam;
+  properties?: Record<string, ToolParam>;
+  required?: string[];
+}
+
+export interface ToolDef {
+  type: "function";
+  function: {
+    name: string;
+    description: string;
+    parameters: ToolFuncParams;
+  };
+}
+
+export interface ChatRequest {
+  model?: string;
+  messages: ChatMessage[];
+  tools?: ToolDef[];
+  toolChoice?: ToolChoice;
+  temperature?: number;
+  topP?: number;
+  topK?: number;
+  maxTokens?: number;
+  reasoningEffort?: string;
+  thinkingBudget?: number;
+  stop?: string[];
+  metadata?: Record<string, string>;
+}
+
+export interface TokenUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+
+export interface ChatResponse {
+  content: string;
+  reasoning?: string;
+  thinkingContent?: string;
+  toolCalls?: ToolCallEntry[];
+  finishReason: string;
+  usage: TokenUsage;
+  model?: string;
+}
+
+export interface LLMProvider {
+  chat(req: ChatRequest, signal?: AbortSignal): Promise<ChatResponse>;
+}
+
+export interface ModelRouter {
+  route(model: string): LLMProvider;
+}

package/src/memory-selector.ts

@@ -0,0 +1,38 @@
+export interface MemoryHeader {
+  path: string;
+  title?: string;
+  description?: string;
+  type?: string;
+}
+
+export interface MemorySelector {
+  select(
+    query: string,
+    headers: MemoryHeader[],
+    limit: number,
+    signal?: AbortSignal,
+  ): Promise<MemoryHeader[]>;
+}
+
+export class KeywordMemorySelector implements MemorySelector {
+  async select(
+    query: string,
+    headers: MemoryHeader[],
+    limit: number,
+  ): Promise<MemoryHeader[]> {
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    if (!terms.length || !headers.length) return [];
+
+    const scored = headers.map((h) => {
+      const text = `${h.title ?? ""} ${h.description ?? ""} ${h.type ?? ""} ${h.path}`.toLowerCase();
+      const score = terms.reduce((acc, t) => acc + (text.includes(t) ? 1 : 0), 0);
+      return { h, score };
+    });
+
+    return scored
+      .filter((s) => s.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit)
+      .map((s) => s.h);
+  }
+}

package/src/memory.ts

@@ -0,0 +1,34 @@
+export type Scope = "user" | "project";
+
+export interface MemoryEntry {
+  path: string;
+  scope: Scope;
+  content?: string;
+  source?: string;
+  updatedAt?: number;
+}
+
+export interface MemorySearchResult extends MemoryEntry {
+  score: number;
+}
+
+export interface MemoryProvider {
+  view(scope: Scope, path: string, signal?: AbortSignal): Promise<string>;
+  create(scope: Scope, path: string, content: string, signal?: AbortSignal): Promise<void>;
+  strReplace(scope: Scope, path: string, oldStr: string, newStr: string, signal?: AbortSignal): Promise<void>;
+  delete(scope: Scope, path: string, signal?: AbortSignal): Promise<void>;
+  rename(scope: Scope, oldPath: string, newPath: string, signal?: AbortSignal): Promise<void>;
+  list(scope: Scope, path: string, signal?: AbortSignal): Promise<string[]>;
+  search(scope: Scope, query: string, signal?: AbortSignal): Promise<MemoryEntry[]>;
+}
+
+export interface MemoryRoot {
+  scope: Scope;
+  path: string;
+  label: string;
+}
+
+export const DEFAULT_MEMORY_ROOTS: MemoryRoot[] = [
+  { scope: "user", path: "/", label: "User memory" },
+  { scope: "project", path: "/", label: "Project memory" },
+];

package/src/mode.ts

@@ -0,0 +1,81 @@
+export type BaseMode = "balanced" | "analyst" | "deep_work";
+
+export type ToolsMode = "allowlist" | "denylist";
+
+export interface ModeMeta {
+  id: string;
+  name: string;
+  baseMode?: string;
+  toolsMode?: ToolsMode;
+  tools?: string[];
+  model?: string;
+  reasoningEffort?: string;
+  temperature?: string;
+  author?: string;
+  created?: string;
+}
+
+export interface ModelSettings {
+  model?: string;
+  reasoningEffort?: string;
+  temperature?: number;
+}
+
+export interface Mode {
+  meta: ModeMeta;
+  id: string;
+  name: string;
+  baseModeId?: BaseMode;
+  promptContent?: string;
+  modelSettings?: ModelSettings;
+  toolsMode?: ToolsMode;
+  toolsList?: string[];
+}
+
+export function isToolAllowed(mode: Mode, toolName: string): boolean {
+  if (!mode.toolsMode || !mode.toolsList?.length) return true;
+  const listed = mode.toolsList.includes(toolName);
+  if (mode.toolsMode === "allowlist") return listed;
+  if (mode.toolsMode === "denylist") return !listed;
+  return true;
+}
+
+export interface ModeProvider {
+  get(modeId: string, signal?: AbortSignal): Promise<Mode>;
+  list(signal?: AbortSignal): Promise<Mode[]>;
+  create(mode: Mode, signal?: AbortSignal): Promise<Mode>;
+  builtinModes(): Mode[];
+}
+
+export class StaticModeProvider implements ModeProvider {
+  private modes: Map<string, Mode>;
+  private modeList: Mode[];
+
+  constructor(modes: Mode[]) {
+    this.modes = new Map();
+    this.modeList = [];
+    for (const mode of modes) {
+      if (!mode.id) continue;
+      this.modes.set(mode.id, mode);
+      this.modeList.push(mode);
+    }
+  }
+
+  async get(modeId: string): Promise<Mode> {
+    const mode = this.modes.get(modeId);
+    if (!mode) throw new Error(`mode not found: ${modeId}`);
+    return mode;
+  }
+
+  async list(): Promise<Mode[]> {
+    return this.modeList;
+  }
+
+  async create(): Promise<Mode> {
+    throw new Error("mode creation not supported by static mode provider");
+  }
+
+  builtinModes(): Mode[] {
+    return [];
+  }
+}