maskweaver 0.9.4 → 0.9.6

package/dist/shared-context/types.d.ts

@@ -1,40 +1,13 @@
-/**
- * Shared Context Type Definitions
- *
- * Core types for multi-agent collaboration system.
- * "State. You're doing it wrong." - Rich Hickey
- *
- * Design principles:
- * - Data is immutable and validatable
- * - Validate at boundaries, trust internally
- * - Parse, don't validate
- *
- * @author Kent Beck's Dummy Human
- */
 import { z } from "zod";
-/** Lifecycle status for squads and tasks */
 export type Status = "pending" | "active" | "paused" | "completed" | "failed";
-/** Task priority levels */
 export type Priority = "low" | "medium" | "high" | "critical";
-/** Unique identifier for an agent */
 export type AgentId = string;
-/** UUID for correlation across events */
 export type CorrelationId = string;
-/**
- * Generic result type for operations that may fail.
- * Use this pattern instead of throwing for expected failures.
- *
- * @template T - The type of data on success
- */
 export interface Result<T> {
-    /** Whether the operation succeeded */
     success: boolean;
-    /** The result data (only present on success) */
     data?: T;
-    /** Error message (only present on failure) */
     error?: string;
 }
-/** Status enum schema */
 export declare const StatusSchema: z.ZodEnum<{
     active: "active";
     paused: "paused";
@@ -42,43 +15,26 @@ export declare const StatusSchema: z.ZodEnum<{
     pending: "pending";
     failed: "failed";
 }>;
-/** Priority enum schema */
 export declare const PrioritySchema: z.ZodEnum<{
     low: "low";
     medium: "medium";
     high: "high";
     critical: "critical";
 }>;
-/** Agent ID schema (non-empty string) */
 export declare const AgentIdSchema: z.ZodString;
-/** Correlation ID schema (UUID format) */
 export declare const CorrelationIdSchema: z.ZodString;
-/**
- * Session manifest containing metadata and squad references.
- * This is the root document for a collaboration session.
- */
 export interface Manifest {
-    /** UUID of the session */
     sessionId: string;
-    /** Schema version for migration support */
     version: number;
-    /** High-level goal for the session */
     goal: string;
-    /** ISO timestamp of creation */
     createdAt: string;
-    /** Agent ID of the session creator */
     createdBy: AgentId;
-    /** List of squad IDs in this session */
     squads: string[];
-    /** Optional resource constraints */
     constraints?: {
-        /** Maximum duration (e.g., "1h", "30m") */
         timeout?: string;
-        /** Maximum token budget */
         tokenBudget?: number;
     };
 }
-/** Manifest schema for runtime validation */
 export declare const ManifestSchema: z.ZodObject<{
     sessionId: z.ZodString;
     version: z.ZodNumber;
@@ -91,37 +47,21 @@ export declare const ManifestSchema: z.ZodObject<{
         tokenBudget: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-/**
- * Squad specification defining mission, constraints, and scope.
- * Immutable after creation - use SquadState for mutable data.
- */
 export interface SquadSpec {
-    /** Unique squad identifier (e.g., "squad-a1b2c3d4") */
     squadId: string;
-    /** The squad's mission objective */
     mission: string;
-    /** Agent ID of the squad operator */
     operator: AgentId;
-    /** Resource constraints for the squad */
     constraints?: {
-        /** Maximum duration */
         timeout?: string;
-        /** Maximum token budget */
         tokenBudget?: number;
-        /** Maximum number of worker agents */
         maxWorkers?: number;
     };
-    /** File and directory scope for the squad */
     scope?: {
-        /** Files the squad can modify */
         files?: string[];
-        /** Directories the squad can access */
         directories?: string[];
     };
-    /** ISO timestamp of creation */
     createdAt: string;
 }
-/** SquadSpec schema for runtime validation */
 export declare const SquadSpecSchema: z.ZodObject<{
     squadId: z.ZodString;
     mission: z.ZodString;
@@ -137,32 +77,18 @@ export declare const SquadSpecSchema: z.ZodObject<{
     }, z.core.$strip>>;
     createdAt: z.ZodString;
 }, z.core.$strip>;
-/**
- * Individual task state within a squad.
- */
 export interface TaskState {
-    /** Unique task identifier */
     taskId: string;
-    /** Agent assigned to this task */
     assignee: AgentId;
-    /** Current task status */
     status: Status;
-    /** Task priority */
     priority: Priority;
-    /** Human-readable task description */
     description: string;
-    /** IDs of tasks this depends on */
     dependencies?: string[];
-    /** ISO timestamp of creation */
     createdAt: string;
-    /** ISO timestamp when work started */
     startedAt?: string;
-    /** ISO timestamp when completed */
     completedAt?: string;
-    /** Task result data */
     result?: unknown;
 }
-/** TaskState schema for runtime validation */
 export declare const TaskStateSchema: z.ZodObject<{
     taskId: z.ZodString;
     assignee: z.ZodString;
@@ -186,23 +112,13 @@ export declare const TaskStateSchema: z.ZodObject<{
     completedAt: z.ZodOptional<z.ZodString>;
     result: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strip>;
-/**
- * Options for creating a new task.
- * "Make implicit concepts explicit" - Eric Evans
- */
 export interface CreateTaskOptions {
-    /** Agent responsible for executing this task */
     assignee: AgentId;
-    /** Human-readable description of what needs to be done */
     description: string;
-    /** Task priority (defaults to 'medium' if not specified) */
     priority?: Priority;
-    /** Task IDs that must complete before this task can start */
     dependencies?: string[];
-    /** Maximum time allowed for task execution in milliseconds */
     timeout?: number;
 }
-/** CreateTaskOptions schema for runtime validation */
 export declare const CreateTaskOptionsSchema: z.ZodObject<{
     assignee: z.ZodString;
     description: z.ZodString;
@@ -215,42 +131,28 @@ export declare const CreateTaskOptionsSchema: z.ZodObject<{
     dependencies: z.ZodOptional<z.ZodArray<z.ZodString>>;
     timeout: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
-/** Structured error information for failed tasks */
 export interface TaskError {
-    /** Machine-readable error code (e.g., "TIMEOUT", "DEPENDENCY_FAILED") */
     code: string;
-    /** Human-readable error description */
     message: string;
 }
-/** TaskError schema */
 export declare const TaskErrorSchema: z.ZodObject<{
     code: z.ZodString;
     message: z.ZodString;
 }, z.core.$strip>;
-/** Execution metrics captured during task processing */
 export interface TaskMetrics {
-    /** Task execution duration in milliseconds */
     duration: number;
-    /** Number of tokens consumed (if applicable) */
     tokensUsed?: number;
 }
-/** TaskMetrics schema */
 export declare const TaskMetricsSchema: z.ZodObject<{
     duration: z.ZodNumber;
     tokensUsed: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
-/** The outcome of a completed task */
 export interface TaskResult {
-    /** Whether the task completed successfully */
     success: boolean;
-    /** Task output data (present on success) */
     output?: unknown;
-    /** Structured error information (present on failure) */
     error?: TaskError;
-    /** Execution metrics for observability */
     metrics?: TaskMetrics;
 }
-/** TaskResult schema for runtime validation */
 export declare const TaskResultSchema: z.ZodObject<{
     success: z.ZodBoolean;
     output: z.ZodOptional<z.ZodUnknown>;
@@ -263,24 +165,17 @@ export declare const TaskResultSchema: z.ZodObject<{
         tokensUsed: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-/** Actions to take when a timeout occurs */
 export type TimeoutAction = "fail" | "pause" | "notify";
-/** Timeout action schema */
 export declare const TimeoutActionSchema: z.ZodEnum<{
     fail: "fail";
     pause: "pause";
     notify: "notify";
 }>;
-/** Custom timeout configuration for squads and tasks */
 export interface TimeoutConfig {
-    /** Custom timeout in milliseconds (overrides LIMITS.watchdogTimeoutMs) */
     timeoutMs?: number;
-    /** Grace period before hard kill */
     gracePeriodMs?: number;
-    /** Action to take on timeout: fail (default), pause for retry, or notify only */
     onTimeout?: TimeoutAction;
 }
-/** TimeoutConfig schema for runtime validation */
 export declare const TimeoutConfigSchema: z.ZodObject<{
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     gracePeriodMs: z.ZodOptional<z.ZodNumber>;
@@ -290,43 +185,26 @@ export declare const TimeoutConfigSchema: z.ZodObject<{
         notify: "notify";
     }>>;
 }, z.core.$strip>;
-/** Real-time timeout status from watchdog health check */
 export interface TimeoutStatus {
-    /** Whether the timeout has expired */
     isExpired: boolean;
-    /** Milliseconds elapsed since start or last activity */
     elapsedMs: number;
-    /** Milliseconds remaining before timeout (negative if expired) */
     remainingMs: number;
-    /** ISO timestamp of last recorded activity */
     lastActivityAt: string;
 }
-/** TimeoutStatus schema for runtime validation */
 export declare const TimeoutStatusSchema: z.ZodObject<{
     isExpired: z.ZodBoolean;
     elapsedMs: z.ZodNumber;
     remainingMs: z.ZodNumber;
     lastActivityAt: z.ZodString;
 }, z.core.$strip>;
-/**
- * Mutable squad state including status, progress, and tasks.
- * Updated frequently as work progresses.
- */
 export interface SquadState {
-    /** Squad ID (matches SquadSpec.squadId) */
     squadId: string;
-    /** Current squad status */
     status: Status;
-    /** Progress percentage (0-100) */
     progress: number;
-    /** List of tasks in this squad */
     tasks: TaskState[];
-    /** Shared context data between workers */
     sharedContext: Record<string, unknown>;
-    /** ISO timestamp of last update */
     updatedAt: string;
 }
-/** SquadState schema for runtime validation */
 export declare const SquadStateSchema: z.ZodObject<{
     squadId: z.ZodString;
     status: z.ZodEnum<{
@@ -369,10 +247,6 @@ export interface Session {
     sessionPath: string;
 }
 import { StorageAdapter } from "./storage.js";
-/**
- * Discriminated union of all possible log event types.
- * Each event has a `type` field for discrimination and `ts` for timestamp.
- */
 export type LogEvent = {
     type: "squad_started";
     ts: string;
@@ -406,10 +280,6 @@ export type LogEvent = {
     message: string;
     source?: AgentId;
 };
-/**
- * Log event input type (without timestamp).
- * Used for logEvent() function - timestamp is added automatically.
- */
 export type LogEventInput = {
     type: "squad_started";
     squadId: string;
@@ -437,7 +307,6 @@ export type LogEventInput = {
     message: string;
     source?: AgentId;
 };
-/** LogEvent schema for runtime validation (discriminated union) */
 export declare const LogEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"squad_started">;
     ts: z.ZodString;
@@ -477,112 +346,28 @@ export declare const LogEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     message: z.ZodString;
     source: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>], "type">;
-/**
- * System limits to prevent resource exhaustion.
- * These values are enforced at runtime.
- *
- * Watchdog timeouts follow the principle:
- * "If you can't measure it, you can't improve it." - Brendan Gregg
- */
 export declare const LIMITS: {
-    /** Maximum number of squads per session */
     readonly maxSquadsPerSession: 10;
-    /** Maximum number of worker agents per squad */
     readonly maxWorkersPerSquad: 5;
-    /** Maximum number of tasks per squad */
     readonly maxTasksPerSquad: 50;
-    /** Maximum size of shared context data (1MB) */
     readonly maxSharedContextSize: number;
-    /** Maximum size of log file (10MB) */
     readonly maxLogSize: number;
-    /** Lock acquisition timeout in milliseconds */
     readonly lockTimeout: 5000;
-    /** Time after which a lock is considered stale (ms) */
     readonly lockStale: 30000;
-    /** Number of retry attempts for lock acquisition */
     readonly lockRetries: 3;
-    /** Default watchdog timeout (5 minutes) - kills stuck agents */
     readonly watchdogTimeoutMs: number;
-    /** Watchdog health check interval (30 seconds) */
     readonly watchdogCheckIntervalMs: number;
-    /** Grace period before hard timeout (10 seconds) - allows cleanup */
     readonly watchdogGracePeriodMs: number;
 };
-/**
- * Validate manifest data at system boundaries.
- * Parse once at the edge, trust internally.
- *
- * @param data - Unknown data from external source
- * @returns Validated Manifest
- * @throws {z.ZodError} If validation fails
- */
 export declare function validateManifest(data: unknown): Manifest;
-/**
- * Validate squad spec data.
- *
- * @param data - Unknown data from external source
- * @returns Validated SquadSpec
- * @throws {z.ZodError} If validation fails
- */
 export declare function validateSquadSpec(data: unknown): SquadSpec;
-/**
- * Validate squad state data.
- *
- * @param data - Unknown data from external source
- * @returns Validated SquadState
- * @throws {z.ZodError} If validation fails
- */
 export declare function validateSquadState(data: unknown): SquadState;
-/**
- * Validate task state data.
- *
- * @param data - Unknown data from external source
- * @returns Validated TaskState
- * @throws {z.ZodError} If validation fails
- */
 export declare function validateTaskState(data: unknown): TaskState;
-/**
- * Validate log event data.
- *
- * @param data - Unknown data from external source
- * @returns Validated LogEvent
- * @throws {z.ZodError} If validation fails
- */
 export declare function validateLogEvent(data: unknown): LogEvent;
-/**
- * Validate task creation options.
- */
 export declare function validateCreateTaskOptions(data: unknown): CreateTaskOptions;
-/**
- * Validate task result data.
- */
 export declare function validateTaskResult(data: unknown): TaskResult;
-/**
- * Validate timeout config data.
- */
 export declare function validateTimeoutConfig(data: unknown): TimeoutConfig;
-/**
- * Validate timeout status data.
- */
 export declare function validateTimeoutStatus(data: unknown): TimeoutStatus;
-/**
- * Safely validate manifest data without throwing.
- *
- * @param data - Unknown data from external source
- * @returns Result with validated data or error message
- */
 export declare function safeValidateManifest(data: unknown): Result<Manifest>;
-/**
- * Safely validate squad spec data without throwing.
- *
- * @param data - Unknown data from external source
- * @returns Result with validated data or error message
- */
 export declare function safeValidateSquadSpec(data: unknown): Result<SquadSpec>;
-/**
- * Safely validate squad state data without throwing.
- *
- * @param data - Unknown data from external source
- * @returns Result with validated data or error message
- */
 export declare function safeValidateSquadState(data: unknown): Result<SquadState>;

package/dist/shared-context/types.js

@@ -1,29 +1,8 @@
-/**
- * Shared Context Type Definitions
- *
- * Core types for multi-agent collaboration system.
- * "State. You're doing it wrong." - Rich Hickey
- *
- * Design principles:
- * - Data is immutable and validatable
- * - Validate at boundaries, trust internally
- * - Parse, don't validate
- *
- * @author Kent Beck's Dummy Human
- */
 import { z } from "zod";
-// ============================================================================
-// Zod Schemas - Validate at boundaries, trust internally
-// ============================================================================
-/** Status enum schema */
 export const StatusSchema = z.enum(["pending", "active", "paused", "completed", "failed"]);
-/** Priority enum schema */
 export const PrioritySchema = z.enum(["low", "medium", "high", "critical"]);
-/** Agent ID schema (non-empty string) */
 export const AgentIdSchema = z.string().min(1);
-/** Correlation ID schema (UUID format) */
 export const CorrelationIdSchema = z.string().uuid();
-/** Manifest schema for runtime validation */
 export const ManifestSchema = z.object({
     sessionId: z.string().uuid(),
     version: z.number().int().positive(),
@@ -36,7 +15,6 @@ export const ManifestSchema = z.object({
         tokenBudget: z.number().optional(),
     }).optional(),
 });
-/** SquadSpec schema for runtime validation */
 export const SquadSpecSchema = z.object({
     squadId: z.string().min(1),
     mission: z.string().min(1),
@@ -52,7 +30,6 @@ export const SquadSpecSchema = z.object({
     }).optional(),
     createdAt: z.string().datetime(),
 });
-/** TaskState schema for runtime validation */
 export const TaskStateSchema = z.object({
     taskId: z.string().min(1),
     assignee: AgentIdSchema,
@@ -65,7 +42,6 @@ export const TaskStateSchema = z.object({
     completedAt: z.string().datetime().optional(),
     result: z.unknown().optional(),
 });
-/** CreateTaskOptions schema for runtime validation */
 export const CreateTaskOptionsSchema = z.object({
     assignee: AgentIdSchema,
     description: z.string().min(1, "Description cannot be empty"),
@@ -73,17 +49,14 @@ export const CreateTaskOptionsSchema = z.object({
     dependencies: z.array(z.string().min(1)).optional(),
     timeout: z.number().int().positive().optional(),
 });
-/** TaskError schema */
 export const TaskErrorSchema = z.object({
     code: z.string().min(1),
     message: z.string().min(1),
 });
-/** TaskMetrics schema */
 export const TaskMetricsSchema = z.object({
     duration: z.number().int().nonnegative(),
     tokensUsed: z.number().int().nonnegative().optional(),
 });
-/** TaskResult schema for runtime validation */
 export const TaskResultSchema = z.object({
     success: z.boolean(),
     output: z.unknown().optional(),
@@ -96,22 +69,18 @@ export const TaskResultSchema = z.object({
         return false;
     return true;
 }, { message: "Failed tasks must have error, successful tasks must not have error" });
-/** Timeout action schema */
 export const TimeoutActionSchema = z.enum(["fail", "pause", "notify"]);
-/** TimeoutConfig schema for runtime validation */
 export const TimeoutConfigSchema = z.object({
     timeoutMs: z.number().int().positive().optional(),
     gracePeriodMs: z.number().int().positive().optional(),
     onTimeout: TimeoutActionSchema.optional(),
 });
-/** TimeoutStatus schema for runtime validation */
 export const TimeoutStatusSchema = z.object({
     isExpired: z.boolean(),
     elapsedMs: z.number().int().nonnegative(),
     remainingMs: z.number().int(),
     lastActivityAt: z.string().datetime(),
 });
-/** SquadState schema for runtime validation */
 export const SquadStateSchema = z.object({
     squadId: z.string().min(1),
     status: StatusSchema,
@@ -120,7 +89,6 @@ export const SquadStateSchema = z.object({
     sharedContext: z.record(z.string(), z.unknown()),
     updatedAt: z.string().datetime(),
 });
-/** LogEvent schema for runtime validation (discriminated union) */
 export const LogEventSchema = z.discriminatedUnion("type", [
     z.object({
         type: z.literal("squad_started"),
@@ -161,127 +129,46 @@ export const LogEventSchema = z.discriminatedUnion("type", [
         source: AgentIdSchema.optional(),
     }),
 ]);
-// ============================================================================
-// Limits and Constants
-// ============================================================================
-/**
- * System limits to prevent resource exhaustion.
- * These values are enforced at runtime.
- *
- * Watchdog timeouts follow the principle:
- * "If you can't measure it, you can't improve it." - Brendan Gregg
- */
 export const LIMITS = {
-    /** Maximum number of squads per session */
     maxSquadsPerSession: 10,
-    /** Maximum number of worker agents per squad */
     maxWorkersPerSquad: 5,
-    /** Maximum number of tasks per squad */
     maxTasksPerSquad: 50,
-    /** Maximum size of shared context data (1MB) */
     maxSharedContextSize: 1024 * 1024,
-    /** Maximum size of log file (10MB) */
     maxLogSize: 10 * 1024 * 1024,
-    /** Lock acquisition timeout in milliseconds */
     lockTimeout: 5000,
-    /** Time after which a lock is considered stale (ms) */
     lockStale: 30000,
-    /** Number of retry attempts for lock acquisition */
     lockRetries: 3,
-    /** Default watchdog timeout (5 minutes) - kills stuck agents */
     watchdogTimeoutMs: 5 * 60 * 1000,
-    /** Watchdog health check interval (30 seconds) */
     watchdogCheckIntervalMs: 30 * 1000,
-    /** Grace period before hard timeout (10 seconds) - allows cleanup */
     watchdogGracePeriodMs: 10 * 1000,
 };
-// ============================================================================
-// Validation Functions - Parse, don't validate
-// ============================================================================
-/**
- * Validate manifest data at system boundaries.
- * Parse once at the edge, trust internally.
- *
- * @param data - Unknown data from external source
- * @returns Validated Manifest
- * @throws {z.ZodError} If validation fails
- */
 export function validateManifest(data) {
     return ManifestSchema.parse(data);
 }
-/**
- * Validate squad spec data.
- *
- * @param data - Unknown data from external source
- * @returns Validated SquadSpec
- * @throws {z.ZodError} If validation fails
- */
 export function validateSquadSpec(data) {
     return SquadSpecSchema.parse(data);
 }
-/**
- * Validate squad state data.
- *
- * @param data - Unknown data from external source
- * @returns Validated SquadState
- * @throws {z.ZodError} If validation fails
- */
 export function validateSquadState(data) {
     return SquadStateSchema.parse(data);
 }
-/**
- * Validate task state data.
- *
- * @param data - Unknown data from external source
- * @returns Validated TaskState
- * @throws {z.ZodError} If validation fails
- */
 export function validateTaskState(data) {
     return TaskStateSchema.parse(data);
 }
-/**
- * Validate log event data.
- *
- * @param data - Unknown data from external source
- * @returns Validated LogEvent
- * @throws {z.ZodError} If validation fails
- */
 export function validateLogEvent(data) {
     return LogEventSchema.parse(data);
 }
-/**
- * Validate task creation options.
- */
 export function validateCreateTaskOptions(data) {
     return CreateTaskOptionsSchema.parse(data);
 }
-/**
- * Validate task result data.
- */
 export function validateTaskResult(data) {
     return TaskResultSchema.parse(data);
 }
-/**
- * Validate timeout config data.
- */
 export function validateTimeoutConfig(data) {
     return TimeoutConfigSchema.parse(data);
 }
-/**
- * Validate timeout status data.
- */
 export function validateTimeoutStatus(data) {
     return TimeoutStatusSchema.parse(data);
 }
-// ============================================================================
-// Safe Validation - Result pattern (doesn't throw)
-// ============================================================================
-/**
- * Safely validate manifest data without throwing.
- *
- * @param data - Unknown data from external source
- * @returns Result with validated data or error message
- */
 export function safeValidateManifest(data) {
     const result = ManifestSchema.safeParse(data);
     if (result.success) {
@@ -289,12 +176,6 @@ export function safeValidateManifest(data) {
     }
     return { success: false, error: result.error.message };
 }
-/**
- * Safely validate squad spec data without throwing.
- *
- * @param data - Unknown data from external source
- * @returns Result with validated data or error message
- */
 export function safeValidateSquadSpec(data) {
     const result = SquadSpecSchema.safeParse(data);
     if (result.success) {
@@ -302,12 +183,6 @@ export function safeValidateSquadSpec(data) {
     }
     return { success: false, error: result.error.message };
 }
-/**
- * Safely validate squad state data without throwing.
- *
- * @param data - Unknown data from external source
- * @returns Result with validated data or error message
- */
 export function safeValidateSquadState(data) {
     const result = SquadStateSchema.safeParse(data);
     if (result.success) {