klaus-agent 0.1.0

package/dist/wire/types.js

@@ -0,0 +1,3 @@
+// Wire — typed async event channel types
+export {};
+//# sourceMappingURL=types.js.map

package/dist/wire/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/wire/types.ts"],"names":[],"mappings":"AAAA,yCAAyC"}

package/dist/wire/wire.d.ts

@@ -0,0 +1,20 @@
+import type { WireMessage, WireSubscriber, WireSubscription } from "./types.js";
+export interface WireOptions {
+    /** Max messages to buffer for replay to late subscribers. 0 = no buffering. */
+    bufferSize?: number;
+}
+export declare class Wire {
+    private _subscribers;
+    private _buffer;
+    private _bufferSize;
+    constructor(options?: WireOptions);
+    publish<T>(type: string, payload: T): WireMessage<T>;
+    subscribe(fn: WireSubscriber, options?: {
+        replay?: boolean;
+    }): WireSubscription;
+    on<T>(type: string, fn: (message: WireMessage<T>) => void, options?: {
+        replay?: boolean;
+    }): WireSubscription;
+    getBuffer(): readonly WireMessage[];
+    dispose(): void;
+}

package/dist/wire/wire.js

@@ -0,0 +1,71 @@
+// Wire — typed async event channel with optional replay buffer
+import { generateId } from "../utils/id.js";
+export class Wire {
+    _subscribers = new Set();
+    _buffer = [];
+    _bufferSize;
+    constructor(options) {
+        this._bufferSize = options?.bufferSize ?? 0;
+    }
+    publish(type, payload) {
+        const message = {
+            id: generateId(),
+            timestamp: Date.now(),
+            type,
+            payload,
+        };
+        if (this._bufferSize > 0) {
+            this._buffer.push(message);
+            if (this._buffer.length > this._bufferSize) {
+                this._buffer.shift();
+            }
+        }
+        for (const fn of this._subscribers) {
+            try {
+                fn(message);
+            }
+            catch {
+                // Subscriber errors should not break the publisher
+            }
+        }
+        return message;
+    }
+    subscribe(fn, options) {
+        if (options?.replay) {
+            for (const msg of this._buffer) {
+                try {
+                    fn(msg);
+                }
+                catch { }
+            }
+        }
+        this._subscribers.add(fn);
+        return { unsubscribe: () => this._subscribers.delete(fn) };
+    }
+    on(type, fn, options) {
+        const filtered = (msg) => {
+            if (msg.type === type)
+                fn(msg);
+        };
+        if (options?.replay) {
+            for (const msg of this._buffer) {
+                if (msg.type === type) {
+                    try {
+                        fn(msg);
+                    }
+                    catch { }
+                }
+            }
+        }
+        this._subscribers.add(filtered);
+        return { unsubscribe: () => this._subscribers.delete(filtered) };
+    }
+    getBuffer() {
+        return this._buffer;
+    }
+    dispose() {
+        this._subscribers.clear();
+        this._buffer = [];
+    }
+}
+//# sourceMappingURL=wire.js.map

package/dist/wire/wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.js","sourceRoot":"","sources":["../../src/wire/wire.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAE/D,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAQ5C,MAAM,OAAO,IAAI;IACP,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,OAAO,GAAkB,EAAE,CAAC;IAC5B,WAAW,CAAS;IAE5B,YAAY,OAAqB;QAC/B,IAAI,CAAC,WAAW,GAAG,OAAO,EAAE,UAAU,IAAI,CAAC,CAAC;IAC9C,CAAC;IAED,OAAO,CAAI,IAAY,EAAE,OAAU;QACjC,MAAM,OAAO,GAAmB;YAC9B,EAAE,EAAE,UAAU,EAAE;YAChB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,IAAI;YACJ,OAAO;SACR,CAAC;QAEF,IAAI,IAAI,CAAC,WAAW,GAAG,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC3B,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;gBAC3C,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACvB,CAAC;QACH,CAAC;QAED,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACnC,IAAI,CAAC;gBACH,EAAE,CAAC,OAAO,CAAC,CAAC;YACd,CAAC;YAAC,MAAM,CAAC;gBACP,mDAAmD;YACrD,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,SAAS,CAAC,EAAkB,EAAE,OAA8B;QAC1D,IAAI,OAAO,EAAE,MAAM,EAAE,CAAC;YACpB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBAC/B,IAAI,CAAC;oBAAC,EAAE,CAAC,GAAG,CAAC,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAA,CAAC;YAC3B,CAAC;QACH,CAAC;QACD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1B,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;IAC7D,CAAC;IAED,EAAE,CAAI,IAAY,EAAE,EAAqC,EAAE,OAA8B;QACvF,MAAM,QAAQ,GAAmB,CAAC,GAAG,EAAE,EAAE;YACvC,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI;gBAAE,EAAE,CAAC,GAAqB,CAAC,CAAC;QACnD,CAAC,CAAC;QACF,IAAI,OAAO,EAAE,MAAM,EAAE,CAAC;YACpB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBAC/B,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;oBACtB,IAAI,CAAC;wBAAC,EAAE,CAAC,GAAqB,CAAC,CAAC;oBAAC,CAAC;oBAAC,MAAM,CAAC,CAAA,CAAC;gBAC7C,CAAC;YACH,CAAC;QACH,CAAC;QACD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAChC,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;IACnE,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,OAAO;QACL,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;QAC1B,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;IACpB,CAAC;CACF"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "klaus-agent",
+  "version": "0.1.0",
+  "description": "Universal agent framework",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/approval/approval.ts

@@ -0,0 +1,108 @@
+// 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

@@ -0,0 +1,26 @@
+// 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

@@ -0,0 +1,112 @@
+// 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

@@ -0,0 +1,84 @@
+// 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

@@ -0,0 +1,29 @@
+// 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

@@ -0,0 +1,60 @@
+// 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

@@ -0,0 +1,35 @@
+// 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

@@ -0,0 +1,16 @@
+// 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;
+}