@ziggs-ai/agent-sdk 0.1.3 → 0.1.5

package/src/runtime/PromptBuilder.ts

@@ -0,0 +1,463 @@
+import type { Action, Ctx, PromptDef } from '../types.js';
+import { HistoryFormatter, AgreementFormatter } from '../formatters/index.js';
+import { validateContext } from '../cognition/validateContext.js';
+import type { RawEvent } from './buildOutcome.js';
+
+type AnyObj = Record<string, unknown>;
+
+interface ServerContext {
+  history?: AnyObj[];
+  agreements?: AnyObj[];
+  agents?: AnyObj[];
+  users?: AnyObj[];
+  [key: string]: unknown;
+}
+
+interface ServerContextBundle {
+  context: ServerContext;
+  tools: AnyObj[];
+}
+
+interface SenderMeta {
+  senderId?: string;
+  senderType?: string;
+  [key: string]: unknown;
+}
+
+interface BuildArgs {
+  statePrompt: PromptDef;
+  actions: Record<string, Action>;
+  serverContext: ServerContextBundle;
+  incomingEvent: RawEvent | null;
+  definition: { description?: string };
+  chatId: string | null;
+  stateId: string;
+  ctx: Ctx;
+  /** When true, respond-action schemas omit the "message" field — used for 2-call streaming (ZIG-471). */
+  omitMessageFromRespond?: boolean;
+}
+
+interface HistoryFormatterI { format(history: unknown[] | null | undefined, agentId: string, options?: AnyObj): string; }
+interface AgreementFormatterI { format(agreements: unknown[] | null): string; }
+interface LoggerI { info?(...args: unknown[]): void; warn?(...args: unknown[]): void; debug?(...args: unknown[]): void; }
+
+export interface PromptBuilderOptions {
+  description?: string;
+  specialization?: string | null;
+  maxHistoryEntries?: number;
+  historyFormatter?: HistoryFormatterI;
+  agreementFormatter?: AgreementFormatterI;
+  logger?: LoggerI | null | { warn: (msg: string) => void };
+}
+
+/**
+ * Builds the XML prompt for a thinking-state turn:
+ *   <agent><self/><world/><decision_schema/></agent>
+ *
+ * Reads Ctx (identity + persistent ids + lastOutcome) for <machine_context>.
+ * Action tool binding is direct (action.tool). Decision schema documents the
+ * action's `produces` outcome kind.
+ */
+export class PromptBuilder {
+  description: string;
+  specialization: string | null;
+  maxHistoryEntries: number;
+  historyFormatter: HistoryFormatterI;
+  agreementFormatter: AgreementFormatterI;
+  logger: LoggerI | null;
+
+  constructor(options: PromptBuilderOptions = {}) {
+    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.agreementFormatter = (options.agreementFormatter || new AgreementFormatter()) as AgreementFormatterI;
+    this.logger = options.logger as LoggerI | null || null;
+  }
+
+  buildFromState(args: BuildArgs): string {
+    const { statePrompt, actions, serverContext, incomingEvent, definition, stateId, ctx, omitMessageFromRespond } = args;
+    const ctxObj = serverContext?.context || {};
+    validateContext(ctxObj, { logger: this.logger as { warn: (msg: string) => void } | undefined });
+
+    const agentId = this._getMyAgentId(ctxObj);
+    const senderMeta = this._getSenderMeta(incomingEvent, ctxObj);
+    const agreements = ctxObj.agreements || [];
+    const otherAgents = (ctxObj.agents || []).filter((a) => !a.isYou);
+    const users = ctxObj.users || [];
+    const desc = definition?.description || this.description;
+
+    return `<agent>
+
+${this._renderSelfFromState(desc, statePrompt, serverContext?.tools)}
+
+${this._renderWorld(incomingEvent, ctxObj, agentId, senderMeta, agreements, otherAgents, users, stateId, ctx)}
+
+${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessageFromRespond)}
+
+</agent>`;
+  }
+
+  _renderSelfFromState(description: string, statePrompt: PromptDef, tools?: AnyObj[]): string {
+    const lines: string[] = ['<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 toolAny = tool as AnyObj;
+        const fn = (toolAny.schema as AnyObj | undefined)?.function as AnyObj | undefined || toolAny.schema as AnyObj | undefined;
+        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: RawEvent | null,
+    ctxObj: ServerContext,
+    agentId: string | null,
+    senderMeta: SenderMeta,
+    agreements: AnyObj[],
+    otherAgents: AnyObj[],
+    users: AnyObj[],
+    stateId: string,
+    ctx: Ctx,
+  ): string {
+    const lines: string[] = ['<world>'];
+
+    const machineBlock = this._renderMachineContext(stateId, ctx);
+    if (machineBlock) {
+      lines.push(machineBlock);
+      lines.push('');
+    }
+
+    lines.push(this._renderEvent(event, senderMeta));
+    lines.push('');
+    lines.push(this._renderHistory(ctxObj.history, agentId));
+    lines.push('');
+    lines.push(this._renderAgreements(agreements));
+
+    if (users.length > 0 || otherAgents.length > 0) {
+      lines.push('');
+      lines.push(this._renderRecipients(users, otherAgents, agreements, agentId));
+    }
+
+    lines.push(`\n<context>\n  currentTime: ${new Date().toISOString()}\n</context>`);
+    lines.push('</world>');
+    return lines.join('\n');
+  }
+
+  _renderMachineContext(stateId: string, ctx: Ctx): string {
+    if (!ctx) return stateId ? `<machine_context>\n${JSON.stringify({ stateId }, null, 2)}\n</machine_context>` : '';
+    const out: Record<string, unknown> = { stateId };
+    if (ctx.identity?.sessionId) out.chatId = ctx.identity.sessionId;
+    if (ctx.identity?.laneKey) out.laneKey = ctx.identity.laneKey;
+    if (ctx.identity?.agentId) out.ownAgentId = ctx.identity.agentId;
+    if (ctx.activeAgreementId) out.activeAgreementId = ctx.activeAgreementId;
+    if (ctx.activeTaskId) out.activeTaskId = ctx.activeTaskId;
+    if (ctx.pendingProposalAgreementId) out.pendingProposalAgreementId = ctx.pendingProposalAgreementId;
+    if (ctx.delegatedAgreementIds?.length) out.delegatedAgreementIds = ctx.delegatedAgreementIds;
+    if (ctx.lastOutcome) out.lastOutcomeKind = ctx.lastOutcome.kind;
+    return `<machine_context>\n${JSON.stringify(out, null, 2)}\n</machine_context>`;
+  }
+
+  _renderEvent(event: RawEvent | AnyObj | null, senderMeta: SenderMeta): string {
+    if (!event) return '<event type="none">No incoming event.</event>';
+
+    const evAny = event as AnyObj;
+    if (evAny.type === 'batch' && Array.isArray(evAny.events) && (evAny.events as unknown[]).length > 0) {
+      const parts = (evAny.events as AnyObj[]).map((e: AnyObj, i: number) => {
+        const sub: SenderMeta = { ...senderMeta, senderId: (e.senderId ?? senderMeta.senderId) as string | undefined, senderType: (e.senderType ?? senderMeta.senderType) as string | undefined };
+        return (i > 0 ? '\n---\n' : '') + this._renderEvent(e, sub);
+      });
+      return `<event type="batch" count="${(evAny.events as unknown[]).length}">\n${parts.join('')}\n</event>`;
+    }
+
+    const eventType = String(evAny.type || 'message');
+    const from = `${senderMeta.senderId} (${String(senderMeta.senderType || 'unknown').toLowerCase()})`;
+
+    const result = evAny.result as AnyObj | undefined;
+    if (eventType === 'task_result' && result?.taskId) {
+      return this._renderTaskResultEvent(result, from);
+    }
+    if (eventType === 'tool_result') {
+      const r = typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result);
+      return `<event type="${eventType}" from="${from}">\nTool: ${evAny.tool}\nResult:\n${r}\n</event>`;
+    }
+    if (eventType === 'tool_error') {
+      return `<event type="${eventType}" from="${from}">\nTool Error: ${evAny.tool}\nMessage: ${evAny.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) : String(content);
+    const display = str.length > 1000 ? str.slice(0, 1000) + '...' : str;
+    return `<event type="${eventType}" from="${from}">\n${display}\n</event>`;
+  }
+
+  _renderTaskResultEvent(task: AnyObj, from: string): string {
+    const lines: string[] = [];
+    const ag = task.agreement as AnyObj | undefined;
+    const parties = (ag?.parties as AnyObj) || {};
+    const creatorIsYou = task.creatorIsYou;
+    const providerIsYou = task.providerIsYou;
+
+    if (ag?.agreementId) {
+      lines.push(`Agreement: ${ag.agreementId}${creatorIsYou ? ' (yours)' : ''}`);
+      lines.push(`  Creator: ${parties.creator ?? 'N/A'}${creatorIsYou ? ' (You)' : ''}`);
+      lines.push(`  Provider: ${parties.provider ?? 'N/A'}${providerIsYou ? ' (You)' : ''}`);
+      const proposal = ag.proposal as AnyObj | undefined;
+      if (proposal?.status) {
+        lines.push(`  Proposal: ${proposal.status} (to ${parties.proposedTo}${task.proposedToIsYou ? ' - You' : ''})`);
+      }
+      const money = ag.money as AnyObj | undefined;
+      if (typeof money?.price === 'number' && (money.price as number) > 0) {
+        lines.push(`  Price: ${money.price} cents (${money.paymentStatus})`);
+      }
+    }
+
+    lines.push('');
+    lines.push(`Task: ${task.taskId}`);
+    lines.push(`  Description: ${task.description}`);
+    lines.push(`  State: ${task.state}`);
+    if (task.parentTaskId) lines.push(`  Parent task: ${task.parentTaskId}`);
+
+    // Tasks are always born active in the new model. Proposal lifecycle lives
+    // only on the agreement; the prompt surfaces it through the <agreements>
+    // section, not via task state.
+    void ag;
+    void parties;
+
+    return `<event type="task_result" from="${from}"${creatorIsYou ? ' own_agreement="true"' : ''}>\n${lines.join('\n')}\n</event>`;
+  }
+
+  _renderHistory(history: AnyObj[] | undefined, agentId: string | null): string {
+    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>`;
+  }
+
+  _renderAgreements(agreements: AnyObj[]): string {
+    const formatted = this.agreementFormatter.format(agreements || []);
+    return `<agreements>\n${formatted}\n</agreements>`;
+  }
+
+  _renderRecipients(users: AnyObj[], otherAgents: AnyObj[], agreements: AnyObj[], myAgentId: string | null | undefined): string {
+    // <recipients> is grouped by surface so the LLM knows which ids it can use
+    // for each kind of action. Same id appears in multiple subsections when it
+    // participates in multiple surfaces. <users> / <agents> stay as the typed
+    // directory (existing prompts reference <recipients><users>); the new
+    // <chat>/<agreement>/<task>/<transfer> subsections narrow that directory
+    // to a specific action surface.
+    const userIds = new Set<string>();
+    const userLabels = new Map<string, string>();
+    for (const u of users) {
+      const id = u?.userId as string | undefined;
+      if (!id || id === myAgentId) continue;
+      userIds.add(id);
+      userLabels.set(id, u.userName ? `${u.userName} (${id})` : id);
+    }
+    const agentIds = new Set<string>();
+    const agentLabels = new Map<string, string>();
+    for (const a of otherAgents) {
+      const id = a?.agentId as string | undefined;
+      if (!id || id === myAgentId) continue;
+      agentIds.add(id);
+      const desc = typeof a.description === 'string' ? `: ${a.description.slice(0, 80)}` : '';
+      const name = a.name && a.name !== id ? `${a.name} (${id})` : id;
+      agentLabels.set(id, `${name}${desc}`);
+    }
+    const kindOf = (id: string): 'user' | 'agent' | 'unknown' =>
+      userIds.has(id) ? 'user' : agentIds.has(id) ? 'agent' : 'unknown';
+    const labelOf = (id: string): string =>
+      userLabels.get(id) ?? agentLabels.get(id) ?? id;
+    const tagged = (id: string): string => `${labelOf(id)} [${kindOf(id)}]`;
+
+    // Agreement parties — derived from current agreements, role-tagged.
+    type PartyHit = { agreementId: string; role: string };
+    const agreementParties = new Map<string, PartyHit[]>();
+    for (const ag of agreements || []) {
+      const agId = ag?.agreementId as string | undefined;
+      const parties = (ag?.parties as AnyObj) || {};
+      const roles: Array<[string, string]> = [
+        ['creator', 'creator'],
+        ['provider', 'provider'],
+        ['payer', 'payer'],
+        ['proposedTo', 'proposedTo'],
+      ];
+      for (const [field, role] of roles) {
+        const pid = parties[field] as string | undefined;
+        if (!pid || pid === myAgentId) continue;
+        if (!agreementParties.has(pid)) agreementParties.set(pid, []);
+        agreementParties.get(pid)!.push({ agreementId: agId ?? '', role });
+      }
+    }
+
+    // Chat and transfer surfaces default to the full directory: every chat
+    // counterparty can receive a chat message; every id can receive a transfer
+    // by their principal id until per-wallet routing is wired through.
+    const chatIds = new Set<string>([...userIds, ...agentIds]);
+    const transferIds = new Set<string>([...userIds, ...agentIds]);
+
+    const lines: string[] = ['<recipients>'];
+
+    lines.push('<users>');
+    if (userIds.size === 0) lines.push('  (none)');
+    else for (const id of userIds) lines.push(`  - ${userLabels.get(id)}`);
+    lines.push('</users>');
+
+    lines.push('<agents>');
+    if (agentIds.size === 0) lines.push('  (none)');
+    else for (const id of agentIds) lines.push(`  - ${agentLabels.get(id)}`);
+    lines.push('</agents>');
+
+    lines.push('<chat>');
+    if (chatIds.size === 0) lines.push('  (none)');
+    else for (const id of chatIds) lines.push(`  - ${tagged(id)}`);
+    lines.push('</chat>');
+
+    lines.push('<agreement>');
+    if (agreementParties.size === 0) lines.push('  (no agreement parties in this chat)');
+    else for (const [id, hits] of agreementParties) {
+      const tag = hits.map((h) => `${h.agreementId}:${h.role}`).join(', ');
+      lines.push(`  - ${tagged(id)} [${tag}]`);
+    }
+    lines.push('</agreement>');
+
+    lines.push('<task>');
+    if (agreementParties.size === 0) lines.push('  (no task parties in this chat)');
+    else for (const [id, hits] of agreementParties) {
+      const tag = hits.map((h) => `${h.agreementId}:${h.role}`).join(', ');
+      lines.push(`  - ${tagged(id)} [${tag}]`);
+    }
+    lines.push('</task>');
+
+    lines.push('<transfer>');
+    if (transferIds.size === 0) lines.push('  (none)');
+    else for (const id of transferIds) lines.push(`  - ${tagged(id)}`);
+    lines.push('</transfer>');
+
+    lines.push('</recipients>');
+    return lines.join('\n');
+  }
+
+  _renderDecisionSchemaFromActions(actions: Record<string, Action>, senderMeta: SenderMeta, ctxObj: ServerContext, omitMessage?: boolean): string {
+    const lines: string[] = ['<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.');
+    lines.push('Message text is rendered as markdown (CommonMark + GFM). You MAY use **bold**, *italic*, `code`, fenced code blocks, lists, links, and tables when they improve clarity — plain text is also fine.\n');
+
+    const replyTo = (senderMeta.defaultReplyReceiverId as string) || '<receiverId>';
+    const pendingProposals = (ctxObj.agreements || []).filter(
+      (a) => (a.proposal as Record<string, unknown> | undefined)?.status === 'pending' && (a.proposedToIsYou || (a.parties as Record<string, unknown> | undefined)?.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_agreement_respond>", "args": {"agreementId": "<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 = actionDef.tool ?? null;
+      if (boundTool) {
+        lines.push(`Tool: ${boundTool}`);
+        lines.push(`Response: {"thought": "...", "action": "${name}", "args": {...}}`);
+      } else {
+        lines.push(this._buildActionSchema(name, replyTo, omitMessage));
+      }
+
+      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: string, replyTo: string, omitMessage?: boolean): string {
+    if (name === 'wait') {
+      return `Response: {"thought": "...", "action": "${name}"}`;
+    }
+    // Never pre-fill a non-routable id (the literal 'system' or 'service'
+    // buckets) as the default receiverId. Fall back to an explicit placeholder
+    // so the model picks a real recipient from <recipients>.
+    const isSystemReplyTo =
+      !replyTo ||
+      replyTo === 'system' ||
+      replyTo === 'service' ||
+      replyTo.startsWith('<');
+    const renderedReplyTo = isSystemReplyTo ? '<receiverId from <recipients>>' : replyTo;
+    if (omitMessage) {
+      return `Response: {"thought": "...", "action": "${name}", "receiverId": "${renderedReplyTo}"}`;
+    }
+    return `Response: {"thought": "...", "action": "${name}", "receiverId": "${renderedReplyTo}", "message": "..."}`;
+  }
+
+  _getSenderMeta(event: RawEvent | AnyObj | null, ctxObj: ServerContext): SenderMeta {
+    const ev = event as AnyObj | null;
+    const senderId = String(ev?.senderId || 'system');
+    const senderType = ev?.senderType ? String(ev.senderType).toUpperCase() : 'SYSTEM';
+    const myId = this._getMyAgentId(ctxObj);
+
+    const isNonRoutableSenderType = (t: string): boolean =>
+      t === 'SYSTEM' || t === 'SERVICE';
+
+    let defaultReplyReceiverId = senderId;
+    const isNonRoutable = isNonRoutableSenderType(senderType);
+    if (isNonRoutable) {
+      const history = ctxObj.history || [];
+      for (let i = history.length - 1; i >= 0; i--) {
+        const row = history[i];
+        const sender = row.sender as Record<string, unknown> | undefined;
+        const id = String(sender?.id || row.senderId || '');
+        const type = String(sender?.type || row.senderType || '').toUpperCase();
+        if (id && id !== myId && !isNonRoutableSenderType(type)) {
+          defaultReplyReceiverId = id;
+          break;
+        }
+      }
+    }
+
+    return { senderId, senderType, myAgentId: myId, defaultReplyReceiverId: defaultReplyReceiverId || senderId };
+  }
+
+  _getMyAgentId(ctxObj: ServerContext): string | null {
+    const agents = ctxObj.agents || [];
+    const me = agents.find((a) => a.isYou);
+    return (me?.agentId as string | undefined) || null;
+  }
+}