universal-agent-memory 0.6.1 → 0.6.3

package/dist/utils/rate-limiter.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Configuration options for the RateLimiter.
+ */
+export interface RateLimiterConfig {
+    maxRequests: number;
+    windowMs: number;
+}
+export declare class RateLimiter {
+    private static readonly configSchema;
+    private static readonly clientIdSchema;
+    private readonly maxRequests;
+    private readonly windowMs;
+    private readonly requests;
+    /**
+     * Creates a new RateLimiter instance.
+     *
+     * @param config - Configuration for request limits and window size
+     * @returns A configured RateLimiter instance
+     * @throws AppError when config is invalid
+     */
+    constructor(config: RateLimiterConfig);
+    /**
+     * Checks if a request from the given client is allowed and records it if so.
+     *
+     * @param clientId - Identifier for the calling client
+     * @returns True if the request is allowed; otherwise false
+     * @throws AppError when clientId is invalid
+     */
+    isAllowed(clientId: string): boolean;
+    /**
+     * Returns the remaining number of requests for a client in the current window.
+     *
+     * @param clientId - Identifier for the calling client
+     * @returns Remaining number of requests in the window
+     * @throws AppError when clientId is invalid
+     */
+    getRemainingRequests(clientId: string): number;
+    /**
+     * Resets rate limiting for a single client or all clients.
+     *
+     * @param clientId - Optional client identifier to reset; omit to reset all
+     * @returns Nothing
+     */
+    reset(clientId?: string): void;
+    /**
+     * Removes expired timestamps and deletes empty client entries.
+     *
+     * @param now - Current timestamp used as reference
+     * @param clientId - Optional client identifier to scope cleanup
+     * @returns Nothing
+     */
+    private cleanupExpiredEntries;
+    /**
+     * Ensures the client identifier is valid.
+     *
+     * @param clientId - Identifier to validate
+     * @returns Nothing
+     * @throws AppError when clientId is invalid
+     */
+    private ensureValidClientId;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/utils/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/utils/rate-limiter.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AASD,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAejC;IAEH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAKE;IAExC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAE7D;;;;;;OAMG;gBACS,MAAM,EAAE,iBAAiB;IAcrC;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAgBpC;;;;;;OAMG;IACH,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAc9C;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAU9B;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IAoC7B;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;CAU5B"}

package/dist/utils/rate-limiter.js

@@ -0,0 +1,150 @@
+/**
+ * A sliding-window rate limiter that tracks requests per client.
+ */
+import { z } from 'zod';
+import { AppError } from './validate-json.js';
+export class RateLimiter {
+    static configSchema = z.object({
+        maxRequests: z
+            .number({
+            required_error: 'maxRequests is required',
+            invalid_type_error: 'maxRequests must be a number',
+        })
+            .int('maxRequests must be an integer')
+            .positive('maxRequests must be greater than 0'),
+        windowMs: z
+            .number({
+            required_error: 'windowMs is required',
+            invalid_type_error: 'windowMs must be a number',
+        })
+            .int('windowMs must be an integer')
+            .positive('windowMs must be greater than 0'),
+    });
+    static clientIdSchema = z
+        .string({
+        required_error: 'clientId is required',
+        invalid_type_error: 'clientId must be a string',
+    })
+        .min(1, 'clientId must not be empty');
+    maxRequests;
+    windowMs;
+    requests = new Map();
+    /**
+     * Creates a new RateLimiter instance.
+     *
+     * @param config - Configuration for request limits and window size
+     * @returns A configured RateLimiter instance
+     * @throws AppError when config is invalid
+     */
+    constructor(config) {
+        const validation = RateLimiter.configSchema.safeParse(config);
+        if (!validation.success) {
+            throw new AppError('Invalid rate limiter configuration', 'INVALID_CONFIG', {
+                errors: validation.error.errors,
+                received: config,
+            });
+        }
+        this.maxRequests = validation.data.maxRequests;
+        this.windowMs = validation.data.windowMs;
+    }
+    /**
+     * Checks if a request from the given client is allowed and records it if so.
+     *
+     * @param clientId - Identifier for the calling client
+     * @returns True if the request is allowed; otherwise false
+     * @throws AppError when clientId is invalid
+     */
+    isAllowed(clientId) {
+        this.ensureValidClientId(clientId);
+        const now = Date.now();
+        this.cleanupExpiredEntries(now, clientId);
+        const timestamps = this.requests.get(clientId) ?? [];
+        if (timestamps.length < this.maxRequests) {
+            timestamps.push(now);
+            this.requests.set(clientId, timestamps);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Returns the remaining number of requests for a client in the current window.
+     *
+     * @param clientId - Identifier for the calling client
+     * @returns Remaining number of requests in the window
+     * @throws AppError when clientId is invalid
+     */
+    getRemainingRequests(clientId) {
+        this.ensureValidClientId(clientId);
+        const now = Date.now();
+        this.cleanupExpiredEntries(now, clientId);
+        const timestamps = this.requests.get(clientId);
+        if (!timestamps) {
+            return this.maxRequests;
+        }
+        return Math.max(0, this.maxRequests - timestamps.length);
+    }
+    /**
+     * Resets rate limiting for a single client or all clients.
+     *
+     * @param clientId - Optional client identifier to reset; omit to reset all
+     * @returns Nothing
+     */
+    reset(clientId) {
+        if (clientId) {
+            this.ensureValidClientId(clientId);
+            this.requests.delete(clientId);
+            return;
+        }
+        this.requests.clear();
+    }
+    /**
+     * Removes expired timestamps and deletes empty client entries.
+     *
+     * @param now - Current timestamp used as reference
+     * @param clientId - Optional client identifier to scope cleanup
+     * @returns Nothing
+     */
+    cleanupExpiredEntries(now, clientId) {
+        const cutoff = now - this.windowMs;
+        if (clientId) {
+            const timestamps = this.requests.get(clientId);
+            if (!timestamps) {
+                return;
+            }
+            const validTimestamps = timestamps.filter((timestamp) => timestamp > cutoff);
+            if (validTimestamps.length === 0) {
+                this.requests.delete(clientId);
+            }
+            else {
+                this.requests.set(clientId, validTimestamps);
+            }
+            return;
+        }
+        for (const [id, timestamps] of this.requests.entries()) {
+            const validTimestamps = timestamps.filter((timestamp) => timestamp > cutoff);
+            if (validTimestamps.length === 0) {
+                this.requests.delete(id);
+            }
+            else {
+                this.requests.set(id, validTimestamps);
+            }
+        }
+    }
+    /**
+     * Ensures the client identifier is valid.
+     *
+     * @param clientId - Identifier to validate
+     * @returns Nothing
+     * @throws AppError when clientId is invalid
+     */
+    ensureValidClientId(clientId) {
+        const validation = RateLimiter.clientIdSchema.safeParse(clientId);
+        if (!validation.success) {
+            throw new AppError('Invalid client identifier', 'INVALID_CLIENT_ID', {
+                errors: validation.error.errors,
+                received: clientId,
+            });
+        }
+    }
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/utils/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../src/utils/rate-limiter.ts"],"names":[],"mappings":"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"}

package/dist/utils/validate-json.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Custom error class for application-level errors with detailed context.
+ * Extends the built-in Error class to provide additional metadata.
+ */
+export declare class AppError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: string;
+    /** Additional context about the error */
+    readonly context?: Record<string, unknown>;
+    /**
+     * Creates a new AppError instance.
+     *
+     * @param message - Human-readable error message
+     * @param code - Error code for programmatic handling
+     * @param context - Optional additional context
+     */
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+/**
+ * Validates that a string is valid JSON and parses it.
+ *
+ * Uses zod for runtime validation to ensure the input is a valid string
+ * before attempting to parse. The parsed result is then validated
+ * against a permissive schema that accepts any valid JSON value.
+ *
+ * @param input - The string to validate and parse as JSON
+ * @returns The parsed JSON value (object, array, string, number, boolean, or null)
+ * @throws AppError with code 'INVALID_INPUT' if input is not a string
+ * @throws AppError with code 'JSON_PARSE_ERROR' if the string is not valid JSON
+ *
+ * @example
+ * ```typescript
+ * // Parse a valid JSON object
+ * const obj = validateAndParseJSON('{"name": "test", "value": 42}');
+ * // Returns: { name: "test", value: 42 }
+ *
+ * // Parse a valid JSON array
+ * const arr = validateAndParseJSON('[1, 2, 3]');
+ * // Returns: [1, 2, 3]
+ *
+ * // Invalid JSON throws AppError
+ * try {
+ *   validateAndParseJSON('{invalid}');
+ * } catch (error) {
+ *   if (error instanceof AppError) {
+ *     console.log(error.code); // 'JSON_PARSE_ERROR'
+ *   }
+ * }
+ * ```
+ */
+export declare function validateAndParseJSON(input: string): Promise<unknown>;
+//# sourceMappingURL=validate-json.d.ts.map

package/dist/utils/validate-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-json.d.ts","sourceRoot":"","sources":["../../src/utils/validate-json.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE3C;;;;;;OAMG;gBAED,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAYpC;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAiD1E"}

package/dist/utils/validate-json.js

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+/**
+ * Custom error class for application-level errors with detailed context.
+ * Extends the built-in Error class to provide additional metadata.
+ */
+export class AppError extends Error {
+    /** Error code for programmatic handling */
+    code;
+    /** Additional context about the error */
+    context;
+    /**
+     * Creates a new AppError instance.
+     *
+     * @param message - Human-readable error message
+     * @param code - Error code for programmatic handling
+     * @param context - Optional additional context
+     */
+    constructor(message, code, context) {
+        super(message);
+        this.name = 'AppError';
+        this.code = code;
+        this.context = context;
+        // Maintains proper stack trace for where error was thrown (V8 engines)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, AppError);
+        }
+    }
+}
+/**
+ * Zod schema for validating that a value is valid JSON.
+ * Accepts any valid JSON value (object, array, string, number, boolean, null).
+ */
+const jsonSchema = z.unknown();
+/**
+ * Validates that a string is valid JSON and parses it.
+ *
+ * Uses zod for runtime validation to ensure the input is a valid string
+ * before attempting to parse. The parsed result is then validated
+ * against a permissive schema that accepts any valid JSON value.
+ *
+ * @param input - The string to validate and parse as JSON
+ * @returns The parsed JSON value (object, array, string, number, boolean, or null)
+ * @throws AppError with code 'INVALID_INPUT' if input is not a string
+ * @throws AppError with code 'JSON_PARSE_ERROR' if the string is not valid JSON
+ *
+ * @example
+ * ```typescript
+ * // Parse a valid JSON object
+ * const obj = validateAndParseJSON('{"name": "test", "value": 42}');
+ * // Returns: { name: "test", value: 42 }
+ *
+ * // Parse a valid JSON array
+ * const arr = validateAndParseJSON('[1, 2, 3]');
+ * // Returns: [1, 2, 3]
+ *
+ * // Invalid JSON throws AppError
+ * try {
+ *   validateAndParseJSON('{invalid}');
+ * } catch (error) {
+ *   if (error instanceof AppError) {
+ *     console.log(error.code); // 'JSON_PARSE_ERROR'
+ *   }
+ * }
+ * ```
+ */
+export async function validateAndParseJSON(input) {
+    // Validate input is a string using zod
+    const stringSchema = z.string({
+        required_error: 'Input is required',
+        invalid_type_error: 'Input must be a string',
+    });
+    const validationResult = stringSchema.safeParse(input);
+    if (!validationResult.success) {
+        throw new AppError('Input must be a valid string', 'INVALID_INPUT', {
+            errors: validationResult.error.errors,
+            receivedType: typeof input,
+        });
+    }
+    // Attempt to parse the JSON string
+    let parsed;
+    try {
+        parsed = JSON.parse(validationResult.data);
+    }
+    catch (error) {
+        throw new AppError(`Failed to parse JSON: ${error instanceof Error ? error.message : 'Unknown error'}`, 'JSON_PARSE_ERROR', {
+            input: input.length > 100 ? `${input.substring(0, 100)}...` : input,
+            originalError: error instanceof Error ? error.message : String(error),
+        });
+    }
+    // Validate the parsed result with zod (accepts any valid JSON value)
+    const parseResult = jsonSchema.safeParse(parsed);
+    if (!parseResult.success) {
+        throw new AppError('Parsed value failed schema validation', 'SCHEMA_VALIDATION_ERROR', {
+            errors: parseResult.error.errors,
+        });
+    }
+    return parseResult.data;
+}
+//# sourceMappingURL=validate-json.js.map

package/dist/utils/validate-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-json.js","sourceRoot":"","sources":["../../src/utils/validate-json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,2CAA2C;IAClC,IAAI,CAAS;IACtB,yCAAyC;IAChC,OAAO,CAA2B;IAE3C;;;;;;OAMG;IACH,YACE,OAAe,EACf,IAAY,EACZ,OAAiC;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QAEvB,uEAAuE;QACvE,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,KAAa;IACtD,uCAAuC;IACvC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;QAC5B,cAAc,EAAE,mBAAmB;QACnC,kBAAkB,EAAE,wBAAwB;KAC7C,CAAC,CAAC;IAEH,MAAM,gBAAgB,GAAG,YAAY,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAEvD,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC;QAC9B,MAAM,IAAI,QAAQ,CAChB,8BAA8B,EAC9B,eAAe,EACf;YACE,MAAM,EAAE,gBAAgB,CAAC,KAAK,CAAC,MAAM;YACrC,YAAY,EAAE,OAAO,KAAK;SAC3B,CACF,CAAC;IACJ,CAAC;IAED,mCAAmC;IACnC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,QAAQ,CAChB,yBAAyB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAAE,EACnF,kBAAkB,EAClB;YACE,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK;YACnE,aAAa,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SACtE,CACF,CAAC;IACJ,CAAC;IAED,qEAAqE;IACrE,MAAM,WAAW,GAAG,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAEjD,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;QACzB,MAAM,IAAI,QAAQ,CAChB,uCAAuC,EACvC,yBAAyB,EACzB;YACE,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,MAAM;SACjC,CACF,CAAC;IACJ,CAAC;IAED,OAAO,WAAW,CAAC,IAAI,CAAC;AAC1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-agent-memory",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Universal AI agent memory system - CLAUDE.md templates, memory, worktrees for Claude Code, Factory.AI, VSCode, OpenCode",
   "type": "module",
   "main": "dist/index.js",
@@ -78,6 +78,7 @@
     "eslint": "^8.56.0",
     "fake-indexeddb": "^6.0.0",
     "prettier": "^3.2.4",
+    "tsx": "^4.21.0",
     "typescript": "^5.3.3",
     "vitest": "^1.2.0"
   },

package/templates/CLAUDE.template.md

@@ -188,6 +188,56 @@ multi_tool_use.parallel([
 
 ---
 
+## 🧩 MULTI-AGENT EXECUTION (DEPENDENCY-AWARE)
+
+**Goal**: Finish faster by parallelizing independent work while preserving correctness and avoiding conflicts.
+
+**Aggressive parallelization mandate**: Default to multi-agent execution whenever tasks can be safely decomposed; only stay single-threaded when dependencies or overlap risk make parallel work unsafe.
+
+**Process**:
+1. **Decompose** the request into discrete work items with clear inputs/outputs.
+2. **Map dependencies** (A blocks B). Only run B after A is complete.
+3. **Parallelize** dependency-free items with separate agents and explicit file boundaries.
+4. **Gate edits** with `uam agent overlaps --resource "<files>"` before touching any file.
+5. **Merge in dependency order** (upstream first). Rebase or re-run dependent steps if needed.
+
+**When to expand the agent pool**:
+- Multiple files/modules with low coupling
+- Parallel research or analysis tasks
+- Independent test or verification tasks
+
+**Example**:
+```bash
+# Parallel research tasks (dependency-free)
+Task(subagent_type: "security-auditor", prompt: "Threat model: auth flow in src/auth/*")
+Task(subagent_type: "performance-optimizer", prompt: "Find hotspots in src/cache/*")
+
+# Dependent work (sequential)
+# 1) Agent A updates schema → 2) Agent B updates queries → 3) Agent C updates tests
+```
+
+**Conflict avoidance**:
+- One agent per file at a time
+- Declare file ownership in prompts
+- If overlap risk is high, wait or split by section
+
+---
+
+## 🛠️ SKILLFORGE MODE (OPTIONAL)
+
+**Use when**: The request is to create, improve, or compose skills (not regular feature work).
+
+**Phases**:
+0. **Triage** → USE_EXISTING / IMPROVE_EXISTING / CREATE_NEW / COMPOSE
+1. **Deep Analysis** (multi‑lens, edge cases, constraints)
+2. **Specification** (structured skill spec)
+3. **Generation** (implement skill)
+4. **Multi‑Agent Synthesis** (quality + security + evolution approval)
+
+**Fallback**: If SkillForge scripts/requirements are unavailable, use the existing skill routing matrix and create skills manually in `{{SKILLS_PATH}}`.
+
+---
+
 ## 🧾 TOKEN EFFICIENCY RULES
 
 - Prefer concise, high-signal responses; avoid repeating instructions or large logs.
@@ -216,7 +266,7 @@ multi_tool_use.parallel([
 │                                                                  │
 │  4. WORKTREE │ {{WORKTREE_CREATE_CMD}} <slug>                   │
 │              │ cd {{WORKTREE_DIR}}/NNN-<slug>/                  │
-│              │ NEVER commit to {{DEFAULT_BRANCH}}               │
+│              │ NEVER commit directly to {{DEFAULT_BRANCH}}      │
 │                                                                  │
 │  5. WORK     │ Implement → Test → {{WORKTREE_PR_CMD}}           │
 │                                                                  │