@ziggs-ai/agent-sdk 0.1.12 → 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,466 @@
+/**
+ * Foundation types for the agent SDK workflow runtime.
+ *
+ * One outcome vocabulary, one ctx shape, one transition signature.
+ * Every state — parked or thinking — re-enters with exactly one Outcome.
+ */
+export interface AgreementRef {
+    agreementId: string;
+    parties?: {
+        creator?: string;
+        provider?: string;
+        payer?: string;
+        proposedTo?: string;
+    };
+    proposal?: {
+        status?: 'pending' | 'approved' | 'rejected' | 'cancelled';
+    };
+    money?: {
+        price?: number;
+        paymentStatus?: string;
+    };
+}
+export interface TaskRef {
+    taskId: string;
+    agreementId?: string;
+    agreement?: AgreementRef;
+    state?: string;
+    description?: string;
+    parentTaskId?: string;
+    executorId?: string;
+    assigneeId?: string | null;
+    /** Work product set by task_update (safeJsonStringify'd string on the wire). */
+    result?: unknown;
+    proposal?: {
+        status?: 'pending' | 'approved' | 'rejected' | 'cancelled';
+    };
+    proposedToIsYou?: boolean;
+    providerIsYou?: boolean;
+    creatorIsYou?: boolean;
+    payerIsYou?: boolean;
+}
+export interface ProposalRef {
+    agreementId: string;
+    agreement?: AgreementRef;
+}
+export type OutcomeKind = 'enter' | 'wait' | 'state-timeout' | 'message-sent' | 'message-received' | 'task-assigned' | 'task-delegated' | 'task-closed' | 'subtask-finished' | 'proposal-made' | 'proposal-resolved' | 'tool-result' | 'error' | 'extension';
+export type Outcome = {
+    kind: 'enter';
+} | {
+    kind: 'wait';
+} | {
+    kind: 'state-timeout';
+    state: string;
+    waitedMs: number;
+} | {
+    kind: 'message-sent';
+    text?: string;
+    receiverId?: string;
+} | {
+    kind: 'message-received';
+    text?: string;
+    senderId?: string;
+    senderType?: string;
+} | {
+    kind: 'task-assigned';
+    task: TaskRef;
+} | {
+    kind: 'task-delegated';
+    task: TaskRef;
+} | {
+    kind: 'task-closed';
+    status: 'completed' | 'failed';
+    result?: unknown;
+} | {
+    kind: 'subtask-finished';
+    status: 'completed' | 'failed';
+    task: TaskRef;
+    result?: unknown;
+} | {
+    kind: 'proposal-made';
+    proposal: ProposalRef;
+} | {
+    kind: 'proposal-resolved';
+    action: 'approve' | 'reject';
+    proposal: ProposalRef;
+    /**
+     * True when THIS agent made the proposal being resolved. Computed in
+     * AgentMachine._handleFrame by matching proposal.agreementId against
+     * ctx.pendingProposalAgreementId BEFORE applyOutcomeToCtx clears it —
+     * wire frames carry no trustworthy proposer field (agreement_lifecycle
+     * drops `parties` at ingress, and parties.creator is a principal id,
+     * not an agentId). Drives the injected agreement-kickoff default.
+     */
+    proposedByMe: boolean;
+} | {
+    kind: 'tool-result';
+    tool: string;
+    result: unknown;
+} | {
+    kind: 'error';
+    source: 'llm' | 'tool' | 'protocol' | 'validation' | 'unknown';
+    cause: unknown;
+    retryable: boolean;
+} | {
+    kind: 'extension';
+    name: string;
+    payload: unknown;
+};
+/**
+ * A session is the Server-side abstraction the Agent operates against:
+ * `{ sessionId, ctx, queue, parked }`. `Identity` is the Agent's view of
+ * which session this tick belongs to. `sessionId` is opaque to the Agent —
+ * it's a string the Server uses to route inbound events and outbound
+ * effects. (Today, the Ziggs transport derives sessionId from `chatId` at
+ * the wire boundary; non-chat surfaces will produce sessionIds of other
+ * shapes.)
+ */
+export interface Identity {
+    agentId: string;
+    sessionId: string;
+    laneKey: string;
+}
+export interface HistoryEntry {
+    entryType?: string;
+    text?: string;
+    sender?: {
+        id?: string;
+        type?: string;
+    };
+    receiver?: {
+        id?: string;
+    };
+    timestamp?: number;
+    [key: string]: unknown;
+}
+export interface ToolResultEntry {
+    tool: string;
+    result?: unknown;
+    error?: string;
+}
+export interface PendingSubtask {
+    /** Executor the task was placed with; null only when the spawn result carried
+     * no executor identity (open/broadcast agreement task not yet claimed). */
+    agentId: string | null;
+    spawnedAt: number;
+}
+export interface CollectedSubtaskResult {
+    taskId: string;
+    agentId: string | null;
+    status: 'completed' | 'failed';
+    /** task.result from the finishing event; null when the event carried none. */
+    result: unknown;
+}
+/**
+ * Per-lane runtime state. Outcome is "what just happened"; Ctx is "what I know."
+ *
+ * Persistent identifiers (activeAgreementId, pendingProposalAgreementId,
+ * pendingSubtasks) survive across outcomes — they're the memory of which
+ * agreement the agent is currently bound to and which subtasks it's awaiting.
+ */
+export interface Ctx {
+    identity: Identity;
+    activeAgreementId: string | null;
+    activeTaskId: string | null;
+    pendingProposalAgreementId: string | null;
+    delegatedAgreementIds: string[];
+    /** Durable barrier for orchestration: every spawned-but-unfinished subtask, keyed by taskId. */
+    pendingSubtasks: Record<string, PendingSubtask>;
+    /** Every finished subtask of the current engagement, arrival order. Synthesis prompts render ALL of these. */
+    collectedResults: CollectedSubtaskResult[];
+    toolResults: ToolResultEntry[];
+    lastOutcome: Outcome;
+    /** Claude Agent SDK session id for resume across ticks (claude-sdk cognition only). */
+    claudeSessionId?: string;
+    /**
+     * Recent wake timestamps (epoch ms) for this lane (claude-sdk cognition
+     * only). Backstop circuit breaker: if a lane wakes faster than any real
+     * traffic could drive it, the brain skips the LLM instead of burning the
+     * fleet key on a wake storm.
+     */
+    recentWakes?: number[];
+}
+export interface PromptDef {
+    role?: string;
+    goal?: string;
+    context?: string;
+    constraints?: string;
+}
+export interface ActionPrompt {
+    instruction: string;
+    format?: string;
+    when?: string;
+    examples?: Array<{
+        scenario?: string;
+        input?: string;
+        output?: string;
+        query?: string;
+    }>;
+}
+/**
+ * `produces` is the outcome-kind contract for an action. Static form for
+ * actions that always emit the same kind (most common); function form for
+ * tool-bound actions where the result determines the kind (e.g. success vs
+ * error). The runtime composes the kind with action metadata to build the
+ * full Outcome.
+ */
+export type ProducesFn = (result: unknown, args: unknown) => OutcomeKind;
+export type Produces = OutcomeKind | ProducesFn;
+export interface Action {
+    prompt: ActionPrompt;
+    tool?: string | null;
+    produces: Produces;
+    /**
+     * When true, the tool loop exits immediately after this action's tool result,
+     * even if the result is non-terminal. Prevents the LLM from issuing additional
+     * tool calls in the same turn (e.g. calling agreement_subcontract right after
+     * agent_search before the FSM can route to evaluatingCandidates).
+     */
+    terminatesLoop?: boolean;
+}
+export interface Transition {
+    to: string;
+    when?: (outcome: Outcome, ctx: Ctx) => boolean;
+}
+export interface ParkedState {
+    kind: 'parked';
+    /**
+     * Liveness timer. When the machine settles in this state and no event
+     * arrives on the lane within timeoutMs, the host wakes the lane with a
+     * { kind: 'state-timeout', state, waitedMs } outcome so a transition can
+     * route to a recovery/nudge state. If no transition matches, the machine
+     * parks loudly (runtimeLog.error) and the timer is NOT re-armed. Countdown
+     * starts when the tick settles and resets on any event for the lane.
+     * In-memory only: lost on process restart; re-armed by the next real event
+     * that ticks the lane.
+     */
+    timeoutMs?: number;
+    transitions: Transition[];
+}
+export interface ThinkingState {
+    kind: 'thinking';
+    prompt: PromptDef;
+    actions: Record<string, Action>;
+    transitions: Transition[];
+    /**
+     * Opt out of the validateWorkflow warning that flags thinking states
+     * missing a `wait` action / activeWait fallthrough. Use sparingly — silent
+     * states that loop on themselves are usually a bug.
+     */
+    allowNoWait?: boolean;
+}
+/**
+ * ZIG-764: fixed tool invoke with no LLM turn. Entered after transitions
+ * (e.g. task-assigned → executing); runs `tool` once and emits `produces`.
+ */
+export interface MechanicalState {
+    kind: 'mechanical';
+    tool: string;
+    args?: Record<string, unknown>;
+    buildArgs?: (ctx: Ctx, outcome: Outcome) => Record<string, unknown>;
+    produces: Produces;
+    transitions: Transition[];
+}
+export type State = ParkedState | ThinkingState | MechanicalState;
+export interface Workflow {
+    id: string;
+    description: string;
+    initial: string;
+    states: Record<string, State>;
+}
+export interface LlmToolCall {
+    id: string;
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface LlmMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content?: string;
+    tool_calls?: LlmToolCall[];
+    tool_call_id?: string;
+}
+export interface LlmToolSchema {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters?: unknown;
+    };
+}
+export interface LlmResponse {
+    content?: string;
+    tool_calls?: LlmToolCall[];
+    usage?: {
+        total_tokens?: number;
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        totalTokens?: number;
+        promptTokens?: number;
+        completionTokens?: number;
+    };
+}
+export interface ContextSnapshot {
+    history: HistoryEntry[];
+    agreements: unknown[];
+    agents: unknown[];
+    users: unknown[];
+    timelineSummary?: string | null;
+    latestSequence?: string | null;
+    unavailable?: boolean;
+    /**
+     * The session's chat no longer resolves on the backend (messages read
+     * 404'd) — deleted or never visible to this agent. Message-triggered wakes
+     * check this and skip the LLM instead of reasoning over a fabricated empty
+     * history. Agreement-keyed lanes also set it (their sessionId is not a
+     * chat), so it only gates message wakes, never task lanes.
+     */
+    chatMissing?: boolean;
+    /** Index signature so PromptBuilder's `ServerContext` can accept it directly. */
+    [key: string]: unknown;
+}
+export interface ReadContextOpts {
+    maxMessages?: number;
+}
+/**
+ * Result of executing a single tool. Tool execution may emit multiple
+ * "events" (terminal markers like `message_sent`, `waited`, etc.) that the
+ * cognition loop inspects to decide whether to keep looping. Those carry
+ * through here as `events`; `result` is the value returned to the LLM.
+ */
+export interface ToolCallResult {
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+    events?: unknown[];
+    /**
+     * Summed token usage of any nested LLM call the tool made (e.g. llmTool).
+     * Threaded up so the turn's authoritative token count (machine.tokens ->
+     * result.metrics) includes tool-internal spend rather than leaking it (ZIG-813).
+     */
+    usage?: LlmResponse['usage'];
+}
+export interface RecordedEntry {
+    kind: string;
+    text?: string;
+    [k: string]: unknown;
+}
+import type { MemoryStore } from './memory/MemoryStore.js';
+export type EffectKind = 'read-context' | 'llm-call' | 'stream-text' | 'tool-call' | 'send-message' | 'record-event';
+export type Effect = {
+    kind: 'read-context';
+    sessionId: string;
+    opts?: ReadContextOpts;
+} | {
+    kind: 'llm-call';
+    messages: LlmMessage[];
+    tools: LlmToolSchema[];
+    /** Chat/session id for monitoring ingest (ZIG-360). */
+    sessionId?: string;
+    /** Per-turn UUID grouping all LLM + tool calls in one turn (ZIG-440). */
+    runId?: string;
+    /** FSM state name at the time of this call (ZIG-440). */
+    stateId?: string;
+} | {
+    kind: 'stream-text';
+    sessionId: string;
+    receiverId: string;
+    /** Pre-allocated messageId shared across all chunks and the final send-message. */
+    messageId: string;
+    messages: LlmMessage[];
+} | {
+    kind: 'tool-call';
+    sessionId: string;
+    name: string;
+    args: unknown;
+    memory?: MemoryStore;
+    senderId?: string;
+    senderType?: string;
+    /**
+     * Agreement this tool call is acting under (ZIG-831). For a delegated
+     * per-user MCP call, `senderId` is the delegating agent, not the end-user
+     * who owns the connection; this lets the gateway resolve the delegation
+     * root's user. Sourced from the waking task event's `result.agreementId`.
+     */
+    onBehalfOfAgreementId?: string;
+    /** Per-turn UUID (ZIG-440). */
+    runId?: string;
+    /** FSM state name (ZIG-440). */
+    stateId?: string;
+} | {
+    kind: 'send-message';
+    sessionId: string;
+    receiverId: string;
+    text: string;
+    messageId?: string;
+} | {
+    kind: 'record-event';
+    sessionId: string;
+    entry: RecordedEntry;
+};
+/**
+ * Typed result map. With this shape, `await eff({ kind: 'read-context', ... })`
+ * resolves to `ContextSnapshot`, not a union — the discriminant carries the
+ * result type. Tests and Server impls implement this map exhaustively.
+ */
+export interface EffectResultMap {
+    'read-context': ContextSnapshot;
+    'llm-call': LlmResponse;
+    'stream-text': {
+        text: string;
+        usage?: LlmResponse['usage'];
+    };
+    'tool-call': ToolCallResult;
+    'send-message': {
+        ok: true;
+    };
+    'record-event': {
+        ok: true;
+    };
+}
+export type EffectResult<K extends EffectKind> = EffectResultMap[K];
+/** The single side-channel between Agent and Server. */
+export type EffectHandler = <K extends EffectKind>(effect: Extract<Effect, {
+    kind: K;
+}>) => Promise<EffectResult<K>>;
+export interface ServicesConfig {
+    llm?: {
+        model: string;
+        temperature?: number;
+    };
+    tools?: unknown[];
+}
+export interface DefineAgentInput {
+    agentId: string;
+    description: string;
+    specialization?: string;
+    initial: string;
+    states: Record<string, State>;
+    tools?: unknown[];
+    services?: ServicesConfig;
+    operatorKey?: string;
+    taskTools?: 'all' | 'none' | string[];
+    [key: string]: unknown;
+}
+/**
+ * Frozen output of defineAgent. Consumed directly by AgentHost / createAgent.
+ * defineAgent injects ONE default: the agreement-kickoff state `kickingOff`
+ * plus a last-position transition into it, added to states that don't already
+ * handle a proposer-side proposal-resolved/approve outcome (runtime/kickoff.ts).
+ * `wait` defaults remain the author's visible spread of `thinkingDefaults`.
+ */
+export interface AgentConfig {
+    openaiKey: string | undefined;
+    anthropicKey: string | undefined;
+    operatorKey?: string;
+    agentId: string;
+    description: string;
+    specialization?: string;
+    tools: unknown[];
+    model: string;
+    workflow: Workflow;
+    services?: ServicesConfig;
+    taskTools?: 'all' | 'none' | string[];
+    [key: string]: unknown;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Foundation types for the agent SDK workflow runtime.
+ *
+ * One outcome vocabulary, one ctx shape, one transition signature.
+ * Every state — parked or thinking — re-enters with exactly one Outcome.
+ */
+export {};

package/dist/utils/jsonExtractor.d.ts

@@ -0,0 +1,2 @@
+export declare function extractJSON(content: string): string;
+export declare function safeParseJSON<T = unknown>(content: string, fallback?: T | null): T | null;

package/dist/utils/jsonExtractor.js

@@ -0,0 +1,111 @@
+import { runtimeLog } from '../shared/runtimeLog.js';
+export function extractJSON(content) {
+    if (!content || typeof content !== 'string')
+        return '';
+    const trimmed = content.trim();
+    if (!trimmed.startsWith('{') && !trimmed.startsWith('[')) {
+        const jsonBlockMatch = content.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+        if (jsonBlockMatch) {
+            content = jsonBlockMatch[1].trim();
+        }
+    }
+    const firstBrace = content.indexOf('{');
+    const firstBracket = content.indexOf('[');
+    let startIdx = -1;
+    let isArray = false;
+    if (firstBrace !== -1 && (firstBracket === -1 || firstBrace < firstBracket)) {
+        startIdx = firstBrace;
+        isArray = false;
+    }
+    else if (firstBracket !== -1) {
+        startIdx = firstBracket;
+        isArray = true;
+    }
+    if (startIdx === -1)
+        return content.trim();
+    const openChar = isArray ? '[' : '{';
+    const closeChar = isArray ? ']' : '}';
+    let depth = 0;
+    let endIdx = startIdx;
+    for (let i = startIdx; i < content.length; i++) {
+        const char = content[i];
+        if (char === openChar) {
+            depth++;
+        }
+        else if (char === closeChar) {
+            depth--;
+            if (depth === 0) {
+                endIdx = i + 1;
+                break;
+            }
+        }
+        else if (char === '"') {
+            i++;
+            while (i < content.length && content[i] !== '"') {
+                if (content[i] === '\\')
+                    i++;
+                i++;
+            }
+        }
+    }
+    if (endIdx > startIdx)
+        content = content.substring(startIdx, endIdx);
+    content = content.trim();
+    content = content.replace(/(?<!:)\/\/.*$/gm, '');
+    content = content.replace(/\/\*[\s\S]*?\*\//g, '');
+    content = content.replace(/,(\s*[}\]])/g, '$1');
+    return content;
+}
+function repairJsonStrings(jsonText) {
+    if (!jsonText || typeof jsonText !== 'string')
+        return jsonText;
+    const validEscapes = new Set(['"', '\\', '/', 'b', 'f', 'n', 'r', 't', 'u']);
+    let out = '';
+    let inString = false;
+    for (let i = 0; i < jsonText.length; i++) {
+        const ch = jsonText[i];
+        if (!inString) {
+            if (ch === '"')
+                inString = true;
+            out += ch;
+            continue;
+        }
+        if (ch === '\\') {
+            const next = jsonText[i + 1];
+            out += (next && validEscapes.has(next)) ? ch : '\\\\';
+            continue;
+        }
+        if (ch === '"') {
+            inString = false;
+            out += ch;
+            continue;
+        }
+        if (ch === '\n') {
+            out += '\\n';
+            continue;
+        }
+        if (ch === '\r') {
+            out += '\\r';
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+}
+export function safeParseJSON(content, fallback = null) {
+    try {
+        const extracted = extractJSON(content);
+        if (!extracted || extracted.trim().length === 0)
+            throw new Error('Empty JSON content');
+        try {
+            return JSON.parse(extracted);
+        }
+        catch {
+            return JSON.parse(repairJsonStrings(extracted));
+        }
+    }
+    catch {
+        runtimeLog.error('JSONExtractor', 'Error parsing JSON', content.length > 500 ? `${content.slice(0, 500)}…` : content);
+        return fallback ?? null;
+    }
+}

package/package.json

@@ -1,16 +1,23 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.1.12",
+  "version": "0.2.0",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
-  "main": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
   },
   "engines": {
     "node": ">=18"
   },
   "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "node --experimental-test-module-mocks --import tsx/esm --test --test-reporter=spec test/*.test.ts",
     "test:watch": "node --experimental-test-module-mocks --import tsx/esm --test --watch test/*.test.ts"
@@ -34,8 +41,9 @@
   ],
   "license": "MIT",
   "files": [
-    "src",
-    "README.md"
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public",