@ziggs-ai/agent-sdk 0.1.3

package/src/cognition/runTurn.js

@@ -0,0 +1,578 @@
+/**
+ * Single LLM turn for a thinking state: read context → prompt → LLM → one action → effects.
+ */
+
+import { ContextProperties } from '../shared/types.js';
+import { generateId } from '../shared/ids.js';
+import { safeParseJSON } from '../utils/jsonExtractor.js';
+import { buildContextUpdates } from '../context/applyEffects.js';
+import { resolveActionTool } from './resolveActionTool.js';
+
+const MAX_TOOL_LOOP_ITERS = 20;
+
+const TASK_CREATION_TOOLS = new Set(['task_make_task', 'task_make_sub_tasks']);
+
+/**
+ * When the current workflow state has no action bound to this tool (e.g. agent_network in delegating),
+ * still execute — otherwise the model's tool call is dropped and delegation cannot recover.
+ */
+const GENERIC_FALLBACK_TOOLS = new Set(['agent_network', 'task_board']);
+
+/**
+ * Per assistant message: only one task-creation call; only one task_update_task per taskId.
+ * Models often emit duplicate task_update_task after a successful close → avoid double PATCH / errors.
+ */
+function annotateToolCallDedup(toolCalls) {
+  let sawTaskCreate = false;
+  const seenUpdateTaskIds = new Set();
+  return (toolCalls || []).map(tc => {
+    const name = tc?.function?.name;
+    if (name && TASK_CREATION_TOOLS.has(name)) {
+      if (sawTaskCreate) {
+        return {
+          tc,
+          skipExecute: true,
+          skipReason:
+            'duplicate task creation in same assistant message; only the first call was executed',
+        };
+      }
+      sawTaskCreate = true;
+      return { tc, skipExecute: false };
+    }
+    if (name === 'task_update_task') {
+      let taskId = null;
+      try {
+        const a = JSON.parse(tc.function.arguments || '{}');
+        taskId = typeof a.taskId === 'string' ? a.taskId : null;
+      } catch {}
+      const key = taskId || tc.id || '_';
+      if (seenUpdateTaskIds.has(key)) {
+        return {
+          tc,
+          skipExecute: true,
+          skipReason:
+            'duplicate task_update_task for the same taskId in one assistant message; only the first call was executed',
+        };
+      }
+      seenUpdateTaskIds.add(key);
+      return { tc, skipExecute: false };
+    }
+    return { tc, skipExecute: false };
+  });
+}
+
+function isTerminalPartial(partial) {
+  return Boolean(
+    partial?.delegatedTask ||
+      partial?.messageSent ||
+      partial?.activeWait ||
+      partial?.proposal,
+  );
+}
+
+function pickPrimaryUserIdFromContext(context) {
+  const users = context?.[ContextProperties.USERS] || [];
+  for (const u of users) {
+    const id = u?.userId || u?.id;
+    if (id && typeof id === 'string') return id;
+  }
+  const hist = context?.[ContextProperties.HISTORY] || [];
+  for (let i = hist.length - 1; i >= 0; i--) {
+    const row = hist[i];
+    const type = String(row?.sender?.type || row?.senderType || '').toUpperCase();
+    const id = row?.sender?.id ?? row?.senderId;
+    if (type === 'USER' && id) return id;
+  }
+  return null;
+}
+
+function shouldEchoToolSummaryToUser(result) {
+  if (!result || typeof result !== 'object') return false;
+  if (typeof result.message !== 'string' || !result.message.trim()) return false;
+  if (result.success === false) return false;
+  if (result.error) return false;
+  return true;
+}
+
+/**
+ * Tools may set `echoUserSummaryOnSuccess` (via defineTool 4th arg). If the model sent no
+ * chat this turn, mirror the tool's `result.message` to the user once (last matching tool wins).
+ */
+async function echoOptInToolSummaryIfNeeded({
+  allEmittedEvents,
+  messageSender,
+  chatId,
+  context,
+  toolManager,
+}) {
+  if (!messageSender || !chatId || !context || !toolManager?.getTool) return;
+  if (allEmittedEvents.some(e => e?.type === 'message_sent')) return;
+
+  let summary = null;
+  let toolName = null;
+  for (const ev of allEmittedEvents) {
+    if (ev?.type !== 'tool_result' || !ev.tool) continue;
+    const reg = toolManager.getTool(ev.tool);
+    if (!reg?.echoUserSummaryOnSuccess) continue;
+    if (!shouldEchoToolSummaryToUser(ev.result)) continue;
+    summary = ev.result.message.trim();
+    toolName = ev.tool;
+  }
+  if (!summary) return;
+
+  const receiverId = pickPrimaryUserIdFromContext(context);
+  if (!receiverId) return;
+
+  const max = 3500;
+  const safe = summary.length > max ? `${summary.slice(0, max)}\n\n[truncated]` : summary;
+  try {
+    await messageSender(safe, receiverId, chatId);
+  } catch (e) {
+    console.warn(`[runTurn] echoUserSummaryOnSuccess send failed: ${e?.message || e}`);
+    return;
+  }
+  console.log(`[runTurn] echoed result.message (echoUserSummaryOnSuccess, tool=${toolName})`);
+  allEmittedEvents.push({
+    type: 'message_sent',
+    receiverId,
+    chatId,
+    message: safe,
+    senderId: 'system',
+  });
+}
+
+export async function runTurn(input) {
+  const {
+    stateId, statePrompt, actions,
+    chatId, incomingEvent, machineContext,
+    _services, _definition,
+  } = input;
+
+  const {
+    llm, toolManager,
+    contextReader, contextWriter, taskService,
+    messageSender, messageBuffer, promptBuilder,
+    operatorKey, agentId,
+  } = _services;
+
+  console.log(`[runTurn] enter state=${stateId}`);
+
+  const serverContext = await readServerContext({
+    chatId, contextReader, toolManager, messageBuffer, incomingEvent,
+  });
+
+  const prompt = buildDecisionPrompt({
+    statePrompt, actions, serverContext, incomingEvent, definition: _definition,
+    promptBuilder, chatId, stateId, machineContext,
+  });
+
+  // Build initial message array for the agentic loop.
+  // When tools are available let the model use tool_calls; only force JSON when there are no tools.
+  const systemContent = serverContext.tools.length > 0
+    ? 'You are a helpful AI agent. Use the available tools to complete your tasks. When you are finished using tools, respond with a valid JSON decision object.'
+    : 'Respond with valid JSON.';
+  const messages = [
+    { role: 'system', content: systemContent },
+    { role: 'user', content: prompt },
+  ];
+
+  const allEmittedEvents = [];
+  let lastAction = null;
+  let llmCallsTotal = 0;
+  let tokensTotal = 0, tokensInput = 0, tokensOutput = 0;
+  const actionNames = Object.keys(actions);
+  const turnScratch = {};
+  const execServices = {
+    messageSender, toolManager, contextWriter, taskService, operatorKey, agentId, chatId,
+    agents: serverContext.context?.[ContextProperties.AGENTS] || [],
+    turnScratch,
+  };
+
+  console.log(`[runTurn] calling LLM... tools=${serverContext.tools.length}`, serverContext.tools.map(t => t.schema?.function?.name || t.name || 'unnamed'));
+
+  for (let iter = 0; iter < MAX_TOOL_LOOP_ITERS; iter++) {
+    console.log(`[runTurn] loop iter=${iter} start msgCount=${messages.length}`);
+    const llmResponse = await llm.chatMessages(messages, serverContext.tools);
+    llmCallsTotal++;
+    console.log(`[runTurn] loop iter=${iter} llm responded tool_calls=${!!llmResponse?.tool_calls?.length} content=${!!llmResponse?.content}`);
+    const usage = llmResponse?.usage;
+    tokensTotal  += (usage?.total_tokens  ?? usage?.totalTokens)  || 0;
+    tokensInput  += (usage?.prompt_tokens ?? usage?.promptTokens) || 0;
+    tokensOutput += (usage?.completion_tokens ?? usage?.completionTokens) || 0;
+
+    if (llmResponse?.tool_calls?.length) {
+      // Record LLM reasoning text (content alongside tool_calls) as a thought.
+      // This is what produces "many thinkings in a row" — one per loop iteration.
+      if (llmResponse.content && contextWriter && chatId) {
+        try { await contextWriter.recordThought(chatId, llmResponse.content); } catch {}
+      }
+
+      // — tool call path — execute in assistant-message order (turnScratch + propose→search ordering)
+      const tcs = llmResponse.tool_calls;
+      if (tcs.length > 1) {
+        console.log(`[runTurn] iter=${iter} executing ${tcs.length} tool_calls sequentially`);
+      }
+
+      const annotated = annotateToolCallDedup(tcs);
+      const dupCount = annotated.filter(a => a.skipExecute).length;
+      if (dupCount > 0) {
+        console.warn(
+          `[runTurn] iter=${iter} skipping ${dupCount} duplicate tool call(s) in same message (task create/update dedup)`,
+        );
+      }
+
+      // Append assistant message with all tool_calls
+      messages.push({ role: 'assistant', tool_calls: tcs });
+
+      const toolCallResults = [];
+      for (const ann of annotated) {
+        const { tc, skipExecute, skipReason } = ann;
+        if (skipExecute) {
+          toolCallResults.push({ tc, matchingAction: null, result: null, skippedDuplicate: true, skipReason });
+          continue;
+        }
+        const toolName = tc?.function?.name;
+        if (!toolName) {
+          toolCallResults.push({ tc, matchingAction: null, result: null });
+          continue;
+        }
+
+        let matchingAction = findActionForTool(toolName, actionNames, actions);
+        let actionDef = matchingAction ? actions[matchingAction] : null;
+
+        if (!matchingAction && GENERIC_FALLBACK_TOOLS.has(toolName) && toolManager.getTool?.(toolName)) {
+          matchingAction = '_genericDiscoveryTool';
+          actionDef = null;
+          console.log(
+            `[runTurn] iter=${iter} tool "${toolName}" — no state action bound; executing as discovery helper`,
+          );
+        } else if (!matchingAction) {
+          console.log(`[runTurn] iter=${iter} tool "${toolName}" not bound to any action — skipping`);
+          toolCallResults.push({ tc, matchingAction: null, result: null });
+          continue;
+        }
+
+        let args = {};
+        try { args = JSON.parse(tc.function.arguments || '{}'); } catch {}
+        const decision = { action: matchingAction, tool: toolName, args, thought: `Using tool: ${toolName}` };
+
+        console.log(`[runTurn] iter=${iter} action=${matchingAction} (tool_call_id=${tc.id})`);
+        const result = await executeDecision(decision, actionDef, execServices);
+        toolCallResults.push({ tc, matchingAction, result });
+      }
+
+      // Add tool response messages for ALL tool_calls (required by OpenAI)
+      let hasTerminal = false;
+      for (const item of toolCallResults) {
+        const { tc, matchingAction, result, skippedDuplicate, skipReason } = item;
+        if (skippedDuplicate) {
+          messages.push({
+            role: 'tool',
+            tool_call_id: tc.id,
+            content: JSON.stringify({ skipped: true, reason: skipReason || 'deduplicated' }),
+          });
+          continue;
+        }
+        if (!matchingAction || !result) {
+          messages.push({ role: 'tool', tool_call_id: tc.id, content: '{"error":"unknown tool or no result"}' });
+          continue;
+        }
+
+        const events = Array.isArray(result) ? result : [result];
+        allEmittedEvents.push(...events);
+        lastAction = matchingAction;
+
+        const firstEvent = events[0] || {};
+        const toolResultContent = JSON.stringify(firstEvent.result ?? firstEvent);
+        messages.push({ role: 'tool', tool_call_id: tc.id, content: toolResultContent });
+
+        const partial = buildContextUpdates(matchingAction, events);
+        if (isTerminalPartial(partial)) {
+          hasTerminal = true;
+        }
+      }
+
+      if (hasTerminal) {
+        console.log(`[runTurn] iter=${iter} terminal event detected, ending loop`);
+        break;
+      }
+      console.log(`[runTurn] iter=${iter} all tool_calls processed — continuing loop`);
+      // Remind the LLM to output a JSON decision now that tools have run.
+      // This user-role injection is more reliable than the system message alone
+      // because it appears as the most recent instruction in the message history.
+      messages.push({ role: 'user', content: 'Tools done. Return your JSON decision now (follow the decision_schema). Do not write prose.' });
+
+    } else {
+      // — non-tool (JSON) response path —
+      const decision = parseLLMDecision(llmResponse, actionNames, actions);
+      if (!decision) {
+        console.log(`[runTurn] iter=${iter} no parseable decision`);
+        break;
+      }
+      const chosenAction = decision.action;
+      const actionDef = actions[chosenAction];
+      applyActionToolBinding(decision, actionDef);
+      console.log(`[runTurn] iter=${iter} action=${chosenAction}`);
+      lastAction = chosenAction;
+
+      const result = await executeDecision(decision, actionDef, execServices);
+      if (result) {
+        const events = Array.isArray(result) ? result : [result];
+        allEmittedEvents.push(...events);
+
+        // If the action had a tool binding, inject the result and continue the loop
+        // (LLM responded with JSON instead of tool_calls due to prompt wording)
+        const boundTool = resolveActionTool(actionDef, chosenAction);
+        if (boundTool) {
+          const firstEvent = events[0] || {};
+          const toolResultContent = JSON.stringify(firstEvent.result ?? firstEvent);
+          messages.push({ role: 'assistant', content: llmResponse.content });
+          messages.push({ role: 'user', content: `Tool "${boundTool}" result:\n${toolResultContent}\n\nContinue with your next action.` });
+
+          const partial = buildContextUpdates(chosenAction, events);
+          console.log(`[runTurn] iter=${iter} (json-tool) terminal check: delegatedTask=${!!partial.delegatedTask} messageSent=${!!partial.messageSent} activeWait=${!!partial.activeWait} proposal=${!!partial.proposal}`);
+          if (isTerminalPartial(partial)) {
+            console.log(`[runTurn] iter=${iter} terminal event detected, ending loop`);
+            break;
+          }
+          console.log(`[runTurn] iter=${iter} json-tool result injected — continuing loop`);
+          continue;
+        }
+      }
+      if (decision.thought && contextWriter && chatId) {
+        try { await contextWriter.recordThought(chatId, decision.thought); } catch {}
+      }
+      break; // non-tool-bound response ends the loop
+    }
+  }
+
+  await echoOptInToolSummaryIfNeeded({
+    allEmittedEvents,
+    messageSender,
+    chatId,
+    context: serverContext.context,
+    toolManager,
+  });
+
+  const contextUpdates = buildContextUpdates(lastAction, allEmittedEvents);
+  console.log(`[runTurn] done state=${stateId} lastAction=${lastAction} events=${allEmittedEvents.length} llmCalls=${llmCallsTotal}`);
+
+  if (_services.telemetryClient) {
+    _services.telemetryClient.send({
+      source: 'agent',
+      chatId,
+      execution: {
+        executionLoops: llmCallsTotal,
+        llmCallsTotal,
+        tokensTotal,
+        tokensInput,
+        tokensOutput,
+      },
+      meta: { stateId, action: lastAction },
+    }).catch(() => {});
+  }
+
+  return { contextUpdates };
+}
+
+async function readServerContext({ chatId, contextReader, toolManager, messageBuffer, incomingEvent }) {
+  const [rawContext, tools] = await Promise.all([
+    contextReader.read(chatId, {}),
+    toolManager?.getAvailableTools?.() ?? Promise.resolve([]),
+  ]);
+
+  let context = rawContext;
+  if (!context || typeof context !== 'object') {
+    context = {
+      [ContextProperties.HISTORY]: [],
+      [ContextProperties.ACTIVE_TASKS]: [],
+      [ContextProperties.AGENTS]: [],
+      [ContextProperties.USERS]: [],
+    };
+  }
+  for (const key of [ContextProperties.HISTORY, ContextProperties.ACTIVE_TASKS, ContextProperties.AGENTS, ContextProperties.USERS]) {
+    if (!Array.isArray(context[key])) context[key] = [];
+  }
+
+  const agentId = context[ContextProperties.AGENTS]?.find(a => a.isYou)?.agentId || null;
+  if (messageBuffer) {
+    messageBuffer.merge(chatId, context[ContextProperties.HISTORY], agentId);
+  }
+
+  return { context, tools };
+}
+
+function buildDecisionPrompt({
+  statePrompt, actions, serverContext, incomingEvent, definition, promptBuilder, chatId,
+  stateId, machineContext,
+}) {
+  if (typeof promptBuilder?.buildFromState !== 'function') {
+    throw new Error('[runTurn] promptBuilder.buildFromState is required');
+  }
+  return promptBuilder.buildFromState({
+    statePrompt, actions, serverContext, incomingEvent, definition, chatId,
+    stateId, machineContext,
+  });
+}
+
+function applyActionToolBinding(decision, actionDef) {
+  if (!resolveActionTool(actionDef, decision.action)) return;
+  if (decision.args == null && decision.toolArgs != null) decision.args = decision.toolArgs;
+}
+
+function parseLLMDecision(llmResponse, allowedActionNames, actions = {}) {
+  if (llmResponse?.tool_calls?.length) {
+    const n = llmResponse.tool_calls.length;
+    if (n > 1) {
+      // Multiple tool_calls per turn are not supported. Only the first is executed;
+      // the rest are silently dropped, which means parts of the user's request will be lost.
+      // If this error appears, fix the state prompt to instruct the LLM to consolidate
+      // all tasks into a single tool call instead of returning multiple.
+      console.error(`[runTurn] LLM returned ${n} tool_calls but only the first will be executed — the remaining ${n - 1} are dropped. Fix the prompt to prevent this.`);
+    }
+    const tc = llmResponse.tool_calls[0];
+    if (!tc?.function?.name) return null;
+    let args = {};
+    try { args = JSON.parse(tc.function.arguments || '{}'); } catch {}
+
+    const matchingAction = findActionForTool(tc.function.name, allowedActionNames, actions);
+    if (!matchingAction) {
+      console.log(`[runTurn] tool_calls: no action binds tool "${tc.function.name}"`);
+      return null;
+    }
+    return {
+      thought: `Using tool: ${tc.function.name}`,
+      action: matchingAction,
+      tool: tc.function.name,
+      args,
+    };
+  }
+
+  const parsed = safeParseJSON(llmResponse?.content, null);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return null;
+  }
+
+  if (!parsed.action || !allowedActionNames.includes(parsed.action)) {
+    console.log('[runTurn] missing or unknown action in JSON response');
+    return null;
+  }
+
+  return parsed;
+}
+
+function findActionForTool(toolName, allowedActionNames, actions) {
+  if (!toolName) return null;
+  const byBinding = allowedActionNames.filter(
+    n => resolveActionTool(actions[n], n) === toolName
+  );
+  if (byBinding.length === 1) return byBinding[0];
+  if (byBinding.length > 1) {
+    console.log(`[runTurn] ambiguous: ${byBinding.length} actions bind tool "${toolName}"`);
+    return null;
+  }
+  return null;
+}
+
+async function executeDecision(decision, actionDef, services) {
+  const { messageSender, toolManager, contextWriter, taskService, operatorKey, agentId, chatId, agents, turnScratch } = services;
+
+  const boundTool = actionDef ? resolveActionTool(actionDef, decision.action) : null;
+
+  if (boundTool) {
+    decision.tool = boundTool;
+    return await executeTool(decision, toolManager, contextWriter, operatorKey, agentId, chatId, taskService, agents, turnScratch);
+  }
+
+  if (decision.action === '_genericDiscoveryTool' && decision.tool) {
+    return await executeTool(decision, toolManager, contextWriter, operatorKey, agentId, chatId, taskService, agents, turnScratch);
+  }
+
+  if (decision.tool) {
+    return await executeTool(decision, toolManager, contextWriter, operatorKey, agentId, chatId, taskService, agents, turnScratch);
+  }
+
+  if (decision.messages && Array.isArray(decision.messages) && decision.messages.length > 0) {
+    return await executeSendMessages(decision, messageSender, chatId);
+  }
+
+  if (decision.message && decision.receiverId) {
+    return await executeSendMessage(decision, messageSender, chatId);
+  }
+
+  if (decision.action === 'wait') {
+    return { type: 'waited' };
+  }
+
+  return null;
+}
+
+const MAX_MSG_CHARS = 3500;
+
+function truncateMsg(msg) {
+  if (typeof msg !== 'string') return msg;
+  return msg.length > MAX_MSG_CHARS ? msg.slice(0, MAX_MSG_CHARS) + '\n\n[truncated]' : msg;
+}
+
+async function executeSendMessage(decision, messageSender, chatId) {
+  const { message, receiverId } = decision;
+  if (!message || !receiverId) return null;
+
+  const targetChatId = decision.chatId || chatId;
+  const safeMessage = truncateMsg(message);
+
+  if (messageSender) {
+    await messageSender(safeMessage, receiverId, targetChatId);
+  }
+
+  const events = [{ type: 'message_sent', receiverId, chatId: targetChatId, message: safeMessage, senderId: 'system' }];
+  if (targetChatId !== chatId) {
+    events.push({ type: 'report_sent', message: 'Reported to owner.', senderId: 'system' });
+  }
+  return events;
+}
+
+async function executeSendMessages(decision, messageSender, chatId) {
+  const events = [];
+  for (const msg of decision.messages) {
+    if (!msg.receiverId || !msg.message) continue;
+    const targetChatId = msg.chatId || chatId;
+    const safeMessage = truncateMsg(msg.message);
+    if (messageSender) {
+      try { await messageSender(safeMessage, msg.receiverId, targetChatId); } catch (e) {
+        console.log('[runTurn] send failed:', e.message);
+        continue;
+      }
+    }
+    events.push({ type: 'message_sent', receiverId: msg.receiverId, chatId: targetChatId, message: safeMessage, senderId: 'system' });
+    if (targetChatId !== chatId) {
+      events.push({ type: 'report_sent', message: 'Reported to owner.', senderId: 'system' });
+    }
+  }
+  return events;
+}
+
+async function executeTool(decision, toolManager, contextWriter, operatorKey, agentId, chatId, taskService, agents, turnScratch) {
+  const { tool, args } = decision;
+  if (!tool) return null;
+
+  const operationId = generateId();
+  try {
+    await contextWriter?.recordOperation(chatId, { operationId, type: 'tool', tool, args: args || {}, state: 'started' });
+  } catch {}
+
+  try {
+    const result = await toolManager.executeTool(tool, args || {}, {
+      operatorKey, agentId, chatId, taskService, agents, turnScratch,
+    });
+    try {
+      await contextWriter?.recordOperation(chatId, { operationId, type: 'tool', tool, args: args || {}, result, state: 'completed' });
+    } catch {}
+    return { type: 'tool_result', operationId, tool, result, senderId: 'system' };
+  } catch (error) {
+    try {
+      await contextWriter?.recordOperation(chatId, { operationId, type: 'tool', tool, args: args || {}, error: error.message, state: 'failed' });
+    } catch {}
+    return { type: 'tool_error', operationId, tool, error: error.message, senderId: 'system' };
+  }
+}