@ziggs-ai/agent-sdk 0.1.11 → 0.2.0

package/dist/context/classifyEnvelope.js

@@ -0,0 +1,58 @@
+import { CONTEXT_RESET } from './applyEffects.js';
+import { getBatchEvents, isTaskResultRelevantToAgent } from './batch.js';
+function isTaskAssignment(result, ownAgentId) {
+    const parties = result['agreement']?.['parties'] ?? {};
+    const isProvider = result['providerIsYou'] || parties['provider'] === ownAgentId;
+    return !!(isProvider && (result['state'] === 'active' || result['state'] === 'in-progress'));
+}
+export function classifyIncomingEvent(rawEvent, ownAgentId) {
+    const flags = { ...CONTEXT_RESET };
+    if (!rawEvent)
+        return flags;
+    for (const ev of getBatchEvents(rawEvent)) {
+        if (!ev)
+            continue;
+        const e = ev;
+        if (e['type'] !== 'task_result') {
+            flags['incomingMessage'] = true;
+            continue;
+        }
+        const result = e['result'] || {};
+        if (ownAgentId && !isTaskResultRelevantToAgent(result, ownAgentId) && e['receiverId'] !== ownAgentId)
+            continue;
+        const state = result['state'];
+        const ag = result['agreement'];
+        const parties = ag?.['parties'] || {};
+        const proposalStatus = ag?.['proposal']?.['status'];
+        if (state === 'active' && proposalStatus === 'approved' && ownAgentId && parties['creator'] === ownAgentId) {
+            flags['approval'] = true;
+            flags['taskAssignment'] = result;
+            continue;
+        }
+        if (isTaskAssignment(result, ownAgentId)) {
+            flags['taskAssignment'] = result;
+            flags['approval'] = true;
+            continue;
+        }
+        if (proposalStatus === 'approved' || (state === 'active' && proposalStatus === 'pending')) {
+            flags['approval'] = true;
+            flags['taskAssignment'] = result;
+            continue;
+        }
+        if (proposalStatus === 'rejected' || state === 'cancelled') {
+            flags['rejection'] = true;
+            continue;
+        }
+        if (state === 'completed') {
+            flags['subtaskResult'] = result;
+            continue;
+        }
+        if (state === 'failed') {
+            flags['subtaskResult'] = result;
+            flags['subtaskFailed'] = true;
+            continue;
+        }
+        flags['subtaskResult'] = result;
+    }
+    return flags;
+}

package/dist/context/routingLabels.d.ts

@@ -0,0 +1,4 @@
+export declare function unwrapBatchEvent(event: unknown): unknown;
+export declare function classifyWorkflowEvent(event: unknown, ownAgentId?: string | null): string;
+export declare function findTaskResult(output: Record<string, unknown> | null | undefined): unknown;
+export declare function findIncomingTaskResult(incomingEvent: unknown): unknown;

package/dist/context/routingLabels.js

@@ -0,0 +1,48 @@
+import { isProtocolToolName } from '../tasks/protocolRegistry.js';
+import { getBatchEvents, isTaskResultRelevantToAgent } from './batch.js';
+export function unwrapBatchEvent(event) {
+    const e = event;
+    if (e?.['type'] === 'batch' && Array.isArray(e['events']) && e['events'][0])
+        return e['events'][0];
+    return event;
+}
+export function classifyWorkflowEvent(event, ownAgentId = null) {
+    const events = getBatchEvents(event);
+    if (events.length === 0)
+        return 'message';
+    let sawTaskResult = false, sawOwnTaskResult = false;
+    for (const ev of events) {
+        const e = ev;
+        if (e?.['type'] !== 'task_result')
+            continue;
+        sawTaskResult = true;
+        const result = e['result'] || {};
+        if (!isTaskResultRelevantToAgent(result, ownAgentId))
+            continue;
+        sawOwnTaskResult = true;
+        const state = result['state'];
+        const ag = result['agreement'];
+        const parties = ag?.['parties'] || {};
+        const proposalStatus = ag?.['proposal'] ? ag['proposal']['status'] : undefined;
+        const isProvider = result['providerIsYou'] || parties['provider'] === ownAgentId;
+        if (isProvider && (state === 'active' || state === 'in-progress'))
+            return 'task_assignment';
+        if (proposalStatus === 'approved' || (state === 'active' && proposalStatus === 'pending'))
+            return 'task_approved';
+        if (proposalStatus === 'rejected' || state === 'cancelled')
+            return 'task_rejected';
+    }
+    if (sawOwnTaskResult || sawTaskResult)
+        return 'task_update';
+    return 'message';
+}
+export function findTaskResult(output) {
+    const events = output?.['emittedEvents'] ?? [];
+    return events.find(e => {
+        const ev = e;
+        return ev['type'] === 'task_result' || (ev['type'] === 'tool_result' && isProtocolToolName(ev['tool']));
+    }) ?? null;
+}
+export function findIncomingTaskResult(incomingEvent) {
+    return getBatchEvents(incomingEvent).find(e => e?.['type'] === 'task_result') ?? null;
+}

package/dist/defineAgent.d.ts

@@ -0,0 +1,14 @@
+import type { AgentConfig, DefineAgentInput } from './types.js';
+/**
+ * Validates the workflow synchronously, resolves merged tools and model, and
+ * returns a frozen AgentConfig. Never mutates the input. `wait` defaults remain
+ * the author's visible spread of `thinkingDefaults`. ONE default is injected (as
+ * new objects): the agreement-kickoff state `kickingOff` plus a last-position
+ * transition into it, appended to every state that does not already handle a
+ * proposer-side proposal-resolved/approve outcome (runtime/kickoff.ts). The
+ * state name 'kickingOff' is reserved; defining it throws.
+ *
+ * Validation throws WorkflowValidationError on hard problems and logs warnings
+ * on soft ones (e.g. missing wait fallthrough).
+ */
+export declare function defineAgent(input: DefineAgentInput): AgentConfig;

package/dist/defineAgent.js

@@ -0,0 +1,68 @@
+import { validateWorkflow } from './runtime/validateWorkflow.js';
+import { injectKickoffDefault } from './runtime/kickoff.js';
+import { deriveRespondsToProposals } from './runtime/deriveRespondsToProposals.js';
+import { runtimeLog } from './shared/runtimeLog.js';
+import { DEFAULT_MODEL } from './AgentHost.js';
+/**
+ * Validates the workflow synchronously, resolves merged tools and model, and
+ * returns a frozen AgentConfig. Never mutates the input. `wait` defaults remain
+ * the author's visible spread of `thinkingDefaults`. ONE default is injected (as
+ * new objects): the agreement-kickoff state `kickingOff` plus a last-position
+ * transition into it, appended to every state that does not already handle a
+ * proposer-side proposal-resolved/approve outcome (runtime/kickoff.ts). The
+ * state name 'kickingOff' is reserved; defining it throws.
+ *
+ * Validation throws WorkflowValidationError on hard problems and logs warnings
+ * on soft ones (e.g. missing wait fallthrough).
+ */
+export function defineAgent(input) {
+    if (!input?.agentId)
+        throw new Error('[defineAgent] agentId is required');
+    if (!input?.description)
+        throw new Error('[defineAgent] description is required');
+    if (!input?.states)
+        throw new Error('[defineAgent] states is required');
+    if (!input?.initial)
+        throw new Error('[defineAgent] initial state is required');
+    // Agreement-kickoff default (see runtime/kickoff.ts): injected BEFORE
+    // validation so the injected state/transitions are validated too.
+    const workflow = injectKickoffDefault({
+        id: input.agentId,
+        description: input.description,
+        initial: input.initial,
+        states: input.states,
+    });
+    const { warnings } = validateWorkflow(workflow);
+    for (const w of warnings)
+        runtimeLog.warn('defineAgent', w);
+    const tools = [
+        ...(Array.isArray(input.tools) ? input.tools : []),
+        ...(Array.isArray(input.services?.tools) ? input.services.tools : []),
+    ];
+    // Model resolution, most-specific-first: a per-agent pin, then the
+    // fleet-wide `LLM_MODEL` lever, then the single `DEFAULT_MODEL` fallback (the
+    // ONE place the default lives — see AgentHost). The id also picks the provider
+    // (claude-* → Anthropic). No agent hardcodes its own fallback.
+    const model = input.services?.llm?.model ||
+        process.env.LLM_MODEL ||
+        DEFAULT_MODEL;
+    // Strip the structural fields we already consumed; pass through everything
+    // else (operatorKey, taskTools, custom keys consumed by AgentHost).
+    const { agentId, description, specialization, services: _services, initial: _initial, states: _states, tools: _tools, operatorKey, taskTools, ...rest } = input;
+    const config = {
+        openaiKey: process.env.OPENAI_API_KEY,
+        anthropicKey: process.env.ANTHROPIC_API_KEY,
+        ...(operatorKey ? { operatorKey } : {}),
+        agentId,
+        description,
+        ...(specialization ? { specialization } : {}),
+        tools,
+        model,
+        workflow,
+        respondsToProposals: input.respondsToProposals ?? deriveRespondsToProposals(workflow),
+        ...(input.services ? { services: input.services } : {}),
+        ...(taskTools !== undefined ? { taskTools } : {}),
+        ...rest,
+    };
+    return Object.freeze(config);
+}

package/dist/formatters/AgreementFormatter.d.ts

@@ -0,0 +1,18 @@
+interface AgreementFormatterOptions {
+    shortIds?: boolean;
+    indentSize?: number;
+}
+type AnyObj = Record<string, unknown>;
+export declare class AgreementFormatter {
+    private shortIds;
+    private indentSize;
+    constructor(options?: AgreementFormatterOptions);
+    format(agreements: AnyObj[] | null | undefined): string;
+    formatAgreement(ag: AnyObj, indent?: string): string;
+    _renderTaskExecution(task: AnyObj, indent?: string): string;
+    _labelParty(id: string | null | undefined, isYou: boolean | undefined): string;
+    shortId(id: string | null | undefined): string;
+    private _indent;
+}
+export declare const agreementFormatter: AgreementFormatter;
+export {};

package/dist/formatters/AgreementFormatter.js

@@ -0,0 +1,130 @@
+export class AgreementFormatter {
+    shortIds;
+    indentSize;
+    constructor(options = {}) {
+        this.shortIds = options.shortIds ?? false;
+        this.indentSize = options.indentSize ?? 2;
+    }
+    format(agreements) {
+        if (!agreements?.length)
+            return 'No active agreements.';
+        const pending = agreements.filter(a => a['proposal']?.['status'] === 'pending' && a['proposedToIsYou']);
+        const standing = agreements.filter(a => !a['task']);
+        const active = agreements.filter(a => a['task'] && !(a['proposal']?.['status'] === 'pending' && a['proposedToIsYou']));
+        const sections = [];
+        if (pending.length > 0) {
+            sections.push('Pending Proposals (awaiting your response):');
+            for (const ag of pending)
+                sections.push(this.formatAgreement(ag, this._indent(1)));
+        }
+        if (active.length > 0) {
+            if (sections.length > 0)
+                sections.push('');
+            sections.push('Active Agreements:');
+            for (const ag of active)
+                sections.push(this.formatAgreement(ag, this._indent(1)));
+        }
+        if (standing.length > 0) {
+            if (sections.length > 0)
+                sections.push('');
+            sections.push('Standing Agreements (no execution running):');
+            for (const ag of standing)
+                sections.push(this.formatAgreement(ag, this._indent(1)));
+        }
+        return sections.join('\n');
+    }
+    formatAgreement(ag, indent = '') {
+        const status = (ag['status'] || 'unknown').toUpperCase();
+        const agId = this.shortId(ag['agreementId']);
+        const parties = ag['parties'] || {};
+        const lines = [
+            `${indent}[${status}] Agreement ${agId}`,
+            `${indent}  Creator: ${this._labelParty(parties['creator'], ag['creatorIsYou'])}`,
+            `${indent}  Provider: ${this._labelParty(parties['provider'], ag['providerIsYou'])}`,
+            `${indent}  Payer: ${this._labelParty(parties['payer'], ag['payerIsYou'])}`,
+        ];
+        if (parties['proposedTo'])
+            lines.push(`${indent}  Proposed to: ${this._labelParty(parties['proposedTo'], ag['proposedToIsYou'])}`);
+        const proposal = ag['proposal'];
+        if (proposal?.['status'])
+            lines.push(`${indent}  Proposal: ${proposal['status']}${proposal['respondedBy'] ? ` (by ${proposal['respondedBy']})` : ''}`);
+        const money = ag['money'];
+        if (typeof money?.['price'] === 'number' && money['price'] > 0) {
+            const parts = [`${money['price']} cents`];
+            if (money['paymentStatus'] && money['paymentStatus'] !== 'none')
+                parts.push(money['paymentStatus']);
+            lines.push(`${indent}  Money: ${parts.join(', ')}`);
+        }
+        const terms = ag['terms'];
+        if (terms) {
+            const tparts = [];
+            if (terms['lifecycle'] && terms['lifecycle'] !== 'open')
+                tparts.push(`lifecycle: ${terms['lifecycle']}`);
+            if (terms['maxExecutions'] != null)
+                tparts.push(`maxExecutions: ${terms['maxExecutions']}`);
+            if (terms['expiresAt'])
+                tparts.push(`expiresAt: ${terms['expiresAt']}`);
+            if (terms['description'])
+                tparts.push(`"${terms['description']}"`);
+            if (tparts.length > 0)
+                lines.push(`${indent}  Terms: ${tparts.join(', ')}`);
+        }
+        if (ag['task']) {
+            lines.push('');
+            lines.push(`${indent}  Execution:`);
+            lines.push(this._renderTaskExecution(ag['task'], indent + '    '));
+        }
+        else
+            lines.push(`${indent}  Execution: (none yet)`);
+        return lines.join('\n');
+    }
+    _renderTaskExecution(task, indent = '') {
+        const state = (task['state'] || 'unknown').toUpperCase();
+        const id = this.shortId(task['taskId']);
+        const lines = [`${indent}[${state}] ${task['description'] || 'No description'}`, `${indent}  Task ID: ${id}`];
+        if (task['parentTaskId'])
+            lines.push(`${indent}  Parent task: ${task['parentTaskId']}`);
+        if (task['result'] && (task['state'] === 'completed' || task['state'] === 'failed')) {
+            const r = String(task['result']);
+            lines.push(`${indent}  Result: ${r.length > 100 ? r.slice(0, 100) + '...' : r}`);
+        }
+        const plan = task['plan'];
+        const steps = plan?.['steps'];
+        if (steps?.length) {
+            const sorted = [...steps].sort((a, b) => a['order'] - b['order']);
+            const done = sorted.filter(s => s['status'] === 'completed').length;
+            lines.push(`${indent}  Plan (${done}/${sorted.length} done):`);
+            for (const step of sorted) {
+                const icon = { pending: '○', in_progress: '●', completed: '✓', skipped: '–' }[step['status']] || '?';
+                const note = step['status'] === 'completed' && step['result'] ? ` → ${String(step['result']).slice(0, 60)}${String(step['result']).length > 60 ? '...' : ''}` : '';
+                lines.push(`${indent}    ${step['order']}. [${icon}] ${step['description'] || step['stepId']}${note}`);
+            }
+        }
+        const subtasks = task['subtasks'];
+        if (subtasks?.length) {
+            lines.push(`${indent}  Subtasks (${subtasks.length}):`);
+            for (const st of subtasks) {
+                const sstate = (st['state'] || 'unknown').toUpperCase();
+                const sid = this.shortId(st['taskId']);
+                lines.push(`${indent}    [${sstate}] ${st['description'] || sid} (${sid}, provider: ${st['providerIsYou'] ? 'You' : (st['provider'] ?? 'unassigned')})`);
+            }
+        }
+        return lines.join('\n');
+    }
+    _labelParty(id, isYou) {
+        if (!id)
+            return 'N/A';
+        return isYou ? `You (${id})` : id;
+    }
+    shortId(id) {
+        if (!id)
+            return '?';
+        if (!this.shortIds)
+            return id;
+        return id.length > 20 ? id.slice(0, 20) + '...' : id;
+    }
+    _indent(level) {
+        return ' '.repeat(level * this.indentSize);
+    }
+}
+export const agreementFormatter = new AgreementFormatter();

package/dist/formatters/HistoryFormatter.d.ts

@@ -0,0 +1,26 @@
+type AnyObj = Record<string, unknown>;
+interface HistoryFormatterOptions {
+    showTimestamps?: boolean;
+    shortIds?: boolean;
+}
+export declare class HistoryFormatter {
+    private showTimestamps;
+    private shortIds;
+    constructor(options?: HistoryFormatterOptions);
+    format(history: AnyObj[] | null | undefined, agentId: string, options?: {
+        mode?: string;
+    }): string;
+    formatEntry(entry: AnyObj, agentId: string, labelTypes?: boolean): string;
+    formatMessage(entry: AnyObj, agentId: string, timePrefix: string): string;
+    formatTaskHistory(entry: AnyObj, agentId: string, timePrefix: string): string;
+    formatArtifact(entry: AnyObj, _agentId: string, timePrefix: string): string;
+    formatParticipant(participant: AnyObj | null | undefined, agentId: string): string;
+    formatOwner(task: AnyObj, agentId: string): string;
+    formatExecutor(task: AnyObj, agentId: string): string;
+    shortId(id: string | null | undefined): string;
+    formatTime(timestamp: string | null | undefined): string;
+    formatArgs(args: AnyObj | null | undefined): string;
+    private safeParseJSON;
+}
+export declare const historyFormatter: HistoryFormatter;
+export {};

package/dist/formatters/HistoryFormatter.js

@@ -0,0 +1,173 @@
+export class HistoryFormatter {
+    showTimestamps;
+    shortIds;
+    constructor(options = {}) {
+        this.showTimestamps = options.showTimestamps ?? true;
+        this.shortIds = options.shortIds ?? false;
+    }
+    format(history, agentId, options = {}) {
+        if (!history?.length)
+            return 'No previous activity.';
+        const labelTypes = options.mode === 'mission';
+        const sorted = [...history].sort((a, b) => {
+            const tA = a['timestamp'] ? new Date(a['timestamp']).getTime() : 0;
+            const tB = b['timestamp'] ? new Date(b['timestamp']).getTime() : 0;
+            return tA - tB;
+        });
+        return sorted.map(entry => this.formatEntry(entry, agentId, labelTypes)).join('\n');
+    }
+    formatEntry(entry, agentId, labelTypes = false) {
+        const timestamp = this.showTimestamps ? this.formatTime(entry['timestamp']) : '';
+        const timePrefix = timestamp ? `[${timestamp}] ` : '';
+        const entryType = entry['entryType'];
+        if (entryType === 'message' || !entryType) {
+            const label = labelTypes ? '[CHAT] ' : '';
+            return `${label}${this.formatMessage(entry, agentId, timePrefix)}`;
+        }
+        if (entryType === 'task_history') {
+            const label = labelTypes ? '[TASK] ' : '';
+            return `${label}${this.formatTaskHistory(entry, agentId, timePrefix)}`;
+        }
+        if (entryType === 'artifact') {
+            const line = this.formatArtifact(entry, agentId, timePrefix);
+            if (labelTypes) {
+                if (entry['content_type'] === 'thought')
+                    return `[THOUGHT] ${line}`;
+                const text = entry['text'] || '';
+                const json = text.replace(/^operation_(?:started|completed|error):/, '');
+                const data = json ? this.safeParseJSON(json) : null;
+                const label = (data?.['type'] === 'tool' || text.includes('operation_error')) ? '[TOOL] ' : '[TASK] ';
+                return `${label}${line}`;
+            }
+            return line;
+        }
+        return `${timePrefix}${entry['text'] || 'Unknown entry'}`;
+    }
+    formatMessage(entry, agentId, timePrefix) {
+        const from = this.formatParticipant(entry['sender'], agentId);
+        const to = entry['receiver'] ? ` → ${this.formatParticipant(entry['receiver'], agentId)}` : '';
+        return `${timePrefix}${from}${to}: ${entry['text'] || ''}`;
+    }
+    formatTaskHistory(entry, agentId, timePrefix) {
+        const service = entry['service'];
+        const task = service?.['task'];
+        if (!task)
+            return `${timePrefix}Update`;
+        const changeType = service?.['changeType'];
+        const taskId = this.shortId(task['taskId']);
+        const agreementId = task['agreementId'] ? this.shortId(task['agreementId']) : null;
+        const desc = task['description'] || 'No description';
+        const ids = agreementId ? `agreement=${agreementId} task=${taskId}` : `task=${taskId}`;
+        switch (changeType) {
+            case 'created': {
+                const ag = task['agreement'];
+                const parties = ag?.['parties'] || {};
+                return `${timePrefix}Task created under agreement: "${desc}" (${ids})\n    Owner: ${this.formatOwner(task, agentId)}\n    Executor: ${this.formatExecutor(task, agentId)}\n    Proposed to: ${parties['proposedTo'] || 'N/A'}`;
+            }
+            case 'state_changed': {
+                const prev = service?.['previousState']?.['state'] || '?';
+                const next = service?.['newState']?.['state'] || '?';
+                return `${timePrefix}Task "${desc}" (${ids}): ${prev} → ${next}`;
+            }
+            case 'proposal_responded': {
+                const action = service?.['metadata']?.['action'];
+                return `${timePrefix}Proposal ${action ?? 'responded'} for "${desc}" (${ids})`;
+            }
+            case 'processing_changed': {
+                const processing = service?.['newState']?.['processing'];
+                return `${timePrefix}Task "${desc}" (${ids}): processing ${processing ? 'started' : 'stopped'}`;
+            }
+            default:
+                return `${timePrefix}${changeType}: "${desc}" (${ids})`;
+        }
+    }
+    formatArtifact(entry, _agentId, timePrefix) {
+        const text = entry['text'] || '';
+        if (entry['content_type'] === 'thought')
+            return `${timePrefix}Thought: ${text}`;
+        if (text.startsWith('operation_started:')) {
+            const data = this.safeParseJSON(text.replace('operation_started:', ''));
+            if (data?.['type'] === 'tool')
+                return `${timePrefix}Tool starting: ${data['tool']}(${this.formatArgs(data['args'])})`;
+            if (data?.['type'] === 'task')
+                return `${timePrefix}Task operation: ${data['operation']}`;
+            return `${timePrefix}Operation started: ${data?.['type'] || 'unknown'}`;
+        }
+        if (text.startsWith('operation_completed:')) {
+            const data = this.safeParseJSON(text.replace('operation_completed:', ''));
+            if (data?.['type'] === 'tool')
+                return `${timePrefix}Tool completed: ${data['tool']}`;
+            if (data?.['type'] === 'task')
+                return `${timePrefix}Task operation completed: ${data['operation']}`;
+            return `${timePrefix}Operation completed: ${data?.['type'] || 'unknown'}`;
+        }
+        if (text.startsWith('operation_error:')) {
+            const data = this.safeParseJSON(text.replace('operation_error:', ''));
+            return `${timePrefix}ERROR: ${data?.['error'] || 'Unknown error'}`;
+        }
+        return `${timePrefix}${text}`;
+    }
+    formatParticipant(participant, agentId) {
+        if (!participant)
+            return 'unknown';
+        // Message.sender is stored as {agentId, underAgreementId} (no `id`, no
+        // `type`) while Message.receiver is {id, type} — two different shapes on
+        // the same document (see backend Message schema). Without this fallback,
+        // every sender renders as "unknown (unknown)" and self-sent history rows
+        // never match `id === agentId`, so the agent can't recognize its own
+        // past messages in <history>.
+        const id = participant['id'] || participant['agentId'] || 'unknown';
+        if (participant['type'] === 'system')
+            return 'System';
+        if (id === agentId)
+            return 'You';
+        return `${id} (${participant['type'] || 'unknown'})`;
+    }
+    formatOwner(task, agentId) {
+        const ag = task['agreement'];
+        const creatorId = ag?.['parties']?.['creator'] ?? task['agentId'];
+        return creatorId === agentId ? 'You' : String(creatorId ?? 'N/A');
+    }
+    formatExecutor(task, agentId) {
+        const ag = task['agreement'];
+        const providerId = ag?.['parties']?.['provider'] ?? task['executorId'];
+        return providerId === agentId ? 'You' : String(providerId ?? 'N/A');
+    }
+    shortId(id) {
+        if (!id)
+            return '?';
+        if (!this.shortIds)
+            return id;
+        const parts = id.split('_');
+        if (parts.length >= 3)
+            return `task_...${parts[parts.length - 1]}`;
+        return id.length > 20 ? id.slice(0, 20) + '...' : id;
+    }
+    formatTime(timestamp) {
+        if (!timestamp)
+            return '??:??';
+        const date = new Date(timestamp);
+        if (isNaN(date.getTime()))
+            return '??:??';
+        return date.toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit', second: '2-digit', hour12: false, timeZone: 'UTC' });
+    }
+    formatArgs(args) {
+        if (!args || typeof args !== 'object')
+            return '';
+        const entries = Object.entries(args);
+        if (entries.length === 0)
+            return '';
+        if (entries.length <= 3)
+            return entries.map(([k, v]) => `${k}=${JSON.stringify(v)}`).join(', ');
+        return JSON.stringify(args);
+    }
+    safeParseJSON(str) {
+        try {
+            return JSON.parse(str);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+export const historyFormatter = new HistoryFormatter();

package/dist/formatters/index.js

@@ -0,0 +1,2 @@
+export { HistoryFormatter, historyFormatter } from './HistoryFormatter.js';
+export { AgreementFormatter, agreementFormatter } from './AgreementFormatter.js';

package/{src/index.ts → dist/index.d.ts}

@@ -3,16 +3,19 @@
  *
  * Foundation:
  *   • Outcome union — discriminated, hybrid (closed core + extension)
- *   • Workflow shape — explicit kind: 'parked' | 'thinking'
+ *   • Workflow shape — explicit kind: 'parked' | 'thinking' | 'mechanical'
  *   • Visible defaults — thinkingDefaults({ initial }) spread by author
  *   • Validation at load — defineAgent throws on hard problems, warns on soft
  */
-
 export { defineAgent } from './defineAgent.js';
 export { createMcpAgent, resolveZiggsGatewayTarget, wrapGatewayFetch, ZiggsGatewayError } from './adapters/McpAdapter.js';
 export type { CreateMcpAgentOptions, McpAgentHandle, McpTransportConfig } from './adapters/McpAdapter.js';
-export { AgentHost, createAgent, createAgentPool } from './AgentHost.js';
+export { AgentHost, createAgent, createAgentPool, DEFAULT_MODEL } from './AgentHost.js';
 export { Agent } from './agent/Agent.js';
+export { ClaudeSdkAgent } from './agent/ClaudeSdkAgent.js';
+export type { CognitionKind } from './agent/ClaudeSdkAgent.js';
+export { ziggsBrain, claudeBrain, isBrainSelection, isClaudeCognition } from './brain/index.js';
+export type { Brain, BrainSelection, ZiggsBrainConfig, ClaudeBrainConfig, } from './brain/index.js';
 export type { TickInput, TickOutput, AgentOptions } from './agent/Agent.js';
 export type { SessionResolver, AgentHostOptions } from './AgentHost.js';
 export { createZiggsEffectHandler } from './server/ZiggsEffectHandler.js';
@@ -22,34 +25,17 @@ export { StateTimers } from './server/StateTimers.js';
 export type { StateTimeoutEvent } from './server/StateTimers.js';
 export { OutboxBuffer } from './server/OutboxBuffer.js';
 export { normalizeIncomingEvent } from './ingress/normalizeIncoming.js';
-
-// Runtime primitives
 export { AgentMachine, type TransitionEvent } from './runtime/AgentMachine.js';
 export { runTurn } from './runtime/runTurn.js';
+export { runMechanical } from './runtime/runMechanical.js';
 export { PromptBuilder } from './runtime/PromptBuilder.js';
-export { thinkingDefaults, defineThinkingState, DEFAULT_WAIT_PROMPT } from './runtime/defaults.js';
+export { thinkingDefaults, defineThinkingState, defineMechanicalState, DEFAULT_WAIT_PROMPT } from './runtime/defaults.js';
 export { KICKOFF_STATE, injectKickoffDefault, buildKickoffState } from './runtime/kickoff.js';
 export { validateWorkflow, WorkflowValidationError } from './runtime/validateWorkflow.js';
+export { deriveRespondsToProposals, statesRespondToProposals, } from './runtime/deriveRespondsToProposals.js';
 export { outcomeFromEvent, outcomeFromActionResult, applyOutcomeToCtx } from './runtime/buildOutcome.js';
-
-// Types
-export type {
-  Outcome, OutcomeKind,
-  Ctx, Identity, HistoryEntry, ToolResultEntry,
-  Workflow, State, ParkedState, ThinkingState,
-  Action, Transition, PromptDef, ActionPrompt, Produces, ProducesFn,
-  AgreementRef, TaskRef, ProposalRef,
-  AgentConfig, DefineAgentInput, ServicesConfig,
-  // Effects — Agent↔Server boundary
-  Effect, EffectKind, EffectResult, EffectResultMap, EffectHandler,
-  LlmMessage, LlmToolCall, LlmToolSchema, LlmResponse,
-  ContextSnapshot, ReadContextOpts, ToolCallResult, RecordedEntry,
-} from './types.js';
-
+export type { Outcome, OutcomeKind, Ctx, Identity, HistoryEntry, ToolResultEntry, Workflow, State, ParkedState, ThinkingState, MechanicalState, Action, Transition, PromptDef, ActionPrompt, Produces, ProducesFn, AgreementRef, TaskRef, ProposalRef, AgentConfig, DefineAgentInput, ServicesConfig, Effect, EffectKind, EffectResult, EffectResultMap, EffectHandler, LlmMessage, LlmToolCall, LlmToolSchema, LlmResponse, ContextSnapshot, ReadContextOpts, ToolCallResult, RecordedEntry, } from './types.js';
 export { default } from './AgentHost.js';
-
-// ── Supporting modules ──────────────────────────────────────────────────────
-
 export { validateContext, ContextWarning } from './cognition/validateContext.js';
 export { runLauncher } from './server/runLauncher.js';
 export { ConnectionPool } from './server/ConnectionPool.js';
@@ -68,25 +54,8 @@ export { ProactiveTrigger } from './server/proactive/ProactiveTrigger.js';
 export { ZiggsPayClient, createZiggsPayClient } from './server/ziggspay/ZiggsPayClient.js';
 export { ZiggsConnectClient, createZiggsConnectClient } from './server/ziggsconnect/ZiggsConnectClient.js';
 export { ZiggsContextClient } from './server/ziggscontext/ZiggsContextClient.js';
-export type {
-  ZiggsContextClientOptions,
-  ContextReachDescriptor,
-  DelegateContextGrantParams,
-} from './server/ziggscontext/ZiggsContextClient.js';
-// All agent tool bundles live under server/tools/ (tier1 = protocol grammar,
-// tier2 = opt-in HTTP capability bundles). Single home: server/tools/index.ts.
-export {
-  // Tier 1 — protocol grammar (framework-managed via taskTools).
-  PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool,
-  agreementRespondTool, agreementCounterProposalTool, agreementCheckProposalTool,
-  taskSpawnTool, taskUpdateTool, taskUpdatePlanStepTool,
-  dispatchProtocolOp,
-  // Tier 2 — opt-in capability bundles (spread into `tools:`).
-  PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool,
-  CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool,
-  DISCOVERY_TOOLS, agentSearchTool, agentGetTool,
-  MARKETPLACE_TOOLS, marketplaceViewTool,
-} from './server/tools/index.js';
+export type { ZiggsContextClientOptions, ContextReachDescriptor, DelegateContextGrantParams, } from './server/ziggscontext/ZiggsContextClient.js';
+export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementCounterProposalTool, agreementCheckProposalTool, taskSpawnTool, taskUpdateTool, taskUpdatePlanStepTool, dispatchProtocolOp, PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, } from './server/tools/index.js';
 export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from './tasks/protocolRegistry.js';
 export { InMemoryStore, FileMemoryStore } from './memory/MemoryStore.js';
 export type { MemoryStore } from './memory/MemoryStore.js';
@@ -95,16 +64,7 @@ export { classifyIncomingEvent } from './context/classifyEnvelope.js';
 export { buildContextUpdates, CONTEXT_RESET } from './context/applyEffects.js';
 export { getBatchEvents, isTaskResultRelevantToAgent } from './context/batch.js';
 export { classifyWorkflowEvent, findTaskResult, unwrapBatchEvent, findIncomingTaskResult } from './context/routingLabels.js';
-export {
-  WebSocketClient,
-  MessagesClient,
-  ArtifactsClient,
-  ScopeClient,
-  AgentSearchClient,
-  getBackendUrl,
-  getWebSocketUrl,
-} from '@ziggs-ai/api-client';
-
+export { WebSocketClient, MessagesClient, ArtifactsClient, AgentSearchClient, getBackendUrl, getWebSocketUrl, } from '@ziggs-ai/api-client';
 export { runInboxCatchUp } from './server/InboxCatchUp.js';
 export type { InboxCatchUpDeps, InboxCatchUpResult } from './server/InboxCatchUp.js';
 export { SeenMessages } from './server/SeenMessages.js';