klaus-agent 0.1.0 → 0.1.1

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "klaus-agent",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Universal agent framework",
   "type": "module",
+  "files": ["dist", "README.md"],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {

package/src/approval/approval.ts

@@ -1,108 +0,0 @@
-// Queue-based approval system
-
-import { generateId } from "../utils/id.js";
-import type { Approval, ApprovalConfig, ApprovalRequest, ApprovalResponse } from "./types.js";
-
-interface PendingRequest {
-  request: ApprovalRequest;
-  resolve: (approved: boolean) => void;
-}
-
-export class ApprovalImpl implements Approval {
-  private _yolo: boolean;
-  private _autoApproveActions: Set<string>;
-  private _pending = new Map<string, PendingRequest>();
-  private _queue: ApprovalRequest[] = [];
-  private _waiters: ((req: ApprovalRequest) => void)[] = [];
-
-  constructor(config?: ApprovalConfig) {
-    this._yolo = config?.yolo ?? false;
-    this._autoApproveActions = new Set(config?.autoApproveActions ?? []);
-  }
-
-  async request(sender: string, action: string, description: string, toolCallId: string): Promise<boolean> {
-    if (this._yolo) return true;
-    if (this._autoApproveActions.has(action)) return true;
-
-    const req: ApprovalRequest = {
-      id: generateId(),
-      toolCallId,
-      sender,
-      action,
-      description,
-    };
-
-    return new Promise<boolean>((resolve) => {
-      this._pending.set(req.id, { request: req, resolve });
-
-      // Deliver to waiter or queue
-      const waiter = this._waiters.shift();
-      if (waiter) {
-        waiter(req);
-      } else {
-        this._queue.push(req);
-      }
-    });
-  }
-
-  async fetchRequest(): Promise<ApprovalRequest> {
-    const queued = this._queue.shift();
-    if (queued) return queued;
-
-    return new Promise<ApprovalRequest>((resolve, reject) => {
-      const waiter = (req: ApprovalRequest) => resolve(req);
-      (waiter as any)._reject = reject;
-      this._waiters.push(waiter);
-    });
-  }
-
-  /** Cancel all pending waiters (e.g., on agent dispose) */
-  cancelPendingWaiters(): void {
-    for (const waiter of this._waiters) {
-      const reject = (waiter as any)._reject;
-      if (reject) reject(new Error("Approval cancelled"));
-    }
-    this._waiters = [];
-  }
-
-  resolve(requestId: string, response: ApprovalResponse): void {
-    const pending = this._pending.get(requestId);
-    if (!pending) return;
-
-    this._pending.delete(requestId);
-
-    if (response === "approve_for_session") {
-      this._autoApproveActions.add(pending.request.action);
-      pending.resolve(true);
-    } else {
-      pending.resolve(response === "approve");
-    }
-  }
-
-  setYolo(yolo: boolean): void {
-    this._yolo = yolo;
-  }
-
-  isYolo(): boolean {
-    return this._yolo;
-  }
-
-  get autoApproveActions(): Set<string> {
-    return this._autoApproveActions;
-  }
-
-  share(): Approval {
-    // Shared state (yolo, autoApproveActions), independent queue
-    // Use a shared state object so changes propagate bidirectionally
-    const shared = new ApprovalImpl();
-    shared._autoApproveActions = this._autoApproveActions; // same reference
-    // Share yolo via getter/setter delegation
-    const parent = this;
-    Object.defineProperty(shared, '_yolo', {
-      get() { return parent._yolo; },
-      set(v: boolean) { parent._yolo = v; },
-      configurable: true,
-    });
-    return shared;
-  }
-}

package/src/approval/types.ts

@@ -1,26 +0,0 @@
-// Approval system types
-
-export type ApprovalResponse = "approve" | "approve_for_session" | "reject";
-
-export interface ApprovalRequest {
-  id: string;
-  toolCallId: string;
-  sender: string;
-  action: string;
-  description: string;
-}
-
-export interface ApprovalConfig {
-  yolo?: boolean;
-  autoApproveActions?: string[];
-}
-
-export interface Approval {
-  request(sender: string, action: string, description: string, toolCallId: string): Promise<boolean>;
-  fetchRequest(): Promise<ApprovalRequest>;
-  resolve(requestId: string, response: ApprovalResponse): void;
-  setYolo(yolo: boolean): void;
-  isYolo(): boolean;
-  readonly autoApproveActions: Set<string>;
-  share(): Approval;
-}

package/src/background/task-manager.ts

@@ -1,112 +0,0 @@
-// Background task manager — in-process async task execution
-
-import { generateId } from "../utils/id.js";
-import type { BackgroundTaskStatus, BackgroundTaskInfo, BackgroundTaskHandle, BackgroundTaskEvent } from "./types.js";
-
-interface InternalTask {
-  id: string;
-  name: string;
-  status: BackgroundTaskStatus;
-  createdAt: number;
-  startedAt?: number;
-  completedAt?: number;
-  result?: unknown;
-  error?: Error;
-  abortController: AbortController;
-}
-
-export class BackgroundTaskManager {
-  private _tasks = new Map<string, InternalTask>();
-  private _onEvent?: (event: BackgroundTaskEvent) => void;
-
-  constructor(onEvent?: (event: BackgroundTaskEvent) => void) {
-    this._onEvent = onEvent;
-  }
-
-  spawn<T>(name: string, fn: (signal: AbortSignal) => Promise<T>): BackgroundTaskHandle<T> {
-    const id = generateId();
-    const abortController = new AbortController();
-    const now = Date.now();
-
-    const task: InternalTask = {
-      id,
-      name,
-      status: "running",
-      createdAt: now,
-      startedAt: now,
-      abortController,
-    };
-
-    this._tasks.set(id, task);
-    this._onEvent?.({ type: "task_started", task: this._toInfo(task) });
-
-    fn(abortController.signal).then(
-      (result) => {
-        task.status = "completed";
-        task.completedAt = Date.now();
-        task.result = result;
-        try { this._onEvent?.({ type: "task_completed", task: this._toInfo(task), result }); } catch {}
-      },
-      (err) => {
-        task.status = "failed";
-        task.completedAt = Date.now();
-        task.error = err instanceof Error ? err : new Error(String(err));
-        try { this._onEvent?.({ type: "task_failed", task: this._toInfo(task), error: task.error.message }); } catch {}
-      },
-    );
-
-    return this._toHandle<T>(task);
-  }
-
-  get(id: string): BackgroundTaskHandle | undefined {
-    const task = this._tasks.get(id);
-    return task ? this._toHandle(task) : undefined;
-  }
-
-  list(): BackgroundTaskInfo[] {
-    return [...this._tasks.values()].map((t) => this._toInfo(t));
-  }
-
-  abort(id: string): boolean {
-    const task = this._tasks.get(id);
-    if (!task || task.status !== "running") return false;
-    task.abortController.abort();
-    return true;
-  }
-
-  abortAll(): void {
-    for (const task of this._tasks.values()) {
-      if (task.status === "running") {
-        task.abortController.abort();
-      }
-    }
-  }
-
-  dispose(): void {
-    this.abortAll();
-    this._tasks.clear();
-  }
-
-  private _toInfo(task: InternalTask): BackgroundTaskInfo {
-    return {
-      id: task.id,
-      name: task.name,
-      status: task.status,
-      createdAt: task.createdAt,
-      startedAt: task.startedAt,
-      completedAt: task.completedAt,
-      error: task.error?.message,
-    };
-  }
-
-  private _toHandle<T>(task: InternalTask): BackgroundTaskHandle<T> {
-    return {
-      get id() { return task.id; },
-      get name() { return task.name; },
-      get status() { return task.status; },
-      get result() { return task.result as T | undefined; },
-      get error() { return task.error; },
-      abort: () => task.abortController.abort(),
-    };
-  }
-}

package/src/background/tools.ts

@@ -1,84 +0,0 @@
-// Built-in background task tools — allows LLM to manage background tasks
-
-import { Type } from "@sinclair/typebox";
-import type { AgentTool, AgentToolResult, ToolExecutionContext } from "../tools/types.js";
-import type { BackgroundTaskManager } from "./task-manager.js";
-import type { TaskFactory } from "./types.js";
-
-export function createBackgroundTaskTools(
-  manager: BackgroundTaskManager,
-  factories?: Record<string, TaskFactory>,
-): AgentTool[] {
-  const tools: AgentTool[] = [
-    {
-      name: "check_task_status",
-      label: "Check Task Status",
-      description: "Check the status of background tasks. If no task_id is provided, returns all tasks.",
-      parameters: Type.Object({
-        task_id: Type.Optional(Type.String({ description: "Task ID to check. Omit to list all tasks." })),
-      }),
-      async execute(_toolCallId: string, params: { task_id?: string }): Promise<AgentToolResult> {
-        if (params.task_id) {
-          const handle = manager.get(params.task_id);
-          if (!handle) {
-            return { content: [{ type: "text", text: `No task found with ID: ${params.task_id}` }] };
-          }
-          return { content: [{ type: "text", text: JSON.stringify({ id: handle.id, name: handle.name, status: handle.status }, null, 2) }] };
-        }
-        const tasks = manager.list();
-        if (tasks.length === 0) {
-          return { content: [{ type: "text", text: "No background tasks." }] };
-        }
-        return { content: [{ type: "text", text: JSON.stringify(tasks, null, 2) }] };
-      },
-    },
-    {
-      name: "get_task_result",
-      label: "Get Task Result",
-      description: "Get the result of a completed background task.",
-      parameters: Type.Object({
-        task_id: Type.String({ description: "Task ID to get the result for." }),
-      }),
-      async execute(_toolCallId: string, params: { task_id: string }): Promise<AgentToolResult> {
-        const handle = manager.get(params.task_id);
-        if (!handle) {
-          return { content: [{ type: "text", text: `No task found with ID: ${params.task_id}` }] };
-        }
-        if (handle.status === "running") {
-          return { content: [{ type: "text", text: `Task "${handle.name}" is still running.` }] };
-        }
-        if (handle.status === "failed") {
-          return { content: [{ type: "text", text: `Task "${handle.name}" failed: ${handle.error?.message ?? "unknown error"}` }] };
-        }
-        const resultText = handle.result !== undefined ? JSON.stringify(handle.result, null, 2) : "(no result)";
-        return { content: [{ type: "text", text: resultText }] };
-      },
-    },
-  ];
-
-  if (factories && Object.keys(factories).length > 0) {
-    const names = Object.keys(factories);
-    const description = `Start a background task. Available tasks:\n${names.map((n) => `- ${n}`).join("\n")}`;
-
-    tools.push({
-      name: "start_background_task",
-      label: "Start Background Task",
-      description,
-      parameters: Type.Object({
-        task_name: Type.String({ description: "Name of the task to start." }),
-        args: Type.Optional(Type.Unknown({ description: "Arguments to pass to the task." })),
-      }),
-      async execute(_toolCallId: string, params: { task_name: string; args?: unknown }): Promise<AgentToolResult> {
-        const factory = factories[params.task_name];
-        if (!factory) {
-          const available = Object.keys(factories).join(", ");
-          return { content: [{ type: "text", text: `Unknown task: "${params.task_name}". Available: ${available}` }] };
-        }
-        const handle = manager.spawn(params.task_name, (signal) => factory(params.args, signal));
-        return { content: [{ type: "text", text: `Task started: ${handle.name} (ID: ${handle.id})` }] };
-      },
-    });
-  }
-
-  return tools;
-}

package/src/background/types.ts

@@ -1,29 +0,0 @@
-// Background task types
-
-export type BackgroundTaskStatus = "pending" | "running" | "completed" | "failed";
-
-export interface BackgroundTaskInfo {
-  id: string;
-  name: string;
-  status: BackgroundTaskStatus;
-  createdAt: number;
-  startedAt?: number;
-  completedAt?: number;
-  error?: string;
-}
-
-export interface BackgroundTaskHandle<T = unknown> {
-  readonly id: string;
-  readonly name: string;
-  readonly status: BackgroundTaskStatus;
-  readonly result?: T;
-  readonly error?: Error;
-  abort(): void;
-}
-
-export type BackgroundTaskEvent =
-  | { type: "task_started"; task: BackgroundTaskInfo }
-  | { type: "task_completed"; task: BackgroundTaskInfo; result: unknown }
-  | { type: "task_failed"; task: BackgroundTaskInfo; error: string };
-
-export type TaskFactory = (args: unknown, signal: AbortSignal) => Promise<unknown>;

package/src/checkpoint/checkpoint-manager.ts

@@ -1,60 +0,0 @@
-// Checkpoint manager — creates checkpoints in session tree, handles D-Mail revert
-
-import type { SessionManager } from "../session/session-manager.js";
-import type { CheckpointInfo } from "./types.js";
-import { DenwaRenji } from "./dmail.js";
-
-export class CheckpointManager {
-  private _checkpoints: CheckpointInfo[] = [];
-  private _nextId = 0; // Global counter, never resets after D-Mail
-  private _denwaRenji = new DenwaRenji();
-
-  constructor(private _session: SessionManager) {}
-
-  get denwaRenji(): DenwaRenji {
-    return this._denwaRenji;
-  }
-
-  async checkpoint(): Promise<CheckpointInfo> {
-    const checkpointId = this._nextId++;
-    const entryId = await this._session.appendCheckpoint(checkpointId);
-
-    const info: CheckpointInfo = { checkpointId, entryId };
-    this._checkpoints.push(info);
-    this._denwaRenji.setCheckpointCount(this._checkpoints.length);
-
-    return info;
-  }
-
-  getCheckpoint(checkpointId: number): CheckpointInfo | undefined {
-    return this._checkpoints.find((cp) => cp.checkpointId === checkpointId);
-  }
-
-  getAllCheckpoints(): CheckpointInfo[] {
-    return [...this._checkpoints];
-  }
-
-  /**
-   * Handle D-Mail: branch from the target checkpoint and inject the message.
-   * Returns the D-Mail content if one was pending, null otherwise.
-   */
-  async handleDMail(): Promise<string | null> {
-    const dmail = this._denwaRenji.fetchPendingDMail();
-    if (!dmail) return null;
-
-    const checkpoint = this._checkpoints.find((cp) => cp.checkpointId === dmail.checkpointId);
-    if (!checkpoint) {
-      throw new Error(`Checkpoint ${dmail.checkpointId} not found`);
-    }
-
-    // Branch session tree back to checkpoint entry
-    this._session.branch(checkpoint.entryId);
-
-    // Remove checkpoints after the target (keep target itself)
-    const targetIdx = this._checkpoints.indexOf(checkpoint);
-    this._checkpoints.length = targetIdx + 1;
-    this._denwaRenji.setCheckpointCount(this._checkpoints.length);
-
-    return dmail.message;
-  }
-}

package/src/checkpoint/dmail.ts

@@ -1,35 +0,0 @@
-// DenwaRenji — D-Mail state machine
-
-import type { DMail } from "./types.js";
-
-export class DenwaRenji {
-  private _pendingDMail: DMail | null = null;
-  private _checkpointCount = 0;
-
-  sendDMail(message: string, checkpointId: number): void {
-    if (checkpointId < 0 || checkpointId >= this._checkpointCount) {
-      throw new Error(
-        `Invalid checkpoint ID ${checkpointId}. Valid range: 0-${this._checkpointCount - 1}`,
-      );
-    }
-    this._pendingDMail = { message, checkpointId };
-  }
-
-  setCheckpointCount(n: number): void {
-    this._checkpointCount = n;
-  }
-
-  getCheckpointCount(): number {
-    return this._checkpointCount;
-  }
-
-  fetchPendingDMail(): DMail | null {
-    const dmail = this._pendingDMail;
-    this._pendingDMail = null;
-    return dmail;
-  }
-
-  hasPendingDMail(): boolean {
-    return this._pendingDMail !== null;
-  }
-}

package/src/checkpoint/types.ts

@@ -1,16 +0,0 @@
-// Checkpoint and D-Mail types
-
-export interface CheckpointConfig {
-  enabled?: boolean;
-  enableDMail?: boolean;
-}
-
-export interface DMail {
-  message: string;
-  checkpointId: number;
-}
-
-export interface CheckpointInfo {
-  checkpointId: number;
-  entryId: string;
-}

package/src/compaction/compaction.ts

@@ -1,119 +0,0 @@
-// Compaction logic — token estimation, cut point detection, shouldCompact
-
-import type { AgentMessage, Message } from "../types.js";
-import type { CutPointResult } from "./types.js";
-
-const CHARS_PER_TOKEN = 4;
-
-export function estimateTokens(messages: AgentMessage[]): number {
-  let total = 0;
-  for (const msg of messages) {
-    total += estimateMessageTokens(msg);
-  }
-  return total;
-}
-
-function estimateMessageTokens(msg: AgentMessage): number {
-  if (!msg || typeof msg !== "object" || !("role" in msg)) return 0;
-  const m = msg as Message;
-
-  if (m.role === "user") {
-    if (typeof m.content === "string") return Math.ceil(m.content.length / CHARS_PER_TOKEN);
-    return m.content.reduce((sum, block) => {
-      if (block.type === "text") return sum + Math.ceil(block.text.length / CHARS_PER_TOKEN);
-      return sum + 1000; // image estimate
-    }, 0);
-  }
-
-  if (m.role === "assistant") {
-    return m.content.reduce((sum, block) => {
-      if (block.type === "text") return sum + Math.ceil(block.text.length / CHARS_PER_TOKEN);
-      if (block.type === "thinking") return sum + Math.ceil(block.thinking.length / CHARS_PER_TOKEN);
-      if (block.type === "tool_call") return sum + Math.ceil(JSON.stringify(block.input).length / CHARS_PER_TOKEN) + 20;
-      return sum;
-    }, 0);
-  }
-
-  if (m.role === "tool_result") {
-    if (typeof m.content === "string") return Math.ceil(m.content.length / CHARS_PER_TOKEN);
-    return m.content.reduce((sum, block) => {
-      if (block.type === "text") return sum + Math.ceil(block.text.length / CHARS_PER_TOKEN);
-      return sum + 1000;
-    }, 0);
-  }
-
-  return 0;
-}
-
-export function shouldCompact(
-  contextTokens: number,
-  maxContextTokens: number,
-  reserveTokens: number,
-): boolean {
-  return contextTokens > maxContextTokens - reserveTokens;
-}
-
-export function findCutPoint(
-  messages: AgentMessage[],
-  keepRecentTokens: number,
-): CutPointResult {
-  if (messages.length === 0) {
-    return { firstKeptIndex: 0, isSplitTurn: false };
-  }
-
-  // Walk backwards, accumulating tokens until we reach keepRecentTokens
-  let accumulated = 0;
-  let cutIndex = messages.length;
-
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const tokens = estimateMessageTokens(messages[i]);
-    accumulated += tokens;
-
-    if (accumulated >= keepRecentTokens) {
-      cutIndex = i + 1;
-      break;
-    }
-  }
-
-  // Ensure we don't cut at a tool_result (must follow its tool_call)
-  while (cutIndex < messages.length) {
-    const msg = messages[cutIndex];
-    if (msg && typeof msg === "object" && "role" in msg && (msg as Message).role === "tool_result") {
-      cutIndex++;
-    } else {
-      break;
-    }
-  }
-
-  // Don't cut if nothing to discard
-  if (cutIndex <= 1) {
-    return { firstKeptIndex: 0, isSplitTurn: false };
-  }
-
-  const isSplitTurn = cutIndex > 0 && cutIndex < messages.length &&
-    messages[cutIndex - 1] && typeof messages[cutIndex - 1] === "object" &&
-    "role" in messages[cutIndex - 1]! && (messages[cutIndex - 1] as Message).role === "assistant";
-
-  return { firstKeptIndex: cutIndex, isSplitTurn };
-}
-
-export function messagesToText(messages: AgentMessage[]): string {
-  const parts: string[] = [];
-  for (const msg of messages) {
-    if (!msg || typeof msg !== "object" || !("role" in msg)) continue;
-    const m = msg as Message;
-
-    if (m.role === "user") {
-      const text = typeof m.content === "string" ? m.content : m.content.filter((b) => b.type === "text").map((b) => (b as { text: string }).text).join("\n");
-      parts.push(`User: ${text}`);
-    } else if (m.role === "assistant") {
-      const text = m.content.filter((b) => b.type === "text").map((b) => (b as { text: string }).text).join("\n");
-      const toolCalls = m.content.filter((b) => b.type === "tool_call").map((b) => (b as { name: string }).name);
-      parts.push(`Assistant: ${text}${toolCalls.length ? ` [tools: ${toolCalls.join(", ")}]` : ""}`);
-    } else if (m.role === "tool_result") {
-      const text = typeof m.content === "string" ? m.content : m.content.filter((b) => b.type === "text").map((b) => (b as { text: string }).text).join("\n");
-      parts.push(`Tool result: ${text.slice(0, 500)}`);
-    }
-  }
-  return parts.join("\n");
-}

package/src/compaction/summarizer.ts

@@ -1,83 +0,0 @@
-// LLM-based summarization for compaction
-
-import type { LLMProvider, LLMRequestOptions, AssistantMessage } from "../llm/types.js";
-import type { AgentMessage } from "../types.js";
-import type { CompactionSummarizer, CompactionInput } from "./types.js";
-import { messagesToText } from "./compaction.js";
-
-const SUMMARIZE_PROMPT = `You are a conversation summarizer. Summarize the following conversation history concisely, preserving:
-- Key decisions and outcomes
-- Important context and facts established
-- Current state of any ongoing tasks
-- Tool calls made and their results (briefly)
-
-Be concise but thorough. Use bullet points. Do not include greetings or filler.`;
-
-const UPDATE_PROMPT = `You are a conversation summarizer. You have a previous summary and new conversation to incorporate.
-
-Previous summary:
-{previous_summary}
-
-Merge the new conversation into the summary, preserving all important context. Remove outdated information that has been superseded.`;
-
-export class LLMSummarizer implements CompactionSummarizer {
-  constructor(
-    private provider: LLMProvider,
-    private modelId: string,
-  ) {}
-
-  async summarize(messages: CompactionInput[], previousSummary?: string): Promise<string> {
-    const conversationText = messages.map((m) => `${m.role}: ${m.content}`).join("\n");
-
-    const systemPrompt = previousSummary
-      ? UPDATE_PROMPT.replace("{previous_summary}", previousSummary)
-      : SUMMARIZE_PROMPT;
-
-    const options: LLMRequestOptions = {
-      model: this.modelId,
-      systemPrompt,
-      messages: [{ role: "user", content: `Summarize this conversation:\n\n${conversationText}` }],
-      maxTokens: 2048,
-    };
-
-    let result = "";
-    for await (const event of this.provider.stream(options)) {
-      if (event.type === "text") {
-        result += event.text;
-      } else if (event.type === "done") {
-        const textBlocks = event.message.content.filter((b) => b.type === "text");
-        if (textBlocks.length > 0) {
-          result = textBlocks.map((b) => (b as { text: string }).text).join("");
-        }
-      }
-    }
-
-    return result;
-  }
-}
-
-export function agentMessagesToCompactionInput(messages: AgentMessage[]): CompactionInput[] {
-  const results: CompactionInput[] = [];
-  for (const msg of messages) {
-    if (!msg || typeof msg !== "object" || !("role" in msg)) continue;
-    const m = msg as any;
-
-    if (m.role === "user") {
-      const text = typeof m.content === "string"
-        ? m.content
-        : (m.content ?? []).filter((b: any) => b.type === "text").map((b: any) => b.text).join("\n");
-      results.push({ role: "user", content: text });
-    } else if (m.role === "assistant") {
-      const text = (m.content ?? []).filter((b: any) => b.type === "text").map((b: any) => b.text).join("\n");
-      const toolCalls = (m.content ?? []).filter((b: any) => b.type === "tool_call").map((b: any) => b.name);
-      const suffix = toolCalls.length ? ` [tools: ${toolCalls.join(", ")}]` : "";
-      results.push({ role: "assistant", content: text + suffix });
-    } else if (m.role === "tool_result") {
-      const text = typeof m.content === "string"
-        ? m.content
-        : (m.content ?? []).filter((b: any) => b.type === "text").map((b: any) => b.text).join("\n");
-      results.push({ role: "tool_result", content: text.slice(0, 500) });
-    }
-  }
-  return results;
-}