@sw4rm/js-sdk 0.3.0 → 0.4.0

package/dist/types/clients/workflow.d.ts

@@ -0,0 +1,301 @@
+/**
+ * Workflow client for SW4RM.
+ *
+ * This module provides the WorkflowClient for managing DAG-based workflow
+ * orchestration. Workflows enable:
+ * - Multi-step task coordination
+ * - Dependency-based execution ordering
+ * - Node-level state tracking
+ * - Context passing between nodes
+ *
+ * Based on workflow.proto definitions.
+ */
+/**
+ * Status of a workflow node.
+ */
+export declare enum NodeStatus {
+    NODE_STATUS_UNSPECIFIED = 0,
+    /** Node waiting for dependencies */
+    PENDING = 1,
+    /** Node ready to execute */
+    READY = 2,
+    /** Node currently executing */
+    RUNNING = 3,
+    /** Node finished successfully */
+    COMPLETED = 4,
+    /** Node encountered an error */
+    FAILED = 5,
+    /** Node skipped due to conditional logic */
+    SKIPPED = 6
+}
+/**
+ * Type of trigger for a workflow node.
+ */
+export declare enum TriggerType {
+    TRIGGER_TYPE_UNSPECIFIED = 0,
+    /** Triggered by specific events */
+    EVENT = 1,
+    /** Triggered on a schedule (cron-like) */
+    SCHEDULE = 2,
+    /** Triggered by explicit user action */
+    MANUAL = 3,
+    /** Triggered by dependency completion */
+    DEPENDENCY = 4
+}
+/**
+ * Status of a workflow instance.
+ */
+export declare enum WorkflowStatus {
+    WORKFLOW_STATUS_UNSPECIFIED = 0,
+    /** Workflow has been created but not started */
+    CREATED = 1,
+    /** Workflow is currently running */
+    RUNNING = 2,
+    /** Workflow completed successfully */
+    COMPLETED = 3,
+    /** Workflow failed with error */
+    FAILED = 4,
+    /** Workflow was cancelled */
+    CANCELLED = 5,
+    /** Workflow is paused */
+    PAUSED = 6
+}
+/**
+ * A node in a workflow definition.
+ *
+ * Represents a single step in the workflow DAG with its dependencies,
+ * trigger conditions, and input/output mappings.
+ */
+export interface WorkflowNode {
+    /** Unique identifier for this node */
+    nodeId: string;
+    /** Identifier of the agent executing this node */
+    agentId: string;
+    /** Set of node_ids that must complete before this node runs */
+    dependencies: string[];
+    /** How this node is triggered */
+    triggerType: TriggerType;
+    /** Maps workflow state keys to node input parameters */
+    inputMapping: Record<string, string>;
+    /** Maps node output keys to workflow state keys */
+    outputMapping: Record<string, string>;
+    /** Additional node configuration and context */
+    metadata: Record<string, string>;
+}
+/**
+ * A workflow definition.
+ *
+ * Describes a complete workflow as a DAG of nodes with their
+ * dependencies and configuration.
+ */
+export interface WorkflowDefinition {
+    /** Unique identifier for this workflow */
+    workflowId: string;
+    /** Map of node_id to WorkflowNode */
+    nodes: Record<string, WorkflowNode>;
+    /** When the workflow was created (ISO-8601 string) */
+    createdAt?: string;
+    /** Additional workflow-level configuration */
+    metadata: Record<string, string>;
+}
+/**
+ * State of a single node during execution.
+ */
+export interface NodeState {
+    /** The node this state belongs to */
+    nodeId: string;
+    /** Current execution status */
+    status: NodeStatus;
+    /** When node execution started (ISO-8601 string) */
+    startedAt?: string;
+    /** When node execution completed (ISO-8601 string) */
+    completedAt?: string;
+    /** Output data from node execution (JSON string) */
+    output?: string;
+    /** Error information if node failed */
+    error?: string;
+}
+/**
+ * A running instance of a workflow.
+ *
+ * Tracks the execution state of all nodes and the shared workflow data.
+ */
+export interface WorkflowInstance {
+    /** Identifier of this workflow instance */
+    instanceId: string;
+    /** Identifier of the workflow definition */
+    workflowId: string;
+    /** Current status of the workflow */
+    status: WorkflowStatus;
+    /** Map of node_id to NodeState for tracking execution */
+    nodeStates: Record<string, NodeState>;
+    /** Shared workflow data (JSON string) */
+    workflowData: string;
+    /** When the workflow execution started (ISO-8601 string) */
+    startedAt?: string;
+    /** When the workflow execution completed (ISO-8601 string) */
+    completedAt?: string;
+    /** Additional runtime metadata */
+    metadata: Record<string, string>;
+}
+/**
+ * Error thrown when a workflow operation fails validation.
+ */
+export declare class WorkflowValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when a workflow contains a cycle.
+ */
+export declare class WorkflowCycleError extends Error {
+    constructor(message: string);
+}
+/**
+ * Client for managing workflow orchestration.
+ *
+ * Enables creation and execution of DAG-based workflows that coordinate
+ * multiple agents. This is an in-memory implementation for Phase 2;
+ * future phases will integrate with gRPC services.
+ */
+export declare class WorkflowClient {
+    private definitions;
+    private instances;
+    private instancesByWorkflow;
+    /**
+     * Create a new workflow from a definition.
+     *
+     * Validates the workflow definition and stores it for later execution.
+     *
+     * @param definition - The workflow definition to create
+     * @returns The workflow_id of the created workflow
+     * @throws WorkflowValidationError if the definition is invalid
+     * @throws WorkflowCycleError if the workflow contains a cycle
+     *
+     * @example
+     * ```typescript
+     * const client = new WorkflowClient();
+     * const definition: WorkflowDefinition = {
+     *   workflowId: "review-workflow",
+     *   nodes: {
+     *     "produce": {
+     *       nodeId: "produce",
+     *       agentId: "producer-agent",
+     *       dependencies: [],
+     *       triggerType: TriggerType.MANUAL,
+     *       inputMapping: {},
+     *       outputMapping: { "artifact": "produced_artifact" },
+     *       metadata: {}
+     *     },
+     *     "review": {
+     *       nodeId: "review",
+     *       agentId: "critic-agent",
+     *       dependencies: ["produce"],
+     *       triggerType: TriggerType.DEPENDENCY,
+     *       inputMapping: { "artifact": "produced_artifact" },
+     *       outputMapping: { "result": "review_result" },
+     *       metadata: {}
+     *     }
+     *   },
+     *   metadata: {}
+     * };
+     * const workflowId = await client.createWorkflow(definition);
+     * ```
+     */
+    createWorkflow(definition: WorkflowDefinition): Promise<string>;
+    /**
+     * Start a new instance of a workflow.
+     *
+     * Creates a new workflow instance and initializes all nodes to their
+     * starting states based on dependencies.
+     *
+     * @param workflowId - The ID of the workflow to start
+     * @param initialData - Optional initial workflow data (JSON string)
+     * @param metadata - Optional runtime metadata
+     * @returns The created workflow instance
+     * @throws WorkflowValidationError if the workflow does not exist
+     *
+     * @example
+     * ```typescript
+     * const instance = await client.startWorkflow("review-workflow");
+     * console.log(instance.status); // WorkflowStatus.RUNNING
+     * ```
+     */
+    startWorkflow(workflowId: string, initialData?: string, metadata?: Record<string, string>): Promise<WorkflowInstance>;
+    /**
+     * Get the current status of a workflow instance.
+     *
+     * @param instanceId - The ID of the workflow instance
+     * @returns The workflow instance with current state
+     * @throws WorkflowValidationError if the instance does not exist
+     *
+     * @example
+     * ```typescript
+     * const instance = await client.getWorkflowStatus("wf-123-abc");
+     * console.log(instance.status);
+     * for (const [nodeId, state] of Object.entries(instance.nodeStates)) {
+     *   console.log(`${nodeId}: ${NodeStatus[state.status]}`);
+     * }
+     * ```
+     */
+    getWorkflowStatus(instanceId: string): Promise<WorkflowInstance>;
+    /**
+     * Cancel a running workflow instance.
+     *
+     * Marks the workflow as cancelled and stops any pending nodes.
+     *
+     * @param instanceId - The ID of the workflow instance to cancel
+     * @throws WorkflowValidationError if the instance does not exist
+     * @throws WorkflowValidationError if the workflow is not in a cancellable state
+     *
+     * @example
+     * ```typescript
+     * await client.cancelWorkflow("wf-123-abc");
+     * const instance = await client.getWorkflowStatus("wf-123-abc");
+     * console.log(instance.status); // WorkflowStatus.CANCELLED
+     * ```
+     */
+    cancelWorkflow(instanceId: string): Promise<void>;
+    /**
+     * Get the workflow definition.
+     *
+     * @param workflowId - The ID of the workflow
+     * @returns The workflow definition if it exists, null otherwise
+     */
+    getWorkflowDefinition(workflowId: string): Promise<WorkflowDefinition | null>;
+    /**
+     * List all instances of a workflow.
+     *
+     * @param workflowId - The ID of the workflow
+     * @returns List of all instances for the workflow
+     */
+    listWorkflowInstances(workflowId: string): Promise<WorkflowInstance[]>;
+    /**
+     * Update the state of a node in a workflow instance.
+     *
+     * This is an internal method used by node executors to report progress.
+     *
+     * @param instanceId - The ID of the workflow instance
+     * @param nodeId - The ID of the node to update
+     * @param status - The new status of the node
+     * @param output - Optional output data from the node
+     * @param error - Optional error message if the node failed
+     * @throws WorkflowValidationError if the instance or node does not exist
+     */
+    updateNodeState(instanceId: string, nodeId: string, status: NodeStatus, output?: string, error?: string): Promise<void>;
+    /**
+     * Update the status of nodes that depend on a completed node.
+     */
+    private updateDependentNodes;
+    /**
+     * Check if a workflow instance is complete and update its status.
+     */
+    private checkWorkflowCompletion;
+    /**
+     * Update the shared workflow data.
+     *
+     * @param instanceId - The ID of the workflow instance
+     * @param workflowData - The new workflow data (JSON string)
+     * @throws WorkflowValidationError if the instance does not exist
+     */
+    updateWorkflowData(instanceId: string, workflowData: string): Promise<void>;
+}

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-export declare const version = "0.3.0";
+export declare const version = "0.4.0";
 export * from './clients/router.js';
 export * from './clients/scheduler.js';
 export * from './clients/schedulerPolicy.js';
@@ -11,6 +11,9 @@ export * from './clients/negotiation.js';
 export * from './clients/reasoning.js';
 export * from './clients/connector.js';
 export * from './clients/registry.js';
+export * from './clients/negotiationRoom.js';
+export * from './clients/handoff.js';
+export * from './clients/workflow.js';
 export { buildEnvelope, type EnvelopeBuilt, type EnvelopeInput, nowTimestamp, type Timestamp, } from './internal/envelope.js';
 export * from './internal/errorMapping.js';
 export * from './internal/baseClient.js';
@@ -26,6 +29,9 @@ export * from './runtime/activitySync.js';
 export * from './runtime/streams.js';
 export * from './runtime/negotiationEvents.js';
 export * from './persistence/persistence.js';
+export * from './runtime/voting.js';
+export * from './runtime/policyStore.js';
+export * from './runtime/agentState.js';
 export * from './internal/ids.js';
 export * from './internal/idempotency.js';
 export * from './runtime/persistenceAdapter.js';

package/dist/types/internal/baseClient.d.ts

@@ -29,5 +29,5 @@ export declare class BaseClient {
     protected metadata(base?: grpc.Metadata): grpc.Metadata;
     protected deadlineFromNow(): Date;
     protected getServiceClient<T = any>(fqn: string): T;
-    protected withRetryUnary<Req, Res>(fn: () => Promise<Res>, methodName?: string, mdForCtx?: grpc.Metadata): Promise<Res>;
+    protected withRetryUnary<Res>(fn: () => Promise<Res>, methodName?: string, mdForCtx?: grpc.Metadata): Promise<Res>;
 }

package/dist/types/runtime/agentState.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Agent runtime state machine for SW4RM.
+ *
+ * This module provides the AgentState enum and state transition validation
+ * for implementing the agent lifecycle as specified in spec section 8.
+ *
+ * The agent lifecycle states are:
+ * - INITIALIZING: Agent starting up and registering
+ * - RUNNABLE: Agent ready to accept tasks
+ * - SCHEDULED: Agent has task assigned but not yet running
+ * - RUNNING: Agent actively executing task
+ * - WAITING: Agent waiting for external input
+ * - WAITING_RESOURCES: Agent waiting for resources
+ * - SUSPENDED: Agent paused by scheduler
+ * - RESUMED: Agent transitioning from suspended to running
+ * - COMPLETED: Agent finished current task
+ * - FAILED: Agent encountered error
+ * - SHUTTING_DOWN: Agent gracefully terminating
+ * - RECOVERING: Agent recovering from failure
+ */
+/**
+ * Agent lifecycle states as defined in spec section 8.
+ */
+export declare enum AgentState {
+    /** Agent state not set */
+    AGENT_STATE_UNSPECIFIED = 0,
+    /** Agent starting up and registering */
+    INITIALIZING = 1,
+    /** Agent ready to accept tasks */
+    RUNNABLE = 2,
+    /** Agent has task assigned but not yet running */
+    SCHEDULED = 3,
+    /** Agent actively executing task */
+    RUNNING = 4,
+    /** Agent waiting for external input */
+    WAITING = 5,
+    /** Agent waiting for resources */
+    WAITING_RESOURCES = 6,
+    /** Agent paused by scheduler */
+    SUSPENDED = 7,
+    /** Agent transitioning from suspended to running */
+    RESUMED = 8,
+    /** Agent finished current task */
+    COMPLETED = 9,
+    /** Agent encountered error */
+    FAILED = 10,
+    /** Agent gracefully terminating */
+    SHUTTING_DOWN = 11,
+    /** Agent recovering from failure */
+    RECOVERING = 12
+}
+/**
+ * Error thrown when an invalid state transition is attempted.
+ */
+export declare class StateTransitionError extends Error {
+    readonly fromState: AgentState;
+    readonly toState: AgentState;
+    constructor(fromState: AgentState, toState: AgentState);
+}
+/**
+ * Check if a state transition is valid.
+ *
+ * @param fromState - The current state
+ * @param toState - The target state
+ * @returns True if the transition is valid, false otherwise
+ */
+export declare function isValidTransition(fromState: AgentState, toState: AgentState): boolean;
+/**
+ * Get all valid target states from a given state.
+ *
+ * @param fromState - The current state
+ * @returns Array of valid target states
+ */
+export declare function getValidTransitions(fromState: AgentState): AgentState[];
+/**
+ * Lifecycle hook types for agent state changes.
+ */
+export interface AgentLifecycleHooks {
+    /** Called on any state change */
+    onStateChange?: (fromState: AgentState, toState: AgentState, context?: Record<string, unknown>) => void | Promise<void>;
+    /** Called when agent becomes SCHEDULED */
+    onScheduled?: (taskId: string, context?: Record<string, unknown>) => void | Promise<void>;
+    /** Called when agent is preempted (RUNNING -> SUSPENDED) */
+    onPreempt?: (reason: string, context?: Record<string, unknown>) => void | Promise<void>;
+    /** Called when agent resumes (RESUMED -> RUNNING) */
+    onResume?: (context?: Record<string, unknown>) => void | Promise<void>;
+    /** Called when agent starts waiting (RUNNING -> WAITING) */
+    onWait?: (reason: string, context?: Record<string, unknown>) => void | Promise<void>;
+    /** Called when agent waits for resources (RUNNING -> WAITING_RESOURCES) */
+    onWaitResources?: (resources: string[], context?: Record<string, unknown>) => void | Promise<void>;
+    /** Called when task completes (RUNNING -> COMPLETED) */
+    onComplete?: (result?: unknown, context?: Record<string, unknown>) => void | Promise<void>;
+    /** Called when agent fails (any -> FAILED) */
+    onFail?: (error: Error, context?: Record<string, unknown>) => void | Promise<void>;
+    /** Called when shutdown starts (RUNNING -> SHUTTING_DOWN) */
+    onShutdown?: (gracePeriodMs: number, context?: Record<string, unknown>) => void | Promise<void>;
+    /** Called when recovery starts (FAILED -> RECOVERING) */
+    onRecover?: (context?: Record<string, unknown>) => void | Promise<void>;
+}
+/**
+ * Agent state machine implementation.
+ *
+ * Manages agent lifecycle state transitions with validation and lifecycle hooks.
+ */
+export declare class AgentStateMachine {
+    private state;
+    private hooks;
+    private stateHistory;
+    /**
+     * Create a new agent state machine.
+     *
+     * @param hooks - Optional lifecycle hooks
+     */
+    constructor(hooks?: AgentLifecycleHooks);
+    /**
+     * Get the current state.
+     *
+     * @returns The current agent state
+     */
+    getState(): AgentState;
+    /**
+     * Get the state history.
+     *
+     * @returns Array of state transitions with timestamps
+     */
+    getStateHistory(): Array<{
+        state: AgentState;
+        timestamp: string;
+        context?: Record<string, unknown>;
+    }>;
+    /**
+     * Initialize the agent (transition to INITIALIZING).
+     *
+     * @throws StateTransitionError if already initialized
+     */
+    initialize(): Promise<void>;
+    /**
+     * Transition to a new state.
+     *
+     * @param toState - The target state
+     * @param context - Optional context for the transition
+     * @throws StateTransitionError if the transition is invalid
+     */
+    transitionTo(toState: AgentState, context?: Record<string, unknown>): Promise<void>;
+    /**
+     * Perform the state transition and call hooks.
+     */
+    private doTransition;
+    /**
+     * Call specific lifecycle hooks based on the transition.
+     */
+    private callSpecificHooks;
+    /**
+     * Check if the agent can transition to a given state.
+     *
+     * @param toState - The target state
+     * @returns True if the transition is valid
+     */
+    canTransitionTo(toState: AgentState): boolean;
+    /**
+     * Get all states the agent can currently transition to.
+     *
+     * @returns Array of valid target states
+     */
+    getAvailableTransitions(): AgentState[];
+    /**
+     * Check if the agent is in a terminal state.
+     *
+     * Terminal states are states where the agent cannot make further
+     * progress without external intervention.
+     *
+     * @returns True if in a terminal state
+     */
+    isTerminal(): boolean;
+    /**
+     * Check if the agent is in an active state (executing work).
+     *
+     * @returns True if the agent is actively working
+     */
+    isActive(): boolean;
+    /**
+     * Check if the agent is in a waiting state.
+     *
+     * @returns True if the agent is waiting
+     */
+    isWaiting(): boolean;
+    /**
+     * Check if the agent is in a suspended or shutdown state.
+     *
+     * @returns True if the agent is suspended or shutting down
+     */
+    isSuspendedOrShuttingDown(): boolean;
+    /**
+     * Update lifecycle hooks.
+     *
+     * @param hooks - New hooks to merge with existing hooks
+     */
+    setHooks(hooks: Partial<AgentLifecycleHooks>): void;
+    /**
+     * Reset the state machine to uninitialized state.
+     *
+     * This is primarily for testing purposes.
+     */
+    reset(): void;
+}