@ziggs-ai/agent-sdk 0.1.12 → 0.2.1

package/dist/runtime/AgentMachine.d.ts

@@ -0,0 +1,143 @@
+import type { Ctx, Outcome, Workflow, Identity, EffectHandler } from '../types.js';
+import { type RawEvent } from './buildOutcome.js';
+import type { runTurn as RunTurnFn } from './runTurn.js';
+import { PromptBuilder } from './PromptBuilder.js';
+import type { MemoryStore } from '../memory/MemoryStore.js';
+import type { ToolManager } from '../tools/ToolManager.js';
+export interface MachineSnapshot {
+    value: string;
+    ctx: Ctx;
+    status: 'active' | 'stopped';
+}
+export type TransitionEvent = {
+    kind: 'transition';
+    fromState: string;
+    toState: string;
+    outcomeKind: string;
+    depth: number;
+} | {
+    kind: 'no-match';
+    state: string;
+    outcomeKind: string;
+    depth: number;
+} | {
+    kind: 'depth-guard';
+    state: string;
+    depth: number;
+} | {
+    kind: 'turn-budget-guard';
+    state: string;
+    turns: number;
+} | {
+    kind: 'error-escape';
+    fromState: string;
+    toState: string;
+} | {
+    kind: 'timeout-unhandled';
+    state: string;
+    waitedMs: number;
+};
+interface MachineInput {
+    identity: Identity;
+    /** Server-provided ctx for an existing session. If omitted, a fresh ctx is built. */
+    ctx?: Ctx;
+    /** Server-provided state name for an existing session. Defaults to workflow.initial. */
+    state?: string;
+}
+interface MachineOptions {
+    workflow: Workflow;
+    executionCore: typeof RunTurnFn;
+    /** Side channel for all I/O. Provided by the Server. */
+    eff: EffectHandler;
+    /** Pure tool metadata (schemas, flags). Owned by the Agent. */
+    toolManager: ToolManager;
+    promptBuilder: PromptBuilder;
+    /** Agent-private long-term memory. Operator-provided. */
+    memory?: MemoryStore;
+    input: MachineInput;
+    /** Optional tap for FSM transition events — called synchronously on each transition. */
+    transitionTap?: (event: TransitionEvent) => void;
+    /** Runaway-loop backstop: max thinking turns without human input before parking. Default 100. */
+    maxTurnsWithoutUserInput?: number;
+}
+interface IncomingFrame {
+    event?: RawEvent;
+    identity?: Identity;
+}
+type Subscriber = (snapshot: MachineSnapshot) => void;
+/**
+ * Per-lane interpreter. Holds (current state name, Ctx). Re-entry is the
+ * single primitive: every external event and every turn produces exactly
+ * one Outcome that re-enters the current state.
+ *
+ * Parked states stop on entry. Thinking states run an LLM turn → produce an
+ * outcome → re-enter. Transitions are evaluated against the new outcome
+ * (first matching `when` wins; no `when` is fallthrough).
+ *
+ * `_running` guards against concurrent turns on the same machine — outer
+ * runtime is expected to serialize via EventQueue, but we belt-and-suspenders.
+ */
+export declare class AgentMachine {
+    workflow: Workflow;
+    executionCore: typeof RunTurnFn;
+    eff: EffectHandler;
+    toolManager: ToolManager;
+    promptBuilder: PromptBuilder;
+    memory?: MemoryStore;
+    state: string;
+    status: 'active' | 'stopped';
+    ctx: Ctx;
+    _running: boolean;
+    _subscribers: Set<Subscriber>;
+    _prevSnapshot: MachineSnapshot | null;
+    _pendingFrames: IncomingFrame[];
+    _draining: boolean;
+    _llmCalls: number;
+    _tokens: {
+        total: number;
+        input: number;
+        output: number;
+    };
+    _lastUserSenderId: string | null;
+    _stateTimeoutUnhandled: boolean;
+    _transitionTap: ((event: TransitionEvent) => void) | undefined;
+    /** Thinking turns run since the last human (USER) frame. Reset on USER input. */
+    _turnsSinceUserInput: number;
+    _maxTurnsWithoutUserInput: number;
+    get llmCalls(): number;
+    get tokens(): {
+        total: number;
+        input: number;
+        output: number;
+    };
+    get stateTimeoutUnhandled(): boolean;
+    constructor({ workflow, executionCore, eff, toolManager, promptBuilder, memory, input, transitionTap, maxTurnsWithoutUserInput }: MachineOptions);
+    getSnapshot(): MachineSnapshot;
+    /** Parked = currently in a parked state and not executing a turn. */
+    get isParked(): boolean;
+    subscribe(fn: Subscriber): {
+        unsubscribe: () => void;
+    };
+    /**
+     * Process an incoming wire event: convert to outcome → apply to ctx →
+     * evaluate current state's transitions → re-enter or stop.
+     *
+     * Serialized via a single-slot queue: if a turn is already in flight, the
+     * frame is held until the running turn settles, then drained. Without this,
+     * an inbound event mid-turn re-entered _step with a stale state and a hot
+     * `_running=true`, which spawned overlapping turns and re-created the
+     * clarifyingDuringApproval feedback loop even after fixing the workflow
+     * fall-through (ZIG-181).
+     */
+    send(frame: IncomingFrame): Promise<void>;
+    _handleFrame(frame: IncomingFrame): Promise<void>;
+    _step(outcome: Outcome, depth?: number): Promise<void>;
+    /** Error with no author-defined escape: park at workflow.initial if it is parked. */
+    _escapeToInitialParked(outcome: Outcome, fromState: string): Promise<boolean>;
+    /** Sends a short fallback to the last known human user when the machine parks unexpectedly. Best-effort — never throws. */
+    _sendFallbackIfUserWaiting(text: string): Promise<void>;
+    _evaluateTransitions(outcome: Outcome): string | null;
+    _notify(): void;
+    _lastIncomingEvent: RawEvent | null;
+}
+export {};

package/dist/runtime/AgentMachine.js

@@ -0,0 +1,400 @@
+import { runtimeLog } from '../shared/runtimeLog.js';
+import { applyOutcomeToCtx, outcomeFromEvent } from './buildOutcome.js';
+import { runMechanical } from './runMechanical.js';
+import { bootstrapCtx } from './bootstrapCtx.js';
+/**
+ * Max thinking turns a session may run without any human (USER) input before it
+ * is treated as a runaway loop and parked (ZIG-768). The depth-guard only bounds
+ * re-entries within a single event chain; this bounds turns ACROSS events, which
+ * is how a supervising session ran 436 turns in a day. The counter resets on
+ * every USER frame, so human-driven conversations are never affected — only
+ * autonomous agent↔agent loops accumulate toward it.
+ */
+const DEFAULT_MAX_TURNS_WITHOUT_USER_INPUT = 100;
+/**
+ * Per-lane interpreter. Holds (current state name, Ctx). Re-entry is the
+ * single primitive: every external event and every turn produces exactly
+ * one Outcome that re-enters the current state.
+ *
+ * Parked states stop on entry. Thinking states run an LLM turn → produce an
+ * outcome → re-enter. Transitions are evaluated against the new outcome
+ * (first matching `when` wins; no `when` is fallthrough).
+ *
+ * `_running` guards against concurrent turns on the same machine — outer
+ * runtime is expected to serialize via EventQueue, but we belt-and-suspenders.
+ */
+export class AgentMachine {
+    workflow;
+    executionCore;
+    eff;
+    toolManager;
+    promptBuilder;
+    memory;
+    state;
+    status = 'active';
+    ctx;
+    _running = false;
+    _subscribers = new Set();
+    _prevSnapshot = null;
+    _pendingFrames = [];
+    _draining = false;
+    _llmCalls = 0;
+    _tokens = { total: 0, input: 0, output: 0 };
+    _lastUserSenderId = null;
+    _stateTimeoutUnhandled = false;
+    _transitionTap;
+    /** Thinking turns run since the last human (USER) frame. Reset on USER input. */
+    _turnsSinceUserInput = 0;
+    _maxTurnsWithoutUserInput;
+    get llmCalls() { return this._llmCalls; }
+    get tokens() { return this._tokens; }
+    get stateTimeoutUnhandled() { return this._stateTimeoutUnhandled; }
+    constructor({ workflow, executionCore, eff, toolManager, promptBuilder, memory, input, transitionTap, maxTurnsWithoutUserInput }) {
+        this.workflow = workflow;
+        this.executionCore = executionCore;
+        this.eff = eff;
+        this.toolManager = toolManager;
+        this.promptBuilder = promptBuilder;
+        this.memory = memory;
+        this._transitionTap = transitionTap;
+        this._maxTurnsWithoutUserInput = maxTurnsWithoutUserInput ?? DEFAULT_MAX_TURNS_WITHOUT_USER_INPUT;
+        this.state = input.state || workflow.initial;
+        this.ctx = bootstrapCtx(input.identity, input.ctx);
+    }
+    getSnapshot() {
+        return { value: this.state, ctx: this.ctx, status: this.status };
+    }
+    /** Parked = currently in a parked state and not executing a turn. */
+    get isParked() {
+        if (this._running)
+            return false;
+        const sd = this.workflow.states[this.state];
+        return sd?.kind === 'parked';
+    }
+    subscribe(fn) {
+        this._subscribers.add(fn);
+        return { unsubscribe: () => this._subscribers.delete(fn) };
+    }
+    /**
+     * Process an incoming wire event: convert to outcome → apply to ctx →
+     * evaluate current state's transitions → re-enter or stop.
+     *
+     * Serialized via a single-slot queue: if a turn is already in flight, the
+     * frame is held until the running turn settles, then drained. Without this,
+     * an inbound event mid-turn re-entered _step with a stale state and a hot
+     * `_running=true`, which spawned overlapping turns and re-created the
+     * clarifyingDuringApproval feedback loop even after fixing the workflow
+     * fall-through (ZIG-181).
+     */
+    async send(frame) {
+        if (this.status !== 'active')
+            return;
+        this._pendingFrames.push(frame);
+        if (this._draining)
+            return;
+        this._draining = true;
+        try {
+            while (this._pendingFrames.length) {
+                const next = this._pendingFrames.shift();
+                await this._handleFrame(next);
+            }
+        }
+        finally {
+            this._draining = false;
+        }
+    }
+    async _handleFrame(frame) {
+        if (this.status !== 'active')
+            return;
+        if (frame.identity)
+            this.ctx.identity = frame.identity;
+        const ev = frame.event;
+        this._lastIncomingEvent = ev ?? null;
+        if (ev?.senderId && String(ev?.senderType ?? '').toUpperCase() === 'USER') {
+            this._lastUserSenderId = String(ev.senderId);
+            // Human input is real progress — reset the runaway-loop budget (ZIG-768).
+            this._turnsSinceUserInput = 0;
+        }
+        runtimeLog.debug('FSM', `_handleFrame ev.type=${ev?.type} ev.senderId=${ev?.senderId} ev.receiverId=${ev?.receiverId} myId=${this.ctx.identity?.agentId}`);
+        const outcome = outcomeFromEvent(ev, this.ctx.identity.agentId);
+        // `outcomeFromEvent` never returns null — it falls back to `{ kind: 'enter' }`
+        // when all events in a batch are no-ops (resource_changed, self-echo, etc.).
+        // If a real raw event produced `enter`, that means the event carried no
+        // meaningful signal for the FSM, so skip it entirely.  Without this guard
+        // `idle`'s unconditional `{ to: 'understanding' }` transition fires on every
+        // resource_changed wake-up, kicking off an LLM turn that sends a duplicate
+        // message, which triggers another resource_changed, and so on.
+        if (ev && outcome.kind === 'enter')
+            return;
+        // Proposer detection must read pendingProposalAgreementId BEFORE
+        // applyOutcomeToCtx clears it on resolution (buildOutcome.ts). Wire frames
+        // carry no trustworthy proposer field — agreement_lifecycle drops `parties`
+        // in normalizeIncomingEvent, and parties.creator is a principal id, not an
+        // agentId (backend ZIG-272) — so the SDK's own "I made this proposal"
+        // memory is the signal. Side effect we rely on: the first resolution clears
+        // the pending id, so duplicate approval frames compute proposedByMe=false
+        // and can never double-kickoff.
+        if (outcome.kind === 'proposal-resolved') {
+            outcome.proposedByMe =
+                this.ctx.pendingProposalAgreementId !== null &&
+                    outcome.proposal.agreementId === this.ctx.pendingProposalAgreementId;
+        }
+        applyOutcomeToCtx(this.ctx, outcome);
+        await this._step(outcome);
+    }
+    async _step(outcome, depth = 0) {
+        const fromState = this.state;
+        const target = this._evaluateTransitions(outcome);
+        const o = outcome;
+        runtimeLog.debug('FSM', `_step from=${fromState} outcome.kind=${o?.kind} senderId=${o?.senderId ?? '<none>'} myId=${this.ctx.identity?.agentId ?? '<none>'} → target=${target ?? '(stay)'} depth=${depth}`);
+        if (target && target !== this.state) {
+            this._transitionTap?.({ kind: 'transition', fromState, toState: target, outcomeKind: outcome.kind, depth });
+            this.state = target;
+            this._notify();
+        }
+        // A state-timeout only enters at depth 0 (host-armed frame via _handleFrame;
+        // turns cannot produce it — validateWorkflow rejects produces:'state-timeout').
+        // No matching transition = the author declared timeoutMs but no route: park
+        // loudly and tell the host not to re-arm (re-arming would error every
+        // timeoutMs forever). Next real event still recovers the lane. A matched
+        // transition (target !== null) — including an explicit self-loop — is
+        // "handled" and re-arms as a heartbeat.
+        if (outcome.kind === 'state-timeout' && depth === 0 && !target) {
+            this._stateTimeoutUnhandled = true;
+            runtimeLog.error('AgentMachine', `state=${this.state} timed out after ${outcome.waitedMs}ms but no transition matches { kind: 'state-timeout' } — parking without a timer. Add a state-timeout transition to "${this.state}" or remove timeoutMs.`);
+            this._transitionTap?.({ kind: 'timeout-unhandled', state: this.state, waitedMs: outcome.waitedMs });
+            this._notify();
+            return;
+        }
+        const sd = this.workflow.states[this.state];
+        if (!sd)
+            return;
+        if (sd.kind === 'parked') {
+            runtimeLog.debug('FSM', `_step parked state=${this.state} — exit`);
+            // Notify so runtime detects park and resolves the wait promise.
+            this._notify();
+            return;
+        }
+        if (sd.kind === 'mechanical') {
+            if (depth >= 12) {
+                runtimeLog.warn('AgentMachine', `state=${this.state} runaway mechanical loop (depth=${depth}); parking`);
+                this._transitionTap?.({ kind: 'depth-guard', state: this.state, depth });
+                await this._sendFallbackIfUserWaiting('Something went wrong. Please try again.');
+                this._notify();
+                return;
+            }
+            if (this._turnsSinceUserInput >= this._maxTurnsWithoutUserInput) {
+                runtimeLog.warn('AgentMachine', `state=${this.state} runaway loop: ${this._turnsSinceUserInput} turns without user input (cap ${this._maxTurnsWithoutUserInput}); parking`);
+                this._transitionTap?.({ kind: 'turn-budget-guard', state: this.state, turns: this._turnsSinceUserInput });
+                await this._sendFallbackIfUserWaiting('I got stuck in a loop and paused. Please send another message to continue.');
+                this._notify();
+                return;
+            }
+            runtimeLog.debug('FSM', `_step mechanical state=${this.state} — run tool`);
+            this._running = true;
+            try {
+                const { outcome: turnOutcome, toolResults, llmCalls, tokens } = await runMechanical({
+                    stateId: this.state,
+                    state: sd,
+                    ctx: this.ctx,
+                    eff: this.eff,
+                    memory: this.memory,
+                    incomingEvent: this._lastIncomingEvent,
+                });
+                this.ctx.toolResults = toolResults;
+                this._llmCalls += llmCalls;
+                this._turnsSinceUserInput += 1;
+                this._tokens.total += tokens.total;
+                this._tokens.input += tokens.input;
+                this._tokens.output += tokens.output;
+                applyOutcomeToCtx(this.ctx, turnOutcome);
+                this._running = false;
+                this._notify();
+                await this._step(turnOutcome, depth + 1);
+            }
+            catch (error) {
+                runtimeLog.error('AgentMachine', `mechanical state=${this.state} error: ${error?.message || error}`);
+                const errOutcome = {
+                    kind: 'error',
+                    source: 'unknown',
+                    cause: error?.message || String(error),
+                    retryable: false,
+                };
+                applyOutcomeToCtx(this.ctx, errOutcome);
+                this._running = false;
+                this._notify();
+                const fallback = this._evaluateTransitions(errOutcome);
+                if (fallback && fallback !== this.state) {
+                    this.state = fallback;
+                    this._notify();
+                }
+                else {
+                    await this._sendFallbackIfUserWaiting('Something went wrong. Please try again.');
+                }
+            }
+            return;
+        }
+        // A thinking turn that yields an outcome no transition handles must not
+        // silently re-enter the same state and burn another LLM call (ZIG-303).
+        // Explicit self-loops still match (target is non-null, even if target === state).
+        if (sd.kind === 'thinking' &&
+            depth > 0 &&
+            fromState === this.state &&
+            !target) {
+            if (await this._escapeToInitialParked(outcome, fromState))
+                return;
+            runtimeLog.warn('AgentMachine', `state=${fromState} outcome.kind=${outcome.kind} matched no transition; parking (depth=${depth})`);
+            this._transitionTap?.({ kind: 'no-match', state: fromState, outcomeKind: outcome.kind, depth });
+            await this._sendFallbackIfUserWaiting('Something went wrong. Please try again.');
+            this._notify();
+            return;
+        }
+        // Recursion / runaway-turn guard. Without this, a thinking state whose
+        // transitions don't match the turn outcome (e.g. `delegating` not
+        // catching `tool-result` from an agent_network search) re-enters the
+        // same state forever — the LLM keeps re-rolling search/dummy actions
+        // until something accidentally matches, burning tokens and emitting
+        // duplicate side effects (ZIG-181: ziggs ran `discoverSpecialist` six
+        // times before finally invoking `delegate`). 12 is well above any
+        // legitimate same-state turn chain we exercise in tests; if we trip
+        // it, treat the state as wedged and park.
+        if (depth >= 12) {
+            runtimeLog.warn('AgentMachine', `state=${this.state} runaway turn loop (depth=${depth}); parking`);
+            this._transitionTap?.({ kind: 'depth-guard', state: this.state, depth });
+            await this._sendFallbackIfUserWaiting('Something went wrong. Please try again.');
+            this._notify();
+            return;
+        }
+        // Cross-event runaway guard (ZIG-768). The depth-guard above only bounds
+        // one event chain; a supervising session that keeps waking on agent/system
+        // messages re-enters at depth 0 each time and never trips it. Bound the
+        // total thinking turns since the last human input instead — a runaway
+        // agent↔agent loop climbs toward the cap while a human conversation resets
+        // it on every user message.
+        if (this._turnsSinceUserInput >= this._maxTurnsWithoutUserInput) {
+            runtimeLog.warn('AgentMachine', `state=${this.state} runaway loop: ${this._turnsSinceUserInput} turns without user input (cap ${this._maxTurnsWithoutUserInput}); parking`);
+            this._transitionTap?.({ kind: 'turn-budget-guard', state: this.state, turns: this._turnsSinceUserInput });
+            await this._sendFallbackIfUserWaiting('I got stuck in a loop and paused. Please send another message to continue.');
+            this._notify();
+            return;
+        }
+        runtimeLog.debug('FSM', `_step thinking state=${this.state} — run turn`);
+        // Thinking: run a turn, produce an outcome, re-step.
+        this._running = true;
+        try {
+            const { outcome: turnOutcome, toolResults, llmCalls, tokens } = await this.executionCore({
+                stateId: this.state,
+                statePrompt: sd.prompt,
+                actions: sd.actions,
+                incomingEvent: this._lastIncomingEvent,
+                ctx: this.ctx,
+                eff: this.eff,
+                toolManager: this.toolManager,
+                promptBuilder: this.promptBuilder,
+                memory: this.memory,
+                definition: this.workflow,
+            });
+            this.ctx.toolResults = toolResults;
+            this._llmCalls += llmCalls;
+            this._turnsSinceUserInput += 1;
+            this._tokens.total += tokens.total;
+            this._tokens.input += tokens.input;
+            this._tokens.output += tokens.output;
+            applyOutcomeToCtx(this.ctx, turnOutcome);
+            this._running = false;
+            this._notify();
+            await this._step(turnOutcome, depth + 1);
+        }
+        catch (error) {
+            runtimeLog.error('AgentMachine', `state=${this.state} error: ${error?.message || error}`);
+            const errOutcome = {
+                kind: 'error',
+                source: 'unknown',
+                cause: error?.message || String(error),
+                retryable: false,
+            };
+            applyOutcomeToCtx(this.ctx, errOutcome);
+            this._running = false;
+            this._notify();
+            // Try to fall through using current state's transitions; if none match
+            // the error outcome the machine just parks (next event will re-enter).
+            const fallback = this._evaluateTransitions(errOutcome);
+            if (fallback && fallback !== this.state) {
+                this.state = fallback;
+                this._notify();
+            }
+            else {
+                await this._sendFallbackIfUserWaiting('Something went wrong. Please try again.');
+            }
+        }
+    }
+    /** Error with no author-defined escape: park at workflow.initial if it is parked. */
+    async _escapeToInitialParked(outcome, fromState) {
+        if (outcome.kind !== 'error')
+            return false;
+        const initial = this.workflow.initial;
+        const initialSd = this.workflow.states[initial];
+        if (!initialSd || initialSd.kind !== 'parked' || initial === fromState) {
+            return false;
+        }
+        runtimeLog.warn('AgentMachine', `state=${fromState} error outcome had no transition — escaped to parked initial "${initial}"`);
+        this._transitionTap?.({ kind: 'error-escape', fromState, toState: initial });
+        this.state = initial;
+        // The turn failed and no workflow transition handled it — a waiting human
+        // got nothing, so apologize before parking (same text as the other parks).
+        await this._sendFallbackIfUserWaiting('Something went wrong. Please try again.');
+        this._notify();
+        return true;
+    }
+    /** Sends a short fallback to the last known human user when the machine parks unexpectedly. Best-effort — never throws. */
+    async _sendFallbackIfUserWaiting(text) {
+        const userId = this._lastUserSenderId;
+        if (!userId)
+            return;
+        try {
+            await this.eff({ kind: 'send-message', sessionId: this.ctx.identity.sessionId, receiverId: userId, text });
+        }
+        catch { /* best-effort */ }
+    }
+    _evaluateTransitions(outcome) {
+        const sd = this.workflow.states[this.state];
+        if (!sd?.transitions?.length) {
+            runtimeLog.debug('FSM', `evaluate state=${this.state}: NO TRANSITIONS DEFINED`);
+            return null;
+        }
+        for (let i = 0; i < sd.transitions.length; i++) {
+            const rule = sd.transitions[i];
+            let matched;
+            let err = null;
+            if (!rule.when) {
+                matched = true;
+            }
+            else {
+                try {
+                    matched = !!rule.when(outcome, this.ctx);
+                }
+                catch (e) {
+                    matched = false;
+                    err = e;
+                }
+            }
+            runtimeLog.debug('FSM', `evaluate state=${this.state} rule[${i}] to=${rule.to} when=${rule.when ? 'fn' : 'always'} → ${matched}${err ? ` ERR=${err.message}` : ''}`);
+            if (matched)
+                return rule.to;
+        }
+        runtimeLog.debug('FSM', `evaluate state=${this.state}: NONE matched`);
+        return null;
+    }
+    _notify() {
+        const snapshot = this.getSnapshot();
+        for (const fn of this._subscribers) {
+            try {
+                fn(snapshot);
+            }
+            catch { }
+        }
+    }
+    // Held so PromptBuilder/runTurn can render the original wire event in <event>.
+    // Set by the runtime layer when it calls send(); we don't classify it twice.
+    _lastIncomingEvent = null;
+}

package/dist/runtime/PromptBuilder.d.ts

@@ -0,0 +1,96 @@
+import type { Action, CollectedSubtaskResult, Ctx, PromptDef } from '../types.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;
+    /**
+     * Token budget for the <history> block. History is included newest-first up
+     * to this many (estimated) tokens, so a few large turns can't blow the prompt
+     * up to tens of thousands of input tokens (ZIG-769). maxHistoryEntries still
+     * applies as a secondary hard ceiling.
+     */
+    maxHistoryTokens?: 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 declare class PromptBuilder {
+    description: string;
+    specialization: string | null;
+    maxHistoryEntries: number;
+    maxHistoryTokens: number;
+    historyFormatter: HistoryFormatterI;
+    agreementFormatter: AgreementFormatterI;
+    logger: LoggerI | null;
+    constructor(options?: PromptBuilderOptions);
+    buildFromState(args: BuildArgs): string;
+    _renderSelfFromState(description: string, statePrompt: PromptDef, tools?: AnyObj[]): string;
+    _renderWorld(event: RawEvent | null, ctxObj: ServerContext, agentId: string | null, senderMeta: SenderMeta, agreements: AnyObj[], otherAgents: AnyObj[], users: AnyObj[], stateId: string, ctx: Ctx): string;
+    _renderMachineContext(stateId: string, ctx: Ctx): string;
+    _renderSubtaskResults(results: CollectedSubtaskResult[]): string;
+    _renderEvent(event: RawEvent | AnyObj | null, senderMeta: SenderMeta): string;
+    _renderTaskResultEvent(task: AnyObj, from: string): string;
+    _renderHistory(history: AnyObj[] | undefined, agentId: string | null): string;
+    /** Rough character size of one history entry, used for the token budget. */
+    _estimateEntryChars(entry: AnyObj): number;
+    _renderAgreements(agreements: AnyObj[]): string;
+    _renderRecipients(users: AnyObj[], otherAgents: AnyObj[], agreements: AnyObj[], myAgentId: string | null | undefined): string;
+    _renderDecisionSchemaFromActions(actions: Record<string, Action>, senderMeta: SenderMeta, ctxObj: ServerContext, omitMessage?: boolean): string;
+    _buildActionSchema(name: string, replyTo: string, omitMessage?: boolean): string;
+    _getSenderMeta(event: RawEvent | AnyObj | null, ctxObj: ServerContext): SenderMeta;
+    _getMyAgentId(ctxObj: ServerContext): string | null;
+}
+export {};