@ziggs-ai/agent-sdk 0.1.3

package/src/cognition/PromptBuilder.js

@@ -0,0 +1,312 @@
+import { HistoryFormatter, TaskFormatter } from '../formatters/index.js';
+import { resolveActionTool } from './resolveActionTool.js';
+
+/**
+ * Builds agent prompts from state/action definitions (`buildFromState`).
+ *
+ * Prompt structure:
+ *   <agent>
+ *     <self>identity + state prompt</self>
+ *     <world>event + history + tasks + recipients</world>
+ *     <decision_schema>actions with prompts</decision_schema>
+ *   </agent>
+ */
+export class PromptBuilder {
+  constructor(options = {}) {
+    this.description = options.description || 'A capable agent ready to assist';
+    this.specialization = options.specialization || null;
+    this.maxHistoryEntries = options.maxHistoryEntries ?? 50;
+    this.historyFormatter = options.historyFormatter || new HistoryFormatter();
+    this.taskFormatter = options.taskFormatter || new TaskFormatter();
+  }
+
+  buildFromState({
+    statePrompt, actions, serverContext, incomingEvent, definition, chatId,
+    stateId, machineContext,
+  }) {
+    const ctx = serverContext?.context || serverContext || {};
+    const agentId = this._getMyAgentId(ctx);
+    const senderMeta = this._getSenderMeta(incomingEvent, ctx);
+    const allTasks = ctx.activeTasks || [];
+    const otherAgents = (ctx.agents || []).filter(a => !a.isYou);
+    const users = ctx.users || [];
+    const desc = definition?.description || this.description;
+
+    const prompt = `<agent>
+
+${this._renderSelfFromState(desc, statePrompt, serverContext?.tools)}
+
+${this._renderWorld(incomingEvent, ctx, agentId, senderMeta, allTasks, otherAgents, users, stateId, machineContext)}
+
+${this._renderDecisionSchemaFromActions(actions, senderMeta, ctx)}
+
+</agent>`;
+
+    return prompt;
+  }
+
+  _renderSelfFromState(description, statePrompt, tools) {
+    const lines = ['<self>'];
+    lines.push(`<identity>\nYou are an Autonomous Agent.\n${description}\n</identity>`);
+
+    lines.push('\n<state>');
+    if (statePrompt.role) lines.push(`Role: ${statePrompt.role}`);
+    if (statePrompt.goal) lines.push(`Goal: ${statePrompt.goal}`);
+    if (statePrompt.context) lines.push(`Context: ${statePrompt.context}`);
+    if (statePrompt.constraints) lines.push(`Constraints: ${statePrompt.constraints}`);
+    lines.push('</state>');
+
+    if (tools?.length) {
+      lines.push('\n<tools>');
+      for (const tool of tools) {
+        const fn = tool.schema?.function || tool.schema;
+        const name = fn?.name;
+        const desc = fn?.description;
+        if (name) lines.push(`- ${name}${desc ? ': ' + desc : ''}`);
+      }
+      lines.push('</tools>');
+    }
+
+    lines.push('</self>');
+    return lines.join('\n');
+  }
+
+  _renderWorld(event, ctx, agentId, senderMeta, allTasks, otherAgents, users, stateId, machineContext) {
+    const lines = ['<world>'];
+
+    const machineBlock = this._renderMachineContext(stateId, machineContext);
+    if (machineBlock) {
+      lines.push(machineBlock);
+      lines.push('');
+    }
+
+    lines.push(this._renderEvent(event, senderMeta));
+    lines.push('');
+    lines.push(this._renderHistory(ctx.history, agentId));
+    lines.push('');
+    lines.push(this._renderTasks(allTasks, agentId));
+
+    if (users.length > 0 || otherAgents.length > 0) {
+      lines.push('');
+      lines.push(this._renderRecipients(users, otherAgents));
+    }
+
+    lines.push(`\n<context>\n  currentTime: ${new Date().toISOString()}\n</context>`);
+    lines.push('</world>');
+    return lines.join('\n');
+  }
+
+  _renderMachineContext(stateId, machineContext) {
+    const picked = pickAllowedMachineFields(stateId, machineContext);
+    if (!picked) return '';
+    const json = JSON.stringify(picked, null, 2);
+    return `<machine_context>\n${json}\n</machine_context>`;
+  }
+
+  _renderEvent(event, senderMeta) {
+    if (!event) return '<event type="none">No incoming event.</event>';
+
+    if (event.type === 'batch' && Array.isArray(event.events) && event.events.length > 0) {
+      const parts = event.events.map((e, i) => {
+        const sub = { ...senderMeta, senderId: e.senderId ?? senderMeta.senderId, senderType: e.senderType ?? senderMeta.senderType };
+        return (i > 0 ? '\n---\n' : '') + this._renderEvent(e, sub);
+      });
+      return `<event type="batch" count="${event.events.length}">\n${parts.join('')}\n</event>`;
+    }
+
+    const eventType = event.type || 'message';
+    const from = `${senderMeta.senderId} (${(senderMeta.senderType || 'unknown').toLowerCase()})`;
+
+    if (eventType === 'task_result' && event.result?.taskId) {
+      return this._renderTaskResultEvent(event.result, from);
+    }
+    if (eventType === 'tool_result') {
+      const r = typeof event.result === 'object' ? JSON.stringify(event.result, null, 2) : String(event.result);
+      return `<event type="${eventType}" from="${from}">\nTool: ${event.tool}\nResult:\n${r}\n</event>`;
+    }
+    if (eventType === 'tool_error') {
+      return `<event type="${eventType}" from="${from}">\nTool Error: ${event.tool}\nMessage: ${event.error}\n</event>`;
+    }
+    if (eventType === 'message_sent') {
+      return `<event type="${eventType}" from="${from}">\nYour message was delivered. Do not repeat it.\n</event>`;
+    }
+
+    const content = event.text || event.result || event.content;
+    if (!content) return `<event type="${eventType}" from="${from}">(Empty)</event>`;
+    const str = typeof content === 'object' ? JSON.stringify(content) : content;
+    const display = str.length > 1000 ? str.slice(0, 1000) + '...' : str;
+    return `<event type="${eventType}" from="${from}">\n${display}\n</event>`;
+  }
+
+  _renderTaskResultEvent(task, from) {
+    const lines = [];
+    if (task.agentIdIsYou) { lines.push('YOUR TASK'); lines.push(''); }
+    lines.push(`Task: ${task.description}`);
+    lines.push(`ID: ${task.taskId}`);
+    lines.push(`State: ${task.state}`);
+    lines.push(`Owner: ${task.agentId}${task.agentIdIsYou ? ' (You)' : ''}`);
+    lines.push(`Executor: ${task.executorId}${task.executorIdIsYou ? ' (You)' : ''}`);
+    if (task.proposal) {
+      lines.push(`Proposal: ${task.proposal.status} (to ${task.proposal.proposedTo}${task.proposedToIsYou ? ' - You' : ''})`);
+    }
+    if (task.parentTaskId) lines.push(`Parent: ${task.parentTaskId}`);
+
+    if (task.contract?.specialistAgentId) {
+      lines.push(`contract.specialistAgentId: ${task.contract.specialistAgentId}`);
+    }
+    if (Array.isArray(task.contract?.specialistAgentIds) && task.contract.specialistAgentIds.length > 0) {
+      lines.push(`contract.specialistAgentIds: ${task.contract.specialistAgentIds.join(', ')}`);
+    }
+
+    if (task.state === 'proposal' && task.proposal?.status === 'pending' && (task.proposedToIsYou || task.proposal?.proposedTo === 'everyone')) {
+      lines.push('');
+      lines.push(`Action: Use task_respond_proposal with taskId="${task.taskId}" and action approve or reject.`);
+    }
+
+    return `<event type="task_result" from="${from}"${task.agentIdIsYou ? ' own_task="true"' : ''}>\n${lines.join('\n')}\n</event>`;
+  }
+
+  _renderHistory(history, agentId) {
+    let entries = history || [];
+    let truncNote = '';
+    if (entries.length > this.maxHistoryEntries) {
+      truncNote = `[Showing last ${this.maxHistoryEntries} of ${entries.length} entries]\n\n`;
+      entries = entries.slice(-this.maxHistoryEntries);
+    }
+    const formatted = this.historyFormatter.format(entries, agentId, {});
+    return `<history>\n${truncNote}${formatted}\n</history>`;
+  }
+
+  _renderTasks(tasks, agentId) {
+    const formatted = this.taskFormatter.format(tasks || [], agentId);
+    return `<tasks>\n${formatted}\n</tasks>`;
+  }
+
+  _renderRecipients(users, otherAgents) {
+    const lines = ['<recipients>'];
+    if (users.length > 0) {
+      lines.push('<users>');
+      users.forEach(u => lines.push(`  - ${u.userName || u.userId} (${u.userId})`));
+      lines.push('</users>');
+    }
+    if (otherAgents.length > 0) {
+      lines.push('<agents>');
+      otherAgents.forEach(a => {
+        const desc = a.description ? `: ${a.description.slice(0, 80)}` : '';
+        const caps = a.capabilities && Object.keys(a.capabilities).length > 0
+          ? ` [capabilities: ${JSON.stringify(a.capabilities)}]`
+          : '';
+        lines.push(`  - ${a.name || a.agentId} (${a.agentId})${desc}${caps}`);
+      });
+      lines.push('</agents>');
+    }
+    if (users.length === 0 && otherAgents.length === 0) {
+      lines.push('No other recipients available.');
+    }
+    lines.push('</recipients>');
+    return lines.join('\n');
+  }
+
+  _renderDecisionSchemaFromActions(actions, senderMeta, ctx) {
+    const lines = ['<decision_schema>'];
+    lines.push('Return ONE JSON object. ALWAYS include "thought" as the FIRST field — briefly explain your reasoning before choosing an action.');
+    lines.push('Set "action" to exactly one of the action names below.\n');
+
+    const replyTo = senderMeta.defaultReplyReceiverId || '<receiverId>';
+    const pendingProposals = (ctx.activeTasks || []).filter(
+      t => t.state === 'proposal' && t.proposal?.status === 'pending' && (t.proposedToIsYou || t.proposal?.proposedTo === 'everyone')
+    );
+
+    if (pendingProposals.length > 0) {
+      lines.push(`PRIORITY: You have ${pendingProposals.length} pending proposal(s) directed at you. Respond BEFORE other actions.`);
+      lines.push(`{"thought": "...", "action": "<action_bound_to_task_respond_proposal>", "args": {"taskId": "<id>", "action": "approve|reject"}}\n`);
+    }
+
+    for (const [name, actionDef] of Object.entries(actions)) {
+      lines.push(`─── "${name}" ───`);
+      if (actionDef.prompt?.when) lines.push(`Use when: ${actionDef.prompt.when}`);
+      if (actionDef.prompt?.instruction) lines.push(`Instruction: ${actionDef.prompt.instruction}`);
+      if (actionDef.prompt?.format) lines.push(`Format: ${actionDef.prompt.format}`);
+
+      const boundTool = resolveActionTool(actionDef, name);
+      if (boundTool) {
+        lines.push(`Tool: ${boundTool}`);
+        lines.push(`Response: {"thought": "...", "action": "${name}", "args": {...}}`);
+      } else {
+        lines.push(this._buildActionSchema(name, replyTo));
+      }
+
+      if (actionDef.prompt?.examples?.length) {
+        lines.push('Examples:');
+        for (const ex of actionDef.prompt.examples) {
+          const desc = ex.scenario || ex.input || '';
+          const out = ex.output || ex.query || '';
+          lines.push(`  - ${desc}${out ? ' → ' + out : ''}`);
+        }
+      }
+
+      lines.push('');
+    }
+
+    lines.push('</decision_schema>');
+    return lines.join('\n');
+  }
+
+  _buildActionSchema(name, replyTo) {
+    if (name === 'wait') {
+      return `Response: {"thought": "...", "action": "${name}"}`;
+    }
+    return `Response: {"thought": "...", "action": "${name}", "receiverId": "${replyTo}", "message": "..."}`;
+  }
+
+  _getSenderMeta(event, ctx) {
+    const senderId = event?.senderId || 'system';
+    const senderType = event?.senderType ? event.senderType.toUpperCase() : 'SYSTEM';
+    const myId = this._getMyAgentId(ctx);
+
+    let defaultReplyReceiverId = senderId;
+    const isNonRoutable = !senderId || senderId === 'system' || senderType === 'SERVICE';
+    if (isNonRoutable) {
+      const history = ctx.history || [];
+      for (let i = history.length - 1; i >= 0; i--) {
+        const id = history[i].sender?.id || history[i].senderId;
+        const type = (history[i].sender?.type || history[i].senderType || '').toUpperCase();
+        if (id && id !== 'system' && id !== myId && type !== 'SERVICE') {
+          defaultReplyReceiverId = id;
+          break;
+        }
+      }
+    }
+
+    return { senderId, senderType, myAgentId: myId, defaultReplyReceiverId: defaultReplyReceiverId || senderId };
+  }
+
+  _getMyAgentId(ctx) {
+    const agents = ctx.agents || [];
+    const me = agents.find(a => a.isYou);
+    return me?.agentId || null;
+  }
+}
+
+const MACHINE_CONTEXT_KEYS = [
+  'chatId', 'laneKey', 'ownAgentId', 'activeTaskId', 'pendingProposalId', 'perspectiveId',
+  'delegatedTaskIds', 'orchestrationSpecialistAgentId', 'orchestrationSpecialistAgentIds',
+  'orchestrationActiveStepIndex', 'orchestrationContinueChain', 'lastError', 'lastAction',
+];
+
+function pickAllowedMachineFields(stateId, machineContext) {
+  if (!machineContext || typeof machineContext !== 'object') {
+    return stateId != null ? { stateId } : null;
+  }
+  const out = {};
+  if (stateId != null) out.stateId = stateId;
+  for (const k of MACHINE_CONTEXT_KEYS) {
+    const v = machineContext[k];
+    if (v !== undefined && v !== null) out[k] = v;
+  }
+  if (machineContext.incomingEvent != null) {
+    const ev = machineContext.incomingEvent;
+    out.incomingEventType = typeof ev === 'object' && ev && ev.type != null ? String(ev.type) : '(present)';
+  }
+  return Object.keys(out).length ? out : null;
+}

package/src/cognition/resolveActionTool.js

@@ -0,0 +1,12 @@
+/**
+ * Each action may bind at most one registered tool. Args are chosen by the LLM;
+ * the tool name is fixed by the action definition's explicit `tool` property.
+ */
+
+export function resolveActionTool(actionDef, actionKey) {
+  if (!actionDef) return null;
+  if (actionDef.tool === null) return null;
+  if (typeof actionDef.tool === 'string') return actionDef.tool;
+  if (Array.isArray(actionDef.tools) && actionDef.tools.length >= 1) return actionDef.tools[0];
+  return null;
+}