@ziggs-ai/agent-sdk 0.1.12 → 0.2.0

package/dist/runtime/buildOutcome.js

@@ -0,0 +1,464 @@
+import { isProtocolToolName, mapProtocolToolToOperation } from '../tasks/protocolRegistry.js';
+import { getBatchEvents, isTaskResultRelevantToAgent } from '../context/batch.js';
+// ── outcomeFromEvent: incoming wire event → Outcome ──────────────────────────
+/**
+ * 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 function outcomeFromEvent(rawEvent, ownAgentId) {
+    if (!rawEvent)
+        return { kind: 'enter' };
+    const events = getBatchEvents(rawEvent);
+    let best = null;
+    for (const ev of events) {
+        if (!ev)
+            continue;
+        const candidate = singleEventToOutcome(ev, ownAgentId);
+        if (!candidate)
+            continue;
+        if (!best || outcomeRank(candidate) > outcomeRank(best))
+            best = candidate;
+    }
+    return best ?? { kind: 'enter' };
+}
+function singleEventToOutcome(ev, ownAgentId) {
+    if (ev.type === 'agreement_lifecycle') {
+        const operation = ev.operation;
+        const agreementId = ev.agreementId ?? '';
+        const action = operation === 'proposal_rejected'
+            ? 'reject'
+            : operation === 'proposal_approved' || operation === 'proposal_approved_execute'
+                ? 'approve'
+                : null;
+        if (action && agreementId) {
+            return {
+                kind: 'proposal-resolved',
+                action,
+                proposal: { agreementId },
+                proposedByMe: false, // real value stamped in AgentMachine._handleFrame from ctx (needs pendingProposalAgreementId, unavailable here)
+            };
+        }
+        return null;
+    }
+    if (ev.type === 'task_result') {
+        const result = ev.result || {};
+        if (ownAgentId &&
+            !isTaskResultRelevantToAgent(result, ownAgentId) &&
+            ev.receiverId !== ownAgentId) {
+            return null;
+        }
+        // Agreement lifecycle notification routed as task_result by normalizeIncomingEvent.
+        // _operation is set to the backend operation name (e.g. 'proposal_approved').
+        const inboundOp = result._operation;
+        if (inboundOp) {
+            const proposalAction = inboundOp === 'proposal_approved' ? 'approve'
+                : inboundOp === 'proposal_rejected' ? 'reject'
+                    : null;
+            if (proposalAction) {
+                const agId = result.agreementId;
+                const proposal = agId
+                    ? { agreementId: agId, agreement: result }
+                    : { agreementId: '' };
+                return { kind: 'proposal-resolved', action: proposalAction, proposal, proposedByMe: false }; // real value stamped in AgentMachine._handleFrame from ctx
+            }
+            // Other lifecycle ops (countered, expired) treated as enter — no FSM action needed here.
+            return null;
+        }
+        // Tasks are born active in the new model — no `proposal` task state.
+        // The wire shape `task_result` always carries an active or terminal task.
+        const task = result;
+        const ag = result.agreement;
+        const parties = ag?.parties || {};
+        const state = result.state;
+        // Direct assignment to me (provider) — task spawned, citing an active agreement.
+        const isAssignedToMe = (result.providerIsYou || parties.provider === ownAgentId) &&
+            (state === 'active' || state === 'in-progress');
+        if (isAssignedToMe) {
+            return { kind: 'task-assigned', task };
+        }
+        if (state === 'active' || state === 'in-progress') {
+            return { kind: 'task-assigned', task };
+        }
+        if (state === 'completed' || state === 'failed') {
+            return {
+                kind: 'subtask-finished',
+                status: state === 'completed' ? 'completed' : 'failed',
+                task,
+                result,
+            };
+        }
+        if (state === 'cancelled') {
+            return {
+                kind: 'subtask-finished',
+                status: 'failed',
+                task,
+                result,
+            };
+        }
+        // Fallback: addressed to us with no clear state.
+        if (ownAgentId && ev.receiverId === ownAgentId) {
+            return { kind: 'task-assigned', task };
+        }
+        return { kind: 'subtask-finished', status: 'completed', task, result };
+    }
+    if (ev.type === 'resource_changed') {
+        const resource = (ev.resource ?? ev);
+        const reason = resource.reason;
+        if (resource.kind === 'agreement' &&
+            (reason === 'proposal_approved' || reason === 'proposal_rejected')) {
+            const agreementId = resource.agreementId ?? resource.resourceId ?? '';
+            const proposal = { agreementId };
+            return {
+                kind: 'proposal-resolved',
+                action: reason === 'proposal_approved' ? 'approve' : 'reject',
+                proposal,
+                proposedByMe: false, // real value stamped in AgentMachine._handleFrame from ctx
+            };
+        }
+        if (resource.kind === 'task-state' && reason === 'subtask_completed') {
+            const taskId = resource.taskId ?? resource.resourceId ?? '';
+            const task = { taskId, state: 'completed' };
+            return { kind: 'subtask-finished', status: 'completed', task, result: task };
+        }
+        return null;
+    }
+    if (ev.type === 'state-timeout') {
+        // Synthetic frame from AgentHost's StateTimers — host-constructed, fields always present.
+        return { kind: 'state-timeout', state: ev.state, waitedMs: ev.waitedMs };
+    }
+    // Only real inbound chat messages should drive the FSM. Backend bookkeeping
+    // (presence/heartbeat, raw `batch` outer frames, etc.) are NOT chat traffic.
+    if (ev.type !== 'message')
+        return null;
+    // Suppress our own messages echoed back through the chat fanout.
+    if (ownAgentId && ev.senderId && ev.senderId === ownAgentId)
+        return null;
+    const text = typeof ev.text === 'string' ? ev.text : undefined;
+    const senderType = typeof ev.senderType === 'string' ? ev.senderType : undefined;
+    return { kind: 'message-received', text, senderId: ev.senderId, senderType };
+}
+// Higher rank wins when collapsing batched events into one outcome.
+function outcomeRank(o) {
+    switch (o.kind) {
+        case 'task-assigned': return 100;
+        case 'proposal-resolved': return 90;
+        case 'subtask-finished': return 80;
+        case 'message-received': return 10;
+        // Any real event coalesced into the same batch supersedes the timer —
+        // waking to "nothing happened" is moot when something did. Must stay below
+        // message-received (10).
+        case 'state-timeout': return 1;
+        default: return 50;
+    }
+}
+// ── outcomeFromActionResult: turn output → 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 function outcomeFromActionResult(actionName, action, args, emittedEvents, toolResultsOut) {
+    if (!emittedEvents.length) {
+        return { kind: 'error', source: 'unknown', cause: `action "${actionName}" emitted nothing`, retryable: false };
+    }
+    // Collect tool results in caller's accumulator (used in prompts and ctx).
+    for (const e of emittedEvents) {
+        if (e?.type === 'tool_result')
+            toolResultsOut.push({ tool: e.tool || '', result: e.result });
+        if (e?.type === 'tool_error')
+            toolResultsOut.push({ tool: e.tool || '', error: e.error });
+    }
+    // Pick the "primary" event the outcome describes.
+    //
+    // Protocol-level state changes (agreement creation, task assignment/closure,
+    // proposal response) outrank EVERYTHING else, including message_sent and
+    // waited. Why: when the LLM batches `delegate` + `wait` in one round, the
+    // sub-agreement DOES get created server-side, but if `waited` wins the FSM
+    // sees `wait` and bounces back to `idle` instead of transitioning to
+    // `awaitingSubAgreementApproval` — and the chain stalls. The meaningful
+    // turn outcome is the work that landed, not the LLM's terminal decision.
+    //
+    // Among non-protocol events: message_sent / waited still outrank pure
+    // query tool_results (e.g. agent_network search) and tool_errors, because
+    // those are the LLM's explicit final intent in turns that did no protocol
+    // work.
+    const primary = emittedEvents.find(e => e.type === 'task_result' && isStateChangingProtocolEvent(e)) ??
+        emittedEvents.find(e => e.type === 'tool_result' && isStateChangingProtocolEvent(e)) ??
+        emittedEvents.find(e => e.type === 'message_sent') ??
+        emittedEvents.find(e => e.type === 'message_duplicate_skipped') ??
+        emittedEvents.find(e => e.type === 'waited') ??
+        emittedEvents.find(e => e.type === 'tool_result') ??
+        emittedEvents.find(e => e.type === 'tool_error') ??
+        emittedEvents.find(e => e.type === 'task_result') ??
+        emittedEvents.find(e => e.type === 'task_error') ??
+        emittedEvents[0];
+    // Resolve the kind via produces (preferred) or by inferring from primary.
+    let kind = null;
+    if (action?.produces) {
+        const p = action.produces;
+        const result = primary?.type === 'tool_result' ? primary.result : undefined;
+        kind = typeof p === 'function' ? p(result, args) : p;
+    }
+    if (!kind)
+        kind = inferKindFromEvent(primary);
+    return buildOutcomeOfKind(kind, primary, action);
+}
+/**
+ * Whether a tool_result / task_result represents a protocol state change
+ * (agreement creation, task assignment / closure, proposal response). Used
+ * to outrank pure query tool_results (e.g. `agent_network search`) when the
+ * same turn batches multiple tools.
+ */
+function isStateChangingProtocolEvent(ev) {
+    const op = ev.type === 'task_result'
+        ? ev.operation
+        : (ev.tool && isProtocolToolName(ev.tool) ? mapProtocolToolToOperation(ev.tool) : null);
+    if (!op)
+        return false;
+    const r = ev.result ?? {};
+    if (r.success === false || r.error)
+        return false;
+    const ag = r.agreement ?? (r.agreementId ? r : null);
+    const task = r.task || (r.taskId ? r : null);
+    const proposalStatus = ag?.proposal?.status;
+    const state = task?.state || r.state;
+    if (op === 'agreement-propose' || op === 'agreement-subcontract') {
+        return proposalStatus === 'pending' || proposalStatus === 'approved' || !!ag?.agreementId;
+    }
+    if (op === 'agreement-respond')
+        return true;
+    if (op === 'task-update') {
+        return state === 'completed' || state === 'failed' || state === 'cancelled';
+    }
+    if (op === 'task-spawn')
+        return !!task?.taskId;
+    return false;
+}
+function inferKindFromEvent(primary) {
+    if (!primary)
+        return 'error';
+    switch (primary.type) {
+        case 'message_sent': return 'message-sent';
+        case 'message_duplicate_skipped': return 'message-sent';
+        case 'waited': return 'wait';
+        case 'tool_error': return 'error';
+        case 'task_error': return 'error';
+        case 'tool_result': return inferKindFromToolResult(primary);
+        case 'task_result': return inferKindFromTaskResult(primary);
+        default: return 'tool-result';
+    }
+}
+function inferKindFromToolResult(ev) {
+    if (!isProtocolToolName(ev.tool ?? ''))
+        return 'tool-result';
+    const op = mapProtocolToolToOperation(ev.tool ?? '');
+    return inferKindFromProtocolOp(op ?? undefined, ev.result);
+}
+function inferKindFromTaskResult(ev) {
+    return inferKindFromProtocolOp(ev.operation, ev.result);
+}
+function inferKindFromProtocolOp(op, result) {
+    const r = result || {};
+    const ag = r.agreement ?? (r.agreementId ? r : undefined);
+    const task = r.task || (r.taskId ? r : undefined);
+    // Agreement creation verbs no longer create paired tasks. The caller (creator)
+    // has made a proposal awaiting response from the proposedTo party.
+    if (op === 'agreement-propose' ||
+        op === 'agreement-subcontract') {
+        return 'proposal-made';
+    }
+    if (op === 'task-spawn') {
+        // A task was just spawned under an active agreement. From the spawner's
+        // side this is a delegation; the executor sees `task-assigned` via the
+        // task_result event channel.
+        return 'task-delegated';
+    }
+    if (op === 'task-update') {
+        const status = task?.state || r.state || r.status;
+        if (status === 'completed' || status === 'failed')
+            return 'task-closed';
+        return 'tool-result';
+    }
+    if (op === 'agreement-respond') {
+        // The responder's tool result is the agreement after approve/reject.
+        return 'proposal-resolved';
+    }
+    void ag;
+    return 'tool-result';
+}
+function buildOutcomeOfKind(kind, primary, action) {
+    const tool = action?.tool || primary?.tool || '';
+    const result = primary?.type === 'tool_result' ? primary.result : primary?.result;
+    switch (kind) {
+        case 'enter':
+        case 'wait':
+            return { kind };
+        case 'state-timeout':
+            // Runtime-generated only (validateWorkflow rejects produces:'state-timeout').
+            // Break-fast backstop if an action somehow declares it.
+            throw new Error(`action produced reserved outcome kind "state-timeout" — runtime-generated only`);
+        case 'message-sent':
+            return { kind, text: primary?.message, receiverId: primary?.receiverId };
+        case 'message-received':
+            return { kind, text: primary?.text };
+        case 'task-assigned': {
+            const task = (result?.task || result || {});
+            return { kind, task };
+        }
+        case 'task-delegated': {
+            const task = (result?.task || result || {});
+            return { kind, task };
+        }
+        case 'task-closed': {
+            const raw = result?.task?.state || result?.state;
+            const status = raw === 'failed' ? 'failed' : 'completed';
+            return { kind, status, result };
+        }
+        case 'subtask-finished': {
+            const task = (result?.task || result || {});
+            const status = (task.state === 'failed' ? 'failed' : 'completed');
+            return { kind, status, task, result };
+        }
+        case 'proposal-made': {
+            const ag = result?.agreement ?? (result?.agreementId ? result : undefined);
+            const proposal = ag
+                ? { agreementId: ag.agreementId, agreement: ag }
+                : { agreementId: result?.agreementId || '' };
+            return { kind, proposal };
+        }
+        case 'proposal-resolved': {
+            const ag = result?.agreement ?? (result?.agreementId ? result : undefined);
+            const status = ag?.proposal?.status;
+            const action_ = status === 'rejected' ? 'reject' : 'approve';
+            const proposal = ag
+                ? { agreementId: ag.agreementId, agreement: ag }
+                : { agreementId: result?.agreementId || '' };
+            return { kind, action: action_, proposal, proposedByMe: false }; // turn path = our own agreement_respond ran — we are the responder, by definition not the proposer
+        }
+        case 'tool-result':
+            return { kind, tool, result };
+        case 'error': {
+            const cause = primary?.error || primary?.result || 'unknown error';
+            const source = primary?.type === 'tool_error' || primary?.type === 'tool_result' ? 'tool' : 'unknown';
+            return { kind, source, cause, retryable: false };
+        }
+        case 'extension':
+            return { kind, name: tool || 'unknown', payload: result };
+    }
+}
+// ── applyOutcomeToCtx: persistent ctx updates from a new 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 function applyOutcomeToCtx(ctx, outcome) {
+    ctx.lastOutcome = outcome;
+    switch (outcome.kind) {
+        case 'task-assigned': {
+            const t = outcome.task || {};
+            const tid = t.taskId || t.id;
+            const agId = t.agreementId || t.agreement?.agreementId || ctx.pendingProposalAgreementId;
+            if (tid)
+                ctx.activeTaskId = tid;
+            if (agId)
+                ctx.activeAgreementId = agId;
+            ctx.pendingProposalAgreementId = null;
+            return;
+        }
+        case 'task-delegated': {
+            const t = outcome.task || {};
+            const tid = t.taskId;
+            const agId = t.agreementId || t.agreement?.agreementId;
+            if (tid && !(tid in ctx.pendingSubtasks)) {
+                ctx.pendingSubtasks[tid] = {
+                    agentId: t.assigneeId ?? t.executorId ?? t.agreement?.parties?.provider ?? null,
+                    spawnedAt: Date.now(),
+                };
+            }
+            if (agId && !ctx.delegatedAgreementIds.includes(agId))
+                ctx.delegatedAgreementIds.push(agId);
+            return;
+        }
+        case 'proposal-made': {
+            const agId = outcome.proposal?.agreementId;
+            if (agId)
+                ctx.pendingProposalAgreementId = agId;
+            return;
+        }
+        case 'proposal-resolved': {
+            // Approval of the agent's PRIMARY proposal (the one binding it to its
+            // counterparty — e.g. Ziggs ↔ user) promotes the pending id into
+            // activeAgreementId so transitions gated on activeAgreementId fire.
+            // We only do this when no agreement is currently active, so that
+            // approvals of CHILD sub-agreements (e.g. coffee-agent approving the
+            // Ziggs-issued subcontract) don't overwrite the root the primary agent
+            // is bound to. Sub-agreement bookkeeping lives in delegatedAgreementIds
+            // (recorded on task-delegated) — not here.
+            if (outcome.action === 'approve' && !ctx.activeAgreementId) {
+                const agId = outcome.proposal?.agreementId || ctx.pendingProposalAgreementId;
+                if (agId)
+                    ctx.activeAgreementId = agId;
+            }
+            ctx.pendingProposalAgreementId = null;
+            return;
+        }
+        case 'subtask-finished': {
+            const t = outcome.task;
+            const taskId = t?.taskId;
+            const agId = t?.agreementId || t?.agreement?.agreementId;
+            if (taskId) {
+                const pending = ctx.pendingSubtasks[taskId];
+                delete ctx.pendingSubtasks[taskId];
+                const payload = t?.result ?? null;
+                const existing = ctx.collectedResults.find(r => r.taskId === taskId);
+                if (!existing) {
+                    ctx.collectedResults.push({
+                        taskId,
+                        agentId: pending?.agentId ?? t?.assigneeId ?? t?.executorId ?? t?.agreement?.parties?.provider ?? null,
+                        status: outcome.status,
+                        result: payload,
+                    });
+                }
+                else if (existing.result == null && payload != null) {
+                    // A bare resource_changed(subtask_completed) skeleton ({taskId, state})
+                    // can arrive BEFORE the full task_result for the same completion.
+                    // Upgrade the placeholder in place instead of dropping the real payload.
+                    // The skeleton often lacks executor identity, so also fill agentId
+                    // from the fuller frame when the placeholder recorded none.
+                    existing.status = outcome.status;
+                    existing.result = payload;
+                    if (existing.agentId == null) {
+                        existing.agentId = t?.assigneeId ?? t?.executorId ?? t?.agreement?.parties?.provider ?? null;
+                    }
+                }
+            }
+            if (agId)
+                ctx.delegatedAgreementIds = ctx.delegatedAgreementIds.filter(id => id !== agId);
+            return;
+        }
+        case 'task-closed': {
+            ctx.activeAgreementId = null;
+            ctx.activeTaskId = null;
+            ctx.pendingProposalAgreementId = null;
+            ctx.pendingSubtasks = {};
+            ctx.collectedResults = [];
+            ctx.delegatedAgreementIds = [];
+            return;
+        }
+        default:
+            return;
+    }
+}

package/dist/runtime/defaults.d.ts

@@ -0,0 +1,54 @@
+import type { Action, Ctx, MechanicalState, Outcome, Produces, Transition, ThinkingState } from '../types.js';
+/**
+ * Defaults that workflow authors spread into thinking states explicitly.
+ * No auto-injection — what you read in the file is what runs.
+ *
+ *   const dflt = thinkingDefaults({ initial: 'idle' });
+ *
+ *   listening: {
+ *     kind: 'thinking',
+ *     ...dflt,
+ *     prompt: { ... },
+ *     actions: { ...dflt.actions, greetUser: { ... } },
+ *     transitions: [
+ *       { to: 'executing', when: o => o.kind === 'task-assigned' },
+ *       ...dflt.transitions,
+ *     ],
+ *   }
+ */
+export interface ThinkingDefaults {
+    actions: Record<string, Action>;
+    transitions: Transition[];
+}
+export declare const DEFAULT_WAIT_PROMPT: Readonly<{
+    instruction: "Do nothing - wait for the next event.";
+    when: "No action is needed, you are waiting for external input, or you should pause without repeating yourself.";
+    format: "{\"thought\": \"...\", \"action\": \"wait\"}";
+}>;
+export declare function thinkingDefaults(opts: {
+    initial: string;
+}): ThinkingDefaults;
+/**
+ * Convenience builder for a `thinking` state that always carries the defaults.
+ * Equivalent to spreading manually but the spread points are in one place.
+ *
+ *   defineThinkingState({ initial: 'idle' }, {
+ *     prompt: { ... },
+ *     actions: { greetUser: { ... } },
+ *     transitions: [ { to: 'executing', when: o => o.kind === 'task-assigned' } ],
+ *   })
+ */
+export declare function defineThinkingState(opts: {
+    initial: string;
+}, state: Omit<ThinkingState, 'kind' | 'actions' | 'transitions'> & {
+    actions: Record<string, Action>;
+    transitions: Transition[];
+}): ThinkingState;
+/** ZIG-764: mechanical state — one tool call, zero LLM turns. */
+export declare function defineMechanicalState(state: {
+    tool: string;
+    args?: Record<string, unknown>;
+    buildArgs?: (ctx: Ctx, outcome: Outcome) => Record<string, unknown>;
+    produces: Produces;
+    transitions: Transition[];
+}): MechanicalState;

package/dist/runtime/defaults.js

@@ -0,0 +1,47 @@
+export const DEFAULT_WAIT_PROMPT = Object.freeze({
+    instruction: 'Do nothing - wait for the next event.',
+    when: 'No action is needed, you are waiting for external input, or you should pause without repeating yourself.',
+    format: '{"thought": "...", "action": "wait"}',
+});
+export function thinkingDefaults(opts) {
+    const { initial } = opts;
+    return {
+        actions: {
+            wait: {
+                prompt: { ...DEFAULT_WAIT_PROMPT },
+                produces: 'wait',
+            },
+        },
+        transitions: [
+            { to: initial, when: o => o.kind === 'wait' },
+            { to: initial, when: o => o.kind === 'message-sent' },
+            // Errors (empty/failed turns) fall back to the initial state instead of
+            // silently re-entering and recursing until the depth guard (ZIG-303).
+            { to: initial, when: o => o.kind === 'error' },
+        ],
+    };
+}
+/**
+ * Convenience builder for a `thinking` state that always carries the defaults.
+ * Equivalent to spreading manually but the spread points are in one place.
+ *
+ *   defineThinkingState({ initial: 'idle' }, {
+ *     prompt: { ... },
+ *     actions: { greetUser: { ... } },
+ *     transitions: [ { to: 'executing', when: o => o.kind === 'task-assigned' } ],
+ *   })
+ */
+export function defineThinkingState(opts, state) {
+    const dflt = thinkingDefaults(opts);
+    return {
+        kind: 'thinking',
+        prompt: state.prompt,
+        allowNoWait: state.allowNoWait,
+        actions: { ...dflt.actions, ...state.actions },
+        transitions: [...state.transitions, ...dflt.transitions],
+    };
+}
+/** ZIG-764: mechanical state — one tool call, zero LLM turns. */
+export function defineMechanicalState(state) {
+    return { kind: 'mechanical', ...state };
+}

package/dist/runtime/deriveRespondsToProposals.d.ts

@@ -0,0 +1,9 @@
+import type { State, Workflow } from '../types.js';
+/**
+ * ZIG-826: true when the workflow exposes `agreement_respond` on a thinking
+ * action — the agent can approve/reject inbound proposals directed at it.
+ * Kickoff-only states (proposer-side approval → task_spawn) do not count.
+ */
+export declare function deriveRespondsToProposals(workflow: Workflow): boolean;
+/** Scan custom states (pre-defineAgent) for agreement_respond actions. */
+export declare function statesRespondToProposals(states: Record<string, State> | undefined): boolean;

package/dist/runtime/deriveRespondsToProposals.js

@@ -0,0 +1,38 @@
+/**
+ * ZIG-826: true when the workflow exposes `agreement_respond` on a thinking
+ * action — the agent can approve/reject inbound proposals directed at it.
+ * Kickoff-only states (proposer-side approval → task_spawn) do not count.
+ */
+export function deriveRespondsToProposals(workflow) {
+    if (!workflow?.states)
+        return false;
+    for (const state of Object.values(workflow.states)) {
+        if (state.kind !== 'thinking')
+            continue;
+        const actions = state.actions;
+        if (!actions)
+            continue;
+        for (const action of Object.values(actions)) {
+            if (action?.tool === 'agreement_respond')
+                return true;
+        }
+    }
+    return false;
+}
+/** Scan custom states (pre-defineAgent) for agreement_respond actions. */
+export function statesRespondToProposals(states) {
+    if (!states)
+        return false;
+    for (const state of Object.values(states)) {
+        if (state.kind !== 'thinking')
+            continue;
+        const actions = state.actions;
+        if (!actions)
+            continue;
+        for (const action of Object.values(actions)) {
+            if (action?.tool === 'agreement_respond')
+                return true;
+        }
+    }
+    return false;
+}

package/dist/runtime/kickoff.d.ts

@@ -0,0 +1,15 @@
+import type { ThinkingState, Workflow } from '../types.js';
+/** Reserved state name for the injected agreement-kickoff default. */
+export declare const KICKOFF_STATE = "kickingOff";
+export declare function buildKickoffState(initial: string): ThinkingState;
+/**
+ * Agreement-kickoff default. For every state whose transitions do not already
+ * match a proposer-side approval (probe above), append a transition to the
+ * injected `kickingOff` state. Appended LAST so any user transition on the same
+ * outcome always wins (first match wins in AgentMachine._evaluateTransitions).
+ * Returns a NEW workflow — input states are not mutated. After kickoff the
+ * machine returns to `initial`; when this agent is itself the provider the
+ * backend then assigns the spawned task back to it as a normal task-assigned
+ * event, which the author's existing work loop handles.
+ */
+export declare function injectKickoffDefault(workflow: Workflow): Workflow;