@sw4rm/js-sdk 0.3.0 → 0.4.0

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

@@ -0,0 +1,188 @@
+/**
+ * Handoff client for SW4RM.
+ *
+ * This module provides the HandoffClient for managing agent-to-agent task
+ * handoffs. The handoff pattern enables:
+ * - Graceful transfer of work between agents
+ * - Context preservation during handoff
+ * - Capability-based routing to appropriate agents
+ *
+ * Based on handoff.proto definitions.
+ */
+/**
+ * Status of a handoff request.
+ */
+export declare enum HandoffStatus {
+    HANDOFF_STATUS_UNSPECIFIED = 0,
+    PENDING = 1,
+    ACCEPTED = 2,
+    REJECTED = 3,
+    COMPLETED = 4,
+    EXPIRED = 5
+}
+/**
+ * A request to hand off work from one agent to another.
+ *
+ * Contains the context needed for the receiving agent to continue
+ * the work, including capability requirements and priority information.
+ */
+export interface HandoffRequest {
+    /** Unique identifier for this handoff request */
+    requestId: string;
+    /** Agent ID of the agent initiating the handoff */
+    fromAgent: string;
+    /** Agent ID of the target agent (or empty for capability-based routing) */
+    toAgent: string;
+    /** Human-readable reason for the handoff */
+    reason: string;
+    /** Serialized context snapshot for the receiving agent */
+    contextSnapshot: Uint8Array;
+    /** List of capabilities required by the receiving agent */
+    capabilitiesRequired: string[];
+    /** Priority level of the handoff (lower is higher priority) */
+    priority: number;
+    /** Timeout in milliseconds for the handoff to be accepted */
+    timeoutMs?: number;
+    /** Timestamp when the request was created (ISO-8601 string) */
+    createdAt?: string;
+}
+/**
+ * Response to a handoff request.
+ *
+ * Indicates whether the handoff was accepted and by whom, or provides
+ * a rejection reason.
+ */
+export interface HandoffResponse {
+    /** Identifier of the handoff request being responded to */
+    requestId: string;
+    /** Whether the handoff was accepted */
+    accepted: boolean;
+    /** Agent ID of the agent that accepted the handoff (if accepted) */
+    acceptingAgent?: string;
+    /** Reason for rejection (if not accepted) */
+    rejectionReason?: string;
+}
+/**
+ * Error thrown when a handoff operation fails validation.
+ */
+export declare class HandoffValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when a handoff operation times out.
+ */
+export declare class HandoffTimeoutError extends Error {
+    constructor(message: string);
+}
+/**
+ * Client for managing agent-to-agent handoffs.
+ *
+ * Enables agents to transfer work to other agents while preserving
+ * context and ensuring proper capability matching. This is an in-memory
+ * implementation for Phase 2; future phases will integrate with gRPC services.
+ */
+export declare class HandoffClient {
+    private requests;
+    private responses;
+    private pendingByAgent;
+    /**
+     * Request a handoff to another agent.
+     *
+     * Initiates a handoff request that the target agent can accept or reject.
+     * The request is stored and made available to the target agent via
+     * getPendingHandoffs().
+     *
+     * @param request - The handoff request containing context and requirements
+     * @returns The response once the handoff is accepted, rejected, or times out
+     * @throws HandoffValidationError if a request with the same ID already exists
+     *
+     * @example
+     * ```typescript
+     * const client = new HandoffClient();
+     * const request: HandoffRequest = {
+     *   requestId: "handoff-123",
+     *   fromAgent: "agent-a",
+     *   toAgent: "agent-b",
+     *   reason: "Capability mismatch",
+     *   contextSnapshot: new TextEncoder().encode('{"state": "in_progress"}'),
+     *   capabilitiesRequired: ["code_review"],
+     *   priority: 5
+     * };
+     * const response = await client.requestHandoff(request);
+     * ```
+     */
+    requestHandoff(request: HandoffRequest): Promise<HandoffResponse>;
+    /**
+     * Accept a pending handoff request.
+     *
+     * Called by the target agent to accept a handoff. After acceptance,
+     * the agent should process the context snapshot and continue the work.
+     *
+     * @param handoffId - The ID of the handoff request to accept
+     * @throws HandoffValidationError if no request exists with the given ID
+     * @throws HandoffValidationError if the request has already been responded to
+     *
+     * @example
+     * ```typescript
+     * // Get pending handoffs for this agent
+     * const pending = await client.getPendingHandoffs("agent-b");
+     * if (pending.length > 0) {
+     *   await client.acceptHandoff(pending[0].requestId);
+     * }
+     * ```
+     */
+    acceptHandoff(handoffId: string): Promise<void>;
+    /**
+     * Reject a pending handoff request.
+     *
+     * Called by the target agent to reject a handoff. A reason should be
+     * provided to help the originating agent determine next steps.
+     *
+     * @param handoffId - The ID of the handoff request to reject
+     * @param reason - Human-readable reason for the rejection
+     * @throws HandoffValidationError if no request exists with the given ID
+     * @throws HandoffValidationError if the request has already been responded to
+     *
+     * @example
+     * ```typescript
+     * await client.rejectHandoff("handoff-123", "Agent at capacity");
+     * ```
+     */
+    rejectHandoff(handoffId: string, reason: string): Promise<void>;
+    /**
+     * Get all pending handoff requests for an agent.
+     *
+     * Returns handoff requests that have been addressed to the specified
+     * agent and have not yet been accepted or rejected.
+     *
+     * @param agentId - The ID of the agent to get pending handoffs for
+     * @returns List of pending handoff requests for the agent
+     *
+     * @example
+     * ```typescript
+     * const pending = await client.getPendingHandoffs("agent-b");
+     * console.log(`${pending.length} pending handoffs`);
+     * for (const request of pending) {
+     *   console.log(`From ${request.fromAgent}: ${request.reason}`);
+     * }
+     * ```
+     */
+    getPendingHandoffs(agentId: string): Promise<HandoffRequest[]>;
+    /**
+     * Get the response for a handoff request.
+     *
+     * Returns the response if the handoff has been accepted, rejected, or
+     * timed out. Returns null if the handoff is still pending.
+     *
+     * @param handoffId - The ID of the handoff request
+     * @returns The handoff response if available, null otherwise
+     */
+    getHandoffResponse(handoffId: string): Promise<HandoffResponse | null>;
+    /**
+     * Get the original handoff request.
+     *
+     * @param handoffId - The ID of the handoff request
+     * @returns The handoff request if it exists, null otherwise
+     */
+    getHandoffRequest(handoffId: string): Promise<HandoffRequest | null>;
+}

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

@@ -0,0 +1,347 @@
+/**
+ * Negotiation Room client for SW4RM.
+ *
+ * This module provides the NegotiationRoomClient for managing multi-agent
+ * artifact approval workflows using the Negotiation Room pattern. The client
+ * supports:
+ * - Submitting artifacts for review
+ * - Collecting votes from critics
+ * - Retrieving and waiting for decisions
+ * - Coordinating the review process
+ *
+ * Based on SPEC_REQUESTS.md section 6.1.
+ */
+/**
+ * Type of artifact being negotiated.
+ *
+ * Maps to the artifact_type field in negotiation proposals to categorize
+ * what stage of the workflow the artifact belongs to.
+ */
+export declare enum ArtifactType {
+    ARTIFACT_TYPE_UNSPECIFIED = 0,
+    REQUIREMENTS = 1,
+    PLAN = 2,
+    CODE = 3,
+    DEPLOYMENT = 4
+}
+/**
+ * Outcome of a negotiation decision.
+ *
+ * Represents the final decision made by the coordinator after aggregating
+ * critic votes and applying policy.
+ */
+export declare enum DecisionOutcome {
+    DECISION_OUTCOME_UNSPECIFIED = 0,
+    APPROVED = 1,
+    REVISION_REQUESTED = 2,
+    ESCALATED_TO_HITL = 3
+}
+/**
+ * A proposal for artifact evaluation in a negotiation room.
+ *
+ * Submitted by a producer agent to request multi-agent review of an artifact.
+ * The proposal specifies which critics should evaluate the artifact and
+ * includes the artifact content for review.
+ */
+export interface NegotiationProposal {
+    /** Category of artifact (requirements, plan, code, deployment) */
+    artifactType: ArtifactType;
+    /** Unique identifier for this artifact */
+    artifactId: string;
+    /** Agent ID of the producer submitting the artifact */
+    producerId: string;
+    /** Binary artifact content (e.g., serialized JSON, code files) */
+    artifact: Uint8Array;
+    /** MIME type or content type identifier */
+    artifactContentType: string;
+    /** List of critic agent IDs requested for evaluation */
+    requestedCritics: string[];
+    /** Identifier for the negotiation room session */
+    negotiationRoomId: string;
+    /** Timestamp when proposal was created (ISO-8601 string) */
+    createdAt?: string;
+}
+/**
+ * A critic's evaluation of an artifact.
+ *
+ * Represents a single critic's assessment including numerical scoring,
+ * qualitative feedback, and confidence level based on POMDP uncertainty.
+ */
+export interface NegotiationVote {
+    /** Identifier of the artifact being evaluated */
+    artifactId: string;
+    /** Agent ID of the critic providing this vote */
+    criticId: string;
+    /** Numerical score from 0-10 (10 = excellent) */
+    score: number;
+    /** Confidence level from 0-1 (based on POMDP research) */
+    confidence: number;
+    /** Boolean indicating if artifact meets minimum criteria */
+    passed: boolean;
+    /** List of identified strengths in the artifact */
+    strengths: string[];
+    /** List of identified weaknesses or concerns */
+    weaknesses: string[];
+    /** List of suggestions for improvement */
+    recommendations: string[];
+    /** Identifier for the negotiation room session */
+    negotiationRoomId: string;
+    /** Timestamp when vote was cast (ISO-8601 string) */
+    votedAt?: string;
+}
+/**
+ * Statistical aggregation of multiple critic votes.
+ *
+ * Provides multiple views of the voting results including basic statistics
+ * and confidence-weighted metrics for decision making.
+ */
+export interface AggregatedScore {
+    /** Arithmetic mean of all scores */
+    mean: number;
+    /** Minimum score from any critic */
+    minScore: number;
+    /** Maximum score from any critic */
+    maxScore: number;
+    /** Standard deviation of scores (measures consensus) */
+    stdDev: number;
+    /** Confidence-weighted mean (higher confidence votes weighted more) */
+    weightedMean: number;
+    /** Number of votes included in aggregation */
+    voteCount: number;
+}
+/**
+ * Final decision on an artifact after critic evaluation.
+ *
+ * Represents the coordinator's decision after aggregating all critic votes
+ * and applying policy thresholds. Includes full audit trail of votes and
+ * reasoning.
+ */
+export interface NegotiationDecision {
+    /** Identifier of the artifact that was evaluated */
+    artifactId: string;
+    /** Final decision (approved, revision requested, escalated to HITL) */
+    outcome: DecisionOutcome;
+    /** Complete list of all critic votes considered */
+    votes: NegotiationVote[];
+    /** Statistical summary of the votes */
+    aggregatedScore: AggregatedScore;
+    /** Version identifier of the policy used for decision */
+    policyVersion: string;
+    /** Human-readable explanation of the decision */
+    reason: string;
+    /** Identifier for the negotiation room session */
+    negotiationRoomId: string;
+    /** Timestamp when decision was made (ISO-8601 string) */
+    decidedAt?: string;
+}
+/**
+ * Error thrown when a negotiation room operation times out.
+ */
+export declare class NegotiationTimeoutError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when a negotiation room operation fails validation.
+ */
+export declare class NegotiationValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Client for interacting with negotiation rooms.
+ *
+ * Manages the lifecycle of artifact proposals through the multi-agent
+ * review process. Producers submit proposals, critics submit votes,
+ * and coordinators retrieve votes to make decisions.
+ *
+ * This is an in-memory implementation for Phase 2. Future phases
+ * will integrate with persistent storage and gRPC services.
+ */
+export declare class NegotiationRoomClient {
+    private proposals;
+    private votes;
+    private decisions;
+    /**
+     * Submit an artifact proposal for multi-agent review.
+     *
+     * Stores the proposal and initializes empty vote tracking for the artifact.
+     * This method is typically called by producer agents.
+     *
+     * @param proposal - The negotiation proposal containing artifact details
+     * @returns The artifact_id of the submitted proposal
+     * @throws NegotiationValidationError if a proposal with the same artifact_id already exists
+     *
+     * @example
+     * ```typescript
+     * const client = new NegotiationRoomClient();
+     * const proposal: NegotiationProposal = {
+     *   artifactType: ArtifactType.CODE,
+     *   artifactId: "code-123",
+     *   producerId: "agent-producer",
+     *   artifact: new TextEncoder().encode("def hello(): pass"),
+     *   artifactContentType: "text/x-python",
+     *   requestedCritics: ["critic-1", "critic-2"],
+     *   negotiationRoomId: "room-1"
+     * };
+     * const artifactId = await client.submitProposal(proposal);
+     * console.log(artifactId); // "code-123"
+     * ```
+     */
+    submitProposal(proposal: NegotiationProposal): Promise<string>;
+    /**
+     * Submit a critic's vote for an artifact.
+     *
+     * Adds the vote to the collection for the specified artifact.
+     * This method is typically called by critic agents after evaluating
+     * an artifact.
+     *
+     * @param vote - The negotiation vote containing the critic's evaluation
+     * @throws NegotiationValidationError if no proposal exists for the vote's artifact_id
+     * @throws NegotiationValidationError if the critic has already voted for this artifact
+     * @throws NegotiationValidationError if score or confidence are out of range
+     *
+     * @example
+     * ```typescript
+     * const vote: NegotiationVote = {
+     *   artifactId: "code-123",
+     *   criticId: "critic-1",
+     *   score: 8.5,
+     *   confidence: 0.9,
+     *   passed: true,
+     *   strengths: ["Good structure"],
+     *   weaknesses: ["Needs tests"],
+     *   recommendations: ["Add unit tests"],
+     *   negotiationRoomId: "room-1"
+     * };
+     * await client.submitVote(vote);
+     * ```
+     */
+    submitVote(vote: NegotiationVote): Promise<void>;
+    /**
+     * Retrieve all votes for a specific artifact.
+     *
+     * Returns all critic votes that have been submitted for the artifact.
+     * This method is typically called by coordinator agents to aggregate
+     * votes and make decisions.
+     *
+     * @param artifactId - The identifier of the artifact
+     * @returns List of all votes for the artifact (empty array if no votes yet)
+     * @throws NegotiationValidationError if no proposal exists for the artifact_id
+     *
+     * @example
+     * ```typescript
+     * const votes = await client.getVotes("code-123");
+     * console.log(votes.length); // 1
+     * ```
+     */
+    getVotes(artifactId: string): Promise<NegotiationVote[]>;
+    /**
+     * Retrieve the decision for a specific artifact if available.
+     *
+     * Returns the final decision if one has been made, or null if the
+     * artifact is still under review.
+     *
+     * @param artifactId - The identifier of the artifact
+     * @returns The negotiation decision if available, null otherwise
+     * @throws NegotiationValidationError if no proposal exists for the artifact_id
+     *
+     * @example
+     * ```typescript
+     * const decision = await client.getDecision("code-123");
+     * if (decision === null) {
+     *   console.log("Decision pending");
+     * }
+     * ```
+     */
+    getDecision(artifactId: string): Promise<NegotiationDecision | null>;
+    /**
+     * Store a decision for an artifact.
+     *
+     * This is an internal method used by coordinators to record the
+     * final decision after evaluating votes. Once a decision is stored,
+     * it becomes available via getDecision() and waitForDecision().
+     *
+     * @param decision - The negotiation decision to store
+     * @throws NegotiationValidationError if no proposal exists for the decision's artifact_id
+     * @throws NegotiationValidationError if a decision already exists for this artifact
+     *
+     * @example
+     * ```typescript
+     * const votes = await client.getVotes("code-123");
+     * const aggregated = aggregateVotes(votes);
+     * const decision: NegotiationDecision = {
+     *   artifactId: "code-123",
+     *   outcome: DecisionOutcome.APPROVED,
+     *   votes: votes,
+     *   aggregatedScore: aggregated,
+     *   policyVersion: "1.0",
+     *   reason: "Met all criteria",
+     *   negotiationRoomId: "room-1"
+     * };
+     * await client.storeDecision(decision);
+     * ```
+     */
+    storeDecision(decision: NegotiationDecision): Promise<void>;
+    /**
+     * Wait for a decision to be made on an artifact.
+     *
+     * Polls for a decision until one is available or the timeout is reached.
+     * This method is useful for producer agents waiting for the outcome
+     * of their artifact review.
+     *
+     * @param artifactId - The identifier of the artifact
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 30000)
+     * @param pollIntervalMs - Time between polling attempts in milliseconds (default: 100)
+     * @returns The negotiation decision once available
+     * @throws NegotiationValidationError if no proposal exists for the artifact_id
+     * @throws NegotiationTimeoutError if no decision is made within the timeout period
+     *
+     * @example
+     * ```typescript
+     * // In a separate thread/process, a coordinator makes a decision
+     * const decision = await client.waitForDecision("code-123", 10000);
+     * console.log(decision.outcome); // DecisionOutcome.APPROVED
+     * ```
+     */
+    waitForDecision(artifactId: string, timeoutMs?: number, pollIntervalMs?: number): Promise<NegotiationDecision>;
+    /**
+     * Retrieve the original proposal for an artifact.
+     *
+     * Useful for critics that need to review the original artifact
+     * before submitting a vote.
+     *
+     * @param artifactId - The identifier of the artifact
+     * @returns The negotiation proposal if it exists, null otherwise
+     *
+     * @example
+     * ```typescript
+     * const proposal = await client.getProposal("code-123");
+     * console.log(proposal?.artifactType); // ArtifactType.CODE
+     * ```
+     */
+    getProposal(artifactId: string): Promise<NegotiationProposal | null>;
+    /**
+     * List all proposals, optionally filtered by negotiation room.
+     *
+     * @param negotiationRoomId - If provided, only return proposals for this room
+     * @returns List of proposals matching the filter criteria
+     *
+     * @example
+     * ```typescript
+     * const proposals = await client.listProposals("room-1");
+     * console.log(proposals.length); // 1
+     * ```
+     */
+    listProposals(negotiationRoomId?: string): Promise<NegotiationProposal[]>;
+}
+/**
+ * Aggregate multiple critic votes into statistical summary.
+ *
+ * Computes both basic statistics (mean, min, max, std dev) and a
+ * confidence-weighted mean that gives more weight to votes from critics
+ * with higher confidence levels.
+ *
+ * @param votes - List of critic votes to aggregate
+ * @returns AggregatedScore with statistical summary of votes
+ * @throws NegotiationValidationError if votes list is empty
+ */
+export declare function aggregateVotes(votes: NegotiationVote[]): AggregatedScore;