@sw4rm/js-sdk 0.3.0 → 0.5.0

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

@@ -0,0 +1,423 @@
+/**
+ * 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.
+ *
+ * ## Concurrency Fix (v0.5.0)
+ *
+ * The client now uses a pluggable storage backend (NegotiationRoomStore) instead
+ * of instance-local storage. This enables multiple client instances to share
+ * state, which is essential for multi-agent deployments where producer, critic,
+ * and coordinator agents run in different processes or workers.
+ *
+ * ### Usage patterns
+ *
+ * 1. Single-process with shared default store (recommended):
+ * ```typescript
+ * const client1 = new NegotiationRoomClient();  // Uses shared default store
+ * const client2 = new NegotiationRoomClient();  // Same store, shared state
+ * ```
+ *
+ * 2. Explicit store sharing:
+ * ```typescript
+ * const store = new InMemoryNegotiationRoomStore();
+ * const producer = new NegotiationRoomClient({ store });
+ * const critic = new NegotiationRoomClient({ store });
+ * ```
+ *
+ * 3. File-based persistence (multi-process, requires colony):
+ * ```typescript
+ * import { JsonFileNegotiationRoomStore } from 'colony/stores/typescript/jsonFileStore';
+ * const store = new JsonFileNegotiationRoomStore("/path/to/storage");
+ * const client = new NegotiationRoomClient({ store });
+ * ```
+ */
+import { NegotiationRoomStore } from './negotiationRoomStore.js';
+/**
+ * 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);
+}
+/**
+ * Configuration options for NegotiationRoomClient.
+ */
+export interface NegotiationRoomClientOptions {
+    /**
+     * Storage backend for proposals, votes, and decisions.
+     * If not provided, uses the shared default in-memory store.
+     */
+    store?: NegotiationRoomStore;
+}
+/**
+ * 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 client uses a pluggable storage backend, enabling state sharing
+ * across multiple client instances. By default, all clients within the
+ * same process share a common in-memory store.
+ *
+ * @example
+ * ```typescript
+ * // Simple usage - all clients share default store
+ * 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"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Explicit store sharing
+ * import { InMemoryNegotiationRoomStore } from './negotiationRoomStore';
+ *
+ * const store = new InMemoryNegotiationRoomStore();
+ * const producer = new NegotiationRoomClient({ store });
+ * const critic = new NegotiationRoomClient({ store });
+ *
+ * // Producer and critic now share state
+ * ```
+ */
+export declare class NegotiationRoomClient {
+    private readonly store;
+    /**
+     * Create a new negotiation room client.
+     *
+     * @param options - Configuration options. If no store is provided,
+     *                  uses the shared default in-memory store.
+     */
+    constructor(options?: NegotiationRoomClientOptions);
+    /**
+     * 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;

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

@@ -0,0 +1,155 @@
+/**
+ * Negotiation Room storage backend abstraction.
+ *
+ * This module provides a pluggable storage layer for NegotiationRoomClient,
+ * enabling shared state across multiple client instances.
+ *
+ * The key insight is that NegotiationRoomClient previously used instance-local
+ * storage (private Maps), which broke multi-instance deployments. By extracting
+ * storage into a separate abstraction that can be shared, we enable:
+ *
+ * 1. Multiple client instances sharing the same storage
+ * 2. Producer/Critic/Coordinator agents in different processes sharing state
+ * 3. Future gRPC integration where the server becomes the source of truth
+ *
+ * For persistent storage backends (JSON file, Redis, PostgreSQL), see the
+ * colony/stores module which provides optional persistence implementations.
+ *
+ * Based on the PolicyStore pattern established in policyStore.ts.
+ */
+import { NegotiationProposal, NegotiationVote, NegotiationDecision } from './negotiationRoom.js';
+/**
+ * Error thrown when a negotiation room store operation fails.
+ */
+export declare class NegotiationRoomStoreError extends Error {
+    constructor(message: string);
+}
+/**
+ * Interface defining the contract for negotiation room storage backends.
+ *
+ * All storage implementations must support these operations for proposals,
+ * votes, and decisions. This follows the same pattern as PolicyStore,
+ * enabling pluggable backends ranging from in-memory to file-based to gRPC-based.
+ */
+export interface NegotiationRoomStore {
+    /**
+     * Check if a proposal exists for the given artifact_id.
+     *
+     * @param artifactId - Unique identifier for the artifact
+     * @returns True if a proposal exists, false otherwise
+     */
+    hasProposal(artifactId: string): Promise<boolean>;
+    /**
+     * Retrieve a proposal by artifact_id.
+     *
+     * @param artifactId - Unique identifier for the artifact
+     * @returns The proposal if found, null otherwise
+     */
+    getProposal(artifactId: string): Promise<NegotiationProposal | null>;
+    /**
+     * Save a proposal to storage.
+     *
+     * @param proposal - The proposal to save
+     * @throws NegotiationRoomStoreError if a proposal with the same artifact_id already exists
+     */
+    saveProposal(proposal: NegotiationProposal): Promise<void>;
+    /**
+     * 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
+     */
+    listProposals(negotiationRoomId?: string): Promise<NegotiationProposal[]>;
+    /**
+     * Retrieve all votes for a specific artifact.
+     *
+     * @param artifactId - The identifier of the artifact
+     * @returns List of all votes for the artifact (empty array if no votes)
+     */
+    getVotes(artifactId: string): Promise<NegotiationVote[]>;
+    /**
+     * Add a vote for an artifact.
+     *
+     * @param vote - The vote to add
+     * @throws NegotiationRoomStoreError if the critic has already voted for this artifact
+     */
+    addVote(vote: NegotiationVote): Promise<void>;
+    /**
+     * Retrieve the decision for an artifact.
+     *
+     * @param artifactId - The identifier of the artifact
+     * @returns The decision if available, null otherwise
+     */
+    getDecision(artifactId: string): Promise<NegotiationDecision | null>;
+    /**
+     * Save a decision for an artifact.
+     *
+     * @param decision - The decision to save
+     * @throws NegotiationRoomStoreError if a decision already exists for this artifact
+     */
+    saveDecision(decision: NegotiationDecision): Promise<void>;
+}
+/**
+ * In-memory implementation of NegotiationRoomStore.
+ *
+ * Stores proposals, votes, and decisions in memory. Data is lost when the
+ * process terminates. Suitable for testing and single-process deployments.
+ *
+ * Thread-safety: JavaScript is single-threaded, but async operations are
+ * properly sequenced.
+ *
+ * @example
+ * ```typescript
+ * // Create a single shared store
+ * const sharedStore = new InMemoryNegotiationRoomStore();
+ *
+ * // Pass to multiple clients
+ * const producerClient = new NegotiationRoomClient({ store: sharedStore });
+ * const criticClient = new NegotiationRoomClient({ store: sharedStore });
+ * const coordinatorClient = new NegotiationRoomClient({ store: sharedStore });
+ *
+ * // Now all clients share the same state
+ * ```
+ */
+export declare class InMemoryNegotiationRoomStore implements NegotiationRoomStore {
+    private proposals;
+    private votes;
+    private decisions;
+    hasProposal(artifactId: string): Promise<boolean>;
+    getProposal(artifactId: string): Promise<NegotiationProposal | null>;
+    saveProposal(proposal: NegotiationProposal): Promise<void>;
+    listProposals(negotiationRoomId?: string): Promise<NegotiationProposal[]>;
+    getVotes(artifactId: string): Promise<NegotiationVote[]>;
+    addVote(vote: NegotiationVote): Promise<void>;
+    getDecision(artifactId: string): Promise<NegotiationDecision | null>;
+    saveDecision(decision: NegotiationDecision): Promise<void>;
+}
+/**
+ * Get the default shared in-memory store.
+ *
+ * This provides a convenient way to share state across multiple
+ * NegotiationRoomClient instances within the same process without
+ * explicitly passing a store instance.
+ *
+ * @returns The default shared InMemoryNegotiationRoomStore instance
+ *
+ * @example
+ * ```typescript
+ * // All clients automatically share the same store
+ * const client1 = new NegotiationRoomClient();  // Uses default store
+ * const client2 = new NegotiationRoomClient();  // Uses same default store
+ *
+ * // Equivalent to:
+ * const store = getDefaultStore();
+ * const client1 = new NegotiationRoomClient({ store });
+ * const client2 = new NegotiationRoomClient({ store });
+ * ```
+ */
+export declare function getDefaultStore(): InMemoryNegotiationRoomStore;
+/**
+ * Reset the default store (primarily for testing).
+ *
+ * This clears the default store singleton, causing a new store
+ * to be created on the next call to getDefaultStore().
+ */
+export declare function resetDefaultStore(): void;