@jussmor/sdk-ai 0.2.0

package/src/streaming.ts

@@ -0,0 +1,124 @@
+import type { AgentLoopResult } from "./agent-loop.js";
+import type { Artifact } from "./artifact.js";
+import type { InterruptRequest } from "./interrupt.js";
+import type { ToolCallEntry, ToolResult } from "./dispatch.js";
+import type { LLMProvider, ChatRequest } from "./llm.js";
+
+export 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";
+
+export interface CompactionEvent {
+  messagesDropped: number;
+  overflowTokens: number;
+  summary?: string;
+}
+
+export interface PlanModeEvent {
+  state: "entered" | "exited";
+  plan?: string;
+  reason?: string;
+}
+
+export interface AgentResult {
+  agentId: string;
+  result: AgentLoopResult;
+}
+
+export 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;
+}
+
+export interface StreamingLLMProvider extends LLMProvider {
+  chatStream(
+    req: ChatRequest,
+    signal?: AbortSignal,
+  ): AsyncGenerator<StreamEvent>;
+}
+
+export async function collectStream(
+  events: AsyncGenerator<StreamEvent>,
+): Promise<{ text: string; final: AgentLoopResult | undefined; error: Error | undefined }> {
+  let text = "";
+  let final: AgentLoopResult | undefined;
+  let error: Error | undefined;
+
+  for await (const ev of events) {
+    if (ev.type === "delta" && ev.delta) text += ev.delta;
+    if (ev.type === "done") final = ev.final;
+    if (ev.type === "error") error = ev.error;
+  }
+  return { text, final, error };
+}
+
+export function fanOutStream(
+  source: AsyncGenerator<StreamEvent>,
+  consumers: number,
+): AsyncGenerator<StreamEvent>[] {
+  const queues: StreamEvent[][] = Array.from({ length: consumers }, () => []);
+  const resolvers: Array<((value: IteratorResult<StreamEvent>) => void) | null> = Array(consumers).fill(null);
+  let done = false;
+
+  void (async () => {
+    for await (const ev of source) {
+      for (let i = 0; i < consumers; i++) {
+        const resolve = resolvers[i];
+        if (resolve) {
+          resolvers[i] = null;
+          resolve({ value: ev, done: false });
+        } else {
+          queues[i]!.push(ev);
+        }
+      }
+    }
+    done = true;
+    for (let i = 0; i < consumers; i++) {
+      const resolve = resolvers[i];
+      if (resolve) {
+        resolvers[i] = null;
+        resolve({ value: undefined as unknown as StreamEvent, done: true });
+      }
+    }
+  })();
+
+  return Array.from({ length: consumers }, (_, i) => {
+    return (async function* (): AsyncGenerator<StreamEvent> {
+      while (true) {
+        const queued = queues[i]!.shift();
+        if (queued !== undefined) {
+          yield queued;
+          continue;
+        }
+        if (done) return;
+        const ev = await new Promise<IteratorResult<StreamEvent>>((resolve) => {
+          resolvers[i] = resolve;
+        });
+        if (ev.done) return;
+        yield ev.value;
+      }
+    })();
+  });
+}

package/src/system-prompt.ts

@@ -0,0 +1,71 @@
+import type { Tokenizer } from "./tokenizer.js";
+import { truncateToTokens } from "./tokenizer.js";
+
+export type SystemPromptLayer =
+  | "core"
+  | "behavior"
+  | "memory"
+  | "session"
+  | "mode";
+
+const LAYER_ORDER: SystemPromptLayer[] = [
+  "core",
+  "behavior",
+  "memory",
+  "session",
+  "mode",
+];
+
+export class SystemPromptBuilder {
+  private layers = new Map<SystemPromptLayer, string>();
+  private maxLayerTokens = new Map<SystemPromptLayer, number>();
+
+  setMaxLayerTokens(layer: SystemPromptLayer, maxTokens: number): void {
+    this.maxLayerTokens.set(layer, maxTokens);
+  }
+
+  build(): string {
+    return this.buildWithBudget();
+  }
+
+  buildWithBudget(tok?: Tokenizer): string {
+    const parts: string[] = [];
+    for (const layer of LAYER_ORDER) {
+      let content = (this.layers.get(layer) ?? "").trim();
+      if (!content) continue;
+      if (tok) {
+        const cap = this.maxLayerTokens.get(layer);
+        if (cap && cap > 0 && tok.count(content) > cap) {
+          content = truncateToTokens(content, cap, tok);
+        }
+      }
+      parts.push(content);
+    }
+    return parts.join("\n\n");
+  }
+
+  get(layer: SystemPromptLayer): string {
+    return this.layers.get(layer) ?? "";
+  }
+
+  has(layer: SystemPromptLayer): boolean {
+    return (this.layers.get(layer) ?? "").trim().length > 0;
+  }
+
+  set(layer: SystemPromptLayer, content: string): void {
+    this.layers.set(layer, content.trim());
+  }
+
+  append(layer: SystemPromptLayer, content: string): void {
+    const existing = this.layers.get(layer) ?? "";
+    if (!existing) {
+      this.layers.set(layer, content.trim());
+    } else {
+      this.layers.set(layer, existing + "\n\n" + content.trim());
+    }
+  }
+
+  clear(layer: SystemPromptLayer): void {
+    this.layers.delete(layer);
+  }
+}

package/src/system-reminder.ts

@@ -0,0 +1,9 @@
+export function systemReminder(content: string): string {
+  const trimmed = content.trim();
+  if (!trimmed) return "";
+  return `<system-reminder>\n${trimmed}\n</system-reminder>`;
+}
+
+export function joinSystemReminders(...reminders: string[]): string {
+  return reminders.filter(Boolean).join("\n\n");
+}

package/src/thread.ts

@@ -0,0 +1,33 @@
+export type ThreadStatus = "active" | "completed" | "failed" | "archived";
+
+export interface Thread {
+  id: string;
+  userId?: string;
+  projectId?: string;
+  modeId?: string;
+  status: ThreadStatus;
+  parentId?: string;
+}
+
+export interface Message {
+  id?: string;
+  fromThreadId: string;
+  toThreadId: string;
+  content: string;
+  sentAt?: Date;
+}
+
+export 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>;
+}
+
+export 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[]>;
+}
+
+export const ErrThreadAccessDenied = new Error("thread: access denied");

package/src/tokenizer.ts

@@ -0,0 +1,31 @@
+export interface Tokenizer {
+  count(text: string): number;
+  encode(text: string): number[];
+  decode(tokens: number[]): string;
+}
+
+export class HeuristicTokenizer implements Tokenizer {
+  count(text: string): number {
+    return Math.ceil(text.length / 4);
+  }
+  encode(_text: string): number[] {
+    return [];
+  }
+  decode(_tokens: number[]): string {
+    return "";
+  }
+}
+
+export function truncateToTokens(
+  text: string,
+  maxTokens: number,
+  tok: Tokenizer,
+): string {
+  if (tok.count(text) <= maxTokens) return text;
+  const tokens = tok.encode(text);
+  if (tokens.length > 0 && tokens.length > maxTokens) {
+    return tok.decode(tokens.slice(0, maxTokens));
+  }
+  const limit = Math.min(maxTokens * 4, text.length);
+  return text.slice(0, limit);
+}

package/src/tool.ts

@@ -0,0 +1,175 @@
+import type { ToolDef, ToolFuncParams } from "./llm.js";
+
+export type ToolCategory =
+  | "workspace"
+  | "compute"
+  | "data"
+  | "web"
+  | "planning"
+  | "communication"
+  | "integrations"
+  | "memory"
+  | "custom";
+
+export type ToolExecuteFunc = (
+  ctx: AbortSignal | undefined,
+  sandboxId: string,
+  args: Record<string, unknown>,
+) => Promise<string>;
+
+export type ToolPredicate = (args: Record<string, unknown>) => boolean;
+
+export type ToolValidator = (
+  ctx: AbortSignal | undefined,
+  args: Record<string, unknown>,
+) => Promise<void>;
+
+export type PermissionDecision = "allow" | "deny" | "ask_user";
+
+export interface PermissionResult {
+  decision: PermissionDecision;
+  reason?: string;
+  updatedArgs?: Record<string, unknown>;
+}
+
+export type ToolPermissionFn = (
+  ctx: AbortSignal | undefined,
+  args: Record<string, unknown>,
+) => Promise<PermissionResult>;
+
+export type ToolReminderFn = (
+  ctx: AbortSignal | undefined,
+) => Promise<string>;
+
+export 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;
+}
+
+export interface ToolMatch {
+  tool: Tool;
+  score: number;
+}
+
+function toToolDef(t: Tool): ToolDef {
+  return {
+    type: "function",
+    function: {
+      name: t.name,
+      description: t.description,
+      parameters: t.parameters,
+    },
+  };
+}
+
+function scoreToolMatch(t: Tool, query: string): number {
+  let score = 0;
+  if (t.name.toLowerCase().includes(query)) score += 0.6;
+  if (t.searchHint?.toLowerCase().includes(query)) score += 0.4;
+  if (t.description.toLowerCase().includes(query)) score += 0.3;
+  if (t.category.toLowerCase().includes(query)) score += 0.1;
+  if (t.aliases?.some((a) => a.toLowerCase().includes(query))) score += 0.2;
+  return score;
+}
+
+export class ToolRegistry {
+  private tools = new Map<string, Tool>();
+  private aliases = new Map<string, string>();
+
+  register(tool: Tool): void {
+    this.tools.set(tool.name, tool);
+    for (const alias of tool.aliases ?? []) {
+      const trimmed = alias.trim();
+      if (trimmed && trimmed !== tool.name) {
+        this.aliases.set(trimmed, tool.name);
+      }
+    }
+  }
+
+  get(name: string): Tool | undefined {
+    return this.tools.get(name) ?? this.tools.get(this.aliases.get(name) ?? "");
+  }
+
+  list(): Tool[] {
+    return Array.from(this.tools.values());
+  }
+
+  byCategory(category: ToolCategory): Tool[] {
+    return this.list().filter((t) => t.category === category);
+  }
+
+  names(): string[] {
+    return Array.from(this.tools.keys()).sort();
+  }
+
+  describeAvailable(): string {
+    const tools = this.list().sort((a, b) => a.name.localeCompare(b.name));
+    if (tools.length === 0) return "- none";
+    const lines = tools
+      .filter((t) => t.name.trim())
+      .map((t) => {
+        const desc = t.description.trim();
+        return desc ? `- ${t.name}: ${desc}` : `- ${t.name}`;
+      });
+    return lines.length === 0 ? "- none" : lines.join("\n");
+  }
+
+  toolDefs(): ToolDef[] {
+    return this.list()
+      .filter((t) => !t.hidden && !t.deferred)
+      .map(toToolDef);
+  }
+
+  async collectDynamicReminders(
+    signal?: AbortSignal,
+  ): Promise<string[]> {
+    const tools = this.list()
+      .filter((t) => t.dynamicReminder != null)
+      .sort((a, b) => a.name.localeCompare(b.name));
+
+    const results: string[] = [];
+    for (const t of tools) {
+      const block = await t.dynamicReminder!(signal);
+      if (block.trim()) results.push(block);
+    }
+    return results;
+  }
+
+  search(query: string): ToolMatch[] {
+    const q = query.toLowerCase().trim();
+    if (!q) return [];
+    return this.list()
+      .map((t) => ({ tool: t, score: scoreToolMatch(t, q) }))
+      .filter((m) => m.score > 0)
+      .sort((a, b) => b.score - a.score);
+  }
+
+  reveal(name: string): void {
+    const tool = this.tools.get(name);
+    if (!tool) throw new Error(`tool "${name}" not found`);
+    tool.hidden = false;
+  }
+
+  hide(name: string): void {
+    const tool = this.tools.get(name);
+    if (!tool) throw new Error(`tool "${name}" not found`);
+    tool.hidden = true;
+  }
+}
+
+export { toToolDef };

package/src/tracing.ts

@@ -0,0 +1,63 @@
+import { randomUUID } from "node:crypto";
+
+export interface Span {
+  traceId: string;
+  spanId: string;
+  parentId?: string;
+  name: string;
+  startedAt: Date;
+  finishedAt?: Date;
+  attrs?: Record<string, unknown>;
+  error?: string;
+}
+
+export class Tracer {
+  private readonly _traceId: string;
+  private spans: Span[] = [];
+  private stack: string[] = [];
+
+  constructor() {
+    this._traceId = randomUUID();
+  }
+
+  traceId(): string {
+    return this._traceId;
+  }
+
+  startSpan(name: string, attrs?: Record<string, unknown>): Span {
+    const span: Span = {
+      traceId: this._traceId,
+      spanId: randomUUID(),
+      parentId: this.stack[this.stack.length - 1],
+      name,
+      startedAt: new Date(),
+      attrs,
+    };
+    this.spans.push(span);
+    this.stack.push(span.spanId);
+    return span;
+  }
+
+  finishSpan(span: Span, error?: Error): void {
+    span.finishedAt = new Date();
+    if (error) span.error = error.message;
+    const idx = this.stack.lastIndexOf(span.spanId);
+    if (idx !== -1) this.stack.splice(idx, 1);
+  }
+
+  allSpans(): Span[] {
+    return this.spans.slice();
+  }
+}
+
+export interface TracedContext {
+  __tracer?: Tracer;
+}
+
+export function withTracer<T extends TracedContext>(ctx: T, tracer: Tracer): T {
+  return { ...ctx, __tracer: tracer };
+}
+
+export function tracerFromContext(ctx: TracedContext): Tracer | undefined {
+  return ctx.__tracer;
+}