@sw4rm/js-sdk 0.3.0 → 0.5.0

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

@@ -0,0 +1,316 @@
+/**
+ * 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;
+    /**
+     * Resume a workflow by marking a node as completed and advancing dependents.
+     *
+     * Implements the ResumeWorkflow RPC (spec §17.7 MUST). Marks the specified
+     * node as COMPLETED, updates workflow data if provided, then transitions
+     * dependent nodes from PENDING to READY when all their dependencies are met.
+     *
+     * @param instanceId - The ID of the workflow instance
+     * @param nodeId - The ID of the node to mark as completed
+     * @param workflowData - Optional updated workflow data (JSON string)
+     * @param metadata - Optional metadata for the resume operation
+     * @returns The updated workflow instance
+     * @throws WorkflowValidationError if the instance or node does not exist
+     */
+    resumeWorkflow(instanceId: string, nodeId: string, workflowData?: string, metadata?: Record<string, string>): Promise<WorkflowInstance>;
+    /**
+     * 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/constants/index.d.ts

@@ -0,0 +1,100 @@
+export { ErrorCode } from '../internal/errorMapping.js';
+export { MessageType } from '../internal/envelope.js';
+/**
+ * CommunicationClass constants (spec section 7.3).
+ */
+export declare enum CommunicationClass {
+    COMM_CLASS_UNSPECIFIED = 0,
+    PRIVILEGED = 1,
+    STANDARD = 2,
+    BULK = 3
+}
+/**
+ * DebateIntensity constants (spec section 17).
+ */
+export declare enum DebateIntensity {
+    DEBATE_INTENSITY_UNSPECIFIED = 0,
+    LOWEST = 1,
+    LOW = 2,
+    MEDIUM = 3,
+    HIGH = 4,
+    HIGHEST = 5
+}
+/**
+ * HitlReasonType constants (spec section 15).
+ */
+export declare enum HitlReasonType {
+    HITL_REASON_UNSPECIFIED = 0,
+    CONFLICT = 1,
+    SECURITY_APPROVAL = 2,
+    TASK_ESCALATION = 3,
+    MANUAL_OVERRIDE = 4,
+    WORKTREE_OVERRIDE = 5,
+    DEBATE_DEADLOCK = 6,
+    TOOL_PRIVILEGE_ESCALATION = 7,
+    CONNECTOR_APPROVAL = 8
+}
+/**
+ * AgentState constants (spec section 8).
+ * Re-exported from agentState.ts for convenience.
+ */
+export { AgentState } from '../runtime/agentState.js';
+/**
+ * AckStage constants.
+ */
+export declare enum AckStage {
+    ACK_STAGE_UNSPECIFIED = 0,
+    RECEIVED = 1,
+    READ = 2,
+    FULFILLED = 3,
+    REJECTED = 4,
+    FAILED = 5,
+    TIMED_OUT = 6
+}
+/**
+ * EnvelopeState lifecycle constants.
+ *
+ * Tracks the lifecycle of an envelope through the system:
+ * SENT -> RECEIVED -> READ -> FULFILLED/REJECTED/FAILED/TIMED_OUT
+ */
+export declare enum EnvelopeState {
+    ENVELOPE_STATE_UNSPECIFIED = 0,
+    SENT = 1,
+    RECEIVED = 2,
+    READ = 3,
+    FULFILLED = 4,
+    REJECTED = 5,
+    FAILED = 6,
+    TIMED_OUT = 7
+}
+/**
+ * WorktreeState constants (spec section 16).
+ */
+export declare enum WorktreeStateEnum {
+    WORKTREE_STATE_UNSPECIFIED = 0,
+    UNBOUND = 1,
+    BOUND_HOME = 2,
+    SWITCH_PENDING = 3,
+    BOUND_NON_HOME = 4,
+    BIND_FAILED = 5
+}
+/**
+ * Default timeout for acknowledgement in milliseconds.
+ */
+export declare const DEFAULT_ACK_TIMEOUT_MS = 10000;
+/**
+ * Deduplication window in seconds.
+ */
+export declare const DEDUP_WINDOW_S = 3600;
+/**
+ * Check if an envelope state is terminal (no further transitions expected).
+ *
+ * Terminal states: FULFILLED, REJECTED, FAILED, TIMED_OUT
+ */
+export declare function isTerminalEnvelopeState(state: EnvelopeState): boolean;
+/**
+ * Update the state of an envelope object.
+ */
+export declare function updateEnvelopeState<T extends {
+    state?: number;
+}>(envelope: T, newState: EnvelopeState): T;

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-export declare const version = "0.3.0";
+export declare const version = "0.5.0";
 export * from './clients/router.js';
 export * from './clients/scheduler.js';
 export * from './clients/schedulerPolicy.js';
@@ -11,27 +11,38 @@ 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/negotiationRoomStore.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';
+export { ClientOptions, BaseClient, } from './internal/baseClient.js';
 export * from './internal/time.js';
 export * from './internal/interceptors.js';
 export * from './internal/worktreeState.js';
 export * from './internal/worktreePolicy.js';
 export * from './internal/runtime/activityBuffer.js';
-export * from './internal/runtime/ackLifecycle.js';
-export * from './internal/runtime/messageProcessor.js';
+export { AckState, ACKLifecycleManager, } from './internal/runtime/ackLifecycle.js';
+export { EnvelopeLike, MessageProcessor, } from './internal/runtime/messageProcessor.js';
 export * from './runtime/ackHelpers.js';
 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 { AgentState, isValidTransition, getValidTransitions, type AgentLifecycleHooks, AgentStateMachine, } from './runtime/agentState.js';
 export * from './internal/ids.js';
 export * from './internal/idempotency.js';
 export * from './runtime/persistenceAdapter.js';
 export * from './internal/errorMapper.js';
 export * from './internal/ack.js';
 export * from './internal/control.js';
+export { CommunicationClass, DebateIntensity, HitlReasonType, AckStage, EnvelopeState, WorktreeStateEnum, DEFAULT_ACK_TIMEOUT_MS, DEDUP_WINDOW_S, isTerminalEnvelopeState, updateEnvelopeState, MessageType, } from './constants/index.js';
+export * from './audit.js';
+export * from './agentConfig.js';
+export { type EnvelopeRecord, PersistentActivityBuffer, } from './persistentActivityBuffer.js';
 export * from './secrets/types.js';
 export * from './secrets/errors.js';
 export * from './secrets/backend.js';

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

@@ -25,9 +25,15 @@ export declare class BaseClient {
     protected readonly interceptors: InterceptorChain;
     protected readonly errorMapper: ErrorCodeMapper;
     constructor(opts: ClientOptions);
+    /**
+     * Resolves the protos directory, checking multiple locations:
+     * 1. npm package: ./protos relative to package root
+     * 2. Monorepo dev: ../../../../protos relative to this file
+     */
+    private resolveProtosDir;
     protected channelCredentials(): grpc.ChannelCredentials;
     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/internal/envelope.d.ts

@@ -30,6 +30,10 @@ export interface EnvelopeInput {
     hlc_timestamp?: string;
     ttl_ms?: number;
     timestamp?: Date;
+    state?: number;
+    effective_policy_id?: string;
+    audit_proof?: Uint8Array;
+    audit_policy_id?: string;
 }
 export interface EnvelopeBuilt {
     message_id: string;
@@ -47,7 +51,19 @@ export interface EnvelopeBuilt {
     ttl_ms?: number;
     timestamp: Timestamp;
     payload?: Uint8Array;
+    state: number;
+    effective_policy_id: string;
+    audit_proof: Uint8Array;
+    audit_policy_id: string;
 }
 export declare function nowTimestamp(date?: Date): Timestamp;
+/**
+ * Generate a stub HLC timestamp in the canonical format `HLC:<wall>:<logical>:<node>`.
+ *
+ * Per spec section 4, the HLC format combines wall-clock time (Unix microseconds),
+ * a logical counter (always 0 in this stub), and a node identifier (hostname).
+ * Full HLC implementations should increment the logical counter on concurrent
+ * events within the same microsecond.
+ */
 export declare function nowHlcStub(date?: Date): string;
 export declare function buildEnvelope(input: EnvelopeInput): EnvelopeBuilt;

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

@@ -13,6 +13,8 @@ export declare enum ErrorCode {
     PARTIAL_DELIVERY = 11,
     FORCED_PREEMPTION = 12,
     TTL_EXPIRED = 13,
+    DUPLICATE_DETECTED = 14,
+    ALREADY_IN_PROGRESS = 15,
     INTERNAL_ERROR = 99
 }
 export declare class Sw4rmError extends Error {
@@ -24,4 +26,116 @@ export declare class Sw4rmError extends Error {
         details?: string;
     });
 }
+/**
+ * Thrown when input validation fails.
+ * Default error code: VALIDATION_ERROR
+ */
+export declare class ValidationError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when an operation times out.
+ * Default error code: ACK_TIMEOUT
+ */
+export declare class TimeoutError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when an invalid state transition is attempted.
+ * Default error code: INTERNAL_ERROR
+ */
+export declare class StateTransitionError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when negotiation fails.
+ * Default error code: INTERNAL_ERROR
+ */
+export declare class NegotiationError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when the activity buffer is full.
+ * Default error code: BUFFER_FULL
+ */
+export declare class BufferFullError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when no route to destination exists.
+ * Default error code: NO_ROUTE
+ */
+export declare class RouteError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when permission is denied.
+ * Default error code: PERMISSION_DENIED
+ */
+export declare class PermissionError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when a duplicate request is detected.
+ * Default error code: DUPLICATE_DETECTED
+ */
+export declare class DuplicateDetectedError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when an agent is forcibly preempted by the scheduler.
+ * Default error code: FORCED_PREEMPTION
+ */
+export declare class PreemptionError extends Sw4rmError {
+    readonly agentId: string;
+    readonly reason: string;
+    constructor(agentId: string, reason: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when a worktree operation fails (bind, switch, etc.).
+ * Default error code: INTERNAL_ERROR
+ */
+export declare class WorktreeError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
+/**
+ * Thrown when an action violates a configured policy.
+ * Default error code: PERMISSION_DENIED
+ */
+export declare class PolicyViolationError extends Sw4rmError {
+    constructor(message: string, code?: ErrorCode, opts?: {
+        grpcStatus?: number;
+        details?: string;
+    });
+}
 export declare function mapGrpcStatusToErrorCode(status: number): ErrorCode;