takos-control 1.0.0

package/src/application/services/agent/langgraph-tools.ts

@@ -0,0 +1,157 @@
+/**
+ * LangGraph Tool Helpers
+ *
+ * Shared utility functions, tool creation, and public types for the
+ * LangGraph agent subsystem.
+ */
+
+import { z } from 'zod';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { ToolExecutorLike } from '../../tools/executor';
+import type { ToolDefinition, ToolParameter } from '../../tools/tool-definitions';
+
+// ── Shared helpers ──────────────────────────────────────────────────────
+
+/** Extract string content from a BaseMessage's content field (string or structured parts). */
+export function extractMessageText(content: BaseMessage['content']): string {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .map(part => {
+        if (typeof part === 'string') return part;
+        if (part && typeof part === 'object' && 'text' in part) {
+          return (part as { text: string }).text;
+        }
+        return '';
+      })
+      .filter(Boolean)
+      .join('\n');
+  }
+  if (content !== null && content !== undefined) {
+    try { return JSON.stringify(content); } catch { return String(content); }
+  }
+  return '';
+}
+
+/** Convert a ToolParameter definition to a Zod schema type. */
+export function toolParameterToZod(param: ToolParameter): z.ZodType {
+  let zodType: z.ZodType;
+
+  switch (param.type) {
+    case 'string':
+      zodType = param.enum
+        ? z.enum(param.enum as [string, ...string[]])
+        : z.string();
+      break;
+    case 'number':
+      zodType = z.number();
+      break;
+    case 'boolean':
+      zodType = z.boolean();
+      break;
+    case 'array': {
+      const itemType = param.items ? toolParameterToZod(param.items) : z.string();
+      zodType = z.array(itemType);
+      break;
+    }
+    case 'object':
+      zodType = z.record(z.string(), z.unknown());
+      break;
+    default:
+      zodType = z.unknown();
+  }
+
+  if (param.description) {
+    zodType = zodType.describe(param.description);
+  }
+
+  return zodType;
+}
+
+/** Coerce an unknown tool invocation result into a string. */
+export function stringifyToolResult(result: unknown): string {
+  if (typeof result === 'string') return result;
+  if (result === null || result === undefined) return '';
+  try { return JSON.stringify(result); } catch { return String(result); }
+}
+
+export function anySignal(signals: AbortSignal[]): AbortSignal {
+  const controller = new AbortController();
+  for (const signal of signals) {
+    if (signal.aborted) {
+      controller.abort(signal.reason);
+      return controller.signal;
+    }
+    signal.addEventListener('abort', () => controller.abort(signal.reason), { once: true });
+  }
+  return controller.signal;
+}
+
+export { throwIfAborted } from 'takos-common/abort';
+
+// ── Public types ────────────────────────────────────────────────────────
+
+export interface LangGraphEvent {
+  type: 'thinking' | 'tool_call' | 'tool_result' | 'message' | 'completed' | 'error' | 'progress';
+  data: Record<string, unknown>;
+}
+
+export interface CreateAgentOptions {
+  apiKey: string;
+  model?: string;
+  temperature?: number;
+  systemPrompt: string;
+  tools: ToolDefinition[];
+  toolExecutor: ToolExecutorLike;
+  db?: import('../../../shared/types/bindings.ts').SqlDatabaseBinding;
+  maxIterations?: number;
+  abortSignal?: AbortSignal;
+}
+
+/** Generate a unique tool-call ID using crypto random bytes. */
+export function generateToolCallId(counter: number): string {
+  const idBytes = new Uint8Array(8);
+  crypto.getRandomValues(idBytes);
+  return `call_${Date.now()}_${counter}_${Array.from(idBytes, b => b.toString(16).padStart(2, '0')).join('')}`;
+}
+
+// ── ToolParameter → LangChain DynamicStructuredTool conversion ──────────
+
+export function createLangChainTool(
+  toolDef: ToolDefinition,
+  executor: ToolExecutorLike
+): DynamicStructuredTool {
+  const schemaProps: Record<string, z.ZodTypeAny> = {};
+  const required = toolDef.parameters.required || [];
+
+  for (const [key, param] of Object.entries(toolDef.parameters.properties)) {
+    let zodType = toolParameterToZod(param);
+
+    if (!required.includes(key)) {
+      zodType = zodType.optional();
+    }
+
+    schemaProps[key] = zodType;
+  }
+
+  const schema = z.object(schemaProps);
+  return new DynamicStructuredTool({
+    name: toolDef.name,
+    description: toolDef.description,
+
+    schema: schema as z.ZodObject<Record<string, z.ZodTypeAny>>,
+    func: async (args: Record<string, unknown>) => {
+      const result = await executor.execute({
+        id: generateToolCallId(0),
+        name: toolDef.name,
+        arguments: args,
+      });
+
+      if (result.error) {
+        return `Error: ${result.error}`;
+      }
+      return result.output;
+    },
+  });
+}

package/src/application/services/agent/llm-manager.ts

@@ -0,0 +1,51 @@
+/**
+ * LLM Manager - Handles LLM client initialization, model selection, and API key management.
+ *
+ * Extracted from runner.ts to separate LLM provider concerns from the core run loop.
+ */
+
+import type { Env } from '../../../shared/types';
+import { LLMClient, createMultiModelClient, getProviderFromModel, type ModelProvider } from './llm';
+
+export interface LLMManagerConfig {
+  apiKey: string | undefined;
+  env: Env;
+  aiModel: string;
+}
+
+export interface LLMState {
+  readonly aiModel: string;
+  readonly modelProvider: ModelProvider;
+  readonly openAiKey: string | undefined;
+  readonly anthropicKey: string | undefined;
+  readonly googleKey: string | undefined;
+  readonly client: LLMClient | undefined;
+}
+
+/** Build LLM state: resolve API keys, detect provider, and create client. */
+export function createLLMState(config: LLMManagerConfig): LLMState {
+  const aiModel = config.aiModel;
+  const modelProvider = getProviderFromModel(config.aiModel);
+
+  const openAiKey = config.apiKey || config.env.OPENAI_API_KEY;
+  const anthropicKey = config.env.ANTHROPIC_API_KEY;
+  const googleKey = config.env.GOOGLE_API_KEY;
+
+  const providerKeyMap: Record<ModelProvider, string | undefined> = {
+    openai: openAiKey,
+    anthropic: anthropicKey,
+    google: googleKey,
+  };
+  const providerKey = providerKeyMap[modelProvider];
+
+  const client = providerKey
+    ? createMultiModelClient({
+        apiKey: providerKey,
+        model: config.aiModel,
+        anthropicApiKey: anthropicKey,
+        googleApiKey: googleKey,
+      })
+    : undefined;
+
+  return { aiModel, modelProvider, openAiKey, anthropicKey, googleKey, client };
+}

package/src/application/services/agent/llm.ts

@@ -0,0 +1,106 @@
+import type { AgentMessage, AgentTool } from './agent-models';
+import {
+  createProvider,
+  getProviderFromModel,
+  DEFAULT_MODEL_ID,
+  type ModelConfig,
+  type ModelProvider,
+  type LLMProvider,
+  type LLMResponse,
+} from './providers/llm-providers';
+
+export type { ModelConfig, ModelProvider, LLMProvider, LLMResponse };
+export { getProviderFromModel };
+
+export interface LLMConfig {
+  apiKey: string;
+  model?: string;
+  maxTokens?: number;
+  temperature?: number;
+  provider?: ModelProvider;
+  anthropicApiKey?: string;
+  googleApiKey?: string;
+}
+
+export class LLMClient {
+  private provider: LLMProvider;
+  private config: LLMConfig;
+
+  constructor(config: LLMConfig) {
+    this.config = config;
+
+    const model = config.model || DEFAULT_MODEL_ID;
+    const providerType = config.provider || getProviderFromModel(model);
+
+    let apiKey = config.apiKey;
+    if (providerType === 'anthropic' && config.anthropicApiKey) {
+      apiKey = config.anthropicApiKey;
+    } else if (providerType === 'google' && config.googleApiKey) {
+      apiKey = config.googleApiKey;
+    }
+
+    this.provider = createProvider({
+      provider: providerType,
+      model,
+      apiKey,
+      maxTokens: config.maxTokens || 4096,
+      temperature: config.temperature ?? 1,
+    });
+  }
+
+  getConfig(): LLMConfig {
+    return this.config;
+  }
+
+  async chat(
+    messages: AgentMessage[],
+    tools?: AgentTool[],
+    signal?: AbortSignal,
+  ): Promise<LLMResponse> {
+    return this.provider.chat(messages, tools, signal);
+  }
+}
+
+export function createLLMClient(apiKey: string, config?: Partial<LLMConfig>): LLMClient {
+  return new LLMClient({ apiKey, ...config });
+}
+
+export function createMultiModelClient(config: LLMConfig): LLMClient {
+  return new LLMClient(config);
+}
+
+export const VALID_PROVIDERS: readonly ModelProvider[] = ['openai', 'anthropic', 'google'];
+
+function parseModelProvider(value: string | undefined): ModelProvider | undefined {
+  if (!value) return undefined;
+  return (VALID_PROVIDERS as readonly string[]).includes(value) ? (value as ModelProvider) : undefined;
+}
+
+export function createLLMClientFromEnv(env: {
+  OPENAI_API_KEY?: string;
+  ANTHROPIC_API_KEY?: string;
+  GOOGLE_API_KEY?: string;
+  AI_MODEL?: string;
+  AI_PROVIDER?: string;
+}): LLMClient {
+  const model = env.AI_MODEL || DEFAULT_MODEL_ID;
+  const providerType = parseModelProvider(env.AI_PROVIDER) || getProviderFromModel(model);
+
+  const keyMap: Record<ModelProvider, { key: string | undefined; label: string }> = {
+    openai: { key: env.OPENAI_API_KEY, label: 'OpenAI API key (OPENAI_API_KEY) is required for OpenAI models' },
+    anthropic: { key: env.ANTHROPIC_API_KEY, label: 'Anthropic API key (ANTHROPIC_API_KEY) is required for Claude models' },
+    google: { key: env.GOOGLE_API_KEY, label: 'Google API key (GOOGLE_API_KEY) is required for Gemini models' },
+  };
+
+  const entry = keyMap[providerType];
+  if (!entry) throw new Error(`Unknown provider type: ${providerType}`);
+  if (!entry.key) throw new Error(entry.label);
+
+  return new LLMClient({
+    apiKey: entry.key,
+    model,
+    provider: providerType,
+    anthropicApiKey: env.ANTHROPIC_API_KEY,
+    googleApiKey: env.GOOGLE_API_KEY,
+  });
+}

package/src/application/services/agent/memory-manager.ts

@@ -0,0 +1,84 @@
+/**
+ * Memory Manager - Handles memory runtime integration and memory graph processing.
+ *
+ * Extracted from runner.ts to separate memory concerns from the core run loop.
+ */
+
+import type { SqlDatabaseBinding } from '../../../shared/types/bindings.ts';
+import type { Env } from '../../../shared/types';
+import type { AgentContext } from './agent-models';
+import type { AgentRunnerIo } from './runner';
+import type { ToolExecutorLike } from '../../tools/executor';
+import { AgentMemoryRuntime, type AgentMemoryBackend } from '../memory-graph/memory-graph-runtime';
+import { logWarn } from '../../../shared/utils/logger';
+
+export interface MemoryManagerDeps {
+  db: SqlDatabaseBinding;
+  env: Env;
+  context: AgentContext;
+  runIo: AgentRunnerIo;
+}
+
+export interface MemoryState {
+  runtime: AgentMemoryRuntime | undefined;
+}
+
+/**
+ * Initialize and bootstrap the memory runtime, wiring the tool observer into the
+ * provided tool executor. Silently degrades if initialization fails.
+ */
+export async function bootstrapMemory(
+  deps: MemoryManagerDeps,
+  state: MemoryState,
+  toolExecutor: ToolExecutorLike | undefined,
+): Promise<void> {
+  try {
+    const backend = createMemoryBackend(deps);
+    state.runtime = new AgentMemoryRuntime(
+      deps.db,
+      deps.context,
+      deps.env,
+      backend,
+    );
+    await state.runtime.bootstrap();
+    if (toolExecutor) {
+      const observer = state.runtime.createToolObserver();
+      toolExecutor.setObserver(observer);
+    }
+  } catch (err) {
+    logWarn('Memory runtime initialization failed, continuing without memory', {
+      module: 'services/agent/memory-manager',
+      detail: err,
+    });
+    state.runtime = undefined;
+  }
+}
+
+/**
+ * Finalize the memory runtime (flush overlay claims to DB).
+ * Safe to call even if runtime was never initialized.
+ */
+export async function finalizeMemory(state: MemoryState): Promise<void> {
+  if (!state.runtime) return;
+  try {
+    await state.runtime.finalize();
+  } catch (err) {
+    logWarn('Memory runtime finalize failed during cleanup', {
+      module: 'services/agent/memory-manager',
+      detail: err,
+    });
+  }
+  state.runtime = undefined;
+}
+
+function createMemoryBackend(deps: MemoryManagerDeps): AgentMemoryBackend | undefined {
+  return {
+    bootstrap: () => deps.runIo.getMemoryActivation({ spaceId: deps.context.spaceId }),
+    finalize: ({ claims, evidence }) => deps.runIo.finalizeMemoryOverlay({
+      runId: deps.context.runId,
+      spaceId: deps.context.spaceId,
+      claims,
+      evidence,
+    }),
+  };
+}

package/src/application/services/agent/message-persistence.ts

@@ -0,0 +1,151 @@
+import type { Env, MessageRole } from '../../../shared/types';
+import type { AgentMessage } from './agent-models';
+import { getDb, messages } from '../../../infra/db';
+import { eq, sql } from 'drizzle-orm';
+import { generateId } from '../../../shared/utils';
+import { makeMessagePreview, shouldOffloadMessage, writeMessageToR2 } from '../offload/messages';
+import { logError, logWarn } from '../../../shared/utils/logger';
+import type { SqlDatabaseBinding } from '../../../shared/types/bindings.ts';
+
+export interface MessagePersistenceDeps {
+  db: SqlDatabaseBinding;
+  env: Env;
+  threadId: string;
+}
+
+export async function persistMessage(
+  deps: MessagePersistenceDeps,
+  message: AgentMessage,
+  metadata?: Record<string, unknown>
+): Promise<void> {
+  const { db: dbBinding, env, threadId } = deps;
+  const db = getDb(dbBinding);
+  const now = new Date().toISOString();
+  const maxRetries = 5;
+  const baseDelayMs = 10;
+  const maxDelayMs = 500;
+
+  // Deterministic ID based on content hash for idempotency across retries
+  const contentForHash = JSON.stringify({
+    threadId,
+    role: message.role,
+    content: message.content?.slice(0, 1000), // Use first 1000 chars for uniqueness
+    toolCalls: message.tool_calls ? JSON.stringify(message.tool_calls).slice(0, 500) : null,
+    toolCallId: message.tool_call_id || null,
+    timestamp: now.slice(0, 16), // Use timestamp to minute precision for grouping
+  });
+
+  let hash = 0;
+  for (let i = 0; i < contentForHash.length; i++) {
+    const char = contentForHash.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash = hash & hash;
+  }
+  const idBase = Math.abs(hash).toString(36);
+  const randomSuffix = generateId(4);
+  const id = `msg_${idBase}_${randomSuffix}`;
+
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      // Idempotency: skip if a previous retry already inserted this message
+      const existing = await db.select({
+        id: messages.id,
+      }).from(messages).where(eq(messages.id, id)).get();
+
+      if (existing) {
+        // Message already exists (previous retry succeeded), skip
+        return;
+      }
+
+      // Get max sequence
+      const maxSeqResult = await db.select({
+        maxSeq: sql<number>`max(${messages.sequence})`,
+      }).from(messages).where(eq(messages.threadId, threadId)).get();
+
+      const nextSequence = (maxSeqResult?.maxSeq ?? -1) + 1;
+
+      const toolCallsStr = message.tool_calls ? JSON.stringify(message.tool_calls) : null;
+      const metadataStr = JSON.stringify(metadata || {});
+
+      let r2Key: string | null = null;
+      let contentForD1 = message.content;
+      let toolCallsForD1: string | null = toolCallsStr;
+      let metadataForD1 = metadataStr;
+
+      const offloadBucket = env.TAKOS_OFFLOAD;
+      if (offloadBucket && shouldOffloadMessage({ role: message.role as MessageRole, content: message.content })) {
+        try {
+          const { key } = await writeMessageToR2(offloadBucket, threadId, id, {
+            id,
+            thread_id: threadId,
+            role: message.role as MessageRole,
+            content: message.content,
+            tool_calls: toolCallsStr,
+            tool_call_id: message.tool_call_id || null,
+            metadata: metadataStr,
+            sequence: nextSequence,
+            created_at: now,
+          });
+          r2Key = key;
+          contentForD1 = makeMessagePreview(message.content);
+          toolCallsForD1 = null;
+          // Keep D1 small; hydrate from R2 on reads.
+          metadataForD1 = '{}';
+        } catch (err) {
+          logWarn(`Failed to persist message ${id} to R2, storing inline`, { module: 'message_offload', detail: err });
+        }
+      }
+
+      await db.insert(messages).values({
+        id,
+        threadId,
+        role: message.role,
+        content: contentForD1,
+        r2Key,
+        toolCalls: toolCallsForD1,
+        toolCallId: message.tool_call_id || null,
+        metadata: metadataForD1,
+        sequence: nextSequence,
+        createdAt: now,
+      });
+
+      return; // Success
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+
+      // Duplicate ID means a previous retry already succeeded
+      if (errorMessage.includes('UNIQUE constraint') && errorMessage.includes('id')) {
+        return;
+      }
+
+      // Check if it's a sequence conflict (need to retry with new sequence)
+      const isSequenceConflict = errorMessage.includes('UNIQUE constraint');
+      const isRetryable = isSequenceConflict || errorMessage.includes('SQLITE_BUSY');
+
+      if (isRetryable && attempt < maxRetries - 1) {
+        const exponentialDelay = Math.min(maxDelayMs, baseDelayMs * Math.pow(2, attempt));
+        const jitter = Math.random() * exponentialDelay;
+        const totalDelay = Math.floor(exponentialDelay + jitter);
+
+        if (attempt >= 2) {
+          logWarn(`Message sequence conflict on attempt ${attempt + 1}/${maxRetries}, ` +
+            `retrying in ${totalDelay}ms (thread: ${threadId})`, { module: 'services/agent/message-persistence' });
+        }
+
+        await new Promise(resolve => setTimeout(resolve, totalDelay));
+        continue;
+      }
+
+      if (attempt === maxRetries - 1) {
+        logError(`Message insert failed after ${maxRetries} attempts: ${errorMessage}`, { threadId, role: message.role }, { module: 'services/agent/message-persistence' });
+      }
+
+      throw error;
+    }
+  }
+
+  throw new Error(
+    `Failed to add message after ${maxRetries} attempts due to sequence conflicts. ` +
+    `This may indicate very high concurrency on thread ${threadId}.`
+  );
+}