@ziggs-ai/agent-sdk 0.1.12 → 0.2.0

package/dist/runtime/PromptBuilder.js

@@ -0,0 +1,439 @@
+import { HistoryFormatter, AgreementFormatter } from '../formatters/index.js';
+import { validateContext } from '../cognition/validateContext.js';
+import { isBroadcastTarget } from '@ziggs-ai/api-client';
+/** Rough chars-per-token ratio for budgeting (English/JSON averages ~4). */
+const CHARS_PER_TOKEN = 4;
+/**
+ * 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;
+    specialization;
+    maxHistoryEntries;
+    maxHistoryTokens;
+    historyFormatter;
+    agreementFormatter;
+    logger;
+    constructor(options = {}) {
+        this.description = options.description || 'A capable agent ready to assist';
+        this.specialization = options.specialization ?? null;
+        this.maxHistoryEntries = options.maxHistoryEntries ?? 50;
+        this.maxHistoryTokens = options.maxHistoryTokens ?? 8000;
+        this.historyFormatter = options.historyFormatter || new HistoryFormatter();
+        this.agreementFormatter = (options.agreementFormatter || new AgreementFormatter());
+        this.logger = options.logger || null;
+    }
+    // Section order is deliberate and cache-stable (ZIG-769): <self> (identity,
+    // state, tools) is stable per agent+state and comes first, so OpenAI automatic
+    // prompt caching can reuse it as a prefix across a conversation's turns. All
+    // volatile content (the incoming event, history, and currentTime) lives later
+    // in <world>, so it never invalidates that cacheable prefix.
+    buildFromState(args) {
+        const { statePrompt, actions, serverContext, incomingEvent, definition, stateId, ctx, omitMessageFromRespond } = args;
+        const ctxObj = serverContext?.context || {};
+        validateContext(ctxObj, { logger: this.logger });
+        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, 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 toolAny = tool;
+                const fn = toolAny.schema?.function || toolAny.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, ctxObj, agentId, senderMeta, agreements, otherAgents, users, stateId, ctx) {
+        const lines = ['<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 (ctx?.collectedResults?.length) {
+            lines.push('');
+            lines.push(this._renderSubtaskResults(ctx.collectedResults));
+        }
+        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, ctx) {
+        if (!ctx)
+            return stateId ? `<machine_context>\n${JSON.stringify({ stateId }, null, 2)}\n</machine_context>` : '';
+        const out = { 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 (Object.keys(ctx.pendingSubtasks ?? {}).length)
+            out.pendingSubtasks = ctx.pendingSubtasks;
+        if (ctx.lastOutcome)
+            out.lastOutcomeKind = ctx.lastOutcome.kind;
+        return `<machine_context>\n${JSON.stringify(out, null, 2)}\n</machine_context>`;
+    }
+    _renderSubtaskResults(results) {
+        const lines = ['<subtask_results>'];
+        lines.push(`All ${results.length} finished subtask(s) for the current engagement, oldest first. Synthesize from ALL of them — not just the most recent event.`);
+        for (const r of results) {
+            const payload = r.result == null ? null : typeof r.result === 'string' ? r.result : JSON.stringify(r.result);
+            const display = payload && payload.length > 2000 ? payload.slice(0, 2000) + `… [truncated of ${payload.length} chars]` : payload;
+            lines.push(`- taskId=${r.taskId} agent=${r.agentId ?? 'unknown'} status=${r.status}`);
+            lines.push(`  result: ${display ?? '(none)'}`);
+        }
+        lines.push('</subtask_results>');
+        return lines.join('\n');
+    }
+    _renderEvent(event, senderMeta) {
+        if (!event)
+            return '<event type="none">No incoming event.</event>';
+        const evAny = event;
+        if (evAny.type === 'batch' && Array.isArray(evAny.events) && evAny.events.length > 0) {
+            const parts = evAny.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="${evAny.events.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;
+        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);
+        // Matches MAX_MSG_CHARS in runTurn.ts — the incoming instruction shouldn't
+        // be truncated tighter than what the agent itself is allowed to send back.
+        const display = str.length > 3500 ? str.slice(0, 3500) + '...' : str;
+        return `<event type="${eventType}" from="${from}">\n${display}\n</event>`;
+    }
+    _renderTaskResultEvent(task, from) {
+        const lines = [];
+        const ag = task.agreement;
+        const parties = ag?.parties || {};
+        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;
+            if (proposal?.status) {
+                lines.push(`  Proposal: ${proposal.status} (to ${parties.proposedTo}${task.proposedToIsYou ? ' - You' : ''})`);
+            }
+            const money = ag.money;
+            if (typeof money?.price === 'number' && money.price > 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, agentId) {
+        const all = history || [];
+        const charBudget = this.maxHistoryTokens * CHARS_PER_TOKEN;
+        // Include entries newest-first, bounded by BOTH a token budget and the
+        // entry-count ceiling. The newest entry is always kept even if it alone
+        // exceeds the budget, so the most recent turn is never dropped.
+        let startIdx = all.length;
+        let usedChars = 0;
+        for (let i = all.length - 1; i >= 0; i--) {
+            if (all.length - i > this.maxHistoryEntries)
+                break;
+            const size = this._estimateEntryChars(all[i]);
+            if (startIdx < all.length && usedChars + size > charBudget)
+                break;
+            usedChars += size;
+            startIdx = i;
+        }
+        const entries = all.slice(startIdx);
+        const dropped = all.length - entries.length;
+        const truncNote = dropped > 0
+            ? `[Showing last ${entries.length} of ${all.length} entries — older turns dropped to fit the context budget]\n\n`
+            : '';
+        const formatted = this.historyFormatter.format(entries, agentId ?? '', {});
+        return `<history>\n${truncNote}${formatted}\n</history>`;
+    }
+    /** Rough character size of one history entry, used for the token budget. */
+    _estimateEntryChars(entry) {
+        try {
+            return JSON.stringify(entry)?.length ?? 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    _renderAgreements(agreements) {
+        const formatted = this.agreementFormatter.format(agreements || []);
+        return `<agreements>\n${formatted}\n</agreements>`;
+    }
+    _renderRecipients(users, otherAgents, agreements, myAgentId) {
+        // <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();
+        const userLabels = new Map();
+        for (const u of users) {
+            const id = u?.userId;
+            if (!id || id === myAgentId)
+                continue;
+            userIds.add(id);
+            userLabels.set(id, u.userName ? `${u.userName} (${id})` : id);
+        }
+        const agentIds = new Set();
+        const agentLabels = new Map();
+        for (const a of otherAgents) {
+            const id = a?.agentId;
+            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) => userIds.has(id) ? 'user' : agentIds.has(id) ? 'agent' : 'unknown';
+        const labelOf = (id) => userLabels.get(id) ?? agentLabels.get(id) ?? id;
+        const tagged = (id) => `${labelOf(id)} [${kindOf(id)}]`;
+        const agreementParties = new Map();
+        for (const ag of agreements || []) {
+            const agId = ag?.agreementId;
+            const parties = ag?.parties || {};
+            const roles = [
+                ['creator', 'creator'],
+                ['provider', 'provider'],
+                ['payer', 'payer'],
+                ['proposedTo', 'proposedTo'],
+            ];
+            for (const [field, role] of roles) {
+                const pid = parties[field];
+                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([...userIds, ...agentIds]);
+        const transferIds = new Set([...userIds, ...agentIds]);
+        const lines = ['<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, senderMeta, ctxObj, omitMessage) {
+        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.');
+        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 || '<receiverId>';
+        const pendingProposals = (ctxObj.agreements || []).filter((a) => a.proposal?.status === 'pending' && (a.proposedToIsYou || isBroadcastTarget(a.parties?.proposedTo)));
+        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, replyTo, omitMessage) {
+        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, ctxObj) {
+        const ev = event;
+        const senderId = String(ev?.senderId || 'system');
+        const senderType = ev?.senderType ? String(ev.senderType).toUpperCase() : 'SYSTEM';
+        const myId = this._getMyAgentId(ctxObj);
+        const isNonRoutableSenderType = (t) => 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;
+                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) {
+        const agents = ctxObj.agents || [];
+        const me = agents.find((a) => a.isYou);
+        return me?.agentId || null;
+    }
+}

package/{src/runtime/bootstrapCtx.ts → dist/runtime/bootstrapCtx.d.ts}

@@ -1,5 +1,4 @@
 import type { Ctx, Identity } from '../types.js';
-
 /**
  * The one place a per-lane `Ctx` is constructed.
  *
@@ -16,24 +15,4 @@ import type { Ctx, Identity } from '../types.js';
  *   without `pendingSubtasks` / `collectedResults`; default them here, nowhere
  *   else.
  */
-export function bootstrapCtx(identity: Identity, existing?: Ctx | null): Ctx {
-  if (existing) {
-    return {
-      ...existing,
-      identity,
-      pendingSubtasks: existing.pendingSubtasks ?? {},
-      collectedResults: existing.collectedResults ?? [],
-    };
-  }
-  return {
-    identity,
-    activeAgreementId: null,
-    activeTaskId: null,
-    pendingProposalAgreementId: null,
-    delegatedAgreementIds: [],
-    pendingSubtasks: {},
-    collectedResults: [],
-    toolResults: [],
-    lastOutcome: { kind: 'enter' },
-  };
-}
+export declare function bootstrapCtx(identity: Identity, existing?: Ctx | null): Ctx;

package/dist/runtime/bootstrapCtx.js

@@ -0,0 +1,37 @@
+/**
+ * The one place a per-lane `Ctx` is constructed.
+ *
+ * Both cognitions bootstrap the same Ctx: the FSM (`AgentMachine` constructor)
+ * and the Claude Agent SDK brain (`ClaudeSdkAgent.tick`). Before this, each
+ * carried its own copy of the fresh-Ctx literal and the restore-path defaulting,
+ * and they had already drifted (the "default them ONCE here" comment in
+ * AgentMachine no longer held). Keep it here so the shape lives in a single spot.
+ *
+ * - No `existing` → a fresh Ctx for a brand-new session.
+ * - `existing` present → restore it, re-stamping `identity` and defaulting the
+ *   fields that sessions persisted before they existed may lack. Sessions live
+ *   up to SESSION_TTL_SECONDS (24h) in DynamoDB, so an old row can come back
+ *   without `pendingSubtasks` / `collectedResults`; default them here, nowhere
+ *   else.
+ */
+export function bootstrapCtx(identity, existing) {
+    if (existing) {
+        return {
+            ...existing,
+            identity,
+            pendingSubtasks: existing.pendingSubtasks ?? {},
+            collectedResults: existing.collectedResults ?? [],
+        };
+    }
+    return {
+        identity,
+        activeAgreementId: null,
+        activeTaskId: null,
+        pendingProposalAgreementId: null,
+        delegatedAgreementIds: [],
+        pendingSubtasks: {},
+        collectedResults: [],
+        toolResults: [],
+        lastOutcome: { kind: 'enter' },
+    };
+}

package/dist/runtime/buildOutcome.d.ts

@@ -0,0 +1,68 @@
+import type { Action, AgreementRef, Ctx, Outcome, TaskRef, ToolResultEntry } from '../types.js';
+/** Wire payload from the backend for task/agreement state. */
+export interface WireResult {
+    taskId?: string;
+    state?: string;
+    status?: string;
+    agreement?: AgreementRef;
+    agreementId?: string;
+    proposal?: {
+        status?: 'pending' | 'approved' | 'rejected' | 'cancelled';
+    };
+    task?: TaskRef;
+    success?: boolean;
+    error?: string;
+    providerIsYou?: boolean;
+    [key: string]: unknown;
+}
+export interface RawEvent {
+    type?: string;
+    result?: WireResult;
+    receiverId?: string;
+    senderId?: string;
+    text?: string;
+    events?: RawEvent[];
+    [key: string]: unknown;
+}
+export interface EmittedEvent {
+    type: string;
+    tool?: string;
+    result?: WireResult;
+    error?: string;
+    receiverId?: string;
+    chatId?: string;
+    message?: string;
+    text?: string;
+    operation?: string;
+    senderId?: string;
+    [key: string]: unknown;
+}
+/**
+ * Converts a raw incoming event into the single Outcome that re-enters the
+ * machine.
+ *
+ * For batched events, returns the *most significant* outcome (task assignments
+ * win over messages). EventQueue already flattened multiple distinct events
+ * via re-entry, so a batch here usually means events that arrived together
+ * within a single backend frame.
+ */
+export declare function outcomeFromEvent(rawEvent: RawEvent | null | undefined, ownAgentId: string | null): Outcome;
+/**
+ * Builds the single Outcome that ends a thinking-state turn from the
+ * action that ran and the events it emitted.
+ *
+ * Action's `produces` declares the outcome kind — runtime fills in payload.
+ *   - static string: kind is fixed; runtime constructs payload from events.
+ *   - function: receives the tool result and args, returns the kind.
+ *
+ * If `produces` is missing or doesn't match the events, falls back to a
+ * best-effort inference.
+ */
+export declare function outcomeFromActionResult(actionName: string | null, action: Action | null, args: unknown, emittedEvents: EmittedEvent[], toolResultsOut: ToolResultEntry[]): Outcome;
+/**
+ * Mutates ctx to absorb persistent state from a new outcome:
+ * - active agreement/task ids on assignment, cleared on close
+ * - pending proposal id on proposal-made, cleared on resolution
+ * - delegated task ids accumulated on delegation, used to match later subtask events
+ */
+export declare function applyOutcomeToCtx(ctx: Ctx, outcome: Outcome): void;