universal-agent-protocol 0.5.0

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/string-similarity.d.ts

@@ -0,0 +1,37 @@
+/**
+ * String Similarity Utilities for UAP
+ *
+ * Shared text comparison functions used across memory compression,
+ * deduplication, and retrieval systems.
+ */
+/**
+ * Calculate Jaccard similarity between two strings (word-level)
+ * Returns a value between 0 (no overlap) and 1 (identical)
+ */
+export declare function jaccardSimilarity(a: string, b: string): number;
+/**
+ * Calculate content hash for deduplication
+ * Uses SHA-256 for reliable collision resistance
+ */
+export declare function contentHash(text: string): string;
+/**
+ * Improved token estimation
+ * More accurate than simple length/4 for mixed code and prose
+ */
+export declare function estimateTokensAccurate(text: string): number;
+/**
+ * Simple stemming for keyword matching
+ * Handles common English suffixes for better fuzzy matching
+ */
+export declare function simpleStem(word: string): string;
+/**
+ * Fuzzy keyword match using stemming
+ * Returns true if any stemmed form matches
+ */
+export declare function fuzzyKeywordMatch(text: string, keyword: string): boolean;
+/**
+ * Calculate text similarity using multiple methods
+ * Returns weighted average for more robust comparison
+ */
+export declare function textSimilarity(a: string, b: string): number;
+//# sourceMappingURL=string-similarity.d.ts.map

package/dist/utils/string-similarity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string-similarity.d.ts","sourceRoot":"","sources":["../../src/utils/string-similarity.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAW9D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKhD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAuB3D;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkB/C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAkBxE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAa3D"}

package/dist/utils/string-similarity.js

@@ -0,0 +1,114 @@
+/**
+ * String Similarity Utilities for UAP
+ *
+ * Shared text comparison functions used across memory compression,
+ * deduplication, and retrieval systems.
+ */
+import { createHash } from 'crypto';
+/**
+ * Calculate Jaccard similarity between two strings (word-level)
+ * Returns a value between 0 (no overlap) and 1 (identical)
+ */
+export function jaccardSimilarity(a, b) {
+    const setA = new Set(a.toLowerCase().split(/\s+/).filter(w => w.length > 1));
+    const setB = new Set(b.toLowerCase().split(/\s+/).filter(w => w.length > 1));
+    if (setA.size === 0 && setB.size === 0)
+        return 1;
+    if (setA.size === 0 || setB.size === 0)
+        return 0;
+    const intersection = new Set([...setA].filter(x => setB.has(x)));
+    const union = new Set([...setA, ...setB]);
+    return intersection.size / union.size;
+}
+/**
+ * Calculate content hash for deduplication
+ * Uses SHA-256 for reliable collision resistance
+ */
+export function contentHash(text) {
+    return createHash('sha256')
+        .update(text.toLowerCase().replace(/\s+/g, ' ').trim())
+        .digest('hex')
+        .slice(0, 16); // 16 hex chars = 64 bits, sufficient for dedup
+}
+/**
+ * Improved token estimation
+ * More accurate than simple length/4 for mixed code and prose
+ */
+export function estimateTokensAccurate(text) {
+    if (!text || text.length === 0)
+        return 0;
+    // Split by whitespace and count
+    const words = text.split(/\s+/).filter(w => w.length > 0);
+    // Count special characters that typically become separate tokens
+    const specialChars = (text.match(/[{}()\[\]<>:;,."'`@#$%^&*+=|\\/?!~-]/g) || []).length;
+    // Code tokens: variable names split on camelCase/snake_case
+    const codeTokens = (text.match(/[a-z][A-Z]|_[a-z]/g) || []).length;
+    // Numbers often tokenize separately
+    const numbers = (text.match(/\d+/g) || []).length;
+    // Base: words + adjustments
+    // Average English word is ~1.3 tokens, code identifiers ~1.5
+    const baseTokens = words.length * 1.3;
+    const specialTokens = specialChars * 0.5;
+    const extraCodeTokens = codeTokens * 0.3;
+    const numberTokens = numbers * 0.5;
+    return Math.ceil(baseTokens + specialTokens + extraCodeTokens + numberTokens);
+}
+/**
+ * Simple stemming for keyword matching
+ * Handles common English suffixes for better fuzzy matching
+ */
+export function simpleStem(word) {
+    const lower = word.toLowerCase();
+    // Common suffixes to strip
+    const suffixes = ['ing', 'ed', 'es', 's', 'er', 'est', 'ly', 'tion', 'ment', 'ness', 'able', 'ible'];
+    for (const suffix of suffixes) {
+        if (lower.endsWith(suffix) && lower.length > suffix.length + 2) {
+            const stem = lower.slice(0, -suffix.length);
+            // Handle doubling (e.g., "running" -> "run")
+            if (stem.length > 2 && stem[stem.length - 1] === stem[stem.length - 2]) {
+                return stem.slice(0, -1);
+            }
+            return stem;
+        }
+    }
+    return lower;
+}
+/**
+ * Fuzzy keyword match using stemming
+ * Returns true if any stemmed form matches
+ */
+export function fuzzyKeywordMatch(text, keyword) {
+    const textLower = text.toLowerCase();
+    const keywordLower = keyword.toLowerCase();
+    // Exact match first
+    if (textLower.includes(keywordLower))
+        return true;
+    // Stemmed match
+    const keywordStem = simpleStem(keywordLower);
+    const textWords = textLower.split(/\s+/);
+    for (const word of textWords) {
+        if (simpleStem(word) === keywordStem)
+            return true;
+        // Also check if the stem is contained in the word (for compound words)
+        if (word.includes(keywordStem) && keywordStem.length >= 3)
+            return true;
+    }
+    return false;
+}
+/**
+ * Calculate text similarity using multiple methods
+ * Returns weighted average for more robust comparison
+ */
+export function textSimilarity(a, b) {
+    // Jaccard on words
+    const jaccard = jaccardSimilarity(a, b);
+    // Character-level containment
+    const aLower = a.toLowerCase();
+    const bLower = b.toLowerCase();
+    const shorter = aLower.length < bLower.length ? aLower : bLower;
+    const longer = aLower.length >= bLower.length ? aLower : bLower;
+    const containment = shorter.length > 0 && longer.includes(shorter) ? 0.8 : 0;
+    // Weighted combination
+    return Math.max(jaccard, containment);
+}
+//# sourceMappingURL=string-similarity.js.map

package/dist/utils/string-similarity.js.map

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

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

@@ -0,0 +1,51 @@
+/**
+ * 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_JSON' 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); // 'INVALID_JSON'
+ *   }
+ * }
+ * ```
+ */
+export declare function validateAndParseJSON(input: string): 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;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAmC3D"}

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();
+/** Maximum number of characters of the original input to include in error context. */
+const MAX_ERROR_CONTEXT_CHARS = 100;
+/**
+ * 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_JSON' 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); // 'INVALID_JSON'
+ *   }
+ * }
+ * ```
+ */
+export function validateAndParseJSON(input) {
+    const jsonStringSchema = z
+        .string({
+        required_error: 'Input is required',
+        invalid_type_error: 'Input must be a string',
+    })
+        .transform((value, ctx) => {
+        try {
+            return JSON.parse(value);
+        }
+        catch (error) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: error instanceof Error
+                    ? `Invalid JSON: ${error.message}`
+                    : 'Invalid JSON',
+            });
+            return z.NEVER;
+        }
+    })
+        .pipe(jsonSchema);
+    const result = jsonStringSchema.safeParse(input);
+    if (!result.success) {
+        throw new AppError('Input must be valid JSON', 'INVALID_JSON', {
+            errors: result.error.errors,
+            input: input.length > MAX_ERROR_CONTEXT_CHARS
+                ? `${input.substring(0, MAX_ERROR_CONTEXT_CHARS)}...`
+                : input,
+        });
+    }
+    return result.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,sFAAsF;AACtF,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,MAAM,gBAAgB,GAAG,CAAC;SACvB,MAAM,CAAC;QACN,cAAc,EAAE,mBAAmB;QACnC,kBAAkB,EAAE,wBAAwB;KAC7C,CAAC;SACD,SAAS,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACxB,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAY,CAAC;QACtC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,GAAG,CAAC,QAAQ,CAAC;gBACX,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM;gBAC3B,OAAO,EACL,KAAK,YAAY,KAAK;oBACpB,CAAC,CAAC,iBAAiB,KAAK,CAAC,OAAO,EAAE;oBAClC,CAAC,CAAC,cAAc;aACrB,CAAC,CAAC;YACH,OAAO,CAAC,CAAC,KAAK,CAAC;QACjB,CAAC;IACH,CAAC,CAAC;SACD,IAAI,CAAC,UAAU,CAAC,CAAC;IAEpB,MAAM,MAAM,GAAG,gBAAgB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAEjD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,QAAQ,CAAC,0BAA0B,EAAE,cAAc,EAAE;YAC7D,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM;YAC3B,KAAK,EACH,KAAK,CAAC,MAAM,GAAG,uBAAuB;gBACpC,CAAC,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,uBAAuB,CAAC,KAAK;gBACrD,CAAC,CAAC,KAAK;SACZ,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC"}

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "universal-agent-protocol",
+  "version": "0.5.0",
+  "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "universal-agent-protocol": "dist/bin/cli.js",
+    "uap": "dist/bin/cli.js",
+    "uap-tool-calls": "dist/bin/tool-calls.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/bin/cli.js",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "format": "prettier --write src/**/*.ts",
+    "prepare": "npm run build",
+    "install:web": "bash scripts/install-web.sh",
+    "install:desktop": "bash scripts/install-desktop.sh",
+    "install:all": "bash scripts/install.sh",
+    "postinstall": "echo '\n✨ Run: npx universal-agent-protocol init --interactive'",
+    "update-uap": "bash scripts/update-uap-compliance.sh",
+    "verify-uap": "bash scripts/verify-compliance.sh",
+    "check-claude": "bash scripts/verify-compliance.sh"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "factory-ai",
+    "opencode",
+    "vscode",
+    "ai-agent",
+    "context",
+    "memory",
+    "worktree",
+    "cli"
+  ],
+  "author": "Miller Tech",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DammianMiller/universal-agent-protocol.git"
+  },
+  "homepage": "https://github.com/DammianMiller/universal-agent-protocol#readme",
+  "bugs": {
+    "url": "https://github.com/DammianMiller/universal-agent-protocol/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@octokit/rest": "^20.0.2",
+    "@qdrant/js-client-rest": "^1.11.0",
+    "better-sqlite3": "^11.0.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "dexie": "^4.0.8",
+    "glob": "^10.3.10",
+    "handlebars": "^4.7.8",
+    "inquirer": "^9.2.12",
+    "js-yaml": "^4.1.0",
+    "ora": "^8.0.1",
+    "simple-git": "^3.22.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.8",
+    "@types/inquirer": "^9.0.7",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.11.0",
+    "@typescript-eslint/eslint-plugin": "^6.19.0",
+    "@typescript-eslint/parser": "^6.19.0",
+    "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"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "tools/agents",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/templates/CLAUDE.template.md

@@ -0,0 +1,11 @@
+<!-- CLAUDE.md v2.3.0 - 34 Model Outcome Success Optimizations + Hooks Enforcement -->
+<!-- Optimizations #22-27: Template Compression, Structured Iteration, Inline Domain Knowledge, Early Impossibility Exit, Conditional Context, Remove Emphasis Theater -->
+<!-- Optimizations #28-34: Mandatory Verifier Loop, Decoder-First Gate, Context Stripping, Environment Check, Schema Diff, State Protection, Conditional Domain -->
+
+<!-- ENFORCEMENT_CHECKS: SESSION_START,DECISION_LOOP,MANDATORY_WORKTREE,PARALLEL_REVIEW,SCHEMA_DIFF,GATES,RTK_INCLUDES,PATTERN_ROUTER -->
+<!-- TEMPLATE_VERSION: 2.3.0 -->
+<!-- LAST_VALIDATED: 2026-03-09 -->
+
+@hooks-session-start.md
+@PreCompact.md
+