@ziggs-ai/agent-sdk 0.1.11 → 0.2.0

package/dist/runtime/kickoff.js

@@ -0,0 +1,112 @@
+import { thinkingDefaults } from './defaults.js';
+import { PROBE_CTX } from './validateWorkflow.js';
+/** Reserved state name for the injected agreement-kickoff default. */
+export const KICKOFF_STATE = 'kickingOff';
+// Synthetic outcome used to ask "does this state already handle a proposer-side
+// approval?" — the same probe pattern validateWorkflow uses for the wait/error
+// fallthrough checks.
+const PROBE_APPROVE = {
+    kind: 'proposal-resolved',
+    action: 'approve',
+    proposal: { agreementId: '__kickoff_probe__' },
+    proposedByMe: true,
+};
+const KICKOFF_TRANSITION = {
+    to: KICKOFF_STATE,
+    when: (o, ctx) => o.kind === 'proposal-resolved' &&
+        o.action === 'approve' &&
+        o.proposedByMe === true &&
+        // "first task" guard — both branches cover one exact scenario: a task under
+        // THIS agreement already exists because a racing task_result frame was
+        // applied to ctx before this approval frame.
+        // (1) we already delegated under it:
+        !ctx.delegatedAgreementIds.includes(o.proposal.agreementId) &&
+        // (2) we already hold an assigned task bound to it (task-assigned sets
+        // activeTaskId + activeAgreementId together in applyOutcomeToCtx):
+        !(ctx.activeTaskId !== null && ctx.activeAgreementId === o.proposal.agreementId),
+};
+// A state "handles" proposer-approval if some transition would fire for it.
+// An unconditional (when-less) transition counts: it catches every outcome,
+// so the kickoff transition — appended LAST — would be unreachable dead code
+// there anyway. Consequence to know: a state whose only route for a
+// proposal-resolved/approve is an unconditional fallthrough to an UNRELATED
+// state will NOT auto-kickoff (the approval follows the fallthrough instead).
+// Authors who want guaranteed kickoff in such a state must add an explicit
+// `when: o => o.kind === 'proposal-resolved' && o.action === 'approve'`
+// transition (which this probe then respects) — or route approval into a
+// thinking state that spawns the task itself.
+function stateHandlesProposerApproval(state) {
+    return state.transitions.some(t => {
+        if (!t.when)
+            return true;
+        try {
+            return !!t.when(PROBE_APPROVE, PROBE_CTX);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+export function buildKickoffState(initial) {
+    const dflt = thinkingDefaults({ initial });
+    return {
+        kind: 'thinking',
+        prompt: {
+            role: 'The counterparty just approved an agreement you proposed. The platform never auto-starts work — as the proposer, you spawn the first task now.',
+            goal: 'Spawn exactly one task under the just-approved agreement so work begins.',
+            constraints: 'The approved agreement id is in <event> and as activeAgreementId in <machine_context>; the agreement row is in <agreements>. Call task_spawn with that agreementId and a description of the concrete work the agreement covers. Include ALL specifics the counterparty provided in <history> (addresses, quantities, times, item names, deliverables) — the executor has no other way to get them. Plain natural language, no step numbering. Do not re-negotiate — the agreement is active. Do not send a chat message instead of spawning. If <agreements> or <history> show a task already running under this agreement, choose wait.',
+        },
+        actions: {
+            ...dflt.actions,
+            spawnFirstTask: {
+                prompt: {
+                    when: 'Always — this state exists only to spawn the first task under the agreement whose proposal was just approved. Pick wait only if a task already exists under it.',
+                    instruction: 'Spawn the first task under the approved agreement so work starts.',
+                    format: '{"agreementId": "<the agreement whose proposal was just approved>", "description": "<concrete work + all counterparty specifics from history>"}',
+                },
+                tool: 'task_spawn',
+                // Function form so a failed task_spawn surfaces as an error outcome
+                // (→ dflt error transition + machine warn log) instead of a fake
+                // task-delegated with an empty task.
+                produces: (result) => {
+                    const r = result;
+                    return r?.taskId || r?.task?.taskId ? 'task-delegated' : 'error';
+                },
+                terminatesLoop: true,
+            },
+        },
+        transitions: [
+            { to: initial, when: o => o.kind === 'task-delegated' },
+            ...dflt.transitions, // wait / message-sent / error → initial
+        ],
+    };
+}
+/**
+ * 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 function injectKickoffDefault(workflow) {
+    if (workflow.states[KICKOFF_STATE]) {
+        throw new Error(`[defineAgent] state name "${KICKOFF_STATE}" is reserved for the injected agreement-kickoff default — rename the state`);
+    }
+    const states = {};
+    let injected = false;
+    for (const [name, state] of Object.entries(workflow.states)) {
+        if (stateHandlesProposerApproval(state)) {
+            states[name] = state;
+            continue;
+        }
+        states[name] = { ...state, transitions: [...state.transitions, KICKOFF_TRANSITION] };
+        injected = true;
+    }
+    if (!injected)
+        return workflow; // every state handles approval — nothing to add, no dead state
+    states[KICKOFF_STATE] = buildKickoffState(workflow.initial);
+    return { ...workflow, states };
+}

package/dist/runtime/runMechanical.d.ts

@@ -0,0 +1,25 @@
+import type { Ctx, EffectHandler, MechanicalState, Outcome, ToolResultEntry } from '../types.js';
+import type { MemoryStore } from '../memory/MemoryStore.js';
+import { type RawEvent } from './buildOutcome.js';
+export interface RunMechanicalResult {
+    outcome: Outcome;
+    toolResults: ToolResultEntry[];
+    llmCalls: number;
+    tokens: {
+        total: number;
+        input: number;
+        output: number;
+    };
+}
+/**
+ * ZIG-764: run a mechanical state — invoke one bound tool with no LLM turn.
+ * Used by dumb coordinators whose only job is a fixed tool call on task-assigned.
+ */
+export declare function runMechanical(input: {
+    stateId: string;
+    state: MechanicalState;
+    ctx: Ctx;
+    eff: EffectHandler;
+    memory?: MemoryStore;
+    incomingEvent: RawEvent | null;
+}): Promise<RunMechanicalResult>;

package/dist/runtime/runMechanical.js

@@ -0,0 +1,74 @@
+import { outcomeFromActionResult } from './buildOutcome.js';
+import { runtimeLog } from '../shared/runtimeLog.js';
+/**
+ * ZIG-764: run a mechanical state — invoke one bound tool with no LLM turn.
+ * Used by dumb coordinators whose only job is a fixed tool call on task-assigned.
+ */
+export async function runMechanical(input) {
+    const { stateId, state, ctx, eff, memory, incomingEvent } = input;
+    const sessionId = ctx.identity.sessionId;
+    const runId = crypto.randomUUID();
+    const effWithTrace = (effect) => {
+        if (effect.kind === 'tool-call') {
+            return eff({ ...effect, runId, stateId });
+        }
+        return eff(effect);
+    };
+    runtimeLog.info('runMechanical', `enter state=${stateId} tool=${state.tool}`);
+    const args = typeof state.buildArgs === 'function'
+        ? state.buildArgs(ctx, ctx.lastOutcome)
+        : { ...(state.args ?? {}) };
+    const pseudoAction = {
+        prompt: { instruction: '' },
+        tool: state.tool,
+        produces: state.produces,
+    };
+    let emitted = [];
+    try {
+        const r = await effWithTrace({
+            kind: 'tool-call',
+            sessionId,
+            name: state.tool,
+            args,
+            memory,
+            senderId: incomingEvent?.senderId != null ? String(incomingEvent.senderId) : undefined,
+            senderType: incomingEvent?.senderType != null ? String(incomingEvent.senderType) : undefined,
+        });
+        if (!r.ok) {
+            emitted = [{ type: 'tool_error', tool: state.tool, error: r.error || 'unknown', senderId: 'system' }];
+        }
+        else if (r.events && r.events.length > 0) {
+            emitted = r.events;
+        }
+        else {
+            emitted = [{ type: 'tool_result', tool: state.tool, result: r.result, senderId: 'system' }];
+        }
+    }
+    catch (error) {
+        emitted = [
+            {
+                type: 'tool_error',
+                tool: state.tool,
+                error: error?.message ?? String(error),
+                senderId: 'system',
+            },
+        ];
+    }
+    const toolResults = [];
+    let outcome = outcomeFromActionResult('__mechanical__', pseudoAction, args, emitted, toolResults);
+    if (emitted.some((e) => e?.type === 'tool_error')) {
+        outcome = {
+            kind: 'error',
+            source: 'tool',
+            cause: emitted.find((e) => e?.type === 'tool_error')?.error ?? 'tool failed',
+            retryable: false,
+        };
+    }
+    runtimeLog.info('runMechanical', `done state=${stateId} outcome=${outcome.kind} llmCalls=0`);
+    return {
+        outcome,
+        toolResults,
+        llmCalls: 0,
+        tokens: { total: 0, input: 0, output: 0 },
+    };
+}

package/dist/runtime/runTurn.d.ts

@@ -0,0 +1,63 @@
+import type { Action, Ctx, Outcome, ToolResultEntry, EffectHandler } from '../types.js';
+import type { MemoryStore } from '../memory/MemoryStore.js';
+import { type RawEvent } from './buildOutcome.js';
+import { PromptBuilder } from './PromptBuilder.js';
+import type { ToolManager } from '../tools/ToolManager.js';
+interface RunTurnInput {
+    stateId: string;
+    statePrompt: import('../types.js').PromptDef;
+    actions: Record<string, Action>;
+    incomingEvent: RawEvent | null;
+    ctx: Ctx;
+    /** The only side channel. Every I/O — context, LLM, tools, send, record — flows through here. */
+    eff: EffectHandler;
+    /** Pure metadata: tool schemas, flags. Owned by the Agent. */
+    toolManager: ToolManager;
+    promptBuilder: PromptBuilder;
+    /**
+     * Agent-private long-term memory, threaded from AgentHost. Currently
+     * surfaced into `eff` as part of the tool-call effect payload so tools
+     * can read/write notes; the prompt builder doesn't consume it yet.
+     */
+    memory?: MemoryStore;
+    definition: {
+        description?: string;
+    };
+    /**
+     * Respond actions use 2-call streaming: Call 1 picks action+receiverId,
+     * Call 2 streams the text (ZIG-471). On by default (ZIG-838); pass false
+     * (or set ENABLE_LLM_STREAMING=false) to fold the reply text back into the
+     * single decision call. The env flag is a deployment kill-switch — the
+     * streaming path once broke long replies in production, so ops keeps a way
+     * to disable it without a code change.
+     */
+    streamRespondActions?: boolean;
+}
+interface RunTurnResult {
+    outcome: Outcome;
+    toolResults: ToolResultEntry[];
+    llmCalls: number;
+    tokens: {
+        total: number;
+        input: number;
+        output: number;
+    };
+}
+/**
+ * Run a single thinking-state turn.
+ *
+ * Reads context → builds prompt → tool loop with the LLM → executes one
+ * action → returns exactly one Outcome via outcomeFromActionResult.
+ *
+ * No direct service calls. Every impure operation goes through `eff`:
+ *   • eff('read-context')  — history/agreements/agents snapshot
+ *   • eff('llm-call')      — model invocation
+ *   • eff('tool-call')     — tool execution (Server runs the tool body)
+ *   • eff('send-message')  — outbound peer message
+ *   • eff('record-event')  — persist a thought / decision marker
+ *
+ * The Server is responsible for turning each effect into the right HTTP/WS
+ * call and (optionally) wrapping it in telemetry / dedup / retries.
+ */
+export declare function runTurn(input: RunTurnInput): Promise<RunTurnResult>;
+export {};