@jussmor/sdk-ai 0.2.0

package/src/agent-loop.ts

@@ -0,0 +1,311 @@
+import type { LLMProvider, ChatRequest, ChatMessage, ChatResponse } from "./llm.js";
+import type { ToolRegistry } from "./tool.js";
+import type { SandboxDriver } from "./sandbox.js";
+import type { PermissionEngine } from "./permissions.js";
+import type { Engine } from "./engine.js";
+import type { ReasoningStep } from "./reasoning.js";
+import { ToolDispatcher, toolResultsToMessages } from "./dispatch.js";
+import { hasLLM, hasTools, hasSandbox, hasModes, hasPrompt } from "./engine.js";
+import { parseModelRef } from "./llm-router.js";
+
+export 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;
+}
+
+export 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";
+}
+
+function previewText(value: string, limit: number): string {
+  const trimmed = value.trim().replace(/\s+/g, " ");
+  if (trimmed.length <= limit || limit <= 3) return trimmed;
+  return trimmed.slice(0, limit - 3) + "...";
+}
+
+function previewJson(value: string, limit: number): string {
+  const trimmed = value.trim();
+  if (!trimmed) return "";
+  try {
+    const parsed = JSON.parse(trimmed);
+    return previewText(JSON.stringify(parsed), limit);
+  } catch {
+    return previewText(trimmed, limit);
+  }
+}
+
+function buildDefaultRequest(cfg: AgentLoopConfig, messages: ChatMessage[]): ChatRequest {
+  const req: ChatRequest = {
+    model: cfg.model,
+    messages: [],
+  };
+  if (cfg.systemPrompt) {
+    req.messages.push({ role: "system", content: cfg.systemPrompt });
+  }
+  req.messages.push(...messages);
+  if (cfg.tools) {
+    req.tools = cfg.tools.toolDefs();
+  }
+  return req;
+}
+
+function buildRequest(cfg: AgentLoopConfig, messages: ChatMessage[]): ChatRequest {
+  if (cfg.buildRequest) {
+    return cfg.buildRequest(cfg.systemPrompt ?? "", messages, cfg.tools);
+  }
+  return buildDefaultRequest(cfg, messages);
+}
+
+type ErrorClass = "transient" | "permanent" | "unknown";
+
+function classifyError(err: Error): ErrorClass {
+  const msg = err.message.toLowerCase();
+  const permanent = ["unauthorized", "401", "403", "forbidden", "invalid api key",
+    "authentication", "invalid request", "400", "not found", "404",
+    "context length", "context window", "content_filter", "content filter"];
+  if (permanent.some((p) => msg.includes(p))) return "permanent";
+
+  const transient = ["rate limit", "429", "too many requests", "timeout", "deadline",
+    "connection reset", "connection refused", "eof", "broken pipe",
+    "500", "502", "503", "504", "server error", "service unavailable", "temporary"];
+  if (transient.some((t) => msg.includes(t))) return "transient";
+
+  return "unknown";
+}
+
+async function callWithRetry(
+  provider: LLMProvider,
+  req: ChatRequest,
+  maxRetries: number,
+  onError?: (err: Error, attempt: number) => boolean,
+  signal?: AbortSignal,
+): Promise<ChatResponse> {
+  let lastErr: Error = new Error("unknown");
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await provider.chat(req, signal);
+    } catch (e) {
+      lastErr = e instanceof Error ? e : new Error(String(e));
+
+      switch (classifyError(lastErr)) {
+        case "permanent":
+          throw lastErr;
+        case "transient":
+          if (attempt < maxRetries) {
+            const delay = Math.min(1000 * 2 ** (attempt - 1), 30000);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            continue;
+          }
+          break;
+        default:
+          if (onError == null || !onError(lastErr, attempt)) throw lastErr;
+      }
+    }
+  }
+  throw new Error(`max retries (${maxRetries}) exceeded: ${lastErr.message}`);
+}
+
+export async function runAgentLoop(
+  cfg: AgentLoopConfig,
+  messages: ChatMessage[],
+  signal?: AbortSignal,
+): Promise<AgentLoopResult> {
+  if (!cfg.provider) throw new Error("AgentLoopConfig.provider is required");
+
+  const maxTurns = cfg.maxTurns && cfg.maxTurns > 0 ? cfg.maxTurns : 50;
+  const maxRetries = cfg.maxRetries && cfg.maxRetries > 0 ? cfg.maxRetries : 3;
+
+  let req = buildRequest(cfg, messages);
+
+  const dispatcher = cfg.tools
+    ? new ToolDispatcher(cfg.tools, cfg.sandbox)
+    : undefined;
+  if (dispatcher && cfg.permissions) {
+    dispatcher.withPermissions(cfg.permissions);
+  }
+
+  const result: AgentLoopResult = {
+    finalContent: "",
+    providerReasoning: "",
+    totalTurns: 0,
+    totalUsage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+    messages: req.messages.slice(),
+    reasoningTrace: [],
+    stopReason: "complete",
+  };
+
+  let traceSeq = 0;
+  const appendTrace = (
+    type: ReasoningStep["type"],
+    title: string,
+    content?: string,
+    details?: string[],
+  ) => {
+    result.reasoningTrace.push({
+      id: `trace-${++traceSeq}`,
+      type,
+      title,
+      content,
+      details,
+    });
+  };
+
+  for (let turn = 1; turn <= maxTurns; turn++) {
+    if (signal?.aborted) {
+      result.stopReason = "aborted";
+      return result;
+    }
+
+    const resp = await callWithRetry(cfg.provider, req, maxRetries, cfg.onError, signal);
+
+    result.totalTurns = turn;
+    result.totalUsage.promptTokens += resp.usage.promptTokens;
+    result.totalUsage.completionTokens += resp.usage.completionTokens;
+    result.totalUsage.totalTokens += resp.usage.totalTokens;
+
+    if (resp.reasoning?.trim()) {
+      result.providerReasoning = result.providerReasoning
+        ? result.providerReasoning + "\n\n" + resp.reasoning
+        : resp.reasoning;
+      appendTrace("thinking", `Provider reasoning ${turn}`, previewText(resp.reasoning, 220));
+    }
+    appendTrace("thinking", `Turn ${turn}`, undefined, [
+      `Finish reason: ${resp.finishReason}`,
+      `Tool calls requested: ${resp.toolCalls?.length ?? 0}`,
+      `Tokens this turn: ${resp.usage.totalTokens}`,
+    ]);
+
+    if (cfg.onTurn && !cfg.onTurn(turn, resp)) {
+      result.finalContent = resp.content;
+      result.stopReason = "aborted";
+      return result;
+    }
+
+    if (cfg.shouldStop?.(turn, resp)) {
+      result.finalContent = resp.content;
+      result.stopReason = "stopped";
+      result.messages.push({ role: "assistant", content: resp.content });
+      return result;
+    }
+
+    if (!resp.toolCalls?.length) {
+      result.finalContent = resp.content;
+      result.stopReason = "complete";
+      result.messages.push({ role: "assistant", content: resp.content });
+      return result;
+    }
+
+    if (!dispatcher) {
+      result.stopReason = "error";
+      throw new Error("LLM requested tool calls but no ToolRegistry is configured");
+    }
+
+    const callsToRun = resp.toolCalls.filter(
+      (tc) => cfg.onToolCall == null || cfg.onToolCall(tc),
+    );
+
+    for (const tc of callsToRun) {
+      appendTrace("action", `Tool call: ${tc.name}`, previewJson(tc.arguments, 220));
+    }
+
+    let toolResults = await dispatcher.dispatchAll(callsToRun, cfg.sandboxId ?? "", signal);
+
+    if (cfg.onToolResult) {
+      toolResults = toolResults.map((tr, i) =>
+        cfg.onToolResult!(callsToRun[i]!, tr),
+      );
+    }
+
+    for (const tr of toolResults) {
+      appendTrace(tr.error ? "thinking" : "result", `Tool result: ${tr.name}`, previewText(tr.content, 220));
+    }
+
+    const toolMsgs = toolResultsToMessages(resp.toolCalls, toolResults);
+    result.messages.push(...toolMsgs);
+    req = buildRequest(cfg, result.messages);
+  }
+
+  result.stopReason = "max_turns";
+  return result;
+}
+
+export async function runAgentLoopWithEngine(
+  engine: Engine,
+  modeId: string,
+  cfg: AgentLoopConfig,
+  messages: ChatMessage[],
+  signal?: AbortSignal,
+): Promise<AgentLoopResult> {
+  const callerSuppliedPrompt = Boolean(cfg.systemPrompt);
+  let resolvedModel = cfg.model ?? "";
+
+  if (hasModes(engine) && modeId) {
+    const mode = await engine.modes!.get(modeId, signal);
+    if (!cfg.model && mode.modelSettings?.model) {
+      cfg.model = mode.modelSettings.model;
+    }
+    if (!callerSuppliedPrompt) {
+      if (hasPrompt(engine)) {
+        engine.prompt!.set("mode", mode.promptContent ?? "");
+        cfg.systemPrompt = engine.prompt!.build();
+      } else {
+        cfg.systemPrompt = mode.promptContent ?? "";
+      }
+    }
+    resolvedModel = cfg.model ?? "";
+  } else if (!callerSuppliedPrompt && hasPrompt(engine)) {
+    cfg.systemPrompt = engine.prompt!.build();
+  }
+
+  if (!resolvedModel) resolvedModel = cfg.model ?? "";
+
+  if (!cfg.provider) {
+    if (!hasLLM(engine)) throw new Error("no LLM provider configured");
+    cfg.provider = resolveProvider(engine, resolvedModel);
+    const [, modelOnly] = parseModelRef(cfg.model ?? "");
+    if (modelOnly) cfg.model = modelOnly;
+  }
+
+  if (!cfg.tools && hasTools(engine)) cfg.tools = engine.tools;
+  if (!cfg.sandbox && hasSandbox(engine)) cfg.sandbox = engine.sandbox;
+
+  return runAgentLoop(cfg, messages, signal);
+}
+
+function resolveProvider(engine: Engine, model: string): LLMProvider {
+  if (!hasLLM(engine)) throw new Error("no LLM provider configured");
+  if (model) {
+    const llm = engine.llm!;
+    if ("route" in llm && typeof (llm as { route?: unknown }).route === "function") {
+      return (llm as { route: (m: string) => LLMProvider }).route(model);
+    }
+  }
+  return engine.llm!;
+}

package/src/agent-source.ts

@@ -0,0 +1,12 @@
+export interface Agent {
+  id: string;
+  name: string;
+  description?: string;
+  promptContent?: string;
+  sourceKind?: string;
+}
+
+export interface AgentSource {
+  sourceName(): string;
+  list(signal?: AbortSignal): Promise<Agent[]>;
+}

package/src/artifact.ts

@@ -0,0 +1,31 @@
+export type ArtifactType = "file" | "component" | "data";
+
+export interface Artifact {
+  id: string;
+  type: ArtifactType;
+  title?: string;
+  content: string;
+  mediaType?: string;
+  props?: Record<string, unknown>;
+  createdAt?: Date;
+  updatedAt?: Date;
+}
+
+export type ArtifactEmitter = (artifact: Artifact) => void;
+
+const ARTIFACT_EMITTER_KEY = Symbol("artifactEmitter");
+
+export interface ArtifactContext {
+  [ARTIFACT_EMITTER_KEY]?: ArtifactEmitter;
+}
+
+export function withArtifactEmitter<T extends ArtifactContext>(
+  ctx: T,
+  emitter: ArtifactEmitter,
+): T & ArtifactContext {
+  return { ...ctx, [ARTIFACT_EMITTER_KEY]: emitter };
+}
+
+export function emitArtifact(ctx: ArtifactContext, artifact: Artifact): void {
+  ctx[ARTIFACT_EMITTER_KEY]?.(artifact);
+}

package/src/compaction.ts

@@ -0,0 +1,75 @@
+import type { ChatMessage, LLMProvider } from "./llm.js";
+import type { EnforcementResult } from "./context-budget.js";
+import type { Conversation } from "./conversation.js";
+import type { ContextBudget } from "./context-budget.js";
+import { enforceContextBudget } from "./context-budget.js";
+import type { Tokenizer } from "./tokenizer.js";
+import { HeuristicTokenizer } from "./tokenizer.js";
+
+export interface CompactionResult {
+  enforcementResult: EnforcementResult;
+  summary: string;
+}
+
+export interface Compactor {
+  summarize(messages: ChatMessage[], signal?: AbortSignal): Promise<string>;
+}
+
+export class LLMCompactor implements Compactor {
+  constructor(private llm: LLMProvider) {}
+
+  async summarize(messages: ChatMessage[], signal?: AbortSignal): Promise<string> {
+    const history = messages
+      .map((m) => `${m.role.toUpperCase()}: ${m.content}`)
+      .join("\n\n");
+
+    const resp = await this.llm.chat(
+      {
+        messages: [
+          {
+            role: "user",
+            content: `Summarize the following conversation history concisely, preserving key decisions, facts, and context:\n\n${history}`,
+          },
+        ],
+        maxTokens: 1024,
+      },
+      signal,
+    );
+    return resp.content;
+  }
+}
+
+export class BulletCompactor implements Compactor {
+  async summarize(messages: ChatMessage[]): Promise<string> {
+    const points: string[] = [];
+    for (const msg of messages) {
+      if (msg.role === "assistant" && msg.content.trim()) {
+        const first = msg.content.split("\n")[0]?.trim() ?? "";
+        if (first) points.push(`- ${first.slice(0, 120)}`);
+      }
+    }
+    return points.join("\n");
+  }
+}
+
+export async function enforceWithCompaction(
+  budget: ContextBudget,
+  compactor: Compactor | undefined,
+  conv: Conversation,
+  memoryTokens: number,
+  tok: Tokenizer = new HeuristicTokenizer(),
+  signal?: AbortSignal,
+): Promise<CompactionResult> {
+  const enforcementResult = enforceContextBudget(budget, conv, memoryTokens, tok);
+
+  let summary = "";
+  if (compactor && enforcementResult.truncatedHistory) {
+    try {
+      summary = await compactor.summarize(conv.messages.slice(0, enforcementResult.historyDropped), signal);
+    } catch {
+      // compaction failure is non-fatal
+    }
+  }
+
+  return { enforcementResult, summary };
+}

package/src/context-budget.ts

@@ -0,0 +1,65 @@
+import type { ChatMessage } from "./llm.js";
+import type { Tokenizer } from "./tokenizer.js";
+import type { Conversation } from "./conversation.js";
+
+export interface ContextBudget {
+  windowSize: number;
+  skillsReserve: number;
+  memoryReserve: number;
+  historyReserve: number;
+  reserveBuffer: number;
+}
+
+export interface EnforcementResult {
+  overflowTokens: number;
+  truncatedHistory: boolean;
+  historyDropped: number;
+  stillOverflow: boolean;
+}
+
+export function defaultContextBudget(windowSize: number): ContextBudget {
+  return {
+    windowSize,
+    skillsReserve: Math.floor(windowSize * 0.1),
+    memoryReserve: Math.floor(windowSize * 0.15),
+    historyReserve: Math.floor(windowSize * 0.6),
+    reserveBuffer: Math.floor(windowSize * 0.05),
+  };
+}
+
+export function enforceContextBudget(
+  budget: ContextBudget,
+  conv: Conversation,
+  memoryTokens: number,
+  tok: Tokenizer,
+): EnforcementResult {
+  const result: EnforcementResult = {
+    overflowTokens: 0,
+    truncatedHistory: false,
+    historyDropped: 0,
+    stillOverflow: false,
+  };
+
+  const available = budget.historyReserve;
+  let used = 0;
+  const kept: ChatMessage[] = [];
+
+  for (let i = conv.messages.length - 1; i >= 0; i--) {
+    const msg = conv.messages[i]!;
+    const tokens = tok.count(msg.content);
+    if (used + tokens > available && kept.length > 0) {
+      result.truncatedHistory = true;
+      result.historyDropped = i + 1;
+      result.overflowTokens = used + tokens - available;
+      break;
+    }
+    used += tokens;
+    kept.unshift(msg);
+  }
+
+  if (result.truncatedHistory) {
+    conv.messages = kept;
+  }
+
+  return result;
+}

package/src/conversation-store.ts

@@ -0,0 +1,8 @@
+import type { Conversation } from "./conversation.js";
+
+export interface ConversationStore {
+  save(conv: Conversation, signal?: AbortSignal): Promise<void>;
+  load(id: string, signal?: AbortSignal): Promise<Conversation | undefined>;
+  list(threadId?: string, signal?: AbortSignal): Promise<Conversation[]>;
+  delete(id: string, signal?: AbortSignal): Promise<void>;
+}

package/src/conversation.ts

@@ -0,0 +1,42 @@
+import type { ChatMessage } from "./llm.js";
+
+export interface Conversation {
+  id: string;
+  threadId?: string;
+  messages: ChatMessage[];
+  memoryRead: boolean;
+  turnCount: number;
+  createdAt: Date;
+  lastTurnAt?: Date;
+}
+
+export function newConversation(id: string): Conversation {
+  return {
+    id,
+    messages: [],
+    memoryRead: false,
+    turnCount: 0,
+    createdAt: new Date(),
+  };
+}
+
+export function isCold(conv: Conversation): boolean {
+  return conv.turnCount === 0;
+}
+
+export function appendUser(conv: Conversation, content: string): void {
+  conv.messages.push({ role: "user", content });
+}
+
+export function appendAssistant(conv: Conversation, content: string): void {
+  conv.messages.push({ role: "assistant", content });
+}
+
+export function incrementTurn(conv: Conversation): void {
+  conv.turnCount++;
+  conv.lastTurnAt = new Date();
+}
+
+export function messageCount(conv: Conversation): number {
+  return conv.messages.length;
+}