@jussmor/sdk-ai 0.2.0

package/src/providers/tokenizers/tiktoken.ts

@@ -0,0 +1,91 @@
+import type { Tokenizer } from "../../tokenizer.js";
+import { ClaudeTokenizer } from "./byte.js";
+
+// Lazy-loaded tiktoken encoding. Falls back to ClaudeTokenizer if not installed.
+type TiktokenEncoding = {
+  encode(text: string): Uint32Array;
+  decode(tokens: Uint32Array): string;
+};
+
+type TiktokenModule = {
+  getEncoding(name: string): TiktokenEncoding;
+};
+
+let cl100k: TiktokenEncoding | undefined;
+let o200k: TiktokenEncoding | undefined;
+let loadAttempted = false;
+let tiktokenMod: TiktokenModule | undefined;
+
+async function loadTiktoken(): Promise<TiktokenModule | undefined> {
+  if (loadAttempted) return tiktokenMod;
+  loadAttempted = true;
+  try {
+    // Dynamic import — tiktoken is an optional peer dependency.
+    // Use a variable to prevent tsc from resolving the literal "tiktoken" module.
+    const modName = "tiktoken";
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const mod = await import(/* @vite-ignore */ modName as string) as unknown;
+    tiktokenMod = mod as TiktokenModule;
+  } catch {
+    // tiktoken not installed — fall back to heuristic
+  }
+  return tiktokenMod;
+}
+
+export type TiktokenEncName = "cl100k_base" | "o200k_base";
+
+export class TiktokenTokenizer implements Tokenizer {
+  private encName: TiktokenEncName;
+  private enc?: TiktokenEncoding;
+  private fallback = new ClaudeTokenizer();
+  private initPromise: Promise<void>;
+
+  constructor(encName: TiktokenEncName = "cl100k_base") {
+    this.encName = encName;
+    this.initPromise = loadTiktoken().then((mod) => {
+      if (!mod) return;
+      try {
+        if (this.encName === "cl100k_base") {
+          cl100k ??= mod.getEncoding("cl100k_base");
+          this.enc = cl100k;
+        } else {
+          o200k ??= mod.getEncoding("o200k_base");
+          this.enc = o200k;
+        }
+      } catch {
+        // encoding load failed
+      }
+    });
+  }
+
+  async ready(): Promise<void> {
+    await this.initPromise;
+  }
+
+  count(text: string): number {
+    if (!this.enc) return this.fallback.count(text);
+    try {
+      return this.enc.encode(text).length;
+    } catch {
+      return this.fallback.count(text);
+    }
+  }
+
+  encode(text: string): number[] {
+    if (!this.enc) return [];
+    try {
+      return Array.from(this.enc.encode(text));
+    } catch {
+      return [];
+    }
+  }
+
+  decode(tokens: number[]): string {
+    if (!this.enc) return "";
+    try {
+      return this.enc.decode(new Uint32Array(tokens));
+    } catch {
+      return "";
+    }
+  }
+}

package/src/reasoning.ts

@@ -0,0 +1,7 @@
+export interface ReasoningStep {
+  id: string;
+  type: "thinking" | "action" | "result";
+  title: string;
+  content?: string;
+  details?: string[];
+}

package/src/rule-matcher.ts

@@ -0,0 +1,32 @@
+export interface RuleMatcher {
+  match(ruleContent: string, input: Record<string, unknown>): boolean;
+}
+
+export type RuleMatcherFunc = (
+  ruleContent: string,
+  input: Record<string, unknown>,
+) => boolean;
+
+export function ruleMatcherFromFn(fn: RuleMatcherFunc): RuleMatcher {
+  return { match: fn };
+}
+
+export function prefixMatcher(argKey: string): RuleMatcher {
+  return {
+    match(rule: string, input: Record<string, unknown>): boolean {
+      if (!rule) return true;
+      const val = input[argKey];
+      return typeof val === "string" && val.startsWith(rule);
+    },
+  };
+}
+
+export function exactMatcher(): RuleMatcher {
+  return {
+    match(rule: string, input: Record<string, unknown>): boolean {
+      if (!rule) return true;
+      const primary = Object.values(input)[0];
+      return String(primary) === rule;
+    },
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,416 @@
+import type { Engine } from "./engine.js";
+import { hasLLM, hasMemory, hasPrompt, hasBudget, hasModes, hasTools } from "./engine.js";
+import type { Conversation } from "./conversation.js";
+import {
+  isCold,
+  appendUser,
+  appendAssistant,
+  incrementTurn,
+} from "./conversation.js";
+import type { Tokenizer } from "./tokenizer.js";
+import { HeuristicTokenizer } from "./tokenizer.js";
+import type { ConversationStore } from "./conversation-store.js";
+import type { SafetyFilter } from "./safety.js";
+import type { Compactor } from "./compaction.js";
+import { enforceWithCompaction } from "./compaction.js";
+import type { SessionContextProvider } from "./session-context.js";
+import { formatSessionContext } from "./session-context.js";
+import type { PermissionEngine } from "./permissions.js";
+import type { InterruptGate } from "./interrupt.js";
+import type { MemoryRoot } from "./memory.js";
+import { DEFAULT_MEMORY_ROOTS } from "./memory.js";
+import type { Span } from "./tracing.js";
+import { Tracer } from "./tracing.js";
+import type { AgentLoopResult } from "./agent-loop.js";
+import { runAgentLoopWithEngine } from "./agent-loop.js";
+import type { StreamEvent } from "./streaming.js";
+import type { ChatMessage } from "./llm.js";
+import { ToolDispatcher } from "./dispatch.js";
+import { systemReminder, joinSystemReminders } from "./system-reminder.js";
+
+export interface RuntimeResult {
+  response: string;
+  turns: number;
+  usage: { promptTokens: number; completionTokens: number; totalTokens: number };
+  stopReason: string;
+  trace: Span[];
+  traceId: string;
+  memoryRead: boolean;
+  memoryWritten: string[];
+  warnings: string[];
+  startedAt: Date;
+  completedAt?: Date;
+}
+
+export interface PlanController {
+  onStateChanged?: (ev: { state: string; plan?: string; reason?: string }) => void;
+}
+
+export class Runtime {
+  private engine: Engine;
+  private mode = "";
+  private model = "";
+  private safety?: SafetyFilter;
+  private tokenizer: Tokenizer = new HeuristicTokenizer();
+  private store?: ConversationStore;
+  private sessionContext?: SessionContextProvider;
+  private compactor?: Compactor;
+  private maxMemoryTokens = 0;
+  private memoryRoots: MemoryRoot[] = DEFAULT_MEMORY_ROOTS;
+  private thinkingBudget = 0;
+  private interruptGate?: InterruptGate;
+  private permissions?: PermissionEngine;
+  private planController?: PlanController;
+  private _emit?: (ev: StreamEvent) => void;
+
+  constructor(engine: Engine) {
+    this.engine = engine;
+  }
+
+  withMode(modeId: string): this { this.mode = modeId; return this; }
+  withModel(model: string): this { this.model = model; return this; }
+  withSafety(s: SafetyFilter): this { this.safety = s; return this; }
+  withPermissions(e: PermissionEngine): this { this.permissions = e; return this; }
+  withTokenizer(t: Tokenizer): this { this.tokenizer = t; return this; }
+  withConversationStore(s: ConversationStore): this { this.store = s; return this; }
+  withSessionContext(p: SessionContextProvider): this { this.sessionContext = p; return this; }
+  withCompactor(c: Compactor): this { this.compactor = c; return this; }
+  withMaxMemoryTokens(n: number): this { this.maxMemoryTokens = n; return this; }
+  withMemoryRoots(...roots: MemoryRoot[]): this { this.memoryRoots = roots; return this; }
+  withThinkingBudget(tokens: number): this { this.thinkingBudget = tokens; return this; }
+  withInterruptGate(gate: InterruptGate): this { this.interruptGate = gate; return this; }
+  withPlanController(pc: PlanController): this {
+    const prev = pc.onStateChanged;
+    pc.onStateChanged = (ev) => {
+      prev?.(ev);
+      const planMode = { state: ev.state as "entered" | "exited", plan: ev.plan, reason: ev.reason };
+      this._emit?.({ type: "plan_mode_changed", planMode });
+    };
+    this.planController = pc;
+    return this;
+  }
+
+  async run(
+    conv: Conversation,
+    userMessage: string,
+    signal?: AbortSignal,
+  ): Promise<RuntimeResult> {
+    if (!hasLLM(this.engine)) throw new Error("runtime: no LLM provider");
+    if (!conv) throw new Error("runtime: conversation is required");
+
+    const tracer = new Tracer();
+    const rr: RuntimeResult = {
+      response: "",
+      turns: 0,
+      usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+      stopReason: "",
+      trace: [],
+      traceId: tracer.traceId(),
+      memoryRead: false,
+      memoryWritten: [],
+      warnings: [],
+      startedAt: new Date(),
+    };
+
+    appendUser(conv, userMessage);
+
+    // Orientation
+    if (isCold(conv)) {
+      await this.orientation(conv, userMessage, rr, signal);
+    } else {
+      await this.warmRefresh(conv, userMessage, signal);
+    }
+
+    if (signal?.aborted) return rr;
+
+    // Preparation
+    await this.preparation(conv, rr, signal);
+
+    if (signal?.aborted) return rr;
+
+    // Execution
+    const loopResult = await this.execution(conv, rr, signal);
+
+    if (loopResult?.finalContent) {
+      appendAssistant(conv, loopResult.finalContent);
+    }
+
+    if (signal?.aborted) return rr;
+
+    // Closure (no-op in v3 — memory writes go through the tool)
+
+    incrementTurn(conv);
+
+    if (this.store) {
+      try {
+        await this.store.save(conv, signal);
+      } catch (e) {
+        rr.warnings.push(`save conversation: ${(e as Error).message}`);
+      }
+    }
+
+    rr.completedAt = new Date();
+    rr.trace = tracer.allSpans();
+    return rr;
+  }
+
+  async *runStream(
+    conv: Conversation,
+    userMessage: string,
+    signal?: AbortSignal,
+  ): AsyncGenerator<StreamEvent> {
+    const out: StreamEvent[] = [];
+    let resolve: (() => void) | null = null;
+    let done = false;
+
+    this._emit = (ev: StreamEvent) => {
+      out.push(ev);
+      resolve?.();
+    };
+
+    const runPromise = this.run(conv, userMessage, signal).then(
+      (result) => {
+        if (result.response) {
+          for (const chunk of chunkBySentence(result.response)) {
+            out.push({ type: "delta", delta: chunk });
+          }
+        }
+        out.push({ type: "done" });
+        done = true;
+        resolve?.();
+      },
+      (err: Error) => {
+        out.push({ type: "error", error: err });
+        out.push({ type: "done" });
+        done = true;
+        resolve?.();
+      },
+    ).finally(() => {
+      this._emit = undefined;
+    });
+
+    while (!done || out.length > 0) {
+      if (out.length === 0) {
+        await new Promise<void>((r) => { resolve = r; });
+        resolve = null;
+        continue;
+      }
+      yield out.shift()!;
+    }
+
+    await runPromise;
+  }
+
+  private async orientation(
+    conv: Conversation,
+    userMessage: string,
+    rr: RuntimeResult,
+    signal?: AbortSignal,
+  ): Promise<void> {
+    if (hasMemory(this.engine) && hasPrompt(this.engine)) {
+      const scopes = [...new Set(this.memoryRoots.map((r) => r.scope))];
+      const sections: string[] = [];
+      for (const scope of scopes) {
+        try {
+          const index = await this.engine.memory!.view(scope, "MEMORY.md", signal);
+          if (index.trim()) sections.push(index.trim());
+        } catch {
+          // no MEMORY.md yet — that's fine
+        }
+      }
+      if (sections.length > 0) {
+        let section = sections.join("\n\n");
+        if (this.maxMemoryTokens > 0 && this.tokenizer.count(section) > this.maxMemoryTokens) {
+          section = evictMemoryToTokenBudget(section, this.maxMemoryTokens, this.tokenizer);
+        }
+        this.engine.prompt!.set("memory", section);
+        rr.memoryRead = true;
+        conv.memoryRead = true;
+      }
+    }
+    await this.buildSessionLayer(conv, userMessage, signal);
+  }
+
+  private async warmRefresh(
+    conv: Conversation,
+    userMessage: string,
+    signal?: AbortSignal,
+  ): Promise<void> {
+    await this.buildSessionLayer(conv, userMessage, signal);
+  }
+
+  private async buildSessionLayer(
+    conv: Conversation,
+    _userMessage: string,
+    signal?: AbortSignal,
+  ): Promise<void> {
+    if (!hasPrompt(this.engine)) return;
+    if (!this.sessionContext) {
+      this.engine.prompt!.clear("session");
+      return;
+    }
+    try {
+      const sc = await this.sessionContext.get(conv, signal);
+      if (!sc) { this.engine.prompt!.clear("session"); return; }
+      const rendered = formatSessionContext(sc);
+      if (!rendered) { this.engine.prompt!.clear("session"); return; }
+      this.engine.prompt!.set("session", rendered);
+    } catch {
+      this.engine.prompt!.clear("session");
+    }
+  }
+
+  private async preparation(
+    conv: Conversation,
+    rr: RuntimeResult,
+    signal?: AbortSignal,
+  ): Promise<void> {
+    if (!hasBudget(this.engine) || !hasPrompt(this.engine)) return;
+    const memoryTokens = this.tokenizer.count(
+      this.engine.prompt!.get("memory"),
+    );
+    const compResult = await enforceWithCompaction(
+      this.engine.budget!,
+      this.compactor,
+      conv,
+      memoryTokens,
+      this.tokenizer,
+      signal,
+    );
+    const enforce = compResult.enforcementResult;
+    if (enforce.overflowTokens > 0) {
+      if (enforce.truncatedHistory) {
+        rr.warnings.push(`budget: dropped ${enforce.historyDropped} messages`);
+      }
+      if (enforce.stillOverflow) {
+        rr.warnings.push("budget: still over after enforcement");
+      }
+    }
+    if (compResult.summary) {
+      this.engine.prompt!.append(
+        "memory",
+        `\n\nContext summary (from earlier turns):\n${compResult.summary}`,
+      );
+    }
+    if (this._emit && enforce.truncatedHistory) {
+      this._emit({
+        type: "compaction",
+        compaction: {
+          messagesDropped: enforce.historyDropped,
+          overflowTokens: enforce.overflowTokens,
+          summary: compResult.summary,
+        },
+      });
+    }
+  }
+
+  private async execution(
+    conv: Conversation,
+    rr: RuntimeResult,
+    signal?: AbortSignal,
+  ): Promise<AgentLoopResult | undefined> {
+    let systemPrompt = "";
+    if (hasPrompt(this.engine)) {
+      if (this.mode && hasModes(this.engine)) {
+        try {
+          const mode = await this.engine.modes!.get(this.mode, signal);
+          this.engine.prompt!.set("mode", mode.promptContent ?? "");
+        } catch {}
+      }
+      systemPrompt = this.engine.prompt!.build();
+    }
+
+    // Collect dynamic reminders
+    if (hasTools(this.engine)) {
+      const blocks = await this.engine.tools!.collectDynamicReminders(signal);
+      if (blocks.length > 0) {
+        const wrapped = blocks.map(systemReminder).filter(Boolean);
+        const joined = joinSystemReminders(...wrapped);
+        if (joined) {
+          systemPrompt = systemPrompt ? systemPrompt + "\n\n" + joined : joined;
+        }
+      }
+    }
+
+    const cfg = {
+      systemPrompt,
+      model: this.model,
+      permissions: this.permissions,
+      maxTurns: 50,
+      onToolCall: (call: { name: string; arguments: string; id: string }) => {
+        if (this.safety) {
+          const verdict = this.safety.inspect(call);
+          return verdict.decision !== "block";
+        }
+        return true;
+      },
+    };
+
+    const loopResult = await runAgentLoopWithEngine(
+      this.engine,
+      this.mode,
+      cfg,
+      conv.messages,
+      signal,
+    );
+
+    rr.turns += loopResult.totalTurns;
+    rr.usage.promptTokens += loopResult.totalUsage.promptTokens;
+    rr.usage.completionTokens += loopResult.totalUsage.completionTokens;
+    rr.usage.totalTokens += loopResult.totalUsage.totalTokens;
+    rr.stopReason = loopResult.stopReason;
+    rr.response = loopResult.finalContent;
+
+    conv.messages = loopResult.messages;
+
+    return loopResult;
+  }
+}
+
+function evictMemoryToTokenBudget(
+  content: string,
+  maxTokens: number,
+  tok: Tokenizer,
+): string {
+  const paragraphs = content.trim().split(/\n\n+/);
+  const kept: string[] = [];
+  let used = 0;
+
+  for (let i = paragraphs.length - 1; i >= 0; i--) {
+    const p = paragraphs[i]!.trim();
+    if (!p) continue;
+    const tokens = tok.count(p);
+    if (used + tokens > maxTokens && kept.length > 0) break;
+    kept.unshift(p);
+    used += tokens;
+  }
+
+  if (kept.length < paragraphs.length) {
+    kept.unshift("[Earlier memory entries omitted — token budget exceeded]");
+  }
+  return kept.join("\n\n");
+}
+
+function chunkBySentence(text: string): string[] {
+  if (!text) return [];
+  const chunks: string[] = [];
+  let current = "";
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]!;
+    current += ch;
+    if (ch === "." || ch === "!" || ch === "?" || ch === "\n") {
+      const next = text[i + 1];
+      if (!next || next === " " || next === "\n" || next === "\t") {
+        const chunk = current.trim();
+        if (chunk) chunks.push(chunk + " ");
+        current = "";
+      }
+    }
+  }
+  if (current.trim()) chunks.push(current.trim());
+  return chunks;
+}
+
+export function newRuntime(engine: Engine): Runtime {
+  return new Runtime(engine);
+}

package/src/safety.ts

@@ -0,0 +1,56 @@
+import type { ToolCallEntry } from "./llm.js";
+
+export type SafetyDecision = "allow" | "block" | "transform";
+
+export interface SafetyVerdict {
+  decision: SafetyDecision;
+  reason?: string;
+  newArgs?: string;
+}
+
+export interface SafetyFilter {
+  inspect(call: ToolCallEntry, signal?: AbortSignal): SafetyVerdict;
+}
+
+const DANGEROUS_PATTERNS = [
+  /rm\s+-rf\s+\/[^a-z]/i,
+  /curl.*\|\s*(?:bash|sh|python)/i,
+  /wget.*\|\s*(?:bash|sh|python)/i,
+  /mkfs/i,
+  /dd\s+if=/i,
+  />\s*\/dev\/sd[a-z]/i,
+];
+
+const SECRET_PATTERNS = [
+  /sk-[a-zA-Z0-9]{20,}/,
+  /AKIA[0-9A-Z]{16}/,
+  /ghp_[a-zA-Z0-9]{36}/,
+  /-----BEGIN (?:RSA |EC )?PRIVATE KEY-----/,
+  /password\s*[:=]\s*['"][^'"]{8,}['"]/i,
+];
+
+export class DefaultSafetyFilter implements SafetyFilter {
+  inspect(call: ToolCallEntry): SafetyVerdict {
+    const args = call.arguments;
+
+    for (const pattern of DANGEROUS_PATTERNS) {
+      if (pattern.test(args)) {
+        return {
+          decision: "block",
+          reason: `dangerous command pattern detected: ${pattern.source}`,
+        };
+      }
+    }
+
+    for (const pattern of SECRET_PATTERNS) {
+      if (pattern.test(args)) {
+        return {
+          decision: "block",
+          reason: "potential secret leak detected in tool arguments",
+        };
+      }
+    }
+
+    return { decision: "allow" };
+  }
+}

package/src/sandbox.ts

@@ -0,0 +1,23 @@
+export interface SandboxExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export 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>;
+}

package/src/session-context.ts

@@ -0,0 +1,33 @@
+import type { Conversation } from "./conversation.js";
+
+export interface SessionContext {
+  currentTime?: Date;
+  timezone?: string;
+  userId?: string;
+  username?: string;
+  projectId?: string;
+  activeArtifactId?: string;
+  extras?: Record<string, string>;
+}
+
+export function formatSessionContext(sc: SessionContext): string {
+  const parts: string[] = [];
+  if (sc.currentTime) {
+    parts.push(`Current time: ${sc.currentTime.toISOString()}`);
+  }
+  if (sc.timezone) parts.push(`Timezone: ${sc.timezone}`);
+  if (sc.userId) parts.push(`User ID: ${sc.userId}`);
+  if (sc.username) parts.push(`Username: ${sc.username}`);
+  if (sc.projectId) parts.push(`Project: ${sc.projectId}`);
+  if (sc.activeArtifactId) parts.push(`Active artifact: ${sc.activeArtifactId}`);
+  if (sc.extras) {
+    for (const [k, v] of Object.entries(sc.extras)) {
+      parts.push(`${k}: ${v}`);
+    }
+  }
+  return parts.join("\n");
+}
+
+export interface SessionContextProvider {
+  get(conv: Conversation, signal?: AbortSignal): Promise<SessionContext | undefined>;
+}

package/src/skill-source.ts

@@ -0,0 +1,21 @@
+export interface Skill {
+  id: string;
+  name: string;
+  description?: string;
+  promptContent?: string;
+  sourceKind?: string;
+  allowedTools?: string[];
+}
+
+export interface SkillSource {
+  sourceName(): string;
+  list(signal?: AbortSignal): Promise<Skill[]>;
+}
+
+export interface SkillBashExecutor {
+  execute(
+    command: string,
+    allowedTools: string[],
+    signal?: AbortSignal,
+  ): Promise<string>;
+}