@sw4rm/js-sdk 0.3.0 → 0.5.0

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

@@ -1,14 +1,74 @@
 export type WorktreeState = 'UNBOUND' | 'BOUND_HOME' | 'SWITCH_PENDING' | 'BOUND_NON_HOME' | 'BIND_FAILED';
+/**
+ * Check if a worktree state transition is valid.
+ */
+export declare function isValidWorktreeTransition(from: WorktreeState, to: WorktreeState): boolean;
+export declare class WorktreeTransitionError extends Error {
+    readonly fromState: WorktreeState;
+    readonly toState: WorktreeState;
+    constructor(from: WorktreeState, to: WorktreeState);
+}
+/**
+ * Persistent worktree state machine with full spec §16 support.
+ *
+ * Supports SWITCH_PENDING approval flow with TTL on BOUND_NON_HOME.
+ */
 export declare class PersistentWorktreeState {
     private state;
     private repoId?;
     private worktreeId?;
+    private homeRepoId?;
+    private homeWorktreeId?;
+    private switchTtlMs?;
+    private switchTimer?;
+    /**
+     * Transition to a new state with validation.
+     * @throws WorktreeTransitionError if transition is invalid
+     */
+    private transitionTo;
+    /**
+     * Bind to a home worktree (UNBOUND -> BOUND_HOME or BIND_FAILED -> BOUND_HOME).
+     */
     bind(repoId: string, worktreeId: string): void;
+    /**
+     * Handle bind failure (UNBOUND -> BIND_FAILED).
+     */
+    bindFailed(): void;
+    /**
+     * Unbind from current worktree.
+     */
     unbind(): void;
+    /**
+     * Request switch to a non-home worktree (BOUND_HOME -> SWITCH_PENDING).
+     * Requires approval or rejection before taking effect.
+     */
+    requestSwitch(targetRepoId: string, targetWorktreeId: string): void;
+    /**
+     * Approve a pending switch (SWITCH_PENDING -> BOUND_NON_HOME).
+     * @param ttlMs - Time-to-live in milliseconds before auto-reverting to BOUND_HOME
+     */
+    approveSwitch(ttlMs?: number): void;
+    /**
+     * Reject a pending switch (SWITCH_PENDING -> BOUND_HOME).
+     */
+    rejectSwitch(): void;
+    /**
+     * Revert from non-home to home worktree (BOUND_NON_HOME -> BOUND_HOME).
+     * Called on TTL expiry or explicit revoke.
+     */
+    revertToHome(): void;
+    /**
+     * Reset from BIND_FAILED to UNBOUND for retry.
+     */
+    resetFromFailed(): void;
+    private clearSwitchTimer;
     setState(state: WorktreeState): void;
     current(): {
         state: WorktreeState;
         repo_id: string | undefined;
         worktree_id: string | undefined;
+        home_repo_id: string | undefined;
+        home_worktree_id: string | undefined;
+        switch_ttl_ms: number | undefined;
     };
 }

package/dist/types/persistentActivityBuffer.d.ts

@@ -0,0 +1,94 @@
+import { EnvelopeState } from './constants/index.js';
+export interface EnvelopeRecord {
+    message_id: string;
+    direction: 'in' | 'out';
+    envelope: Record<string, unknown>;
+    ts_ms: number;
+    ack_stage: number;
+    error_code: number;
+    ack_note: string;
+}
+export interface PersistenceBackend {
+    load(): {
+        records: Record<string, EnvelopeRecord>;
+        order: string[];
+    };
+    save(records: Record<string, EnvelopeRecord>, order: string[]): void;
+    clear(): void;
+}
+/**
+ * JSON file persistence backend.
+ */
+export declare class JSONFilePersistence implements PersistenceBackend {
+    private filePath;
+    constructor(filePath?: string);
+    load(): {
+        records: Record<string, EnvelopeRecord>;
+        order: string[];
+    };
+    save(records: Record<string, EnvelopeRecord>, order: string[]): void;
+    clear(): void;
+}
+/**
+ * Persistent Activity Buffer with Three-ID model support.
+ *
+ * Tracks inbound/outbound envelopes by message_id and records ACK progression.
+ * Supports multiple persistence backends (JSON file, etc.) and provides
+ * reconciliation on startup to restore previous state.
+ *
+ * When the buffer is full, new records are REJECTED with BufferFullError
+ * per spec compliance (not silently pruned).
+ */
+export declare class PersistentActivityBuffer {
+    private byId;
+    private byIdempotencyToken;
+    private order;
+    private maxItems;
+    private persistence;
+    private dedupWindowS;
+    private dirty;
+    constructor(opts?: {
+        maxItems?: number;
+        persistence?: PersistenceBackend;
+        dedupWindowS?: number;
+    });
+    private loadFromPersistence;
+    private saveToPersistence;
+    private checkCapacity;
+    private cleanupExpiredDedupEntries;
+    /**
+     * Record an incoming envelope. Throws BufferFullError if buffer is at capacity.
+     */
+    recordIncoming(envelope: Record<string, unknown>): EnvelopeRecord;
+    /**
+     * Record an outgoing envelope. Throws BufferFullError if buffer is at capacity.
+     */
+    recordOutgoing(envelope: Record<string, unknown>): EnvelopeRecord;
+    /**
+     * Process an ACK for a previously recorded message.
+     */
+    ack(ackMsg: {
+        ack_for_message_id: string;
+        ack_stage?: number;
+        error_code?: number;
+        note?: string;
+    }): EnvelopeRecord | undefined;
+    /** Get record by message ID. */
+    get(messageId: string): EnvelopeRecord | undefined;
+    /** Get record by idempotency token (for deduplication). */
+    getByIdempotencyToken(token: string): EnvelopeRecord | undefined;
+    /** Get all un-ACKed records. */
+    unacked(): EnvelopeRecord[];
+    /** Get N most recent records. */
+    recent(n?: number): EnvelopeRecord[];
+    /** Update envelope state for a message. */
+    updateState(messageId: string, newState: EnvelopeState): EnvelopeRecord | undefined;
+    /** Return unacked outgoing messages for reconciliation. */
+    reconcile(): EnvelopeRecord[];
+    /** Force save to persistence. */
+    flush(): void;
+    /** Clear all records. */
+    clear(): void;
+    /** Get the count of records. */
+    get size(): number;
+}

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;
+}