klaus-agent 0.2.1 → 0.3.0

package/src/index.ts

@@ -15,6 +15,7 @@ import type { SubagentConfig } from "./multi-agent/types.js";
 import type { SkillSource } from "./skills/types.js";
 import type { MCPServerConfig, MCPClient } from "./tools/mcp-adapter.js";
 import type { TaskFactory } from "./background/types.js";
+import type { PlanningConfig } from "./planning/types.js";
 
 export interface CreateAgentConfig {
   // Required
@@ -41,6 +42,7 @@ export interface CreateAgentConfig {
   mcp?: { servers: MCPServerConfig[]; clientFactory: (config: MCPServerConfig) => MCPClient };
   wire?: { bufferSize?: number };
   backgroundTasks?: { factories?: Record<string, TaskFactory> };
+  planning?: PlanningConfig;
 
   // Advanced: provide your own LLM provider
   provider?: LLMProvider;
@@ -71,6 +73,7 @@ export function createAgent(config: CreateAgentConfig): Agent {
     mcp: config.mcp,
     wire: config.wire,
     backgroundTasks: config.backgroundTasks,
+    planning: config.planning,
   });
 }
 
@@ -80,10 +83,8 @@ export { ApprovalImpl } from "./approval/approval.js";
 export { registerProvider, resolveProvider } from "./llm/provider.js";
 export { AnthropicProvider } from "./providers/anthropic.js";
 export { OpenAIProvider } from "./providers/openai.js";
+export { OpenAIResponsesProvider } from "./providers/openai-responses.js";
 export { GeminiProvider } from "./providers/google.js";
-export { MiniMaxProvider } from "./providers/minimax.js";
-export { KimiProvider } from "./providers/kimi.js";
-export { VolcengineProvider } from "./providers/volcengine.js";
 export { executeToolCalls } from "./tools/executor.js";
 export { SessionManager } from "./session/session-manager.js";
 export { buildSessionContext } from "./session/session-context-builder.js";
@@ -98,10 +99,14 @@ export { discoverSkills } from "./skills/discovery.js";
 export { loadSkill, renderSkillTemplate } from "./skills/loader.js";
 export { MCPAdapter } from "./tools/mcp-adapter.js";
 export { estimateTokens, shouldCompact, findCutPoint } from "./compaction/compaction.js";
+export { calculateCost } from "./providers/shared.js";
 export { LLMSummarizer } from "./compaction/summarizer.js";
 export { Wire } from "./wire/wire.js";
 export { BackgroundTaskManager } from "./background/task-manager.js";
 export { createBackgroundTaskTools } from "./background/tools.js";
+export { PlanningManager } from "./planning/planning-manager.js";
+export { createPlanningTools } from "./planning/tools.js";
+export { PlanningNagProvider } from "./planning/nag-injection.js";
 
 // Core types
 export type {
@@ -144,6 +149,8 @@ export type {
   ToolResultMessage,
   Message,
   TokenUsage,
+  ModelCost,
+  UsageCost,
   ContentBlock,
   TextContent,
   ImageContent,
@@ -226,3 +233,13 @@ export type {
   BackgroundTaskEvent,
   TaskFactory,
 } from "./background/types.js";
+
+// Planning types
+export type {
+  PlanningConfig,
+  PlanPhase,
+  TodoItem,
+  TodoStatus,
+} from "./planning/types.js";
+
+export { PLANNING_TOOL_NAMES } from "./planning/types.js";

package/src/llm/provider.ts

@@ -3,27 +3,18 @@
 import { AnthropicProvider } from "../providers/anthropic.js";
 import { OpenAIProvider } from "../providers/openai.js";
 import { OpenAICodexProvider } from "../providers/openai-codex.js";
+import { OpenAIResponsesProvider } from "../providers/openai-responses.js";
 import { GeminiProvider } from "../providers/google.js";
-import { MiniMaxProvider } from "../providers/minimax.js";
-import { KimiProvider } from "../providers/kimi.js";
-import { VolcengineProvider } from "../providers/volcengine.js";
 import type { LLMProvider, LLMProviderFactory } from "./types.js";
 
 const providers = new Map<string, LLMProviderFactory>();
 
-// Built-in providers
+// Built-in protocol providers
 providers.set("anthropic", (c) => new AnthropicProvider(c.apiKey, c.baseUrl));
 providers.set("openai", (c) => new OpenAIProvider(c.apiKey, c.baseUrl));
+providers.set("openai-responses", (c) => new OpenAIResponsesProvider(c.apiKey, c.baseUrl));
 providers.set("openai-codex", (c) => new OpenAICodexProvider(c.apiKey, c.baseUrl));
 providers.set("google", (c) => new GeminiProvider(c.apiKey, c.baseUrl));
-providers.set("minimax", (c) => new MiniMaxProvider(c.apiKey, c.baseUrl));
-providers.set("kimi", (c) => new KimiProvider(c.apiKey, c.baseUrl));
-providers.set("volcengine", (c) => new VolcengineProvider(c.apiKey, c.baseUrl));
-
-// Protocol-compatible proxies — user provides baseUrl to connect any compatible service
-providers.set("openai-compatible", (c) => new OpenAIProvider(c.apiKey, c.baseUrl));
-providers.set("anthropic-compatible", (c) => new AnthropicProvider(c.apiKey, c.baseUrl));
-providers.set("gemini-compatible", (c) => new GeminiProvider(c.apiKey, c.baseUrl));
 
 export function registerProvider(name: string, factory: LLMProviderFactory): void {
   providers.set(name, factory);

package/src/llm/types.ts

@@ -1,5 +1,22 @@
 // LLM abstraction types
 
+/** Per-token pricing in $/million tokens. */
+export interface ModelCost {
+  input: number;
+  output: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+}
+
+/** Calculated cost in actual dollars for a single request. */
+export interface UsageCost {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  total: number;
+}
+
 export interface ModelConfig {
   provider: string;
   model: string;
@@ -10,6 +27,7 @@ export interface ModelConfig {
     vision?: boolean;
     thinking?: boolean;
   };
+  cost?: ModelCost;
 }
 
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
@@ -84,6 +102,7 @@ export interface TokenUsage {
   totalTokens: number;
   cacheReadTokens?: number;
   cacheWriteTokens?: number;
+  cost?: UsageCost;
 }
 
 // --- Streaming events ---

package/src/planning/nag-injection.ts

@@ -0,0 +1,24 @@
+// Nag injection provider — reminds model to update todos when it hasn't for N rounds
+
+import type { DynamicInjectionProvider, DynamicInjection } from "../injection/types.js";
+import type { AgentMessage } from "../types.js";
+import type { PlanningManager } from "./planning-manager.js";
+
+export class PlanningNagProvider implements DynamicInjectionProvider {
+  constructor(private _manager: PlanningManager) {}
+
+  async getInjections(_history: AgentMessage[]): Promise<DynamicInjection[]> {
+    if (!this._manager.shouldNag()) return [];
+
+    // Reset after check so the next nag waits another N rounds.
+    // Kept here (not in shouldNag) so shouldNag() stays side-effect-free.
+    this._manager.resetRoundCounter();
+
+    return [
+      {
+        type: "planning-nag",
+        content: this._manager.getNagMessage(),
+      },
+    ];
+  }
+}

package/src/planning/planning-manager.ts

@@ -0,0 +1,133 @@
+// Planning manager — two-phase planning with structured todo tracking
+
+import type { TodoItem, TodoStatus, PlanPhase, PlanningState, PlanningConfig } from "./types.js";
+import { PLANNING_TOOL_NAMES } from "./types.js";
+import { generateId } from "../utils/id.js";
+
+export class PlanningManager {
+  private _state: PlanningState;
+  private _config: PlanningConfig;
+  private _allowedInPlanning: ReadonlySet<string>;
+
+  constructor(config: PlanningConfig = {}) {
+    this._config = config;
+    const allowed = new Set(config.readOnlyTools ?? []);
+    allowed.add(PLANNING_TOOL_NAMES.todo);
+    allowed.add(PLANNING_TOOL_NAMES.planMode);
+    this._allowedInPlanning = allowed;
+    this._state = {
+      phase: "planning",
+      todos: [],
+      roundsSinceTodoUpdate: 0,
+    };
+  }
+
+  get phase(): PlanPhase {
+    return this._state.phase;
+  }
+
+  get todos(): readonly Readonly<TodoItem>[] {
+    return this._state.todos;
+  }
+
+  get roundsSinceTodoUpdate(): number {
+    return this._state.roundsSinceTodoUpdate;
+  }
+
+  get config(): Readonly<PlanningConfig> {
+    return this._config;
+  }
+
+  /** Pre-built set of tool names allowed during planning phase. */
+  get allowedInPlanning(): ReadonlySet<string> {
+    return this._allowedInPlanning;
+  }
+
+  // --- Phase control ---
+
+  startExecution(): string {
+    if (this._state.todos.length === 0) {
+      throw new Error("Cannot start execution: no todos defined. Create a plan first.");
+    }
+    this._state.phase = "executing";
+    this.resetRoundCounter();
+    return `Switched to execution phase. ${this._state.todos.length} todo(s) to complete.\n\n${this.render()}`;
+  }
+
+  switchToPlanning(): string {
+    this._state.phase = "planning";
+    this.resetRoundCounter();
+    return `Switched to planning phase. Tools restricted to read-only.\n\n${this.render()}`;
+  }
+
+  // --- Todo CRUD ---
+
+  updateTodos(items: Array<{ id: string; text: string; status: TodoStatus }>): string {
+    const max = this._config.maxTodos ?? 50;
+    if (items.length > max) {
+      throw new Error(`Too many todos: ${items.length} exceeds limit of ${max}.`);
+    }
+
+    let inProgressCount = 0;
+    const validated: TodoItem[] = [];
+
+    for (const item of items) {
+      const status = item.status ?? "pending";
+      if (status === "in_progress") inProgressCount++;
+      validated.push({
+        id: item.id || generateId(),
+        text: item.text,
+        status,
+      });
+    }
+
+    if (inProgressCount > 1) {
+      throw new Error("Only one todo can be in_progress at a time.");
+    }
+
+    this._state.todos = validated;
+    this.resetRoundCounter();
+    return this.render();
+  }
+
+  // --- Render ---
+
+  render(): string {
+    if (this._state.todos.length === 0) {
+      return `[phase: ${this._state.phase}] No todos.`;
+    }
+
+    const lines = this._state.todos.map((t) => {
+      const icon = t.status === "completed" ? "[x]" : t.status === "in_progress" ? "[>]" : "[ ]";
+      return `${icon} ${t.id}: ${t.text}`;
+    });
+
+    const done = this._state.todos.filter((t) => t.status === "completed").length;
+    const total = this._state.todos.length;
+
+    return `[phase: ${this._state.phase}] Progress: ${done}/${total}\n${lines.join("\n")}`;
+  }
+
+  // --- Nag tracking ---
+
+  /** Call once per agent loop step (after tool execution). */
+  tickRound(): void {
+    this._state.roundsSinceTodoUpdate++;
+  }
+
+  /** Reset the round counter (called when the model updates todos). */
+  resetRoundCounter(): void {
+    this._state.roundsSinceTodoUpdate = 0;
+  }
+
+  shouldNag(): boolean {
+    if (this._state.phase !== "executing") return false;
+    if (this._state.todos.length === 0) return false;
+    const threshold = this._config.nagAfterRounds ?? 3;
+    return this._state.roundsSinceTodoUpdate >= threshold;
+  }
+
+  getNagMessage(): string {
+    return this._config.nagMessage ?? "<reminder>Update your todos to reflect current progress.</reminder>";
+  }
+}

package/src/planning/tools.ts

@@ -0,0 +1,71 @@
+// Planning tools — todo management + phase switching
+
+import { Type } from "@sinclair/typebox";
+import type { AgentTool, AgentToolResult } from "../tools/types.js";
+import type { PlanningManager } from "./planning-manager.js";
+import { PLANNING_TOOL_NAMES } from "./types.js";
+import type { TodoStatus } from "./types.js";
+
+export function createPlanningTools(manager: PlanningManager): AgentTool[] {
+  return [
+    {
+      name: PLANNING_TOOL_NAMES.todo,
+      label: "Todo",
+      description:
+        "Manage your task list. Use this tool to plan work, track progress, and stay on track. " +
+        "Only one todo can be in_progress at a time. Update todos frequently to reflect your current state.",
+      parameters: Type.Object({
+        items: Type.Array(
+          Type.Object({
+            id: Type.String({ description: "Unique ID for the todo item." }),
+            text: Type.String({ description: "Description of the task." }),
+            status: Type.Union(
+              [Type.Literal("pending"), Type.Literal("in_progress"), Type.Literal("completed")],
+              { description: "Task status. Only one item can be in_progress at a time." },
+            ),
+          }),
+          { description: "The full updated todo list (replaces previous list)." },
+        ),
+      }),
+      async execute(
+        _toolCallId: string,
+        params: { items: Array<{ id: string; text: string; status: TodoStatus }> },
+      ): Promise<AgentToolResult> {
+        const result = manager.updateTodos(params.items);
+        return { content: [{ type: "text", text: result }] };
+      },
+    },
+    {
+      name: PLANNING_TOOL_NAMES.planMode,
+      label: "Plan Mode",
+      description:
+        "Switch between planning and execution phases. " +
+        "In planning phase, only read-only tools are available — use this time to analyze and create todos. " +
+        "In execution phase, all tools are available and nag reminders will prompt you to update todos.",
+      parameters: Type.Object({
+        action: Type.Union(
+          [Type.Literal("start_execution"), Type.Literal("switch_to_planning"), Type.Literal("status")],
+          { description: "Action to perform." },
+        ),
+      }),
+      async execute(
+        _toolCallId: string,
+        params: { action: "start_execution" | "switch_to_planning" | "status" },
+      ): Promise<AgentToolResult> {
+        let result: string;
+        switch (params.action) {
+          case "start_execution":
+            result = manager.startExecution();
+            break;
+          case "switch_to_planning":
+            result = manager.switchToPlanning();
+            break;
+          case "status":
+            result = manager.render();
+            break;
+        }
+        return { content: [{ type: "text", text: result }] };
+      },
+    },
+  ];
+}

package/src/planning/types.ts

@@ -0,0 +1,40 @@
+// Planning module types — two-phase planning + structured todo tracking
+
+export const PLANNING_TOOL_NAMES = {
+  todo: "todo",
+  planMode: "plan_mode",
+} as const;
+
+export type TodoStatus = "pending" | "in_progress" | "completed";
+
+export interface TodoItem {
+  id: string;
+  text: string;
+  status: TodoStatus;
+}
+
+export type PlanPhase = "planning" | "executing";
+
+export interface PlanningState {
+  phase: PlanPhase;
+  todos: TodoItem[];
+  roundsSinceTodoUpdate: number;
+}
+
+export interface PlanningConfig {
+  /**
+   * Tool names allowed during the planning phase (read-only tools).
+   * If omitted or empty, all tools are available during planning
+   * (phase separation is advisory only via system prompt).
+   */
+  readOnlyTools?: string[];
+
+  /** Number of rounds without a todo update before injecting a nag reminder. Default: 3. */
+  nagAfterRounds?: number;
+
+  /** Custom nag reminder text. */
+  nagMessage?: string;
+
+  /** Maximum number of todo items. Default: 50. */
+  maxTodos?: number;
+}

package/src/providers/openai-codex.ts

@@ -14,6 +14,8 @@ import type {
   ToolDefinition,
 } from "../llm/types.js";
 import { platform, release, arch } from "node:os";
+import { mapMessages, mapTools } from "./openai-responses-shared.js";
+import type { ResponseInput, ResponseTool } from "./openai-responses-shared.js";
 
 // --- Configuration ---
 
@@ -41,26 +43,6 @@ interface CodexRequestBody {
   [key: string]: unknown;
 }
 
-type ResponseInput = ResponseInputItem[];
-
-type ResponseInputItem =
-  | { type: "message"; role: "user" | "assistant"; content: ResponseContent[] }
-  | { type: "function_call"; id: string; call_id: string; name: string; arguments: string }
-  | { type: "function_call_output"; call_id: string; output: string };
-
-type ResponseContent =
-  | { type: "input_text"; text: string }
-  | { type: "output_text"; text: string }
-  | { type: "input_image"; image_url: string };
-
-interface ResponseTool {
-  type: "function";
-  name: string;
-  description: string;
-  parameters: Record<string, unknown>;
-  strict: null;
-}
-
 // --- Provider ---
 
 export class OpenAICodexProvider implements LLMProvider {
@@ -289,75 +271,6 @@ function buildRequestBody(
   return body;
 }
 
-function mapMessages(messages: Message[]): ResponseInput {
-  const input: ResponseInput = [];
-
-  for (const m of messages) {
-    if (m.role === "user") {
-      const content: ResponseContent[] = [];
-      if (typeof m.content === "string") {
-        content.push({ type: "input_text", text: m.content });
-      } else {
-        for (const block of m.content) {
-          if (block.type === "text") {
-            content.push({ type: "input_text", text: block.text });
-          } else if (block.type === "image") {
-            const url = block.source.type === "url"
-              ? block.source.url
-              : `data:${block.source.mediaType};base64,${block.source.data}`;
-            content.push({ type: "input_image", image_url: url });
-          }
-        }
-      }
-      input.push({ type: "message", role: "user", content });
-    } else if (m.role === "assistant") {
-      const content: ResponseContent[] = [];
-      for (const block of m.content) {
-        if (block.type === "text") {
-          content.push({ type: "output_text", text: block.text });
-        } else if (block.type === "tool_call") {
-          // Flush accumulated text before the tool call
-          if (content.length > 0) {
-            input.push({ type: "message", role: "assistant", content: [...content] });
-            content.length = 0;
-          }
-          input.push({
-            type: "function_call",
-            id: block.id,
-            call_id: block.id,
-            name: block.name,
-            arguments: JSON.stringify(block.input),
-          });
-        }
-      }
-      // Remaining text content
-      if (content.length > 0) {
-        input.push({ type: "message", role: "assistant", content });
-      }
-    } else if (m.role === "tool_result") {
-      const output = typeof m.content === "string"
-        ? m.content
-        : m.content.map((b) => b.type === "text" ? b.text : JSON.stringify(b)).join("\n");
-      input.push({
-        type: "function_call_output",
-        call_id: m.toolCallId,
-        output,
-      });
-    }
-  }
-
-  return input;
-}
-
-function mapTools(tools: ToolDefinition[]): ResponseTool[] {
-  return tools.map((t) => ({
-    type: "function" as const,
-    name: t.name,
-    description: t.description,
-    parameters: t.inputSchema,
-    strict: null,
-  }));
-}
 
 function mapReasoningEffort(modelId: string, level?: ThinkingLevel): string | undefined {
   if (!level || level === "off") return undefined;

package/src/providers/openai-responses-shared.ts

@@ -0,0 +1,97 @@
+// Shared types and utilities for OpenAI Responses API providers (openai-responses, openai-codex)
+
+import type { Message, ToolDefinition } from "../llm/types.js";
+
+// --- Types ---
+
+export type ResponseInput = ResponseInputItem[];
+
+export type ResponseInputItem =
+  | { type: "message"; role: "user" | "assistant"; content: ResponseContent[] }
+  | { type: "function_call"; id: string; call_id: string; name: string; arguments: string }
+  | { type: "function_call_output"; call_id: string; output: string };
+
+export type ResponseContent =
+  | { type: "input_text"; text: string }
+  | { type: "output_text"; text: string }
+  | { type: "input_image"; image_url: string };
+
+export interface ResponseTool {
+  type: "function";
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  strict: null;
+}
+
+// --- Message conversion ---
+
+export function mapMessages(messages: Message[]): ResponseInput {
+  const input: ResponseInput = [];
+
+  for (const m of messages) {
+    if (m.role === "user") {
+      const content: ResponseContent[] = [];
+      if (typeof m.content === "string") {
+        content.push({ type: "input_text", text: m.content });
+      } else {
+        for (const block of m.content) {
+          if (block.type === "text") {
+            content.push({ type: "input_text", text: block.text });
+          } else if (block.type === "image") {
+            const url = block.source.type === "url"
+              ? block.source.url
+              : `data:${block.source.mediaType};base64,${block.source.data}`;
+            content.push({ type: "input_image", image_url: url });
+          }
+        }
+      }
+      input.push({ type: "message", role: "user", content });
+    } else if (m.role === "assistant") {
+      const content: ResponseContent[] = [];
+      for (const block of m.content) {
+        if (block.type === "text") {
+          content.push({ type: "output_text", text: block.text });
+        } else if (block.type === "tool_call") {
+          // Flush accumulated text before the tool call
+          if (content.length > 0) {
+            input.push({ type: "message", role: "assistant", content: [...content] });
+            content.length = 0;
+          }
+          input.push({
+            type: "function_call",
+            id: block.id,
+            call_id: block.id,
+            name: block.name,
+            arguments: JSON.stringify(block.input),
+          });
+        }
+      }
+      // Remaining text content
+      if (content.length > 0) {
+        input.push({ type: "message", role: "assistant", content });
+      }
+    } else if (m.role === "tool_result") {
+      const output = typeof m.content === "string"
+        ? m.content
+        : m.content.map((b) => b.type === "text" ? b.text : JSON.stringify(b)).join("\n");
+      input.push({
+        type: "function_call_output",
+        call_id: m.toolCallId,
+        output,
+      });
+    }
+  }
+
+  return input;
+}
+
+export function mapTools(tools: ToolDefinition[]): ResponseTool[] {
+  return tools.map((t) => ({
+    type: "function" as const,
+    name: t.name,
+    description: t.description,
+    parameters: t.inputSchema,
+    strict: null,
+  }));
+}