@ziggs-ai/agent-sdk 0.1.11 → 0.2.0

package/src/types.ts

@@ -1,456 +0,0 @@
-/**
- * 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.
- */
-
-// ── Refs (opaque payloads from the protocol layer) ───────────────────────────
-
-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;
-}
-
-// ── Outcomes (hybrid: closed core + extension) ───────────────────────────────
-
-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 };
-
-// ── Ctx (memory only — no event-derived flags) ───────────────────────────────
-
-/**
- * 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;
-
-  // Persistent protocol state
-  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[];
-
-  // Per-turn working memory
-  toolResults: ToolResultEntry[];
-
-  // Last event/turn that caused this entry
-  lastOutcome: Outcome;
-
-  // Server-provided context (history, agreements, agents, users) is fetched
-  // on demand inside runTurn; not persisted on Ctx.
-}
-
-// ── Workflow shape ───────────────────────────────────────────────────────────
-
-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;
-}
-
-export type State = ParkedState | ThinkingState;
-
-export interface Workflow {
-  id: string;
-  description: string;
-  initial: string;
-  states: Record<string, State>;
-}
-
-// ── Effects (the Agent ↔ Server boundary) ────────────────────────────────────
-//
-// The Agent is pure: its only side channel is `EffectHandler`. Every impure
-// operation — reading context, calling the LLM, executing a tool, sending a
-// message — is expressed as an Effect. The Server implements the handler;
-// the Agent emits effects via `await eff({ kind: ..., ... })` and consumes
-// the typed result. This is the Node.js-style "sync dress over async" loop:
-// `tick` reads top-to-bottom but every `await` is a yield to the Server.
-
-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;
-  /** Index signature so PromptBuilder's `ServerContext` can accept it directly. */
-  [key: string]: unknown;
-}
-
-export interface ReadContextOpts {
-  maxMessages?: number;
-  maxCharacters?: number;
-  maxTaskHistory?: number;
-  summarize?: boolean;
-  sinceSequence?: string;
-}
-
-/**
- * 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[];
-}
-
-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'
-  | 'get-scope'
-  | 'list-messages'
-  | 'list-artifacts'
-  | 'list-task-history';
-
-export interface ScopeRef { kind: 'chat' | 'agreement' | 'task' | 'counterparty'; id: string }
-
-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;
-      /** 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 }
-  | { kind: 'get-scope'; via: ScopeRef }
-  | { kind: 'list-messages'; chatId: string; after?: string; limit?: number }
-  | { kind: 'list-artifacts'; chatId?: string; agreementId?: string; after?: string; limit?: number }
-  | { kind: 'list-task-history'; taskId: string; after?: string; limit?: number };
-
-/**
- * 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 };
-  'tool-call': ToolCallResult;
-  'send-message': { ok: true };
-  'record-event': { ok: true };
-  'get-scope': unknown;
-  'list-messages': { messages: unknown[]; latestSequence: string | null };
-  'list-artifacts': { artifacts: unknown[]; latestSequence: string | null };
-  'list-task-history': { taskId: string; history: unknown[]; latestSequence: string | null };
-}
-
-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>>;
-
-// ── defineAgent input/output ─────────────────────────────────────────────────
-
-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/src/utils/jsonExtractor.ts

@@ -1,100 +0,0 @@
-import { runtimeLog } from '../shared/runtimeLog.js';
-
-export function extractJSON(content: string): string {
-  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: string): string {
-  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<T = unknown>(content: string, fallback: T | null = null): T | null {
-  try {
-    const extracted = extractJSON(content);
-    if (!extracted || extracted.trim().length === 0) throw new Error('Empty JSON content');
-    try {
-      return JSON.parse(extracted) as T;
-    } catch {
-      return JSON.parse(repairJsonStrings(extracted)) as T;
-    }
-  } catch {
-    runtimeLog.error('JSONExtractor', 'Error parsing JSON', content.length > 500 ? `${content.slice(0, 500)}…` : content);
-    return fallback ?? null;
-  }
-}