@sw4rm/js-sdk 0.3.0 → 0.5.0

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

@@ -0,0 +1,391 @@
+/**
+ * Policy store for SW4RM.
+ *
+ * This module provides interfaces and implementations for storing and
+ * retrieving negotiation policies. Policies define the rules and thresholds
+ * for negotiation workflows.
+ *
+ * Based on policy.proto definitions.
+ */
+/**
+ * HITL gate mode for policies.
+ */
+export declare enum HitlMode {
+    NONE = "None",
+    PAUSE_BETWEEN_ROUNDS = "PauseBetweenRounds",
+    PAUSE_ON_FINAL_ACCEPT = "PauseOnFinalAccept"
+}
+/**
+ * Scoring configuration for policies.
+ */
+export interface ScoringConfig {
+    /** Whether to require JSON schema validation */
+    requireSchemaValid: boolean;
+    /** Whether to require examples to pass */
+    requireExamplesPass: boolean;
+    /** Weight for LLM-based scoring (0-1) */
+    llmWeight: number;
+}
+/**
+ * A negotiation policy defining rules and thresholds.
+ *
+ * Policies are used by the scheduler to control negotiation behavior
+ * and ensure consistency across negotiations.
+ */
+export interface NegotiationPolicy {
+    /** Maximum number of negotiation rounds */
+    maxRounds: number;
+    /** Score threshold for approval (0-1) */
+    scoreThreshold: number;
+    /** Tolerance for structural differences (0-1) */
+    diffTolerance: number;
+    /** Timeout per round in milliseconds */
+    roundTimeoutMs: number;
+    /** Token budget per round */
+    tokenBudgetPerRound: number;
+    /** Total token budget (0 = unlimited) */
+    totalTokenBudget: number;
+    /** Maximum oscillations before escalation */
+    oscillationLimit: number;
+    /** HITL gate mode */
+    hitl: HitlMode;
+    /** Scoring configuration */
+    scoring: ScoringConfig;
+}
+/**
+ * Agent preferences for negotiation.
+ *
+ * Same fields as NegotiationPolicy but advisory; scheduler clamps to guardrails.
+ */
+export interface AgentPreferences {
+    maxRounds?: number;
+    scoreThreshold?: number;
+    diffTolerance?: number;
+    roundTimeoutMs?: number;
+    tokenBudgetPerRound?: number;
+    totalTokenBudget?: number;
+    oscillationLimit?: number;
+}
+/**
+ * Network access policy for execution.
+ */
+export type NetworkPolicy = 'none' | 'restricted' | 'full';
+/**
+ * Privilege level for execution.
+ */
+export type PrivilegeLevel = 'standard' | 'elevated' | 'admin';
+/**
+ * Backoff strategy for retries.
+ */
+export type BackoffStrategy = 'none' | 'linear' | 'exponential';
+/**
+ * Policy governing task execution.
+ *
+ * Defines constraints and resource limits for executing tasks.
+ * Per SPEC_REQUESTS §6.3.
+ *
+ * Note: Named TaskExecutionPolicy to avoid conflict with tool.ts ExecutionPolicy.
+ */
+export interface TaskExecutionPolicy {
+    /** Maximum execution time in milliseconds */
+    timeoutMs: number;
+    /** Maximum number of retry attempts */
+    maxRetries: number;
+    /** Backoff strategy for retries */
+    backoff: BackoffStrategy;
+    /** Whether a worktree binding is required for execution */
+    worktreeRequired: boolean;
+    /** Network access policy */
+    networkPolicy: NetworkPolicy;
+    /** Required privilege level */
+    privilegeLevel: PrivilegeLevel;
+    /** CPU time budget in milliseconds */
+    budgetCpuMs: number;
+    /** Wall clock time budget in milliseconds */
+    budgetWallMs: number;
+}
+/**
+ * Policy governing escalation behavior.
+ *
+ * Defines when and how negotiations should be escalated.
+ * Per SPEC_REQUESTS §6.3.
+ */
+export interface EscalationPolicy {
+    /** Whether to automatically escalate when deadlock is detected */
+    autoEscalateOnDeadlock: boolean;
+    /** Number of rounds without progress before declaring deadlock */
+    deadlockRounds: number;
+    /** List of valid reasons for escalation */
+    escalationReasons: string[];
+    /** Default action when escalation is triggered */
+    defaultAction: 'retry_same' | 'escalate' | 'fail';
+}
+/**
+ * Default execution policy.
+ */
+export declare const DEFAULT_EXECUTION_POLICY: TaskExecutionPolicy;
+/**
+ * Default escalation policy.
+ */
+export declare const DEFAULT_ESCALATION_POLICY: EscalationPolicy;
+/**
+ * Effective policy after applying agent preferences and scheduler guardrails.
+ *
+ * Combines negotiation, execution, and escalation policies as per SPEC_REQUESTS §6.3.
+ */
+export interface EffectivePolicy {
+    /** Unique identifier for this effective policy */
+    policyId: string;
+    /** Version string for the policy (timestamp_uuid format) */
+    version: string;
+    /** The derived authoritative negotiation policy */
+    negotiation: NegotiationPolicy;
+    /** Execution policy settings */
+    execution: TaskExecutionPolicy;
+    /** Escalation policy settings */
+    escalation: EscalationPolicy;
+    /** Per-agent clamped preferences (optional) */
+    applied?: Record<string, AgentPreferences>;
+    /** Negotiation ID this policy applies to */
+    negotiationId?: string;
+    /** Timestamp when policy was created (ISO-8601 string) */
+    createdAt?: string;
+}
+/**
+ * A named policy profile.
+ */
+export interface PolicyProfile {
+    /** Profile name (e.g., "LOW", "MEDIUM", "HIGH") */
+    name: string;
+    /** The negotiation policy for this profile */
+    negotiation: NegotiationPolicy;
+    /** The execution policy for this profile */
+    execution: TaskExecutionPolicy;
+    /** The escalation policy for this profile */
+    escalation: EscalationPolicy;
+}
+/**
+ * Error thrown when a policy operation fails.
+ */
+export declare class PolicyStoreError extends Error {
+    constructor(message: string);
+}
+/**
+ * Interface for policy storage backends.
+ *
+ * Implementations provide storage and retrieval of negotiation policies.
+ * Policies are immutable once stored - saving a policy with the same
+ * policy_id but different version creates a new snapshot in the history.
+ */
+export interface PolicyStore {
+    /**
+     * Get the latest version of a policy by its ID.
+     *
+     * @param policyId - The unique identifier of the policy
+     * @returns The effective policy if found, null otherwise
+     */
+    getPolicy(policyId: string): Promise<EffectivePolicy | null>;
+    /**
+     * Save a policy snapshot.
+     *
+     * If the policy does not have a version, one will be generated.
+     * The policy snapshot is immutable once saved.
+     *
+     * @param policy - The effective policy to save
+     * @returns The policy ID
+     */
+    savePolicy(policy: EffectivePolicy): Promise<string>;
+    /**
+     * List all policy IDs, optionally filtered by prefix.
+     *
+     * @param prefix - Optional prefix to filter policy IDs
+     * @returns List of matching policy IDs
+     */
+    listPolicies(prefix?: string): Promise<string[]>;
+    /**
+     * Delete a policy by its ID (removes all versions).
+     *
+     * @param policyId - The unique identifier of the policy
+     * @returns True if the policy was deleted, false if not found
+     */
+    deletePolicy(policyId: string): Promise<boolean>;
+    /**
+     * Retrieve the complete version history for a policy.
+     *
+     * Returns policies in chronological order (oldest to newest).
+     *
+     * @param policyId - The unique identifier of the policy
+     * @returns List of all versions of the policy
+     */
+    getHistory(policyId: string): Promise<EffectivePolicy[]>;
+    /**
+     * Get a policy profile by name.
+     *
+     * @param name - The profile name
+     * @returns The policy profile if found, null otherwise
+     */
+    getProfile(name: string): Promise<PolicyProfile | null>;
+    /**
+     * Save a policy profile.
+     *
+     * @param profile - The policy profile to save
+     * @returns The profile name
+     */
+    saveProfile(profile: PolicyProfile): Promise<string>;
+    /**
+     * List all profile names.
+     *
+     * @returns List of profile names
+     */
+    listProfiles(): Promise<string[]>;
+}
+/**
+ * Default negotiation policy.
+ *
+ * Used when no specific policy is configured.
+ */
+export declare const DEFAULT_NEGOTIATION_POLICY: NegotiationPolicy;
+/**
+ * In-memory implementation of PolicyStore.
+ *
+ * Provides a simple in-memory storage for policies and profiles with
+ * full version history support. Data is lost when the process terminates.
+ * Suitable for development and testing; production deployments should
+ * use JsonFilePolicyStore for persistence.
+ */
+export declare class InMemoryPolicyStore implements PolicyStore {
+    private policies;
+    private profiles;
+    constructor();
+    /**
+     * Initialize default policy profiles.
+     */
+    private initializeDefaultProfiles;
+    /**
+     * Get the latest version of a policy by its ID.
+     *
+     * @param policyId - The unique identifier of the policy
+     * @returns The most recent effective policy if found, null otherwise
+     */
+    getPolicy(policyId: string): Promise<EffectivePolicy | null>;
+    /**
+     * Save a policy snapshot to the version history.
+     *
+     * If the policy does not have an ID, one will be generated.
+     * If the policy does not have a version, one will be generated.
+     *
+     * @param policy - The effective policy to save
+     * @returns The policy ID
+     */
+    savePolicy(policy: EffectivePolicy): Promise<string>;
+    /**
+     * List all policy IDs, optionally filtered by prefix.
+     *
+     * @param prefix - Optional prefix to filter policy IDs
+     * @returns List of matching policy IDs
+     */
+    listPolicies(prefix?: string): Promise<string[]>;
+    /**
+     * Delete a policy by its ID (removes all versions).
+     *
+     * @param policyId - The unique identifier of the policy
+     * @returns True if the policy was deleted, false if not found
+     */
+    deletePolicy(policyId: string): Promise<boolean>;
+    /**
+     * Retrieve the complete version history for a policy.
+     *
+     * Returns policies in chronological order (oldest to newest).
+     *
+     * @param policyId - The unique identifier of the policy
+     * @returns List of all versions of the policy
+     */
+    getHistory(policyId: string): Promise<EffectivePolicy[]>;
+    /**
+     * Get a policy profile by name.
+     *
+     * @param name - The profile name
+     * @returns The policy profile if found, null otherwise
+     */
+    getProfile(name: string): Promise<PolicyProfile | null>;
+    /**
+     * Save a policy profile.
+     *
+     * @param profile - The policy profile to save
+     * @returns The profile name
+     */
+    saveProfile(profile: PolicyProfile): Promise<string>;
+    /**
+     * List all profile names.
+     *
+     * @returns List of profile names
+     */
+    listProfiles(): Promise<string[]>;
+    /**
+     * Create an effective policy from a profile and agent preferences.
+     *
+     * Clamps agent preferences to the profile's guardrails.
+     *
+     * @param profileName - The profile to use as base
+     * @param agentPrefs - Optional agent preferences to apply
+     * @param negotiationId - Optional negotiation ID
+     * @returns The effective policy
+     * @throws PolicyStoreError if the profile does not exist
+     */
+    createEffectivePolicy(profileName: string, agentPrefs?: Record<string, AgentPreferences>, negotiationId?: string): Promise<EffectivePolicy>;
+}
+/**
+ * JSON file-based implementation of PolicyStore.
+ *
+ * Stores policies as JSON files on disk with full version history support.
+ * Each policy is stored in a separate file named `{sanitized_policy_id}.json`.
+ * Uses atomic writes (temp file + rename) to prevent corruption.
+ *
+ * Suitable for production use in single-node deployments.
+ */
+export declare class JsonFilePolicyStore implements PolicyStore {
+    private readonly directory;
+    private profiles;
+    /**
+     * Create a new JSON file policy store.
+     *
+     * @param directory - Directory to store policy files
+     */
+    constructor(directory: string);
+    /**
+     * Initialize the store, creating the directory if needed.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Initialize default policy profiles.
+     */
+    private initializeDefaultProfiles;
+    /**
+     * Sanitize a policy ID for use as a filename.
+     */
+    private sanitizeId;
+    /**
+     * Get the file path for a policy.
+     */
+    private getFilePath;
+    /**
+     * Load versions from a file.
+     */
+    private loadFromFile;
+    /**
+     * Save versions to a file atomically.
+     */
+    private saveToFile;
+    getPolicy(policyId: string): Promise<EffectivePolicy | null>;
+    savePolicy(policy: EffectivePolicy): Promise<string>;
+    listPolicies(prefix?: string): Promise<string[]>;
+    deletePolicy(policyId: string): Promise<boolean>;
+    getHistory(policyId: string): Promise<EffectivePolicy[]>;
+    getProfile(name: string): Promise<PolicyProfile | null>;
+    saveProfile(profile: PolicyProfile): Promise<string>;
+    listProfiles(): Promise<string[]>;
+    /**
+     * Create an effective policy from a profile and agent preferences.
+     */
+    createEffectivePolicy(profileName: string, agentPrefs?: Record<string, AgentPreferences>, negotiationId?: string): Promise<EffectivePolicy>;
+}

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

@@ -0,0 +1,208 @@
+/**
+ * Voting and aggregation strategies for SW4RM.
+ *
+ * This module provides aggregation strategies for combining critic votes
+ * in negotiation room workflows. Strategies include:
+ * - SimpleAverageAggregator: Arithmetic mean of all scores
+ * - ConfidenceWeightedAggregator: Weight votes by confidence (POMDP-based)
+ * - MajorityVoteAggregator: Count passed vs failed votes
+ * - BordaCountAggregator: Ranked voting with position-based points
+ *
+ * Based on Python SDK voting/strategies.py and voting/aggregation.py.
+ */
+import { NegotiationVote, AggregatedScore } from '../clients/negotiationRoom.js';
+/**
+ * Interface for vote aggregation strategies.
+ *
+ * Implementations must provide an aggregate method that takes a list of votes
+ * and returns an AggregatedScore with statistical summary.
+ */
+export interface VotingAggregator {
+    /**
+     * Aggregate votes into statistical summary.
+     *
+     * @param votes - List of critic votes to aggregate
+     * @returns AggregatedScore with aggregation results
+     * @throws NegotiationValidationError if votes list is empty or invalid
+     */
+    aggregate(votes: NegotiationVote[]): AggregatedScore;
+}
+/**
+ * Simple arithmetic mean aggregation strategy.
+ *
+ * Computes basic statistics without considering confidence levels.
+ * All votes are weighted equally.
+ */
+export declare class SimpleAverageAggregator implements VotingAggregator {
+    /**
+     * Aggregate votes using simple arithmetic mean.
+     *
+     * @param votes - List of critic votes to aggregate
+     * @returns AggregatedScore with simple mean in both mean and weightedMean fields
+     * @throws NegotiationValidationError if votes list is empty
+     */
+    aggregate(votes: NegotiationVote[]): AggregatedScore;
+}
+/**
+ * Confidence-weighted aggregation strategy based on POMDP research.
+ *
+ * Weights each vote's score by its confidence value, giving more influence
+ * to votes from critics with higher certainty. This implements the approach
+ * from POMDP research where agent confidence reflects belief state certainty.
+ *
+ * Formula: weighted_mean = sum(score_i * confidence_i) / sum(confidence_i)
+ */
+export declare class ConfidenceWeightedAggregator implements VotingAggregator {
+    /**
+     * Aggregate votes using confidence weighting.
+     *
+     * @param votes - List of critic votes to aggregate
+     * @returns AggregatedScore with confidence-weighted mean
+     * @throws NegotiationValidationError if votes list is empty
+     */
+    aggregate(votes: NegotiationVote[]): AggregatedScore;
+}
+/**
+ * Majority voting aggregation strategy.
+ *
+ * Counts the number of passed vs failed votes and returns a score based on
+ * the majority outcome. This is a binary approach that ignores the numerical
+ * score values and focuses on the pass/fail decision.
+ *
+ * Score mapping:
+ * - All passed: 10.0
+ * - Majority passed (>50%): 7.5
+ * - Tie: 5.0
+ * - Majority failed (>50%): 2.5
+ * - All failed: 0.0
+ */
+export declare class MajorityVoteAggregator implements VotingAggregator {
+    /**
+     * Aggregate votes using majority voting.
+     *
+     * @param votes - List of critic votes to aggregate
+     * @returns AggregatedScore with score based on majority outcome
+     * @throws NegotiationValidationError if votes list is empty
+     */
+    aggregate(votes: NegotiationVote[]): AggregatedScore;
+}
+/**
+ * Borda count aggregation strategy.
+ *
+ * Implements ranked voting where each vote receives points based on its
+ * rank position. Higher scored votes receive more points.
+ *
+ * Ranking system:
+ * - Votes are sorted by score (highest to lowest)
+ * - Highest score receives n points (where n = number of votes)
+ * - Second highest receives n-1 points
+ * - Lowest score receives 1 point
+ * - Points are summed and normalized to 0-10 scale
+ *
+ * This method is resistant to strategic voting and reduces impact of outliers.
+ */
+export declare class BordaCountAggregator implements VotingAggregator {
+    /**
+     * Aggregate votes using Borda count.
+     *
+     * @param votes - List of critic votes to aggregate
+     * @returns AggregatedScore with Borda count normalized score
+     * @throws NegotiationValidationError if votes list is empty
+     */
+    aggregate(votes: NegotiationVote[]): AggregatedScore;
+}
+/**
+ * Main aggregator class with consensus and polarization detection.
+ *
+ * Wraps a VotingAggregator strategy and provides additional methods for
+ * analyzing vote distributions, detecting consensus, and identifying
+ * polarization.
+ */
+export declare class VotingAnalyzer {
+    private strategy;
+    /**
+     * Initialize analyzer with a strategy.
+     *
+     * @param strategy - The aggregation strategy to use
+     */
+    constructor(strategy: VotingAggregator);
+    /**
+     * Aggregate votes using the configured strategy.
+     *
+     * @param votes - List of critic votes to aggregate
+     * @returns AggregatedScore with aggregation results
+     * @throws NegotiationValidationError if votes list is empty
+     */
+    aggregate(votes: NegotiationVote[]): AggregatedScore;
+    /**
+     * Compute Shannon entropy of vote distribution.
+     *
+     * Entropy measures the uncertainty or disorder in the vote distribution.
+     * Higher entropy indicates more disagreement/uncertainty, lower entropy
+     * indicates more consensus.
+     *
+     * The score range [0, 10] is divided into bins, and entropy is computed
+     * over the probability distribution of votes across bins.
+     *
+     * @param votes - List of critic votes
+     * @returns Entropy value in bits (0 = perfect consensus, higher = more uncertainty)
+     * @throws NegotiationValidationError if votes list is empty
+     */
+    computeEntropy(votes: NegotiationVote[]): number;
+    /**
+     * Detect if votes show strong consensus.
+     *
+     * Consensus is detected when:
+     * 1. Standard deviation of scores is low (< 2.0)
+     * 2. A large proportion of critics agree on pass/fail (>= threshold)
+     *
+     * @param votes - List of critic votes
+     * @param threshold - Minimum proportion of agreement required (default 0.8 = 80%)
+     * @returns True if consensus is detected, false otherwise
+     * @throws NegotiationValidationError if votes list is empty or threshold not in [0, 1]
+     */
+    detectConsensus(votes: NegotiationVote[], threshold?: number): boolean;
+    /**
+     * Detect if votes show polarization (bimodal distribution).
+     *
+     * Polarization is detected when votes cluster into two distinct groups,
+     * typically at opposite ends of the score spectrum. This is identified by:
+     * 1. High standard deviation (>= 3.0)
+     * 2. Low density in the middle range (4-6)
+     * 3. High density in the extremes (0-3 or 7-10)
+     *
+     * @param votes - List of critic votes
+     * @returns True if polarization is detected, false otherwise
+     * @throws NegotiationValidationError if votes list is empty
+     */
+    detectPolarization(votes: NegotiationVote[]): boolean;
+    /**
+     * Compute variance of confidence levels across votes.
+     *
+     * High variance in confidence suggests critics have different levels of
+     * certainty about their evaluations, which may indicate the artifact is
+     * harder to assess or has ambiguous quality.
+     *
+     * @param votes - List of critic votes
+     * @returns Variance of confidence values
+     * @throws NegotiationValidationError if votes list is empty
+     */
+    computeConfidenceVariance(votes: NegotiationVote[]): number;
+    /**
+     * Get comprehensive summary of vote characteristics.
+     *
+     * Combines multiple analytical methods to provide a complete picture
+     * of the vote distribution and critic agreement.
+     *
+     * @param votes - List of critic votes
+     * @returns Object with summary statistics
+     * @throws NegotiationValidationError if votes list is empty
+     */
+    getVoteSummary(votes: NegotiationVote[]): {
+        entropy: number;
+        consensus: boolean;
+        polarization: boolean;
+        confidenceVariance: number;
+        passRate: number;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sw4rm/js-sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "SW4RM Agentic Protocol JavaScript/TypeScript SDK",
   "type": "module",
   "main": "./dist/cjs/index.cjs",
@@ -14,7 +14,8 @@
     }
   },
   "scripts": {
-    "build": "npm run build:proto && npm run build:lib",
+    "build": "npm run build:proto && npm run build:lib && npm run copy:protos",
+    "copy:protos": "rm -rf protos && cp -r ../../protos protos",
     "example": "tsx",
     "build:proto": "npm run proto:js && npm run proto:ts",
     "build:lib": "npm run build:esm && npm run build:cjs && npm run build:types",
@@ -30,6 +31,7 @@
   },
   "files": [
     "dist",
+    "protos",
     "README.md",
     "LICENSE"
   ],

package/protos/activity.proto

@@ -0,0 +1,24 @@
+syntax = "proto3";
+
+package sw4rm.activity;
+
+message Artifact {
+  string negotiation_id = 1;
+  string kind = 2;       // contract|diff|decision|score|note
+  string version = 3;    // e.g., v3
+  string content_type = 4;
+  bytes content = 5;
+  string created_at = 6; // ISO-8601
+}
+
+message AppendArtifactRequest { Artifact artifact = 1; }
+message AppendArtifactResponse { bool ok = 1; string reason = 2; }
+
+message ListArtifactsRequest { string negotiation_id = 1; string kind = 2; }
+message ListArtifactsResponse { repeated Artifact items = 1; }
+
+service ActivityService {
+  rpc AppendArtifact(AppendArtifactRequest) returns (AppendArtifactResponse);
+  rpc ListArtifacts(ListArtifactsRequest) returns (ListArtifactsResponse);
+}
+