@tpsdev-ai/agent 0.2.0 → 0.4.2

package/src/llm/provider.ts

@@ -1,20 +1,17 @@
-import type { LLMConfig } from "../runtime/types.js";
+import type {
+  LLMConfig,
+  CompletionRequest,
+  CompletionResponse,
+  ToolCall,
+  ToolSpec,
+  LLMMessage,
+} from "../runtime/types.js";
 
-export interface CompletionRequest {
-  systemPrompt?: string;
-  messages: Array<{ role: "user" | "assistant"; content: string }>;
-  maxTokens?: number;
-}
-
-export interface CompletionResponse {
-  content: string;
-  inputTokens: number;
-  outputTokens: number;
-}
+type ProviderKind = LLMConfig["provider"];
 
 /**
- * Routes completion requests to the appropriate provider.
- * Supports Anthropic, Google, and local Ollama.
+ * Routes completion requests to the configured provider and normalizes
+ * tool-call responses into a common shape.
  */
 export class ProviderManager {
   constructor(private readonly config: LLMConfig) {}
@@ -25,6 +22,8 @@ export class ProviderManager {
         return this.completeAnthropic(request);
       case "google":
         return this.completeGoogle(request);
+      case "openai":
+        return this.completeOpenAI(request);
       case "ollama":
         return this.completeOllama(request);
       default:
@@ -32,10 +31,123 @@ export class ProviderManager {
     }
   }
 
+  private toolSetForAnthropic(tools: ToolSpec[]) {
+    return tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      input_schema: tool.input_schema,
+    }));
+  }
+
+  private toolSetForOpenAI(tools: ToolSpec[]) {
+    return tools.map((tool) => ({
+      type: "function",
+      function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.input_schema,
+      },
+    }));
+  }
+
+  private toolSetForGoogle(tools: ToolSpec[]) {
+    return {
+      functionDeclarations: tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.input_schema,
+      })),
+    };
+  }
+
+  private mapAnthropicResponse(raw: any): CompletionResponse {
+    const blocks = raw?.content ?? [];
+    const toolCalls: ToolCall[] = [];
+    let content = "";
+
+    for (const block of blocks) {
+      if (block?.type === "tool_use" && block?.name && block?.id) {
+        toolCalls.push({
+          id: block.id,
+          name: block.name,
+          input: typeof block.input === "object" ? block.input : {},
+        });
+      }
+      if (block?.type === "text") {
+        content += block.text ?? "";
+      }
+    }
+
+    return {
+      content,
+      toolCalls: toolCalls.length ? toolCalls : undefined,
+      inputTokens: raw?.usage?.input_tokens ?? 0,
+      outputTokens: raw?.usage?.output_tokens ?? 0,
+    };
+  }
+
+  private mapOpenAIResponse(raw: any): CompletionResponse {
+    const message = raw?.choices?.[0]?.message ?? {};
+    const toolCalls = (message.tool_calls ?? []).map((toolCall: any) => ({
+      id: toolCall?.id,
+      name: toolCall?.function?.name,
+      input: this.safeJson(toolCall?.function?.arguments),
+    })) as ToolCall[];
+
+    return {
+      content: message?.content ?? "",
+      toolCalls: toolCalls.length ? toolCalls : undefined,
+      inputTokens: raw?.usage?.prompt_tokens ?? 0,
+      outputTokens: raw?.usage?.completion_tokens ?? 0,
+    };
+  }
+
+  private mapOllamaResponse(raw: any): CompletionResponse {
+    const message = raw?.message ?? {};
+    let toolCalls: ToolCall[] | undefined;
+
+    if (message?.tool_calls) {
+      toolCalls = message.tool_calls.map((toolCall: any) => ({
+        id: toolCall?.id,
+        name: toolCall?.name,
+        input: this.safeJson(toolCall?.arguments),
+      }));
+    }
+
+    return {
+      content: message?.content ?? "",
+      toolCalls: toolCalls && toolCalls.length ? toolCalls : undefined,
+      inputTokens: raw?.prompt_eval_count ?? 0,
+      outputTokens: raw?.eval_count ?? 0,
+    };
+  }
+
+  private safeJson(raw: unknown): Record<string, unknown> {
+    if (typeof raw === "object" && raw !== null) return raw as Record<string, unknown>;
+    if (typeof raw === "string") {
+      try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed === "object" && parsed !== null ? parsed : {};
+      } catch {
+        return {};
+      }
+    }
+    return {};
+  }
+
   private async completeAnthropic(request: CompletionRequest): Promise<CompletionResponse> {
     const apiKey = this.config.apiKey ?? process.env.ANTHROPIC_API_KEY;
     if (!apiKey) throw new Error("ANTHROPIC_API_KEY not set");
 
+    const body = {
+      model: this.config.model,
+      max_tokens: request.maxTokens ?? 2048,
+      system: request.systemPrompt,
+      messages: request.messages,
+      tools: this.toolSetForAnthropic(request.tools),
+      tool_choice: request.toolChoice ?? "auto",
+    };
+
     const res = await fetch("https://api.anthropic.com/v1/messages", {
       method: "POST",
       headers: {
@@ -43,12 +155,7 @@ export class ProviderManager {
         "x-api-key": apiKey,
         "anthropic-version": "2023-06-01",
       },
-      body: JSON.stringify({
-        model: this.config.model,
-        max_tokens: request.maxTokens ?? 2048,
-        system: request.systemPrompt,
-        messages: request.messages,
-      }),
+      body: JSON.stringify(body),
     });
 
     if (!res.ok) {
@@ -56,11 +163,7 @@ export class ProviderManager {
     }
 
     const data = (await res.json()) as any;
-    return {
-      content: data.content?.[0]?.text ?? "",
-      inputTokens: data.usage?.input_tokens ?? 0,
-      outputTokens: data.usage?.output_tokens ?? 0,
-    };
+    return this.mapAnthropicResponse(data);
   }
 
   private async completeGoogle(request: CompletionRequest): Promise<CompletionResponse> {
@@ -68,17 +171,24 @@ export class ProviderManager {
     if (!apiKey) throw new Error("GOOGLE_API_KEY not set");
 
     const url = `https://generativelanguage.googleapis.com/v1beta/models/${this.config.model}:generateContent?key=${apiKey}`;
+    const toolPayload = this.toolSetForGoogle(request.tools);
+
     const res = await fetch(url, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
-        contents: request.messages.map((m) => ({
-          role: m.role === "assistant" ? "model" : "user",
-          parts: [{ text: m.content }],
-        })),
         systemInstruction: request.systemPrompt
           ? { parts: [{ text: request.systemPrompt }] }
           : undefined,
+        contents: request.messages.map((m) => ({
+          role: m.role === "assistant" ? "model" : "user",
+          parts: [{ text: m.content ?? "" }],
+        })),
+        tools: toolPayload,
+        toolConfig: request.toolChoice === "required" ? { functionCallingConfig: { mode: "ANY" } } : undefined,
+        generationConfig: {
+          maxOutputTokens: request.maxTokens ?? 2048,
+        },
       }),
     });
 
@@ -87,27 +197,64 @@ export class ProviderManager {
     }
 
     const data = (await res.json()) as any;
-    const text = data.candidates?.[0]?.content?.parts?.[0]?.text ?? "";
-    const usage = data.usageMetadata ?? {};
+    const candidate = data?.candidates?.[0] ?? {};
+    const functionCalls = candidate?.content?.parts?.flatMap((part: any) => {
+      if (Array.isArray(part?.functionCalls)) return part.functionCalls;
+      if (part?.functionCall) return [part.functionCall];
+      return [];
+    }) ?? [];
+
+    const toolCalls = functionCalls.map((toolCall: any) => ({
+      id: toolCall?.id,
+      name: toolCall?.name,
+      input: this.safeJson(toolCall?.args),
+    } as ToolCall));
+
     return {
-      content: text,
-      inputTokens: usage.promptTokenCount ?? 0,
-      outputTokens: usage.candidatesTokenCount ?? 0,
+      content: candidate?.content?.parts?.map((part: any) => part?.text).filter(Boolean).join("\n") ?? "",
+      toolCalls: toolCalls.length ? toolCalls : undefined,
+      inputTokens: data?.usageMetadata?.promptTokenCount ?? 0,
+      outputTokens: data?.usageMetadata?.candidatesTokenCount ?? 0,
     };
   }
 
+  private async completeOpenAI(request: CompletionRequest): Promise<CompletionResponse> {
+    const apiKey = this.config.apiKey ?? process.env.OPENAI_API_KEY;
+    if (!apiKey) throw new Error("OPENAI_API_KEY not set");
+
+    const res = await fetch("https://api.openai.com/v1/chat/completions", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        model: this.config.model,
+        messages: request.messages,
+        tools: this.toolSetForOpenAI(request.tools),
+        tool_choice: request.toolChoice ?? "auto",
+        max_tokens: request.maxTokens ?? 2048,
+      }),
+    });
+
+    if (!res.ok) {
+      throw new Error(`OpenAI API error: ${res.status} ${await res.text()}`);
+    }
+
+    const data = (await res.json()) as any;
+    return this.mapOpenAIResponse(data);
+  }
+
   private async completeOllama(request: CompletionRequest): Promise<CompletionResponse> {
-    const baseUrl = this.config.baseUrl ?? "http://localhost:11434";
-    const systemMsg = request.systemPrompt
-      ? [{ role: "system" as const, content: request.systemPrompt }]
-      : [];
+    const baseUrl = this.config.baseUrl ?? process.env.OLLAMA_HOST ?? "http://localhost:11434";
 
     const res = await fetch(`${baseUrl}/api/chat`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
         model: this.config.model,
-        messages: [...systemMsg, ...request.messages],
+        messages: request.messages,
+        tools: this.toolSetForOpenAI(request.tools),
         stream: false,
       }),
     });
@@ -117,10 +264,24 @@ export class ProviderManager {
     }
 
     const data = (await res.json()) as any;
+    return this.mapOllamaResponse(data);
+  }
+
+  public toToolSpec(name: string, description: string, inputSchema: Record<string, unknown>): ToolSpec {
     return {
-      content: data.message?.content ?? "",
-      inputTokens: data.prompt_eval_count ?? 0,
-      outputTokens: data.eval_count ?? 0,
+      name,
+      description,
+      input_schema: {
+        type: "object",
+        properties: inputSchema,
+        additionalProperties: false,
+      },
     };
   }
+
+  public toolInputSchemaFor(provider: ProviderKind): (schema: ToolSpec[]) => unknown {
+    if (provider === "openai" || provider === "ollama") return this.toolSetForOpenAI.bind(this);
+    if (provider === "google") return this.toolSetForGoogle.bind(this);
+    return this.toolSetForAnthropic.bind(this);
+  }
 }

package/src/runtime/agent.ts

@@ -4,23 +4,50 @@ import { MailClient } from "../io/mail.js";
 import { MemoryStore } from "../io/memory.js";
 import { ContextManager } from "../io/context.js";
 import { ProviderManager } from "../llm/provider.js";
+import { BoundaryManager } from "../governance/boundary.js";
+import { createDefaultToolset } from "../tools/index.js";
 
 export class AgentRuntime {
   private loop: EventLoop;
+  private readonly mail: MailClient;
+  private readonly boundary: BoundaryManager;
 
   constructor(public readonly config: AgentConfig) {
     const mail = new MailClient(config.mailDir);
     const memory = new MemoryStore(config.memoryPath);
-    const context = new ContextManager(memory, config.contextWindowTokens ?? 8_000);
+    const context = new ContextManager(memory, config.contextWindowTokens ?? 8000);
     const provider = new ProviderManager(config.llm);
-    this.loop = new EventLoop({ config, mail, memory, context, provider });
+
+    this.mail = mail;
+    this.boundary = new BoundaryManager(config.workspace);
+    const tools = createDefaultToolset({
+      boundary: this.boundary,
+      mail,
+      tools: config.tools,
+      execAllowlist: config.execAllowlist,
+    });
+
+    this.loop = new EventLoop({ config, memory, context, provider, tools });
   }
 
   async start(): Promise<void> {
-    await this.loop.run();
+    const checkInbox = async () => this.mail.checkNewMail();
+    await this.loop.run(checkInbox);
   }
 
   async stop(): Promise<void> {
     await this.loop.stop();
   }
+
+  async runOnce(message: string): Promise<void> {
+    await this.loop.runOnce(message);
+  }
+
+  getState(): string {
+    return this.loop.getState();
+  }
+
+  describeBoundaries(): string {
+    return this.boundary.describeCapabilities();
+  }
 }

package/src/runtime/event-loop.ts

@@ -1,54 +1,60 @@
-import type { AgentConfig, AgentState } from "./types.js";
-import type { MailClient } from "../io/mail.js";
+import type { MailMessage } from "../io/mail.js";
+import type {
+  AgentConfig,
+  AgentState,
+  CompletionRequest,
+  CompletionResponse,
+  ToolCall,
+  ToolSpec,
+} from "./types.js";
 import type { MemoryStore } from "../io/memory.js";
 import type { ContextManager } from "../io/context.js";
 import type { ProviderManager } from "../llm/provider.js";
+import type { ToolRegistry } from "../tools/registry.js";
+import { ReviewGate } from "../governance/review-gate.js";
 
 interface EventLoopDeps {
   config: AgentConfig;
-  mail: MailClient;
   memory: MemoryStore;
   context: ContextManager;
   provider: ProviderManager;
+  tools: ToolRegistry;
+  reviewGate?: ReviewGate;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
 export class EventLoop {
   private state: AgentState = "idle";
   private running = false;
 
-  constructor(private readonly deps: EventLoopDeps) {}
+  constructor(private readonly deps: EventLoopDeps, private readonly pollMs = 500) {}
 
-  async run(): Promise<void> {
+  async run(checkInbox: () => Promise<MailMessage[]>): Promise<void> {
     this.running = true;
     this.state = "idle";
 
     while (this.running) {
-      const messages = await this.deps.mail.checkNewMail();
-
-      if (messages.length === 0) {
-        // No work — sleep briefly before next poll
-        await sleep(500);
-        continue;
-      }
-
+      const messages = await checkInbox();
       for (const msg of messages) {
         if (!this.running) break;
-
         this.state = "processing";
-
         try {
-          await this.processMessage(msg);
-        } catch (err) {
-          // Log errors to memory and continue rather than crashing the loop
+          await this.processMail(msg);
+        } catch (err: any) {
           await this.deps.memory.append({
             type: "error",
             ts: new Date().toISOString(),
-            data: String(err),
+            data: String(err?.message ?? err),
           });
         }
-
         this.state = "idle";
       }
+
+      if (!this.running) break;
+      if (messages.length === 0) await sleep(this.pollMs);
     }
   }
 
@@ -61,16 +67,152 @@ export class EventLoop {
     return this.state;
   }
 
-  private async processMessage(msg: unknown): Promise<void> {
-    // Stub: real implementation builds prompt, calls LLM, handles tool calls
+  async runOnce(prompt: string): Promise<void> {
+    await this.processMessage(prompt);
+  }
+
+  private async processMail(message: MailMessage): Promise<void> {
+    await this.processMessage(message.body);
+  }
+
+  private async processMessage(promptRaw: string): Promise<void> {
+    const prompt = String(promptRaw).trim();
+
+    const tools = this.deps.tools
+      .list()
+      .map<ToolSpec>((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        input_schema: {
+          type: "object",
+          properties: tool.input_schema,
+          additionalProperties: false,
+        },
+      }));
+
     await this.deps.memory.append({
       type: "message",
       ts: new Date().toISOString(),
-      data: msg,
+      data: { direction: "in", body: prompt },
     });
+
+    const request: CompletionRequest = {
+      systemPrompt: await this.buildSystemPrompt(),
+      messages: [{ role: "user", content: prompt }],
+      tools,
+      toolChoice: "auto",
+      maxTokens: this.deps.config.maxTokens ?? 1024,
+    };
+
+    let completion = await this.deps.provider.complete(request);
+    let turns = 0;
+
+    while (true) {
+      if (completion.content) {
+        await this.deps.memory.append({
+          type: "assistant",
+          ts: new Date().toISOString(),
+          data: {
+            content: completion.content,
+            inputTokens: completion.inputTokens,
+            outputTokens: completion.outputTokens,
+          },
+        });
+      }
+
+      if (!completion.toolCalls || completion.toolCalls.length === 0) {
+        return;
+      }
+
+      if (turns++ > 8) {
+        await this.deps.memory.append({
+          type: "error",
+          ts: new Date().toISOString(),
+          data: { message: "tool loop max depth reached" },
+        });
+        return;
+      }
+
+      const toolMessages: Array<{ role: "tool"; tool_call_id: string; name: string; content: string }> = [];
+      for (const call of completion.toolCalls ?? []) {
+        await this.deps.memory.append({
+          type: "tool_call",
+          ts: new Date().toISOString(),
+          data: { tool: call.name, args: call.input },
+        });
+
+        if (this.deps.reviewGate && this.deps.reviewGate.isHighRisk(call.name)) {
+          await this.deps.reviewGate.requestApproval(call.name, call.input);
+          await this.deps.memory.append({
+            type: "approval_request",
+            ts: new Date().toISOString(),
+            data: { tool: call.name, args: call.input },
+          });
+          continue;
+        }
+
+        let result;
+        try {
+          result = await this.deps.tools.execute(call.name, call.input);
+        } catch (err: any) {
+          result = { content: `Tool execution error: ${err?.message ?? String(err)}`, isError: true };
+        }
+
+        await this.deps.memory.append({
+          type: "tool_result",
+          ts: new Date().toISOString(),
+          data: { tool: call.name, result },
+        });
+
+        toolMessages.push({
+          role: "tool",
+          tool_call_id: String((call as ToolCall).id ?? `${Date.now()}-${Math.random()}`),
+          name: call.name,
+          content: JSON.stringify(result),
+        });
+      }
+
+      const nextMessages = [
+        ...request.messages,
+        { role: "assistant", content: completion.content ?? "" },
+        ...toolMessages,
+      ];
+
+      completion = await this.deps.provider.complete({
+        systemPrompt: request.systemPrompt,
+        messages: nextMessages,
+        tools,
+        toolChoice: "auto",
+        maxTokens: this.deps.config.maxTokens ?? 1024,
+      });
+    }
   }
-}
 
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  private async buildSystemPrompt(): Promise<string> {
+    const fs = await import("node:fs/promises");
+    const docs = await Promise.all([
+      this.fileOrEmpty(`${this.deps.config.workspace}/SOUL.md`),
+      this.fileOrEmpty(`${this.deps.config.workspace}/AGENTS.md`),
+      this.fileOrEmpty(`${this.deps.config.workspace}/IDENTITY.md`),
+      Promise.resolve(this.deps.config.systemPrompt || ""),
+    ]);
+
+    const sections = [
+      `Role: ${this.deps.config.name}`,
+      `Tools: ${this.deps.tools.list().map((t) => t.name).join(", ") || "(none)"}`,
+      `Context: ${this.deps.config.agentId}`,
+    ];
+
+    const docBlock = docs.filter(Boolean).join("\n\n");
+    return `${docBlock}\n\n${sections.join("\n")}`;
+  }
+
+  private async fileOrEmpty(path: string): Promise<string> {
+    try {
+      const fs = await import("node:fs/promises");
+      return await fs.readFile(path, "utf-8");
+    } catch {
+      return "";
+    }
+  }
 }

package/src/runtime/types.ts

@@ -1,5 +1,7 @@
+export type ProviderName = "anthropic" | "google" | "openai" | "ollama";
+
 export interface LLMConfig {
-  provider: "anthropic" | "google" | "ollama";
+  provider: ProviderName;
   model: string;
   apiKey?: string;
   baseUrl?: string;
@@ -10,19 +12,65 @@ export interface AgentConfig {
   agentId: string;
   /** Human-readable name */
   name: string;
-  /** Maildir root: ~/mail/inbox, ~/mail/outbox */
+  /** Maildir root */
   mailDir: string;
   /** JSONL memory file path */
   memoryPath: string;
-  /** Target token context window (for compaction) */
-  contextWindowTokens?: number;
+  /** Workspace root for file tools */
+  workspace: string;
   /** LLM provider config */
   llm: LLMConfig;
-  /** System prompt override */
+  /** Optional override personas/system prompt */
+  systemPrompt?: string;
+  /** Target token context window */
+  contextWindowTokens?: number;
+  /** Max model output tokens */
+  maxTokens?: number;
+  /** Tools the runtime should load */
+  tools?: Array<"read" | "write" | "edit" | "exec" | "mail">;
+  /** Allow-list for exec command binary names */
+  execAllowlist?: string[];
+}
+
+export interface ToolResult {
+  content: string;
+  isError?: boolean;
+}
+
+export interface ToolCall {
+  id?: string;
+  name: string;
+  input: Record<string, unknown>;
+}
+
+export interface LLMMessage {
+  role: "system" | "user" | "assistant" | "tool" | "developer" | string;
+  content?: string;
+  name?: string;
+  tool_call_id?: string;
+}
+
+export interface CompletionRequest {
   systemPrompt?: string;
+  messages: LLMMessage[];
+  tools: ToolSpec[];
+  toolChoice?: "auto" | "required";
+  maxTokens?: number;
+}
+
+export interface ToolSpec {
+  name: string;
+  description: string;
+  input_schema: Record<string, unknown>;
+}
+
+export interface CompletionResponse {
+  content?: string;
+  toolCalls?: ToolCall[];
+  inputTokens: number;
+  outputTokens: number;
 }
 
-/** Runtime state machine states */
 export type AgentState =
   | "idle"
   | "processing"